pi-codemcp 0.1.0

package/src/output.ts

@@ -0,0 +1,52 @@
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+  truncateHead,
+} from "@earendil-works/pi-coding-agent";
+
+export interface CodeMcpOutputDetails {
+  truncated: boolean;
+  outputBytes: number;
+  totalBytes: number;
+  outputLines: number;
+  totalLines: number;
+  outputTokens: number;
+}
+
+export interface CodeMcpOutputLimits {
+  maxBytes?: number;
+  maxLines?: number;
+}
+
+export function formatCodeMcpOutput(
+  value: unknown,
+  limits: CodeMcpOutputLimits = {},
+): {
+  text: string;
+  details: CodeMcpOutputDetails;
+} {
+  const serialized = JSON.stringify(value, null, 2);
+  const truncation = truncateHead(serialized, {
+    maxBytes: limits.maxBytes ?? DEFAULT_MAX_BYTES,
+    maxLines: limits.maxLines ?? DEFAULT_MAX_LINES,
+  });
+  let text = truncation.content;
+  if (truncation.truncated) {
+    text +=
+      `\n\n[Output truncated: showing ${truncation.outputLines} of ` +
+      `${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ` +
+      `${formatSize(truncation.totalBytes)}). The full result was not persisted.]`;
+  }
+  return {
+    text,
+    details: {
+      truncated: truncation.truncated,
+      outputBytes: truncation.outputBytes,
+      totalBytes: truncation.totalBytes,
+      outputLines: truncation.outputLines,
+      totalLines: truncation.totalLines,
+      outputTokens: Math.ceil(text.length / 4),
+    },
+  };
+}

package/src/settings.ts

@@ -0,0 +1,144 @@
+import { existsSync } from "node:fs";
+import { readJsonObject, requireJsonObject, writeJsonObjectAtomically } from "./json-file.js";
+
+export interface CodeMcpSettings {
+  backgroundWarmup: boolean;
+  cacheTtlHours: number;
+  executionTimeoutSeconds: number;
+  toolTimeoutSeconds: number;
+  maxCalls: number;
+  resultLimitKiB: number;
+  outputLimitKiB: number;
+  outputLineLimit: number;
+  disabledTools: Record<string, string[]>;
+}
+
+export type EditableSettingKey = Exclude<keyof CodeMcpSettings, "disabledTools">;
+export type EditableSettingValue = boolean | number;
+
+export const DEFAULT_CODEMCP_SETTINGS: Readonly<CodeMcpSettings> = {
+  backgroundWarmup: true,
+  cacheTtlHours: 24,
+  executionTimeoutSeconds: 30,
+  toolTimeoutSeconds: 30,
+  maxCalls: 50,
+  resultLimitKiB: 16,
+  outputLimitKiB: 50,
+  outputLineLimit: 2_000,
+  disabledTools: {},
+};
+
+const ALLOWED_KEYS = new Set([
+  "version",
+  "backgroundWarmup",
+  "cacheTtlHours",
+  "executionTimeoutSeconds",
+  "toolTimeoutSeconds",
+  "maxCalls",
+  "resultLimitKiB",
+  "outputLimitKiB",
+  "outputLineLimit",
+  "disabledTools",
+]);
+
+export function loadCodeMcpSettings(path: string): CodeMcpSettings {
+  if (!existsSync(path)) return cloneDefaults();
+  const root = readJsonObject(path, "CodeMCP settings");
+  const unknown = Object.keys(root).filter((key) => !ALLOWED_KEYS.has(key));
+  if (unknown.length > 0) {
+    throw new Error(`Unknown CodeMCP settings: ${unknown.join(", ")}`);
+  }
+  const version = root.version ?? 1;
+  if (version !== 1) throw new Error(`Unsupported CodeMCP settings version: ${String(version)}`);
+
+  return {
+    backgroundWarmup: booleanSetting(root, "backgroundWarmup"),
+    cacheTtlHours: integerSetting(root, "cacheTtlHours", 0, 720),
+    executionTimeoutSeconds: integerSetting(root, "executionTimeoutSeconds", 1, 300),
+    toolTimeoutSeconds: integerSetting(root, "toolTimeoutSeconds", 1, 300),
+    maxCalls: integerSetting(root, "maxCalls", 1, 200),
+    resultLimitKiB: integerSetting(root, "resultLimitKiB", 1, 1_024),
+    outputLimitKiB: integerSetting(root, "outputLimitKiB", 1, 1_024),
+    outputLineLimit: integerSetting(root, "outputLineLimit", 1, 10_000),
+    disabledTools: disabledToolSetting(root.disabledTools),
+  };
+}
+
+export function saveCodeMcpSettings(path: string, settings: CodeMcpSettings): void {
+  writeJsonObjectAtomically(path, {
+    version: 1,
+    backgroundWarmup: settings.backgroundWarmup,
+    cacheTtlHours: settings.cacheTtlHours,
+    executionTimeoutSeconds: settings.executionTimeoutSeconds,
+    toolTimeoutSeconds: settings.toolTimeoutSeconds,
+    maxCalls: settings.maxCalls,
+    resultLimitKiB: settings.resultLimitKiB,
+    outputLimitKiB: settings.outputLimitKiB,
+    outputLineLimit: settings.outputLineLimit,
+    disabledTools: settings.disabledTools,
+  });
+}
+
+export function setEditableSetting(
+  settings: CodeMcpSettings,
+  key: EditableSettingKey,
+  value: EditableSettingValue,
+): CodeMcpSettings {
+  if (key === "backgroundWarmup") {
+    if (typeof value !== "boolean") throw new TypeError(`${key} must be a boolean`);
+    return { ...settings, [key]: value };
+  }
+  if (typeof value !== "number") throw new TypeError(`${key} must be a number`);
+  return { ...settings, [key]: value };
+}
+
+export function setToolEnabled(
+  settings: CodeMcpSettings,
+  server: string,
+  tool: string,
+  enabled: boolean,
+): CodeMcpSettings {
+  const disabled = new Set(settings.disabledTools[server] ?? []);
+  if (enabled) disabled.delete(tool);
+  else disabled.add(tool);
+  const disabledTools = { ...settings.disabledTools };
+  if (disabled.size === 0) delete disabledTools[server];
+  else disabledTools[server] = [...disabled].sort();
+  return { ...settings, disabledTools };
+}
+
+function cloneDefaults(): CodeMcpSettings {
+  return { ...DEFAULT_CODEMCP_SETTINGS, disabledTools: {} };
+}
+
+function booleanSetting(root: Record<string, unknown>, key: "backgroundWarmup"): boolean {
+  const value = root[key] ?? DEFAULT_CODEMCP_SETTINGS[key];
+  if (typeof value !== "boolean") throw new TypeError(`${key} must be a boolean`);
+  return value;
+}
+
+function integerSetting(
+  root: Record<string, unknown>,
+  key: Exclude<EditableSettingKey, "backgroundWarmup">,
+  minimum: number,
+  maximum: number,
+): number {
+  const value = root[key] ?? DEFAULT_CODEMCP_SETTINGS[key];
+  if (typeof value !== "number" || !Number.isInteger(value) || value < minimum || value > maximum) {
+    throw new TypeError(`${key} must be an integer from ${minimum} to ${maximum}`);
+  }
+  return value;
+}
+
+function disabledToolSetting(value: unknown): Record<string, string[]> {
+  if (value === undefined) return {};
+  const root = requireJsonObject(value, "disabledTools");
+  return Object.fromEntries(
+    Object.entries(root).map(([server, tools]) => {
+      if (!Array.isArray(tools) || tools.some((tool) => typeof tool !== "string")) {
+        throw new TypeError(`disabledTools.${server} must be an array of tool names`);
+      }
+      return [server, [...new Set(tools)].sort()];
+    }),
+  );
+}

package/src/tools.ts

@@ -0,0 +1,332 @@
+import { type ExtensionAPI, highlightCode, keyHint } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { type ChainScope, nativeChainToolName, type SavedChainManager } from "./chains.js";
+import {
+  getTextContent,
+  previewExecutionValue,
+  renderExecutionResult,
+} from "./execution-rendering.js";
+import type { CodeMcpLifecycle } from "./lifecycle.js";
+import { type CodeMcpOutputDetails, formatCodeMcpOutput } from "./output.js";
+
+interface SearchRenderDetails extends CodeMcpOutputDetails {
+  matchCount: number;
+  totalToolCount: number;
+  serverCount: number;
+  preview: string[];
+}
+
+const SearchParameters = Type.Object({
+  query: Type.String({
+    minLength: 1,
+    description: "Words describing an upstream capability, tool, or saved chain",
+  }),
+  limit: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: 20,
+      description: "Maximum compact matches to return (default 5)",
+    }),
+  ),
+  server: Type.Optional(
+    Type.String({
+      minLength: 1,
+      description: "Configured upstream server to search, or chains for saved chains",
+    }),
+  ),
+});
+
+const SaveChainParameters = Type.Object({
+  scope: Type.Optional(
+    Type.String({
+      enum: ["project", "global"],
+      description: "Storage scope for the chain (default project)",
+    }),
+  ),
+  name: Type.String({
+    minLength: 1,
+    maxLength: 64,
+    pattern: "^[a-z][a-z0-9_]{0,63}$",
+    description: "Stable lowercase SDK method name used as chains.<name>",
+  }),
+  description: Type.String({
+    minLength: 1,
+    maxLength: 1000,
+    description: "Purpose and appropriate use of the reusable native tool",
+  }),
+  code: Type.String({
+    minLength: 1,
+    description:
+      "Sandboxed Python body. Read typed arguments from input, call MCP or chains SDK methods, and return a value matching outputSchema.",
+  }),
+  inputSchema: Type.Record(Type.String(), Type.Unknown(), {
+    description: "JSON Schema for the native tool arguments; the root must be an object",
+  }),
+  outputSchema: Type.Record(Type.String(), Type.Unknown(), {
+    description: "Required JSON Schema for the chain return value",
+  }),
+});
+
+const ExecuteParameters = Type.Object({
+  code: Type.String({
+    minLength: 1,
+    description:
+      "Sandboxed Python body. Call typed SDK methods such as await linear.list_issues(arguments) and return a compact final value.",
+  }),
+});
+
+export function registerCodeMcpTools(
+  pi: ExtensionAPI,
+  lifecycle: CodeMcpLifecycle,
+  chains: SavedChainManager,
+): void {
+  pi.registerTool({
+    name: "codemcp_search",
+    label: "MCP Search",
+    description:
+      "Search configured upstream MCP tools and saved chains, returning their typed SDK stubs.",
+    promptSnippet: "Search MCP capabilities and reusable chains, then inspect typed SDK stubs",
+    promptGuidelines: [
+      "Use codemcp_search before codemcp_execute; every upstream or saved-chain match includes the complete typed SDK stub needed to write the execution.",
+    ],
+    parameters: SearchParameters,
+    async execute(_toolCallId, params, signal, onUpdate) {
+      onUpdate?.({
+        content: [{ type: "text", text: "Searching MCP tools..." }],
+        details: undefined,
+      });
+      const result = await lifecycle.request(
+        "search",
+        {
+          query: params.query,
+          limit: params.limit ?? 5,
+          ...(params.server === undefined ? {} : { server: params.server }),
+        },
+        signal,
+      );
+      const output = formatCodeMcpOutput(result, outputLimits(lifecycle));
+      const results = Array.isArray(result.results) ? result.results : [];
+      const preview = results
+        .slice(0, 3)
+        .map((item) => (isRecord(item) ? String(item.call ?? item.name ?? "unknown") : "unknown"));
+      const servers = Array.isArray(result.servers)
+        ? result.servers.flatMap((item) => {
+            if (!isRecord(item)) return [];
+            return [`${String(item.name)} ${String(item.tool_count ?? 0)}`];
+          })
+        : [];
+      return {
+        content: [{ type: "text", text: output.text }],
+        details: {
+          ...output.details,
+          matchCount: results.length,
+          totalToolCount: Number(result.total_tool_count ?? 0),
+          serverCount: servers.length,
+          preview,
+        },
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        `${theme.fg("toolTitle", theme.bold("MCP Search "))}${theme.fg("accent", `"${args.query}"`)}`,
+        0,
+        0,
+      );
+    },
+    renderResult(result, { expanded, isPartial }, theme) {
+      if (isPartial) return new Text(theme.fg("warning", "Searching catalog..."), 0, 0);
+      if (expanded) return renderExpandedJson(result.content);
+      const details = result.details as SearchRenderDetails | undefined;
+      let text = theme.fg(
+        "success",
+        `${details?.matchCount ?? 0} matches · ${details?.totalToolCount ?? 0} tools · ${details?.serverCount ?? 0} servers`,
+      );
+      for (const name of details?.preview ?? []) {
+        text += `\n${theme.fg("dim", `  ${name}`)}`;
+      }
+      text += `\n${theme.fg("muted", keyHint("app.tools.expand", "full results"))}`;
+      return new Text(text, 0, 0);
+    },
+  });
+
+  pi.registerTool({
+    name: "codemcp_execute",
+    label: "MCP Execute",
+    description:
+      "Type-check and execute one sandboxed Python MCP call graph. Supports sequential and dependent calls, loops, conditions, cross-server calls, enabled upstream tools, and reusable chains.* calls. The code has no host filesystem, environment, network, or subprocess access. Return a compact final value within the configured result limit; oversized values fail with a shape summary.",
+    promptSnippet: "Run a typed, sandboxed multi-call chain across configured MCP servers",
+    promptGuidelines: [
+      "Use codemcp_execute if you know tool schemas; call the returned server.method facade and use top-level return for the compact final value.",
+      "It is always better to execute multiple MCP calls in one codemcp_execute call rather than multiple single-call invocations.",
+      "You can compose upstream SDK calls and saved chains.* calls, running independent work with asyncio.gather or dependent work sequentially.",
+    ],
+    parameters: ExecuteParameters,
+    async execute(_toolCallId, params, signal, onUpdate) {
+      onUpdate?.({
+        content: [{ type: "text", text: "Type-checking MCP chain..." }],
+        details: undefined,
+      });
+      const result = await lifecycle.request("execute", { code: params.code }, signal);
+      const output = formatCodeMcpOutput(result, outputLimits(lifecycle));
+      const ok = result.ok === true;
+      return {
+        content: [{ type: "text", text: output.text }],
+        details: {
+          ...output.details,
+          ok,
+          failureStage: typeof result.failure_stage === "string" ? result.failure_stage : undefined,
+          callsMade: Number(result.calls_made ?? 0),
+          chainCalls: Number(result.chain_calls ?? 0),
+          preview: previewExecutionValue(ok ? result.result : result.error),
+        },
+      };
+    },
+    renderCall(args, theme, context) {
+      const code = args.code.trim();
+      const lineCount = code ? code.split("\n").length : 0;
+      const title = theme.fg("toolTitle", theme.bold("MCP Execute"));
+      const codeLabel = theme.fg(
+        "accent",
+        theme.bold(`Agent code · ${lineCount} ${lineCount === 1 ? "line" : "lines"}`),
+      );
+      if (context.expanded && code) {
+        return new Text(
+          `${title}\n${codeLabel}\n${highlightCode(code, "python").join("\n")}`,
+          0,
+          0,
+        );
+      }
+      const firstLine =
+        code
+          .split("\n")
+          .find((line) => line.trim())
+          ?.trim() ?? "";
+      return new Text(
+        `${title} ${theme.fg("muted", "·")} ${codeLabel}${firstLine ? `\n${theme.fg("dim", `  ${truncate(firstLine, 100)}`)}` : ""}`,
+        0,
+        0,
+      );
+    },
+    renderResult(result, state, theme) {
+      return renderExecutionResult(result, state, theme);
+    },
+  });
+
+  pi.registerTool({
+    name: "codemcp_save_chain",
+    label: "Save MCP Chain",
+    description:
+      "Validate and persist a reusable typed MCP chain in project scope by default or global scope when explicitly requested. Project chains override same-named global chains. The effective chain is immediately registered as a native mcp_chain_<name> tool and as chains.<name> inside CodeMCP. Requires explicit input and output JSON Schemas. Saving the same scoped name updates and re-enables it.",
+    promptSnippet: "Save a repeated MCP execution as a typed reusable native tool",
+    promptGuidelines: [
+      "If a user repeatedly performs the same MCP workflow, you may offer to save it with codemcp_save_chain, but do not persist it until the user explicitly asks or accepts.",
+      "Use codemcp_save_chain only after the user explicitly asks to save a chain or accepts your suggestion to do so.",
+      "When using codemcp_save_chain, parameterize repeated values through the typed input object and provide exact inputSchema and outputSchema contracts.",
+      "Save chains in project scope unless the user explicitly asks to make one available globally across projects.",
+    ],
+    parameters: SaveChainParameters,
+    async execute(_toolCallId, params, signal, onUpdate) {
+      onUpdate?.({
+        content: [{ type: "text", text: `Validating saved chain ${params.name}...` }],
+        details: undefined,
+      });
+      const scope = requireChainScope(params.scope ?? "project");
+      const view = await chains.save(
+        {
+          scope,
+          name: params.name,
+          description: params.description,
+          code: params.code,
+          inputSchema: params.inputSchema,
+          outputSchema: params.outputSchema,
+        },
+        signal,
+      );
+      const result = {
+        saved: true,
+        scope: view.scope,
+        name: view.chain.name,
+        native_tool: nativeChainToolName(view.chain.name),
+        call: `chains.${view.chain.name}`,
+        status: view.status,
+        dependencies: view.chain.dependencies.map((dependency) => dependency.call),
+      };
+      const output = formatCodeMcpOutput(result, outputLimits(lifecycle));
+      return {
+        content: [{ type: "text", text: output.text }],
+        details: {
+          ...output.details,
+          name: view.chain.name,
+          nativeTool: nativeChainToolName(view.chain.name),
+          dependencyCount: view.chain.dependencies.length,
+        },
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        `${theme.fg("toolTitle", theme.bold("Save MCP Chain "))}${theme.fg("accent", args.name)} ${theme.fg("muted", `· ${args.scope ?? "project"}`)}`,
+        0,
+        0,
+      );
+    },
+    renderResult(result, { expanded, isPartial }, theme, context) {
+      if (isPartial) return new Text(theme.fg("warning", "Validating chain contract..."), 0, 0);
+      const details = result.details as
+        | (CodeMcpOutputDetails & {
+            name: string;
+            nativeTool: string;
+            dependencyCount: number;
+          })
+        | undefined;
+      if (context.isError || !details) {
+        const message = getTextContent(result.content).trim();
+        if (expanded) {
+          return new Text(theme.fg("error", message || "Saved chain validation failed"), 0, 0);
+        }
+        const preview = message.split("\n", 1)[0];
+        return new Text(
+          theme.fg("error", `✗ Save failed${preview ? ` · ${truncate(preview, 120)}` : ""}`),
+          0,
+          0,
+        );
+      }
+      if (expanded) return renderExpandedJson(result.content);
+      return new Text(
+        theme.fg(
+          "success",
+          `✓ ${details.name} · ${details.nativeTool} · ${details.dependencyCount} dependencies`,
+        ),
+        0,
+        0,
+      );
+    },
+  });
+}
+
+function renderExpandedJson(content: readonly unknown[]): Text {
+  return new Text(highlightCode(getTextContent(content), "json").join("\n"), 0, 0);
+}
+
+function outputLimits(lifecycle: CodeMcpLifecycle): { maxBytes: number; maxLines: number } {
+  const settings = lifecycle.loadSettings();
+  return {
+    maxBytes: settings.outputLimitKiB * 1024,
+    maxLines: settings.outputLineLimit,
+  };
+}
+
+function truncate(value: string, maxLength: number): string {
+  return value.length <= maxLength ? value : `${value.slice(0, maxLength - 1)}…`;
+}
+
+function requireChainScope(value: string): ChainScope {
+  if (value !== "project" && value !== "global") {
+    throw new TypeError("Saved chain scope must be project or global");
+  }
+  return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}