@akanjs/devkit 3.0.0-beta.16 → 3.0.0-beta.18

package/codeAgent/agent/SubagentPool.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
-import { type CodeAgentProfile, codeAgentReadOnlyBuiltins } from "akanjs/common";
+import { type CodeAgentProfile, type CodeAgentSubagent, codeAgentReadOnlyBuiltins } from "akanjs/common";
 import { Type } from "typebox";
 import type { Workspace } from "../../commandDecorators";
 
@@ -10,10 +10,21 @@ export interface SubagentPoolOptions {
   depth: number;
   /** Progress and refusals reach the parent's host through this rather than through a new event kind. */
   onNotice?: (message: string) => void;
+  /** The running children, whole, for a host that draws them as a rail beside the prompt. */
+  onAgents?: (agents: CodeAgentSubagent[]) => void;
 }
 
 const maxResultChars = 8_000;
 
+/**
+ * How often the running children are re-reported while none of them starts or finishes.
+ *
+ * A child spends tokens for minutes between the two frames its lifetime would otherwise produce, and the
+ * number that decides whether to let it keep going is the one climbing in between. One frame a second for at
+ * most a handful of rows is far below what a single streaming turn already puts on the wire.
+ */
+const tickMs = 1_000;
+
 export type SubagentKind = keyof typeof SubagentPool.kinds;
 
 /**
@@ -47,8 +58,14 @@ export class SubagentPool {
   static readonly defaultKind: SubagentKind = "explore";
 
   readonly #options: SubagentPoolOptions;
+  /** Keyed by the `task` call that opened each child. `agent` lands once it exists, and reports live tokens. */
+  readonly #children = new Map<
+    string,
+    { kind: SubagentKind; description: string; startedAt: number; agent?: { tokensUsed: number } }
+  >();
   #running = 0;
   #spent = 0;
+  #ticker: ReturnType<typeof setInterval> | null = null;
 
   constructor(options: SubagentPoolOptions) {
     this.#options = options;
@@ -82,19 +99,23 @@ export class SubagentPool {
           ),
         ),
       }),
-      execute: async (_id, params, signal) => {
+      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.#running += 1;
+        this.#children.set(id, { kind, description: params.description, startedAt: Date.now() });
+        this.#report();
         // Said before it starts, not only when it ends: a turn that goes quiet for a minute while a child
         // reads the repo is otherwise indistinguishable from a turn that has stopped responding.
         this.#options.onNotice?.(`${kind} sub-agent · ${params.description}`);
         try {
-          const text = await this.#run(kind, params.prompt, signal);
+          const text = await this.#run(id, kind, params.prompt, signal);
           return { content: [{ type: "text", text }], details: undefined };
         } finally {
           this.#running -= 1;
+          this.#children.delete(id);
+          this.#report();
         }
       },
     });
@@ -137,7 +158,35 @@ export class SubagentPool {
     };
   }
 
-  async #run(kind: SubagentKind, prompt: string, signal: AbortSignal | undefined) {
+  /**
+   * The running children as a list, and the ticker that keeps it moving.
+   *
+   * The ticker is owned by the report rather than by the tool call: two children overlapping must not each
+   * start one, and the last one to finish is what stops it. It is unref'd because a pool with a child still
+   * registered is a bug that should end the process, not hold it 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);
@@ -148,6 +197,8 @@ export class SubagentPool {
       apps: [],
       depth: this.#options.depth + 1,
     });
+    const running = this.#children.get(id);
+    if (running) running.agent = agent;
     const abort = () => void agent.abort();
     signal?.addEventListener("abort", abort, { once: true });
     try {

package/codeAgent/agent/akanCodeModel.ts

@@ -1,11 +1,11 @@
-import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 
 /**
  * The engine's `Model` type lives in `@earendil-works/pi-ai` and is not re-exported from the package we depend
  * on, so it is recovered from the one public function that returns it rather than by adding a dependency on a
  * transitive package whose version we do not control.
  */
-export type CodeAgentModel = NonNullable<ReturnType<ModelRegistry["find"]>>;
+export type CodeAgentModel = NonNullable<ReturnType<ModelRuntime["getModel"]>>;
 
 export interface CodeAgentModelRef {
   provider: string;
@@ -42,17 +42,17 @@ const correctInputs = (model: CodeAgentModel | undefined) => {
  * An empty API key produces a request that succeeds with no content rather than an error, so a provider with no
  * configured auth is skipped here instead of answering with nothing three seconds later.
  */
-export const akanCodeModel = async (registry: ModelRegistry, ref?: CodeAgentModelRef) => {
+export const akanCodeModel = async (runtime: ModelRuntime, ref?: CodeAgentModelRef) => {
   if (ref) {
-    const requested = registry.find(ref.provider, ref.id);
+    const requested = runtime.getModel(ref.provider, ref.id);
     if (!requested) throw new Error(`Unknown model: ${ref.provider}/${ref.id}`);
-    if (!registry.hasConfiguredAuth(requested))
+    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 = registry.find(akanCodeDefaultModel.provider, akanCodeDefaultModel.id);
-  if (fallback && registry.hasConfiguredAuth(fallback)) return correctInputs(fallback);
-  return correctInputs(registry.getAvailable()[0]);
+  const fallback = runtime.getModel(akanCodeDefaultModel.provider, akanCodeDefaultModel.id);
+  if (fallback && runtime.hasConfiguredAuth(fallback.provider)) return correctInputs(fallback);
+  return correctInputs((await runtime.getAvailable())[0]);
 };
 
 /** A screenshot is worth attaching only to a model that can see it — after the catalogue has been corrected. */

package/codeAgent/agent/akanCodePaths.ts

@@ -12,6 +12,15 @@ const builtinSkillsDir = () => {
   return candidates.find((candidate) => existsSync(candidate));
 };
 
+/**
+ * Where `akan code` keeps what belongs to the person rather than to the repo.
+ *
+ * `AKAN_CODE_HOME` moves the whole set. A container that mounts no home directory, a CI job that must not
+ * write to one, and a second checkout that wants its own credentials all need the same thing, and moving the
+ * files apart would let a `models.json` and the `auth.json` it names drift into different directories.
+ */
+const globalDir = () => process.env.AKAN_CODE_HOME ?? path.join(homedir(), ".akan", "code");
+
 /**
  * Sessions live in the workspace — they are project history, and a second checkout of the same repo is a
  * different project. Credentials live in the home directory instead: a repo directory is the one place a key
@@ -25,7 +34,18 @@ export const akanCodePaths = {
   mailDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "mail"),
   builtinSkillsDir,
   mcpFile: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "mcp.json"),
-  globalDir: () => path.join(homedir(), ".akan", "code"),
-  authFile: () => path.join(homedir(), ".akan", "code", "auth.json"),
-  modelsFile: () => path.join(homedir(), ".akan", "code", "models.json"),
+  /**
+   * The MCP servers that belong to the person rather than to one checkout.
+   *
+   * A server is an integration with an account — the credential for it is already global, in `mcpAuth.json` —
+   * so declaring it per repo means declaring it again in every repo and signing in again in each. The
+   * workspace file stays, for a server that is genuinely this repo's, and 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,115 @@
+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;
+};
+
+/** What the engine hands over: the one context file it took for that directory. */
+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));
+
+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");
+  });
+
+  /** Cursor's other three kinds are conditional; applying one always is applying a rule its author scoped. */
+  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

@@ -14,6 +14,7 @@ export const akanSystemPrompt = (profile: CodeAgentProfile) => {
     "- 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"))
@@ -28,6 +29,10 @@ export const akanSystemPrompt = (profile: CodeAgentProfile) => {
     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.`,

package/codeAgent/index.ts

@@ -8,7 +8,6 @@
  * `globalThis.console`, and it has to be the first import of an RPC entry rather than a re-export of this one.
  */
 
-export * from "./agent/AkanAuthStorageBackend";
 export * from "./agent/AkanCodeServices";
 export * from "./agent/akanCodeModel";
 export * from "./agent/akanCodePaths";

package/codeAgent/skills/akan-code/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: akan-code
+description: "Answer a question about `akan code` itself — how to add or remove an MCP server, sign one in, switch model, fork or resume a session, what the slash commands and keys are, and where its files live. Read this before telling anyone how to use this tool."
+---
+
+# akan code — the manual
+
+This is the tool the user is talking to right now. When they ask how to do something *with it* — rather than
+with their code — answer from here, and quote the exact gesture: the slash command to type, or the file to
+edit. Do not guess a command; everything this tool offers is listed below.
+
+You cannot type a slash command yourself. They are the host's, not yours — say which one to type. You *can*
+edit the files named below, which is the useful half of most of these answers: write the change, then say
+which command makes it take effect.
+
+## MCP servers
+
+Declared in **`.akan/code/mcp.json`**, in the same `mcpServers` shape Claude, Cursor and VS Code already
+write, so a block can be pasted across rather than translated. VS Code's `servers` spelling is read too, and
+whichever key the file already uses is the one a write goes back into.
+
+```jsonc
+{
+  "mcpServers": {
+    "github":   { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
+    "linear":   { "url": "https://mcp.linear.app/sse" },
+    "internal": { "url": "https://…/mcp", "headers": { "x-api-key": "…" } },
+    "old":      { "command": "x", "disabled": true }
+  }
+}
+```
+
+A `url` is an http server; anything else is a command with its argv. `env` passes variables to a stdio
+server, `headers` goes on every http request (a server behind a static token needs nothing else), and
+`disabled: true` keeps an entry without connecting it.
+
+From the prompt:
+
+```
+/mcp                      what is declared, what connected, and how many tools each gave
+/mcp <name>               the tools that one server published
+/mcp add <name> <command> [args…]
+/mcp add <name> <https://…>
+/mcp remove <name>
+/mcp login <name>         OAuth, in the browser
+/mcp logout <name>        forget the token, leaving the server declared
+/mcp reload               reopen this session so the file takes effect
+```
+
+**A server added now is not reachable until the session reloads.** The tool allowlist is fixed when the
+session is created, so `add`, `remove`, `login` and `logout` all reload by themselves — a session that has
+said nothing yet has nothing on disk to reopen, and says so. If you edit `mcp.json` yourself, tell the user to
+run `/mcp reload`.
+
+Sign-in is discovered, not configured: the server's `401` names its resource metadata, that names the
+authorization server, and most hosted servers register a client on demand — so a url is usually the whole
+entry. For a provider that issues client ids by hand, add `"oauth": { "clientId": "…", "scope": "…" }`.
+Tokens are stored per server in `~/.akan/code/mcpAuth.json` at mode 0600, never in the repo, and refreshed
+silently; `/mcp` shows `sign-in needed` when a server wants one.
+
+## Sessions
+
+Stored under `.akan/code/sessions` — project history, so a second checkout of the same repo has its own.
+
+- `←` at the start of the prompt lists past sessions; enter reopens the chosen one.
+- `akan code --resume <id>` (`-R`) reopens one from the shell.
+- `/fork [name]` continues the conversation twice: the copy takes over here, and the notice names the command
+  that reopens the original.
+- `/name <text>` names this one, which is what the session list is read by.
+- `/peers` lists other `akan code` sessions running in this workspace; `/msg <peer> <text>` hands one a
+  message.
+- `/clear` wipes the screen and keeps the conversation; `/compact [notes]` shortens what the model carries.
+
+## Model, effort, keys
+
+- `/model <provider>/<id>`, e.g. `/model deepseek/deepseek-v4-pro`. `/effort <level>` for how hard it thinks.
+- A provider is authorized by **`<PROVIDER>_API_KEY`** — `DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY`. The
+  workspace's own `.env` is read as well as the environment, and a key found there is used for the run and
+  never copied anywhere.
+- Credentials and the model catalogue live in `~/.akan/code/` (`auth.json`, `models.json`). **`AKAN_CODE_HOME`
+  moves the whole directory** — for a container with no home, or a checkout that wants its own.
+
+## What the agent reads, and how to change it
+
+- Every `AGENTS.md` / `CLAUDE.md` from the workspace root down to the working directory, `.cursorrules`, and
+  any `.cursor/rules/*.mdc` that applies unconditionally (`alwaysApply: true`, or no frontmatter at all).
+  Edit those to change how this agent behaves in this repo — they are the files the editor beside it reads.
+- Skills: drop a `<name>/SKILL.md` into `.akan/code/skills`. Extensions: `.akan/code/extensions`. Neither is
+  read from a home directory, so a session behaves the same in two checkouts.
+
+## Keys
+
+```
+enter send · shift+enter newline · ↑↓ move (history at the edges) · ←→ move
+esc interrupt · pgup/pgdn scroll · ^c quit · tab completes a slash command
+@ completes a file in this repo · wheel scrolls the transcript (hold shift to select text instead)
+cmd+v attaches an image from the clipboard · ^v does too, without the terminal in the way
+```
+
+Most terminals send the same byte for enter and shift+enter, so the key only arrives where the terminal can
+say which was pressed. In VS Code, bind it with `workbench.action.terminal.sendSequence` and a `text` of
+`"\\\u001b\r"`; iTerm2 calls the same thing "Send Text". Either spelling of that sequence works here, and
+the backslash a shell would read as a line continuation never reaches the prompt.
+
+## Starting it
+
+```
+akan code                       open the session
+akan code "<prompt>"            run one turn and print the answer
+akan code -i "<prompt>"         open the session with the prompt already sent
+--app <name>                    narrow the agent to one app
+--profile local|pod|review|web  what it may do (default local)
+--model <provider>/<id>         --thinking, --json, --rpc, --resume <id>
+```
+
+`review` reads and never writes, loads no project context files, and keeps no session on disk. `pod` has
+nobody in front of it: it cannot ask a question. MCP is off in both.
+
+## The rest of the commands
+
+`/help` prints all of this list · `/tools` what this session can call · `/agents` what a sub-agent may be and
+what one may spend · `/thinking` shows or folds the reasoning · `/abort` stops the running turn · `/quit`.

package/codeAgent/skills/akan-module/SKILL.md

@@ -41,5 +41,5 @@ module. Collection-level helpers go `static` on the full model.
 - Read the module's `<module>.abstract.md` before changing it, and update it when an invariant or workflow
   changes — not for formatting.
 
-Deeper detail per layer is a `get_guideline` call away: `moduleOverview`, `moduleCodegen`, `modelConstant`,
-`modelDocument`, `modelService`, `modelSignal`, `modelStore`, `modelDictionary`.
+Deeper detail per layer is a `get_guideline` call away: `moduleOverview`, `modelConstant`, `modelDocument`,
+`modelService`, `modelSignal`, `modelStore`, `modelDictionary`.

package/codeAgent/skills/akan-store/SKILL.md

@@ -37,14 +37,18 @@ Only what the generated set does not cover: extra client state, a multi-step or
 calls to the non-CRUD endpoints you added in the signal. Each is an `async` method using `this.set(...)` /
 `this.get()` / `this.pick(...)`.
 
+To reach another store, cast `this`: `import type { RootStore } from "../st"`, then
+`(this as unknown as RootStore).logout()` to call its action or `(this as unknown as RootStore).set({ … })` /
+`.get()` to write or read its state. Every store is mixed into one root at runtime, so the cast only tells the
+type what `this` already is. Keep it `import type` — `st.ts` imports every store, so a value import is a cycle.
+
 A store that needs none of this stays empty. `store(sig.comment, () => ({}))` with an empty body is the
 correct, complete result — an empty store is not an unfinished one.
 
-## Two rules the linter enforces
+## The rule the linter enforces
 
 - **An action returns nothing.** Every method dispatches through `st.do.<action>()` and is typed `void`, so a
   returned value is unreachable. Write it into state with `this.set({ … })`.
-- **Never `import type { RootStore } from "../st"`** — it crashes `akan build` with a Bun SSR segfault.
 
 ## From UI
 

package/codeAgent/tools/AkanCodePlugins.ts

@@ -1,5 +1,5 @@
 import type { InlineExtension } from "@earendil-works/pi-coding-agent";
-import type { CodeAgentProfile } from "akanjs/common";
+import type { CodeAgentMcpStatus, CodeAgentProfile, CodeAgentQuestion, CodeAgentSubagent } from "akanjs/common";
 import type { Workspace } from "../../commandDecorators";
 import type { CodeMailbox } from "../agent/CodeMailbox";
 import { SubagentPool } from "../agent/SubagentPool";
@@ -9,6 +9,7 @@ import { PreviewView } from "../feedback/PreviewView";
 import { TurnFeedback, type TurnFeedbackSource } from "../feedback/TurnFeedback";
 import { VerifyFeedback } from "../feedback/VerifyFeedback";
 import { AkanToolPack } from "./AkanToolPack";
+import { AskToolPack } from "./AskToolPack";
 import { MailToolPack } from "./MailToolPack";
 import { McpToolPack } from "./McpToolPack";
 import { SessionToolPack } from "./SessionToolPack";
@@ -28,6 +29,9 @@ export interface AkanCodePluginsOptions {
   /** Late, because the session this announces to its peers does not exist yet when the pack is built. */
   mailbox: () => CodeMailbox | undefined;
   onNotice?: (message: string) => void;
+  onAgents?: (agents: CodeAgentSubagent[]) => void;
+  /** How `ask_user` reaches the person. Absent on a host that has nobody to reach. */
+  onAsk?: (question: Omit<CodeAgentQuestion, "questionId">) => Promise<string | undefined>;
 }
 
 /**
@@ -40,6 +44,8 @@ export interface AkanCodePluginsResult {
   extensions: InlineExtension[];
   /** Names the session's tool allowlist has to carry, or the model is told these tools do not exist. */
   toolNames: string[];
+  /** Every declared MCP server and what it published, including the ones that published nothing. */
+  mcp: CodeAgentMcpStatus[];
   /** Closes anything the pack holds open — currently the MCP server connections. */
   dispose: () => void;
 }
@@ -52,6 +58,7 @@ export class AkanCodePlugins {
       ...(options.onNotice ? { onNotice: options.onNotice } : {}),
     });
     const dispose = () => mcp?.close();
+    const mcpStatus = mcp?.status ?? [];
     const web = new WebToolPack({ profile: options.profile });
     const webExtension = web.extension();
     const sessions = new SessionToolPack({
@@ -63,10 +70,22 @@ export class AkanCodePlugins {
     const sessionExtension = sessions.extension();
     const mail = new MailToolPack({ profile: options.profile, mailbox: options.mailbox });
     const mailExtension = mail.extension();
+    const onAsk = options.onAsk;
+    const ask = onAsk ? new AskToolPack({ profile: options.profile, ask: onAsk }) : undefined;
+    const askExtension = ask?.extension();
     if (!options.profile.tools.akan)
       return {
-        extensions: [mcp?.extension(), webExtension, sessionExtension, mailExtension].filter((entry) => !!entry),
-        toolNames: [...(mcp?.toolNames ?? []), ...web.names(), ...sessions.names(), ...mail.names()],
+        extensions: [mcp?.extension(), webExtension, sessionExtension, mailExtension, askExtension].filter(
+          (entry) => !!entry,
+        ),
+        toolNames: [
+          ...(mcp?.toolNames ?? []),
+          ...web.names(),
+          ...sessions.names(),
+          ...mail.names(),
+          ...(ask?.names() ?? []),
+        ],
+        mcp: mcpStatus,
         dispose,
       };
     const readOnly = !options.profile.tools.builtin.includes("write");
@@ -82,6 +101,7 @@ export class AkanCodePlugins {
       parent: options.profile,
       depth: options.depth,
       ...(options.onNotice ? { onNotice: options.onNotice } : {}),
+      ...(options.onAgents ? { onAgents: options.onAgents } : {}),
     });
     if (subagent) extensions.push(subagent);
     const sources = await AkanCodePlugins.#sources(options, readOnly);
@@ -96,6 +116,7 @@ export class AkanCodePlugins {
     if (webExtension) extensions.push(webExtension);
     if (sessionExtension) extensions.push(sessionExtension);
     if (mailExtension) extensions.push(mailExtension);
+    if (askExtension) extensions.push(askExtension);
     return {
       extensions,
       toolNames: [
@@ -105,7 +126,9 @@ export class AkanCodePlugins {
         ...web.names(),
         ...sessions.names(),
         ...mail.names(),
+        ...(ask?.names() ?? []),
       ],
+      mcp: mcpStatus,
       dispose,
     };
   }

package/codeAgent/tools/AkanEnvKeys.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
-import type { AuthStorage } from "@earendil-works/pi-coding-agent";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 
 /**
  * Loads provider keys from the workspace's `.env` into the session, without persisting them anywhere.
@@ -12,12 +12,14 @@ import type { AuthStorage } from "@earendil-works/pi-coding-agent";
  * asked for.
  */
 export class AkanEnvKeys {
-  static apply(authStorage: AuthStorage, workspaceRoot: string) {
+  static async apply(runtime: ModelRuntime, workspaceRoot: string) {
     const applied: string[] = [];
     for (const [name, value] of AkanEnvKeys.#entries(workspaceRoot)) {
       const provider = AkanEnvKeys.#providerOf(name);
       if (!provider || !value) continue;
-      authStorage.setRuntimeApiKey(provider, value);
+      // Serially, not through `Promise.all`: the runtime queues credential operations against the same file,
+      // and a key written while another is mid-write is the one that goes missing.
+      await runtime.setRuntimeApiKey(provider, value);
       applied.push(provider);
     }
     return applied;