@piagent/platform 1.3.0 → 1.4.0

package/packages/piagent-webui/server/core-inspection-provider.ts

@@ -0,0 +1,403 @@
+import { randomBytes } from "node:crypto";
+
+import { redactSensitiveText } from "../../piagent-core/extensions/redaction-core.js";
+import { ReadModelNotFound, type SourceView, type StreamEvent, type WebUiReadModelProvider } from "./read-model-provider.ts";
+import { projectTranscript } from "./transcript-projection.ts";
+
+const CORE_ROOT = "../../piagent-core";
+
+type RuntimeEvent = { eventCursor: string; [key: string]: unknown };
+type EventReplay = {
+  state: "current" | "truncated" | "resync-required";
+  events: RuntimeEvent[];
+  nextCursor: string;
+  latestCursor: string;
+  reasonCode: string | null;
+};
+type EventStore = {
+  retention(): unknown;
+  currentCursor(): string | null;
+  resyncRequired(): boolean;
+  replay(after: string | null, limit: number): EventReplay;
+};
+
+async function loadCoreInspection() {
+  const [{ collectFileDiff }, { buildWebUiInspectionProjection }, { matchesProtectedPath }, reviewProjection, reviewStore, mutationProjection, revertProjection, openProjection, commitSummaryProjection, taskIndexProjection, taskTimelineProjection, recoveryHistoryProjection, handoffHistoryProjection, subagentTreeProjection, releaseMonitorProjection] = await Promise.all([
+    import(`${CORE_ROOT}/runtime/inspection/diff-projection.ts`),
+    import(`${CORE_ROOT}/runtime/inspection/webui-snapshot.ts`),
+    import(`${CORE_ROOT}/extensions/policy-core.js`),
+    import(`${CORE_ROOT}/runtime/inspection/review-state-projection.ts`),
+    import(`${CORE_ROOT}/runtime/inspection/review-state-store.ts`),
+    import(`${CORE_ROOT}/runtime/inspection/source-mutation-projection.ts`),
+    import(`${CORE_ROOT}/runtime/inspection/source-revert-projection.ts`),
+    import(`${CORE_ROOT}/runtime/inspection/source-open-target.ts`),
+    import(`${CORE_ROOT}/runtime/inspection/commit-summary-projection.ts`),
+    import(`${CORE_ROOT}/runtime/inspection/task-run-index.ts`),
+    import(`${CORE_ROOT}/runtime/inspection/task-recovery-timeline.ts`),
+    import(`${CORE_ROOT}/runtime/inspection/task-compaction-history.ts`),
+    import(`${CORE_ROOT}/runtime/inspection/task-handoff-history.ts`),
+    import(`${CORE_ROOT}/runtime/inspection/task-subagent-tree.ts`),
+    import("./benchmark-release-monitor.ts")
+  ]);
+  return { collectFileDiff, buildWebUiInspectionProjection, matchesProtectedPath, ...reviewProjection, ...reviewStore, ...mutationProjection, ...revertProjection, ...openProjection, ...commitSummaryProjection, ...taskIndexProjection, ...taskTimelineProjection, ...recoveryHistoryProjection, ...handoffHistoryProjection, ...subagentTreeProjection, ...releaseMonitorProjection };
+}
+
+export type CoreInspectionInput = {
+  cwd: string;
+  sessionId: string;
+  runtimeInstanceId: string;
+  eventStore: EventStore;
+  task?: () => unknown;
+  activityEvents?: () => unknown[];
+  currentActivity?: () => unknown[];
+  sessionEntries?: () => unknown[];
+  protectedPaths?: () => string[];
+  contextUsage?: () => { tokens: number | null; contextWindow: number; percent: number | null } | undefined;
+  model?: () => { provider?: unknown; id?: unknown; name?: unknown; reasoning?: unknown; input?: unknown; thinkingLevelMap?: unknown; contextWindow?: unknown; maxTokens?: unknown } | undefined;
+  thinkingLevel?: () => unknown;
+  queueProjection?: () => unknown;
+  modelCatalog?: () => unknown;
+  attachmentCapability?: () => { kinds: Array<"file" | "image">; mimeTypes: string[] };
+  approvalProjection?: () => { revision: string | null; summary: Record<string, unknown> };
+  approvalDetail?: (approvalRef: string) => unknown | null;
+  sourceMutationGuardAvailable?: () => boolean;
+  sourceOpenAvailable?: () => boolean;
+  lifecycleControl?: () => { state: "active" | "pause-requested" | "paused" | "terminal" | "unknown"; controlRevision: string | null;
+    dispatchBlocked: boolean; currentPhase: string; pauseEpoch: number; actions: { stop: boolean; pause: boolean; resume: boolean } };
+  chatControl?: () => { state: "unbound" | "ready" | "replacement-pending" | "shutdown"; liveness: "idle" | "running" | "unknown";
+    taskState: "none" | "active" | "pause-requested" | "paused" | "terminal" | "unknown"; identity: Record<string, any> | null; revisions: Record<string, any> | null;
+    heldCount: number; queueRevision: string | null };
+};
+
+export class CoreInspectionProvider implements WebUiReadModelProvider {
+  readonly #input: CoreInspectionInput;
+  readonly #listeners = new Set<(event: StreamEvent) => void>();
+  #cachedProjection: { at: number; value: any } | null = null;
+  #invalidationEpoch = 0;
+  readonly #diffCache = new Map<string, { at: number; value: unknown }>();
+  readonly #sourceRevertConfirmationKey = randomBytes(32);
+
+  constructor(input: CoreInspectionInput) { this.#input = input; }
+
+  invalidate(): void {
+    this.#invalidationEpoch += 1;
+    this.#cachedProjection = null;
+    this.#diffCache.clear();
+  }
+
+  async #projection() {
+    if (this.#cachedProjection && Date.now() - this.#cachedProjection.at <= 200) return this.#cachedProjection.value;
+    const projectionEpoch = this.#invalidationEpoch;
+    const { buildWebUiInspectionProjection } = await loadCoreInspection();
+    const retention = this.#input.eventStore.retention();
+    const value = await buildWebUiInspectionProjection({
+      cwd: this.#input.cwd, sessionId: this.#input.sessionId, runtimeInstanceId: this.#input.runtimeInstanceId,
+      task: this.#input.task?.(), events: this.#input.activityEvents?.() ?? [], current: this.#input.currentActivity?.() ?? [],
+      sessionEntries: this.#input.sessionEntries?.() ?? [], protectedPaths: this.#input.protectedPaths?.() ?? [],
+      contextUsage: this.#input.contextUsage?.(), model: this.#input.model?.(), thinkingLevel: this.#input.thinkingLevel?.(),
+      eventCursor: this.#input.eventStore.currentCursor(), resyncRequired: this.#input.eventStore.resyncRequired(), eventReplay: retention
+    });
+    const control = this.#input.chatControl?.();
+    if (control?.state === "ready" && control.identity && control.revisions && !this.#input.eventStore.resyncRequired()) {
+      const available = { available: true, reasonCode: null }, disabled = (reasonCode: string) => ({ available: false, reasonCode });
+      const lifecycle = this.#input.lifecycleControl?.(), terminal = control.taskState === "terminal";
+      const dispatchBlocked = terminal || lifecycle?.dispatchBlocked === true;
+      value.snapshot.identity = structuredClone(control.identity);
+      value.snapshot.capabilities.identity = structuredClone(control.identity);
+      for (const name of ["runtimeRevision", "taskRevision", "controlRevision", "sessionOptionRevision", "queueRevision"])
+        value.snapshot.revision[name] = control.revisions[name];
+      value.snapshot.capabilities.mode = "control-enabled";
+      value.snapshot.capabilities.capabilities["control.chat"] = {
+        status: "available", version: 1, reason: null, queuePersistence: "runtime-lifetime",
+        actions: { send: dispatchBlocked ? disabled(terminal ? "task-terminal" : "task-control-gate-closed") : available, hold: available, editHeld: available,
+          deleteHeld: available, dispatchHeld: dispatchBlocked ? disabled(terminal ? "task-terminal" : "task-control-gate-closed") : available,
+          interruptAndSend: dispatchBlocked ? disabled(terminal ? "task-terminal" : "task-control-gate-closed") : control.liveness === "running" ? available : disabled("agent-not-running") }
+      };
+      if (!terminal && this.#input.attachmentCapability) {
+        const attachment = this.#input.attachmentCapability();
+        value.snapshot.capabilities.capabilities.attachments = { status: "available", version: 1, reason: null,
+          kinds: attachment.kinds, mimeTypes: attachment.mimeTypes };
+        Object.assign(value.snapshot.capabilities.limits, { maxRequestBodyBytes: 11_250_000, maxAttachmentCount: 4,
+          maxAttachmentFileBytes: 8_388_608, maxAttachmentTotalBytes: 16_777_216 });
+      }
+      let modelCatalog: any;
+      try { modelCatalog = this.#input.modelCatalog?.(); }
+      catch { modelCatalog = null; }
+      if (modelCatalog?.state === "ready" && modelCatalog.identity?.sessionRef === control.identity.sessionRef
+        && modelCatalog.revision?.sessionOptionRevision === control.revisions.sessionOptionRevision) {
+        const idle = control.liveness === "idle" && !dispatchBlocked, optionAvailability = idle ? available : disabled(dispatchBlocked ? "task-control-gate-closed" : "agent-not-idle");
+        value.snapshot.capabilities.capabilities["control.sessionOptions"] = {
+          status: "available", version: 1, reason: null, effectScope: "session-and-user-default",
+          allowedLifecyclePoints: ["idle", "pre-fresh-task"], actions: { setModel: optionAvailability, setThinking: optionAvailability }
+        };
+      }
+      value.snapshot.session.operation = { liveness: control.liveness, operationRef: control.identity.agentOperationId,
+        hostPhase: control.liveness === "unknown" ? { state: "unknown", value: null, evidence: null, reasonCode: "bridge-liveness-unavailable" }
+          : { state: "known", value: control.liveness === "idle" ? "idle" : "other", evidence: "observed", reasonCode: null },
+        startedAt: null, settledAt: null, reasonCode: control.liveness === "unknown" ? "bridge-liveness-unavailable" : null };
+      value.snapshot.session.queue = { state: "known", hasPending: control.heldCount > 0, heldCount: control.heldCount,
+        revision: control.queueRevision ?? control.revisions.queueRevision, reasonCode: null };
+      if (lifecycle) {
+        value.snapshot.session.controlState = lifecycle.state;
+        if (value.snapshot.task) value.snapshot.task.controlState = lifecycle.state;
+        value.snapshot.revision.controlRevision = lifecycle.controlRevision ?? control.revisions.controlRevision;
+        const phases = ["idle", "input-preflight", "model", "tool-preflight", "waiting-approval", "tool", "retry", "compaction", "branch-summary", "direct-bash", "settling", "other", "unknown"];
+        const stopPhaseSupport = Object.fromEntries(phases.map((phase) => [phase, phase === lifecycle.currentPhase && lifecycle.actions.stop
+          ? { stop: "supported", reasonCode: null } : { stop: phase === lifecycle.currentPhase ? "unsupported" : "unknown", reasonCode: phase === lifecycle.currentPhase ? "no-current-operation" : "phase-not-observed" }]));
+        value.snapshot.capabilities.capabilities["control.lifecycle"] = { status: "available", version: 1, reason: null,
+          currentPhase: phases.includes(lifecycle.currentPhase) ? lifecycle.currentPhase : "unknown",
+          actions: { pause: lifecycle.actions.pause ? available : disabled(lifecycle.state === "terminal" ? "task-terminal" : `control-state-${lifecycle.state}`),
+            resume: lifecycle.actions.resume ? available : disabled(lifecycle.state === "active" ? "already-active" : `control-state-${lifecycle.state}`) }, stopPhaseSupport };
+        value.snapshot.capabilities.capabilities["control.resumeAndContinue"] = lifecycle.actions.resume && control.liveness === "idle"
+          && Boolean(control.revisions.queueRevision) ? { status: "available", version: 1, reason: null, delivery: "new-operation",
+            requires: ["control.lifecycle", "control.chat"] }
+          : { status: "unavailable", version: null, reason: { code: lifecycle.actions.resume ? "agent-not-idle" : `control-state-${lifecycle.state}`,
+            message: "Resume & Continue requires a paused task and an idle Pi session." } };
+      }
+      const approval = this.#input.approvalProjection?.();
+      if (approval?.revision) {
+        value.snapshot.revision.approvalRevision = approval.revision;
+        value.snapshot.approvals = structuredClone(approval.summary);
+        value.snapshot.session.approvalState = (approval.summary as any).state;
+        value.snapshot.capabilities.capabilities.approve = { status: "available", version: 1, reason: null,
+          decisions: ["allow", "deny"], arbitration: "first-valid-cas" };
+      }
+      if (control.identity.taskId && control.identity.taskRunId && control.revisions.taskRevision && value.snapshot.revision.workspaceRevision) {
+        const mutationGuardAvailable = this.#input.sourceMutationGuardAvailable?.() === true;
+        const chatSend = value.snapshot.capabilities.capabilities["control.chat"]?.status === "available"
+          && value.snapshot.capabilities.capabilities["control.chat"].actions.send.available;
+        value.snapshot.capabilities.capabilities.reviewActions = { status: "available", version: 1, reason: null, actions: {
+          reviewMark: available,
+          stage: control.liveness === "idle" && !terminal && mutationGuardAvailable ? available
+            : disabled(terminal ? "task-terminal" : control.liveness !== "idle" ? "agent-not-idle" : "mutation-guard-unavailable"),
+          unstage: control.liveness === "idle" && !terminal && mutationGuardAvailable ? available
+            : disabled(terminal ? "task-terminal" : control.liveness !== "idle" ? "agent-not-idle" : "mutation-guard-unavailable"),
+          revert: control.liveness === "idle" && !terminal && mutationGuardAvailable ? available
+            : disabled(terminal ? "task-terminal" : control.liveness !== "idle" ? "agent-not-idle" : "mutation-guard-unavailable"),
+          openInVsCode: this.#input.sourceOpenAvailable?.() === true ? available : disabled("vscode-cli-unavailable"),
+          generateCommitSummaryDeterministic: available,
+          generateCommitSummaryModel: chatSend && control.liveness === "idle" && !terminal ? available
+            : disabled(terminal ? "task-terminal" : control.liveness !== "idle" ? "agent-not-idle" : "chat-dispatch-unavailable")
+        } };
+      }
+    }
+    if (projectionEpoch === this.#invalidationEpoch) this.#cachedProjection = { at: Date.now(), value };
+    return value;
+  }
+
+  async snapshot(): Promise<unknown> { return (await this.#projection()).snapshot; }
+  async sourceChanges(view: SourceView): Promise<unknown> {
+    const source = (await this.#projection()).sourceViews;
+    return view === "working-tree" ? source.workingTree : source[view];
+  }
+  async activity(): Promise<unknown> { return (await this.#projection()).snapshot.activity; }
+  async logPreview(activityRef: string): Promise<unknown> {
+    const activity = (await this.#projection()).snapshot.activity;
+    const item = [...activity.running, ...activity.recent].find((candidate: Record<string, unknown>) => candidate.activityRef === activityRef);
+    if (!item) throw new ReadModelNotFound();
+    return { activityRef, state: "available", preview: String((item as Record<string, unknown>).preview ?? "").slice(0, 65_536), truncated: false, reasonCode: null };
+  }
+  async transcript(beforeCursor: string | null, limit: number): Promise<unknown> {
+    const snapshot = await this.snapshot() as any;
+    return projectTranscript({ identity: { projectRef: snapshot.identity.projectRef, runtimeInstanceId: snapshot.identity.runtimeInstanceId,
+      sessionRef: snapshot.identity.sessionRef, taskId: snapshot.identity.taskId, taskRunId: snapshot.identity.taskRunId, agentOperationId: null, toolCallId: null },
+      revision: { runtimeRevision: snapshot.revision.runtimeRevision, taskRevision: snapshot.revision.taskRevision,
+        controlRevision: snapshot.revision.controlRevision, workspaceRevision: snapshot.revision.workspaceRevision,
+        indexRevision: snapshot.revision.indexRevision, approvalRevision: snapshot.revision.approvalRevision,
+        sessionOptionRevision: snapshot.revision.sessionOptionRevision, queueRevision: snapshot.revision.queueRevision },
+      eventCursor: snapshot.revision.eventCursor, entries: this.#input.sessionEntries?.() ?? [], beforeCursor, limit,
+      generatedAt: snapshot.generatedAt });
+  }
+  async queue(): Promise<unknown> {
+    if (!this.#input.queueProjection) throw new ReadModelNotFound();
+    return this.#input.queueProjection();
+  }
+  async modelCatalog(): Promise<unknown> {
+    if (!this.#input.modelCatalog) throw new ReadModelNotFound();
+    return this.#input.modelCatalog();
+  }
+  async approval(approvalRef: string): Promise<unknown> {
+    const value = this.#input.approvalDetail?.(approvalRef); if (!value) throw new ReadModelNotFound(); return value;
+  }
+  async diff(view: SourceView, fileRef: string): Promise<unknown> {
+    const cacheKey = `${view}:${fileRef}`;
+    const cached = this.#diffCache.get(cacheKey);
+    if (cached && Date.now() - cached.at <= 200) return cached.value;
+    const { collectFileDiff, matchesProtectedPath } = await loadCoreInspection();
+    const projection = await this.#projection();
+    const source = view === "working-tree" ? projection.sourceViews.workingTree : projection.sourceViews[view];
+    const file = source?.files.find((candidate: any) => candidate.fileRef === fileRef) as Record<string, any> | undefined;
+    if (!source || !file) throw new ReadModelNotFound();
+    const identity = projection.snapshot.identity;
+    const protectedPaths = this.#input.protectedPaths?.() ?? [];
+    const value = await collectFileDiff({
+      cwd: this.#input.cwd, identity, sourceView: source, fileRef,
+      precondition: { expectedViewRevision: source.viewRevision, expectedFileRevision: file.fileRevision,
+        expectedBaseDigest: file.baseDigest ?? null, expectedCurrentDigest: file.currentDigest ?? null },
+      taskRevision: projection.snapshot.revision.taskRevision,
+      redactLine: (text: string) => redactSensitiveText(text),
+      revalidationMode: "selected-file",
+      selectedRepoPaths: file.pathDisplay === "exact-safe" ? [file.oldPath, file.path].filter((value: unknown): value is string => typeof value === "string") : undefined,
+      isProtectedPath: (_root: string, repoPath: string) => Boolean(matchesProtectedPath(repoPath, protectedPaths))
+    });
+    this.#diffCache.set(cacheKey, { at: Date.now(), value });
+    if (this.#diffCache.size > 128) this.#diffCache.delete(this.#diffCache.keys().next().value as string);
+    return value;
+  }
+
+  async review(view: SourceView, fileRef: string): Promise<unknown> {
+    // Review is authority-bearing evidence. Never reuse the short UI projection
+    // cache when deriving its exact Git/task preimage.
+    this.invalidate();
+    const projection = await this.#projection(), snapshot = projection.snapshot;
+    const identity = { ...snapshot.identity, agentOperationId: null, toolCallId: null };
+    if (!identity.taskId || !identity.taskRunId || !snapshot.revision.taskRevision || !snapshot.revision.workspaceRevision) throw new ReadModelNotFound();
+    const diff = await this.diff(view, fileRef) as any;
+    const { deriveReviewTarget, projectReviewState, readReviewEvidence } = await loadCoreInspection();
+    const target = deriveReviewTarget({ diff, taskId: identity.taskId, taskRunId: identity.taskRunId,
+      taskRevision: snapshot.revision.taskRevision, workspaceRevision: snapshot.revision.workspaceRevision,
+      indexRevision: snapshot.revision.indexRevision });
+    const evidence = readReviewEvidence(this.#input.cwd, identity.taskRunId);
+    return projectReviewState({ identity, target, records: evidence.records, corruptions: evidence.corruptions,
+      unavailableReason: diff.availability?.reasonCode ?? diff.fallback?.reasonCode ?? "review-target-unavailable" });
+  }
+
+  async #sourceMutation(action: "source.stage" | "source.unstage", fileRef: string) {
+    this.invalidate();
+    const projection = await this.#projection(), snapshot = projection.snapshot;
+    const identity = { ...snapshot.identity, agentOperationId: null, toolCallId: null };
+    if (!identity.taskId || !identity.taskRunId || !snapshot.revision.taskRevision || !snapshot.revision.workspaceRevision || !snapshot.revision.indexRevision)
+      throw new ReadModelNotFound();
+    const view: SourceView = action === "source.stage" ? "working-tree" : "staged";
+    const source = view === "working-tree" ? projection.sourceViews.workingTree : projection.sourceViews.staged;
+    if (!source?.files.some((file: any) => file.fileRef === fileRef)) throw new ReadModelNotFound();
+    const diff = await this.diff(view, fileRef) as any;
+    const { collectSourceMutationPreview, matchesProtectedPath } = await loadCoreInspection();
+    const protectedPaths = this.#input.protectedPaths?.() ?? [];
+    return collectSourceMutationPreview({ cwd: this.#input.cwd, identity, action, sourceView: source, diff,
+      taskRevision: snapshot.revision.taskRevision, workspaceRevision: snapshot.revision.workspaceRevision,
+      indexRevision: snapshot.revision.indexRevision,
+      guardAvailable: this.#input.sourceMutationGuardAvailable?.() === true,
+      isProtectedPath: (_root: string, repoPath: string) => Boolean(matchesProtectedPath(repoPath, protectedPaths)) });
+  }
+
+  async sourceMutation(action: "source.stage" | "source.unstage", fileRef: string): Promise<unknown> {
+    return (await this.#sourceMutation(action, fileRef)).projection;
+  }
+
+  async sourceMutationAuthority(action: "source.stage" | "source.unstage", fileRef: string) {
+    return this.#sourceMutation(action, fileRef);
+  }
+
+  async #sourceRevert(fileRef: string, hunkRef: string | null) {
+    this.invalidate();
+    const projection = await this.#projection(), snapshot = projection.snapshot;
+    const identity = { ...snapshot.identity, agentOperationId: null, toolCallId: null };
+    if (!identity.taskId || !identity.taskRunId || !snapshot.revision.taskRevision || !snapshot.revision.workspaceRevision || !snapshot.revision.indexRevision)
+      throw new ReadModelNotFound();
+    const source = projection.sourceViews.workingTree, taskView = projection.sourceViews.task ?? null;
+    if (!source?.files.some((file: any) => file.fileRef === fileRef)) throw new ReadModelNotFound();
+    const diff = await this.diff("working-tree", fileRef) as any;
+    const { collectSourceRevertPreview, matchesProtectedPath } = await loadCoreInspection();
+    const protectedPaths = this.#input.protectedPaths?.() ?? [];
+    return collectSourceRevertPreview({ cwd: this.#input.cwd, identity, sourceView: source, taskView, diff,
+      taskRevision: snapshot.revision.taskRevision, workspaceRevision: snapshot.revision.workspaceRevision,
+      indexRevision: snapshot.revision.indexRevision, selectedHunkRefs: hunkRef ? [hunkRef] : [],
+      confirmationKey: this.#sourceRevertConfirmationKey,
+      guardAvailable: this.#input.sourceMutationGuardAvailable?.() === true,
+      isProtectedPath: (_root: string, repoPath: string) => Boolean(matchesProtectedPath(repoPath, protectedPaths)) });
+  }
+
+  async sourceRevert(fileRef: string, hunkRef: string | null): Promise<unknown> {
+    return (await this.#sourceRevert(fileRef, hunkRef)).projection;
+  }
+
+  async sourceRevertAuthority(fileRef: string, hunkRefs: string[]) {
+    if (hunkRefs.length > 1) throw new ReadModelNotFound();
+    return this.#sourceRevert(fileRef, hunkRefs[0] ?? null);
+  }
+
+  async sourceOpenAuthority(fileRef: string) {
+    this.invalidate(); const projection = await this.#projection(), snapshot = projection.snapshot;
+    const identity = { ...snapshot.identity, agentOperationId: null, toolCallId: null };
+    if (!identity.taskId || !identity.taskRunId || !snapshot.revision.taskRevision || !snapshot.revision.workspaceRevision) return null;
+    const { resolveSourceOpenTarget, matchesProtectedPath } = await loadCoreInspection(), protectedPaths = this.#input.protectedPaths?.() ?? [];
+    return resolveSourceOpenTarget({ cwd: this.#input.cwd, identity, sourceView: projection.sourceViews.workingTree, fileRef,
+      taskRevision: snapshot.revision.taskRevision, workspaceRevision: snapshot.revision.workspaceRevision,
+      isProtectedPath: (_root: string, repoPath: string) => Boolean(matchesProtectedPath(repoPath, protectedPaths)) });
+  }
+
+  async commitSummary(): Promise<unknown> {
+    this.invalidate(); const projection = await this.#projection(), snapshot = projection.snapshot;
+    const identity = { ...snapshot.identity, agentOperationId: null, toolCallId: null };
+    if (!identity.taskId || !identity.taskRunId || !snapshot.revision.taskRevision || !snapshot.revision.indexRevision) throw new ReadModelNotFound();
+    const { projectDeterministicCommitSummary } = await loadCoreInspection();
+    return projectDeterministicCommitSummary({ identity, sourceView: projection.sourceViews.staged,
+      taskRevision: snapshot.revision.taskRevision, indexRevision: snapshot.revision.indexRevision });
+  }
+
+  async taskIndex(): Promise<unknown> {
+    this.invalidate(); const snapshot = await this.snapshot() as any;
+    const identity = { ...snapshot.identity, agentOperationId: null, toolCallId: null };
+    const { projectTaskRunIndex } = await loadCoreInspection();
+    return projectTaskRunIndex({ cwd: this.#input.cwd, identity, currentSessionId: this.#input.sessionId });
+  }
+
+  async taskTimeline(runRef: string): Promise<unknown> {
+    this.invalidate(); const snapshot = await this.snapshot() as any;
+    const { projectTaskRecoveryTimeline, resolveTaskRunRef } = await loadCoreInspection();
+    const task = resolveTaskRunRef(this.#input.cwd, runRef); if (!task) throw new ReadModelNotFound();
+    const identity = { ...snapshot.identity, taskId: task.taskId, taskRunId: task.taskRunId, agentOperationId: null, toolCallId: null };
+    return projectTaskRecoveryTimeline({ cwd: this.#input.cwd, identity, task });
+  }
+
+  async recoveryHistory(runRef: string): Promise<unknown> {
+    this.invalidate(); const snapshot = await this.snapshot() as any;
+    const { projectTaskCompactionHistory, resolveTaskRunRef } = await loadCoreInspection();
+    const task = resolveTaskRunRef(this.#input.cwd, runRef); if (!task) throw new ReadModelNotFound();
+    const identity = { ...snapshot.identity, taskId: task.taskId, taskRunId: task.taskRunId, agentOperationId: null, toolCallId: null };
+    return projectTaskCompactionHistory({ cwd: this.#input.cwd, identity, task });
+  }
+
+  async handoffHistory(runRef: string): Promise<unknown> {
+    this.invalidate(); const snapshot = await this.snapshot() as any;
+    const { projectTaskHandoffHistory, resolveTaskRunRef } = await loadCoreInspection();
+    const task = resolveTaskRunRef(this.#input.cwd, runRef); if (!task) throw new ReadModelNotFound();
+    const identity = { ...snapshot.identity, taskId: task.taskId, taskRunId: task.taskRunId, agentOperationId: null, toolCallId: null };
+    return projectTaskHandoffHistory({ cwd: this.#input.cwd, identity, task });
+  }
+
+  async subagentTree(runRef: string): Promise<unknown> {
+    this.invalidate(); const snapshot = await this.snapshot() as any;
+    const { projectTaskSubagentTree, resolveTaskRunRef } = await loadCoreInspection();
+    const task = resolveTaskRunRef(this.#input.cwd, runRef); if (!task) throw new ReadModelNotFound();
+    const identity = { ...snapshot.identity, taskId: task.taskId, taskRunId: task.taskRunId, agentOperationId: null, toolCallId: null };
+    return projectTaskSubagentTree({ cwd: this.#input.cwd, identity, task });
+  }
+
+  async releaseMonitor(): Promise<unknown> {
+    const snapshot = await this.snapshot() as any;
+    const identity = { ...snapshot.identity, agentOperationId: null, toolCallId: null };
+    const { projectBenchmarkReleaseMonitor } = await loadCoreInspection();
+    return projectBenchmarkReleaseMonitor({ cwd: this.#input.cwd, identity });
+  }
+
+  async canonicalRevisions(): Promise<Record<string, string | null>> {
+    this.invalidate(); return structuredClone((await this.#projection()).snapshot.revision);
+  }
+
+  replay(after: string | null, limit: number) {
+    const replay = this.#input.eventStore.replay(after, limit);
+    if (replay.state !== "current") {
+      this.#cachedProjection = null;
+      this.#diffCache.clear();
+    }
+    return { ...replay, events: replay.events.map((event) => ({ cursor: event.eventCursor, value: event })) };
+  }
+  subscribe(listener: (event: StreamEvent) => void): () => void { this.#listeners.add(listener); return () => this.#listeners.delete(listener); }
+  publishObserved(event: RuntimeEvent): void {
+    this.invalidate();
+    const item = { cursor: event.eventCursor, value: event };
+    for (const listener of this.#listeners) listener(item);
+  }
+}

package/packages/piagent-webui/server/gateway-websocket.ts

@@ -0,0 +1,143 @@
+import type { IncomingMessage, Server } from "node:http";
+import { WebSocket, WebSocketServer } from "ws";
+
+import type { SessionAuthority } from "./session-auth.ts";
+
+const FRAME_LIMIT = 70_000;
+const CLIENT_LIMIT = 8;
+const BACKPRESSURE_LIMIT = 512 * 1024;
+const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+const REQUEST_ID = /^[A-Za-z0-9_-]{16,96}$/;
+
+type GatewayProtocolEvent = {
+  sequence: number;
+  [key: string]: unknown;
+};
+export type GatewayRequest = { requestId: string; method: "gateway.health" | "sessions.list" | "sessions.get" | "sessions.command"; params: Record<string, unknown> };
+export type GatewayProtocolHandler = {
+  capabilities(): unknown;
+  execute(request: GatewayRequest): Promise<unknown>;
+  events: {
+    readonly stateVersion: number;
+    subscribe(listener: (event: GatewayProtocolEvent) => void): () => void;
+    replay(after: number | null): { state: "current" | "resync-required"; events: GatewayProtocolEvent[]; earliestSequence: number; currentSequence: number };
+  };
+};
+
+function exactKeys(value: Record<string, unknown>, keys: string[]): boolean {
+  return Object.keys(value).length === keys.length && Object.keys(value).every((key) => keys.includes(key));
+}
+
+function record(value: unknown): value is Record<string, unknown> { return Boolean(value) && typeof value === "object" && !Array.isArray(value); }
+function nullableRef(value: unknown): boolean { return value === null || typeof value === "string" && REF.test(value); }
+
+function parseConnect(value: unknown): { lastEventSequence: number | null } | null {
+  if (!record(value) || !exactKeys(value, ["schemaVersion", "version", "messageType", "clientRef", "minimumProtocol", "maximumProtocol", "lastEventSequence", "catalogRevision"])) return null;
+  if (value.schemaVersion !== 1 || value.version !== "piagent-gateway-protocol-v1" || value.messageType !== "connect"
+    || typeof value.clientRef !== "string" || !REF.test(value.clientRef) || value.minimumProtocol !== 1 || value.maximumProtocol !== 1
+    || !nullableRef(value.catalogRevision)) return null;
+  const sequence = value.lastEventSequence;
+  if (sequence !== null && (!Number.isSafeInteger(sequence) || Number(sequence) < 0)) return null;
+  return { lastEventSequence: sequence as number | null };
+}
+
+function parseRequest(value: unknown): GatewayRequest | null {
+  if (!record(value) || !exactKeys(value, ["schemaVersion", "version", "messageType", "requestId", "method", "params"]) || value.schemaVersion !== 1
+    || value.version !== "piagent-gateway-protocol-v1" || value.messageType !== "request" || typeof value.requestId !== "string"
+    || !REQUEST_ID.test(value.requestId) || !["gateway.health", "sessions.list", "sessions.get", "sessions.command"].includes(String(value.method))
+    || !record(value.params)) return null;
+  const params = value.params;
+  if (value.method === "gateway.health" && !exactKeys(params, [])) return null;
+  if (value.method === "sessions.get" && (!exactKeys(params, ["sessionRef"]) || typeof params.sessionRef !== "string" || !REF.test(params.sessionRef))) return null;
+  if (value.method === "sessions.command" && (!exactKeys(params, ["command"]) || !record(params.command))) return null;
+  if (value.method === "sessions.list") {
+    if (!exactKeys(params, ["cursor", "limit", "filter", "query", "projectRef"]) || !nullableRef(params.cursor) || !nullableRef(params.projectRef)
+      || !Number.isInteger(params.limit) || Number(params.limit) < 1 || Number(params.limit) > 200
+      || !["active", "archived", "all"].includes(String(params.filter))
+      || !(params.query === null || typeof params.query === "string" && params.query.length >= 1 && params.query.length <= 200
+        && !/[\u0000-\u001f\u007f]/.test(params.query))) return null;
+  }
+  return value as GatewayRequest;
+}
+
+function send(socket: WebSocket, value: unknown): void {
+  if (socket.readyState !== WebSocket.OPEN) return;
+  if (socket.bufferedAmount > BACKPRESSURE_LIMIT) { socket.close(1013, "backpressure"); return; }
+  const body = JSON.stringify(value);
+  if (Buffer.byteLength(body) > FRAME_LIMIT) { socket.close(1009, "frame-limit"); return; }
+  socket.send(body);
+}
+
+function response(request: GatewayRequest, stateVersion: number, result: unknown) {
+  return { schemaVersion: 1, version: "piagent-gateway-protocol-v1", messageType: "response", requestId: request.requestId,
+    method: request.method, ok: true, stateVersion, result, error: null };
+}
+
+function errorResponse(request: GatewayRequest, stateVersion: number, error: unknown) {
+  const failure = error && typeof error === "object" && "code" in error && typeof error.code === "string"
+    ? { code: error.code, retryable: "retryable" in error && error.retryable === true } : { code: "gateway-request-failed", retryable: true };
+  return { schemaVersion: 1, version: "piagent-gateway-protocol-v1", messageType: "response", requestId: request.requestId,
+    method: request.method, ok: false, stateVersion, result: null,
+    error: { code: failure.code, message: failure.code, retryable: failure.retryable } };
+}
+
+export function attachGatewayWebSocket(options: {
+  server: Server;
+  origin(): string;
+  authority: SessionAuthority;
+  protocol: GatewayProtocolHandler;
+}): { close(): Promise<void> } {
+  const sockets = new Set<WebSocket>();
+  const webSockets = new WebSocketServer({ noServer: true, clientTracking: false, perMessageDeflate: false, maxPayload: FRAME_LIMIT });
+  const reject = (socket: import("node:stream").Duplex, status: number) => socket.end(`HTTP/1.1 ${status} Rejected\r\nConnection: close\r\n\r\n`);
+  const upgrade = (request: IncomingMessage, socket: import("node:stream").Duplex, head: Buffer) => {
+    let url: URL;
+    try { url = new URL(request.url ?? "", options.origin()); } catch { reject(socket, 400); return; }
+    const protocol = String(request.headers["sec-websocket-protocol"] ?? "").split(",").map((item) => item.trim());
+    if (request.headers.origin !== options.origin() || request.headers.host !== options.origin().slice("http://".length)
+      || url.pathname !== "/api/v1/gateway" || url.search || !options.authority.authenticate(request)
+      || !protocol.includes("piagent.gateway.v1") || sockets.size >= CLIENT_LIMIT) { reject(socket, 403); return; }
+    webSockets.handleUpgrade(request, socket, head, (client) => webSockets.emit("connection", client, request));
+  };
+  options.server.on("upgrade", upgrade);
+  webSockets.on("connection", (socket) => {
+    sockets.add(socket); let connected = false, unsubscribe: (() => void) | null = null, chain = Promise.resolve();
+    const timeout = setTimeout(() => socket.close(1008, "connect-timeout"), 5_000);
+    socket.on("message", (data, binary) => {
+      if (binary) { socket.close(1003, "text-only"); return; }
+      chain = chain.then(async () => {
+        let value: unknown;
+        try { value = JSON.parse(data.toString()); } catch { socket.close(1007, "invalid-json"); return; }
+        if (!connected) {
+          const connect = parseConnect(value);
+          if (!connect) { socket.close(1008, "invalid-connect"); return; }
+          connected = true; clearTimeout(timeout);
+          const pending: GatewayProtocolEvent[] = [], seen = new Set<number>(); let replaying = true;
+          unsubscribe = options.protocol.events.subscribe((event) => replaying ? pending.push(event) : send(socket, event));
+          send(socket, { schemaVersion: 1, version: "piagent-gateway-protocol-v1", messageType: "hello", capabilities: options.protocol.capabilities() });
+          const replay = options.protocol.events.replay(connect.lastEventSequence);
+          if (replay.state === "resync-required") send(socket, {
+            schemaVersion: 1, version: "piagent-gateway-protocol-v1", messageType: "event", sequence: replay.currentSequence,
+            stateVersion: replay.currentSequence, generatedAt: new Date().toISOString(), kind: "resync.required",
+            payload: { reasonCode: "gateway-event-cursor-gap", earliestSequence: replay.earliestSequence, currentSequence: replay.currentSequence }
+          });
+          else for (const event of replay.events) { seen.add(event.sequence); send(socket, event); }
+          replaying = false;
+          for (const event of pending) if (!seen.has(event.sequence)) send(socket, event);
+          return;
+        }
+        const request = parseRequest(value);
+        if (!request) { socket.close(1008, "invalid-request"); return; }
+        try { send(socket, response(request, options.protocol.events.stateVersion, await options.protocol.execute(request))); }
+        catch (error) { send(socket, errorResponse(request, options.protocol.events.stateVersion, error)); }
+      }).catch(() => socket.close(1011, "gateway-failure"));
+    });
+    socket.once("close", () => { clearTimeout(timeout); unsubscribe?.(); sockets.delete(socket); });
+    socket.once("error", () => socket.terminate());
+  });
+  return { close: async () => {
+    options.server.off("upgrade", upgrade);
+    for (const socket of sockets) socket.terminate();
+    await new Promise<void>((resolve) => webSockets.close(() => resolve()));
+  } };
+}

package/packages/piagent-webui/server/http-security.ts

@@ -0,0 +1,27 @@
+import type { ServerResponse } from "node:http";
+
+export const SECURITY_HEADERS = Object.freeze({
+  "Cross-Origin-Opener-Policy": "same-origin",
+  "Permissions-Policy": "camera=(), microphone=(), geolocation=(), payment=(), usb=()",
+  "Referrer-Policy": "no-referrer",
+  "X-Content-Type-Options": "nosniff",
+  "X-Frame-Options": "DENY"
+});
+
+export function applySecurityHeaders(response: ServerResponse, styleNonce: string): void {
+  for (const [name, value] of Object.entries(SECURITY_HEADERS)) response.setHeader(name, value);
+  response.setHeader("Content-Security-Policy", `default-src 'self'; base-uri 'none'; object-src 'none'; frame-ancestors 'none'; img-src 'self' data:; style-src 'self'; style-src-elem 'self' 'nonce-${styleNonce}'; style-src-attr 'unsafe-inline'; script-src 'self'; connect-src 'self'`);
+}
+
+export function jsonResponse(response: ServerResponse, status: number, value: unknown): void {
+  const body = Buffer.from(JSON.stringify(value));
+  response.statusCode = status;
+  response.setHeader("Cache-Control", "no-store");
+  response.setHeader("Content-Type", "application/json; charset=utf-8");
+  response.setHeader("Content-Length", body.length);
+  response.end(body);
+}
+
+export function errorResponse(response: ServerResponse, status: number, code: string): void {
+  jsonResponse(response, status, { error: { code } });
+}