@sammorrowdrums/mcpi-ext 0.1.0

package/src/code-mode/index.ts

@@ -0,0 +1,208 @@
+import type { McpClientManager, McpTool } from "../mcp/index.js";
+import { getEligibleTools } from "./eligibility.js";
+import type { ExecuteResult, ExecutorOptions } from "./executor.js";
+import { executeInSandbox } from "./executor.js";
+import { createCodeExecuteTool, createCodeSearchTool } from "./tools.js";
+import { generateTypeHints } from "./type-hints.js";
+
+export { getEligibleTools, isEligibleForCodeMode } from "./eligibility.js";
+export type { ExecuteResult, ExecutorOptions } from "./executor.js";
+export { executeInSandbox, normalizeCode } from "./executor.js";
+export { createCodeExecuteTool, createCodeSearchTool } from "./tools.js";
+export { generateTypeHints, jsonSchemaToTypeString, sanitizeToolName } from "./type-hints.js";
+
+export interface CodeModeManagerOptions extends ExecutorOptions {
+  /** Log function for status messages. */
+  log?: (msg: string) => void;
+}
+
+/**
+ * Orchestrates code mode: discovers eligible tools, generates type hints,
+ * and executes model-generated code in a sandbox with tool dispatch.
+ */
+export class CodeModeManager {
+  private mcpManager: McpClientManager | null = null;
+  private eligibleTools: McpTool[] = [];
+  private typeHints = "";
+  private options: CodeModeManagerOptions;
+
+  constructor(options: CodeModeManagerOptions = {}) {
+    this.options = options;
+  }
+
+  /** Initialize with MCP manager, discover eligible tools, generate type hints. */
+  initialize(mcpManager: McpClientManager): void {
+    this.mcpManager = mcpManager;
+    this.refresh();
+  }
+
+  /** Refresh eligible tools and type hints (call on tools/list_changed). */
+  refresh(): void {
+    if (!this.mcpManager) return;
+    this.eligibleTools = getEligibleTools(this.mcpManager);
+    this.typeHints = generateTypeHints(this.eligibleTools);
+    this.options.log?.(
+      `[code-mode] ${this.eligibleTools.length} eligible tool(s), ${this.typeHints.length} chars of type hints`,
+    );
+  }
+
+  /** Get the type hints string for injection into system prompt. */
+  getTypeHints(): string {
+    return this.typeHints;
+  }
+
+  /** Get eligible tools. */
+  getEligibleTools(): McpTool[] {
+    return this.eligibleTools;
+  }
+
+  /** Whether code mode has any eligible tools. */
+  get isActive(): boolean {
+    return this.eligibleTools.length > 0;
+  }
+
+  /** Execute code in search mode (tool catalog queries). */
+  async searchTools(code: string): Promise<ExecuteResult> {
+    return this.execute(code);
+  }
+
+  /** Execute code that chains MCP tool calls. */
+  async executeCode(code: string): Promise<ExecuteResult> {
+    return this.execute(code);
+  }
+
+  /** Create the Pi tool definitions for code_search and code_execute. */
+  createTools() {
+    return {
+      codeSearch: createCodeSearchTool(this),
+      codeExecute: createCodeExecuteTool(this),
+    };
+  }
+
+  /** Format a system prompt section for code mode. */
+  formatSystemPromptSection(): string {
+    if (!this.isActive) return "";
+
+    return [
+      "",
+      "<code_mode>",
+      "## Code mode",
+      "",
+      "`code_execute` runs vanilla JavaScript in a sandboxed V8 isolate. Use it for:",
+      "",
+      "1. **Arbitrary computation** — math, string manipulation, date arithmetic, data transformation,",
+      "   or any calculation the user asks for. No MCP tools needed; plain JS works.",
+      "2. **Multi-tool aggregation** — counting, filtering, trending, or transforming results across",
+      "   many tool calls. Write a loop inside one `code_execute` instead of making many separate tool calls.",
+      "3. **Pagination** — fetch batches in a loop until exhausted, then compute over the full dataset.",
+      "",
+      "Use `code_search` first to discover what tools are available before writing execution code.",
+      "",
+      "**Code mode tools are always available — you do not need to call `load_skill` first.**",
+      "",
+      "### Choosing the right approach",
+      "",
+      "- **Skill** (`load_skill`) — a curated workflow exists for this domain task (e.g., a GitHub skill for PR management).",
+      "- **tool-cli** — you need to discover what tools exist, or make a quick ad-hoc tool call.",
+      "- **Code mode** (`code_execute`) — you need computation: math, aggregation, looping over results,",
+      "  data transformation, or chaining multiple tool calls with logic in between.",
+      "",
+      "Pick based on what the task needs, not a fixed order. A calculation goes straight to code mode;",
+      "a single lookup goes to a skill or tool-cli; exploration starts with tool-cli or `code_search`.",
+      "",
+      "**If unsure what's available**, start with `code_search` or `tool-cli --help` to see what you have.",
+      "After producing a result, verify it makes sense — run a quick sanity check or spot-check values.",
+      "",
+      "### How to write code",
+      "",
+      "Write vanilla JavaScript (not TypeScript, not Node.js). No `require`, `import`, `fetch`,",
+      "`fs`, `process`, or any Node.js/browser APIs. The only external API is the `codemode` namespace",
+      "for MCP tool calls (optional — pure computation works without it). Always `return` the final result.",
+      "",
+      "**Write ONE `code_execute` call that does the whole job.** Loops, comparisons, pagination,",
+      "and aggregation all happen inside a single execution.",
+      "",
+      "```javascript",
+      "// Pure computation — no tools needed",
+      "const factorial = (n) => n <= 1 ? 1 : n * factorial(n - 1);",
+      "return { result: factorial(20), formatted: factorial(20).toLocaleString() };",
+      "```",
+      "",
+      "```javascript",
+      "// Aggregate across paginated MCP tool results",
+      "const counts = {};",
+      "let page = 1;",
+      "while (true) {",
+      "  const result = await codemode.list_items({ page, perPage: 100 });",
+      "  for (const item of result.items) {",
+      "    counts[item.category] = (counts[item.category] || 0) + 1;",
+      "  }",
+      "  if (result.items.length < 100) break;",
+      "  page++;",
+      "}",
+      "return counts;",
+      "```",
+      "",
+      "### Available tools",
+      "",
+      "```typescript",
+      this.typeHints,
+      "```",
+      "</code_mode>",
+    ].join("\n");
+  }
+
+  private async execute(code: string): Promise<ExecuteResult> {
+    if (!this.mcpManager) {
+      return { result: undefined, error: "Code mode not initialized", logs: [] };
+    }
+
+    // Refresh eligible tools in case MCP servers changed since initialization
+    this.refresh();
+
+    const toolNames = this.eligibleTools.map((t) => t.name);
+
+    const dispatch = async (toolName: string, args: Record<string, unknown>) => {
+      const tool = this.eligibleTools.find((t) => t.name === toolName);
+      if (!tool) {
+        throw new Error(`Tool "${toolName}" not found in code mode eligible tools`);
+      }
+
+      const client = this.mcpManager?.getClient(tool.serverName);
+      if (!client) {
+        throw new Error(`MCP server "${tool.serverName}" is not connected`);
+      }
+
+      const result = await client.callTool({ name: toolName, arguments: args });
+
+      // Prefer structuredContent (typed output) over raw content
+      if (result.structuredContent) {
+        return result.structuredContent;
+      }
+
+      // Fall back to parsing text content
+      if (Array.isArray(result.content)) {
+        const textParts = result.content
+          .filter(
+            (c): c is { type: string; text: string } =>
+              typeof c === "object" && c !== null && "text" in c,
+          )
+          .map((c) => c.text);
+
+        const combined = textParts.join("\n");
+        try {
+          return JSON.parse(combined);
+        } catch {
+          return combined;
+        }
+      }
+
+      return result;
+    };
+
+    return executeInSandbox(code, toolNames, dispatch, {
+      memoryLimit: this.options.memoryLimit,
+      timeoutMs: this.options.timeoutMs,
+    });
+  }
+}

package/src/code-mode/tools.ts

@@ -0,0 +1,110 @@
+import type { AgentToolResult, ExtensionContext } from "@sammorrowdrums/mcpi";
+import { Type, type Static } from "typebox";
+import type { ExecuteResult } from "./executor.js";
+import type { CodeModeManager } from "./index.js";
+
+const CodeInput = Type.Object({
+  code: Type.String({
+    description:
+      "JavaScript code to execute. Use the `codemode` namespace to call tools (e.g. `codemode.search_docs({ query: 'test' })`). Always `return` your final result. Code runs in a sandbox with no access to filesystem, network, or Node.js APIs.",
+  }),
+});
+
+type CodeInputType = Static<typeof CodeInput>;
+
+export interface CodeModeToolDetails {
+  executionMs: number;
+  logs: string[];
+  error?: string;
+}
+
+/** Format an ExecuteResult into a tool response. Falls back to logs if result is undefined. */
+function formatResult(
+  result: ExecuteResult,
+  executionMs: number,
+  errorPrefix: string,
+): AgentToolResult<CodeModeToolDetails> {
+  if (result.error) {
+    return {
+      content: [{ type: "text", text: `${errorPrefix}: ${result.error}` }],
+      details: { executionMs, logs: result.logs, error: result.error },
+    };
+  }
+
+  // If code didn't return a value, fall back to captured console output
+  const output =
+    result.result !== undefined && result.result !== null
+      ? typeof result.result === "string"
+        ? result.result
+        : JSON.stringify(result.result, null, 2)
+      : result.logs.length > 0
+        ? result.logs.join("\n")
+        : "(no return value)";
+
+  const logsSection =
+    result.result !== undefined && result.logs.length > 0
+      ? `\n\nLogs:\n${result.logs.join("\n")}`
+      : "";
+
+  return {
+    content: [{ type: "text", text: output + logsSection }],
+    details: { executionMs, logs: result.logs },
+  };
+}
+
+/**
+ * Create the `code_search` tool for querying the tool catalog.
+ *
+ * The model writes JavaScript to discover and filter available tools.
+ * The sandbox provides `codemode.listTools()` and `codemode.describeTools(names)`.
+ */
+export function createCodeSearchTool(manager: CodeModeManager) {
+  return {
+    name: "code_search",
+    label: "Code Search",
+    description:
+      "Discover available read-only MCP tools by writing JavaScript. Use `codemode.listTools()` to list tools and `codemode.describeTools(names)` for type info. Use this before code_execute to understand what data sources are available.",
+    parameters: CodeInput,
+
+    async execute(
+      _toolCallId: string,
+      params: CodeInputType,
+      _signal: AbortSignal | undefined,
+      _onUpdate: undefined,
+      _ctx: ExtensionContext,
+    ): Promise<AgentToolResult<CodeModeToolDetails>> {
+      const start = performance.now();
+      const result = await manager.searchTools(params.code);
+      return formatResult(result, Math.round(performance.now() - start), "Code search error");
+    },
+  };
+}
+
+/**
+ * Create the `code_execute` tool for chaining tool calls.
+ *
+ * The model writes JavaScript that calls read-only MCP tools via
+ * the `codemode` namespace (e.g. `codemode.search_docs({ query: 'test' })`).
+ * Code runs in a sandbox with no access to filesystem, network, or Node.js APIs.
+ */
+export function createCodeExecuteTool(manager: CodeModeManager) {
+  return {
+    name: "code_execute",
+    label: "Code Execute",
+    description:
+      "Execute JavaScript that chains read-only MCP tool calls for computation over data. Use when you need to aggregate, filter, loop, or transform results across multiple tool calls. Access tools via `codemode.toolName(args)`. Runs in a sandbox — no filesystem, network, or Node.js API access.",
+    parameters: CodeInput,
+
+    async execute(
+      _toolCallId: string,
+      params: CodeInputType,
+      _signal: AbortSignal | undefined,
+      _onUpdate: undefined,
+      _ctx: ExtensionContext,
+    ): Promise<AgentToolResult<CodeModeToolDetails>> {
+      const start = performance.now();
+      const result = await manager.executeCode(params.code);
+      return formatResult(result, Math.round(performance.now() - start), "Code execution error");
+    },
+  };
+}

package/src/code-mode/type-hints.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, it } from "vitest";
+import type { McpTool } from "../mcp/index.js";
+import { generateTypeHints, jsonSchemaToTypeString, sanitizeToolName } from "./type-hints.js";
+
+describe("jsonSchemaToTypeString", () => {
+  it("converts string type", () => {
+    expect(jsonSchemaToTypeString({ type: "string" })).toBe("string");
+  });
+
+  it("converts number type", () => {
+    expect(jsonSchemaToTypeString({ type: "number" })).toBe("number");
+  });
+
+  it("converts integer type", () => {
+    expect(jsonSchemaToTypeString({ type: "integer" })).toBe("number");
+  });
+
+  it("converts boolean type", () => {
+    expect(jsonSchemaToTypeString({ type: "boolean" })).toBe("boolean");
+  });
+
+  it("converts null type", () => {
+    expect(jsonSchemaToTypeString({ type: "null" })).toBe("null");
+  });
+
+  it("converts type array", () => {
+    expect(jsonSchemaToTypeString({ type: ["string", "null"] })).toBe("string | null");
+  });
+
+  it("converts enum to union", () => {
+    expect(jsonSchemaToTypeString({ enum: ["a", "b", "c"] })).toBe('"a" | "b" | "c"');
+  });
+
+  it("converts const", () => {
+    expect(jsonSchemaToTypeString({ const: "fixed" })).toBe('"fixed"');
+  });
+
+  it("converts simple object", () => {
+    const result = jsonSchemaToTypeString({
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        age: { type: "number" },
+      },
+      required: ["name"],
+    });
+    expect(result).toContain("name: string;");
+    expect(result).toContain("age?: number;");
+  });
+
+  it("converts empty object to Record", () => {
+    expect(jsonSchemaToTypeString({ type: "object" })).toBe("Record<string, unknown>");
+  });
+
+  it("converts array with items", () => {
+    expect(jsonSchemaToTypeString({ type: "array", items: { type: "string" } })).toBe("string[]");
+  });
+
+  it("converts array without items", () => {
+    expect(jsonSchemaToTypeString({ type: "array" })).toBe("unknown[]");
+  });
+
+  it("handles anyOf", () => {
+    const result = jsonSchemaToTypeString({
+      anyOf: [{ type: "string" }, { type: "number" }],
+    });
+    expect(result).toBe("string | number");
+  });
+
+  it("handles oneOf", () => {
+    const result = jsonSchemaToTypeString({
+      oneOf: [{ type: "boolean" }, { type: "null" }],
+    });
+    expect(result).toBe("boolean | null");
+  });
+
+  it("handles allOf", () => {
+    const result = jsonSchemaToTypeString({
+      allOf: [
+        { type: "object", properties: { a: { type: "string" } }, required: ["a"] },
+        { type: "object", properties: { b: { type: "number" } }, required: ["b"] },
+      ],
+    });
+    expect(result).toContain("a: string;");
+    expect(result).toContain("b: number;");
+    expect(result).toContain("&");
+  });
+
+  it("resolves $ref", () => {
+    const result = jsonSchemaToTypeString(
+      { $ref: "#/definitions/Foo" },
+      { Foo: { type: "string" } },
+    );
+    expect(result).toBe("string");
+  });
+
+  it("handles unknown $ref gracefully", () => {
+    expect(jsonSchemaToTypeString({ $ref: "#/definitions/Missing" }, {})).toBe("unknown");
+  });
+
+  it("guards against deep recursion", () => {
+    // Create a deeply nested schema
+    let schema: Record<string, unknown> = { type: "string" };
+    for (let i = 0; i < 25; i++) {
+      schema = { type: "object", properties: { nested: schema }, required: ["nested"] };
+    }
+    const result = jsonSchemaToTypeString(schema);
+    expect(result).toContain("unknown"); // Should hit depth guard
+  });
+
+  it("includes description as JSDoc in object properties", () => {
+    const result = jsonSchemaToTypeString({
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search term" },
+      },
+      required: ["query"],
+    });
+    expect(result).toContain("/** Search term */");
+  });
+});
+
+describe("sanitizeToolName", () => {
+  it("replaces hyphens with underscores", () => {
+    expect(sanitizeToolName("list-issues")).toBe("list_issues");
+  });
+
+  it("replaces dots with underscores", () => {
+    expect(sanitizeToolName("github.search")).toBe("github_search");
+  });
+
+  it("keeps valid identifiers unchanged", () => {
+    expect(sanitizeToolName("searchDocs")).toBe("searchDocs");
+  });
+});
+
+describe("generateTypeHints", () => {
+  it("returns empty string for no tools", () => {
+    expect(generateTypeHints([])).toBe("");
+  });
+
+  it("generates declaration for a simple tool", () => {
+    const tools: McpTool[] = [
+      {
+        name: "search_docs",
+        description: "Search documentation",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "Search term" },
+          },
+          required: ["query"],
+        },
+        outputSchema: {
+          type: "object",
+          properties: {
+            results: { type: "array", items: { type: "string" } },
+          },
+          required: ["results"],
+        },
+        serverName: "docs",
+      },
+    ];
+
+    const result = generateTypeHints(tools);
+    expect(result).toContain("declare const codemode");
+    expect(result).toContain("search_docs:");
+    expect(result).toContain("Promise<");
+    expect(result).toContain("listTools");
+    expect(result).toContain("describeTools");
+  });
+
+  it("sanitizes tool names with special characters", () => {
+    const tools: McpTool[] = [
+      {
+        name: "github.list-repos",
+        description: "List repos",
+        inputSchema: { type: "object", properties: {} },
+        outputSchema: { type: "object", properties: {} },
+        serverName: "github",
+      },
+    ];
+
+    const result = generateTypeHints(tools);
+    expect(result).toContain("github_list_repos:");
+  });
+});