@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/acp/test/realAdapter.js

@@ -0,0 +1,377 @@
+/**
+ * The opt-in real-adapter harness on the processor path (Task 30a). It replaces the real-adapter coverage Task 29 deleted with
+ * `AcpSession` (`qoderContract.test.ts`'s `AXOM_ACP_CONTRACT_COMMAND` certification, `providerLifecycleBaseline`,
+ * `qoderAdapter/acpHostIntegration`): every case opens through `AcpAgents.open` → `ProcessorSession`, over the local transport and
+ * over a real keeper-acp (the built bundle in `dist/keepers`), and reads what the daemon would — the session's frames and its raw log.
+ *
+ * ## Isolation
+ *
+ * Every run gets its own temp config dir (keeper-acp's sockets, raw logs and outboxes live there, never `~/.config/axom`), its own
+ * temp workspace and its own temp HOME. The adapter is started by a small launcher ({@link writeLauncher}) that:
+ * - puts it in a process group of its own (the owned-group cleanup of the deleted certification), and
+ * - replaces its environment with a minimal one read from a 0600 file in the run dir: PATH, the temp HOME, temp `CLAUDE_CONFIG_DIR`,
+ *   `CODEX_HOME`, `XDG_CONFIG_HOME` (all created), the build's own launch env, and only the variables named in
+ *   `AXOM_REAL_ADAPTER_ENV_PASS`. Nothing else of this process's environment (API keys, `CLAUDE_CODE_*`, tokens) reaches the
+ *   adapter, and the environment is never in the spawn's argv (keeper-acp records argv in its label).
+ *
+ * A case that needs a logged-in adapter uses `AXOM_REAL_ADAPTER_AUTH_HOME` as HOME instead of a temp one: a directory the operator
+ * prepared for this purpose (e.g. `HOME=<dir> qodercli` once, then log in). The harness never defaults to the real HOME.
+ *
+ * ## Flags (all off: `npm test` runs only the hermetic cases and reports the rest as skipped, with the reason)
+ *
+ * | variable | effect |
+ * |---|---|
+ * | `AXOM_REAL_ADAPTER_HARNESS=1` | enables the real-adapter tiers at all |
+ * | `AXOM_REAL_ADAPTER_AGENTS=claude-acp,codex-acp` | registry adapters for the no-prompt tier, installed into the temp config dir |
+ * | `AXOM_ACP_CONTRACT_COMMAND` / `AXOM_ACP_CONTRACT_ARGS` | an adapter command (and a JSON argv, default `["--acp"]`): the no-prompt tier, and the Qoder certification's adapter |
+ * | `AXOM_REAL_ADAPTER_PROMPTS=1` | also runs the cases that send prompts (model usage, see each case's cost) |
+ * | `AXOM_REAL_ADAPTER_AUTH_HOME` | HOME for the prompt cases (required by them) |
+ * | `AXOM_REAL_ADAPTER_ENV_PASS=A,B` | extra variables passed through to the adapter (token-based auth) |
+ * | `AXOM_REAL_ADAPTER_TRANSPORTS=local,keeper` | which transports to run on (default both) |
+ * | `AXOM_QODER_SDK_QODERCLI=<path>` | the real SDK adapter tier: `node dist/cli.js qoder-acp --qodercli <path>` (prompts) |
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path, { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AcpKeeperClient } from '../../keepers/acp/client.js';
+import { readKeeperManifest } from '../../keepers/kit/bundle.js';
+import { keeperGen } from '../../keepers/kit/identity.js';
+import { KeeperLauncher } from '../../keepers/kit/launcher.js';
+import { killKeepersUnder } from '../../../test/keeperKit.js';
+import { AcpAgents } from '../acpAgents.js';
+import { KeeperTransport } from '../processor/transport/keeper.js';
+import { LocalTransport } from '../processor/transport/local.js';
+import { RawTruncatedError } from '../processor/transport/types.js';
+import { startRawAgent } from '../processor/test/rawAgent.js';
+import { watch } from './sessionFrames.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const PACKAGE_ROOT = path.join(here, '..', '..', '..', '..');
+export const REAL_KEEPER_DIST = path.join(PACKAGE_ROOT, 'dist', 'keepers');
+const list = (value) => (value ?? '').split(',').map((part) => part.trim()).filter(Boolean);
+export function realAdapterConfig(env = process.env) {
+    const transports = list(env.AXOM_REAL_ADAPTER_TRANSPORTS);
+    for (const name of transports)
+        if (name !== 'local' && name !== 'keeper')
+            throw new Error(`AXOM_REAL_ADAPTER_TRANSPORTS: unknown transport '${name}'`);
+    const args = env.AXOM_ACP_CONTRACT_ARGS ? JSON.parse(env.AXOM_ACP_CONTRACT_ARGS) : ['--acp'];
+    if (!Array.isArray(args) || !args.every((arg) => typeof arg === 'string'))
+        throw new Error('AXOM_ACP_CONTRACT_ARGS must be a JSON array of strings');
+    return {
+        enabled: env.AXOM_REAL_ADAPTER_HARNESS === '1',
+        prompts: env.AXOM_REAL_ADAPTER_PROMPTS === '1',
+        agents: list(env.AXOM_REAL_ADAPTER_AGENTS),
+        ...(env.AXOM_ACP_CONTRACT_COMMAND ? { command: env.AXOM_ACP_CONTRACT_COMMAND } : {}),
+        args,
+        ...(env.AXOM_REAL_ADAPTER_AUTH_HOME ? { authHome: env.AXOM_REAL_ADAPTER_AUTH_HOME } : {}),
+        envPass: list(env.AXOM_REAL_ADAPTER_ENV_PASS),
+        transports: transports.length > 0 ? transports : ['local', 'keeper'],
+        ...(env.AXOM_QODER_SDK_QODERCLI ? { sdkQodercli: env.AXOM_QODER_SDK_QODERCLI } : {}),
+    };
+}
+/** Why a tier does not run (undefined: it runs). Shown as the skipped test's name. */
+export function skipReason(config, tier) {
+    if (!config.enabled)
+        return 'set AXOM_REAL_ADAPTER_HARNESS=1 (see acp/test/realAdapter.ts)';
+    if (tier === 'no-prompt') {
+        return config.command || config.agents.length > 0 ? undefined : 'set AXOM_ACP_CONTRACT_COMMAND or AXOM_REAL_ADAPTER_AGENTS';
+    }
+    if (!config.prompts)
+        return 'sends prompts (model usage): set AXOM_REAL_ADAPTER_PROMPTS=1';
+    if (!config.authHome)
+        return 'needs a logged-in adapter: set AXOM_REAL_ADAPTER_AUTH_HOME';
+    if (tier === 'qoder')
+        return config.command ? undefined : 'set AXOM_ACP_CONTRACT_COMMAND to qodercli';
+    return config.sdkQodercli ? undefined : 'set AXOM_QODER_SDK_QODERCLI to qodercli';
+}
+/**
+ * A provider history failure fails certification but never prevents local teardown; each local step is guarded on its own, so one
+ * failure cannot strand the resources after it. Every failure is reported together.
+ */
+export async function cleanupOwnedFixture(actions) {
+    const failures = [];
+    try {
+        await actions.deleteSession();
+    }
+    catch (error) {
+        failures.push(error);
+    }
+    finally {
+        for (const release of [actions.closeTransport, actions.killOwnedGroup, actions.removeWorkspace]) {
+            try {
+                await release();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+    }
+    if (failures.length)
+        throw new AggregateError(failures, `Qoder cleanup incomplete: ${failures.map(String).join('; ')}`);
+}
+export async function bounded(promise, label, ms) {
+    let timer;
+    try {
+        return await Promise.race([promise, new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`UNCERTIFIED: ${label} exceeded ${ms}ms`)), ms);
+            })]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ---- launcher and environment -------------------------------------------------------------------------------------------------
+/**
+ * `launch.cjs <envFile> <pidFile> <command> ...args`: spawns the adapter detached (its own process group), with exactly the
+ * environment in `envFile`, stdio inherited (the pipes keeper-acp or the local transport gave the launcher), and records its pid.
+ * It forwards SIGTERM/SIGINT to the group and exits with the adapter.
+ */
+const LAUNCHER = `const {spawn}=require('node:child_process');const fs=require('node:fs');
+const [envFile,pidFile,command,...args]=process.argv.slice(2);
+const env=JSON.parse(fs.readFileSync(envFile,'utf8'));
+const child=spawn(command,args,{detached:true,stdio:'inherit',env});
+fs.writeFileSync(pidFile,String(child.pid));
+for(const signal of ['SIGTERM','SIGINT'])process.on(signal,()=>{try{process.kill(-child.pid,signal)}catch{}});
+child.on('exit',(code,signal)=>process.exit(code??(signal?1:0)));
+child.on('error',(error)=>{process.stderr.write(String(error)+'\\n');process.exit(127)});`;
+export async function writeLauncher(dir) {
+    const file = join(dir, 'launch.cjs');
+    await writeFile(file, LAUNCHER);
+    return file;
+}
+/** The adapter's whole environment (see the file comment). `home` is created when it is a temp one. */
+export async function isolatedEnv(home, config, launchEnv = {}) {
+    const env = {
+        PATH: launchEnv.PATH ?? process.env.PATH ?? '/usr/bin:/bin', HOME: home,
+        CLAUDE_CONFIG_DIR: join(home, '.claude'), CODEX_HOME: join(home, '.codex'), XDG_CONFIG_HOME: join(home, '.config'),
+    };
+    for (const name of config.envPass) {
+        const value = process.env[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    Object.assign(env, launchEnv);
+    for (const dir of [env.CLAUDE_CONFIG_DIR, env.CODEX_HOME, env.XDG_CONFIG_HOME])
+        await mkdir(dir, { recursive: true });
+    return env;
+}
+export async function startRun(transport, prefix) {
+    const configDir = await mkdtemp(join(tmpdir(), `${prefix}-${transport}-cfg-`));
+    const runDir = await mkdtemp(join(tmpdir(), `${prefix}-${transport}-run-`));
+    if (transport === 'local') {
+        const local = new LocalTransport({ configDir });
+        const acp = new AcpAgents({ cacheDir: configDir, transports: { local }, sessionStartTimeoutMs: 60_000 });
+        return { transport, configDir, runDir, acp, reader: local, async dispose() {
+                await local.dispose(0);
+                for (const dir of [configDir, runDir])
+                    await rm(dir, { recursive: true, force: true });
+            } };
+    }
+    const launcher = new KeeperLauncher({ configDir, workstationId: 'ws-t30a', server: 'http://test.invalid', distDir: REAL_KEEPER_DIST,
+        useSystemd: false, startTimeoutMs: 20_000, umask: 0o022 });
+    const keeper = new KeeperTransport(new AcpKeeperClient({ launcher }));
+    const acp = new AcpAgents({ cacheDir: configDir, transports: { keeper }, sessionStartTimeoutMs: 60_000 });
+    return { transport, configDir, runDir, acp, reader: keeper, async dispose() {
+            keeper.close();
+            const gen = keeperGen((await readKeeperManifest(join(REAL_KEEPER_DIST, 'acp'))).buildVersion);
+            await launcher.stop('acp', gen, 'force').catch(() => { });
+            killKeepersUnder(configDir);
+            for (const dir of [configDir, runDir])
+                await rm(dir, { recursive: true, force: true });
+        } };
+}
+/**
+ * Every retained raw record of `sessionKey`. A turn's end cuts a checkpoint and the transport may drop the records before it, so a
+ * case that needs the open's lines reads them before its first turn.
+ */
+export async function readAllRaw(run, sessionKey) {
+    const records = [];
+    for (let at = 0;;) {
+        let page;
+        try {
+            page = await run.reader.readRaw(sessionKey, at);
+        }
+        catch (error) {
+            if (!(error instanceof RawTruncatedError) || at !== 0)
+                throw error;
+            at = error.first;
+            continue;
+        }
+        if (page.length === 0)
+            break;
+        records.push(...page);
+        at = page[page.length - 1].o + 1;
+    }
+    return records;
+}
+export const downMethodsOf = (records) => records.filter((r) => r.kind === 'down')
+    .map((r) => JSON.parse(r.line).method).filter((m) => m !== undefined);
+let refCounter = 0;
+/** The launcher argv (and its 0600 env file) for one adapter process of `ref`. */
+async function launcherArgs(run, ref, launch, options) {
+    const envFile = join(run.runDir, `${ref}.env.json`);
+    const pidFile = join(run.runDir, `${ref}.pid`);
+    await writeFile(envFile, JSON.stringify(await isolatedEnv(options.home, options.config, launch.launchEnv)), { mode: 0o600 });
+    await chmod(envFile, 0o600);
+    const launcher = await writeLauncher(run.runDir);
+    return { args: [launcher, envFile, pidFile, launch.command, ...launch.args], pidFile };
+}
+export async function openReal(run, launch, options) {
+    refCounter += 1;
+    const ref = `real-${refCounter}`;
+    const { args, pidFile } = await launcherArgs(run, ref, launch, options);
+    let opened;
+    try {
+        opened = await run.acp.open({ agentId: launch.agentId, cwd: options.cwd, env: { HOME: options.home }, agentEnv: {},
+            command: process.execPath, args, sessionRef: ref, agentKey: 'real-harness', ...options.over });
+    }
+    catch (error) {
+        // The ref, so a case can read what the refused open wrote (and kill what it started).
+        throw Object.assign(error instanceof Error ? error : new Error(String(error)), { harnessRef: ref, pidFile });
+    }
+    const onEvent = options.onEvent;
+    const watched = watch(opened.session, onEvent ? (event) => onEvent(event, opened.session) : undefined);
+    return { ref, session: opened.session, nativeSessionId: opened.nativeSessionId, watched, pidFile,
+        keeperHosted: run.acp.placementOf(opened.session)?.keeper === true };
+}
+/** A JSON-RPC error answer as an outcome: `-32601` (method not found) is the adapter rejecting the method itself. */
+const errorOutcome = (error) => error.code === -32601 ? 'unsupported' : `failed: ${error.code ?? '?'} ${error.message ?? ''}`.trimEnd();
+/**
+ * `session/delete` on a still-open session's own connection (what the deleted harness did, before closing its transport): an
+ * `rpc.request` note, the processor writes the request, and the answer is read back from the raw log. `not-sent` when the session is
+ * no longer connected (the processor drops the note) or nothing came back in time.
+ */
+export async function deleteOnLive(run, opened, id, timeoutMs = 15_000) {
+    if (!opened.session.liveness.agentAlive)
+        return 'not-sent';
+    await opened.session.note({ type: 'rpc.request', method: 'session/delete', params: { sessionId: id } });
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const lines = (await readAllRaw(run, opened.ref)).filter((r) => r.kind === 'up' || r.kind === 'down')
+            .map((r) => ({ kind: r.kind, message: JSON.parse(r.line) }));
+        const request = lines.filter((l) => l.kind === 'down' && l.message.method === 'session/delete' && l.message.params?.sessionId === id).at(-1);
+        const answer = request && lines.find((l) => l.kind === 'up' && l.message.method === undefined && l.message.id === request.message.id);
+        if (answer)
+            return answer.message.error ? errorOutcome(answer.message.error) : 'deleted';
+        await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+    return 'not-sent';
+}
+/**
+ * `session/delete` straight over a fresh adapter process (raw ndjson, our own `initialize`), whatever the adapter advertised — the
+ * deleted harness sent it unconditionally. Same launcher and environment as the sessions.
+ */
+async function deleteDirect(run, launch, options, ids) {
+    refCounter += 1;
+    const { args, pidFile } = await launcherArgs(run, `delete-direct-${refCounter}`, launch, options);
+    const agent = startRawAgent({ command: process.execPath, args });
+    const outcomes = {};
+    try {
+        agent.send(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: 1, clientCapabilities: {} } }));
+        await agent.nextLine((m) => m.id === 1 && m.method === undefined, 30_000);
+        for (const [index, id] of ids.entries()) {
+            const rpcId = 2 + index;
+            agent.send(JSON.stringify({ jsonrpc: '2.0', id: rpcId, method: 'session/delete', params: { sessionId: id } }));
+            const answer = JSON.parse(await agent.nextLine((m) => m.id === rpcId && m.method === undefined, 30_000));
+            outcomes[id] = answer.error ? errorOutcome(answer.error) : 'deleted';
+        }
+    }
+    finally {
+        await agent.close();
+        await killOwnedGroup(pidFile);
+    }
+    return outcomes;
+}
+/**
+ * Deletes the test-owned native sessions; throws unless every one was deleted. Order (the ruling of T30a fix round 1):
+ * 1. on the session's own live connection, before its transport closes (the deleted harness's order — an adapter may refuse a
+ *    delete from another process while the session is open);
+ * 2. what is left, over a throwaway connection through the production `deleteNativeSessions`;
+ * 3. if that answered `unsupported` only because the adapter does not advertise `sessionCapabilities.delete`, the request is sent
+ *    directly anyway (logged `advertised:false`). `unsupported` is reported only when the adapter itself rejects the method.
+ * Which order a real Qoder needs is not known without one; both run, and the log line says which one deleted each id (T30b reads it).
+ */
+export async function deleteOwnedSessions(run, launch, options, sessions) {
+    const ids = [...new Set(sessions.map((s) => s.nativeSessionId).filter((id) => !!id))];
+    const outcomes = {};
+    for (const id of ids) {
+        const live = [...sessions].reverse().find((s) => s.nativeSessionId === id && s.session.liveness.agentAlive);
+        if (live)
+            outcomes[id] = { via: 'live', outcome: await deleteOnLive(run, live, id) };
+    }
+    const rest = ids.filter((id) => outcomes[id]?.outcome !== 'deleted');
+    if (rest.length > 0) {
+        refCounter += 1;
+        const { args, pidFile } = await launcherArgs(run, `delete-${refCounter}`, launch, options);
+        let results;
+        try {
+            results = await run.acp.deleteNativeSessions({ agentId: launch.agentId, cwd: options.cwd, env: { HOME: options.home }, agentEnv: {},
+                command: process.execPath, args }, rest);
+        }
+        finally {
+            await killOwnedGroup(pidFile);
+        }
+        for (const result of results)
+            outcomes[result.nativeSessionId] = { via: 'deleteNativeSessions', outcome: result.outcome === 'failed'
+                    ? `failed: ${result.error ?? ''}` : result.outcome };
+        const unadvertised = rest.filter((id) => outcomes[id]?.outcome === 'unsupported');
+        if (unadvertised.length > 0) {
+            console.info('Qoder owned-session delete', JSON.stringify({ advertised: false, ids: unadvertised }));
+            for (const [id, outcome] of Object.entries(await deleteDirect(run, launch, options, unadvertised)))
+                outcomes[id] = { via: 'direct', outcome };
+        }
+    }
+    console.info('Qoder owned-session delete', JSON.stringify(outcomes));
+    const failed = ids.filter((id) => outcomes[id]?.outcome !== 'deleted');
+    if (failed.length > 0)
+        throw new Error(`owned session/delete failed: ${JSON.stringify(Object.fromEntries(failed.map((id) => [id, outcomes[id]])))}`);
+}
+/** The ref and pid file of an open that failed ({@link openReal} attaches them to the error). */
+export const failedOpen = (error) => (error ?? {});
+/** An adapter refused `session/new` / `session/load` for want of credentials (ACP `auth_required`, -32000). */
+export const isAuthRequired = (error) => error.errorCode === -32000 || /authentication required|auth_required/i.test(String(error));
+/** Kills the adapter's own process group (from its pid file); an exited group or a launch that never wrote one is fine. */
+export async function killOwnedGroup(pidFile) {
+    try {
+        const pid = Number(await readFile(pidFile, 'utf8'));
+        if (!Number.isInteger(pid) || pid <= 1)
+            throw new Error('Invalid owned process group ID');
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT' && code !== 'ESRCH')
+            throw error;
+    }
+}
+/** Sends one prompt and waits for its `agent_turn_done`; returns the turn and the events it produced. */
+export async function turn(opened, text, timeoutMs) {
+    const start = opened.watched.events.length;
+    const n = opened.watched.turns.length + 1;
+    const done = opened.watched.turn(n);
+    opened.session.prompt([{ type: 'text', text }], `turn-${refCounter}-${n}`);
+    const result = await bounded(done, 'prompt', timeoutMs);
+    return { done: result, events: opened.watched.events.slice(start) };
+}
+/** Drains a load's backfill (the history the processor folded inside the load's window). */
+export async function historyOf(opened) {
+    const history = [];
+    const backfill = opened.session.backfill;
+    if (backfill)
+        for await (const event of backfill())
+            history.push(event);
+    return history;
+}
+/** `node dist/cli.js` (the built CLI), for the real SDK adapter (`qoder-acp --qodercli`). */
+export const BUILT_CLI = join(PACKAGE_ROOT, 'dist', 'cli.js');
+export const builtCliExists = () => existsSync(BUILT_CLI);
+/** Runs `node dist/cli.js qoder-acp --prepare-sdk` once (network: the SDK runtime) under `env`. */
+export async function prepareSdkRuntime(env) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [BUILT_CLI, 'qoder-acp', '--prepare-sdk'], { env, stdio: ['ignore', 'inherit', 'inherit'] });
+        child.once('error', reject);
+        child.once('exit', (code) => (code === 0 ? resolve() : reject(new Error(`qoder-acp --prepare-sdk exited ${code}`))));
+    });
+}

package/dist/workstation/acp/test/scriptAgent.js

@@ -0,0 +1,206 @@
+// @ts-nocheck
+// A scripted ACP agent in plain JavaScript over raw ndjson (no SDK), for the Task 21 adoption tests: its turns are driven by
+// marker files, so a test can let a turn run on while the daemon is gone, and prove from files what reached the agent. Run like
+// `fakeAgent.ts`: `node -e "eval(readFileSync(argv[1]))" <this file> <config JSON>` (see `scriptAgentLaunch` in the test helpers).
+//
+// Config (all optional except `dir`):
+//   dir: string                      every marker file lives here
+//   sessionId?: string               session/new's id (default 'S1'); session/load answers {} for any id
+//   chunksBefore?: string[]          agent_message_chunk texts sent when a prompt arrives
+//   permission?: { id }              then: session/request_permission with this JSON-RPC id; waits for its response
+//   cancelPermissionOn?: string      while waiting: once this file exists, send `$/cancel_request{requestId}` (keep waiting)
+//   waitFor?: string                 then: wait for this file
+//   crashOn?: string                 while a prompt runs: once this file exists, the process exits 3 mid-turn (no end_turn)
+//   chunksAfter?: string[]           then: more chunks; then the prompt answers {stopReason:'end_turn'}
+//   commandsAfterOpen?: object[]     an available_commands_update right after session/new or session/load answers
+//   chunksAfterOpen?: string[]       agent_message_chunk texts right after session/new answers (output outside any turn)
+//   mcpHttp?: boolean                initialize advertises mcpCapabilities.http (a delegation MCP lease can be opened on it)
+//   stderrEnv?: string[]             at start: for each env var, its value on stderr (raw, and JSON-escaped) — Task 23's sentinel
+//   stderrMcpHeaders?: boolean       on session/new and session/load: every MCP header value received, on stderr (raw and JSON)
+//   version?: string                 initialize's agentInfo.version (default '1.0.0')                                    (Task 24)
+//   noLoad?: boolean                 initialize does not advertise loadSession
+//   failLoad?: boolean               session/load answers an error
+//   loadWaitFor?: string             session/load waits for this file before it answers
+//   historyOnLoad?: string[]         agent_message_chunk texts replayed (as history) before session/load answers
+//   configOptions?: object[]         session/new and session/load answer these configOptions (load: as configured — the agent keeps
+//                                    no choice); session/set_config_option sets currentValue and answers the new list
+//   envOut?: string[]                at start: these env vars' values into `env.json`
+//   initializeWaitFor?: string       initialize waits for this file before it answers                     (Task 24 fix round 1)
+//   emitOn?: { file, text }          once the session is open: when this file appears, one agent_message_chunk outside any turn
+//   chunkOnTerm?: string             on SIGTERM: one agent_message_chunk (outside any turn), then exit            (fix round 2)
+//   stderrOn?: { file, text }        once the session is open: when this file appears, one stderr line
+//   exitAfterOpenOn?: string         once the session is open (session/new or session/load answered): if this file exists, the
+//                                    process exits 3 shortly after — an adapter that dies on every respawn
+//
+// Files it writes: `stdin.jsonl` (every line received), `prompt-<n>` (prompt n arrived), `turn-<n>-ended` (its end_turn was written),
+// `permission-response.json` (the raw
+// response to its permission request), `cancel-received` (a session/cancel notification), `pid`.
+const { appendFileSync, existsSync, writeFileSync } = require('node:fs');
+const path = require('node:path');
+const config = JSON.parse(process.argv[2] || '{}');
+const at = (name) => path.join(config.dir, name);
+writeFileSync(at('pid'), String(process.pid));
+if (config.envOut)
+    writeFileSync(at('env.json'), JSON.stringify(Object.fromEntries(config.envOut.map((name) => [name, process.env[name] ?? null]))));
+let configOptions = JSON.parse(JSON.stringify(config.configOptions ?? []));
+let openSessionId;
+if (config.chunkOnTerm) {
+    process.on('SIGTERM', () => {
+        if (openSessionId)
+            notify('session/update', { sessionId: openSessionId, update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: config.chunkOnTerm } } });
+        setTimeout(() => process.exit(0), 50);
+    });
+}
+for (const name of config.stderrEnv ?? []) {
+    const value = process.env[name] ?? '';
+    process.stderr.write(`env ${name}=${value}\n`);
+    process.stderr.write(`env-json ${JSON.stringify({ [name]: value })}\n`);
+}
+const send = (message) => process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', ...message })}\n`);
+const notify = (method, params) => send({ method, params });
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const waitForFile = async (name) => { while (!existsSync(at(name)))
+    await sleep(20); };
+const pending = new Map();
+let prompts = 0;
+async function prompt(id, params) {
+    prompts += 1;
+    writeFileSync(at(`prompt-${prompts}`), JSON.stringify(params));
+    const chunk = (text) => notify('session/update', { sessionId: params.sessionId, update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text } } });
+    for (const text of config.chunksBefore ?? []) {
+        chunk(text);
+        await sleep(5);
+    }
+    if (config.crashOn)
+        void waitForFile(config.crashOn).then(() => process.exit(3));
+    if (config.permission) {
+        const answered = new Promise((resolve) => pending.set(config.permission.id, resolve));
+        send({ id: config.permission.id, method: 'session/request_permission', params: {
+                sessionId: params.sessionId,
+                toolCall: { toolCallId: 'tool-1', title: 'Run the thing', kind: 'execute', status: 'pending' },
+                options: [{ optionId: 'allow', name: 'Allow', kind: 'allow_once' }, { optionId: 'deny', name: 'Deny', kind: 'reject_once' }],
+            } });
+        if (config.cancelPermissionOn) {
+            void (async () => {
+                await waitForFile(config.cancelPermissionOn);
+                if (pending.has(config.permission.id))
+                    notify('$/cancel_request', { requestId: config.permission.id });
+            })();
+        }
+        const response = await answered;
+        writeFileSync(at('permission-response.json'), JSON.stringify(response));
+    }
+    if (config.waitFor)
+        await waitForFile(config.waitFor);
+    for (const text of config.chunksAfter ?? []) {
+        chunk(text);
+        await sleep(5);
+    }
+    send({ id, result: { stopReason: 'end_turn' } });
+    writeFileSync(at(`turn-${prompts}-ended`), '');
+}
+function onLine(line) {
+    appendFileSync(at('stdin.jsonl'), `${line}\n`);
+    let message;
+    try {
+        message = JSON.parse(line);
+    }
+    catch {
+        return;
+    }
+    if (message.method === undefined && message.id !== undefined) {
+        const resolve = pending.get(message.id);
+        if (resolve) {
+            pending.delete(message.id);
+            resolve(message);
+        }
+        return;
+    }
+    switch (message.method) {
+        case 'initialize': {
+            const answer = () => send({ id: message.id, result: { protocolVersion: 1, agentCapabilities: { loadSession: !config.noLoad, ...(config.mcpHttp ? { mcpCapabilities: { http: true } } : {}) }, authMethods: [],
+                    agentInfo: { name: 'script-agent', version: config.version ?? '1.0.0' } } });
+            if (config.initializeWaitFor)
+                void waitForFile(config.initializeWaitFor).then(answer);
+            else
+                answer();
+            return;
+        }
+        case 'session/set_config_option': {
+            configOptions = configOptions.map((option) => (option.id === message.params.configId ? { ...option, currentValue: message.params.value } : option));
+            send({ id: message.id, result: { configOptions } });
+            return;
+        }
+        case 'session/load':
+            void (async () => {
+                if (config.loadWaitFor)
+                    await waitForFile(config.loadWaitFor);
+                if (config.failLoad) {
+                    send({ id: message.id, error: { code: -32002, message: 'Resource not found: session' } });
+                    return;
+                }
+                for (const text of config.historyOnLoad ?? []) {
+                    notify('session/update', { sessionId: message.params.sessionId, update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text } } });
+                }
+                openSession(message);
+            })();
+            return;
+        case 'session/new':
+            openSession(message);
+            return;
+        case 'session/prompt':
+            void prompt(message.id, message.params);
+            return;
+        case 'session/cancel':
+            writeFileSync(at('cancel-received'), line);
+            return;
+        default:
+            if (message.id !== undefined)
+                send({ id: message.id, error: { code: -32601, message: 'Method not found' } });
+    }
+}
+function openSession(message) {
+    const sessionId = message.method === 'session/new' ? (config.sessionId ?? 'S1') : message.params.sessionId;
+    if (config.stderrMcpHeaders) {
+        for (const server of message.params.mcpServers ?? []) {
+            for (const header of server.headers ?? []) {
+                process.stderr.write(`mcp header ${header.name}: ${header.value}\n`);
+                process.stderr.write(`mcp header json ${JSON.stringify(header)}\n`);
+            }
+        }
+    }
+    const opened = config.configOptions ? { configOptions: JSON.parse(JSON.stringify(config.configOptions)) } : {};
+    if (config.configOptions)
+        configOptions = JSON.parse(JSON.stringify(config.configOptions));
+    send({ id: message.id, result: message.method === 'session/new' ? { sessionId, ...opened } : opened });
+    if (message.method === 'session/new') {
+        for (const text of config.chunksAfterOpen ?? []) {
+            notify('session/update', { sessionId, update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text } } });
+        }
+    }
+    openSessionId = sessionId;
+    if (config.exitAfterOpenOn && existsSync(at(config.exitAfterOpenOn)))
+        setTimeout(() => process.exit(3), 50);
+    if (config.stderrOn)
+        void waitForFile(config.stderrOn.file).then(() => process.stderr.write(`${config.stderrOn.text}\n`));
+    if (config.emitOn) {
+        void waitForFile(config.emitOn.file).then(() => {
+            notify('session/update', { sessionId, update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: config.emitOn.text } } });
+        });
+    }
+    if (config.commandsAfterOpen) {
+        notify('session/update', { sessionId, update: { sessionUpdate: 'available_commands_update', availableCommands: config.commandsAfterOpen } });
+    }
+}
+let buffer = '';
+process.stdin.on('data', (chunk) => {
+    buffer += chunk.toString('utf8');
+    for (let newline = buffer.indexOf('\n'); newline >= 0; newline = buffer.indexOf('\n')) {
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        if (line.trim())
+            onLine(line);
+    }
+});
+process.stdin.on('end', () => process.exit(0));
+export {};

package/dist/workstation/acp/test/sessionFrames.js

@@ -0,0 +1,42 @@
+export const eventOf = (frame) => ({
+    eventName: frame.eventName,
+    payload: frame.payload,
+    ...(frame.acpSessionId !== undefined ? { acpSessionId: frame.acpSessionId } : {}),
+});
+/** `onEvent` (optional) sees each `agent_event` as it arrives — how a test answers cards the moment they are raised. */
+export function watch(session, onEvent) {
+    const watched = { frames: [], events: [], turns: [],
+        activity: [], diagnostics: [] };
+    const waiters = [];
+    session.onFrames((frames) => {
+        for (const output of frames) {
+            watched.frames.push(output);
+            const frame = output.frame;
+            if (frame.t === 'agent_event') {
+                const event = eventOf(frame);
+                watched.events.push(event);
+                onEvent?.(event);
+            }
+            else if (frame.t === 'agent_session_state')
+                watched.activity.push(frame.raw);
+            else if (frame.t === 'agent_runtime_profile')
+                watched.diagnostics.push(frame.diagnostics);
+            else if (frame.t === 'agent_turn_done') {
+                watched.turns.push(frame);
+                for (const waiter of waiters.filter((w) => w.n <= watched.turns.length)) {
+                    waiters.splice(waiters.indexOf(waiter), 1);
+                    waiter.resolve(watched.turns[waiter.n - 1]);
+                }
+            }
+        }
+    });
+    return {
+        ...watched,
+        turn: (n = 1) => new Promise((resolve) => {
+            if (watched.turns.length >= n)
+                resolve(watched.turns[n - 1]);
+            else
+                waiters.push({ n, resolve });
+        }),
+    };
+}

package/dist/workstation/acp/timedCommand.js

@@ -25,9 +25,11 @@ import { execFile } from 'node:child_process';
  * `binaryInstall.ts`'s zip-extraction fallback — keep working unchanged; it is `undefined` on a
  * timeout, which is never `ENOENT`.
  */
-export function runTimedCommand(command, args, timeoutMs) {
+export function runTimedCommand(command, args, timeoutMs, options = {}) {
     return new Promise((resolve) => {
-        execFile(command, args, { encoding: 'utf8', timeout: timeoutMs, windowsHide: true }, (error, stdout) => {
+        execFile(command, args, {
+            encoding: 'utf8', timeout: timeoutMs, windowsHide: true, maxBuffer: 16 * 1024 * 1024, ...(options.env ? { env: options.env } : {}),
+        }, (error, stdout) => {
             if (!error) {
                 resolve({ ok: true, stdout: stdout.toString() });
                 return;