@tangle-network/agent-app 0.43.46 → 0.43.47

package/dist/turn-stream/index.d.ts

@@ -0,0 +1,551 @@
+import { R as ReconcileStaleTurnLockOptions } from '../stale-turn-lock-C8Na1cFZ.js';
+import { d as TurnEventStore } from '../turn-buffer-C9mEgoop.js';
+
+/**
+ * `/turn-stream` core — the pure, substrate-free half of the shared durable
+ * turn replay/broadcast/lock channel (issue #221).
+ *
+ * Extracted from the reference consumer's hand-rolled Durable Object
+ * (gtm-agent `SessionStreamDO` + `session-broadcast.ts`): the per-turn
+ * segment store that backs reconnect replay over a live socket, the
+ * single-flight chat-turn lock record and its release fences, and the wire
+ * contract (channel keys, endpoint paths, request/response bodies) shared by
+ * the DO transport shell (`./do`) and the worker-side adapters
+ * (`./adapters`). Everything here is plain data + functions — no
+ * `cloudflare:workers`, no storage, no sockets — so the semantics are
+ * unit-testable in Node and the DO stays a thin shell.
+ */
+/** One event on a turn-stream channel. `seq` is monotonic within a turn
+ *  segment and assigned by {@link appendSegmentEvent} on arrival at the DO. */
+interface TurnStreamEvent {
+    type: string;
+    data?: unknown;
+    timestamp: number;
+    seq?: number;
+}
+/** Terminal run markers: they close a turn segment and auto-release the
+ *  channel's chat-turn lock for the segment's execution. */
+declare function isTerminalRunEvent(type: string): boolean;
+type TurnLockScope = 'thread' | 'workspace';
+declare function threadChannelKey(workspaceId: string, threadId: string): string;
+declare function workspaceChannelKey(workspaceId: string): string;
+/** The channel a lock lives on: workspace-scope locks serialize every thread
+ *  in the workspace (one shared sandbox), thread-scope locks serialize one
+ *  thread (router lane). Same keying as the reference consumer, so a product
+ *  swapping its fork for this package contends on identical instances. */
+declare function turnLockChannelKey(workspaceId: string, threadId: string, scope: TurnLockScope): string;
+declare function turnStorageChannelKey(turnId: string): string;
+declare function scopeIndexChannelKey(scopeId: string): string;
+interface TurnSegment {
+    events: TurnStreamEvent[];
+    maxSeq: number;
+    terminal: boolean;
+}
+interface SegmentStore {
+    segments: Map<string, TurnSegment>;
+    activeExecutionId: string | null;
+}
+/** Per-turn replay window. Generous enough for normal turns; a turn that
+ *  exceeds it loses its earliest deltas from replay (a late resumer
+ *  self-heals via the final `result` event + loader revalidation). */
+declare const MAX_SEGMENT_EVENTS = 2000;
+/** Recent `thread.created` markers kept for late-connecting sidebars. */
+declare const MAX_RECENT_CREATED = 50;
+/** A responding marker older than this is treated as stale, so a dropped
+ *  `end` broadcast can't leave a permanently-stuck "responding" dot. */
+declare const ACTIVITY_TTL_MS: number;
+declare function createSegmentStore(): SegmentStore;
+/**
+ * Append a per-turn event to its execution's segment, assigning a monotonic
+ * `seq`. A `session.run.started` (or the first-seen event for an execution)
+ * opens a fresh segment, makes it active, and drops prior turns' buffers so a
+ * resumer only ever replays the current turn. A terminal run event marks the
+ * segment terminal. Returns the seq-stamped event to broadcast.
+ */
+declare function appendSegmentEvent(store: SegmentStore, executionId: string, incoming: TurnStreamEvent, maxEvents?: number): TurnStreamEvent;
+/**
+ * Events of the active, non-terminal turn with `seq > afterSeq` — what a
+ * (re)connecting client replays before going live. A terminal (finished) turn
+ * replays nothing: the client falls back to the loader's persisted row.
+ */
+declare function replayActiveSegment(store: SegmentStore, afterSeq: number): TurnStreamEvent[];
+/**
+ * Remove responding entries (threadId → startedAt) older than `ttlMs`, so a
+ * dropped `end` broadcast can't leave a permanently-stuck dot. Mutates
+ * `active` and returns the removed thread ids.
+ */
+declare function pruneStaleThreads(active: Map<string, number>, now: number, ttlMs: number): string[];
+/** Default lifetime of an unreleased lock. Long enough that a legitimately
+ *  slow sandbox turn never loses its guard mid-run; the way OUT of a wedge is
+ *  never the TTL but `reconcileStaleTurnLock` (in `/chat-routes`), which
+ *  probes the execution's actual state. */
+declare const TURN_LOCK_TTL_MS: number;
+/** The stored single-flight lock. Field-compatible with the reference
+ *  consumer's `ChatTurnLock` so adoption is a swap, not a migration. */
+interface DurableTurnLock {
+    workspaceId: string;
+    threadId: string;
+    scope: TurnLockScope;
+    executionId: string;
+    lockId: string;
+    startedAt: number;
+    expiresAt: number;
+    turnId?: string;
+    /** The turn released this lock, but a product-owned post-turn task (e.g.
+     *  file persistence reading the box) is still running, so the release is
+     *  parked on the lock until the task settles. Written only through the DO's
+     *  defer seam — the base package never sets it on its own. */
+    releasePending?: boolean;
+}
+interface TurnLockAcquireInput {
+    workspaceId: string;
+    threadId: string;
+    scope: TurnLockScope;
+    executionId: string;
+    lockId: string;
+    turnId?: string;
+}
+type TurnLockAcquireResult = {
+    acquired: true;
+    lock: DurableTurnLock;
+} | {
+    acquired: false;
+    active: DurableTurnLock;
+};
+interface TurnLockReleaseInput {
+    workspaceId: string;
+    threadId: string;
+    scope: TurnLockScope;
+    executionId: string;
+    lockId: string;
+}
+/** Fenced out-of-band release (stop button, stale-lock reconciliation). The
+ *  fences make it refuse a SUCCESSOR lock: `interruptedAt` must not precede
+ *  the lock's own start, and when either side names a turn, both must name
+ *  the same one. */
+interface TurnLockInterruptedReleaseInput {
+    workspaceId: string;
+    threadId: string;
+    /** Try only this scope; omit to try workspace then thread. */
+    scope?: TurnLockScope;
+    interruptedAt: number;
+    turnId?: string;
+}
+/** `stored` is what the DO read from storage; expired locks are dead. */
+declare function activeTurnLock(stored: DurableTurnLock | undefined, now: number): DurableTurnLock | null;
+declare function createTurnLock(input: TurnLockAcquireInput, now: number, ttlMs?: number): DurableTurnLock;
+/** A cooperative release must present the lock's own identity — both the
+ *  execution and the lockId minted at acquire — so a retry of a PREVIOUS turn
+ *  can never release the current one. `lockId` is optional only for the DO's
+ *  internal terminal-event auto-release, which knows the execution but not
+ *  the caller-held lockId. */
+declare function turnLockMatchesRelease(active: DurableTurnLock, input: {
+    executionId: string;
+    lockId?: string;
+}): boolean;
+/**
+ * The interrupted/stale release fence. `interruptedAt` is the instant the
+ * releasing evidence was observed (the stop click, the stale-lock probe) —
+ * a lock STARTED after that instant is a successor the evidence says nothing
+ * about, so it survives. When the lock recorded a client turnId, the release
+ * must name the same turn; a lock without one refuses a turn-specific
+ * release (it cannot prove it is that turn).
+ */
+declare function interruptedReleaseApplies(active: DurableTurnLock, input: {
+    threadId: string;
+    interruptedAt: number;
+    turnId?: string;
+}): boolean;
+declare const TURN_STREAM_PATHS: {
+    readonly broadcast: "/broadcast";
+    readonly lockAcquire: "/chat-turn-lock/acquire";
+    readonly lockRelease: "/chat-turn-lock/release";
+    readonly lockReleaseInterrupted: "/chat-turn-lock/release-interrupted";
+    readonly turnEventsAppend: "/turn-events/append";
+    readonly turnEventsRead: "/turn-events/read";
+    readonly turnStatusSet: "/turn-status/set";
+    readonly turnStatusGet: "/turn-status/get";
+    readonly scopeStatusSet: "/turn-scope/set";
+    readonly scopeRunningList: "/turn-scope/running";
+};
+/** Storage keys inside a DO instance. Exported for subclass coexistence —
+ *  a product extending the DO must not collide with these. */
+declare const TURN_STREAM_STORAGE_KEYS: {
+    readonly lock: "chatTurnLock";
+    readonly activeThreads: "activeThreads";
+    readonly turnStatus: "turnStatus";
+    readonly turnScope: "turnScopeIndex";
+    readonly turnEventPrefix: "turnEvent:";
+};
+/** Zero-padded seq so DO storage `list({ prefix })` returns rows in replay
+ *  order without a sort. 10 digits holds any realistic turn. */
+declare function turnEventStorageKey(seq: number): string;
+
+/**
+ * `TurnStreamDO` — the shared Durable Object transport shell over the pure
+ * core (`./core`). One class serves every channel family; the instance NAME
+ * decides which endpoints a given instance ever sees:
+ *
+ * - **thread channel** (`${workspaceId}:${threadId}`) — the live chat turn:
+ *   WebSocket fanout, per-turn segments with `sync`/`afterSeq` reconnect
+ *   replay, and the thread-scope lock.
+ * - **workspace channel** (`${workspaceId}`) — coarse sidebar signals
+ *   (`thread.activity` responding set, durable across eviction;
+ *   `thread.created` recent list) and the workspace-scope lock.
+ * - **turn storage** (`turn:${turnId}`) — the durable `TurnEventStore` rows +
+ *   status for one buffered turn (replay survives DO eviction — this is what
+ *   graduates the vertical's `turnStore` from no-op).
+ * - **scope index** (`scope:${scopeId}`) — the running-turn index backing
+ *   `TurnEventStore.listRunning` reconnect discovery.
+ *
+ * The class is a PLAIN class over a structural {@link TurnStreamDOState} —
+ * no `cloudflare:workers` import, so this package stays substrate-free and
+ * the DO is unit-testable in Node. Cloudflare's `DurableObjectState`
+ * satisfies the interface; a product binds it in wrangler by re-exporting:
+ *
+ *   // worker entry
+ *   export { TurnStreamDO } from '@tangle-network/agent-app/turn-stream'
+ *
+ * Fan-out enumerates `state.getWebSockets()` (never an in-memory socket map)
+ * and reads per-socket metadata from the serialized attachment, so it is
+ * correct across WebSocket hibernation.
+ *
+ * Product extension (how the reference consumer keeps its Vault machinery
+ * while deleting its fork): subclass and override
+ * {@link TurnStreamDO.handleProductRequest} (extra POST endpoints),
+ * {@link TurnStreamDO.shouldDeferLockRelease} /
+ * {@link TurnStreamDO.completeDeferredLockRelease} (park a lock release
+ * behind a product-owned post-turn task), and
+ * {@link TurnStreamDO.productSyncEvents} (extra state replayed to a
+ * late-connecting socket). Product storage keys must avoid
+ * {@link TURN_STREAM_STORAGE_KEYS}.
+ */
+
+/** The socket surface the DO touches. Cloudflare's hibernatable `WebSocket`
+ *  satisfies it. */
+interface TurnStreamSocket {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    serializeAttachment(value: unknown): void;
+    deserializeAttachment(): unknown;
+}
+/** The storage surface the DO touches (Cloudflare `DurableObjectStorage`
+ *  satisfies it structurally). `list` must return keys in ascending order —
+ *  the turn-event rows rely on it for replay order. */
+interface TurnStreamStorage {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    put<T = unknown>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<boolean | void>;
+    list<T = unknown>(options: {
+        prefix: string;
+        start?: string;
+    }): Promise<Map<string, T>>;
+}
+/** The `DurableObjectState` surface the DO uses. */
+interface TurnStreamDOState {
+    storage: TurnStreamStorage;
+    acceptWebSocket(ws: TurnStreamSocket): void;
+    getWebSockets(): TurnStreamSocket[];
+}
+interface TurnStreamDOOptions {
+    /** Override {@link TURN_LOCK_TTL_MS}. */
+    lockTtlMs?: number;
+    /** Override {@link MAX_SEGMENT_EVENTS}. */
+    maxSegmentEvents?: number;
+    /** Override {@link ACTIVITY_TTL_MS}. */
+    activityTtlMs?: number;
+}
+declare class TurnStreamDO {
+    protected readonly state: TurnStreamDOState;
+    protected readonly env: unknown;
+    protected readonly options: TurnStreamDOOptions;
+    private segments;
+    private recentCreated;
+    private activeThreads;
+    constructor(state: TurnStreamDOState, env?: unknown, options?: TurnStreamDOOptions);
+    fetch(request: Request): Promise<Response>;
+    /** Called for any request no base endpoint claimed (before the 404), so a
+     *  subclass adds product endpoints without touching base routing. Return
+     *  `null` to decline. */
+    protected handleProductRequest(_request: Request, _url: URL): Promise<Response | null>;
+    /** Consulted before any lock release (cooperative, interrupted, or the
+     *  terminal-event auto-release). Return `true` while a product-owned
+     *  post-turn task for `executionId` must keep the scope serialized (e.g.
+     *  file persistence still reading the box) — the release is then parked as
+     *  `releasePending` on the lock and completed via
+     *  {@link completeDeferredLockRelease}. Base: never defer. */
+    protected shouldDeferLockRelease(_executionId: string): Promise<boolean>;
+    /** Complete a release parked by {@link shouldDeferLockRelease}. A subclass
+     *  calls this when its deferred condition settles. */
+    protected completeDeferredLockRelease(executionId: string): Promise<boolean>;
+    /** Extra product state replayed to a socket during its `sync`, after the
+     *  base replay for its scope (e.g. an in-flight persistence status card).
+     *  Base: none. */
+    protected productSyncEvents(_scope: 'thread' | 'workspace', _meta: {
+        sessionId: string;
+    }): Promise<TurnStreamEvent[]>;
+    private handleWebSocketUpgrade;
+    /**
+     * First (and only) client message after open: `{ type: 'sync', afterSeq }`.
+     * Replays the current state for the socket's scope, then marks it `synced`
+     * so live broadcasts start flowing. Because the DO is single-threaded, the
+     * replay snapshot and the synced flip are atomic w.r.t. broadcasts — every
+     * event reaches the socket exactly once, in order, via replay XOR live
+     * fan-out.
+     */
+    webSocketMessage(ws: TurnStreamSocket, message: string | ArrayBuffer): Promise<void>;
+    webSocketClose(ws: TurnStreamSocket, code: number, reason: string): void;
+    webSocketError(): void;
+    private trySend;
+    private handleBroadcast;
+    private loadActiveThreads;
+    private persistActiveThreads;
+    protected loadActiveLock(now?: number): Promise<DurableTurnLock | null>;
+    private releaseActiveLock;
+    /** Park a release on the lock itself; {@link completeDeferredLockRelease}
+     *  finishes it once the product's deferred condition settles. */
+    private deferLockRelease;
+    private handleLockAcquire;
+    private handleLockRelease;
+    private handleLockReleaseInterrupted;
+    private handleTurnEventsAppend;
+    private handleTurnEventsRead;
+    private handleTurnStatusSet;
+    private handleTurnStatusGet;
+    private handleScopeStatusSet;
+    private handleScopeRunningList;
+}
+
+/**
+ * Worker-side adapters over {@link TurnStreamDO}: the concrete implementations
+ * of the chat vertical's `turnStore` and `turnLock` seams, the WebSocket
+ * upgrade forwarder, the best-effort broadcast helpers, and an in-process
+ * memory harness for tests and keyless local dev.
+ *
+ * Everything takes the namespace STRUCTURALLY ({@link TurnStreamNamespaceLike}
+ * — Cloudflare's `DurableObjectNamespace` satisfies it), so nothing here
+ * imports Cloudflare types and the same adapters run against the memory
+ * harness in vitest.
+ *
+ * Live fanout is deliberately NOT a side effect of the turn-event store: the
+ * store is keyed by turnId/scopeId while viewer sockets live on the
+ * `${workspaceId}:${threadId}` channel, and only the product's per-turn
+ * context knows both. Products wire {@link broadcastTurnStreamEvent} (and the
+ * workspace helpers) into `createChatTurnRoutes`' `onEvent` — the same
+ * contract the reference consumer already runs.
+ */
+
+interface TurnStreamStubLike {
+    fetch(input: Request | string, init?: RequestInit): Promise<Response>;
+}
+/** The surface of `DurableObjectNamespace` the adapters use. */
+interface TurnStreamNamespaceLike {
+    idFromName(name: string): unknown;
+    get(id: unknown): TurnStreamStubLike;
+}
+/**
+ * A {@link TurnEventStore} backed by {@link TurnStreamDO} storage — the
+ * production implementation of `createChatTurnRoutes`' `turnStore` seam for
+ * apps that don't run D1 for turn events (or want replay co-located with the
+ * live channel). Each buffered turn lives on its own `turn:<turnId>` DO
+ * instance; `listRunning` reconnect discovery rides a per-scope index
+ * instance. Drops in wherever `createD1TurnEventStore(env.DB)` would.
+ */
+declare function createDurableObjectTurnEventStore(namespace: TurnStreamNamespaceLike): TurnEventStore;
+interface AcquireDurableTurnLockInput {
+    workspaceId: string;
+    threadId: string;
+    scope: TurnLockScope;
+    executionId: string;
+    turnId?: string;
+    /** Supply to reclaim/retry with a stable id; default mints a UUID. */
+    lockId?: string;
+}
+declare function acquireDurableTurnLock(namespace: TurnStreamNamespaceLike, input: AcquireDurableTurnLockInput): Promise<TurnLockAcquireResult>;
+declare function releaseDurableTurnLock(namespace: TurnStreamNamespaceLike, input: TurnLockReleaseInput): Promise<{
+    released: boolean;
+    deferred?: boolean;
+}>;
+interface ReleaseInterruptedDurableTurnLockInput {
+    workspaceId: string;
+    threadId: string;
+    /** Try only this scope; omit to try workspace then thread (a stop button
+     *  doesn't know which lane the wedged turn ran on). */
+    scope?: TurnLockScope;
+    interruptedAt: number;
+    turnId?: string;
+}
+/** Fenced out-of-band release — the DO refuses a successor lock (started
+ *  after `interruptedAt`) and a turnId mismatch. Returns whether any scope
+ *  released. */
+declare function releaseInterruptedDurableTurnLock(namespace: TurnStreamNamespaceLike, input: ReleaseInterruptedDurableTurnLockInput): Promise<boolean>;
+interface ReconcileStaleDurableTurnLockOptions extends Pick<ReconcileStaleTurnLockOptions, 'probeSandbox' | 'probeSession' | 'graceMs' | 'terminalGraceMs' | 'context' | 'log' | 'now'> {
+    namespace: TurnStreamNamespaceLike;
+    workspaceId: string;
+    threadId: string;
+    /** The lock the acquire attempt was refused on. */
+    active: DurableTurnLock;
+}
+/**
+ * `/chat-routes`' `reconcileStaleTurnLock` policy wired to the DO: the
+ * product supplies the probes (which box, what its session says), the policy
+ * decides, and a release lands as a FENCED interrupted release —
+ * `interruptedAt` is the policy's `fence.observedAt`, so a successor lock
+ * acquired while the probes were in flight survives by construction.
+ */
+declare function reconcileStaleDurableTurnLock(options: ReconcileStaleDurableTurnLockOptions): Promise<{
+    released: boolean;
+    diagnostics: Record<string, unknown>;
+}>;
+/** The subset of `ChatTurnProduceArgs` the lock adapter reads — structural,
+ *  so this module needs no import from `/chat-routes/turn-routes` (which
+ *  would drag the `agent-runtime` peer into every `/turn-stream` consumer). */
+interface TurnLockSeamArgs<TContext> {
+    identity: {
+        tenantId: string;
+        sessionId: string;
+    };
+    executionId: string;
+    context: TContext;
+    body: {
+        turnId?: string;
+    };
+}
+/** Verdict shape of the vertical's `turnLock.acquire`. */
+type TurnLockSeamResult = {
+    acquired: true;
+    handle?: unknown;
+} | {
+    acquired: false;
+    response: Response;
+};
+interface CreateDurableTurnLockOptions<TContext> {
+    namespace: TurnStreamNamespaceLike;
+    /** Which lane serializes this turn: `'workspace'` (shared sandbox — one
+     *  turn per workspace) or `'thread'` (router lane — one turn per thread). */
+    scopeOf(args: TurnLockSeamArgs<TContext>): TurnLockScope;
+    /** Override the execution id the lock records (e.g. a follow-up reclaiming
+     *  the execution it already dispatched). Default: the turn's own. */
+    lockExecutionIdOf?(args: TurnLockSeamArgs<TContext>): string | undefined;
+    /** Client turn id recorded on the lock (fences interrupted releases to the
+     *  right turn). Default: the request body's `turnId`. */
+    clientTurnIdOf?(args: TurnLockSeamArgs<TContext>): string | undefined;
+    /**
+     * Attempt stale-lock recovery after a refused acquire. Return whether the
+     * held lock was released (the adapter then retries the acquire once).
+     * Products wire {@link reconcileStaleDurableTurnLock} with their sandbox +
+     * session probes here. Omit → a refused acquire is final.
+     */
+    reconcile?(args: TurnLockSeamArgs<TContext>, active: DurableTurnLock): Promise<{
+        released: boolean;
+        diagnostics?: Record<string, unknown>;
+    }>;
+    /** Build the refusal `Response`. Default: a 409 with the shared body shape
+     *  (`code`, `message`, lock identity + age, reconcile diagnostics). */
+    onRefused?(active: DurableTurnLock, diagnostics: Record<string, unknown> | undefined): Response;
+}
+/**
+ * The vertical's `turnLock` seam on the shared DO: dual-scope single-flight
+ * acquire (with one reconcile-then-retry pass when the product supplies a
+ * stale-lock reconciler) and cooperative release on settle. The returned
+ * object satisfies `createChatTurnRoutes`' `ChatTurnLock<TContext>`
+ * structurally.
+ */
+declare function createDurableTurnLock<TContext>(options: CreateDurableTurnLockOptions<TContext>): {
+    acquire(args: TurnLockSeamArgs<TContext>): Promise<TurnLockSeamResult>;
+    release(handle: unknown): Promise<void>;
+};
+/**
+ * Fan a turn event out to the per-thread channel. `executionId` groups events
+ * into a per-turn segment with a monotonic seq, so a reconnecting client
+ * replays only the active turn and resumes from a cursor. Callers MUST await
+ * (the DO assigns seq on arrival — emission order matters); failures are
+ * swallowed (fanout is best-effort and never breaks chat delivery).
+ */
+declare function broadcastTurnStreamEvent(namespace: TurnStreamNamespaceLike, input: {
+    workspaceId: string;
+    threadId: string;
+    executionId: string;
+    event: {
+        type: string;
+        data?: Record<string, unknown>;
+    };
+}): Promise<void>;
+/** Coarse per-workspace marker that a thread's turn started / ended — drives
+ *  a sidebar "agent responding" indicator subscribed once per workspace. */
+declare function broadcastWorkspaceActivity(namespace: TurnStreamNamespaceLike, workspaceId: string, threadId: string, phase: 'start' | 'end'): Promise<void>;
+/** Per-workspace marker that a new thread was created, so an already-open
+ *  history list prepends it without a reload. */
+declare function broadcastThreadCreated(namespace: TurnStreamNamespaceLike, workspaceId: string, thread: {
+    threadId: string;
+    title: string;
+}): Promise<void>;
+type TurnStreamUpgradeAuthorization = {
+    ok: true;
+} | {
+    ok: false;
+    response: Response;
+};
+interface CreateTurnStreamUpgradeHandlerOptions {
+    namespace: TurnStreamNamespaceLike;
+    /** The worker route serving the stream. Default `/api/session-stream`. */
+    path?: string;
+    /** Viewer access check (session cookie → workspace membership). */
+    authorize(request: Request, target: {
+        workspaceId: string;
+        threadId: string | null;
+    }): Promise<TurnStreamUpgradeAuthorization>;
+}
+/**
+ * The worker-entry WebSocket forwarder. Call BEFORE the app router (a router
+ * loader cannot return a 101); returns `null` for requests that are not a
+ * WebSocket upgrade on the configured path.
+ *
+ *   GET {path}?workspaceId=...            → workspace channel (sidebar)
+ *   GET {path}?workspaceId=...&threadId=… → thread channel (turn resume)
+ *
+ * After the 101, the client sends `{type:'sync', afterSeq}` and receives the
+ * replay-then-live stream (see {@link TurnStreamDO.webSocketMessage}).
+ */
+declare function createTurnStreamUpgradeHandler(options: CreateTurnStreamUpgradeHandlerOptions): (request: Request) => Promise<Response | null>;
+
+/**
+ * In-process turn-stream harness: a fake namespace that routes `idFromName`
+ * to REAL {@link TurnStreamDO} instances over an in-memory storage/socket
+ * state. The adapters and the DO run their production code paths — only the
+ * Cloudflare runtime (isolation, hibernation, real sockets) is simulated.
+ *
+ * For vitest composition tests and keyless local dev (the same role
+ * `createMemoryTurnEventStore` plays for the D1 store). Not for production:
+ * state is per-process and evaporates on restart.
+ */
+
+/** A test-side viewer socket: records frames sent by the DO and lets the
+ *  test drive the `sync` handshake. */
+interface MemoryTurnStreamSocket extends TurnStreamSocket {
+    readonly frames: string[];
+    readonly closed: boolean;
+}
+interface MemoryTurnStreamChannel {
+    /** Attach a viewer socket to this channel (bypasses the HTTP 101 — the
+     *  upgrade handshake is Cloudflare-runtime-only) and run its `sync`. */
+    connect(input: {
+        sessionId: string;
+        scope: 'thread' | 'workspace';
+        afterSeq?: number;
+    }): Promise<MemoryTurnStreamSocket>;
+    readonly instance: TurnStreamDO;
+}
+interface MemoryTurnStreamHarness {
+    namespace: TurnStreamNamespaceLike;
+    /** The channel (creating its DO instance if needed) for a channel key —
+     *  e.g. `threadChannelKey(ws, thread)` — to connect test viewers. */
+    channel(name: string): MemoryTurnStreamChannel;
+}
+/**
+ * Build the harness. `createInstance` lets a product test run its own
+ * `TurnStreamDO` subclass through the same wiring.
+ */
+declare function createMemoryTurnStreamHarness(createInstance?: (state: TurnStreamDOState) => TurnStreamDO, _options?: TurnStreamDOOptions): MemoryTurnStreamHarness;
+
+export { ACTIVITY_TTL_MS, type AcquireDurableTurnLockInput, type CreateDurableTurnLockOptions, type CreateTurnStreamUpgradeHandlerOptions, type DurableTurnLock, MAX_RECENT_CREATED, MAX_SEGMENT_EVENTS, type MemoryTurnStreamChannel, type MemoryTurnStreamHarness, type MemoryTurnStreamSocket, type ReconcileStaleDurableTurnLockOptions, type ReleaseInterruptedDurableTurnLockInput, type SegmentStore, TURN_LOCK_TTL_MS, TURN_STREAM_PATHS, TURN_STREAM_STORAGE_KEYS, type TurnLockAcquireInput, type TurnLockAcquireResult, type TurnLockInterruptedReleaseInput, type TurnLockReleaseInput, type TurnLockScope, type TurnLockSeamArgs, type TurnLockSeamResult, type TurnSegment, TurnStreamDO, type TurnStreamDOOptions, type TurnStreamDOState, type TurnStreamEvent, type TurnStreamNamespaceLike, type TurnStreamSocket, type TurnStreamStorage, type TurnStreamStubLike, type TurnStreamUpgradeAuthorization, acquireDurableTurnLock, activeTurnLock, appendSegmentEvent, broadcastThreadCreated, broadcastTurnStreamEvent, broadcastWorkspaceActivity, createDurableObjectTurnEventStore, createDurableTurnLock, createMemoryTurnStreamHarness, createSegmentStore, createTurnLock, createTurnStreamUpgradeHandler, interruptedReleaseApplies, isTerminalRunEvent, pruneStaleThreads, reconcileStaleDurableTurnLock, releaseDurableTurnLock, releaseInterruptedDurableTurnLock, replayActiveSegment, scopeIndexChannelKey, threadChannelKey, turnEventStorageKey, turnLockChannelKey, turnLockMatchesRelease, turnStorageChannelKey, workspaceChannelKey };