@piagent/platform 1.3.1 → 1.4.1

package/packages/piagent-webui/server/session-auth.ts

@@ -0,0 +1,88 @@
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import type { IncomingMessage } from "node:http";
+
+const SESSION_COOKIE = "piagent_webui_session";
+
+function secret(): string { return randomBytes(32).toString("base64url"); }
+function equal(left: string, right: string): boolean {
+  const a = Buffer.from(left), b = Buffer.from(right);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function cookie(request: IncomingMessage, name: string): string | null {
+  for (const part of String(request.headers.cookie ?? "").split(";")) {
+    const index = part.indexOf("=");
+    if (index > 0 && part.slice(0, index).trim() === name) return part.slice(index + 1).trim();
+  }
+  return null;
+}
+
+export type BrowserSession = { id: string; csrf: string; expiresAt: number };
+
+export class SessionAuthority {
+  readonly #initialBootstrap: string;
+  readonly #bootstrapTtlMs: number;
+  readonly #sessionTtlMs: number;
+  readonly #cookieSigningKey = randomBytes(32);
+  #bootstraps = new Map<string, number>();
+  #sessions = new Map<string, BrowserSession>();
+
+  constructor(options: { now?: number; bootstrapTtlMs?: number; sessionTtlMs?: number } = {}) {
+    this.#bootstrapTtlMs = options.bootstrapTtlMs ?? 60_000;
+    this.#sessionTtlMs = options.sessionTtlMs ?? 8 * 60 * 60_000;
+    this.#initialBootstrap = this.issueBootstrapCapability(options.now ?? Date.now());
+  }
+
+  get bootstrapCapability(): string { return this.#initialBootstrap; }
+
+  issueBootstrapCapability(now = Date.now()): string {
+    for (const [value, createdAt] of this.#bootstraps) {
+      if (now > createdAt + this.#bootstrapTtlMs) this.#bootstraps.delete(value);
+    }
+    while (this.#bootstraps.size >= 8) this.#bootstraps.delete(this.#bootstraps.keys().next().value as string);
+    const value = secret();
+    this.#bootstraps.set(value, now);
+    return value;
+  }
+
+  exchange(candidate: string, now = Date.now()): BrowserSession | null {
+    const match = [...this.#bootstraps].find(([value, createdAt]) => now <= createdAt + this.#bootstrapTtlMs && equal(candidate, value));
+    if (!match) return null;
+    this.#bootstraps.delete(match[0]);
+    const session = { id: randomUUID(), csrf: secret(), expiresAt: now + this.#sessionTtlMs };
+    this.#sessions.set(session.id, session);
+    return session;
+  }
+
+  authenticate(request: IncomingMessage, now = Date.now()): BrowserSession | null {
+    const value = cookie(request, SESSION_COOKIE);
+    if (!value) return null;
+    const separator = value.lastIndexOf(".");
+    if (separator < 1) return null;
+    const id = value.slice(0, separator), signature = value.slice(separator + 1);
+    if (!equal(signature, this.#cookieSignature(id))) return null;
+    const session = this.#sessions.get(id);
+    if (!session || session.expiresAt < now || !equal(id, session.id)) {
+      if (session) this.#sessions.delete(id);
+      return null;
+    }
+    return session;
+  }
+
+  authorizeMutation(request: IncomingMessage, now = Date.now()): BrowserSession | null {
+    const session = this.authenticate(request, now);
+    const csrf = request.headers["x-piagent-csrf"];
+    return session && typeof csrf === "string" && equal(csrf, session.csrf) ? session : null;
+  }
+
+  cookieHeader(session: BrowserSession): string {
+    const seconds = Math.max(1, Math.floor((session.expiresAt - Date.now()) / 1000));
+    const token = `${session.id}.${this.#cookieSignature(session.id)}`;
+    return `${SESSION_COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${seconds}`;
+  }
+
+  #cookieSignature(id: string): string {
+    return createHmac("sha256", this.#cookieSigningKey).update(id).digest("base64url");
+  }
+
+  invalidate(): void { this.#bootstraps.clear(); this.#sessions.clear(); }
+}

package/packages/piagent-webui/server/sidecar-main.ts

@@ -0,0 +1,86 @@
+import { timingSafeEqual } from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+
+import { IpcReadModelClient } from "./ipc-read-model-client.ts";
+import { startLoopbackServer, type LoopbackServer } from "./loopback-server.ts";
+
+type InitMessage = {
+  channel: "piagent-webui";
+  type: "init";
+  staticRoot: string;
+  controlSocket: string;
+  controlToken: string;
+};
+
+function equal(left: string, right: string): boolean {
+  const a = Buffer.from(left), b = Buffer.from(right);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+async function controlServer(socketPath: string, token: string, web: LoopbackServer): Promise<net.Server> {
+  try {
+    const stat = fs.lstatSync(socketPath);
+    if (!stat.isSocket()) throw new Error("webui-control-path-unsafe");
+    fs.unlinkSync(socketPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  const server = net.createServer((socket) => {
+    let input = Buffer.alloc(0), settled = false;
+    socket.setTimeout(2_000, () => socket.destroy());
+    socket.on("data", (chunk) => {
+      if (settled) return;
+      input = Buffer.concat([input, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+      if (input.length > 4_096) { settled = true; socket.end('{"ok":false,"error":"request-limit"}\n'); return; }
+      const newline = input.indexOf(10);
+      if (newline < 0) return;
+      settled = true;
+      try {
+        const value = JSON.parse(input.subarray(0, newline).toString("utf8"));
+        if (!value || value.action !== "launch" || typeof value.token !== "string" || !equal(value.token, token)) {
+          socket.end('{"ok":false,"error":"authority-rejected"}\n'); return;
+        }
+        socket.end(`${JSON.stringify({ ok: true, launchUrl: web.issueLaunchUrl() })}\n`);
+      } catch { socket.end('{"ok":false,"error":"invalid-request"}\n'); }
+    });
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, resolve);
+  });
+  fs.chmodSync(socketPath, 0o600);
+  return server;
+}
+
+let closing = false, web: LoopbackServer | undefined, control: net.Server | undefined, controlPath: string | undefined;
+async function close(code = 0): Promise<void> {
+  if (closing) return;
+  closing = true;
+  await web?.close().catch(() => undefined);
+  await new Promise<void>((resolve) => control ? control.close(() => resolve()) : resolve());
+  if (controlPath) {
+    try { if (fs.lstatSync(controlPath).isSocket()) fs.unlinkSync(controlPath); } catch { /* already removed */ }
+  }
+  process.exit(code);
+}
+
+process.once("message", (message: unknown) => { void (async () => {
+  const init = message as Partial<InitMessage>;
+  if (init.channel !== "piagent-webui" || init.type !== "init" || typeof init.staticRoot !== "string"
+    || typeof init.controlSocket !== "string" || typeof init.controlToken !== "string") throw new Error("webui-sidecar-init-invalid");
+  const client = new IpcReadModelClient();
+  web = await startLoopbackServer({ staticRoot: init.staticRoot, readCapabilities: () => client.capabilities(), readModel: client,
+    executeControl: (command) => client.executeControl(command), executeAttachment: (command) => client.executeAttachment(command),
+    executeApproval: (approvalRef, decision) => client.executeApproval(approvalRef, decision) });
+  controlPath = init.controlSocket;
+  control = await controlServer(init.controlSocket, init.controlToken, web);
+  process.send?.({ channel: "piagent-webui", type: "ready", origin: web.origin, launchUrl: web.launchUrl });
+})().catch((error) => {
+  process.send?.({ channel: "piagent-webui", type: "fatal", error: error instanceof Error ? error.message : "sidecar-start-failed" });
+  void close(1);
+}); });
+
+process.once("disconnect", () => { void close(0); });
+process.once("SIGTERM", () => { void close(0); });
+process.once("SIGINT", () => { void close(0); });

package/packages/piagent-webui/server/sse-hub.ts

@@ -0,0 +1,76 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { StreamEvent, WebUiReadModelProvider } from "./read-model-provider.ts";
+
+const CURSOR = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+const MAX_EVENT_BYTES = 65_536;
+const MAX_HANDOFF_EVENTS = 256;
+
+function frame(event: string, value: unknown, cursor?: string): string | null {
+  let json: string;
+  try { json = JSON.stringify(value); } catch { return null; }
+  if (Buffer.byteLength(json) > MAX_EVENT_BYTES || (cursor && !CURSOR.test(cursor))) return null;
+  return `${cursor ? `id: ${cursor}\n` : ""}event: ${event}\ndata: ${json}\n\n`;
+}
+
+export class SseHub {
+  readonly #provider: WebUiReadModelProvider;
+  readonly #clients = new Set<ServerResponse>();
+  readonly #maximumClients: number;
+  readonly #maximumReplayEvents: number;
+
+  constructor(provider: WebUiReadModelProvider, options: { maximumClients?: number; maximumReplayEvents?: number } = {}) {
+    this.#provider = provider;
+    this.#maximumClients = Math.max(1, Math.min(32, options.maximumClients ?? 8));
+    this.#maximumReplayEvents = Math.max(1, Math.min(10_000, options.maximumReplayEvents ?? 10_000));
+  }
+
+  async open(request: IncomingMessage, response: ServerResponse, after: string | null): Promise<void> {
+    if (this.#clients.size >= this.#maximumClients) {
+      response.statusCode = 503; response.end(JSON.stringify({ error: { code: "sse-client-limit" } })); return;
+    }
+    const buffered: StreamEvent[] = [];
+    let live = false, handoffOverflow = false;
+    const writeEvent = (event: StreamEvent): boolean => {
+      const encoded = frame("runtime-event", event.value, event.cursor);
+      if (!encoded) { response.end(frame("resync-required", { reasonCode: "event-payload-limit", latestCursor: event.cursor }) as string); return false; }
+      response.write(encoded); return true;
+    };
+    const unsubscribe = this.#provider.subscribe((event: StreamEvent) => {
+      if (live) { writeEvent(event); return; }
+      if (buffered.length >= MAX_HANDOFF_EVENTS) { handoffOverflow = true; return; }
+      buffered.push(event);
+    });
+    let replay;
+    try { replay = await this.#provider.replay(after, this.#maximumReplayEvents); }
+    catch (error) { unsubscribe(); throw error; }
+    response.statusCode = 200;
+    response.setHeader("Cache-Control", "no-store");
+    response.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+    response.setHeader("Connection", "keep-alive");
+    response.flushHeaders();
+    if (replay.state === "resync-required" || replay.state === "truncated" || handoffOverflow) {
+      unsubscribe();
+      response.end(frame("resync-required", { reasonCode: replay.reasonCode ?? "event-replay-limit", latestCursor: replay.latestCursor }) ?? "event: resync-required\ndata: {}\n\n");
+      return;
+    }
+    const replayed = new Set<string>();
+    for (const event of replay.events) {
+      replayed.add(event.cursor);
+      if (!writeEvent(event)) { unsubscribe(); return; }
+    }
+    live = true;
+    for (const event of buffered) if (!replayed.has(event.cursor) && !writeEvent(event)) { unsubscribe(); return; }
+    response.write("retry: 2000\n\n");
+    this.#clients.add(response);
+    const heartbeat = setInterval(() => { if (!response.destroyed) response.write(": keepalive\n\n"); }, 15_000);
+    heartbeat.unref();
+    const cleanup = () => { clearInterval(heartbeat); unsubscribe(); this.#clients.delete(response); };
+    request.once("close", cleanup); response.once("close", cleanup);
+  }
+
+  close(): void {
+    for (const response of this.#clients) response.end();
+    this.#clients.clear();
+  }
+}

package/packages/piagent-webui/server/static-bundle.ts

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 16 * 1024 * 1024;
+const MIME = new Map([
+  [".css", "text/css; charset=utf-8"], [".html", "text/html; charset=utf-8"],
+  [".js", "text/javascript; charset=utf-8"], [".json", "application/json; charset=utf-8"],
+  [".svg", "image/svg+xml"], [".woff2", "font/woff2"]
+]);
+
+export type StaticAsset = { body: Buffer; contentType: string };
+
+export function loadStaticBundle(root: string): ReadonlyMap<string, StaticAsset> {
+  const absoluteRoot = path.resolve(root), rootStat = fs.lstatSync(absoluteRoot);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error("static-root-invalid");
+  const assets = new Map<string, StaticAsset>();
+  let total = 0;
+  const visit = (directory: string) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const absolute = path.join(directory, entry.name), stat = fs.lstatSync(absolute);
+      if (stat.isSymbolicLink()) throw new Error("static-symlink-rejected");
+      if (entry.isDirectory()) { visit(absolute); continue; }
+      const relative = path.relative(absoluteRoot, absolute).split(path.sep).join("/");
+      const contentType = MIME.get(path.extname(relative));
+      if (!entry.isFile() || !contentType || stat.size > MAX_FILE_BYTES) throw new Error("static-asset-invalid");
+      total += stat.size;
+      if (total > MAX_TOTAL_BYTES) throw new Error("static-bundle-limit");
+      const descriptor = fs.openSync(absolute, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+      try {
+        const opened = fs.fstatSync(descriptor);
+        if (!opened.isFile() || opened.dev !== stat.dev || opened.ino !== stat.ino || opened.size !== stat.size) throw new Error("static-asset-race");
+        assets.set(relative === "index.html" ? "/" : `/${relative}`, { body: fs.readFileSync(descriptor), contentType });
+      } finally { fs.closeSync(descriptor); }
+    }
+  };
+  visit(absoluteRoot);
+  if (!assets.has("/")) throw new Error("static-index-missing");
+  return assets;
+}

package/packages/piagent-webui/server/transcript-projection.ts

@@ -0,0 +1,125 @@
+import { createHash } from "node:crypto";
+
+import { redactSensitiveText } from "../../piagent-core/extensions/redaction-core.js";
+
+const MAX_ENTRIES = 50_000;
+const MAX_ITEMS = 200;
+const MAX_TEXT = 16_384;
+const ANSI = /\u001b(?:[@-_]|\[[0-?]*[ -/]*[@-~])/g;
+
+type TranscriptIdentity = { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string | null; taskRunId: string | null;
+  agentOperationId: null; toolCallId: null };
+type TranscriptRevision = { runtimeRevision: string; taskRevision: string | null; controlRevision: string | null; workspaceRevision: string | null;
+  indexRevision: string | null; approvalRevision: string | null; sessionOptionRevision: string | null; queueRevision: string | null };
+type TranscriptContent = { state: "available" | "redacted" | "unavailable"; text: string | null; textChars: number | null; digest: string | null;
+  truncated: boolean; redacted: boolean; imageCount: number; reasonCode: string | null };
+type TranscriptItem = { messageRef: string; parentMessageRef: string | null; role: "user" | "assistant" | "tool-result"; recordedAt: string;
+  agentOperationId: string | null; turnIndex: number | null; content: TranscriptContent;
+  toolCalls: Array<{ toolCallRef: string; toolName: string; state: "requested" | "completed" | "failed" | "unknown" }> };
+export type TranscriptDocument = { schemaVersion: 1; version: "piagent-webui-transcript-v1"; generatedAt: string; identity: TranscriptIdentity;
+  revision: TranscriptRevision; eventCursor: string; state: "ready" | "unavailable"; items: TranscriptItem[];
+  page: { beforeCursor: string | null; nextBeforeCursor: string | null; hasOlder: boolean; limit: number; truncated: boolean }; reasonCode: string | null };
+
+export type TranscriptProjectionInput = {
+  identity: TranscriptIdentity;
+  revision: TranscriptRevision;
+  eventCursor: string;
+  entries: unknown[];
+  beforeCursor?: string | null;
+  limit?: number;
+  generatedAt?: string;
+};
+
+function hash(value: string): string { return createHash("sha256").update(value).digest("hex"); }
+function opaque(prefix: string, value: unknown): string { return `${prefix}.${hash(JSON.stringify(value))}`; }
+function timestamp(value: unknown): string | null {
+  const parsed = typeof value === "number" && Number.isFinite(value) ? value : typeof value === "string" ? Date.parse(value) : Number.NaN;
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+function messageText(message: any): string {
+  if (typeof message?.content === "string") return message.content;
+  if (!Array.isArray(message?.content)) return "";
+  return message.content.filter((item: any) => item?.type === "text" && typeof item.text === "string").map((item: any) => item.text).join("\n");
+}
+function assistantFailureReason(message: any): string | null {
+  if (message?.role !== "assistant" || message?.stopReason !== "error") return null;
+  const detail = String(message?.errorMessage ?? "").toLowerCase();
+  if (/(?:authentication|auth|token|credential).{0,48}expired|expired.{0,48}(?:authentication|auth|token|credential)/.test(detail)) {
+    return "provider-auth-expired";
+  }
+  if (/(?:authentication|unauthorized|forbidden|credential|api[ _-]?key|log[ -]?in|sign[ -]?in)/.test(detail)) {
+    return "provider-auth-required";
+  }
+  if (/(?:rate[ _-]?limit|too many requests|quota)/.test(detail)) return "provider-rate-limited";
+  if (/(?:network|fetch failed|econn|timed? ?out|unavailable)/.test(detail)) return "provider-unavailable";
+  return "provider-response-failed";
+}
+function safeText(value: string): { full: string; preview: string; redacted: boolean; truncated: boolean } {
+  const clean = value.replace(ANSI, "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ");
+  const redaction = redactSensitiveText(clean);
+  return { full: redaction.text, preview: redaction.text.slice(0, MAX_TEXT), redacted: redaction.redacted,
+    truncated: redaction.text.length > MAX_TEXT };
+}
+function safeToolName(value: unknown): string {
+  const projected = safeText(String(value ?? "tool"));
+  if (projected.redacted) return "redacted-tool";
+  return projected.full.replace(/[^A-Za-z0-9._:@~-]/g, "-").replace(/^[^A-Za-z0-9]+/, "").slice(0, 80) || "tool";
+}
+function imageCount(message: any): number {
+  return Array.isArray(message?.content) ? Math.min(32, message.content.filter((item: any) => item?.type === "image").length) : 0;
+}
+function toolCalls(message: any, sessionRef: string, role: TranscriptItem["role"]): TranscriptItem["toolCalls"] {
+  const values: Array<{ id: unknown; name: unknown; state: "requested" | "completed" | "failed" | "unknown" }> = [];
+  if (role === "assistant" && Array.isArray(message?.content)) {
+    for (const item of message.content) if (item?.type === "toolCall") values.push({ id: item.id, name: item.name, state: "requested" });
+  } else if (role === "tool-result") {
+    values.push({ id: message?.toolCallId, name: message?.toolName, state: message?.isError ? "failed" : "completed" });
+  }
+  return values.slice(0, 64).map((item, index) => {
+    return { toolCallRef: opaque("tool", [sessionRef, item.id ?? index]), toolName: safeToolName(item.name), state: item.state };
+  });
+}
+function role(message: any): TranscriptItem["role"] | null {
+  return message?.role === "user" ? "user" : message?.role === "assistant" ? "assistant" : message?.role === "toolResult" ? "tool-result" : null;
+}
+function unavailableContent(reasonCode: string): TranscriptContent {
+  return { state: "unavailable", text: null, textChars: null, digest: null, truncated: false, redacted: false, imageCount: 0, reasonCode };
+}
+function item(entry: any, identity: TranscriptIdentity): TranscriptItem | null {
+  if (!entry || entry.type !== "message" || !entry.message) return null;
+  const itemRole = role(entry.message), recordedAt = timestamp(entry.timestamp ?? entry.message.timestamp);
+  if (!itemRole || !recordedAt || typeof entry.id !== "string" || entry.id.length === 0) return null;
+  const content = itemRole === "tool-result" ? unavailableContent("tool-output-in-activity-preview") : (() => {
+    const projected = safeText(messageText(entry.message));
+    const failureReason = projected.full.length === 0 ? assistantFailureReason(entry.message) : null;
+    if (failureReason) return unavailableContent(failureReason);
+    return { state: projected.redacted ? "redacted" as const : "available" as const, text: projected.preview,
+      textChars: Math.min(1_000_000_000, projected.full.length), digest: `sha256:${hash(projected.full)}`, truncated: projected.truncated,
+      redacted: projected.redacted, imageCount: imageCount(entry.message), reasonCode: projected.redacted ? "sensitive-values-redacted" as const : null };
+  })();
+  return { messageRef: opaque("message", [identity.sessionRef, entry.id]), parentMessageRef: null, role: itemRole, recordedAt,
+    agentOperationId: null, turnIndex: null, content, toolCalls: toolCalls(entry.message, identity.sessionRef, itemRole) };
+}
+function unavailable(input: TranscriptProjectionInput, reasonCode: string, limit: number): TranscriptDocument {
+  return { schemaVersion: 1, version: "piagent-webui-transcript-v1", generatedAt: input.generatedAt ?? new Date().toISOString(),
+    identity: structuredClone(input.identity), revision: structuredClone(input.revision), eventCursor: input.eventCursor,
+    state: "unavailable", items: [], page: { beforeCursor: input.beforeCursor ?? null, nextBeforeCursor: null, hasOlder: false, limit, truncated: false }, reasonCode };
+}
+
+export function projectTranscript(input: TranscriptProjectionInput): TranscriptDocument {
+  const limit = Math.max(1, Math.min(MAX_ITEMS, Number.isInteger(input.limit) ? Number(input.limit) : 50));
+  if (!Array.isArray(input.entries) || input.entries.length > MAX_ENTRIES) return unavailable(input, "transcript-history-unavailable", limit);
+  const projected = input.entries.map((entry) => ({ entry, item: item(entry, input.identity) })).filter((value): value is { entry: any; item: TranscriptItem } => Boolean(value.item));
+  const cursors = projected.map(({ entry }) => opaque("transcript", [input.identity.sessionRef, entry.id]));
+  let end = projected.length;
+  if (input.beforeCursor) {
+    const cursorIndex = cursors.indexOf(input.beforeCursor);
+    if (cursorIndex < 0) return unavailable(input, "transcript-cursor-gap", limit);
+    end = cursorIndex;
+  }
+  const start = Math.max(0, end - limit), selected = projected.slice(start, end).map((value) => value.item), hasOlder = start > 0;
+  return { schemaVersion: 1, version: "piagent-webui-transcript-v1", generatedAt: input.generatedAt ?? new Date().toISOString(),
+    identity: structuredClone(input.identity), revision: structuredClone(input.revision), eventCursor: input.eventCursor,
+    state: "ready", items: selected, page: { beforeCursor: input.beforeCursor ?? null, nextBeforeCursor: hasOlder ? cursors[start] : null,
+      hasOlder, limit, truncated: projected.length !== input.entries.filter((entry: any) => entry?.type === "message").length }, reasonCode: null };
+}

package/schemas/mutation-provenance-record.schema.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://piagent.io.vn/schemas/mutation-provenance-record.schema.json",
+  "title": "Piagent mutation provenance record v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion", "version", "recordId", "evidenceRef", "taskId", "taskRunId",
+    "sessionIdentityHash", "toolCallIdentityHash", "toolName", "recordedAt", "evidenceMode",
+    "beforeTreeDigest", "afterTreeDigest", "changes", "integrityDigest"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "version": { "const": "piagent-mutation-provenance-v1" },
+    "recordId": { "type": "string", "pattern": "^provenance\\.[a-f0-9]{64}$" },
+    "evidenceRef": { "type": "string", "pattern": "^mutation\\.[a-f0-9]{64}$" },
+    "taskId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@~-]*$" },
+    "taskRunId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@~-]*$" },
+    "sessionIdentityHash": { "$ref": "#/$defs/digest" },
+    "toolCallIdentityHash": { "$ref": "#/$defs/digest" },
+    "toolName": { "enum": ["edit", "write", "apply_patch", "shell", "opaque"] },
+    "recordedAt": { "type": "string", "format": "date-time", "maxLength": 32 },
+    "evidenceMode": { "enum": ["exact-runtime", "observed-runtime"] },
+    "beforeTreeDigest": { "$ref": "#/$defs/treeDigest" },
+    "afterTreeDigest": { "$ref": "#/$defs/treeDigest" },
+    "changes": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 100,
+      "items": { "$ref": "#/$defs/change" }
+    },
+    "integrityDigest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "treeDigest": { "type": "string", "pattern": "^wt-content-v2:[a-f0-9]{64}$" },
+    "carrierDigest": { "type": "string", "pattern": "^wt-content-v2:[a-f0-9]{64}$" },
+    "change": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "pathDigest", "repoPathBase64", "beforeCarrierDigest", "afterCarrierDigest",
+        "afterContentDigest", "proofMode", "effect"
+      ],
+      "properties": {
+        "pathDigest": { "$ref": "#/$defs/digest" },
+        "repoPathBase64": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^[A-Za-z0-9_-]+$" },
+        "beforeCarrierDigest": {
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/carrierDigest" }]
+        },
+        "afterCarrierDigest": {
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/carrierDigest" }]
+        },
+        "afterContentDigest": {
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/digest" }]
+        },
+        "proofMode": {
+          "oneOf": [{ "type": "null" }, { "enum": ["full-content", "exact-replacement"] }]
+        },
+        "effect": { "enum": ["exact-content", "content-preserved", "content-changed", "unknown"] }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "evidenceMode": { "const": "exact-runtime" } }, "required": ["evidenceMode"] },
+      "then": {
+        "properties": {
+          "toolName": { "enum": ["edit", "write", "apply_patch"] },
+          "changes": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "afterCarrierDigest": { "$ref": "#/$defs/carrierDigest" },
+                "afterContentDigest": { "$ref": "#/$defs/digest" },
+                "proofMode": { "enum": ["full-content", "exact-replacement"] },
+                "effect": { "const": "exact-content" }
+              }
+            }
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "changes": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "proofMode": { "type": "null" },
+                "effect": { "enum": ["content-preserved", "content-changed", "unknown"] }
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}