@tangle-network/agent-app 0.43.46 → 0.43.47

package/dist/stale-turn-lock-C8Na1cFZ.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Recovery policy for a `ChatTurnLock` whose holder died.
+ *
+ * `createChatTurnRoutes` takes the lock as a seam (`acquire`/`release`) and a
+ * lock is a single-flight guard: while it is held, a second turn on the same
+ * scope is refused. Products give it a TTL measured in tens of minutes, so a
+ * turn that dies without releasing wedges chat for that whole window. Every
+ * app on the seam inherits that wedge, which is why the way OUT of it is
+ * policy this package owns rather than something each app rediscovers.
+ *
+ * The policy takes PROBES, not clients: it imports no sandbox SDK, opens no
+ * connection, and knows nothing about how a product finds its box or talks to
+ * a sidecar. That is what makes the rules testable and what keeps the concrete
+ * probes — which box key, which session id, which sidecar endpoint — in the
+ * product.
+ *
+ * The rules, in precedence order:
+ *
+ * 1. The session probe answered and the execution is TERMINAL ⇒ release, once
+ *    the lock is past a short grace period. The authority on "is this turn
+ *    still running" is whatever is actually running it; a terminal verdict is
+ *    proof the lock outlived its turn — but only if the verdict is about THIS
+ *    turn, which is what the grace buys (see
+ *    {@link DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS}).
+ * 2. The session probe answered and the execution is LIVE ⇒ hold, always.
+ *    Nothing below may override this. The lock is doing exactly its job.
+ * 3. The probes could not reach that authority at all — the sandbox could not
+ *    be listed, is gone, is not running, or its session probe failed ⇒ fall
+ *    back on the physical argument: an execution runs INSIDE the box, so a box
+ *    that is not there is running nothing, and the lock is releasable. Without
+ *    this fallback the recovery would depend on the very subsystem whose
+ *    failure produced the stale lock.
+ *
+ * Rule 3 is gated on a grace period because it is an inference, not an
+ * observation — see {@link DEFAULT_STALE_TURN_LOCK_GRACE_MS}.
+ */
+/** Where the box is, as far as the caller can see. `state` on `not-running`
+ *  is the platform's own status string, carried through for the log. */
+type StaleTurnLockSandboxProbeResult = {
+    status: 'running';
+} | {
+    status: 'absent';
+} | {
+    status: 'not-running';
+    state?: string;
+};
+/** What the thing running the turn says about it. `terminal: false` means an
+ *  execution is LIVE — the strongest signal in the policy. `diagnostics` rides
+ *  through to the result and the logs unread. */
+type StaleTurnLockSessionProbeResult = {
+    reachable: true;
+    terminal: boolean;
+    diagnostics?: Record<string, unknown>;
+} | {
+    reachable: false;
+    reason?: string;
+};
+/**
+ * Minimum age a lock must reach before the "sandbox unreachable ⇒ nothing can
+ * be running" fallback may force-release it.
+ *
+ * The lock is acquired BEFORE the box is ensured, so during a cold workspace's
+ * first turn there is a real window in which the lock is held and no box exists
+ * yet — indistinguishable, from a peek, from a box that vanished. The grace
+ * period has to outlast that window (create + bootstrap + whatever the product
+ * hydrates) or a concurrent request steals the lock from a turn that is merely
+ * still provisioning. Five minutes clears observed cold starts with room to
+ * spare while cutting the worst case from a TTL-length wedge down to five
+ * minutes. Raising it makes recovery slower; lowering it risks stealing a lock
+ * mid-provision.
+ */
+declare const DEFAULT_STALE_TURN_LOCK_GRACE_MS: number;
+/**
+ * Minimum age a lock must reach before a TERMINAL session verdict may release
+ * it.
+ *
+ * The session probe is keyed on the THREAD, not on the execution the lock
+ * holds: a sidecar that has nothing running reports `terminal` with
+ * `activeExecutionId: null`, so there is no id to match the lock against. The
+ * lock, meanwhile, is acquired BEFORE the box is ensured and before the
+ * execution registers with the sidecar. Between those two moments a second
+ * request that reconciles the lock asks the sidecar about a turn it has not
+ * heard of yet and gets back the PREVIOUS turn's terminal state — proof about
+ * the wrong execution. Releasing on that verdict hands the second request a
+ * lock the first one is still using, which is two concurrent turns on a scope
+ * whose single-flight guard just voted for itself.
+ *
+ * One minute covers the acquire → box-ensure → sidecar-registration window on
+ * a warm box (the cold-box case is Rule 3's, and has its own, much longer
+ * grace). Deliberately NOT
+ * {@link DEFAULT_STALE_TURN_LOCK_GRACE_MS}: this branch has a positive
+ * observation behind it, so it should recover fast, and stretching it to five
+ * minutes would leave a genuinely dead turn wedged for the whole window that
+ * the session probe exists to shortcut. Raising it delays recovery from a
+ * crashed turn; lowering it narrows the registration window it protects.
+ */
+declare const DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS: number;
+interface ReconcileStaleTurnLockOptions {
+    /** When the held lock was acquired (epoch ms). The grace period is measured
+     *  from here, so it must be the LOCK's start, not the turn's. */
+    lockStartedAt: number;
+    /** Is the box there and running? Never provisions — a peek, not an ensure.
+     *  A throw is treated as unreachable, same as `absent`. */
+    probeSandbox(): Promise<StaleTurnLockSandboxProbeResult>;
+    /** Ask the running box whether the execution is still live. Only called when
+     *  `probeSandbox` reported `running`. A throw is treated as unreachable. */
+    probeSession(): Promise<StaleTurnLockSessionProbeResult>;
+    /** Release the lock, fenced by the instant the releasing evidence was
+     *  observed. `fence.observedAt` is snapshotted BEFORE the probe that
+     *  justified the release, so a store that can compare it against the held
+     *  lock's start refuses to delete a SUCCESSOR lock acquired while the probe
+     *  was in flight. A store that cannot make that comparison may ignore the
+     *  fence, but must not substitute its own `Date.now()` — that timestamp is
+     *  by construction newer than any successor and makes the check vacuous.
+     *
+     *  Returns whether the release actually landed — `false` when the lock was
+     *  already gone (someone else got there first), which is reported, never
+     *  treated as a release. */
+    release(fence: {
+        observedAt: number;
+    }): boolean | Promise<boolean>;
+    /** Override {@link DEFAULT_STALE_TURN_LOCK_GRACE_MS} (Rule 3's fallback). */
+    graceMs?: number;
+    /** Override {@link DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS} (Rule 1's release). */
+    terminalGraceMs?: number;
+    /** Identity fields merged into every log line (workspace, thread, execution
+     *  id — whatever makes the entry findable in the product's logs). */
+    context?: Record<string, unknown>;
+    /** Defaults to `console.warn`. Both the withheld and the force-released
+     *  branches log; a force-release is never silent. */
+    log?(message: string, meta: Record<string, unknown>): void;
+    /** Injectable clock, for tests. */
+    now?(): number;
+}
+interface ReconcileStaleTurnLockResult {
+    released: boolean;
+    /** Why the policy decided what it did — the probe's own diagnostics on the
+     *  reachable path, the unreachable reason and lock age on the fallback. */
+    diagnostics: Record<string, unknown>;
+}
+/**
+ * Decide whether a held lock is stale and, if so, release it.
+ *
+ * Never provisions and never mutates anything but the lock: a reconciliation
+ * attempt on a cold workspace leaves it cold.
+ */
+declare function reconcileStaleTurnLock(options: ReconcileStaleTurnLockOptions): Promise<ReconcileStaleTurnLockResult>;
+
+export { DEFAULT_STALE_TURN_LOCK_GRACE_MS as D, type ReconcileStaleTurnLockOptions as R, type StaleTurnLockSandboxProbeResult as S, DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS as a, type ReconcileStaleTurnLockResult as b, type StaleTurnLockSessionProbeResult as c, reconcileStaleTurnLock as r };

package/dist/stream/index.d.ts

@@ -1,4 +1,5 @@
 import { b as ChatInteractionStatus } from '../contract-KfqJh_au.js';
+export { B as BufferedTurnEvent, a as BufferedTurnOptions, b as BufferedTurnTap, D as D1LikeForTurns, P as PumpBufferedTurnOptions, R as ReplayTurnEventsOptions, T as TURN_EVENTS_MIGRATION_SQL, c as TURN_STATUS_SCOPE_MIGRATION_SQL, d as TurnEventStore, e as TurnStatus, f as coalesceChatStreamEvents, g as coalesceDeltas, h as createBufferedTurnTap, i as createD1TurnEventStore, j as createMemoryTurnEventStore, p as pumpBufferedTurn, r as replayTurnEvents } from '../turn-buffer-C9mEgoop.js';
 import '@tangle-network/agent-interface';
 
 type JsonRecord = Record<string, unknown>;
@@ -67,149 +68,4 @@ declare function resolveChatTurn(input: {
     turnId?: string;
 }): ResolvedChatTurn;
 
-/**
- * Resumable chat turns — the router-path answer to "streams resume on
- * disconnect" (issue #27). A turn's loop events are teed into a store as they
- * stream; the turn keeps running under `ctx.waitUntil` when the client drops;
- * a reconnecting client replays the buffered tail by sequence number and
- * keeps following until the turn completes.
- *
- *   POST /chat/stream            → pumpBufferedTurn(...) + live NDJSON
- *   GET  /chat/stream/:turnId    → replayTurnEvents({ fromSeq }) → NDJSON
- *
- * Storage is a structural seam ({@link TurnEventStore}); a D1 implementation
- * ships here because that's what Cloudflare products have (KV is unsuitable:
- * eventually consistent cross-isolate). Per-token deltas would mean hundreds
- * of rows per turn, so consecutive text/reasoning deltas are coalesced within
- * a flush window before they are persisted — replay yields slightly chunkier
- * deltas with identical concatenation.
- */
-type TurnStatus = 'running' | 'complete' | 'error';
-interface BufferedTurnEvent {
-    seq: number;
-    /** The serialized event line (JSON string, no trailing newline). */
-    event: string;
-}
-interface TurnEventStore {
-    append(turnId: string, events: BufferedTurnEvent[]): Promise<void>;
-    read(turnId: string, fromSeq: number): Promise<BufferedTurnEvent[]>;
-    /** Record turn lifecycle. `scopeId` (a thread/session id) is optional and lets
-     *  {@link TurnEventStore.listRunning} rediscover this turn after a client reload
-     *  loses the turnId; stores that don't track scope ignore it. */
-    setStatus(turnId: string, status: TurnStatus, scopeId?: string): Promise<void>;
-    getStatus(turnId: string): Promise<TurnStatus | null>;
-    /** Running turnIds for a scope, newest first — so a reloaded client (clientRunId
-     *  lost) can find and resume the in-flight turn. Optional: a store records it
-     *  only if `setStatus` was given a `scopeId`. */
-    listRunning?(scopeId: string): Promise<string[]>;
-}
-/** Merge consecutive text/reasoning deltas of the same type into one event.
- *  Concatenation-preserving: replaying the coalesced stream produces the same
- *  accumulated text as the original. */
-declare function coalesceDeltas(events: unknown[]): unknown[];
-/**
- * Coalesce consecutive `message.part.updated` deltas for the SAME part into one
- * event. agent-runtime products stream `ChatStreamEvent` NDJSON
- * (`{type:'message.part.updated', data:{part, delta}}`); pumped through the
- * buffer with the default tool-loop coalescer, every per-token delta persists as
- * its own row because that coalescer never recognizes the shape. Pass this as
- * {@link PumpBufferedTurnOptions.coalesce} instead.
- *
- * Concatenation-preserving for BOTH consumer styles: the merged event keeps the
- * LATEST event's `data.part` (already the cumulative accumulation) and sets
- * `data.delta` to the concatenation of the merged deltas, so a client that
- * appends `delta` and one that reads the cumulative `part` both reconstruct the
- * identical final text.
- */
-declare function coalesceChatStreamEvents(events: unknown[]): unknown[];
-interface BufferedTurnOptions {
-    store: TurnEventStore;
-    turnId: string;
-    /** Deliver one serialized line to the live client. Throwing here (client
-     *  disconnected) does NOT stop buffering — events keep persisting. */
-    write?: (line: string) => Promise<void> | void;
-    /** Flush buffered events to the store at most this often. Default 400ms. */
-    flushIntervalMs?: number;
-    /** Per-flush coalescer. Default {@link coalesceDeltas} (tool-loop text/reasoning
-     *  deltas). agent-runtime products streaming `ChatStreamEvent` pass
-     *  {@link coalesceChatStreamEvents} so per-token deltas don't each persist as a
-     *  row. Must be concatenation-preserving. */
-    coalesce?: (events: unknown[]) => unknown[];
-    /** Optional scope (thread/session id) recorded with the turn status, so
-     *  {@link TurnEventStore.listRunning} can find this turn after a reload. */
-    scopeId?: string;
-}
-/** A push-driven buffer for a turn whose producer the caller does NOT own. */
-interface BufferedTurnTap {
-    /** Buffer one event: persist (coalesced, on the flush window) + best-effort
-     *  live-deliver. Wire to a push source's per-event hook (e.g. agent-runtime
-     *  `handleChatTurn`'s `hooks.onEvent`). Marks the turn 'running' on first call. */
-    onEvent(raw: unknown): Promise<void>;
-    /** Settle the turn: final flush + set status. Call after the producer resolves
-     *  ('complete') or rejects ('error'). 'error' flushes what was produced first. */
-    done(status?: Extract<TurnStatus, 'complete' | 'error'>): Promise<void>;
-}
-/**
- * The buffering core. Sequence-numbers every event, delivers it to `write`
- * (best-effort — a disconnected client never stops buffering), and flushes to
- * the store in coalesced batches. Drives both transports:
- *
- *   • {@link pumpBufferedTurn}     — when you OWN an `AsyncIterable` producer.
- *   • this tap (`onEvent`/`done`)  — when the producer owns iteration and only
- *     hands you a push callback (agent-runtime `handleChatTurn`'s `hooks.onEvent`
- *     + the finished body). Durability stays here in the shell; the engine needs
- *     no `TurnEventStore` seam.
- */
-declare function createBufferedTurnTap(opts: BufferedTurnOptions): BufferedTurnTap;
-interface PumpBufferedTurnOptions extends BufferedTurnOptions {
-    source: AsyncIterable<unknown>;
-}
-/**
- * Drive a turn to completion regardless of the live client, when you OWN the
- * producer as an `AsyncIterable`. A thin driver over {@link createBufferedTurnTap}.
- * Returns a promise that resolves when the turn finishes — hand it to
- * `ctx.waitUntil` so a disconnect can't kill the turn. Never rejects on
- * client-write failure; a source error marks the turn 'error' (after flushing
- * what was produced) and rethrows.
- */
-declare function pumpBufferedTurn(opts: PumpBufferedTurnOptions): Promise<void>;
-interface ReplayTurnEventsOptions {
-    store: TurnEventStore;
-    turnId: string;
-    /** Replay strictly after this sequence number (0 = from the beginning). */
-    fromSeq?: number;
-    /** Poll cadence while the turn is still running. Default 500ms. */
-    pollMs?: number;
-    /** Give up following a 'running' turn after this long. Default 120s. */
-    timeoutMs?: number;
-}
-/**
- * Yield buffered events after `fromSeq`, then keep polling while the turn is
- * still 'running' until it completes, errors, or times out. Terminates with a
- * final `{seq: -1, event: '{"type":"turn_status",...}'}` marker so clients
- * know why the replay ended.
- */
-declare function replayTurnEvents(opts: ReplayTurnEventsOptions): AsyncGenerator<BufferedTurnEvent>;
-/** Minimal structural D1 contract (Cloudflare `D1Database` satisfies it). */
-interface D1LikeForTurns {
-    prepare(sql: string): {
-        bind(...values: unknown[]): {
-            run(): Promise<unknown>;
-            all<T = Record<string, unknown>>(): Promise<{
-                results: T[];
-            }>;
-            first<T = Record<string, unknown>>(): Promise<T | null>;
-        };
-    };
-}
-/** Schema for the D1 store — append to the product's migrations. */
-declare const TURN_EVENTS_MIGRATION_SQL = "\nCREATE TABLE IF NOT EXISTS turn_events (\n  turnId TEXT NOT NULL,\n  seq INTEGER NOT NULL,\n  event TEXT NOT NULL,\n  PRIMARY KEY (turnId, seq)\n);\nCREATE TABLE IF NOT EXISTS turn_status (\n  turnId TEXT PRIMARY KEY,\n  status TEXT NOT NULL,\n  scopeId TEXT,\n  updatedAt TEXT NOT NULL\n);\nCREATE INDEX IF NOT EXISTS idx_turn_status_scope ON turn_status (scopeId, status);\n";
-/** For deployments whose `turn_status` table predates `scopeId`/`listRunning` —
- *  run once to add the column (the CREATE above already includes it for new
- *  deployments). SQLite ignores a duplicate-add error if already applied. */
-declare const TURN_STATUS_SCOPE_MIGRATION_SQL = "ALTER TABLE turn_status ADD COLUMN scopeId TEXT;";
-declare function createD1TurnEventStore(db: D1LikeForTurns): TurnEventStore;
-/** In-memory store for tests and keyless local dev. */
-declare function createMemoryTurnEventStore(): TurnEventStore;
-
-export { type BufferedTurnEvent, type BufferedTurnOptions, type BufferedTurnTap, type D1LikeForTurns, type JsonRecord, MISSING_TOOL_TERMINAL_ERROR, MISSING_TOOL_TERMINAL_REASON, type PersistedChatMessageForTurn, type PumpBufferedTurnOptions, type ReplayTurnEventsOptions, type ResolvedChatTurn, type StreamEvent, TURN_EVENTS_MIGRATION_SQL, TURN_STATUS_SCOPE_MIGRATION_SQL, type TurnEventStore, type TurnStatus, asRecord, asString, attachmentPartKey, buildUserTextParts, coalesceChatStreamEvents, coalesceDeltas, collapseRedundantTextParts, createBufferedTurnTap, createD1TurnEventStore, createMemoryTurnEventStore, encodeEvent, finalizeAssistantParts, finalizePendingInteractionParts, getPartKey, mergePersistedPart, messageHasTurnId, normalizeClientTurnId, normalizePersistedPart, normalizeTime, normalizeToolEvent, pumpBufferedTurn, replayTurnEvents, resolveChatTurn, resolveToolId, resolveToolName, terminalizeDanglingAssistantToolUpdates, terminalizeDanglingToolPart, terminalizeDanglingToolParts };
+export { type JsonRecord, MISSING_TOOL_TERMINAL_ERROR, MISSING_TOOL_TERMINAL_REASON, type PersistedChatMessageForTurn, type ResolvedChatTurn, type StreamEvent, asRecord, asString, attachmentPartKey, buildUserTextParts, collapseRedundantTextParts, encodeEvent, finalizeAssistantParts, finalizePendingInteractionParts, getPartKey, mergePersistedPart, messageHasTurnId, normalizeClientTurnId, normalizePersistedPart, normalizeTime, normalizeToolEvent, resolveChatTurn, resolveToolId, resolveToolName, terminalizeDanglingAssistantToolUpdates, terminalizeDanglingToolPart, terminalizeDanglingToolParts };

package/dist/teams/index.js

@@ -1,3 +1,12 @@
+import {
+  INVITATION_EXPIRY_DAYS,
+  generateInvitationToken,
+  getInvitationExpiresAt,
+  inviteUrlForToken,
+  normalizeInvitationEmail,
+  parseInvitationPermission,
+  renderInvitationEmail
+} from "../chunk-WEBBJBDH.js";
 import {
   generateInviteToken,
   isInviteTokenShape,
@@ -18,15 +27,6 @@ import {
   workspaceRoleToCollaborationAccess,
   workspaceRoleToSandboxRole
 } from "../chunk-63CE7FEZ.js";
-import {
-  INVITATION_EXPIRY_DAYS,
-  generateInvitationToken,
-  getInvitationExpiresAt,
-  inviteUrlForToken,
-  normalizeInvitationEmail,
-  parseInvitationPermission,
-  renderInvitationEmail
-} from "../chunk-WEBBJBDH.js";
 export {
   ASSIGNABLE_WORKSPACE_ROLES,
   INVITATION_EXPIRY_DAYS,

package/dist/teams/invitations-api.js

@@ -1,10 +1,3 @@
-import {
-  SeatLimitError
-} from "../chunk-SWUVTGMR.js";
-import "../chunk-3SVAA3MA.js";
-import {
-  hasWorkspaceRole
-} from "../chunk-63CE7FEZ.js";
 import {
   generateInvitationToken,
   getInvitationExpiresAt,
@@ -12,6 +5,13 @@ import {
   normalizeInvitationEmail,
   parseInvitationPermission
 } from "../chunk-WEBBJBDH.js";
+import {
+  SeatLimitError
+} from "../chunk-SWUVTGMR.js";
+import "../chunk-3SVAA3MA.js";
+import {
+  hasWorkspaceRole
+} from "../chunk-63CE7FEZ.js";
 
 // src/teams/invitations-api.ts
 import { and, eq, lte, sql } from "drizzle-orm";

package/dist/turn-buffer-C9mEgoop.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Resumable chat turns — the router-path answer to "streams resume on
+ * disconnect" (issue #27). A turn's loop events are teed into a store as they
+ * stream; the turn keeps running under `ctx.waitUntil` when the client drops;
+ * a reconnecting client replays the buffered tail by sequence number and
+ * keeps following until the turn completes.
+ *
+ *   POST /chat/stream            → pumpBufferedTurn(...) + live NDJSON
+ *   GET  /chat/stream/:turnId    → replayTurnEvents({ fromSeq }) → NDJSON
+ *
+ * Storage is a structural seam ({@link TurnEventStore}); a D1 implementation
+ * ships here because that's what Cloudflare products have (KV is unsuitable:
+ * eventually consistent cross-isolate). Per-token deltas would mean hundreds
+ * of rows per turn, so consecutive text/reasoning deltas are coalesced within
+ * a flush window before they are persisted — replay yields slightly chunkier
+ * deltas with identical concatenation.
+ */
+type TurnStatus = 'running' | 'complete' | 'error';
+interface BufferedTurnEvent {
+    seq: number;
+    /** The serialized event line (JSON string, no trailing newline). */
+    event: string;
+}
+interface TurnEventStore {
+    append(turnId: string, events: BufferedTurnEvent[]): Promise<void>;
+    read(turnId: string, fromSeq: number): Promise<BufferedTurnEvent[]>;
+    /** Record turn lifecycle. `scopeId` (a thread/session id) is optional and lets
+     *  {@link TurnEventStore.listRunning} rediscover this turn after a client reload
+     *  loses the turnId; stores that don't track scope ignore it. */
+    setStatus(turnId: string, status: TurnStatus, scopeId?: string): Promise<void>;
+    getStatus(turnId: string): Promise<TurnStatus | null>;
+    /** Running turnIds for a scope, newest first — so a reloaded client (clientRunId
+     *  lost) can find and resume the in-flight turn. Optional: a store records it
+     *  only if `setStatus` was given a `scopeId`. */
+    listRunning?(scopeId: string): Promise<string[]>;
+}
+/** Merge consecutive text/reasoning deltas of the same type into one event.
+ *  Concatenation-preserving: replaying the coalesced stream produces the same
+ *  accumulated text as the original. */
+declare function coalesceDeltas(events: unknown[]): unknown[];
+/**
+ * Coalesce consecutive `message.part.updated` deltas for the SAME part into one
+ * event. agent-runtime products stream `ChatStreamEvent` NDJSON
+ * (`{type:'message.part.updated', data:{part, delta}}`); pumped through the
+ * buffer with the default tool-loop coalescer, every per-token delta persists as
+ * its own row because that coalescer never recognizes the shape. Pass this as
+ * {@link PumpBufferedTurnOptions.coalesce} instead.
+ *
+ * Concatenation-preserving for BOTH consumer styles: the merged event keeps the
+ * LATEST event's `data.part` (already the cumulative accumulation) and sets
+ * `data.delta` to the concatenation of the merged deltas, so a client that
+ * appends `delta` and one that reads the cumulative `part` both reconstruct the
+ * identical final text.
+ */
+declare function coalesceChatStreamEvents(events: unknown[]): unknown[];
+interface BufferedTurnOptions {
+    store: TurnEventStore;
+    turnId: string;
+    /** Deliver one serialized line to the live client. Throwing here (client
+     *  disconnected) does NOT stop buffering — events keep persisting. */
+    write?: (line: string) => Promise<void> | void;
+    /** Flush buffered events to the store at most this often. Default 400ms. */
+    flushIntervalMs?: number;
+    /** Per-flush coalescer. Default {@link coalesceDeltas} (tool-loop text/reasoning
+     *  deltas). agent-runtime products streaming `ChatStreamEvent` pass
+     *  {@link coalesceChatStreamEvents} so per-token deltas don't each persist as a
+     *  row. Must be concatenation-preserving. */
+    coalesce?: (events: unknown[]) => unknown[];
+    /** Optional scope (thread/session id) recorded with the turn status, so
+     *  {@link TurnEventStore.listRunning} can find this turn after a reload. */
+    scopeId?: string;
+}
+/** A push-driven buffer for a turn whose producer the caller does NOT own. */
+interface BufferedTurnTap {
+    /** Buffer one event: persist (coalesced, on the flush window) + best-effort
+     *  live-deliver. Wire to a push source's per-event hook (e.g. agent-runtime
+     *  `handleChatTurn`'s `hooks.onEvent`). Marks the turn 'running' on first call. */
+    onEvent(raw: unknown): Promise<void>;
+    /** Settle the turn: final flush + set status. Call after the producer resolves
+     *  ('complete') or rejects ('error'). 'error' flushes what was produced first. */
+    done(status?: Extract<TurnStatus, 'complete' | 'error'>): Promise<void>;
+}
+/**
+ * The buffering core. Sequence-numbers every event, delivers it to `write`
+ * (best-effort — a disconnected client never stops buffering), and flushes to
+ * the store in coalesced batches. Drives both transports:
+ *
+ *   • {@link pumpBufferedTurn}     — when you OWN an `AsyncIterable` producer.
+ *   • this tap (`onEvent`/`done`)  — when the producer owns iteration and only
+ *     hands you a push callback (agent-runtime `handleChatTurn`'s `hooks.onEvent`
+ *     + the finished body). Durability stays here in the shell; the engine needs
+ *     no `TurnEventStore` seam.
+ */
+declare function createBufferedTurnTap(opts: BufferedTurnOptions): BufferedTurnTap;
+interface PumpBufferedTurnOptions extends BufferedTurnOptions {
+    source: AsyncIterable<unknown>;
+}
+/**
+ * Drive a turn to completion regardless of the live client, when you OWN the
+ * producer as an `AsyncIterable`. A thin driver over {@link createBufferedTurnTap}.
+ * Returns a promise that resolves when the turn finishes — hand it to
+ * `ctx.waitUntil` so a disconnect can't kill the turn. Never rejects on
+ * client-write failure; a source error marks the turn 'error' (after flushing
+ * what was produced) and rethrows.
+ */
+declare function pumpBufferedTurn(opts: PumpBufferedTurnOptions): Promise<void>;
+interface ReplayTurnEventsOptions {
+    store: TurnEventStore;
+    turnId: string;
+    /** Replay strictly after this sequence number (0 = from the beginning). */
+    fromSeq?: number;
+    /** Poll cadence while the turn is still running. Default 500ms. */
+    pollMs?: number;
+    /** Give up following a 'running' turn after this long. Default 120s. */
+    timeoutMs?: number;
+}
+/**
+ * Yield buffered events after `fromSeq`, then keep polling while the turn is
+ * still 'running' until it completes, errors, or times out. Terminates with a
+ * final `{seq: -1, event: '{"type":"turn_status",...}'}` marker so clients
+ * know why the replay ended.
+ */
+declare function replayTurnEvents(opts: ReplayTurnEventsOptions): AsyncGenerator<BufferedTurnEvent>;
+/** Minimal structural D1 contract (Cloudflare `D1Database` satisfies it). */
+interface D1LikeForTurns {
+    prepare(sql: string): {
+        bind(...values: unknown[]): {
+            run(): Promise<unknown>;
+            all<T = Record<string, unknown>>(): Promise<{
+                results: T[];
+            }>;
+            first<T = Record<string, unknown>>(): Promise<T | null>;
+        };
+    };
+}
+/** Schema for the D1 store — append to the product's migrations. */
+declare const TURN_EVENTS_MIGRATION_SQL = "\nCREATE TABLE IF NOT EXISTS turn_events (\n  turnId TEXT NOT NULL,\n  seq INTEGER NOT NULL,\n  event TEXT NOT NULL,\n  PRIMARY KEY (turnId, seq)\n);\nCREATE TABLE IF NOT EXISTS turn_status (\n  turnId TEXT PRIMARY KEY,\n  status TEXT NOT NULL,\n  scopeId TEXT,\n  updatedAt TEXT NOT NULL\n);\nCREATE INDEX IF NOT EXISTS idx_turn_status_scope ON turn_status (scopeId, status);\n";
+/** For deployments whose `turn_status` table predates `scopeId`/`listRunning` —
+ *  run once to add the column (the CREATE above already includes it for new
+ *  deployments). SQLite ignores a duplicate-add error if already applied. */
+declare const TURN_STATUS_SCOPE_MIGRATION_SQL = "ALTER TABLE turn_status ADD COLUMN scopeId TEXT;";
+declare function createD1TurnEventStore(db: D1LikeForTurns): TurnEventStore;
+/** In-memory store for tests and keyless local dev. */
+declare function createMemoryTurnEventStore(): TurnEventStore;
+
+export { type BufferedTurnEvent as B, type D1LikeForTurns as D, type PumpBufferedTurnOptions as P, type ReplayTurnEventsOptions as R, TURN_EVENTS_MIGRATION_SQL as T, type BufferedTurnOptions as a, type BufferedTurnTap as b, TURN_STATUS_SCOPE_MIGRATION_SQL as c, type TurnEventStore as d, type TurnStatus as e, coalesceChatStreamEvents as f, coalesceDeltas as g, createBufferedTurnTap as h, createD1TurnEventStore as i, createMemoryTurnEventStore as j, pumpBufferedTurn as p, replayTurnEvents as r };