@piagent/platform 1.2.0 → 1.2.2

package/scripts/mcp-manage.mjs

@@ -10,6 +10,7 @@ import {
   collectServers,
   configPathForScope,
   isRecord,
+  mergedServerEntry,
   readMcpConfig,
   writeMcpConfig
 } from "../packages/piagent-core/mcp/mcp-config-layers.js";
@@ -28,18 +29,18 @@ import {
 } from "../packages/piagent-core/mcp/mcp-server-entry.js";
 import {
   approvalState,
+  approvalStorePath,
   clearApproval,
   recordApproval
 } from "../packages/piagent-core/mcp/mcp-approval-store.js";
 import { evaluateServerReadiness } from "../packages/piagent-core/mcp/mcp-auth-readiness.js";
 import {
   McpViewError,
-  blockedRows,
-  collectServerRows,
   describeServer,
   formatDoctorReport,
   formatServerDetail,
   formatServerTable,
+  sessionMcpState,
   usesDocker
 } from "../packages/piagent-core/mcp/mcp-session-view.js";
 
@@ -214,6 +215,25 @@ function locateServer(name, flags) {
   return servers[0];
 }
 
+/**
+ * A server this command has no file of its own to edit: it was read out of
+ * another tool's config through `imports`. `located.file` is that other tool's
+ * config, and writing it back through `writeMcpConfig` would rewrite somebody's
+ * Cursor or VS Code file in this platform's format -- adding a `settings` block
+ * it does not use and dropping every key this shape does not carry.
+ *
+ * @param {{name: string, origin?: string, scope: string, file: string}} located
+ * @param {string} action
+ */
+function assertOwnedByThisTool(located, action) {
+  if (!located.origin?.startsWith("import:")) return;
+  const kind = located.origin.slice("import:".length);
+  throw new UsageError(
+    `${located.name} is not defined by any config this command owns. The ${located.scope} config imports ${kind}, ` +
+    `and the definition lives in ${located.file}. Edit that file to ${action} it, or drop "${kind}" from its imports list.`
+  );
+}
+
 // --- commands ---------------------------------------------------------------
 
 /** @param {ReturnType<typeof parseArgs>} args */
@@ -277,12 +297,21 @@ function commandRemove(args) {
   const name = args.positionals[0];
   if (!name) throw new UsageError("remove needs a server name");
   const located = locateServer(name, args.flags);
+  assertOwnedByThisTool(located, "remove");
   const config = readMcpConfig(located.file);
   delete config.mcpServers[name];
   writeMcpConfig(located.file, config);
-  clearApproval({ projectPath: projectPath(args.flags), name });
   process.stdout.write(`Removed MCP server ${name} from ${located.scope} scope\n`);
   process.stdout.write(`File modified: ${located.file}\n`);
+  // The definition is gone either way; the decision about it is a separate
+  // record, and leaving one behind for a name that no longer exists means a
+  // later server reusing the name would meet an approval nobody granted it.
+  if (!clearApproval({ projectPath: projectPath(args.flags), name })) {
+    process.stdout.write(
+      `Warning: could not update ${approvalStorePath() ?? "the approval store"}, ` +
+      `so the recorded decision for ${name} is still there. Run \`piagent-mcp reset ${name}\` once it is writable.\n`
+    );
+  }
   return 0;
 }
 
@@ -318,33 +347,51 @@ function commandGet(args) {
 function commandList(args) {
   const scopeFilter = value(args.flags, "--scope");
   const project = projectPath(args.flags);
-  const rows = collectServerRows({ projectPath: project, scopes: scopeFilter ? [scopeFilter] : undefined });
+  // Listing nothing is the correct answer only when nothing is reaching the
+  // session. A config the gate cannot verify reaches it with an unknown set of
+  // servers, and telling somebody to seed a baseline in that state sends them
+  // to the wrong file entirely.
+  const state = sessionMcpState({ projectPath: project, scopes: scopeFilter ? [scopeFilter] : undefined });
+  const { rows } = state;
 
   if (args.flags.get("--json") === true) {
+    // The same fields the human output carries. A caller scripting against this
+    // read `servers: []` as "nothing configured" while every tool call was being
+    // refused, and an exit code of 0 agreed with it.
     process.stdout.write(`${JSON.stringify({
       project,
+      usable: state.usable,
+      blockingConfig: state.blockingConfig,
       servers: rows.map((row) => ({
         name: row.name,
         scope: row.scope,
+        origin: row.origin,
+        requiresApproval: row.requiresApproval,
         file: row.file,
         state: row.readiness.state,
         detail: row.readiness.detail,
         entry: maskServerEntry(row.entry)
       }))
     }, null, 2)}\n`);
-    return 0;
+    return state.usable ? 0 : 1;
   }
 
+  for (const problem of state.blockingConfig) process.stdout.write(`BLOCKED every tool call: ${problem.detail}\n`);
+
   if (rows.length === 0) {
-    process.stdout.write("No MCP servers configured.\n");
-    process.stdout.write("Seed the pinned baseline with: piagent-mcp --preset core --scope global\n");
-    return 0;
+    if (state.usable) {
+      process.stdout.write("No MCP servers configured.\n");
+      process.stdout.write("Seed the pinned baseline with: piagent-mcp --preset core --scope global\n");
+    }
+  } else {
+    process.stdout.write(`${formatServerTable(rows)}\n`);
+    if (state.blocked.length > 0) {
+      process.stdout.write(`\n${state.blocked.length} server(s) not usable yet. Run \`piagent-mcp doctor\`.\n`);
+    }
   }
-
-  process.stdout.write(`${formatServerTable(rows)}\n`);
-  const blocked = blockedRows(rows);
-  if (blocked.length > 0) process.stdout.write(`\n${blocked.length} server(s) not usable yet. Run \`piagent-mcp doctor\`.\n`);
-  return 0;
+  // Out of the no-rows branch: the exit code answers "can MCP work here", and
+  // that question does not depend on how many rows happened to print.
+  return state.usable ? 0 : 1;
 }
 
 /** @param {ReturnType<typeof parseArgs>} args @param {boolean} enabled */
@@ -352,6 +399,7 @@ function commandToggle(args, enabled) {
   const name = args.positionals[0];
   if (!name) throw new UsageError(`${enabled ? "enable" : "disable"} needs a server name`);
   const located = locateServer(name, args.flags);
+  assertOwnedByThisTool(located, enabled ? "enable" : "disable");
   const config = readMcpConfig(located.file);
   const entry = { ...(isRecord(config.mcpServers[name]) ? config.mcpServers[name] : {}) };
   if (enabled) delete entry.enabled;
@@ -384,9 +432,19 @@ function commandDecide(args, decision) {
   if (decision === "approved" && before.state === "pending" && args.flags.get("--force") !== true) {
     // Approving without reading it is the failure this gate exists to prevent, so
     // the definition is put in front of the operator before the decision lands.
-    process.stdout.write(`${JSON.stringify(maskServerEntry(server.entry), null, 2)}\n`);
+    // The merged entry, not this layer's fragment: the adapter merges a
+    // same-named server key by key across layers, so a repository declaring only
+    // `{"args": [...]}` runs with a command it never showed the operator.
+    process.stdout.write(`${JSON.stringify(
+      maskServerEntry(mergedServerEntry({ projectPath: project, name, entry: server.entry })), null, 2
+    )}\n`);
+  }
+  // A decision that was not written is not a decision. Printing "Approved" while
+  // the store rejected the write would leave the operator waiting for a gate that
+  // is still blocking, with nothing on screen to explain why.
+  if (!recordApproval({ projectPath: project, name, entry: server.entry, decision })) {
+    throw new UsageError(`could not write ${approvalStorePath() ?? "the approval store"}; ${name} is still ${before.state}`);
   }
-  recordApproval({ projectPath: project, name, entry: server.entry, decision });
   const after = approvalState({ projectPath: project, name, entry: server.entry });
   process.stdout.write(`${decision === "approved" ? "Approved" : "Rejected"} MCP server ${name} (${server.scope}) for ${project}\n`);
   process.stdout.write(`Pinned to this definition: ${after.digest}\n`);
@@ -398,7 +456,9 @@ function commandDecide(args, decision) {
 function commandReset(args) {
   const project = projectPath(args.flags);
   const name = args.positionals[0];
-  clearApproval({ projectPath: project, name });
+  if (!clearApproval({ projectPath: project, name })) {
+    throw new UsageError(`could not write ${approvalStorePath() ?? "the approval store"}; nothing was forgotten`);
+  }
   process.stdout.write(name
     ? `Forgot the decision for ${name} in ${project}\n`
     : `Forgot every MCP approval decision for ${project}\n`);
@@ -408,7 +468,12 @@ function commandReset(args) {
 /** @param {ReturnType<typeof parseArgs>} args */
 function commandDoctor(args) {
   const project = projectPath(args.flags);
-  const rows = collectServerRows({ projectPath: project });
+  // Resolved before the no-servers shortcut below. A layer nobody can parse
+  // produces no rows, so reporting "no servers configured" and stopping would
+  // answer the question exactly backwards. The guard refuses every tool call
+  // under `blockingConfig`, and this is where somebody comes to find out why.
+  const state = sessionMcpState({ projectPath: project });
+  const { rows, unreadable: broken, imports, blockingConfig: unverifiable } = state;
 
   // The one check too slow for a session start: a daemon that is installed but
   // not running looks exactly like one that is running until something asks it.
@@ -422,22 +487,46 @@ function commandDoctor(args) {
     process.stdout.write(`${JSON.stringify({
       project,
       dockerRunning,
-      servers: rows.map((row) => ({ name: row.name, scope: row.scope, state: row.readiness.state, detail: row.readiness.detail, remedy: row.readiness.remedy }))
+      servers: rows.map((row) => ({ name: row.name, scope: row.scope, state: row.readiness.state, detail: row.readiness.detail, remedy: row.readiness.remedy })),
+      unreadableLayers: broken,
+      repositoryImports: imports.map((layer) => ({ scope: layer.scope, kinds: layer.kinds })),
+      unverifiableConfig: unverifiable
     }, null, 2)}\n`);
-    return blockedRows(rows).length > 0 ? 1 : 0;
+    return state.blocked.length > 0 || broken.length > 0 || unverifiable.length > 0 ? 1 : 0;
   }
 
+  for (const layer of broken) process.stdout.write(`Unreadable ${layer.scope} config: ${layer.detail}\n`);
+  for (const problem of unverifiable) process.stdout.write(`BLOCKED every tool call: ${problem.detail}\n`);
+
   if (rows.length === 0) {
+    if (unverifiable.length > 0 || broken.length > 0) {
+      process.stdout.write(`\n${unverifiable.length + broken.length} MCP config problem(s) need attention.\n`);
+      return 1;
+    }
     process.stdout.write("No MCP servers configured.\n");
     return 0;
   }
 
   const report = formatDoctorReport(rows, { dockerRunning, rerun: "piagent-mcp doctor" });
   for (const line of report.lines) process.stdout.write(`${line}\n`);
-  process.stdout.write(report.problems === 0
+
+  // A layer nothing can parse hides whatever it defines and reads as empty, so
+  // it is counted (and already printed above). An import is named but not
+  // counted: the servers it brings in are in the report above with their own
+  // state, and this line says where they came from, which reading the
+  // repository's own config would not reveal.
+  for (const layer of imports) {
+    process.stdout.write(
+      `${layer.file} imports servers from ${layer.kinds.join(", ")} config; ` +
+      "they need approval here like any server the repository defines.\n"
+    );
+  }
+
+  const problems = report.problems + broken.length + unverifiable.length;
+  process.stdout.write(problems === 0
     ? "\nPASS: every configured MCP server can be reached.\n"
-    : `\n${report.problems} MCP server(s) need attention.\n`);
-  return report.problems === 0 ? 0 : 1;
+    : `\n${problems} MCP problem(s) need attention.\n`);
+  return problems === 0 ? 0 : 1;
 }
 
 /** @param {ReturnType<typeof parseArgs>} args */

package/scripts/pi-model-catalog.sh

@@ -22,6 +22,15 @@ USAGE
 FORMAT="text"
 PROVIDER=""
 
+require_value() {
+  local option="$1"
+  local value="${2:-}"
+  if [[ -z "$value" || "$value" == --* ]]; then
+    echo "Missing value for $option" >&2
+    exit 2
+  fi
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --json)
@@ -29,7 +38,8 @@ while [[ $# -gt 0 ]]; do
       shift
       ;;
     --provider)
-      PROVIDER="${2:-}"
+      require_value "$1" "${2:-}"
+      PROVIDER="$2"
       shift 2
       ;;
     -h|--help)

package/scripts/pi-session-stats.sh

@@ -5,23 +5,49 @@ usage() {
   cat <<'USAGE'
 Usage:
   scripts/pi-session-stats.sh [project-path] [session-file]
+  scripts/pi-session-stats.sh --history [project-path] [history-options]
 
 Examples:
   scripts/pi-session-stats.sh .
   scripts/pi-session-stats.sh /path/to/project
   scripts/pi-session-stats.sh /path/to/project ~/.pi/agent/sessions/.../session.jsonl
+  scripts/pi-session-stats.sh --history . --days 7
+  scripts/pi-session-stats.sh --history --all-projects --csv
 
 Notes:
   - Reads exact Pi token/cache/cost totals via RPC get_session_stats.
   - If session-file is omitted, the newest persisted session whose header cwd matches project-path is used.
+  - Use --history for finished/old session totals read directly from Pi JSONL.
 USAGE
 }
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HISTORY_SCRIPT="$SCRIPT_DIR/pi-usage-history.mjs"
+
 if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
   usage
   exit 0
 fi
 
+for argument in "$@"; do
+  case "$argument" in
+    --history|--all-projects|--days|--since|--until|--format|--json|--csv|--markdown|--include-subagents|--no-subagents|--limit|--sessions-dir)
+      exec node "$HISTORY_SCRIPT" "$@"
+      ;;
+  esac
+done
+
+# Both arguments are positional and the project path comes first, so a flag in
+# either slot is a typo rather than a path. Saying so beats failing later with a
+# message about a directory that was never meant to be one.
+for argument in "${1:-}" "${2:-}"; do
+  if [[ "$argument" == -* ]]; then
+    echo "FAIL: this script takes <project-path> [session-file], not flags; received: $argument" >&2
+    usage >&2
+    exit 2
+  fi
+done
+
 PROJECT_PATH="${1:-.}"
 SESSION_FILE="${2:-}"
 
@@ -79,7 +105,7 @@ fi
 
 RPC_OUTPUT="$(
   printf '%s\n' '{"type":"get_session_stats","id":"piagent-usage"}' \
-    | pi --mode rpc --session "$SESSION_FILE" --offline --approve
+    | pi -ne --mode rpc --session "$SESSION_FILE" --offline --approve
 )"
 
 node --input-type=module - "$RPC_OUTPUT" <<'NODE'