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

package/codeAgent/agent/AkanCodeServices.ts

@@ -18,60 +18,38 @@ export interface AkanCodeServicesOptions {
   sessionId?: string;
 }
 
-/**
- * Assembles the engine's injectable services from akan's own storage.
- *
- * Every one of the four is passed explicitly. Leave any of them out and the engine falls back to `~/.pi/` —
- * measured: with all four injected it writes nothing outside the paths named here.
- */
+// All four engine services are injected explicitly: any one left out makes the engine fall back to `~/.pi/`.
 export class AkanCodeServices {
   static settings() {
-    // Settings are in memory on purpose: the engine's file settings would be a second configuration surface
-    // beside `akan.config.ts` with its own precedence, for options akan already decides through the profile.
-    // `enableInstallTelemetry` defaults to true and attaches pi-branded headers to OpenRouter, NVIDIA and
-    // Cloudflare requests, so it is turned off here rather than per host — a host that changes provider later
-    // would otherwise turn it back on without meaning to.
+    // In memory on purpose: file settings would be a second configuration surface beside the profile.
+    // `enableInstallTelemetry` defaults to true and adds pi-branded headers to OpenRouter/NVIDIA/Cloudflare calls.
     return SettingsManager.inMemory({
       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.
+      // Twice the engine's 16,384: at 16k a reasoning model stops mid-thought at the compaction threshold,
+      // and the recovery re-sends a near-full window to retry the turn.
       compaction: { reserveTokens: 32_768 },
     });
   }
 
-  /**
-   * The model catalogue and the credentials behind it, both under `~/.akan/`.
-   *
-   * `authPath` is the whole of what akan's own credential file used to need a storage backend for: the engine
-   * 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.
-   */
+  // The engine locks and rewrites `authPath` itself, so two `akan code` refreshing a token at once cannot clobber it.
   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(),
+      //* Behind a proxy no real key may reach a request, so credentials live in a throwaway file.
+      authPath: proxy
+        ? path.join(mkdtempSync(path.join(tmpdir(), "akan-code-proxy-")), "auth.json")
+        : akanCodePaths.authFile(),
       modelsPath: akanCodePaths.modelsFile(),
     });
-    await AkanEnvKeys.apply(runtime, workspaceRoot);
+    if (proxy) await proxy.apply(runtime);
+    else await AkanEnvKeys.apply(runtime, workspaceRoot);
     return runtime;
   }
 
   static sessions(workspaceRoot: string, cwd: string, profile: CodeAgentProfile, resume?: string) {
-    //* `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.
+    //* `remote` has no store of its own yet, so it keeps a file session: a pod worker's suspended asks need it.
     if (profile.session.store === "memory") return SessionManager.inMemory(cwd);
     const dir = akanCodePaths.sessionsDir(workspaceRoot);
     mkdirSync(dir, { recursive: true });
@@ -84,15 +62,7 @@ export class AkanCodeServices {
     return manager;
   }
 
-  /**
-   * The akan skill set, then the person's own, then the workspace's.
-   *
-   * `~/.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.
-   */
+  // Skills are text, never code that runs, so unlike extensions they may come from the home directory too.
   static #skillPaths(profile: CodeAgentProfile, workspaceRoot: string) {
     if (!profile.context.skills) return [];
     const dirs = [
@@ -103,28 +73,16 @@ export class AkanCodeServices {
     return dirs.filter((dir): dir is string => !!dir && existsSync(dir));
   }
 
-  /**
-   * 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.
     const present = (dir: string) => (existsSync(dir) ? [dir] : []);
     return {
       noExtensions: true,
-      // Always on: it turns off the engine's *default* skill locations, which are `~/.pi/skills` and the
-      // checkout's own `.pi/`. Explicit `additionalSkillPaths` are merged either way, so this is the switch
-      // that keeps a skill in whoever's home directory from changing how the agent works here.
+      // Disables only the engine's default skill locations (`~/.pi/skills`, `.pi/`); `additionalSkillPaths` merge.
       noSkills: true,
       noPromptTemplates: true,
       noThemes: true,
       noContextFiles: !options.profile.context.projectFiles,
-      // The engine takes one context file per directory and looks at no editor's own rules, so a repo whose
-      // conventions live in a `CLAUDE.md` or under `.cursor/rules` hands this agent less than it hands the
-      // editor beside it — see {@link AkanContextFiles}. Gated on the same flag, so a profile that wants no
-      // project context still gets none.
       agentsFilesOverride: ({ agentsFiles }: { agentsFiles: AkanContextFile[] }) => ({
         agentsFiles: options.profile.context.projectFiles
           ? AkanContextFiles.extend(agentsFiles, { workspaceRoot: options.workspaceRoot, cwd: options.cwd })

package/codeAgent/agent/AkanContextFiles.ts

@@ -11,25 +11,15 @@ export interface AkanContextFilesOptions {
   cwd: string;
 }
 
-/**
- * The workspace-authored rules the engine's own discovery leaves behind.
- *
- * It walks the ancestors of `cwd` and takes **one** file per directory, first match of
- * `AGENTS.override.md · AGENTS.md · AGENTS.MD · CLAUDE.md · CLAUDE.MD` — so a repo carrying both an `AGENTS.md`
- * and a `CLAUDE.md` has the second one silently dropped, and a `.cursor/rules` tree is never looked at. Both
- * are files a developer wrote expecting an agent to obey them, and an agent that reads one editor's copy and
- * not another's follows rules that disagree with the repo it is in.
- *
- * Added rather than replaced: the base list keeps its order and its precedence, and these land after it.
- */
+// The engine takes only the first of `AGENTS.override.md · AGENTS.md · CLAUDE.md` per directory and never reads
+// `.cursor/rules`; this appends what it drops, after the engine's own list.
 export class AkanContextFiles {
   /** Cursor's frontmatter block, which is metadata for its own rule picker and not instruction for a model. */
   static readonly #frontmatter = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
 
   static extend(base: AkanContextFile[], options: AkanContextFilesOptions): AkanContextFile[] {
     const seen = new Set(base.map((file) => file.path));
-    // Keyed by content as well as by path, because the usual way to carry both names is to make one a symlink
-    // to the other or a one-line pointer at it — and the same guide twice is the same guide twice.
+    // Keyed by content too: the usual way to carry both names is a symlink or a one-line pointer.
     const contents = new Set(base.map((file) => file.content.trim()));
     const added: AkanContextFile[] = [];
     for (const file of [...AkanContextFiles.#claude(base), ...AkanContextFiles.#cursor(options)]) {
@@ -41,12 +31,7 @@ export class AkanContextFiles {
     return [...base, ...added];
   }
 
-  /**
-   * The `CLAUDE.md` beside an `AGENTS.md` the engine already took.
-   *
-   * Not beside an `AGENTS.override.md`: that name means "ignore what this directory would otherwise say", so
-   * reinstating the file it was written to displace is the one case where loading both is wrong.
-   */
+  // Not beside an `AGENTS.override.md`: that file exists to displace the others in its directory.
   static #claude(base: AkanContextFile[]) {
     const files: AkanContextFile[] = [];
     for (const file of base) {
@@ -60,14 +45,7 @@ export class AkanContextFiles {
     return files;
   }
 
-  /**
-   * Cursor's always-on rules, from the workspace root and from the session's own directory.
-   *
-   * Only `alwaysApply: true` is taken. Cursor's other three kinds are conditional — `globs` attaches a rule to
-   * the files it names, a bare `description` offers it for the model to ask for, and neither means the rule is
-   * loaded manually — so putting them in a system prompt applies rules their author scoped away. A file with
-   * no frontmatter at all is the `.cursorrules` shape, which was never conditional.
-   */
+  // Only `alwaysApply: true` or frontmatter-less rules: Cursor's `globs`/`description`/manual kinds are scoped.
   static #cursor(options: AkanContextFilesOptions) {
     const files: AkanContextFile[] = [];
     const roots = [...new Set([options.workspaceRoot, options.cwd])];
@@ -84,7 +62,6 @@ export class AkanContextFiles {
     return files;
   }
 
-  /** The rule body when the rule applies unconditionally, and nothing when its author scoped it. */
   static #applied(raw: string) {
     const match = AkanContextFiles.#frontmatter.exec(raw);
     if (!match) return raw;

package/codeAgent/agent/CodeAgent.ts

@@ -42,11 +42,9 @@ import { CodeAgentUi } from "./CodeAgentUi";
 import { CodeMailbox } from "./CodeMailbox";
 import { CodeSessionFork } from "./CodeSessionFork";
 import { CodeSessionIndex } from "./CodeSessionIndex";
+import type { SubagentSpend } from "./SubagentPool";
 
-/**
- * What the engine calls a run mode. It is not re-exported from the package entry, so the literal set is
- * restated here; it is the whole type, and a mismatch is a type error at the one call site that uses it.
- */
+// The engine's run-mode type is not re-exported from its package entry, so the literal set is restated.
 export type CodeAgentHostMode = "tui" | "rpc" | "json" | "print";
 
 export interface CodeAgentOptions {
@@ -56,23 +54,18 @@ export interface CodeAgentOptions {
   model?: CodeAgentModelRef;
   /** Apps whose dev server and preview the turn-end feedback loop watches. */
   apps?: string[];
-  /** Extra capability packs, layered on top of the profile gate and the akan pack. */
   extensions?: InlineExtension[];
   customTools?: ToolDefinition[];
   /** `print` for a one-shot stream, `rpc` when a host drives this process over stdio. */
   mode?: CodeAgentHostMode;
-  /** How many `task` tools deep this agent already is. A sub-agent is created one level down. */
+  /** How many `task` tools deep this agent already is. */
   depth?: number;
+  /** The tally (tokens spent, sub-agents running) of the sub-agent tree whose `task` opened this agent. */
+  subagentSpend?: SubagentSpend;
   /** Id of a stored session to continue instead of opening a new one. */
   resume?: string;
 }
 
-/**
- * The code agent core: one engine session, gated by a profile, emitting the akan wire.
- *
- * Nothing here knows what a host is. A host receives events, sends commands and injects a profile — which is
- * what lets one core serve a terminal, an RPC child and a browser without three copies of the loop.
- */
 export class CodeAgent {
   readonly #profile: CodeAgentProfile;
   readonly #gate: CodeAgentGate;
@@ -88,12 +81,7 @@ export class CodeAgent {
   #mailbox: CodeMailbox | undefined;
   #mcp: CodeAgentMcpStatus[] = [];
   #workspaceRoot = "";
-  /**
-   * The frames of the turn in flight, so a host that reconnects mid-turn can be handed what it missed.
-   *
-   * Bounded and cleared at `idle`: the completed messages of an earlier turn are in the transcript, and the
-   * only thing that exists nowhere else is the bubble still being written.
-   */
+  // Cleared at `idle`: an earlier turn is in the transcript; only the turn in flight exists nowhere else.
   readonly #replay: CodeAgentEvent[] = [];
   #replayFrom = 0;
   #lastContextTokens: number | undefined;
@@ -120,6 +108,7 @@ export class CodeAgent {
       apps: options.apps ?? [],
       canSeeImages: akanCodeModelSupportsImages(model),
       depth: options.depth ?? 0,
+      ...(options.subagentSpend ? { subagentSpend: options.subagentSpend } : {}),
       currentSessionId: () => agent.sessionId,
       mailbox: () => agent.#mailbox,
       onNotice: (message) => agent.#emit({ type: "notice", level: "warning", message }),
@@ -168,7 +157,6 @@ export class CodeAgent {
     return this.#profile;
   }
 
-  /** Whether the model can be handed a picture at all, which decides whether offering to attach one is honest. */
   get canSeeImages() {
     const model = this.#session?.model;
     return model ? akanCodeModelSupportsImages(model) : false;
@@ -185,10 +173,8 @@ export class CodeAgent {
   }
 
   /**
-   * The MCP servers this session was built against, and what each one published.
-   *
-   * Read from the assembly rather than from the live session: the tool allowlist is fixed when the session is
-   * created, so a server declared afterwards is not one this agent can reach however the file now reads.
+   * As assembled at creation: the tool allowlist is fixed then, so a server declared later is unreachable. A
+   * server's `auth` still turns `required` when a call's token cannot be renewed, until a reload.
    */
   mcpServers(): CodeAgentMcpStatus[] {
     return this.#mcp;
@@ -199,12 +185,7 @@ export class CodeAgent {
     return this.#mailbox?.peers() ?? [];
   }
 
-  /**
-   * Hands a message to another session, which receives it as a prompt of its own.
-   *
-   * It is a prompt rather than a note on its screen because the point of reaching another session is to set
-   * it working — and it goes in as a follow-up, so a peer in the middle of a turn finishes that turn first.
-   */
+  /** The peer receives the text as a prompt of its own, queued as a follow-up when it is mid-turn. */
   send(target: string, text: string) {
     const mailbox = this.#mailbox;
     if (!mailbox) throw new Error("This profile keeps no shared mailbox, so it has no peers.");
@@ -221,7 +202,7 @@ export class CodeAgent {
     this.#mailbox.open(cwd, (mail) => {
       const from = `${mail.fromName} (${mail.from.slice(0, 8)})`;
       this.#emit({ type: "notice", level: "info", message: `message from ${from}` });
-      void this.prompt(`Message from another session — ${from}:\n${mail.text}`).catch((error: unknown) =>
+      void this.#prompt(`Message from another session — ${from}:\n${mail.text}`).catch((error: unknown) =>
         this.#emit({ type: "notice", level: "error", message: String(error) }),
       );
     });
@@ -235,7 +216,6 @@ export class CodeAgent {
     return this.#session?.isStreaming ?? false;
   }
 
-  /** Total tokens this session has spent, which is what a sub-agent budget is drawn down against. */
   get tokensUsed() {
     return this.#session?.getSessionStats().tokens.total ?? 0;
   }
@@ -250,19 +230,14 @@ export class CodeAgent {
       model: model ? { provider: model.provider, id: model.id, name: model.name } : undefined,
       tools: session.getActiveToolNames(),
       contextTokens: model?.contextWindow,
-      // A model that does no reasoning has no level to report, and `off` is a level — one of them is a
-      // capability and the other is a setting, so they cannot share a spelling.
+      // Not `off`: that is a setting of a reasoning model, not the absence of reasoning.
       effort: session.supportsThinking() ? session.thinkingLevel : undefined,
       name: session.sessionName,
       interaction: this.#profile.interaction,
     };
   }
 
-  /**
-   * Emits the opening `session` frame through the same counter as everything else.
-   *
-   * A frame minted outside it would carry `seq: 0`, which every client drops — their watermark starts there.
-   */
+  /** A `session` frame minted outside this counter would carry `seq: 0`, which every client drops. */
   announce() {
     this.#emit({ type: "session", info: this.info });
     this.#restore();
@@ -272,16 +247,7 @@ export class CodeAgent {
     for (const request of approvals) this.#emit({ type: "approval", request });
   }
 
-  /**
-   * Replays a resumed session's conversation onto the wire.
-   *
-   * The model gets its context back from the session file; a host gets nothing, because the wire only carries
-   * what happens live. Without this a resumed session is a blank screen in front of an agent that remembers
-   * everything — which reads as a resume that failed.
-   *
-   * Prose only: the tool traffic of a past turn is in the file, but replaying it would redraw calls nobody is
-   * waiting on, against a working tree that has moved since.
-   */
+  // Prose only: a past turn's tool calls would redraw rows nobody waits on, against a tree that has moved since.
   #restore() {
     const session = this.#session;
     if (!session) return;
@@ -311,12 +277,7 @@ export class CodeAgent {
   /** One turn's worth of frames is kept for reconnection; a client further behind reloads the transcript. */
   static readonly replayLimit = 2_000;
 
-  /**
-   * Current state, and the frames after `sinceSeq` when a reconnecting host asks for them.
-   *
-   * `replayFrom` says how far back the buffer reaches. A client behind it cannot be caught up frame by frame
-   * and has to reload — saying so is better than silently handing it a gap.
-   */
+  /** `frames` only when `sinceSeq` is given; a client behind `replayFrom` has to reload the transcript. */
   async state({ sinceSeq }: { sinceSeq?: number } = {}): Promise<CodeAgentState> {
     const base = { info: this.info, streaming: this.isStreaming, replayFrom: this.#replayFrom };
     if (sinceSeq === undefined) return base;
@@ -324,9 +285,13 @@ export class CodeAgent {
   }
 
   async prompt(message: string, images?: CodeAgentImage[]) {
+    this.#suspended.clear();
+    await this.#prompt(message, images);
+  }
+
+  async #prompt(message: string, images?: CodeAgentImage[]) {
     const session = this.#require();
-    // Named from the first thing asked of it, not from the answer: the name is derived, so waiting for the
-    // turn to end would only mean the session is nameless for exactly as long as it is interesting to watch.
+    // From the first prompt, not the answer, so the session is not nameless while it is worth watching.
     if (!session.sessionName && message.trim()) this.setName(codeAgentSessionName(message));
     const attachments = await CodeAgent.#attachments(images);
     const options = attachments.length ? { images: attachments } : {};
@@ -335,17 +300,13 @@ export class CodeAgent {
   }
 
   async abort() {
-    // The engine finalizes an interrupted message as an ordinary stop, so the only party that knows this was
-    // an abort is the one that asked for it.
+    // The engine finalizes an interrupted message as an ordinary stop, so the abort is noted here.
     this.#mapper.noteOutcome("aborted");
     this.#asks.clear();
     await this.#require().abort();
   }
 
-  /**
-   * Answering is not prompting. Routing an answer through `prompt` would open a turn while the question slot is
-   * still filled, leaving a card on screen that still looks clickable — the library does not stop that.
-   */
+  // Not via `prompt`: that opens a turn with the question slot still filled, which the engine does not stop.
   async answer(questionId: string, answer: CodeAgentAnswer) {
     const question = this.#asks.questionOf(questionId);
     const rendered = question ? codeAgentRenderAnswer(question, answer) : (answer.text ?? "");
@@ -358,9 +319,8 @@ export class CodeAgent {
     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: ${suspendedRendered}\nContinue the task.`);
+    // As prose: compaction and the next turn read message content only, so a structured-only answer is lost.
+    await this.#prompt(`The user answered: ${suspendedRendered}\nContinue the task.`);
     return true;
   }
 
@@ -372,7 +332,7 @@ export class CodeAgent {
     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.");
+    if (approved) await this.#prompt("The user approved the pending action. Retry it and continue.");
     return true;
   }
 
@@ -389,12 +349,7 @@ export class CodeAgent {
     this.#emit({ type: "session", info: this.info });
   }
 
-  /**
-   * Copies this session under a new id, so the conversation can be continued two ways.
-   *
-   * The copy is taken off disk rather than out of memory: the file is what a resume replays, so forking it is
-   * the only version of "the same conversation" that both agents will actually agree on.
-   */
+  /** Copies the session file, not memory, under a new id: the file is what a resume replays. */
   fork(name?: string) {
     if (!this.#sessionDir) throw new Error("This profile keeps no sessions on disk, so there is nothing to fork");
     return CodeSessionFork.fork(this.#sessionDir, this.sessionId, name);
@@ -415,13 +370,7 @@ 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.
-   */
+  /** Every registered provider, keyed or not — `getAvailable()` would list only what is already reachable. */
   catalogue(): CodeAgentProviderInfo[] {
     const runtime = this.#session?.modelRuntime;
     if (!runtime) return [];
@@ -468,7 +417,8 @@ export class CodeAgent {
     this.#session = session;
     session.subscribe((event) => {
       for (const body of this.#mapper.map(event)) this.#emit(body);
-      this.#emitContextUsage(event.type);
+      // Per turn, not per delta: the count only moves when a provider response lands.
+      if (event.type === "agent_end" || event.type === "compaction_end") this.#emitContextNow();
     });
     await session.bindExtensions({
       mode,
@@ -494,29 +444,10 @@ export class CodeAgent {
     );
   }
 
-  /**
-   * Reports how full the window is, once per turn and after a compaction.
-   *
-   * Per turn rather than per delta: the number moves only when a provider response lands, and a frame per
-   * token delta would be thousands of frames saying the same thing. `tokens` is null right after a compaction
-   * and before the next response — that is "unknown", not zero, so nothing is emitted for it.
-   */
-  #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.
-   */
+  // Also on resume, or a session reopened at 80% shows no usage until its next turn ends.
   #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`.
+    // `== null` on purpose: typed `number | null`, but `undefined` must not emit `used: undefined`.
     if (usage?.tokens == null) return;
     if (usage.tokens === this.#lastContextTokens) return;
     this.#lastContextTokens = usage.tokens;
@@ -589,13 +520,7 @@ export class CodeAgent {
     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.
-   */
+  /** The rendered answer; `undefined` when skipped, suspended, or nobody can be prompted. */
   async ask(spec: Omit<CodeAgentQuestion, "questionId">) {
     const question: CodeAgentQuestion = { questionId: this.#asks.nextId("q"), ...spec };
     if (!this.#profile.ui.canPrompt) {

package/codeAgent/agent/CodeAgentAsks.ts

@@ -1,23 +1,10 @@
 import type { CodeAgentQuestion } from "akanjs/common";
 
-interface Deferred<T> {
-  resolve: (value: T) => void;
-  promise: Promise<T>;
-}
-
-/**
- * Holds what the agent is waiting on a person for.
- *
- * A question is a **single slot**: asking one ends the turn, so a second cannot exist. An approval is a
- * **queue**: "may I write this file" naturally arrives twice in a row while a turn is still running, and a
- * single slot would drop the second silently.
- *
- * Idempotency is by id. Two browser tabs, or answering after a refresh, both produce a second answer for an id
- * that is already resolved — which must be ignored rather than applied to whatever is pending now.
- */
+// A question is a single slot (asking ends the turn); approvals queue, since two can arrive within one turn.
+// Idempotent by id: a second tab, or an answer after a refresh, for an already resolved id is ignored.
 export class CodeAgentAsks {
-  #question: { question: CodeAgentQuestion; deferred: Deferred<string> } | undefined;
-  readonly #approvals = new Map<string, Deferred<boolean>>();
+  #question: { question: CodeAgentQuestion; deferred: PromiseWithResolvers<string> } | undefined;
+  readonly #approvals = new Map<string, PromiseWithResolvers<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);
@@ -26,7 +13,6 @@ export class CodeAgentAsks {
     return this.#question?.question.questionId;
   }
 
-  /** The open question, so an answer can be rendered against the options it was asked with. */
   questionOf(questionId: string) {
     return this.#question?.question.questionId === questionId ? this.#question.question : undefined;
   }
@@ -41,10 +27,9 @@ export class CodeAgentAsks {
   }
 
   openQuestion(question: CodeAgentQuestion) {
-    // A question opened while one is already pending replaces it: the old turn is gone, so nobody is left to
-    // receive the old answer, and leaving it would strand the caller forever.
+    // Replaces a pending question: its turn is gone, and leaving it unresolved would strand its caller.
     this.#question?.deferred.resolve("");
-    const deferred = CodeAgentAsks.#defer<string>();
+    const deferred = Promise.withResolvers<string>();
     this.#question = { question, deferred };
     return deferred.promise;
   }
@@ -58,7 +43,7 @@ export class CodeAgentAsks {
   }
 
   openApproval(id: string) {
-    const deferred = CodeAgentAsks.#defer<boolean>();
+    const deferred = Promise.withResolvers<boolean>();
     this.#approvals.set(id, deferred);
     return deferred.promise;
   }
@@ -78,12 +63,4 @@ export class CodeAgentAsks {
     for (const deferred of this.#approvals.values()) deferred.resolve(false);
     this.#approvals.clear();
   }
-
-  static #defer<T>(): Deferred<T> {
-    let resolve: (value: T) => void = () => {};
-    const promise = new Promise<T>((r) => {
-      resolve = r;
-    });
-    return { resolve, promise };
-  }
 }