@zvada/agent-server 0.3.2 → 0.3.3

package/src/core/agents/session-store.ts

@@ -12,12 +12,38 @@ export interface StoredSession {
  */
 export class SessionStore<S extends StoredSession> {
 	private readonly sessions = new Map<string, S>();
+	private readonly pending = new Map<string, Set<S["client"]>>();
+	private closed = false;
+
+	/** Own a client before its initialization RPCs have completed. */
+	trackPending(sessionId: string, client: S["client"]): () => void {
+		if (this.closed) {
+			client.close();
+			throw new Error("session store is closed");
+		}
+		let clients = this.pending.get(sessionId);
+		if (!clients) {
+			clients = new Set();
+			this.pending.set(sessionId, clients);
+		}
+		clients.add(client);
+		return () => {
+			clients.delete(client);
+			if (!clients.size && this.pending.get(sessionId) === clients) {
+				this.pending.delete(sessionId);
+			}
+		};
+	}
 
 	get(sessionId: string): S | undefined {
 		return this.sessions.get(sessionId);
 	}
 
 	set(sessionId: string, session: S): void {
+		if (this.closed || session.client.closed) {
+			session.client.close();
+			throw new Error("cannot register a closed session");
+		}
 		this.sessions.set(sessionId, session);
 	}
 
@@ -36,20 +62,21 @@ export class SessionStore<S extends StoredSession> {
 
 	/** Tear down one session: cancel its idle timer, unmap it, close its client. */
 	close(sessionId: string): void {
+		const pending = this.pending.get(sessionId);
+		this.pending.delete(sessionId);
 		const session = this.sessions.get(sessionId);
-		if (!session) return;
-		this.clearIdle(session);
 		this.sessions.delete(sessionId);
-		session.client.close();
+		if (session) this.clearIdle(session);
+		for (const client of pending ?? []) client.close();
+		session?.client.close();
 	}
 
-	/** Tear down every session (process shutdown). */
+	/** Tear down ready and initializing clients; refuse subsequent registrations. */
 	closeAll(): void {
-		for (const session of this.sessions.values()) {
-			this.clearIdle(session);
-			session.client.close();
+		this.closed = true;
+		for (const id of new Set([...this.sessions.keys(), ...this.pending.keys()])) {
+			this.close(id);
 		}
-		this.sessions.clear();
 	}
 
 	/** Shut the session down after `idleMs` unless another turn claims it first. */

package/src/core/index.ts

@@ -75,6 +75,9 @@ export { CodexSdkTransformer, createCodexSdkTransformer } from "./agents/codex-s
 export {
 	CodexAppServerAgent,
 	type CodexAppServerAgentOptions,
+	type CodexAppServerAuth,
+	type CodexChatGptAuth,
+	type CodexChatGptAuthTokens,
 } from "./agents/codex-app-server/codex-app-server-agent.ts";
 export {
 	CodexAppServerTransformer,

package/src/core/presets.ts

@@ -4,7 +4,10 @@ import { createAcpTransformer } from "./agents/acp/adapter.ts";
 import { createClaudeCodeTransformer } from "./agents/claude-code/adapter.ts";
 import { ClaudeCodeAgent, type ClaudeCodeAgentOptions } from "./agents/claude-code/claude-agent.ts";
 import { createCodexAppServerTransformer } from "./agents/codex-app-server/adapter.ts";
-import { CodexAppServerAgent } from "./agents/codex-app-server/codex-app-server-agent.ts";
+import {
+	CodexAppServerAgent,
+	type CodexAppServerAgentOptions,
+} from "./agents/codex-app-server/codex-app-server-agent.ts";
 import { createCodexSdkTransformer } from "./agents/codex-sdk/adapter.ts";
 import { CodexSdkAgent } from "./agents/codex-sdk/codex-sdk-agent.ts";
 import { AgentRegistry } from "./agents/registry.ts";
@@ -33,6 +36,8 @@ export interface CreateRegistryOptions {
 	 * `resolveCliPath` stays provisioner-wired here.
 	 */
 	claudeCode?: Omit<ClaudeCodeAgentOptions, "resolveCliPath">;
+	/** Codex embed-tier authentication and process options; CLI resolution stays provisioner-owned. */
+	codexAppServer?: Omit<CodexAppServerAgentOptions, "resolveCliPath">;
 	/**
 	 * Operational diagnostics port (see `EngineDiagnostic`): interrupt
 	 * timeouts, resume fallbacks, sink failures — signals the engine must not
@@ -72,7 +77,7 @@ export function createAgentRegistry(opts: CreateRegistryOptions = {}): AgentRegi
 	}
 	if (enabled.has("codex-app-server")) {
 		registry.register(
-			new CodexAppServerAgent({ resolveCliPath: codexCli }),
+			new CodexAppServerAgent({ ...opts.codexAppServer, resolveCliPath: codexCli }),
 			createCodexAppServerTransformer,
 		);
 	}

package/src/core/provision/provisioner.ts

@@ -1,5 +1,6 @@
 import { randomBytes } from "node:crypto";
 import {
+	type Stats,
 	chmodSync,
 	existsSync,
 	lstatSync,
@@ -10,7 +11,7 @@ import {
 } from "node:fs";
 import { chmod, mkdir, readdir, rename, rm } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 import { CliNotFoundError, CliProvisionError } from "../utils/errors.ts";
 import { extractTarGz } from "./extract.ts";
 import { DEFAULT_NPM_REGISTRY, downloadWithIntegrity, fetchDist } from "./npm.ts";
@@ -147,7 +148,7 @@ function moduleDir(): string {
  */
 export class CliProvisioner {
 	private readonly mode: ProvisionMode;
-	private readonly cacheDir: string;
+	private cacheDir: string;
 	private readonly registry: string;
 	/** Explicit pins only — see `versionFor` for the per-tool default chain. */
 	private readonly pins: Partial<Record<CliTool, string>>;
@@ -159,15 +160,15 @@ export class CliProvisioner {
 	private readonly extract: (tgzPath: string, destDir: string) => Promise<void>;
 	private readonly hostResolve: (tool: CliTool) => ResolvedCli | undefined;
 	private readonly memo = new Map<CliTool, Promise<ResolvedCli | undefined>>();
-	private cacheRootTrusted = false;
 
 	constructor(options: ProvisionOptions = {}, deps: ProvisionerDeps = {}) {
 		this.env = deps.env ?? process.env;
 		this.mode = options.mode ?? this.modeFromEnv();
-		this.cacheDir =
+		this.cacheDir = resolve(
 			options.cacheDir ??
-			this.env.AGENT_SERVER_CACHE_DIR ??
-			join(this.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "agent-server", "cli");
+				this.env.AGENT_SERVER_CACHE_DIR ??
+				join(this.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "agent-server", "cli"),
+		);
 		this.registry = options.registry ?? this.env.AGENT_SERVER_NPM_REGISTRY ?? DEFAULT_NPM_REGISTRY;
 		this.pins = options.pins ?? {};
 		this.overrides = options.overrides ?? {};
@@ -184,17 +185,30 @@ export class CliProvisioner {
 	 * finds its sibling platform package and has the clearest failure message.
 	 */
 	resolve(tool: CliTool): Promise<ResolvedCli | undefined> {
-		const memoized = this.memo.get(tool);
-		if (memoized) return memoized;
-		const pending = this.doResolve(tool).then((resolved) => {
-			if (resolved) {
-				this.log(`${tool} CLI: ${resolved.path} (${resolved.source}${withVersion(resolved)})`);
-			}
-			return resolved;
-		});
-		this.memo.set(tool, pending);
-		pending.catch(() => this.memo.delete(tool));
-		return pending;
+		let pending = this.memo.get(tool);
+		if (!pending) {
+			pending = this.doResolve(tool).then((resolved) => {
+				if (resolved)
+					this.log(`${tool} CLI: ${resolved.path} (${resolved.source}${withVersion(resolved)})`);
+				return resolved;
+			});
+			this.memo.set(tool, pending);
+		}
+		return pending
+			.then((resolved) => {
+				if (resolved?.source === "cache" || resolved?.source === "downloaded") {
+					const root = this.ensureTrustedCacheRoot();
+					if (!managedDirectory(root, dirname(resolved.path), false)) {
+						throw new CliProvisionError(`Cached CLI disappeared: ${resolved.path}`);
+					}
+					trustedBinary(resolved.path, lstatSync(resolved.path));
+				}
+				return resolved;
+			})
+			.catch((error) => {
+				if (this.memo.get(tool) === pending) this.memo.delete(tool);
+				throw error;
+			});
 	}
 
 	/** Warm the managed cache with the pinned build (the `install` command). */
@@ -355,48 +369,30 @@ export class CliProvisioner {
 	 * (lstat): a symlink here could redirect the spawn — and the post-install
 	 * `chmod` — at a path outside the tree we verified.
 	 */
-	private binaryIn(tool: CliTool, dir: string): string | undefined {
+	private binaryIn(tool: CliTool, dir: string, managedRoot?: string): string | undefined {
 		const candidates =
 			tool === "claude"
 				? ["claude", "claude.exe"]
 				: [join("bin", "codex"), join("bin", "codex.exe")];
 		for (const candidate of candidates) {
 			const path = join(dir, candidate);
+			if (managedRoot && !managedDirectory(managedRoot, dirname(path), false)) continue;
+			let stat: Stats;
 			try {
-				if (lstatSync(path).isFile()) return path;
+				stat = lstatSync(path);
 			} catch {
-				// not here — try the next candidate
+				continue;
 			}
+			if (managedRoot) trustedBinary(path, stat);
+			if (stat.isFile()) return path;
 		}
 		return undefined;
 	}
 
-	/**
-	 * Trust gate on the cache root, mirroring the Claude SDK's own temp-dir
-	 * defense: install paths are predictable (public versions + platform), so
-	 * under a shared/pre-created directory another local user could plant the
-	 * binary we spawn. Create `0o700`, require our own uid, and tighten a
-	 * looser mode (earlier runs created it with the umask). POSIX-only — on
-	 * Windows the default cache locations are already per-user.
-	 */
-	private ensureTrustedCacheRoot(): void {
-		if (this.cacheRootTrusted) return;
-		mkdirSync(this.cacheDir, { recursive: true, mode: 0o700 });
-		if (typeof process.getuid === "function") {
-			const stat = lstatSync(this.cacheDir);
-			if (!stat.isDirectory()) {
-				throw new CliProvisionError(
-					`Cache dir ${this.cacheDir} is not a directory (planted symlink?) — refusing to use it`,
-				);
-			}
-			if (stat.uid !== process.getuid()) {
-				throw new CliProvisionError(
-					`Cache dir ${this.cacheDir} is owned by uid ${stat.uid}, expected ${process.getuid()} — refusing to use it`,
-				);
-			}
-			if ((stat.mode & 0o777) !== 0o700) chmodSync(this.cacheDir, 0o700);
-		}
-		this.cacheRootTrusted = true;
+	/** Pin trusted aliases to their physical location and recheck on every use. */
+	private ensureTrustedCacheRoot(): string {
+		this.cacheDir = trustedCacheDirectory(this.cacheDir, true);
+		return this.cacheDir;
 	}
 
 	/** The directory inside an extracted tarball that becomes the install. */
@@ -418,38 +414,40 @@ export class CliProvisioner {
 	}
 
 	private async ensureInstalled(tool: CliTool): Promise<ResolvedCli> {
-		this.ensureTrustedCacheRoot();
+		const root = this.ensureTrustedCacheRoot();
 		const pkg = this.packageFor(tool);
-		const dir = join(this.cacheDir, tool, `${pkg.version}-${pkg.suffix}`);
-		const cached = this.binaryIn(tool, dir);
+		const dir = join(root, tool, `${pkg.version}-${pkg.suffix}`);
+		const cached = this.binaryIn(tool, dir, root);
 		if (cached) return { path: cached, source: "cache", version: pkg.version };
 
 		this.log(`downloading ${tool} ${pkg.version} (${pkg.suffix}) from ${this.registry}…`);
 		const startedAt = Date.now();
 		const staging = join(
-			this.cacheDir,
+			root,
 			".tmp",
 			`${tool}-${pkg.version}-${process.pid}-${randomBytes(4).toString("hex")}`,
 		);
-		await mkdir(staging, { recursive: true });
+		managedDirectory(root, dirname(staging), true);
+		await mkdir(staging, { mode: 0o700 });
 		try {
 			const dist = await fetchDist(this.registry, pkg.name, pkg.registryVersion, this.fetch);
 			const tgz = join(staging, "package.tgz");
 			const bytes = await downloadWithIntegrity(dist.tarball, tgz, dist.integrity, this.fetch);
 			const extracted = join(staging, "x");
-			await mkdir(extracted);
+			await mkdir(extracted, { mode: 0o700 });
 			await this.extract(tgz, extracted);
 			const payload = await this.payloadDir(tool, extracted);
 
-			await mkdir(dirname(dir), { recursive: true });
+			this.ensureTrustedCacheRoot();
+			managedDirectory(root, dirname(dir), true);
 			try {
 				await rename(payload, dir);
 			} catch (error) {
 				// Lost an install race with another process. The directory is
 				// version-keyed, so the winner's tree is what we would have written.
-				if (!this.binaryIn(tool, dir)) throw error;
+				if (!this.binaryIn(tool, dir, root)) throw error;
 			}
-			const path = this.binaryIn(tool, dir);
+			const path = this.binaryIn(tool, dir, root);
 			if (!path) {
 				throw new CliProvisionError(`downloaded ${pkg.name}@${pkg.registryVersion} has no binary`);
 			}
@@ -476,3 +474,90 @@ export class CliProvisioner {
 function withVersion(resolved: ResolvedCli): string {
 	return resolved.version ? ` ${resolved.version}` : "";
 }
+
+function refuseCache(path: string, reason: string): never {
+	throw new CliProvisionError(`Untrusted CLI cache path ${path}: ${reason} — refusing to use it`);
+}
+
+function trustedOwner(path: string, stat: Stats, ownOnly = false): void {
+	if (typeof process.getuid !== "function") return;
+	const uid = process.getuid();
+	if (stat.uid !== uid && (ownOnly || stat.uid !== 0))
+		refuseCache(path, `owned by uid ${stat.uid}, expected ${uid}${ownOnly ? "" : " or root"}`);
+}
+
+function privateDirectory(path: string, stat: Stats, allowSticky = false): void {
+	if (!stat.isDirectory()) refuseCache(path, "not a directory (planted symlink?)");
+	trustedOwner(path, stat);
+	if (
+		typeof process.getuid === "function" &&
+		stat.mode & 0o022 &&
+		!(allowSticky && stat.mode & 0o1000)
+	) {
+		refuseCache(path, "writable by other users");
+	}
+}
+
+function createDirectory(path: string): void {
+	try {
+		mkdirSync(path, { mode: 0o700 });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+	}
+}
+
+/** Check each parent before creating its child; trusted sticky parents permit /tmp. */
+function trustedCacheDirectory(path: string, ownLeaf: boolean): string {
+	const root = parse(path).root;
+	let current = root;
+	privateDirectory(root, lstatSync(root), true);
+	const components = relative(root, path).split(sep).filter(Boolean);
+	if (ownLeaf && !components.length) refuseCache(path, "filesystem root cannot be a CLI cache");
+	for (const [index, component] of components.entries()) {
+		const candidate = join(current, component);
+		createDirectory(candidate);
+		const stat = lstatSync(candidate);
+		const leaf = ownLeaf && index === components.length - 1;
+		if (stat.isSymbolicLink() && !leaf) {
+			trustedOwner(candidate, stat);
+			current = trustedCacheDirectory(realpathSync(candidate), false);
+			continue;
+		}
+		if (leaf) {
+			if (!stat.isDirectory()) refuseCache(candidate, "not a directory (planted symlink?)");
+			trustedOwner(candidate, stat, true);
+			if (typeof process.getuid === "function" && (stat.mode & 0o777) !== 0o700)
+				chmodSync(candidate, 0o700);
+		} else privateDirectory(candidate, stat, true);
+		current = candidate;
+	}
+	return current;
+}
+
+/** Managed descendants cannot be aliases or outsider-writable, even under a repaired root. */
+function managedDirectory(root: string, path: string, create: boolean): boolean {
+	const rel = relative(root, path);
+	if (isAbsolute(rel) || rel.split(sep).includes(".."))
+		refuseCache(path, "outside the managed root");
+	let current = root;
+	for (const component of rel.split(sep).filter(Boolean)) {
+		current = join(current, component);
+		if (create) createDirectory(current);
+		let stat: Stats;
+		try {
+			stat = lstatSync(current);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+			throw error;
+		}
+		privateDirectory(current, stat);
+	}
+	return true;
+}
+
+function trustedBinary(path: string, stat: Stats): void {
+	if (!stat.isFile()) refuseCache(path, "not a regular executable file");
+	trustedOwner(path, stat);
+	if (typeof process.getuid === "function" && stat.mode & 0o022)
+		refuseCache(path, "executable writable by other users");
+}

package/src/core/runtime/event-processor.ts

@@ -155,7 +155,12 @@ export class EventProcessor {
 			// A parented message is a sub-agent's output — nests under its tool call,
 			// not a top-level model message (see DESIGN.md D5).
 			...(parentToolCallId && { parentToolCallId }),
-			...(this.meta.model && { model: this.meta.model }),
+			// `model` is assistant/model-message metadata (the turn's configured
+			// model from `RunConfig.model`) — never on the user echo, which is
+			// user-authored. Gating here keeps it off every user message; every
+			// assistant message (top-level AND parented sub-agent output) keeps it,
+			// since `config.model` is the only per-turn model signal available.
+			...(role === "assistant" && this.meta.model && { model: this.meta.model }),
 			timestamp: Date.now(),
 		};
 	}

package/src/protocol/reduce.ts

@@ -331,7 +331,11 @@ function openMessage(
 		outputIndex: init.outputIndex,
 		role: init.role,
 		...(init.parentToolCallId !== undefined && { parentToolCallId: init.parentToolCallId }),
-		...(init.model !== undefined && { model: init.model }),
+		// `model` is assistant/model-message metadata; the user echo is
+		// user-authored, so never persist it on a user-role message. Defense in
+		// depth alongside the producer gate: a hand-built or replayed
+		// `message.started{role:"user", model}` does not leak into the fold.
+		...(init.role === "assistant" && init.model !== undefined && { model: init.model }),
 		parts: [],
 		startedAt: init.timestamp,
 	};

package/src/protocol/verify.ts

@@ -59,10 +59,21 @@ export function verifyStreamContract(
 	// Via the Law-6 decoder, not the closed union: an unknown event type (or an
 	// unknown part inside a known event) is forward-compat, not a violation —
 	// only a KNOWN type with a malformed body is.
+	//
+	// Indices that fail to decode are recorded and skipped by the later passes
+	// that re-touch raw event bodies (the bookkeeping loop and the projection-
+	// prep loop below): a malformed event's nested fields (message.part's
+	// `event.part.id`, `event.part.messageId`, `"raw" in part`) cannot be safely
+	// dereferenced a second time, so without the skip the bookkeeping forEach
+	// would throw a TypeError and discard the `violations` array — including the
+	// schema-valid report just pushed for it. The schema-valid report is
+	// authoritative for the index; the raw-body passes leave the index alone.
+	const schemaBad = new Set<number>();
 	events.forEach((event, i) => {
 		try {
 			decodeLifecycleEvent(event);
 		} catch (err) {
+			schemaBad.add(i);
 			report(
 				"schema-valid",
 				i,
@@ -113,6 +124,13 @@ export function verifyStreamContract(
 		// Unknown types carry no contract obligations we can check — they are
 		// preserved, not interpreted.
 		if (isUnknownEvent(event)) return;
+		// The validity loop already reported this index as schema-invalid. The
+		// bookkeeping below dereferences a malformed event's nested body —
+		// `message.part` reads `event.part.id`/`event.part.messageId` and runs
+		// `"raw" in part` — which a malformed `part` (null/undefined/non-object)
+		// cannot safely provide, so the index is left to the schema-valid report
+		// instead of crashing this forEach out from under the violations array.
+		if (schemaBad.has(i)) return;
 		switch (event.type) {
 			case "session.created":
 				sessionCreatedInTurn++;
@@ -168,6 +186,18 @@ export function verifyStreamContract(
 				turn.lastOutputIndex = Math.max(turn.lastOutputIndex, event.outputIndex);
 				turn.openMessages.set(event.messageId, i);
 				messageRole.set(event.messageId, event.role);
+				// `model` is assistant/model-message metadata; the user echo (and any
+				// user-role message) is user-authored, so a `model` field on it
+				// misattributes the configured model to the user's prompt. This catches
+				// leaks the producer gate prevents but a hand-built or replayed stream
+				// could still carry.
+				if (event.model !== undefined && event.role !== "assistant") {
+					report(
+						"model-assistant-only",
+						i,
+						`message.started ${event.messageId} carries model ${JSON.stringify(event.model)} on a ${event.role} message; model is assistant-only metadata`,
+					);
+				}
 				return;
 			}
 			case "message.part": {
@@ -306,6 +336,12 @@ export function verifyStreamContract(
 	const lastTextDelta = new Map<string, number>();
 	events.forEach((event, i) => {
 		if (isUnknownEvent(event)) return;
+		// Reported above as schema-invalid; this pass dereferences the nested
+		// `event.part.id` and `event.delta.type`, which a malformed body cannot
+		// safely provide. At HEAD the bookkeeping loop throws first, so this
+		// deref is not separately reachable — once that loop is guarded, this
+		// one becomes the next reachable crash, so both passes check the set.
+		if (schemaBad.has(i)) return;
 		if (event.type === "message.part") lastSnapshot.set(event.part.id, { event, index: i });
 		else if (event.type === "message.part.delta" && event.delta.type !== "tool_input") {
 			lastTextDelta.set(event.partId, i);

package/src/protocol/wire.ts

@@ -267,7 +267,8 @@ export type WireMessage =
 	| { kind: "notification"; method: string; params?: unknown }
 	/** `id` is null on protocol-level errors answering unparseable requests. */
 	| { kind: "response"; id: JsonRpcId | null; result?: unknown; error?: JsonRpcError }
-	| { kind: "invalid"; error: string };
+	/** The decoder sets parseError; optional for existing callers constructing invalid messages. */
+	| { kind: "invalid"; error: string; parseError?: boolean };
 
 /** Decode one NDJSON line into a JSON-RPC message (never throws). */
 export function decodeWireMessage(line: string): WireMessage {
@@ -275,13 +276,14 @@ export function decodeWireMessage(line: string): WireMessage {
 	try {
 		raw = JSON.parse(line);
 	} catch {
-		return { kind: "invalid", error: "not valid JSON" };
+		return { kind: "invalid", error: "not valid JSON", parseError: true };
 	}
 	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-		return { kind: "invalid", error: "not a JSON-RPC object" };
+		return { kind: "invalid", error: "not a JSON-RPC object", parseError: false };
 	}
 	const msg = raw as Record<string, unknown>;
-	if (msg.jsonrpc !== "2.0") return { kind: "invalid", error: "missing jsonrpc: '2.0'" };
+	if (msg.jsonrpc !== "2.0")
+		return { kind: "invalid", error: "missing jsonrpc: '2.0'", parseError: false };
 	const id = JsonRpcIdSchema.safeParse(msg.id);
 	if (typeof msg.method === "string") {
 		return id.success
@@ -297,7 +299,11 @@ export function decodeWireMessage(line: string): WireMessage {
 			error: error.success ? error.data : undefined,
 		};
 	}
-	return { kind: "invalid", error: "neither request, notification, nor response" };
+	return {
+		kind: "invalid",
+		error: "neither request, notification, nor response",
+		parseError: false,
+	};
 }
 
 export function encodeRequest(id: JsonRpcId, method: string, params?: unknown): string {

package/src/server/acp/translate.ts

@@ -115,20 +115,31 @@ export class AcpUpdateTranslator {
 		const kind = part.kind
 			? ((acpKinds.has(part.kind) ? part.kind : "other") as "other")
 			: undefined;
+		const updates: SessionUpdate[] = [];
 		if (!this.openedTools.has(part.toolCallId)) {
 			this.openedTools.add(part.toolCallId);
-			return [
-				{
-					sessionUpdate: "tool_call",
-					toolCallId: part.toolCallId,
-					title: part.title ?? part.toolName,
-					name: part.toolName,
-					...(kind && { kind }),
-					status,
-					...(part.locations?.length && { locations: part.locations }),
-					...("input" in part.state && { rawInput: part.state.input }),
-				},
-			];
+			// A terminal-first snapshot — a tool already `completed`/`failed` on
+			// its first (and maybe only) `message.part` (e.g. a conforming ACP
+			// agent that reports a tool solely via a bare terminal
+			// `tool_call_update`, which the `acp` harness preserves as a single
+			// terminal part) — must still deliver its result body. Emit the
+			// spec-canonical pair: announce with a NON-terminal `in_progress`
+			// status, then a `tool_call_update` carrying the real terminal
+			// status and the output/error `content` (the only update a result
+			// can ride on). `cancelled` has no body to drop and stays on the
+			// single-event announce path with its mapped `failed` status.
+			const terminalFirst = part.state.status === "completed" || part.state.status === "failed";
+			updates.push({
+				sessionUpdate: "tool_call",
+				toolCallId: part.toolCallId,
+				title: part.title ?? part.toolName,
+				name: part.toolName,
+				...(kind && { kind }),
+				status: terminalFirst ? "in_progress" : status,
+				...(part.locations?.length && { locations: part.locations }),
+				...("input" in part.state && { rawInput: part.state.input }),
+			});
+			if (!terminalFirst) return updates;
 		}
 		const output =
 			part.state.status === "failed"
@@ -136,16 +147,15 @@ export class AcpUpdateTranslator {
 				: part.state.status === "completed"
 					? part.state.output
 					: undefined;
-		return [
-			{
-				sessionUpdate: "tool_call_update",
-				toolCallId: part.toolCallId,
-				status,
-				...(output && {
-					content: [{ type: "content", content: { type: "text", text: output } }],
-				}),
-			},
-		];
+		updates.push({
+			sessionUpdate: "tool_call_update",
+			toolCallId: part.toolCallId,
+			status,
+			...(output && {
+				content: [{ type: "content", content: { type: "text", text: output } }],
+			}),
+		});
+		return updates;
 	}
 }
 

package/src/server/agent-server.ts

@@ -111,16 +111,31 @@ export class AgentServer {
 		if (this.shuttingDown) return;
 		this.shuttingDown = true;
 		// Drain first so cancelled turns still broadcast their turn.ended.
-		await this.runtime.shutdown();
-		for (const transport of [...this.transports]) transport.close();
-		this.options.onShutdown?.();
+		// The drain (and each transport's close) is a library extension point
+		// that may throw; the finally still closes every transport and runs the
+		// host hook even then — every other external call in this file is
+		// defended the same way (broadcast/observers/sink/handleLine).
+		try {
+			await this.runtime.shutdown();
+		} finally {
+			for (const transport of [...this.transports]) {
+				try {
+					transport.close();
+				} catch {
+					// One faulty transport's close must not skip the others or the
+					// host's shutdown hook — same isolation broadcast uses for send.
+				}
+			}
+			this.options.onShutdown?.();
+		}
 	}
 
 	private async handleLine(transport: WireTransport, line: string): Promise<void> {
 		if (!line.trim()) return;
 		const msg = decodeWireMessage(line);
 		if (msg.kind === "invalid") {
-			transport.send(encodeErrorResponse(null, WIRE_ERROR_CODES.parseError, msg.error));
+			const code = msg.parseError ? WIRE_ERROR_CODES.parseError : WIRE_ERROR_CODES.invalidRequest;
+			transport.send(encodeErrorResponse(null, code, msg.error));
 			return;
 		}
 		// Clients only send requests on this wire; stray notifications/responses
@@ -375,7 +390,10 @@ export class AgentServer {
 
 			case WIRE_METHODS.shutdown: {
 				transport.send(encodeResponse(id, {}));
-				await this.shutdown();
+				// The success ack is already committed on the wire; a throw out of
+				// shutdown() must not reach handleLine's catch and emit a second
+				// response for this id (a JSON-RPC 2.0 violation).
+				await this.shutdown().catch(() => {});
 				return;
 			}