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

package/codeAgent/tools/McpClient.ts

@@ -0,0 +1,162 @@
+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[]; content?: unknown; isError?: boolean };
+  error?: { code: number; message: string };
+}
+
+const protocolVersion = "2025-06-18";
+
+/**
+ * A client for one MCP server, over stdio or streamable HTTP.
+ *
+ * **Every failure is non-fatal.** A server that will not start, answers nothing, or dies mid-session costs its
+ * own tools and nothing else: an agent that cannot finish a turn because an unrelated integration is down is
+ * worse than one with fewer tools.
+ */
+export class McpClient {
+  readonly ref: CodeAgentMcpServerRef;
+  #proc: Bun.Subprocess<"pipe", "pipe", "ignore"> | undefined;
+  #nextId = 0;
+  #buffer = "";
+  readonly #pending = new Map<number, (response: JsonRpcResponse) => void>();
+  #sessionId: string | undefined;
+
+  constructor(ref: CodeAgentMcpServerRef) {
+    this.ref = ref;
+  }
+
+  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;
+  }
+
+  async listTools(): Promise<McpToolInfo[]> {
+    const response = await this.#call("tools/list", {});
+    if (response.error) throw new Error(response.error.message);
+    return response.result?.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",
+      // A server's diagnostics belong in its own stderr, never mixed into the JSON-RPC stream.
+      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",
+        ...(this.#sessionId ? { "mcp-session-id": this.#sessionId } : {}),
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(30_000),
+    });
+    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");
+  }
+}

package/codeAgent/tools/McpToolPack.ts

@@ -0,0 +1,134 @@
+import { existsSync, readFileSync } from "node:fs";
+import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
+import { type CodeAgentMcpServerRef, type CodeAgentProfile, codeAgentClip, codeAgentOutputChars } from "akanjs/common";
+import { Type } from "typebox";
+import { akanCodePaths } from "../agent/akanCodePaths";
+import { McpClient, type McpToolInfo } from "./McpClient";
+
+export interface McpToolPackOptions {
+  workspaceRoot: string;
+  profile: CodeAgentProfile;
+  onNotice?: (message: string) => void;
+}
+
+interface ServerFileEntry {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+  type?: string;
+  disabled?: boolean;
+}
+
+/**
+ * Connects the workspace's MCP servers and publishes their tools.
+ *
+ * Servers are declared in `.akan/code/mcp.json` in the shape the editors already use (`mcpServers`), so a
+ * developer can paste the block they already have rather than learn a second format.
+ *
+ * Tool names are prefixed with the server. Two servers offering `search` is the normal case, not the edge one,
+ * and a collision that silently shadows one of them is invisible from the model's side.
+ */
+export class McpToolPack {
+  readonly #options: McpToolPackOptions;
+  readonly #clients: { client: McpClient; tools: McpToolInfo[] }[] = [];
+
+  private constructor(options: McpToolPackOptions) {
+    this.#options = options;
+  }
+
+  /**
+   * Connects every declared server before the session exists, because the session's tool allowlist has to name
+   * these tools and their names are only knowable from a live `tools/list`.
+   */
+  static async connect(options: McpToolPackOptions) {
+    const refs = McpToolPack.#refs(options);
+    if (!refs.length) return undefined;
+    const pack = new McpToolPack(options);
+    for (const ref of refs) {
+      try {
+        const client = await new McpClient(ref).connect();
+        pack.#clients.push({ client, tools: await client.listTools() });
+      } catch (error) {
+        // One unreachable integration must not cost the agent its turn, so it costs only its own tools.
+        options.onNotice?.(`MCP server "${ref.name}" is unavailable: ${String(error)}`);
+      }
+    }
+    return pack.#clients.length ? pack : undefined;
+  }
+
+  get toolNames() {
+    return this.#clients.flatMap(({ client, tools }) =>
+      tools.map((tool) => McpToolPack.#nameOf(client.ref.name, tool.name)),
+    );
+  }
+
+  extension(): InlineExtension {
+    return { name: "akan-mcp", factory: (pi: ExtensionAPI) => this.#register(pi) };
+  }
+
+  close() {
+    for (const { client } of this.#clients) client.close();
+  }
+
+  #register(pi: ExtensionAPI) {
+    for (const { client, tools } of this.#clients)
+      for (const tool of tools) {
+        const name = McpToolPack.#nameOf(client.ref.name, tool.name);
+        const description = tool.description ?? tool.name;
+        pi.registerTool({
+          name,
+          label: `${client.ref.name}: ${tool.name}`,
+          description,
+          promptSnippet: `${name}: ${description.split(".")[0] ?? description}`,
+          // The server's own schema goes through untouched; it is the party that validates the call.
+          parameters: Type.Unsafe<Record<string, unknown>>(tool.inputSchema),
+          execute: async (_id, params) => {
+            const result = await client.callTool(tool.name, params ?? {});
+            return {
+              content: [{ type: "text", text: codeAgentClip(result.text, codeAgentOutputChars) }],
+              details: undefined,
+              isError: result.isError,
+            };
+          },
+        });
+      }
+  }
+
+  static #nameOf(server: string, tool: string) {
+    return `mcp__${server.replace(/[^a-zA-Z0-9_]/g, "_")}__${tool}`;
+  }
+
+  static #refs(options: McpToolPackOptions): CodeAgentMcpServerRef[] {
+    if (options.profile.tools.mcp === "off") return [];
+    const declared = Array.isArray(options.profile.tools.mcp) ? options.profile.tools.mcp : [];
+    return [...McpToolPack.#fromFile(options.workspaceRoot), ...declared];
+  }
+
+  static #fromFile(workspaceRoot: string): CodeAgentMcpServerRef[] {
+    const file = akanCodePaths.mcpFile(workspaceRoot);
+    if (!existsSync(file)) return [];
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf8")) as {
+        mcpServers?: Record<string, ServerFileEntry>;
+        servers?: Record<string, ServerFileEntry>;
+      };
+      const entries = Object.entries(parsed.mcpServers ?? parsed.servers ?? {});
+      return entries
+        .filter(([, entry]) => !entry.disabled)
+        .map(([name, entry]): CodeAgentMcpServerRef => {
+          const transport = entry.url ? "http" : "stdio";
+          return {
+            name,
+            transport,
+            ...(entry.command ? { command: entry.command } : {}),
+            ...(entry.args ? { args: entry.args } : {}),
+            ...(entry.url ? { url: entry.url } : {}),
+            ...(entry.env ? { env: entry.env } : {}),
+          };
+        });
+    } catch {
+      return [];
+    }
+  }
+}

package/codeAgent/tools/SessionToolPack.ts

@@ -0,0 +1,101 @@
+import type { ExtensionAPI, InlineExtension, SessionInfo } from "@earendil-works/pi-coding-agent";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { type CodeAgentProfile, codeAgentClip, codeAgentOutputChars } from "akanjs/common";
+import { Type } from "typebox";
+import { akanCodePaths } from "../agent/akanCodePaths";
+
+export interface SessionToolPackOptions {
+  workspaceRoot: string;
+  cwd: string;
+  profile: CodeAgentProfile;
+  /** Excluded from results: reading your own transcript back is a way to spend a context window twice. */
+  currentSessionId: () => string;
+}
+
+const snippetChars = 240;
+
+/**
+ * Lets the agent reach its own earlier conversations in this workspace.
+ *
+ * Every past session is already on disk as JSONL under `.akan/code/sessions/`, so this is a reader, not a
+ * second store. "We decided last Tuesday to keep the adapter in `srvkit/`" is the kind of thing that exists
+ * nowhere else — not in the code, not in git, not in the guide.
+ */
+export class SessionToolPack {
+  readonly #options: SessionToolPackOptions;
+
+  constructor(options: SessionToolPackOptions) {
+    this.#options = options;
+  }
+
+  static readonly toolNames = ["session_search", "session_read"];
+
+  names() {
+    return this.#options.profile.session.crossSession ? SessionToolPack.toolNames : [];
+  }
+
+  extension(): InlineExtension | undefined {
+    if (!this.names().length) return undefined;
+    return { name: "akan-sessions", factory: (pi: ExtensionAPI) => this.#register(pi) };
+  }
+
+  #register(pi: ExtensionAPI) {
+    pi.registerTool({
+      name: "session_search",
+      label: "Search sessions",
+      description:
+        "Search earlier coding-agent conversations in this workspace for a phrase, and get back the matching sessions with a snippet. Use it when the user refers to something decided before, or when you suspect this problem has been solved here already.",
+      promptSnippet: "session_search: find earlier conversations in this workspace by phrase",
+      parameters: Type.Object({
+        query: Type.String({ description: "A phrase to look for, matched case-insensitively." }),
+        limit: Type.Optional(Type.Number({ description: "How many sessions to return, default 5." })),
+      }),
+      execute: async (_id, params) => {
+        const matches = await this.#search(params.query, params.limit ?? 5);
+        return { content: [{ type: "text", text: matches }], details: undefined };
+      },
+    });
+    pi.registerTool({
+      name: "session_read",
+      label: "Read session",
+      description: "Read one earlier conversation, found with session_search, as plain text.",
+      promptSnippet: "session_read: read one earlier conversation by id",
+      parameters: Type.Object({ sessionId: Type.String() }),
+      execute: async (_id, params) => {
+        const text = await this.#read(params.sessionId);
+        return { content: [{ type: "text", text }], details: undefined, isError: text.startsWith("No session") };
+      },
+    });
+  }
+
+  async #search(query: string, limit: number) {
+    const needle = query.toLowerCase();
+    const sessions = (await this.#list()).filter(
+      (session) =>
+        session.id !== this.#options.currentSessionId() && session.allMessagesText.toLowerCase().includes(needle),
+    );
+    if (!sessions.length) return `No earlier session mentions "${query}".`;
+    return sessions
+      .slice(0, limit)
+      .map((session) => {
+        const at = session.allMessagesText.toLowerCase().indexOf(needle);
+        const snippet = session.allMessagesText.slice(Math.max(0, at - 80), at + snippetChars).replace(/\s+/g, " ");
+        return `- ${session.id} (${session.modified.toISOString().slice(0, 10)}${session.name ? `, "${session.name}"` : ""})\n  …${snippet}…`;
+      })
+      .join("\n");
+  }
+
+  async #read(sessionId: string) {
+    const session = (await this.#list()).find((entry) => entry.id === sessionId);
+    if (!session) return `No session with id ${sessionId} in this workspace.`;
+    return codeAgentClip(session.allMessagesText, codeAgentOutputChars * 2);
+  }
+
+  /**
+   * Sessions are listed for this workspace's directory only. A global list would reach another checkout's
+   * conversations, which is somebody else's project even when it is the same person's machine.
+   */
+  async #list(): Promise<SessionInfo[]> {
+    return await SessionManager.list(this.#options.cwd, akanCodePaths.sessionsDir(this.#options.workspaceRoot));
+  }
+}

package/codeAgent/tools/WebToolPack.ts

@@ -0,0 +1,153 @@
+import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
+import { type CodeAgentProfile, codeAgentClip, codeAgentOutputChars } from "akanjs/common";
+import { Type } from "typebox";
+
+export interface WebToolPackOptions {
+  profile: CodeAgentProfile;
+}
+
+interface SearchProvider {
+  name: string;
+  envKey: string;
+  search(key: string, query: string, count: number): Promise<string>;
+}
+
+/**
+ * `web_fetch` and `web_search`, gated by the profile's network settings.
+ *
+ * Search needs a provider nobody ships a free key for, so the tool is registered only when one of the known
+ * environment keys is present. Registering it unconditionally and failing at call time costs prompt tokens for
+ * a capability that does not exist, and teaches the model to retry a tool that can never work.
+ */
+export class WebToolPack {
+  readonly #options: WebToolPackOptions;
+
+  constructor(options: WebToolPackOptions) {
+    this.#options = options;
+  }
+
+  static providers: SearchProvider[] = [
+    {
+      name: "brave",
+      envKey: "BRAVE_API_KEY",
+      search: async (key, query, count) => {
+        const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${count}`;
+        const response = await fetch(url, { headers: { "x-subscription-token": key, accept: "application/json" } });
+        const body = (await response.json()) as {
+          web?: { results?: { title: string; url: string; description: string }[] };
+        };
+        return (body.web?.results ?? []).map((r) => `- ${r.title}\n  ${r.url}\n  ${r.description}`).join("\n");
+      },
+    },
+    {
+      name: "tavily",
+      envKey: "TAVILY_API_KEY",
+      search: async (key, query, count) => {
+        const response = await fetch("https://api.tavily.com/search", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ api_key: key, query, max_results: count }),
+        });
+        const body = (await response.json()) as { results?: { title: string; url: string; content: string }[] };
+        return (body.results ?? []).map((r) => `- ${r.title}\n  ${r.url}\n  ${r.content}`).join("\n");
+      },
+    },
+  ];
+
+  /** Names the session allowlist must carry. Empty when the profile, or the environment, offers nothing. */
+  names() {
+    const names: string[] = [];
+    if (this.#options.profile.tools.web.fetch) names.push("web_fetch");
+    if (this.#options.profile.tools.web.search && WebToolPack.#provider()) names.push("web_search");
+    return names;
+  }
+
+  extension(): InlineExtension | undefined {
+    if (!this.names().length) return undefined;
+    return { name: "akan-web", factory: (pi: ExtensionAPI) => this.#register(pi) };
+  }
+
+  #register(pi: ExtensionAPI) {
+    if (this.#options.profile.tools.web.fetch) this.#registerFetch(pi);
+    const provider = WebToolPack.#provider();
+    if (this.#options.profile.tools.web.search && provider) this.#registerSearch(pi, provider);
+  }
+
+  #registerFetch(pi: ExtensionAPI) {
+    const allowHosts = this.#options.profile.network.allowHosts;
+    pi.registerTool({
+      name: "web_fetch",
+      label: "Fetch",
+      description: "Fetch a URL and return its readable text. HTML is stripped to text; the result is truncated.",
+      promptSnippet: "web_fetch: fetch a URL and return its readable text",
+      parameters: Type.Object({ url: Type.String({ description: "Absolute http(s) URL." }) }),
+      execute: async (_id, params) => {
+        const refusal = WebToolPack.#refuseHost(params.url, allowHosts);
+        if (refusal) return { content: [{ type: "text", text: refusal }], details: undefined, isError: true };
+        const response = await fetch(params.url, { signal: AbortSignal.timeout(20_000), redirect: "follow" });
+        const text = WebToolPack.#readable(await response.text());
+        return {
+          content: [
+            { type: "text", text: `${response.status} ${params.url}\n\n${codeAgentClip(text, codeAgentOutputChars)}` },
+          ],
+          details: undefined,
+          isError: !response.ok,
+        };
+      },
+    });
+  }
+
+  #registerSearch(pi: ExtensionAPI, provider: SearchProvider) {
+    pi.registerTool({
+      name: "web_search",
+      label: "Search",
+      description: `Search the web (${provider.name}) and return the top results as title, url and snippet.`,
+      promptSnippet: "web_search: search the web and return titles, urls and snippets",
+      parameters: Type.Object({
+        query: Type.String(),
+        count: Type.Optional(Type.Number({ description: "How many results, default 5." })),
+      }),
+      execute: async (_id, params) => {
+        const key = process.env[provider.envKey] ?? "";
+        const results = await provider.search(key, params.query, params.count ?? 5);
+        return {
+          content: [{ type: "text", text: codeAgentClip(results || "(no results)", codeAgentOutputChars) }],
+          details: undefined,
+        };
+      },
+    });
+  }
+
+  static #provider() {
+    return WebToolPack.providers.find((provider) => !!process.env[provider.envKey]);
+  }
+
+  static #refuseHost(url: string, allowHosts: string[] | undefined) {
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return `"${url}" is not an absolute URL.`;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return "Only http and https URLs can be fetched.";
+    if (allowHosts?.length && !allowHosts.includes(parsed.hostname))
+      return `This profile only allows ${allowHosts.join(", ")}.`;
+    return undefined;
+  }
+
+  /** Enough to read a documentation page; a full HTML parser is not worth a dependency for that. */
+  static #readable(html: string) {
+    return html
+      .replace(/<script[\s\S]*?<\/script>/gi, " ")
+      .replace(/<style[\s\S]*?<\/style>/gi, " ")
+      .replace(/<[^>]+>/g, " ")
+      .replace(/&nbsp;/g, " ")
+      .replace(/&amp;/g, "&")
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&quot;/g, '"')
+      .replace(/[ \t]+/g, " ")
+      .replace(/\n{3,}/g, "\n\n")
+      .trim();
+  }
+}