@piagent/platform 1.3.1 → 1.4.0

package/packages/piagent-core/runtime/hooks/tool-result-metadata.ts

@@ -0,0 +1,13 @@
+export function patchLineStats(details: unknown): { additions?: number; deletions?: number } {
+  if (!details || typeof details !== "object") return {};
+  const patch = (details as Record<string, unknown>).patch;
+  if (typeof patch !== "string" || !patch.trim()) return {};
+  let additions = 0;
+  let deletions = 0;
+  for (const line of patch.split(/\r?\n/)) {
+    if (line.startsWith("+++ ") || line.startsWith("--- ")) continue;
+    if (line.startsWith("+")) additions += 1;
+    else if (line.startsWith("-")) deletions += 1;
+  }
+  return { additions, deletions };
+}

package/packages/piagent-core/runtime/input/chat-images.ts

@@ -32,7 +32,7 @@ function escapeRegExp(input: string): string {
   return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-function supportedImageMimeType(bytes: Buffer): string | undefined {
+export function supportedChatImageMimeType(bytes: Buffer): string | undefined {
   if (
     bytes.length >= 24
     && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
@@ -236,7 +236,7 @@ export function readChatImage(
       offset += read;
     }
     if (offset !== bytes.length) return { status: "error", reason: "file changed while it was being read" };
-    const mimeType = supportedImageMimeType(bytes);
+    const mimeType = supportedChatImageMimeType(bytes);
     if (!mimeType) return { status: "error", reason: "file bytes are not a supported image" };
     return { status: "ok", absolutePath: canonicalPath, bytes, mimeType };
   } finally {

package/packages/piagent-core/runtime/inspection/activity-event-adapter.ts

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+
+import { redactSensitiveText } from "../../extensions/redaction-core.js";
+import type { ActivityInspectorEvent } from "../product/activity-inspector.ts";
+import type { RuntimeEventDraft, RuntimeEventRevision } from "./runtime-event-store.ts";
+
+export type RuntimeEventIdentity = {
+  projectRef: string;
+  runtimeInstanceId: string;
+  sessionRef: string;
+  taskId: string | null;
+  taskRunId: string | null;
+  agentOperationId?: string | null;
+};
+export type ActivityEventAdapterInput = {
+  event: ActivityInspectorEvent & Record<string, unknown>;
+  identity: RuntimeEventIdentity;
+  revision: RuntimeEventRevision;
+};
+
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+function hash(value: string): string { return createHash("sha256").update(value).digest("hex"); }
+function opaque(prefix: string, value: unknown): string { return `${prefix}.${hash(String(value ?? "unknown"))}`; }
+function digest(value: unknown): string | null {
+  const candidate = String(value ?? "");
+  return /^[a-f0-9]{64}$/.test(candidate) ? `sha256:${candidate}` : /^sha256:[a-f0-9]{64}$/.test(candidate) ? candidate : null;
+}
+function safeText(value: unknown, maximum = 4000): { text: string; redacted: number } {
+  const source = String(value ?? "");
+  const redaction = redactSensitiveText(source);
+  const text = redaction.text.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim().slice(0, maximum);
+  return { text, redacted: redaction.redacted ? 1 : 0 };
+}
+function correlation() {
+  return { commandId: null, messageRequestId: null, replacementId: null, approvalRequestId: null, causationEventId: null, idempotencyKeyDigest: null };
+}
+function base(identity: RuntimeEventIdentity, revision: RuntimeEventRevision, sourceObservedAt: string): Omit<RuntimeEventDraft, "kind" | "payload" | "evidence" | "redaction"> {
+  return { sourceObservedAt, projectRef: identity.projectRef, runtimeInstanceId: identity.runtimeInstanceId, sessionRef: identity.sessionRef,
+    taskId: identity.taskId, taskRunId: identity.taskRunId, agentOperationId: null, turnIndex: null, messageRef: null, toolCallId: null,
+    revision, correlation: correlation() };
+}
+
+export function adaptActivityTelemetryEvent(input: ActivityEventAdapterInput): RuntimeEventDraft | null {
+  const event = input.event, observedAt = String(event.recordedAt ?? "");
+  if (!TIMESTAMP.test(observedAt)) return null;
+  const eventName = String(event.event ?? "");
+  if (!["tool_call", "tool_result", "tool_decision"].includes(eventName)) return null;
+  if (eventName === "tool_decision" && event.decision !== "blocked") return null;
+  const toolName = safeText(event.toolName ?? "unknown", 80).text.replace(/[^A-Za-z0-9._:@~-]/g, "-") || "unknown";
+  const rawToolCall = String(event.toolCallId ?? event.activityId ?? `${observedAt}:${toolName}`);
+  const hasOperation = typeof input.identity.agentOperationId === "string" && input.identity.agentOperationId.length > 0;
+  const operationRef = hasOperation ? opaque("operation", input.identity.agentOperationId) : null;
+  const toolCallRef = hasOperation ? opaque("tool", rawToolCall) : null;
+  const activityType = hasOperation ? "tool" : ["bash", "shell", "exec"].includes(toolName) ? "command" : "other";
+  const failed = eventName === "tool_result" && (event.isError === true || typeof event.exitCode === "number" && event.exitCode !== 0);
+  const blocked = eventName === "tool_decision";
+  const state = eventName === "tool_call" ? "started" : blocked ? "blocked" : failed ? "failed" : "finished";
+  const kind = `activity.${state}`;
+  const previewValue = blocked ? event.reason : event.command ?? event.targetPath ?? event.toolName;
+  const preview = safeText(previewValue, 4000);
+  const storedRedactions = typeof event.sensitiveValuesRedacted === "number" && Number.isInteger(event.sensitiveValuesRedacted)
+    ? Math.max(0, Math.min(10_000, event.sensitiveValuesRedacted)) : 0;
+  const reasonCode = blocked ? "policy-blocked" : failed ? "tool-result-failed" : null;
+  return {
+    ...base(input.identity, input.revision, observedAt), agentOperationId: operationRef, toolCallId: toolCallRef,
+    kind, evidence: "derived",
+    payload: {
+      state, activityType, activityRef: opaque("activity", `${input.identity.runtimeInstanceId}\0${input.identity.sessionRef}\0${rawToolCall}`),
+      toolName, inputDigest: digest((event as any).inputHash), outputDigest: digest((event as any).outputHash),
+      preview: preview.text || null, previewKind: preview.text ? "summary" : "none",
+      outputBytes: Number.isInteger((event as any).outputBytes) && (event as any).outputBytes >= 0 ? Math.min(1_000_000_000, (event as any).outputBytes) : null,
+      outputLines: Number.isInteger((event as any).outputLines) && (event as any).outputLines >= 0 ? Math.min(1_000_000_000, (event as any).outputLines) : null,
+      exitCode: typeof event.exitCode === "number" && Number.isInteger(event.exitCode) ? event.exitCode : null,
+      isError: eventName === "tool_result" ? failed : null,
+      affectedFileRefs: [], criterionIds: [], verifierAttemptIds: [], reasonCode
+    },
+    redaction: { applied: preview.redacted + storedRedactions > 0, valuesRemoved: Math.min(10_000, preview.redacted + storedRedactions), truncated: String(previewValue ?? "").length > 4000 }
+  };
+}
+
+export function runtimeStartedEventDraft(input: {
+  identity: Pick<RuntimeEventIdentity, "projectRef" | "runtimeInstanceId" | "sessionRef">;
+  revision: RuntimeEventRevision;
+  sourceObservedAt: string;
+  buildRef: string;
+  capabilitySnapshotRef: string;
+}): RuntimeEventDraft {
+  return {
+    ...base({ ...input.identity, taskId: null, taskRunId: null }, input.revision, input.sourceObservedAt),
+    kind: "runtime.started", evidence: "observed",
+    payload: { connectionState: "connected", operationState: "idle", buildRef: input.buildRef, capabilitySnapshotRef: input.capabilitySnapshotRef, reasonCode: null },
+    redaction: { applied: false, valuesRemoved: 0, truncated: false }
+  };
+}

package/packages/piagent-core/runtime/inspection/approval-broker.ts

@@ -0,0 +1,318 @@
+import { createHmac, randomBytes, randomUUID } from "node:crypto";
+import path from "node:path";
+
+import { redactSensitiveText } from "../../extensions/redaction-core.js";
+
+const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+const PUBLIC_REF = /^[A-Za-z0-9][A-Za-z0-9._:@~-]{0,159}$/;
+const REVISION = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const MAX_PENDING = 32, MAX_RECENT = 64, DEFAULT_TTL_MS = 5 * 60_000;
+
+type Identity = { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string; taskRunId: string;
+  agentOperationId: string; toolCallId: string };
+type TreePrecondition = { workspaceRevision: string; indexRevision: string | null; preimageDigest: string };
+type Revisions = { runtimeRevision: string; taskRevision: string; controlRevision: string; approvalRevision: string;
+  treePrecondition: TreePrecondition | null };
+type ReceiptRevisions = Omit<Revisions, "treePrecondition">;
+export type ApprovalAuthority = { identity: Omit<Identity, "toolCallId">; revisions: Omit<ReceiptRevisions, "approvalRevision">;
+  taskState: "active" | "terminal" } | null;
+export type ApprovalActionDraft = {
+  kind: "external-provider-action" | "filesystem-write" | "filesystem-delete" | "workspace-patch" | "source-stage" | "source-unstage" | "source-revert";
+  preconditionClass: "runtime-only" | "workspace-tree" | "workspace-index";
+  toolName: string; rawAction: unknown; commandPreview?: string | null; parameterPreview?: string; targetPaths?: string[];
+  targetSummaries?: string[]; provider?: string | null; urlOrigin?: string | null; requestedScope: string; reason: string;
+  riskClass: "low" | "medium" | "high" | "critical"; allowConsequence: string; denyConsequence: string;
+  treePrecondition?: TreePrecondition | null;
+};
+type Request = { schemaVersion: 1; version: "piagent-webui-approval-v1"; recordType: "request"; approvalRef: string; decisionToken: string;
+  identity: Identity; action: Record<string, unknown>; expectedRevisions: Revisions; state: "waiting"; requestedAt: string; expiresAt: string;
+  executor: "pi-guard"; directExecution: false };
+type Receipt = { schemaVersion: 1; version: "piagent-webui-approval-v1"; recordType: "receipt"; approvalRef: string; decisionId: string | null;
+  identity: Identity; actionDigest: string; state: "resolved" | "expired" | "cancelled"; decision: "allow" | "deny" | null;
+  winnerSurface: "webui" | "terminal" | "runtime-expiry" | "runtime-control" | "runtime-restart"; resolutionReason: string | null;
+  resolvedAt: string; preRevisions: Revisions; postRevisions: ReceiptRevisions; permit: Record<string, unknown>; deduplicated: boolean;
+  auditRef: string; executor: "pi-guard"; directExecution: false };
+type Binding = { cwd: string; rawSessionId: string; runtimeInstanceId: string; secret: Buffer; authority(): ApprovalAuthority;
+  listeners: Set<(event: ApprovalBrokerEvent) => void>; pending: Map<string, Pending>; requests: Map<string, Request>; recent: Receipt[];
+  approvalCounter: number; approvalRevision: string };
+type Pending = { request: Request; resolve(value: ApprovalGuardDecision): void; receipt: Receipt | null; timer: NodeJS.Timeout;
+  finalWaiters: Array<(receipt: Receipt) => void>; recheck(): boolean };
+export type ApprovalBrokerEvent = { kind: "requested" | "resolved" | "expired" | "cancelled"; approvalRef: string; request?: Request; receipt?: Receipt };
+export type ApprovalGuardDecision = { allowed: boolean; brokered: boolean; receipt: Receipt | null;
+  consume(): boolean; cancel(reasonCode?: string): void };
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (!value || typeof value !== "object") return JSON.stringify(value);
+  return `{${Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(",")}}`;
+}
+function exactTimestamp(value: unknown): value is string {
+  if (typeof value !== "string" || !TIMESTAMP.test(value)) return false;
+  const parsed = Date.parse(value); return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+function exactKeys(value: unknown, keys: string[]): boolean {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value)
+    && canonical(Object.keys(value as Record<string, unknown>).sort()) === canonical([...keys].sort()));
+}
+function ref(prefix: string, secret: Buffer, value: unknown): string {
+  return `${prefix}.${createHmac("sha256", secret).update(canonical(value)).digest("hex")}`;
+}
+function digest(secret: Buffer, value: unknown): string { return `sha256:${createHmac("sha256", secret).update(canonical(value)).digest("hex")}`; }
+function safe(value: unknown, maximum: number): { text: string; redacted: boolean; truncated: boolean } {
+  const raw = String(value ?? ""); const redacted = redactSensitiveText(raw);
+  const clean = redacted.text.replace(/\u001b(?:[@-_]|\[[0-?]*[ -/]*[@-~])/g, "").replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+    .replace(/\s+/g, " ").trim();
+  return { text: clean.slice(0, maximum), redacted: redacted.redacted, truncated: clean.length > maximum };
+}
+function publicId(value: string): string { const clean = safe(value, 160).text.replace(/[^A-Za-z0-9._:@~-]/g, "-"); return PUBLIC_REF.test(clean) ? clean : "unknown"; }
+function reasonCode(value: string, fallback: string): string { const clean = safe(value, 96).text.toLowerCase().replace(/[^a-z0-9.-]+/g, "-").replace(/^-+|-+$/g, ""); return clean || fallback; }
+function key(cwd: string, rawSessionId: string): string { return `${cwd}\0${rawSessionId}`; }
+function clone<T>(value: T): T { return structuredClone(value); }
+
+export class PiApprovalBroker {
+  readonly #bindings = new Map<string, Binding>();
+
+  bind(input: { cwd: string; rawSessionId: string; runtimeInstanceId: string; authority(): ApprovalAuthority }): () => void {
+    const bindingKey = key(input.cwd, input.rawSessionId), prior = this.#bindings.get(bindingKey);
+    if (prior && prior.runtimeInstanceId !== input.runtimeInstanceId) this.#cancelBinding(prior, "runtime-replaced", "runtime-restart");
+    if (prior?.runtimeInstanceId === input.runtimeInstanceId) { prior.authority = input.authority; return () => this.unbind(input); }
+    const secret = randomBytes(32);
+    const binding: Binding = { ...input, secret, listeners: new Set(), pending: new Map(), requests: new Map(), recent: [], approvalCounter: 0,
+      approvalRevision: ref("approval-rev", secret, [input.runtimeInstanceId, 0]) };
+    this.#bindings.set(bindingKey, binding);
+    return () => this.unbind(input);
+  }
+
+  unbind(input: { cwd: string; rawSessionId: string; runtimeInstanceId: string }): void {
+    const bindingKey = key(input.cwd, input.rawSessionId), binding = this.#bindings.get(bindingKey);
+    if (!binding || binding.runtimeInstanceId !== input.runtimeInstanceId) return;
+    this.#cancelBinding(binding, "runtime-stopped", "runtime-restart"); this.#bindings.delete(bindingKey);
+  }
+
+  subscribe(cwd: string, rawSessionId: string, listener: (event: ApprovalBrokerEvent) => void): () => void {
+    const binding = this.#bindings.get(key(cwd, rawSessionId)); if (!binding) return () => undefined;
+    binding.listeners.add(listener); return () => binding.listeners.delete(listener);
+  }
+
+  cancelForControl(cwd: string, rawSessionId: string, taskRunId: string, reason = "task-pausing"): number {
+    const binding = this.#bindings.get(key(cwd, rawSessionId)); if (!binding) return 0;
+    const targets = [...binding.pending.entries()].filter(([, pending]) => pending.request.identity.taskRunId === taskRunId);
+    for (const [approvalRef] of targets) this.#cancelPending(binding, approvalRef, reason, "runtime-control", "cancelled");
+    return targets.length;
+  }
+
+  projection(cwd: string, rawSessionId: string): { revision: string | null; summary: Record<string, unknown> } {
+    const binding = this.#bindings.get(key(cwd, rawSessionId));
+    if (!binding) return { revision: null, summary: { state: "unknown", pending: [], recent: [],
+      health: { state: "unavailable", reasonCode: "approval-broker-unavailable", message: "Approval broker is unavailable" } } };
+    const pending = [...binding.pending.values()].filter((item) => !item.receipt).map((item) => this.#summary(item.request));
+    const recent = binding.recent.slice(-MAX_RECENT).reverse().map((item) => this.#summary(item));
+    const latest = binding.recent.at(-1);
+    const state = pending.length ? "waiting" : !latest ? "none" : latest.state === "expired" ? "expired" : "resolved";
+    return { revision: binding.approvalRevision, summary: { state, pending, recent: state === "none" ? [] : recent,
+      health: { state: "ok", reasonCode: null, message: null } } };
+  }
+
+  detail(cwd: string, rawSessionId: string, approvalRef: string): Request | null {
+    if (!REF.test(approvalRef)) return null;
+    const pending = this.#bindings.get(key(cwd, rawSessionId))?.pending.get(approvalRef);
+    return pending && !pending.receipt ? clone(pending.request) : null;
+  }
+
+  async request(input: { cwd: string; rawSessionId: string; toolCallId: string; action: ApprovalActionDraft;
+    expectedTask?: { taskId: string; taskRunId: string } | null; terminalConfirm(): Promise<boolean>; recheck?(): boolean; ttlMs?: number }): Promise<ApprovalGuardDecision> {
+    const binding = this.#bindings.get(key(input.cwd, input.rawSessionId));
+    const authority = binding?.authority();
+    if (!binding || !authority || authority.taskState !== "active" || input.expectedTask && (authority.identity.taskId !== input.expectedTask.taskId || authority.identity.taskRunId !== input.expectedTask.taskRunId)
+      || !REF.test(authority.identity.agentOperationId)
+      || !REF.test(input.toolCallId) || binding.pending.size >= MAX_PENDING) return this.#terminalOnly(input.terminalConfirm);
+    const now = Date.now(), requestedAt = new Date(now).toISOString(), expiresAt = new Date(now + Math.min(Math.max(input.ttlMs ?? DEFAULT_TTL_MS, 5_000), DEFAULT_TTL_MS)).toISOString();
+    const approvalRef = ref("approval", binding.secret, [input.toolCallId, now, randomUUID()]);
+    const decisionToken = randomBytes(32).toString("base64url");
+    const nextRevision = this.#nextRevision(binding, "requested", approvalRef);
+    const identity: Identity = { ...authority.identity, toolCallId: input.toolCallId };
+    const action = this.#action(binding, input.action, input.cwd);
+    const expectedRevisions: Revisions = { ...authority.revisions, approvalRevision: nextRevision,
+      treePrecondition: input.action.preconditionClass === "runtime-only" ? null : input.action.treePrecondition ?? null };
+    if ((input.action.preconditionClass !== "runtime-only" && !expectedRevisions.treePrecondition)
+      || !this.#validTree(expectedRevisions.treePrecondition)) return this.#terminalOnly(input.terminalConfirm);
+    const request: Request = { schemaVersion: 1, version: "piagent-webui-approval-v1", recordType: "request", approvalRef, decisionToken,
+      identity, action, expectedRevisions, state: "waiting", requestedAt, expiresAt, executor: "pi-guard", directExecution: false };
+    const result = new Promise<ApprovalGuardDecision>((resolve) => {
+      const timer = setTimeout(() => this.#expire(binding, approvalRef), Date.parse(expiresAt) - Date.now()); timer.unref();
+      binding.pending.set(approvalRef, { request, resolve, receipt: null, timer, finalWaiters: [], recheck: input.recheck ?? (() => true) }); binding.requests.set(approvalRef, request);
+      while (binding.requests.size > MAX_PENDING + MAX_RECENT) binding.requests.delete(binding.requests.keys().next().value as string);
+    });
+    this.#emit(binding, { kind: "requested", approvalRef, request: clone(request) });
+    void Promise.resolve().then(input.terminalConfirm).then(
+      (allow) => this.#settle(binding, approvalRef, allow ? "allow" : "deny", "terminal", ref("decision", binding.secret, [approvalRef, "terminal", now])),
+      () => this.#settle(binding, approvalRef, "deny", "terminal", ref("decision", binding.secret, [approvalRef, "terminal-error", now]))
+    );
+    return result;
+  }
+
+  async decide(cwd: string, rawSessionId: string, approvalRef: string, value: unknown): Promise<Receipt> {
+    const binding = this.#bindings.get(key(cwd, rawSessionId)); if (!binding || !REF.test(approvalRef)) throw new Error("approval-unavailable");
+    const pending = binding.pending.get(approvalRef);
+    if (!pending) {
+      const prior = binding.recent.find((item) => item.approvalRef === approvalRef);
+      const request = binding.requests.get(approvalRef);
+      if (prior && request && this.#validDecision(value, request, null) && (value as any).decisionId === prior.decisionId) return { ...clone(prior), deduplicated: true };
+      throw new Error("approval-not-pending");
+    }
+    if (!this.#validDecision(value, pending.request, null)) throw new Error("approval-decision-invalid");
+    const decision = value as any;
+    if (pending.receipt) {
+      if (decision.decisionId !== pending.receipt.decisionId) throw new Error("approval-already-resolved");
+      if (pending.receipt.permit.status === "provisional") return new Promise<Receipt>((resolve) => pending.finalWaiters.push((receipt) => resolve({ ...receipt, deduplicated: true })));
+      return { ...clone(pending.receipt), deduplicated: true };
+    }
+    if (Date.now() >= Date.parse(pending.request.expiresAt)) { this.#expire(binding, approvalRef); throw new Error("approval-expired"); }
+    const final = new Promise<Receipt>((resolve) => pending.finalWaiters.push(resolve));
+    this.#settle(binding, approvalRef, decision.decision, "webui", decision.decisionId);
+    if (decision.decision === "deny") return clone(binding.recent.at(-1)!);
+    return final;
+  }
+
+  #terminalOnly(confirm: () => Promise<boolean>): Promise<ApprovalGuardDecision> {
+    return Promise.resolve().then(confirm).then((allowed) => ({ allowed, brokered: false, receipt: null,
+      consume: () => allowed, cancel: () => undefined }), () => ({ allowed: false, brokered: false, receipt: null,
+      consume: () => false, cancel: () => undefined }));
+  }
+
+  #action(binding: Binding, draft: ApprovalActionDraft, cwd: string): Record<string, unknown> {
+    const command = draft.commandPreview === null || draft.commandPreview === undefined ? null : safe(draft.commandPreview, 4_000);
+    const parameter = safe(draft.parameterPreview ?? "No additional parameters", 4_000);
+    const targetPaths = (draft.targetPaths ?? []).slice(0, 32).map((item) => safe(item, 500)).filter((item) => item.text).map((item) => item.text);
+    const targetSummaries = (draft.targetSummaries ?? []).slice(0, 32).map((item) => safe(item, 500)).filter((item) => item.text).map((item) => item.text);
+    const removed = [command, parameter].filter((item) => item?.redacted).length;
+    const truncated = Boolean(command?.truncated || parameter.truncated || (draft.targetPaths?.length ?? 0) > 32 || (draft.targetSummaries?.length ?? 0) > 32);
+    const provider = draft.provider ? safe(draft.provider, 160).text : "";
+    const targetProvided = targetPaths.length > 0 || targetSummaries.length > 0;
+    return { kind: draft.kind, preconditionClass: draft.preconditionClass, toolName: publicId(draft.toolName),
+      actionDigest: digest(binding.secret, draft.rawAction), canonicalization: "digest-bound-action-v1", previewPolicy: "redacted-no-secrets-v1",
+      commandPreview: command?.text || null, parameterPreview: parameter.text || "No additional parameters",
+      targetEvidence: targetProvided ? { state: "provided", reasonCode: null } : { state: "redacted", reasonCode: "target-not-exposed" },
+      cwdRef: ref("cwd", binding.secret, cwd), cwdDisplay: safe(path.basename(cwd), 500).text || null,
+      targetRefs: [], targetPaths, targetSummaries, providerRef: provider ? ref("provider", binding.secret, provider) : null,
+      urlOrigin: /^https?:\/\/(?:[A-Za-z0-9-]+\.)*[A-Za-z0-9-]+(?::[0-9]{1,5})?$/.test(draft.urlOrigin ?? "") ? draft.urlOrigin : null,
+      requestedScope: reasonCode(draft.requestedScope, "one-action"), reason: safe(draft.reason, 500).text || "Human confirmation is required",
+      riskClass: draft.riskClass, consequences: { allow: safe(draft.allowConsequence, 500).text || "Allow this exact action once",
+        deny: safe(draft.denyConsequence, 500).text || "Block this action" },
+      redaction: { applied: removed > 0, valuesRemoved: removed, truncated } };
+  }
+
+  #validDecision(value: unknown, request?: Request, receipt?: Receipt | null): boolean {
+    if (!exactKeys(value, ["schemaVersion", "version", "recordType", "approvalRef", "decisionId", "decisionToken", "identity", "actionDigest",
+      "expectedRevisions", "decision", "reason", "decidedAt", "expiresAt", "decisionSurface", "executor", "directExecution"])) return false;
+    const item = value as any;
+    if (item.schemaVersion !== 1 || item.version !== "piagent-webui-approval-v1" || item.recordType !== "decision"
+      || !REF.test(item.approvalRef) || !REF.test(item.decisionId) || typeof item.decisionToken !== "string" || item.decisionToken.length < 32
+      || !["allow", "deny"].includes(item.decision) || !exactTimestamp(item.decidedAt) || !exactTimestamp(item.expiresAt)
+      || item.decisionSurface !== "webui" || item.executor !== "pi-guard" || item.directExecution !== false
+      || !(item.reason === null || typeof item.reason === "string" && item.reason.length <= 500)) return false;
+    if (request) return item.approvalRef === request.approvalRef && item.decisionToken === request.decisionToken
+      && item.actionDigest === request.action.actionDigest && canonical(item.identity) === canonical(request.identity)
+      && canonical(item.expectedRevisions) === canonical(request.expectedRevisions) && item.expiresAt === request.expiresAt
+      && Date.parse(item.decidedAt) >= Date.parse(request.requestedAt) - 1_000 && Date.parse(item.decidedAt) <= Date.now() + 1_000;
+    return Boolean(receipt && item.approvalRef === receipt.approvalRef && item.decisionId === receipt.decisionId
+      && item.actionDigest === receipt.actionDigest && canonical(item.identity) === canonical(receipt.identity));
+  }
+
+  #validTree(value: TreePrecondition | null): boolean {
+    return value === null || Boolean(REVISION.test(value.workspaceRevision) && (value.indexRevision === null || REVISION.test(value.indexRevision)) && DIGEST.test(value.preimageDigest));
+  }
+
+  #settle(binding: Binding, approvalRef: string, decision: "allow" | "deny", surface: "webui" | "terminal", decisionId: string): void {
+    const pending = binding.pending.get(approvalRef); if (!pending || pending.receipt) return;
+    clearTimeout(pending.timer); const resolvedAt = new Date().toISOString();
+    const postRevision = this.#nextRevision(binding, "resolved", [approvalRef, decision, surface]);
+    const receipt: Receipt = { schemaVersion: 1, version: "piagent-webui-approval-v1", recordType: "receipt", approvalRef, decisionId,
+      identity: clone(pending.request.identity), actionDigest: String(pending.request.action.actionDigest), state: "resolved", decision,
+      winnerSurface: surface, resolutionReason: null, resolvedAt, preRevisions: clone(pending.request.expectedRevisions),
+      postRevisions: { runtimeRevision: pending.request.expectedRevisions.runtimeRevision, taskRevision: pending.request.expectedRevisions.taskRevision,
+        controlRevision: pending.request.expectedRevisions.controlRevision, approvalRevision: postRevision },
+      permit: decision === "allow" ? { status: "provisional", issuedAt: resolvedAt, consumedAt: null, reasonCode: null }
+        : { status: "not-issued", issuedAt: null, consumedAt: null, reasonCode: null }, deduplicated: false,
+      auditRef: ref("approval-audit", binding.secret, [approvalRef, resolvedAt, surface, decision]), executor: "pi-guard", directExecution: false };
+    pending.receipt = receipt; binding.recent.push(receipt); binding.recent = binding.recent.slice(-MAX_RECENT);
+    this.#emit(binding, { kind: "resolved", approvalRef, receipt: clone(receipt) });
+    const decisionResult: ApprovalGuardDecision = { allowed: decision === "allow", brokered: true, receipt: clone(receipt),
+      consume: () => this.#consume(binding, receipt), cancel: (reason = "guard-cancelled") => this.#cancelPermit(binding, receipt, reason) };
+    pending.resolve(decisionResult);
+    if (decision === "deny") this.#finish(binding, pending, receipt);
+  }
+
+  #consume(binding: Binding, receipt: Receipt): boolean {
+    if (receipt.permit.status !== "provisional") return receipt.permit.status === "consumed";
+    const authority = binding.authority();
+    const pending = binding.pending.get(receipt.approvalRef);
+    const expectedIdentity = { projectRef: receipt.identity.projectRef, runtimeInstanceId: receipt.identity.runtimeInstanceId,
+      sessionRef: receipt.identity.sessionRef, taskId: receipt.identity.taskId, taskRunId: receipt.identity.taskRunId,
+      agentOperationId: receipt.identity.agentOperationId };
+    if (!authority || authority.taskState !== "active" || !pending?.recheck() || canonical(authority.identity) !== canonical(expectedIdentity)) {
+      this.#cancelPermit(binding, receipt, "authority-changed"); return false;
+    }
+    const expected = receipt.preRevisions;
+    if (authority.revisions.runtimeRevision !== expected.runtimeRevision || authority.revisions.taskRevision !== expected.taskRevision
+      || authority.revisions.controlRevision !== expected.controlRevision || binding.approvalRevision !== receipt.postRevisions.approvalRevision) {
+      this.#cancelPermit(binding, receipt, "revision-changed"); return false;
+    }
+    const consumedAt = new Date().toISOString(); receipt.permit = { status: "consumed", issuedAt: receipt.permit.issuedAt, consumedAt, reasonCode: null };
+    receipt.postRevisions.approvalRevision = this.#nextRevision(binding, "permit-consumed", receipt.approvalRef);
+    if (pending) this.#finish(binding, pending, receipt);
+    this.#emit(binding, { kind: "resolved", approvalRef: receipt.approvalRef, receipt: clone(receipt) }); return true;
+  }
+
+  #cancelPermit(binding: Binding, receipt: Receipt, reason: string): void {
+    if (receipt.permit.status !== "provisional") return;
+    receipt.permit = { status: "cancelled", issuedAt: receipt.permit.issuedAt, consumedAt: null, reasonCode: reasonCode(reason, "guard-cancelled") };
+    receipt.postRevisions.approvalRevision = this.#nextRevision(binding, "permit-cancelled", [receipt.approvalRef, reason]);
+    const pending = binding.pending.get(receipt.approvalRef); if (pending) this.#finish(binding, pending, receipt);
+    this.#emit(binding, { kind: "cancelled", approvalRef: receipt.approvalRef, receipt: clone(receipt) });
+  }
+
+  #expire(binding: Binding, approvalRef: string): void { this.#cancelPending(binding, approvalRef, "approval-expired", "runtime-expiry", "expired"); }
+  #cancelBinding(binding: Binding, reason: string, surface: "runtime-restart" | "runtime-control"): void {
+    for (const approvalRef of [...binding.pending.keys()]) this.#cancelPending(binding, approvalRef, reason, surface, "cancelled");
+  }
+  #cancelPending(binding: Binding, approvalRef: string, reason: string, surface: "runtime-expiry" | "runtime-restart" | "runtime-control", state: "expired" | "cancelled"): void {
+    const pending = binding.pending.get(approvalRef); if (!pending || pending.receipt) return; clearTimeout(pending.timer);
+    const resolvedAt = new Date().toISOString(), post = this.#nextRevision(binding, state, approvalRef);
+    const receipt: Receipt = { schemaVersion: 1, version: "piagent-webui-approval-v1", recordType: "receipt", approvalRef, decisionId: null,
+      identity: clone(pending.request.identity), actionDigest: String(pending.request.action.actionDigest), state, decision: null, winnerSurface: surface,
+      resolutionReason: reasonCode(reason, "approval-cancelled"), resolvedAt, preRevisions: clone(pending.request.expectedRevisions),
+      postRevisions: { runtimeRevision: pending.request.expectedRevisions.runtimeRevision, taskRevision: pending.request.expectedRevisions.taskRevision,
+        controlRevision: pending.request.expectedRevisions.controlRevision, approvalRevision: post },
+      permit: { status: state === "expired" ? "expired" : "cancelled", issuedAt: null, consumedAt: null, reasonCode: reasonCode(reason, "approval-cancelled") },
+      deduplicated: false, auditRef: ref("approval-audit", binding.secret, [approvalRef, resolvedAt, surface]), executor: "pi-guard", directExecution: false };
+    pending.receipt = receipt; binding.recent.push(receipt); binding.recent = binding.recent.slice(-MAX_RECENT);
+    this.#emit(binding, { kind: state === "expired" ? "expired" : "cancelled", approvalRef, receipt: clone(receipt) });
+    pending.resolve({ allowed: false, brokered: true, receipt: clone(receipt), consume: () => false, cancel: () => undefined }); this.#finish(binding, pending, receipt);
+  }
+
+  #finish(binding: Binding, pending: Pending, receipt: Receipt): void {
+    binding.pending.delete(receipt.approvalRef); for (const resolve of pending.finalWaiters.splice(0)) resolve(clone(receipt));
+  }
+  #nextRevision(binding: Binding, kind: string, value: unknown): string {
+    binding.approvalCounter += 1; binding.approvalRevision = ref("approval-rev", binding.secret, [binding.runtimeInstanceId, binding.approvalCounter, kind, value]);
+    return binding.approvalRevision;
+  }
+  #emit(binding: Binding, event: ApprovalBrokerEvent): void { for (const listener of binding.listeners) { try { listener(clone(event)); } catch { /* projection listeners are fail-soft */ } } }
+  #summary(value: Request | Receipt): Record<string, unknown> {
+    if (value.recordType === "request") return { approvalRef: value.approvalRef, state: "waiting", resolution: null,
+      actionSummary: safe(`${value.action.toolName}: ${value.action.reason}`, 500).text || "Approval required", toolCallId: value.identity.toolCallId,
+      expiresAt: value.expiresAt, reasonCode: null };
+    return { approvalRef: value.approvalRef, state: value.state === "expired" ? "expired" : "resolved",
+      resolution: value.state === "expired" ? "expired" : value.state === "cancelled" ? "cancelled" : value.decision,
+      actionSummary: safe(`${value.identity.toolCallId}: ${value.decision ?? value.state}`, 500).text || "Approval resolved",
+      toolCallId: value.identity.toolCallId, expiresAt: null, reasonCode: value.state === "expired" ? value.resolutionReason : null };
+  }
+}
+
+const BROKER_KEY = Symbol.for("piagent.webui.approval-broker.v1");
+const root = globalThis as typeof globalThis & { [BROKER_KEY]?: PiApprovalBroker };
+export const piApprovalBroker = root[BROKER_KEY] ??= new PiApprovalBroker();

package/packages/piagent-core/runtime/inspection/commit-summary-projection.ts

@@ -0,0 +1,59 @@
+import { createHash } from "node:crypto";
+
+import { redactSensitiveText } from "../../extensions/redaction-core.js";
+import { canonicalReviewValue } from "./review-state-contract.ts";
+import type { SourceChangeDocument, WebUiIdentity } from "./source-change-projection.ts";
+
+const MAX_FILES = 300, MAX_BODY_FILES = 12;
+type Status = "A" | "M" | "D" | "R" | "C";
+const ACTION: Record<Status, string> = { A: "Add", M: "Update", D: "Remove", R: "Rename", C: "Resolve conflict in" };
+
+function token(value: unknown): string { return `commit-summary.${createHash("sha256").update(canonicalReviewValue(value)).digest("hex")}`; }
+function safe(value: unknown, maximum: number): { text: string; redacted: boolean } {
+  const raw = String(value ?? "").replace(/[\u0000-\u001F\u007F]/g, " ").replace(/\s+/g, " ").trim();
+  const result = redactSensitiveText(raw); return { text: result.text.slice(0, maximum).trim(), redacted: result.redacted };
+}
+function unavailable(identity: WebUiIdentity, generatedAt: string, reasonCode: string) {
+  return { schemaVersion: 1 as const, version: "piagent-webui-commit-summary-v1" as const, generatedAt, identity,
+    state: "unavailable" as const, summary: null, reasonCode,
+    health: { state: "unavailable" as const, reasonCode, message: "A current non-empty staged projection is required." } };
+}
+
+export function projectDeterministicCommitSummary(options: { identity: WebUiIdentity; sourceView: SourceChangeDocument;
+  taskRevision: string; indexRevision: string; generatedAt?: string }) {
+  const generatedAt = options.generatedAt ?? new Date().toISOString(), identity = { ...options.identity, agentOperationId: null, toolCallId: null };
+  if (!identity.taskId || !identity.taskRunId || options.sourceView.view !== "staged"
+    || options.sourceView.availability.state !== "current") return unavailable(identity, generatedAt, "staged-projection-unavailable");
+  const files = options.sourceView.files.slice(0, MAX_FILES) as Array<Record<string, any>>;
+  const total = Math.min(2_000, Number((options.sourceView.page as any)?.total ?? files.length));
+  if (total < 1 || files.length < 1) return unavailable(identity, generatedAt, "no-staged-changes");
+  const statusCounts: Record<Status, number> = { A: 0, M: 0, D: 0, R: 0, C: 0 }, lines: string[] = [];
+  let protectedFileCount = 0, redacted = false, additions = 0, deletions = 0, exactStats = total === files.length;
+  const commitments: unknown[] = [];
+  for (const file of files) {
+    const status = ["A", "M", "D", "R", "C"].includes(file.status) ? file.status as Status : "M";
+    statusCounts[status] += 1; commitments.push([file.fileRef, file.fileRevision, status, file.currentDigest, file.baseDigest]);
+    const restricted = file.content?.access !== "available" || file.pathDisplay !== "exact-safe";
+    if (restricted) { protectedFileCount += 1; exactStats = false; continue; }
+    const display = safe(file.path, 300); redacted ||= display.redacted;
+    const label = display.redacted || !display.text ? "[redacted staged file]" : display.text;
+    const statsExact = file.stats?.state === "exact" && Number.isInteger(file.stats.additions) && Number.isInteger(file.stats.deletions);
+    if (statsExact) { additions += file.stats.additions; deletions += file.stats.deletions; } else exactStats = false;
+    if (lines.length < MAX_BODY_FILES) lines.push(`- ${ACTION[status]} ${label}${statsExact ? ` (+${file.stats.additions}/-${file.stats.deletions})` : ""}`);
+  }
+  if (protectedFileCount) lines.push(`- ${protectedFileCount} protected staged file${protectedFileCount === 1 ? "" : "s"} (names omitted)`);
+  const omitted = Math.max(0, total - Math.min(files.length, MAX_BODY_FILES + protectedFileCount));
+  if (omitted) lines.push(`- ${omitted} additional staged file${omitted === 1 ? "" : "s"} omitted from this bounded preview`);
+  lines.push(exactStats ? `- Staged changes: +${additions} / -${deletions}` : "- Staged line totals are incomplete");
+  const singleVisible = total === 1 && protectedFileCount === 0 && lines[0]?.startsWith("- ") ? lines[0].replace(/^- /, "").replace(/ \(\+\d+\/-\d+\)$/, "") : null;
+  const title = safe(singleVisible ?? `Update ${total} staged files`, 160).text || `Update ${total} staged files`;
+  const summaryRef = token({ taskRevision: options.taskRevision, indexRevision: options.indexRevision, total, commitments, lines, title });
+  const modelPrompt = ["Write a concise Git commit message from the exact staged summary below.",
+    "Return one title of at most 72 characters, then optional bullet points. Do not claim that a commit or push was executed.",
+    `Index revision: ${options.indexRevision}`, `Deterministic title: ${title}`, ...lines].join("\n").slice(0, 8_000);
+  return { schemaVersion: 1 as const, version: "piagent-webui-commit-summary-v1" as const, generatedAt, identity, state: "ready" as const,
+    summary: { summaryRef, taskRevision: options.taskRevision, indexRevision: options.indexRevision, title, bodyLines: lines,
+      modelPrompt, fileCount: total, returnedFiles: files.length, statusCounts, additions: exactStats ? additions : null,
+      deletions: exactStats ? deletions : null, protectedFileCount, redacted, truncated: Boolean((options.sourceView.page as any)?.truncated) || omitted > 0 },
+    reasonCode: null, health: { state: "ok" as const, reasonCode: null, message: null } };
+}

package/packages/piagent-core/runtime/inspection/context-telemetry-inspection.ts

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+
+import { contextEnginePaths } from "../../extensions/context-engine.js";
+import { resolveLocalStatePath } from "../../extensions/local-state-path.js";
+
+function tailText(file: string, maximumBytes: number): { text: string; truncated: boolean } {
+  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  try {
+    const stat = fs.fstatSync(descriptor), start = Math.max(0, stat.size - maximumBytes);
+    const buffer = Buffer.allocUnsafe(stat.size - start); fs.readSync(descriptor, buffer, 0, buffer.length, start);
+    let text = buffer.toString("utf8"); if (start > 0) text = text.slice(Math.max(0, text.indexOf("\n") + 1));
+    return { text, truncated: start > 0 };
+  } finally { fs.closeSync(descriptor); }
+}
+
+export function inspectBoundedContextTelemetry(cwd: string, options: { limit?: number; maximumBytes?: number } = {}) {
+  const limit = Math.max(1, Math.min(50_000, options.limit ?? 5_000));
+  const maximumBytes = Math.max(64 * 1024, Math.min(256 * 1024 * 1024, options.maximumBytes ?? 32 * 1024 * 1024));
+  const target = contextEnginePaths(cwd).telemetry, rows: Record<string, unknown>[] = [];
+  let exists = false, corruptions = 0, recoverableTailBytes = 0, inputTruncated = false;
+  for (const source of [`${target}.1`, target]) {
+    const safe = resolveLocalStatePath(cwd, source, { label: "Context telemetry" });
+    try {
+      const stat = fs.lstatSync(safe); if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("Context telemetry must be a regular file");
+      exists = true;
+    } catch (error: any) { if (error?.code === "ENOENT") continue; throw error; }
+    const read = tailText(safe, maximumBytes); inputTruncated ||= read.truncated;
+    const complete = read.text.endsWith("\n") || read.text.endsWith("\r"), lines = read.text.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = lines[index]; if (!line) continue;
+      try { const row = JSON.parse(line); if (row && typeof row === "object" && !Array.isArray(row)) rows.push(row); else corruptions += 1; }
+      catch { if (!complete && index === lines.length - 1) recoverableTailBytes += Buffer.byteLength(line); else corruptions += 1; }
+    }
+  }
+  return { records: rows.slice(-limit), exists, corruptions, recoverableTailBytes,
+    inputTruncated: inputTruncated || rows.length > limit };
+}