@tangle-network/agent-app 0.43.68 → 0.43.70

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

@@ -14,6 +14,46 @@ import { d as TurnEventStore } from '../turn-buffer-DGnAPKwa.js';
  * (`./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.
+ *
+ * ── The two-lane rule (measured, not assumed) ────────────────────────────
+ *
+ * A 4-arm A/B on production (sandbox.tangle.tools, SDK 0.12.0, one box, one
+ * gateway client per arm) established which sandbox lane a browser can see:
+ *
+ *   | turn driver                          | raw turn events | seen at gateway |
+ *   | ------------------------------------ | --------------- | --------------- |
+ *   | `box.streamPrompt()` (run/stream)    | 71 / 527 / 408  | 0 / 0 / 0       |
+ *   | `box.session(id).sendMessage()`      | 297             | 297             |
+ *
+ * `POST /agents/run/stream` publishes nothing to the sidecar session event
+ * bus, so a `SessionGatewayClient` attached to that session receives zero
+ * turn events — three different session-id strategies all got 0, the id was
+ * not the variable. `POST /agents/sessions/{id}/messages` publishes to the
+ * bus and the gateway delivered every frame, byte-matching the sidecar tail.
+ *
+ * Consequences for this module, and they cut both ways:
+ *
+ * 1. INTERACTIVE sandbox turns should be driven on the message lane and
+ *    tailed by the browser through `box.mintScopedToken({ scope: 'session' })`
+ *    + `SessionGatewayClient`. Re-broadcasting those same events through the
+ *    per-turn SEGMENT buffer below duplicates the SDK and adds a worker hop.
+ *    That half is `@deprecated` (see the tags on {@link createSegmentStore},
+ *    {@link appendSegmentEvent}, {@link replayActiveSegment} and
+ *    `broadcastTurnStreamEvent` in `./adapters`).
+ * 2. DETACHED/autonomous turns are INVISIBLE to the gateway:
+ *    `dispatchPrompt({ detach: true })` and `driveTurn` both go through
+ *    `streamPrompt` internally, i.e. the run/stream lane, which does not fan
+ *    out. A browser that must tail an unattended run still needs a buffer —
+ *    `runDetachedTurn` (`/chat-routes`) over the durable turn-event rows
+ *    below. That half is NOT deprecated and has no SDK replacement today.
+ * 3. The LOCK and the per-workspace SIGNALS have no gateway equivalent at
+ *    all (the gateway is per-session and read-only). They stay canonical.
+ *
+ * Server-side resume of a run/stream turn is also already solved by the SDK
+ * and needs nothing here: `box.streamPrompt('', { executionId, lastEventId })`
+ * replays strictly after the cursor without re-dispatching — measured across
+ * a SIGKILL mid-run and a fresh process resuming from the cursor alone:
+ * 0 lost, 0 duplicated, 0 out-of-order, ids 1..517 contiguous.
  */
 /** One event on a turn-stream channel. `seq` is monotonic within a turn
  *  segment and assigned by {@link appendSegmentEvent} on arrival at the DO. */
@@ -24,57 +64,113 @@ interface TurnStreamEvent {
     seq?: number;
 }
 /** Terminal run markers: they close a turn segment and auto-release the
- *  channel's chat-turn lock for the segment's execution. */
+ *  channel's chat-turn lock for the segment's execution.
+ *
+ *  KEPT (not deprecated with the segment buffer): the lock auto-release
+ *  reads it. A product that stops broadcasting turn events to the thread
+ *  channel loses only that auto-release — the cooperative release on settle
+ *  (`createDurableTurnLock().release`) and `reconcileStaleDurableTurnLock`
+ *  both still fire, which is what actually frees a wedged lane. */
 declare function isTerminalRunEvent(type: string): boolean;
 /** Define the scope level for acquiring a turn lock within thread or workspace contexts */
 type TurnLockScope = 'thread' | 'workspace';
-/** Generate a unique string key combining workspace and thread identifiers */
+/** Generate a unique string key combining workspace and thread identifiers.
+ *
+ *  KEPT: thread-scope LOCKS are keyed on it (see {@link turnLockChannelKey}).
+ *  Only its second use — addressing a live-viewer socket for interactive
+ *  sandbox-turn rebroadcast — is superseded by the session gateway. */
 declare function threadChannelKey(workspaceId: string, threadId: string): string;
-/** Generate a unique channel key based on the given workspace identifier */
+/** Generate a unique channel key based on the given workspace identifier.
+ *
+ *  KEPT and canonical: the per-workspace signal channel (`thread.created`,
+ *  `thread.activity`) plus workspace-scope locks. The session gateway is
+ *  per-SESSION and read-only, so it cannot carry either. */
 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;
-/** Generate a storage channel key string for a given turn identifier */
+/** Generate a storage channel key string for a given turn identifier.
+ *
+ *  KEPT and canonical: the DETACHED lane's durable turn-event rows live on
+ *  this instance. A detached run never reaches the session gateway, so this
+ *  is the only way a browser tails one. */
 declare function turnStorageChannelKey(turnId: string): string;
-/** Generate a unique channel key string based on the provided scope identifier */
+/** Generate a unique channel key string based on the provided scope identifier.
+ *
+ *  KEPT and canonical: backs `TurnEventStore.listRunning`, which is how a
+ *  reloaded client rediscovers an in-flight DETACHED turn. */
 declare function scopeIndexChannelKey(scopeId: string): string;
-/** Represent a segment of a turn containing events, sequence limit, and terminal status */
+/** DEPRECATED (interactive turn-rebroadcast buffer) — represent a segment of a turn containing events, sequence limit, and terminal status.
+ *
+ *  @deprecated Part of the interactive turn-rebroadcast buffer — see the
+ *  two-lane rule in this file's header. Removal is a major-version change. */
 interface TurnSegment {
     events: TurnStreamEvent[];
     maxSeq: number;
     terminal: boolean;
 }
-/** Define a store managing segments and tracking the active execution identifier */
+/** DEPRECATED (interactive turn-rebroadcast buffer) — define a store managing segments and tracking the active execution identifier.
+ *
+ *  @deprecated Part of the interactive turn-rebroadcast buffer — see the
+ *  two-lane rule in this file's header. Removal is a major-version change. */
 interface SegmentStore {
     segments: Map<string, TurnSegment>;
     activeExecutionId: string | null;
 }
-/** Per-turn replay window. Generous enough for normal turns; a turn that
+/** DEPRECATED (interactive turn-rebroadcast buffer) — 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). */
+ *  self-heals via the final `result` event + loader revalidation).
+ *
+ *  @deprecated Sizes the interactive turn-rebroadcast buffer only. The
+ *  DETACHED lane's durable rows (`turnEvent:` storage) are uncapped and are
+ *  not affected. */
 declare const MAX_SEGMENT_EVENTS = 2000;
-/** Recent `thread.created` markers kept for late-connecting sidebars. */
+/** Recent `thread.created` markers kept for late-connecting sidebars.
+ *
+ *  KEPT: a workspace-level signal, not a turn rebroadcast. */
 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;
-/** Create a SegmentStore with initialized segments and no active execution ID */
+/** DEPRECATED (interactive sandbox-turn rebroadcast; the SDK's session gateway replaces it) — create a SegmentStore with initialized segments and no active execution ID.
+ *
+ *  @deprecated Backs the interactive sandbox-turn rebroadcast, which the
+ *  sandbox SDK already does better (measured: run/stream → 0 frames at the
+ *  gateway, message lane → 297/297; see the two-lane rule in this file's
+ *  header). Sandbox turns: drive on `box.session(id).sendMessage()` and let
+ *  the browser attach with `box.mintScopedToken({ scope: 'session' })` +
+ *  `SessionGatewayClient`. Sandbox-FREE turns: `/stream`'s
+ *  `replayTurnEvents` (`GET /chat/stream/:turnId`) already follows a running
+ *  turn from a cursor. Detached turns keep the durable turn-event rows —
+ *  they are a different, non-deprecated lane. Removal is a major-version
+ *  change; nothing is deleted here. */
 declare function createSegmentStore(): SegmentStore;
 /**
- * Append a per-turn event to its execution's segment, assigning a monotonic
+ * DEPRECATED (interactive turn-rebroadcast buffer) — 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.
+ *
+ * @deprecated The interactive rebroadcast half — {@link createSegmentStore}
+ * names the replacement per lane; this file's header holds the measurement.
  */
 declare function appendSegmentEvent(store: SegmentStore, executionId: string, incoming: TurnStreamEvent, maxEvents?: number): TurnStreamEvent;
 /**
- * Events of the active, non-terminal turn with `seq > afterSeq` — what a
+ * DEPRECATED (interactive turn-rebroadcast buffer; the SDK replays losslessly on
+ * both lanes) — events of the active, non-terminal turn with `seq > afterSeq`,
+ * i.e. 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.
+ *
+ * @deprecated The interactive rebroadcast half — {@link createSegmentStore}
+ * names the replacement per lane. The SDK's own reconnect replay is
+ * `SessionGatewayClient` + `lastEventId` (browser) or
+ * `box.streamPrompt('', { executionId, lastEventId })` (worker); both were
+ * measured lossless.
  */
 declare function replayActiveSegment(store: SegmentStore, afterSeq: number): TurnStreamEvent[];
 /**
@@ -86,7 +182,12 @@ declare function pruneStaleThreads(active: Map<string, number>, now: number, ttl
 /** 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. */
+ *  probes the execution's actual state.
+ *
+ *  Everything from here down is the LOCK, and it is fully KEPT. The sandbox
+ *  SDK ships no single-flight primitive — the session gateway is a read-only
+ *  fanout — so moving a product to the message lane changes nothing about
+ *  who is allowed to start a turn. */
 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. */
@@ -199,17 +300,23 @@ declare function turnEventStorageKey(seq: number): string;
  * 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.
+ * - **thread channel** (`${workspaceId}:${threadId}`) — the thread-scope lock
+ *   (KEPT), plus the live turn rebroadcast: WebSocket fanout and per-turn
+ *   segments with `sync`/`afterSeq` reconnect replay. That rebroadcast is
+ *   `@deprecated` for sandbox-backed interactive turns — the sandbox session
+ *   gateway already does it, browser-direct, when the turn is driven on the
+ *   message lane (`./core`'s header has the production measurement).
  * - **workspace channel** (`${workspaceId}`) — coarse sidebar signals
  *   (`thread.activity` responding set, durable across eviction;
- *   `thread.created` recent list) and the workspace-scope lock.
+ *   `thread.created` recent list) and the workspace-scope lock. KEPT: the
+ *   gateway is per-session and read-only, so it carries neither.
  * - **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).
+ *   graduates the vertical's `turnStore` from no-op). KEPT and load-bearing:
+ *   a DETACHED run never reaches the gateway, so this is the only way a
+ *   browser tails autonomous work.
  * - **scope index** (`scope:${scopeId}`) — the running-turn index backing
- *   `TurnEventStore.listRunning` reconnect discovery.
+ *   `TurnEventStore.listRunning` reconnect discovery. KEPT.
  *
  * The class is a PLAIN class over a structural {@link TurnStreamDOState} —
  * no `cloudflare:workers` import, so this package stays substrate-free and
@@ -345,9 +452,21 @@ declare class TurnStreamDO {
  * 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.
+ * context knows both. Products wire the workspace signal helpers into
+ * `createChatTurnRoutes`' `onEvent`.
+ *
+ * Which adapters are still the right answer (see `./core`'s header for the
+ * production measurement behind this split):
+ *
+ * | adapter                              | status                            |
+ * | ------------------------------------ | --------------------------------- |
+ * | {@link createDurableTurnLock}        | KEPT — no SDK equivalent          |
+ * | {@link reconcileStaleDurableTurnLock}| KEPT — no SDK equivalent          |
+ * | {@link createDurableObjectTurnEventStore} | KEPT — the DETACHED lane     |
+ * | {@link broadcastWorkspaceActivity}   | KEPT — workspace signal           |
+ * | {@link broadcastThreadCreated}       | KEPT — workspace signal           |
+ * | {@link createTurnStreamUpgradeHandler} | KEPT for the workspace channel  |
+ * | {@link broadcastTurnStreamEvent}     | `@deprecated` for sandbox turns   |
  */
 
 /** Resolve a stub interface for handling fetch requests with optional initialization parameters */
@@ -366,6 +485,15 @@ interface TurnStreamNamespaceLike {
  * 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.
+ *
+ * KEPT and load-bearing for AUTONOMOUS work. A detached run
+ * (`dispatchPrompt({ detach: true })`, `driveTurn`) executes on the sandbox
+ * run/stream lane, which publishes nothing to the session event bus — a
+ * `SessionGatewayClient` attached to that session sees zero turn events
+ * (measured: 0 of 71 / 0 of 527 / 0 of 408 across three session-id
+ * strategies). So a browser that must tail a mission step, a queue job, or
+ * an inbound-email review has no SDK path; it needs these durable rows plus
+ * `runDetachedTurn` (`/chat-routes`). Nothing here is deprecated.
  */
 declare function createDurableObjectTurnEventStore(namespace: TurnStreamNamespaceLike): TurnEventStore;
 /** Define input parameters required to acquire a durable turn lock in a workspace thread context */
@@ -478,11 +606,36 @@ declare function createDurableTurnLock<TContext>(options: CreateDurableTurnLockO
     release(handle: unknown): Promise<void>;
 };
 /**
- * Fan a turn event out to the per-thread channel. `executionId` groups events
+ * DEPRECATED for sandbox-backed interactive turns (drive on the session-message
+ * lane + `SessionGatewayClient` instead) — 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).
+ *
+ * @deprecated For a SANDBOX-backed interactive turn this re-broadcasts events
+ * the sandbox platform already fans out, at the cost of a worker hop. Drive
+ * the turn on the session-MESSAGE lane instead —
+ * `box.createSession({ sessionId, backend })` then
+ * `box.session(id).sendMessage({ parts: [{ type: 'text', text }] })` — and let
+ * the tab attach with `box.mintScopedToken({ scope: 'session', sessionId,
+ * runtimeSessionId })` + `SessionGatewayClient`
+ * (`@tangle-network/sandbox/session-gateway`). Measured on production
+ * (4 arms, SDK 0.12.0): turns driven with `box.streamPrompt()` delivered
+ * 0 of 71 / 0 of 527 / 0 of 408 turn events to a gateway client, because
+ * `POST /agents/run/stream` publishes nothing to the session event bus;
+ * the message lane delivered 297 of 297.
+ *
+ * Two things this deprecation does NOT cover, both still supported:
+ * DETACHED runs (no gateway fanout at all — keep `runDetachedTurn` over the
+ * durable turn-event rows) and the per-workspace signals
+ * ({@link broadcastWorkspaceActivity} / {@link broadcastThreadCreated}).
+ * A SANDBOX-FREE copilot that wants a second viewer should use `/stream`'s
+ * `replayTurnEvents` (`GET /chat/stream/:turnId`), which follows a running
+ * turn from a cursor without a second broadcast fabric.
+ *
+ * Kept for back-compat; removal is a major-version change.
  */
 declare function broadcastTurnStreamEvent(namespace: TurnStreamNamespaceLike, input: {
     workspaceId: string;
@@ -530,6 +683,14 @@ interface CreateTurnStreamUpgradeHandlerOptions {
  *
  * After the 101, the client sends `{type:'sync', afterSeq}` and receives the
  * replay-then-live stream (see {@link TurnStreamDO.webSocketMessage}).
+ *
+ * NOT deprecated — the workspace variant (no `threadId`) is the canonical
+ * transport for the per-workspace signals, which the session gateway cannot
+ * carry (it is per-session and read-only). The THREAD variant is the
+ * deprecated half: for a sandbox-backed interactive turn the tab should
+ * attach to the session gateway directly instead of to this socket. See
+ * {@link broadcastTurnStreamEvent} for the measurement and the replacement
+ * wiring.
  */
 declare function createTurnStreamUpgradeHandler(options: CreateTurnStreamUpgradeHandlerOptions): (request: Request) => Promise<Response | null>;