From 23dd9528b7ec64c2c648940e55473786cc8c3d85 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 18:18:05 +0100 Subject: [PATCH 1/6] feat(plugins): install managed local artifacts --- .changeset/managed-plugin-artifact.md | 5 + .../src/schema/command-overrides.ts | 8 +- packages/plugins/src/store-artifact.test.ts | 164 ++++++++++++++++++ packages/plugins/src/store.ts | 162 +++++++++++++++-- src/cli/commands/__tests__/plugins.test.ts | 53 ++++++ src/cli/commands/plugins.ts | 28 ++- src/sdk/plugins.ts | 2 + .../installed-package-metro.test.ts | 2 +- website/docs/docs/plugins.md | 19 ++ 9 files changed, 415 insertions(+), 28 deletions(-) create mode 100644 .changeset/managed-plugin-artifact.md create mode 100644 packages/plugins/src/store-artifact.test.ts diff --git a/.changeset/managed-plugin-artifact.md b/.changeset/managed-plugin-artifact.md new file mode 100644 index 0000000000..321667654f --- /dev/null +++ b/.changeset/managed-plugin-artifact.md @@ -0,0 +1,5 @@ +--- +'agent-device': minor +--- + +Install local plugin tarballs with `plugins add-artifact` or the plugin manager API. Artifact selections record their version and SHA-512 integrity and require an explicit replacement. diff --git a/packages/command-surface/src/schema/command-overrides.ts b/packages/command-surface/src/schema/command-overrides.ts index 691b1dd020..f98467d89b 100644 --- a/packages/command-surface/src/schema/command-overrides.ts +++ b/packages/command-surface/src/schema/command-overrides.ts @@ -15,13 +15,13 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = { text: { summary: 'Manage installed provider plugins', description: - 'Install, list, update, or remove npm provider plugins in AGENT_DEVICE_HOME (default ~/.agent-device). Changes take effect after restarting the local daemon. list works offline and, when a daemon is running for --state-dir, also reports the providers it registered. Use --json for structured results.', + 'Install, list, update, or remove provider plugins in AGENT_DEVICE_HOME (default ~/.agent-device). Changes take effect after restarting the local daemon. list works offline and, when a daemon is running for --state-dir, also reports the providers it registered. Use --json for structured results.', }, usageOverride: - 'plugins list [--state-dir ]|add |update |remove ', + 'plugins list [--state-dir ]|add |add-artifact |update |remove ', listUsageOverride: 'plugins', - positionalArgs: ['list|add|update|remove', 'package?'], - flagsByAction: { list: ['stateDir'], add: [], update: [], remove: [] }, + positionalArgs: ['list|add|add-artifact|update|remove', 'package?'], + flagsByAction: { list: ['stateDir'], add: [], 'add-artifact': [], update: [], remove: [] }, supportedFlags: ['stateDir'], }, cdp: { diff --git a/packages/plugins/src/store-artifact.test.ts b/packages/plugins/src/store-artifact.test.ts new file mode 100644 index 0000000000..235640e764 --- /dev/null +++ b/packages/plugins/src/store-artifact.test.ts @@ -0,0 +1,164 @@ +import assert from 'node:assert/strict'; +import crypto from 'node:crypto'; +import fs from 'node:fs'; +import path from 'node:path'; +import { execFileSync } from 'node:child_process'; +import { test } from 'vitest'; +import { mkdtempForTestSync, pluginHome, v2RegistrationSource } from '@agent-device/test-kit'; +import { + addPluginArtifact, + changePlugin, + createPluginSelectionGuard, + listPlugins, + storePluginCandidates, +} from './store.ts'; + +function packFixture( + root: string, + name: string, + exportsField: unknown = { './agent-device': './plugin.mjs' }, +) { + const source = path.join(root, name); + fs.mkdirSync(source, { recursive: true }); + const sentinel = path.join(root, `${name}-executed`); + fs.writeFileSync( + path.join(source, 'package.json'), + JSON.stringify({ + name, + version: '1.2.3', + type: 'module', + exports: exportsField, + scripts: { + preinstall: `node sentinel.cjs`, + install: `node sentinel.cjs`, + postinstall: `node sentinel.cjs`, + }, + }), + ); + fs.writeFileSync( + path.join(source, 'sentinel.cjs'), + `require('node:fs').writeFileSync(${JSON.stringify(sentinel)}, 'script')`, + ); + fs.writeFileSync( + path.join(source, 'plugin.mjs'), + v2RegistrationSource(name).replace( + 'export default (options = {}) => (', + `export default (options = {}) => (fs.writeFileSync(${JSON.stringify(sentinel)}, 'factory'), `, + ), + ); + const output = execFileSync( + 'npm', + ['pack', '--ignore-scripts', '--json', '--pack-destination', root], + { cwd: source, encoding: 'utf8' }, + ); + return { archive: path.join(root, JSON.parse(output)[0].filename), sentinel }; +} + +test('artifact installation preserves immutable identity, isolation, collision and stale guard', async () => { + const root = mkdtempForTestSync('plugin-artifact-'); + const fixture = packFixture(root, 'fixture-provider'); + const { home, env: isolated } = pluginHome(); + const env = { ...process.env, ...isolated }; + const other = pluginHome(); + const expected = `sha512-${crypto.createHash('sha512').update(fs.readFileSync(fixture.archive)).digest('base64')}`; + const result = await addPluginArtifact(path.basename(fixture.archive), { cwd: root, env }); + assert.equal(result.integrity, expected); + assert.equal(result.name, 'fixture-provider'); + assert.equal(result.version, '1.2.3'); + assert.equal(fs.existsSync(fixture.sentinel), false); + assert.ok(fs.existsSync(fixture.archive)); + assert.deepEqual(await listPlugins(other.env, []), []); + const guard = createPluginSelectionGuard(await storePluginCandidates(env), env); + const configPath = path.join(home, 'config.json'); + const before = fs.readFileSync(configPath, 'utf8'); + await assert.rejects(addPluginArtifact(fixture.archive, { cwd: root, env }), { + code: 'INVALID_ARGS', + }); + await assert.rejects(changePlugin('update', result.name, env), { code: 'INVALID_ARGS' }); + await assert.rejects(changePlugin('add', result.name, env), { code: 'INVALID_ARGS' }); + assert.equal(fs.readFileSync(configPath, 'utf8'), before); + assert.equal(fs.readdirSync(path.join(home, 'plugins')).length, 1); + const [listed] = await listPlugins(env, []); + assert.equal(listed?.version, '1.2.3'); + assert.equal(listed?.integrity, expected); + assert.equal(listed?.installation, result.installation); + assert.equal(fs.readFileSync(fixture.sentinel, 'utf8'), 'factory'); + const config = JSON.parse(before); + config.plugins[result.name].artifact.integrity = + `sha512-${Buffer.alloc(64, 1).toString('base64')}`; + fs.writeFileSync(configPath, JSON.stringify(config)); + assert.throws( + () => guard(result.name), + (error: unknown) => + (error as { details?: { reason?: string } }).details?.reason === 'daemon-plugin-set-stale', + ); +}); + +test('invalid artifact and missing export roll back without disturbing selections', async () => { + const root = mkdtempForTestSync('plugin-artifact-invalid-'); + const { home, env: isolated } = pluginHome(); + const env = { ...process.env, ...isolated }; + const valid = packFixture(root, 'fixture-valid'); + await addPluginArtifact(valid.archive, { cwd: root, env }); + const before = fs.readFileSync(path.join(home, 'config.json'), 'utf8'); + const missing = packFixture(root, 'fixture-missing', { '.': './plugin.mjs' }); + await assert.rejects(addPluginArtifact(missing.archive, { cwd: root, env })); + const bad = path.join(root, 'bad.tgz'); + fs.writeFileSync(bad, 'not an archive'); + await assert.rejects(addPluginArtifact(bad, { cwd: root, env })); + assert.equal(fs.readFileSync(path.join(home, 'config.json'), 'utf8'), before); + assert.equal(fs.readdirSync(path.join(home, 'plugins')).length, 1); + assert.equal(fs.existsSync(missing.sentinel), false); +}); + +test('concurrent artifact additions preserve both selections', async () => { + const root = mkdtempForTestSync('plugin-artifact-concurrent-'); + const one = packFixture(root, 'fixture-one'); + const two = packFixture(root, 'fixture-two'); + const { env: isolated } = pluginHome(); + const env = { ...process.env, ...isolated }; + await Promise.all( + [one, two].map(({ archive }) => addPluginArtifact(archive, { cwd: root, env })), + ); + assert.deepEqual( + (await listPlugins(env, [])).map((plugin) => plugin.name), + ['fixture-one', 'fixture-two'], + ); + assert.equal(fs.existsSync(one.sentinel), true); +}); + +test('npm staging rejects an escaping symlink entry and leaves external files untouched', async () => { + const { default: tar } = await import('tar-stream'); + const { gzipSync } = await import('node:zlib'); + const root = mkdtempForTestSync('plugin-artifact-symlink-'); + const outside = path.join(root, 'outside.mjs'); + fs.writeFileSync(outside, 'outside'); + const archive = path.join(root, 'malicious.tgz'); + const stream = tar.pack(); + const chunks: Buffer[] = []; + stream.on('data', (chunk: Buffer) => chunks.push(chunk)); + stream.entry( + { name: 'package/package.json' }, + JSON.stringify({ + name: 'fixture-escape', + version: '1.0.0', + exports: { './agent-device': './plugin.mjs' }, + }), + ); + stream.entry({ name: 'package/plugin.mjs', type: 'symlink', linkname: outside }); + stream.entry({ name: 'package/../../escape' }, 'escaped'); + const finished = new Promise((resolve, reject) => { + stream.on('end', resolve); + stream.on('error', reject); + }); + stream.finalize(); + await finished; + fs.writeFileSync(archive, gzipSync(Buffer.concat(chunks))); + const { home, env: isolated } = pluginHome(); + await assert.rejects( + addPluginArtifact(archive, { cwd: root, env: { ...process.env, ...isolated } }), + ); + assert.equal(fs.readFileSync(outside, 'utf8'), 'outside'); + assert.equal(fs.existsSync(path.join(home, 'escape')), false); + assert.equal(fs.existsSync(path.join(home, 'config.json')), false); +}); diff --git a/packages/plugins/src/store.ts b/packages/plugins/src/store.ts index 635e1a8bea..ce1752deb3 100644 --- a/packages/plugins/src/store.ts +++ b/packages/plugins/src/store.ts @@ -18,6 +18,7 @@ export type PluginSelection = { installation: string; version?: string; options?: Record; + artifact?: { integrity: string; version: string }; }; type PluginConfig = Record & { plugins?: Record }; @@ -43,7 +44,12 @@ function validatePluginSelection(name: string, selection: PluginSelection): void typeof selection.installation !== 'string' || !/^[a-f0-9-]{36}$/.test(selection.installation) || (selection.version !== undefined && !isVersionSelector(selection.version)) || - (selection.options !== undefined && !isRecord(selection.options)) + (selection.options !== undefined && !isRecord(selection.options)) || + (selection.artifact !== undefined && + (!isRecord(selection.artifact) || + typeof selection.artifact.integrity !== 'string' || + !/^sha512-[A-Za-z0-9+/]{86}==$/.test(selection.artifact.integrity) || + !isExactVersion(selection.artifact.version))) ) { throw new AppError('INVALID_ARGS', `Invalid plugin selection: ${name}`); } @@ -110,6 +116,15 @@ function isVersionSelector(value: unknown): value is string { ); } +function isExactVersion(value: unknown): value is string { + return ( + typeof value === 'string' && + /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test( + value, + ) + ); +} + type StoreInstallation = { name: string; version: string; @@ -133,6 +148,15 @@ async function describeInstallation( reason: 'invalid_plugin', }); } + if ( + selection.artifact && + (version !== selection.artifact.version || + !isRecord(packageJson.exports) || + !Object.hasOwn(packageJson.exports, './agent-device')) + ) + throw new AppError('INVALID_ARGS', `Invalid artifact plugin metadata: ${name}`, { + reason: 'invalid_plugin', + }); return { name, version, directory, selection, entry: discoverPluginEntry(directory) }; } @@ -218,8 +242,18 @@ export async function listPlugins(env: NodeJS.ProcessEnv, builtinProviders: read ...claimProviderIds(builtinProviders), ...(await storePluginCandidates(env)), ]); + let selections: Record = {}; + try { + selections = readPluginConfig(env).plugins ?? {}; + } catch {} return resolved.inventory().map((entry) => ({ name: entry.package, + ...(entry.package && selections[entry.package]?.artifact + ? { + installation: selections[entry.package]!.installation, + integrity: selections[entry.package]!.artifact!.integrity, + } + : {}), ...(entry.version !== undefined ? { version: entry.version } : {}), ...(entry.provider !== undefined ? { provider: entry.provider } : {}), ...(entry.backend !== undefined ? { backend: entry.backend } : {}), @@ -245,6 +279,25 @@ function parsePluginRequest(action: PluginAction, input: string) { return { name: match[1], version: match[2] }; } +async function installInProject(project: string, env: NodeJS.ProcessEnv, artifact?: string) { + await runCmd( + 'npm', + [ + 'install', + '--ignore-scripts', + '--no-audit', + '--no-fund', + '--global=false', + '--prefix', + project, + '--workspaces=false', + '--package-lock=true', + ...(artifact ? ['--', artifact] : []), + ], + { cwd: project, env, timeoutMs: 120_000 }, + ); +} + async function stagePlugin( home: string, name: string, @@ -259,21 +312,7 @@ async function stagePlugin( path.join(project, 'package.json'), JSON.stringify({ private: true, dependencies: { [name]: version ?? 'latest' } }), ); - await runCmd( - 'npm', - [ - 'install', - '--ignore-scripts', - '--no-audit', - '--no-fund', - '--global=false', - '--prefix', - project, - '--workspaces=false', - '--package-lock=true', - ], - { cwd: project, env, timeoutMs: 120_000 }, - ); + await installInProject(project, env); const staged = await describeInstallation( name, installationDirectory(home, name, installation), @@ -315,6 +354,12 @@ export async function changePlugin( const previous = Object.hasOwn(selections, name) ? selections[name] : undefined; if (action !== 'add' && !Object.hasOwn(selections, name)) throw new AppError('INVALID_ARGS', `Plugin is not installed: ${name}`); + if (action !== 'remove' && previous?.artifact) + throw new AppError( + 'INVALID_ARGS', + `Artifact plugin cannot be updated from the registry: ${name}`, + { reason: 'artifact_update_requires_remove' }, + ); if (action === 'remove') delete selections[name]; else { const requested = @@ -338,3 +383,88 @@ export async function changePlugin( await release(); } } + +/** Install immutable local package bytes through the managed store. */ +export async function addPluginArtifact( + input: string, + host: { env: Record; cwd: string }, +): Promise<{ name: string; version: string; installation: string; integrity: string }> { + if (!input.endsWith('.tgz') || !path.isAbsolute(host.cwd)) + throw new AppError('INVALID_ARGS', 'Expected a local .tgz path and an absolute host cwd'); + if ( + !host.env.HOME?.trim() && + (!host.env.AGENT_DEVICE_HOME?.trim() || host.env.AGENT_DEVICE_HOME.trim().startsWith('~')) + ) + throw new AppError( + 'INVALID_ARGS', + 'Provide HOME or an absolute AGENT_DEVICE_HOME in the host environment', + ); + const bytes = fs.readFileSync(path.resolve(host.cwd, input)); + const integrity = `sha512-${crypto.createHash('sha512').update(bytes).digest('base64')}`; + const configPath = resolveUserConfigPath(host.env); + const home = path.dirname(configPath); + fs.mkdirSync(home, { recursive: true, mode: 0o700 }); + const release = await acquireProcessLock({ + lockDirPath: path.join(home, 'plugins.lock'), + owner: { ...readCurrentOwnerIdentity(), acquiredAtMs: Date.now() }, + description: 'plugin installation', + }); + const installation = crypto.randomUUID(); + const project = path.join(home, 'plugins', installation); + let published = false; + try { + fs.mkdirSync(project, { recursive: true, mode: 0o700 }); + const artifact = path.join(project, 'artifact.tgz'); + fs.writeFileSync(artifact, bytes, { mode: 0o600, flag: 'wx' }); + fs.writeFileSync(path.join(project, 'package.json'), JSON.stringify({ private: true })); + await installInProject(project, host.env, artifact); + const lock = JSON.parse(fs.readFileSync(path.join(project, 'package-lock.json'), 'utf8')); + const names = Object.keys(lock.packages?.['']?.dependencies ?? {}); + if (names.length !== 1 || !isPackageName(names[0]!)) + throw new AppError('INVALID_ARGS', 'Artifact has an invalid package name', { + reason: 'invalid_plugin', + }); + const name = names[0]!; + const directory = installationDirectory(home, name, installation); + const root = fs.realpathSync(project); + const actualDirectory = fs.realpathSync(directory); + if (!actualDirectory.startsWith(`${root}${path.sep}`)) + throw new AppError('INVALID_ARGS', 'Artifact package escaped its installation', { + reason: 'invalid_plugin', + }); + const manifestPath = fs.realpathSync(path.join(directory, 'package.json')); + if (!manifestPath.startsWith(`${actualDirectory}${path.sep}`)) + throw new AppError('INVALID_ARGS', 'Artifact manifest escaped its package', { + reason: 'invalid_plugin', + }); + const { readPackageJson } = await import('./discovery.ts'); + const manifest = readPackageJson(directory); + if (manifest.name !== name || !isExactVersion(manifest.version)) + throw new AppError('INVALID_ARGS', `Invalid artifact package identity: ${name}`, { + reason: 'invalid_plugin', + }); + const selection: PluginSelection = { + installation, + version: manifest.version, + artifact: { integrity, version: manifest.version }, + }; + await describeInstallation(name, directory, selection); + const config = readPluginConfig(host.env); + const selections = { ...config.plugins }; + if (Object.hasOwn(selections, name)) + throw new AppError('INVALID_ARGS', `Plugin is already installed: ${name}`, { + reason: 'plugin_already_installed', + }); + selections[name] = selection; + publishFileSync({ + destination: configPath, + contents: `${JSON.stringify({ ...config, plugins: selections }, null, 2)}\n`, + mode: 0o600, + }); + published = true; + return { name, version: manifest.version, installation, integrity }; + } finally { + if (!published) fs.rmSync(project, { recursive: true, force: true }); + await release(); + } +} diff --git a/src/cli/commands/__tests__/plugins.test.ts b/src/cli/commands/__tests__/plugins.test.ts index 207589a32d..abfa00d76c 100644 --- a/src/cli/commands/__tests__/plugins.test.ts +++ b/src/cli/commands/__tests__/plugins.test.ts @@ -1,6 +1,7 @@ import assert from 'node:assert/strict'; import fs from 'node:fs'; import path from 'node:path'; +import { execFileSync } from 'node:child_process'; import { afterEach, test, vi } from 'vitest'; import { runCli } from '../../../cli.ts'; import { readCurrentOwnerIdentity } from '@agent-device/host-kit/process'; @@ -66,6 +67,11 @@ test('plugin schema exposes operator help and preserves scoped npm package specs const help = await usageForCommand('plugins'); assert.ok(help); assert.match(help, /plugins list \[--state-dir \]\|add/); + assert.match(help, /add-artifact /); + assert.deepEqual( + parseRawArgs(['plugins', 'add-artifact', './plugin.tgz', '--json']).positionals, + ['add-artifact', './plugin.tgz'], + ); }); test('plugins list reports the running daemon inventory next to the store selections', async () => { @@ -184,3 +190,50 @@ test('plugins list says when the daemon record cannot be used instead of hiding assert.match(text, /No provider plugins installed\./); assert.match(text, /daemon record for .* is invalid, so its providers are unknown/); }); + +test('plugins add-artifact installs without loading the factory', async () => { + const { home } = pluginHome(); + vi.stubEnv('AGENT_DEVICE_HOME', home); + vi.stubEnv('AGENT_DEVICE_STATE_DIR', path.join(home, 'state')); + vi.stubEnv('AGENT_DEVICE_NO_UPDATE_NOTIFIER', '1'); + const source = path.join(home, 'source'); + fs.mkdirSync(source); + const marker = path.join(home, 'executed'); + fs.writeFileSync( + path.join(source, 'package.json'), + JSON.stringify({ + name: 'cli-artifact', + version: '1.0.0', + type: 'module', + exports: { './agent-device': './plugin.mjs' }, + scripts: { preinstall: 'node sentinel.cjs' }, + }), + ); + fs.writeFileSync( + path.join(source, 'sentinel.cjs'), + `require('node:fs').writeFileSync(${JSON.stringify(marker)}, 'script')`, + ); + fs.writeFileSync( + path.join(source, 'plugin.mjs'), + `import fs from 'node:fs'; fs.writeFileSync(${JSON.stringify(marker)}, 'factory'); export default () => ({});`, + ); + const packed = JSON.parse( + execFileSync('npm', ['pack', '--ignore-scripts', '--json', '--pack-destination', home], { + cwd: source, + encoding: 'utf8', + }), + ); + const archive = path.join(home, packed[0].filename); + const capture = beginStdoutCapture(); + try { + await runCli(['plugins', 'add-artifact', archive, '--json'], { sendToDaemon: vi.fn() }); + const { data } = JSON.parse(capture.read()); + assert.equal(data.plugins[0].name, 'cli-artifact'); + assert.equal(data.plugins[0].version, '1.0.0'); + assert.match(data.plugins[0].integrity, /^sha512-/); + assert.equal(data.restartRequired, true); + assert.equal(fs.existsSync(marker), false); + } finally { + capture.restore(); + } +}); diff --git a/src/cli/commands/plugins.ts b/src/cli/commands/plugins.ts index dea8b696f6..65a9150451 100644 --- a/src/cli/commands/plugins.ts +++ b/src/cli/commands/plugins.ts @@ -5,7 +5,7 @@ import { readDaemonStatus, } from '@agent-device/daemon-contracts/daemon-registration'; import { AppError } from '@agent-device/kernel/errors'; -import { changePlugin, listPlugins } from '@agent-device/plugins/store'; +import { addPluginArtifact, changePlugin, listPlugins } from '@agent-device/plugins/store'; import { BUILTIN_PROVIDER_IDS } from '../../builtin-provider-ids.ts'; import { writeCommandOutput } from './shared.ts'; import type { ClientCommandHandler } from './router-types.ts'; @@ -14,18 +14,32 @@ export const pluginsCommand: ClientCommandHandler = async ({ positionals, flags const [action = 'list', name, extra] = positionals; if ( extra || - !['add', 'update', 'remove', 'list'].includes(action) || + !['add', 'add-artifact', 'update', 'remove', 'list'].includes(action) || (action === 'list' ? name !== undefined : !name) ) { throw new AppError( 'INVALID_ARGS', - 'Use plugins list, add , update , or remove ', + 'Use plugins list, add , add-artifact , update , or remove ', ); } - if (action !== 'list' && name) { + const artifact = + action === 'add-artifact' && name + ? await addPluginArtifact(name, { env: process.env, cwd: process.cwd() }) + : undefined; + if (action !== 'list' && action !== 'add-artifact' && name) { await changePlugin(action as 'add' | 'update' | 'remove', name, process.env); } - const plugins = await listPlugins(process.env, BUILTIN_PROVIDER_IDS); + const plugins = artifact + ? [ + { + ...artifact, + compatible: undefined, + provider: undefined, + backend: undefined, + error: undefined, + }, + ] + : await listPlugins(process.env, BUILTIN_PROVIDER_IDS); const daemon = readDaemonStatus(resolveDaemonPaths(flags.stateDir)); const daemonPlugins = readPluginInventory(daemon.plugins); const failedInDaemon = daemonPlugins.filter(({ state }) => state === 'failed'); @@ -40,8 +54,8 @@ export const pluginsCommand: ClientCommandHandler = async ({ positionals, flags await writeCommandOutput(flags, data, () => [ ...plugins.map((plugin) => - plugin.compatible - ? `${plugin.name}@${plugin.version} (${plugin.provider ?? plugin.backend})` + plugin.compatible || artifact + ? `${plugin.name}@${plugin.version}${plugin.provider || plugin.backend ? ` (${plugin.provider ?? plugin.backend})` : ''}` : plugin.name === undefined ? `Plugin config unavailable: ${plugin.error?.message}` : `${plugin.name}: unavailable; run plugins update ${plugin.name} or plugins remove ${plugin.name}`, diff --git a/src/sdk/plugins.ts b/src/sdk/plugins.ts index 411bccad5a..56aabad01b 100644 --- a/src/sdk/plugins.ts +++ b/src/sdk/plugins.ts @@ -34,3 +34,5 @@ export type { ReplayExecutionPlugin, ReplayExecutionResolver, } from '@agent-device/contracts/replay-execution'; + +export { addPluginArtifact } from '@agent-device/plugins/store'; diff --git a/test/integration/installed-package-metro.test.ts b/test/integration/installed-package-metro.test.ts index 1ffa91b772..4047655157 100644 --- a/test/integration/installed-package-metro.test.ts +++ b/test/integration/installed-package-metro.test.ts @@ -634,7 +634,7 @@ assert.equal(fs.existsSync(path.join(cwd, 'host-a', 'daemon.json')), false); return runtime.provider; }, './metro': (mod) => mod.buildBundleUrl('https://public.example.test', 'ios'), - './plugins': (mod) => Object.keys(mod).length === 0, + './plugins': (mod) => Object.keys(mod).length === 1 && typeof mod.addPluginArtifact === 'function', './plugins/webdriver': (mod) => Object.keys(mod).length === 0, './remote-config': (mod) => typeof mod, './selectors': (mod) => diff --git a/website/docs/docs/plugins.md b/website/docs/docs/plugins.md index 78f316481b..6ea48645e9 100644 --- a/website/docs/docs/plugins.md +++ b/website/docs/docs/plugins.md @@ -196,3 +196,22 @@ For a format backend such as `maestro`, setup returns `{ replayBackend: { create For the native `ad` backend, setup returns `{ execution: { create() }, dispose? }`. The object returned by `create()` implements `inspectAdReplay`, `runAdReplay`, and `runReplayTestSuite`. Return only the factory for your backend: the host rejects a native setup that provides `replayBackend`, or a format setup that provides `execution`. The daemon owns sessions, policy, selector/ref authority, and device cleanup. `dispose` runs once after requests drain. Client-side source collection and export dispose their scoped plugin registry when the operation ends. + + +## Install a local plugin artifact + +On each host that needs the plugin, install its `.tgz` file: + +```sh +agent-device plugins add-artifact ./provider-plugin.tgz --json +agent-device plugins list --json +``` + +The archive must contain an npm package with a name, an exact version, and an `./agent-device` export. Installation does not run package lifecycle scripts or load the plugin factory. The list command loads the factory to check compatibility. The JSON inventory includes the artifact's installation ID and SHA-512 integrity. If the package is already selected, remove it before adding the artifact. `plugins update` does not update artifacts from the registry; remove the selection and add the replacement artifact. Finish active sessions and restart the daemon after changing the selection. + +A Node.js host can call the same manager with an explicit environment and working directory: + +```js +import { addPluginArtifact } from 'agent-device/plugins'; +await addPluginArtifact('./provider-plugin.tgz', { env: process.env, cwd: process.cwd() }); +``` From ac8102c535239fbb091f0e59779cb6991b7597cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 18:56:36 +0100 Subject: [PATCH 2/6] fix(plugins): bind artifact integrity and inventory to installed selections --- packages/plugins/src/store-artifact.test.ts | 99 +++++++++++++++++++-- packages/plugins/src/store.ts | 27 ++++-- 2 files changed, 110 insertions(+), 16 deletions(-) diff --git a/packages/plugins/src/store-artifact.test.ts b/packages/plugins/src/store-artifact.test.ts index 235640e764..b630298737 100644 --- a/packages/plugins/src/store-artifact.test.ts +++ b/packages/plugins/src/store-artifact.test.ts @@ -3,7 +3,8 @@ import crypto from 'node:crypto'; import fs from 'node:fs'; import path from 'node:path'; import { execFileSync } from 'node:child_process'; -import { test } from 'vitest'; +import { test, vi } from 'vitest'; +import * as command from '@agent-device/host-kit/command'; import { mkdtempForTestSync, pluginHome, v2RegistrationSource } from '@agent-device/test-kit'; import { addPluginArtifact, @@ -17,6 +18,7 @@ function packFixture( root: string, name: string, exportsField: unknown = { './agent-device': './plugin.mjs' }, + factoryGate?: string, ) { const source = path.join(root, name); fs.mkdirSync(source, { recursive: true }); @@ -39,13 +41,20 @@ function packFixture( path.join(source, 'sentinel.cjs'), `require('node:fs').writeFileSync(${JSON.stringify(sentinel)}, 'script')`, ); - fs.writeFileSync( - path.join(source, 'plugin.mjs'), - v2RegistrationSource(name).replace( - 'export default (options = {}) => (', - `export default (options = {}) => (fs.writeFileSync(${JSON.stringify(sentinel)}, 'factory'), `, - ), + let pluginSource = v2RegistrationSource(name).replace( + 'export default (options = {}) => (', + `export default (options = {}) => (fs.writeFileSync(${JSON.stringify(sentinel)}, 'factory'), `, ); + if (factoryGate) { + pluginSource = pluginSource.replace('export default ', 'const createPlugin = '); + pluginSource += `\nexport default async (options) => { + const gate = globalThis[Symbol.for(${JSON.stringify(factoryGate)})]; + gate.enter(); + await gate.resume; + return createPlugin(options); + };`; + } + fs.writeFileSync(path.join(source, 'plugin.mjs'), pluginSource); const output = execFileSync( 'npm', ['pack', '--ignore-scripts', '--json', '--pack-destination', root], @@ -162,3 +171,79 @@ test('npm staging rejects an escaping symlink entry and leaves external files un assert.equal(fs.existsSync(path.join(home, 'escape')), false); assert.equal(fs.existsSync(path.join(home, 'config.json')), false); }); + +test('artifact installation rejects replacement bytes consumed by npm', async () => { + const root = mkdtempForTestSync('plugin-artifact-replaced-'); + const originalRoot = path.join(root, 'original'); + const replacementRoot = path.join(root, 'replacement'); + const original = packFixture(originalRoot, 'fixture-replaced'); + const replacement = packFixture(replacementRoot, 'fixture-replaced'); + assert.notDeepEqual(fs.readFileSync(original.archive), fs.readFileSync(replacement.archive)); + const { home, env: isolated } = pluginHome(); + const env = { ...process.env, ...isolated }; + const runCmd = command.runCmd; + let replaced = false; + const spy = vi.spyOn(command, 'runCmd').mockImplementation(async (program, args, options) => { + if (program === 'npm' && args[0] === 'install' && args.at(-2) === '--') { + fs.copyFileSync(replacement.archive, args.at(-1)!); + replaced = true; + } + return runCmd(program, args, options); + }); + try { + await assert.rejects(addPluginArtifact(original.archive, { cwd: root, env }), { + code: 'INVALID_ARGS', + details: { reason: 'artifact_integrity_mismatch' }, + }); + assert.equal(replaced, true); + assert.equal(fs.existsSync(path.join(home, 'config.json')), false); + assert.deepEqual(fs.readdirSync(path.join(home, 'plugins')), []); + assert.equal(fs.existsSync(replacement.sentinel), false); + } finally { + spy.mockRestore(); + } +}); + +test('inventory retains one selection snapshot while a factory awaits', async () => { + const root = mkdtempForTestSync('plugin-artifact-inventory-'); + const key = `agent-device.artifact-inventory.${crypto.randomUUID()}`; + const first = packFixture(path.join(root, 'first'), 'fixture-inventory', undefined, key); + const second = packFixture(path.join(root, 'second'), 'fixture-inventory'); + const { env: isolated } = pluginHome(); + const env = { ...process.env, ...isolated }; + const original = await addPluginArtifact(first.archive, { cwd: root, env }); + let enter!: () => void; + let continueListing!: () => void; + const entered = new Promise((resolve) => { + enter = resolve; + }); + const resume = new Promise((resolve) => { + continueListing = resolve; + }); + const gates = globalThis as typeof globalThis & Record; + gates[Symbol.for(key)] = { enter, resume }; + const listing = listPlugins(env, []); + try { + await entered; + await changePlugin('remove', original.name, env); + const replacement = await addPluginArtifact(second.archive, { cwd: root, env }); + assert.notEqual(replacement.integrity, original.integrity); + continueListing(); + const [entry] = await listing; + assert.deepEqual(entry, { + name: original.name, + installation: original.installation, + integrity: original.integrity, + version: original.version, + provider: 'fixture-inventory', + compatible: true, + }); + const [current] = await listPlugins(env, []); + assert.equal(current?.installation, replacement.installation); + assert.equal(current?.integrity, replacement.integrity); + } finally { + continueListing(); + await listing; + delete gates[Symbol.for(key)]; + } +}); diff --git a/packages/plugins/src/store.ts b/packages/plugins/src/store.ts index ce1752deb3..06375ee03c 100644 --- a/packages/plugins/src/store.ts +++ b/packages/plugins/src/store.ts @@ -185,15 +185,22 @@ async function loadInstallation({ name, entry, selection }: StoreInstallation) { * only once its factory runs, and the registry settles a duplicate then. */ export async function storePluginCandidates(env: NodeJS.ProcessEnv): Promise { + return (await readPluginSnapshot(env)).candidates; +} + +async function readPluginSnapshot(env: NodeJS.ProcessEnv): Promise<{ + candidates: PluginCandidate[]; + selections: Record; +}> { const home = storeHome(env); let selections: [string, PluginSelection][]; try { selections = Object.entries(readPluginConfig(env).plugins ?? {}); } catch (error) { - return [{ source: 'store', load: () => Promise.reject(error) }]; + return { candidates: [{ source: 'store', load: () => Promise.reject(error) }], selections: {} }; } const ordered = selections.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)); - return await Promise.all( + const candidates = await Promise.all( ordered.map(async ([name, selection]): Promise => { try { const installation = await readInstallation(home, name, selection); @@ -216,6 +223,7 @@ export async function storePluginCandidates(env: NodeJS.ProcessEnv): Promise = {}; - try { - selections = readPluginConfig(env).plugins ?? {}; - } catch {} return resolved.inventory().map((entry) => ({ name: entry.package, ...(entry.package && selections[entry.package]?.artifact @@ -402,8 +407,8 @@ export async function addPluginArtifact( const bytes = fs.readFileSync(path.resolve(host.cwd, input)); const integrity = `sha512-${crypto.createHash('sha512').update(bytes).digest('base64')}`; const configPath = resolveUserConfigPath(host.env); - const home = path.dirname(configPath); - fs.mkdirSync(home, { recursive: true, mode: 0o700 }); + fs.mkdirSync(path.dirname(configPath), { recursive: true, mode: 0o700 }); + const home = fs.realpathSync(path.dirname(configPath)); const release = await acquireProcessLock({ lockDirPath: path.join(home, 'plugins.lock'), owner: { ...readCurrentOwnerIdentity(), acquiredAtMs: Date.now() }, @@ -425,6 +430,10 @@ export async function addPluginArtifact( reason: 'invalid_plugin', }); const name = names[0]!; + if (lock.packages?.[`node_modules/${name}`]?.integrity !== integrity) + throw new AppError('INVALID_ARGS', 'Artifact contents changed during installation', { + reason: 'artifact_integrity_mismatch', + }); const directory = installationDirectory(home, name, installation); const root = fs.realpathSync(project); const actualDirectory = fs.realpathSync(directory); From 356a66961b1a73987fa6fd84a1db7fd36be89a80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 19:58:13 +0100 Subject: [PATCH 3/6] test(plugins): exercise managed artifact installation from the packed SDK --- .../installed-package-metro.test.ts | 38 ++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/test/integration/installed-package-metro.test.ts b/test/integration/installed-package-metro.test.ts index 4047655157..fab3651dd0 100644 --- a/test/integration/installed-package-metro.test.ts +++ b/test/integration/installed-package-metro.test.ts @@ -108,11 +108,15 @@ async function typeCheckInstalledPluginContract(consumerRoot: string): Promise }) { + return await addPluginArtifact(archive, host); +} + export async function hostConsumer(host: NonNullable) { const options: StartAgentDeviceOptions = { stateDir: './state', host, plugins: [await example(), maestro(), replay()] }; const running: AgentDeviceHost = await startAgentDevice(options); @@ -323,6 +327,38 @@ test('installed package exposes Node APIs and packaged companion tunnel entrypoi ); } await typeCheckInstalledPluginContract(consumerRoot); + const managedHome = path.join(consumerRoot, 'managed-plugin-home'); + const replayArchive = path.join(consumerRoot, 'replay.tgz'); + const expectedIntegrity = `sha512-${crypto.createHash('sha512').update(fs.readFileSync(replayArchive)).digest('base64')}`; + const selection = await runNodeModuleJson( + consumerRoot, + ['--input-type=module', '-e'], + `import { addPluginArtifact } from 'agent-device/plugins'; + const selected = await addPluginArtifact(${JSON.stringify(replayArchive)}, { + cwd: process.cwd(), + env: { ...process.env, HOME: ${JSON.stringify(managedHome)}, AGENT_DEVICE_HOME: ${JSON.stringify(managedHome)} }, + }); + console.log(JSON.stringify(selected));`, + ); + assert.equal(selection.name, '@agent-device/replay'); + assert.equal(selection.integrity, expectedIntegrity); + const inventory = await runCmd( + process.execPath, + [path.join(installedPackageRoot, 'bin/agent-device.mjs'), 'plugins', 'list', '--json'], + { + cwd: consumerRoot, + env: { ...process.env, HOME: managedHome, AGENT_DEVICE_HOME: managedHome }, + timeoutMs: SUBPROCESS_TIMEOUT_MS, + }, + ); + const selectedPlugin = readJson(inventory.stdout).data.plugins.find( + (plugin: { name?: string }) => plugin.name === '@agent-device/replay', + ); + assert.equal(selectedPlugin?.installation, selection.installation); + assert.equal(selectedPlugin?.integrity, expectedIntegrity); + assert.equal(selectedPlugin?.version, selection.version); + assert.equal(selectedPlugin?.backend, 'ad'); + assert.equal(selectedPlugin?.compatible, true); fs.writeFileSync( path.join(consumerRoot, 'fixture-plugin.mjs'), String.raw` From b719e5d8e158fb7f8301489238c6413ee8902363 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 22:01:35 +0100 Subject: [PATCH 4/6] fix(plugins): preserve host context and clarify artifact receipts --- .changeset/managed-plugin-artifact.md | 2 +- .../src/schema/command-overrides.ts | 2 +- packages/plugins/src/store-artifact.test.ts | 22 +++++- packages/plugins/src/store.test.ts | 23 ++++++ packages/plugins/src/store.ts | 19 ++--- src/cli/commands/__tests__/plugins.test.ts | 74 ++++++++++++++++--- src/cli/commands/plugins.ts | 44 +++++------ website/docs/docs/plugins.md | 2 +- 8 files changed, 132 insertions(+), 56 deletions(-) diff --git a/.changeset/managed-plugin-artifact.md b/.changeset/managed-plugin-artifact.md index 321667654f..9e9f534f30 100644 --- a/.changeset/managed-plugin-artifact.md +++ b/.changeset/managed-plugin-artifact.md @@ -2,4 +2,4 @@ 'agent-device': minor --- -Install local plugin tarballs with `plugins add-artifact` or the plugin manager API. Artifact selections record their version and SHA-512 integrity and require an explicit replacement. +Install local plugin tarballs with `plugins add-artifact` or the plugin manager API. Artifact selections record their version and SHA-512 integrity. To replace one, run `plugins remove ` and then `plugins add-artifact `. Close active sessions and restart the daemon to apply the changed selection. diff --git a/packages/command-surface/src/schema/command-overrides.ts b/packages/command-surface/src/schema/command-overrides.ts index f98467d89b..46ebdf954a 100644 --- a/packages/command-surface/src/schema/command-overrides.ts +++ b/packages/command-surface/src/schema/command-overrides.ts @@ -20,7 +20,7 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = { usageOverride: 'plugins list [--state-dir ]|add |add-artifact |update |remove ', listUsageOverride: 'plugins', - positionalArgs: ['list|add|add-artifact|update|remove', 'package?'], + positionalArgs: ['list|add|add-artifact|update|remove', 'package-or-path?'], flagsByAction: { list: ['stateDir'], add: [], 'add-artifact': [], update: [], remove: [] }, supportedFlags: ['stateDir'], }, diff --git a/packages/plugins/src/store-artifact.test.ts b/packages/plugins/src/store-artifact.test.ts index b630298737..209ecd9ec7 100644 --- a/packages/plugins/src/store-artifact.test.ts +++ b/packages/plugins/src/store-artifact.test.ts @@ -2,7 +2,6 @@ import assert from 'node:assert/strict'; import crypto from 'node:crypto'; import fs from 'node:fs'; import path from 'node:path'; -import { execFileSync } from 'node:child_process'; import { test, vi } from 'vitest'; import * as command from '@agent-device/host-kit/command'; import { mkdtempForTestSync, pluginHome, v2RegistrationSource } from '@agent-device/test-kit'; @@ -55,12 +54,13 @@ function packFixture( };`; } fs.writeFileSync(path.join(source, 'plugin.mjs'), pluginSource); - const output = execFileSync( + const packed = command.runCmdSync( 'npm', ['pack', '--ignore-scripts', '--json', '--pack-destination', root], - { cwd: source, encoding: 'utf8' }, + { cwd: source }, ); - return { archive: path.join(root, JSON.parse(output)[0].filename), sentinel }; + assert.equal(packed.exitCode, 0, packed.stderr); + return { archive: path.join(root, JSON.parse(packed.stdout)[0].filename), sentinel }; } test('artifact installation preserves immutable identity, isolation, collision and stale guard', async () => { @@ -247,3 +247,17 @@ test('inventory retains one selection snapshot while a factory awaits', async () delete gates[Symbol.for(key)]; } }); + +test.each([undefined, '~/plugin-store'])( + 'missing HOME does not preempt archive validation (%s)', + async (override) => { + const root = mkdtempForTestSync('plugin-artifact-home-'); + await assert.rejects( + addPluginArtifact(path.join(root, 'missing.tgz'), { + cwd: root, + env: { HOME: undefined, AGENT_DEVICE_HOME: override }, + }), + { code: 'ENOENT' }, + ); + }, +); diff --git a/packages/plugins/src/store.test.ts b/packages/plugins/src/store.test.ts index 756ac1ee30..ee9c13568b 100644 --- a/packages/plugins/src/store.test.ts +++ b/packages/plugins/src/store.test.ts @@ -317,3 +317,26 @@ test('equivalent nested option key order keeps the daemon selection current', as }, ); }); + +test.each([ + ['1.2.3-01', false], + ['1.2.3-rc.01', false], + ['1.2.3-00', false], + ['1.2.3-0', true], + ['1.2.3-01a', true], + ['1.2.3-1a.0+001', true], + ['1.2.3+01', true], +] as const)('artifact selection validates exact SemVer %s', async (version, valid) => { + const { home, env } = pluginHome(); + selectV2Plugin(home, 'example', v2RegistrationSource('example'), { manifest: { version } }); + const config = readPluginConfig(env); + config.plugins.example.artifact = { + version, + integrity: `sha512-${Buffer.alloc(64).toString('base64')}`, + }; + fs.writeFileSync(path.join(home, 'config.json'), JSON.stringify(config)); + const [entry] = await listPlugins(env, []); + assert.equal(entry?.compatible, valid); + if (valid) assert.equal(entry?.version, version); + assert.equal(vi.mocked(runCmd).mock.calls.length, 0); +}); diff --git a/packages/plugins/src/store.ts b/packages/plugins/src/store.ts index 06375ee03c..80556c8a73 100644 --- a/packages/plugins/src/store.ts +++ b/packages/plugins/src/store.ts @@ -117,12 +117,13 @@ function isVersionSelector(value: unknown): value is string { } function isExactVersion(value: unknown): value is string { - return ( - typeof value === 'string' && - /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test( + if (typeof value !== 'string') return false; + const match = + /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec( value, - ) - ); + ); + if (!match) return false; + return match[4]?.split('.').every((identifier) => !/^0\d+$/.test(identifier)) ?? true; } type StoreInstallation = { @@ -396,14 +397,6 @@ export async function addPluginArtifact( ): Promise<{ name: string; version: string; installation: string; integrity: string }> { if (!input.endsWith('.tgz') || !path.isAbsolute(host.cwd)) throw new AppError('INVALID_ARGS', 'Expected a local .tgz path and an absolute host cwd'); - if ( - !host.env.HOME?.trim() && - (!host.env.AGENT_DEVICE_HOME?.trim() || host.env.AGENT_DEVICE_HOME.trim().startsWith('~')) - ) - throw new AppError( - 'INVALID_ARGS', - 'Provide HOME or an absolute AGENT_DEVICE_HOME in the host environment', - ); const bytes = fs.readFileSync(path.resolve(host.cwd, input)); const integrity = `sha512-${crypto.createHash('sha512').update(bytes).digest('base64')}`; const configPath = resolveUserConfigPath(host.env); diff --git a/src/cli/commands/__tests__/plugins.test.ts b/src/cli/commands/__tests__/plugins.test.ts index abfa00d76c..3a6e937647 100644 --- a/src/cli/commands/__tests__/plugins.test.ts +++ b/src/cli/commands/__tests__/plugins.test.ts @@ -1,9 +1,10 @@ import assert from 'node:assert/strict'; import fs from 'node:fs'; import path from 'node:path'; -import { execFileSync } from 'node:child_process'; +import { runCmdSync } from '@agent-device/host-kit/command'; import { afterEach, test, vi } from 'vitest'; import { runCli } from '../../../cli.ts'; +import * as pluginStore from '@agent-device/plugins/store'; import { readCurrentOwnerIdentity } from '@agent-device/host-kit/process'; import { pluginHome, @@ -111,7 +112,7 @@ test('plugins list reports the running daemon inventory next to the store select }); const { data } = JSON.parse(stdoutCapture.read()); assert.deepEqual(data.daemon, { pid: owner.pid, stateDir, plugins: [failed] }); - assert.equal(data.plugins[0].name, 'example'); + assert.equal(data.artifact.name, 'example'); } finally { stdoutCapture.restore(); } @@ -217,23 +218,76 @@ test('plugins add-artifact installs without loading the factory', async () => { path.join(source, 'plugin.mjs'), `import fs from 'node:fs'; fs.writeFileSync(${JSON.stringify(marker)}, 'factory'); export default () => ({});`, ); - const packed = JSON.parse( - execFileSync('npm', ['pack', '--ignore-scripts', '--json', '--pack-destination', home], { - cwd: source, - encoding: 'utf8', - }), + const packedResult = runCmdSync( + 'npm', + ['pack', '--ignore-scripts', '--json', '--pack-destination', home], + { cwd: source }, ); + assert.equal(packedResult.exitCode, 0, packedResult.stderr); + const packed = JSON.parse(packedResult.stdout); const archive = path.join(home, packed[0].filename); const capture = beginStdoutCapture(); try { await runCli(['plugins', 'add-artifact', archive, '--json'], { sendToDaemon: vi.fn() }); const { data } = JSON.parse(capture.read()); - assert.equal(data.plugins[0].name, 'cli-artifact'); - assert.equal(data.plugins[0].version, '1.0.0'); - assert.match(data.plugins[0].integrity, /^sha512-/); + assert.equal(data.artifact.name, 'cli-artifact'); + assert.equal(data.artifact.version, '1.0.0'); + assert.match(data.artifact.integrity, /^sha512-/); + assert.equal(data.artifact.compatibility, 'unchecked'); + assert.equal('plugins' in data, false); assert.equal(data.restartRequired, true); assert.equal(fs.existsSync(marker), false); } finally { capture.restore(); } }); + +test.each([false, true])('artifact receipt uses the executing CLI host (json=%s)', async (json) => { + const { home, env } = pluginHome(); + const cwd = path.join(home, 'workspace'); + const stateDir = path.join(home, 'state'); + fs.mkdirSync(cwd); + fs.mkdirSync(stateDir); + fs.writeFileSync(path.join(stateDir, 'daemon.json'), '{invalid'); + const host = { + cwd, + env: { + ...process.env, + ...env, + AGENT_DEVICE_STATE_DIR: stateDir, + AGENT_DEVICE_NO_UPDATE_NOTIFIER: '1', + }, + }; + const artifact = { + name: 'cli-artifact', + version: '1.0.0', + installation: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa', + integrity: `sha512-${Buffer.alloc(64).toString('base64')}`, + }; + const install = vi.spyOn(pluginStore, 'addPluginArtifact').mockResolvedValue(artifact); + const sendToDaemon = vi.fn(async () => { + throw new Error('unexpected daemon access'); + }); + const capture = beginStdoutCapture(); + try { + await runCli( + ['plugins', 'add-artifact', './fixture.tgz', ...(json ? ['--json'] : [])], + { sendToDaemon }, + host, + ); + assert.deepEqual(install.mock.calls, [['./fixture.tgz', host]]); + assert.equal(sendToDaemon.mock.calls.length, 0); + const output = capture.read(); + if (json) { + const { data } = JSON.parse(output); + assert.deepEqual(data.artifact, { ...artifact, compatibility: 'unchecked' }); + assert.equal('plugins' in data, false); + assert.equal(data.daemonRecord, 'invalid'); + } else { + assert.match(output, /compatibility unchecked/i); + assert.match(output, /plugins list/); + } + } finally { + capture.restore(); + } +}); diff --git a/src/cli/commands/plugins.ts b/src/cli/commands/plugins.ts index 65a9150451..dc0a6cfc8e 100644 --- a/src/cli/commands/plugins.ts +++ b/src/cli/commands/plugins.ts @@ -10,7 +10,7 @@ import { BUILTIN_PROVIDER_IDS } from '../../builtin-provider-ids.ts'; import { writeCommandOutput } from './shared.ts'; import type { ClientCommandHandler } from './router-types.ts'; -export const pluginsCommand: ClientCommandHandler = async ({ positionals, flags }) => { +export const pluginsCommand: ClientCommandHandler = async ({ host, positionals, flags }) => { const [action = 'list', name, extra] = positionals; if ( extra || @@ -23,28 +23,16 @@ export const pluginsCommand: ClientCommandHandler = async ({ positionals, flags ); } const artifact = - action === 'add-artifact' && name - ? await addPluginArtifact(name, { env: process.env, cwd: process.cwd() }) - : undefined; + action === 'add-artifact' && name ? await addPluginArtifact(name, host) : undefined; if (action !== 'list' && action !== 'add-artifact' && name) { - await changePlugin(action as 'add' | 'update' | 'remove', name, process.env); + await changePlugin(action as 'add' | 'update' | 'remove', name, host.env); } - const plugins = artifact - ? [ - { - ...artifact, - compatible: undefined, - provider: undefined, - backend: undefined, - error: undefined, - }, - ] - : await listPlugins(process.env, BUILTIN_PROVIDER_IDS); - const daemon = readDaemonStatus(resolveDaemonPaths(flags.stateDir)); + const plugins = artifact ? [] : await listPlugins(host.env, BUILTIN_PROVIDER_IDS); + const daemon = readDaemonStatus(resolveDaemonPaths(flags.stateDir, host)); const daemonPlugins = readPluginInventory(daemon.plugins); const failedInDaemon = daemonPlugins.filter(({ state }) => state === 'failed'); const data = { - plugins, + ...(artifact ? { artifact: { ...artifact, compatibility: 'unchecked' } } : { plugins }), ...(daemon.state === 'running' ? { daemon: { pid: daemon.pid, stateDir: daemon.stateDir, plugins: daemonPlugins } } : {}), @@ -53,17 +41,21 @@ export const pluginsCommand: ClientCommandHandler = async ({ positionals, flags }; await writeCommandOutput(flags, data, () => [ - ...plugins.map((plugin) => - plugin.compatible || artifact - ? `${plugin.name}@${plugin.version}${plugin.provider || plugin.backend ? ` (${plugin.provider ?? plugin.backend})` : ''}` - : plugin.name === undefined - ? `Plugin config unavailable: ${plugin.error?.message}` - : `${plugin.name}: unavailable; run plugins update ${plugin.name} or plugins remove ${plugin.name}`, - ), + ...(artifact + ? [ + `${artifact.name}@${artifact.version}: installed; compatibility unchecked. Run agent-device plugins list.`, + ] + : plugins.map((plugin) => + plugin.compatible + ? `${plugin.name}@${plugin.version} (${plugin.provider ?? plugin.backend})` + : plugin.name === undefined + ? `Plugin config unavailable: ${plugin.error?.message}` + : `${plugin.name}: unavailable; run plugins update ${plugin.name} or plugins remove ${plugin.name}`, + )), ...(action !== 'list' ? ['Restart the local daemon after closing active sessions to use the changed plugin set.'] : []), - ...(plugins.length === 0 ? ['No provider plugins installed.'] : []), + ...(!artifact && plugins.length === 0 ? ['No provider plugins installed.'] : []), ...(isUnusableRecord(daemon) ? [ `The daemon record for ${daemon.stateDir} is ${daemon.state}, so its providers are unknown.`, diff --git a/website/docs/docs/plugins.md b/website/docs/docs/plugins.md index 6ea48645e9..e8f4f51f41 100644 --- a/website/docs/docs/plugins.md +++ b/website/docs/docs/plugins.md @@ -207,7 +207,7 @@ agent-device plugins add-artifact ./provider-plugin.tgz --json agent-device plugins list --json ``` -The archive must contain an npm package with a name, an exact version, and an `./agent-device` export. Installation does not run package lifecycle scripts or load the plugin factory. The list command loads the factory to check compatibility. The JSON inventory includes the artifact's installation ID and SHA-512 integrity. If the package is already selected, remove it before adding the artifact. `plugins update` does not update artifacts from the registry; remove the selection and add the replacement artifact. Finish active sessions and restart the daemon after changing the selection. +The archive must contain an npm package with a name, an exact version, and an `./agent-device` export. Installation does not run package lifecycle scripts or load the plugin factory. The list command loads the factory to check compatibility. The installation returns an `artifact` receipt with compatibility marked `unchecked`. Run `plugins list --json` for the checked `plugins` inventory, including the artifact's installation ID and SHA-512 integrity. If the package is already selected, remove it before adding the artifact. `plugins update` does not update artifacts from the registry; remove the selection and add the replacement artifact. Finish active sessions and restart the daemon after changing the selection. A Node.js host can call the same manager with an explicit environment and working directory: From 47b4d14eef3ed9e3783f5469bb9aa9ae0a990e7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 22:06:51 +0100 Subject: [PATCH 5/6] test(plugins): correct list assertions and isolate host fixtures --- src/cli/commands/__tests__/plugins.test.ts | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/cli/commands/__tests__/plugins.test.ts b/src/cli/commands/__tests__/plugins.test.ts index 3a6e937647..eecc23864f 100644 --- a/src/cli/commands/__tests__/plugins.test.ts +++ b/src/cli/commands/__tests__/plugins.test.ts @@ -112,7 +112,7 @@ test('plugins list reports the running daemon inventory next to the store select }); const { data } = JSON.parse(stdoutCapture.read()); assert.deepEqual(data.daemon, { pid: owner.pid, stateDir, plugins: [failed] }); - assert.equal(data.artifact.name, 'example'); + assert.equal(data.plugins[0].name, 'example'); } finally { stdoutCapture.restore(); } @@ -252,7 +252,6 @@ test.each([false, true])('artifact receipt uses the executing CLI host (json=%s) const host = { cwd, env: { - ...process.env, ...env, AGENT_DEVICE_STATE_DIR: stateDir, AGENT_DEVICE_NO_UPDATE_NOTIFIER: '1', @@ -275,7 +274,13 @@ test.each([false, true])('artifact receipt uses the executing CLI host (json=%s) { sendToDaemon }, host, ); - assert.deepEqual(install.mock.calls, [['./fixture.tgz', host]]); + assert.equal(install.mock.calls.length, 1); + assert.equal(install.mock.calls[0]?.[0], './fixture.tgz'); + const installedHost = install.mock.calls[0]![1]; + assert.equal(installedHost.cwd, cwd); + assert.deepEqual(Object.keys(installedHost.env).sort(), Object.keys(host.env).sort()); + for (const [key, value] of Object.entries(host.env)) + assert.equal(installedHost.env[key], value); assert.equal(sendToDaemon.mock.calls.length, 0); const output = capture.read(); if (json) { From 4d0b0108c3a7fc66f404031474582bf8f1224712 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 22:38:47 +0100 Subject: [PATCH 6/6] test(limrun): handle canceled fixture uploads --- .../interactors/limrun-ios-runner.fixtures.ts | 17 ++++++++++++++--- src/core/interactors/limrun-ios-runner.test.ts | 16 ++++++++++++++++ 2 files changed, 30 insertions(+), 3 deletions(-) diff --git a/src/core/interactors/limrun-ios-runner.fixtures.ts b/src/core/interactors/limrun-ios-runner.fixtures.ts index 6fc4eba525..a893808ab0 100644 --- a/src/core/interactors/limrun-ios-runner.fixtures.ts +++ b/src/core/interactors/limrun-ios-runner.fixtures.ts @@ -15,6 +15,18 @@ afterEach(async () => { cleanups.length = 0; }); +async function readRequestBody(request: IncomingMessage): Promise { + const chunks: Buffer[] = []; + try { + for await (const chunk of request) chunks.push(Buffer.from(chunk)); + } catch (error) { + if (request.destroyed && (error as NodeJS.ErrnoException).code === 'ECONNRESET') + return undefined; + throw error; + } + return Buffer.concat(chunks); +} + type Session = Parameters[0]; type Manifest = { files: Array<{ path: string; mode: number }>; @@ -195,9 +207,8 @@ export async function fixture( response.writeHead(401).end(); return; } - const chunks: Buffer[] = []; - for await (const chunk of request) chunks.push(Buffer.from(chunk)); - let body = Buffer.concat(chunks); + let body = await readRequestBody(request); + if (body === undefined) return; if (request.headers['content-encoding'] === 'gzip') body = gunzipSync(body); if (storage.serve(request, response, body)) return; if (request.url === '/v1/ios_test/api/sync') { diff --git a/src/core/interactors/limrun-ios-runner.test.ts b/src/core/interactors/limrun-ios-runner.test.ts index 62c85c4519..da34e8238b 100644 --- a/src/core/interactors/limrun-ios-runner.test.ts +++ b/src/core/interactors/limrun-ios-runner.test.ts @@ -1,5 +1,6 @@ import { promises as fs } from 'node:fs'; import path from 'node:path'; +import { request as httpRequest } from 'node:http'; import { registerRequestAbort, markRequestCanceled, @@ -802,3 +803,18 @@ test('a new cache waiter retries after the canceled preparation finishes cleanup cleanup.mockRestore(); } }); + +test('an interrupted upload does not prevent the fixture from serving a later request', async () => { + const f = await fixture(); + const request = httpRequest(`${f.apiUrl}/sync`, { + method: 'POST', + headers: { authorization: 'Bearer instance-token', 'content-length': '100' }, + }); + request.on('error', () => {}); + request.write('partial'); + await vi.waitFor(() => expect(f.requests).toContain('/v1/ios_test/api/sync')); + request.destroy(); + await new Promise((resolve) => request.once('close', resolve)); + await f.runner.applicationTools.prewarmRunnerCache(f.device, {}, new AbortController().signal); + expect(f.uploads).toHaveLength(1); +});