@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/codeAgent/tools/McpToolPack.ts

@@ -0,0 +1,199 @@
+import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
+import {
+  type CodeAgentMcpServerRef,
+  type CodeAgentMcpStatus,
+  type CodeAgentProfile,
+  codeAgentClip,
+  codeAgentOutputChars,
+} from "akanjs/common";
+import { Type } from "typebox";
+import { McpClient, type McpToolInfo, McpUnauthorized } from "./McpClient";
+import { McpServerConfig } from "./McpServerConfig";
+import { McpSignIn } from "./McpSignIn";
+
+export interface McpToolPackOptions {
+  workspaceRoot: string;
+  profile: CodeAgentProfile;
+  onNotice?: (message: string) => void;
+}
+
+interface McpToolPackServer {
+  client: McpClient;
+  tools: McpToolInfo[];
+  token: string | undefined;
+  status: CodeAgentMcpStatus;
+  renewing: Promise<McpClient | undefined> | undefined;
+  refused: McpClient | undefined;
+}
+
+// Tool names carry the server prefix: two servers offering `search` is the normal case, and a shadow is invisible.
+export class McpToolPack {
+  readonly #clients: McpToolPackServer[] = [];
+  readonly #status: CodeAgentMcpStatus[] = [];
+  readonly #onNotice: ((message: string) => void) | undefined;
+
+  private constructor(onNotice: ((message: string) => void) | undefined) {
+    this.#onNotice = onNotice;
+  }
+
+  /** Undefined only when nothing is declared; a pack whose every server failed still comes back to say why. */
+  static async connect(options: McpToolPackOptions) {
+    const refs = McpToolPack.#refs(options);
+    if (!refs.length) return undefined;
+    const pack = new McpToolPack(options.onNotice);
+    for (const ref of refs) {
+      const base = { name: ref.name, transport: ref.transport, target: McpServerConfig.targetOf(ref) };
+      // Never an interactive sign-in: connect runs inside `CodeAgent.create`, before any screen is drawn.
+      const token = ref.transport === "http" ? await McpSignIn.token(ref, options.onNotice) : undefined;
+      try {
+        const opened = await McpToolPack.#openRefreshing(ref, token, options.onNotice);
+        const status: CodeAgentMcpStatus = {
+          ...base,
+          tools: opened.tools.map((tool) => McpToolPack.#nameOf(ref.name, tool.name)),
+          auth: opened.token ? "authorized" : "none",
+        };
+        pack.#clients.push({ ...opened, status, renewing: undefined, refused: undefined });
+        pack.#status.push(status);
+      } catch (error) {
+        if (error instanceof McpUnauthorized) {
+          options.onNotice?.(`MCP server "${ref.name}" needs signing in — /mcp login ${ref.name}`);
+          pack.#status.push({ ...base, tools: [], auth: "required" });
+          continue;
+        }
+        // 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)}`);
+        pack.#status.push({ ...base, tools: [], error: String(error) });
+      }
+    }
+    return pack;
+  }
+
+  // A token refused before its stated expiry, or issued with none, gets one refresh before a sign-in is asked for.
+  static async #openRefreshing(
+    ref: CodeAgentMcpServerRef,
+    token: string | undefined,
+    onNotice: ((message: string) => void) | undefined,
+  ) {
+    try {
+      return await McpToolPack.#open(ref, token);
+    } catch (error) {
+      if (!(error instanceof McpUnauthorized) || !token) throw error;
+      const retry = await McpSignIn.retryToken(ref, token, onNotice);
+      if (!retry) throw error;
+      return await McpToolPack.#open(ref, retry);
+    }
+  }
+
+  static async #open(ref: CodeAgentMcpServerRef, token: string | undefined) {
+    const client = await new McpClient(ref, token).connect();
+    return { client, tools: await client.listTools(), token };
+  }
+
+  get toolNames() {
+    return this.#clients.flatMap(({ client, tools }) =>
+      tools.map((tool) => McpToolPack.#nameOf(client.ref.name, tool.name)),
+    );
+  }
+
+  get status(): CodeAgentMcpStatus[] {
+    return this.#status;
+  }
+
+  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 server of this.#clients)
+      for (const tool of server.tools) {
+        const name = McpToolPack.#nameOf(server.client.ref.name, tool.name);
+        const description = tool.description ?? tool.name;
+        pi.registerTool({
+          name,
+          label: `${server.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 this.#call(server, tool.name, params ?? {});
+            return {
+              content: [{ type: "text", text: codeAgentClip(result.text, codeAgentOutputChars) }],
+              details: undefined,
+              isError: result.isError,
+            };
+          },
+        });
+      }
+  }
+
+  async #call(server: McpToolPackServer, tool: string, args: Record<string, unknown>) {
+    const client = server.client;
+    try {
+      return await client.callTool(tool, args);
+    } catch (error) {
+      if (!(error instanceof McpUnauthorized)) throw error;
+    }
+    const renewed = await this.#renewed(server, client);
+    try {
+      if (renewed) return await renewed.callTool(tool, args);
+    } catch (error) {
+      if (!(error instanceof McpUnauthorized)) throw error;
+      McpToolPack.#refuse(server, renewed);
+    }
+    throw new Error(`MCP server "${client.ref.name}" needs signing in — /mcp login ${client.ref.name}`);
+  }
+
+  // Reported as a failed connect is; only a new pack, after `/mcp login` or `/mcp reload`, reads `authorized` again.
+  static #refuse(server: McpToolPackServer, client: McpClient | undefined) {
+    server.refused = client;
+    server.status.auth = "required";
+  }
+
+  // One refresh per refused token, shared by every call it refused; a server that refuses every token costs one.
+  async #renewed(server: McpToolPackServer, refused: McpClient) {
+    if (server.client === refused && server.refused !== refused)
+      server.renewing ??= this.#renew(server, refused).finally(() => {
+        server.renewing = undefined;
+      });
+    if (server.renewing) return await server.renewing;
+    return server.client === server.refused ? undefined : server.client;
+  }
+
+  async #renew(server: McpToolPackServer, refused: McpClient) {
+    const token = server.token ? await McpSignIn.retryToken(refused.ref, server.token, this.#onNotice) : undefined;
+    const client = token ? await McpToolPack.#reopen(refused.ref, token) : undefined;
+    if (!client) {
+      McpToolPack.#refuse(server, refused);
+      return undefined;
+    }
+    refused.close();
+    server.client = client;
+    server.token = token;
+    return client;
+  }
+
+  // A new client, so a new streamable HTTP session: a server may bind its session to the token that opened it.
+  static async #reopen(ref: CodeAgentMcpServerRef, token: string) {
+    try {
+      return await new McpClient(ref, token).connect();
+    } catch (error) {
+      if (error instanceof McpUnauthorized) return undefined;
+      throw error;
+    }
+  }
+
+  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 [...McpServerConfig.read(options.workspaceRoot), ...declared];
+  }
+}

package/codeAgent/tools/SessionToolPack.ts

@@ -0,0 +1,91 @@
+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;
+
+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);
+  }
+
+  // This workspace's directory only: a global list would reach another checkout's conversations.
+  async #list(): Promise<SessionInfo[]> {
+    return await SessionManager.list(this.#options.cwd, akanCodePaths.sessionsDir(this.#options.workspaceRoot));
+  }
+}

package/codeAgent/tools/WebToolPack.ts

@@ -0,0 +1,147 @@
+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_search only with a provider key set: a tool that can never work costs prompt tokens and invites retries.
+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();
+  }
+}