@akanjs/devkit 3.0.0-beta.17 → 3.0.0-beta.19

package/cloud/constants.ts

@@ -24,13 +24,36 @@ export interface RemoteEnvServerConfig {
   username?: string;
   port?: number;
 }
+export type PlatformGatePolicy = "gate" | "warn";
+export interface LinuxTestTargetConfig {
+  cpus?: number;
+  memory?: string;
+  policy?: PlatformGatePolicy;
+}
+export interface WindowsTestTargetConfig {
+  host: string;
+  user: string;
+  identityFile: string;
+  knownHostsFile?: string;
+  utmVm?: string;
+  workRoot?: string;
+  tolerateScriptFailures?: string[];
+  policy?: PlatformGatePolicy;
+  greenStreak?: number;
+}
+export interface TestTargetsConfig {
+  linux?: LinuxTestTargetConfig;
+  windows?: WindowsTestTargetConfig;
+}
 export interface AkanGlobalConfig {
   cloudHost: { [key: string]: HostConfigDto };
   remoteEnvServers: Record<string, RemoteEnvServerConfig>;
+  testTargets: TestTargetsConfig;
 }
 export const defaultAkanGlobalConfig: AkanGlobalConfig = {
   cloudHost: {},
   remoteEnvServers: {},
+  testTargets: {},
 };
 
 export interface AccessTokenDto {

package/cloud/globalConfig.ts

@@ -12,6 +12,7 @@ import {
   type HostConfig,
   type HostConfigDto,
   type RemoteEnvServerConfig,
+  type TestTargetsConfig,
 } from "./constants";
 
 export class GlobalConfig {
@@ -27,6 +28,7 @@ export class GlobalConfig {
       ...akanConfig,
       cloudHost: akanConfig.cloudHost ?? defaultAkanGlobalConfig.cloudHost,
       remoteEnvServers: akanConfig.remoteEnvServers ?? defaultAkanGlobalConfig.remoteEnvServers,
+      testTargets: akanConfig.testTargets ?? defaultAkanGlobalConfig.testTargets,
     };
   }
   /**
@@ -71,6 +73,17 @@ export class GlobalConfig {
       remoteEnvServers,
     });
   }
+  static async getTestTargets(): Promise<TestTargetsConfig> {
+    const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
+    return akanConfig.testTargets;
+  }
+  static async setTestTargets(testTargets: TestTargetsConfig) {
+    const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
+    await GlobalConfig.#setAkanGlobalConfig({
+      ...akanConfig,
+      testTargets: { ...akanConfig.testTargets, ...testTargets },
+    });
+  }
   static needRefreshToken(accessToken: AccessToken): boolean {
     return !!accessToken?.expiresAt?.isBefore(dayjs().add(1, "hour"));
   }

package/codeAgent/agent/AkanCodeServices.ts

@@ -1,10 +1,13 @@
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import { type InlineExtension, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { CodeAgentProfile } from "akanjs/common";
 import { AkanEnvKeys } from "../tools/AkanEnvKeys";
 import { type AkanContextFile, AkanContextFiles } from "./AkanContextFiles";
 import { akanCodePaths } from "./akanCodePaths";
 import { akanSystemPrompt } from "./akanSystemPrompt";
+import type { CodeAgentProxy } from "./CodeAgentProxy";
 import { CodeSessionIndex } from "./CodeSessionIndex";
 
 export interface AkanCodeServicesOptions {
@@ -32,6 +35,10 @@ export class AkanCodeServices {
       enableInstallTelemetry: false,
       enableAnalytics: false,
       quietStartup: true,
+      // Twice the engine's 16,384. The reserve is all the room the response at the threshold gets — a request
+      // clamps its output to the window less the prompt less 4,096 — and 80% of it caps the summary. At 16k a
+      // reasoning model stops mid-thought there, and the recovery re-sends a near-full window to retry the turn.
+      compaction: { reserveTokens: 32_768 },
     });
   }
 
@@ -42,8 +49,18 @@ export class AkanCodeServices {
    * locks and rewrites that file itself, so a second `akan code` refreshing an OAuth token at the same moment
    * cannot clobber the first. Nothing lands in `~/.pi/`, and a user who removes akan takes their keys with them.
    */
-  static async runtime(workspaceRoot: string) {
+  static async runtime(workspaceRoot: string, proxy: CodeAgentProxy | null = null) {
     mkdirSync(akanCodePaths.globalDir(), { recursive: true, mode: 0o700 });
+    if (proxy) {
+      //* Behind a proxy neither `auth.json` nor an env key may reach a request, so credentials live in a throwaway
+      //* file and the only key the engine ever sends is the proxy token.
+      const runtime = await ModelRuntime.create({
+        authPath: path.join(mkdtempSync(path.join(tmpdir(), "akan-code-proxy-")), "auth.json"),
+        modelsPath: akanCodePaths.modelsFile(),
+      });
+      await proxy.apply(runtime);
+      return runtime;
+    }
     const runtime = await ModelRuntime.create({
       authPath: akanCodePaths.authFile(),
       modelsPath: akanCodePaths.modelsFile(),
@@ -53,7 +70,9 @@ export class AkanCodeServices {
   }
 
   static sessions(workspaceRoot: string, cwd: string, profile: CodeAgentProfile, resume?: string) {
-    if (profile.session.store !== "file") return SessionManager.inMemory(cwd);
+    //* `remote` has no store of its own yet, so it keeps a file session rather than none: a pod's worker is long-lived
+    //* and its suspended asks and resume need the file more than a laptop does.
+    if (profile.session.store === "memory") return SessionManager.inMemory(cwd);
     const dir = akanCodePaths.sessionsDir(workspaceRoot);
     mkdirSync(dir, { recursive: true });
     const manager = SessionManager.create(cwd, dir);
@@ -66,22 +85,29 @@ export class AkanCodeServices {
   }
 
   /**
-   * The akan skill set, then the workspace's own.
+   * The akan skill set, then the person's own, then the workspace's.
    *
-   * A path that does not exist is a reported load error rather than a skip, so both are checked first.
+   * `~/.akan/code/skills` is read because a skill somebody wrote for themselves is theirs, not one checkout's,
+   * and having to copy it into every repo is the same friction that makes people stop writing them. It is
+   * text the model may read, never code that runs — which is why extensions stay workspace-only below.
+   *
+   * A path that does not exist is a reported load error rather than a skip, so each is checked first.
    */
   static #skillPaths(profile: CodeAgentProfile, workspaceRoot: string) {
     if (!profile.context.skills) return [];
-    const workspace = akanCodePaths.skillsDir(workspaceRoot);
-    return [akanCodePaths.builtinSkillsDir(), existsSync(workspace) ? workspace : undefined].filter(
-      (dir): dir is string => !!dir,
-    );
+    const dirs = [
+      akanCodePaths.builtinSkillsDir(),
+      akanCodePaths.globalSkillsDir(),
+      akanCodePaths.skillsDir(workspaceRoot),
+    ];
+    return dirs.filter((dir): dir is string => !!dir && existsSync(dir));
   }
 
   /**
-   * What the engine's resource loader may discover. Extensions and skills come from the workspace, never from
-   * the home directory: a coding agent that picks up a globally installed extension behaves differently in two
-   * checkouts of the same repo for reasons nothing in the repo explains.
+   * What the engine's resource loader may discover. Extensions come from the workspace and nowhere else: a
+   * globally installed extension is code that runs in every checkout, so an agent would behave differently in
+   * two clones of the same repo for reasons nothing in the repo explains. Skills are text and are read from
+   * the home directory too — see `#skillPaths`.
    */
   static resourceOptions(options: AkanCodeServicesOptions) {
     // A path that does not exist is reported as a load error rather than skipped, and these two are optional.

package/codeAgent/agent/CodeAgent.ts

@@ -1,7 +1,6 @@
 import {
   type AgentSession,
   createAgentSession,
-  DEFAULT_COMPACTION_SETTINGS,
   DefaultResourceLoader,
   type ExtensionAPI,
   type InlineExtension,
@@ -15,6 +14,7 @@ import {
   type CodeAgentImage,
   type CodeAgentMcpStatus,
   type CodeAgentProfile,
+  type CodeAgentProviderInfo,
   type CodeAgentQuestion,
   type CodeAgentSessionInfo,
   type CodeAgentState,
@@ -36,6 +36,8 @@ import { akanCodePaths } from "./akanCodePaths";
 import { CodeAgentAsks } from "./CodeAgentAsks";
 import { CodeAgentEventMapper } from "./CodeAgentEventMapper";
 import { CodeAgentGate } from "./CodeAgentGate";
+import { CodeAgentProxy } from "./CodeAgentProxy";
+import { CodeAgentSuspended } from "./CodeAgentSuspended";
 import { CodeAgentUi } from "./CodeAgentUi";
 import { CodeMailbox } from "./CodeMailbox";
 import { CodeSessionFork } from "./CodeSessionFork";
@@ -76,6 +78,7 @@ export class CodeAgent {
   readonly #gate: CodeAgentGate;
   readonly #mapper = new CodeAgentEventMapper();
   readonly #asks = new CodeAgentAsks();
+  #suspended = new CodeAgentSuspended(null);
   readonly #listeners = new Set<(event: CodeAgentEvent) => void>();
   #session: AgentSession | undefined;
   #disposePlugins: (() => void) | undefined;
@@ -105,9 +108,9 @@ export class CodeAgent {
     const cwd = options.cwd ?? workspaceRoot;
     const agent = new CodeAgent(options.profile);
     const settingsManager = AkanCodeServices.settings();
-    const modelRuntime = await AkanCodeServices.runtime(workspaceRoot);
+    const modelRuntime = await AkanCodeServices.runtime(workspaceRoot, CodeAgentProxy.fromEnv(options.profile));
     const model = await akanCodeModel(modelRuntime, options.model);
-    const compaction = DEFAULT_COMPACTION_SETTINGS;
+    const compaction = settingsManager.getCompactionSettings(model);
     const modelWarnings = akanCodeModelWarnings(model, compaction.reserveTokens + compaction.keepRecentTokens);
 
     const akan = await AkanCodePlugins.build({
@@ -121,6 +124,7 @@ export class CodeAgent {
       mailbox: () => agent.#mailbox,
       onNotice: (message) => agent.#emit({ type: "notice", level: "warning", message }),
       onAgents: (agents) => agent.#emit({ type: "subagent", agents }),
+      onAsk: (question) => agent.ask(question),
     });
 
     const resourceLoader = new DefaultResourceLoader({
@@ -151,9 +155,11 @@ export class CodeAgent {
     agent.#disposePlugins = akan.dispose;
     agent.#mcp = akan.mcp;
     agent.#workspaceRoot = workspaceRoot;
-    if (options.profile.session.store === "file") agent.#sessionDir = akanCodePaths.sessionsDir(workspaceRoot);
+    if (options.profile.session.store !== "memory") agent.#sessionDir = akanCodePaths.sessionsDir(workspaceRoot);
     await agent.#attach(session, options.mode ?? "print");
-    if (agent.#sessionDir) agent.#openMail(akanCodePaths.mailDir(workspaceRoot), cwd);
+    agent.#suspended = new CodeAgentSuspended(CodeAgentSuspended.fileOf(agent.#sessionDir, agent.sessionId));
+    if (agent.#sessionDir && options.profile.session.store === "file")
+      agent.#openMail(akanCodePaths.mailDir(workspaceRoot), cwd);
     for (const message of modelWarnings) agent.#emit({ type: "notice", level: "warning", message });
     return agent;
   }
@@ -260,6 +266,10 @@ export class CodeAgent {
   announce() {
     this.#emit({ type: "session", info: this.info });
     this.#restore();
+    //* A resumed worker says again what it is still waiting on, or a host that reattached has no card to answer.
+    const { question, approvals } = this.#suspended;
+    if (question) this.#emit({ type: "question", question });
+    for (const request of approvals) this.#emit({ type: "approval", request });
   }
 
   /**
@@ -281,6 +291,7 @@ export class CodeAgent {
       const text = CodeAgent.#textOf(message.content);
       if (text) this.#emit({ type: "message", turnId, role: message.role, text });
     }
+    this.#emitContextNow();
   }
 
   static #textOf(content: unknown) {
@@ -343,10 +354,13 @@ export class CodeAgent {
       return true;
     }
     if (this.#profile.interaction.question !== "suspend") return false;
-    this.#emit({ type: "question_resolved", questionId, answer, rendered });
+    const suspended = this.#suspended.takeQuestion(questionId);
+    if (!suspended) return false;
+    const suspendedRendered = codeAgentRenderAnswer(suspended, answer);
+    this.#emit({ type: "question_resolved", questionId, answer, rendered: suspendedRendered });
     // The answer has to reach the model as prose: compaction and the next turn read message content only, so
     // an answer that exists solely as structure is one the agent will not remember being given.
-    await this.prompt(`The user answered: ${rendered}\nContinue the task.`);
+    await this.prompt(`The user answered: ${suspendedRendered}\nContinue the task.`);
     return true;
   }
 
@@ -356,6 +370,7 @@ export class CodeAgent {
       return true;
     }
     if (this.#profile.interaction.approval !== "suspend") return false;
+    if (!this.#suspended.takeApproval(approvalId)) return false;
     this.#emit({ type: "approval_resolved", approvalId, approved });
     if (approved) await this.prompt("The user approved the pending action. Retry it and continue.");
     return true;
@@ -400,6 +415,33 @@ export class CodeAgent {
     this.#emit({ type: "session", info: this.info });
   }
 
+  /**
+   * The model catalogue, as the two questions a person actually asks of it.
+   *
+   * Built from the registry rather than `getAvailable()` so it needs no await and can answer about a provider
+   * nobody has a key for: "what else could I run" is most of why the list is opened, and a list of only what
+   * is already reachable cannot answer it.
+   */
+  catalogue(): CodeAgentProviderInfo[] {
+    const runtime = this.#session?.modelRuntime;
+    if (!runtime) return [];
+    const current = this.#session?.model;
+    return runtime
+      .getProviders()
+      .map((provider) => ({
+        id: provider.id,
+        name: provider.name ?? provider.id,
+        authorized: runtime.hasConfiguredAuth(provider.id),
+        models: (runtime.getModels(provider.id) ?? []).map((model) => ({
+          id: model.id,
+          name: model.name,
+          ...(model.contextWindow ? { contextWindow: model.contextWindow } : {}),
+          current: model.provider === current?.provider && model.id === current?.id,
+        })),
+      }))
+      .sort((a, b) => a.id.localeCompare(b.id));
+  }
+
   async setModel(ref: CodeAgentModelRef) {
     const session = this.#require();
     const model = await akanCodeModel(session.modelRuntime, ref);
@@ -461,6 +503,17 @@ export class CodeAgent {
    */
   #emitContextUsage(eventType: string) {
     if (eventType !== "agent_end" && eventType !== "compaction_end") return;
+    this.#emitContextNow();
+  }
+
+  /**
+   * The same frame, on demand, for the one moment the window is already full and no turn has run.
+   *
+   * A resumed session restores a conversation the model is carrying and the host has never seen, so without
+   * this the status line offers the declared window and no share of it until the next turn ends — a session
+   * reopened at 80% looks identical to one reopened empty.
+   */
+  #emitContextNow() {
     const usage = this.#session?.getContextUsage();
     // `== null`, not `=== null`: the field is typed `number | null`, and a strict null check sails straight
     // past an `undefined` the way the mirror of this bug does — which would emit `used: undefined`.
@@ -520,42 +573,53 @@ export class CodeAgent {
     // Nobody to ask means nobody to refuse: a pod would otherwise deny every write it was created to make.
     if (!this.#profile.ui.canPrompt) return true;
     const approvalId = this.#asks.nextId("a");
-    this.#emit({
-      type: "approval",
-      request: {
-        approvalId,
-        toolCallId,
-        name,
-        summary: codeAgentClip(summary, codeAgentLabelChars),
-        policy: this.#profile.approval,
-      },
-    });
+    const request = {
+      approvalId,
+      toolCallId,
+      name,
+      summary: codeAgentClip(summary, codeAgentLabelChars),
+      policy: this.#profile.approval,
+    };
+    this.#emit({ type: "approval", request });
     if (this.#profile.interaction.approval === "suspend") {
+      this.#suspended.addApproval(request);
       this.#mapper.noteOutcome("awaiting");
       return false;
     }
     return await this.#asks.openApproval(approvalId);
   }
 
+  /**
+   * Puts one question on the wire and waits for its answer, rendered as the labels a person chose.
+   *
+   * The single way anything asks: the engine's own UI port and the `ask_user` tool both land here, so the
+   * suspend path, the profile's refusal to prompt at all, and the id the host answers against cannot disagree
+   * between them. An empty answer is a skip, which is a real answer and not a failure.
+   */
+  async ask(spec: Omit<CodeAgentQuestion, "questionId">) {
+    const question: CodeAgentQuestion = { questionId: this.#asks.nextId("q"), ...spec };
+    if (!this.#profile.ui.canPrompt) {
+      this.#emit({ type: "question_skipped", question, reason: "no-host" });
+      return undefined;
+    }
+    this.#emit({ type: "question", question });
+    if (this.#profile.interaction.question === "suspend") {
+      this.#suspended.setQuestion(question);
+      this.#mapper.noteOutcome("awaiting");
+      return undefined;
+    }
+    return (await this.#asks.openQuestion(question)) || undefined;
+  }
+
   #ui() {
     return new CodeAgentUi({
-      ask: async (prompt, kind, choices) => {
-        if (!this.#profile.ui.canPrompt) return undefined;
-        const questionId = this.#asks.nextId("q");
-        const question: CodeAgentQuestion = {
-          questionId,
+      ask: async (prompt, kind, choices) =>
+        await this.ask({
           prompt,
           kind,
           ...(choices ? { options: choices.map((label) => ({ key: label, label })) } : {}),
           freeText: kind === "text",
-        };
-        this.#emit({ type: "question", question });
-        if (this.#profile.interaction.question === "suspend") {
-          this.#mapper.noteOutcome("awaiting");
-          return undefined;
-        }
-        return (await this.#asks.openQuestion(question)) || undefined;
-      },
+        }),
       notify: (level, message) => this.#emit({ type: "notice", level, message }),
     });
   }

package/codeAgent/agent/CodeAgentAsks.ts

@@ -19,6 +19,8 @@ export class CodeAgentAsks {
   #question: { question: CodeAgentQuestion; deferred: Deferred<string> } | undefined;
   readonly #approvals = new Map<string, Deferred<boolean>>();
   #nextId = 0;
+  //* Ids outlive the process on a suspending session, so a resumed worker must not hand out `q1` a second time.
+  readonly #epoch = Date.now().toString(36);
 
   get pendingQuestionId() {
     return this.#question?.question.questionId;
@@ -35,7 +37,7 @@ export class CodeAgentAsks {
 
   nextId(prefix: string) {
     this.#nextId += 1;
-    return `${prefix}${this.#nextId}`;
+    return `${prefix}${this.#epoch}.${this.#nextId}`;
   }
 
   openQuestion(question: CodeAgentQuestion) {

package/codeAgent/agent/CodeAgentEventMapper.ts

@@ -79,7 +79,15 @@ export class CodeAgentEventMapper {
       case "compaction_start":
         return [{ type: "compaction", phase: "start", reason: event.reason }];
       case "compaction_end":
-        return [{ type: "compaction", phase: "end", reason: event.reason }];
+        return [
+          {
+            type: "compaction",
+            phase: "end",
+            reason: event.reason,
+            ...(event.errorMessage ? { error: event.errorMessage } : {}),
+            ...(event.aborted ? { aborted: true } : {}),
+          },
+        ];
       case "auto_retry_start":
         return [
           {

package/codeAgent/agent/CodeAgentProxy.ts

@@ -0,0 +1,91 @@
+import { readFile } from "node:fs/promises";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type { CodeAgentProfile } from "akanjs/common";
+import { akanCodeDefaultModel } from "./akanCodeModel";
+
+interface PreparedRequest {
+  model: { provider: string; baseUrl?: string };
+  options: { apiKey?: string };
+}
+
+type PrepareRequest = (model: unknown, options?: Record<string, unknown>) => Promise<PreparedRequest>;
+
+export interface CodeAgentProxyOptions {
+  baseUrl: string;
+  providers: string[];
+  tokenFile?: string;
+  token?: string;
+}
+
+/**
+ * Routes every model request through a host's LLM proxy, so a pod never holds a provider key: the host mints a
+ * short-lived token, writes it to a file, and rotates it there while the worker keeps running.
+ *
+ * `baseUrl` may carry `{provider}` for a proxy that fronts several providers under one host.
+ */
+export class CodeAgentProxy {
+  static readonly placeholderKey = "akan-code-proxy";
+
+  readonly baseUrl: string;
+  readonly providers: string[];
+  readonly #tokenFile?: string;
+  readonly #token?: string;
+
+  constructor({ baseUrl, providers, tokenFile, token }: CodeAgentProxyOptions) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.providers = providers;
+    this.#tokenFile = tokenFile;
+    this.#token = token;
+    if (!tokenFile && !token)
+      throw new Error("AKAN_CODE_PROXY_URL needs AKAN_CODE_PROXY_TOKEN_FILE or AKAN_CODE_PROXY_TOKEN");
+  }
+
+  static fromEnv(profile?: CodeAgentProfile): CodeAgentProxy | null {
+    const baseUrl = process.env.AKAN_CODE_PROXY_URL?.trim() || profile?.network.proxyBaseUrl;
+    if (!baseUrl) return null;
+    const providers = (process.env.AKAN_CODE_PROXY_PROVIDERS ?? akanCodeDefaultModel.provider)
+      .split(",")
+      .map((provider) => provider.trim())
+      .filter(Boolean);
+    return new CodeAgentProxy({
+      baseUrl,
+      providers,
+      tokenFile: process.env.AKAN_CODE_PROXY_TOKEN_FILE?.trim() || undefined,
+      token: process.env.AKAN_CODE_PROXY_TOKEN?.trim() || undefined,
+    });
+  }
+
+  baseUrlFor(provider: string) {
+    return this.baseUrl.replaceAll("{provider}", provider);
+  }
+
+  //* Read per request, not cached: the host rotates a token that outlives no single turn, and a worker holding the
+  //* first one would start failing half an hour into a session it is still running.
+  async token() {
+    if (!this.#tokenFile) return this.#token ?? "";
+    const token = (await readFile(this.#tokenFile, "utf8")).trim();
+    if (!token) throw new Error(`${this.#tokenFile} is empty`);
+    return token;
+  }
+
+  /**
+   * `prepareRequest` is the one path every stream, completion, compaction and cache-warm request takes, which is
+   * why it is wrapped rather than the public stream methods. It is private in the engine's typings, so its
+   * absence after an engine upgrade fails here at boot instead of sending a request with no key.
+   */
+  async apply(runtime: ModelRuntime) {
+    const target = runtime as unknown as { prepareRequest?: PrepareRequest };
+    const original = target.prepareRequest?.bind(runtime);
+    if (!original) throw new Error("The model runtime no longer exposes prepareRequest; update CodeAgentProxy");
+    for (const provider of this.providers) await runtime.setRuntimeApiKey(provider, CodeAgentProxy.placeholderKey);
+    target.prepareRequest = async (model, options = {}) => {
+      const apiKey = await this.token();
+      const prepared = await original(model, { ...options, apiKey });
+      return {
+        ...prepared,
+        model: { ...prepared.model, baseUrl: this.baseUrlFor(prepared.model.provider) },
+        options: { ...prepared.options, apiKey },
+      };
+    };
+  }
+}

package/codeAgent/agent/CodeAgentRpcHost.ts

@@ -2,7 +2,7 @@ import type { CodeAgentCommand, CodeAgentEvent, CodeAgentReply, CodeAgentRequest
 import type { CodeAgent } from "./CodeAgent";
 
 /**
- * Serves one code agent over stdio as newline-delimited akan wire frames.
+ * Serves one code agent as newline-delimited akan wire frames, over stdio or whatever transport attaches.
  *
  * The protocol is **ours**, not the engine's: a host — the web relay, a pod runner, a test harness — reads the
  * same events the in-process API emits, so an engine upgrade stops at the core instead of reaching every
@@ -13,23 +13,41 @@ import type { CodeAgent } from "./CodeAgent";
  */
 export class CodeAgentRpcHost {
   readonly #agent: CodeAgent;
-  readonly #write: (line: string) => void;
+  #write: ((line: string) => void) | null;
   #buffer = "";
+  #started = false;
+  #resolveShutdown: () => void = () => {};
+  readonly shutdown = new Promise<void>((resolve) => {
+    this.#resolveShutdown = resolve;
+  });
 
-  constructor(agent: CodeAgent, write: (line: string) => void = (line) => process.stdout.write(line)) {
+  constructor(agent: CodeAgent, write: ((line: string) => void) | null = (line) => process.stdout.write(line)) {
     this.#agent = agent;
     this.#write = write;
   }
 
   async serve(input: AsyncIterable<Uint8Array> = process.stdin) {
-    this.#agent.on((event) => this.#emit(event));
-    this.#agent.announce();
+    this.start();
     const decoder = new TextDecoder();
-    for await (const chunk of input) await this.#push(decoder.decode(chunk, { stream: true }));
+    for await (const chunk of input) await this.feed(decoder.decode(chunk, { stream: true }));
     await this.#agent.abort().catch(() => {});
   }
 
-  async #push(text: string) {
+  start() {
+    if (this.#started) return;
+    this.#started = true;
+    this.#agent.on((event) => this.#emit(event));
+    this.#agent.announce();
+  }
+
+  //* Frames emitted while no client is attached are dropped here and kept in the agent's replay buffer; a client
+  //* that attaches catches up with `get_state { sinceSeq }` instead of receiving a burst it did not ask for.
+  attach(write: ((line: string) => void) | null) {
+    this.#write = write;
+    this.#buffer = "";
+  }
+
+  async feed(text: string) {
     this.#buffer += text;
     let index = this.#buffer.indexOf("\n");
     while (index >= 0) {
@@ -52,6 +70,8 @@ export class CodeAgentRpcHost {
     } catch (error) {
       this.#reply({ type: "reply", id: request.id, ok: false, error: String(error) });
     }
+    //* After the reply, so a socket transport that closes on shutdown has already written the acknowledgement.
+    if (request.command?.type === "shutdown") this.#resolveShutdown();
   }
 
   /**
@@ -87,10 +107,10 @@ export class CodeAgentRpcHost {
   }
 
   #emit(event: CodeAgentEvent) {
-    this.#write(`${JSON.stringify({ type: "event", event })}\n`);
+    this.#write?.(`${JSON.stringify({ type: "event", event })}\n`);
   }
 
   #reply(reply: CodeAgentReply) {
-    this.#write(`${JSON.stringify(reply)}\n`);
+    this.#write?.(`${JSON.stringify(reply)}\n`);
   }
 }