@tangle-network/agent-app 0.43.67 → 0.43.69

package/dist/queue-C24V13h9.d.ts

@@ -0,0 +1,68 @@
+import { i as WorkProductRecord, j as WorkProductRef, h as WorkProductProvenance } from './types-CEchbvgz.js';
+
+/**
+ * The review queue is a PROJECTION, not a store — a client-safe pure fold of
+ * existing sources into queue items (the `/missions` events.ts pattern: pure
+ * data, re-validation at JSON boundaries). The only genuinely-new durable
+ * state behind it is the {@link WorkProductRecord} row and its status
+ * machine; everything else reads what already exists:
+ *
+ *  - intake: a chat thread for the engagement scope with NO record yet
+ *  - missing_info: the open record's thread has a PENDING `/interactions` ask
+ *  - working: record status `draft` (the live token tail stays on the chat
+ *    surface's existing running-turns endpoint — the projection tracks no
+ *    live runs, per the reuse-the-primitive invariant)
+ *  - ready_for_review / changes_requested / approved / blocked: read directly
+ *    off `WorkProductRecord.status` (blocked surfaces its unresolved count)
+ */
+
+type ReviewQueueState = 'intake' | 'missing_info' | 'working' | 'ready_for_review' | 'changes_requested' | 'approved' | 'blocked';
+/** One row of the review queue projection for an engagement scope */
+interface ReviewQueueItem {
+    scopeKey: string;
+    state: ReviewQueueState;
+    threadId: string | null;
+    workProduct?: WorkProductRef & {
+        title: string;
+        kind: string;
+    };
+    /** The pending `/interactions` ask parking this scope, when any. */
+    pendingAsk?: {
+        interactionId: string;
+        title: string;
+    };
+    blockingExceptions: number;
+    failedChecks: number;
+    provenance?: Pick<WorkProductProvenance, 'profileHash' | 'servingModels'>;
+    updatedAt: number;
+}
+/** An engagement-scoped chat thread — the intake candidate source. Products
+ *  that scope threads already carry a scopeKey-style column. */
+interface ReviewQueueThread {
+    scopeKey: string;
+    threadId: string;
+    updatedAt: number;
+}
+/** A pending `/interactions` ask on a thread (from the existing list
+ *  endpoint) — the missing_info source. */
+interface ReviewQueuePendingAsk {
+    threadId: string;
+    interactionId: string;
+    title: string;
+}
+/** Existing-source inputs the projection folds — no new stores */
+interface ReviewQueueInputs {
+    workProducts: readonly WorkProductRecord[];
+    /** Engagement threads with no work product yet → intake items. */
+    threads?: readonly ReviewQueueThread[];
+    /** Pending asks by thread → missing_info override on open records. */
+    pendingAsks?: readonly ReviewQueuePendingAsk[];
+}
+/** Fold the existing sources into queue items, newest first. */
+declare function projectReviewQueue(inputs: ReviewQueueInputs): ReviewQueueItem[];
+/** Re-validate one JSON-boundary row into a queue item; null for junk. The
+ *  client-side twin of the server projection, for payloads that cross a
+ *  fetch boundary. */
+declare function parseReviewQueueItem(raw: unknown): ReviewQueueItem | null;
+
+export { type ReviewQueueInputs as R, type ReviewQueueItem as a, type ReviewQueuePendingAsk as b, type ReviewQueueState as c, type ReviewQueueThread as d, projectReviewQueue as e, parseReviewQueueItem as p };

package/dist/runtime/index.js

@@ -8,7 +8,7 @@ import {
   runToolLoop,
   streamToolLoop,
   toLoopEvents
-} from "../chunk-JWBZ74TW.js";
+} from "../chunk-7ESQUSAC.js";
 import {
   DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR,
   DEFAULT_TANGLE_ROUTER_BASE_URL,
@@ -24,7 +24,8 @@ import {
   tangleExecutionKeyHttpError,
   trimOrNull
 } from "../chunk-JML7WKWU.js";
-import "../chunk-7CTIUCQ4.js";
+import "../chunk-UOAYS72M.js";
+import "../chunk-YEFFHORB.js";
 import {
   __resetCatalogCache,
   buildCatalog,

package/dist/sandbox/index.js

@@ -60,11 +60,12 @@ import {
   writeProfileFilesToBox
 } from "../chunk-3ALFBTIW.js";
 import "../chunk-CQZSAR77.js";
-import "../chunk-YKBDH2UY.js";
+import "../chunk-WL7XHLDK.js";
 import "../chunk-3EJ6SFJI.js";
 import "../chunk-S5SRJJQG.js";
 import "../chunk-JML7WKWU.js";
-import "../chunk-7CTIUCQ4.js";
+import "../chunk-UOAYS72M.js";
+import "../chunk-YEFFHORB.js";
 export {
   DEFAULT_SANDBOX_RESOURCES,
   ENV_TOTAL_MAX_BYTES,

package/dist/teams/index.js

@@ -1,3 +1,8 @@
+import {
+  generateInviteToken,
+  isInviteTokenShape,
+  validateInviteToken
+} from "../chunk-DJ4VJIH5.js";
 import {
   INVITATION_EXPIRY_DAYS,
   generateInvitationToken,
@@ -7,11 +12,6 @@ import {
   parseInvitationPermission,
   renderInvitationEmail
 } from "../chunk-2DRYTJHI.js";
-import {
-  generateInviteToken,
-  isInviteTokenShape,
-  validateInviteToken
-} from "../chunk-DJ4VJIH5.js";
 import {
   ASSIGNABLE_WORKSPACE_ROLES,
   ORGANIZATION_ROLES,

package/dist/teams/invitations-api.js

@@ -1,3 +1,7 @@
+import {
+  SeatLimitError
+} from "../chunk-MEUNTJL5.js";
+import "../chunk-DJ4VJIH5.js";
 import {
   generateInvitationToken,
   getInvitationExpiresAt,
@@ -5,10 +9,6 @@ import {
   normalizeInvitationEmail,
   parseInvitationPermission
 } from "../chunk-2DRYTJHI.js";
-import {
-  SeatLimitError
-} from "../chunk-MEUNTJL5.js";
-import "../chunk-DJ4VJIH5.js";
 import {
   hasWorkspaceRole
 } from "../chunk-6XIAPIW6.js";

package/dist/teams-react/index.js

@@ -1,12 +1,12 @@
+import {
+  InviteAcceptPage
+} from "../chunk-VCPZ3HTN.js";
 import {
   MembersPanel
 } from "../chunk-S564OFTL.js";
 import {
   InvitationsPanel
 } from "../chunk-5SXS3YAB.js";
-import {
-  InviteAcceptPage
-} from "../chunk-VCPZ3HTN.js";
 import "../chunk-6XIAPIW6.js";
 export {
   InvitationsPanel,

package/dist/tools/index.js

@@ -6,7 +6,7 @@ import {
   restrictTaxonomy,
   verifyCapabilityToken,
   verifyExpiringCapabilityToken
-} from "../chunk-YKBDH2UY.js";
+} from "../chunk-WL7XHLDK.js";
 import {
   DEFAULT_APP_TOOL_PATHS,
   DEFAULT_HEADER_NAMES,
@@ -19,18 +19,20 @@ import {
   readToolArgs
 } from "../chunk-3EJ6SFJI.js";
 import "../chunk-S5SRJJQG.js";
+import {
+  createAppToolRuntimeExecutor,
+  dispatchAppTool,
+  outcomeStatus
+} from "../chunk-UOAYS72M.js";
 import {
   APP_TOOL_NAMES,
   ToolInputError,
   buildAppToolOpenAITools,
-  createAppToolRuntimeExecutor,
   customToolToOpenAI,
   defineAppTool,
-  dispatchAppTool,
   findCustomTool,
-  isAppToolName,
-  outcomeStatus
-} from "../chunk-7CTIUCQ4.js";
+  isAppToolName
+} from "../chunk-YEFFHORB.js";
 export {
   APP_TOOL_NAMES,
   DEFAULT_APP_TOOL_PATHS,

package/dist/trust-gate-Dcm5xSva.d.ts

@@ -0,0 +1,83 @@
+import { JudgeVerdict } from '@tangle-network/agent-eval';
+
+/**
+ * Trust gate — decides whether an ensemble's scores are allowed to be BELIEVED,
+ * one level up from {@link aggregateJudgeVerdicts} (which only reduces ONE
+ * artifact's raters to a composite). A composite is a number; this is the check
+ * that the number means anything. It is the code "Enforced by" for the
+ * measurement-validation skill's after-gate ("is this result allowed to be
+ * believed").
+ *
+ * Three checks, each fail-loud and named in `trustReasons`:
+ *   (1) inter-rater reliability over the corpus ≥ `irrFloor` — raters that
+ *       disagree no better than chance carry no signal to optimize against.
+ *   (2) per-item rater spread ≤ `spreadCeiling` — for EACH item, raters must
+ *       converge on THAT item.
+ *   (3) surviving raters per item ≥ `minSurvivors` — a mean over one or two
+ *       raters is an anecdote, not an ensemble.
+ *
+ * CRITICAL metric semantics — per-item spread is rater disagreement about the
+ * SAME item: `max(score) − min(score)` across the raters that scored THAT item
+ * (max over its dimensions), never pooled across different items or across the
+ * baseline/candidate sides. Pooling reads a genuine quality gap BETWEEN items as
+ * "the raters split" and so trips the gate exactly when the finding is largest —
+ * the failure mode the after-gate exists to prevent. The corpus IRR (check 1)
+ * leans on the substrate's `interRaterReliability`, whose expected-disagreement
+ * denominator already pools across items, so genuine item-to-item variation
+ * RAISES reliability rather than lowering it.
+ */
+
+/** One item's raters: the per-judge verdicts {@link aggregateJudgeVerdicts}
+ *  reduces, tagged with the item they scored so spread stays within-item. */
+interface TrustItem<D extends string = string> {
+    /** Stable item identifier — surfaces in `perItemSpread` and `trustReasons`. */
+    itemId: string;
+    /** The raters' verdicts for THIS item (one per judge call). A failed judge
+     *  (`perDimension: null`) is dropped before spread/IRR, never folded as 0. */
+    verdicts: readonly JudgeVerdict<D>[];
+}
+/** Thresholds for {@link trustVerdicts}. All overridable; defaults are the
+ *  conservative after-gate bar. */
+interface TrustThresholds {
+    /** Minimum corpus inter-rater reliability (Krippendorff-style α). Below this
+     *  the raters agree no better than chance. Default 0.2. */
+    irrFloor?: number;
+    /** Maximum per-item rater spread (`max − min` over a single item's surviving
+     *  raters, across its dimensions). Above this the raters split ON THAT ITEM.
+     *  Default 0.5. */
+    spreadCeiling?: number;
+    /** Minimum surviving (non-failed) raters required per item. Default 3. */
+    minSurvivors?: number;
+}
+/** Result of the trust gate. `trustworthy` iff every check passed; `trustReasons`
+ *  is empty iff `trustworthy`. */
+interface TrustVerdict {
+    /** True iff IRR ≥ floor AND every item's spread ≤ ceiling AND every item has
+     *  ≥ `minSurvivors` surviving raters. */
+    trustworthy: boolean;
+    /** One entry per FAILED check, each naming its number + the offending value.
+     *  Empty iff `trustworthy`. */
+    trustReasons: string[];
+    /** Corpus inter-rater reliability actually measured (the check-1 value). */
+    interRaterReliability: number;
+    /** Per-item spread (`max − min` over surviving raters, max over dimensions),
+     *  keyed by `itemId`. The check-2 input, surfaced for drill-down. */
+    perItemSpread: Record<string, number>;
+}
+/**
+ * Decide whether an ensemble's per-item verdicts are trustworthy enough to
+ * believe a lift computed from them. Pure: no LLM, no I/O, no clock, no random —
+ * the same `items` + `thresholds` always yield the same verdict.
+ *
+ * Sibling to {@link aggregateJudgeVerdicts}: that reduces ONE item's raters to a
+ * composite; this audits the raters ACROSS items and reports whether the
+ * composites are believable. Run it on the corpus of held-out items before
+ * reporting any lift over their scores.
+ *
+ * @throws if `items` is empty — an empty corpus has no measurable trust, and a
+ *   silent `trustworthy: true` over zero evidence is the exact lie the gate
+ *   exists to refuse.
+ */
+declare function trustVerdicts<D extends string>(items: readonly TrustItem<D>[], thresholds?: TrustThresholds): TrustVerdict;
+
+export { type TrustItem as T, type TrustThresholds as a, type TrustVerdict as b, trustVerdicts as t };

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>;