Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Install catalog npx agents before they start (PRD-9262) (#6184)

Andrew Mikofalvy02a2297beedd
diff --git a/.changeset/prd-9262-teardown-install.md b/.changeset/prd-9262-teardown-install.md
new file mode 100644
index 000000000..d9e7ac622
--- /dev/null
+++ b/.changeset/prd-9262-teardown-install.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Closing an agent conversation while its catalog agent is still installing no longer leaves a broken npm cache entry or starts the agent anyway.
diff --git a/docs/content/features/editor.mdx b/docs/content/features/editor.mdx
index 2eea07f3a..1fbe6a229 100644
--- a/docs/content/features/editor.mdx
+++ b/docs/content/features/editor.mdx
@@ -149,6 +149,8 @@ When an in-app agent needs you to sign in, the chat says so and offers what the
When a catalog-managed agent that OpenKnowledge launches through npx fails because npm reports that the entry in its npx cache is missing its `package.json`, OpenKnowledge deletes that one `_npx/<hash>` directory from npm's cache and relaunches the adapter once before reporting a failure. Custom agent commands and uv-managed adapters are never retried this way. Every launch that does fail, whatever its kind, is recorded with the last lines the adapter printed in [`.ok/local/acp-launch-failures.log`](../reference/what-open-knowledge-writes.mdx#while-a-project-is-open), which bug reports include.
+A catalog-managed npx agent whose catalog entry pins an exact release, such as `<package>@1.2.3`, is installed before it starts, while the chat reads "Installing" followed by the agent's name, and it starts only from that installed copy. That agent runs at npm's `error` log level whatever `loglevel` your npm configuration sets, and npm passes that level on to the agent as `npm_config_loglevel=error`, so npm commands the agent runs in that environment show only errors unless they pass their own `--loglevel`. The installed copy can go missing while OpenKnowledge is running, for example when its `_npx/<hash>` directory is deleted. When npm then reports `npx canceled due to missing packages and no YES option` as the agent starts, OpenKnowledge installs it again once before reporting a failure. Closing the conversation during an install lets the install finish without starting the agent.
+
A startup error ending with "Try again after an allowed release becomes available." means the requested adapter has no eligible release under that policy. Retry after one becomes eligible; OpenKnowledge does not disable your cooldown. Acquisition contacts your configured package registry or Python index; see [network requests](../reference/what-open-knowledge-writes.mdx#what-leaves-your-machine).
### Add your own in-app agent
@@ -171,6 +173,8 @@ Create `.ok/local/acp-agents.json` inside the project, a JSON array with one ent
OpenKnowledge reads the file every time it builds the agent catalog, so once it is saved, open **Settings → Agent connections** (the **Configure agents** row in the launcher menus goes there too). A new custom agent starts folded under **In app**, because nothing has turned it on yet: expand the **Show more** button there (its label counts the folded entries) or type the agent's name in the search box, then turn it on. The agent then appears in the **In app** section of the [Open with AI](#open-with-ai) menu and the **Ask AI** agent picker, and its conversations run in the Agents panel like any other, with the same MCP tools and permission prompts. The npx cache retry described above applies only to catalog-managed agents; a custom command is launched exactly as written.
+A custom command that installs its package as it starts, such as `npx -y <package>`, runs that install inside the agent's own process, so closing the conversation or stopping OpenKnowledge before the install finishes can stop npm partway and leave its `_npx` cache entry incomplete. If that agent then fails on every launch with an npm `ENOENT` error for an `_npx/<hash>/package.json` path, which [`.ok/local/acp-launch-failures.log`](../reference/what-open-knowledge-writes.mdx#while-a-project-is-open) records, delete that whole `_npx/<hash>` directory, or install the agent first and point `command` at the installed program.
+
To make an agent appear for everyone without per-machine configuration, publish its manifest to the ACP registry; it then flows into the catalog on its own.
### From a text selection
diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdx
index 7a8ec70f4..5c0915327 100644
--- a/docs/content/reference/what-open-knowledge-writes.mdx
+++ b/docs/content/reference/what-open-knowledge-writes.mdx
@@ -195,7 +195,7 @@ Beta writes the `~/.ok/` entries below under `~/.ok-beta/` instead, except the s
| `~/.ok/local/installed-skills.json`, `~/.ok/local/skill-placements.json`, `~/.ok/local/skill-move-retained.json`, `~/.ok/skills-lock.json` | The same skill-install markers, placement records, unfinished-scope-move bookkeeping, and import provenance that a project keeps under its own `.ok/`, written under your home directory for Global-scope skills instead. Shared by every product: Beta writes these to `~/.ok/` too | No |
| `~/.ok/stats.jsonl` | Local "open with AI" handoff stats — local-only, no phone-home | No |
| `~/.ok/agent-browser/<chat>/` | Only while **Let agent chats use a browser** is on: `npm/`, the folder that chat's browser server starts from, rebuilt each time it launches, and `files/`, everything the browser saves. Removed when you delete the chat in OpenKnowledge; turning the setting off keeps it, and nothing else clears it, so delete the folder yourself to remove every chat's saved files at once | No |
-| `_npx/<hash>/` in the npm cache that launch uses: your own npm cache (`~/.npm` unless your `npm_config_cache` says otherwise) when the agent runs through your system npx, or OpenKnowledge's managed Node.js runtime cache at `~/.ok/runtimes/cache/node` when no usable system Node.js was found and the agent runs on that runtime | Deleted, not written: when a catalog-managed in-app agent that OpenKnowledge launched through npx fails because npm reports that entry is missing its `package.json`, OpenKnowledge removes that one directory so npx rebuilds it on the single relaunch that follows. The same applies, with one reinstall, to the entry of the browser server a Claude Code or Codex chat starts while **Let agent chats use a browser** is on. Never for custom agent commands or uv-managed adapters | No |
+| `_npx/<hash>/` in the npm cache that launch uses: your own npm cache (`~/.npm` unless your `npm_config_cache` says otherwise) when the agent runs through your system npx, or OpenKnowledge's managed Node.js runtime cache at `~/.ok/runtimes/cache/node` when no usable system Node.js was found and the agent runs on that runtime | Written when OpenKnowledge installs or launches an in-app agent through npx, a custom command such as `npx -y <package>` included, and when the browser server a Claude Code or Codex chat starts while **Let agent chats use a browser** is on installs `@playwright/mcp`. OpenKnowledge repairs the entry only for catalog-managed agents and the browser server, never for custom agent commands or uv-managed adapters. When npm reports that the installed copy is missing as a catalog-managed agent starts, OpenKnowledge installs it again once. When npm reports that the entry is missing its `package.json`, OpenKnowledge deletes that one directory and relaunches the agent once, which installs it again. The browser server's entry is cleared the same way and reinstalled once | No |
| `~/.ok/themes/` | Your saved color themes from the [Themes plugin](../plugins/themes.mdx), one Tinted Theming base16 YAML file per theme, written when you create or edit a theme | No |
| `~/.ok/mcp-status.json` | First-launch MCP consent record | No |
| `~/.ok/logs/`, `~/.ok/bug-reports/` | Desktop and CLI logs, and bug-report bundles from `ok bug-report` and the app's **Help → Report a bug…** dialog (`ok diagnose bundle` writes into the project, under `.ok/local/diagnostics/`). Each report from the dialog also gets a small YAML record holding its send state and a secret-redacted copy of the note you wrote, so report history can still show what a report was about. The zip is deleted once the report is sent; the record is kept, and both go when you delete the report from report history. If that record ever can't be read back, OpenKnowledge leaves it exactly as it is rather than overwriting your note, and writes a second tiny `.sent.yaml` file beside it when a report does send, so history still shows it as sent instead of offering to send it again | No |
@@ -335,7 +335,7 @@ Beta writes the `~/.ok/` entries below under `~/.ok-beta/` instead, except the s
| `~/.ok/local/installed-skills.json`, `~/.ok/local/skill-placements.json`, `~/.ok/local/skill-move-retained.json`, `~/.ok/skills-lock.json` | The same skill-install markers, placement records, unfinished-scope-move bookkeeping, and import provenance that a project keeps under its own `.ok/`, written under your home directory for Global-scope skills instead. Shared by every product: Beta writes these to `~/.ok/` too | No |
| `~/.ok/stats.jsonl` | Local "open with AI" handoff stats — local-only, no phone-home | No |
| `~/.ok/agent-browser/<chat>/` | Only while **Let agent chats use a browser** is on: `npm/`, the folder that chat's browser server starts from, rebuilt each time it launches, and `files/`, everything the browser saves. Removed when you delete the chat in OpenKnowledge; turning the setting off keeps it, and nothing else clears it, so delete the folder yourself to remove every chat's saved files at once | No |
-| `_npx/<hash>/` in the npm cache that launch uses: your own npm cache (`~/.npm` unless your `npm_config_cache` says otherwise) when the agent runs through your system npx, or OpenKnowledge's managed Node.js runtime cache at `~/.ok/runtimes/cache/node` when no usable system Node.js was found and the agent runs on that runtime | Deleted, not written: when a catalog-managed in-app agent that OpenKnowledge launched through npx fails because npm reports that entry is missing its `package.json`, OpenKnowledge removes that one directory so npx rebuilds it on the single relaunch that follows. The same applies, with one reinstall, to the entry of the browser server a Claude Code or Codex chat starts while **Let agent chats use a browser** is on. Never for custom agent commands or uv-managed adapters | No |
+| `_npx/<hash>/` in the npm cache that launch uses: your own npm cache (`~/.npm` unless your `npm_config_cache` says otherwise) when the agent runs through your system npx, or OpenKnowledge's managed Node.js runtime cache at `~/.ok/runtimes/cache/node` when no usable system Node.js was found and the agent runs on that runtime | Written when OpenKnowledge installs or launches an in-app agent through npx, a custom command such as `npx -y <package>` included, and when the browser server a Claude Code or Codex chat starts while **Let agent chats use a browser** is on installs `@playwright/mcp`. OpenKnowledge repairs the entry only for catalog-managed agents and the browser server, never for custom agent commands or uv-managed adapters. When npm reports that the installed copy is missing as a catalog-managed agent starts, OpenKnowledge installs it again once. When npm reports that the entry is missing its `package.json`, OpenKnowledge deletes that one directory and relaunches the agent once, which installs it again. The browser server's entry is cleared the same way and reinstalled once | No |
| `~/.ok/themes/` | Your saved color themes from the [Themes plugin](../plugins/themes.mdx), one Tinted Theming base16 YAML file per theme, written when you create or edit a theme | No |
| `~/.ok/logs/` | CLI logs (`cli.<date>.log`), size- and age-capped | No |
| `~/.ok/bug-reports/` | Bug-report bundles from `ok bug-report` — the desktop app's **Help → Report a bug…** dialog writes here too (`ok diagnose bundle` writes into the project, under `.ok/local/diagnostics/`). A report filed from the dialog also leaves a small YAML record beside its bundle, holding the report's send state and a secret-redacted copy of the note you wrote so report history can name it. That record outlives the bundle: the zip is deleted once the report is sent, and the record is kept until you delete the report from report history. If the record ever can't be read back, OpenKnowledge leaves it exactly as it is rather than overwriting your note, and writes a second tiny `.sent.yaml` file beside it when a report does send. That marker holds only the send time and the report's reference, never your note, and it is removed with the rest of the report | No |
diff --git a/packages/server/src/acp/acquisition-contract.test-helper.ts b/packages/server/src/acp/acquisition-contract.test-helper.ts
index d23dbb73b..d2f80e909 100644
--- a/packages/server/src/acp/acquisition-contract.test-helper.ts
+++ b/packages/server/src/acp/acquisition-contract.test-helper.ts
@@ -90,12 +90,18 @@ export function acquisitionFailureContract(
export type AcquisitionRegistryControl = { closeRegistry: () => Promise<void> };
+export const ARGV_PROBE_PACKAGE = 'ok-argv-probe';
+export const ARGV_PROBE_VERSION = '1.0.0';
+
export async function withLocalAcquisitionRegistry(
run: (home: string, control: AcquisitionRegistryControl) => Promise<void>,
): Promise<void> {
await withAcquisitionHome(async (home) => {
- const packages = new Map<string, Map<string, { bytes: Buffer; published: string }>>();
- for (const { name, version, published } of [
+ const packages = new Map<
+ string,
+ Map<string, { bytes: Buffer; published: string; manifest: { bin?: Record<string, string> } }>
+ >();
+ for (const { name, version, published, bin } of [
{ name: 'is-number', version: '7.0.0', published: '2018-07-04T15:08:58.238Z' },
{ name: 'is-number', version: '6.0.0', published: '2018-03-31T17:02:39.953Z' },
{
@@ -103,10 +109,25 @@ export async function withLocalAcquisitionRegistry(
version: '0.75.1',
published: '2018-07-04T15:08:58.238Z',
},
- ] satisfies { name: string; version: string; published: string }[]) {
+ {
+ name: ARGV_PROBE_PACKAGE,
+ version: ARGV_PROBE_VERSION,
+ published: '2018-07-04T15:08:58.238Z',
+ bin: `process.stdout.write(JSON.stringify({ args: process.argv.slice(2), script: require('node:fs').realpathSync(__filename) }));`,
+ },
+ ] satisfies { name: string; version: string; published: string; bin?: string }[]) {
const directory = join(home, `${name.replaceAll('/', '-')}-${version}`);
mkdirSync(join(directory, 'package'), { recursive: true });
- writeFileSync(join(directory, 'package/package.json'), JSON.stringify({ name, version }));
+ const manifest = bin === undefined ? {} : { bin: { [name]: 'bin.js' } };
+ writeFileSync(
+ join(directory, 'package/package.json'),
+ JSON.stringify({ name, version, ...manifest }),
+ );
+ if (bin !== undefined) {
+ writeFileSync(join(directory, 'package/bin.js'), `#!/usr/bin/env node\n${bin}\n`, {
+ mode: 0o755,
+ });
+ }
const archive = join(directory, 'fixture.tgz');
execFileSync('tar', ['-czf', archive, '-C', directory, 'package']);
let releases = packages.get(name);
@@ -114,7 +135,7 @@ export async function withLocalAcquisitionRegistry(
releases = new Map();
packages.set(name, releases);
}
- releases.set(version, { bytes: readFileSync(archive), published });
+ releases.set(version, { bytes: readFileSync(archive), published, manifest });
}
const endpoint = createServer((req, res) => {
const pathname = decodeURIComponent(req.url ?? '/');
@@ -165,11 +186,12 @@ export async function withLocalAcquisitionRegistry(
name,
'dist-tags': { latest: [...releases.keys()].sort(compareVersions).at(-1) },
versions: Object.fromEntries(
- [...releases].map(([version, { bytes }]) => [
+ [...releases].map(([version, { bytes, manifest }]) => [
version,
{
name,
version,
+ ...manifest,
dist: {
tarball: `http://${req.headers.host}/${name}/${version}.tgz`,
shasum: createHash('sha1').update(bytes).digest('hex'),
diff --git a/packages/server/src/acp/launch-package-acquisition.test.ts b/packages/server/src/acp/launch-package-acquisition.test.ts
index 21a70c19c..93b3233fd 100644
--- a/packages/server/src/acp/launch-package-acquisition.test.ts
+++ b/packages/server/src/acp/launch-package-acquisition.test.ts
@@ -5,6 +5,7 @@ import {
mkdirSync,
readdirSync,
readFileSync,
+ rmSync,
writeFileSync,
} from 'node:fs';
import { createServer } from 'node:http';
@@ -17,11 +18,21 @@ import {
} from '../../../../test-support/capabilities.test-helper.ts';
import { getLogger } from '../logger.ts';
import {
+ ARGV_PROBE_PACKAGE,
+ ARGV_PROBE_VERSION,
acquisitionFailureContract,
withLocalAcquisitionRegistry,
} from './acquisition-contract.test-helper.ts';
-import { AgentLaunchError, agentSpawnPath, resolveRegistryLaunch } from './launch.ts';
import {
+ AgentLaunchError,
+ agentSpawnPath,
+ npxInstallRefused,
+ resolveRegistryLaunch,
+ spawnAcpAgent,
+} from './launch.ts';
+import { entryOutcome, npxEntries } from './npx-cache-entry.test-helper.ts';
+import {
+ captureChild,
installNodeFixture,
npmNative,
npmOutputs,
@@ -37,6 +48,93 @@ acquisitionFailureContract(withLocalAcquisitionRegistry, {
uvxOnAgentSpawnPath: findExecutable('uvx', agentSpawnPath(), executableFacts),
});
+describe('npx launches that OK installs before they start', () => {
+ const spec = `${ARGV_PROBE_PACKAGE}@${ARGV_PROBE_VERSION}`;
+ const resolveInstalled = async (reacquire = false) => {
+ const launch = await resolveRegistryLaunch(
+ registryPackage(spec),
+ null,
+ log,
+ undefined,
+ async (prepared) => prepared,
+ { install: true, reacquire },
+ );
+ if (launch?.kind !== 'npx') throw new Error(`expected an npx launch, got ${launch?.kind}`);
+ return launch;
+ };
+
+ test('the launch refuses to install and runs the copy its install step put in the npx cache', async () => {
+ await withLocalAcquisitionRegistry(async (home) => {
+ const launch = await resolveInstalled();
+ expect(launch.args).toEqual(['--yes=false', '--loglevel=error', spec, '--version']);
+ const installed = npxEntries(home);
+ expect(installed).toHaveLength(1);
+ const entry = String(installed[0]);
+ expect(entryOutcome(entry, ARGV_PROBE_PACKAGE).state).toBe('complete');
+ const run = await captureChild(spawnAcpAgent(launch));
+ expect(run.code, run.stderr).toBe(0);
+ expect(JSON.parse(run.stdout)).toEqual({
+ args: ['--version'],
+ script: join(entry, 'node_modules', ARGV_PROBE_PACKAGE, 'bin.js'),
+ });
+ expect(npxEntries(home)).toEqual([entry]);
+ });
+ }, 90_000);
+
+ test('a launch whose npx cache was wiped is refused before npm installs anything, and runs once reinstalled', async () => {
+ await withLocalAcquisitionRegistry(async (home) => {
+ const launch = await resolveInstalled();
+ const installed = npxEntries(home);
+ expect(installed).toHaveLength(1);
+ const entry = String(installed[0]);
+ expect(entryOutcome(entry, ARGV_PROBE_PACKAGE).state).toBe('complete');
+ rmSync(join(home, 'npm-cache', '_npx'), { recursive: true, force: true });
+ rmSync(join(home, 'npm-cache', '_cacache'), { recursive: true, force: true });
+ const refused = await captureChild(spawnAcpAgent(launch));
+ expect(refused.code, refused.stdout).toBe(1);
+ expect(npxInstallRefused(refused.stderr), refused.stderr).toBe(true);
+ expect(npxEntries(home)).toEqual([entry]);
+ expect(readdirSync(entry)).toEqual([]);
+ expect(await resolveInstalled(true)).toEqual(launch);
+ expect(entryOutcome(entry, ARGV_PROBE_PACKAGE).state).toBe('complete');
+ const run = await captureChild(spawnAcpAgent(launch));
+ expect(run.code, run.stderr).toBe(0);
+ expect(JSON.parse(run.stdout)).toEqual({
+ args: ['--version'],
+ script: join(entry, 'node_modules', ARGV_PROBE_PACKAGE, 'bin.js'),
+ });
+ });
+ }, 90_000);
+
+ test.each([
+ {
+ silencedBy: 'loglevel=silent in the user .npmrc',
+ silence: (home: string) => writeFileSync(join(home, '.npmrc'), 'loglevel=silent\n'),
+ },
+ {
+ silencedBy: 'npm_config_loglevel=silent in the environment',
+ silence: () => {
+ process.env.npm_config_loglevel = 'silent';
+ },
+ },
+ ])(
+ 'a launch whose npx cache was wiped still reports the refusal when $silencedBy',
+ async ({ silence }) => {
+ await withLocalAcquisitionRegistry(async (home) => {
+ silence(home);
+ const launch = await resolveInstalled();
+ expect(npxEntries(home)).toHaveLength(1);
+ rmSync(join(home, 'npm-cache', '_npx'), { recursive: true, force: true });
+ rmSync(join(home, 'npm-cache', '_cacache'), { recursive: true, force: true });
+ const refused = await captureChild(spawnAcpAgent(launch));
+ expect(refused.code, refused.stdout).toBe(1);
+ expect(npxInstallRefused(refused.stderr), refused.stderr).toBe(true);
+ });
+ },
+ 90_000,
+ );
+});
+
describe('hermetic package acquisition and native dispatch', () => {
test('the fixture latest tag is independent of release insertion order', async () => {
await withLocalAcquisitionRegistry(async () => {
diff --git a/packages/server/src/acp/launch-probe-scope.test.ts b/packages/server/src/acp/launch-probe-scope.test.ts
index 3268812ce..da50e2256 100644
--- a/packages/server/src/acp/launch-probe-scope.test.ts
+++ b/packages/server/src/acp/launch-probe-scope.test.ts
@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { describe, expect, test, vi } from 'vitest';
import { getLogger } from '../logger.ts';
@@ -437,6 +437,32 @@ describe('registry launch probe scope', () => {
});
});
+ test('a pinned launch that found no npm sibling still installs before it starts', async () => {
+ await withAcquisitionHome(async (home) => {
+ const { bin } = acquisitionBin(home);
+ const npxLog = join(home, 'npx.log');
+ writeExecutable(
+ join(bin, 'npx'),
+ `require('node:fs').appendFileSync(${JSON.stringify(npxLog)}, JSON.stringify(process.argv.slice(2)) + '\\n');`,
+ );
+ const descriptor = '[email protected]';
+
+ const launch = await resolveRegistryLaunch(
+ registryPackage(descriptor, 'npx', { PATH: bin }),
+ null,
+ log,
+ undefined,
+ (candidate) => Promise.resolve(candidate),
+ { install: true },
+ );
+
+ expect(launch?.args).toEqual(['--yes=false', '--loglevel=error', descriptor, '--version']);
+ expect(readFileSync(npxLog, 'utf8')).toBe(
+ `${JSON.stringify(['--yes', `--package=${descriptor}`, '--call=exit 0'])}\n`,
+ );
+ });
+ });
+
test('a failing probe that outlives a reset does not evict the entry that replaced it', async () => {
await withAcquisitionHome(async (home) => {
const { bin, probeLog, entered, release } = gatedNpmBin(home, 'refuse');
diff --git a/packages/server/src/acp/launch.test.ts b/packages/server/src/acp/launch.test.ts
index a4723e458..06cff8535 100644
--- a/packages/server/src/acp/launch.test.ts
+++ b/packages/server/src/acp/launch.test.ts
@@ -27,6 +27,7 @@ import {
isPathQualified,
MINIMUM_NPX_NODE_MAJOR,
mergedEnv,
+ npxInstallRefused,
overlaySetsPath,
packageAcquisitionFailure,
preflightLaunch,
@@ -1445,6 +1446,49 @@ describe('staleNpxCacheEntry', () => {
});
});
+describe('npxInstallRefused', () => {
+ const refusal =
+ 'npm error npx canceled due to missing packages and no YES option: ["[email protected]"]';
+
+ test("recognizes npm's refusal to install a missing package", () => {
+ expect(npxInstallRefused(`${refusal}\n`)).toBe(true);
+ });
+
+ test('reads the older npm ERR! spelling', () => {
+ expect(
+ npxInstallRefused(
+ 'npm ERR! npx canceled due to missing packages and no YES option: ["[email protected]"]\r\n',
+ ),
+ ).toBe(true);
+ });
+
+ test('finds the refusal after an npm notice line', () => {
+ expect(
+ npxInstallRefused(
+ `npm notice New major version of npm available! 11.19.0 -> 12.2.0\n${refusal}\n`,
+ ),
+ ).toBe(true);
+ });
+
+ test('reads a refusal npm printed with color=always', () => {
+ expect(
+ npxInstallRefused(
+ '\u001b[1mnpm\u001b[22m \u001b[31merror\u001b[39m npx canceled due to missing packages and no YES option: ["[email protected]"]\n',
+ ),
+ ).toBe(true);
+ });
+
+ test.each([
+ [
+ 'a missing file',
+ "npm error code ENOENT\nnpm error syscall open\nnpm error path /Users/andrew/.npm/_npx/4142609e2aa780f6/package.json\nnpm error enoent Could not read package.json: Error: ENOENT: no such file or directory, open '/Users/andrew/.npm/_npx/4142609e2aa780f6/package.json'",
+ ],
+ ['a missing version', 'npm error code ETARGET\nnpm error notarget No matching version found'],
+ ])('ignores %s', (_label, detail) => {
+ expect(npxInstallRefused(detail)).toBe(false);
+ });
+});
+
test('diagnostic stderr hands each kept line to the raw inspector before redaction', () => {
const raw: string[] = [];
const lines: string[] = [];
diff --git a/packages/server/src/acp/launch.ts b/packages/server/src/acp/launch.ts
index 57f06e78a..ff8ca53ef 100644
--- a/packages/server/src/acp/launch.ts
+++ b/packages/server/src/acp/launch.ts
@@ -4,6 +4,7 @@ import { closeSync, constants, createReadStream, existsSync, statSync } from 'no
import { access, chmod, readFile, stat } from 'node:fs/promises';
import { homedir } from 'node:os';
import { basename, delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
import { augmentAgentSpawnPath, OK_HOSTED_AGENT_ENV } from '@inkeep/open-knowledge-core';
import { okUserHomeDir } from '@inkeep/open-knowledge-core/server';
import { z } from 'zod';
@@ -39,6 +40,8 @@ export type NpxCacheEntry = string & { readonly __brand: 'NpxCacheEntry' };
export const MINIMUM_NPX_NODE_MAJOR = 22;
+const NPX_REFUSE_INSTALL = ['--yes=false', '--loglevel=error'] as const;
+
export class AgentLaunchError extends Error {
readonly machineDetail?: string;
readonly npxCacheEntry?: NpxCacheEntry;
@@ -171,15 +174,16 @@ export async function resolveRegistryLaunch(
dist.npx.package,
);
if (pin?.groups === undefined) return launch;
- const { acquired, outcome } = await acquireNpmPackage(
+ const acquired = await acquireNpmPackage(
launch,
pin.groups.name,
pin.groups.version,
log,
reporting,
);
- if (acquisition?.install === true && outcome !== 'forwarded') {
+ if (acquisition?.install === true) {
await ensureNpmPackageInstalled(launch, acquired, log, reporting);
+ return { ...launch, args: [...NPX_REFUSE_INSTALL, acquired, ...(dist.npx.args ?? [])] };
}
return { ...launch, args: ['-y', acquired, ...(dist.npx.args ?? [])] };
}
@@ -298,6 +302,24 @@ export function staleNpxCacheEntry(detail: string): NpxCacheEntry | null {
return null;
}
+export function npxInstallRefused(detail: string): boolean {
+ return /^npm (?:error|ERR!) npx canceled due to missing packages and no YES option: /m.test(
+ stripVTControlCharacters(detail),
+ );
+}
+
+function refusesNpxInstall(args: readonly string[]): boolean {
+ return NPX_REFUSE_INSTALL.every((flag, index) => args[index] === flag);
+}
+
+export function allowNpxInstall(args: readonly string[]): string[] {
+ return refusesNpxInstall(args) ? ['-y', ...args.slice(NPX_REFUSE_INSTALL.length)] : [...args];
+}
+
+export function refusedNpxPackage(args: readonly string[]): string | undefined {
+ return refusesNpxInstall(args) ? args[NPX_REFUSE_INSTALL.length] : undefined;
+}
+
async function npmCommand(launch: ResolvedLaunch): Promise<string | null> {
let npx = launch.cmd;
if (!isPathQualified(npx)) {
@@ -602,7 +624,7 @@ function acquireNpmPackage(
ceiling: string,
log: PinoLogger,
acquisition?: RegistryAcquisitionOptions,
-): Promise<{ acquired: string; outcome: NpmPackageResolution['outcome'] }> {
+): Promise<string> {
const key = acquisitionKey(launch, name, ceiling);
const cached = acquiredNpmPackages.get(key);
const held = heldNpmPackage(cached);
@@ -613,7 +635,7 @@ function acquireNpmPackage(
source: 'memo',
elapsedMs: 0,
});
- return Promise.resolve({ acquired: held.acquired, outcome: held.outcome });
+ return Promise.resolve(held.acquired);
}
const joined = openNpmProbe(cached);
if (joined !== null) acquisition?.onAcquiring?.();
@@ -621,7 +643,7 @@ function acquireNpmPackage(
const source: 'probe' | 'joined' = joined === null ? 'probe' : 'joined';
return probe.then((resolved) => {
acquisition?.onResolved?.({ ...resolved, source });
- return { acquired: resolved.acquired, outcome: resolved.outcome };
+ return resolved.acquired;
});
}
diff --git a/packages/server/src/acp/npx-cache-entry.test-helper.ts b/packages/server/src/acp/npx-cache-entry.test-helper.ts
new file mode 100644
index 000000000..286d04b9f
--- /dev/null
+++ b/packages/server/src/acp/npx-cache-entry.test-helper.ts
@@ -0,0 +1,84 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readProcessState } from '../process-scan.ts';
+
+export function descendantsOf(root: number): number[] {
+ const ps = spawnSync('ps', ['-A', '-o', 'pid=,ppid='], { encoding: 'utf8' });
+ if (ps.error !== undefined) throw ps.error;
+ if (ps.status !== 0) throw new Error(`ps exited ${ps.status}: ${ps.stderr}`);
+ const children = new Map<number, number[]>();
+ for (const line of ps.stdout.split('\n')) {
+ const [pid, ppid] = line.trim().split(/\s+/).map(Number);
+ if (pid === undefined || ppid === undefined || !Number.isInteger(pid) || pid === ps.pid) {
+ continue;
+ }
+ children.set(ppid, [...(children.get(ppid) ?? []), pid]);
+ }
+ const found: number[] = [];
+ const queue = [root];
+ for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+ for (const kid of children.get(next) ?? []) {
+ found.push(kid);
+ queue.push(kid);
+ }
+ }
+ return found;
+}
+
+export function processEnded(pid: number): boolean {
+ const state = readProcessState(pid, {
+ onProbeFailure: ({ reason }) => {
+ throw new Error(`could not read the state of process ${pid}: ${reason}`);
+ },
+ });
+ return state.status === 'gone' || state.status === 'defunct';
+}
+
+export function npxEntries(home: string): string[] {
+ const npxCache = join(home, 'npm-cache', '_npx');
+ return existsSync(npxCache) ? readdirSync(npxCache).map((name) => join(npxCache, name)) : [];
+}
+
+export function hasManifest(dir: string): boolean {
+ return existsSync(join(dir, 'package.json'));
+}
+
+function installedPackages(entry: string): string[] {
+ const modules = join(entry, 'node_modules');
+ return existsSync(modules) ? readdirSync(modules).filter((name) => !name.startsWith('.')) : [];
+}
+
+export function entryOutcome(entry: string, agentName: string) {
+ const packages = installedPackages(entry);
+ const modules = join(entry, 'node_modules');
+ const agentDir = join(modules, agentName);
+ const agentDependencies = hasManifest(agentDir)
+ ? Object.keys(
+ (
+ JSON.parse(readFileSync(join(agentDir, 'package.json'), 'utf8')) as {
+ dependencies?: Record<string, string>;
+ }
+ ).dependencies ?? {},
+ )
+ : [];
+ const snapshot = {
+ rootManifest: hasManifest(entry),
+ lock: existsSync(join(entry, 'concurrency.lock')),
+ packages,
+ withoutManifest: packages.filter((name) => !hasManifest(join(modules, name))),
+ };
+ const complete =
+ snapshot.rootManifest &&
+ !snapshot.lock &&
+ hasManifest(agentDir) &&
+ agentDependencies.every((name) => hasManifest(join(modules, name))) &&
+ snapshot.withoutManifest.length === 0;
+ const rolledBack = !snapshot.rootManifest && !snapshot.lock && packages.length === 0;
+ const state: 'complete' | 'rolled-back' | 'partial' = complete
+ ? 'complete'
+ : rolledBack
+ ? 'rolled-back'
+ : 'partial';
+ return { state, ...snapshot };
+}
diff --git a/packages/server/src/acp/npx-install-server-exit.integration.test.ts b/packages/server/src/acp/npx-install-server-exit.integration.test.ts
index d1f88f08e..42ae1a477 100644
--- a/packages/server/src/acp/npx-install-server-exit.integration.test.ts
+++ b/packages/server/src/acp/npx-install-server-exit.integration.test.ts
@@ -1,14 +1,20 @@
-import { type ChildProcess, execFileSync, fork } from 'node:child_process';
+import { type ChildProcess, fork } from 'node:child_process';
import { existsSync, mkdtempSync, readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { describe, expect, test } from 'vitest';
-import { readProcessState } from '../process-scan.ts';
import { waitWithinTestBudget } from '../wait-within-test-budget.test-helper.ts';
import {
type HeldInstallRegistry,
withHeldInstallRegistry,
} from './held-install-registry.test-helper.ts';
+import {
+ descendantsOf,
+ entryOutcome,
+ hasManifest,
+ npxEntries,
+ processEnded,
+} from './npx-cache-entry.test-helper.ts';
import type { RegistryAgent } from './registry.ts';
const SERVER_PROCESS = fileURLToPath(
@@ -63,44 +69,6 @@ function startServerProcess(held: HeldInstallRegistry): ServerProcess {
};
}
-function descendantsOf(root: number): number[] {
- const table = execFileSync('ps', ['-A', '-o', 'pid=,ppid='], { encoding: 'utf8' });
- const children = new Map<number, number[]>();
- for (const line of table.split('\n')) {
- const [pid, ppid] = line.trim().split(/\s+/).map(Number);
- if (pid === undefined || ppid === undefined || !Number.isInteger(pid)) continue;
- children.set(ppid, [...(children.get(ppid) ?? []), pid]);
- }
- const found: number[] = [];
- const queue = [root];
- for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
- for (const kid of children.get(next) ?? []) {
- found.push(kid);
- queue.push(kid);
- }
- }
- return found;
-}
-
-function processEnded(pid: number): boolean {
- const state = readProcessState(pid, {
- onProbeFailure: ({ reason }) => {
- throw new Error(`could not read the state of process ${pid}: ${reason}`);
- },
- });
- return state.status === 'gone' || state.status === 'defunct';
-}
-
-function npxEntries(home: string): string[] {
- const npxCache = join(home, 'npm-cache', '_npx');
- return existsSync(npxCache) ? readdirSync(npxCache).map((name) => join(npxCache, name)) : [];
-}
-
-function installedPackages(entry: string): string[] {
- const modules = join(entry, 'node_modules');
- return existsSync(modules) ? readdirSync(modules).filter((name) => !name.startsWith('.')) : [];
-}
-
function npmDebugLogs(home: string): string {
const logs = join(home, 'npm-cache', '_logs');
return existsSync(logs)
@@ -111,40 +79,6 @@ function npmDebugLogs(home: string): string {
: '';
}
-function hasManifest(dir: string): boolean {
- return existsSync(join(dir, 'package.json'));
-}
-
-function entryOutcome(entry: string, agentName: string) {
- const packages = installedPackages(entry);
- const modules = join(entry, 'node_modules');
- const agentDir = join(modules, agentName);
- const agentDependencies = hasManifest(agentDir)
- ? Object.keys(
- (
- JSON.parse(readFileSync(join(agentDir, 'package.json'), 'utf8')) as {
- dependencies?: Record<string, string>;
- }
- ).dependencies ?? {},
- )
- : [];
- const snapshot = {
- rootManifest: hasManifest(entry),
- lock: existsSync(join(entry, 'concurrency.lock')),
- packages,
- withoutManifest: packages.filter((name) => !hasManifest(join(modules, name))),
- };
- const complete =
- snapshot.rootManifest &&
- !snapshot.lock &&
- hasManifest(agentDir) &&
- agentDependencies.every((name) => hasManifest(join(modules, name))) &&
- snapshot.withoutManifest.length === 0;
- const rolledBack = !snapshot.rootManifest && !snapshot.lock && packages.length === 0;
- const state = complete ? 'complete' : rolledBack ? 'rolled-back' : 'partial';
- return { state, ...snapshot };
-}
-
const SERVER_ENDINGS = [
{ ending: 'shuts down on SIGTERM', signal: 'SIGTERM', exit: { code: 0, signal: null } },
{ ending: 'is killed', signal: 'SIGKILL', exit: { code: null, signal: 'SIGKILL' } },
diff --git a/packages/server/src/acp/npx-install-teardown.integration.test.ts b/packages/server/src/acp/npx-install-teardown.integration.test.ts
new file mode 100644
index 000000000..847405dc8
--- /dev/null
+++ b/packages/server/src/acp/npx-install-teardown.integration.test.ts
@@ -0,0 +1,222 @@
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { describe, expect, test } from 'vitest';
+import type { AgentSessionManager } from '../agent-sessions.ts';
+import { getLogger } from '../logger.ts';
+import { waitWithinTestBudget } from '../wait-within-test-budget.test-helper.ts';
+import {
+ type HeldInstallRegistry,
+ withHeldInstallRegistry,
+} from './held-install-registry.test-helper.ts';
+import {
+ descendantsOf,
+ entryOutcome,
+ hasManifest,
+ npxEntries,
+ processEnded,
+} from './npx-cache-entry.test-helper.ts';
+import { npmCli } from './package-acquisition.test-helper.ts';
+import { AcpPermissionStore } from './permissions.ts';
+import { AcpRegistry, type RegistryAgent } from './registry.ts';
+import { AcpThreadManager } from './thread-manager.ts';
+
+const log = getLogger('npx-install-teardown-test');
+
+const WAIT = { timeoutMs: 60_000 };
+const TARBALL_ARRIVES_AFTER_MS = 10_000;
+const REGISTRY_AGENT_ID = 'held-install';
+
+const sessionManager = {
+ getSession: async () => {
+ throw new Error('the held agent never uses client fs');
+ },
+ closeAllForAgent: async () => {},
+} as unknown as AgentSessionManager;
+
+function heldManager(held: HeldInstallRegistry): AcpThreadManager {
+ const localDir = mkdtempSync(join(held.home, 'local-'));
+ const contentDir = mkdtempSync(join(held.home, 'content-'));
+ const agent: RegistryAgent = {
+ id: REGISTRY_AGENT_ID,
+ name: 'Held install agent',
+ version: '1.0.0',
+ distribution: { npx: { package: held.npmPackage } },
+ };
+ return new AcpThreadManager({
+ contentDir,
+ localDir,
+ globalDir: null,
+ registry: new AcpRegistry({
+ localDir,
+ log,
+ fetchImpl: (async () => new Response(JSON.stringify({ agents: [agent] }))) as typeof fetch,
+ }),
+ permissions: new AcpPermissionStore(localDir, log),
+ sessionManager,
+ isExcludedPath: () => false,
+ isIgnoredPath: () => false,
+ log,
+ resolveLoginShellPath: async () => null,
+ projectSkillSourceDir: null,
+ });
+}
+
+type InstallingThread = { threadId: string; dependencyRequests: number };
+
+const SITES = [
+ {
+ site: 'a registry agent whose npx lacks npm',
+ open: async (
+ manager: AcpThreadManager,
+ held: HeldInstallRegistry,
+ ): Promise<InstallingThread> => {
+ const npxOnly = join(held.home, 'npx-only-bin');
+ mkdirSync(npxOnly);
+ symlinkSync(npmCli('npx'), join(npxOnly, 'npx'));
+ process.env.PATH = `${npxOnly}${delimiter}${process.env.PATH ?? ''}`;
+ const info = await manager.createThread({
+ agent: { source: 'registry', id: REGISTRY_AGENT_ID },
+ });
+ return { threadId: info.threadId, dependencyRequests: 1 };
+ },
+ },
+ {
+ site: 'a reopened agent whose cache was wiped',
+ open: async (
+ manager: AcpThreadManager,
+ held: HeldInstallRegistry,
+ ): Promise<InstallingThread> => {
+ const first = await manager.createThread({
+ agent: { source: 'registry', id: REGISTRY_AGENT_ID },
+ });
+ held.release('npm-dependency');
+ await waitWithinTestBudget(
+ 'the first thread to install the agent and start it',
+ () => {
+ const status = manager.getInfo(first.threadId)?.status;
+ if (status === 'error' || status === 'exited') {
+ throw new Error(`the first thread settled as ${status}`);
+ }
+ return status === 'ready';
+ },
+ WAIT,
+ );
+ await manager.closeThread(first.threadId);
+ const [installed] = npxEntries(held.home);
+ expect(installed, 'the first thread left an installed npx cache entry').toBeDefined();
+ expect(hasManifest(String(installed))).toBe(true);
+ rmSync(join(held.home, 'npm-cache', '_npx'), { recursive: true, force: true });
+ rmSync(join(held.home, 'npm-cache', '_cacache'), { recursive: true, force: true });
+ held.rearm('npm-dependency');
+ const second = await manager.createThread({
+ agent: { source: 'registry', id: REGISTRY_AGENT_ID },
+ });
+ return { threadId: second.threadId, dependencyRequests: 2 };
+ },
+ },
+] as const;
+
+const TEARDOWNS = [
+ {
+ teardown: 'the thread is closed',
+ run: (manager: AcpThreadManager, threadId: string) => manager.closeThread(threadId),
+ },
+ {
+ teardown: 'the server shuts its threads down',
+ run: (manager: AcpThreadManager) => manager.destroy(),
+ },
+] as const;
+
+const CASES = SITES.flatMap((site) => TEARDOWNS.map((teardown) => ({ ...site, ...teardown })));
+
+describe.skipIf(process.platform === 'win32')(
+ 'tearing down a thread whose agent child is still installing its npx package',
+ () => {
+ test.each(CASES)(
+ 'the npx cache entry ends complete or rolled back when $teardown while $site is installing',
+ async ({ open, run }) => {
+ expect(
+ () => descendantsOf(process.pid),
+ 'this test reads the process table with ps',
+ ).not.toThrow();
+ await withHeldInstallRegistry(async (held) => {
+ const agentName = held.npmPackage.slice(0, held.npmPackage.lastIndexOf('@'));
+ const preexisting = new Set(descendantsOf(process.pid));
+ const started = new Set<number>();
+ const liveSinceStart = (): number[] => {
+ const live = descendantsOf(process.pid).filter((pid) => !preexisting.has(pid));
+ for (const pid of live) started.add(pid);
+ return live;
+ };
+ const everyStartedProcessEnded = (): boolean =>
+ liveSinceStart().length === 0 && [...started].every(processEnded);
+ const manager = heldManager(held);
+ const path = process.env.PATH;
+ try {
+ const { threadId, dependencyRequests } = await open(manager, held);
+ await waitWithinTestBudget(
+ 'npm to request the held dependency tarball mid-install',
+ () => {
+ liveSinceStart();
+ const status = manager.getInfo(threadId)?.status;
+ if (status === 'error' || status === 'exited') {
+ throw new Error(`the thread settled as ${status} before npm reached the tarball`);
+ }
+ return held.requested('npm-dependency') === dependencyRequests;
+ },
+ WAIT,
+ );
+ const entries = npxEntries(held.home);
+ expect(entries).toHaveLength(1);
+ const entry = String(entries[0]);
+ expect(hasManifest(entry), 'npm is still installing when the teardown begins').toBe(
+ false,
+ );
+
+ let teardownSettled = false;
+ const teardownStartedAt = Date.now();
+ const teardown = run(manager, threadId);
+ teardown.then(
+ () => {
+ teardownSettled = true;
+ },
+ () => {
+ teardownSettled = true;
+ },
+ );
+ await waitWithinTestBudget(
+ 'the teardown to settle or the held tarball to outlast every teardown grace',
+ () => {
+ liveSinceStart();
+ return (
+ teardownSettled || Date.now() - teardownStartedAt >= TARBALL_ARRIVES_AFTER_MS
+ );
+ },
+ { timeoutMs: TARBALL_ARRIVES_AFTER_MS + 5_000 },
+ );
+ held.release('npm-dependency');
+ await teardown;
+ await waitWithinTestBudget(
+ 'every process the thread started to exit',
+ everyStartedProcessEnded,
+ WAIT,
+ );
+
+ const outcome = entryOutcome(entry, agentName);
+ expect(['complete', 'rolled-back'], JSON.stringify(outcome)).toContain(outcome.state);
+ } finally {
+ process.env.PATH = path;
+ held.release('npm-dependency');
+ await manager.destroy();
+ await waitWithinTestBudget(
+ 'every process the test started to exit',
+ everyStartedProcessEnded,
+ WAIT,
+ );
+ }
+ });
+ },
+ 150_000,
+ );
+ },
+);
diff --git a/packages/server/src/acp/terminal-auth.test.ts b/packages/server/src/acp/terminal-auth.test.ts
index b7f7a75e9..a2b5b347e 100644
--- a/packages/server/src/acp/terminal-auth.test.ts
+++ b/packages/server/src/acp/terminal-auth.test.ts
@@ -33,6 +33,41 @@ test('a managed-runtime launch puts its bin directory ahead of the terminal PATH
});
});
+test('an npx launch that refuses to install signs in with -y', () => {
+ const base = terminalAuthBaseFor(
+ {
+ ...MANAGED_NPX,
+ args: ['--yes=false', '--loglevel=error', '@augmentcode/[email protected]', '--acp'],
+ },
+ PROCESS_ENV,
+ );
+ expect(base.args).toEqual(['-y', '@augmentcode/[email protected]', '--acp']);
+});
+
+test('only the leading --yes=false of an npx launch becomes -y, never an agent argument', () => {
+ const base = terminalAuthBaseFor(
+ {
+ ...MANAGED_NPX,
+ args: ['--yes=false', '--loglevel=error', '@augmentcode/[email protected]', '--yes=false'],
+ },
+ PROCESS_ENV,
+ );
+ expect(base.args).toEqual(['-y', '@augmentcode/[email protected]', '--yes=false']);
+});
+
+test('a custom command keeps a leading --yes=false as written', () => {
+ const base = terminalAuthBaseFor(
+ {
+ cmd: 'npx',
+ args: ['--yes=false', '[email protected]', '--acp'],
+ env: PROCESS_ENV,
+ kind: 'custom',
+ },
+ PROCESS_ENV,
+ );
+ expect(base.args).toEqual(['--yes=false', '[email protected]', '--acp']);
+});
+
test('only the agent overlay survives into the launch env, never the inherited process env or PATH', () => {
const base = terminalAuthBaseFor(
{
diff --git a/packages/server/src/acp/terminal-auth.ts b/packages/server/src/acp/terminal-auth.ts
index 1592e292c..9570c6164 100644
--- a/packages/server/src/acp/terminal-auth.ts
+++ b/packages/server/src/acp/terminal-auth.ts
@@ -5,7 +5,7 @@ import type {
ThreadAuthMethod,
ThreadAuthTerminalLaunch,
} from '@inkeep/open-knowledge-core/acp/thread-protocol';
-import type { ResolvedLaunch } from './launch.ts';
+import { allowNpxInstall, type ResolvedLaunch } from './launch.ts';
export type TerminalAuthBase = ThreadAuthTerminalLaunch;
@@ -24,7 +24,7 @@ export function terminalAuthBaseFor(
}
return {
executable: launch.cmd,
- args: [...launch.args],
+ args: launch.kind === 'npx' ? allowNpxInstall(launch.args) : [...launch.args],
env,
pathPrepend: managedRuntime ? [dirname(launch.cmd)] : [],
};
diff --git a/packages/server/src/acp/thread-manager.integration.test.ts b/packages/server/src/acp/thread-manager.integration.test.ts
index 0b45ca5e4..786811e8e 100644
--- a/packages/server/src/acp/thread-manager.integration.test.ts
+++ b/packages/server/src/acp/thread-manager.integration.test.ts
@@ -33,7 +33,6 @@ import type { AgentPresenceBroadcaster } from '../agent-presence.ts';
import type { AgentSessionManager } from '../agent-sessions.ts';
import { resolveBundledSkillDir } from '../build-skill-zip.ts';
import { getLogger, type PinoLogger } from '../logger.ts';
-import { isValidLockPid } from '../process-alive.ts';
import { RUNTIME_VERSION } from '../version-constants.ts';
import { withLocalAcquisitionRegistry } from './acquisition-contract.test-helper.ts';
import { isWithin } from './archive.ts';
@@ -41,7 +40,7 @@ import {
type HeldInstallRegistry,
withHeldInstallRegistry,
} from './held-install-registry.test-helper.ts';
-import { agentSpawnPath, resetAcquisitionCache } from './launch.ts';
+import { agentSpawnPath, resetAcquisitionCache, terminateAgentTree } from './launch.ts';
import {
installNodeFixture,
native,
@@ -149,9 +148,11 @@ function internals(manager: AcpThreadManager): {
turnActive: (threadId: string) => boolean;
child: (threadId: string) => ChildProcess | null | undefined;
sessionId: (threadId: string) => string | null | undefined;
+ persisted: (threadId: string) => Promise<void>;
} {
const m = manager as unknown as {
reapIdleThreads: () => void;
+ persistence: { whenIdle: (threadId: string) => Promise<void> };
threads: Map<
string,
{
@@ -168,6 +169,7 @@ function internals(manager: AcpThreadManager): {
turnActive: (threadId) => m.threads.get(threadId)?.turnActive ?? false,
child: (threadId) => m.threads.get(threadId)?.child,
sessionId: (threadId) => m.threads.get(threadId)?.sessionId,
+ persisted: (threadId) => m.persistence.whenIdle(threadId),
};
}
@@ -1139,11 +1141,15 @@ process.stdin.on('data', (chunk) => {
reply({});
}
} else if (msg.method === 'session/prompt') {
- notify({
- sessionUpdate: 'agent_message_chunk',
- content: { type: 'text', text: 'echo:' + msg.params.prompt[0].text },
- });
- reply({ stopReason: 'end_turn' });
+ if (process.env.FAIL_PROMPT === '1') {
+ replyErr(-32603, 'prompt failed');
+ } else {
+ notify({
+ sessionUpdate: 'agent_message_chunk',
+ content: { type: 'text', text: 'echo:' + msg.params.prompt[0].text },
+ });
+ reply({ stopReason: 'end_turn' });
+ }
} else if (msg.method === 'session/load') {
if (process.env.FAIL_LOAD === '1' || msg.params.sessionId !== 'sess-fixed') {
replyErr(-32002, 'unknown session');
@@ -1167,6 +1173,14 @@ process.stdin.on('data', (chunk) => {
});
`;
+function launchesIn(launchLog: string): string[] {
+ return existsSync(launchLog)
+ ? readFileSync(launchLog, 'utf8')
+ .split('\n')
+ .filter((line) => line !== '')
+ : [];
+}
+
function writeResumableAgentEntry(localDir: string, id: string, env: Record<string, string>): void {
const agentPath = join(localDir, `${id}.mjs`);
writeFileSync(agentPath, RESUMABLE_AGENT_SOURCE);
@@ -4531,6 +4545,142 @@ describe('AcpThreadManager retry', () => {
expect(manager.getInfo(info.threadId)?.archived).toBe(true);
await expect(manager.retryThread(info.threadId)).rejects.toThrow(/archived/);
}, 40_000);
+
+ test('a retry closed before its agent spawns keeps a session a restarted server resumes', async () => {
+ const contentDir = tmp();
+ const localDir = tmp();
+ writeResumableAgentEntry(localDir, 'codex-acp', { FAKE_CAPS: 'resume', FAIL_PROMPT: '1' });
+ const release = Promise.withResolvers<string | null>();
+ const entered = Promise.withResolvers<void>();
+ let hold = false;
+ const manager = makeManager(contentDir, localDir, {
+ resolveLoginShellPath: async () => {
+ if (!hold) return null;
+ entered.resolve();
+ return release.promise;
+ },
+ });
+ await manager.init();
+ const info = await manager.createThread({
+ agent: { source: 'custom', id: 'codex-acp' },
+ settings: { contextWindow: 272_000 },
+ });
+ await waitUntil(() => manager.getInfo(info.threadId)?.status === 'ready', 15_000, 'ready');
+ manager.sendPrompt(info.threadId, 'fail this prompt');
+ await waitUntil(
+ () => manager.getInfo(info.threadId)?.status === 'error',
+ 5000,
+ 'prompt failure',
+ );
+
+ hold = true;
+ const retried = manager.retryThread(info.threadId).catch((error: unknown) => error);
+ await entered.promise;
+ await manager.closeThread(info.threadId);
+ expect(manager.getInfo(info.threadId)?.archived).toBe(true);
+ hold = false;
+ release.resolve(null);
+
+ expect(await retried).toMatchObject({
+ code: 'not-ready',
+ message: 'thread closed during retry',
+ });
+ expect(manager.getInfo(info.threadId)?.contextWindow).toBe(272_000);
+ await internals(manager).persisted(info.threadId);
+ await manager.destroy();
+
+ const restarted = makeManager(contentDir, localDir);
+ await restarted.init();
+ expect(restarted.getInfo(info.threadId)?.resumable).toBe(true);
+ const resumed = await restarted.resumeThread(info.threadId);
+ expect(resumed.status).toBe('ready');
+ expect(resumed.contextWindow).toBe(272_000);
+ await restarted.destroy();
+ }, 40_000);
+
+ test('a retry still before its agent spawns when the server shuts down keeps a session the next server resumes', async () => {
+ const contentDir = tmp();
+ const localDir = tmp();
+ writeResumableAgentEntry(localDir, 'codex-acp', { FAKE_CAPS: 'resume', FAIL_PROMPT: '1' });
+ const release = Promise.withResolvers<string | null>();
+ const entered = Promise.withResolvers<void>();
+ let hold = false;
+ const manager = makeManager(contentDir, localDir, {
+ resolveLoginShellPath: async () => {
+ if (!hold) return null;
+ entered.resolve();
+ return release.promise;
+ },
+ });
+ await manager.init();
+ const info = await manager.createThread({
+ agent: { source: 'custom', id: 'codex-acp' },
+ settings: { contextWindow: 272_000 },
+ });
+ await waitUntil(() => manager.getInfo(info.threadId)?.status === 'ready', 15_000, 'ready');
+ manager.sendPrompt(info.threadId, 'fail this prompt');
+ await waitUntil(
+ () => manager.getInfo(info.threadId)?.status === 'error',
+ 5000,
+ 'prompt failure',
+ );
+
+ hold = true;
+ const retried = manager.retryThread(info.threadId).catch((error: unknown) => error);
+ await entered.promise;
+ await manager.destroy();
+
+ const restarted = makeManager(contentDir, localDir);
+ try {
+ await restarted.init();
+ expect(restarted.getInfo(info.threadId)?.resumable).toBe(true);
+ const resumed = await restarted.resumeThread(info.threadId);
+ expect(resumed.status).toBe('ready');
+ expect(resumed.contextWindow).toBe(272_000);
+ } finally {
+ await restarted.destroy();
+ hold = false;
+ release.resolve(null);
+ await retried;
+ await internals(manager).persisted(info.threadId);
+ }
+ }, 40_000);
+
+ test('a failed retry on an open thread leaves no session a restarted server can resume', async () => {
+ const contentDir = tmp();
+ const localDir = tmp();
+ writeResumableAgentEntry(localDir, 'codex-acp', { FAKE_CAPS: 'resume', FAIL_PROMPT: '1' });
+ const manager = makeManager(contentDir, localDir);
+ await manager.init();
+ const info = await manager.createThread({ agent: { source: 'custom', id: 'codex-acp' } });
+ await waitUntil(() => manager.getInfo(info.threadId)?.status === 'ready', 15_000, 'ready');
+ manager.sendPrompt(info.threadId, 'fail this prompt');
+ await waitUntil(
+ () => manager.getInfo(info.threadId)?.status === 'error',
+ 5000,
+ 'prompt failure',
+ );
+ expect(internals(manager).sessionId(info.threadId)).not.toBeNull();
+
+ writeMarkerGatedAgentEntry(localDir, 'codex-acp', join(tmp(), 'never-written'));
+ await expect(manager.retryThread(info.threadId)).rejects.toThrow(/harness not installed/);
+ await internals(manager).persisted(info.threadId);
+ const metaPath = join(localDir, 'threads', `${info.threadId}.meta.json`);
+ const meta = JSON.parse(readFileSync(metaPath, 'utf8')) as { sessionId: string | null };
+ expect(meta.sessionId).toBeNull();
+
+ await manager.closeThread(info.threadId);
+ await internals(manager).persisted(info.threadId);
+ await manager.destroy();
+
+ const restarted = makeManager(contentDir, localDir);
+ try {
+ await restarted.init();
+ expect(restarted.getInfo(info.threadId)?.resumable).toBe(false);
+ } finally {
+ await restarted.destroy();
+ }
+ }, 40_000);
});
function writeSessionFailingAgentEntry(
@@ -5719,6 +5869,145 @@ process.stdin.on('data', (chunk) => {
await manager.closeThread(info.threadId);
}, 45_000);
+ test('a context window change closed before its agent spawns keeps a session a restarted server resumes', async () => {
+ const contentDir = tmp();
+ const localDir = tmp();
+ writeResumableAgentEntry(localDir, 'codex-acp', { FAKE_CAPS: 'resume' });
+ const release = Promise.withResolvers<string | null>();
+ const entered = Promise.withResolvers<void>();
+ let hold = false;
+ const manager = makeManager(contentDir, localDir, {
+ resolveLoginShellPath: async () => {
+ if (!hold) return null;
+ entered.resolve();
+ return release.promise;
+ },
+ });
+ await manager.init();
+ const info = await manager.createThread({
+ agent: { source: 'custom', id: 'codex-acp' },
+ settings: { contextWindow: 272_000 },
+ });
+ await waitUntil(() => manager.getInfo(info.threadId)?.status === 'ready', 15_000, 'ready');
+ manager.sendPrompt(info.threadId, 'retain history');
+ await waitUntil(() => manager.getInfo(info.threadId)?.status === 'ready', 15_000, 'turn ended');
+ await manager.closeThread(info.threadId);
+ expect((await manager.resumeThread(info.threadId)).status).toBe('ready');
+
+ hold = true;
+ const changed = manager
+ .setContextWindow(info.threadId, 872_000)
+ .catch((error: unknown) => error);
+ await entered.promise;
+ await manager.closeThread(info.threadId);
+ expect(manager.getInfo(info.threadId)?.archived).toBe(true);
+ hold = false;
+ release.resolve(null);
+
+ expect(await changed).toMatchObject({
+ code: 'not-ready',
+ message: 'thread closed during the context window change',
+ });
+ expect(manager.getInfo(info.threadId)?.contextWindow).toBe(272_000);
+ await internals(manager).persisted(info.threadId);
+ await manager.destroy();
+
+ const restarted = makeManager(contentDir, localDir);
+ await restarted.init();
+ expect(restarted.getInfo(info.threadId)?.resumable).toBe(true);
+ const resumed = await restarted.resumeThread(info.threadId);
+ expect(resumed.status).toBe('ready');
+ expect(resumed.contextWindow).toBe(272_000);
+ await restarted.destroy();
+ }, 45_000);
+
+ test('a context window change still before its agent spawns when the server shuts down keeps a session the next server resumes', async () => {
+ const contentDir = tmp();
+ const localDir = tmp();
+ writeResumableAgentEntry(localDir, 'codex-acp', { FAKE_CAPS: 'resume' });
+ const release = Promise.withResolvers<string | null>();
+ const entered = Promise.withResolvers<void>();
+ let hold = false;
+ const manager = makeManager(contentDir, localDir, {
+ resolveLoginShellPath: async () => {
+ if (!hold) return null;
+ entered.resolve();
+ return release.promise;
+ },
+ });
+ await manager.init();
+ const info = await manager.createThread({
+ agent: { source: 'custom', id: 'codex-acp' },
+ settings: { contextWindow: 272_000 },
+ });
+ await waitUntil(() => manager.getInfo(info.threadId)?.status === 'ready', 15_000, 'ready');
+ manager.sendPrompt(info.threadId, 'retain history');
+ await waitUntil(() => manager.getInfo(info.threadId)?.status === 'ready', 15_000, 'turn ended');
+ await manager.closeThread(info.threadId);
+ expect((await manager.resumeThread(info.threadId)).status).toBe('ready');
+
+ hold = true;
+ const changed = manager
+ .setContextWindow(info.threadId, 872_000)
+ .catch((error: unknown) => error);
+ await entered.promise;
+ await manager.destroy();
+
+ const restarted = makeManager(contentDir, localDir);
+ try {
+ await restarted.init();
+ expect(restarted.getInfo(info.threadId)?.resumable).toBe(true);
+ const resumed = await restarted.resumeThread(info.threadId);
+ expect(resumed.status).toBe('ready');
+ expect(resumed.contextWindow).toBe(272_000);
+ } finally {
+ await restarted.destroy();
+ hold = false;
+ release.resolve(null);
+ await changed;
+ await internals(manager).persisted(info.threadId);
+ }
+ }, 45_000);
+
+ test('a context window change that fails to apply on an open thread leaves no session a restarted server can resume', async () => {
+ const contentDir = tmp();
+ const localDir = tmp();
+ writeResumableAgentEntry(localDir, 'codex-acp', { FAKE_CAPS: 'resume' });
+ const manager = makeManager(contentDir, localDir);
+ await manager.init();
+ const info = await manager.createThread({
+ agent: { source: 'custom', id: 'codex-acp' },
+ settings: { contextWindow: 272_000 },
+ });
+ await waitUntil(() => manager.getInfo(info.threadId)?.status === 'ready', 15_000, 'ready');
+ manager.sendPrompt(info.threadId, 'retain history');
+ await waitUntil(() => manager.getInfo(info.threadId)?.status === 'ready', 15_000, 'turn ended');
+ await manager.closeThread(info.threadId);
+ expect((await manager.resumeThread(info.threadId)).status).toBe('ready');
+ expect(internals(manager).sessionId(info.threadId)).not.toBeNull();
+
+ writeMarkerGatedAgentEntry(localDir, 'codex-acp', join(tmp(), 'never-written'));
+ await expect(manager.setContextWindow(info.threadId, 872_000)).rejects.toMatchObject({
+ code: 'spawn-failed',
+ });
+ await internals(manager).persisted(info.threadId);
+ const metaPath = join(localDir, 'threads', `${info.threadId}.meta.json`);
+ const meta = JSON.parse(readFileSync(metaPath, 'utf8')) as { sessionId: string | null };
+ expect(meta.sessionId).toBeNull();
+
+ await manager.closeThread(info.threadId);
+ await internals(manager).persisted(info.threadId);
+ await manager.destroy();
+
+ const restarted = makeManager(contentDir, localDir);
+ try {
+ await restarted.init();
+ expect(restarted.getInfo(info.threadId)?.resumable).toBe(false);
+ } finally {
+ await restarted.destroy();
+ }
+ }, 45_000);
+
test('a picked window survives a restart, so a resumed conversation keeps it', async () => {
const contentDir = tmp();
const localDir = tmp();
@@ -6273,7 +6562,7 @@ describe('diagnostic stream lifetime', () => {
20_000,
);
- test('a resume that spawns after close terminates its rejected agent', async () => {
+ test('a resume closed before its agent spawns starts no agent', async () => {
const localDir = tmp();
const id = 'resume-after-close';
const pidFile = join(localDir, 'resumed-pid');
@@ -6314,25 +6603,11 @@ describe('diagnostic stream lifetime', () => {
await manager.closeThread(info.threadId);
expect(manager.getInfo(info.threadId)?.archived).toBe(true);
release.resolve(null);
- expect(await resumed).toMatchObject({ code: 'spawn-failed' });
- const pid = Number(readFileSync(pidFile, 'utf8'));
- expect(
- isValidLockPid(pid),
- `resumed-pid held ${JSON.stringify(readFileSync(pidFile, 'utf8'))}`,
- ).toBe(true);
- await expect
- .poll(
- () => {
- try {
- process.kill(pid, 0);
- return true;
- } catch {
- return false;
- }
- },
- { timeout: 3000 },
- )
- .toBe(false);
+ expect(await resumed).toMatchObject({
+ code: 'not-ready',
+ message: 'thread closed during resume',
+ });
+ expect(existsSync(pidFile)).toBe(false);
const replay: ThreadEvent[] = [];
await manager.subscribe(info.threadId, 0, (frame) => {
if (frame.op === 'event') replay.push(frame.event);
@@ -6341,6 +6616,41 @@ describe('diagnostic stream lifetime', () => {
expect(replay.at(-1)).toMatchObject({ kind: 'status', detail: 'thread closed' });
}, 15_000);
+ test('a resume closed before its agent spawns can be resumed again', async () => {
+ const localDir = tmp();
+ const id = 'resume-again-after-close';
+ writeResumableAgentEntry(localDir, id, { FAKE_CAPS: 'resume' });
+ const release = Promise.withResolvers<string | null>();
+ const entered = Promise.withResolvers<void>();
+ let hold = false;
+ const manager = makeManager(tmp(), localDir, {
+ resolveLoginShellPath: async () => {
+ if (!hold) return null;
+ entered.resolve();
+ return release.promise;
+ },
+ });
+ await manager.init();
+ const info = await manager.createThread({ agent: { source: 'custom', id } });
+ await waitUntil(() => manager.getInfo(info.threadId)?.status === 'ready', 5000, 'ready');
+ manager.sendPrompt(info.threadId, 'retain history');
+ await waitUntil(() => manager.getInfo(info.threadId)?.status === 'ready', 5000, 'prompt');
+ await manager.closeThread(info.threadId);
+
+ hold = true;
+ const cancelled = manager.resumeThread(info.threadId).catch((error: unknown) => error);
+ await entered.promise;
+ await manager.closeThread(info.threadId);
+ hold = false;
+ release.resolve(null);
+ expect(await cancelled).toMatchObject({
+ code: 'not-ready',
+ message: 'thread closed during resume',
+ });
+
+ expect((await manager.resumeThread(info.threadId)).status).toBe('ready');
+ }, 15_000);
+
test.each(['prompt', 'resume'] as const)(
'closing during %s diagnostics keeps thread closed last in replayed history',
async (mode) => {
@@ -7728,6 +8038,105 @@ describe('registry adapter acquisition probe scope across thread opens', () => {
]);
});
}, 90_000);
+
+ test('the refusal recovery reinstalls at most once', async () => {
+ await withAcquisitionHome(async (home) => {
+ const launchLog = join(home, 'launches.log');
+ const refusal = `npm error npx canceled due to missing packages and no YES option: ${JSON.stringify([PINNED_DESCRIPTOR])}\n`;
+ const { bin } = acquisitionBin(
+ home,
+ `const args = process.argv.slice(2);
+ if (args.includes('--call=exit 0')) process.exit(0);
+ process.getBuiltinModule('node:fs').appendFileSync(${JSON.stringify(launchLog)}, JSON.stringify(args) + '\\n');
+ process.stderr.write(${JSON.stringify(refusal)}, () => process.exit(1));`,
+ );
+ const { agentId, manager } = pinnedAdapterManager(home, bin);
+
+ const info = await manager.createThread({ agent: { source: 'registry', id: agentId } });
+ await waitUntil(
+ () =>
+ ['error', 'exited'].includes(manager.getInfo(info.threadId)?.status ?? '') ||
+ launchesIn(launchLog).length > 2,
+ 30_000,
+ 'the refused launch to settle',
+ );
+
+ expect(launchesIn(launchLog)).toHaveLength(2);
+ const statuses = await statusesOf(manager, info.threadId);
+ expect(statuses.filter((status) => status === 'installing' || status === 'spawning')).toEqual(
+ ['spawning', 'installing', 'spawning', 'installing', 'spawning'],
+ );
+ expect(statuses.at(-1)).toBe('error');
+ });
+ }, 60_000);
+
+ test('a conversation closed during its install starts no agent', async () => {
+ await withAcquisitionHome(async (home) => {
+ const hold = join(home, 'install.hold');
+ const launchLog = join(home, 'launches.log');
+ const { bin } = acquisitionBin(
+ home,
+ `const fs = process.getBuiltinModule('node:fs');
+ const args = process.argv.slice(2);
+ if (args.includes('--call=exit 0')) {
+ const parent = process.ppid;
+ const poll = setInterval(() => {
+ if (!fs.existsSync(${JSON.stringify(hold)}) || process.ppid !== parent) {
+ clearInterval(poll);
+ process.exit(0);
+ }
+ }, 25);
+ } else {
+ fs.appendFileSync(${JSON.stringify(launchLog)}, JSON.stringify(args) + '\\n');
+ ${RESUMABLE_AGENT_SOURCE}
+ }`,
+ );
+ const { agentId, manager } = pinnedAdapterManager(home, bin, {
+ FAKE_CAPS: 'resume,load',
+ });
+ await manager.init();
+
+ const info = await manager.createThread({ agent: { source: 'registry', id: agentId } });
+ await waitUntil(
+ () => manager.getInfo(info.threadId)?.status === 'ready',
+ 20_000,
+ 'the open to become ready',
+ );
+ manager.sendPrompt(info.threadId, 'retain this session');
+ await waitUntil(
+ () => manager.getInfo(info.threadId)?.status === 'ready',
+ 20_000,
+ 'the turn to end',
+ );
+ await manager.closeThread(info.threadId);
+ expect(manager.getInfo(info.threadId)?.archived).toBe(true);
+ const firstOpen = launchesIn(launchLog);
+ expect(firstOpen).toHaveLength(1);
+
+ resetAcquisitionCache();
+ writeFileSync(hold, '');
+ const resuming = manager.resumeThread(info.threadId).catch((error: unknown) => error);
+ try {
+ await waitUntil(
+ () => manager.getInfo(info.threadId)?.status === 'installing',
+ 20_000,
+ 'the resume to install the adapter',
+ );
+ await manager.closeThread(info.threadId);
+ } finally {
+ rmSync(hold, { force: true });
+ }
+ await resuming;
+
+ try {
+ expect(launchesIn(launchLog)).toEqual(firstOpen);
+ expect(manager.getInfo(info.threadId)?.status).not.toBe('ready');
+ } finally {
+ const child = internals(manager).child(info.threadId);
+ if (child) await terminateAgentTree(child, { graceMs: 2_000 });
+ }
+ });
+ }, 90_000);
});
describe.skipIf(process.platform === 'win32')(
@@ -8127,16 +8536,28 @@ describe.skipIf(process.platform === 'win32')(
const NPX_ENTRY_HASH = '4142609e2aa780f6';
const NPX_RELAUNCH_LOG = '[acp-threads] cleared a stale npx cache entry; relaunching the agent';
+const NPX_CLOSED_CLEAR_LOG =
+ '[acp-threads] cleared a stale npx cache entry; the thread was closed, so the agent is not relaunched';
const NPX_JOIN_LOG =
'[acp-threads] npx cache entry was cleared by another launch moments ago; relaunching without clearing it again';
-type NpxEnoentMode = 'while-entry-exists' | 'always' | 'stderr-after-stdout-eof';
+type NpxEnoentMode =
+ | 'while-entry-exists'
+ | 'always'
+ | 'stderr-after-stdout-eof'
+ | 'held-after-stdout-eof';
+
+function stdoutEndedMarker(entryDir: string): string {
+ return join(dirname(dirname(dirname(entryDir))), 'npx-stdout-ended');
+}
function npmEnoentSource(entryDir: string, mode: NpxEnoentMode): string {
const fail =
mode === 'stderr-after-stdout-eof'
? `process.stdout.end(() => setTimeout(() => process.stderr.write(lines.join('\\n'), () => process.exit(254)), 150));`
- : `process.stderr.write(lines.join('\\n'), () => process.exit(254));`;
+ : mode === 'held-after-stdout-eof'
+ ? `process.stderr.write(lines.join('\\n'), () => process.stdout.end(() => { process.getBuiltinModule('node:fs').writeFileSync(${JSON.stringify(stdoutEndedMarker(entryDir))}, ''); setTimeout(() => process.exit(254), 10_000); }));`
+ : `process.stderr.write(lines.join('\\n'), () => process.exit(254));`;
return `
const entry = ${JSON.stringify(entryDir)};
if (${mode === 'always' ? 'true' : 'existsSync(entry)'}) {
@@ -8271,6 +8692,29 @@ describe('launch failure diagnostics and npx cache recovery', () => {
);
}, 40_000);
+ test('a conversation closed while its launch reports a stale npx entry still clears the entry', async () => {
+ await withNpxLaunchFixture(
+ 'held-after-stdout-eof',
+ async ({ manager, agentId, entryDir, warn }) => {
+ mkdirSync(entryDir, { recursive: true });
+ const info = await manager.createThread({ agent: { source: 'registry', id: agentId } });
+ await waitUntil(
+ () => existsSync(stdoutEndedMarker(entryDir)),
+ 20_000,
+ 'the failing launch to close its stdout',
+ );
+ await manager.closeThread(info.threadId);
+ await waitUntil(() => !existsSync(entryDir), 5_000, 'the stale entry to be cleared');
+ await waitUntil(
+ () => logCount(warn, NPX_CLOSED_CLEAR_LOG) === 1,
+ 5_000,
+ 'the removal to be logged',
+ );
+ expect(logCount(warn, NPX_RELAUNCH_LOG)).toBe(0);
+ },
+ );
+ }, 40_000);
+
test('a launch that keeps failing on the npx cache is reported after one retry', async () => {
await withNpxLaunchFixture('always', async ({ manager, agentId, entryDir, localDir, warn }) => {
mkdirSync(entryDir, { recursive: true });
@@ -8403,6 +8847,101 @@ describe('launch failure diagnostics and npx cache recovery', () => {
expect(logText).toContain('npm error code ENOENT');
}, 30_000);
+ test('a custom agent whose npx prints the install refusal is launched once and not retried', async () => {
+ const localDir = tmp();
+ const bin = tmp();
+ const launchLog = join(localDir, 'launches.log');
+ const refusal =
+ 'npm error npx canceled due to missing packages and no YES option: ["[email protected]"]\n';
+ writeExecutable(
+ join(bin, 'npx'),
+ `const args = process.argv.slice(2);
+ if (args.join(' ') === '--version') process.exit(0);
+ require('node:fs').appendFileSync(${JSON.stringify(launchLog)}, JSON.stringify(args) + '\\n');
+ process.stderr.write(${JSON.stringify(refusal)}, () => process.exit(1));`,
+ );
+ writeFileSync(
+ join(localDir, 'acp-agents.json'),
+ JSON.stringify([
+ {
+ id: 'refused-npx',
+ name: 'Refused npx agent',
+ command: join(bin, 'npx'),
+ args: ['--yes=false', '[email protected]'],
+ },
+ ]),
+ );
+ const manager = makeManager(tmp(), localDir);
+
+ const info = await manager.createThread({ agent: { source: 'custom', id: 'refused-npx' } });
+ await waitUntil(
+ () => manager.getInfo(info.threadId)?.status === 'error',
+ 20_000,
+ 'launch failure',
+ );
+
+ const launches = launchesIn(launchLog).map((line) => JSON.parse(line) as string[]);
+ expect(launches).toEqual([['--yes=false', '[email protected]']]);
+ expect(manager.getInfo(info.threadId)?.status).toBe('error');
+ }, 30_000);
+
+ test('the reinstall stays silent when the npx refusal lands after stdout closes', async () => {
+ await withAcquisitionHome(async (home) => {
+ const localDir = tmp();
+ const bin = join(home, 'bin');
+ mkdirSync(bin);
+ installNodeFixture(bin);
+ writeRecordingNpm(bin, join(home, 'probes.log'));
+ const refusedOnce = join(home, 'refused-once');
+ const descriptor = '[email protected]';
+ const refusal = `npm error npx canceled due to missing packages and no YES option: ${JSON.stringify([descriptor])}\n`;
+ writeExecutable(
+ join(bin, 'npx'),
+ `const { existsSync, writeFileSync } = require('node:fs');
+ const args = process.argv.slice(2);
+ if (args.join(' ') === '--version' || args.includes('--call=exit 0')) process.exit(0);
+ if (!existsSync(${JSON.stringify(refusedOnce)})) {
+ writeFileSync(${JSON.stringify(refusedOnce)}, '');
+ process.stdout.end(() => setTimeout(() => process.stderr.write(${JSON.stringify(refusal)}, () => process.exit(1)), 150));
+ } else {
+ import(${JSON.stringify(pathToFileURL(EXAMPLE_AGENT).href)});
+ }`,
+ );
+ const agent = registryPackage(descriptor, 'npx', { PATH: bin });
+ const registry = new AcpRegistry({
+ localDir,
+ log,
+ fetchImpl: async () => new Response(JSON.stringify({ agents: [agent] })),
+ });
+ const warn = vi.spyOn(log, 'warn');
+ const manager = makeManager(home, localDir, { registry });
+ try {
+ const info = await manager.createThread({ agent: { source: 'registry', id: agent.id } });
+ await waitUntil(
+ () => manager.getInfo(info.threadId)?.status === 'ready',
+ 20_000,
+ 'agent ready after reinstall',
+ );
+ expect(existsSync(refusedOnce)).toBe(true);
+ expect(
+ logCount(
+ warn,
+ '[acp-threads] npx refused to install a missing agent package; reinstalling it before relaunch',
+ ),
+ ).toBe(1);
+ expect(warn).toHaveBeenCalledWith(
+ expect.objectContaining({ package: descriptor }),
+ '[acp-threads] npx refused to install a missing agent package; reinstalling it before relaunch',
+ );
+ const statuses = await statusesOf(manager, info.threadId);
+ expect(statuses).not.toContain('exited');
+ expect(statuses).not.toContain('error');
+ } finally {
+ await manager.destroy();
+ }
+ });
+ }, 40_000);
+
test('a session setup failure is recorded with its reason', async () => {
const localDir = tmp();
writeSessionFailingAgentEntry(
@@ -8549,6 +9088,57 @@ describe('terminal sign-in methods', () => {
expect(JSON.parse(readFileSync(capsFile, 'utf8'))).toMatchObject({ auth: { terminal: true } });
}, 20_000);
+ test('a catalog npx agent installed by OK signs in through npx -y and its pinned package', async () => {
+ await withAcquisitionHome(async (home) => {
+ const localDir = tmp();
+ const agentPath = writeTerminalAuthAgentEntry(
+ localDir,
+ 'term-auth',
+ {},
+ join(localDir, 'caps.json'),
+ );
+ const bin = join(home, 'bin');
+ mkdirSync(bin);
+ installNodeFixture(bin);
+ writeRecordingNpm(bin, join(home, 'probes.log'));
+ const invocationLog = join(home, 'npx-invocations.log');
+ writeExecutable(
+ join(bin, 'npx'),
+ `const args = process.argv.slice(2);
+ if (args.join(' ') === '--version') process.exit(0);
+ require('node:fs').appendFileSync(${JSON.stringify(invocationLog)}, JSON.stringify(args) + '\\n');
+ if (args.includes('--call=exit 0')) process.exit(0);
+ import(${JSON.stringify(pathToFileURL(agentPath).href)});`,
+ );
+ const descriptor = '[email protected]';
+ const agent = registryPackage(descriptor, 'npx', { PATH: bin });
+ const registry = new AcpRegistry({
+ localDir,
+ log,
+ fetchImpl: async () => new Response(JSON.stringify({ agents: [agent] })),
+ });
+ const manager = makeManager(home, localDir, { registry, terminalAuthAvailable: true });
+
+ const info = await manager.createThread({ agent: { source: 'registry', id: agent.id } });
+ await waitUntil(
+ () => manager.getInfo(info.threadId)?.status === 'auth_required',
+ 20_000,
+ 'sign in',
+ );
+
+ const invocations = launchesIn(invocationLog).map((line) => JSON.parse(line) as string[]);
+ expect(invocations).toContainEqual(
+ expect.arrayContaining([`--package=${descriptor}`, '--call=exit 0']),
+ );
+ expect(manager.terminalAuthLaunch(info.threadId, 'cli-login').args).toEqual([
+ '-y',
+ descriptor,
+ '--version',
+ 'login',
+ ]);
+ });
+ }, 30_000);
+
test('a host without a terminal does not advertise terminal sign-in', async () => {
const localDir = tmp();
const capsFile = join(localDir, 'caps.json');
diff --git a/packages/server/src/acp/thread-manager.ts b/packages/server/src/acp/thread-manager.ts
index 04c72513e..8059aec78 100644
--- a/packages/server/src/acp/thread-manager.ts
+++ b/packages/server/src/acp/thread-manager.ts
@@ -123,11 +123,13 @@ import {
incompatibleNodeHint,
isPathQualified,
type NpxCacheEntry,
+ npxInstallRefused,
packageAcquisitionFailure,
preflightLaunch,
probeInterpreterHealth,
probeNpxNodeCompatibility,
type ResolvedLaunch,
+ refusedNpxPackage,
resolveCustomLaunch,
resolveRegistryLaunch,
rewriteLaunchToManagedRuntime,
@@ -218,7 +220,7 @@ const CONCURRENT_OVERWRITE_REFUSED_CODE = -32009;
type AcquisitionPolicy = 'reuse' | 'reacquire';
-type NpxCacheRecovery = 'available' | 'spent';
+type NpxLaunchRecovery = 'available' | 'spent';
const NPX_CACHE_CLEAR_COOLDOWN_MS = 5 * 60 * 1000;
@@ -349,6 +351,10 @@ interface ThreadRecord {
agentLaunchPath?: string;
agentNpmCache?: string | null;
sessionId: string | null;
+ sessionBeforeRestart: {
+ sessionId: string | null;
+ contextWindow: ThreadInfo['contextWindow'];
+ } | null;
agentSessionId: string;
events: ThreadEvent[];
baseSeq: number;
@@ -710,6 +716,7 @@ export class AcpThreadManager {
lastInit: null,
terminalAuthBase: null,
sessionId: null,
+ sessionBeforeRestart: null,
agentSessionId: `acp-${threadId}`,
events: [],
baseSeq: 0,
@@ -843,7 +850,7 @@ export class AcpThreadManager {
custom: CustomAgentEntry | null,
acquisition: AcquisitionPolicy = 'reuse',
consentBudgetMs: number,
- npxCacheRecovery: NpxCacheRecovery = 'available',
+ npxLaunchRecovery: NpxLaunchRecovery = 'available',
): Promise<{ conn: ClientConnection; init: InitializeResponse; launch: ResolvedLaunch } | null> {
let launch: ResolvedLaunch | null;
if (custom !== null) {
@@ -880,7 +887,7 @@ export class AcpThreadManager {
if (
err instanceof AgentLaunchError &&
err.npxCacheEntry !== undefined &&
- npxCacheRecovery === 'available' &&
+ npxLaunchRecovery === 'available' &&
(await this.clearStaleNpxCacheEntry(record, err.npxCacheEntry))
) {
return this.connectAgent(record, custom, 'reacquire', consentBudgetMs, 'spent');
@@ -888,13 +895,13 @@ export class AcpThreadManager {
throw err;
}
}
- if (launch === null || record.closed) return null;
+ if (launch === null || isThreadClosed(record)) return null;
const loginShellPath = await this.resolveLoginShellPath().catch(() => null);
- if (record.closed) return null;
+ if (isThreadClosed(record)) return null;
record.projectSkill = await this.stageProjectSkillFor(record);
- if (record.closed) return null;
+ if (isThreadClosed(record)) return null;
const terminals = new AcpTerminalSet({
defaultCwd: record.cwd,
@@ -958,12 +965,12 @@ export class AcpThreadManager {
);
const launchKind = launch.kind;
let launchSuperseded = false;
- const staleNpxCacheRecoveryPending = (): boolean =>
+ const npxLaunchRecoveryPending = (): boolean =>
launchKind === 'npx' &&
capturingStartup &&
- npxCacheRecovery === 'available' &&
- staleNpxCacheEntry(rawStartupStderr) !== null;
- const launchStatusMuted = (): boolean => launchSuperseded || staleNpxCacheRecoveryPending();
+ npxLaunchRecovery === 'available' &&
+ (staleNpxCacheEntry(rawStartupStderr) !== null || npxInstallRefused(rawStartupStderr));
+ const launchStatusMuted = (): boolean => launchSuperseded || npxLaunchRecoveryPending();
child.stderr?.setEncoding('utf8');
child.stderr?.on('data', diagnosticCapture.write);
@@ -1165,26 +1172,52 @@ export class AcpThreadManager {
if (acquisitionFailure !== null) throw acquisitionFailure;
}
const staleEntry =
- launchKind === 'npx' && npxCacheRecovery === 'available'
+ launchKind === 'npx' && npxLaunchRecovery === 'available'
? staleNpxCacheEntry(rawStartupStderr)
: null;
if (staleEntry !== null && (await this.clearStaleNpxCacheEntry(record, staleEntry))) {
launchSuperseded = true;
return this.connectAgent(record, custom, 'reacquire', consentBudgetMs, 'spent');
}
+ if (
+ launchKind === 'npx' &&
+ npxLaunchRecovery === 'available' &&
+ npxInstallRefused(rawStartupStderr) &&
+ (await this.discardRefusedNpxLaunch(record, launch))
+ ) {
+ launchSuperseded = true;
+ return this.connectAgent(record, custom, 'reacquire', consentBudgetMs, 'spent');
+ }
throw new ThreadOpError('spawn-failed', `initialize failed: ${agentErrorMessage(err)}`);
} finally {
capturingStartup = false;
startupStderr = '';
rawStartupStderr = '';
}
- if (record.closed) return null;
+ if (isThreadClosed(record)) return null;
record.lastInit = init;
record.info.promptCapabilities = init.agentCapabilities?.promptCapabilities ?? {};
this.emitInfo(record);
return { conn, init, launch };
}
+ private async discardRefusedNpxLaunch(
+ record: ThreadRecord,
+ launch: ResolvedLaunch,
+ ): Promise<boolean> {
+ if (isThreadClosed(record)) return false;
+ this.opts.log.warn(
+ {
+ threadId: record.info.threadId,
+ agentId: record.info.agent.id,
+ package: refusedNpxPackage(launch.args),
+ },
+ '[acp-threads] npx refused to install a missing agent package; reinstalling it before relaunch',
+ );
+ await this.discardFailedLaunch(record);
+ return !isThreadClosed(record);
+ }
+
private async clearStaleNpxCacheEntry(
record: ThreadRecord,
entryDir: NpxCacheEntry,
@@ -1196,6 +1229,15 @@ export class AcpThreadManager {
};
const outcome = await this.removeStaleNpxCacheEntry(entryDir, logContext);
if (outcome === 'kept') return false;
+ if (isThreadClosed(record)) {
+ if (outcome === 'removed') {
+ this.opts.log.warn(
+ logContext,
+ '[acp-threads] cleared a stale npx cache entry; the thread was closed, so the agent is not relaunched',
+ );
+ }
+ return false;
+ }
this.opts.log.warn(
logContext,
outcome === 'recently-removed'
@@ -1286,7 +1328,7 @@ export class AcpThreadManager {
return this.fallbackToManagedRuntime(record, launch, err, undefined, consentBudgetMs);
candidate = viaLoginShell;
}
- if (record.closed) return null;
+ if (isThreadClosed(record)) return null;
return this.ensureInterpreterRuns(record, candidate, consentBudgetMs);
}
@@ -1297,17 +1339,17 @@ export class AcpThreadManager {
): Promise<ResolvedLaunch | null> {
if (launch.kind !== 'npx' && launch.kind !== 'uvx') return launch;
const failure = await this.probeInterpreterOnce(launch);
- if (record.closed) return null;
+ if (isThreadClosed(record)) return null;
if (failure === null) return launch;
if (failure.kind === 'incompatible') {
const preferred = await this.withPreferredLoginShellPathIfEligible(launch);
- if (record.closed) return null;
+ if (isThreadClosed(record)) return null;
if (envPath(preferred.env) !== envPath(launch.env)) {
try {
await preflightLaunch(preferred);
const preferredFailure = await this.probeInterpreterOnce(preferred);
- if (record.closed) return null;
+ if (isThreadClosed(record)) return null;
if (preferredFailure === null) {
this.opts.log.info(
{ threadId: record.info.threadId, agentId: record.info.agent.id },
@@ -1528,7 +1570,7 @@ export class AcpThreadManager {
if (existing !== null) return existing;
const decision = await this.requestRuntimeConsent(record, runtimeKind, reason, consentBudgetMs);
- if (decision === 'closed' || record.closed) return null;
+ if (decision === 'closed' || isThreadClosed(record)) return null;
if (decision !== 'granted') {
throw new RuntimeConsentRefusedError(
decision,
@@ -1538,7 +1580,7 @@ export class AcpThreadManager {
try {
const runtime = await this.downloadRuntime(record, runtimeKind);
- return record.closed ? null : runtime;
+ return isThreadClosed(record) ? null : runtime;
} catch (err) {
const name = describeRuntime(runtimeKind).displayName;
throw new AgentLaunchError(
@@ -1618,7 +1660,7 @@ export class AcpThreadManager {
const now = Date.now();
if (now - lastProgressAt < RUNTIME_PROGRESS_THROTTLE_MS) return;
lastProgressAt = now;
- if (record.closed) return;
+ if (isThreadClosed(record)) return;
this.appendEvent(record, {
kind: 'runtime_install_progress',
runtime: runtimeKind,
@@ -1807,7 +1849,7 @@ export class AcpThreadManager {
npx: ResolvedBrowserNpx,
npmCache: string | null,
packageData: BrowserPackageData = 'cached',
- npxCacheRecovery: NpxCacheRecovery = 'available',
+ npxCacheRecovery: NpxLaunchRecovery = 'available',
): Promise<boolean> {
const context = { threadId: record.info.threadId, agentId: record.agentRef.id };
const ensure = this.opts.ensureBrowserPackage ?? ensureNpmPackageInstalled;
@@ -2339,10 +2381,12 @@ export class AcpThreadManager {
t.info.configOptions = configOptions;
}
await this.applyInitialConfig(t, conn, resumedConfig, configOptions == null);
- if (t.closed) throw new ThreadOpError('not-ready', 'thread closed during resume');
+ if (isThreadClosed(t)) throw new ThreadOpError('not-ready', 'thread closed during resume');
if (resumedModeId !== undefined) {
await this.applyInitialMode(t, conn, resumedModeId, modes == null);
- if (t.closed) throw new ThreadOpError('not-ready', 'thread closed during resume');
+ if (isThreadClosed(t)) {
+ throw new ThreadOpError('not-ready', 'thread closed during resume');
+ }
}
this.emitStatus(t, 'ready');
this.opts.log.info(
@@ -2409,6 +2453,7 @@ export class AcpThreadManager {
t.launchSettings = { ...t.launchSettings, contextWindow: Math.floor(tokens) };
t.resumeInFlight = true;
let applied = false;
+ t.sessionBeforeRestart = { sessionId: t.sessionId, contextWindow: t.info.contextWindow };
try {
const { custom } = await this.resolveAgentInfo(t.agentRef);
await this.teardownFailedAgent(t);
@@ -2422,8 +2467,8 @@ export class AcpThreadManager {
custom,
BLOCKING_CONSENT_TIMEOUT_MS,
);
- if (t.closed) {
- throw new ThreadOpError('spawn-failed', 'thread closed during the context window change');
+ if (isThreadClosed(t)) {
+ throw new ThreadOpError('not-ready', 'thread closed during the context window change');
}
const settled = this.getInfo(threadId)?.status;
if (settled === 'ready' || settled === 'running') {
@@ -2445,8 +2490,10 @@ export class AcpThreadManager {
t.confirmedContextWindow = previousConfirmed;
t.info.contextWindow =
this.getInfo(threadId)?.status === 'ready' ? previousConfirmed : null;
+ this.endRestart(t);
this.emitInfo(t);
}
+ t.sessionBeforeRestart = null;
t.resumeInFlight = false;
}
}
@@ -2464,6 +2511,7 @@ export class AcpThreadManager {
throw new ThreadOpError('not-ready', 'a retry is already in progress');
}
t.resumeInFlight = true;
+ t.sessionBeforeRestart = { sessionId: t.sessionId, contextWindow: t.info.contextWindow };
try {
resetSharedLoginShellPathProvider();
this.healthyInterpreters.clear();
@@ -2487,7 +2535,7 @@ export class AcpThreadManager {
this.emitStatus(t, 'error', detail, { reason: 'connect', agentMessage: detail });
throw new ThreadOpError('spawn-failed', detail);
}
- if (t.closed) throw new ThreadOpError('not-ready', 'thread closed during retry');
+ if (isThreadClosed(t)) throw new ThreadOpError('not-ready', 'thread closed during retry');
const settled = this.getInfo(threadId)?.status;
if (settled === 'ready' || settled === 'running') {
this.opts.log.info(
@@ -2498,6 +2546,7 @@ export class AcpThreadManager {
}
throw new ThreadOpError('spawn-failed', lastFailureMessage(t) ?? 'the agent failed to start');
} finally {
+ if (this.threads.has(threadId) && this.endRestart(t)) this.emitInfo(t);
t.resumeInFlight = false;
}
}
@@ -2557,7 +2606,7 @@ export class AcpThreadManager {
});
throw new ThreadOpError('not-ready', message);
}
- if (t.closed) throw new ThreadOpError('not-ready', 'thread closed during sign-in');
+ if (isThreadClosed(t)) throw new ThreadOpError('not-ready', 'thread closed during sign-in');
if (t.conn !== conn) throw threadRestartedDuringSignIn();
const opened = await this.openSession(
t,
@@ -2619,7 +2668,7 @@ export class AcpThreadManager {
private async abortResume(t: ThreadRecord, failure: ThreadFailureDetail): Promise<void> {
if (isThreadClosed(t)) {
- await this.teardownFailedAgent(t);
+ await this.stopFailedAgent(t);
this.emitStatus(t, 'exited', 'resume failed', failure);
return;
}
@@ -3805,11 +3854,26 @@ export class AcpThreadManager {
}
private async teardownFailedAgent(t: ThreadRecord): Promise<void> {
+ t.sessionId = null;
+ t.info.contextWindow = null;
+ await this.stopFailedAgent(t);
+ }
+
+ private endRestart(t: ThreadRecord): boolean {
+ const previous = t.sessionBeforeRestart;
+ t.sessionBeforeRestart = null;
+ if (previous === null || t.sessionId !== null) return false;
+ if (isThreadClosed(t)) {
+ t.sessionId = previous.sessionId;
+ t.info.contextWindow = previous.contextWindow;
+ }
+ return true;
+ }
+
+ private async stopFailedAgent(t: ThreadRecord): Promise<void> {
this.failPendingPermissions(t);
this.failPendingConsents(t);
t.lastInit = null;
- t.sessionId = null;
- t.info.contextWindow = null;
await this.stopAgentProcess(
t,
'[acp-threads] terminal cleanup on failed-agent teardown failed',
@@ -3849,7 +3913,7 @@ export class AcpThreadManager {
return {
version: 1,
info,
- sessionId: t.sessionId,
+ sessionId: t.sessionId ?? t.sessionBeforeRestart?.sessionId ?? null,
cwd: t.cwd,
agentRef: t.agentRef,
docName: t.docName,
@@ -4006,6 +4070,7 @@ function rehydratedRecord(meta: PersistedThreadMeta): ThreadRecord {
lastInit: null,
terminalAuthBase: null,
sessionId: meta.sessionId,
+ sessionBeforeRestart: null,
agentSessionId: `acp-${meta.info.threadId}`,
events: [],
baseSeq: meta.info.lastSeq + 1,
diff --git a/packages/server/tsconfig.test-helper-callers.json b/packages/server/tsconfig.test-helper-callers.json
index c47532fcb..2cb7def1c 100644
--- a/packages/server/tsconfig.test-helper-callers.json
+++ b/packages/server/tsconfig.test-helper-callers.json
@@ -4,6 +4,7 @@
"files": [
"src/acp/browser-install-teardown.integration.test.ts",
"src/acp/npx-install-server-exit.integration.test.ts",
+ "src/acp/npx-install-teardown.integration.test.ts",
"src/config-file-watcher-readiness.test.ts",
"src/expect-stable.test.ts",
"src/file-watcher-chokidar-fallback.test.ts",