@piagent/platform 1.2.16 → 1.3.0-ie.8

package/packages/piagent-core/runtime/model/model-selection-provenance.ts

@@ -0,0 +1,51 @@
+import type { ModelSelectionSource } from "./model-route-types.ts";
+import { MODEL_SELECTION_SOURCES } from "./model-route-types.ts";
+
+function truthy(value: unknown): boolean {
+  return ["1", "true", "yes", "on", "pinned"].includes(String(value ?? "").trim().toLowerCase());
+}
+
+function hasModelArgument(argv: readonly string[]): boolean {
+  return argv.some((arg, index) => arg === "--model" || arg === "-m" || arg.startsWith("--model=")
+    || ((arg === "--provider" || arg === "--thinking") && Boolean(argv[index + 1])));
+}
+
+export function modelSelectionSourceFromInvocation(
+  argv: readonly string[] = process.argv,
+  env: NodeJS.ProcessEnv = process.env
+): ModelSelectionSource {
+  const declared = String(env.PIAGENT_MODEL_SELECTION_SOURCE ?? "").trim().toLowerCase();
+  if (MODEL_SELECTION_SOURCES.includes(declared as ModelSelectionSource)) return declared as ModelSelectionSource;
+  if (truthy(env.PIAGENT_MODEL_PINNED) || hasModelArgument(argv) || Boolean(env.PI_MODEL?.trim())) return "explicit-user-pin";
+  return "unknown";
+}
+
+export class ModelSelectionProvenanceTracker {
+  readonly #initial: ModelSelectionSource;
+  readonly #bySession = new Map<string, ModelSelectionSource>();
+
+  constructor(initial = modelSelectionSourceFromInvocation()) {
+    this.#initial = initial;
+  }
+
+  source(sessionId: string): ModelSelectionSource {
+    return this.#bySession.get(sessionId) ?? this.#initial;
+  }
+
+  observeModelSelection(sessionId: string, source: "set" | "cycle" | "restore" | string): void {
+    this.#bySession.set(sessionId, source === "set" || source === "cycle" || source === "restore" ? "explicit-user-pin" : "unknown");
+  }
+
+  observeThinkingSelection(sessionId: string): void {
+    this.#bySession.set(sessionId, "explicit-user-pin");
+  }
+
+  markRouterSelected(sessionId: string): void {
+    this.#bySession.set(sessionId, "router-selected");
+  }
+
+  clear(sessionId?: string): void {
+    if (sessionId) this.#bySession.delete(sessionId);
+    else this.#bySession.clear();
+  }
+}

package/packages/piagent-core/runtime/model/runtime-snapshot.ts

@@ -0,0 +1,346 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { redactSensitiveText } from "../../security/sensitive-data.js";
+
+export const RUNTIME_MODEL_SNAPSHOT_SCHEMA_VERSION = 1 as const;
+
+export const RUNTIME_FACT_SOURCES = Object.freeze([
+  "pi-runtime",
+  "authenticated-catalog",
+  "provider-profile",
+  "api-doc-hint"
+] as const);
+
+export type RuntimeFactSource = typeof RUNTIME_FACT_SOURCES[number];
+export type RuntimeAvailability = "authenticated" | "unavailable" | "offline" | "logged-out" | "unknown";
+export type RuntimeCapabilityValue = boolean | null;
+
+export type RuntimeCapabilityFact = {
+  name: string;
+  value: RuntimeCapabilityValue;
+  source: RuntimeFactSource;
+};
+
+export type RuntimeFactProvenance = {
+  field: string;
+  source: RuntimeFactSource;
+  capturedAt: string;
+  detail?: string;
+};
+
+export type RuntimeModelSnapshot = {
+  schemaVersion: typeof RUNTIME_MODEL_SNAPSHOT_SCHEMA_VERSION;
+  capturedAt: string;
+  source: RuntimeFactSource;
+  piHostVersion: string | null;
+  piagentVersion: string | null;
+  provider: string | null;
+  modelId: string | null;
+  availability: RuntimeAvailability;
+  contextWindow: number | null;
+  requestedThinkingLevel: string | null;
+  effectiveThinkingLevel: string | null;
+  supportedThinkingLevels: string[] | null;
+  capabilities: RuntimeCapabilityFact[];
+  provenance: RuntimeFactProvenance[];
+  warnings: string[];
+};
+
+export type RuntimeVersionMetadata = {
+  piHostVersion: string | null;
+  piagentVersion: string | null;
+  piHostSource: RuntimeFactSource;
+  piagentSource: RuntimeFactSource;
+};
+
+export type RuntimeSnapshotCaptureOptions = {
+  capturedAt?: string;
+  requestedThinkingLevel?: string | null;
+  effectiveThinkingLevel?: string | null;
+  versions?: RuntimeVersionMetadata;
+};
+
+const SNAPSHOT_FIELDS = new Set([
+  "schemaVersion", "capturedAt", "source", "piHostVersion", "piagentVersion",
+  "provider", "modelId", "availability", "contextWindow", "requestedThinkingLevel",
+  "effectiveThinkingLevel", "supportedThinkingLevels", "capabilities", "provenance", "warnings"
+]);
+const CAPABILITY_FIELDS = new Set(["name", "value", "source"]);
+const PROVENANCE_FIELDS = new Set(["field", "source", "capturedAt", "detail"]);
+const AVAILABILITY = new Set<RuntimeAvailability>(["authenticated", "unavailable", "offline", "logged-out", "unknown"]);
+const SOURCE_TRUST: Record<RuntimeFactSource, number> = {
+  "pi-runtime": 4,
+  "authenticated-catalog": 3,
+  "provider-profile": 2,
+  "api-doc-hint": 1
+};
+const ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const NAME = /^[a-z0-9][a-z0-9._:/-]{0,127}$/i;
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function unknownFields(value: Record<string, unknown>, allowed: Set<string>): string[] {
+  return Object.keys(value).filter((field) => !allowed.has(field));
+}
+
+function validTimestamp(value: unknown): boolean {
+  return typeof value === "string" && ISO_TIMESTAMP.test(value) && !Number.isNaN(Date.parse(value));
+}
+
+function validNullableText(value: unknown, max = 160): boolean {
+  return value === null || (typeof value === "string" && value.length > 0 && value.length <= max);
+}
+
+function source(value: unknown): value is RuntimeFactSource {
+  return RUNTIME_FACT_SOURCES.includes(value as RuntimeFactSource);
+}
+
+export function runtimeModelSnapshotValidationErrors(input: unknown): string[] {
+  const value = record(input);
+  if (!value) return ["snapshot must be an object"];
+  const errors = unknownFields(value, SNAPSHOT_FIELDS).map((field) => `unknown snapshot field: ${field}`);
+  for (const field of SNAPSHOT_FIELDS) {
+    if (!(field in value)) errors.push(`missing snapshot field: ${field}`);
+  }
+  if (value.schemaVersion !== RUNTIME_MODEL_SNAPSHOT_SCHEMA_VERSION) errors.push("schemaVersion must be 1");
+  if (!validTimestamp(value.capturedAt)) errors.push("capturedAt must be a UTC ISO timestamp with milliseconds");
+  if (!source(value.source)) errors.push("source is invalid");
+  for (const field of ["piHostVersion", "piagentVersion", "provider", "modelId", "requestedThinkingLevel", "effectiveThinkingLevel"] as const) {
+    if (!validNullableText(value[field])) errors.push(`${field} must be null or bounded non-empty text`);
+  }
+  if (!AVAILABILITY.has(value.availability as RuntimeAvailability)) errors.push("availability is invalid");
+  if (value.contextWindow !== null && (!Number.isInteger(value.contextWindow) || Number(value.contextWindow) < 1 || Number(value.contextWindow) > 10_000_000)) {
+    errors.push("contextWindow must be null or an integer between 1 and 10000000");
+  }
+  if (value.supportedThinkingLevels !== null) {
+    if (!Array.isArray(value.supportedThinkingLevels) || value.supportedThinkingLevels.length > 16
+      || value.supportedThinkingLevels.some((entry) => typeof entry !== "string" || !NAME.test(entry))) {
+      errors.push("supportedThinkingLevels must be null or at most 16 bounded names");
+    } else if (new Set(value.supportedThinkingLevels).size !== value.supportedThinkingLevels.length) {
+      errors.push("supportedThinkingLevels must be unique");
+    }
+  }
+  if (!Array.isArray(value.capabilities) || value.capabilities.length > 64) {
+    errors.push("capabilities must be an array with at most 64 entries");
+  } else {
+    const names = new Set<string>();
+    for (const [index, raw] of value.capabilities.entries()) {
+      const capability = record(raw);
+      if (!capability) {
+        errors.push(`capabilities[${index}] must be an object`);
+        continue;
+      }
+      for (const field of unknownFields(capability, CAPABILITY_FIELDS)) errors.push(`capabilities[${index}] has unknown field: ${field}`);
+      if (typeof capability.name !== "string" || !NAME.test(capability.name)) errors.push(`capabilities[${index}].name is invalid`);
+      else if (names.has(capability.name)) errors.push(`duplicate capability: ${capability.name}`);
+      else names.add(capability.name);
+      if (capability.value !== null && typeof capability.value !== "boolean") errors.push(`capabilities[${index}].value must be boolean or null`);
+      if (!source(capability.source)) errors.push(`capabilities[${index}].source is invalid`);
+    }
+  }
+  if (!Array.isArray(value.provenance) || value.provenance.length > 128) {
+    errors.push("provenance must be an array with at most 128 entries");
+  } else {
+    for (const [index, raw] of value.provenance.entries()) {
+      const item = record(raw);
+      if (!item) {
+        errors.push(`provenance[${index}] must be an object`);
+        continue;
+      }
+      for (const field of unknownFields(item, PROVENANCE_FIELDS)) errors.push(`provenance[${index}] has unknown field: ${field}`);
+      if (typeof item.field !== "string" || !NAME.test(item.field)) errors.push(`provenance[${index}].field is invalid`);
+      if (!source(item.source)) errors.push(`provenance[${index}].source is invalid`);
+      if (!validTimestamp(item.capturedAt)) errors.push(`provenance[${index}].capturedAt is invalid`);
+      if (item.detail !== undefined && (typeof item.detail !== "string" || item.detail.length > 240)) errors.push(`provenance[${index}].detail is invalid`);
+    }
+  }
+  if (!Array.isArray(value.warnings) || value.warnings.length > 32
+    || value.warnings.some((warning) => typeof warning !== "string" || warning.length < 1 || warning.length > 240)) {
+    errors.push("warnings must contain at most 32 bounded strings");
+  }
+  return errors;
+}
+
+export function validateRuntimeModelSnapshot(input: unknown, sourceName = "runtime snapshot"): RuntimeModelSnapshot {
+  const errors = runtimeModelSnapshotValidationErrors(input);
+  if (errors.length > 0) throw new Error(`${sourceName}: ${errors.join("; ")}`);
+  return input as RuntimeModelSnapshot;
+}
+
+function redactedText(value: string, max: number): string {
+  return redactSensitiveText(value).text.trim().slice(0, max);
+}
+
+export function redactRuntimeModelSnapshot(input: RuntimeModelSnapshot): RuntimeModelSnapshot {
+  const snapshot = structuredClone(input);
+  snapshot.warnings = snapshot.warnings.map((value) => redactedText(value, 240)).filter(Boolean).slice(0, 32);
+  snapshot.provenance = snapshot.provenance.map((item) => ({
+    ...item,
+    detail: item.detail === undefined ? undefined : redactedText(item.detail, 240)
+  }));
+  return validateRuntimeModelSnapshot(snapshot);
+}
+
+export function serializeRuntimeModelSnapshot(input: RuntimeModelSnapshot): string {
+  const snapshot = redactRuntimeModelSnapshot(input);
+  snapshot.capabilities.sort((left, right) => left.name.localeCompare(right.name));
+  snapshot.provenance.sort((left, right) => `${left.field}:${left.source}`.localeCompare(`${right.field}:${right.source}`));
+  snapshot.supportedThinkingLevels?.sort();
+  snapshot.warnings.sort();
+  return `${JSON.stringify(snapshot)}\n`;
+}
+
+export function runtimeModelSnapshotDigest(input: RuntimeModelSnapshot): string {
+  const stable = JSON.parse(serializeRuntimeModelSnapshot(input)) as RuntimeModelSnapshot;
+  stable.capturedAt = "1970-01-01T00:00:00.000Z";
+  for (const item of stable.provenance) item.capturedAt = "1970-01-01T00:00:00.000Z";
+  return crypto.createHash("sha256").update(JSON.stringify(stable)).digest("hex");
+}
+
+function trust(value: RuntimeFactSource): number {
+  return SOURCE_TRUST[value];
+}
+
+export function mergeRuntimeModelSnapshots(inputs: readonly RuntimeModelSnapshot[]): RuntimeModelSnapshot {
+  if (inputs.length === 0) throw new Error("at least one runtime snapshot is required");
+  const snapshots = inputs.map((item) => validateRuntimeModelSnapshot(structuredClone(item)));
+  const ranked = [...snapshots].sort((left, right) => trust(right.source) - trust(left.source));
+  const result = structuredClone(ranked[0]);
+  const nullable = ["piHostVersion", "piagentVersion", "provider", "modelId", "contextWindow", "requestedThinkingLevel", "effectiveThinkingLevel", "supportedThinkingLevels"] as const;
+  for (const candidate of ranked.slice(1)) {
+    for (const field of nullable) {
+      if (result[field] === null && candidate[field] !== null) (result as Record<string, unknown>)[field] = candidate[field];
+    }
+    if (result.availability === "unknown" && candidate.availability !== "unknown") result.availability = candidate.availability;
+  }
+  const capabilities = new Map<string, RuntimeCapabilityFact>();
+  for (const candidate of ranked) {
+    for (const capability of candidate.capabilities) if (!capabilities.has(capability.name)) capabilities.set(capability.name, capability);
+  }
+  result.capabilities = [...capabilities.values()].sort((left, right) => left.name.localeCompare(right.name));
+  result.provenance = snapshots.flatMap((item) => item.provenance)
+    .filter((item, index, all) => all.findIndex((other) => `${other.field}:${other.source}:${other.capturedAt}` === `${item.field}:${item.source}:${item.capturedAt}`) === index)
+    .slice(0, 128);
+  result.warnings = [...new Set(snapshots.flatMap((item) => item.warnings))].slice(0, 32);
+  result.capturedAt = snapshots.map((item) => item.capturedAt).sort().at(-1) as string;
+  return validateRuntimeModelSnapshot(result);
+}
+
+function boundedNullable(value: unknown): string | null {
+  const normalized = String(value ?? "").trim();
+  return normalized ? normalized.slice(0, 160) : null;
+}
+
+export function readRuntimeVersionMetadata(platformRoot: string): RuntimeVersionMetadata {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(platformRoot, "package.json"), "utf8")) as {
+      version?: unknown;
+      peerDependencies?: Record<string, unknown>;
+    };
+    return {
+      piHostVersion: boundedNullable(manifest.peerDependencies?.["@earendil-works/pi-coding-agent"]),
+      piagentVersion: boundedNullable(manifest.version),
+      piHostSource: "provider-profile",
+      piagentSource: "provider-profile"
+    };
+  } catch {
+    return {
+      piHostVersion: null,
+      piagentVersion: null,
+      piHostSource: "provider-profile",
+      piagentSource: "provider-profile"
+    };
+  }
+}
+
+function activeModel(ctx: ExtensionContext): { provider: string | null; modelId: string | null } {
+  const model = (ctx as unknown as { model?: { provider?: unknown; id?: unknown; name?: unknown } }).model;
+  return {
+    provider: boundedNullable(model?.provider),
+    modelId: boundedNullable(model?.id ?? model?.name)
+  };
+}
+
+function provenance(field: string, source: RuntimeFactSource, capturedAt: string, detail?: string): RuntimeFactProvenance {
+  return { field, source, capturedAt, ...(detail ? { detail } : {}) };
+}
+
+export function captureActiveRuntimeSnapshot(
+  ctx: ExtensionContext,
+  options: RuntimeSnapshotCaptureOptions = {}
+): RuntimeModelSnapshot {
+  const capturedAt = options.capturedAt ?? new Date().toISOString();
+  const versions = options.versions ?? {
+    piHostVersion: null,
+    piagentVersion: null,
+    piHostSource: "provider-profile" as const,
+    piagentSource: "provider-profile" as const
+  };
+  const model = activeModel(ctx);
+  const warnings: string[] = [];
+  let contextWindow: number | null = null;
+  try {
+    const usage = typeof ctx.getContextUsage === "function" ? ctx.getContextUsage() : undefined;
+    if (Number.isInteger(usage?.contextWindow) && Number(usage?.contextWindow) > 0) contextWindow = Number(usage?.contextWindow);
+    else warnings.push("Live context window is unavailable.");
+  } catch {
+    warnings.push("Live context usage capture failed; runtime behavior is unchanged.");
+  }
+  if (!model.provider) warnings.push("Active provider is unavailable.");
+  if (!model.modelId) warnings.push("Active model is unavailable.");
+  const requestedThinkingLevel = boundedNullable(options.requestedThinkingLevel);
+  const effectiveThinkingLevel = boundedNullable(options.effectiveThinkingLevel);
+  if (!effectiveThinkingLevel) warnings.push("Effective thinking level is unavailable.");
+  const facts: RuntimeFactProvenance[] = [
+    provenance("provider", "pi-runtime", capturedAt),
+    provenance("modelId", "pi-runtime", capturedAt),
+    provenance("contextWindow", "pi-runtime", capturedAt),
+    provenance("requestedThinkingLevel", "pi-runtime", capturedAt),
+    provenance("effectiveThinkingLevel", "pi-runtime", capturedAt)
+  ];
+  if (versions.piHostVersion) facts.push(provenance("piHostVersion", versions.piHostSource, capturedAt, "reviewed package metadata"));
+  if (versions.piagentVersion) facts.push(provenance("piagentVersion", versions.piagentSource, capturedAt, "reviewed package metadata"));
+  return validateRuntimeModelSnapshot({
+    schemaVersion: RUNTIME_MODEL_SNAPSHOT_SCHEMA_VERSION,
+    capturedAt,
+    source: "pi-runtime",
+    piHostVersion: versions.piHostVersion,
+    piagentVersion: versions.piagentVersion,
+    provider: model.provider,
+    modelId: model.modelId,
+    availability: "unknown",
+    contextWindow,
+    requestedThinkingLevel,
+    effectiveThinkingLevel,
+    supportedThinkingLevels: null,
+    capabilities: [],
+    provenance: facts,
+    warnings
+  });
+}
+
+export class RuntimeSnapshotCapture {
+  readonly #bySession = new Map<string, { identity: string; snapshot: RuntimeModelSnapshot }>();
+
+  capture(ctx: ExtensionContext, options: RuntimeSnapshotCaptureOptions = {}): RuntimeModelSnapshot {
+    const candidate = captureActiveRuntimeSnapshot(ctx, options);
+    const sessionId = boundedNullable(ctx.sessionManager?.getSessionId?.()) ?? "unknown-session";
+    const identity = runtimeModelSnapshotDigest(candidate);
+    const existing = this.#bySession.get(sessionId);
+    if (existing?.identity === identity) return structuredClone(existing.snapshot);
+    this.#bySession.set(sessionId, { identity, snapshot: candidate });
+    return structuredClone(candidate);
+  }
+
+  clear(sessionId?: string): void {
+    if (sessionId) this.#bySession.delete(sessionId);
+    else this.#bySession.clear();
+  }
+}

package/packages/piagent-core/runtime/model/snapshot-telemetry.ts

@@ -0,0 +1,102 @@
+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 {
+  redactRuntimeModelSnapshot,
+  runtimeModelSnapshotDigest,
+  validateRuntimeModelSnapshot
+} from "./runtime-snapshot.ts";
+import type { RuntimeModelSnapshot } from "./runtime-snapshot.ts";
+
+export const RUNTIME_SNAPSHOT_TELEMETRY_SCHEMA_VERSION = 1 as const;
+const MAX_TELEMETRY_BYTES = 512 * 1024;
+
+type RuntimeSnapshotTelemetryRecord = {
+  schemaVersion: typeof RUNTIME_SNAPSHOT_TELEMETRY_SCHEMA_VERSION;
+  recordedAt: string;
+  snapshotDigest: string;
+  snapshot: RuntimeModelSnapshot;
+};
+
+export type RuntimeSnapshotTelemetryView = {
+  records: RuntimeSnapshotTelemetryRecord[];
+  latest?: RuntimeSnapshotTelemetryRecord;
+  corruptions: string[];
+  routingSafe: boolean;
+};
+
+export function runtimeSnapshotTelemetryPath(cwd: string): string {
+  return path.join(cwd, ".pi", "piagent-state", "runtime-model", "snapshots.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 validateRecord(value: unknown): RuntimeSnapshotTelemetryRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("record must be an object");
+  const record = value as Record<string, unknown>;
+  const allowed = new Set(["schemaVersion", "recordedAt", "snapshotDigest", "snapshot"]);
+  const unknown = Object.keys(record).filter((field) => !allowed.has(field));
+  if (unknown.length > 0) throw new Error(`unknown fields: ${unknown.join(", ")}`);
+  if (record.schemaVersion !== 1) throw new Error("schemaVersion must be 1");
+  if (typeof record.recordedAt !== "string" || !Number.isFinite(Date.parse(record.recordedAt))) throw new Error("recordedAt is invalid");
+  if (typeof record.snapshotDigest !== "string" || !/^[a-f0-9]{64}$/.test(record.snapshotDigest)) throw new Error("snapshotDigest is invalid");
+  const snapshot = validateRuntimeModelSnapshot(record.snapshot, "persisted runtime snapshot");
+  if (runtimeModelSnapshotDigest(snapshot) !== record.snapshotDigest) throw new Error("snapshot digest mismatch");
+  return record as RuntimeSnapshotTelemetryRecord;
+}
+
+export function readRuntimeSnapshotTelemetry(cwd: string): RuntimeSnapshotTelemetryView {
+  let current: string;
+  let rotated: string;
+  try {
+    const target = runtimeSnapshotTelemetryPath(cwd);
+    current = resolveLocalStatePath(cwd, target, { label: "Runtime snapshot telemetry" });
+    rotated = resolveLocalStatePath(cwd, `${target}.1`, { label: "Rotated runtime snapshot telemetry" });
+  } catch {
+    return { records: [], corruptions: ["runtime snapshot telemetry path is unsafe"], routingSafe: false };
+  }
+  const records: RuntimeSnapshotTelemetryRecord[] = [];
+  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(validateRecord(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 };
+}
+
+export function recordRuntimeSnapshotTelemetry(
+  cwd: string,
+  input: RuntimeModelSnapshot,
+  options: { recordedAt?: string } = {}
+): { written: boolean; snapshotDigest: string; corruptions: string[] } {
+  const snapshot = redactRuntimeModelSnapshot(input);
+  const snapshotDigest = runtimeModelSnapshotDigest(snapshot);
+  const existing = readRuntimeSnapshotTelemetry(cwd);
+  if (!existing.routingSafe) return { written: false, snapshotDigest, corruptions: existing.corruptions };
+  if (existing.latest?.snapshotDigest === snapshotDigest) return { written: false, snapshotDigest, corruptions: [] };
+  const record: RuntimeSnapshotTelemetryRecord = {
+    schemaVersion: RUNTIME_SNAPSHOT_TELEMETRY_SCHEMA_VERSION,
+    recordedAt: options.recordedAt ?? new Date().toISOString(),
+    snapshotDigest,
+    snapshot
+  };
+  appendJsonlBounded(runtimeSnapshotTelemetryPath(cwd), record, {
+    maxBytes: MAX_TELEMETRY_BYTES,
+    mode: 0o600,
+    projectRoot: cwd
+  });
+  return { written: true, snapshotDigest, corruptions: [] };
+}

package/packages/piagent-core/runtime/orchestration/helper-lifecycle.ts

@@ -0,0 +1,81 @@
+import crypto from "node:crypto";
+import { redactSensitiveText } from "../../extensions/redaction-core.js";
+import type { AuthenticatedModelCatalog } from "../model/authenticated-catalog.ts";
+import type { RuntimeModelSnapshot } from "../model/runtime-snapshot.ts";
+import type { SolverDecision, TaskFeatures } from "../solver/solver-types.ts";
+import { bindRole, type RoleBinding } from "./role-binder.ts";
+import { AUTOMATIC_OWNED_WORK_CEILINGS, OwnedWorkBudgetController } from "./owned-work-budget.ts";
+import { createHelperRequest, defaultRolePolicy, type HelperRequest, type HelperRole } from "./role-policy.ts";
+
+export const HELPERS_MODE_VALUES = Object.freeze(["off", "recommend", "on"] as const);
+export type HelpersMode = typeof HELPERS_MODE_VALUES[number];
+export type HelperDecision = { mode: HelpersMode; action: "solo" | "recommend" | "dispatch" | "unavailable" | "blocked"; role: HelperRole | null; reasonCodes: string[]; binding: RoleBinding | null; request: HelperRequest | null };
+export type HelperDispatchResult = { status: "succeeded" | "failed" | "timeout" | "cancelled"; calls: number; tokens: number; output: string; summary?: string };
+export type HelperUsageReceipt = { role: HelperRole; disposition: string; reasonCodes: string[]; requestRef: string; outputDigest: string | null; summary: string | null; mergeOwner: "parent" | null; calls: number; tokens: number; helperUsed: boolean };
+type DispatchAdapter = (request: HelperRequest, signal: AbortSignal) => Promise<HelperDispatchResult>;
+type DispatchOptions = { timeoutMs?: number };
+
+function digest(value: unknown): string { return crypto.createHash("sha256").update(String(value ?? "")).digest("hex"); }
+export function helpersMode(value = process.env.PIAGENT_HELPERS_MODE): HelpersMode { return HELPERS_MODE_VALUES.includes(value as HelpersMode) ? value as HelpersMode : "recommend"; }
+
+export function selectHelperRole(input: { features: TaskFeatures; solver: SolverDecision; confidence?: string; conflictingEvidence?: boolean; repeatedSourceFailure?: boolean; independentReviewUseful?: boolean }): { role: HelperRole | null; reasons: string[] } {
+  if (input.features.riskLane === "tiny") return { role: null, reasons: ["tiny-task-solo"] };
+  const oracleEligible = input.features.riskLane === "high-risk" && (input.confidence === "low" || input.conflictingEvidence || input.repeatedSourceFailure);
+  if (oracleEligible) return { role: "oracle", reasons: ["high-risk-second-opinion", input.conflictingEvidence ? "conflicting-evidence" : input.repeatedSourceFailure ? "repeated-source-failure" : "low-confidence"] };
+  if (input.solver.helper.needed && input.solver.helper.role) return { role: input.solver.helper.role as HelperRole, reasons: ["solver-independent-lane"] };
+  if (input.independentReviewUseful && input.features.changeMode === "source-change") return { role: "reviewer", reasons: ["independent-review-useful"] };
+  return { role: null, reasons: ["solo-sufficient"] };
+}
+
+export class HelperLifecycleRuntime {
+  readonly #budgets: OwnedWorkBudgetController;
+  readonly #active = new Map<string, Set<AbortController>>();
+  constructor(budgets = new OwnedWorkBudgetController()) { this.#budgets = budgets; }
+  decide(input: { mode: HelpersMode; objective: string; taskId: string; taskRunId: string; sessionId: string; taskScope: string[]; parentAllowedTools: string[]; features: TaskFeatures; solver: SolverDecision; runtime: RuntimeModelSnapshot; catalog: AuthenticatedModelCatalog; confidence?: string; conflictingEvidence?: boolean; repeatedSourceFailure?: boolean; independentReviewUseful?: boolean }): HelperDecision {
+    if (input.mode === "off") return { mode: input.mode, action: "solo", role: null, reasonCodes: ["helpers-off"], binding: null, request: null };
+    const selection = selectHelperRole(input); if (!selection.role) return { mode: input.mode, action: "solo", role: null, reasonCodes: selection.reasons, binding: null, request: null };
+    const policy = defaultRolePolicy(selection.role, input.taskScope);
+    const binding = bindRole({ policy, features: input.features, solver: input.solver, runtime: input.runtime, catalog: input.catalog, helperBudgetAvailable: true });
+    if (binding.disposition !== "recommended") return { mode: input.mode, action: "unavailable", role: selection.role, reasonCodes: [...selection.reasons, ...binding.reasonCodes], binding, request: null };
+    const request = createHelperRequest({ policy, objective: input.objective, taskId: input.taskId, taskRunId: input.taskRunId, sessionId: input.sessionId, parentReadScope: input.taskScope, parentWriteScope: input.taskScope, parentAllowedTools: input.parentAllowedTools, requestedReadScope: input.taskScope, requestedWriteScope: [], model: { provider: binding.provider as string, modelId: binding.modelId as string, effort: binding.effort as string, source: binding.mappingVersion }, singleWriterOwnership: null });
+    const action = input.mode === "recommend" ? "recommend" : policy.authority === "read-only" ? "dispatch" : "blocked";
+    return { mode: input.mode, action, role: selection.role, reasonCodes: action === "blocked" ? [...selection.reasons, "automatic-worker-disabled"] : selection.reasons, binding, request };
+  }
+  async dispatch(cwd: string, decision: HelperDecision, adapter: DispatchAdapter, options: DispatchOptions = {}): Promise<HelperUsageReceipt> {
+    if (decision.action !== "dispatch" || !decision.request || !decision.role) return { role: decision.role ?? "scout", disposition: decision.action, reasonCodes: decision.reasonCodes, requestRef: "none", outputDigest: null, summary: null, mergeOwner: null, calls: 0, tokens: 0, helperUsed: false };
+    const reservation = this.#budgets.reserve(cwd, decision.request, undefined, AUTOMATIC_OWNED_WORK_CEILINGS);
+    if (reservation.decision !== "reserved" || !reservation.reservationId) return { role: decision.role, disposition: reservation.reason, reasonCodes: [...decision.reasonCodes, reservation.reason], requestRef: decision.request.deduplicationKey, outputDigest: null, summary: null, mergeOwner: null, calls: 0, tokens: 0, helperUsed: false };
+    const controller = new AbortController(), active = this.#active.get(decision.request.taskRunId) ?? new Set<AbortController>();
+    active.add(controller); this.#active.set(decision.request.taskRunId, active);
+    const ceilingMs = decision.request.ceilings.timeSeconds * 1000;
+    const timeoutMs = Math.max(1, Math.min(ceilingMs, Number.isFinite(options.timeoutMs) ? Number(options.timeoutMs) : ceilingMs));
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<HelperDispatchResult>((resolve) => {
+      timer = setTimeout(() => { resolve({ status: "timeout", calls: 0, tokens: 0, output: "" }); controller.abort("helper-time-budget-exceeded"); }, timeoutMs);
+    });
+    let result: HelperDispatchResult;
+    try {
+      const operation = Promise.resolve(adapter(structuredClone(decision.request), controller.signal))
+        .catch(() => ({ status: controller.signal.aborted ? "cancelled" : "failed", calls: 0, tokens: 0, output: "" } as HelperDispatchResult));
+      result = await Promise.race([operation, timeout]);
+    } finally {
+      if (timer) clearTimeout(timer);
+      active.delete(controller); if (active.size === 0) this.#active.delete(decision.request.taskRunId);
+    }
+    const terminal = result.status === "succeeded" ? "succeeded" : result.status === "cancelled" ? "cancelled" : "failed";
+    const released = this.#budgets.release(cwd, decision.request, reservation.reservationId, terminal, { calls: result.calls, tokens: result.tokens, output: result.output });
+    const calls = Math.min(Math.max(0, Number(result.calls) || 0), decision.request.ceilings.calls + 1);
+    const tokens = Math.min(Math.max(0, Number(result.tokens) || 0), decision.request.contextBudget + 1);
+    if (!released.accepted) return { role: decision.role, disposition: released.status === "cancelled" ? "cancelled" : "stale-result", reasonCodes: [...decision.reasonCodes, released.reason], requestRef: decision.request.deduplicationKey, outputDigest: null, summary: null, mergeOwner: null, calls, tokens, helperUsed: true };
+    const withinBudget = released.reason === "released", succeeded = result.status === "succeeded" && withinBudget;
+    const summary = succeeded && typeof result.summary === "string" ? redactSensitiveText(result.summary).text.replace(/\s+/g, " ").trim().slice(0, 1000) || null : null;
+    return { role: decision.role, disposition: withinBudget ? result.status : "budget-exceeded", reasonCodes: withinBudget ? decision.reasonCodes : [...decision.reasonCodes, released.reason], requestRef: decision.request.deduplicationKey, outputDigest: succeeded && result.output ? digest(result.output) : null, summary, mergeOwner: summary ? "parent" : null, calls, tokens, helperUsed: true };
+  }
+  cancelTask(cwd: string, decision: HelperDecision, now = new Date().toISOString()): number {
+    if (!decision.request) return 0;
+    this.#budgets.markParentTerminal(cwd, decision.request, now);
+    const active = this.#active.get(decision.request.taskRunId); if (!active) return 0;
+    for (const controller of active) controller.abort("parent-task-terminal");
+    return active.size;
+  }
+}