@akanjs/devkit 3.0.0-beta.14 → 3.0.0-beta.15

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

@@ -0,0 +1,44 @@
+---
+name: akan-validate
+description: "Run the akan check loop after editing and fix each failure class the right way — no silencing, no lint-disable, no gaming the checker."
+---
+
+# Akan validation loop
+
+## One call does the whole chain
+
+`akan_verify` runs sync → lint → typecheck → `quality ssr` over everything the working tree has changed, in
+the right order, and reports only what failed. **Call it after editing, before you say you are done.** It
+also runs itself at the end of a turn that changed source, so a failure comes back to you either way.
+
+The same chain by hand, for the app you are editing:
+
+- `akan sync <app>` — after adding, renaming, or deleting any file. Regenerates the barrels.
+- `akan lint <app>` — fast; run after every edit. Prints up to 200 diagnostics.
+- `akan typecheck <app>` — the client/server boundary violations land here, not in lint.
+- `akan quality ssr` — only when you wrote or changed a `.tsx`. Did the server share hold?
+- `akan build <app>` — the full production build; slower, and only when the build itself is in question.
+
+Raw `tsc` misses the generated barrels and reports false errors. Do not reach for it.
+
+## Fixing rules
+
+**Apply the real fix the rule intends. Do not silence the checker.** No blanket lint-disable, no throwaway
+re-export, no export-in-place trick, no `as any`, no non-null assertion. Gaming a check is a defect, not a
+fix. When a suppression is genuinely right it carries a reason:
+`// biome-ignore lint/<rule>: <why>` — and a grit plugin diagnostic is suppressed as `lint/plugin`, not the
+bare `plugin` category Biome's own message suggests.
+
+Common classes and their real fix:
+
+| symptom | fix |
+| --- | --- |
+| a member "already exists" or conflicts with the base class | you redeclared something Akan generates, usually store CRUD. **Delete your version** and call the generated one — do not rename, cast, or suppress. See `akan-store`. |
+| `throw new Error` | a typed `Err` with a dictionary key. See `akan-err`. |
+| an edit to a generated file | regenerate instead: `akan sync <app>` or `repair_generated`. |
+| a file in the wrong place | relocate to `common/` / `webkit/` / `srvkit/` / `ui/`. Never a sibling helper `.ts` inside `lib/<model>/`. |
+| a missing dependency | declare it in the owning app or lib `package.json`. See `akan-deps`. |
+| a Tailwind class order or colour complaint | let the formatter sort; use semantic tokens. See `akan-ui`. |
+
+Re-run until clean. If a failure is genuinely outside the scope of what you changed, say so in your reply
+instead of forcing it.

package/codeAgent/tools/AkanCli.ts

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { stripAnsi } from "../../stripAnsi";
+
+export interface AkanCliResult {
+  command: string;
+  ok: boolean;
+  exitCode: number;
+  output: string;
+}
+
+/**
+ * Runs `akan` as a child process and captures what it printed.
+ *
+ * The runners behind these commands write straight to an inherited stdio and return nothing, so there is no
+ * in-process call that yields text to hand back to a model. A subprocess also isolates a crash in a build or a
+ * typechecker from the agent's own turn.
+ */
+export class AkanCli {
+  readonly #cwd: string;
+  readonly #entry: string;
+
+  constructor(cwd: string) {
+    this.#cwd = cwd;
+    this.#entry = AkanCli.#resolveEntry();
+  }
+
+  async run(args: string[], { timeoutMs = 300_000 }: { timeoutMs?: number } = {}): Promise<AkanCliResult> {
+    const proc = Bun.spawn([process.execPath, this.#entry, ...args], {
+      cwd: this.#cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" },
+    });
+    const timer = setTimeout(() => proc.kill(), timeoutMs);
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    clearTimeout(timer);
+    // `NO_COLOR` reaches akan's own output but not every tool it shells out to — tsgo colours regardless, and
+    // escape sequences in a tool result are tokens the model pays for and cannot read.
+    const output = stripAnsi(`${stdout}${stderr}`).trim();
+    return { command: `akan ${args.join(" ")}`, ok: exitCode === 0, exitCode, output };
+  }
+
+  /**
+   * Bundling rewrites `import.meta.dir` to the output directory, where devkit is inlined into the CLI and the
+   * entry is `index.js` beside this module; from source the entry belongs to the neighbouring package and is
+   * still TypeScript. `Bun.main` is the last resort and is only right when the CLI is the process — an SDK
+   * embedder's main is its own. The path is written out rather than resolved through the package name because
+   * devkit does not depend on the CLI, and must not start.
+   */
+  static #resolveEntry() {
+    const candidates = [
+      path.join(import.meta.dir, "index.js"),
+      path.join(import.meta.dir, "..", "..", "..", "cli", "index.ts"),
+    ];
+    return candidates.find((candidate) => existsSync(candidate)) ?? Bun.main;
+  }
+}

package/codeAgent/tools/AkanCodePlugins.ts

@@ -0,0 +1,135 @@
+import type { InlineExtension } from "@earendil-works/pi-coding-agent";
+import type { CodeAgentProfile } from "akanjs/common";
+import type { Workspace } from "../../commandDecorators";
+import type { CodeMailbox } from "../agent/CodeMailbox";
+import { SubagentPool } from "../agent/SubagentPool";
+import { DevLogFeedback } from "../feedback/DevLogFeedback";
+import { PreviewFeedback } from "../feedback/PreviewFeedback";
+import { PreviewView } from "../feedback/PreviewView";
+import { TurnFeedback, type TurnFeedbackSource } from "../feedback/TurnFeedback";
+import { VerifyFeedback } from "../feedback/VerifyFeedback";
+import { AkanToolPack } from "./AkanToolPack";
+import { MailToolPack } from "./MailToolPack";
+import { McpToolPack } from "./McpToolPack";
+import { SessionToolPack } from "./SessionToolPack";
+import { WebToolPack } from "./WebToolPack";
+
+export interface AkanCodePluginsOptions {
+  workspace: Workspace;
+  cwd: string;
+  profile: CodeAgentProfile;
+  /** Apps whose dev server should be watched, and whose page should be probed. */
+  apps: string[];
+  canSeeImages: boolean;
+  /** How many `task` levels deep the owning agent is. */
+  depth: number;
+  /** Reading the current session back would spend its own window twice, so it is excluded from search. */
+  currentSessionId: () => string;
+  /** 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;
+}
+
+/**
+ * Assembles the akan capability pack for one profile.
+ *
+ * Gating happens here rather than at run time: a capability the profile excludes is never constructed, so the
+ * model cannot call it and it costs nothing in the system prompt either.
+ */
+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[];
+  /** Closes anything the pack holds open — currently the MCP server connections. */
+  dispose: () => void;
+}
+
+export class AkanCodePlugins {
+  static async build(options: AkanCodePluginsOptions): Promise<AkanCodePluginsResult> {
+    const mcp = await McpToolPack.connect({
+      workspaceRoot: options.workspace.workspaceRoot,
+      profile: options.profile,
+      ...(options.onNotice ? { onNotice: options.onNotice } : {}),
+    });
+    const dispose = () => mcp?.close();
+    const web = new WebToolPack({ profile: options.profile });
+    const webExtension = web.extension();
+    const sessions = new SessionToolPack({
+      workspaceRoot: options.workspace.workspaceRoot,
+      cwd: options.cwd,
+      profile: options.profile,
+      currentSessionId: options.currentSessionId,
+    });
+    const sessionExtension = sessions.extension();
+    const mail = new MailToolPack({ profile: options.profile, mailbox: options.mailbox });
+    const mailExtension = mail.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()],
+        dispose,
+      };
+    const readOnly = !options.profile.tools.builtin.includes("write");
+    const pack = new AkanToolPack({
+      workspace: options.workspace,
+      cwd: options.cwd,
+      mode: readOnly ? "readonly" : "apply",
+    });
+    const extensions: InlineExtension[] = [pack.extension()];
+    const subagent = SubagentPool.extensionFor({
+      workspace: options.workspace,
+      cwd: options.cwd,
+      parent: options.profile,
+      depth: options.depth,
+      ...(options.onNotice ? { onNotice: options.onNotice } : {}),
+    });
+    if (subagent) extensions.push(subagent);
+    const sources = await AkanCodePlugins.#sources(options, readOnly);
+    if (sources.length)
+      extensions.push(
+        new TurnFeedback(sources, {
+          budget: options.profile.limits.feedback,
+          ...(options.onNotice ? { onNotice: options.onNotice } : {}),
+        }).extension(),
+      );
+    if (mcp) extensions.push(mcp.extension());
+    if (webExtension) extensions.push(webExtension);
+    if (sessionExtension) extensions.push(sessionExtension);
+    if (mailExtension) extensions.push(mailExtension);
+    return {
+      extensions,
+      toolNames: [
+        ...(await pack.names()),
+        ...(subagent ? [SubagentPool.toolName] : []),
+        ...(mcp?.toolNames ?? []),
+        ...web.names(),
+        ...sessions.names(),
+        ...mail.names(),
+      ],
+      dispose,
+    };
+  }
+
+  static async #sources(options: AkanCodePluginsOptions, readOnly: boolean): Promise<TurnFeedbackSource[]> {
+    const sources: TurnFeedbackSource[] = [
+      new VerifyFeedback({ cwd: options.cwd, readOnly }),
+      new DevLogFeedback({ workspaceRoot: options.workspace.workspaceRoot, cwd: options.cwd, apps: options.apps }),
+    ];
+    const previewUrl = await AkanCodePlugins.#previewUrl(options);
+    if (!previewUrl) return sources;
+    // A dev server is up and the agent still cannot look at the page. Said once, at assembly, because the
+    // alternative is a UI turn that quietly skips its only visual check and reads as a clean run.
+    const reason = PreviewView.unavailableReason();
+    if (reason) options.onNotice?.(reason);
+    else sources.push(new PreviewFeedback({ cwd: options.cwd, previewUrl, canSeeImages: options.canSeeImages }));
+    return sources;
+  }
+
+  static async #previewUrl(options: AkanCodePluginsOptions) {
+    for (const app of options.apps) {
+      const url = await DevLogFeedback.previewUrl(options.workspace.workspaceRoot, app);
+      if (url) return url;
+    }
+    return undefined;
+  }
+}

package/codeAgent/tools/AkanEditScope.ts

@@ -0,0 +1,58 @@
+export interface AkanEditScopeResult {
+  paths: string[];
+  apps: string[];
+  libs: string[];
+  /** A created, deleted or renamed file under `apps/**` or `libs/**` — the only kind a barrel has to catch up with. */
+  needsSync: boolean;
+  touchesTsx: boolean;
+}
+
+const empty: AkanEditScopeResult = { paths: [], apps: [], libs: [], needsSync: false, touchesTsx: false };
+
+/**
+ * What the working tree says changed, and which akan targets that implicates.
+ *
+ * Read from git rather than from tool events on purpose: a model that edits through `bash` — a heredoc, `sed`,
+ * a codemod — produces no write tool call at all, and a verification gate that trusts tool events would wave
+ * exactly those turns through.
+ */
+export class AkanEditScope {
+  static async since(cwd: string, baseline: ReadonlySet<string>): Promise<AkanEditScopeResult> {
+    const current = await AkanEditScope.#status(cwd);
+    const changed = [...current].filter((line) => !baseline.has(line));
+    if (!changed.length) return empty;
+    const entries = changed.map((line) => ({ code: line.slice(0, 2), file: line.slice(3).split(" -> ").at(-1) ?? "" }));
+    const paths = entries.map((entry) => entry.file).filter(Boolean);
+    return {
+      paths,
+      apps: AkanEditScope.#targets(paths, "apps"),
+      libs: AkanEditScope.#targets(paths, "libs"),
+      needsSync: entries.some((entry) => /[ARD?]/.test(entry.code) && /^(apps|libs)\//.test(entry.file)),
+      touchesTsx: paths.some((file) => file.endsWith(".tsx")),
+    };
+  }
+
+  /** The porcelain lines before a turn, so the turn is judged on what it changed rather than on a dirty tree. */
+  static async baseline(cwd: string) {
+    return await AkanEditScope.#status(cwd);
+  }
+
+  static async #status(cwd: string) {
+    const proc = Bun.spawn(["git", "status", "--porcelain=v1", "--untracked-files=all"], {
+      cwd,
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const text = await new Response(proc.stdout).text();
+    await proc.exited;
+    return new Set(text.split("\n").filter((line) => line.trim().length > 3));
+  }
+
+  static #targets(paths: string[], root: "apps" | "libs") {
+    const names = paths
+      .filter((file) => file.startsWith(`${root}/`))
+      .map((file) => file.split("/")[1] ?? "")
+      .filter(Boolean);
+    return [...new Set(names)];
+  }
+}

package/codeAgent/tools/AkanEnvKeys.ts

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import type { AuthStorage } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Loads provider keys from the workspace's `.env` into the session, without persisting them anywhere.
+ *
+ * Bun auto-loads `.env` from the **current directory**, so `akan code` run from a subdirectory — or embedded in
+ * a process started elsewhere — sees none of the workspace's keys and fails with "No API key found" for a key
+ * that is plainly there. They are applied as runtime overrides rather than stored credentials: the key belongs
+ * to the repo's env file, and copying it into `~/.akan/code/auth.json` would give it a second lifetime nobody
+ * asked for.
+ */
+export class AkanEnvKeys {
+  static apply(authStorage: AuthStorage, 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);
+      applied.push(provider);
+    }
+    return applied;
+  }
+
+  static #entries(workspaceRoot: string): [string, string][] {
+    const fromProcess = Object.entries(process.env).filter(([, value]) => typeof value === "string") as [
+      string,
+      string,
+    ][];
+    const file = path.join(workspaceRoot, ".env");
+    if (!existsSync(file)) return fromProcess;
+    const fromFile = readFileSync(file, "utf8")
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#") && line.includes("="))
+      .map((line): [string, string] => {
+        const index = line.indexOf("=");
+        return [
+          line.slice(0, index).trim(),
+          line
+            .slice(index + 1)
+            .trim()
+            .replace(/^["']|["']$/g, ""),
+        ];
+      });
+    // The real environment wins: an operator exporting a key for one run should not be overridden by the file.
+    return [...fromFile, ...fromProcess];
+  }
+
+  /** `DEEPSEEK_API_KEY` names the provider `deepseek`; the engine's provider ids are lower-kebab. */
+  static #providerOf(name: string) {
+    const match = /^([A-Z0-9_]+)_API_KEY$/.exec(name);
+    return match?.[1]?.toLowerCase().replace(/_/g, "-");
+  }
+}

package/codeAgent/tools/AkanToolPack.ts

@@ -0,0 +1,114 @@
+import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { Workspace } from "../../commandDecorators";
+import { AkanEditScope } from "./AkanEditScope";
+import { AkanVerifier } from "./AkanVerifier";
+
+export interface AkanToolPackOptions {
+  workspace: Workspace;
+  cwd: string;
+  /** `readonly` for a reviewer, `apply` for an agent that may run a workflow. */
+  mode: "readonly" | "plan" | "apply";
+}
+
+/**
+ * Publishes the workspace's own agent tools — context inspection, workflows, repair, validation — to the model.
+ *
+ * These already exist as the akan MCP catalogue, dispatched in-process by `ContextRunner.callMcpTool`. Wrapping
+ * that dispatcher is the whole implementation: a second copy of "what does add-field do" would drift from the
+ * one the editors already talk to.
+ */
+export class AkanToolPack {
+  readonly #options: AkanToolPackOptions;
+
+  constructor(options: AkanToolPackOptions) {
+    this.#options = options;
+  }
+
+  extension(): InlineExtension {
+    return { name: "akan-tools", factory: async (pi) => await this.#register(pi) };
+  }
+
+  /**
+   * The names this pack will register.
+   *
+   * A `tools` allowlist on the session is an allowlist over *every* tool, extension ones included — pass only
+   * the built-ins and the model is told the akan tools do not exist, which is exactly what it then reports.
+   */
+  /**
+   * The CLI's own MCP catalogue is what these tools are, so this pack is the one place devkit reaches back
+   * into the executable package. `ContextRunner` composes the repair and workflow runners and cannot move
+   * here; the path is written out because devkit does not depend on the CLI and must not start. Both packages
+   * are bundled into one at publish, so the specifier resolves at build time either way.
+   */
+  async names() {
+    const { ContextRunner } = await import("../../../cli/context/context.runner");
+    return [
+      ...new ContextRunner().listMcpTools(this.#options.mode).map((tool) => tool.name),
+      AkanToolPack.verifyToolName,
+    ];
+  }
+
+  static readonly verifyToolName = "akan_verify";
+
+  async #register(pi: ExtensionAPI) {
+    const { ContextRunner } = await import("../../../cli/context/context.runner");
+    const runner = new ContextRunner();
+    const guidelineNames = await AkanToolPack.#guidelineNames();
+    for (const tool of runner.listMcpTools(this.#options.mode, { guidelineNames })) {
+      const description = tool.description ?? tool.name;
+      pi.registerTool({
+        name: tool.name,
+        label: tool.name,
+        description,
+        // Without a snippet a custom tool is left out of the system prompt's tool list entirely, and a model
+        // whose built-ins are narrowed then reads "Available tools: (none)" and stops trusting the list.
+        promptSnippet: `${tool.name}: ${description.split(".")[0] ?? description}`,
+        parameters: Type.Unsafe<Record<string, unknown>>(tool.inputSchema),
+        execute: async (_id, params) => {
+          const result = await runner.callMcpTool(this.#options.workspace, tool.name, params ?? {}, {
+            mode: this.#options.mode,
+          });
+          return { content: [{ type: "text", text: AkanToolPack.#render(result) }], details: undefined };
+        },
+      });
+    }
+    this.#registerVerify(pi);
+  }
+
+  #registerVerify(pi: ExtensionAPI) {
+    const verifier = new AkanVerifier(this.#options.cwd);
+    pi.registerTool({
+      name: AkanToolPack.verifyToolName,
+      label: "akan verify",
+      description:
+        "Run the akan validation chain (sync, lint, typecheck, and quality ssr for .tsx changes) over everything the working tree has changed, and report what failed. Call this after editing before you finish.",
+      promptSnippet: "akan_verify: run sync/lint/typecheck/quality over the working tree's changes",
+      parameters: Type.Object({}),
+      execute: async () => {
+        const scope = await AkanEditScope.since(this.#options.cwd, new Set());
+        const report = await verifier.verify(scope);
+        return {
+          content: [{ type: "text", text: AkanVerifier.summarize(report) }],
+          details: undefined,
+          isError: !report.ok,
+        };
+      },
+    });
+  }
+
+  /** The guideline list is a directory read, so a model cannot name one without being handed the enum. */
+  static async #guidelineNames() {
+    try {
+      const { Prompter } = await import("../../prompter");
+      return await Prompter.listGuidelines();
+    } catch {
+      return [];
+    }
+  }
+
+  static #render(result: unknown) {
+    if (typeof result === "string") return result;
+    return JSON.stringify(result, null, 2);
+  }
+}

package/codeAgent/tools/AkanVerifier.ts

@@ -0,0 +1,55 @@
+import { AkanCli, type AkanCliResult } from "./AkanCli";
+import type { AkanEditScopeResult } from "./AkanEditScope";
+
+export interface AkanVerifyReport {
+  ok: boolean;
+  steps: AkanCliResult[];
+  scope: AkanEditScopeResult;
+}
+
+/**
+ * Runs the workspace's own validation chain over whatever a turn changed.
+ *
+ * The order is the one the guide names and it is not interchangeable: `sync` first because a stale generated
+ * barrel makes `typecheck` report a missing symbol whose real cause is a file that was added, which sends the
+ * model editing the wrong place. `lint` before `typecheck` because it rewrites formatting and import order,
+ * and a typecheck run against the pre-format text reports positions that no longer exist.
+ */
+export class AkanVerifier {
+  readonly #cli: AkanCli;
+
+  constructor(cwd: string) {
+    this.#cli = new AkanCli(cwd);
+  }
+
+  async verify(scope: AkanEditScopeResult): Promise<AkanVerifyReport> {
+    const steps: AkanCliResult[] = [];
+    const targets = [...scope.apps, ...scope.libs];
+    if (scope.needsSync) for (const target of targets) steps.push(await this.#cli.run(["sync", target]));
+    for (const target of targets) steps.push(await this.#cli.run(["lint", target]));
+    for (const app of scope.apps) steps.push(await this.#cli.run(["typecheck", app]));
+    if (scope.touchesTsx) steps.push(await this.#cli.run(["quality", "ssr"]));
+    return { ok: steps.every((step) => step.ok), steps, scope };
+  }
+
+  /** What a model needs to act: which step failed and its tail — never the whole output, which rides every later turn. */
+  static summarize(report: AkanVerifyReport, { tailLines = 40 }: { tailLines?: number } = {}) {
+    if (!report.steps.length) return "No akan target was touched, so there was nothing to verify.";
+    if (report.ok) return `Verification passed: ${report.steps.map((step) => step.command).join(", ")}.`;
+    const failed = report.steps.filter((step) => !step.ok);
+    const passed = report.steps.filter((step) => step.ok).map((step) => step.command);
+    const blocks = failed.map((step) => `### ${step.command} (exit ${step.exitCode})\n${tail(step.output, tailLines)}`);
+    return [
+      `Verification failed: ${failed.map((step) => step.command).join(", ")}.`,
+      passed.length ? `Passed: ${passed.join(", ")}.` : "",
+      ...blocks,
+    ]
+      .filter(Boolean)
+      .join("\n\n");
+  }
+}
+
+const tail = (text: string, lines: number) => {
+  const all = text.split("\n");
+  return all.length <= lines ? text : `…\n${all.slice(-lines).join("\n")}`;
+};

package/codeAgent/tools/MailToolPack.ts

@@ -0,0 +1,85 @@
+import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
+import type { CodeAgentProfile } from "akanjs/common";
+import { Type } from "typebox";
+import type { CodeMailbox, CodePeer } from "../agent/CodeMailbox";
+
+export interface MailToolPackOptions {
+  profile: CodeAgentProfile;
+  /** Late, because the mailbox only exists once the session it announces has one. */
+  mailbox: () => CodeMailbox | undefined;
+}
+
+/**
+ * Lets the agent reach the other `akan code` sessions running in this workspace.
+ *
+ * The person can already do it with `/peers` and `/msg`; this is the half that makes it *coordination* — one
+ * session asking another to take a piece of the work, or telling it the file they both touch has moved.
+ *
+ * A message arrives at the other end as a prompt, so the tool's cost is a whole turn of somebody else's
+ * window. That is why the description says what it says: it is for handing over work, not for chatting.
+ */
+export class MailToolPack {
+  static readonly toolNames = ["list_peers", "send_peer_message"];
+
+  readonly #options: MailToolPackOptions;
+
+  constructor(options: MailToolPackOptions) {
+    this.#options = options;
+  }
+
+  names() {
+    return this.#options.profile.session.store === "file" ? MailToolPack.toolNames : [];
+  }
+
+  extension(): InlineExtension | undefined {
+    if (!this.names().length) return undefined;
+    return { name: "akan-mail", factory: (pi: ExtensionAPI) => this.#register(pi) };
+  }
+
+  #register(pi: ExtensionAPI) {
+    pi.registerTool({
+      name: "list_peers",
+      label: "List peer sessions",
+      description:
+        "List the other akan code sessions running in this workspace right now, with their name and working directory. Call it before send_peer_message so you name a session that is actually there.",
+      promptSnippet: "list_peers: the other akan code sessions running here",
+      parameters: Type.Object({}),
+      execute: async () => ({
+        content: [{ type: "text" as const, text: MailToolPack.#render(this.#options.mailbox()?.peers() ?? []) }],
+        details: undefined,
+      }),
+    });
+    pi.registerTool({
+      name: "send_peer_message",
+      label: "Message a peer session",
+      description:
+        "Hand a message to another akan code session in this workspace. It arrives there as a prompt, so it costs that session a turn — use it to hand over a piece of work or to warn it about a change you made, not to chat. Say what you want done and what you already did.",
+      promptSnippet: "send_peer_message: hand work to another akan code session",
+      parameters: Type.Object({
+        to: Type.String({ description: "The peer's name, or the front of its id, from list_peers." }),
+        message: Type.String({ description: "What that session should know or do." }),
+      }),
+      execute: async (_id, params) => {
+        const mailbox = this.#options.mailbox();
+        const peer = mailbox?.find(params.to);
+        if (!mailbox || !peer)
+          return {
+            content: [{ type: "text" as const, text: `No live session matches "${params.to}". Call list_peers.` }],
+            details: undefined,
+            isError: true,
+          };
+        try {
+          mailbox.send(peer.id, params.message);
+          return { content: [{ type: "text" as const, text: `Sent to ${peer.name}.` }], details: undefined };
+        } catch (error: unknown) {
+          return { content: [{ type: "text" as const, text: String(error) }], details: undefined, isError: true };
+        }
+      },
+    });
+  }
+
+  static #render(peers: CodePeer[]) {
+    if (!peers.length) return "No other akan code session is running in this workspace.";
+    return peers.map((peer) => `${peer.name} (${peer.id.slice(0, 8)}) — ${peer.cwd}`).join("\n");
+  }
+}