@piagent/platform 1.0.0

package/scripts/migrate-project-state.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// Converts a project from the pre-piagent layout to the current one.
+//
+// This runs once per project. There is no alias layer, so a project that
+// still carries the old layout cannot be served by the current guard at all;
+// converting is the only path forward. The old files are left in place until
+// the caller confirms removal, so an interrupted run is always recoverable.
+import fs from "node:fs";
+import path from "node:path";
+
+const RENAMES = [
+  { from: ".pi/company-profile.json", to: ".pi/piagent-profile.json" },
+  { from: ".pi/company-profile.lock.json", to: ".pi/piagent-profile.lock.json" },
+  { from: ".pi/company-state", to: ".pi/piagent-state" }
+];
+
+// Applied to the text of migrated JSON and to AGENTS.md, which commonly
+// references tool names and profile paths in its instructions.
+const TEXT_REPLACEMENTS = [
+  ["PI_COMPANY_", "PIAGENT_"],
+  ["pi.company/", "piagent/"],
+  ["pi-company-", "piagent-"],
+  ["company_", "piagent_"],
+  ["company-profile", "piagent-profile"],
+  ["company-state", "piagent-state"]
+];
+
+function usage() {
+  console.log(`Usage:
+  piagent-migrate [project-path] [--apply] [--remove-old]
+
+Converts project-local state from the pre-piagent layout.
+
+  (default)      Dry run. Reports what would change and exits 0.
+  --apply        Write the new layout.
+  --remove-old   With --apply, delete the old files once the new ones exist.
+
+After --apply, regenerate the capability lock:
+  piagent-capabilities resolve --profile .pi/piagent-profile.json \\
+    --output .pi/piagent-profile.lock.json --package-source <source>`);
+}
+
+const args = process.argv.slice(2);
+if (args.includes("-h") || args.includes("--help")) {
+  usage();
+  process.exit(0);
+}
+
+const apply = args.includes("--apply");
+const removeOld = args.includes("--remove-old");
+const positional = args.filter((arg) => !arg.startsWith("--"));
+if (positional.length > 1) {
+  console.error(`Expected at most one project path, received ${positional.length}.`);
+  usage();
+  process.exit(2);
+}
+if (removeOld && !apply) {
+  console.error("--remove-old requires --apply.");
+  process.exit(2);
+}
+
+const projectPath = path.resolve(positional[0] ?? process.cwd());
+if (!fs.existsSync(projectPath)) {
+  console.error(`Project path does not exist: ${projectPath}`);
+  process.exit(2);
+}
+
+function rewriteText(text) {
+  let output = text;
+  for (const [from, to] of TEXT_REPLACEMENTS) output = output.split(from).join(to);
+  return output;
+}
+
+function copyRecursive(from, to) {
+  const stat = fs.lstatSync(from);
+  if (stat.isSymbolicLink()) return { skipped: from, reason: "symlink" };
+  if (stat.isDirectory()) {
+    fs.mkdirSync(to, { recursive: true });
+    for (const entry of fs.readdirSync(from)) copyRecursive(path.join(from, entry), path.join(to, entry));
+    return {};
+  }
+  if (from.endsWith(".json") || from.endsWith(".md") || from.endsWith(".jsonl")) {
+    fs.writeFileSync(to, rewriteText(fs.readFileSync(from, "utf8")));
+  } else {
+    fs.copyFileSync(from, to);
+  }
+  return {};
+}
+
+const planned = [];
+const skipped = [];
+// Source and target both present means a previous --apply already copied this
+// entry and the caller has not cleaned up yet. That is the normal midpoint of
+// the two-step workflow, not a conflict, so it stays eligible for --remove-old.
+const alreadyMigrated = [];
+
+for (const { from, to } of RENAMES) {
+  const source = path.join(projectPath, from);
+  const target = path.join(projectPath, to);
+  if (!fs.existsSync(source)) continue;
+  if (fs.existsSync(target)) {
+    alreadyMigrated.push({ from, to });
+    continue;
+  }
+  planned.push({ from, to });
+}
+
+// AGENTS.md is rewritten in place because it is the instruction file the guard
+// reads; leaving old tool names there would keep pointing the agent at tools
+// that no longer exist.
+const agentsPath = path.join(projectPath, "AGENTS.md");
+let agentsNeedsRewrite = false;
+if (fs.existsSync(agentsPath)) {
+  const text = fs.readFileSync(agentsPath, "utf8");
+  agentsNeedsRewrite = rewriteText(text) !== text;
+}
+
+const nothingToDo = planned.length === 0 && alreadyMigrated.length === 0 && !agentsNeedsRewrite;
+
+if (nothingToDo) {
+  console.log(JSON.stringify({ ok: true, projectPath, migrated: false, reason: "already on the current layout" }, null, 2));
+  process.exit(0);
+}
+
+if (!apply) {
+  console.log(JSON.stringify({
+    ok: true,
+    projectPath,
+    dryRun: true,
+    wouldRename: planned,
+    wouldRewrite: agentsNeedsRewrite ? ["AGENTS.md"] : [],
+    alreadyMigrated,
+    next: alreadyMigrated.length > 0 && planned.length === 0
+      ? "re-run with --apply --remove-old to delete the originals"
+      : "re-run with --apply"
+  }, null, 2));
+  process.exit(0);
+}
+
+const renamed = [];
+for (const { from, to } of planned) {
+  const result = copyRecursive(path.join(projectPath, from), path.join(projectPath, to));
+  if (result.skipped) {
+    skipped.push({ path: from, reason: result.reason });
+    continue;
+  }
+  renamed.push({ from, to });
+}
+
+if (agentsNeedsRewrite) {
+  fs.writeFileSync(agentsPath, rewriteText(fs.readFileSync(agentsPath, "utf8")));
+}
+
+const removed = [];
+if (removeOld) {
+  for (const { from } of [...renamed, ...alreadyMigrated]) {
+    fs.rmSync(path.join(projectPath, from), { recursive: true, force: true });
+    removed.push(from);
+  }
+}
+
+const pendingCleanup = renamed.length + alreadyMigrated.length - removed.length;
+
+console.log(JSON.stringify({
+  ok: true,
+  projectPath,
+  migrated: true,
+  renamed,
+  alreadyMigrated,
+  rewrote: agentsNeedsRewrite ? ["AGENTS.md"] : [],
+  skipped,
+  removedOld: removed,
+  next: pendingCleanup > 0
+    ? "verify the new files, then re-run with --apply --remove-old to delete the originals"
+    : "regenerate the capability lock with piagent-capabilities resolve"
+}, null, 2));

package/scripts/pi-auto.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  piagent-auto [--read-only|--workspace-write|--full-access] [--no-approve] [--] [pi args...]
+
+Purpose:
+  Launch Pi with project-local trust approved for this run.
+
+Examples:
+  piagent-auto
+  piagent-auto --name "payment scout"
+  piagent-auto --read-only -p "Scout payment mapping. Do not edit source."
+  piagent-auto --full-access -p "Run the trusted local benchmark suite."
+  piagent-auto -- --model openai-codex/gpt-5.5:xhigh
+
+Notes:
+  - This wraps `pi --approve`; it does not disable Piagent guardrails.
+  - Protected paths, destructive shell checks, task gates, and verify evidence still run.
+  - Use `--read-only` for guard-enforced read-only mode.
+  - Use `--full-access` only for trusted projects in an externally safe environment.
+  - Use `--no-approve` to force Pi to ignore project-local resources for this run.
+USAGE
+}
+
+PERMISSION_PROFILE="workspace-write"
+APPROVE_FLAG="--approve"
+ARGS=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    --read-only)
+      PERMISSION_PROFILE="read-only"
+      shift
+      ;;
+    --workspace-write)
+      PERMISSION_PROFILE="workspace-write"
+      shift
+      ;;
+    --full-access|--trusted-full-access)
+      PERMISSION_PROFILE="trusted-full-access"
+      shift
+      ;;
+    --no-approve|-na)
+      APPROVE_FLAG="--no-approve"
+      shift
+      ;;
+    --approve|-a)
+      APPROVE_FLAG="--approve"
+      shift
+      ;;
+    --)
+      shift
+      ARGS+=("$@")
+      break
+      ;;
+    *)
+      ARGS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+if ! command -v pi >/dev/null 2>&1; then
+  echo "FAIL: pi is not on PATH. Run piagent-setup or follow the exact-version install flow in docs/release-install-policy.md." >&2
+  exit 1
+fi
+
+if [[ "$PERMISSION_PROFILE" == "read-only" ]]; then
+  exec env PIAGENT_PERMISSION_PROFILE="$PERMISSION_PROFILE" pi "$APPROVE_FLAG" --exclude-tools bash,write,edit "${ARGS[@]}"
+fi
+
+exec env PIAGENT_PERMISSION_PROFILE="$PERMISSION_PROFILE" pi "$APPROVE_FLAG" "${ARGS[@]}"

package/scripts/pi-model-catalog.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/pi-model-catalog.sh [--json] [--provider <provider>]
+
+Examples:
+  scripts/pi-model-catalog.sh
+  scripts/pi-model-catalog.sh --provider openai-codex
+  scripts/pi-model-catalog.sh --provider anthropic --json
+
+Notes:
+  - Reads Pi's local model catalog at ~/.pi/agent/models-store.json by default.
+  - Run `pi update --models` first when you want the newest provider catalog.
+  - `pi --list-models` may hide models until a provider credential is available;
+    this script reads the local catalog directly so docs/presets can be reviewed.
+USAGE
+}
+
+FORMAT="text"
+PROVIDER=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json)
+      FORMAT="json"
+      shift
+      ;;
+    --provider)
+      PROVIDER="${2:-}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+node --input-type=module - "$FORMAT" "$PROVIDER" <<'NODE'
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const [format, providerFilter] = process.argv.slice(2);
+const agentDir = process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+const catalogPath = path.join(agentDir, "models-store.json");
+
+if (!fs.existsSync(catalogPath)) {
+  console.error(`FAIL: Pi model catalog not found: ${catalogPath}`);
+  console.error("Hint: run `pi update --models` or open Pi once after login.");
+  process.exit(1);
+}
+
+const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf8"));
+const targetProviders = providerFilter ? [providerFilter] : ["openai-codex", "anthropic"];
+
+function explicitThinkingLevels(model) {
+  if (!model.reasoning) return "no";
+  const map = model.thinkingLevelMap;
+  if (!map || typeof map !== "object") return "yes";
+  const levels = Object.entries(map)
+    .filter(([, value]) => value !== null && value !== false)
+    .map(([key]) => key);
+  return levels.length > 0 ? levels.join(",") : "yes";
+}
+
+function recommendedThinking(model) {
+  if (!model.reasoning) return "";
+  const raw = explicitThinkingLevels(model);
+  if (raw === "yes") return "xhigh";
+  if (raw === "no") return "";
+  const levels = raw.split(",");
+  for (const preferred of ["xhigh", "max", "high", "medium", "low", "minimal"]) {
+    if (levels.includes(preferred)) return preferred;
+  }
+  return levels[0] ?? "xhigh";
+}
+
+function roleFor(provider, id) {
+  if (provider === "openai-codex") {
+    if (/mini|spark/i.test(id)) return "fast";
+    if (/5\.4$/.test(id)) return "balanced";
+    if (/5\.5/.test(id)) return "balanced,hard";
+    if (/luna/i.test(id)) return "focused-hard";
+    if (/sol/i.test(id)) return "strategic-deep";
+    if (/terra/i.test(id)) return "huge-context";
+    return "general";
+  }
+  if (provider === "anthropic") {
+    if (/haiku/i.test(id)) return "fast";
+    if (/sonnet/i.test(id)) return "balanced,hard";
+    if (/opus/i.test(id)) return "strategic-deep";
+    if (/fable/i.test(id)) return "huge-context,deep";
+    return "general";
+  }
+  return "general";
+}
+
+const rows = [];
+for (const provider of targetProviders) {
+  const models = catalog[provider]?.models ?? [];
+  for (const model of models) {
+    rows.push({
+      provider,
+      id: model.id,
+      name: model.name ?? model.id,
+      contextWindow: model.contextWindow ?? null,
+      maxTokens: model.maxTokens ?? null,
+      reasoning: Boolean(model.reasoning),
+      thinking: explicitThinkingLevels(model),
+      recommendedThinking: recommendedThinking(model),
+      images: Array.isArray(model.input) && model.input.includes("image"),
+      role: roleFor(provider, model.id),
+      example: `${provider}/${model.id}${model.reasoning ? `:${recommendedThinking(model)}` : ""}`
+    });
+  }
+}
+
+if (format === "json") {
+  console.log(JSON.stringify({ catalogPath, providers: targetProviders, models: rows }, null, 2));
+  process.exit(0);
+}
+
+const number = (value) => value === null || value === undefined ? "?" : Number(value).toLocaleString("en-US");
+console.log(`# Pi Agent model catalog`);
+console.log();
+console.log(`Source: ${catalogPath}`);
+console.log(`Tip: run \`pi update --models\` before checking latest model versions.`);
+console.log();
+for (const provider of targetProviders) {
+  const providerRows = rows.filter((row) => row.provider === provider);
+  console.log(`## ${provider}`);
+  console.log();
+  if (providerRows.length === 0) {
+    console.log("_No models found in local catalog._");
+    console.log();
+    continue;
+  }
+  console.log("| Model | Role | Context | Max output | Thinking | Images | Command example |");
+  console.log("|---|---|---:|---:|---|---|---|");
+  for (const row of providerRows) {
+    console.log(`| \`${row.id}\` | ${row.role} | ${number(row.contextWindow)} | ${number(row.maxTokens)} | ${row.thinking} | ${row.images ? "yes" : "no"} | \`pi --model ${row.example}\` |`);
+  }
+  console.log();
+}
+NODE

package/scripts/pi-session-stats.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/pi-session-stats.sh [project-path] [session-file]
+
+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
+
+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.
+USAGE
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+PROJECT_PATH="${1:-.}"
+SESSION_FILE="${2:-}"
+
+if [[ ! -d "$PROJECT_PATH" ]]; then
+  echo "FAIL: project path does not exist: $PROJECT_PATH" >&2
+  exit 1
+fi
+
+PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
+
+if [[ -z "$SESSION_FILE" ]]; then
+  SESSION_FILE="$(node --input-type=module - "$PROJECT_PATH" <<'NODE'
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const projectPath = process.argv[2];
+const agentDir = process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+const sessionsDir = process.env.PI_CODING_AGENT_SESSION_DIR || path.join(agentDir, "sessions");
+const candidates = [];
+
+function walk(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const target = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(target);
+      continue;
+    }
+    if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
+    try {
+      const firstLine = fs.readFileSync(target, "utf8").split(/\n/, 1)[0];
+      const header = JSON.parse(firstLine);
+      if (header.cwd !== projectPath) continue;
+      const stat = fs.statSync(target);
+      candidates.push({ target, mtimeMs: stat.mtimeMs });
+    } catch {
+      // Ignore malformed or inaccessible session files.
+    }
+  }
+}
+
+walk(sessionsDir);
+candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+if (candidates[0]) process.stdout.write(candidates[0].target);
+NODE
+)"
+fi
+
+if [[ -z "$SESSION_FILE" || ! -f "$SESSION_FILE" ]]; then
+  echo "FAIL: no Pi session file found for project: $PROJECT_PATH" >&2
+  echo "Hint: run /session inside Pi, or pass the session file explicitly." >&2
+  exit 1
+fi
+
+RPC_OUTPUT="$(
+  printf '%s\n' '{"type":"get_session_stats","id":"piagent-usage"}' \
+    | pi --mode rpc --session "$SESSION_FILE" --offline --approve
+)"
+
+node --input-type=module - "$RPC_OUTPUT" <<'NODE'
+const input = process.argv[2] ?? "";
+
+  const line = input
+    .split(/\n+/)
+    .find((item) => item.includes('"command":"get_session_stats"'));
+  if (!line) {
+    console.error("FAIL: get_session_stats response not found");
+    process.exit(1);
+  }
+  const response = JSON.parse(line);
+  if (!response.success) {
+    console.error(`FAIL: ${response.error ?? "get_session_stats failed"}`);
+    process.exit(1);
+  }
+  const data = response.data;
+  const tokens = data.tokens ?? {};
+  const context = data.contextUsage ?? {};
+  const number = (value) => value === null || value === undefined ? "unknown" : Math.round(Number(value)).toLocaleString("en-US");
+  const money = (value) => value === null || value === undefined ? "unknown" : `$${Number(value).toFixed(6)}`;
+  const percent = (value) => value === null || value === undefined ? "unknown" : `${Number(value).toFixed(1)}%`;
+  console.log(JSON.stringify({
+    sessionFile: data.sessionFile,
+    sessionId: data.sessionId,
+    messages: {
+      user: data.userMessages,
+      assistant: data.assistantMessages,
+      toolCalls: data.toolCalls,
+      toolResults: data.toolResults,
+      total: data.totalMessages
+    },
+    tokens: {
+      input: tokens.input ?? null,
+      output: tokens.output ?? null,
+      cacheRead: tokens.cacheRead ?? null,
+      cacheWrite: tokens.cacheWrite ?? null,
+      total: tokens.total ?? null
+    },
+    cost: data.cost ?? null,
+    contextUsage: context.tokens === undefined ? null : {
+      tokens: context.tokens,
+      contextWindow: context.contextWindow,
+      percent: context.percent
+    },
+    summary: {
+      tokens: `${number(tokens.total)} total (${number(tokens.input)} input, ${number(tokens.output)} output, ${number(tokens.cacheRead)} cache read, ${number(tokens.cacheWrite)} cache write)`,
+      cost: money(data.cost),
+      context: context.tokens === undefined ? "unknown" : `${number(context.tokens)} / ${number(context.contextWindow)} (${percent(context.percent)})`
+    }
+  }, null, 2));
+NODE

package/scripts/piagent-cli.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptByCommand = {
+  "piagent-setup": "scripts/setup.sh",
+  "piagent-install": "scripts/install-global.sh",
+  "piagent-init": "scripts/init-project.sh",
+  "piagent-doctor": "scripts/team-doctor.sh",
+  "piagent-benchmark": "scripts/quality-benchmark.sh",
+  "piagent-usage": "scripts/pi-session-stats.sh",
+  "piagent-models": "scripts/pi-model-catalog.sh",
+  "piagent-model-scope": "scripts/configure-model-scope.sh",
+  "piagent-mcp": "scripts/configure-mcp.sh",
+  "piagent-subagents": "scripts/configure-subagents.sh",
+  "piagent-capabilities": "scripts/capability-catalog.mjs",
+  "piagent-migrate": "scripts/migrate-project-state.mjs",
+  "piagent-import-instructions": "scripts/import-agent-instructions.mjs",
+  "piagent-auto": "scripts/pi-auto.sh"
+};
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const invokedAs = path.basename(process.argv[1] ?? "");
+const script = scriptByCommand[invokedAs];
+
+if (!script) {
+  console.error(`Unknown Pi Agent command: ${invokedAs || "(unknown)"}`);
+  console.error(`Expected one of: ${Object.keys(scriptByCommand).sort().join(", ")}`);
+  process.exit(2);
+}
+
+const target = path.join(packageRoot, script);
+const runner = target.endsWith(".mjs") ? process.execPath : "bash";
+const child = spawn(runner, [target, ...process.argv.slice(2)], {
+  cwd: process.cwd(),
+  env: process.env,
+  stdio: "inherit"
+});
+
+child.once("error", (error) => {
+  const code = error && typeof error === "object" && "code" in error ? ` (${error.code})` : "";
+  console.error(`Pi Agent command could not start ${runner}${code}. Ensure it is installed and available on PATH.`);
+  process.exit(1);
+});
+
+child.once("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});