@tangle-network/agent-app 0.51.16 → 0.52.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,193 +1,56 @@
1
1
  /**
2
- * `/turn-stream` core — the pure, substrate-free half of the shared durable
3
- * turn replay/broadcast/lock channel (issue #221).
4
- *
5
- * Extracted from the reference consumer's hand-rolled Durable Object
6
- * (gtm-agent `SessionStreamDO` + `session-broadcast.ts`): the per-turn
7
- * segment store that backs reconnect replay over a live socket, the
8
- * single-flight chat-turn lock record and its release fences, and the wire
9
- * contract (channel keys, endpoint paths, request/response bodies) shared by
10
- * the DO transport shell (`./do`) and the worker-side adapters
11
- * (`./adapters`). Everything here is plain data + functions — no
12
- * `cloudflare:workers`, no storage, no sockets — so the semantics are
13
- * unit-testable in Node and the DO stays a thin shell.
14
- *
15
- * ── The two-lane rule (measured, not assumed) ────────────────────────────
16
- *
17
- * A 4-arm A/B on production (sandbox.tangle.tools, SDK 0.12.0, one box, one
18
- * gateway client per arm) established which sandbox lane a browser can see:
19
- *
20
- * | turn driver | raw turn events | seen at gateway |
21
- * | ------------------------------------ | --------------- | --------------- |
22
- * | `box.streamPrompt()` (run/stream) | 71 / 527 / 408 | 0 / 0 / 0 |
23
- * | `box.session(id).sendMessage()` | 297 | 297 |
24
- * | `box.driveTurn()` (Sandbox 0.37+) | — | SDK contract |
25
- *
26
- * `POST /agents/run/stream` publishes nothing to the sidecar session event
27
- * bus, so a `SessionGatewayClient` attached to that session receives zero
28
- * turn events — three different session-id strategies all got 0, the id was
29
- * not the variable. `POST /agents/sessions/{id}/messages` publishes to the
30
- * bus and the gateway delivered every frame, byte-matching the sidecar tail.
31
- * Sandbox 0.37 admits `driveTurn` through the session message lane, so the
32
- * gateway can observe it. That is an SDK contract, not a new production count.
33
- *
34
- * Consequences for this module, and they cut both ways:
35
- *
36
- * 1. INTERACTIVE sandbox turns should be driven on the message lane and
37
- * tailed by the browser through `box.mintScopedToken({ scope: 'session' })`
38
- * + `SessionGatewayClient`. Re-broadcasting those same events through the
39
- * per-turn SEGMENT buffer below duplicates the SDK and adds a worker hop.
40
- * That half is `@deprecated` (see the tags on {@link createSegmentStore},
41
- * {@link appendSegmentEvent}, {@link replayActiveSegment} and
42
- * `broadcastTurnStreamEvent` in `./adapters`).
43
- * 2. Detached turns driven through `dispatchPrompt({ detach: true })` or
44
- * `streamPrompt` remain on the run/stream lane and need a buffer when a
45
- * browser must tail them. Sandbox 0.37 `driveTurn` is different: it uses
46
- * the session message lane and the gateway can observe it. The buffer
47
- * remains the path for stream/dispatch runs and has no SDK replacement.
48
- * 3. The LOCK and the per-workspace SIGNALS have no gateway equivalent at
49
- * all (the gateway is per-session and read-only). They stay canonical.
50
- *
51
- * Server-side resume of a run/stream turn is also already solved by the SDK
52
- * and needs nothing here: `box.streamPrompt('', { executionId, lastEventId })`
53
- * replays strictly after the cursor without re-dispatching — measured across
54
- * a SIGKILL mid-run and a fresh process resuming from the cursor alone:
55
- * 0 lost, 0 duplicated, 0 out-of-order, ids 1..517 contiguous.
2
+ * Channel tokens, lock records, workspace signals, and durable event keys.
3
+ * Interactive turn replay belongs to the sandbox session gateway.
4
+ * An optional turn-event backend stores durable rows and a running-turn index.
5
+ * This core uses WebCrypto and plain data without a Cloudflare runtime import.
56
6
  */
57
- /** One event on a turn-stream channel. `seq` is monotonic within a turn
58
- * segment and assigned by {@link appendSegmentEvent} on arrival at the DO. */
7
+ /** One event on a turn-stream channel. Workspace-signal events
8
+ * (`thread.created`, `thread.activity`, product events) carry no `seq` —
9
+ * ordering is delivery order on the DO's single-threaded event loop. */
59
10
  export interface TurnStreamEvent {
60
11
  type: string;
61
12
  data?: unknown;
62
13
  timestamp: number;
63
- seq?: number;
14
+ seq?: never;
64
15
  }
65
- /** Terminal run markers: they close a turn segment and auto-release the
66
- * channel's chat-turn lock for the segment's execution.
67
- *
68
- * KEPT (not deprecated with the segment buffer): the lock auto-release
69
- * reads it. A product that stops broadcasting turn events to the thread
70
- * channel loses only that auto-release — the cooperative release on settle
71
- * (`createDurableTurnLock().release`) and `reconcileStaleDurableTurnLock`
72
- * both still fire, which is what actually frees a wedged lane. */
73
- export declare function isTerminalRunEvent(type: string): boolean;
16
+ /** Default capability lifetime. Tokens are minted per worker request and
17
+ * verified immediately; a WS token gates only the upgrade handshake — an
18
+ * accepted socket lives until it closes. */
19
+ export declare const TURN_STREAM_TOKEN_TTL_MS = 60000;
20
+ /** Request header the adapters attach (and the DO accepts). The worker also
21
+ * attaches it when forwarding an authorized browser WebSocket handshake. */
22
+ export declare const TURN_STREAM_TOKEN_HEADER = "x-turn-stream-token";
23
+ /** `v1.<base64url-channel>.<exp-ms-36>.<base64url-mac>` — the expiry is inside the signed payload so
24
+ * it cannot be extended by editing the token. */
25
+ export declare function mintTurnStreamToken(channelName: string, secret: string, now?: () => number, ttlMs?: number): Promise<string>;
26
+ /** Verify a token for `channelName`: constant-time MAC compare with the
27
+ * exact channel name embedded in the signed payload, plus freshness. A
28
+ * token minted for any other channel — or a tampered expiry — is false. */
29
+ export declare function verifyTurnStreamToken(channelName: string, token: string, secret: string, now?: () => number): Promise<boolean>;
74
30
  /** Define the scope level for acquiring a turn lock within thread or workspace contexts */
75
31
  export type TurnLockScope = 'thread' | 'workspace';
76
- /** Generate a unique string key combining workspace and thread identifiers.
77
- *
78
- * KEPT: thread-scope LOCKS are keyed on it (see {@link turnLockChannelKey}).
79
- * Only its second use — addressing a live-viewer socket for interactive
80
- * sandbox-turn rebroadcast — is superseded by the session gateway. */
32
+ /** Channel for a thread-scoped lock. */
81
33
  export declare function threadChannelKey(workspaceId: string, threadId: string): string;
82
- /** Generate a unique channel key based on the given workspace identifier.
83
- *
84
- * KEPT and canonical: the per-workspace signal channel (`thread.created`,
85
- * `thread.activity`) plus workspace-scope locks. The session gateway is
86
- * per-SESSION and read-only, so it cannot carry either. */
34
+ /** Channel for workspace signals and the workspace-scoped lock. */
87
35
  export declare function workspaceChannelKey(workspaceId: string): string;
88
36
  /** The channel a lock lives on: workspace-scope locks serialize every thread
89
37
  * in the workspace (one shared sandbox), thread-scope locks serialize one
90
38
  * thread (router lane). Same keying as the reference consumer, so a product
91
39
  * swapping its fork for this package contends on identical instances. */
92
40
  export declare function turnLockChannelKey(workspaceId: string, threadId: string, scope: TurnLockScope): string;
93
- /** Generate a storage channel key string for a given turn identifier.
94
- *
95
- * KEPT and canonical: durable turn-event rows for stream/dispatch detached
96
- * runs live on this instance. Those run/stream paths do not reach the
97
- * session gateway, so this is how a browser tails one. */
41
+ /** Channel for the optional Durable Object turn-event backend. */
98
42
  export declare function turnStorageChannelKey(turnId: string): string;
99
- /** Generate a unique channel key string based on the provided scope identifier.
100
- *
101
- * KEPT and canonical: backs `TurnEventStore.listRunning`, which is how a
102
- * reloaded client rediscovers an in-flight DETACHED turn. */
43
+ /** Running-turn index for the optional Durable Object turn-event backend. */
103
44
  export declare function scopeIndexChannelKey(scopeId: string): string;
104
- /** DEPRECATED (interactive turn-rebroadcast buffer) — represent a segment of a turn containing events, sequence limit, and terminal status.
105
- *
106
- * @deprecated Part of the interactive turn-rebroadcast buffer — see the
107
- * two-lane rule in this file's header. Removal is a major-version change. */
108
- export interface TurnSegment {
109
- events: TurnStreamEvent[];
110
- maxSeq: number;
111
- terminal: boolean;
112
- }
113
- /** DEPRECATED (interactive turn-rebroadcast buffer) — define a store managing segments and tracking the active execution identifier.
114
- *
115
- * @deprecated Part of the interactive turn-rebroadcast buffer — see the
116
- * two-lane rule in this file's header. Removal is a major-version change. */
117
- export interface SegmentStore {
118
- segments: Map<string, TurnSegment>;
119
- activeExecutionId: string | null;
120
- }
121
- /** DEPRECATED (interactive turn-rebroadcast buffer) — per-turn replay window. Generous enough for normal turns; a turn that
122
- * exceeds it loses its earliest deltas from replay (a late resumer
123
- * self-heals via the final `result` event + loader revalidation).
124
- *
125
- * @deprecated Sizes the interactive turn-rebroadcast buffer only. The
126
- * stream/dispatch detached lanes' durable rows (`turnEvent:` storage) are
127
- * uncapped and are not affected. */
128
- export declare const MAX_SEGMENT_EVENTS = 2000;
129
- /** Recent `thread.created` markers kept for late-connecting sidebars.
130
- *
131
- * KEPT: a workspace-level signal, not a turn rebroadcast. */
45
+ /** Recent thread-created markers kept for late-connecting sidebars. */
132
46
  export declare const MAX_RECENT_CREATED = 50;
133
47
  /** A responding marker older than this is treated as stale, so a dropped
134
48
  * `end` broadcast can't leave a permanently-stuck "responding" dot. */
135
49
  export declare const ACTIVITY_TTL_MS: number;
136
- /** DEPRECATED (interactive sandbox-turn rebroadcast; the SDK's session gateway replaces it) — create a SegmentStore with initialized segments and no active execution ID.
137
- *
138
- * @deprecated Backs the interactive sandbox-turn rebroadcast, which the
139
- * sandbox SDK already does better (measured: run/stream → 0 frames at the
140
- * gateway, message lane → 297/297; see the two-lane rule in this file's
141
- * header). Sandbox turns: drive on `box.session(id).sendMessage()` and let
142
- * the browser attach with `box.mintScopedToken({ scope: 'session' })` +
143
- * `SessionGatewayClient`. Sandbox-FREE turns: `/stream`'s
144
- * `replayTurnEvents` (`GET /chat/stream/:turnId`) already follows a running
145
- * turn from a cursor. Stream/dispatch detached turns keep the durable
146
- * turn-event rows —
147
- * they are a different, non-deprecated lane. Removal is a major-version
148
- * change; nothing is deleted here. */
149
- export declare function createSegmentStore(): SegmentStore;
150
- /**
151
- * DEPRECATED (interactive turn-rebroadcast buffer) — append a per-turn event to
152
- * its execution's segment, assigning a monotonic
153
- * `seq`. A `session.run.started` (or the first-seen event for an execution)
154
- * opens a fresh segment, makes it active, and drops prior turns' buffers so a
155
- * resumer only ever replays the current turn. A terminal run event marks the
156
- * segment terminal. Returns the seq-stamped event to broadcast.
157
- *
158
- * @deprecated The interactive rebroadcast half — {@link createSegmentStore}
159
- * names the replacement per lane; this file's header holds the measurement.
160
- */
161
- export declare function appendSegmentEvent(store: SegmentStore, executionId: string, incoming: TurnStreamEvent, maxEvents?: number): TurnStreamEvent;
162
- /**
163
- * DEPRECATED (interactive turn-rebroadcast buffer; the SDK replays losslessly on
164
- * both lanes) — events of the active, non-terminal turn with `seq > afterSeq`,
165
- * i.e. what a
166
- * (re)connecting client replays before going live. A terminal (finished) turn
167
- * replays nothing: the client falls back to the loader's persisted row.
168
- *
169
- * @deprecated The interactive rebroadcast half — {@link createSegmentStore}
170
- * names the replacement per lane. The SDK's own reconnect replay is
171
- * `SessionGatewayClient` + `lastEventId` (browser) or
172
- * `box.streamPrompt('', { executionId, lastEventId })` (worker); both were
173
- * measured lossless.
174
- */
175
- export declare function replayActiveSegment(store: SegmentStore, afterSeq: number): TurnStreamEvent[];
176
- /**
177
- * Remove responding entries (threadId → startedAt) older than `ttlMs`, so a
178
- * dropped `end` broadcast can't leave a permanently-stuck dot. Mutates
179
- * `active` and returns the removed thread ids.
180
- */
50
+ /** Remove responding markers older than ttlMs; return their thread IDs. */
181
51
  export declare function pruneStaleThreads(active: Map<string, number>, now: number, ttlMs: number): string[];
182
- /** Default lifetime of an unreleased lock. Long enough that a legitimately
183
- * slow sandbox turn never loses its guard mid-run; the way OUT of a wedge is
184
- * never the TTL but `reconcileStaleTurnLock` (in `/chat-routes`), which
185
- * probes the execution's actual state.
186
- *
187
- * Everything from here down is the LOCK, and it is fully KEPT. The sandbox
188
- * SDK ships no single-flight primitive — the session gateway is a read-only
189
- * fanout — so moving a product to the message lane changes nothing about
190
- * who is allowed to start a turn. */
52
+ /** Fallback lifetime for an unreleased lock. Use stale-lock reconciliation to
53
+ * recover earlier when execution state proves that its holder stopped. */
191
54
  export declare const TURN_LOCK_TTL_MS: number;
192
55
  /** The stored single-flight lock. Field-compatible with the reference
193
56
  * consumer's `ChatTurnLock` so adoption is a swap, not a migration. */
@@ -247,11 +110,7 @@ export interface TurnLockInterruptedReleaseInput {
247
110
  export declare function activeTurnLock(stored: DurableTurnLock | undefined, now: number): DurableTurnLock | null;
248
111
  /** Create a durable turn lock object with timing and scope based on input parameters */
249
112
  export declare function createTurnLock(input: TurnLockAcquireInput, now: number, ttlMs?: number): DurableTurnLock;
250
- /** A cooperative release must present the lock's own identity — both the
251
- * execution and the lockId minted at acquire — so a retry of a PREVIOUS turn
252
- * can never release the current one. `lockId` is optional only for the DO's
253
- * internal terminal-event auto-release, which knows the execution but not
254
- * the caller-held lockId. */
113
+ /** A cooperative release matches the execution and, when supplied, lock ID. */
255
114
  export declare function turnLockMatchesRelease(active: DurableTurnLock, input: {
256
115
  executionId: string;
257
116
  lockId?: string;
@@ -1,47 +1,12 @@
1
1
  /**
2
- * `TurnStreamDO` — the shared Durable Object transport shell over the pure
3
- * core (`./core`). One class serves every channel family; the instance NAME
4
- * decides which endpoints a given instance ever sees:
2
+ * Durable Object transport for thread/workspace locks, workspace signals,
3
+ * detached turn-event rows, and running-turn discovery.
4
+ * Cloudflare's named object identity binds every request's capability token.
5
+ * Worker and DO code share TURN_STREAM_AUTH_SECRET; absent configuration fails closed.
5
6
  *
6
- * - **thread channel** (`${workspaceId}:${threadId}`) — the thread-scope lock
7
- * (KEPT), plus the live turn rebroadcast: WebSocket fanout and per-turn
8
- * segments with `sync`/`afterSeq` reconnect replay. That rebroadcast is
9
- * `@deprecated` for sandbox-backed interactive turns — the sandbox session
10
- * gateway already does it, browser-direct, when the turn is driven on the
11
- * message lane (`./core`'s header has the production measurement).
12
- * - **workspace channel** (`${workspaceId}`) — coarse sidebar signals
13
- * (`thread.activity` responding set, durable across eviction;
14
- * `thread.created` recent list) and the workspace-scope lock. KEPT: the
15
- * gateway is per-session and read-only, so it carries neither.
16
- * - **turn storage** (`turn:${turnId}`) — the durable `TurnEventStore` rows +
17
- * status for one buffered turn (replay survives DO eviction — this is what
18
- * graduates the vertical's `turnStore` from no-op). KEPT and load-bearing:
19
- * a stream/dispatch DETACHED run does not reach the gateway on the
20
- * measured path, so this is how a browser tails that autonomous work.
21
- * - **scope index** (`scope:${scopeId}`) — the running-turn index backing
22
- * `TurnEventStore.listRunning` reconnect discovery. KEPT.
23
- *
24
- * The class is a PLAIN class over a structural {@link TurnStreamDOState} —
25
- * no `cloudflare:workers` import, so this package stays substrate-free and
26
- * the DO is unit-testable in Node. Cloudflare's `DurableObjectState`
27
- * satisfies the interface; a product binds it in wrangler by re-exporting:
28
- *
29
- * // worker entry
30
- * export { TurnStreamDO } from '@tangle-network/agent-app/turn-stream'
31
- *
32
- * Fan-out enumerates `state.getWebSockets()` (never an in-memory socket map)
33
- * and reads per-socket metadata from the serialized attachment, so it is
34
- * correct across WebSocket hibernation.
35
- *
36
- * Product extension (how the reference consumer keeps its Vault machinery
37
- * while deleting its fork): subclass and override
38
- * {@link TurnStreamDO.handleProductRequest} (extra POST endpoints),
39
- * {@link TurnStreamDO.shouldDeferLockRelease} /
40
- * {@link TurnStreamDO.completeDeferredLockRelease} (park a lock release
41
- * behind a product-owned post-turn task), and
42
- * {@link TurnStreamDO.productSyncEvents} (extra state replayed to a
43
- * late-connecting socket). Product storage keys must avoid
44
- * {@link TURN_STREAM_STORAGE_KEYS}.
7
+ * Sockets use hibernation attachments; products may add authenticated endpoints,
8
+ * defer lock release during persistence, and contribute workspace sync events.
9
+ * Product storage keys must avoid TURN_STREAM_STORAGE_KEYS.
45
10
  */
46
11
  import { type DurableTurnLock, type TurnStreamEvent } from './core';
47
12
  /** The socket surface the DO touches. Cloudflare's hibernatable `WebSocket`
@@ -69,34 +34,62 @@ export interface TurnStreamDOState {
69
34
  storage: TurnStreamStorage;
70
35
  acceptWebSocket(ws: TurnStreamSocket): void;
71
36
  getWebSockets(): TurnStreamSocket[];
37
+ /** The instance's named identity — Cloudflare's `DurableObjectState.id`
38
+ * satisfies this structurally (`state.id.name` for `idFromName` bindings).
39
+ * Capability tokens are bound to this name, so it must be present for the
40
+ * DO to serve any request. */
41
+ id?: {
42
+ name?: string | null;
43
+ };
72
44
  }
73
45
  /** Define options to override default TTL and event limits for TURN stream DO operations */
74
46
  export interface TurnStreamDOOptions {
75
47
  /** Override {@link TURN_LOCK_TTL_MS}. */
76
48
  lockTtlMs?: number;
77
- /** Override {@link MAX_SEGMENT_EVENTS}. */
78
- maxSegmentEvents?: number;
79
49
  /** Override {@link ACTIVITY_TTL_MS}. */
80
50
  activityTtlMs?: number;
81
51
  /** How long an unrenewed running turn remains discoverable. */
82
52
  runningTurnLeaseMs?: number;
53
+ /**
54
+ * HMAC secret for the channel-bound capability tokens every request must
55
+ * carry (issue #746). When omitted, the DO reads `TURN_STREAM_AUTH_SECRET`
56
+ * from its `env`. Fail-closed: absent or shorter than 32 chars, every
57
+ * request answers 500 with the fix in the message — there is deliberately
58
+ * no unauthenticated mode.
59
+ */
60
+ authSecret?: string;
83
61
  }
84
- /** Manage per-turn segments and track active threads with durable event storage */
62
+ /** Durable turn-event storage, workspace signals, and the single-flight turn
63
+ * lock, on one channel-bound Durable Object. Every request — including
64
+ * subclass product routes — passes the capability-token gate in
65
+ * {@link TurnStreamDO.fetch} (issue #746). */
85
66
  export declare class TurnStreamDO {
86
67
  protected readonly state: TurnStreamDOState;
87
68
  protected readonly env: unknown;
88
69
  protected readonly options: TurnStreamDOOptions;
89
- private segments;
90
70
  private recentCreated;
91
71
  private activeThreads;
92
72
  constructor(state: TurnStreamDOState, env?: unknown, options?: TurnStreamDOOptions);
73
+ /** The token-verification secret: explicit option first, then the
74
+ * `TURN_STREAM_AUTH_SECRET` env binding. Protected so a product subclass
75
+ * with its own secret store overrides ONE method instead of copying the
76
+ * resolution. */
77
+ protected resolveAuthSecret(): string | undefined;
78
+ /**
79
+ * The single authentication gate for EVERYTHING this DO serves — base
80
+ * endpoints, the WebSocket upgrade, and subclass product routes (they are
81
+ * dispatched from {@link fetch} after this check). A request must present a
82
+ * capability token minted for THIS instance's channel name: cross-channel
83
+ * replay is impossible, an unauthenticated forward gets 401, and a missing
84
+ * secret fails closed with a 500 that names the fix (issue #746).
85
+ */
86
+ private authorizeRequest;
93
87
  fetch(request: Request): Promise<Response>;
94
88
  /** Called for any request no base endpoint claimed (before the 404), so a
95
89
  * subclass adds product endpoints without touching base routing. Return
96
90
  * `null` to decline. */
97
91
  protected handleProductRequest(_request: Request, _url: URL): Promise<Response | null>;
98
- /** Consulted before any lock release (cooperative, interrupted, or the
99
- * terminal-event auto-release). Return `true` while a product-owned
92
+ /** Consulted before any lock release (cooperative or interrupted). Return `true` while a product-owned
100
93
  * post-turn task for `executionId` must keep the scope serialized (e.g.
101
94
  * file persistence still reading the box) — the release is then parked as
102
95
  * `releasePending` on the lock and completed via
@@ -1,63 +1,13 @@
1
1
  /**
2
- * `/turn-stream` — shared durable turn replay/broadcast/lock on a Cloudflare
3
- * Durable Object (issue #221): the graduation of `createChatTurnRoutes`'
4
- * `turnStore` seam from "bring your own DO" to a real implementation, plus
5
- * the dual-scope single-flight turn lock and the live-viewer WebSocket
6
- * channel every fleet app was hand-rolling.
7
- *
8
- * Subpath-only and server-only (like `/chat-routes`): never re-exported from
9
- * the root barrel, never reachable from a client bundle. Cloudflare is
10
- * STRUCTURAL throughout — no `cloudflare:workers` import; a product binds
11
- * the DO by re-exporting {@link TurnStreamDO} from its worker entry and
12
- * declaring it in wrangler.
13
- *
14
- * Layout:
15
- * ./core — pure segment/lock/wire logic (unit-testable)
16
- * ./do — the DO transport shell + product extension seams
17
- * ./adapters — turnStore + turnLock seam implementations, broadcast
18
- * helpers, WS upgrade forwarder
19
- * ./memory — in-process harness for tests and keyless local dev
20
- *
21
- * What stays product-side, on purpose: WHICH scope a turn locks on, the
22
- * sandbox/session probes for stale-lock recovery, viewer authorization, and
23
- * any post-turn machinery that defers a lock release (the DO's protected
24
- * seams exist for exactly that).
25
- *
26
- * ── What is still the right answer here, and what is not ─────────────────
27
- *
28
- * A production A/B (4 arms, sandbox.tangle.tools, SDK 0.12.0) showed that a
29
- * browser attached to the sandbox session gateway sees a turn only when the
30
- * turn is driven on the session-MESSAGE lane
31
- * (`box.session(id).sendMessage()` → 297 of 297 frames delivered), never on
32
- * the run/stream lane (`box.streamPrompt()` → 0 of 71, 0 of 527, 0 of 408
33
- * across three session-id strategies). `./core`'s header carries the full
34
- * table.
35
- *
36
- * KEPT — no SDK primitive replaces these:
37
- * • the dual-scope single-flight TURN LOCK (`createDurableTurnLock`,
38
- * `reconcileStaleDurableTurnLock`) — the gateway is a read-only fanout
39
- * and ships no admission control;
40
- * • the per-workspace SIGNALS (`thread.created`, `thread.activity`, plus
41
- * `productSyncEvents`) — the gateway is per-session;
42
- * • the durable TURN-EVENT rows + running-turn index
43
- * (`createDurableObjectTurnEventStore`) that `runDetachedTurn` streams
44
- * into — stream/dispatch detached runs (`dispatchPrompt({ detach: true })`,
45
- * `streamPrompt`) do not reach the gateway on the measured path. Sandbox
46
- * 0.37 `driveTurn` uses the session message lane and is gateway-visible
47
- * by SDK contract. Autonomous stream/dispatch work a browser must tail
48
- * still needs the durable rows.
49
- *
50
- * DEPRECATED — duplicates the SDK:
51
- * • the interactive per-turn REBROADCAST/replay on the thread channel
52
- * (`broadcastTurnStreamEvent` + the segment functions in `./core`).
53
- * Sandbox products: drive on the message lane and attach the tab with
54
- * `box.mintScopedToken({ scope: 'session' })` + `SessionGatewayClient`;
55
- * resume a worker-side read with
56
- * `box.streamPrompt('', { executionId, lastEventId })`, which replays
57
- * strictly after the cursor without re-dispatching.
58
- *
59
- * Nothing is removed: these are published exports and unknown consumers may
60
- * hold them. Removal is a major-version change.
2
+ * Server-only durable turn storage, workspace signals, and single-flight locks.
3
+ * Products bind TurnStreamDO and share TURN_STREAM_AUTH_SECRET with worker adapters.
4
+ * The worker authorizes workspace viewers before forwarding their WebSocket upgrade.
5
+ * Every DO request independently verifies a short-lived token for its own named channel.
6
+ *
7
+ * Interactive turn replay belongs to the sandbox session gateway.
8
+ * The optional turn-event backend is independent of lock and signal coordination.
9
+ * Products own sandbox probes, membership checks, and deferred persistence tasks.
10
+ * See docs/turn-stream-migration.md for the 0.52.0 consumer migration.
61
11
  */
62
12
  export * from './core';
63
13
  export * from './do';