@piagent/platform 1.2.17 → 1.3.0-ie.9

package/scripts/model-route-evaluation.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { evaluateModelRouteCorpus } from "./model-route-evaluation-core.ts";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const corpus = JSON.parse(fs.readFileSync(path.join(root, "benchmarks/model-routing-v1/route-corpus.json"), "utf8"));
+const report = evaluateModelRouteCorpus(corpus);
+const outputIndex = process.argv.indexOf("--output");
+if (outputIndex >= 0) {
+  const value = process.argv[outputIndex + 1];
+  if (!value) throw new Error("--output requires a path");
+  const target = path.resolve(value);
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(target, `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
+  try { fs.chmodSync(path.dirname(target), 0o700); fs.chmodSync(target, 0o600); } catch {}
+} else {
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+if (Object.values(report.gates).some((passed) => !passed)) process.exitCode = 1;

package/scripts/model-routing-benchmark.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { buildRoutedModelRoutingProtocol } from "./model-routing-protocol-core.ts";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const argv = process.argv.slice(2);
+const value = (name, fallback) => { const index = argv.indexOf(name); return index >= 0 ? argv[index + 1] : fallback; };
+if (argv.includes("--help")) {
+  process.stdout.write("Usage: node scripts/model-routing-benchmark.mjs --dry-run [--seed value] [--revision hex] [--output file]\nAuthenticated execution is intentionally unavailable until separately authorized.\n");
+  process.exit(0);
+}
+if (!argv.includes("--dry-run")) throw new Error("Adaptive routing model execution requires separate operator authorization; run --dry-run to validate the pinned 144-session protocol.");
+const corpus = JSON.parse(fs.readFileSync(path.join(root, "benchmarks/model-routing-v1/route-corpus.json"), "utf8"));
+const catalog = {
+  schemaVersion: 1, capturedAt: "2026-08-08T00:00:00.000Z", source: "authenticated-catalog", availability: "authenticated",
+  models: [
+    { provider: "openai-codex", modelId: "gpt-5.6-luna", contextWindow: null, reasoning: true, imageInput: null, supportedThinkingLevels: ["medium"] },
+    { provider: "openai-codex", modelId: "gpt-5.6-terra", contextWindow: null, reasoning: true, imageInput: null, supportedThinkingLevels: ["medium"] },
+    { provider: "openai-codex", modelId: "gpt-5.6-sol", contextWindow: null, reasoning: true, imageInput: null, supportedThinkingLevels: ["high", "xhigh"] }
+  ], warnings: []
+};
+const manifest = buildRoutedModelRoutingProtocol({ corpus, catalog, repositoryRevision: value("--revision", "0000000"), seed: value("--seed", "model-routing-v1-seed") });
+const target = value("--output");
+if (target) {
+  const output = path.resolve(target); fs.mkdirSync(path.dirname(output), { recursive: true, mode: 0o700 }); fs.writeFileSync(output, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+} else process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);

package/scripts/model-routing-protocol-core.ts

@@ -0,0 +1,64 @@
+import crypto from "node:crypto";
+
+import type { AuthenticatedModelCatalog } from "../packages/piagent-core/runtime/model/authenticated-catalog.ts";
+import { routeParentModel } from "../packages/piagent-core/runtime/model/model-route-policy.ts";
+import { authenticatedCatalogDigest } from "../packages/piagent-core/runtime/model/model-route-types.ts";
+import { extractTaskFeatures } from "../packages/piagent-core/runtime/solver/task-features.ts";
+import {
+  buildModelRoutingProtocol,
+  type ModelRoutingProtocolManifest,
+  type ModelRoutingRouteProjection
+} from "../packages/piagent-core/benchmark/model-routing-protocol.ts";
+import {
+  validateModelRouteCorpus,
+  type ModelRouteCorpus
+} from "../packages/piagent-core/benchmark/model-route-grader.ts";
+
+function sha(value: string): string {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+export function buildRoutedModelRoutingProtocol(input: {
+  corpus: ModelRouteCorpus | unknown;
+  catalog: AuthenticatedModelCatalog;
+  repositoryRevision: string;
+  seed: string;
+}): ModelRoutingProtocolManifest {
+  const corpus = validateModelRouteCorpus(input.corpus);
+  const routes: Record<string, ModelRoutingRouteProjection> = {};
+  for (const task of corpus.templates) {
+    const features = extractTaskFeatures({
+      ...structuredClone(corpus.defaults),
+      ...structuredClone(task.overrides),
+      request: task.request
+    });
+    const route = routeParentModel({
+      features,
+      catalog: input.catalog,
+      mode: "auto",
+      objective: "balance",
+      selectionSource: "workspace-default",
+      current: { provider: "openai-codex", modelId: "gpt-5.6-sol", effort: "high" },
+      freshTaskBoundary: true,
+      hostBoundary: "prelaunch"
+    });
+    routes[task.id] = {
+      taskId: task.id,
+      promptHash: sha(task.request),
+      featureHash: features.featureHash,
+      decisionDigest: route.decisionDigest,
+      capabilityBand: route.capabilityBand,
+      enforced: route.enforced,
+      provider: route.provider,
+      modelId: route.modelId,
+      effort: route.effort
+    };
+  }
+  return buildModelRoutingProtocol({
+    corpus,
+    routes,
+    catalogDigest: authenticatedCatalogDigest(input.catalog),
+    repositoryRevision: input.repositoryRevision,
+    seed: input.seed
+  });
+}

package/scripts/phase-tools-evaluation.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { performance } from "node:perf_hooks";
+
+import { createPiHarness, writeRuntimeStubs } from "../tests/helpers/guard-harness.mjs";
+import { createTrajectoryState, createTrajectoryTransition, reduceTrajectory, replayTrajectory } from "../packages/piagent-core/runtime/trajectory/trajectory-state.ts";
+import { PhaseToolRuntime, intendedPhaseTools } from "../packages/piagent-core/runtime/tools/phase-tool-runtime.ts";
+import { PIAGENT_MUTATION_CAPABLE_TOOLS, phaseToolPolicy } from "../packages/piagent-core/runtime/tools/phase-tools.ts";
+
+const repoRoot = path.resolve(import.meta.dirname, "..");
+const hostTools = ["read", "grep", "find", "ls", "edit", "write", "apply_patch", "bash"];
+const outputIndex = process.argv.indexOf("--output");
+const outputPath = outputIndex >= 0 ? path.resolve(process.argv[outputIndex + 1] ?? "") : undefined;
+
+const lanes = [
+  { id: "read-only", changeMode: "read-only", riskLane: "normal", phases: ["scout", "review", "handoff"], p2: ["piagent_task_start", "piagent_task_progress"] },
+  { id: "tiny", changeMode: "source-change", riskLane: "tiny", phases: ["execute", "verify", "handoff"], p2: ["piagent_task_start"] },
+  { id: "normal", changeMode: "source-change", riskLane: "normal", phases: ["plan", "execute", "verify", "review", "handoff"], p2: ["piagent_task_start", "piagent_task_progress"] },
+  { id: "high-risk", changeMode: "source-change", riskLane: "high-risk", phases: ["scout", "plan", "execute", "verify", "review", "handoff"], p2: ["piagent_task_start", "piagent_task_progress", "piagent_context_record", "piagent_verify_record", "piagent_trace_record", "piagent_task_gate_check"] }
+];
+
+async function registeredTools() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "piagent-p3-evaluation-"));
+  try {
+    writeRuntimeStubs(root);
+    fs.cpSync(path.join(repoRoot, "packages", "piagent-core"), path.join(root, "packages", "piagent-core"), { recursive: true });
+    fs.copyFileSync(path.join(repoRoot, "package.json"), path.join(root, "package.json"));
+    const moduleUrl = pathToFileURL(path.join(root, "packages", "piagent-core", "extensions", "piagent-guard.ts")).href;
+    const guard = (await import(`${moduleUrl}?evaluation=${Date.now()}`)).default;
+    const harness = createPiHarness({ activeTools: hostTools });
+    guard(harness.pi);
+    return {
+      tools: new Map([...harness.tools].map(([name, tool]) => [name, {
+        name,
+        description: tool.description,
+        parameters: tool.parameters,
+        promptGuidelines: tool.promptGuidelines,
+        executionMode: tool.executionMode
+      }])),
+      hooks: new Set(harness.handlers.keys())
+    };
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function schemaBytes(names, tools) {
+  return Buffer.byteLength(JSON.stringify(names.map((name) => tools.get(name)).filter(Boolean)));
+}
+
+function replayLane(lane, index) {
+  const initial = createTrajectoryState({
+    taskId: `p3-${lane.id}`,
+    taskRunId: `p3-${lane.id}-run-1`,
+    sessionId: "private-session",
+    changeMode: lane.changeMode,
+    riskLane: lane.riskLane,
+    createdAt: "2026-08-08T00:00:00.000Z"
+  });
+  const causes = { scout: "context-observed", plan: "plan-observed", execute: "mutation-observed", verify: "verification-passed", review: "review-observed", handoff: "handoff-observed", terminal: "task-terminal" };
+  const events = [];
+  let current = initial;
+  for (const [phaseIndex, phase] of [...lane.phases, "terminal"].entries()) {
+    const terminalTaskOutcomeRef = phase === "terminal"
+      ? { taskRunId: initial.taskRunId, taskUpdatedAt: "2026-08-08T00:01:00.000Z", taskDigest: "a".repeat(64) }
+      : null;
+    const event = createTrajectoryTransition(current, {
+      to: phase,
+      cause: causes[phase],
+      sourceHook: phase === "terminal" ? "completion" : "task-state",
+      observedAt: `2026-08-08T00:00:${String(index * 10 + phaseIndex + 1).padStart(2, "0")}.000Z`,
+      terminalTaskOutcomeRef
+    });
+    events.push(event);
+    current = reduceTrajectory(current, event);
+  }
+  const replayed = replayTrajectory(initial, events);
+  return { id: lane.id, events: events.length, finalPhase: replayed.currentPhase, deterministic: JSON.stringify(replayed) === JSON.stringify(current) };
+}
+
+const { tools, hooks } = await registeredTools();
+const phaseRows = [];
+let p2WeightedBytes = 0;
+let phaseWeightedBytes = 0;
+for (const lane of lanes) {
+  const p2Bytes = schemaBytes(lane.p2, tools);
+  for (const phase of lane.phases) {
+    const policy = phaseToolPolicy(phase, lane.changeMode);
+    const visible = intendedPhaseTools([...hostTools, ...tools.keys()], [...hostTools, ...tools.keys()], { currentPhase: phase, changeMode: lane.changeMode });
+    const piagent = visible.filter((name) => tools.has(name));
+    const bytes = schemaBytes(piagent, tools);
+    phaseRows.push({ lane: lane.id, phase, p2PiagentTools: lane.p2.length, phasePiagentTools: piagent.length, p2SchemaBytes: p2Bytes, phaseSchemaBytes: bytes, requiredHostTools: policy.requiredHostTools, piagentTools: piagent });
+    p2WeightedBytes += p2Bytes;
+    phaseWeightedBytes += bytes;
+  }
+}
+
+const descriptions = new Map();
+for (const [name, tool] of tools) {
+  const normalized = String(tool.description ?? "").trim().toLowerCase().replace(/\s+/g, " ");
+  descriptions.set(normalized, [...(descriptions.get(normalized) ?? []), name]);
+}
+const duplicateDescriptions = [...descriptions.values()].filter((names) => names.length > 1);
+const replay = lanes.map(replayLane);
+const runtimeOwnedEvidenceTools = ["piagent_context_record", "piagent_verify_record", "piagent_task_gate_check", "piagent_trace_record"];
+const checks = [
+  { id: "read-only-no-direct-mutator", passed: phaseRows.filter((row) => row.lane === "read-only").every((row) => row.piagentTools.every((tool) => !PIAGENT_MUTATION_CAPABLE_TOOLS.has(tool)) && row.requiredHostTools.every((tool) => !["edit", "write", "apply_patch"].includes(tool))) },
+  { id: "review-carrier-checked-shell-retained", passed: phaseRows.filter((row) => row.phase === "review").every((row) => row.piagentTools.every((tool) => !PIAGENT_MUTATION_CAPABLE_TOOLS.has(tool)) && row.requiredHostTools.includes("bash") && row.requiredHostTools.every((tool) => !["edit", "write", "apply_patch"].includes(tool))) },
+  { id: "verify-surface-complete", passed: phaseRows.filter((row) => row.phase === "verify").every((row) => row.requiredHostTools.includes("bash") && runtimeOwnedEvidenceTools.every((tool) => !row.piagentTools.includes(tool))) },
+  { id: "handoff-surface-complete", passed: phaseRows.filter((row) => row.phase === "handoff").every((row) => row.requiredHostTools.includes("read") && runtimeOwnedEvidenceTools.every((tool) => !row.piagentTools.includes(tool))) },
+  { id: "runtime-evidence-surface-complete", passed: runtimeOwnedEvidenceTools.every((tool) => tools.has(tool)) && ["tool_result", "message_end"].every((hook) => hooks.has(hook)) },
+  { id: "high-risk-review-retained", passed: lanes.find((lane) => lane.id === "high-risk").phases.includes("review") },
+  { id: "duplicate-descriptions-zero", passed: duplicateDescriptions.length === 0 },
+  { id: "trajectory-replay-100-percent", passed: replay.every((item) => item.deterministic && item.finalPhase === "terminal") }
+];
+
+function runtimeContractProbe(mode) {
+  const active = [...hostTools, ...tools.keys()];
+  const initial = [...active];
+  const setCalls = [];
+  const telemetry = [];
+  const pi = {
+    getActiveTools: () => [...active],
+    getAllTools: () => active.map((name) => ({ name })),
+    setActiveTools: (names) => { setCalls.push([...names]); active.splice(0, active.length, ...names); }
+  };
+  const runtime = new PhaseToolRuntime(pi, mode, (_ctx, payload) => telemetry.push(payload));
+  const valid = [];
+  const deniedMutations = [];
+  for (const [laneIndex, lane] of lanes.entries()) {
+    for (const [phaseIndex, phase] of lane.phases.entries()) {
+      const state = {
+        ...createTrajectoryState({
+          taskId: `contract-${mode}-${lane.id}-${phase}`,
+          taskRunId: `contract-${mode}-${lane.id}-${phase}-run-1`,
+          sessionId: "private-session",
+          changeMode: lane.changeMode,
+          riskLane: lane.riskLane,
+          createdAt: "2026-08-08T00:00:00.000Z"
+        }),
+        currentPhase: phase,
+        sequence: laneIndex * 10 + phaseIndex
+      };
+      const ctx = { cwd: `/tmp/phase-contract/${lane.id}/${phase}`, sessionManager: { getSessionId: () => "private-session" } };
+      runtime.apply(ctx, { enforcementSafe: true, state, transitions: [], warnings: [], status: "ok", initialized: false });
+      const policy = phaseToolPolicy(phase, lane.changeMode);
+      for (const tool of policy.requiredHostTools) valid.push({ lane: lane.id, phase, tool, blocked: Boolean(runtime.toolDecision(ctx, tool)?.block) });
+      if (phase === "review") {
+        valid.push({ lane: lane.id, phase, tool: "bash-read-only-carrier", blocked: Boolean(runtime.mutationDecision(ctx, { projectMutation: false, verificationCarrier: true })?.block) });
+        deniedMutations.push({ lane: lane.id, phase, carrier: "bash-project-mutation", blocked: Boolean(runtime.mutationDecision(ctx, { projectMutation: true, verificationCarrier: true })?.block) });
+      }
+      if (phase === "plan") deniedMutations.push({ lane: lane.id, phase, carrier: "direct-edit", blocked: Boolean(runtime.mutationDecision(ctx, { projectMutation: true })?.block) });
+      if (phase === "verify") deniedMutations.push({ lane: lane.id, phase, carrier: "shell-redirection", blocked: Boolean(runtime.mutationDecision(ctx, { projectMutation: true, verificationCarrier: true })?.block) });
+    }
+  }
+  return {
+    mode,
+    providerSchema: { initialCount: initial.length, finalCount: active.length, setActiveToolsCalls: setCalls.length, unchanged: JSON.stringify(active) === JSON.stringify(initial) },
+    validCalls: { evaluated: valid.length, blocked: valid.filter((item) => item.blocked).length, examples: valid.filter((item) => item.blocked) },
+    deniedMutations: { evaluated: deniedMutations.length, blocked: deniedMutations.filter((item) => item.blocked).length, examples: deniedMutations.filter((item) => !item.blocked) },
+    activationTelemetry: telemetry.length
+  };
+}
+
+const strictContract = runtimeContractProbe("on");
+const shadowContract = runtimeContractProbe("shadow");
+checks.push(
+  { id: "provider-schema-stable-shadow", passed: shadowContract.providerSchema.unchanged && shadowContract.providerSchema.setActiveToolsCalls === 0 },
+  { id: "provider-schema-stable-strict", passed: strictContract.providerSchema.unchanged && strictContract.providerSchema.setActiveToolsCalls === 0 },
+  { id: "valid-call-block-rate-zero", passed: strictContract.validCalls.evaluated > 0 && strictContract.validCalls.blocked === 0 },
+  { id: "denied-mutation-carrier-parity", passed: strictContract.deniedMutations.evaluated > 0 && strictContract.deniedMutations.blocked === strictContract.deniedMutations.evaluated },
+  { id: "shadow-never-blocks", passed: shadowContract.validCalls.blocked === 0 && shadowContract.deniedMutations.blocked === 0 }
+);
+
+const durations = [];
+for (let index = 0; index < 2_000; index += 1) {
+  const lane = lanes[index % lanes.length];
+  const phase = lane.phases[index % lane.phases.length];
+  const start = performance.now();
+  intendedPhaseTools([...hostTools, ...tools.keys()], [...hostTools, ...tools.keys()], { currentPhase: phase, changeMode: lane.changeMode });
+  durations.push(performance.now() - start);
+}
+durations.sort((left, right) => left - right);
+const reduction = p2WeightedBytes === 0 ? 0 : (p2WeightedBytes - phaseWeightedBytes) / p2WeightedBytes;
+const report = {
+  schemaVersion: 1,
+  evaluationId: `phase-tools-${new Date().toISOString().replace(/[-:.]/g, "")}`,
+  generatedAt: new Date().toISOString(),
+  platformVersion: "1.2.17",
+  piHostVersion: "0.84.1",
+  methodology: {
+    baseline: "P2 cache-stable Piagent management schemas retained for each active lane after task intake.",
+    candidate: "Phase intent is enforced at tool-call and mutation-carrier boundaries while the provider-visible schema remains byte-for-byte stable for the task.",
+    measurement: "Runtime probes measure actual schema replacement calls, valid-call blocks, mutation-carrier denials, and shadow non-interference. The legacy schemaReduction fields are counterfactual intended-surface estimates only and are not release or token claims.",
+    limitations: "Static schema and invariant evaluation; task quality and authorization regressions are gated by the repository test suites, not inferred here."
+  },
+  registeredPiagentTools: tools.size,
+  evaluatedTurns: phaseRows.length,
+  p2WeightedSchemaBytes: p2WeightedBytes,
+  phaseWeightedSchemaBytes: phaseWeightedBytes,
+  schemaReduction: Number(reduction.toFixed(4)),
+  schemaReductionPercent: Number((reduction * 100).toFixed(2)),
+  schemaReductionSemantics: "counterfactual-intended-surface-only",
+  runtimeContract: { strict: strictContract, shadow: shadowContract },
+  duplicateDescriptions,
+  missingToolEvents: checks.filter((check) => !check.passed && check.id.includes("surface")).length,
+  replay,
+  checks,
+  latencyMs: { samples: durations.length, p95: Number(durations[Math.ceil(durations.length * 0.95) - 1].toFixed(6)), max: Number(durations.at(-1).toFixed(6)) },
+  phaseRows,
+  gatePassed: checks.every((check) => check.passed)
+};
+
+if (outputPath) {
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(outputPath, `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
+}
+process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+if (!report.gatePassed) process.exitCode = 1;

package/scripts/pi-model-catalog.sh

@@ -1,164 +1,5 @@
 #!/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=""
-
-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)
-      FORMAT="json"
-      shift
-      ;;
-    --provider)
-      require_value "$1" "${2:-}"
-      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
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+exec node "$ROOT/scripts/model-catalog.mjs" "$@"

package/scripts/pi-model-route.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { capturePiModelCatalog } from "./model-catalog.mjs";
+import { resolveProjectProfileDocument } from "../packages/piagent-core/capabilities/project-profile.js";
+import { classifyContextTask } from "../packages/piagent-core/extensions/context-engine.js";
+import { matchesProtectedPath } from "../packages/piagent-core/extensions/policy-core.js";
+import { routeParentModel } from "../packages/piagent-core/runtime/model/model-route-policy.ts";
+import { extractTaskFeatures } from "../packages/piagent-core/runtime/solver/task-features.ts";
+
+const platformRoot = fileURLToPath(new URL("..", import.meta.url));
+
+function usage() {
+  process.stdout.write(`Usage:
+  piagent-route --prompt <task> [--objective intelligence|balance|cost] [--json]
+  piagent-route --prompt-file <file> [--execute --yes] [--] [pi args...]
+
+Classifies one fresh task before Pi starts, checks Pi's authenticated catalog,
+and recommends an exact model/effort. --execute is an explicit prelaunch action;
+it refuses pins, blocked preflight, missing catalog entries, and unsafe ambiguity.
+The task text is never written to Piagent route evidence.
+`);
+}
+
+function fail(message) { throw Object.assign(new Error(message), { exitCode: 2 }); }
+function git(args) { const value = spawnSync("git", args, { encoding: "utf8" }); return value.status === 0; }
+function readJson(file) { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return undefined; } }
+function stringArray(value) { return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim()) : []; }
+function profileFacts() {
+  const basePolicy = readJson(new URL("../packages/piagent-core/policies/base-policy.json", import.meta.url)) ?? {};
+  const stored = readJson(".pi/piagent-profile.json");
+  let profile = stored, resolved = true;
+  try {
+    if (stored) profile = resolveProjectProfileDocument(platformRoot, stored).profile;
+  } catch { resolved = false; profile = undefined; }
+  const profileMode = String(profile?.mode ?? profile?.projectId ?? "").trim() || null;
+  let verifierReady = Object.values(profile?.verifyCommands ?? {}).some((commands) => Array.isArray(commands) && commands.some((command) => typeof command === "string" && command.trim()));
+  try {
+    const manifest = JSON.parse(fs.readFileSync("package.json", "utf8"));
+    verifierReady ||= ["verify", "test", "typecheck", "check"].some((name) => typeof manifest.scripts?.[name] === "string");
+  } catch {}
+  return {
+    profileMode,
+    verifierReady,
+    resolved,
+    protectedPaths: [...new Set([...stringArray(basePolicy.protectedPaths), ...stringArray(profile?.protectedPaths)])]
+  };
+}
+
+function parse(argv) {
+  const options = { prompt: "", promptFile: "", objective: "balance", json: false, execute: false, yes: false, pinned: false, currentModel: "openai-codex/gpt-5.6-sol", currentEffort: "high", passthrough: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--") { options.passthrough = argv.slice(index + 1); break; }
+    if (arg === "--help" || arg === "-h") { usage(); process.exit(0); }
+    if (["--prompt", "--prompt-file", "--objective", "--current-model", "--current-effort"].includes(arg)) {
+      if (!argv[index + 1]) fail(`${arg} requires a value`);
+      const field = { "--prompt": "prompt", "--prompt-file": "promptFile", "--objective": "objective", "--current-model": "currentModel", "--current-effort": "currentEffort" }[arg];
+      options[field] = argv[++index];
+    } else if (arg === "--json") options.json = true;
+    else if (arg === "--execute") options.execute = true;
+    else if (arg === "--yes") options.yes = true;
+    else if (arg === "--pinned") options.pinned = true;
+    else fail(`unknown option ${arg}`);
+  }
+  if (!options.prompt && !options.promptFile) fail("provide exactly one of --prompt or --prompt-file");
+  if (options.prompt && options.promptFile) fail("provide exactly one of --prompt or --prompt-file");
+  if (!["intelligence", "balance", "cost"].includes(options.objective)) fail("--objective must be intelligence, balance, or cost");
+  if (options.execute && !options.yes) fail("--execute requires --yes because it starts a provider-backed Pi task");
+  if (options.passthrough.some((arg) => arg === "--model" || arg === "-m" || arg.startsWith("--model="))) fail("pass --pinned instead of combining router execution with a Pi --model override");
+  return options;
+}
+
+try {
+  const options = parse(process.argv.slice(2));
+  const request = options.prompt || fs.readFileSync(options.promptFile, "utf8").trim();
+  if (!request) fail("task prompt is empty");
+  const profile = profileFacts(), gitReady = git(["rev-parse", "--is-inside-work-tree"]);
+  const requestedPaths = classifyContextTask(request).paths;
+  const protectedTarget = requestedPaths.some((candidate) => matchesProtectedPath(candidate, profile.protectedPaths));
+  const catalogReport = capturePiModelCatalog({ offline: false, provider: "openai-codex" });
+  const catalog = {
+    schemaVersion: 1, capturedAt: catalogReport.capturedAt, source: "authenticated-catalog", availability: catalogReport.availability,
+    models: catalogReport.models.map((model) => ({ provider: model.provider, modelId: model.modelId, contextWindow: model.contextWindow, reasoning: model.reasoning, imageInput: model.imageInput, supportedThinkingLevels: model.supportedThinkingLevels })),
+    warnings: catalogReport.warnings
+  };
+  const [currentProvider, ...modelParts] = options.currentModel.split("/");
+  const currentModelId = modelParts.join("/");
+  if (!currentProvider || !currentModelId) fail("--current-model must be provider/model");
+  const features = extractTaskFeatures({
+    request, profileMode: profile.profileMode, projectShape: [], gitReady, dirtyTree: gitReady ? !git(["diff", "--quiet"]) : null,
+    verifierReady: profile.verifierReady, contextPressure: null, activeTaskState: "none", runtimeCapabilitiesKnown: catalog.availability === "authenticated" && profile.resolved,
+    userPinnedProvider: currentProvider, userPinnedModel: currentModelId, userPinnedEffort: options.currentEffort, protectedTarget
+  });
+  const decision = routeParentModel({
+    features, catalog, mode: options.execute ? "auto" : "recommend", objective: options.objective,
+    selectionSource: options.pinned ? "explicit-user-pin" : "workspace-default",
+    current: { provider: currentProvider, modelId: currentModelId, effort: options.currentEffort }, freshTaskBoundary: true, hostBoundary: options.execute ? "prelaunch" : "unavailable"
+  });
+  const report = { schemaVersion: 1, featureHash: features.featureHash, decision, promptStored: false, providerCalls: options.execute ? "task-only-after-route" : 0 };
+  if (options.json || !options.execute) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!options.execute) process.exit(0);
+  if (!decision.enforced || !decision.provider || !decision.modelId || !decision.effort) fail(`route cannot execute: ${decision.disposition}; ${decision.reasonCodes.join(",")}`);
+  const child = spawnSync("pi", [...options.passthrough, "--model", `${decision.provider}/${decision.modelId}`, "--thinking", decision.effort, request], {
+    stdio: "inherit",
+    env: { ...process.env, PIAGENT_PARENT_ROUTING: "auto", PIAGENT_MODEL_SELECTION_SOURCE: "router-selected", PIAGENT_ROUTING_DECISION_DIGEST: decision.decisionDigest }
+  });
+  if (child.error) throw child.error;
+  process.exit(child.status ?? 1);
+} catch (error) {
+  process.stderr.write(`FAIL: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(error?.exitCode ?? 1);
+}