@piagent/platform 1.2.17 → 1.3.0-ie.8

package/packages/piagent-core/runtime/session/tool-result-compaction.ts

@@ -80,6 +80,71 @@ function shouldCompactToolResultText(text: string): boolean {
     || toolResultLineCount(text) > TOOL_RESULT_COMPACT_LINE_THRESHOLD;
 }
 
+function aggregateContentText(content: unknown[]): { text: string; count: number } | undefined {
+  const entries = content.flatMap((block, index) => {
+    if (!block || typeof block !== "object") return [];
+    const typed = block as { type?: unknown; text?: unknown };
+    return typed.type === "text" && typeof typed.text === "string"
+      ? [{ source: `content[${index}].text`, text: typed.text }]
+      : [];
+  });
+  if (entries.length < 2) return undefined;
+  return {
+    count: entries.length,
+    text: entries.map((entry) => `[${entry.source}]\n${entry.text}`).join("\n\n")
+  };
+}
+
+function serializableDetailsText(value: unknown): string | undefined {
+  const seen = new WeakSet<object>();
+  try {
+    return JSON.stringify(value, (_key, item) => {
+      if (typeof item === "bigint") return `${item}n`;
+      if (!item || typeof item !== "object") return item;
+      if (seen.has(item)) return "[circular]";
+      seen.add(item);
+      return item;
+    }, 2);
+  } catch {
+    return undefined;
+  }
+}
+
+type OversizedLeafStats = { count: number; chars: number; maxDepth: number };
+
+function oversizedStringLeaves(value: unknown, seen = new WeakSet<object>(), depth = 0): OversizedLeafStats {
+  if (typeof value === "string") return shouldCompactToolResultText(value)
+    ? { count: 1, chars: value.length, maxDepth: depth }
+    : { count: 0, chars: 0, maxDepth: 0 };
+  if (!value || typeof value !== "object" || depth >= 12 || seen.has(value)) return { count: 0, chars: 0, maxDepth: 0 };
+  seen.add(value);
+  const children = Array.isArray(value) ? value : isPlainRecord(value) ? Object.values(value) : [];
+  const result = { count: 0, chars: 0, maxDepth: 0 };
+  for (const child of children) {
+    const nested = oversizedStringLeaves(child, seen, depth + 1);
+    result.count += nested.count;
+    result.chars += nested.chars;
+    result.maxDepth = Math.max(result.maxDepth, nested.maxDepth);
+  }
+  return result;
+}
+
+function compactDetailsEnvelope(value: unknown, preview: string): unknown {
+  if (Array.isArray(value)) return [{ piagentCompactedDetails: preview }];
+  if (!isPlainRecord(value)) return preview;
+  const preserved: Record<string, unknown> = {};
+  let preservedChars = 0;
+  for (const [key, item] of Object.entries(value)) {
+    if (Object.keys(preserved).length >= 16) break;
+    if (!(item === null || typeof item === "boolean" || typeof item === "number" || (typeof item === "string" && item.length <= 200))) continue;
+    const chars = key.length + String(item).length;
+    if (preservedChars + chars > 1_000) break;
+    preserved[key] = item;
+    preservedChars += chars;
+  }
+  return { ...preserved, piagentCompactedDetails: preview };
+}
+
 function clipPreviewLine(line: string, maxChars = 260): string {
   if (line.length <= maxChars) return line;
   return `${line.slice(0, maxChars).trimEnd()} ... [line clipped]`;
@@ -257,6 +322,23 @@ export function compactToolResultTextContent(
   cache: Map<string, ToolResultCaptureSummary>
 ): { content: unknown; captures: ToolResultCaptureSummary[] } {
   if (!Array.isArray(content)) return { content, captures: [] };
+  const aggregate = aggregateContentText(content);
+  if (aggregate && shouldCompactToolResultText(aggregate.text)) {
+    const source = `content[*].text (${aggregate.count} blocks)`;
+    const capture = writeToolResultCapture(cwd, event, ctx, source, aggregate.text, cache);
+    const preview = compactToolResultPreview(String(event?.toolName ?? "tool"), source, aggregate.text, capture);
+    let emitted = false;
+    return {
+      content: content.flatMap((block) => {
+        const typed = block && typeof block === "object" ? block as { type?: unknown; text?: unknown } : undefined;
+        if (typed?.type !== "text" || typeof typed.text !== "string") return [block];
+        if (emitted) return [];
+        emitted = true;
+        return [{ ...block, text: preview }];
+      }),
+      captures: [capture]
+    };
+  }
   const captures: ToolResultCaptureSummary[] = [];
   const compacted = content.map((block, index) => {
     if (!block || typeof block !== "object") return block;
@@ -283,6 +365,19 @@ export function compactToolResultDetails(
   source = "details",
   depth = 0
 ): unknown {
+  if (depth === 0 && (Array.isArray(value) || isPlainRecord(value))) {
+    const serialized = serializableDetailsText(value);
+    const largeLeaves = oversizedStringLeaves(value);
+    const nonLargePayloadChars = serialized ? Math.max(0, serialized.length - largeLeaves.chars) : 0;
+    const preserveOneReachableLeaf = largeLeaves.count === 1
+      && largeLeaves.maxDepth <= 6
+      && nonLargePayloadChars <= TOOL_RESULT_COMPACT_CHAR_THRESHOLD;
+    if (serialized && shouldCompactToolResultText(serialized) && !preserveOneReachableLeaf) {
+      const capture = writeToolResultCapture(cwd, event, ctx, source, serialized, cache);
+      captures.push(capture);
+      return compactDetailsEnvelope(value, compactToolResultPreview(String(event?.toolName ?? "tool"), source, serialized, capture));
+    }
+  }
   if (typeof value === "string") {
     if (!shouldCompactToolResultText(value)) return value;
     const capture = writeToolResultCapture(cwd, event, ctx, source, value, cache);

package/packages/piagent-core/runtime/solver/runtime-features.ts

@@ -0,0 +1,52 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { hasGitEvidenceRoot, workingTreeSnapshot } from "../../extensions/task-state.js";
+import type { ProjectProfile, TaskContract } from "../../extensions/guard-types.ts";
+import type { RuntimeModelSnapshot } from "../model/runtime-snapshot.ts";
+import { runtimeModelSnapshotDigest } from "../model/runtime-snapshot.ts";
+import type { TaskFeatureInput } from "./task-features.ts";
+import type { SolverShadowEvaluation } from "./solver-shadow.ts";
+import { SolverShadowRuntime } from "./solver-shadow.ts";
+
+export function runtimeTaskFeatureInput(options: {
+  request: string;
+  ctx: ExtensionContext;
+  profile: ProjectProfile;
+  activeTask?: TaskContract;
+  runtimeSnapshot?: RuntimeModelSnapshot;
+  effort: string | null;
+  protectedTarget: boolean;
+}): TaskFeatureInput {
+  const { request, ctx, profile, activeTask, runtimeSnapshot } = options;
+  const usage = ctx.getContextUsage?.();
+  const contextPressure = typeof usage?.percent === "number" && Number.isFinite(usage.percent)
+    ? Math.max(0, Math.min(1, usage.percent / 100))
+    : null;
+  const profileVerifier = Object.values(profile.verifyCommands ?? {}).some((commands) => commands.length > 0);
+  const taskVerifier = (activeTask?.verifyCommands?.length ?? 0) > 0;
+  const roles = Object.keys(profile.techStack?.roles ?? {});
+  return {
+    request,
+    profileMode: profile.mode ?? null,
+    projectShape: roles,
+    gitReady: hasGitEvidenceRoot(ctx.cwd),
+    dirtyTree: Object.keys(workingTreeSnapshot(ctx.cwd) as Record<string, string>).length > 0,
+    verifierReady: profileVerifier || taskVerifier,
+    contextPressure,
+    activeTaskState: !activeTask ? "none" : activeTask.trace.outcome === "pending" ? "pending" : "terminal",
+    runtimeSnapshotDigest: runtimeSnapshot ? runtimeModelSnapshotDigest(runtimeSnapshot) : null,
+    runtimeCapabilitiesKnown: Boolean(runtimeSnapshot?.capabilities.some((item) => item.value !== null)),
+    userPinnedProvider: runtimeSnapshot?.provider ?? ctx.model?.provider ?? null,
+    userPinnedModel: runtimeSnapshot?.modelId ?? ctx.model?.id ?? null,
+    userPinnedEffort: options.effort,
+    protectedTarget: options.protectedTarget
+  };
+}
+
+export function evaluateRuntimeSolver(
+  runtime: SolverShadowRuntime | undefined,
+  options: Parameters<typeof runtimeTaskFeatureInput>[0]
+): SolverShadowEvaluation {
+  if (!runtime) return { status: "off", durationMs: 0 };
+  return runtime.evaluate(options.ctx.cwd, options.ctx.sessionManager.getSessionId(), runtimeTaskFeatureInput(options));
+}

package/packages/piagent-core/runtime/solver/solver-explanation.ts

@@ -0,0 +1,50 @@
+import type { SolverShadowEvaluation } from "./solver-shadow.ts";
+
+export function solverPreflightProjection(evaluation: SolverShadowEvaluation): Record<string, unknown> {
+  if (evaluation.status !== "ok") return {
+    schemaVersion: 1,
+    status: evaluation.status,
+    durationMs: evaluation.durationMs,
+    warnings: evaluation.status === "error" ? evaluation.warnings : []
+  };
+  const { features, decision } = evaluation;
+  return {
+    schemaVersion: 1,
+    status: "ok",
+    shadow: decision.mode === "shadow" ? "no behavior changed" : decision.mode,
+    route: decision.route,
+    reasonCodes: decision.reasonCodes,
+    confidence: decision.confidence,
+    plannedPhases: decision.plannedPhases,
+    context: decision.context,
+    toolGroups: decision.toolGroups,
+    helper: decision.helper,
+    parentModel: decision.parentModel,
+    runtimeProvenance: {
+      snapshotDigest: features.runtimeSnapshotDigest,
+      capabilitiesKnown: features.runtimeCapabilitiesKnown
+    },
+    override: decision.override,
+    featureHash: decision.featureHash,
+    policyVersion: decision.policyVersion
+  };
+}
+
+export function formatSolverPreflight(evaluation: SolverShadowEvaluation): string {
+  const projection = solverPreflightProjection(evaluation);
+  if (evaluation.status === "off") return "solver: off";
+  if (evaluation.status === "error") return `solver: unavailable\nwarning: ${evaluation.warnings.join("; ")}`;
+  const helper = evaluation.decision.helper.needed ? `${evaluation.decision.helper.role} (advisory)` : "none";
+  const parent = [evaluation.decision.parentModel.provider, evaluation.decision.parentModel.modelId, evaluation.decision.parentModel.effort]
+    .filter(Boolean).join("/") || "unknown";
+  return [
+    `route: ${projection.route}; confidence: ${projection.confidence}`,
+    `reasons: ${evaluation.decision.reasonCodes.join(", ")}`,
+    `phases: ${evaluation.decision.plannedPhases.join(" → ")}`,
+    `tools: ${evaluation.decision.toolGroups.join(", ") || "none"}`,
+    `context: ${evaluation.decision.context.recommendation}/${evaluation.decision.context.budgetBand}`,
+    `helper: ${helper}; parent: ${parent} (advisory)`,
+    `runtime: ${evaluation.features.runtimeSnapshotDigest ?? "unavailable"}; capabilities: ${evaluation.features.runtimeCapabilitiesKnown ? "known" : "unknown"}`,
+    evaluation.decision.mode === "shadow" ? "shadow: no behavior changed" : `mode: ${evaluation.decision.mode}`
+  ].join("\n");
+}

package/packages/piagent-core/runtime/solver/solver-policy.ts

@@ -0,0 +1,65 @@
+import type { SolverDecision, SolverMode, SolverRoute, TaskFeatures } from "./solver-types.ts";
+import { SOLVER_POLICY_VERSION, validateSolverDecision, validateTaskFeatures } from "./solver-types.ts";
+
+function routeFor(features: TaskFeatures): { route: SolverRoute; reasons: string[] } {
+  const authorizationRisk = features.protectedTarget || features.externalAction || features.destructiveAction || features.permissionExpansion;
+  if (features.changeMode !== "plan-only" && features.changeMode !== "read-only" && authorizationRisk) return { route: "blocked-preflight", reasons: ["authorization-required"] };
+  if (features.workflowIntent === "review") return { route: "review-only", reasons: ["explicit-review-intent"] };
+  if (features.workflowIntent === "plan" || features.changeMode === "plan-only") return { route: "plan-first", reasons: ["explicit-plan-intent"] };
+  if (features.changeMode === "read-only" || ["diagnose", "scout"].includes(features.workflowIntent)) return { route: "scout-first", reasons: ["explicit-read-only-intent"] };
+  if (features.changeMode === "source-change" && features.gitReady === false) return { route: "blocked-preflight", reasons: ["git-not-ready"] };
+  if (features.changeMode === "source-change" && features.verifierReady === false) return { route: "blocked-preflight", reasons: ["verifier-missing"] };
+  if (features.riskLane === "high-risk") return { route: "plan-first", reasons: ["high-risk-source-work"] };
+  if (features.ambiguity === "high") return { route: "scout-first", reasons: ["ambiguous-scope"] };
+  if (features.scopeEstimate === "broad") return { route: "plan-first", reasons: ["broad-scope"] };
+  if (features.contextPressure !== null && features.contextPressure >= 0.72) return { route: "scout-first", reasons: ["high-context-pressure"] };
+  if (!features.profileMode || features.verifierReady === null || features.gitReady === null) return { route: "plan-first", reasons: ["readiness-unknown"] };
+  return { route: "direct", reasons: [features.explicitPathCount > 0 ? "explicit-path" : "bounded-ready-task"] };
+}
+
+function phases(route: SolverRoute, features: TaskFeatures): SolverDecision["plannedPhases"] {
+  if (route === "blocked-preflight") return ["intake", "handoff"];
+  if (route === "review-only") return ["intake", "context", "review", "handoff"];
+  if (features.changeMode === "plan-only") return ["intake", "context", "plan", "handoff"];
+  if (route === "scout-first" && features.changeMode === "read-only") return ["intake", "context", "review", "handoff"];
+  if (route === "scout-first") return ["intake", "context", "plan", "implement", "verify", "review"];
+  if (route === "plan-first") return ["intake", "context", "plan", "implement", "verify", "review"];
+  return ["intake", "context", "implement", "verify", "review"];
+}
+
+function toolGroups(route: SolverRoute, features: TaskFeatures): string[] {
+  if (route === "blocked-preflight") return ["governance", "policy"];
+  if (features.changeMode === "read-only" || features.changeMode === "plan-only" || route === "review-only") return ["governance", "retrieval", "knowledge"];
+  return route === "direct" ? ["intake", "task"] : ["intake", "governance", "retrieval", "task"];
+}
+
+export function solveTaskFeatures(input: TaskFeatures, mode: Exclude<SolverMode, "off"> = "shadow"): SolverDecision {
+  const features = validateTaskFeatures(input);
+  const selected = routeFor(features);
+  const helperRole = selected.route === "review-only" ? "reviewer" : selected.route === "scout-first" ? "scout" : selected.route === "plan-first" && features.scopeEstimate === "broad" ? "planner" : null;
+  const contextRecommendation = selected.route === "blocked-preflight" ? "none" : features.explicitPathCount > 0 ? "targeted" : "bounded";
+  const budgetBand = contextRecommendation === "none" ? "none" : features.contextPressure !== null && features.contextPressure >= 0.72 ? "small" : features.scopeEstimate === "broad" ? "large" : "medium";
+  const reasons = [...selected.reasons];
+  if (!features.runtimeCapabilitiesKnown) reasons.push("runtime-capabilities-unknown");
+  if (features.dirtyTree === true) reasons.push("dirty-tree-observed");
+  return validateSolverDecision({
+    schemaVersion: 1,
+    policyVersion: SOLVER_POLICY_VERSION,
+    featureHash: features.featureHash,
+    route: selected.route,
+    plannedPhases: phases(selected.route, features),
+    context: { recommendation: contextRecommendation, budgetBand },
+    toolGroups: toolGroups(selected.route, features),
+    helper: { needed: helperRole !== null, role: helperRole, enforced: false },
+    parentModel: {
+      provider: features.userPinnedProvider,
+      modelId: features.userPinnedModel,
+      effort: features.userPinnedEffort,
+      enforced: false
+    },
+    reasonCodes: [...new Set(reasons)],
+    confidence: selected.route === "blocked-preflight" || features.ambiguity === "low" ? "high" : features.ambiguity === "high" || !features.runtimeCapabilitiesKnown ? "low" : "medium",
+    mode,
+    override: { observed: false, route: null, recordedAt: null }
+  });
+}

package/packages/piagent-core/runtime/solver/solver-shadow.ts

@@ -0,0 +1,204 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { resolveLocalStatePath } from "../../extensions/local-state-path.js";
+import { appendJsonlBounded } from "../../extensions/state-retention.js";
+import { solveTaskFeatures } from "./solver-policy.ts";
+import { extractTaskFeatures } from "./task-features.ts";
+import type { TaskFeatureInput } from "./task-features.ts";
+import type { SolverDecision, SolverMode, SolverRoute, TaskFeatures } from "./solver-types.ts";
+import { validateSolverDecision, validateTaskFeatures } from "./solver-types.ts";
+
+export const SOLVER_SHADOW_EVENT_SCHEMA_VERSION = 1 as const;
+const MAX_EVENT_BYTES = 512 * 1024;
+
+export type SolverShadowEvent = {
+  schemaVersion: typeof SOLVER_SHADOW_EVENT_SCHEMA_VERSION;
+  recordedAt: string;
+  sessionHash: string;
+  featureHash: string;
+  features: TaskFeatures;
+  decision: SolverDecision;
+};
+
+export type SolverShadowEvaluation =
+  | { status: "off"; durationMs: 0 }
+  | { status: "error"; durationMs: number; warnings: string[] }
+  | {
+      status: "ok";
+      durationMs: number;
+      reused: boolean;
+      persisted: boolean;
+      warnings: string[];
+      features: TaskFeatures;
+      decision: SolverDecision;
+    };
+
+export type SolverOverrideCapture =
+  | { status: "no-decision" | "same-route" }
+  | { status: "error"; warnings: string[] }
+  | { status: "recorded"; decision: SolverDecision; persisted: boolean; warnings: string[] };
+
+export type SolverShadowTelemetryView = {
+  records: SolverShadowEvent[];
+  latest?: SolverShadowEvent;
+  corruptions: string[];
+  routingSafe: boolean;
+};
+
+type SolverShadowDependencies = {
+  extract?: typeof extractTaskFeatures;
+  solve?: typeof solveTaskFeatures;
+  persist?: typeof recordSolverShadowEvent;
+  now?: () => number;
+};
+
+const HASH = /^[a-f0-9]{64}$/;
+
+export function solverModeFromEnvironment(value: unknown): SolverMode {
+  const normalized = String(value ?? "shadow").trim().toLowerCase();
+  return normalized === "off" || normalized === "recommend" ? normalized : "shadow";
+}
+
+export function solverShadowEventPath(cwd: string): string {
+  return path.join(cwd, ".pi", "piagent-state", "solver", "decisions.jsonl");
+}
+
+function readText(file: string): string {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if ((error as { code?: string })?.code === "ENOENT") return "";
+    throw error;
+  }
+}
+
+function validateEvent(input: unknown): SolverShadowEvent {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("event must be an object");
+  const value = input as Record<string, unknown>;
+  const fields = new Set(["schemaVersion", "recordedAt", "sessionHash", "featureHash", "features", "decision"]);
+  const unknown = Object.keys(value).filter((field) => !fields.has(field));
+  if (unknown.length > 0 || [...fields].some((field) => !(field in value))) throw new Error("event fields are invalid");
+  if (value.schemaVersion !== 1) throw new Error("event schemaVersion must be 1");
+  if (typeof value.recordedAt !== "string" || !Number.isFinite(Date.parse(value.recordedAt))) throw new Error("recordedAt is invalid");
+  if (typeof value.sessionHash !== "string" || !HASH.test(value.sessionHash)) throw new Error("sessionHash is invalid");
+  if (typeof value.featureHash !== "string" || !HASH.test(value.featureHash)) throw new Error("featureHash is invalid");
+  const features = validateTaskFeatures(value.features, "persisted solver features");
+  const decision = validateSolverDecision(value.decision, "persisted solver decision");
+  if (features.featureHash !== value.featureHash || decision.featureHash !== value.featureHash) throw new Error("feature hash mismatch");
+  return value as SolverShadowEvent;
+}
+
+export function readSolverShadowEvents(cwd: string): SolverShadowTelemetryView {
+  try {
+    const target = solverShadowEventPath(cwd);
+    const current = resolveLocalStatePath(cwd, target, { label: "Solver shadow events" });
+    const rotated = resolveLocalStatePath(cwd, `${target}.1`, { label: "Rotated solver shadow events" });
+    const records: SolverShadowEvent[] = [];
+    const corruptions: string[] = [];
+    const lines = [readText(rotated), readText(current)].join("").split(/\r?\n/).filter(Boolean);
+    for (const [index, line] of lines.entries()) {
+      try {
+        records.push(validateEvent(JSON.parse(line)));
+      } catch (error) {
+        corruptions.push(`line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    return { records, latest: records.at(-1), corruptions, routingSafe: corruptions.length === 0 };
+  } catch {
+    return { records: [], corruptions: ["solver shadow event path is unsafe"], routingSafe: false };
+  }
+}
+
+export function recordSolverShadowEvent(
+  cwd: string,
+  sessionId: string,
+  featuresInput: TaskFeatures,
+  decisionInput: SolverDecision,
+  options: { recordedAt?: string } = {}
+): { written: boolean; warnings: string[] } {
+  const features = validateTaskFeatures(structuredClone(featuresInput));
+  const decision = validateSolverDecision(structuredClone(decisionInput));
+  if (features.featureHash !== decision.featureHash) throw new Error("solver feature/decision hash mismatch");
+  const sessionHash = crypto.createHash("sha256").update(String(sessionId || "unknown-session")).digest("hex");
+  const existing = readSolverShadowEvents(cwd);
+  if (!existing.routingSafe) return { written: false, warnings: existing.corruptions };
+  if (existing.latest?.sessionHash === sessionHash && existing.latest.featureHash === features.featureHash
+    && JSON.stringify(existing.latest.decision) === JSON.stringify(decision)) return { written: false, warnings: [] };
+  appendJsonlBounded(solverShadowEventPath(cwd), {
+    schemaVersion: SOLVER_SHADOW_EVENT_SCHEMA_VERSION,
+    recordedAt: options.recordedAt ?? new Date().toISOString(),
+    sessionHash,
+    featureHash: features.featureHash,
+    features,
+    decision
+  } satisfies SolverShadowEvent, { maxBytes: MAX_EVENT_BYTES, mode: 0o600, projectRoot: cwd });
+  return { written: true, warnings: [] };
+}
+
+export class SolverShadowRuntime {
+  readonly #mode: SolverMode;
+  readonly #extract: typeof extractTaskFeatures;
+  readonly #solve: typeof solveTaskFeatures;
+  readonly #persist: typeof recordSolverShadowEvent;
+  readonly #now: () => number;
+  readonly #cache = new Map<string, { features: TaskFeatures; decision: SolverDecision }>();
+
+  constructor(mode: SolverMode, dependencies: SolverShadowDependencies = {}) {
+    this.#mode = mode;
+    this.#extract = dependencies.extract ?? extractTaskFeatures;
+    this.#solve = dependencies.solve ?? solveTaskFeatures;
+    this.#persist = dependencies.persist ?? recordSolverShadowEvent;
+    this.#now = dependencies.now ?? (() => performance.now());
+  }
+
+  evaluate(cwd: string, sessionId: string, input: TaskFeatureInput): SolverShadowEvaluation {
+    if (this.#mode === "off") return { status: "off", durationMs: 0 };
+    const started = this.#now();
+    try {
+      const features = this.#extract(input);
+      const cacheKey = `${cwd}\u0000${sessionId}`;
+      const cached = this.#cache.get(cacheKey);
+      if (cached?.features.featureHash === features.featureHash) {
+        return { status: "ok", durationMs: Math.max(0, this.#now() - started), reused: true, persisted: false, warnings: [], ...cached };
+      }
+      const decision = this.#solve(features, this.#mode);
+      const persisted = this.#persist(cwd, sessionId, features, decision);
+      this.#cache.set(cacheKey, { features, decision });
+      while (this.#cache.size > 100) this.#cache.delete(this.#cache.keys().next().value as string);
+      return {
+        status: "ok",
+        durationMs: Math.max(0, this.#now() - started),
+        reused: false,
+        persisted: persisted.written,
+        warnings: persisted.warnings,
+        features,
+        decision
+      };
+    } catch (error) {
+      return {
+        status: "error",
+        durationMs: Math.max(0, this.#now() - started),
+        warnings: [error instanceof Error ? error.message : String(error)].slice(0, 4)
+      };
+    }
+  }
+
+  observeRoute(cwd: string, sessionId: string, actualRoute: SolverRoute, recordedAt = new Date().toISOString()): SolverOverrideCapture {
+    const cached = this.#cache.get(`${cwd}\u0000${sessionId}`);
+    if (!cached) return { status: "no-decision" };
+    if (cached.decision.route === actualRoute) return { status: "same-route" };
+    try {
+      const decision = validateSolverDecision({
+        ...structuredClone(cached.decision),
+        override: { observed: true, route: actualRoute, recordedAt }
+      });
+      const persisted = this.#persist(cwd, sessionId, cached.features, decision);
+      this.#cache.set(`${cwd}\u0000${sessionId}`, { features: cached.features, decision });
+      return { status: "recorded", decision, persisted: persisted.written, warnings: persisted.warnings };
+    } catch (error) {
+      return { status: "error", warnings: [error instanceof Error ? error.message : String(error)] };
+    }
+  }
+}

package/packages/piagent-core/runtime/solver/solver-types.ts

@@ -0,0 +1,141 @@
+export const TASK_FEATURES_SCHEMA_VERSION = 1 as const;
+export const SOLVER_DECISION_SCHEMA_VERSION = 1 as const;
+export const SOLVER_POLICY_VERSION = "solver-v1" as const;
+
+export const SOLVER_ROUTES = Object.freeze(["direct", "scout-first", "plan-first", "review-only", "blocked-preflight"] as const);
+export type SolverRoute = typeof SOLVER_ROUTES[number];
+export type SolverMode = "off" | "shadow" | "recommend";
+export type WorkflowIntent = "implement" | "review" | "plan" | "diagnose" | "scout" | "unknown";
+export type ChangeMode = "source-change" | "read-only" | "plan-only" | "unknown";
+export type RiskLane = "tiny" | "normal" | "high-risk" | "unknown";
+
+export type TaskFeatures = {
+  schemaVersion: typeof TASK_FEATURES_SCHEMA_VERSION;
+  featureHash: string;
+  workflowIntent: WorkflowIntent;
+  changeMode: ChangeMode;
+  riskLane: RiskLane;
+  riskSignals: string[];
+  ambiguity: "low" | "medium" | "high" | "unknown";
+  explicitPathCount: number;
+  scopeEstimate: "tiny" | "bounded" | "broad" | "unknown";
+  profileMode: string | null;
+  projectShape: string[];
+  gitReady: boolean | null;
+  dirtyTree: boolean | null;
+  verifierReady: boolean | null;
+  contextPressure: number | null;
+  activeTaskState: "none" | "pending" | "terminal" | "unknown";
+  runtimeSnapshotDigest: string | null;
+  runtimeCapabilitiesKnown: boolean;
+  userPinnedProvider: string | null;
+  userPinnedModel: string | null;
+  userPinnedEffort: string | null;
+  protectedTarget: boolean;
+  externalAction: boolean;
+  destructiveAction: boolean;
+  permissionExpansion: boolean;
+};
+
+export type SolverDecision = {
+  schemaVersion: typeof SOLVER_DECISION_SCHEMA_VERSION;
+  policyVersion: typeof SOLVER_POLICY_VERSION;
+  featureHash: string;
+  route: SolverRoute;
+  plannedPhases: Array<"intake" | "context" | "plan" | "implement" | "verify" | "review" | "handoff">;
+  context: { recommendation: "none" | "targeted" | "bounded"; budgetBand: "none" | "small" | "medium" | "large" };
+  toolGroups: string[];
+  helper: { needed: boolean; role: "scout" | "planner" | "reviewer" | null; enforced: false };
+  parentModel: { provider: string | null; modelId: string | null; effort: string | null; enforced: false };
+  reasonCodes: string[];
+  confidence: "low" | "medium" | "high";
+  mode: SolverMode;
+  override: { observed: boolean; route: SolverRoute | null; recordedAt: string | null };
+};
+
+const FEATURE_FIELDS = new Set(["schemaVersion", "featureHash", "workflowIntent", "changeMode", "riskLane", "riskSignals", "ambiguity", "explicitPathCount", "scopeEstimate", "profileMode", "projectShape", "gitReady", "dirtyTree", "verifierReady", "contextPressure", "activeTaskState", "runtimeSnapshotDigest", "runtimeCapabilitiesKnown", "userPinnedProvider", "userPinnedModel", "userPinnedEffort", "protectedTarget", "externalAction", "destructiveAction", "permissionExpansion"]);
+const DECISION_FIELDS = new Set(["schemaVersion", "policyVersion", "featureHash", "route", "plannedPhases", "context", "toolGroups", "helper", "parentModel", "reasonCodes", "confidence", "mode", "override"]);
+const SOLVER_PHASES = new Set(["intake", "context", "plan", "implement", "verify", "review", "handoff"]);
+const HASH = /^[a-f0-9]{64}$/;
+const NAME = /^[a-z0-9][a-z0-9._:/-]{0,127}$/i;
+
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function exact(value: Record<string, unknown>, fields: Set<string>, label: string): string[] {
+  return [
+    ...Object.keys(value).filter((field) => !fields.has(field)).map((field) => `${label} has unknown field: ${field}`),
+    ...[...fields].filter((field) => !(field in value)).map((field) => `${label} missing field: ${field}`)
+  ];
+}
+
+function nullableBoolean(value: unknown): boolean {
+  return value === null || typeof value === "boolean";
+}
+
+function nullableName(value: unknown): boolean {
+  return value === null || (typeof value === "string" && NAME.test(value));
+}
+
+function names(value: unknown, max: number, allowEmpty = true): boolean {
+  return Array.isArray(value) && value.length <= max && (allowEmpty || value.length > 0)
+    && value.every((item) => typeof item === "string" && NAME.test(item))
+    && new Set(value).size === value.length;
+}
+
+export function taskFeaturesValidationErrors(input: unknown): string[] {
+  const value = object(input);
+  if (!value) return ["task features must be an object"];
+  const errors = exact(value, FEATURE_FIELDS, "task features");
+  if (value.schemaVersion !== 1) errors.push("schemaVersion must be 1");
+  if (typeof value.featureHash !== "string" || !HASH.test(value.featureHash)) errors.push("featureHash must be sha256 hex");
+  if (!["implement", "review", "plan", "diagnose", "scout", "unknown"].includes(String(value.workflowIntent))) errors.push("workflowIntent is invalid");
+  if (!["source-change", "read-only", "plan-only", "unknown"].includes(String(value.changeMode))) errors.push("changeMode is invalid");
+  if (!["tiny", "normal", "high-risk", "unknown"].includes(String(value.riskLane))) errors.push("riskLane is invalid");
+  if (!names(value.riskSignals, 16)) errors.push("riskSignals are invalid");
+  if (!["low", "medium", "high", "unknown"].includes(String(value.ambiguity))) errors.push("ambiguity is invalid");
+  if (!Number.isInteger(value.explicitPathCount) || Number(value.explicitPathCount) < 0 || Number(value.explicitPathCount) > 1000) errors.push("explicitPathCount is invalid");
+  if (!["tiny", "bounded", "broad", "unknown"].includes(String(value.scopeEstimate))) errors.push("scopeEstimate is invalid");
+  if (!nullableName(value.profileMode) || !names(value.projectShape, 16)) errors.push("profile/project shape is invalid");
+  for (const field of ["gitReady", "dirtyTree", "verifierReady"] as const) if (!nullableBoolean(value[field])) errors.push(`${field} must be boolean or null`);
+  if (value.contextPressure !== null && (typeof value.contextPressure !== "number" || value.contextPressure < 0 || value.contextPressure > 1)) errors.push("contextPressure is invalid");
+  if (!["none", "pending", "terminal", "unknown"].includes(String(value.activeTaskState))) errors.push("activeTaskState is invalid");
+  if (value.runtimeSnapshotDigest !== null && (typeof value.runtimeSnapshotDigest !== "string" || !HASH.test(value.runtimeSnapshotDigest))) errors.push("runtimeSnapshotDigest is invalid");
+  if (typeof value.runtimeCapabilitiesKnown !== "boolean") errors.push("runtimeCapabilitiesKnown must be boolean");
+  for (const field of ["userPinnedProvider", "userPinnedModel", "userPinnedEffort"] as const) if (!nullableName(value[field])) errors.push(`${field} is invalid`);
+  for (const field of ["protectedTarget", "externalAction", "destructiveAction", "permissionExpansion"] as const) if (typeof value[field] !== "boolean") errors.push(`${field} must be boolean`);
+  return errors;
+}
+
+export function validateTaskFeatures(input: unknown, source = "task features"): TaskFeatures {
+  const errors = taskFeaturesValidationErrors(input);
+  if (errors.length) throw new Error(`${source}: ${errors.join("; ")}`);
+  return input as TaskFeatures;
+}
+
+export function solverDecisionValidationErrors(input: unknown): string[] {
+  const value = object(input);
+  if (!value) return ["solver decision must be an object"];
+  const errors = exact(value, DECISION_FIELDS, "solver decision");
+  if (value.schemaVersion !== 1 || value.policyVersion !== SOLVER_POLICY_VERSION) errors.push("solver schema/policy version is invalid");
+  if (typeof value.featureHash !== "string" || !HASH.test(value.featureHash)) errors.push("featureHash must be sha256 hex");
+  if (!SOLVER_ROUTES.includes(value.route as SolverRoute)) errors.push("route is invalid");
+  if (!names(value.plannedPhases, 7, false) || !(value.plannedPhases as unknown[]).every((phase) => SOLVER_PHASES.has(String(phase)))) errors.push("plannedPhases are invalid");
+  const context = object(value.context), helper = object(value.helper), parent = object(value.parentModel), override = object(value.override);
+  if (!context || exact(context, new Set(["recommendation", "budgetBand"]), "context").length || !["none", "targeted", "bounded"].includes(String(context.recommendation)) || !["none", "small", "medium", "large"].includes(String(context.budgetBand))) errors.push("context recommendation is invalid");
+  if (!names(value.toolGroups, 10)) errors.push("toolGroups are invalid");
+  if (!helper || exact(helper, new Set(["needed", "role", "enforced"]), "helper").length || typeof helper.needed !== "boolean" || !["scout", "planner", "reviewer", null].includes(helper.role as never) || helper.enforced !== false) errors.push("helper recommendation is invalid");
+  if (!parent || exact(parent, new Set(["provider", "modelId", "effort", "enforced"]), "parentModel").length || !nullableName(parent.provider) || !nullableName(parent.modelId) || !nullableName(parent.effort) || parent.enforced !== false) errors.push("parent model recommendation is invalid");
+  if (!names(value.reasonCodes, 24, false)) errors.push("reasonCodes are invalid");
+  if (!["low", "medium", "high"].includes(String(value.confidence)) || !["off", "shadow", "recommend"].includes(String(value.mode))) errors.push("confidence/mode is invalid");
+  if (!override || exact(override, new Set(["observed", "route", "recordedAt"]), "override").length || typeof override.observed !== "boolean" || (override.route !== null && !SOLVER_ROUTES.includes(override.route as SolverRoute)) || (override.recordedAt !== null && (typeof override.recordedAt !== "string" || !Number.isFinite(Date.parse(override.recordedAt))))) errors.push("override is invalid");
+  if (value.mode === "shadow" && parent?.enforced !== false) errors.push("shadow parent recommendation cannot be enforced");
+  return errors;
+}
+
+export function validateSolverDecision(input: unknown, source = "solver decision"): SolverDecision {
+  const errors = solverDecisionValidationErrors(input);
+  if (errors.length) throw new Error(`${source}: ${errors.join("; ")}`);
+  return input as SolverDecision;
+}