@piagent/platform 1.6.0 → 1.7.1

package/packages/piagent-core/runtime/session/usage.ts

@@ -6,6 +6,7 @@ import {
   CONTEXT_WATCH_PERCENT,
   LONG_INPUT_CHARS
 } from "../runtime-limits.ts";
+import type { WorkflowId } from "../workflows/webui-workflow.ts";
 import { modelLabel } from "./message-signals.ts";
 
 export type UsageSnapshot = {
@@ -32,7 +33,7 @@ export type UsageSnapshot = {
 };
 
 export type ContextPreflight = {
-  workflow: string;
+  workflow: WorkflowId;
   inputChars: number;
   inputTokenEstimate: number;
   liveContext?: UsageSnapshot["contextUsage"];
@@ -107,7 +108,7 @@ function estimateTokensFromChars(chars: number): number {
   return Math.max(0, Math.ceil(chars / 4));
 }
 
-export function buildContextPreflight(snapshot: UsageSnapshot, workflow = "task", inputChars = 0): ContextPreflight {
+export function buildContextPreflight(snapshot: UsageSnapshot, workflow: WorkflowId = "task", inputChars = 0): ContextPreflight {
   const inputTokenEstimate = estimateTokensFromChars(inputChars);
   const live = snapshot.contextUsage;
   let projectedContext: ContextPreflight["projectedContext"];
@@ -151,7 +152,7 @@ export function buildContextPreflight(snapshot: UsageSnapshot, workflow = "task"
     commands: [
       "/task-preflight",
       "/task-preflight compact",
-      `/fresh ${workflow === "be-to-fe" ? "be-to-fe" : workflow === "scout" ? "scout" : "task"} <request>`,
+      `/fresh ${workflow} <request>`,
       "/usage",
       "/session"
     ]

package/packages/piagent-core/runtime/tools/apply-patch-tool.ts

@@ -162,9 +162,9 @@ function parseUpdateHunks(section: string[], repoPath: string): UpdateHunk[] {
       if (line[0] !== "-") newLines.push(line.slice(1));
       if (line[0] === "+" || line[0] === "-") changed = true;
     }
-    if (!bodyLines || !changed || oldLines.length === 0) {
-      fail("malformed-hunk", `Hunk must contain a change with stable old-side context: ${repoPath}`);
-    }
+    if (!bodyLines) fail("malformed-hunk", `Hunk body is empty: ${repoPath}. Put @@ on its own line, then add body lines prefixed by space, +, or -; no file was changed.`);
+    if (!changed) fail("malformed-hunk", `Hunk contains no change line: ${repoPath}. Include at least one + or - body line in addition to any exact unchanged context; no file was changed.`);
+    if (oldLines.length === 0) fail("malformed-hunk", `Hunk must contain a change and at least one exact old-side line: ${repoPath}. A plus-only Update File hunk is invalid; for an insertion or append, place an adjacent existing anchor line (prefixed by one space) before or after the new + lines according to the intended position. Keep @@ on its own line and put removed lines on separate - lines; no file was changed.`);
     hunks.push({ oldLines, newLines });
   }
   if (!hunkCount) fail("malformed-hunk", `Update contains no hunks: ${repoPath}`);
@@ -481,10 +481,10 @@ export function registerApplyPatchTool(
     name: "apply_patch",
     label: "Apply Patch",
     description: "Apply one validated OpenAI-style patch across multiple project files in a single guarded tool call.",
-    promptSnippet: "Use apply_patch for bounded multi-file Add File and Update File changes when exact old context is available.",
+    promptSnippet: "Prefer one coherent apply_patch call for a bounded source-and-test or other multi-file change only when exact old context for every target is available. Update hunks require an exact old-side anchor; plus-only insertions are invalid. Otherwise use one bounded writer per file.",
     promptGuidelines: [
-      "Wrap the patch in exact *** Begin Patch and *** End Patch delimiters.",
-      "Use each project-relative target once and include enough unchanged context for every update hunk to match exactly once."
+      "The patch value must contain only the raw patch: its first line is exactly *** Begin Patch, its last line is exactly *** End Patch, and no prose, JSON, code fence, or other content may appear before or after those delimiters. For each *** Update File hunk, put @@ on its own line. Put every old, new, or unchanged body line below it with a leading -, +, or space; never write @@ -old or @@ +new.",
+      "Use each project-relative target once. Every Update File hunk must include at least one exact old-side line prefixed by space or -; for append/insert, put an adjacent existing space-prefixed anchor before or after the + lines to preserve the intended position. Include enough context to match exactly once."
     ],
     parameters: Type.Object({ patch: Type.String({ minLength: 1, maxLength: MAX_PATCH_BYTES }) }, { additionalProperties: false }),
     executionMode: "sequential",

package/packages/piagent-core/runtime/tools/phase-tool-runtime.ts

@@ -12,7 +12,7 @@ export type PhaseMutationInput = {
   verificationCarrier?: boolean;
 };
 
-const MANAGED_HOST_TOOL_ORDER = Object.freeze(["read", "grep", "find", "ls", "edit", "write", "apply_patch", "bash", "shell", "exec"]);
+const MANAGED_HOST_TOOL_ORDER = Object.freeze(["read", "grep", "find", "ls", "apply_patch", "edit", "write", "bash", "shell", "exec"]);
 
 function phaseHostToolName(toolName: string): string {
   return toolName === "shell" || toolName === "exec" ? "bash" : toolName;

package/packages/piagent-core/runtime/tools/phase-tools.ts

@@ -10,6 +10,7 @@ export const PIAGENT_PRIMARY_TOOL_GROUP = Object.freeze({
   piagent_context: "intake",
   piagent_context_preflight: "intake",
   piagent_task_progress: "mutation",
+  piagent_wait: "retrieval",
   piagent_context_record: "recovery",
   piagent_verify_record: "verification",
   piagent_trace_record: "handoff",
@@ -45,11 +46,11 @@ export const PIAGENT_DIAGNOSTIC_TOOLS = new Set<string>([
   "piagent_context_budget", "piagent_context_index_status", "piagent_memory_status", "piagent_usage_snapshot"
 ]);
 export const PIAGENT_MUTATION_CAPABLE_TOOLS = new Set<string>([
-  "piagent_context_engine", "piagent_source_checkout", "piagent_profile_apply", "piagent_profile_tech_apply",
+  "piagent_context_engine", "piagent_profile_apply", "piagent_profile_tech_apply",
   "piagent_profile_tech_context_record", "piagent_project_onboarding_record", "piagent_context_index_record", "piagent_memory_note"
 ]);
 export const PIAGENT_SEQUENTIAL_TOOLS = new Set<string>([
-  ...PIAGENT_MUTATION_CAPABLE_TOOLS, "piagent_tools", "piagent_task_start", "piagent_task_progress", "piagent_context_record",
+  ...PIAGENT_MUTATION_CAPABLE_TOOLS, "piagent_wait", "piagent_source_checkout", "piagent_tools", "piagent_task_start", "piagent_task_progress", "piagent_context_record",
   "piagent_verify_record", "piagent_trace_record", "piagent_memory_citation_record"
 ]);
 
@@ -83,15 +84,15 @@ const REQUIRED_HOST_TOOLS: Record<TrajectoryPhase, string[]> = {
 
 const PHASE_TOOL_ALLOW: Record<TrajectoryPhase, string[]> = {
   intake: [],
-  scout: ["piagent_task_progress", "piagent_context_index_search", "piagent_document_read"],
-  plan: ["piagent_task_progress", "piagent_orchestration_policy"],
-  execute: ["piagent_task_progress"],
+  scout: ["piagent_task_progress", "piagent_context_index_search", "piagent_document_read", "piagent_source_checkout"],
+  plan: ["piagent_task_progress", "piagent_orchestration_policy", "piagent_source_checkout"],
+  execute: ["piagent_task_progress", "piagent_source_checkout"],
   // Runtime hooks own context, verifier, gate, and handoff evidence. Keeping
   // their record tools model-visible duplicates work and creates false manual
   // choreography in otherwise automatic tasks.
-  verify: [],
-  repair: ["piagent_task_progress", "piagent_context_index_search"],
-  review: ["piagent_task_progress"],
+  verify: ["piagent_source_checkout"],
+  repair: ["piagent_task_progress", "piagent_context_index_search", "piagent_source_checkout"],
+  review: ["piagent_task_progress", "piagent_source_checkout"],
   handoff: [],
   terminal: []
 };
@@ -111,7 +112,7 @@ export function phaseToolPolicy(phase: TrajectoryPhase, changeMode: PhaseToolPol
   const readOnlySurface = changeMode === "read-only" || phase === "review";
   const modelVisiblePiagentTools = PIAGENT_TOOL_ORDER.filter((tool) => {
     const group = PIAGENT_PRIMARY_TOOL_GROUP[tool as keyof typeof PIAGENT_PRIMARY_TOOL_GROUP];
-    return PHASE_TOOL_ALLOW[phase].includes(tool)
+    return (PHASE_TOOL_ALLOW[phase].includes(tool) || tool === "piagent_wait" && primaryGroups.includes("retrieval"))
       && primaryGroups.includes(group)
       && !PIAGENT_OPERATOR_TOOLS.has(tool)
       && !PIAGENT_DIAGNOSTIC_TOOLS.has(tool)

package/packages/piagent-core/runtime/tools/session-wait.ts

@@ -0,0 +1,42 @@
+import { performance } from "node:perf_hooks";
+
+export const MAX_SESSION_WAIT_SECONDS = 3600;
+export const SESSION_WAIT_ENTRY = "piagent-session-wait-v1";
+
+export type WaitReceipt = {
+  outcome: "elapsed" | "interrupted";
+  elapsedMs: number;
+};
+
+/** One timer, no polling, provider dispatch, shell, or detached continuation. */
+export class SessionWaitRuntime {
+  private readonly active = new Map<string, () => void>();
+
+  interrupt(key: string): void { this.active.get(key)?.(); }
+
+  wait(key: string, seconds: number, signal?: AbortSignal): Promise<WaitReceipt> {
+    if (!Number.isInteger(seconds) || seconds < 1 || seconds > MAX_SESSION_WAIT_SECONDS) {
+      throw new Error(`Wait seconds must be an integer between 1 and ${MAX_SESSION_WAIT_SECONDS}.`);
+    }
+    if (this.active.has(key)) throw new Error("A wait is already active for this session.");
+    if (signal?.aborted) return Promise.resolve({ outcome: "interrupted", elapsedMs: 0 });
+    return new Promise((resolve) => {
+      const started = performance.now();
+      let settled = false;
+      const finish = (outcome: WaitReceipt["outcome"]) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", interrupt);
+        this.active.delete(key);
+        resolve({ outcome, elapsedMs: Math.max(0, Math.round(performance.now() - started)) });
+      };
+      const interrupt = () => finish("interrupted");
+      const timer = setTimeout(() => finish("elapsed"), seconds * 1000);
+      this.active.set(key, interrupt);
+      signal?.addEventListener("abort", interrupt, { once: true });
+      // Covers an abort observed between entry and listener registration.
+      if (signal?.aborted) interrupt();
+    });
+  }
+}

package/packages/piagent-core/runtime/tools/tool-groups.ts

@@ -10,6 +10,7 @@ export const PIAGENT_TOOL_GROUPS = {
     "piagent_context_preflight"
   ],
   task: ["piagent_task_progress"],
+  waiting: ["piagent_wait"],
   recovery: [
     "piagent_context_record",
     "piagent_verify_record",
@@ -27,12 +28,12 @@ export const PIAGENT_TOOL_GROUPS = {
     "piagent_context_index_status",
     "piagent_context_index_search"
   ],
+  source: ["piagent_source_checkout"],
   knowledge: [
     "piagent_memory_status",
     "piagent_memory_search",
     "piagent_memory_citation_record",
     "piagent_document_read",
-    "piagent_source_checkout",
     "piagent_orchestration_policy"
   ],
   onboarding: [
@@ -53,6 +54,17 @@ export type PiagentToolGroup = keyof typeof PIAGENT_TOOL_GROUPS;
 export const PIAGENT_TOOL_ORDER = Object.values(PIAGENT_TOOL_GROUPS).flat();
 export const PIAGENT_TOOL_NAMES = new Set<string>(PIAGENT_TOOL_ORDER);
 
+function waitingGroups(prompt: string): PiagentToolGroup[] {
+  return /\b(?:wait|poll|monitor|check back|follow up|follow-up)\b|(?:chờ|theo dõi|kiểm tra lại)/iu.test(prompt) ? ["waiting"] : [];
+}
+
+const SUPPORTED_GIT_REPOSITORY_URL = /(?:^|[\s("'\[])https?:\/\/(?:www\.)?(?:github\.com|gitlab\.com|bitbucket\.org)\/[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+(?:\.git)?(?:[\/?#][^\s)"'\]]*)?/i;
+const SUPPORTED_GIT_SSH_REFERENCE = /(?:^|[\s("'\[])git@(?:github\.com|gitlab\.com|bitbucket\.org):[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+(?:\.git)?(?:$|[\s)"'\]])/i;
+
+export function hasSupportedGitRepositoryReference(prompt: string): boolean {
+  return SUPPORTED_GIT_REPOSITORY_URL.test(prompt) || SUPPORTED_GIT_SSH_REFERENCE.test(prompt);
+}
+
 export function toolGroupsForPrompt(prompt: string): PiagentToolGroup[] {
   const signal = classifyContextTask(prompt);
   const lower = prompt.toLowerCase();
@@ -64,11 +76,15 @@ export function toolGroupsForPrompt(prompt: string): PiagentToolGroup[] {
   }
 
   groups.add("intake");
+  for (const group of waitingGroups(prompt)) groups.add(group);
   if (signal.lane !== "tiny") groups.add("task");
   if (/\b(context (?:engine|index|search|diagnostic)|source checkout|vendor checkout)\b/.test(lower)) {
     groups.add("retrieval");
   }
-  if (/\b(document intake|project memory|orchestration policy|source checkout|subagent policy|vendor checkout)\b/.test(lower)) {
+  if (/\b(source checkout|vendor checkout)\b/.test(lower) || hasSupportedGitRepositoryReference(prompt)) {
+    groups.add("source");
+  }
+  if (/\b(document intake|project memory|orchestration policy|subagent policy)\b/.test(lower)) {
     groups.add("knowledge");
   }
   if (/\b(permission|capability|exec policy|tool policy)\b/.test(lower)) groups.add("policy");
@@ -80,7 +96,8 @@ export function toolGroupsForPrompt(prompt: string): PiagentToolGroup[] {
 
 export function activeTaskToolGroups(task: TaskContract): PiagentToolGroup[] {
   const mode = runtimeLifecycleMode(task);
-  if (mode.startsWith("automatic")) return [];
-  if (mode.startsWith("assisted")) return ["task"];
-  return ["task", "recovery"];
+  const waiting = waitingGroups(task.operatorRequest ?? task.summary ?? "");
+  if (mode.startsWith("automatic")) return waiting;
+  if (mode.startsWith("assisted")) return ["task", ...waiting];
+  return ["task", "recovery", ...waiting];
 }

package/packages/piagent-core/runtime/trajectory/trajectory-runtime.ts

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { currentWorkspaceRevisionDigest } from "../../extensions/workspace-revision.js";
 
 import { hasDurableContextEvidence } from "../../extensions/context-evidence.js";
 import type { TaskContract } from "../../extensions/guard-types.ts";
@@ -9,6 +10,7 @@ import { createTrajectoryState, createTrajectoryTransition, reduceTrajectory, tr
 import { appendTrajectoryTransition, readTrajectoryStore, writeTrajectoryState } from "./trajectory-store.ts";
 import type { TrajectoryRecommendationRef, TrajectorySourceHook, TrajectoryState, TrajectoryTransitionEvent } from "./trajectory-types.ts";
 import type { SolverDecision } from "../solver/solver-types.ts";
+import { buildOpenAiCodexWireFingerprint } from "../model/provider-wire-fingerprint.ts";
 
 export type TrajectorySyncOptions = {
   sourceHook: TrajectorySourceHook;
@@ -57,7 +59,8 @@ function phaseObservation(
   task: TaskContract,
   phase: string,
   options: TrajectorySyncOptions,
-  currentTreeDigest?: string | null
+  currentTreeDigest?: string | null,
+  workspaceRevisionDigest?: string | null
 ): TrajectoryTransitionEvent["cause"] | undefined {
   const latest = latestVerification(task);
   if (phase === "scout" && (options.contextObserved === true || hasDurableContextEvidence(task) || stepObserved(task, ["scope", "challenge", "scout"]))) return "context-observed";
@@ -68,7 +71,7 @@ function phaseObservation(
   }
   if (phase === "verify") {
     if (options.verificationStarted === true) return "verification-started";
-    if (verificationEvidenceProvesStableTree(latest, currentTreeDigest)) return "verification-passed";
+    if (verificationEvidenceProvesStableTree(latest, currentTreeDigest, workspaceRevisionDigest)) return "verification-passed";
   }
   if (phase === "review" && stepObserved(task, ["review"])) return "review-observed";
   if (phase === "handoff" && options.handoffObserved === true) return "handoff-observed";
@@ -98,8 +101,19 @@ export class TrajectoryRuntime {
   }
 
   sync(cwd: string, sessionId: string, task: TaskContract, options: TrajectorySyncOptions): TrajectorySyncResult {
+    try { return this.syncDurable(cwd, sessionId, task, options); }
+    catch (error) {
+      wireSessions.get(wireKey(cwd, sessionId))?.invalidate("trajectory-sync-failed");
+      throw error;
+    }
+  }
+
+  private syncDurable(cwd: string, sessionId: string, task: TaskContract, options: TrajectorySyncOptions): TrajectorySyncResult {
     const stored = readTrajectoryStore(cwd, task.taskRunId);
-    if (!stored.enforcementSafe) return { status: "corrupt", initialized: false, enforcementSafe: false, transitions: [], warnings: stored.warnings };
+    if (!stored.enforcementSafe) {
+      wireSessions.get(wireKey(cwd, sessionId))?.invalidate("trajectory-store-corrupt");
+      return { status: "corrupt", initialized: false, enforcementSafe: false, transitions: [], warnings: stored.warnings };
+    }
     let initialized = false;
     let state = stored.state;
     if (!state) {
@@ -123,6 +137,7 @@ export class TrajectoryRuntime {
     const transitions: TrajectoryTransitionEvent[] = [];
     const observedAt = options.observedAt ?? new Date().toISOString();
     const taskDigest = digest(task), currentTreeDigest = treeDigest(task);
+    const workspaceRevisionDigest = currentWorkspaceRevisionDigest(cwd);
     const latest = latestVerification(task);
     if (state.currentPhase === "intake" && sourcePlanningAuthorized(task)) {
       const path = trajectoryPath(state.changeMode, state.riskLane);
@@ -184,7 +199,7 @@ export class TrajectoryRuntime {
       state = recordTransition(cwd, state, event);
       transitions.push(event);
     }
-    const passingVerifierAfterRepair = verificationEvidenceProvesStableTree(latest, currentTreeDigest)
+    const passingVerifierAfterRepair = verificationEvidenceProvesStableTree(latest, currentTreeDigest, workspaceRevisionDigest)
       && Date.parse(String(latest?.observedAt ?? latest?.recordedAt)) >= Date.parse(state.updatedAt);
     if (state.currentPhase === "repair" && (options.verificationStarted || passingVerifierAfterRepair)) {
       const event = createTrajectoryTransition(state, { to: "verify", cause: "verification-started", sourceHook: options.sourceHook, taskDigest, treeDigest: currentTreeDigest, observedAt });
@@ -195,7 +210,7 @@ export class TrajectoryRuntime {
     while (state.currentPhase !== "terminal") {
       const currentIndex = path.indexOf(state.currentPhase);
       const next = currentIndex >= 0 ? path[currentIndex + 1] : undefined;
-      const cause = next && next !== "terminal" ? phaseObservation(task, next, options, currentTreeDigest) : undefined;
+      const cause = next && next !== "terminal" ? phaseObservation(task, next, options, currentTreeDigest, workspaceRevisionDigest) : undefined;
       if (!next || next === "terminal" || !cause) break;
       const event = createTrajectoryTransition(state, { to: next, cause, sourceHook: options.sourceHook, taskDigest, treeDigest: currentTreeDigest, observedAt });
       state = recordTransition(cwd, state, event);
@@ -219,6 +234,7 @@ export class TrajectoryRuntime {
       state = recordTransition(cwd, state, event);
       transitions.push(event);
     }
+    observeHostWireTrajectory(cwd, sessionId, task, state, transitions, initialized);
     return { status: "ok", initialized, enforcementSafe: true, state, transitions, warnings: stored.warnings };
   }
 
@@ -234,3 +250,174 @@ export class TrajectoryRuntime {
     return task ? this.syncToolCall(cwd, sessionId, task, event, observedAt) : undefined;
   }
 }
+
+export const HOST_WIRE_PHASE_EDGES: Record<string, string[]> = {
+  intake: ["scout", "plan", "execute", "review", "handoff", "terminal"],
+  scout: ["plan", "review", "handoff", "terminal"], plan: ["execute", "review", "handoff", "terminal"],
+  execute: ["verify", "repair", "handoff", "terminal"], verify: ["repair", "review", "handoff", "terminal"],
+  repair: ["verify", "handoff", "terminal"], review: ["repair", "handoff", "terminal"], handoff: ["terminal"], terminal: []
+};
+for (const targets of Object.values(HOST_WIRE_PHASE_EDGES)) Object.freeze(targets);
+Object.freeze(HOST_WIRE_PHASE_EDGES);
+type WireRecord = Record<string, any>;
+export type HostWireSessionOptions = {
+  cwd: string; sessionId: string; runtimeInstanceRef: string; manifest: WireRecord;
+  signReceipt: (material: string) => string;
+  record: (envelope: { material: string; signature: string }) => void | Promise<void>;
+};
+export type HostWireOperation = { operationRef: string; messageRequestId: string; inputText: string };
+export type HostWireSession = {
+  beginOperation(input: HostWireOperation): (reason: string) => void;
+  validatePayload(input: { payload: unknown; model: { provider?: string; id?: string }; hookErrors: number }): Promise<void>;
+  dispose(): void;
+};
+type WireInput = { turnId: string; promptHash: string; text: string; source: string; hasImages: boolean };
+type WireState = {
+  invalidate(reason: string): void;
+  observeInput(input: WireInput): void;
+  observeTrajectory(task: TaskContract, state: TrajectoryState, events: TrajectoryTransitionEvent[], initialized: boolean): void;
+};
+const WIRE_REGISTRY_KEY = Symbol.for("piagent.host-wire-session.v1");
+const wireRoot = globalThis as typeof globalThis & { [WIRE_REGISTRY_KEY]?: Map<string, WireState> };
+const wireSessions = wireRoot[WIRE_REGISTRY_KEY] ??= new Map<string, WireState>();
+const wireKey = (cwd: string, sessionId: string) => `${cwd}\0${sessionId}`;
+const wireHash = (value: string) => crypto.createHash("sha256").update(value).digest("hex");
+const wireId = (value: unknown) => typeof value === "string" && value.length > 0 && value.length <= 2048 && !value.includes("\0");
+const wireAssert = (condition: unknown, reason: string): void => { if (!condition) throw new Error(`host-wire-${reason}`); };
+
+export function observeHostWireInput(cwd: string, sessionId: string, input: WireInput): void {
+  wireSessions.get(wireKey(cwd, sessionId))?.observeInput(input);
+}
+
+function observeHostWireTrajectory(cwd: string, sessionId: string, task: TaskContract,
+  state: TrajectoryState, events: TrajectoryTransitionEvent[], initialized: boolean): void {
+  wireSessions.get(wireKey(cwd, sessionId))?.observeTrajectory(task, state, events, initialized);
+}
+
+/** Host callbacks are capabilities; neither a transcript entry nor a serialized task can invoke them. */
+export function createHostWireSession(options: HostWireSessionOptions): HostWireSession {
+  const manifest = structuredClone(options.manifest), key = wireKey(options.cwd, options.sessionId);
+  wireAssert(!wireSessions.has(key), "session-already-bound");
+  wireAssert(wireId(options.sessionId) && wireId(options.runtimeInstanceRef), "runtime-identity-missing");
+  wireAssert(manifest.schemaVersion === 1 && manifest.protocol === "phase-valid-configuration-v1"
+    && manifest.source === "pinned-host-definitions" && manifest.workingDirectory === options.cwd, "manifest-invalid");
+  wireAssert([manifest.candidateDigest, manifest.configurationDigest, manifest.definitionDigest]
+    .every((value) => /^[a-f0-9]{64}$/.test(value ?? "")), "manifest-identity-missing");
+  wireAssert(manifest.requestedTier === "fast" && manifest.requestTier === "priority", "requested-tier-mismatch");
+  wireAssert(JSON.stringify(manifest.allowedEdges) === JSON.stringify(HOST_WIRE_PHASE_EDGES), "phase-policy-mismatch");
+  wireAssert(Array.isArray(manifest.states) && manifest.states.length > 0 && manifest.states.length <= 4096, "states-invalid");
+  const selectors = new Set<string>(), stateIds = new Set<string>();
+  for (const state of manifest.states) {
+    wireAssert(state && wireId(state.id) && !stateIds.has(state.id), "state-id-invalid"); stateIds.add(state.id);
+    wireAssert([state.operatorInputHash, state.inputHash].every((value) => /^[a-f0-9]{64}$/.test(value ?? "")), "input-hash-invalid");
+    wireAssert((state.taskPresence === "none" && state.phase === null)
+      || (state.taskPresence === "current" && Object.hasOwn(HOST_WIRE_PHASE_EDGES, state.phase)), "state-phase-invalid");
+    const selector = JSON.stringify([state.operatorInputHash, state.inputHash, state.taskPresence, state.phase]);
+    wireAssert(!selectors.has(selector), "state-selector-ambiguous"); selectors.add(selector);
+    wireAssert(state.fingerprint?.state === "known" && /^[a-f0-9]{64}$/.test(state.fingerprint.requestPrefixFingerprint), "fingerprint-invalid");
+  }
+  const publicKey = crypto.createPublicKey({ key: Buffer.from(manifest.receiptPublicKey, "base64"), format: "der", type: "spki" });
+  wireAssert(publicKey.asymmetricKeyType === "ed25519" && typeof options.signReceipt === "function"
+    && typeof options.record === "function", "receipt-authority-missing");
+  const manifestDigest = wireHash(JSON.stringify(manifest));
+  let operation: (HostWireOperation & { operatorInputHash: string; token: string }) | undefined;
+  let accepted: (WireInput & { inputHash: string }) | undefined;
+  let task: { taskId: string; taskRunId: string; phase: string; sequence: number; outcome: string; stateDigest: string } | undefined;
+  let disposed = false, pending = false, fault: string | undefined, sequence = 0, previousReceiptHash: string | null = null;
+  const events: WireRecord[] = [];
+  const fail = (reason: string): never => { fault = reason; throw new Error(`host-wire-${reason}`); };
+  const live = () => { if (disposed || wireSessions.get(key) !== state) fail("runtime-retired"); if (fault) fail(fault); };
+  const enqueue = (event: WireRecord) => { if (events.length >= 1024) fail("event-budget-exhausted"); events.push(structuredClone(event)); };
+  const assertCurrentTrajectory = () => {
+    if (!task) return;
+    const stored = readTrajectoryStore(options.cwd, task.taskRunId);
+    if (!stored.enforcementSafe || !stored.state || digest(stored.state) !== task.stateDigest) fail("trajectory-custody-changed");
+  };
+  const state: WireState = {
+    invalidate(reason) { fault = reason; },
+    observeInput(input) {
+      live(); if (!operation || accepted) fail("input-not-admitted");
+      if (input.hasImages !== false) fail("input-images-unprojected");
+      if (!wireId(input.turnId) || !["rpc", "interactive", "extension"].includes(input.source)) fail("input-identity-invalid");
+      const inputHash = wireHash(input.text.trim());
+      if (!manifest.states.some((row: WireRecord) => row.operatorInputHash === operation!.operatorInputHash && row.inputHash === inputHash)) fail("input-not-in-manifest");
+      accepted = { ...input, inputHash };
+      enqueue({ type: "input-accepted", operationRef: operation.operationRef, messageRequestId: operation.messageRequestId,
+        operatorInputHash: operation.operatorInputHash, inputHash, turnId: input.turnId, source: input.source });
+    },
+    observeTrajectory(observedTask, observedState, transitions, initialized) {
+      if (!operation || !accepted) return;
+      live();
+      const stored = readTrajectoryStore(options.cwd, observedTask.taskRunId);
+      if (!stored.enforcementSafe || JSON.stringify(stored.state) !== JSON.stringify(observedState)) fail("trajectory-readback-mismatch");
+      if (observedTask.sessionId !== options.sessionId || observedState.taskId !== observedTask.taskId || observedState.taskRunId !== observedTask.taskRunId
+        || observedState.sessionHash !== wireHash(options.sessionId)) fail("task-identity-mismatch");
+      if (!task || task.taskRunId !== observedTask.taskRunId) {
+        if (task && task.outcome === "pending") fail("pending-task-replaced");
+        if (!initialized || transitions.length === 0 && observedState.sequence !== 0) fail("task-attachment-unproven");
+        task = { taskId: observedTask.taskId, taskRunId: observedTask.taskRunId, phase: "intake", sequence: 0, outcome: "pending", stateDigest: "" };
+        enqueue({ type: "task-attached", initialState: createTrajectoryState({ taskId: task.taskId, taskRunId: task.taskRunId,
+          sessionId: options.sessionId, changeMode: observedState.changeMode, riskLane: observedState.riskLane,
+          recommendationRef: observedState.recommendationRef, createdAt: observedState.createdAt }) });
+      }
+      for (const event of transitions) {
+        if (event.taskRunId !== task.taskRunId || event.taskId !== task.taskId || event.from !== task.phase
+          || event.sequence !== task.sequence + 1 || !HOST_WIRE_PHASE_EDGES[event.from]?.includes(event.to)) fail("trajectory-edge-invalid");
+        enqueue({ type: "phase-transition", event }); task.phase = event.to; task.sequence = event.sequence;
+      }
+      if (task.phase !== observedState.currentPhase || task.sequence !== observedState.sequence) fail("trajectory-observation-gap");
+      task.outcome = observedTask.trace.outcome;
+      task.stateDigest = digest(observedState);
+    }
+  };
+  wireSessions.set(key, state);
+  return {
+    beginOperation(input) {
+      live(); if (operation || pending) fail("operation-already-active");
+      if (!wireId(input.operationRef) || !wireId(input.messageRequestId) || !input.inputText.trim()) fail("operation-identity-invalid");
+      const current = { ...input, operatorInputHash: wireHash(input.inputText.trim()), token: crypto.randomUUID() };
+      if (!manifest.states.some((row: WireRecord) => row.operatorInputHash === current.operatorInputHash)) fail("operation-not-in-manifest");
+      operation = current; accepted = undefined;
+      if (task && task.outcome !== "pending" && task.phase === "terminal") {
+        enqueue({ type: "task-detached", taskId: task.taskId, taskRunId: task.taskRunId, outcome: task.outcome }); task = undefined;
+      }
+      enqueue({ type: "operation-accepted", operationRef: current.operationRef, messageRequestId: current.messageRequestId,
+        operatorInputHash: current.operatorInputHash, predecessorReceiptHash: previousReceiptHash });
+      return (reason) => {
+        if (operation !== current) return;
+        enqueue({ type: "operation-closed", operationRef: current.operationRef, messageRequestId: current.messageRequestId, reason });
+        operation = undefined; accepted = undefined;
+      };
+    },
+    async validatePayload(input) {
+      live(); if (!operation || !accepted || pending) fail("payload-without-current-input");
+      assertCurrentTrajectory();
+      if (input.hookErrors !== 0) fail("extension-hook-error");
+      const current = operation, currentInput = accepted, phase = task?.phase ?? null, taskSequence = task?.sequence ?? 0;
+      const selected = manifest.states.find((row: WireRecord) => row.operatorInputHash === current.operatorInputHash
+        && row.inputHash === currentInput.inputHash && row.taskPresence === (task ? "current" : "none") && row.phase === phase);
+      if (!selected) fail("state-not-in-manifest");
+      const fingerprint = buildOpenAiCodexWireFingerprint({ payload: input.payload, provider: input.model.provider,
+        modelId: input.model.id, workingDirectory: options.cwd, platformRoot: manifest.platformRoot });
+      if (`${input.model.provider}/${input.model.id}` !== manifest.model || fingerprint.state !== "known"
+        || fingerprint.reasoningEffort !== manifest.thinking || (input.payload as WireRecord)?.service_tier !== manifest.requestTier
+        || JSON.stringify(fingerprint) !== JSON.stringify(selected.fingerprint)) fail("final-payload-drift");
+      const material = JSON.stringify({ schemaVersion: 1, protocol: manifest.protocol, manifestDigest, sequence: sequence + 1,
+        previousReceiptHash, sessionId: options.sessionId, workingDirectory: options.cwd, runtimeInstanceRef: options.runtimeInstanceRef,
+        operationRef: current.operationRef, messageRequestId: current.messageRequestId, operatorInputHash: current.operatorInputHash,
+        inputHash: currentInput.inputHash, turnId: currentInput.turnId, taskId: task?.taskId ?? null, taskRunId: task?.taskRunId ?? null,
+        phase, trajectorySequence: taskSequence, stateId: selected.id, fingerprint, events: structuredClone(events) });
+      const envelope = { material, signature: options.signReceipt(material) };
+      if (!crypto.verify(null, Buffer.from(material), publicKey, Buffer.from(envelope.signature, "base64"))) fail("receipt-signature-invalid");
+      pending = true;
+      try {
+        await options.record(structuredClone(envelope)); live(); assertCurrentTrajectory();
+        if (operation !== current || accepted !== currentInput || task?.phase !== (phase ?? undefined)
+          || (task?.sequence ?? 0) !== taskSequence) fail("payload-binding-superseded");
+        previousReceiptHash = wireHash(JSON.stringify(envelope)); sequence += 1; events.length = 0;
+      } catch (error) { fault ??= "receipt-not-durable"; throw error; }
+      finally { pending = false; }
+    },
+    dispose() { disposed = true; operation = undefined; accepted = undefined; if (wireSessions.get(key) === state) wireSessions.delete(key); }
+  };
+}

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

@@ -1,13 +1,14 @@
 import crypto from "node:crypto";
 import { isCurrentWorkingTreeDigest } from "../../extensions/working-tree-digest.js";
+import { TRAJECTORY_PHASES, type TrajectoryPhase } from "../../extensions/trajectory-contract.ts";
+
+export { TRAJECTORY_PHASES, type TrajectoryPhase } from "../../extensions/trajectory-contract.ts";
 
 export const TRAJECTORY_SCHEMA_VERSION = 1 as const;
 export const TRAJECTORY_POLICY_VERSION = "trajectory-v1" as const;
-export const TRAJECTORY_PHASES = Object.freeze(["intake", "scout", "plan", "execute", "verify", "repair", "review", "handoff", "terminal"] as const);
 export const TRAJECTORY_CAUSES = Object.freeze(["task-started", "context-observed", "plan-observed", "execution-authorized", "mutation-observed", "verification-started", "verification-passed", "verification-failed", "review-observed", "handoff-observed", "task-terminal", "recovery-requested", "explicit-skip"] as const);
 export const TRAJECTORY_SOURCE_HOOKS = Object.freeze(["input", "agent-start", "tool-call", "tool-result", "completion", "session-start", "task-state", "operator"] as const);
 
-export type TrajectoryPhase = typeof TRAJECTORY_PHASES[number];
 export type TrajectoryCause = typeof TRAJECTORY_CAUSES[number];
 export type TrajectorySourceHook = typeof TRAJECTORY_SOURCE_HOOKS[number];
 export type TerminalTaskOutcomeRef = { taskRunId: string; taskUpdatedAt: string; taskDigest: string };