@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.1ff37038366e

package/README.md

@@ -31,7 +31,44 @@ 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`:
+
+```bash
+forge-bridge server show
+forge-bridge server set http://localhost:5208
+forge-bridge server set https://srv1493013.tail66073d.ts.net:8443
+```
+
+`FORGE_URL` overrides the saved server. Changing the saved URL retains runner credentials so aliases for the same deployment keep working; pair again with `--server` when switching to a different Forge deployment.
 
 ## Repo-local development
 
@@ -53,6 +90,133 @@ 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:
+
+```bash
+forge sandbox init
+forge sandbox doctor
+forge sandbox smoke
+forge-bridge sandbox reap
+```
+
+Configure the local bridge's persistent Docker placement policy with:
+
+```bash
+forge-bridge sandbox on
+forge-bridge sandbox on --allow-open-public
+forge-bridge sandbox status
+forge-bridge sandbox off
+```
+
+`sandbox on` keeps unrestricted public networking denied by default. The developer-only
+`--allow-open-public` option stores an explicit local approval in `bridge.json`; it survives
+bridge restarts and is reported by `sandbox status`. Restart a connected bridge after changing
+the policy. `FORGE_DOCKER_SANDBOX` and `FORGE_ALLOW_OPEN_PUBLIC_SANDBOX` remain higher-priority
+operator overrides when present.
+
+`forge sandbox smoke` runs doctor, builds the repository-owned `.forge/Dockerfile`, launches a disposable hardened container on an internal network with a fresh workspace volume, and verifies that its exact attempt-labeled container, network, volume, and image are gone afterward. It writes a redacted JSON report under `FORGE_SANDBOX_STATE_ROOT/smoke-reports`; use `--report <path>` to choose a different destination. Stop the connected bridge before running smoke so the command can exclusively acquire the Docker-context ownership lock.
+
+Use `forge sandbox smoke --probe-loopback-port` only when proving Docker host-port allocation. The normal hardened container remains internal with no publication; a separate exact-labeled fixture requests `127.0.0.1::8080/tcp`, records Docker's assigned loopback port, rejects wildcard or ambiguous mappings, and is removed by the same exact-label cleanup verification.
+
+Production shared runners require a Linux rootless Docker daemon. Docker Desktop is developer-only and must be opted in with `FORGE_ALLOW_DOCKER_DESKTOP_SANDBOX=true`. Useful runner settings are:
+
+- `FORGE_TRUST_DOMAIN_ID` — must match the project trust domain.
+- `FORGE_MAX_CONCURRENT_SANDBOXES` — hard slot ceiling; start at `1`.
+- `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.
+- 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).
+- `FORGE_SANDBOX_AUDIT_RETENTION_COUNT` / `FORGE_SANDBOX_AUDIT_RETENTION_TTL_MS` — restricted failed-build/attestation retention (defaults: 200 keys and 30 days); evidence for active image digests is protected.
+- `FORGE_AGENT_TOOLING_IMAGE` — digest-pinned Node tooling base required by `sandbox_required`.
+- `FORGE_SANDBOX_IMAGE_POLICY_ENFORCED`, `FORGE_SANDBOX_SBOM_EXECUTABLE`, `FORGE_SANDBOX_VULNERABILITY_EXECUTABLE`, and `FORGE_SANDBOX_PROVENANCE_SIGNING_KEY` — required generated-image promotion gates. The SBOM command must accept Syft-compatible `<image> -o spdx-json`; the vulnerability command must accept Trivy-compatible image arguments.
+- `FORGE_SANDBOX_SIGNATURE_EXECUTABLE` / `FORGE_SANDBOX_SIGNATURE_PUBLIC_KEY` — Cosign-compatible verifier and bounded public-key file. `sandbox_required` verifies every digest-pinned external Dockerfile base/`COPY --from` source and Forge tooling base before generated-image promotion, plus every service-catalog and egress-proxy image before runtime use; adoption modes emit a warning when verification is not configured.
+- `FORGE_SANDBOX_BUILD_EGRESS_ENFORCED` — confirms the dedicated BuildKit builder is behind the approved build-egress control; required for `sandbox_required`.
+- `FORGE_SANDBOX_BUILD_NOFILE` — bounded per-build-step file-descriptor cap (default: `4096`). `FORGE_SANDBOX_BUILDER_PIDS_LIMIT` caps and verifies aggregate processes on the dedicated BuildKit container (default `512`). Buildx `--resource` memory/CPU caps are intentionally not emitted because they are not portable across supported Buildx versions; agent runtime containers still receive Docker memory/CPU limits.
+- `FORGE_SANDBOX_BUILDKIT_CACHE_MAX` / `FORGE_SANDBOX_BUILDKIT_CACHE_RESERVED` — pressure-triggered dedicated-builder cache bounds (defaults: 20 GiB maximum and 2 GiB reserved; minimum free space follows `FORGE_MINIMUM_WORKSPACE_BYTES`).
+- `FORGE_SANDBOX_SECCOMP_PROFILE` / `FORGE_SANDBOX_LSM_SECURITY_OPT` — absolute hardened seccomp profile and AppArmor/SELinux Docker security option applied to every agent and service; required for `sandbox_required`.
+- `FORGE_SANDBOX_HARD_WALL_SECONDS` / `FORGE_SANDBOX_IDLE_SECONDS` — monotonic worker deadlines (defaults: 8 hours and 30 minutes; both are capped by the 8-hour hard maximum).
+- `FORGE_SANDBOX_PUBLICATION_MODE=bridge_push` — remote-safe exact-SHA result publication. This is required for `sandbox_required`; the default `shared_filesystem` mode is intended only for deployments where the bridge and API intentionally share the repository filesystem.
+- `FORGE_SERVICE_POSTGRES_IMAGE`, `FORGE_SERVICE_REDIS_IMAGE`, and `FORGE_SERVICE_BROWSER_IMAGE` — digest-pinned service-catalog images when declared by a contract.
+
+`public_allowlist` uses an internal agent network plus a separate external network joined only by a restricted Squid-compatible proxy. Configure a digest-pinned `FORGE_SANDBOX_EGRESS_PROXY_IMAGE` and `FORGE_SANDBOX_EGRESS_ENFORCED=true`; Forge generates the domain allowlist with private, loopback, link-local, metadata, unsafe-port, and default-deny rules and injects proxy variables into the worker. `open_public` is developer-only and additionally requires `FORGE_ALLOW_OPEN_PUBLIC_SANDBOX=true`. Neither setting weakens `sandbox_required`.
+
+Before selecting `sandbox_required`, save the full approved 40- or 64-character Git commit SHA in the project's Sandbox policy dialog. The server persists that SHA on the immutable attempt and the bridge reads `.forge/forge.sandbox.yml`, `.forge/Dockerfile`, and the tracked build context only from that commit. API-key dispatches carry an opaque one-time grant handle; the authenticated current runner instance redeems it after reservation, and plaintext stays out of offers, database payloads, Docker metadata, and host-persisted control files.
+
+Temporary host fallback for `sandbox_preferred` requires both sides to opt in: a project owner must save a reason and future expiry (maximum 30 days), and an operator must enable **Host fallback** for the runner in Profile Settings. Either missing or expired authorization fails closed. `sandbox_required` never falls back.
+
+The bridge reaps exact-labeled orphan resources before connecting and every minute afterward. Connected passes reconcile current-instance ledgers against an authoritative, instance-scoped server attempt snapshot; startup does not adopt old-instance resources and terminates them before advertising capacity. Per-resource removal outcomes are written mode-0600 under `FORGE_SANDBOX_STATE_ROOT/cleanup-reports` before transmission, replayed after reconnect, acknowledged by report ID, and persisted by the API only when attempt, fence, resource runner instance, and current reporting runner match. Fenced dispatch events also persist image/cache status, build/agent-start/import/teardown timestamps, and a validated inventory of created agent/sidecar containers, networks, volumes, and published ports. Selected-session diagnostics expose that lifecycle data and recent cleanup actions while retaining cleanup-pending state after the agent outcome is terminal. Install `forge-bridge sandbox reap` as an independently supervised OS timer with the same `FORGE_RUNNER_ID`, Docker context, and state root so resources are reconciled while the bridge is down; the Docker-context ownership lock makes an overlapping pass fail safely. A non-zero `degradedReservationCount` means teardown has not completed; the affected capacity remains unavailable until a successful reaper pass. Drain a runner from Profile Settings before upgrades or Docker maintenance, wait for active/starting counts to reach zero, then restart the bridge. Profile Settings also exposes a scoped **Reap** action; the API delivers it only to the currently established protocol-v2 runner instance. Image GC runs only while disk pressure is latched, shares the build lock, preserves active image digests, and prunes only expired images beyond the per-project retention count. Lease renewals are HMAC-bound to the attempt and fence and advance an in-container monotonic deadline; lease, hard-wall, and idle expiry produce distinct failure codes.
+
+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;