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

package/codeAgent/agent/CodeAgentRpcListener.ts

@@ -0,0 +1,117 @@
+import { existsSync, rmSync } from "node:fs";
+import type { Socket, SocketListener } from "bun";
+import type { CodeAgentRpcHost } from "./CodeAgentRpcHost";
+
+export type CodeAgentRpcAddress = { unix: string } | { hostname: string; port: number };
+
+interface ClientState {
+  pending: Buffer | null;
+  decoder: TextDecoder;
+}
+
+/**
+ * `akan code --rpc-listen <unix:PATH | tcp:[HOST:]PORT>` — the RPC host on a socket instead of stdio, so the agent
+ * outlives the process driving it. A control plane that restarts reconnects and resumes with
+ * `get_state { sinceSeq }`; the turn it was watching kept running in the meantime.
+ *
+ * One client at a time: a new connection replaces the old one, which is what a reconnecting control plane whose
+ * previous socket has not timed out yet needs. TCP binds 127.0.0.1 unless a host is named, because the wire has
+ * no authentication of its own — reach a pod through its unix socket and whatever the orchestrator already
+ * authenticates.
+ */
+export class CodeAgentRpcListener {
+  readonly #host: CodeAgentRpcHost;
+  readonly #address: CodeAgentRpcAddress;
+  #listener: SocketListener<ClientState> | null = null;
+  #client: Socket<ClientState> | null = null;
+
+  constructor(host: CodeAgentRpcHost, address: CodeAgentRpcAddress) {
+    this.#host = host;
+    this.#address = address;
+  }
+
+  static parse(spec: string): CodeAgentRpcAddress {
+    if (spec.startsWith("unix:")) return { unix: spec.slice("unix:".length) };
+    const rest = spec.startsWith("tcp:") ? spec.slice("tcp:".length) : spec;
+    const separator = rest.lastIndexOf(":");
+    const hostname = separator >= 0 ? rest.slice(0, separator) : "127.0.0.1";
+    const port = Number(separator >= 0 ? rest.slice(separator + 1) : rest);
+    if (!Number.isInteger(port) || port < 0 || port > 65_535)
+      throw new Error(`--rpc-listen takes unix:<path> or tcp:[host:]<port>, not "${spec}"`);
+    return { hostname: hostname || "127.0.0.1", port };
+  }
+
+  get port() {
+    return this.#listener && "port" in this.#listener ? this.#listener.port : null;
+  }
+
+  listen() {
+    if ("unix" in this.#address && existsSync(this.#address.unix)) rmSync(this.#address.unix);
+    const socket = {
+      open: (client: Socket<ClientState>) => this.#open(client),
+      data: (client: Socket<ClientState>, data: Buffer) => this.#data(client, data),
+      drain: (client: Socket<ClientState>) => this.#drain(client),
+      close: (client: Socket<ClientState>) => this.#close(client),
+      error: (client: Socket<ClientState>) => this.#close(client),
+    };
+    this.#listener =
+      "unix" in this.#address
+        ? Bun.listen<ClientState>({ unix: this.#address.unix, socket })
+        : Bun.listen<ClientState>({ hostname: this.#address.hostname, port: this.#address.port, socket });
+    this.#host.start();
+    return this;
+  }
+
+  async serve() {
+    if (!this.#listener) this.listen();
+    await this.#host.shutdown;
+    this.stop();
+  }
+
+  stop() {
+    this.#client?.end();
+    this.#client = null;
+    this.#host.attach(null);
+    this.#listener?.stop(true);
+    this.#listener = null;
+    if ("unix" in this.#address && existsSync(this.#address.unix)) rmSync(this.#address.unix);
+  }
+
+  #open(client: Socket<ClientState>) {
+    client.data = { pending: null, decoder: new TextDecoder() };
+    const previous = this.#client;
+    this.#client = client;
+    previous?.end();
+    this.#host.attach((line) => this.#write(client, line));
+  }
+
+  #data(client: Socket<ClientState>, data: Buffer) {
+    if (client !== this.#client) return;
+    void this.#host.feed(client.data.decoder.decode(data, { stream: true }));
+  }
+
+  //* A socket write may take only part of a frame; the rest waits for `drain`, and frames behind it queue in order.
+  #write(client: Socket<ClientState>, line: string) {
+    if (client !== this.#client) return;
+    const bytes = Buffer.from(line);
+    if (client.data.pending) {
+      client.data.pending = Buffer.concat([client.data.pending, bytes]);
+      return;
+    }
+    const written = client.write(bytes);
+    if (written < bytes.length) client.data.pending = bytes.subarray(Math.max(0, written));
+  }
+
+  #drain(client: Socket<ClientState>) {
+    const pending = client.data.pending;
+    if (!pending) return;
+    const written = client.write(pending);
+    client.data.pending = written < pending.length ? pending.subarray(Math.max(0, written)) : null;
+  }
+
+  #close(client: Socket<ClientState>) {
+    if (client !== this.#client) return;
+    this.#client = null;
+    this.#host.attach(null);
+  }
+}

package/codeAgent/agent/CodeAgentSuspended.ts

@@ -0,0 +1,92 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import type { CodeAgentApprovalRequest, CodeAgentQuestion } from "akanjs/common";
+
+interface SuspendedState {
+  question?: CodeAgentQuestion;
+  approvals: CodeAgentApprovalRequest[];
+}
+
+/**
+ * What a suspending profile is waiting on after its turn ended — the question it asked and the approvals it
+ * parked. The turn is gone, so nothing in memory holds them; this does, and on a file-backed session it writes
+ * them beside the session so a worker that restarts and resumes still knows what it asked.
+ *
+ * Taking an ask removes it, which is what makes an answer idempotent: a second tab or a retried frame finds
+ * nothing to take and is refused instead of opening a second turn.
+ */
+export class CodeAgentSuspended {
+  readonly #file: string | null;
+  #state: SuspendedState;
+
+  constructor(file: string | null) {
+    this.#file = file;
+    this.#state = CodeAgentSuspended.#read(file);
+  }
+
+  static fileOf(sessionDir: string | undefined, sessionId: string) {
+    return sessionDir ? path.join(sessionDir, `${sessionId}.suspended.json`) : null;
+  }
+
+  get question() {
+    return this.#state.question;
+  }
+
+  get approvals(): readonly CodeAgentApprovalRequest[] {
+    return this.#state.approvals;
+  }
+
+  //* A new question replaces the old one: asking ends the turn, so the earlier question has nobody left to answer it.
+  setQuestion(question: CodeAgentQuestion) {
+    this.#state = { ...this.#state, question };
+    this.#save();
+  }
+
+  addApproval(request: CodeAgentApprovalRequest) {
+    this.#state = { ...this.#state, approvals: [...this.#state.approvals, request] };
+    this.#save();
+  }
+
+  takeQuestion(questionId: string) {
+    const question = this.#state.question;
+    if (question?.questionId !== questionId) return undefined;
+    this.#state = { approvals: this.#state.approvals };
+    this.#save();
+    return question;
+  }
+
+  takeApproval(approvalId: string) {
+    const request = this.#state.approvals.find((approval) => approval.approvalId === approvalId);
+    if (!request) return undefined;
+    this.#state = { ...this.#state, approvals: this.#state.approvals.filter((approval) => approval !== request) };
+    this.#save();
+    return request;
+  }
+
+  //* A prompt the user typed instead of answering moves the conversation on; the parked asks belong to a turn it replaced.
+  clear() {
+    if (!this.#state.question && !this.#state.approvals.length) return;
+    this.#state = { approvals: [] };
+    this.#save();
+  }
+
+  #save() {
+    if (!this.#file) return;
+    if (!this.#state.question && !this.#state.approvals.length) {
+      rmSync(this.#file, { force: true });
+      return;
+    }
+    mkdirSync(path.dirname(this.#file), { recursive: true });
+    writeFileSync(this.#file, `${JSON.stringify(this.#state)}\n`);
+  }
+
+  static #read(file: string | null): SuspendedState {
+    if (!file || !existsSync(file)) return { approvals: [] };
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf8")) as Partial<SuspendedState>;
+      return { ...(parsed.question ? { question: parsed.question } : {}), approvals: parsed.approvals ?? [] };
+    } catch {
+      return { approvals: [] };
+    }
+  }
+}

package/codeAgent/agent/akanCodeModel.ts

@@ -13,7 +13,7 @@ export interface CodeAgentModelRef {
 }
 
 /** 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-v4-flash" };
+export const akanCodeDefaultModel: CodeAgentModelRef = { provider: "deepseek", id: "deepseek-flash" };
 
 /**
  * Models the catalogue declares text-only that take a picture anyway.

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

@@ -22,7 +22,8 @@ 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));
+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 });

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/agent/codeAgentContract.test.ts

@@ -292,6 +292,23 @@ describe("CodeAgentEventMapper", () => {
     const frames = mapper.map({ type: "agent_end", messages: [{ stopReason: "aborted" }], willRetry: false } as never);
     expect(frames).toEqual([{ type: "turn_end", turnId: "t1", stopReason: "aborted" }]);
   });
+
+  test("a compaction that failed or was cancelled carries that, not just its reason", () => {
+    const mapper = new CodeAgentEventMapper();
+    const end = (fields: object) =>
+      mapper.map({
+        type: "compaction_end",
+        reason: "threshold",
+        result: undefined,
+        willRetry: false,
+        ...fields,
+      } as never);
+    expect(end({ aborted: false, errorMessage: "Auto-compaction failed: 529" })).toEqual([
+      { type: "compaction", phase: "end", reason: "threshold", error: "Auto-compaction failed: 529" },
+    ]);
+    expect(end({ aborted: true })).toEqual([{ type: "compaction", phase: "end", reason: "threshold", aborted: true }]);
+    expect(end({ aborted: false })).toEqual([{ type: "compaction", phase: "end", reason: "threshold" }]);
+  });
 });
 
 describe("CodeAgentStreamPrinter", () => {

package/codeAgent/agent/codeAgentProxy.test.ts

@@ -0,0 +1,74 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { AkanCodeServices } from "./AkanCodeServices";
+import { akanCodeDefaultModel, akanCodeModel } from "./akanCodeModel";
+import { CodeAgentProxy } from "./CodeAgentProxy";
+
+const seen: { path: string; auth: string | null }[] = [];
+let proxy: ReturnType<typeof Bun.serve>;
+let home = "";
+let realHome: string | undefined;
+let realKey: string | undefined;
+
+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`;
+
+beforeAll(() => {
+  home = mkdtempSync(path.join(tmpdir(), "akan-code-proxy-test-"));
+  realHome = process.env.AKAN_CODE_HOME;
+  realKey = process.env.DEEPSEEK_API_KEY;
+  process.env.AKAN_CODE_HOME = home;
+  process.env.DEEPSEEK_API_KEY = "real-provider-key-must-not-leave";
+  proxy = Bun.serve({
+    port: 0,
+    fetch: (req) => {
+      seen.push({ path: new URL(req.url).pathname, auth: req.headers.get("authorization") });
+      const body = `${chunk({ role: "assistant", content: "pong" })}${chunk({}, "stop")}data: [DONE]\n\n`;
+      return new Response(body, { headers: { "content-type": "text/event-stream" } });
+    },
+  });
+});
+
+afterAll(() => {
+  proxy.stop(true);
+  rmSync(home, { recursive: true, force: true });
+  if (realHome === undefined) delete process.env.AKAN_CODE_HOME;
+  else process.env.AKAN_CODE_HOME = realHome;
+  if (realKey === undefined) delete process.env.DEEPSEEK_API_KEY;
+  else process.env.DEEPSEEK_API_KEY = realKey;
+});
+
+describe("CodeAgentProxy", () => {
+  test("sends every request to the proxy with the token read from its file at that moment", async () => {
+    const tokenFile = path.join(home, "token");
+    writeFileSync(tokenFile, "session-token-1\n");
+    const codeProxy = new CodeAgentProxy({
+      baseUrl: `http://127.0.0.1:${proxy.port}/llm/{provider}/v1`,
+      providers: [akanCodeDefaultModel.provider],
+      tokenFile,
+    });
+    const runtime = await AkanCodeServices.runtime(home, codeProxy);
+    const model = await akanCodeModel(runtime);
+    expect(model?.provider).toBe("deepseek");
+    const context = { messages: [{ role: "user" as const, content: "ping", timestamp: Date.now() }] };
+    if (!model) throw new Error("no model");
+    const first = await runtime.completeSimple(model, context);
+    writeFileSync(tokenFile, "session-token-2\n");
+    await runtime.completeSimple(model, context);
+    expect(first.content).toEqual([expect.objectContaining({ type: "text", text: "pong" })]);
+    expect(seen.map((request) => request.auth)).toEqual(["Bearer session-token-1", "Bearer session-token-2"]);
+    expect(seen.every((request) => request.path.startsWith("/llm/deepseek/v1/"))).toBe(true);
+  });
+
+  test("refuses to start with a proxy URL and no token source", () => {
+    expect(() => new CodeAgentProxy({ baseUrl: "https://proxy", providers: ["deepseek"] })).toThrow("TOKEN");
+  });
+});

package/codeAgent/agent/codeAgentRpcListener.test.ts

@@ -0,0 +1,113 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import type { CodeAgentEvent } from "akanjs/common";
+import type { CodeAgent } from "./CodeAgent";
+import { CodeAgentRpcHost } from "./CodeAgentRpcHost";
+import { CodeAgentRpcListener } from "./CodeAgentRpcListener";
+
+const dir = mkdtempSync(path.join(tmpdir(), "akan-rpc-"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+class FakeAgent {
+  seq = 0;
+  frames: CodeAgentEvent[] = [];
+  disposed = false;
+  aborted = false;
+  #listener: (event: CodeAgentEvent) => void = () => {};
+  on(listener: (event: CodeAgentEvent) => void) {
+    this.#listener = listener;
+    return () => {};
+  }
+  announce() {
+    this.emit();
+  }
+  emit() {
+    const event = { type: "idle", seq: ++this.seq } as CodeAgentEvent;
+    this.frames.push(event);
+    this.#listener(event);
+  }
+  async prompt() {
+    this.emit();
+  }
+  async abort() {
+    this.aborted = true;
+  }
+  async state({ sinceSeq }: { sinceSeq?: number } = {}) {
+    return { replayFrom: 0, frames: this.frames.filter((event) => event.seq > (sinceSeq ?? Number.MAX_SAFE_INTEGER)) };
+  }
+  dispose() {
+    this.disposed = true;
+  }
+}
+
+class Client {
+  lines: unknown[] = [];
+  #buffer = "";
+  #socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
+  static async connect(unix: string) {
+    const client = new Client();
+    client.#socket = await Bun.connect({
+      unix,
+      socket: {
+        data: (_socket, data) => {
+          client.#buffer += data.toString();
+          const parts = client.#buffer.split("\n");
+          client.#buffer = parts.pop() ?? "";
+          for (const part of parts) if (part) client.lines.push(JSON.parse(part));
+        },
+      },
+    });
+    return client;
+  }
+  send(id: string, command: object) {
+    this.#socket?.write(`${JSON.stringify({ id, command })}\n`);
+  }
+  async reply(id: string) {
+    for (let idx = 0; idx < 200; idx++) {
+      const found = this.lines.find((line) => (line as { id?: string }).id === id);
+      if (found) return found as { ok: boolean; data: { frames?: CodeAgentEvent[] } };
+      await Bun.sleep(5);
+    }
+    throw new Error(`no reply ${id}`);
+  }
+  close() {
+    this.#socket?.end();
+  }
+}
+
+describe("CodeAgentRpcListener", () => {
+  test("parses unix and tcp addresses, defaulting tcp to loopback", () => {
+    expect(CodeAgentRpcListener.parse("unix:/tmp/a.sock")).toEqual({ unix: "/tmp/a.sock" });
+    expect(CodeAgentRpcListener.parse("tcp:7000")).toEqual({ hostname: "127.0.0.1", port: 7000 });
+    expect(CodeAgentRpcListener.parse("0.0.0.0:7000")).toEqual({ hostname: "0.0.0.0", port: 7000 });
+    expect(() => CodeAgentRpcListener.parse("tcp:nope")).toThrow("--rpc-listen");
+  });
+
+  test("the agent outlives a dropped client, and the next one catches up by seq", async () => {
+    const agent = new FakeAgent();
+    const unix = path.join(dir, "agent.sock");
+    const listener = new CodeAgentRpcListener(new CodeAgentRpcHost(agent as unknown as CodeAgent, null), { unix });
+    listener.listen();
+    const served = listener.serve();
+
+    const first = await Client.connect(unix);
+    first.send("1", { type: "prompt", message: "hi" });
+    expect((await first.reply("1")).ok).toBe(true);
+    first.close();
+    await Bun.sleep(20);
+    agent.emit();
+    expect(agent.aborted).toBe(false);
+
+    const second = await Client.connect(unix);
+    second.send("2", { type: "get_state", sinceSeq: 2 });
+    const state = await second.reply("2");
+    expect(state.data.frames?.map((frame) => frame.seq)).toEqual([3]);
+
+    second.send("3", { type: "shutdown" });
+    await second.reply("3");
+    await served;
+    expect(agent.disposed).toBe(true);
+  });
+});

package/codeAgent/agent/codeAgentSuspended.test.ts

@@ -0,0 +1,47 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { CodeAgentSuspended } from "./CodeAgentSuspended";
+
+const dir = mkdtempSync(path.join(tmpdir(), "akan-suspended-"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+const question = {
+  questionId: "qx.1",
+  prompt: "Which app?",
+  kind: "select" as const,
+  options: [{ key: "a", label: "akan" }],
+};
+const approval = {
+  approvalId: "ax.2",
+  toolCallId: "c1",
+  name: "write",
+  summary: "write a.ts",
+  policy: "writes" as const,
+};
+
+describe("CodeAgentSuspended", () => {
+  test("a restarted worker reads back what it was waiting on, and each ask is taken once", () => {
+    const file = CodeAgentSuspended.fileOf(dir, "s1");
+    const before = new CodeAgentSuspended(file);
+    before.setQuestion(question);
+    before.addApproval(approval);
+
+    const after = new CodeAgentSuspended(file);
+    expect(after.question).toEqual(question);
+    expect(after.approvals).toEqual([approval]);
+    expect(after.takeQuestion("qx.1")).toEqual(question);
+    expect(after.takeQuestion("qx.1")).toBeUndefined();
+    expect(after.takeApproval("ax.2")).toEqual(approval);
+    expect(after.takeApproval("ax.2")).toBeUndefined();
+    expect(existsSync(file ?? "")).toBe(false);
+  });
+
+  test("a memory session keeps its asks without touching disk", () => {
+    const memory = new CodeAgentSuspended(CodeAgentSuspended.fileOf(undefined, "s2"));
+    memory.setQuestion(question);
+    expect(memory.takeQuestion("other")).toBeUndefined();
+    expect(memory.takeQuestion("qx.1")).toEqual(question);
+  });
+});

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`.