@piagent/platform 1.1.9 → 1.2.1

package/packages/piagent-core/mcp/mcp-session-view.js

@@ -0,0 +1,236 @@
+import {
+  SCOPES,
+  collectServers,
+  repositoryImportDeclarations,
+  unreadableLayers,
+  unverifiableMcpConfig
+} from "./mcp-config-layers.js";
+import { approvalState } from "./mcp-approval-store.js";
+import { maskServerEntry, maskUrlCredentials } from "./mcp-server-entry.js";
+import { evaluateServerReadiness } from "./mcp-auth-readiness.js";
+import { CATALOG_PREREQUISITES } from "./mcp-server-catalog.js";
+
+// What the terminal CLI and the in-session `/piagent-mcp` command both show.
+//
+// The same question gets asked from two places — a shell prompt and a Pi
+// session — and two answers that disagree about whether a server is usable is
+// worse than either answer alone. So the reading, the states and the wording
+// live here once, and both surfaces print what this returns.
+//
+// Read-only by construction: nothing here writes a config or an approval.
+
+/** @typedef {import("./mcp-auth-readiness.js").ReadinessState} ReadinessState */
+
+export class McpViewError extends Error {}
+
+/**
+ * The stdio command line, or the remote URL, shortened for a table cell.
+ * @param {Record<string, unknown>} entry
+ * @param {number} [limit]
+ * @returns {string}
+ */
+export function describeTarget(entry, limit = 56) {
+  // Masked here as well as in the detail view. This is the string that goes in
+  // the `list` table, which is the output most likely to be screenshotted.
+  if (typeof entry.url === "string") return String(maskUrlCredentials(entry.url));
+  const argv = [entry.command, ...(Array.isArray(entry.args) ? entry.args : [])].filter((item) => typeof item === "string");
+  const text = argv.join(" ");
+  return text.length > limit ? `${text.slice(0, limit - 3)}...` : text;
+}
+
+/**
+ * Every server visible from a project, with its readiness resolved.
+ * @param {{projectPath: string, scopes?: string[]}} options
+ */
+export function collectServerRows(options) {
+  const { projectPath, scopes } = options;
+  if (scopes) {
+    for (const scope of scopes) {
+      if (!SCOPES.includes(scope)) throw new McpViewError(`unsupported scope: ${scope}`);
+    }
+  }
+  return collectServers({ projectPath, scopes }).map((server) => ({
+    ...server,
+    transport: typeof server.entry.url === "string" ? "http" : "stdio",
+    target: describeTarget(server.entry),
+    readiness: evaluateServerReadiness(server, { projectPath })
+  }));
+}
+
+/**
+ * Servers that will not answer a tool call. `oauth` is excluded: it may already
+ * be signed in, and this cannot tell.
+ * @param {ReturnType<typeof collectServerRows>} rows
+ */
+export function blockedRows(rows) {
+  return rows.filter((row) => row.readiness.state !== "ready" && row.readiness.state !== "oauth");
+}
+
+/**
+ * Everything any surface needs to answer "what is MCP doing here right now".
+ *
+ * The three surfaces — the guard, `/piagent-mcp`, and the terminal CLI — used to
+ * assemble this themselves out of four separate calls, and each one picked a
+ * different subset. That is how `list` came to print "No MCP servers configured"
+ * and exit 0 in a session where the guard was refusing every tool call: the
+ * listing was reading rows, and the thing that made the answer wrong was not a
+ * row. Everything that decides whether MCP works is gathered here once.
+ *
+ * `blockingConfig` is the part that outranks per-server state. While any of it
+ * stands, no server is usable whatever its own readiness says, so a caller that
+ * reports readiness without reporting this is giving an answer that is locally
+ * true and globally wrong.
+ *
+ * @param {{projectPath: string, scopes?: string[]}} options
+ */
+export function sessionMcpState(options) {
+  const { projectPath, scopes } = options;
+  const rows = collectServerRows({ projectPath, scopes });
+  const blockingConfig = unverifiableMcpConfig({ projectPath });
+  return {
+    rows,
+    blocked: blockedRows(rows),
+    blockingConfig,
+    unreadable: unreadableLayers({ projectPath }),
+    imports: repositoryImportDeclarations({ projectPath }),
+    // One boolean rather than each caller re-deriving the rule. `list --json`
+    // read `servers: []` as success while this was true.
+    usable: blockingConfig.length === 0
+  };
+}
+
+/**
+ * One named server, resolved to a single scope. `listHint` is the caller's own
+ * way of listing servers, so the error names a command the reader can actually
+ * run from where they are.
+ *
+ * @param {{projectPath: string, name: string, scope?: string, listHint?: string, scopeHint?: string}} options
+ */
+export function describeServer(options) {
+  const { projectPath, name, scope, listHint, scopeHint = "--scope" } = options;
+  const matches = collectServerRows({ projectPath, scopes: scope ? [scope] : undefined })
+    .filter((row) => row.name === name);
+  if (matches.length === 0) {
+    throw new McpViewError(scope
+      ? `no server named ${name} in ${scope} scope`
+      : `no server named ${name}.${listHint ? ` Run \`${listHint}\` to see what is configured.` : ""}`);
+  }
+  if (matches.length > 1) {
+    throw new McpViewError(
+      `${name} is defined in more than one scope (${matches.map((row) => row.scope).join(", ")}). ` +
+      `Pass ${scopeHint} to say which one.`
+    );
+  }
+  const row = matches[0];
+  // `requiresApproval`, not the scope. A server imported into a `global` config
+  // from a repository-relative kind carries the scope of the file that declared
+  // the import and still needs a decision here, so keying off the scope showed
+  // no approval line for exactly the servers whose approval is least obvious.
+  const approval = row.requiresApproval
+    ? approvalState({ projectPath, name, entry: row.entry })
+    : undefined;
+  return { ...row, masked: maskServerEntry(row.entry), approval };
+}
+
+/**
+ * Readiness remedies are written as terminal commands, because that is where
+ * every one of them can be run. Inside a session the same step is a slash
+ * command, and telling a reader to shell out for something they can do where
+ * they are standing is how a surface ends up feeling harder than it is.
+ *
+ * @param {string | undefined} remedy
+ * @param {boolean} inSession
+ * @returns {string | undefined}
+ */
+export function remedyFor(remedy, inSession) {
+  if (!remedy || !inSession) return remedy;
+  return remedy.replace(/(^|[\s`])piagent-mcp /g, "$1/piagent-mcp ");
+}
+
+/** Left-aligned columns sized to their contents. */
+function table(headers, rows) {
+  const widths = headers.map((header, i) => Math.max(header.length, ...rows.map((cells) => cells[i].length)));
+  const line = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join("  ").trimEnd();
+  return [line(headers), ...rows.map(line)].join("\n");
+}
+
+/**
+ * @param {ReturnType<typeof collectServerRows>} rows
+ * @returns {string}
+ */
+export function formatServerTable(rows) {
+  if (rows.length === 0) return "";
+  return table(
+    ["NAME", "SCOPE", "TRANSPORT", "TARGET", "STATE"],
+    rows.map((row) => [row.name, row.scope, row.transport, row.target, row.readiness.state])
+  );
+}
+
+/** Fields worth showing; the rest of an entry is noise in a status view. */
+const DETAIL_FIELDS = ["url", "command", "args", "env", "headers", "auth", "bearerTokenEnvVar"];
+
+/**
+ * @param {ReturnType<typeof describeServer>} detail
+ * @param {{inSession?: boolean}} [options]
+ * @returns {string[]}
+ */
+export function formatServerDetail(detail, options = {}) {
+  const lines = [
+    detail.name,
+    `  scope: ${detail.scope}`,
+    `  file: ${detail.file}`,
+    // Only for a server that came through `imports`. Without it the `scope` and
+    // `file` lines read as a config this tool can edit, and every write command
+    // suggested against them fails or edits the wrong file.
+    ...(detail.origin?.startsWith("import:")
+      ? [`  origin: ${detail.origin} (declared by the ${detail.scope} config; edit ${detail.file} directly)`]
+      : []),
+    `  transport: ${detail.transport}`
+  ];
+  for (const key of DETAIL_FIELDS) {
+    const item = detail.masked[key];
+    if (item === undefined) continue;
+    lines.push(`  ${key}: ${typeof item === "string" ? item : JSON.stringify(item)}`);
+  }
+  lines.push(`  state: ${detail.readiness.state} (${detail.readiness.detail})`);
+  const next = remedyFor(detail.readiness.remedy, options.inSession === true);
+  if (next) lines.push(`  next: ${next}`);
+  if (detail.approval) lines.push(`  approval: ${detail.approval.state} (${detail.approval.digest})`);
+  return lines;
+}
+
+/**
+ * The readiness report, one line per server plus the remedy for anything stuck.
+ * `dockerRunning` is passed in rather than probed: the probe spawns a process
+ * and only the caller knows whether it can afford that.
+ *
+ * @param {ReturnType<typeof collectServerRows>} rows
+ * @param {{dockerRunning?: boolean, rerun?: string, inSession?: boolean}} [options]
+ * @returns {{lines: string[], problems: number}}
+ */
+export function formatDoctorReport(rows, options = {}) {
+  if (rows.length === 0) return { lines: ["No MCP servers configured."], problems: 0 };
+
+  const lines = [];
+  let problems = 0;
+  for (const row of rows) {
+    const usable = row.readiness.state === "ready" || row.readiness.state === "oauth";
+    if (!usable) problems += 1;
+    lines.push(`${usable ? "OK  " : "NEED"} ${row.name} (${row.scope}): ${row.readiness.detail}`);
+    const remedy = remedyFor(row.readiness.remedy, options.inSession === true);
+    if (remedy) lines.push(`       -> ${remedy}`);
+  }
+  if (options.dockerRunning === false) {
+    problems += 1;
+    lines.push("NEED docker: installed but the daemon is not responding");
+    lines.push(`       -> start Docker Desktop, then re-run ${options.rerun ?? "the check"}`);
+  }
+  const prerequisites = rows.flatMap((row) => (CATALOG_PREREQUISITES[row.name] ?? []).map((item) => `  ${row.name}: ${item}`));
+  if (prerequisites.length > 0) lines.push("", "Pinned servers also expect:", ...prerequisites);
+  return { lines, problems };
+}
+
+/** True when any configured server runs through the docker CLI. */
+export function usesDocker(rows) {
+  return rows.some((row) => row.entry.command === "docker");
+}

package/packages/piagent-core/mcp/mcp-tool-naming.js

@@ -0,0 +1,90 @@
+// How the adapter names the tools it exposes, mirrored here so a tool call can
+// be traced back to the server behind it.
+//
+// The adapter builds a prefix from the server name and joins it to the tool name
+// with an underscore. With the default `toolPrefix: "server"` a server called
+// `github` exposes `github_create_issue`. There is no `mcp__` anywhere in that
+// scheme, which is why a gate written against `mcp__<server>__<tool>` never
+// fired: it was watching for a name shape nothing produces.
+//
+// `none` is the case with no answer. It strips the prefix entirely, so the tool
+// arrives under whatever name the server gave it and carries no evidence of
+// where it came from. Attribution is impossible by construction, which makes the
+// combination of that setting with `directTools` in a repository-carried config
+// something to refuse rather than something to parse.
+
+/** Prefix modes the adapter accepts. */
+export const TOOL_PREFIX_MODES = new Set(["server", "none", "short"]);
+
+/**
+ * The prefix a server's tools carry under one mode, matching the adapter's own
+ * derivation. An empty string means the mode erases the origin.
+ * @param {string} serverName
+ * @param {string} mode
+ * @returns {string}
+ */
+export function serverPrefix(serverName, mode) {
+  if (mode === "none") return "";
+  if (mode === "short") {
+    const short = serverName.replace(/-?mcp$/i, "").replace(/-/g, "_");
+    return short || "mcp";
+  }
+  return serverName.replace(/-/g, "_");
+}
+
+/**
+ * Every prefix a server's tools could arrive under. All prefixing modes are
+ * covered rather than just the configured one, because the setting lives in the
+ * same file as the servers: a repository that wants a different mode can simply
+ * declare it, so trusting the declared value to decide what to inspect would
+ * hand the choice back to the thing being gated.
+ * @param {string} serverName
+ * @returns {string[]}
+ */
+export function serverPrefixes(serverName) {
+  const prefixes = new Set();
+  for (const mode of ["server", "short"]) {
+    const prefix = serverPrefix(serverName, mode);
+    if (prefix) prefixes.add(prefix);
+  }
+  return [...prefixes];
+}
+
+/**
+ * Which of the given servers exposes this tool, or undefined when the name
+ * carries no prefix belonging to any of them.
+ *
+ * The longest match wins. Servers named `db` and `db_admin` both prefix
+ * `db_admin_query`, and answering `db` there would check the wrong server's
+ * approval — the more specific prefix is the one that actually produced it.
+ *
+ * @param {string} toolName
+ * @param {Iterable<string>} serverNames
+ * @returns {string|undefined}
+ */
+export function attributeDirectTool(toolName, serverNames) {
+  if (typeof toolName !== "string" || toolName.length === 0) return undefined;
+  let best;
+  let bestLength = 0;
+  for (const name of serverNames) {
+    for (const prefix of serverPrefixes(name)) {
+      if (prefix.length <= bestLength) continue;
+      if (!toolName.startsWith(`${prefix}_`)) continue;
+      best = name;
+      bestLength = prefix.length;
+    }
+  }
+  return best;
+}
+
+/**
+ * Whether a config's settings put tools on the model under names that cannot be
+ * traced to a server. Both halves are required: without `directTools` every call
+ * goes through the proxy, which names its server explicitly.
+ * @param {Record<string, unknown>} settings
+ * @returns {boolean}
+ */
+export function erasesToolOrigin(settings) {
+  if (!settings || typeof settings !== "object") return false;
+  return settings.directTools === true && settings.toolPrefix === "none";
+}

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.1.9",
+  "version": "1.2.1",
   "type": "module",
   "private": true,
   "license": "MIT",
@@ -37,8 +37,12 @@
     "typebox": "1.1.38"
   },
   "peerDependenciesMeta": {
-    "@earendil-works/pi-coding-agent": { "optional": true },
-    "typebox": { "optional": true }
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=22.19.0"

package/packages/piagent-core/prompts/model-options.md

@@ -1,5 +1,5 @@
 ---
-description: Explain native Pi model selector/scope options for Codex and Claude
+description: Explain native Pi model selector/scope options across model families
 argument-hint: "[task type, budget, or provider preference]"
 ---
 
@@ -18,15 +18,15 @@ Mandatory flow:
    - `/scoped-models` for cycle scope;
    - Ctrl+P / Shift+Ctrl+P for model cycling;
    - Shift+Tab for thinking level.
-4. Include both OpenAI Codex and Claude/Anthropic options unless the user explicitly restricts provider.
-5. Do not limit the answer to one or two legacy examples. Include the current latest-family options for Codex 5.5/5.6 and Claude Sonnet/Opus/Fable where relevant.
+4. Include both model families — the OpenAI Codex models and the Anthropic Claude models — unless the user explicitly restricts the provider. Name them as model families, never as another tool.
+5. Do not limit the answer to one or two legacy examples. Include the current latest-family options: the Codex 5.5/5.6 models and the Claude Sonnet/Opus/Fable models, where relevant.
 6. If the user needs available model versions, recommend `piagent-models`, `/model`, or `pi --list-models`.
 7. Explain thinking levels as task effort, not as quality guarantee.
 8. Do not claim token/cost savings without benchmark evidence.
 
 Current latest-family catalog to consider:
 
-OpenAI Codex:
+OpenAI Codex models (provider `openai-codex`):
 
 - `openai-codex/gpt-5.3-codex-spark`
 - `openai-codex/gpt-5.4-mini`
@@ -36,7 +36,7 @@ OpenAI Codex:
 - `openai-codex/gpt-5.6-sol`
 - `openai-codex/gpt-5.6-terra`
 
-Claude/Anthropic:
+Anthropic Claude models (provider `anthropic`):
 
 - `anthropic/claude-haiku-4-5`
 - `anthropic/claude-sonnet-4-5`
@@ -50,7 +50,7 @@ Claude/Anthropic:
 
 Default selector scope seeded by setup:
 
-| Preset | OpenAI Codex | Claude/Anthropic | Use when |
+| Preset | OpenAI Codex model | Anthropic Claude model | Use when |
 |---|---|---|---|
 | Fast scout | `openai-codex/gpt-5.4-mini:low` | `anthropic/claude-haiku-4-5:low` | quick reads, simple Q&A |
 | Balanced implement | `openai-codex/gpt-5.5:medium` | `anthropic/claude-sonnet-5:medium` | normal source tasks |
@@ -63,6 +63,6 @@ Output:
 - Current model/context if available.
 - How to open/select/change model in Pi UI.
 - What `enabledModels`/scope contains.
-- Codex family options.
-- Claude family options.
+- Codex model family options.
+- Claude model family options.
 - How to inspect/re-apply model scope from terminal.