@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/codeAgent/tools/AkanToolPack.ts

@@ -0,0 +1,92 @@
+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";
+}
+
+// Wraps the akan MCP catalogue's in-process dispatcher (ContextRunner.callMcpTool); a second copy would drift from it.
+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 session allowlist covers extension tools too; a name missing here tells the model the tool does not exist.
+  // devkit must not depend on the CLI, so ContextRunner is reached by relative path; publishing bundles both.
+  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 the engine leaves a custom tool out of the system prompt's tool list entirely.
+        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,
+          });
+          const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+          return { content: [{ type: "text", text }], 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,
+        };
+      },
+    });
+  }
+
+  static async #guidelineNames() {
+    try {
+      const { Prompter } = await import("../../prompter");
+      return await Prompter.listGuidelines();
+    } catch {
+      return [];
+    }
+  }
+}

package/codeAgent/tools/AkanVerifier.ts

@@ -0,0 +1,48 @@
+import { AkanCli, type AkanCliResult } from "./AkanCli";
+import type { AkanEditScopeResult } from "./AkanEditScope";
+
+export interface AkanVerifyReport {
+  ok: boolean;
+  steps: AkanCliResult[];
+  scope: AkanEditScopeResult;
+}
+
+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];
+    // Order matters: a stale barrel reads to typecheck as a missing symbol, and lint moves the positions it reports.
+    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/AskToolPack.ts

@@ -0,0 +1,99 @@
+import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
+import type { CodeAgentProfile, CodeAgentQuestion } from "akanjs/common";
+import { Type } from "typebox";
+
+export interface AskToolPackOptions {
+  profile: CodeAgentProfile;
+  /** Puts one question on the wire and resolves with the labels chosen, or nothing when it was skipped. */
+  ask: (question: Omit<CodeAgentQuestion, "questionId">) => Promise<string | undefined>;
+}
+
+// One question at a time even when several are sent: the host draws one block, and an answer can change the next.
+export class AskToolPack {
+  static readonly toolName = "ask_user";
+  /** Four is what fits on a screen without the transcript disappearing behind the questions. */
+  static readonly maxQuestions = 4;
+
+  readonly #options: AskToolPackOptions;
+
+  constructor(options: AskToolPackOptions) {
+    this.#options = options;
+  }
+
+  names() {
+    return this.#options.profile.ui.canPrompt ? [AskToolPack.toolName] : [];
+  }
+
+  extension(): InlineExtension | undefined {
+    if (!this.#options.profile.ui.canPrompt) return undefined;
+    return { name: "akan-ask", factory: (pi: ExtensionAPI) => this.#register(pi) };
+  }
+
+  #register(pi: ExtensionAPI) {
+    pi.registerTool({
+      name: AskToolPack.toolName,
+      label: "Ask",
+      description:
+        "Ask the user to decide something you cannot decide from the code or the request. Use it when two readings of the task would lead to materially different work, not for choices with an obvious default — and never to ask permission for work you were already asked to do. Offer concrete options whenever you can name them; mark one recommended when you have a view.",
+      promptSnippet: "ask_user: put a decision the user owns back to them, with options",
+      parameters: Type.Object({
+        questions: Type.Array(
+          Type.Object({
+            question: Type.String({ description: "The whole question, as one sentence ending in a question mark." }),
+            header: Type.Optional(
+              Type.String({ description: "Two or three words naming what is being chosen, e.g. 'Auth method'." }),
+            ),
+            options: Type.Optional(
+              Type.Array(
+                Type.Object({
+                  label: Type.String({ description: "The choice, in one to five words." }),
+                  detail: Type.Optional(
+                    Type.String({ description: "What picking it means, or the trade-off it carries." }),
+                  ),
+                  recommended: Type.Optional(
+                    Type.Boolean({ description: "Mark at most one. It is offered first and labelled as such." }),
+                  ),
+                }),
+                { description: "Two to four distinct choices. Leave it out to ask for an answer in prose." },
+              ),
+            ),
+            multiSelect: Type.Optional(
+              Type.Boolean({ description: "Several options may be chosen together, rather than exactly one." }),
+            ),
+            freeText: Type.Optional(
+              Type.Boolean({
+                description: "Offer a further choice that lets the user type an answer of their own. Default true.",
+              }),
+            ),
+          }),
+          { description: `One to ${AskToolPack.maxQuestions} questions, asked in order.` },
+        ),
+      }),
+      execute: async (_id, params) => {
+        const questions = (params.questions ?? []).slice(0, AskToolPack.maxQuestions);
+        if (!questions.length)
+          return { content: [{ type: "text", text: "No question was asked." }], details: undefined, isError: true };
+        const answers: string[] = [];
+        for (const entry of questions) {
+          const options = (entry.options ?? []).map((option, at) => ({
+            key: `${at}`,
+            label: option.label,
+            ...(option.detail ? { detail: option.detail } : {}),
+            ...(option.recommended ? { recommended: true } : {}),
+          }));
+          const answer = await this.#options.ask({
+            prompt: entry.header ? `${entry.header} — ${entry.question}` : entry.question,
+            kind: options.length ? "select" : "text",
+            ...(options.length ? { options } : {}),
+            ...(entry.multiSelect ? { multiSelect: true } : {}),
+            // On by default: the model's options are a guess, and only the person knows when none of them fits.
+            freeText: entry.freeText ?? true,
+          });
+          // Spelled out as a skip: a blank answer reads to a model as "the user wanted nothing".
+          answers.push(`${entry.question}\n→ ${answer ?? "(skipped — decide this yourself and say what you chose)"}`);
+        }
+        return { content: [{ type: "text", text: answers.join("\n\n") }], details: undefined };
+      },
+    });
+  }
+}

package/codeAgent/tools/MailToolPack.ts

@@ -0,0 +1,76 @@
+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;
+}
+
+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");
+  }
+}

package/codeAgent/tools/McpClient.ts

@@ -0,0 +1,187 @@
+import type { CodeAgentMcpServerRef } from "akanjs/common";
+
+export interface McpToolInfo {
+  name: string;
+  description?: string;
+  inputSchema: { type: "object"; properties: Record<string, unknown>; required?: string[] };
+}
+
+interface JsonRpcResponse {
+  id?: number;
+  result?: { tools?: McpToolInfo[]; nextCursor?: string; content?: unknown; isError?: boolean };
+  error?: { code: number; message: string };
+}
+
+const protocolVersion = "2025-06-18";
+
+// Its own class: a 401 is fixed by signing in, and calling it "unavailable" sends someone to debug a working server.
+export class McpUnauthorized extends Error {
+  /** The `WWW-Authenticate` value, which names the resource metadata discovery starts from. */
+  readonly challenge: string;
+
+  constructor(name: string, challenge: string) {
+    super(`MCP server "${name}" requires authentication`);
+    this.name = "McpUnauthorized";
+    this.challenge = challenge;
+  }
+}
+
+export class McpClient {
+  /** A ceiling on a server that never stops paging; 50 pages is 5,000 tools at the usual page size. */
+  static readonly maxToolPages = 50;
+
+  readonly ref: CodeAgentMcpServerRef;
+  #proc: Bun.Subprocess<"pipe", "pipe", "ignore"> | undefined;
+  #nextId = 0;
+  #buffer = "";
+  readonly #pending = new Map<number, (response: JsonRpcResponse) => void>();
+  #sessionId: string | undefined;
+  readonly #token: string | undefined;
+
+  constructor(ref: CodeAgentMcpServerRef, token?: string) {
+    this.ref = ref;
+    this.#token = token;
+  }
+
+  async connect() {
+    if (this.ref.transport === "stdio") this.#spawn();
+    const initialize = await this.#call("initialize", {
+      protocolVersion,
+      capabilities: {},
+      clientInfo: { name: "akan-code", version: "1" },
+    });
+    if (initialize.error) throw new Error(initialize.error.message);
+    await this.#notify("notifications/initialized");
+    return this;
+  }
+
+  /** Every page: `tools/list` pages by `nextCursor` (an akan server at 100), and one page silently drops the tail. */
+  async listTools(): Promise<McpToolInfo[]> {
+    const tools: McpToolInfo[] = [];
+    let cursor: string | undefined;
+    for (let page = 0; page < McpClient.maxToolPages; page += 1) {
+      const response = await this.#call("tools/list", cursor ? { cursor } : {});
+      if (response.error) throw new Error(response.error.message);
+      tools.push(...(response.result?.tools ?? []));
+      const next = response.result?.nextCursor;
+      // Handing back the cursor it was given is a server that would page forever; so is one that cycles.
+      if (!next || next === cursor) return tools;
+      cursor = next;
+    }
+    return tools;
+  }
+
+  async callTool(name: string, args: Record<string, unknown>) {
+    const response = await this.#call("tools/call", { name, arguments: args });
+    if (response.error) return { text: response.error.message, isError: true };
+    return { text: McpClient.#renderContent(response.result?.content), isError: !!response.result?.isError };
+  }
+
+  close() {
+    this.#proc?.kill();
+    this.#proc = undefined;
+    for (const resolve of this.#pending.values()) resolve({ error: { code: -1, message: "MCP server closed" } });
+    this.#pending.clear();
+  }
+
+  #spawn() {
+    if (!this.ref.command) throw new Error(`MCP server "${this.ref.name}" declares no command`);
+    this.#proc = Bun.spawn([this.ref.command, ...(this.ref.args ?? [])], {
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "ignore",
+      env: { ...process.env, ...this.ref.env },
+    });
+    void this.#readStdout();
+  }
+
+  async #readStdout() {
+    const decoder = new TextDecoder();
+    for await (const chunk of this.#proc?.stdout ?? []) {
+      this.#buffer += decoder.decode(chunk as Uint8Array, { stream: true });
+      let index = this.#buffer.indexOf("\n");
+      while (index >= 0) {
+        const line = this.#buffer.slice(0, index).trim();
+        this.#buffer = this.#buffer.slice(index + 1);
+        if (line) this.#receive(line);
+        index = this.#buffer.indexOf("\n");
+      }
+    }
+  }
+
+  #receive(line: string) {
+    try {
+      const message = JSON.parse(line) as JsonRpcResponse;
+      if (typeof message.id !== "number") return;
+      this.#pending.get(message.id)?.(message);
+      this.#pending.delete(message.id);
+    } catch {
+      // A server that writes anything but JSON-RPC on stdout is misbehaving; dropping the line keeps us alive.
+    }
+  }
+
+  async #call(method: string, params: unknown): Promise<JsonRpcResponse> {
+    this.#nextId += 1;
+    const id = this.#nextId;
+    const request = { jsonrpc: "2.0", id, method, params };
+    if (this.ref.transport === "http") return await this.#post(request);
+    this.#proc?.stdin.write(`${JSON.stringify(request)}\n`);
+    return await new Promise<JsonRpcResponse>((resolve) => {
+      this.#pending.set(id, resolve);
+      setTimeout(() => {
+        if (!this.#pending.delete(id)) return;
+        resolve({ error: { code: -2, message: `MCP server "${this.ref.name}" timed out on ${method}` } });
+      }, 30_000);
+    });
+  }
+
+  async #notify(method: string) {
+    const request = { jsonrpc: "2.0", method };
+    if (this.ref.transport === "http") await this.#post(request);
+    else this.#proc?.stdin.write(`${JSON.stringify(request)}\n`);
+  }
+
+  async #post(body: unknown): Promise<JsonRpcResponse> {
+    if (!this.ref.url) throw new Error(`MCP server "${this.ref.name}" declares no url`);
+    const response = await fetch(this.ref.url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        // Streamable HTTP lets a server answer either way; a client that omits the SSE type gets a 406.
+        accept: "application/json, text/event-stream",
+        "mcp-protocol-version": protocolVersion,
+        ...this.ref.headers,
+        ...(this.#token ? { authorization: `Bearer ${this.#token}` } : {}),
+        ...(this.#sessionId ? { "mcp-session-id": this.#sessionId } : {}),
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(30_000),
+    });
+    // Thrown, not returned as a JSON-RPC error: a 401's body says nothing, and the caller needs its header.
+    if (response.status === 401)
+      throw new McpUnauthorized(this.ref.name, response.headers.get("www-authenticate") ?? "");
+    this.#sessionId = response.headers.get("mcp-session-id") ?? this.#sessionId;
+    const text = await response.text();
+    if (!text.trim()) return {};
+    // An SSE answer to a single request carries one `data:` line holding the whole JSON-RPC response.
+    const payload = text.startsWith("event:") || text.startsWith("data:") ? McpClient.#firstSseData(text) : text;
+    return payload ? (JSON.parse(payload) as JsonRpcResponse) : {};
+  }
+
+  static #firstSseData(text: string) {
+    return text
+      .split("\n")
+      .find((line) => line.startsWith("data:"))
+      ?.slice(5)
+      .trim();
+  }
+
+  static #renderContent(content: unknown) {
+    if (!Array.isArray(content)) return typeof content === "string" ? content : JSON.stringify(content ?? null);
+    return content
+      .map((part: { type?: string; text?: string }) =>
+        part.type === "text" ? (part.text ?? "") : JSON.stringify(part),
+      )
+      .join("\n");
+  }
+}