@piagent/platform 1.3.1 → 1.4.0

package/packages/piagent-webui/extension/session-options-controller.ts

@@ -0,0 +1,281 @@
+import { createHash, randomBytes } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { redactSensitiveText } from "../../piagent-core/extensions/redaction-core.js";
+import { webUiModelRef } from "../../piagent-core/runtime/inspection/webui-snapshot.ts";
+import { controlActionDigest, type BridgeIdentity, type BridgeRevisions, type SameSessionPiBridge,
+  type SessionOptionMutationPermit } from "./same-session-bridge.ts";
+
+export const WEBUI_SESSION_OPTION_ENTRY_TYPE = "piagent-webui-session-option-v1";
+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 IDEMPOTENCY = /^[A-Za-z0-9._~-]{32,128}$/;
+const THINKING = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+type ThinkingLevel = typeof THINKING[number];
+type SessionOptionAction = "session-options.set-model" | "session-options.set-thinking";
+type ModelLike = { provider?: unknown; id?: unknown; name?: unknown; reasoning?: unknown; input?: unknown; thinkingLevelMap?: unknown;
+  contextWindow?: unknown; maxTokens?: unknown };
+type Command = {
+  schemaVersion: 1; version: "piagent-webui-control-v1"; messageType: "command"; commandId: string; idempotencyKey: string;
+  requestedAt: string; expiresAt: string; capabilityScope: "control.sessionOptions"; action: SessionOptionAction; actionDigest: string;
+  identity: BridgeIdentity; expectedRevisions: BridgeRevisions & { workspacePreimage: null; indexPreimage: null; patchPreimage: null };
+  payload: { effectScopeAcknowledged: "session-and-user-default"; modelRef?: string; thinkingLevel?: ThinkingLevel };
+};
+export type SessionOptionReceipt = {
+  schemaVersion: 1; version: "piagent-webui-control-v1"; messageType: "receipt"; commandId: string; idempotencyKeyDigest: string;
+  action: SessionOptionAction; actionDigest: string; identity: BridgeIdentity; phase: "settled" | "rejected" | "uncertain";
+  resultCode: "changed" | "unchanged" | "effect-unknown" | "stale-revision" | "identity-mismatch" | "capability-unavailable"
+    | "replay" | "idempotency-payload-mismatch" | "expired" | "invalid-command" | "resync-required";
+  requestedAt: string; settledAt: string; observedRevisionsBefore: BridgeRevisions; observedRevisionsAfter: BridgeRevisions;
+  deduplicated: boolean; auditRef: null; settlementEvidenceRef: string | null;
+  error: { code: string; message: string; retryable: false } | null;
+};
+type CatalogModel = { modelRef: string; provider: string; modelId: string; displayName: string; reasoning: boolean;
+  inputCapabilities: Array<"text" | "image">; supportedThinkingLevels: ThinkingLevel[]; contextWindow: number; maxOutputTokens: number };
+
+function sha(value: string): string { return `sha256:${createHash("sha256").update(value).digest("hex")}`; }
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(",")}}`;
+  return JSON.stringify(value);
+}
+function same(left: unknown, right: unknown): boolean { return canonical(left) === canonical(right); }
+function exactKeys(value: unknown, keys: string[]): boolean {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value)
+    && same(Object.keys(value as object).sort(), [...keys].sort()));
+}
+function timestamp(value: unknown): value is string {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)) return false;
+  const parsed = Date.parse(value); return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+function copy<T>(value: T): T { return structuredClone(value); }
+function validIdentity(value: unknown): value is BridgeIdentity {
+  if (!exactKeys(value, ["projectRef", "runtimeInstanceId", "sessionRef", "taskId", "taskRunId", "agentOperationId", "toolCallId"])) return false;
+  const identity = value as BridgeIdentity;
+  return [identity.projectRef, identity.runtimeInstanceId, identity.sessionRef].every((item) => typeof item === "string" && REF.test(item))
+    && [identity.taskId, identity.taskRunId].every((item) => item === null || PUBLIC_REF.test(item))
+    && (identity.taskRunId === null || identity.taskId !== null) && (identity.agentOperationId === null || REF.test(identity.agentOperationId))
+    && identity.toolCallId === null;
+}
+function validRevisions(value: unknown): value is Command["expectedRevisions"] {
+  if (!exactKeys(value, ["runtimeRevision", "taskRevision", "controlRevision", "workspaceRevision", "indexRevision", "approvalRevision",
+    "sessionOptionRevision", "queueRevision", "workspacePreimage", "indexPreimage", "patchPreimage"])) return false;
+  const revisions = value as Command["expectedRevisions"];
+  return REVISION.test(revisions.runtimeRevision) && [revisions.taskRevision, revisions.controlRevision, revisions.workspaceRevision,
+    revisions.indexRevision, revisions.approvalRevision, revisions.sessionOptionRevision, revisions.queueRevision]
+    .every((item) => item === null || REVISION.test(item)) && revisions.workspacePreimage === null && revisions.indexPreimage === null
+    && revisions.patchPreimage === null;
+}
+function safeName(value: unknown, fallback: string): string {
+  return redactSensitiveText(String(value ?? fallback)).text.replace(/[\u0000-\u001F\u007F]/g, " ").replace(/\s+/g, " ").trim().slice(0, 160) || fallback;
+}
+function safePublicId(value: unknown): string | null {
+  if (typeof value !== "string" || !PUBLIC_REF.test(value)) return null;
+  return redactSensitiveText(value).redacted ? null : value;
+}
+function positive(value: unknown): number | null {
+  return Number.isInteger(value) && Number(value) >= 1 && Number(value) <= 100_000_000 ? Number(value) : null;
+}
+function thinkingLevels(model: ModelLike): ThinkingLevel[] {
+  if (model.reasoning !== true) return ["off"];
+  const mapping = model.thinkingLevelMap && typeof model.thinkingLevelMap === "object" ? model.thinkingLevelMap as Record<string, unknown> : {};
+  const levels = THINKING.filter((level) => mapping[level] !== null && !(["xhigh", "max"].includes(level) && mapping[level] === undefined));
+  return levels.length ? [...levels] : ["off"];
+}
+function catalogModel(value: ModelLike): CatalogModel | null {
+  const provider = safePublicId(value.provider), modelId = safePublicId(value.id);
+  const contextWindow = positive(value.contextWindow), maxOutputTokens = positive(value.maxTokens);
+  if (!provider || !modelId || typeof value.reasoning !== "boolean" || !contextWindow || !maxOutputTokens) return null;
+  const inputCapabilities = Array.isArray(value.input) ? [...new Set(value.input.filter((item): item is "text" | "image" => item === "text" || item === "image"))] : [];
+  return { modelRef: webUiModelRef(provider, modelId), provider, modelId, displayName: safeName(value.name, modelId), reasoning: value.reasoning,
+    inputCapabilities, supportedThinkingLevels: thinkingLevels(value), contextWindow, maxOutputTokens };
+}
+
+export class SessionOptionsController {
+  readonly #pi: ExtensionAPI;
+  readonly #bridge: SameSessionPiBridge;
+  readonly #now: () => Date;
+  #ctx: ExtensionContext | null = null;
+  #models = new Map<string, ModelLike>();
+  #receiptsByKey = new Map<string, SessionOptionReceipt>();
+  #receiptsByCommand = new Map<string, SessionOptionReceipt>();
+  #serial: Promise<unknown> = Promise.resolve();
+  readonly #hostMutation = new AsyncLocalStorage<symbol>();
+  #activeHostMutation: symbol | null = null;
+
+  constructor(options: { pi: ExtensionAPI; bridge: SameSessionPiBridge; now?: () => Date }) {
+    this.#pi = options.pi; this.#bridge = options.bridge; this.#now = options.now ?? (() => new Date());
+  }
+  bind(ctx: ExtensionContext): void { this.#ctx = ctx; this.#models.clear(); this.#receiptsByKey.clear(); this.#receiptsByCommand.clear(); }
+  refresh(ctx: ExtensionContext): void { if (this.#bridge.refresh(ctx)) this.#ctx = ctx; }
+  observeHostOptionChange(ctx: ExtensionContext): void {
+    const causal = this.#activeHostMutation !== null && this.#hostMutation.getStore() === this.#activeHostMutation;
+    this.#bridge.observeSessionOptionChange(ctx, causal); this.refresh(ctx);
+  }
+  reset(): void { this.#ctx = null; this.#models.clear(); this.#receiptsByKey.clear(); this.#receiptsByCommand.clear(); }
+
+  catalog(): Record<string, unknown> {
+    const snapshot = this.#bridge.snapshot();
+    if (!this.#ctx || snapshot.state !== "ready" || !snapshot.identity || !snapshot.revisions) throw new Error("webui-session-options-binding-unavailable");
+    const values = this.#availableModels(this.#ctx), projected: CatalogModel[] = []; this.#models.clear();
+    for (const value of values.slice(0, 300)) {
+      const model = catalogModel(value); if (!model || this.#models.has(model.modelRef)) continue;
+      this.#models.set(model.modelRef, value); projected.push(model);
+    }
+    projected.sort((a, b) => `${a.provider}/${a.modelId}`.localeCompare(`${b.provider}/${b.modelId}`));
+    const active = catalogModel(this.#ctx.model as ModelLike), thinking = this.#currentThinking();
+    const ready = Boolean(active && this.#models.has(active.modelRef) && THINKING.includes(thinking as ThinkingLevel) && projected.length);
+    return { schemaVersion: 1, version: "piagent-webui-model-catalog-v1", generatedAt: this.#now().toISOString(), identity: snapshot.identity,
+      revision: snapshot.revisions, state: ready ? "ready" : "unavailable",
+      catalogScope: ready ? (this.#ctx.scopedModels.length ? "session-scoped" : "authenticated-all") : "unavailable",
+      effectScope: "session-and-user-default", activeModelRef: ready ? active!.modelRef : null, activeThinkingLevel: ready ? thinking : null,
+      models: ready ? projected : [], reasonCode: ready ? null : "authenticated-model-catalog-unavailable" };
+  }
+
+  execute(input: unknown): Promise<SessionOptionReceipt> {
+    const run = this.#serial.then(() => this.#execute(input), () => this.#execute(input)); this.#serial = run.catch(() => undefined); return run;
+  }
+
+  async #execute(input: unknown): Promise<SessionOptionReceipt> {
+    const command = input as Command, snapshot = this.#bridge.snapshot(), structural = this.#validate(command);
+    if (!this.#ctx || snapshot.state !== "ready" || !snapshot.identity || !snapshot.revisions)
+      return this.#reject(command, "resync-required", "session-options-binding-not-ready", "The current Pi session option binding is unavailable.");
+    if (structural) return this.#reject(command, "invalid-command", structural, "The session option command is invalid.");
+    const keyDigest = sha(command.idempotencyKey), old = this.#receiptsByKey.get(keyDigest) ?? this.#receiptsByCommand.get(command.commandId);
+    if (old) {
+      if (old.commandId !== command.commandId || old.actionDigest !== command.actionDigest || old.idempotencyKeyDigest !== keyDigest)
+        return this.#reject(command, "idempotency-payload-mismatch", "idempotency-payload-mismatch", "The command key is bound to another option change.");
+      return { ...copy(old), deduplicated: true };
+    }
+    const now = this.#now().getTime();
+    if (Date.parse(command.requestedAt) > now + 30_000) return this.#reject(command, "invalid-command", "requested-at-in-future", "The command timestamp is not yet valid.");
+    if (now > Date.parse(command.expiresAt)) return this.#reject(command, "expired", "command-expired", "The command expired before execution.");
+    if (!same(command.identity, snapshot.identity)) return this.#reject(command, "identity-mismatch", "identity-mismatch", "The command targets another Pi session.");
+    if (!["runtimeRevision", "taskRevision", "controlRevision", "sessionOptionRevision"].every((key) =>
+      (command.expectedRevisions as any)[key] === (snapshot.revisions as any)[key]))
+      return this.#reject(command, "stale-revision", "stale-revision", "The Pi session option state changed before execution.");
+    if (snapshot.liveness !== "idle" || !this.#ctx.isIdle() || snapshot.identity.agentOperationId)
+      return this.#reject(command, "capability-unavailable", "agent-not-idle", "Model and thinking can change only while Pi is idle.");
+    this.catalog();
+    const permit = this.#bridge.beginSessionOptionMutation(), ctx = this.#ctx;
+    if (!permit) return this.#reject(command, "capability-unavailable", "session-option-linearization-unavailable", "Pi is no longer at an idle option-change boundary.");
+    try { return command.action === "session-options.set-model" ? await this.#setModel(command, ctx, permit) : this.#setThinking(command, ctx, permit); }
+    finally { permit.release(); }
+  }
+
+  async #setModel(command: Command, ctx: ExtensionContext, permit: SessionOptionMutationPermit): Promise<SessionOptionReceipt> {
+    const model = this.#models.get(command.payload.modelRef!);
+    if (!model) return this.#reject(command, "capability-unavailable", "model-not-selectable", "The selected model is not in the authenticated Pi catalog.");
+    const beforeRef = catalogModel(ctx.model as ModelLike)?.modelRef ?? null;
+    let result: "changed" | "unchanged" | "effect-unknown" = beforeRef === command.payload.modelRef ? "unchanged" : "changed";
+    if (result === "changed") {
+      const token = Symbol("webui-session-option"); this.#activeHostMutation = token;
+      try {
+        const accepted = await this.#hostMutation.run(token, () => this.#pi.setModel(model as any));
+        const actual = catalogModel(ctx.model as ModelLike)?.modelRef ?? null;
+        if (!accepted || actual !== command.payload.modelRef) result = "effect-unknown";
+      } catch { result = "effect-unknown"; } finally { this.#activeHostMutation = null; }
+    }
+    return this.#settle(command, result, permit);
+  }
+
+  #setThinking(command: Command, ctx: ExtensionContext, permit: SessionOptionMutationPermit): SessionOptionReceipt {
+    const target = command.payload.thinkingLevel!, active = catalogModel(ctx.model as ModelLike);
+    if (!active?.supportedThinkingLevels.includes(target))
+      return this.#reject(command, "capability-unavailable", "thinking-level-not-supported", "The active model does not support this thinking level.");
+    const before = this.#thinkingFor(ctx); let result: "changed" | "unchanged" | "effect-unknown" = before === target ? "unchanged" : "changed";
+    if (result === "changed") {
+      const token = Symbol("webui-session-option"); this.#activeHostMutation = token;
+      try { this.#hostMutation.run(token, () => this.#pi.setThinkingLevel(target as any)); if (this.#thinkingFor(ctx) !== target) result = "effect-unknown"; }
+      catch { result = "effect-unknown"; } finally { this.#activeHostMutation = null; }
+    }
+    return this.#settle(command, result, permit);
+  }
+
+  #settle(command: Command, result: "changed" | "unchanged" | "effect-unknown", permit: SessionOptionMutationPermit): SessionOptionReceipt {
+    const evidenceRef = `session-option-evidence.${randomBytes(24).toString("hex")}`; let receipt: SessionOptionReceipt | null = null;
+    const observation = permit.commitObservation((before, after) => {
+      receipt = this.#receipt(command, before, after, result === "effect-unknown" ? "uncertain" : "settled", result,
+        result === "effect-unknown" ? { code: "session-option-effect-unconfirmed", message: "Pi did not expose the requested active setting after the change.", retryable: false } : null,
+        result === "effect-unknown" ? null : evidenceRef);
+      this.#pi.appendEntry(WEBUI_SESSION_OPTION_ENTRY_TYPE, { schemaVersion: 1, evidenceRef, action: command.action,
+        targetRef: command.action === "session-options.set-model" ? command.payload.modelRef : command.payload.thinkingLevel,
+        resultCode: result, sessionOptionRevision: after.sessionOptionRevision });
+    });
+    if (!observation) {
+      const before = this.#domainRevisions(command.expectedRevisions), after = this.#bridge.snapshot().revisions ?? before;
+      return this.#receipt(command, before, after, "uncertain", "effect-unknown",
+        { code: "session-option-binding-lost", message: "The session binding changed while the setting was being applied.", retryable: false }, null);
+    }
+    if (!receipt) return this.#receipt(command, observation.before, observation.after, "uncertain", "effect-unknown",
+      { code: "session-option-concurrent-selection", message: "A native Pi selection raced this WebUI setting change.", retryable: false }, null);
+    if (!observation.recorded) receipt = this.#receipt(command, observation.before, observation.after, "uncertain", "effect-unknown",
+      { code: "session-option-evidence-unavailable", message: "The setting may have changed, but its local evidence could not be recorded.", retryable: false }, null);
+    return this.#remember(receipt);
+  }
+
+  #validate(command: Command): string | null {
+    if (!command || typeof command !== "object" || command.schemaVersion !== 1 || command.version !== "piagent-webui-control-v1"
+      || command.messageType !== "command" || command.capabilityScope !== "control.sessionOptions"
+      || !["session-options.set-model", "session-options.set-thinking"].includes(command.action)) return "unsupported-command-shape";
+    if (!exactKeys(command, ["schemaVersion", "version", "messageType", "commandId", "idempotencyKey", "requestedAt", "expiresAt", "capabilityScope",
+      "action", "actionDigest", "identity", "expectedRevisions", "payload"]) || !validIdentity(command.identity) || !validRevisions(command.expectedRevisions)
+      || !REF.test(command.commandId) || !IDEMPOTENCY.test(command.idempotencyKey) || !timestamp(command.requestedAt) || !timestamp(command.expiresAt)
+      || !REVISION.test(command.expectedRevisions.sessionOptionRevision ?? "")
+      || Date.parse(command.requestedAt) > Date.parse(command.expiresAt) || Date.parse(command.expiresAt) - Date.parse(command.requestedAt) > 300_000)
+      return "invalid-command-metadata";
+    const expectedPayload = command.action === "session-options.set-model" ? ["modelRef", "effectScopeAcknowledged"] : ["thinkingLevel", "effectScopeAcknowledged"];
+    if (!exactKeys(command.payload, expectedPayload) || command.payload.effectScopeAcknowledged !== "session-and-user-default") return "effect-scope-not-acknowledged";
+    if (command.action === "session-options.set-model" && (typeof command.payload.modelRef !== "string" || !REF.test(command.payload.modelRef))) return "invalid-model-ref";
+    if (command.action === "session-options.set-thinking" && !THINKING.includes(command.payload.thinkingLevel as ThinkingLevel)) return "invalid-thinking-level";
+    if (!DIGEST.test(command.actionDigest) || command.actionDigest !== controlActionDigest(command)) return "action-digest-mismatch";
+    return null;
+  }
+
+  #receipt(command: Command, before: BridgeRevisions, after: BridgeRevisions, phase: "settled" | "uncertain",
+    resultCode: "changed" | "unchanged" | "effect-unknown", error: SessionOptionReceipt["error"], evidence: string | null): SessionOptionReceipt {
+    return { schemaVersion: 1, version: "piagent-webui-control-v1", messageType: "receipt", commandId: command.commandId,
+      idempotencyKeyDigest: sha(command.idempotencyKey), action: command.action, actionDigest: command.actionDigest, identity: copy(command.identity),
+      phase, resultCode, requestedAt: command.requestedAt, settledAt: this.#now().toISOString(), observedRevisionsBefore: copy(before),
+      observedRevisionsAfter: copy(after), deduplicated: false, auditRef: null, settlementEvidenceRef: evidence, error };
+  }
+  #reject(command: Command, resultCode: SessionOptionReceipt["resultCode"], code: string, message: string): SessionOptionReceipt {
+    const snapshot = this.#bridge.snapshot(), identity = validIdentity(command?.identity) ? command.identity : snapshot.identity ?? {
+      projectRef: "project.unavailable", runtimeInstanceId: "runtime.unavailable", sessionRef: "session.unavailable", taskId: null, taskRunId: null,
+      agentOperationId: null, toolCallId: null };
+    const revisions = snapshot.revisions ?? { runtimeRevision: "runtime-rev.unavailable", taskRevision: null, controlRevision: null,
+      workspaceRevision: null, indexRevision: null, approvalRevision: null, sessionOptionRevision: null, queueRevision: null };
+    const action = ["session-options.set-model", "session-options.set-thinking"].includes(command?.action) ? command.action : "session-options.set-model";
+    return { schemaVersion: 1, version: "piagent-webui-control-v1", messageType: "receipt", commandId: REF.test(command?.commandId ?? "") ? command.commandId : "command.invalid",
+      idempotencyKeyDigest: IDEMPOTENCY.test(command?.idempotencyKey ?? "") ? sha(command.idempotencyKey) : sha("invalid-idempotency"), action,
+      actionDigest: DIGEST.test(command?.actionDigest ?? "") ? command.actionDigest : sha(code), identity: copy(identity), phase: "rejected", resultCode,
+      requestedAt: timestamp(command?.requestedAt) ? command.requestedAt : this.#now().toISOString(), settledAt: this.#now().toISOString(),
+      observedRevisionsBefore: copy(revisions), observedRevisionsAfter: copy(revisions), deduplicated: resultCode === "replay", auditRef: null,
+      settlementEvidenceRef: null, error: { code, message, retryable: false } };
+  }
+  #remember(receipt: SessionOptionReceipt): SessionOptionReceipt {
+    this.#receiptsByKey.set(receipt.idempotencyKeyDigest, copy(receipt)); this.#receiptsByCommand.set(receipt.commandId, copy(receipt)); return receipt;
+  }
+  #domainRevisions(value: BridgeRevisions): BridgeRevisions {
+    return { runtimeRevision: value.runtimeRevision, taskRevision: value.taskRevision, controlRevision: value.controlRevision,
+      workspaceRevision: value.workspaceRevision, indexRevision: value.indexRevision, approvalRevision: value.approvalRevision,
+      sessionOptionRevision: value.sessionOptionRevision, queueRevision: value.queueRevision };
+  }
+  #currentThinking(): ThinkingLevel | null {
+    return this.#ctx ? this.#thinkingFor(this.#ctx) : null;
+  }
+  #thinkingFor(ctx: ExtensionContext): ThinkingLevel | null {
+    const value = ctx.thinkingLevel ?? this.#pi.getThinkingLevel(); return THINKING.includes(value as ThinkingLevel) ? value as ThinkingLevel : null;
+  }
+  #availableModels(ctx: ExtensionContext): ModelLike[] {
+    const available = ctx.modelRegistry.getAvailable() as ModelLike[];
+    if (!ctx.scopedModels.length) return available;
+    const scope = new Set(ctx.scopedModels.map((item: any) => `${item.model?.provider}\0${item.model?.id}`));
+    return available.filter((item) => scope.has(`${item.provider}\0${item.id}`));
+  }
+}

package/packages/piagent-webui/extension/session-stream-adapter.ts

@@ -0,0 +1,249 @@
+import { createHash } from "node:crypto";
+
+import { redactSensitiveText } from "../../piagent-core/extensions/redaction-core.js";
+import type { RuntimeEventDraft, RuntimeEventRevision } from "../../piagent-core/runtime/inspection/runtime-event-store.ts";
+import type { BridgeIdentity, BridgeSnapshot } from "./same-session-bridge.ts";
+
+const MAX_STREAM_BUFFER = 65_536;
+const MAX_DELTA = 16_384;
+const MAX_MESSAGE_STREAM_EVENTS = 128;
+const STREAM_FLUSH_CHARS = 1_024;
+const STREAM_FLUSH_INTERVAL_MS = 100;
+const ANSI = /\u001b(?:[@-_]|\[[0-?]*[ -/]*[@-~])/g;
+const PRIVATE_KEY_BEGIN = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
+const PRIVATE_KEY_END = /-----END [A-Z ]*PRIVATE KEY-----/;
+
+type MessageRole = "user" | "assistant" | "tool-result";
+type ActiveMessage = { ref: string; role: MessageRole; rawBuffer: string; chunkSequence: number; truncated: boolean;
+  emittedEvents: number; lastFlushAt: number; thinking: Set<number>; thinkingStreaming: Set<number>; thinkingCompleted: Set<number> };
+
+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 digest(value: string): string { return `sha256:${hash(value)}`; }
+function controls(value: string): string {
+  return value.replace(ANSI, "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ");
+}
+function safe(value: unknown, maximum = 4_000): { text: string; redacted: boolean; truncated: boolean } {
+  const source = controls(String(value ?? "")), begin = source.search(PRIVATE_KEY_BEGIN);
+  const incompleteKey = begin >= 0 && !PRIVATE_KEY_END.test(source.slice(begin));
+  const protectedSource = incompleteKey ? `${source.slice(0, begin)}[REDACTED_SECRET]` : source;
+  const projected = redactSensitiveText(protectedSource);
+  return { text: projected.text.slice(0, maximum), redacted: incompleteKey || projected.redacted, truncated: projected.text.length > maximum };
+}
+function safeToolName(value: unknown): string {
+  const projected = safe(value, 128);
+  if (projected.redacted) return "redacted-tool";
+  return projected.text.replace(/[^A-Za-z0-9._:-]/g, "-").replace(/^[^A-Za-z0-9]+/, "").slice(0, 128) || "tool";
+}
+function role(message: any): MessageRole | null {
+  return message?.role === "user" ? "user" : message?.role === "assistant" ? "assistant" : message?.role === "toolResult" ? "tool-result" : null;
+}
+function text(message: any): string {
+  if (typeof message?.content === "string") return message.content;
+  return Array.isArray(message?.content) ? message.content.filter((item: any) => item?.type === "text" && typeof item.text === "string")
+    .map((item: any) => item.text).join("\n") : "";
+}
+function imageCount(message: any): number {
+  return Array.isArray(message?.content) ? Math.min(32, message.content.filter((item: any) => item?.type === "image").length) : 0;
+}
+function stopReason(message: any): "pending" | "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred" | null {
+  return ["pending", "stop", "length", "toolUse", "error", "aborted", "deferred"].includes(message?.stopReason) ? message.stopReason : null;
+}
+function usage(message: any) {
+  const value = message?.usage;
+  if (!value || typeof value !== "object") return null;
+  const count = (candidate: unknown): number | null => typeof candidate === "number" && Number.isFinite(candidate) && candidate >= 0
+    ? Math.min(1_000_000_000_000, Math.floor(candidate)) : null;
+  return { input: count(value.input), output: count(value.output), cacheRead: count(value.cacheRead), cacheWrite: count(value.cacheWrite),
+    reasoning: count(value.reasoning), total: count(value.totalTokens ?? value.total) };
+}
+function timestamp(value: unknown, now: Date): string {
+  const parsed = typeof value === "number" && Number.isFinite(value) ? value : typeof value === "string" ? Date.parse(value) : Number.NaN;
+  return Number.isFinite(parsed) && parsed <= now.getTime() ? new Date(parsed).toISOString() : now.toISOString();
+}
+function correlation() {
+  return { commandId: null, messageRequestId: null, replacementId: null, approvalRequestId: null, causationEventId: null, idempotencyKeyDigest: null };
+}
+function redaction(applied = false, truncated = false) { return { applied, valuesRemoved: applied ? 1 : 0, truncated }; }
+function identityReady(identity: BridgeIdentity | null): identity is BridgeIdentity & { agentOperationId: string } {
+  return Boolean(identity?.agentOperationId);
+}
+function activityPayload(state: "started" | "progress" | "finished" | "failed", activityRef: string, toolName: string) {
+  return { state, activityType: "tool", activityRef, toolName, inputDigest: null, outputDigest: null, preview: null, previewKind: "none",
+    outputBytes: null, outputLines: null, exitCode: null, isError: state === "finished" ? false : state === "failed" ? true : null,
+    affectedFileRefs: [], criterionIds: [], verifierAttemptIds: [], reasonCode: state === "failed" ? "tool-execution-failed" : null };
+}
+
+export class PiSessionStreamAdapter {
+  readonly #now: () => Date;
+  #turnIndex: number | null = null;
+  #messageCounter = 0;
+  #activeByRole = new Map<MessageRole, ActiveMessage>();
+  #lastMessageRef: string | null = null;
+  #toolRefs = new Map<string, string>();
+  #lastToolProgress = new Map<string, number>();
+
+  constructor(options: { now?: () => Date } = {}) { this.#now = options.now ?? (() => new Date()); }
+  reset(): void {
+    this.#turnIndex = null; this.#messageCounter = 0; this.#activeByRole.clear(); this.#lastMessageRef = null;
+    this.#toolRefs.clear(); this.#lastToolProgress.clear();
+  }
+
+  #base(snapshot: BridgeSnapshot, sourceObservedAt?: unknown): Omit<RuntimeEventDraft, "kind" | "payload" | "evidence" | "redaction"> | null {
+    if (!snapshot.revisions || !identityReady(snapshot.identity)) return null;
+    const now = this.#now(), identity = snapshot.identity;
+    return { sourceObservedAt: timestamp(sourceObservedAt, now), projectRef: identity.projectRef, runtimeInstanceId: identity.runtimeInstanceId,
+      sessionRef: identity.sessionRef, taskId: identity.taskId, taskRunId: identity.taskRunId, agentOperationId: identity.agentOperationId,
+      turnIndex: this.#turnIndex, messageRef: null, toolCallId: null, revision: structuredClone(snapshot.revisions) as RuntimeEventRevision, correlation: correlation() };
+  }
+  #draft(snapshot: BridgeSnapshot, kind: string, payload: Record<string, unknown>, options: { sourceObservedAt?: unknown; messageRef?: string;
+    toolCallId?: string; redacted?: boolean; truncated?: boolean; evidence?: "observed" | "derived" } = {}): RuntimeEventDraft | null {
+    const base = this.#base(snapshot, options.sourceObservedAt); if (!base) return null;
+    return { ...base, messageRef: options.messageRef ?? null, toolCallId: options.toolCallId ?? null, kind,
+      evidence: options.evidence ?? "observed", payload, redaction: redaction(options.redacted, options.truncated) };
+  }
+
+  agentStarted(snapshot: BridgeSnapshot): RuntimeEventDraft[] {
+    const draft = this.#draft(snapshot, "agent-operation.started", { dispatchSource: "unknown", delivery: "unknown", inputDigest: null });
+    return draft ? [draft] : [];
+  }
+  turnStarted(event: { turnIndex?: unknown; timestamp?: unknown }, snapshot: BridgeSnapshot): RuntimeEventDraft[] {
+    if (!Number.isInteger(event.turnIndex) || Number(event.turnIndex) < 0 || Number(event.turnIndex) > 1_000_000_000) return [];
+    this.#turnIndex = Number(event.turnIndex); this.#activeByRole.clear(); this.#lastMessageRef = null;
+    const draft = this.#draft(snapshot, "turn.started", { phase: "started" }, { sourceObservedAt: event.timestamp });
+    return draft ? [draft] : [];
+  }
+  messageStarted(event: { message?: unknown }, snapshot: BridgeSnapshot): RuntimeEventDraft[] {
+    const message = event.message as any, messageRole = role(message); if (!messageRole || this.#turnIndex === null) return [];
+    const base = this.#base(snapshot, message?.timestamp); if (!base) return [];
+    const messageRef = opaque("message", [base.sessionRef, base.agentOperationId, this.#turnIndex, ++this.#messageCounter, messageRole]);
+    const source = messageRole === "tool-result" ? "" : safe(text(message), MAX_STREAM_BUFFER).text;
+    this.#activeByRole.set(messageRole, { ref: messageRef, role: messageRole, rawBuffer: "", chunkSequence: 0, truncated: false,
+      emittedEvents: 0, lastFlushAt: this.#now().getTime(),
+      thinking: new Set(), thinkingStreaming: new Set(), thinkingCompleted: new Set() });
+    this.#lastMessageRef = messageRef;
+    const draft = this.#draft(snapshot, "message.started", { role: messageRole, contentDigest: source ? digest(source) : null,
+      textChars: source ? source.length : null, imageCount: imageCount(message) }, { sourceObservedAt: message?.timestamp, messageRef });
+    return draft ? [draft] : [];
+  }
+  #deltaDrafts(snapshot: BridgeSnapshot, active: ActiveMessage, value: string, redactedValue: boolean, truncatedValue = false): RuntimeEventDraft[] {
+    const result: RuntimeEventDraft[] = [];
+    for (let offset = 0; offset < value.length; offset += MAX_DELTA) {
+      if (active.emittedEvents >= MAX_MESSAGE_STREAM_EVENTS) { active.truncated = true; break; }
+      const delta = value.slice(offset, offset + MAX_DELTA);
+      const draft = this.#draft(snapshot, "message.text-delta", { role: "assistant", contentIndex: 0,
+        chunkSequence: active.chunkSequence++, delta, deltaDigest: digest(delta) },
+      { messageRef: active.ref, redacted: redactedValue, truncated: truncatedValue });
+      if (draft) { result.push(draft); active.emittedEvents += 1; }
+    }
+    return result;
+  }
+  #drainLines(snapshot: BridgeSnapshot, active: ActiveMessage, final: boolean): RuntimeEventDraft[] {
+    let take = final ? active.rawBuffer.length : active.rawBuffer.lastIndexOf("\n") + 1;
+    if (take <= 0) return [];
+    const candidate = active.rawBuffer.slice(0, take), privateStart = candidate.search(PRIVATE_KEY_BEGIN);
+    if (privateStart >= 0 && !PRIVATE_KEY_END.test(candidate.slice(privateStart))) {
+      if (!final) take = privateStart;
+      else {
+        active.rawBuffer = "";
+        const before = redactSensitiveText(controls(candidate.slice(0, privateStart)));
+        return this.#deltaDrafts(snapshot, active, `${before.text}[REDACTED_SECRET]`, true, active.truncated);
+      }
+    }
+    if (take <= 0) return [];
+    const source = active.rawBuffer.slice(0, take); active.rawBuffer = active.rawBuffer.slice(take);
+    const projected = redactSensitiveText(controls(source));
+    return this.#deltaDrafts(snapshot, active, projected.text, projected.redacted, active.truncated);
+  }
+  messageUpdated(event: { assistantMessageEvent?: any }, snapshot: BridgeSnapshot): RuntimeEventDraft[] {
+    const update = event.assistantMessageEvent, active = this.#activeByRole.get("assistant"); if (!active || !update) return [];
+    if (update.type === "text_delta" && typeof update.delta === "string") {
+      if (active.emittedEvents >= MAX_MESSAGE_STREAM_EVENTS) { active.truncated = true; return []; }
+      const remaining = MAX_STREAM_BUFFER - active.rawBuffer.length;
+      if (remaining <= 0) { active.truncated = true; return []; }
+      active.rawBuffer += update.delta.slice(0, remaining); if (update.delta.length > remaining) active.truncated = true;
+      const now = this.#now().getTime();
+      if (active.rawBuffer.length < STREAM_FLUSH_CHARS && now - active.lastFlushAt < STREAM_FLUSH_INTERVAL_MS
+        && !PRIVATE_KEY_END.test(active.rawBuffer)) return [];
+      const drafts = this.#drainLines(snapshot, active, false);
+      if (drafts.length) active.lastFlushAt = now;
+      return drafts;
+    }
+    if (["thinking_start", "thinking_delta", "thinking_end"].includes(update.type) && Number.isInteger(update.contentIndex)) {
+      const index = Number(update.contentIndex);
+      if (index < 0 || index > 1_000_000_000 || active.emittedEvents >= MAX_MESSAGE_STREAM_EVENTS) { active.truncated = true; return []; }
+      const state = update.type === "thinking_start" ? "started" : update.type === "thinking_end" ? "completed" : "streaming";
+      if (state === "started" && (active.thinking.has(index) || active.thinkingCompleted.has(index))) return [];
+      if (state === "streaming" && (active.thinkingStreaming.has(index) || active.thinkingCompleted.has(index))) return [];
+      if (state === "completed" && active.thinkingCompleted.has(index)) return [];
+      if (state === "started") active.thinking.add(index); if (state === "streaming") active.thinkingStreaming.add(index);
+      if (state === "completed") { active.thinkingCompleted.add(index); active.thinkingStreaming.delete(index); }
+      const draft = this.#draft(snapshot, "message.thinking-state", { contentIndex: index, state, redacted: true },
+        { messageRef: active.ref, redacted: true });
+      if (draft) active.emittedEvents += 1;
+      return draft ? [draft] : [];
+    }
+    return [];
+  }
+  messageEnded(event: { message?: unknown }, snapshot: BridgeSnapshot): RuntimeEventDraft[] {
+    const message = event.message as any, messageRole = role(message); if (!messageRole) return [];
+    const active = this.#activeByRole.get(messageRole); if (!active) return [];
+    const drafts = messageRole === "assistant" ? this.#drainLines(snapshot, active, true) : [];
+    this.#activeByRole.delete(messageRole); this.#lastMessageRef = active.ref;
+    const finalText = messageRole === "tool-result" ? { text: "", redacted: false, truncated: false } : safe(text(message), MAX_STREAM_BUFFER);
+    const reason = stopReason(message);
+    if (messageRole === "assistant" && (reason === "error" || reason === "aborted")) {
+      const error = safe(message?.errorMessage, 500);
+      const failed = this.#draft(snapshot, "message.failed", { role: "assistant", reason, errorCode: reason === "error" ? "assistant-message-error" : "assistant-message-aborted",
+        message: error.text || null, contentDigest: finalText.text ? digest(finalText.text) : null },
+      { sourceObservedAt: message?.timestamp, messageRef: active.ref, redacted: finalText.redacted || error.redacted, truncated: finalText.truncated || error.truncated });
+      if (failed) drafts.push(failed); return drafts;
+    }
+    const completed = this.#draft(snapshot, "message.completed", { role: messageRole, contentDigest: finalText.text ? digest(finalText.text) : null,
+      contentRef: null, textPreview: messageRole === "tool-result" ? null : finalText.text.slice(0, 4_000), textChars: messageRole === "tool-result" ? null : finalText.text.length,
+      blockCount: Math.min(10_000, Array.isArray(message?.content) ? message.content.length : finalText.text ? 1 : 0), stopReason: reason, usage: usage(message) },
+    { sourceObservedAt: message?.timestamp, messageRef: active.ref, redacted: finalText.redacted, truncated: finalText.truncated || active.truncated });
+    if (completed) drafts.push(completed); return drafts;
+  }
+  turnEnded(event: { message?: unknown; toolResults?: unknown[] }, snapshot: BridgeSnapshot): RuntimeEventDraft[] {
+    const reason = stopReason(event.message), count = Array.isArray(event.toolResults) ? Math.min(10_000, event.toolResults.length) : 0;
+    const draft = this.#draft(snapshot, "turn.ended", { phase: "ended", finalMessageRef: this.#lastMessageRef, toolResultCount: count, stopReason: reason });
+    return draft ? [draft] : [];
+  }
+  toolStarted(event: { toolCallId?: unknown; toolName?: unknown }, snapshot: BridgeSnapshot): RuntimeEventDraft[] {
+    if (typeof event.toolCallId !== "string" || !event.toolCallId) return [];
+    const drafts = this.#activeByRole.get("assistant")
+      ? this.#drainLines(snapshot, this.#activeByRole.get("assistant") as ActiveMessage, false) : [];
+    const name = safeToolName(event.toolName);
+    const ref = opaque("tool", [snapshot.identity?.sessionRef, event.toolCallId]), activityRef = opaque("activity", [snapshot.identity?.sessionRef, event.toolCallId]);
+    this.#toolRefs.set(event.toolCallId, ref); this.#lastToolProgress.set(event.toolCallId, 0);
+    const draft = this.#draft(snapshot, "activity.started", activityPayload("started", activityRef, name), { toolCallId: ref });
+    if (draft) drafts.push(draft);
+    return drafts;
+  }
+  toolUpdated(event: { toolCallId?: unknown; toolName?: unknown }, snapshot: BridgeSnapshot): RuntimeEventDraft[] {
+    if (typeof event.toolCallId !== "string") return [];
+    const now = this.#now().getTime(), last = this.#lastToolProgress.get(event.toolCallId) ?? 0; if (now - last < 250) return [];
+    const ref = this.#toolRefs.get(event.toolCallId); if (!ref) return [];
+    this.#lastToolProgress.set(event.toolCallId, now);
+    const name = safeToolName(event.toolName);
+    const activityRef = opaque("activity", [snapshot.identity?.sessionRef, event.toolCallId]);
+    const draft = this.#draft(snapshot, "activity.progress", activityPayload("progress", activityRef, name), { toolCallId: ref });
+    return draft ? [draft] : [];
+  }
+  toolEnded(event: { toolCallId?: unknown; toolName?: unknown; isError?: unknown }, snapshot: BridgeSnapshot): RuntimeEventDraft[] {
+    if (typeof event.toolCallId !== "string") return [];
+    const ref = this.#toolRefs.get(event.toolCallId); if (!ref) return [];
+    const name = safeToolName(event.toolName);
+    const activityRef = opaque("activity", [snapshot.identity?.sessionRef, event.toolCallId]), state = event.isError === true ? "failed" : "finished";
+    this.#toolRefs.delete(event.toolCallId); this.#lastToolProgress.delete(event.toolCallId);
+    const draft = this.#draft(snapshot, `activity.${state}`, activityPayload(state, activityRef, name), { toolCallId: ref });
+    return draft ? [draft] : [];
+  }
+  agentSettled(snapshot: BridgeSnapshot, hasPendingMessages: boolean | null): RuntimeEventDraft[] {
+    const value = hasPendingMessages === null ? { state: "unknown", value: null, reasonCode: "queue-fact-unavailable" }
+      : { state: "known", value: hasPendingMessages, reasonCode: null };
+    const draft = this.#draft(snapshot, "agent-operation.settled", { settlement: "completed", lastStopReason: null, hasPendingMessages: value });
+    this.reset(); return draft ? [draft] : [];
+  }
+}