@sammorrowdrums/mcpi-ext 0.2.0 → 0.2.1

package/src/code-mode/executor.test.ts

@@ -1,168 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { executeInSandbox, normalizeCode } from "./executor.js";
-
-describe("normalizeCode", () => {
-  it("strips markdown code fences", () => {
-    expect(normalizeCode("```js\nconst x = 1;\n```")).toBe("const x = 1;");
-  });
-
-  it("strips typescript fences", () => {
-    expect(normalizeCode("```typescript\nconst x = 1;\n```")).toBe("const x = 1;");
-  });
-
-  it("wraps arrow function in invocation", () => {
-    expect(normalizeCode("async () => { return 42; }")).toBe(
-      "return (async () => { return 42; })();",
-    );
-  });
-
-  it("wraps function declaration in invocation", () => {
-    const code = "async function main() { return 42; }";
-    const result = normalizeCode(code);
-    expect(result).toContain("async function main()");
-    expect(result).toContain("return main();");
-  });
-
-  it("strips export default", () => {
-    const result = normalizeCode("export default async () => { return 42; }");
-    expect(result).toContain("return (async () => { return 42; })();");
-  });
-
-  it("leaves bare code as-is", () => {
-    expect(normalizeCode("const x = 1;\nreturn x;")).toBe("const x = 1;\nreturn x;");
-  });
-});
-
-describe("executeInSandbox", () => {
-  it("executes simple code and returns result", async () => {
-    const result = await executeInSandbox("return 2 + 2;", [], async () => ({}), {
-      timeoutMs: 5000,
-    });
-
-    expect(result.result).toBe(4);
-    expect(result.error).toBeUndefined();
-  });
-
-  it("captures console.log output", async () => {
-    const result = await executeInSandbox(
-      'console.log("hello", "world"); return 1;',
-      [],
-      async () => ({}),
-      { timeoutMs: 5000 },
-    );
-
-    expect(result.result).toBe(1);
-    expect(result.logs).toContain("hello world");
-  });
-
-  it("dispatches tool calls through the callback", async () => {
-    const dispatched: { name: string; args: Record<string, unknown> }[] = [];
-
-    const dispatch = async (name: string, args: Record<string, unknown>) => {
-      dispatched.push({ name, args });
-      return { results: ["doc1", "doc2"] };
-    };
-
-    const code = `
-      const result = await codemode.search_docs({ query: "test" });
-      return result;
-    `;
-
-    const result = await executeInSandbox(code, ["search_docs"], dispatch, { timeoutMs: 5000 });
-
-    expect(result.error).toBeUndefined();
-    expect(result.result).toEqual({ results: ["doc1", "doc2"] });
-    expect(dispatched).toHaveLength(1);
-    expect(dispatched[0].name).toBe("search_docs");
-    expect(dispatched[0].args).toEqual({ query: "test" });
-  });
-
-  it("handles tools with special characters in names", async () => {
-    const dispatched: string[] = [];
-
-    const dispatch = async (name: string) => {
-      dispatched.push(name);
-      return { ok: true };
-    };
-
-    const code = `
-      const result = await codemode.github_list_repos({});
-      return result;
-    `;
-
-    const result = await executeInSandbox(code, ["github.list-repos"], dispatch, {
-      timeoutMs: 5000,
-    });
-
-    expect(result.error).toBeUndefined();
-    expect(dispatched).toContain("github.list-repos");
-  });
-
-  it("returns error for invalid code", async () => {
-    const result = await executeInSandbox("throw new Error('boom');", [], async () => ({}), {
-      timeoutMs: 5000,
-    });
-
-    expect(result.error).toContain("boom");
-    expect(result.result).toBeUndefined();
-  });
-
-  it("enforces timeout", async () => {
-    const result = await executeInSandbox("while(true) {}", [], async () => ({}), {
-      timeoutMs: 100,
-    });
-
-    expect(result.error).toBeDefined();
-    expect(result.result).toBeUndefined();
-  });
-
-  it("chains multiple tool calls", async () => {
-    const calls: string[] = [];
-
-    const dispatch = async (name: string, args: Record<string, unknown>) => {
-      calls.push(name);
-      if (name === "list_items") return { items: ["a", "b", "c"] };
-      if (name === "get_details") return { detail: `info for ${args.id}` };
-      return {};
-    };
-
-    const code = `
-      const { items } = await codemode.list_items({});
-      const details = [];
-      for (const id of items) {
-        const d = await codemode.get_details({ id });
-        details.push(d.detail);
-      }
-      return details;
-    `;
-
-    const result = await executeInSandbox(code, ["list_items", "get_details"], dispatch, {
-      timeoutMs: 5000,
-    });
-
-    expect(result.error).toBeUndefined();
-    expect(result.result).toEqual(["info for a", "info for b", "info for c"]);
-    expect(calls).toEqual(["list_items", "get_details", "get_details", "get_details"]);
-  });
-
-  it("prevents imports", async () => {
-    const code = 'import("fs")';
-    const result = await executeInSandbox(code, [], async () => ({}), { timeoutMs: 5000 });
-
-    expect(result.error).toBeDefined();
-  });
-
-  it("listTools returns available tools", async () => {
-    const code = `
-      const tools = await codemode.listTools();
-      return tools;
-    `;
-
-    const result = await executeInSandbox(code, ["search", "execute"], async () => ({}), {
-      timeoutMs: 5000,
-    });
-
-    expect(result.error).toBeUndefined();
-    expect(result.result).toEqual(["search", "execute"]);
-  });
-});

package/src/code-mode/executor.ts

@@ -1,163 +0,0 @@
-import ivm from "isolated-vm";
-import { sanitizeToolName } from "./type-hints.js";
-
-/** Result of code execution. */
-export interface ExecuteResult {
-  result: unknown;
-  error?: string;
-  logs: string[];
-}
-
-/** A function the sandbox can call to invoke an MCP tool. */
-export type ToolDispatchFn = (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
-
-export interface ExecutorOptions {
-  /** Memory limit in MB for the V8 isolate. Default: 128. */
-  memoryLimit?: number;
-  /** Execution timeout in milliseconds. Default: 30000. */
-  timeoutMs?: number;
-}
-
-const DEFAULT_MEMORY_LIMIT = 128;
-const DEFAULT_TIMEOUT_MS = 30_000;
-
-/**
- * Execute model-generated JavaScript code in an isolated V8 sandbox.
- *
- * The code runs in a fresh `isolated-vm` isolate with:
- * - Enforced memory limit (default 128MB)
- * - Execution timeout (default 30s)
- * - No access to Node.js APIs, filesystem, or network
- * - Only access to provided tool dispatch functions via `codemode.*` proxy
- *
- * Tool calls are dispatched to the host via `Reference` callbacks —
- * actual MCP tool execution happens outside the sandbox.
- */
-export async function executeInSandbox(
-  code: string,
-  toolNames: string[],
-  dispatch: ToolDispatchFn,
-  options: ExecutorOptions = {},
-): Promise<ExecuteResult> {
-  const memoryLimit = options.memoryLimit ?? DEFAULT_MEMORY_LIMIT;
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-
-  const isolate = new ivm.Isolate({ memoryLimit });
-  try {
-    return await runInIsolate(isolate, code, toolNames, dispatch, timeoutMs);
-  } finally {
-    isolate.dispose();
-  }
-}
-
-async function runInIsolate(
-  isolate: ivm.Isolate,
-  code: string,
-  toolNames: string[],
-  dispatch: ToolDispatchFn,
-  timeoutMs: number,
-): Promise<ExecuteResult> {
-  const ctx = await isolate.createContext();
-  const jail = ctx.global;
-
-  const logs: string[] = [];
-
-  // Inject console.log that captures to logs array
-  const logCallback = new ivm.Callback((...args: unknown[]) => {
-    logs.push(args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" "));
-  });
-  await jail.set("__log", logCallback);
-
-  // Inject tool dispatcher Reference (async callback)
-  const dispatchRef = new ivm.Reference(async (toolName: string, argsJson: string) => {
-    const args = JSON.parse(argsJson) as Record<string, unknown>;
-    const result = await dispatch(toolName, args);
-    return JSON.stringify(result === undefined ? null : result);
-  });
-  await jail.set("__dispatch", dispatchRef);
-
-  // Build the tool call helper and codemode proxy as setup code
-  const toolProxyEntries = toolNames
-    .map((name) => {
-      const safe = sanitizeToolName(name);
-      return `    ${safe}: async (args) => __callTool(${JSON.stringify(name)}, args)`;
-    })
-    .join(",\n");
-
-  const normalized = normalizeCode(code);
-
-  // Use ctx.eval with { promise: true } instead of compileModule,
-  // because module.evaluate() can resolve prematurely with multiple
-  // sequential async Reference.apply calls.
-  const wrappedCode = `
-    (async () => {
-      const console = { log: (...args) => __log(args.map(a => typeof a === 'string' ? a : JSON.stringify(a)).join(' ')) };
-      const __callTool = async (name, args) => {
-        const r = await __dispatch.apply(undefined, [name, JSON.stringify(args ?? {})], { arguments: { copy: true }, result: { promise: true, copy: true } });
-        return JSON.parse(r);
-      };
-      const codemode = {
-        listTools: async () => ${JSON.stringify(toolNames)},
-        describeTools: async (names) => "Use the typed codemode.toolName(args) methods instead.",
-${toolProxyEntries}
-      };
-
-      const __userFn = async () => {
-        ${normalized}
-      };
-
-      return JSON.stringify({ value: await __userFn() });
-    })()
-  `;
-
-  try {
-    const rawResult = (await ctx.eval(wrappedCode, {
-      promise: true,
-      copy: true,
-      timeout: timeoutMs,
-    })) as string;
-
-    const parsed = JSON.parse(rawResult) as { value: unknown };
-    return { result: parsed.value, logs };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { result: undefined, error: message, logs };
-  }
-}
-
-/**
- * Normalize model-generated code:
- * - Strip markdown code fences
- * - Handle arrow functions, function declarations, export default
- * - Otherwise leave code as a statement block; callers must explicitly `return` a value
- */
-export function normalizeCode(code: string): string {
-  let normalized = code.trim();
-
-  // Strip markdown code fences
-  normalized = normalized.replace(/^```(?:js|javascript|typescript|ts)?\s*\n?/i, "");
-  normalized = normalized.replace(/\n?```\s*$/i, "");
-  normalized = normalized.trim();
-
-  // If it's an arrow function or function expression, invoke it
-  if (/^(?:async\s+)?(?:\([^)]*\)|[a-zA-Z_$][a-zA-Z0-9_$]*)\s*=>/.test(normalized)) {
-    return `return (${normalized})();`;
-  }
-
-  // If it's a function declaration, invoke it
-  if (/^(?:async\s+)?function\s+/.test(normalized)) {
-    const match = normalized.match(/^(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/);
-    if (match) {
-      return `${normalized}\nreturn ${match[1]}();`;
-    }
-  }
-
-  // If it starts with export default, strip the export default
-  if (/^export\s+default\s+/.test(normalized)) {
-    normalized = normalized.replace(/^export\s+default\s+/, "");
-    return `return (${normalized})();`;
-  }
-
-  // Otherwise, treat as a code block — return the last expression
-  return normalized;
-}

package/src/code-mode/index.ts

@@ -1,208 +0,0 @@
-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

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