@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/codeAgent/agent/SubagentPool.ts

@@ -0,0 +1,214 @@
+import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
+import { type CodeAgentProfile, type CodeAgentSubagent, codeAgentReadOnlyBuiltins } from "akanjs/common";
+import { Type } from "typebox";
+import type { Workspace } from "../../commandDecorators";
+
+export interface SubagentPoolOptions {
+  workspace: Workspace;
+  cwd: string;
+  parent: CodeAgentProfile;
+  depth: number;
+  /** What the tree above this pool has spent and has running; a root pool starts its own. */
+  spend?: SubagentSpend;
+  onNotice?: (message: string) => void;
+  /** The running children, whole, for a host that draws them as a rail beside the prompt. */
+  onAgents?: (agents: CodeAgentSubagent[]) => void;
+}
+
+/** One object shared down a sub-agent tree, so a single token budget and a single concurrency limit bound it. */
+export interface SubagentSpend {
+  tokens: number;
+  running: number;
+}
+
+const maxResultChars = 8_000;
+
+// Children are re-reported every second: their token counts climb between start and finish.
+const tickMs = 1_000;
+
+export type SubagentKind = keyof typeof SubagentPool.kinds;
+
+// Only a child's answer crosses back, never its transcript. Depth, concurrency and token ceilings are checked
+// before a child exists, because an unbounded recursive `task` is a fork bomb that bills per token.
+export class SubagentPool {
+  static readonly kinds = {
+    explore: {
+      readOnly: true,
+      desc: "reads, searches and reports back. It cannot write a file or run a command.",
+    },
+    code: {
+      readOnly: false,
+      desc: "makes the change itself, with the same tools as this session.",
+    },
+  } as const;
+
+  // A writer works unwatched on the parent's checkout, so it has to be asked for by name, never defaulted.
+  static readonly defaultKind: SubagentKind = "explore";
+
+  readonly #options: SubagentPoolOptions;
+  readonly #children = new Map<
+    string,
+    { kind: SubagentKind; description: string; startedAt: number; agent?: { tokensUsed: number } }
+  >();
+  readonly #spend: SubagentSpend;
+  #ticker: ReturnType<typeof setInterval> | null = null;
+
+  constructor(options: SubagentPoolOptions) {
+    this.#options = options;
+    this.#spend = options.spend ?? { tokens: 0, running: 0 };
+  }
+
+  static extensionFor(options: SubagentPoolOptions): InlineExtension | undefined {
+    if (!options.parent.tools.subagent) return undefined;
+    if (options.depth >= options.parent.tools.subagent.maxDepth) return undefined;
+    const pool = new SubagentPool(options);
+    return { name: "akan-subagent", factory: (pi: ExtensionAPI) => pool.#register(pi) };
+  }
+
+  static readonly toolName = "task";
+
+  #register(pi: ExtensionAPI) {
+    pi.registerTool({
+      name: SubagentPool.toolName,
+      label: "Task",
+      description:
+        "Run a focused sub-agent on one self-contained question and get back its answer. Use it for searching and reading that would otherwise fill this conversation — the sub-agent's own reading does not come back, only its answer. Give it everything it needs: it cannot see this conversation.",
+      promptSnippet: "task: run a sub-agent on one self-contained question and get back only its answer",
+      parameters: Type.Object({
+        description: Type.String({ description: "Three to five words naming the task, for the activity log." }),
+        prompt: Type.String({
+          description: "The complete instruction. The sub-agent sees nothing of this conversation.",
+        }),
+        type: Type.Optional(
+          Type.Union(
+            Object.entries(SubagentPool.kinds).map(([kind, spec]) => Type.Literal(kind, { description: spec.desc })),
+            { description: `What the sub-agent may do. Defaults to ${SubagentPool.defaultKind}.` },
+          ),
+        ),
+      }),
+      execute: async (id, params, signal) => {
+        const kind = (params.type ?? SubagentPool.defaultKind) as SubagentKind;
+        const refusal = this.#refuse();
+        if (refusal) return { content: [{ type: "text", text: refusal }], details: undefined, isError: true };
+        this.#spend.running += 1;
+        this.#children.set(id, { kind, description: params.description, startedAt: Date.now() });
+        this.#report();
+        // Announced at start: a turn quiet for a minute while a child reads looks like one that stopped responding.
+        this.#options.onNotice?.(`${kind} sub-agent · ${params.description}`);
+        try {
+          const text = await this.#run(id, kind, params.prompt, signal);
+          return { content: [{ type: "text", text }], details: undefined };
+        } finally {
+          this.#spend.running -= 1;
+          this.#children.delete(id);
+          this.#report();
+        }
+      },
+    });
+  }
+
+  #refuse() {
+    const budget = this.#options.parent.tools.subagent;
+    if (!budget) return "Sub-agents are disabled by this profile.";
+    // Refused, never queued: every ancestor keeps its slot while it waits on its child, so a queued child deadlocks.
+    if (this.#spend.running >= budget.maxConcurrent)
+      return `Too many sub-agents are already running (limit ${budget.maxConcurrent} at once, counted across the whole task tree). ${this.#children.size ? "Wait for one of yours to finish, or do" : "Do"} this part yourself.`;
+    if (this.#spend.tokens >= budget.budget)
+      return `The sub-agent token budget (${budget.budget}) is spent. Do the rest of this work yourself.`;
+    return undefined;
+  }
+
+  /** The parent profile narrowed, never widened: no session file, no `AGENTS.md`, nobody to ask; skills stay. */
+  static childOf(parent: CodeAgentProfile, kind: SubagentKind): CodeAgentProfile {
+    const budget = parent.tools.subagent;
+    return {
+      ...parent,
+      name: `${parent.name}:${kind}`,
+      tools: {
+        ...parent.tools,
+        // Filtered, not replaced: a child of a read-only session must never gain a write tool.
+        builtin: SubagentPool.kinds[kind].readOnly
+          ? parent.tools.builtin.filter((tool) => codeAgentReadOnlyBuiltins.includes(tool))
+          : parent.tools.builtin,
+        subagent: budget ? { ...budget, maxDepth: budget.maxDepth } : false,
+      },
+      session: { store: "memory", crossSession: false },
+      ui: { canPrompt: false },
+      context: { projectFiles: false, skills: parent.context.skills },
+    };
+  }
+
+  // One ticker per pool, unref'd: a child left registered is a bug that must not hold the process open.
+  #report() {
+    const onAgents = this.#options.onAgents;
+    if (!onAgents) return;
+    onAgents(
+      [...this.#children].map(([id, child]) => ({
+        id,
+        kind: child.kind,
+        description: child.description,
+        startedAt: child.startedAt,
+        tokens: child.agent?.tokensUsed ?? 0,
+      })),
+    );
+    if (this.#children.size && !this.#ticker) {
+      this.#ticker = setInterval(() => this.#report(), tickMs);
+      this.#ticker.unref?.();
+    } else if (!this.#children.size && this.#ticker) {
+      clearInterval(this.#ticker);
+      this.#ticker = null;
+    }
+  }
+
+  async #run(id: string, kind: SubagentKind, prompt: string, signal: AbortSignal | undefined) {
+    const { CodeAgent } = await import("./CodeAgent");
+    const budget = this.#options.parent.tools.subagent;
+    const child = SubagentPool.childOf(this.#options.parent, kind);
+    const agent = await CodeAgent.create({
+      workspace: this.#options.workspace,
+      cwd: this.#options.cwd,
+      profile: child,
+      apps: [],
+      depth: this.#options.depth + 1,
+      subagentSpend: this.#spend,
+    });
+    const running = this.#children.get(id);
+    if (running) running.agent = agent;
+    let stopped = false;
+    const abort = () => {
+      stopped = true;
+      void agent.abort();
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+    // A listener added to an already-aborted signal never fires: this child was stopped while it was being created.
+    if (signal?.aborted) stopped = true;
+    let finished = false;
+    try {
+      let answer = "";
+      agent.on((event) => {
+        if (event.type === "message" && event.role === "assistant") answer = event.text;
+        // The engine drops an abort that lands before its run is live, so a stopped child is stopped again there.
+        if (event.type === "turn_start" && stopped) void agent.abort();
+      });
+      if (!stopped) {
+        await agent.prompt(prompt);
+        await agent.waitForIdle();
+      }
+      finished = true;
+      return answer.length > maxResultChars
+        ? `${answer.slice(0, maxResultChars)}\n…(truncated)`
+        : answer || "(no answer)";
+    } finally {
+      signal?.removeEventListener("abort", abort);
+      // Whatever the outcome: a failed or stopped child was billed too, and its own children are counted by its pool.
+      const tokens = agent.tokensUsed;
+      this.#spend.tokens += tokens;
+      const outcome = stopped ? "stopped" : finished ? "finished" : "failed";
+      const ceiling = budget ? budget.budget : 0;
+      this.#options.onNotice?.(
+        `${kind} sub-agent ${outcome}, ${tokens} tokens (${this.#spend.tokens} of ${ceiling} spent)`,
+      );
+      agent.dispose();
+    }
+  }
+}

package/codeAgent/agent/akanCodeModel.ts

@@ -0,0 +1,47 @@
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+
+// The engine's `Model` type (from `pi-ai`) is not re-exported, so it is recovered from `getModel`.
+export type CodeAgentModel = NonNullable<ReturnType<ModelRuntime["getModel"]>>;
+
+export interface CodeAgentModelRef {
+  provider: string;
+  id: string;
+}
+
+/** DeepSeek's million-token window is what makes a 26k-token `AGENTS.md` affordable on every turn. */
+export const akanCodeDefaultModel: CodeAgentModelRef = { provider: "deepseek", id: "deepseek-flash" };
+
+// Declared text-only by the catalogue, yet verified against the provider to see images.
+// `deepseek-v4-pro` is deliberately absent: it accepts an image and then says it cannot view it.
+const catalogueMissesImages = new Set(["deepseek/deepseek-v4-flash"]);
+
+const correctInputs = (model: CodeAgentModel | undefined) => {
+  if (!model || model.input.includes("image")) return model;
+  if (!catalogueMissesImages.has(`${model.provider}/${model.id}`)) return model;
+  return { ...model, input: [...model.input, "image" as const] };
+};
+
+// An empty API key yields a successful empty response rather than an error, so unauthorized providers are skipped.
+export const akanCodeModel = async (runtime: ModelRuntime, ref?: CodeAgentModelRef) => {
+  if (ref) {
+    const requested = runtime.getModel(ref.provider, ref.id);
+    if (!requested) throw new Error(`Unknown model: ${ref.provider}/${ref.id}`);
+    if (!runtime.hasConfiguredAuth(ref.provider))
+      throw new Error(`No API key configured for ${ref.provider}. Set ${ref.provider.toUpperCase()}_API_KEY.`);
+    return correctInputs(requested);
+  }
+  const fallback = runtime.getModel(akanCodeDefaultModel.provider, akanCodeDefaultModel.id);
+  if (fallback && runtime.hasConfiguredAuth(fallback.provider)) return correctInputs(fallback);
+  return correctInputs((await runtime.getAvailable())[0]);
+};
+
+export const akanCodeModelSupportsImages = (model: CodeAgentModel | undefined) => !!model?.input.includes("image");
+
+// Deliberately the only check: `maxTokens >= contextWindow` or `reserveTokens > maxTokens` flag 1 model in 7.
+export const akanCodeModelWarnings = (model: CodeAgentModel | undefined, compactionFloor: number) => {
+  if (!model) return [];
+  if (model.contextWindow >= compactionFloor) return [];
+  return [
+    `${model.provider}/${model.id} declares a ${model.contextWindow}-token context window, below the ${compactionFloor} the compaction policy needs, so every turn will compact immediately. Check the model entry in ~/.akan/code/models.json.`,
+  ];
+};

package/codeAgent/agent/akanCodePaths.ts

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+// Two candidates: the CLI bundle flattens entry chunks into the package root, where `skills/` is a sibling.
+const builtinSkillsDir = () => {
+  const candidates = [path.join(import.meta.dir, "skills"), path.join(import.meta.dir, "..", "skills")];
+  return candidates.find((candidate) => existsSync(candidate));
+};
+
+// One override for the whole set, so a `models.json` and the `auth.json` it names never drift apart.
+const globalDir = () => process.env.AKAN_CODE_HOME ?? path.join(homedir(), ".akan", "code");
+
+// Credentials live under the home directory, never the repo: a repo is what gets committed, zipped and shared.
+export const akanCodePaths = {
+  workspaceDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code"),
+  sessionsDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "sessions"),
+  extensionsDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "extensions"),
+  skillsDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "skills"),
+  mailDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "mail"),
+  builtinSkillsDir,
+  mcpFile: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "mcp.json"),
+  /** Person-wide MCP servers; the workspace `mcpFile` wins on a name they share. */
+  globalMcpFile: () => path.join(globalDir(), "mcp.json"),
+  globalSkillsDir: () => path.join(globalDir(), "skills"),
+  globalDir,
+  authFile: () => path.join(globalDir(), "auth.json"),
+  /** MCP bearer tokens, beside the provider keys and for the same reason: never in a directory that is shared. */
+  mcpAuthFile: () => path.join(globalDir(), "mcpAuth.json"),
+  modelsFile: () => path.join(globalDir(), "models.json"),
+} as const;

package/codeAgent/agent/akanContextFiles.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { type AkanContextFile, AkanContextFiles } from "./AkanContextFiles";
+
+const roots: string[] = [];
+
+const workspace = (files: Record<string, string>) => {
+  const root = mkdtempSync(path.join(tmpdir(), "akan-context-"));
+  roots.push(root);
+  for (const [name, content] of Object.entries(files)) {
+    const file = path.join(root, name);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, content);
+  }
+  return root;
+};
+
+const loaded = (root: string, name = "AGENTS.md"): AkanContextFile[] => [
+  { path: path.join(root, name), content: "the workspace guide" },
+];
+
+const namesOf = (files: AkanContextFile[], root: string) =>
+  files.map((file) => path.relative(root, file.path).split(path.sep).join("/"));
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("workspace context files", () => {
+  test("a CLAUDE.md beside the AGENTS.md the engine took is loaded too", () => {
+    const root = workspace({ "AGENTS.md": "the workspace guide", "CLAUDE.md": "comments override" });
+    const files = AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root });
+    expect(namesOf(files, root)).toEqual(["AGENTS.md", "CLAUDE.md"]);
+    expect(files[1]?.content).toBe("comments override");
+  });
+
+  test("an AGENTS.override.md keeps the CLAUDE.md it was written to displace out", () => {
+    const root = workspace({ "AGENTS.override.md": "instead of that", "CLAUDE.md": "the old one" });
+    const files = AkanContextFiles.extend(loaded(root, "AGENTS.override.md"), { workspaceRoot: root, cwd: root });
+    expect(namesOf(files, root)).toEqual(["AGENTS.override.md"]);
+  });
+
+  test("the same guide under two names is loaded once", () => {
+    const root = workspace({ "AGENTS.md": "the workspace guide" });
+    symlinkSync(path.join(root, "AGENTS.md"), path.join(root, "CLAUDE.md"));
+    expect(namesOf(AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root }), root)).toEqual([
+      "AGENTS.md",
+    ]);
+  });
+
+  test("an always-on cursor rule is loaded without its frontmatter", () => {
+    const root = workspace({
+      ".cursor/rules/house.mdc": "---\ndescription: house style\nalwaysApply: true\n---\nnever use any\n",
+    });
+    const files = AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root });
+    expect(namesOf(files, root)).toEqual(["AGENTS.md", ".cursor/rules/house.mdc"]);
+    expect(files[1]?.content).toBe("never use any\n");
+  });
+
+  test("a scoped cursor rule is left to cursor", () => {
+    const root = workspace({
+      ".cursor/rules/ui.mdc": "---\nglobs: ui/**/*.tsx\n---\nno inline colours\n",
+      ".cursor/rules/ask.mdc": "---\ndescription: for migrations\n---\nread the plan\n",
+      ".cursor/rules/off.mdc": "---\nalwaysApply: false\n---\nnot this one\n",
+    });
+    expect(namesOf(AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root }), root)).toEqual([
+      "AGENTS.md",
+    ]);
+  });
+
+  test("a rule with no frontmatter at all is unconditional, and so is .cursorrules", () => {
+    const root = workspace({ ".cursor/rules/plain.mdc": "just do it", ".cursorrules": "the legacy file" });
+    const files = AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root });
+    expect(namesOf(files, root).sort()).toEqual([".cursorrules", ".cursor/rules/plain.mdc", "AGENTS.md"].sort());
+  });
+
+  test("rules nested under the rules directory are found, in a stable order", () => {
+    const root = workspace({
+      ".cursor/rules/b.mdc": "---\nalwaysApply: true\n---\nsecond\n",
+      ".cursor/rules/a.mdc": "---\nalwaysApply: true\n---\nfirst\n",
+      ".cursor/rules/deep/c.mdc": "---\nalwaysApply: true\n---\nthird\n",
+    });
+    const files = AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root });
+    expect(namesOf(files, root)).toEqual([
+      "AGENTS.md",
+      ".cursor/rules/a.mdc",
+      ".cursor/rules/b.mdc",
+      ".cursor/rules/deep/c.mdc",
+    ]);
+  });
+
+  test("the session's own directory carries its rules as well as the workspace root", () => {
+    const root = workspace({
+      ".cursor/rules/root.mdc": "---\nalwaysApply: true\n---\nworkspace wide\n",
+      "apps/akan/.cursor/rules/app.mdc": "---\nalwaysApply: true\n---\napp only\n",
+    });
+    const cwd = path.join(root, "apps", "akan");
+    const files = AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd });
+    expect(namesOf(files, root)).toEqual(["AGENTS.md", ".cursor/rules/root.mdc", "apps/akan/.cursor/rules/app.mdc"]);
+  });
+
+  test("an empty rule file adds nothing", () => {
+    const root = workspace({ ".cursor/rules/empty.mdc": "---\nalwaysApply: true\n---\n\n" });
+    expect(AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root })).toHaveLength(1);
+  });
+
+  test("nothing to add leaves the list exactly as the engine built it", () => {
+    const root = workspace({ "AGENTS.md": "the workspace guide" });
+    const base = loaded(root);
+    expect(AkanContextFiles.extend(base, { workspaceRoot: root, cwd: root })).toEqual(base);
+  });
+});

package/codeAgent/agent/akanSystemPrompt.ts

@@ -0,0 +1,46 @@
+import type { CodeAgentProfile } from "akanjs/common";
+
+// Only what `AGENTS.md` does not say: the guide is already loaded whole on every turn.
+export const akanSystemPrompt = (profile: CodeAgentProfile) => {
+  const lines = [
+    "You are the akan coding agent, running inside an Akan.js workspace.",
+    "",
+    "- Prefer an akan workflow to a direct source edit. `list_workflows` / `explain_workflow` / `plan_workflow`, then `apply_workflow({ planPath })`. Editing source by hand is the fallback, not the default.",
+    "- Read context with `inspect_akan_context` before reading source bodies; it answers most structural questions without spending the file.",
+    "- Fetch the guideline for an area before a deep pass on it: `get_guideline`.",
+    "- A question about `akan code` itself — its slash commands, MCP servers, sessions, models, keys, or where its files live — is answered by the `akan-code` skill. Read it rather than describing the tool from memory.",
+    "- Never hand-edit a generated file (`lib/cnst.ts`, `db.ts`, `st.ts`, any `*/index.ts` barrel). Fix the owning source and run `repair_generated` or `akan sync`.",
+  ];
+  if (profile.tools.builtin.includes("write"))
+    lines.push(
+      "- After editing, call `akan_verify`. It runs sync, lint, typecheck and the SSR check over what the working tree changed. A turn that edits and does not verify is not finished.",
+    );
+  else
+    lines.push(
+      "- This session is read-only: there is no write, edit or bash tool. Report what should change instead of changing it.",
+    );
+  if (profile.tools.subagent)
+    lines.push(
+      '- Hand a self-contained search or read to `task` — `type: "explore"` reads and reports, `type: "code"` makes the change. Only its answer comes back, so give it everything it needs and ask for exactly what you want returned. Do it yourself when the reading is short or when you need the files in front of you.',
+    );
+  if (profile.ui.canPrompt)
+    lines.push(
+      "- Ask with `ask_user` when two readings of the request would lead to materially different work, and offer the options you can name. Do not ask for a choice that has an obvious default, and do not ask permission for work you were already asked to do — make the call, say the assumption, and carry on.",
+    );
+  if (profile.approval !== "never")
+    lines.push(
+      `- Some tool calls need the user's approval (policy: ${profile.approval}). A refusal is an answer; do not retry it a different way.`,
+    );
+  lines.push(
+    "- Secrets are refused at the tool boundary. If you need a value from `.env`, ask the user for it rather than looking for another way to read the file.",
+    "",
+    "## How to answer",
+    "",
+    "- Answer in as few words as carry the answer. A short question gets one sentence with no heading.",
+    "- Do not open with what you are about to do, and do not close with a summary of what you did. The tool calls are already on the user's screen.",
+    "- Skip headings, bold labels and bullet lists unless the answer is genuinely a list. Prose is shorter.",
+    "- State a file as `path:line`. Do not paste a file back that the user can open.",
+    "- Say what you could not do, and why, in one line. Do not offer alternatives nobody asked for.",
+  );
+  return lines.join("\n");
+};

package/codeAgent/agent/codeAgent.test.ts

@@ -0,0 +1,178 @@
+import { afterAll, beforeAll, describe, expect, spyOn, test } from "bun:test";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
+import { type CodeAgentEvent, type CodeAgentProfile, codeAgentPresets } from "akanjs/common";
+import { WorkspaceExecutor } from "../../executors";
+import { isolateEnv, tempDirs } from "../../testHelpers";
+import { AkanCodePlugins } from "../tools/AkanCodePlugins";
+import { akanCodeDefaultModel } from "./akanCodeModel";
+import { akanCodePaths } from "./akanCodePaths";
+import { CodeAgent, type CodeAgentOptions } from "./CodeAgent";
+import { CodeAgentSuspended } from "./CodeAgentSuspended";
+import { SubagentPool } from "./SubagentPool";
+
+isolateEnv();
+const makeTempRoot = tempDirs("akan-code-agent-");
+
+const chunk = (delta: object, finish: string | null = null) =>
+  `data: ${JSON.stringify({
+    id: "c1",
+    object: "chat.completion.chunk",
+    created: 0,
+    model: akanCodeDefaultModel.id,
+    choices: [{ index: 0, delta, finish_reason: finish }],
+  })}\n\n`;
+
+let llm: ReturnType<typeof Bun.serve>;
+let llmCalls = 0;
+beforeAll(() => {
+  llm = Bun.serve({
+    port: 0,
+    fetch: () => {
+      llmCalls += 1;
+      return new Response(`${chunk({ role: "assistant", content: "ok" })}${chunk({}, "stop")}data: [DONE]\n\n`, {
+        headers: { "content-type": "text/event-stream" },
+      });
+    },
+  });
+});
+afterAll(() => llm.stop(true));
+
+const useProxy = (root: string) => {
+  process.env.AKAN_CODE_HOME = path.join(root, "home");
+  process.env.AKAN_CODE_PROXY_URL = `http://127.0.0.1:${llm.port}/llm/{provider}/v1`;
+  process.env.AKAN_CODE_PROXY_TOKEN = "test-token";
+};
+
+const quietProfile = (root: string): CodeAgentProfile => {
+  const web = codeAgentPresets.web(root);
+  return {
+    ...web,
+    tools: { builtin: [], akan: false, mcp: "off", subagent: false, web: { fetch: false, search: false } },
+    context: { projectFiles: false, skills: false },
+  };
+};
+
+const createAgent = async (root: string, options: Partial<CodeAgentOptions> = {}) => {
+  useProxy(root);
+  return await CodeAgent.create({
+    workspace: new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" }),
+    profile: quietProfile(root),
+    ...options,
+  });
+};
+
+describe("CodeAgent", () => {
+  test("a prompt typed instead of an answer drops the parked asks", async () => {
+    const root = await makeTempRoot();
+    const agent = await createAgent(root);
+    try {
+      await agent.ask({ prompt: "Which app?", kind: "select", options: [{ key: "a", label: "akan" }] });
+      const suspendedFile = CodeAgentSuspended.fileOf(akanCodePaths.sessionsDir(root), agent.sessionId) ?? "";
+      expect(existsSync(suspendedFile)).toBe(true);
+
+      await agent.prompt("Do something else instead.");
+
+      const events: CodeAgentEvent[] = [];
+      agent.on((event) => events.push(event));
+      agent.announce();
+      expect(events.filter((event) => event.type === "question")).toEqual([]);
+      expect(existsSync(suspendedFile)).toBe(false);
+    } finally {
+      agent.dispose();
+    }
+  });
+
+  test("a sub-agent hands its plugins the token tally of the tree that opened it", async () => {
+    const root = await makeTempRoot();
+    const build = AkanCodePlugins.build;
+    const seen: unknown[] = [];
+    const spy = spyOn(AkanCodePlugins, "build").mockImplementation(async (options) => {
+      seen.push(options.subagentSpend);
+      return await build.call(AkanCodePlugins, options);
+    });
+    const subagentSpend = { tokens: 7, running: 0 };
+    try {
+      const agent = await createAgent(root, { subagentSpend, depth: 1 });
+      agent.dispose();
+      expect(seen).toHaveLength(1);
+      expect(seen[0]).toBe(subagentSpend);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});
+
+describe("a sub-agent its parent stops before the sub-agent's run is live", () => {
+  type ToolExecute = (
+    id: string,
+    params: never,
+    signal?: AbortSignal,
+  ) => Promise<{ content: { text: string }[] } | undefined>;
+
+  const runTask = async (root: string, parent: AbortController, notices: string[]) => {
+    useProxy(root);
+    const profile = quietProfile(root);
+    const pool = SubagentPool.extensionFor({
+      workspace: new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" }),
+      cwd: root,
+      parent: { ...profile, tools: { ...profile.tools, subagent: { maxDepth: 2, maxConcurrent: 3, budget: 1_000 } } },
+      depth: 0,
+      onNotice: (message) => notices.push(message),
+    });
+    let execute: ToolExecute | undefined;
+    if (pool && "factory" in pool)
+      pool.factory({
+        registerTool: (tool: { execute: ToolExecute }) => {
+          execute = tool.execute;
+        },
+      } as never);
+    const result = await execute?.("c1", { description: "d", prompt: "p" } as never, parent.signal);
+    return result?.content[0]?.text;
+  };
+
+  test("stopped while it is being created, it never reaches the model and says it stopped", async () => {
+    const root = await makeTempRoot();
+    const parent = new AbortController();
+    const create = CodeAgent.create;
+    const spy = spyOn(CodeAgent, "create").mockImplementation(async (options) => {
+      const agent = await create.call(CodeAgent, options);
+      parent.abort();
+      return agent;
+    });
+    const notices: string[] = [];
+    try {
+      const calls = llmCalls;
+      expect(await runTask(root, parent, notices)).toBe("(no answer)");
+      expect(llmCalls).toBe(calls);
+      expect(notices.at(-1)).toBe("explore sub-agent stopped, 0 tokens (0 of 1000 spent)");
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  test("stopped after it exists but before its run is live, it is stopped as soon as the run starts", async () => {
+    const root = await makeTempRoot();
+    const parent = new AbortController();
+    const stopBeforeTheRun: InlineExtension = {
+      name: "stop-before-the-run",
+      factory: (pi: ExtensionAPI) => {
+        pi.on("before_agent_start", () => {
+          parent.abort();
+        });
+      },
+    };
+    const create = CodeAgent.create;
+    const spy = spyOn(CodeAgent, "create").mockImplementation(
+      async (options) => await create.call(CodeAgent, { ...options, extensions: [stopBeforeTheRun] }),
+    );
+    const notices: string[] = [];
+    try {
+      expect(await runTask(root, parent, notices)).toBe("(no answer)");
+      expect(notices.at(-1)).toMatch(/^explore sub-agent stopped, /);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});