pi-codemcp 1.0.0 → 1.1.0

package/src/tools.ts

@@ -1,7 +1,12 @@
 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 {
+  type ChainScope,
+  nativeChainToolName,
+  type SavedChainManager,
+  type SavedChainView,
+} from "./chains.js";
 import {
   getTextContent,
   previewExecutionValue,
@@ -9,34 +14,72 @@ import {
 } from "./execution-rendering.js";
 import type { CodeMcpLifecycle } from "./lifecycle.js";
 import { type CodeMcpOutputDetails, formatCodeMcpOutput } from "./output.js";
+import {
+  EXECUTE_PROMPT_GUIDELINES,
+  INSPECT_PROMPT_GUIDELINES,
+  MANAGE_CHAIN_PROMPT_GUIDELINES,
+  SAVE_CHAIN_PROMPT_GUIDELINES,
+  SEARCH_PROMPT_GUIDELINES,
+} from "./prompts.js";
 
 interface SearchRenderDetails extends CodeMcpOutputDetails {
   matchCount: number;
   totalToolCount: number;
   serverCount: number;
+  hasMore: boolean;
+  nextCursor?: number;
+  detail: string;
   preview: string[];
 }
 
 const SearchParameters = Type.Object({
-  query: Type.String({
-    minLength: 1,
-    description: "Words describing an upstream capability, tool, or saved chain",
-  }),
+  query: Type.Optional(
+    Type.String({
+      minLength: 1,
+      description: "Capability words for search mode; omit for inventory mode",
+    }),
+  ),
+  mode: Type.Optional(
+    Type.String({
+      enum: ["search", "inventory"],
+      description: "Rank by capability (default) or page through compact inventory",
+    }),
+  ),
+  detail: Type.Optional(
+    Type.String({
+      enum: ["names", "signatures", "full"],
+      description: "Disclosure level (default signatures); use inspect for selected full stubs",
+    }),
+  ),
   limit: Type.Optional(
     Type.Integer({
       minimum: 1,
       maximum: 20,
-      description: "Maximum compact matches to return (default 5)",
+      description: "Maximum matches per page (default 5)",
+    }),
+  ),
+  cursor: Type.Optional(
+    Type.Integer({
+      minimum: 0,
+      description: "Pagination cursor returned by a previous search",
     }),
   ),
   server: Type.Optional(
     Type.String({
       minLength: 1,
-      description: "Configured upstream server to search, or chains for saved chains",
+      description: "Exact configured server name, or chains for saved chains",
     }),
   ),
 });
 
+const InspectParameters = Type.Object({
+  calls: Type.Array(Type.String({ minLength: 1 }), {
+    minItems: 1,
+    maxItems: 20,
+    description: "Exact call identifiers returned by search, such as grafana.query_prometheus",
+  }),
+});
+
 const SaveChainParameters = Type.Object({
   scope: Type.Optional(
     Type.String({
@@ -68,6 +111,32 @@ const SaveChainParameters = Type.Object({
   }),
 });
 
+const ManageChainsParameters = Type.Object({
+  action: Type.String({
+    enum: ["list", "enable", "disable", "revalidate", "delete"],
+    description: "Chain management action",
+  }),
+  name: Type.Optional(
+    Type.String({
+      minLength: 1,
+      maxLength: 64,
+      pattern: "^[a-z][a-z0-9_]{0,63}$",
+      description: "Saved-chain name; required for mutations",
+    }),
+  ),
+  scope: Type.Optional(
+    Type.String({
+      enum: ["project", "global"],
+      description: "Saved-chain scope; required for mutations",
+    }),
+  ),
+  confirmedByUser: Type.Optional(
+    Type.Boolean({
+      description: "Must be true for enable, disable, revalidate, or delete",
+    }),
+  ),
+});
+
 const ExecuteParameters = Type.Object({
   code: Type.String({
     minLength: 1,
@@ -85,11 +154,9 @@ export function registerCodeMcpTools(
     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.",
-    ],
+      "Search configured MCP capabilities or page through compact inventory. Default signature search includes exact stubs for up to three top matches plus compact alternatives; codemcp_inspect loads other selected stubs. Returns ranking evidence, pagination, scope, and execution limits; invalid server names fail with suggestions.",
+    promptSnippet: "Discover compact MCP capabilities or inventory",
+    promptGuidelines: [...SEARCH_PROMPT_GUIDELINES],
     parameters: SearchParameters,
     async execute(_toolCallId, params, signal, onUpdate) {
       onUpdate?.({
@@ -99,8 +166,11 @@ export function registerCodeMcpTools(
       const result = await lifecycle.request(
         "search",
         {
-          query: params.query,
+          ...(params.query === undefined ? {} : { query: params.query }),
+          mode: params.mode ?? "search",
+          detail: params.detail ?? "signatures",
           limit: params.limit ?? 5,
+          cursor: params.cursor ?? 0,
           ...(params.server === undefined ? {} : { server: params.server }),
         },
         signal,
@@ -123,13 +193,17 @@ export function registerCodeMcpTools(
           matchCount: results.length,
           totalToolCount: Number(result.total_tool_count ?? 0),
           serverCount: servers.length,
+          hasMore: result.has_more === true,
+          nextCursor: typeof result.next_cursor === "number" ? result.next_cursor : undefined,
+          detail: typeof result.detail === "string" ? result.detail : "signatures",
           preview,
         },
       };
     },
     renderCall(args, theme) {
+      const subject = args.mode === "inventory" ? "inventory" : `"${args.query ?? ""}"`;
       return new Text(
-        `${theme.fg("toolTitle", theme.bold("MCP Search "))}${theme.fg("accent", `"${args.query}"`)}`,
+        `${theme.fg("toolTitle", theme.bold("MCP Search "))}${theme.fg("accent", subject)}`,
         0,
         0,
       );
@@ -140,27 +214,75 @@ export function registerCodeMcpTools(
       const details = result.details as SearchRenderDetails | undefined;
       let text = theme.fg(
         "success",
-        `${details?.matchCount ?? 0} matches · ${details?.totalToolCount ?? 0} tools · ${details?.serverCount ?? 0} servers`,
+        `${details?.matchCount ?? 0} matches · ${details?.detail ?? "signatures"} · ${details?.totalToolCount ?? 0} tools · ${details?.serverCount ?? 0} servers`,
       );
       for (const name of details?.preview ?? []) {
         text += `\n${theme.fg("dim", `  ${name}`)}`;
       }
+      if (details?.hasMore) {
+        text += `\n${theme.fg("muted", `  more at cursor ${details.nextCursor ?? "?"}`)}`;
+      }
       text += `\n${theme.fg("muted", keyHint("app.tools.expand", "full results"))}`;
       return new Text(text, 0, 0);
     },
   });
 
+  pi.registerTool({
+    name: "codemcp_inspect",
+    label: "MCP Inspect",
+    description:
+      "Return the exact typed SDK stubs for selected call identifiers from codemcp_search. The response deduplicates the shared JsonValue/type prelude.",
+    promptSnippet: "Load exact typed contracts for selected MCP calls",
+    promptGuidelines: [...INSPECT_PROMPT_GUIDELINES],
+    parameters: InspectParameters,
+    async execute(_toolCallId, params, signal, onUpdate) {
+      onUpdate?.({
+        content: [{ type: "text", text: "Inspecting MCP tool contracts..." }],
+        details: undefined,
+      });
+      const result = await lifecycle.request("inspect", { calls: params.calls }, signal);
+      const output = formatCodeMcpOutput(result, outputLimits(lifecycle));
+      const results = Array.isArray(result.results) ? result.results : [];
+      return {
+        content: [{ type: "text", text: output.text }],
+        details: {
+          ...output.details,
+          matchCount: results.length,
+          preview: results
+            .slice(0, 3)
+            .flatMap((item) =>
+              isRecord(item) && typeof item.call === "string" ? [item.call] : [],
+            ),
+        },
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        `${theme.fg("toolTitle", theme.bold("MCP Inspect "))}${theme.fg("accent", `${args.calls.length} calls`)}`,
+        0,
+        0,
+      );
+    },
+    renderResult(result, { expanded, isPartial }, theme) {
+      if (isPartial) return new Text(theme.fg("warning", "Loading exact contracts..."), 0, 0);
+      if (expanded) return renderExpandedJson(result.content);
+      const details = result.details as
+        | (CodeMcpOutputDetails & { matchCount: number; preview: string[] })
+        | undefined;
+      let text = theme.fg("success", `${details?.matchCount ?? 0} exact contracts`);
+      for (const call of details?.preview ?? []) text += `\n${theme.fg("dim", `  ${call}`)}`;
+      text += `\n${theme.fg("muted", keyHint("app.tools.expand", "full stubs"))}`;
+      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.",
-    ],
+      "Type-check and execute one bounded sandboxed Python MCP call graph. Use it when code can deterministically process intermediate results; preserve a model turn for semantic decisions or approvals. The sandbox has no host filesystem, environment, network, or subprocess access. Oversized results fail with bounded shape, size, and sample diagnostics.",
+    promptSnippet: "Run a bounded typed MCP workflow and return a compact result",
+    promptGuidelines: [...EXECUTE_PROMPT_GUIDELINES],
     parameters: ExecuteParameters,
     async execute(_toolCallId, params, signal, onUpdate) {
       onUpdate?.({
@@ -168,8 +290,17 @@ export function registerCodeMcpTools(
         details: undefined,
       });
       const result = await lifecycle.request("execute", { code: params.code }, signal);
-      const output = formatCodeMcpOutput(result, outputLimits(lifecycle));
       const ok = result.ok === true;
+      const modelValue = ok
+        ? result.result
+        : {
+            failure_stage: result.failure_stage,
+            error: result.error,
+            shape: result.shape,
+            calls_made: result.calls_made,
+            chain_calls: result.chain_calls,
+          };
+      const output = formatCodeMcpOutput(modelValue, outputLimits(lifecycle));
       return {
         content: [{ type: "text", text: output.text }],
         details: {
@@ -178,6 +309,7 @@ export function registerCodeMcpTools(
           failureStage: typeof result.failure_stage === "string" ? result.failure_stage : undefined,
           callsMade: Number(result.calls_made ?? 0),
           chainCalls: Number(result.chain_calls ?? 0),
+          ...(isRecord(result.timings) ? { timings: result.timings } : {}),
           preview: previewExecutionValue(ok ? result.result : result.error),
         },
       };
@@ -219,19 +351,19 @@ export function registerCodeMcpTools(
     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.",
-    ],
+    promptGuidelines: [...SAVE_CHAIN_PROMPT_GUIDELINES],
     parameters: SaveChainParameters,
     async execute(_toolCallId, params, signal, onUpdate) {
+      const scope = requireChainScope(params.scope ?? "project");
+      if (scope === "project" && lifecycle.projectChainsPath === undefined) {
+        throw new Error(
+          "Project saved-chain scope is unavailable in this session; ask before using global scope",
+        );
+      }
       onUpdate?.({
         content: [{ type: "text", text: `Validating saved chain ${params.name}...` }],
         details: undefined,
       });
-      const scope = requireChainScope(params.scope ?? "project");
       const view = await chains.save(
         {
           scope,
@@ -302,18 +434,120 @@ export function registerCodeMcpTools(
       );
     },
   });
+
+  pi.registerTool({
+    name: "codemcp_manage_chains",
+    label: "Manage MCP Chains",
+    description:
+      "List saved chains, or explicitly enable, disable, revalidate, or delete one scoped chain. Mutations require confirmedByUser=true and never bypass dependency checks.",
+    promptSnippet: "List or explicitly manage saved MCP chains",
+    promptGuidelines: [...MANAGE_CHAIN_PROMPT_GUIDELINES],
+    parameters: ManageChainsParameters,
+    async execute(_toolCallId, params, signal, onUpdate) {
+      const action = params.action;
+      let views: SavedChainView[];
+      if (action === "list") {
+        views = await chains.list(signal);
+      } else {
+        if (params.confirmedByUser !== true) {
+          throw new Error(`${action} requires confirmedByUser=true after explicit user approval`);
+        }
+        if (params.name === undefined || params.scope === undefined) {
+          throw new Error(`${action} requires name and scope`);
+        }
+        const scope = requireChainScope(params.scope);
+        if (scope === "project" && lifecycle.projectChainsPath === undefined) {
+          throw new Error("Project saved-chain scope is unavailable in this session");
+        }
+        onUpdate?.({
+          content: [{ type: "text", text: `${action} saved chain ${params.name}...` }],
+          details: undefined,
+        });
+        if (action === "enable" || action === "disable") {
+          const applied = await chains.applyEnabled(
+            [{ name: params.name, scope, enabled: action === "enable" }],
+            signal,
+          );
+          views = applied.chains;
+        } else if (action === "revalidate") {
+          await chains.revalidate(params.name, scope, signal);
+          views = await chains.list(signal);
+        } else {
+          views = await chains.delete(params.name, scope, signal);
+        }
+      }
+      const result = {
+        action,
+        project_scope_available: lifecycle.projectChainsPath !== undefined,
+        chains: views.map(compactChainView),
+      };
+      const output = formatCodeMcpOutput(result, outputLimits(lifecycle));
+      return {
+        content: [{ type: "text", text: output.text }],
+        details: {
+          ...output.details,
+          action,
+          chainCount: views.length,
+        },
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        `${theme.fg("toolTitle", theme.bold("Manage MCP Chains "))}${theme.fg("accent", args.action)}${args.name ? ` ${theme.fg("muted", args.name)}` : ""}`,
+        0,
+        0,
+      );
+    },
+    renderResult(result, { expanded, isPartial }, theme, context) {
+      if (isPartial) return new Text(theme.fg("warning", "Managing saved chains..."), 0, 0);
+      const details = result.details as
+        | (CodeMcpOutputDetails & { action: string; chainCount: number })
+        | undefined;
+      if (context.isError || !details) {
+        return new Text(
+          theme.fg("error", getTextContent(result.content).trim() || "Chain management failed"),
+          0,
+          0,
+        );
+      }
+      if (expanded) return renderExpandedJson(result.content);
+      return new Text(
+        theme.fg("success", `${details.action} · ${details.chainCount} chains`),
+        0,
+        0,
+      );
+    },
+  });
+}
+
+function compactChainView(view: SavedChainView) {
+  return {
+    name: view.chain.name,
+    scope: view.scope,
+    status: view.status,
+    enabled: view.chain.enabled,
+    description: view.chain.description,
+    native_tool: nativeChainToolName(view.chain.name),
+    call: `chains.${view.chain.name}`,
+    stale_dependencies: view.staleDependencies,
+    called_by: view.calledBy,
+  };
 }
 
 function renderExpandedJson(content: readonly unknown[]): Text {
-  return new Text(highlightCode(getTextContent(content), "json").join("\n"), 0, 0);
+  const raw = getTextContent(content);
+  let formatted = raw;
+  try {
+    formatted = JSON.stringify(JSON.parse(raw), null, 2);
+  } catch {
+    // Keep explicit non-JSON errors readable.
+  }
+  return new Text(highlightCode(formatted, "json").join("\n"), 0, 0);
 }
 
-function outputLimits(lifecycle: CodeMcpLifecycle): { maxBytes: number; maxLines: number } {
+function outputLimits(lifecycle: CodeMcpLifecycle): { maxBytes: number } {
   const settings = lifecycle.loadSettings();
-  return {
-    maxBytes: settings.outputLimitKiB * 1024,
-    maxLines: settings.outputLineLimit,
-  };
+  return { maxBytes: settings.outputLimitKiB * 1024 };
 }
 
 function truncate(value: string, maxLength: number): string {