@piagent/platform 1.2.16 → 1.3.0-ie.8

package/packages/piagent-core/runtime/registration/extension-registration.ts

@@ -0,0 +1,66 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { PIAGENT_SEQUENTIAL_TOOLS } from "../tools/phase-tools.ts";
+
+type RuntimeCommandDefinition = Parameters<ExtensionAPI["registerCommand"]>[1];
+type RuntimeToolDefinition = Record<string, any> & { name: string };
+
+function legacyToolErrorText(result: Record<string, any>, name: string): string {
+  const content = Array.isArray(result.content) ? result.content : [];
+  const text = content
+    .filter((item) => item && typeof item === "object" && item.type === "text" && typeof item.text === "string")
+    .map((item) => item.text.trim())
+    .filter(Boolean)
+    .join("\n");
+  return text || `${name} failed`;
+}
+
+function hostCompatibleTool(definition: RuntimeToolDefinition): RuntimeToolDefinition {
+  if (typeof definition.execute !== "function") return definition;
+  const execute = definition.execute;
+  return {
+    ...definition,
+    async execute(...args: any[]) {
+      const result = await execute.apply(definition, args);
+      // The pinned Pi host treats thrown execute errors as tool failures. A legacy
+      // `isError` return field is ignored and reaches the model as success,
+      // which made refused intake/progress calls look actionable.
+      if (result && typeof result === "object" && result.isError === true) {
+        const error = new Error(legacyToolErrorText(result, definition.name));
+        Object.assign(error, { details: result.details, piagentToolResult: result });
+        throw error;
+      }
+      return result;
+    }
+  };
+}
+
+export function registerRuntimeCommand(
+  pi: ExtensionAPI,
+  name: string,
+  definition: RuntimeCommandDefinition
+): void {
+  pi.registerCommand(name, definition);
+}
+
+export function piagentToolExecutionMode(name: string): "sequential" | "parallel" {
+  return PIAGENT_SEQUENTIAL_TOOLS.has(name) ? "sequential" : "parallel";
+}
+
+export function piagentToolBatchMode(names: string[]): "sequential" | "parallel" {
+  return names.some((name) => piagentToolExecutionMode(name) === "sequential") ? "sequential" : "parallel";
+}
+
+export function registerPiagentTool(pi: ExtensionAPI, definition: RuntimeToolDefinition): void {
+  pi.registerTool({ ...hostCompatibleTool(definition), executionMode: piagentToolExecutionMode(definition.name) });
+}
+
+export function registerRuntimeTool(pi: ExtensionAPI, definition: RuntimeToolDefinition): void {
+  registerPiagentTool(pi, definition);
+}
+
+export function prefixCompletions(values: readonly string[], prefix: string): Array<{ value: string; label: string }> {
+  const typed = String(prefix ?? "").trim().toLowerCase();
+  return values
+    .filter((value) => value.startsWith(typed))
+    .map((value) => ({ value, label: value }));
+}

package/packages/piagent-core/runtime/registration/knowledge-tools.ts

@@ -0,0 +1,303 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export function registerKnowledgeTools(pi: ExtensionAPI, deps: Record<string, any>): void {
+  const {
+    CONTEXT_INDEX_EDGE_KINDS, CONTEXT_INDEX_NODE_KINDS, StringEnum, Type, appendMemoryNote,
+    appendSessionTrace, appendTrace, buildContextIndexStatus, fs, loadProfileFromContext,
+    defaultRolePolicy, helpersMode, memoryHandbookPath, memoryLocalDir, memorySummaryPath, policy, projectFilePath,
+    registerPiagentTool, resolveMemorySettings, resolveOrchestrationPolicy, searchContextIndex, searchMemoryFiles,
+    writeContextIndex
+  } = deps;
+  registerPiagentTool(pi, {
+    name: "piagent_orchestration_policy",
+    label: "Piagent Orchestration Policy",
+    description: "Return solo-first subagent, review lens, model-role, and Field Guide policy for the current project.",
+    promptSnippet: "Use this before planning medium/large tasks so orchestration stays single-agent-first and token-aware.",
+    promptGuidelines: [
+      "Default to the parent agent plus bounded subagents only when they reduce context risk or improve review quality.",
+      "Use review lenses instead of spawning a broad swarm.",
+      "Treat Field Guide memory as advisory and verify it against current repository files."
+    ],
+    parameters: Type.Object({
+      detail: Type.Optional(StringEnum(["concise", "full"] as const))
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const profile = loadProfileFromContext(ctx);
+      const settings = resolveMemorySettings(profile);
+      const orchestration = resolveOrchestrationPolicy(profile, policy);
+      let fieldGuidePath = orchestration.fieldGuide.path || settings.handbookFile;
+      let fieldGuideExists = false;
+      try {
+        fieldGuideExists = fs.existsSync(projectFilePath(ctx.cwd, fieldGuidePath));
+      } catch {
+        fieldGuidePath = settings.handbookFile;
+        fieldGuideExists = fs.existsSync(memoryHandbookPath(ctx.cwd, settings));
+      }
+      const payload = {
+        ...orchestration,
+        helpersMode: helpersMode(),
+        rolePolicies: ["retriever", "scout", "planner", "worker", "reviewer", "oracle", "researcher"].map((role) => {
+          const rolePolicy = defaultRolePolicy(role);
+          return { role, authority: rolePolicy.authority, enabledByDefault: rolePolicy.enabledByDefault, allowedTools: rolePolicy.allowedTools, contextBudget: rolePolicy.contextBudget, ceilings: rolePolicy.ceilings };
+        }),
+        fieldGuide: {
+          ...orchestration.fieldGuide,
+          path: fieldGuidePath,
+          exists: fieldGuideExists
+        },
+        stance: "single-agent-first; subagents are opt-in tools for bounded scout, planning, and review"
+      };
+      const text = params.detail === "full"
+        ? JSON.stringify(payload, null, 2)
+        : [
+          `mode: ${payload.defaultMode}`,
+          `maxConcurrentSubagents: ${payload.maxConcurrentSubagents}`,
+          `helpersMode: ${payload.helpersMode}`,
+          `reviewLenses: ${payload.defaultReviewLenses.join(", ")}`,
+          `fieldGuide: ${payload.fieldGuide.enabled ? `${payload.fieldGuide.path} (${payload.fieldGuide.exists ? "exists" : "missing"})` : "off"}`,
+          `fieldGuidePolicy: ${payload.fieldGuide.writePolicy}, maxLines=${payload.fieldGuide.maxLines}`,
+          "modelRoles:",
+          `- planner: ${payload.roleModelGuidance.planner}`,
+          `- worker: ${payload.roleModelGuidance.worker}`,
+          `- reviewer: ${payload.roleModelGuidance.reviewer}`,
+          `- watchdog: ${payload.roleModelGuidance.watchdog}`,
+          "rules:",
+          ...payload.rules.map((rule) => `- ${rule}`)
+        ].join("\n");
+      return { content: [{ type: "text", text }], details: payload };
+    }
+  });
+
+  registerPiagentTool(pi, {
+    name: "piagent_memory_status",
+    label: "Piagent Memory Status",
+    description: "Return the project memory policy, files, and safe usage rules.",
+    promptSnippet: "Inspect project memory policy before relying on remembered facts.",
+    promptGuidelines: [
+      "Use memory as hints, not source of truth.",
+      "Verify memory against repository files before making source changes.",
+      "Never store secrets or raw private data in memory."
+    ],
+    parameters: Type.Object({
+      detail: Type.Optional(StringEnum(["concise", "full"] as const))
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const profile = loadProfileFromContext(ctx);
+      const settings = resolveMemorySettings(profile);
+      const summaryPath = memorySummaryPath(ctx.cwd, settings);
+      const handbookPath = memoryHandbookPath(ctx.cwd, settings);
+      const payload = {
+        enabled: settings.enabled,
+        mode: settings.mode,
+        scope: settings.scope,
+        readBeforeTask: settings.readBeforeTask,
+        writePolicy: settings.writePolicy,
+        maxInjectedChars: settings.maxInjectedChars,
+        files: {
+          summary: { path: settings.summaryFile, exists: fs.existsSync(summaryPath) },
+          handbook: { path: settings.handbookFile, exists: fs.existsSync(handbookPath) },
+          localDir: { path: settings.localDir, exists: fs.existsSync(memoryLocalDir(ctx.cwd, settings)) }
+        },
+        externalPackages: settings.externalPackages,
+        rules: [
+          "Memory is advisory; repository files and current task contract are authoritative.",
+          "Only write durable memory after an explicit user remember request or an approved workflow step.",
+          "Do not save secrets, credentials, raw private data, or large source excerpts.",
+          "Prefer compact summaries, tags, and links over long transcripts."
+        ]
+      };
+      const text = params.detail === "full"
+        ? JSON.stringify(payload, null, 2)
+        : [
+          `memory: ${payload.enabled ? payload.mode : "off"}`,
+          `scope: ${payload.scope}`,
+          `summary: ${payload.files.summary.path} (${payload.files.summary.exists ? "exists" : "missing"})`,
+          `handbook: ${payload.files.handbook.path} (${payload.files.handbook.exists ? "exists" : "missing"})`,
+          `writePolicy: ${payload.writePolicy}`,
+          `externalPackages: ${payload.externalPackages.join(", ") || "none"}`
+        ].join("\n");
+      return { content: [{ type: "text", text }], details: payload };
+    }
+  });
+
+  registerPiagentTool(pi, {
+    name: "piagent_memory_note",
+    label: "Piagent Memory Note",
+    description: "Append an explicit durable project memory note to .pi/memory/MEMORY.md.",
+    promptSnippet: "Use only when the user explicitly asks to remember a stable fact, decision, preference, lesson, or open loop.",
+    promptGuidelines: [
+      "Do not call this for incidental transcript content.",
+      "Keep notes compact and evidence-based.",
+      "Secrets are redacted before writing, but avoid sending secrets to the tool."
+    ],
+    parameters: Type.Object({
+      category: StringEnum(["preference", "decision", "project", "lesson", "open-loop", "reference"] as const),
+      title: Type.String({ minLength: 3 }),
+      content: Type.String({ minLength: 3 }),
+      source: Type.Optional(Type.String())
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const profile = loadProfileFromContext(ctx);
+      try {
+        const result = appendMemoryNote(ctx.cwd, profile, params);
+        appendTrace(ctx.cwd, { event: "memory_note", category: params.category, title: params.title, path: result.path, redacted: result.redacted });
+        appendSessionTrace(pi, { event: "memory_note", category: params.category, title: params.title, path: result.path, redacted: result.redacted });
+        return {
+          content: [{ type: "text", text: `Memory note saved: ${result.path}${result.redacted ? " (secrets redacted)" : ""}` }],
+          details: result
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: "text", text: `Memory note failed: ${message}` }], isError: true };
+      }
+    }
+  });
+
+  registerPiagentTool(pi, {
+    name: "piagent_memory_search",
+    label: "Piagent Memory Search",
+    description: "Keyword-search project memory markdown files.",
+    promptSnippet: "Search project memory for relevant durable facts before re-scouting the whole repo.",
+    parameters: Type.Object({
+      query: Type.String({ minLength: 1 }),
+      limit: Type.Optional(Type.Number())
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const profile = loadProfileFromContext(ctx);
+      const limit = Math.max(1, Math.min(20, Math.trunc(params.limit ?? 10)));
+      const matches = searchMemoryFiles(ctx.cwd, profile, params.query, limit);
+      const text = matches.length
+        ? matches.map((match) => `${match.path}:${match.line}: ${match.text}`).join("\n")
+        : "No memory matches.";
+      return { content: [{ type: "text", text }], details: { query: params.query, matches } };
+    }
+  });
+
+  registerPiagentTool(pi, {
+    name: "piagent_context_index_status",
+    label: "Piagent Context Index Status",
+    description: "Return the project context index status, node counts, citations, and stale/pending warnings.",
+    promptSnippet: "Use this during project/profile init to check whether the compact context graph is present and fresh.",
+    promptGuidelines: [
+      "Treat the context index as advisory; verify with current repository files before editing.",
+      "Do not use it as a security boundary or as the only source of truth.",
+      "If warnings mention pending tech context, refresh via Context7 and record concise snapshots."
+    ],
+    parameters: Type.Object({
+      detail: Type.Optional(StringEnum(["concise", "full"] as const))
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const profile = loadProfileFromContext(ctx);
+      const status = buildContextIndexStatus(ctx.cwd, profile);
+      const text = params.detail === "full"
+        ? JSON.stringify(status, null, 2)
+        : [
+            `contextIndex: ${status.enabled ? "enabled" : "off"}`,
+            `path: ${status.path} (${status.exists ? "exists" : "missing"})`,
+            `nodes: ${status.nodes}`,
+            `edges: ${status.edges}`,
+            `citations: ${status.citations}`,
+            `updatedAt: ${status.updatedAt ?? "never"}`,
+            `warnings: ${status.warnings.join("; ") || "none"}`
+          ].join("\n");
+      return { content: [{ type: "text", text }], details: status };
+    }
+  });
+
+  registerPiagentTool(pi, {
+    name: "piagent_context_index_search",
+    label: "Piagent Context Index Search",
+    description: "Keyword-search the compact project context index.",
+    promptSnippet: "Search the project context index before re-scouting broad repository structure.",
+    promptGuidelines: [
+      "Use hits as navigation hints only.",
+      "Open and verify cited files before changing code."
+    ],
+    parameters: Type.Object({
+      query: Type.String({ minLength: 1 }),
+      limit: Type.Optional(Type.Number())
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const profile = loadProfileFromContext(ctx);
+      const limit = Math.max(1, Math.min(20, Math.trunc(params.limit ?? 10)));
+      try {
+        const matches = searchContextIndex(ctx.cwd, profile, params.query, limit);
+        const text = matches.length
+          ? matches.map((match) => `${match.id} [${match.kind}] ${match.label}: ${match.match}`).join("\n")
+          : "No context index matches.";
+        return { content: [{ type: "text", text }], details: { query: params.query, matches } };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: "text", text: `Context index search failed: ${message}` }], isError: true };
+      }
+    }
+  });
+
+  registerPiagentTool(pi, {
+    name: "piagent_context_index_record",
+    label: "Piagent Context Index Record",
+    description: "Persist a compact project context index with cited nodes and edges.",
+    promptSnippet: "Record concise profile/project/tech/task context after onboarding or an approved handoff summary.",
+    promptGuidelines: [
+      "Only record stable, verified, non-secret project facts.",
+      "Keep nodes small and cite project files/docs; do not save raw transcripts or large source excerpts.",
+      "Memory and context index entries are advisory and must be re-verified before editing."
+    ],
+    parameters: Type.Object({
+      summary: Type.String({ minLength: 10 }),
+      source: Type.Optional(StringEnum(["onboarding-record", "approved-workflow", "manual"] as const)),
+      sourceFiles: Type.Optional(Type.Array(Type.Object({
+        path: Type.Optional(Type.String()),
+        reason: Type.Optional(Type.String()),
+        url: Type.Optional(Type.String())
+      }))),
+      nodes: Type.Optional(Type.Array(Type.Object({
+        id: Type.String({ minLength: 1 }),
+        kind: StringEnum(CONTEXT_INDEX_NODE_KINDS),
+        label: Type.String({ minLength: 1 }),
+        summary: Type.Optional(Type.String()),
+        path: Type.Optional(Type.String()),
+        tags: Type.Optional(Type.Array(Type.String())),
+        citations: Type.Optional(Type.Array(Type.Object({
+          path: Type.Optional(Type.String()),
+          reason: Type.Optional(Type.String()),
+          url: Type.Optional(Type.String())
+        })))
+      }))),
+      edges: Type.Optional(Type.Array(Type.Object({
+        from: Type.String({ minLength: 1 }),
+        to: Type.String({ minLength: 1 }),
+        kind: StringEnum(CONTEXT_INDEX_EDGE_KINDS),
+        reason: Type.Optional(Type.String())
+      }))),
+      citations: Type.Optional(Type.Array(Type.Object({
+        path: Type.Optional(Type.String()),
+        reason: Type.Optional(Type.String()),
+        url: Type.Optional(Type.String())
+      })))
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const profile = loadProfileFromContext(ctx);
+      try {
+        const index = writeContextIndex(ctx.cwd, profile, {
+          source: params.source ?? "approved-workflow",
+          summary: params.summary,
+          sourceFiles: params.sourceFiles,
+          nodes: params.nodes,
+          edges: params.edges,
+          citations: params.citations
+        });
+        appendTrace(ctx.cwd, { event: "context_index_record", path: index.policy.path, nodes: index.nodes.length, edges: index.edges.length, warnings: index.warnings });
+        appendSessionTrace(pi, { event: "context_index_record", path: index.policy.path, nodes: index.nodes.length, edges: index.edges.length, warnings: index.warnings });
+        return {
+          content: [{ type: "text", text: `Context index recorded: ${index.policy.path} (${index.nodes.length} nodes, ${index.edges.length} edges, ${index.citations.length} citations)` }],
+          details: index
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: "text", text: `Context index record failed: ${message}` }], isError: true };
+      }
+    }
+  });
+
+}

package/packages/piagent-core/runtime/registration/memory-mcp-commands.ts

@@ -0,0 +1,254 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type ExtensionContext = any;
+
+export function registerMemoryMcpCommands(pi: ExtensionAPI, deps: Record<string, any>): any {
+  const {
+    collectServers, emitRuntimeMessage, loadProfileFromContext, mcpActions, mcpApprovalCache,
+    resolveMemorySettings, selectValueFromUi
+  } = deps;
+  function emitMemoryPolicyStatus(ctx: ExtensionContext): void {
+    const profile = loadProfileFromContext(ctx);
+    const settings = resolveMemorySettings(profile);
+    ctx.ui.notify(`Project memory: ${settings.enabled ? settings.mode : "off"}`, "info");
+    emitRuntimeMessage(ctx, "piagent-memory-status", [
+      `memory: ${settings.enabled ? settings.mode : "off"}`,
+      `scope: ${settings.scope}`,
+      `summary: ${settings.summaryFile}`,
+      `handbook: ${settings.handbookFile}`,
+      `writePolicy: ${settings.writePolicy}`,
+      "rules: explicit-only by default; current repo files remain source of truth",
+      "remember: ask the agent clearly, then it must use piagent_memory_note"
+    ].join("\n"), settings);
+  }
+
+  pi.registerCommand("piagent-memory", {
+    description: "Legacy alias for /memory",
+    handler: async (_args, ctx) => {
+      emitMemoryPolicyStatus(ctx);
+    }
+  });
+
+  pi.registerCommand("memory", {
+    description: "Show project memory policy and available memory files without a model follow-up",
+    handler: async (_args, ctx) => {
+      emitMemoryPolicyStatus(ctx);
+    }
+  });
+
+  pi.registerCommand("memory-policy", {
+    description: "Legacy alias for /memory",
+    handler: async (_args, ctx) => {
+      emitMemoryPolicyStatus(ctx);
+    }
+  });
+
+  /**
+   * MCP management as a command, not as a request to the model.
+   *
+   * Everything here is also reachable from the `piagent-mcp` terminal CLI. The
+   * difference is where you are standing: inside a session, typing the shell
+   * command means asking the model to run bash, read the output and tell you
+   * what it said — three model turns to answer a question this process can
+   * answer from files it has already read. So the same reports are bound to a
+   * command, which pi dispatches without involving the model at all.
+   *
+   * Bare `/piagent-mcp` opens a menu built from what this project actually has,
+   * because the surface only helps if you can find it without already knowing
+   * the subcommand you want. Every entry in that menu is also typeable, so the
+   * menu teaches the direct form rather than replacing it.
+   */
+  function registerMcpCommand(): void {
+    const ACTIONS = new Set([...mcpActions.READ_ACTIONS, ...mcpActions.SERVER_ACTIONS]);
+
+    /** Report without a model turn: the text is shown, nothing is asked. */
+    function emit(customType: string, report: { notify: { message: string; level: string }, lines: string[], details: Record<string, unknown> }, ctx: ExtensionContext): void {
+      ctx.ui.notify(report.notify.message, report.notify.level as "info" | "warning" | "error");
+      pi.sendMessage(
+        { customType, content: report.lines.join("\n"), display: true, details: report.details },
+        { triggerTurn: false }
+      );
+    }
+
+    function fail(ctx: ExtensionContext, message: string): void {
+      ctx.ui.notify(`piagent-mcp: ${message}`, "error");
+      pi.sendMessage(
+        { customType: "piagent-mcp-error", content: message, display: true, details: { error: message } },
+        { triggerTurn: false }
+      );
+    }
+
+    /**
+     * Approval decisions live outside the repository, so writing one changes no
+     * config file the gate's cache is keyed on. Drop the entry so the next tool
+     * call re-reads the decision instead of the one it replaced.
+     */
+    function forgetApprovalCache(cwd: string): void {
+      mcpApprovalCache.delete(cwd);
+    }
+
+    /** Runs one action and shows it. Both the menu and a typed subcommand land here. */
+    function runAction(ctx: ExtensionContext, action: string, name: string | undefined, scope: string | undefined): void {
+      const project = ctx.cwd;
+      switch (action) {
+        case "status":
+          emit("piagent-mcp-status", mcpActions.status({ projectPath: project, scope }), ctx);
+          return;
+        case "get":
+          emit("piagent-mcp-detail", mcpActions.detail({ projectPath: project, name: name as string, scope }), ctx);
+          return;
+        case "doctor":
+          emit("piagent-mcp-doctor", mcpActions.doctor({ projectPath: project }), ctx);
+          return;
+        case "approve":
+        case "reject": {
+          const report = mcpActions.decide({
+            projectPath: project,
+            name: name as string,
+            decision: action === "approve" ? "approved" : "rejected"
+          });
+          forgetApprovalCache(project);
+          emit("piagent-mcp-decision", report, ctx);
+          return;
+        }
+        case "reset": {
+          const report = mcpActions.reset({ projectPath: project, name });
+          forgetApprovalCache(project);
+          emit("piagent-mcp-decision", report, ctx);
+          return;
+        }
+        case "enable":
+        case "disable":
+          emit("piagent-mcp-toggle", mcpActions.toggle({
+            projectPath: project,
+            name: name as string,
+            scope,
+            enabled: action === "enable"
+          }), ctx);
+          return;
+        default:
+          fail(ctx, `unknown subcommand: ${action}. Run /piagent-mcp help.`);
+      }
+    }
+
+    /**
+     * The menu. Falls back to the plain status report when there is no select UI
+     * — print mode and JSON mode have no way to answer a prompt, and blocking
+     * there would hang a non-interactive run.
+     */
+    async function runMenu(ctx: ExtensionContext): Promise<void> {
+      const menu = mcpActions.menuOptions({ projectPath: ctx.cwd });
+      const chosen = ctx.hasUI === false
+        ? undefined
+        : await selectValueFromUi(ctx, "MCP", menu.entries, menu.entries.find((entry) => entry.recommended)?.value);
+      if (!chosen) {
+        emit("piagent-mcp-status", mcpActions.status({ projectPath: ctx.cwd }), ctx);
+        pi.sendMessage(
+          { customType: "piagent-mcp-help", content: mcpActions.HELP_LINES.join("\n"), display: true, details: {} },
+          { triggerTurn: false }
+        );
+        return;
+      }
+      if (chosen === "help") {
+        emit("piagent-mcp-help", mcpActions.help(), ctx);
+        return;
+      }
+      const terminal = mcpActions.terminalOnly(chosen);
+      if (terminal) {
+        emit("piagent-mcp-terminal", terminal, ctx);
+        return;
+      }
+      if (!mcpActions.SERVER_ACTIONS.has(chosen) || chosen === "reset") {
+        // `reset` without a name forgets everything, which is a bigger answer
+        // than the menu asked for, so it still picks a server here.
+        if (chosen !== "reset") {
+          runAction(ctx, chosen, undefined, undefined);
+          return;
+        }
+      }
+      const choices = mcpActions.serverChoices({ projectPath: ctx.cwd, action: chosen });
+      if (choices.length === 0) {
+        fail(ctx, `no server here can be ${chosen === "get" ? "inspected" : `${chosen}d`}.`);
+        return;
+      }
+      const server = choices.length === 1
+        ? choices[0].value
+        : await selectValueFromUi(ctx, `Which server to ${chosen}?`, choices);
+      if (!server) {
+        fail(ctx, `no server chosen. Run \`/piagent-mcp ${chosen} <name>\` directly.`);
+        return;
+      }
+      runAction(ctx, chosen, server, undefined);
+    }
+
+    pi.registerCommand("piagent-mcp", {
+      description: "Show and manage MCP servers, scopes and approvals without a model follow-up",
+      getArgumentCompletions: (prefix: string) => {
+        const typed = String(prefix ?? "");
+        const parts = typed.split(/\s+/);
+        if (parts.length <= 1) {
+          const items = [...ACTIONS, "help"]
+            .filter((name) => name.startsWith(parts[0] ?? ""))
+            .map((name) => ({ value: name, label: name }));
+          return items.length > 0 ? items : null;
+        }
+        if (!mcpActions.SERVER_ACTIONS.has(parts[0])) return null;
+        let names: string[] = [];
+        try {
+          names = collectServers({ projectPath: process.cwd() }).map((server) => server.name);
+        } catch {
+          return null;
+        }
+        const seen = [...new Set(names)].filter((name) => name.startsWith(parts[parts.length - 1] ?? ""));
+        return seen.length > 0 ? seen.map((name) => ({ value: name, label: name })) : null;
+      },
+      handler: async (args, ctx) => {
+        const tokens = String(args ?? "").trim().split(/\s+/).filter(Boolean);
+        const flags = new Map<string, string>();
+        const positionals: string[] = [];
+        for (let i = 0; i < tokens.length; i += 1) {
+          if (tokens[i] === "--scope" && tokens[i + 1]) {
+            flags.set("scope", tokens[i + 1]);
+            i += 1;
+            continue;
+          }
+          positionals.push(tokens[i]);
+        }
+        const requested = (positionals.shift() ?? "").toLowerCase();
+        // `list` is what the terminal calls it, and muscle memory arrives here.
+        const action = requested === "list" ? "status" : requested;
+        const name = positionals[0];
+        const scope = flags.get("scope");
+
+        try {
+          if (action === "") {
+            await runMenu(ctx);
+            return;
+          }
+          if (action === "help" || action === "--help") {
+            emit("piagent-mcp-help", mcpActions.help(), ctx);
+            return;
+          }
+          const terminal = mcpActions.terminalOnly(action);
+          if (terminal) {
+            emit("piagent-mcp-terminal", terminal, ctx);
+            return;
+          }
+          if (!ACTIONS.has(action)) {
+            fail(ctx, `unknown subcommand: ${action}. Run /piagent-mcp help.`);
+            return;
+          }
+          if (mcpActions.SERVER_ACTIONS.has(action) && action !== "reset" && !name) {
+            fail(ctx, `${action} needs a server name.`);
+            return;
+          }
+          runAction(ctx, action, name, scope);
+        } catch (error) {
+          fail(ctx, error instanceof Error ? error.message : String(error));
+        }
+      }
+    });
+  }
+  registerMcpCommand();
+
+}