@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.41da3780c451

package/README.md

@@ -31,7 +31,34 @@ The bridge can also read connection settings from environment variables:
 - `FORGE_DEVICE_NAME`
 - `FORGE_REPO_ROOT`
 - `FORGE_CLI_PROVIDERS`
-- `FORGE_CODEX_MODELS` / `FORGE_CURSOR_MODELS` (optional comma-separated model ids advertised in runner capabilities)
+- `FORGE_CODEX_MODELS` / `FORGE_CURSOR_MODELS` / `FORGE_CLAUDE_MODELS` (optional comma-separated model ids advertised in runner capabilities)
+- `FORGE_DOTNET_PATH` (optional absolute `dotnet` executable; the bridge otherwise selects one SDK compatible with its mapped repositories)
+
+At `connect`, the bridge inspects mapped .NET repositories and the configured repository root,
+selects one installation satisfying their SDK policies, and pins that executable through `PATH` and `DOTNET_ROOT` for dependency warming,
+managed commands, tests, and host-runtime launches. It fails before accepting work when
+no compatible SDK is available instead of falling through to an older ambient SDK.
+During a framework transition, that installation may need both SDK 8 and SDK 10 side by side;
+separate installations do not combine their SDK inventories. Each checkout retains its own
+`global.json` policy. Keep the default clone root narrowly scoped rather than pointing it at
+a parent containing unrelated maintenance checkouts and generated projects.
+
+## Provider CLIs
+
+The bridge auto-detects these provider CLIs on `PATH` and advertises the ones it finds:
+
+| Provider | CLI | Sign-in | Headless invocation |
+| --- | --- | --- | --- |
+| `codex` | `codex` | `codex login` | `codex exec --json` |
+| `cursor` | `cursor-agent` | `cursor-agent login` | `cursor-agent --print --output-format stream-json` |
+| `claude` | `claude` (Claude Code) | `claude` then `/login`, or an Anthropic API key granted by Forge | `claude -p --output-format stream-json --verbose` |
+
+Claude Code notes:
+
+- Install with the native installer or `npm install -g @anthropic-ai/claude-code`. On Windows, Claude Code needs Git for Windows; set `CLAUDE_CODE_GIT_BASH_PATH` if `bash.exe` is not on `PATH`. `CLAUDE_CONFIG_DIR` is passed through if you keep config outside `~/.claude`.
+- Forge pipes the prompt on stdin, runs with `--permission-mode bypassPermissions` inside the managed worktree, and registers its completion MCP server through a temporary `--mcp-config` file outside the worktree with `--strict-mcp-config`, so user-level MCP servers are not loaded into unattended runs. Forge tools appear to the model as `mcp__forge__<tool>`.
+- Claude Code has no model-listing command, so the bridge advertises the `sonnet`, `opus`, and `haiku` aliases. Set `FORGE_CLAUDE_MODELS` to advertise specific model ids instead.
+- Claude runs in host mode only. Docker sandbox placement currently supports Codex only.
 
 Show or change the saved server without editing `bridge.json`:
 
@@ -63,6 +90,45 @@ forge-bridge add-repo Forge /path/to/Forge
 forge-bridge remove-repo Forge
 ```
 
+Readiness probes and Story dispatch select the same local mapping: repository ID first,
+then a remote-only mapping, then a legacy name-only mapping. Explicit mappings may point
+outside the default clone root; both paths use the mapped checkout's parent without moving
+existing managed worktrees. A readiness request must name the same fully qualified local
+checkout. Missing, ambiguous or mismatched mappings fail before runtime preparation; a
+server-supplied path never grants access to a different repository.
+
+Before narrowing a runner's default root, inventory its advertisements, explicitly retain
+every approved or intended executable mapping and its QA launch targets, and document any
+intentional exclusions. An omitted repository mapping can lose its server-side execution
+approval. Reconcile a stale mapping rather than widening filesystem
+access to make a failed readiness request pass.
+
+## Host Docker engine capability
+
+The bridge probes ordinary Docker-daemon access under its own process identity and advertises the
+generic `docker_engine` execution facility independently from Docker sandbox placement. A Story whose
+QA scope requires `docker_engine` is admitted only to a managed host runner with a fresh successful
+probe. This supports repository-owned Testcontainers, Compose services, and other container tests;
+the repository remains responsible for database and image versions. Forge agent sandboxes do not
+receive the host Docker socket, so a Docker-engine requirement is not eligible for
+`executionMode: docker`. The probe is refreshed on heartbeats and again immediately before a matching
+dispatch.
+
+On developer Windows runners, local Docker Desktop recovery can be explicitly enabled by setting
+`dockerDesktopRecoveryEnabled` to `true` in the bridge's local `bridge.json`, or with the
+`FORGE_DOCKER_DESKTOP_AUTO_RECOVERY=true` operator override. The bridge waits for three consecutive
+failed daemon probes plus a fresh confirmation probe after a 30-second grace period. It recovers only
+the local `default` or `desktop-linux` context, and only while it owns no active session or
+reservation. If Docker Desktop is already stopped, recovery starts it without issuing shutdown or
+WSL termination commands. Before relaunch, it removes only verified orphaned Docker companion
+processes whose executable is inside the Docker installation and whose parent is no longer a valid
+Docker backend. A running but unresponsive Desktop is stopped, allowed to settle, and relaunched
+with bounded retries that reject an immediately exiting process. Every recovery is
+single-flight, must pass a fresh `docker info` probe before the capability is advertised again, and
+enters a ten-minute cooldown after an unsuccessful attempt. Remote `DOCKER_HOST` endpoints are never
+restarted. Operators can tune the bounded policy with `FORGE_DOCKER_RECOVERY_FAILURE_THRESHOLD`,
+`FORGE_DOCKER_RECOVERY_COOLDOWN_MS`, and `FORGE_DOCKER_RECOVERY_STARTUP_TIMEOUT_MS`.
+
 ## Docker sandbox runners
 
 Protocol-v2 bridges preflight Docker before advertising the `docker` sandbox runtime. Validate a repository contract and the local runner before enabling a project's `sandbox_required` policy:
@@ -100,8 +166,11 @@ Production shared runners require a Linux rootless Docker daemon. Docker Desktop
 - `FORGE_MAX_CONCURRENT_SANDBOX_BUILDS` / `FORGE_SANDBOX_PID_CAPACITY` — weighted build and PID admission ceilings (defaults: `1` and `2048`).
 - `FORGE_DOCKER_CONTEXT` / `FORGE_DOCKER_EXECUTABLE` — dedicated daemon selection.
 - `FORGE_SANDBOX_STATE_ROOT` — fsync'd attempt ledgers, restricted diagnostics, and build state.
+- `FORGE_SANDBOX_EXECUTION_ROOT` — optional absolute root for disposable managed-host temp/cache/test trees. Windows defaults to the compact per-user `%USERPROFILE%\.fgx` root and rejects a configured root that cannot fit Forge's nested Git/test path budget before an agent starts. Durable ledgers and retained diagnostics remain under `FORGE_SANDBOX_STATE_ROOT`.
 - `FORGE_DISK_HIGH_WATERMARK_PERCENT` / `FORGE_DISK_LOW_WATERMARK_PERCENT` / `FORGE_MINIMUM_WORKSPACE_BYTES` — admission watermarks with high/low hysteresis.
-- `FORGE_SANDBOX_HOST_MEMORY_RESERVE_BYTES` — host memory withheld from sandbox admission. The default is 2 GiB, or 1 GiB when Docker Desktop developer mode is explicitly enabled; production Linux/rootless runners retain 2 GiB unless an operator supplies a measured override.
+- Per-attempt workspace reservations are calculated from the repository source footprint, detected Node/.NET/browser toolchains, the execution role, and immutable sandbox app services. The API uses that request for local and Bridge placement; a Bridge rechecks its authoritative checkout and Docker contract before acceptance. Shared Docker images and package caches remain runner-level capacity, while `FORGE_MINIMUM_WORKSPACE_BYTES` remains a separate host safety reserve rather than a per-lane charge.
+- `FORGE_SANDBOX_HOST_MEMORY_RESERVE_BYTES` — explicit host-memory safety-reserve override for sandbox admission. Without an override, Forge derives a bounded reserve from the sampled capacity domain (Linux: 12.5%, 1–4 GiB; Docker Desktop development: 6.25%, 1–2 GiB). The floor, ceiling, and percentage are configurable with `FORGE_SANDBOX_HOST_MEMORY_RESERVE_FLOOR_BYTES`, `FORGE_SANDBOX_HOST_MEMORY_RESERVE_CEILING_BYTES`, and `FORGE_SANDBOX_HOST_MEMORY_RESERVE_PERCENT`.
+- Managed-host admission uses the same bounded 12.5% physical-memory policy through `FORGE_HOST_MEMORY_RESERVE_BYTES` or its `_FLOOR_BYTES`, `_CEILING_BYTES`, and `_PERCENT` controls. While no Forge attempt holds capacity, the first worker is admitted against the configured reserve floor (1 GiB by default); `FORGE_HOST_IDLE_MEMORY_RESERVE_BYTES` can override that idle reserve. Once an attempt is admitted, every additional admission enforces the full target reserve. Pressure is applied immediately; recovery requires two samples one second apart by default (`FORGE_HOST_MEMORY_RECOVERY_SAMPLES` and `FORGE_HOST_MEMORY_RECOVERY_SAMPLE_INTERVAL_MS`). `FORGE_HOST_DEFAULT_WORKER_MEMORY_LIMIT_BYTES` configures only the conservative cold-start fallback for legacy packets that omit an exact worker request; current packets remain governed by their explicit role request.
 - `FORGE_SANDBOX_MEMORY_SAMPLE_INTERVAL_MS` — interval for sampled Docker peak-memory telemetry (default `1000` ms, clamped to `250`–`30000` ms). Sampling is diagnostic and never changes an attempt outcome.
 - `FORGE_SANDBOX_DEDICATED_DISK=true` — operator assertion that sandbox storage is on a dedicated, conservatively watermarked disk when the Docker storage driver cannot enforce per-volume quotas. `sandbox_required` fails placement unless either quota support or this assertion is advertised.
 - `FORGE_SANDBOX_IMAGE_RETENTION_COUNT` / `FORGE_SANDBOX_IMAGE_RETENTION_TTL_MS` — per-project image-cache retention (defaults: 3 images and 7 days).
@@ -127,10 +196,27 @@ The bridge reaps exact-labeled orphan resources before connecting and every minu
 
 Every attempt-owned container (including short-lived initialization helpers), network, and volume carries `dev.forge.resource-lease-id` equal to the dispatch execution lease. Ledger schema v2 persists the same `resourceLeaseId`; teardown compares the complete expected label set, and orphan reaping fails closed unless the managed, resource-lease, execution-lease, attempt, runner, runner-instance, and fencing identities are all present and consistent.
 
+Host-mode diagnostics retain logs and test results under the 200 MiB archive budget, but omit reproducible `.dll` and `.pdb` copies from `test-output`; the archive manifest records their count and bytes. If other evidence exceeds the budget after supervised children and adapters have stopped, the Bridge releases runtime capacity while preserving the original attempt directory and a released ledger for restricted operator review. It does not delete over-budget original evidence automatically. Process-cleanup failures and unsafe evidence paths still fail closed and retain the runtime claim.
+
 In `bridge_push` mode, the start packet carries only an attempt/fence/branch-bound publication handle. After validating and importing the output bundle, the authenticated current bridge redeems that handle for an in-memory, exact-repository credential; the API rechecks the live lease/fence/grant/branch/result SHA and records redemption before returning it. Git receives the credential through a process environment configuration, never command arguments, files, Git config, or the container. The bridge compares the remote branch with the immutable input commit and pushes only the exact result commit using `--force-with-lease`; cancellation aborts Git, an already-published matching result is an idempotent success, and any other remote value is rejected as stale. The API records the fenced publication acknowledgment before sign-off and does not push the branch a second time while opening the pull request.
 
 Failed project, tooling, and agent image stages preserve only a redacted, capped, mode-0600 diagnostic at `FORGE_SANDBOX_STATE_ROOT/build-logs/<image-key>/<stage>.log`. The event stream carries its digest, byte count, and truncation flag, never the log contents. Treat this directory as restricted source-bearing audit data and apply local retention controls.
 
+## Owned test evidence
+
+`npm test` closes a manifest over the complete Bridge source, test, runtime, configuration, workflow,
+and imported fixture set before compilation. It records the Git commit and exact Node, npm, Git, .NET,
+TypeScript, Vitest, OS, and temporary-root identities, compiles into an owned temporary root, runs
+Vitest through the Windows process-tree supervisor, revalidates the source and toolchain, independently
+rehashes the compiled output, and removes the exact owner root before reporting success.
+
+Set `FORGE_BRIDGE_SUITE_RECEIPT_PATH` to an absolute path for a nonexistent output file to retain the
+verified execution receipt. On Windows evidence runs, `TEMP`, `TMP`, `TMPDIR`, and `FORGE_TMPDIR` may
+point to the same short, empty, high-capacity root. This changes only owned temporary-file placement; it
+does not weaken disk, memory, cleanup, or Docker preflight policy. A Bridge receipt remains
+`fullGateAttested=false` until the suite is registered with the live residue auditor and the required
+source/toolchain-identical repeat evidence is complete.
+
 ## Package smoke check
 
 From this package directory:

package/dist/bridge/bridge-chat.types.d.ts

@@ -0,0 +1,111 @@
+export declare const bridgeChatProtocolVersion = "chat_interactive_v1";
+export declare const bridgeChatUpdateRequiredCode = "update_required";
+export declare const bridgeChatMaxCallbackPayloadBytes: number;
+export declare const bridgeChatMaxProviderThreadIdChars = 256;
+export type BridgeChatAvailability = "available" | "degraded" | "unavailable";
+export type BridgeChatRequestedCapability = "text" | "cancel" | "resume" | "thread_continuity" | "attachment_handoffs" | "action_broker_grants";
+export type ChatTurnCallbackKind = "turn_started" | "output_delta" | "output_completed" | "failed" | "cancelled" | "expired";
+export type ChatTurnCallbackRedactionStatus = "redacted" | "not_applicable";
+export interface BridgeChatCapability {
+    readonly availability: BridgeChatAvailability;
+    readonly protocolVersion: string;
+    readonly supportedProviders: readonly string[];
+    readonly supportedModels: readonly string[];
+    readonly supportsTextStreaming: boolean;
+    readonly supportsCancel: boolean;
+    readonly supportsResume: boolean;
+    readonly supportsProviderThreadContinuity: boolean;
+    readonly supportsAttachments: boolean;
+    readonly supportsActionBrokerGrants: boolean;
+    readonly maxMessageBytes: number;
+    readonly maxContextRefs: number;
+    readonly unavailableCode?: string | null;
+    readonly unavailableReason?: string | null;
+}
+export interface ChatTurnDispatchPacket {
+    readonly chatRunId: string;
+    readonly conversationId: string;
+    readonly turnId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly providerKind: string;
+    readonly model: string;
+    readonly messages: readonly ChatTurnMessage[];
+    readonly contextRefs: readonly ChatTurnContextRef[];
+    readonly idempotencyKey: string;
+    readonly providerThreadId?: string | null;
+    readonly protocolVersion: typeof bridgeChatProtocolVersion;
+    readonly requestedCapabilities: readonly BridgeChatRequestedCapability[];
+    readonly attachmentHandoffs: readonly ChatAttachmentHandoffHandle[];
+    readonly actionBrokerGrants: readonly ChatActionBrokerGrant[];
+}
+export interface ChatTurnMessage {
+    readonly role: string;
+    readonly content: string;
+    readonly metadata?: Readonly<Record<string, unknown>> | null;
+}
+export interface ChatTurnContextRef {
+    readonly kind: string;
+    readonly refId: string;
+    readonly title?: string | null;
+    readonly summary?: string | null;
+    readonly metadata?: Readonly<Record<string, unknown>> | null;
+}
+export interface ChatAttachmentHandoffHandle {
+    readonly turnId: string;
+    readonly attachmentId: string;
+    readonly tempFileToken: string;
+    readonly mimeType: string;
+    readonly sizeBytes: number;
+    readonly sha256: string;
+    readonly fileNameDisplay: string;
+    readonly expiresAt: string;
+    readonly status: "available";
+}
+export interface ChatActionBrokerGrant {
+    readonly grantId: string;
+    readonly turnId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly allowedScopes: readonly string[];
+    readonly nonce: string;
+    readonly expiresAt: string;
+    readonly redactionStatus: ChatTurnCallbackRedactionStatus;
+}
+export interface ChatTurnCallbackEnvelope {
+    readonly callbackId: string;
+    readonly chatRunId: string;
+    readonly conversationId: string;
+    readonly turnId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly sequence: number;
+    readonly eventType: ChatTurnCallbackKind;
+    readonly redactionStatus: ChatTurnCallbackRedactionStatus;
+    readonly providerThreadId?: string | null;
+    readonly payload?: Readonly<Record<string, unknown>> | null;
+    readonly occurredAt?: string | null;
+    readonly protocolVersion: typeof bridgeChatProtocolVersion;
+}
+export interface ChatTurnCancelPacket {
+    readonly chatRunId?: string | null;
+    readonly conversationId?: string | null;
+    readonly turnId?: string | null;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerId?: string | null;
+    readonly runnerInstanceId?: string | null;
+    readonly providerThreadId?: string | null;
+    readonly reason?: string | null;
+    readonly payload?: Readonly<Record<string, unknown>> | null;
+    readonly requestedAt?: string | null;
+    readonly protocolVersion?: string | null;
+}
+export declare function unavailableBridgeChatCapability(protocolVersion?: string, unavailableCode?: string | null, unavailableReason?: string | null): BridgeChatCapability;
+export declare function normalizeBridgeChatCapability(value: BridgeChatCapability | null | undefined): BridgeChatCapability;
+export declare function parseChatTurnDispatchPacket(value: unknown, capability?: BridgeChatCapability): ChatTurnDispatchPacket;
+export declare function isTerminalChatTurnCallbackKind(kind: ChatTurnCallbackKind): boolean;
+export declare function assertBridgeChatCallbackPayload(value: unknown, label?: string): void;

package/dist/bridge/bridge-chat.types.js

@@ -0,0 +1,401 @@
+export const bridgeChatProtocolVersion = "chat_interactive_v1";
+export const bridgeChatUpdateRequiredCode = "update_required";
+export const bridgeChatMaxCallbackPayloadBytes = 256 * 1024;
+export const bridgeChatMaxProviderThreadIdChars = 256;
+const supportedAvailability = new Set(["available", "degraded", "unavailable"]);
+const supportedRequestedCapabilities = new Set([
+    "text",
+    "cancel",
+    "resume",
+    "thread_continuity",
+    "attachment_handoffs",
+    "action_broker_grants",
+]);
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const unixEpochMs = Date.parse("1970-01-01T00:00:00.000Z");
+const maxOpaqueHandleChars = 4096;
+const maxGrantNonceChars = 4096;
+const maxMetadataStringChars = 4096;
+export function unavailableBridgeChatCapability(protocolVersion = bridgeChatProtocolVersion, unavailableCode, unavailableReason) {
+    return {
+        availability: "unavailable",
+        protocolVersion: nonEmptyStringOr(protocolVersion, bridgeChatProtocolVersion),
+        supportedProviders: [],
+        supportedModels: [],
+        supportsTextStreaming: false,
+        supportsCancel: false,
+        supportsResume: false,
+        supportsProviderThreadContinuity: false,
+        supportsAttachments: false,
+        supportsActionBrokerGrants: false,
+        maxMessageBytes: 0,
+        maxContextRefs: 0,
+        unavailableCode: cleanOptionalString(unavailableCode),
+        unavailableReason: cleanOptionalString(unavailableReason),
+    };
+}
+export function normalizeBridgeChatCapability(value) {
+    if (!value) {
+        return unavailableBridgeChatCapability();
+    }
+    const protocolVersion = nonEmptyStringOr(value.protocolVersion, bridgeChatProtocolVersion);
+    if (protocolVersion !== bridgeChatProtocolVersion) {
+        return unavailableBridgeChatCapability(protocolVersion, bridgeChatUpdateRequiredCode, `Bridge Chat protocol '${protocolVersion}' is not supported by this bridge.`);
+    }
+    const availability = supportedAvailability.has(value.availability) ? value.availability : "unavailable";
+    return {
+        availability,
+        protocolVersion: bridgeChatProtocolVersion,
+        supportedProviders: cleanStringArray(value.supportedProviders, true),
+        supportedModels: cleanStringArray(value.supportedModels, false),
+        supportsTextStreaming: value.supportsTextStreaming === true,
+        supportsCancel: value.supportsCancel === true,
+        supportsResume: value.supportsResume === true,
+        supportsProviderThreadContinuity: value.supportsProviderThreadContinuity === true,
+        supportsAttachments: value.supportsAttachments === true,
+        supportsActionBrokerGrants: value.supportsActionBrokerGrants === true,
+        maxMessageBytes: nonNegativeInteger(value.maxMessageBytes),
+        maxContextRefs: nonNegativeInteger(value.maxContextRefs),
+        unavailableCode: availability === "unavailable" ? cleanOptionalString(value.unavailableCode) : null,
+        unavailableReason: availability === "unavailable" ? cleanOptionalString(value.unavailableReason) : null,
+    };
+}
+export function parseChatTurnDispatchPacket(value, capability = unavailableBridgeChatCapability()) {
+    const packet = asObject(value, "chat turn dispatch packet");
+    const protocolVersion = requiredString(packet, "protocolVersion");
+    if (protocolVersion !== bridgeChatProtocolVersion) {
+        throw new Error(`Unsupported chat protocolVersion: ${protocolVersion}`);
+    }
+    assertReservedFieldsAbsent(packet, "chat turn dispatch packet");
+    const normalizedCapability = normalizeBridgeChatCapability(capability);
+    const messages = parseMessages(packet.messages, normalizedCapability.maxMessageBytes);
+    const contextRefs = parseContextRefs(packet.contextRefs);
+    if (normalizedCapability.maxContextRefs > 0 && contextRefs.length > normalizedCapability.maxContextRefs) {
+        throw new Error("contextRefs exceeds maxContextRefs.");
+    }
+    const turnId = requiredUuid(packet, "turnId");
+    const leaseId = requiredUuid(packet, "leaseId");
+    const fencingToken = requiredUuid(packet, "fencingToken");
+    const requestedCapabilities = parseRequestedCapabilities(packet.requestedCapabilities, normalizedCapability);
+    const attachmentHandoffs = parseAttachmentHandoffs(packet.attachmentHandoffs, normalizedCapability, requestedCapabilities);
+    const actionBrokerGrants = parseActionBrokerGrants(packet.actionBrokerGrants, normalizedCapability, requestedCapabilities);
+    assertBoundedEnvelopesMatchFence(attachmentHandoffs, actionBrokerGrants, turnId, leaseId, fencingToken);
+    return {
+        chatRunId: requiredUuid(packet, "chatRunId"),
+        conversationId: requiredUuid(packet, "conversationId"),
+        turnId,
+        leaseId,
+        fencingToken,
+        runnerInstanceId: requiredUuid(packet, "runnerInstanceId"),
+        providerKind: requiredString(packet, "providerKind").trim().toLowerCase(),
+        model: requiredString(packet, "model").trim(),
+        messages,
+        contextRefs,
+        idempotencyKey: requiredString(packet, "idempotencyKey").trim(),
+        providerThreadId: optionalString(packet, "providerThreadId", bridgeChatMaxProviderThreadIdChars),
+        protocolVersion: bridgeChatProtocolVersion,
+        requestedCapabilities,
+        attachmentHandoffs,
+        actionBrokerGrants,
+    };
+}
+export function isTerminalChatTurnCallbackKind(kind) {
+    return kind === "output_completed" || kind === "failed" || kind === "cancelled" || kind === "expired";
+}
+export function assertBridgeChatCallbackPayload(value, label = "payload") {
+    if (value === undefined || value === null) {
+        return;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object when provided.`);
+    }
+    if (new TextEncoder().encode(JSON.stringify(value)).byteLength > bridgeChatMaxCallbackPayloadBytes) {
+        throw new Error(`${label} exceeds maxCallbackPayloadBytes.`);
+    }
+}
+function parseMessages(value, maxMessageBytes) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error("messages must be a non-empty array.");
+    }
+    return value.map((entry, index) => {
+        const message = asObject(entry, `messages[${index}]`);
+        assertReservedFieldsAbsent(message, `messages[${index}]`);
+        const content = requiredString(message, "content");
+        if (maxMessageBytes > 0 && new TextEncoder().encode(content).byteLength > maxMessageBytes) {
+            throw new Error(`messages[${index}].content exceeds maxMessageBytes.`);
+        }
+        return {
+            role: requiredString(message, "role").trim(),
+            content,
+            metadata: optionalObject(message.metadata, `messages[${index}].metadata`),
+        };
+    });
+}
+function parseContextRefs(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("contextRefs must be an array when provided.");
+    }
+    return value.map((entry, index) => {
+        const ref = asObject(entry, `contextRefs[${index}]`);
+        assertReservedFieldsAbsent(ref, `contextRefs[${index}]`);
+        return {
+            kind: requiredString(ref, "kind").trim(),
+            refId: requiredString(ref, "refId").trim(),
+            title: optionalString(ref, "title"),
+            summary: optionalString(ref, "summary"),
+            metadata: optionalObject(ref.metadata, `contextRefs[${index}].metadata`),
+        };
+    });
+}
+function parseAttachmentHandoffs(value, capability, requestedCapabilities) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("attachmentHandoffs must be an array when provided.");
+    }
+    if (value.length > 0 && !capability.supportsAttachments) {
+        throw new Error("Bridge Chat attachmentHandoffs require supportsAttachments.");
+    }
+    if (value.length > 0 && !requestedCapabilities.includes("attachment_handoffs")) {
+        throw new Error("Bridge Chat attachmentHandoffs require requestedCapabilities to include attachment_handoffs.");
+    }
+    return value.map((entry, index) => {
+        const handoff = asObject(entry, `attachmentHandoffs[${index}]`);
+        assertOnlyKeys(handoff, `attachmentHandoffs[${index}]`, [
+            "turnId",
+            "attachmentId",
+            "tempFileToken",
+            "mimeType",
+            "sizeBytes",
+            "sha256",
+            "fileNameDisplay",
+            "expiresAt",
+            "status",
+        ]);
+        const status = requiredString(handoff, "status").trim();
+        if (status !== "available") {
+            throw new Error(`attachmentHandoffs[${index}].status must be available.`);
+        }
+        return {
+            turnId: requiredUuid(handoff, "turnId"),
+            attachmentId: requiredUuid(handoff, "attachmentId"),
+            tempFileToken: boundedRequiredString(handoff, "tempFileToken", maxOpaqueHandleChars),
+            mimeType: boundedRequiredString(handoff, "mimeType", maxMetadataStringChars),
+            sizeBytes: requiredNonNegativeInteger(handoff, "sizeBytes"),
+            sha256: boundedRequiredString(handoff, "sha256", maxMetadataStringChars),
+            fileNameDisplay: boundedRequiredString(handoff, "fileNameDisplay", maxMetadataStringChars),
+            expiresAt: requiredFutureContractTimestamp(handoff, "expiresAt"),
+            status,
+        };
+    });
+}
+function parseActionBrokerGrants(value, capability, requestedCapabilities) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("actionBrokerGrants must be an array when provided.");
+    }
+    if (value.length > 0 && !capability.supportsActionBrokerGrants) {
+        throw new Error("Bridge Chat actionBrokerGrants require supportsActionBrokerGrants.");
+    }
+    if (value.length > 0 && !requestedCapabilities.includes("action_broker_grants")) {
+        throw new Error("Bridge Chat actionBrokerGrants require requestedCapabilities to include action_broker_grants.");
+    }
+    return value.map((entry, index) => {
+        const grant = asObject(entry, `actionBrokerGrants[${index}]`);
+        assertOnlyKeys(grant, `actionBrokerGrants[${index}]`, [
+            "grantId",
+            "turnId",
+            "leaseId",
+            "fencingToken",
+            "allowedScopes",
+            "nonce",
+            "expiresAt",
+            "redactionStatus",
+        ]);
+        const redactionStatus = requiredString(grant, "redactionStatus").trim();
+        if (redactionStatus !== "redacted" && redactionStatus !== "not_applicable") {
+            throw new Error(`actionBrokerGrants[${index}].redactionStatus is unsupported.`);
+        }
+        return {
+            grantId: requiredUuid(grant, "grantId"),
+            turnId: requiredUuid(grant, "turnId"),
+            leaseId: requiredUuid(grant, "leaseId"),
+            fencingToken: requiredUuid(grant, "fencingToken"),
+            allowedScopes: requiredSortedStringArray(grant, "allowedScopes"),
+            nonce: boundedRequiredString(grant, "nonce", maxGrantNonceChars),
+            expiresAt: requiredFutureContractTimestamp(grant, "expiresAt"),
+            redactionStatus,
+        };
+    });
+}
+function parseRequestedCapabilities(value, capability) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("requestedCapabilities must be an array when provided.");
+    }
+    return value.map((entry, index) => {
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            throw new Error(`requestedCapabilities[${index}] must be a non-empty string.`);
+        }
+        const requestedCapability = entry.trim().toLowerCase();
+        if (!supportedRequestedCapabilities.has(requestedCapability)) {
+            throw new Error(`Bridge Chat v1 does not support requestedCapabilities ${requestedCapability}.`);
+        }
+        if (requestedCapability === "attachment_handoffs" && !capability.supportsAttachments) {
+            throw new Error("Bridge Chat v1 does not support requestedCapabilities attachment_handoffs for this runner.");
+        }
+        if (requestedCapability === "action_broker_grants" && !capability.supportsActionBrokerGrants) {
+            throw new Error("Bridge Chat v1 does not support requestedCapabilities action_broker_grants for this runner.");
+        }
+        return requestedCapability;
+    });
+}
+function assertBoundedEnvelopesMatchFence(attachmentHandoffs, actionBrokerGrants, turnId, leaseId, fencingToken) {
+    attachmentHandoffs.forEach((handoff, index) => {
+        if (handoff.turnId !== turnId) {
+            throw new Error(`attachmentHandoffs[${index}].turnId must match turnId.`);
+        }
+    });
+    actionBrokerGrants.forEach((grant, index) => {
+        if (grant.turnId !== turnId || grant.leaseId !== leaseId || grant.fencingToken !== fencingToken) {
+            throw new Error(`actionBrokerGrants[${index}] must match the active dispatch fence.`);
+        }
+    });
+}
+function assertReservedFieldsAbsent(source, label) {
+    for (const key of ["attachments", "attachmentHandles", "actionGrants"]) {
+        if (source[key] !== undefined && source[key] !== null) {
+            throw new Error(`${label}.${key} is reserved for a later Bridge Chat protocol.`);
+        }
+    }
+}
+function assertOnlyKeys(source, label, allowedKeys) {
+    const allowed = new Set(allowedKeys);
+    for (const key of Object.keys(source)) {
+        if (!allowed.has(key)) {
+            throw new Error(`${label}.${key} is not supported by Bridge Chat v1.`);
+        }
+    }
+}
+function asObject(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object.`);
+    }
+    return value;
+}
+function optionalObject(value, label) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    return asObject(value, label);
+}
+function requiredUuid(source, key) {
+    const value = requiredString(source, key).trim();
+    if (!uuidPattern.test(value)) {
+        throw new Error(`${key} must be a UUID.`);
+    }
+    return value;
+}
+function requiredString(source, key) {
+    const value = source[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${key} must be a non-empty string.`);
+    }
+    return value;
+}
+function boundedRequiredString(source, key, maxLength) {
+    const clean = requiredString(source, key).trim();
+    if (clean.length > maxLength) {
+        throw new Error(`${key} exceeds ${maxLength} characters.`);
+    }
+    return clean;
+}
+function requiredNonNegativeInteger(source, key) {
+    const value = source[key];
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`${key} must be a non-negative integer.`);
+    }
+    return value;
+}
+function requiredSortedStringArray(source, key) {
+    const value = source[key];
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`${key} must be a non-empty string array.`);
+    }
+    const cleaned = value.map((entry, index) => {
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            throw new Error(`${key}[${index}] must be a non-empty string.`);
+        }
+        return entry.trim();
+    });
+    if (new Set(cleaned).size !== cleaned.length) {
+        throw new Error(`${key} must not contain duplicate values.`);
+    }
+    const sorted = [...cleaned].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+    if (cleaned.some((scope, index) => scope !== sorted[index])) {
+        throw new Error(`${key} must be sorted.`);
+    }
+    return cleaned;
+}
+function requiredFutureContractTimestamp(source, key) {
+    const value = requiredString(source, key).trim();
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed) || parsed <= unixEpochMs) {
+        throw new Error(`${key} is required.`);
+    }
+    return value;
+}
+function optionalString(source, key, maxLength) {
+    const value = source[key];
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "string") {
+        throw new Error(`${key} must be a string when provided.`);
+    }
+    const clean = value.trim();
+    if (clean.length === 0) {
+        return null;
+    }
+    if (maxLength !== undefined && clean.length > maxLength) {
+        throw new Error(`${key} exceeds maxProviderThreadIdChars.`);
+    }
+    return clean;
+}
+function cleanOptionalString(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const clean = value.trim();
+    return clean.length === 0 ? null : clean;
+}
+function nonEmptyStringOr(value, fallback) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
+function cleanStringArray(values, lower) {
+    const seen = new Set();
+    const cleaned = [];
+    for (const value of values) {
+        if (typeof value !== "string" || value.trim().length === 0) {
+            continue;
+        }
+        const clean = lower ? value.trim().toLowerCase() : value.trim();
+        const key = clean.toLowerCase();
+        if (!seen.has(key)) {
+            seen.add(key);
+            cleaned.push(clean);
+        }
+    }
+    return cleaned;
+}
+function nonNegativeInteger(value) {
+    return Number.isSafeInteger(value) && value > 0 ? value : 0;
+}

package/dist/bridge/bridge.base.d.ts

@@ -1,4 +1,4 @@
-import type { BridgeCancelHandler, BridgeDispatchHandler, BridgeLeaseUpdateHandler, BridgeOfferHandler, BridgeReadinessProbeHandler, BridgeReapHandler, BridgeServiceConfig, BridgeStartHandler } from "./bridge.types.js";
+import type { BridgeCancelHandler, BridgeChatTurnHandler, BridgeDispatchHandler, BridgeLeaseUpdateHandler, BridgeOfferHandler, BridgeReadinessProbeHandler, BridgeReapHandler, BridgeServiceConfig, BridgeStartHandler } from "./bridge.types.js";
 export interface BridgeService {
     connectOnce(): Promise<void>;
     run(signal?: AbortSignal): Promise<void>;
@@ -8,7 +8,10 @@ export interface BridgeConnection {
     start(): Promise<void>;
     stop(): Promise<void>;
     onClose(handler: (error?: Error) => void): void;
+    onReconnecting?(handler: (error?: Error) => void): void;
+    onReconnected?(handler: (connectionId?: string) => void | Promise<void>): void;
     onDispatch(handler: BridgeDispatchHandler): void;
+    onChatTurn?(handler: BridgeChatTurnHandler): void;
     onOffer?(handler: BridgeOfferHandler): void;
     onStart?(handler: BridgeStartHandler): void;
     onLeaseUpdate?(handler: BridgeLeaseUpdateHandler): void;