@piagent/platform 1.3.0 → 1.4.0

package/packages/piagent-core/runtime/inspection/task-control-journal.ts

@@ -0,0 +1,131 @@
+import { createHash } from "node:crypto";
+
+import { activeSessionTask } from "../../extensions/task-state.js";
+import { readTaskJournal, transactTaskJournal } from "../../extensions/task-journal.js";
+
+const CONTROL_FACTS = new Set([
+  "task-control.stop-requested", "task-control.stop-settled", "task-control.pause-requested", "task-control.paused",
+  "task-control.pause-cancelled", "task-control.resume-requested", "task-control.resumed", "task-control.resume-rejected"
+]);
+const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+export type DurableControlState = "active" | "pause-requested" | "paused" | "terminal" | "unknown";
+type Task = { taskId: string; taskRunId: string; sessionId: string; trace: { outcome: string } };
+type JournalEvent = { sequence: number; hash: string; eventType: string; taskRunId?: string; taskId?: string; sessionId?: string;
+  recordedAt: string; data?: Record<string, any> };
+export type TaskControlProjection = { state: DurableControlState; controlRevision: string; pauseEpoch: number; dispatchBlocked: boolean;
+  stopPending: boolean; journalHead: string | null; reasonCode: string | null; sequence: number };
+export type TaskControlTransition = { cwd: string; task: Task; runtimeInstanceId: string; commandId: string; idempotencyKeyDigest: string;
+  actionDigest: string; fact: string; action: "stop" | "pause" | "resume"; expectedControlRevision: string; expectedStates: DurableControlState[];
+  toState: DurableControlState; agentOperationId?: string | null; resultCode: string; reasonCode?: string | null; pauseEpoch?: number;
+  preWorkingTreeDigest?: string | null; postWorkingTreeDigest?: string | null };
+
+function hash(value: unknown): string { return createHash("sha256").update(JSON.stringify(value)).digest("hex"); }
+function revision(taskRunId: string, state: DurableControlState, event?: JournalEvent): string {
+  return `control-rev.${hash([taskRunId, state, event?.sequence ?? 0, event?.hash ?? null])}`;
+}
+function evidence(event?: JournalEvent): string | null { return event?.hash ? `journal.${event.hash}` : null; }
+function taskEvents(events: JournalEvent[], task: Task): JournalEvent[] {
+  return events.filter((event) => event.taskRunId === task.taskRunId && event.taskId === task.taskId && event.sessionId === task.sessionId);
+}
+function project(events: JournalEvent[], task: Task, corruptions: string[] = []): TaskControlProjection {
+  const relevant = taskEvents(events, task).filter((event) => CONTROL_FACTS.has(event.eventType));
+  const latest = relevant.at(-1), sequence = latest?.sequence ?? 0;
+  if (task.trace.outcome !== "pending") return { state: "terminal", controlRevision: revision(task.taskRunId, "terminal", latest), pauseEpoch: 0,
+    dispatchBlocked: true, stopPending: false, journalHead: evidence(latest), reasonCode: null, sequence };
+  if (corruptions.length) return { state: "unknown", controlRevision: revision(task.taskRunId, "unknown", latest), pauseEpoch: 0,
+    dispatchBlocked: true, stopPending: false, journalHead: evidence(latest), reasonCode: "task-journal-corrupt", sequence };
+  let state: DurableControlState = "active", pauseEpoch = 0;
+  const pendingStops = new Set<string>();
+  for (const event of relevant) {
+    const data = event.data ?? {}, commandId = String(data.commandId ?? "");
+    if (event.eventType === "task-control.pause-requested") { state = "pause-requested"; pauseEpoch = Number(data.pauseEpoch) || pauseEpoch + 1; }
+    else if (event.eventType === "task-control.paused") { state = "paused"; pauseEpoch = Number(data.pauseEpoch) || pauseEpoch; }
+    else if (event.eventType === "task-control.pause-cancelled" || event.eventType === "task-control.resumed") state = "active";
+    if (event.eventType === "task-control.stop-requested" && commandId) pendingStops.add(commandId);
+    if (event.eventType === "task-control.stop-settled" && commandId) pendingStops.delete(commandId);
+  }
+  const stopPending = pendingStops.size > 0;
+  return { state, controlRevision: revision(task.taskRunId, state, latest), pauseEpoch, dispatchBlocked: state !== "active",
+    stopPending, journalHead: evidence(latest), reasonCode: null, sequence };
+}
+
+export function inspectTaskControlState(cwd: string, task: Task): TaskControlProjection {
+  const journal = readTaskJournal(cwd, { taskRunId: task.taskRunId, sessionId: task.sessionId });
+  return project(journal.events as JournalEvent[], task, journal.corruptions);
+}
+
+export function appendTaskControlTransition(input: TaskControlTransition): { ok: boolean; duplicate: boolean; reasonCode: string | null;
+  before: TaskControlProjection; after: TaskControlProjection; evidenceRef: string | null } {
+  let before = inspectTaskControlState(input.cwd, input.task), duplicate = false, failure: string | null = null;
+  let record: JournalEvent | undefined;
+  const outcome = transactTaskJournal(input.cwd, ({ events }: { events: JournalEvent[] }) => {
+    const currentTask = activeSessionTask(input.cwd, input.task.sessionId) as Task | undefined;
+    before = project(events, input.task);
+    if (!currentTask || currentTask.taskId !== input.task.taskId || currentTask.taskRunId !== input.task.taskRunId) {
+      failure = "task-identity-mismatch"; return { result: null };
+    }
+    if (currentTask.trace.outcome !== "pending") { failure = "task-terminal"; return { result: null }; }
+    if (before.controlRevision !== input.expectedControlRevision) { failure = "stale-control-revision"; return { result: null }; }
+    if (!input.expectedStates.includes(before.state)) { failure = `control-state-${before.state}`; return { result: null }; }
+    const prior = taskEvents(events, input.task).find((event) => event.eventType === input.fact
+      && (event.data?.commandId === input.commandId || event.data?.idempotencyKeyDigest === input.idempotencyKeyDigest));
+    if (prior) {
+      if (prior.data?.idempotencyKeyDigest !== input.idempotencyKeyDigest || prior.data?.actionDigest !== input.actionDigest) failure = "idempotency-payload-mismatch";
+      else { duplicate = true; record = prior; }
+      return { result: null };
+    }
+    const commandConflict = taskEvents(events, input.task).find((event) => event.data?.commandId === input.commandId
+      && (event.data?.idempotencyKeyDigest !== input.idempotencyKeyDigest || event.data?.actionDigest !== input.actionDigest));
+    if (commandConflict) { failure = "idempotency-payload-mismatch"; return { result: null }; }
+    return { event: { eventType: input.fact, taskRunId: input.task.taskRunId, taskId: input.task.taskId, sessionId: input.task.sessionId,
+      idempotencyKey: input.commandId, data: { schemaVersion: 1, runtimeInstanceId: input.runtimeInstanceId, commandId: input.commandId,
+        idempotencyKeyDigest: input.idempotencyKeyDigest, actionDigest: input.actionDigest, action: input.action,
+        expectedControlRevision: input.expectedControlRevision, fromControlState: before.state, toControlState: input.toState,
+        pauseEpoch: input.pauseEpoch ?? before.pauseEpoch, agentOperationId: input.agentOperationId ?? null,
+        resultCode: input.resultCode, reasonCode: input.reasonCode ?? null,
+        preWorkingTreeDigest: input.preWorkingTreeDigest ?? null, postWorkingTreeDigest: input.postWorkingTreeDigest ?? null } }, result: null };
+  }) as unknown as { appended: boolean; record?: JournalEvent };
+  if (outcome.appended) record = outcome.record;
+  const after = inspectTaskControlState(input.cwd, input.task);
+  return { ok: !failure, duplicate, reasonCode: failure, before, after, evidenceRef: evidence(record) };
+}
+
+export function readTaskControlReceipt(cwd: string, task: Task, binding: { commandId: string; idempotencyKeyDigest: string;
+  actionDigest: string }): { receipt: Record<string, unknown>; conflict: boolean; invalid: boolean } | null {
+  const journal = readTaskJournal(cwd, { taskRunId: task.taskRunId, sessionId: task.sessionId });
+  if (journal.corruptions.length) return null;
+  const event = [...journal.events].reverse().find((item: any) => item.eventType === "task-control.command-receipt"
+    && item.taskId === task.taskId && (item.data?.commandId === binding.commandId
+      || item.data?.idempotencyKeyDigest === binding.idempotencyKeyDigest));
+  if (!event?.data?.receipt || typeof event.data.receipt !== "object") return null;
+  const receipt = event.data.receipt as Record<string, unknown>;
+  const invalid = receipt.commandId !== event.data.commandId || receipt.idempotencyKeyDigest !== event.data.idempotencyKeyDigest
+    || receipt.actionDigest !== event.data.actionDigest;
+  const conflict = event.data.actionDigest !== binding.actionDigest || event.data.commandId === binding.commandId
+    && event.data.idempotencyKeyDigest !== binding.idempotencyKeyDigest;
+  return { receipt: structuredClone(receipt), conflict, invalid };
+}
+
+export function recordTaskControlReceipt(cwd: string, task: Task, commandId: string, idempotencyKeyDigest: string,
+  actionDigest: string, receipt: Record<string, unknown>): { ok: boolean; duplicate: boolean; evidenceRef: string | null } {
+  let duplicate = false, conflict = false, record: JournalEvent | undefined;
+  const result = transactTaskJournal(cwd, ({ events }: { events: JournalEvent[] }) => {
+    const prior = taskEvents(events, task).find((event) => event.eventType === "task-control.command-receipt"
+      && (event.data?.commandId === commandId || event.data?.idempotencyKeyDigest === idempotencyKeyDigest));
+    if (prior) {
+      if (prior.data?.idempotencyKeyDigest !== idempotencyKeyDigest || prior.data?.actionDigest !== actionDigest) conflict = true;
+      else if (JSON.stringify(prior.data?.receipt) === JSON.stringify(receipt)) { duplicate = true; record = prior; }
+      if (conflict || duplicate) return { result: null };
+    }
+    return { event: { eventType: "task-control.command-receipt", taskRunId: task.taskRunId, taskId: task.taskId, sessionId: task.sessionId,
+      idempotencyKey: `${commandId}:${String(receipt.phase ?? "receipt")}:${String(receipt.resultCode ?? "result")}`,
+      data: { schemaVersion: 1, commandId, idempotencyKeyDigest, actionDigest, receipt } }, result: null };
+  }) as unknown as { appended: boolean; record?: JournalEvent };
+  if (result.appended) record = result.record;
+  return { ok: !conflict, duplicate, evidenceRef: evidence(record) };
+}
+
+export function validTaskControlBinding(value: { commandId: string; idempotencyKeyDigest: string; actionDigest: string }): boolean {
+  return REF.test(value.commandId) && DIGEST.test(value.idempotencyKeyDigest) && DIGEST.test(value.actionDigest);
+}

package/packages/piagent-core/runtime/inspection/task-handoff-history.ts

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+
+import { redactSensitiveText } from "../../extensions/redaction-core.js";
+import { readHandoffProjection } from "../recovery/handoff-projection.ts";
+import { inspectTaskResumeState } from "../recovery/resume-state.ts";
+import { inspectBoundedContextTelemetry } from "./context-telemetry-inspection.ts";
+import { taskRunOpaqueRef } from "./task-run-index.ts";
+
+const MAX_EVENTS = 100;
+
+type Task = { taskId: string; taskRunId: string; sessionId: string; [key: string]: any };
+type Identity = { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string; taskRunId: string;
+  agentOperationId: null; toolCallId: null };
+
+function opaque(prefix: string, value: string): string {
+  return `${prefix}.${createHash("sha256").update(`piagent-webui-handoff-history-v1\0${value}`).digest("hex").slice(0, 48)}`;
+}
+
+function display(value: unknown, maximum = 240): string {
+  return redactSensitiveText(String(value ?? "")).text.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim().slice(0, maximum);
+}
+
+function timestamp(value: unknown): value is string {
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)
+    && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+}
+
+function nextAction(cwd: string, task: Task) {
+  const resume = inspectTaskResumeState(cwd, task as any, task.sessionId), next = resume.reconstruction.nextAction;
+  return { action: next.action, stepRef: next.stepId ? opaque("step", `${task.taskRunId}\0${next.stepId}`) : null,
+    reason: display(next.reason, 500) || "No authoritative next-action reason is available.", exactCommandCount: next.exactCommands.length,
+    dispatchable: false, enforcementSafe: resume.enforcementSafe };
+}
+
+function currentHandoff(cwd: string, task: Task) {
+  const handoff = readHandoffProjection(cwd, task.taskRunId); if (!handoff) return null;
+  if (handoff.identity.taskId !== task.taskId || handoff.identity.taskRunId !== task.taskRunId) throw new Error("handoff-identity-conflict");
+  return { handoffRef: opaque("handoff", `${task.taskRunId}\0${handoff.generatedAt}\0${handoff.tree.currentDigest ?? "none"}`),
+    generatedAt: handoff.generatedAt, phase: display(handoff.state.phase, 64) || null, taskOutcome: handoff.state.taskOutcome,
+    gateDecision: handoff.state.gateDecision, completionApproved: handoff.state.completionApproved,
+    requiredAuthority: handoff.requiredAuthority.kind, treeEvidenceCurrent: handoff.tree.evidenceCurrent,
+    latestVerifierMatchesCurrentTree: handoff.tree.latestVerifierMatchesCurrentTree,
+    changedFileCount: handoff.changedFiles.current.length, missingCount: handoff.state.missing.length,
+    projectedAction: display(handoff.nextSafeAction.action, 80) || "unknown" };
+}
+
+function unavailable(identity: Identity, runRef: string, generatedAt: string, reasonCode: string) {
+  return { schemaVersion: 1, version: "piagent-webui-handoff-history-v1", generatedAt, identity: structuredClone(identity), runRef,
+    state: "unavailable", historyRevision: null, completeness: "unknown", current: null,
+    nextAction: { action: "unknown", stepRef: null, reason: "Handoff authority is unavailable.", exactCommandCount: 0,
+      dispatchable: false, enforcementSafe: false }, events: [], page: { total: 0, returned: 0, truncated: false }, warnings: [],
+    health: { state: "error", reasonCode, message: "Handoff history is unavailable." } };
+}
+
+export function projectTaskHandoffHistory(input: { cwd: string; task: Task; identity: Identity; generatedAt?: string }): Record<string, any> {
+  const generatedAt = input.generatedAt ?? new Date().toISOString(), runRef = taskRunOpaqueRef(input.task.taskRunId);
+  try {
+    const inspected = inspectBoundedContextTelemetry(input.cwd, { limit: 5_000 });
+    let malformed = inspected.corruptions;
+    const matching = inspected.records.flatMap((record: any, ordinal: number) => {
+      if (record?.event !== "handoff_projection_written" || record.taskId !== input.task.taskId
+        || record.taskRunId !== input.task.taskRunId || record.sessionId !== input.task.sessionId) return [];
+      if (record.schemaVersion !== 1 || !timestamp(record.recordedAt) || typeof record.completionApproved !== "boolean") { malformed += 1; return []; }
+      const action = display(record.recoveryAction, 80) || "unknown", phase = display(record.phase, 64) || null;
+      return [{ ordinal, recordedAt: record.recordedAt, phase, completionApproved: record.completionApproved, projectedAction: action }];
+    });
+    const projected = matching.map((event: any, index: number) => {
+      const fact = { ...event }; delete fact.ordinal;
+      const digest = createHash("sha256").update(JSON.stringify({ taskRunId: input.task.taskRunId, ordinal: event.ordinal, fact })).digest("hex");
+      return { eventRef: opaque("handoff-event", digest), evidenceRef: opaque("telemetry", digest), sequence: index + 1, ...fact };
+    });
+    const events = projected.slice(-MAX_EVENTS), current = currentHandoff(input.cwd, input.task), next = nextAction(input.cwd, input.task);
+    const warnings: Array<{ code: string; count: number; message: string }> = [];
+    if (!inspected.exists) warnings.push({ code: "telemetry-missing", count: 1, message: "No bounded handoff telemetry was found for this project." });
+    if (malformed > 0) warnings.push({ code: "telemetry-corrupt", count: malformed, message: `${malformed} telemetry record(s) could not be validated.` });
+    if (inspected.recoverableTailBytes > 0) warnings.push({ code: "telemetry-incomplete-tail", count: inspected.recoverableTailBytes,
+      message: "An incomplete telemetry tail may omit the latest handoff fact." });
+    if (inspected.inputTruncated) warnings.push({ code: "telemetry-input-truncated", count: 1, message: "Older handoff telemetry is outside the bounded inspection window." });
+    if (projected.length > events.length) warnings.push({ code: "history-truncated", count: projected.length - events.length,
+      message: `${projected.length - events.length} older handoff event(s) are outside this bounded page.` });
+    if (!current) warnings.push({ code: "current-handoff-missing", count: 1, message: "No current authoritative handoff projection was found for this run." });
+    if (current && projected.length === 0) warnings.push({ code: "history-snapshot-only", count: 1, message: "Only the latest authoritative handoff snapshot is available." });
+    const incomplete = malformed > 0 || inspected.recoverableTailBytes > 0 || inspected.inputTruncated;
+    const completeness = incomplete || !current && projected.length > 0 ? "partial" : current && projected.length === 0 ? "snapshot-only"
+      : !current && projected.length === 0 ? "missing" : "complete";
+    const historyRevision = `handoff-history.${createHash("sha256").update(JSON.stringify({ current, next, events, completeness })).digest("hex")}`;
+    return { schemaVersion: 1, version: "piagent-webui-handoff-history-v1", generatedAt, identity: structuredClone(input.identity), runRef,
+      state: "ready", historyRevision, completeness, current, nextAction: next, events,
+      page: { total: projected.length, returned: events.length, truncated: projected.length > events.length }, warnings,
+      health: warnings.length ? { state: "degraded", reasonCode: "handoff-history-warning", message: "Some handoff facts are unavailable or omitted." }
+        : { state: "ok", reasonCode: null, message: null } };
+  } catch {
+    return unavailable(input.identity, runRef, generatedAt, "handoff-history-invalid");
+  }
+}

package/packages/piagent-core/runtime/inspection/task-provenance-projection.ts

@@ -0,0 +1,60 @@
+import {
+  decodeMutationRepoPath,
+  type MutationProvenanceRecord
+} from "./mutation-provenance-contract.ts";
+import { readMutationProvenance } from "./mutation-provenance-store.ts";
+import { taskBaselineManifestRef } from "./source-evidence-store.ts";
+import type { TaskBaselineEntry, TaskBaselineManifest } from "./source-evidence-contract.ts";
+
+export type SourceProvenance = {
+  classification: "runtime-observed-agent" | "post-baseline-unattributed" | "mixed";
+  evidence: "exact" | "unavailable";
+  baselineEvidenceRef: string | null;
+  mutationEvidenceRefs: string[];
+  reasonCode: string | null;
+};
+
+type ExactState = { contentDigest: string; evidenceRefs: string[] };
+
+function paths(record: MutationProvenanceRecord): Array<{ path: string; index: number }> {
+  const result: Array<{ path: string; index: number }> = [];
+  for (let index = 0; index < record.changes.length; index += 1) {
+    const decoded = decodeMutationRepoPath(record.changes[index]);
+    if (decoded) result.push({ path: decoded, index });
+  }
+  return result;
+}
+
+export function taskProvenanceResolver(projectRoot: string, manifest: TaskBaselineManifest) {
+  const ledger = readMutationProvenance(projectRoot, manifest.taskRunId);
+  const exact = new Map<string, ExactState>();
+  if (ledger.corruptions.length === 0) {
+    for (const record of ledger.records) {
+      for (const item of paths(record)) {
+        const change = record.changes[item.index];
+        const current = exact.get(item.path);
+        if (record.evidenceMode === "exact-runtime" && change.afterContentDigest) {
+          exact.set(item.path, {
+            contentDigest: change.afterContentDigest,
+            evidenceRefs: [...new Set([...(current?.evidenceRefs ?? []), record.evidenceRef])].slice(-64)
+          });
+        } else if (!(change.effect === "content-preserved" && current
+          && change.afterContentDigest === current.contentDigest)) {
+          exact.delete(item.path);
+        }
+      }
+    }
+  }
+  return (projectPath: string, currentContentDigest: string | null, baselineEntry?: TaskBaselineEntry): SourceProvenance => {
+    const state = exact.get(projectPath);
+    if (!state || !currentContentDigest || state.contentDigest !== currentContentDigest) {
+      return {
+        classification: "post-baseline-unattributed", evidence: "unavailable", baselineEvidenceRef: null,
+        mutationEvidenceRefs: [], reasonCode: ledger.corruptions.length ? "provenance-ledger-corrupt" : "provenance-evidence-unavailable"
+      };
+    }
+    return baselineEntry
+      ? { classification: "mixed", evidence: "exact", baselineEvidenceRef: taskBaselineManifestRef(manifest), mutationEvidenceRefs: state.evidenceRefs, reasonCode: null }
+      : { classification: "runtime-observed-agent", evidence: "exact", baselineEvidenceRef: null, mutationEvidenceRefs: state.evidenceRefs, reasonCode: null };
+  };
+}

package/packages/piagent-core/runtime/inspection/task-recovery-timeline.ts

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+
+import { redactSensitiveText } from "../../extensions/redaction-core.js";
+import { readTaskJournal, replayTaskCheckpoints, taskRecoveryDecision } from "../../extensions/task-journal.js";
+import { taskRunOpaqueRef } from "./task-run-index.ts";
+
+const MAX_EVENTS = 300;
+const KINDS: Record<string, { kind: string; state: string; title: string }> = {
+  "contract-written": { kind: "task-written", state: "observed", title: "Task Contract được ghi" },
+  "session-bound": { kind: "session-bound", state: "observed", title: "Session được bind vào task" },
+  checkpoint: { kind: "checkpoint", state: "observed", title: "Checkpoint được ghi" },
+  "task-control.pause-requested": { kind: "pause-requested", state: "requested", title: "Yêu cầu tạm dừng" },
+  "task-control.paused": { kind: "paused", state: "settled", title: "Task đã tạm dừng" },
+  "task-control.pause-cancelled": { kind: "pause-cancelled", state: "settled", title: "Yêu cầu tạm dừng đã hủy" },
+  "task-control.resume-requested": { kind: "resume-requested", state: "requested", title: "Yêu cầu tiếp tục" },
+  "task-control.resumed": { kind: "resumed", state: "settled", title: "Task đã tiếp tục" },
+  "task-control.resume-rejected": { kind: "resume-rejected", state: "failed", title: "Yêu cầu tiếp tục bị từ chối" },
+  "task-control.stop-requested": { kind: "stop-requested", state: "requested", title: "Yêu cầu dừng operation" },
+  "task-control.stop-settled": { kind: "stop-settled", state: "settled", title: "Operation đã dừng" },
+  "continuation-consumed": { kind: "continuation", state: "observed", title: "Continuation budget đã dùng" },
+  "digest-migrated": { kind: "digest-migrated", state: "observed", title: "Evidence digest đã migrate" }
+};
+
+type Task = { taskId: string; taskRunId: string; sessionId: string; trace: { outcome: string }; [key: string]: any };
+type Identity = { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string; taskRunId: string;
+  agentOperationId: null; toolCallId: null };
+
+function opaque(prefix: string, value: string): string {
+  return `${prefix}.${createHash("sha256").update(`piagent-webui-task-timeline-v1\0${value}`).digest("hex").slice(0, 48)}`;
+}
+
+function display(value: unknown, maximum = 160): string {
+  return redactSensitiveText(String(value ?? "")).text.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim().slice(0, maximum);
+}
+
+function eventDetail(event: any): string | null {
+  const data = event.data ?? {};
+  if (event.eventType === "checkpoint") return display(`${data.phase ?? "unknown"} · ${data.status ?? "unknown"}`) || null;
+  if (event.eventType.startsWith("task-control.")) return display(data.resultCode ?? data.reasonCode ?? "") || null;
+  if (event.eventType === "continuation-consumed") return display(`${data.classification ?? "continuation"} · ${data.action ?? "unknown"}`) || null;
+  if (event.eventType === "digest-migrated") return display(`${data.disposition ?? "migration"} · ${data.reasonCode ?? "unknown"}`) || null;
+  if (event.eventType === "contract-written") return display(data.outcome ?? "") || null;
+  return null;
+}
+
+function projectEvent(event: any, task: Task) {
+  const descriptor = KINDS[event.eventType]; if (!descriptor) return null;
+  const checkpointRef = event.eventType === "checkpoint" ? opaque("checkpoint", `${task.taskRunId}\0${event.checkpointId ?? "checkpoint"}`) : null;
+  return { eventRef: opaque("event", `${task.taskRunId}\0${event.sequence}\0${event.hash}`), evidenceRef: `journal.${event.hash}`,
+    sequence: event.sequence, recordedAt: event.recordedAt, ...descriptor, detail: eventDetail(event), checkpointRef };
+}
+
+function unavailable(identity: Identity, runRef: string, generatedAt: string, corruptions: number) {
+  return { schemaVersion: 1, version: "piagent-webui-task-timeline-v1", generatedAt, identity, runRef, state: "unavailable",
+    timelineRevision: null, continuity: { crashEvidence: "unknown", recoveryDecision: "unknown", latestCheckpointRef: null,
+      reasonCode: "task-journal-corrupt" }, events: [], page: { total: 0, returned: 0, truncated: false },
+    warnings: [{ code: "journal-corrupt", count: Math.max(1, corruptions), message: "Task journal could not be validated." }],
+    health: { state: "error", reasonCode: "task-journal-corrupt", message: "Timeline authority is unavailable." } };
+}
+
+export function projectTaskRecoveryTimeline(input: { cwd: string; task: Task; identity: Identity; generatedAt?: string }): Record<string, unknown> {
+  const generatedAt = input.generatedAt ?? new Date().toISOString(), runRef = taskRunOpaqueRef(input.task.taskRunId);
+  const journal = readTaskJournal(input.cwd, { taskRunId: input.task.taskRunId, sessionId: input.task.sessionId,
+    limit: 1000, maximumBytes: 32 * 1024 * 1024 });
+  if (journal.corruptions.length) return unavailable(structuredClone(input.identity), runRef, generatedAt, journal.corruptions.length);
+  const matching = journal.events.filter((event: any) => event.taskId === input.task.taskId && event.taskRunId === input.task.taskRunId
+    && event.sessionId === input.task.sessionId);
+  const projected = matching.map((event: any) => projectEvent(event, input.task)).filter(Boolean) as any[];
+  const events = projected.slice(-MAX_EVENTS), replay = replayTaskCheckpoints(input.cwd, input.task.taskRunId, input.task);
+  if (replay.corruptions.length) return unavailable(structuredClone(input.identity), runRef, generatedAt, replay.corruptions.length);
+  const recovery = taskRecoveryDecision(input.task, replay), latest = replay.checkpoints.at(-1);
+  const tailBytes = Number(journal.recoverableTailBytes ?? 0), warnings = [] as Array<{ code: string; count: number; message: string }>;
+  if (tailBytes > 0) warnings.push({ code: "recoverable-tail", count: tailBytes, message: "An incomplete journal tail indicates a possible interrupted write." });
+  else warnings.push({ code: "crash-not-observed", count: 1, message: "No explicit crash fact was recorded; crash state remains unknown." });
+  if (projected.length > events.length) warnings.push({ code: "timeline-truncated", count: projected.length - events.length,
+    message: `${projected.length - events.length} older timeline event(s) are outside this bounded page.` });
+  if (journal.inputTruncated) warnings.push({ code: "journal-input-truncated", count: Math.max(1, Math.min(100_000, journal.omittedEvents ?? 0)),
+    message: "Older task journal records are outside the bounded inspection window." });
+  const continuity = { crashEvidence: tailBytes > 0 ? "possible-interruption" : "unknown", recoveryDecision: recovery.decision,
+    latestCheckpointRef: latest ? opaque("checkpoint", `${input.task.taskRunId}\0${latest.checkpointId ?? "checkpoint"}`) : null,
+    reasonCode: tailBytes > 0 ? "incomplete-journal-tail" : "no-explicit-crash-evidence" };
+  const timelineRevision = `timeline.${createHash("sha256").update(JSON.stringify({ events, continuity, head: journal.head?.hash ?? null })).digest("hex")}`;
+  return { schemaVersion: 1, version: "piagent-webui-task-timeline-v1", generatedAt, identity: structuredClone(input.identity), runRef, state: "ready",
+    timelineRevision, continuity, events, page: { total: projected.length, returned: events.length,
+      truncated: projected.length > events.length || journal.inputTruncated }, warnings,
+    health: warnings.length ? { state: "degraded", reasonCode: "timeline-warning", message: "Some continuity facts remain unknown or omitted." }
+      : { state: "ok", reasonCode: null, message: null } };
+}

package/packages/piagent-core/runtime/inspection/task-run-index.ts

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+
+import { redactSensitiveText } from "../../extensions/redaction-core.js";
+import { activeSessionTask, listTaskContracts, taskStateMigrationStatus } from "../../extensions/task-state.js";
+
+const MAX_RUNS = 200;
+const TERMINAL = new Set(["completed", "blocked", "partial", "failed"]);
+
+type Identity = {
+  projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string | null; taskRunId: string | null;
+  agentOperationId: null; toolCallId: null;
+};
+
+function ref(prefix: string, value: string): string {
+  return `${prefix}.${createHash("sha256").update(`piagent-webui-task-index-v1\0${value}`).digest("hex").slice(0, 48)}`;
+}
+
+export function taskRunOpaqueRef(taskRunId: string): string { return ref("run", taskRunId); }
+export function resolveTaskRunRef(cwd: string, runRef: string): any | undefined {
+  return listTaskContracts(cwd).find((task: any) => taskRunOpaqueRef(task.taskRunId) === runRef);
+}
+
+function display(value: unknown, maximum: number): string {
+  return redactSensitiveText(String(value ?? "")).text.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim().slice(0, maximum);
+}
+
+function progress(task: any): { completed: number; total: number } {
+  const steps = Array.isArray(task.workPlan) ? task.workPlan.slice(0, 12) : [];
+  return { completed: steps.filter((step: any) => ["done", "skipped"].includes(step?.status)).length, total: steps.length };
+}
+
+function sessionLabel(task: any, isCurrentSession: boolean): string | null {
+  const value = display(task.sessionName, 160), rawId = String(task.sessionId ?? "");
+  if (!value) return null;
+  return rawId && value.includes(rawId) ? isCurrentSession ? "Session hiện tại" : null : value;
+}
+
+function run(task: any, currentSessionId: string, activeTaskRunId: string | null) {
+  const outcome = ["pending", "completed", "blocked", "partial", "failed"].includes(task.trace?.outcome) ? task.trace.outcome : "unknown";
+  const isCurrentSession = task.sessionId === currentSessionId;
+  const isActive = isCurrentSession && outcome === "pending" && task.taskRunId === activeTaskRunId;
+  return {
+    runRef: taskRunOpaqueRef(task.taskRunId), taskRef: ref("task", task.taskId), taskId: task.taskId, taskRunId: task.taskRunId,
+    summary: display(task.summary, 240), sessionLabel: sessionLabel(task, isCurrentSession),
+    outcome, terminal: TERMINAL.has(outcome), attempt: task.attempt, maxAttempts: task.maxAttempts,
+    changeMode: task.changeMode, riskLane: task.riskLane, createdAt: task.createdAt, updatedAt: task.updatedAt,
+    isCurrentSession, isActive, progress: progress(task)
+  };
+}
+
+function revision(runs: unknown[], total: number, corrupt: number, legacy: number): string {
+  const digest = createHash("sha256").update(JSON.stringify({ runs, total, corrupt, legacy })).digest("hex");
+  return `task-index.${digest}`;
+}
+
+export function projectTaskRunIndex(input: {
+  cwd: string; identity: Identity; currentSessionId: string; generatedAt?: string; limit?: number;
+}): Record<string, unknown> {
+  const generatedAt = input.generatedAt ?? new Date().toISOString();
+  try {
+    const tasks = listTaskContracts(input.cwd);
+    const status = taskStateMigrationStatus(input.cwd);
+    const active = activeSessionTask(input.cwd, input.currentSessionId);
+    const limit = Math.max(1, Math.min(MAX_RUNS, input.limit ?? 100));
+    const rows = tasks.map((task: any) => run(task, input.currentSessionId, active?.taskRunId ?? null))
+      .sort((left: any, right: any) => Number(right.isActive) - Number(left.isActive) || Date.parse(right.updatedAt) - Date.parse(left.updatedAt));
+    const returned = rows.slice(0, limit), warnings = [] as Array<{ code: string; count: number; message: string }>;
+    if (status.unreadable.length) warnings.push({ code: "corrupt-task-state", count: status.unreadable.length,
+      message: `${status.unreadable.length} task state record(s) could not be validated.` });
+    if (status.legacy) warnings.push({ code: "legacy-task-state", count: status.legacy,
+      message: `${status.legacy} legacy task state record(s) have reduced evidence.` });
+    if (rows.length > returned.length) warnings.push({ code: "task-index-truncated", count: rows.length - returned.length,
+      message: `${rows.length - returned.length} older task run(s) are outside this bounded page.` });
+    const activeRun = returned.find((item: any) => item.isActive);
+    return {
+      schemaVersion: 1, version: "piagent-webui-task-index-v1", generatedAt, identity: structuredClone(input.identity), state: "ready",
+      indexRevision: revision(returned, rows.length, status.unreadable.length, status.legacy), activeRunRef: activeRun?.runRef ?? null,
+      runs: returned, page: { total: rows.length, returned: returned.length, truncated: rows.length > returned.length }, warnings,
+      health: warnings.length ? { state: "degraded", reasonCode: "task-index-warning", message: "Some task history is unavailable or omitted." }
+        : { state: "ok", reasonCode: null, message: null }
+    };
+  } catch {
+    return { schemaVersion: 1, version: "piagent-webui-task-index-v1", generatedAt, identity: structuredClone(input.identity),
+      state: "unavailable", indexRevision: null, activeRunRef: null, runs: [], page: { total: 0, returned: 0, truncated: false },
+      warnings: [], health: { state: "unavailable", reasonCode: "task-index-unavailable", message: "Task history is unavailable." } };
+  }
+}