@fitchmultz/pi-subagents 0.46.2 → 0.48.0

package/src/pi-intercom/bridge.ts

@@ -8,11 +8,32 @@ import { getBrokerSocketPath } from "./broker/paths.ts";
 import { loadConfig, sameListener, type Config, type Identity } from "./bridge-config.ts";
 import { ASK_TIMEOUT, Fault, fingerprint, log } from "./bridge-protocol.ts";
 import { Session } from "./bridge-session.ts";
-import { operationFor, routeFor, type Operation } from "./bridge-routes.ts";
-import { reply } from "./bridge-http.ts";
-import { Launcher, sameIdentity } from "./bridge-launch.ts";
+import { operationFor, routeFor } from "./bridge-routes.ts";
+import { reply, replyFault } from "./bridge-http.ts";
+import { sameIdentity } from "./bridge-launch.ts";
+import { BridgeOperations } from "./bridge-operations.ts";
+import { authenticatedCertificateChain } from "./native-control-auth.ts";
+import { PersistentPresence } from "./bridge-presence.ts";
+import { WakeDeliveries } from "./bridge-wake.ts";
+import { spawnBrokerIfNeeded } from "./broker/spawn.ts";
 
 const MAX_CONNECTIONS = 128;
+const LONG_ROUTES = new Set([
+  "POST /v1/start",
+  "POST /v1/spawn",
+  "POST /v1/resume",
+  "GET /v1/transcript",
+  "POST /v1/transcript",
+]);
+
+function validCertificateDates(starts: number, expires: number): boolean {
+  return (
+    Number.isFinite(starts) &&
+    Number.isFinite(expires) &&
+    starts <= Date.now() &&
+    expires > Date.now()
+  );
+}
 
 interface Connection {
   readonly fingerprint: string;
@@ -25,16 +46,39 @@ class Bridge {
   private readonly configPath: string;
   private readonly sessions = new Map<string, Session>();
   private readonly losses = new Map<string, number>();
-  private readonly launcher = new Launcher();
+  private readonly operations: BridgeOperations;
   private readonly sockets = new Set<Socket>();
   private readonly connections = new Map<TLSSocket, Connection>();
   private readonly server: Server;
   private stopping = false;
   private readonly handlers = new Set<Promise<void>>();
+  private readonly presence?: PersistentPresence;
+  private readonly deliveries: WakeDeliveries;
 
   constructor(config: Config, configPath: string) {
     this.config = config;
     this.configPath = configPath;
+    this.operations = new BridgeOperations(config.stateDir);
+    this.deliveries = new WakeDeliveries(config.stateDir, (identity) => this.allowed(identity));
+    if (config.stateDir !== undefined) {
+      this.presence = new PersistentPresence({
+        stateDir: config.stateDir,
+        clients: () => this.config.clients,
+        connect: async (identity, expires) => {
+          await spawnBrokerIfNeeded(process.execPath, []);
+          if (!this.allowed(identity)) {
+            return;
+          }
+          const session = this.session(identity, expires);
+          const controller = session.begin();
+          try {
+            await session.connectedPeers(controller.signal);
+          } finally {
+            session.end(controller);
+          }
+        },
+      });
+    }
     this.server = createServer(
       {
         ...config.tls,
@@ -90,7 +134,11 @@ class Bridge {
   }
   private allowed(identity: Identity): boolean {
     const current = this.config.clients.get(identity.fingerprint256);
-    return !this.stopping && sameIdentity(identity, current);
+    return (
+      !this.stopping &&
+      sameIdentity(identity, current) &&
+      JSON.stringify(identity.wake) === JSON.stringify(current?.wake)
+    );
   }
   private lost(fp: string, count = 1): void {
     if (count > 0 && this.config.clients.has(fp)) {
@@ -98,10 +146,13 @@ class Bridge {
     }
   }
   private session(identity: Identity, expires: number): Session {
+    this.deliveries.session(identity, expires);
     let session = this.sessions.get(identity.fingerprint256);
     if (!session) {
       session = new Session(
         {
+          stateDir: this.config.stateDir,
+          notifications: identity.wake !== undefined,
           allowed: (candidate) => this.allowed(candidate),
           lost: (fp, count) => this.lost(fp, count),
           losses: (fp) => this.losses.get(fp) ?? 0,
@@ -134,15 +185,19 @@ class Bridge {
       !socket.authorized ||
       !identity ||
       this.stopping ||
-      !Number.isFinite(expires) ||
-      !Number.isFinite(starts) ||
-      starts > Date.now() ||
-      expires <= Date.now()
+      !validCertificateDates(starts, expires)
     ) {
       log("connection_rejected", { fingerprint: fp, result: "unauthorized" });
       socket.destroy();
       return;
     }
+    try {
+      this.presence?.authenticated(identity, expires);
+    } catch {
+      log("connection_rejected", { fingerprint: fp, result: "presence_storage_failed" });
+      socket.destroy();
+      return;
+    }
     const expiry = () => {
       if (expires <= Date.now()) {
         this.drop(fp, new Fault(403, "certificate_expired", "Client certificate expired."));
@@ -164,6 +219,7 @@ class Bridge {
     log("connected", { name: identity.name, fingerprint: fp, result: "authenticated" });
   }
   private drop(fp: string, error: Readonly<Fault>): void {
+    this.deliveries.drop(fp);
     this.sessions.get(fp)?.close(error);
     for (const [socket, connection] of this.connections) {
       if (connection.fingerprint === fp) {
@@ -181,6 +237,7 @@ class Bridge {
         port: typeof address === "object" && address ? address.port : this.config.port,
         brokerSocket: getBrokerSocketPath(),
       });
+      this.presence?.start();
     });
     process.on("SIGHUP", () => this.reload());
     // Retain listeners during dispatch: selected SDK dependencies use signal-exit's listener check.
@@ -198,11 +255,12 @@ class Bridge {
       }
       this.config = next;
       this.revokeRemoved();
-      this.launcher.revoke(next.clients).catch(() => log("launch_cleanup", { result: "failed" }));
+      this.operations.revoke(next.clients).catch(() => log("launch_cleanup", { result: "failed" }));
       log("allowlist_reloaded", { result: "accepted", clients: next.clients.size });
     } catch {
       this.config = { ...this.config, clients: new Map() };
-      this.launcher
+      this.deliveries.reload();
+      this.operations
         .revoke(this.config.clients)
         .catch(() => log("launch_cleanup", { result: "failed" }));
       for (const session of this.sessions.values()) {
@@ -222,6 +280,7 @@ class Bridge {
     }
   }
   private revokeRemoved(): void {
+    this.deliveries.reload();
     for (const [fp, session] of this.sessions) {
       if (!this.allowed(session.identity)) {
         this.drop(
@@ -263,13 +322,16 @@ class Bridge {
     await Promise.all([
       ...this.handlers,
       ...sessions.map((session) => session.settled()),
-      this.launcher.shutdown(),
+      this.operations.shutdown(),
+      this.presence?.stop(),
+      this.deliveries.stop(),
     ]);
     log("shutdown", { result: "closed" });
   }
   private admission(req: IncomingMessage): {
     readonly identity: Identity;
     readonly expires: number;
+    readonly certificate: string;
   } {
     const socket = req.socket;
     const connection = socket instanceof TLSSocket ? this.connections.get(socket) : undefined;
@@ -288,7 +350,11 @@ class Bridge {
       this.drop(connection.fingerprint, fault);
       throw fault;
     }
-    return { identity, expires: connection.expires };
+    return {
+      identity,
+      expires: connection.expires,
+      certificate: authenticatedCertificateChain(socket),
+    };
   }
   private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
     const requestId = randomUUID();
@@ -321,7 +387,7 @@ class Bridge {
       );
     };
     try {
-      const { identity, expires } = this.admission(req);
+      const { identity, expires, certificate } = this.admission(req);
       const route = routeFor(req);
       session = this.session(identity, expires);
       controller = session.begin();
@@ -329,15 +395,18 @@ class Bridge {
       req.once("aborted", abort);
       res.once("close", onClose);
       const duration = route === "POST /v1/ask" ? ASK_TIMEOUT + 15000 : 15000;
-      setDeadline(route === "POST /v1/start" ? 75000 : duration);
+      setDeadline(LONG_ROUTES.has(route) ? 75000 : duration);
       const operation = await operationFor(req, route, signal);
       if (operation.route === "POST /v1/ask") {
         setDeadline(operation.timeoutMs + 15000);
+      } else if (operation.route === "GET /v1/transcript") {
+        setDeadline(75000);
       }
-      const data = await this.execute(operation, session, {
+      const data = await this.operations.execute(operation, session, {
         signal,
         requestId,
         expires,
+        certificate,
         onPeer: (id) => {
           peer = id;
         },
@@ -351,10 +420,7 @@ class Bridge {
           ? error
           : new Fault(503, "broker_unavailable", "Local broker operation failed.");
       log("request", { ...session?.fields(), requestId, peer, result: fault.code });
-      reply(res, requestId, fault.status, {
-        ok: false,
-        error: { code: fault.code, message: fault.message, ...fault.details },
-      });
+      replyFault(res, requestId, fault);
     } finally {
       clearTimeout(deadline);
       req.off("aborted", abort);
@@ -364,45 +430,13 @@ class Bridge {
       }
     }
   }
-  private async execute(
-    operation: Operation,
-    session: Readonly<Session>,
-    context: {
-      readonly signal: AbortSignal;
-      readonly requestId: string;
-      readonly expires: number;
-      readonly onPeer: (id: string) => void;
-    },
-  ) {
-    switch (operation.route) {
-      case "POST /v1/start":
-        return this.launcher.start(operation.name, {
-          identity: session.identity,
-          expires: context.expires,
-          signal: context.signal,
-          peers: (signal) => session.connectedPeers(signal),
-        });
-      case "GET /v1/sessions":
-        return this.launcher.list(session.identity);
-      case "POST /v1/stop":
-        return this.launcher.stop(session.identity, operation.sessionId);
-      case "GET /v1/list":
-      case "GET /v1/inbox":
-      case "POST /v1/register":
-      case "POST /v1/ask":
-      case "POST /v1/send":
-      case "POST /v1/reply":
-      case "POST /v1/ack":
-        return session.execute(operation, context);
-    }
-  }
 }
 
 function main(): void {
   const args = process.argv.slice(2);
   if (args.length === 1 && (args[0] === "-h" || args[0] === "--help")) {
     process.stdout.write(
-      "Usage: node dist/pi-intercom/bridge.js --config PATH\n\nOptional loopback HTTPS/mTLS bridge for the local pi-intercom broker.\nConfig and TLS key must be owned by you with mode 0600. Never starts the broker.\nSIGHUP reloads the client allowlist (invalid reload denies all clients).\nRestart this helper for TLS/listener rotation. SIGINT/SIGTERM disconnect peers.\n\nExample: node dist/pi-intercom/bridge.js --config ~/.pi/agent/intercom/bridge.json\n",
+      "Usage: node dist/pi-intercom/bridge.js --config PATH\n\nOptional loopback HTTPS/mTLS bridge for the local pi-intercom broker.\nConfig and TLS key must be owned by you with mode 0600.\nWithout stateDir, messaging never starts the broker. Durable presence safely starts\none only when none is running; it never restarts or replaces a live broker.\nSIGHUP reloads the client allowlist (invalid reload denies all clients).\nRestart this helper for TLS/listener rotation. SIGINT/SIGTERM disconnect peers.\n\nExample: node dist/pi-intercom/bridge.js --config ~/.pi/agent/intercom/bridge.json\n",
     );
     return;
   }
@@ -416,7 +450,7 @@ function main(): void {
     new Bridge(loadConfig(path), path).start();
   } catch {
     process.stderr.write(
-      "Bridge startup failed: check config schema, file ownership/mode 0600, absolute TLS/cwd paths, TLS credentials, and launch policy (0700 sessionDir, Pi packageRoot, extension paths).\n",
+      "Bridge startup failed: check config schema, file ownership/mode 0600, absolute TLS/cwd paths, TLS credentials, stateDir (owned 0700 directory), and launch policy (0700 sessionDir, Pi packageRoot, extension paths).\n",
     );
     process.exitCode = 1;
   }

package/src/pi-intercom/broker/client.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from "events";
 import type net from "net";
 import { randomUUID } from "crypto";
+import type { NativeControlEnvelope } from "../native-control-protocol.ts";
 import { writeMessage } from "./framing.ts";
 import { BrokerConnection, connectBrokerSocket } from "./connection.ts";
 import { SnapshotReader } from "./snapshot-reader.ts";
@@ -51,6 +52,7 @@ interface SendOptions {
   readonly messageId?: string;
   readonly human?: HumanMessageOrigin;
   readonly topic?: TopicUpdate;
+  readonly control?: NativeControlEnvelope;
 }
 
 function toError(error: unknown): Error {
@@ -405,6 +407,7 @@ export class IntercomClient extends EventEmitter {
       expectsReply: options.expectsReply,
       ...(options.human ? { human: options.human } : {}),
       ...(options.topic ? { topic: options.topic } : {}),
+      ...(options.control ? { control: options.control } : {}),
       delivery: messageDelivery(options),
       queueMode: options.queueMode,
       threadId: options.threadId,

package/src/pi-intercom/connection.ts

@@ -1,4 +1,3 @@
-import { createHash } from "node:crypto";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { IntercomClient } from "./broker/client.ts";
 import type { IntercomTransport } from "./transport.ts";
@@ -8,7 +7,7 @@ import type { IntercomLifecycle } from "./lifecycle.ts";
 import type { IntercomTopics } from "./topics.ts";
 import type { Message, SessionInfo, TopicChange } from "./types.ts";
 import { asError, errorMessage } from "./validation.ts";
-import { formatTargetOptions, resolveSessionTarget } from "./session-targets.ts";
+import { formatTargetOptions, resolveSessionTarget, nativePeerId } from "./session-targets.ts";
 
 export type ConnectionReason = "startup" | "background" | "tool" | "overlay" | "peer-awareness";
 type Lifecycle = Readonly<
@@ -233,7 +232,7 @@ export class IntercomConnection {
       }
       await next.connect(
         await this.lifecycle.registration(this.hooks.pendingAsks()),
-        `pi-${createHash("sha256").update(sessionId).digest("hex").slice(0, 32)}`,
+        nativePeerId(sessionId),
       );
       if (!this.lifecycle.live(ctx, generation)) {
         await next.disconnect();

package/src/pi-intercom/inbound.ts

@@ -1,4 +1,3 @@
-import { createHash } from "node:crypto";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { IntercomConfig } from "./config.ts";
 import type { IntercomLifecycle } from "./lifecycle.ts";
@@ -13,6 +12,7 @@ import type { Message, SessionInfo } from "./types.ts";
 import { requestedDelivery, isBlockingSupervisorMessage } from "./inbound-record.ts";
 import { formatAttachments } from "./message-format.ts";
 import { readQuestionOwner } from "../runs/shared/supervisor-questions.ts";
+import { nativePeerId } from "./session-targets.ts";
 
 type Lifecycle = Readonly<
   Pick<IntercomLifecycle, "generation" | "isIdle" | "live" | "markActivity">
@@ -53,9 +53,7 @@ export class IntercomInbound {
     }
     const owner = readQuestionOwner(origin.runId);
     return (
-      owner?.sessionId === origin.ownerSessionId &&
-      from.id ===
-        `pi-${createHash("sha256").update(origin.ownerSessionId).digest("hex").slice(0, 32)}`
+      owner?.sessionId === origin.ownerSessionId && from.id === nativePeerId(origin.ownerSessionId)
     );
   }
   private normalize(from: SessionInfo, input: Message): Message {

package/src/pi-intercom/index.ts

@@ -9,6 +9,7 @@ import { InboundDeliveryOwner } from "./inbound-delivery.ts";
 import { ReplyWait } from "./reply-wait.ts";
 import { IntercomConnection } from "./connection.ts";
 import { IntercomInbound } from "./inbound.ts";
+import { NativeControls } from "./native-control.ts";
 import { IntercomOutbound } from "./outbound.ts";
 import { IntercomInspection } from "./inspection.ts";
 import { IntercomTopicActions } from "./topic-actions.ts";
@@ -33,7 +34,11 @@ export default function piIntercomExtension(pi: ExtensionAPI): void {
   const connection = new IntercomConnection(lifecycle, config, topics, {
     restoring: () => delivery.restoring,
     pendingAsks: () => replies.listPending().length,
-    incoming: (ctx, from, message) => inbound.receive(ctx, from, message),
+    incoming: async (ctx, from, message) => {
+      if (!(await controls.receive(ctx, from, message))) {
+        await inbound.receive(ctx, from, message);
+      }
+    },
     peerLeft: (id) => {
       wait.peerDisconnected(id);
       journal.peerLeft(id);
@@ -46,6 +51,7 @@ export default function piIntercomExtension(pi: ExtensionAPI): void {
       }
     },
   });
+  const controls = new NativeControls(lifecycle, connection);
   const delivery = new InboundDeliveryOwner(pi, lifecycle, journal, {
     replies,
     syncStatus: () => connection.syncStatus(),

package/src/pi-intercom/native-control-auth.ts

@@ -0,0 +1,89 @@
+import { X509Certificate } from "node:crypto";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { existsSync } from "node:fs";
+import type { TLSSocket } from "node:tls";
+import { loadControlPolicy } from "./bridge-config.ts";
+import { getPiAgentDir } from "./agent-dir.ts";
+import { fingerprint } from "./bridge-protocol.ts";
+
+export function authenticatedCertificateChain(socket: Readonly<TLSSocket>): string {
+  const blocks: string[] = [];
+  const seen = new Set<string>();
+  let cert = socket.getPeerCertificate(true);
+  for (let depth = 0; depth < 8; depth += 1) {
+    const parsed = new X509Certificate(cert.raw);
+    if (seen.has(parsed.fingerprint256)) {
+      break;
+    }
+    seen.add(parsed.fingerprint256);
+    blocks.push(parsed.toString());
+    cert = cert.issuerCertificate;
+  }
+  return blocks.join("\n");
+}
+function certificates(pem: string): X509Certificate[] {
+  const blocks = pem.match(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g);
+  if (!blocks || blocks.length > 8) {
+    throw new Error("Invalid bounded certificate chain.");
+  }
+  return blocks.map((block) => new X509Certificate(block));
+}
+function validNow(cert: X509Certificate): boolean {
+  return Date.parse(cert.validFrom) <= Date.now() && Date.parse(cert.validTo) > Date.now();
+}
+function trustedChain(
+  chain: readonly X509Certificate[],
+  roots: readonly X509Certificate[],
+): boolean {
+  let current = chain.at(0);
+  if (current === undefined || current.ca || !validNow(current)) {
+    return false;
+  }
+  for (let depth = 0; depth < 8; depth += 1) {
+    const subject: X509Certificate = current;
+    const issuer: X509Certificate | undefined = [...roots, ...chain.slice(1)].find(
+      (candidate) =>
+        candidate.ca &&
+        validNow(candidate) &&
+        subject.checkIssued(candidate) &&
+        subject.verify(candidate.publicKey),
+    );
+    if (!issuer) {
+      return false;
+    }
+    if (roots.some((root) => root.fingerprint256 === issuer.fingerprint256)) {
+      return true;
+    }
+    current = issuer;
+  }
+  return false;
+}
+function controlPolicyPath(): string {
+  const configured = process.env.PI_INTERCOM_BRIDGE_CONFIG;
+  if (configured !== undefined) {
+    return configured;
+  }
+  const standard = join(getPiAgentDir(), "intercom", "bridge.json");
+  return existsSync(standard) ? standard : join(homedir(), ".pi", "intercom-bridge", "config.json");
+}
+/** Unix broker peers are same-user trusted. Names/payload claims grant no authority. */
+export function authorizedControlPeer(peerId: string, certificate: string): boolean {
+  try {
+    const configPath = controlPolicyPath();
+    const config = loadControlPolicy(configPath);
+    const chain = certificates(certificate);
+    const client = chain.at(0);
+    if (client === undefined) {
+      return false;
+    }
+    const fp = fingerprint(client.fingerprint256);
+    return (
+      peerId === `remote-${fp.toLowerCase()}` &&
+      config.clients.has(fp) &&
+      trustedChain(chain, certificates(config.ca.toString("utf8")))
+    );
+  } catch {
+    return false;
+  }
+}

package/src/pi-intercom/native-control-protocol.ts

@@ -0,0 +1,180 @@
+import { isRecord, isUnknownArray } from "../shared/unknown.ts";
+import type { TranscriptOptions, TranscriptPage } from "./transcript.ts";
+
+export const CONTROL_SCHEMA = "pi-intercom/control-v1";
+export const CONTROL_FALLBACK =
+  "Native Intercom metadata exchange (no conversation response needed).";
+export type NativeControlVerb = "capabilities" | "cancel" | "stop" | "transcript";
+export interface NativeControlOperation {
+  readonly to: string;
+  readonly verb: NativeControlVerb;
+  readonly options?: TranscriptOptions;
+  readonly timeoutMs: number;
+}
+export interface NativeControlRequest {
+  readonly schema: typeof CONTROL_SCHEMA;
+  readonly kind: "request";
+  readonly verb: NativeControlVerb;
+  /** Public TLS certificate, supplied by the bridge, never a caller-selected identity. */
+  readonly certificate: string;
+  readonly options?: TranscriptOptions;
+}
+export interface NativeControlResult {
+  readonly schema: typeof CONTROL_SCHEMA;
+  readonly kind: "result";
+  readonly verb: NativeControlVerb;
+  readonly status:
+    | "ok"
+    | "denied"
+    | "cancel_requested"
+    | "shutdown_requested"
+    | "unsupported"
+    | "failed";
+  readonly verbs?: readonly NativeControlVerb[];
+  readonly mode?: string;
+  readonly idle?: boolean;
+  readonly pendingInput?: boolean;
+  readonly queueCleared?: false;
+  readonly processExited?: false;
+  readonly stopSupport?: "native_shutdown" | "requires_activity" | "host_dependent";
+  readonly reason?: string;
+  readonly transcript?: TranscriptPage;
+}
+export type NativeControlEnvelope = NativeControlRequest | NativeControlResult;
+
+export function isControlVerb(value: unknown): value is NativeControlVerb {
+  return (
+    value === "capabilities" || value === "cancel" || value === "stop" || value === "transcript"
+  );
+}
+export function isControlRequest(value: unknown): value is NativeControlRequest {
+  return (
+    isRecord(value) &&
+    value.schema === CONTROL_SCHEMA &&
+    value.kind === "request" &&
+    isControlVerb(value.verb) &&
+    typeof value.certificate === "string" &&
+    value.certificate.length <= 16384 &&
+    Object.keys(value).every((key) =>
+      ["schema", "kind", "verb", "certificate", "options"].includes(key),
+    )
+  );
+}
+export function isControlResult(value: unknown): value is NativeControlResult {
+  if (
+    !isRecord(value) ||
+    value.schema !== CONTROL_SCHEMA ||
+    value.kind !== "result" ||
+    !isControlVerb(value.verb)
+  ) {
+    return false;
+  }
+  return (
+    validResultFields(value) &&
+    validResultPayload(value) &&
+    Buffer.byteLength(JSON.stringify(value)) <= 1024 * 1024
+  );
+}
+function optionalText(value: unknown, max: number): boolean {
+  return value === undefined || (typeof value === "string" && value.length <= max);
+}
+function validResultFields(value: Readonly<Record<string, unknown>>): boolean {
+  const fields = new Set([
+    "schema",
+    "kind",
+    "verb",
+    "status",
+    "mode",
+    "idle",
+    "pendingInput",
+    "queueCleared",
+    "processExited",
+    "stopSupport",
+    "reason",
+    "transcript",
+    "verbs",
+  ]);
+  return (
+    Object.keys(value).every((key) => fields.has(key)) &&
+    typeof value.status === "string" &&
+    ["ok", "denied", "cancel_requested", "shutdown_requested", "unsupported", "failed"].includes(
+      value.status,
+    ) &&
+    optionalText(value.reason, 2048) &&
+    optionalText(value.mode, 64) &&
+    [value.idle, value.pendingInput].every(
+      (flag) => flag === undefined || typeof flag === "boolean",
+    ) &&
+    [value.queueCleared, value.processExited].every((flag) => flag === undefined || flag === false)
+  );
+}
+function validResultPayload(value: Readonly<Record<string, unknown>>): boolean {
+  if (
+    value.stopSupport !== undefined &&
+    (typeof value.stopSupport !== "string" ||
+      !["native_shutdown", "requires_activity", "host_dependent"].includes(value.stopSupport))
+  ) {
+    return false;
+  }
+  if (
+    value.verbs !== undefined &&
+    (!isUnknownArray(value.verbs) || !value.verbs.every(isControlVerb))
+  ) {
+    return false;
+  }
+  return value.transcript === undefined || validTranscript(value.transcript);
+}
+function validTranscript(value: unknown): boolean {
+  if (!isRecord(value) || !isUnknownArray(value.records) || value.records.length > 100) {
+    return false;
+  }
+  const fields = new Set([
+    "sessionId",
+    "leafId",
+    "records",
+    "bytes",
+    "truncated",
+    "cursor",
+    "scanLimitReached",
+    "finalizedOnly",
+    "streaming",
+  ]);
+  return (
+    Object.keys(value).every((key) => fields.has(key)) &&
+    typeof value.sessionId === "string" &&
+    value.sessionId.length <= 512 &&
+    (value.leafId === null || typeof value.leafId === "string") &&
+    value.records.every(validTranscriptRecord) &&
+    validTranscriptMetadata(value)
+  );
+}
+function validTranscriptMetadata(value: Readonly<Record<string, unknown>>): boolean {
+  return (
+    typeof value.bytes === "number" &&
+    Number.isInteger(value.bytes) &&
+    value.bytes >= 0 &&
+    value.bytes <= 131072 &&
+    typeof value.truncated === "boolean" &&
+    optionalText(value.cursor, 512) &&
+    typeof value.scanLimitReached === "boolean" &&
+    value.finalizedOnly === true &&
+    value.streaming === "unavailable"
+  );
+}
+function validTranscriptRecord(value: unknown): boolean {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const fields = new Set(["id", "timestamp", "role", "text", "truncated"]);
+  return (
+    Object.keys(value).every((key) => fields.has(key)) &&
+    [value.id, value.timestamp].every(
+      (field) => typeof field === "string" && field.length <= 512,
+    ) &&
+    typeof value.role === "string" &&
+    ["user", "assistant", "toolResult", "custom"].includes(value.role) &&
+    typeof value.text === "string" &&
+    Buffer.byteLength(value.text) <= 131072 &&
+    typeof value.truncated === "boolean"
+  );
+}