@ouispec/agent-worker 0.3.0 → 0.7.0

package/dist/runtime/types.d.ts

@@ -16,7 +16,8 @@ import type { ToolPolicy } from '../authz/tool-policy.js';
 import type { UIActionChannel } from '../ui/channel.js';
 import type { LanguageModel, ProviderOptions } from '../model.js';
 import type { ApprovalStoreClient } from '../approvals/client.js';
-import type { ApprovalContinuation } from '@ouispec/agent-core';
+import type { ApprovalContinuation, TurnStopReason, TurnStoppedMarker } from '@ouispec/agent-core';
+import type { TurnStopClient } from '../stop/turn-stop.js';
 /**
  * Database handle — opaque to the SDK. The integrator's callbacks receive
  * whatever they return from `getDb` so they can use it directly.
@@ -41,6 +42,24 @@ export interface AgentTurnPayload {
      * token to redeem, or that they declined (ADR-0228 §2.2.5).
      */
     approval?: ApprovalContinuation;
+    /**
+     * The turns of this conversation that this turn supersedes (ADR-0252 §2.5):
+     * the host asked each to stop when this turn's message arrived. The host's
+     * `getHistory` is given them, to wait until each is stored before it reads.
+     */
+    supersedes?: string[];
+}
+/** What `getHistory` is told of the turn it reads for. */
+export interface HistoryRequest {
+    turnId: string;
+    /** The turns this one supersedes, which must be stored (or given up on) before history is read. */
+    supersedes: readonly string[];
+    /**
+     * Aborts when this turn is itself asked to stop while it waits: a wait for
+     * earlier turns should end then, since the turn will store only that it was
+     * stopped and reads no history.
+     */
+    signal: AbortSignal;
 }
 /**
  * Configuration for the agent runtime, whichever adapter hosts it.
@@ -151,6 +170,14 @@ export interface AgentRuntimeConfig<TDb = IntegratorDb> {
         channel?: UIActionChannel;
         /** How long a UI tool waits for the client's answer. Default 20 s. */
         resultTimeoutMs?: number;
+        /**
+         * The longest a UI tool waits, in the call, for the outcome of work its
+         * action started (a GPU job, an export). Work that ends within it is
+         * reported done; work that does not is reported still running, and the
+         * turn ends: its outcome is in the page state the next turn reads.
+         * Default 20 s (`DEFAULT_JOB_WAIT_MS`).
+         */
+        jobWaitMs?: number;
         /** Largest page-state payload given to the model, in characters. Default 12000 (`DEFAULT_PAGE_STATE_CHARS`). */
         maxObservationChars?: number;
         /** Longest the page's index is in the model's context, in characters, before its furthest surfaces are listed by action id only. Default 60000 (`DEFAULT_INDEX_CHARS`, ADR-0245). */
@@ -163,6 +190,15 @@ export interface AgentRuntimeConfig<TDb = IntegratorDb> {
     approvals?: {
         store?: ApprovalStoreClient;
     };
+    /**
+     * Stopping a turn (ADR-0252). The stop request is kept by the realtime
+     * server, and the turn asks for it there unless `client` says otherwise.
+     */
+    stops?: {
+        client?: TurnStopClient;
+        /** How long after a stop an answer already on its way is still waited for. Default 2 s. */
+        graceMs?: number;
+    };
     /**
      * Returns a database client/handle. Called once per invocation.
      * The returned value is passed to `getHistory` and `persistMessages`.
@@ -176,10 +212,17 @@ export interface AgentRuntimeConfig<TDb = IntegratorDb> {
      *
      * The SDK handles appending the current user message — don't include it.
      */
-    getHistory: (conversationId: string, db: TDb) => Promise<TurnHistoryMessage[]>;
+    getHistory: (conversationId: string, db: TDb, turn: HistoryRequest) => Promise<TurnHistoryMessage[]>;
     /**
-     * Persists the new messages generated during this turn.
-     * Called after the turn completes successfully.
+     * Persists the new messages generated during this turn. Called once, before
+     * the client is told the turn ended, whether it ended by itself or was
+     * stopped (`stopped` is then set, and the last assistant message carries the
+     * same marker: ADR-0252 §2.3).
+     *
+     * A host that lets a newer turn give up on this one (ADR-0252 §2.5) answers
+     * `{ stored: false }` when it found the turn already given up on and stored
+     * nothing. The turn is still announced, and nothing that depends on its
+     * messages being stored (an expired approval's confirmation) is done.
      */
     persistMessages: (input: {
         turnId: string;
@@ -190,11 +233,20 @@ export interface AgentRuntimeConfig<TDb = IntegratorDb> {
             completionTokens: number;
             totalTokens: number;
         };
+        stopped?: TurnStoppedMarker;
         db: TDb;
-    }) => Promise<void>;
+    }) => Promise<void | {
+        stored: false;
+    }>;
     /**
      * Optional: record turn start in your database. Receives the db handle.
      * Default: no-op (the SDK still emits `agent:turn_started` to realtime).
+     *
+     * A host that keeps a row per turn claims it here. Answering
+     * `{ run: false, reason }` says the turn must not run: its row shows it
+     * already ended or was given up on, which is what a queue's redelivery of
+     * an old turn finds (ADR-0252 §2.5). The turn then does nothing: no model
+     * call, no UI action, no event to the client.
      */
     recordTurnStart?: (input: {
         turnId: string;
@@ -203,7 +255,10 @@ export interface AgentRuntimeConfig<TDb = IntegratorDb> {
         accountId: string;
         model: string;
         db: TDb;
-    }) => Promise<void>;
+    }) => Promise<void | {
+        run: false;
+        reason: string;
+    }>;
     /**
      * Optional: record turn completion. Default: no-op.
      */
@@ -216,6 +271,8 @@ export interface AgentRuntimeConfig<TDb = IntegratorDb> {
             completionTokens: number;
             totalTokens: number;
         };
+        /** Set when the turn was stopped rather than ending by itself (ADR-0252). */
+        stopReason?: TurnStopReason;
         db: TDb;
     }) => Promise<void>;
     /**

package/dist/runtime/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACnG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC;AAEnC;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,mGAAmG;IACnG,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB,CAAC,GAAG,GAAG,YAAY;IACpD;;;;;;;;;;OAUG;IACH,KAAK,EACD,cAAc,EAAE,GAChB,CAAC,CAAC,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,cAAc,EAAE,CAAC,GAAG,cAAc,EAAE,CAAC,CAAC;IAEnH;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;IAE7B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,eAAe,CAAC;IAE5G;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAE7B;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;KAAE,KAAK,MAAM,CAAC;IAIpH,+EAA+E;IAC/E,KAAK,EAAE,aAAa,CAAC;IAErB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,eAAe,CAAC;IAExC,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,+FAA+F;IAC/F,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB;;;;OAIG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IAIxB;;;;OAIG;IACH,QAAQ,EAAE;QACR,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IAEF;;;;OAIG;IACH,SAAS,CAAC,EAAE;QACV,OAAO,CAAC,EAAE,eAAe,CAAC;QAC1B,sEAAsE;QACtE,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB;;;;;;WAMG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,gHAAgH;QAChH,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,qLAAqL;QACrL,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IAEF;;;OAGG;IACH,SAAS,CAAC,EAAE;QACV,KAAK,CAAC,EAAE,mBAAmB,CAAC;KAC7B,CAAC;IAEF;;;OAGG;IACH,KAAK,CAAC,EAAE;QACN,MAAM,CAAC,EAAE,cAAc,CAAC;QACxB,2FAA2F;QAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAIF;;;;;OAKG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAE1B;;;;;OAKG;IACH,UAAU,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAErG;;;;;;;;;;OAUG;IACH,eAAe,EAAE,CAAC,KAAK,EAAE;QACvB,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,WAAW,EAAE,CAAC;QACxB,KAAK,EAAE;YAAE,YAAY,EAAE,MAAM,CAAC;YAAC,gBAAgB,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC;QAC/E,OAAO,CAAC,EAAE,iBAAiB,CAAC;QAC5B,EAAE,EAAE,GAAG,CAAC;KACT,KAAK,OAAO,CAAC,IAAI,GAAG;QAAE,MAAM,EAAE,KAAK,CAAA;KAAE,CAAC,CAAC;IAExC;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,EAAE,MAAM,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,EAAE,EAAE,GAAG,CAAC;KACT,KAAK,OAAO,CAAC,IAAI,GAAG;QAAE,GAAG,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAErD;;OAEG;IACH,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE;QAC3B,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,EAAE,MAAM,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE;YAAE,YAAY,EAAE,MAAM,CAAC;YAAC,gBAAgB,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC;QAC/E,6EAA6E;QAC7E,UAAU,CAAC,EAAE,cAAc,CAAC;QAC5B,EAAE,EAAE,GAAG,CAAC;KACT,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpB;;OAEG;IACH,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE;QAC1B,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,EAAE,MAAM,CAAC;QACvB,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,OAAO,CAAA;SAAE,CAAC;QAC/D,EAAE,EAAE,GAAG,CAAC;KACT,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE;QACP,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;QAC5D,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;QAC5D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;QAC7D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;KAC9D,CAAC;CACH;AAED,oEAAoE;AACpE,MAAM,MAAM,iBAAiB,CAAC,GAAG,GAAG,YAAY,IAAI,kBAAkB,CAAC,GAAG,CAAC,CAAC"}

package/dist/stop/partial.d.ts

@@ -0,0 +1,49 @@
+/**
+ * What a stopped turn stores (ADR-0252 §2.3): the steps it finished, the step
+ * it was in, and a marker on its last assistant message.
+ *
+ * It is built from what the worker itself recorded as the turn ran: the text
+ * it streamed, the steps it saw end, and the calls its tools were asked to
+ * run. Nothing here reads the model stream's own results, which do not
+ * survive an abort, so it is the same whatever way the abort surfaces.
+ */
+import { type TurnStoppedMarker } from '@ouispec/agent-core';
+import type { TurnMessage } from '../types.js';
+/** A step the turn saw end: its text, and the calls the model made in it. */
+export interface RecordedStep {
+    text: string;
+    toolCalls: ReadonlyArray<{
+        toolCallId: string;
+        toolName: string;
+        input: unknown;
+    }>;
+}
+/** A call a tool of the turn was asked to run, in the order the calls arrived. */
+export interface RecordedCall {
+    toolCallId: string;
+    /** The tool as the model called it (`ui_act` for a page action). */
+    toolName: string;
+    input: unknown;
+    /** Its result as the model would read it; null while it has not settled. */
+    text: string | null;
+}
+/**
+ * The stopped turn's messages, each call with exactly one result:
+ * - a call that settled keeps the result it gave, which for a call the stop
+ *   cut short already says so (not run, or sent with its outcome unknown);
+ * - a call still unsettled when the grace ended is stored as running when the
+ *   turn was stopped, its outcome unknown.
+ *
+ * The last assistant message carries the marker. A turn that produced no
+ * text and no call still stores one assistant message, whose text is the
+ * marker's line: a model provider refuses an empty text block, and the
+ * conversation never holds two user messages with nothing between them.
+ */
+export declare function stoppedTurnMessages(recorded: {
+    steps: readonly RecordedStep[];
+    calls: readonly RecordedCall[];
+    /** Every piece of reply text the turn streamed, in order. */
+    streamedText: string;
+    marker: TurnStoppedMarker;
+}): TurnMessage[];
+//# sourceMappingURL=partial.d.ts.map

package/dist/stop/partial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"partial.d.ts","sourceRoot":"","sources":["../../src/stop/partial.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,aAAa,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACpF;AAED,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,4EAA4E;IAC5E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE;IAC5C,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,iBAAiB,CAAC;CAC3B,GAAG,WAAW,EAAE,CAgDhB"}

package/dist/stop/partial.js

@@ -0,0 +1,73 @@
+/**
+ * What a stopped turn stores (ADR-0252 §2.3): the steps it finished, the step
+ * it was in, and a marker on its last assistant message.
+ *
+ * It is built from what the worker itself recorded as the turn ran: the text
+ * it streamed, the steps it saw end, and the calls its tools were asked to
+ * run. Nothing here reads the model stream's own results, which do not
+ * survive an abort, so it is the same whatever way the abort surfaces.
+ */
+import { turnStoppedNote } from '@ouispec/agent-core';
+import { resultText, stoppedWhileRunning } from './results.js';
+const asArguments = (input) => input && typeof input === 'object' && !Array.isArray(input) ? input : {};
+/**
+ * The stopped turn's messages, each call with exactly one result:
+ * - a call that settled keeps the result it gave, which for a call the stop
+ *   cut short already says so (not run, or sent with its outcome unknown);
+ * - a call still unsettled when the grace ended is stored as running when the
+ *   turn was stopped, its outcome unknown.
+ *
+ * The last assistant message carries the marker. A turn that produced no
+ * text and no call still stores one assistant message, whose text is the
+ * marker's line: a model provider refuses an empty text block, and the
+ * conversation never holds two user messages with nothing between them.
+ */
+export function stoppedTurnMessages(recorded) {
+    const { steps, calls, streamedText, marker } = recorded;
+    const byId = new Map(calls.map((call) => [call.toolCallId, call]));
+    const messages = [];
+    const push = (text, stepCalls) => {
+        // Whitespace alone is no text: a provider refuses that block too.
+        const content = text.trim() ? text : null;
+        if (content === null && stepCalls.length === 0)
+            return;
+        messages.push({
+            role: 'assistant',
+            content,
+            ...(stepCalls.length > 0
+                ? { toolCalls: stepCalls.map((c) => ({ id: c.toolCallId, name: c.toolName, arguments: asArguments(c.input) })) }
+                : {}),
+        });
+        for (const call of stepCalls) {
+            messages.push({
+                role: 'tool',
+                content: byId.get(call.toolCallId)?.text ?? resultText(stoppedWhileRunning(call.toolName)),
+                toolCallId: call.toolCallId,
+                name: call.toolName,
+            });
+        }
+    };
+    const finished = new Set();
+    let finishedText = 0;
+    for (const step of steps) {
+        push(step.text, step.toolCalls);
+        finishedText += step.text.length;
+        for (const call of step.toolCalls)
+            finished.add(call.toolCallId);
+    }
+    // The step the turn was in: the text streamed since the last step ended, and
+    // the calls no finished step holds.
+    push(streamedText.length > finishedText ? streamedText.slice(finishedText) : '', calls.filter((call) => !finished.has(call.toolCallId)));
+    let last;
+    for (let i = messages.length - 1; i >= 0 && !last; i--)
+        if (messages[i].role === 'assistant')
+            last = messages[i];
+    if (!last) {
+        messages.push({ role: 'assistant', content: turnStoppedNote(marker), stopped: marker });
+    }
+    else {
+        last.stopped = marker;
+    }
+    return messages;
+}
+//# sourceMappingURL=partial.js.map

package/dist/stop/partial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"partial.js","sourceRoot":"","sources":["../../src/stop/partial.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,eAAe,EAA0B,MAAM,qBAAqB,CAAC;AAE9E,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAkB/D,MAAM,WAAW,GAAG,CAAC,KAAc,EAA2B,EAAE,CAC9D,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAiC,CAAC,CAAC,CAAC,EAAE,CAAC;AAExG;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAMnC;IACC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;IACxD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IACnE,MAAM,QAAQ,GAAkB,EAAE,CAAC;IAEnC,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,SAAkF,EAAE,EAAE;QAChH,kEAAkE;QAClE,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QAC1C,IAAI,OAAO,KAAK,IAAI,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACvD,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,WAAW;YACjB,OAAO;YACP,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;gBACtB,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE;gBAChH,CAAC,CAAC,EAAE,CAAC;SACR,CAAC,CAAC;QACH,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YAC7B,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,IAAI,IAAI,UAAU,CAAC,mBAAmB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAC1F,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,IAAI,EAAE,IAAI,CAAC,QAAQ;aACpB,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAChC,YAAY,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QACjC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS;YAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACnE,CAAC;IACD,6EAA6E;IAC7E,oCAAoC;IACpC,IAAI,CACF,YAAY,CAAC,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,EAC1E,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CACvD,CAAC;IAEF,IAAI,IAA6B,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE;QAAE,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW;YAAE,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACjH,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,eAAe,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1F,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/stop/results.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What a call's result says when its turn was stopped before the call ended
+ * (ADR-0252 §2.2). Every call the model made keeps exactly one result, so the
+ * stored conversation is one a model accepts, and a later turn reads what
+ * became of each call instead of guessing.
+ */
+import type { ToolExecutionResult } from '../tools/types.js';
+/** The call never left the worker: nothing ran. */
+export declare function stoppedNotRun(what: string): ToolExecutionResult;
+/** The request went out, tabs answered that they got it, and none took it: it did not run. */
+export declare function stoppedNotTaken(what: string): ToolExecutionResult;
+/** The call was sent to the page and no answer came back before the turn ended. */
+export declare function stoppedOutcomeUnknown(what: string): ToolExecutionResult;
+/** A tool was running when the turn was stopped, and did not finish in time to say what it did. */
+export declare function stoppedWhileRunning(what: string): ToolExecutionResult;
+/** A read of the page that the stop cut short: nothing was changed, and nothing was learned. */
+export declare function stoppedBeforeAnswer(what: string): ToolExecutionResult;
+/** The text of a result, as a stored tool message carries it. */
+export declare function resultText(result: ToolExecutionResult): string;
+//# sourceMappingURL=results.d.ts.map

package/dist/stop/results.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../src/stop/results.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,mDAAmD;AACnD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAM/D;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAMjE;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAQvE;AAED,mGAAmG;AACnG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAMrE;AAED,gGAAgG;AAChG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAMrE;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAE9D"}

package/dist/stop/results.js

@@ -0,0 +1,46 @@
+/** The call never left the worker: nothing ran. */
+export function stoppedNotRun(what) {
+    return {
+        success: false,
+        error: `Not run: the turn was stopped before "${what}" was sent. Nothing was changed by it.`,
+        data: { stopped: true, notRun: true },
+    };
+}
+/** The request went out, tabs answered that they got it, and none took it: it did not run. */
+export function stoppedNotTaken(what) {
+    return {
+        success: false,
+        error: `Not run: "${what}" was sent, and no open page took it before the turn was stopped. Nothing was changed by it.`,
+        data: { stopped: true, notRun: true },
+    };
+}
+/** The call was sent to the page and no answer came back before the turn ended. */
+export function stoppedOutcomeUnknown(what) {
+    return {
+        success: false,
+        error: `"${what}" was sent to the page, and the turn was stopped before its answer arrived. It may have run: ` +
+            'its outcome is unknown. Read what the page shows before doing anything that depends on it.',
+        data: { stopped: true, sent: true, outcome: 'unknown' },
+    };
+}
+/** A tool was running when the turn was stopped, and did not finish in time to say what it did. */
+export function stoppedWhileRunning(what) {
+    return {
+        success: false,
+        error: `"${what}" was running when the turn was stopped. It did not finish in time to report: its outcome is unknown.`,
+        data: { stopped: true, sent: true, outcome: 'unknown' },
+    };
+}
+/** A read of the page that the stop cut short: nothing was changed, and nothing was learned. */
+export function stoppedBeforeAnswer(what) {
+    return {
+        success: false,
+        error: `The turn was stopped before ${what} was answered. Nothing was changed.`,
+        data: { stopped: true, notRun: true },
+    };
+}
+/** The text of a result, as a stored tool message carries it. */
+export function resultText(result) {
+    return JSON.stringify({ success: false, error: result.error, ...result.data });
+}
+//# sourceMappingURL=results.js.map

package/dist/stop/results.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.js","sourceRoot":"","sources":["../../src/stop/results.ts"],"names":[],"mappings":"AAQA,mDAAmD;AACnD,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,yCAAyC,IAAI,wCAAwC;QAC5F,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;KACtC,CAAC;AACJ,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,aAAa,IAAI,8FAA8F;QACtH,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;KACtC,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EACH,IAAI,IAAI,+FAA+F;YACvG,4FAA4F;QAC9F,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE;KACxD,CAAC;AACJ,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,IAAI,IAAI,uGAAuG;QACtH,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE;KACxD,CAAC;AACJ,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,+BAA+B,IAAI,qCAAqC;QAC/E,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;KACtC,CAAC;AACJ,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,UAAU,CAAC,MAA2B;IACpD,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,GAAI,MAAM,CAAC,IAAgC,EAAE,CAAC,CAAC;AAC9G,CAAC"}

package/dist/stop/turn-stop.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Hearing that a turn has been asked to stop (ADR-0252 §2.1).
+ *
+ * The worker has no socket. The realtime server keeps a stop request (the
+ * person's Stop, or the host's when a newer message supersedes the turn), and
+ * the worker asks for it for as long as the turn runs, as it asks for UI
+ * answers and approvals.
+ */
+import type { TurnStopReason, TurnStopRecord } from '@ouispec/agent-core';
+/**
+ * Why a turn's work was aborted, as its abort signal's reason. The stop path
+ * is written against this type, so another cause that should also keep what
+ * the turn produced (its deadline) is one more value of `cause`.
+ */
+export declare class TurnStopped extends Error {
+    readonly reason: TurnStopReason;
+    /** When it was asked for, epoch ms. */
+    readonly at: number;
+    readonly cause: "stopped";
+    constructor(reason: TurnStopReason, 
+    /** When it was asked for, epoch ms. */
+    at: number);
+}
+/** The stop a signal was aborted with, or null when it was not aborted, or was for another cause. */
+export declare function stopOf(signal: AbortSignal | undefined): TurnStopped | null;
+/**
+ * What a tool is told of a stop: set on its context for the whole turn, and
+ * answering null until the turn is asked to stop. A tool that was waiting on
+ * something it sent uses `graceSignal`, never the turn's aborted signal, for
+ * the one last look it takes.
+ */
+export interface TurnStopState {
+    /** Why the turn was stopped, or null while it has not been. */
+    reason(): TurnStopReason | null;
+    /** Aborts when the grace after a stop is over. A fresh signal: the turn's own is already aborted. */
+    graceSignal(): AbortSignal;
+    /** How long after a stop an answer already on its way is still waited for. */
+    graceMs: number;
+}
+/** How long after a stop an answer already on its way is still waited for (ADR-0252 §2.2). */
+export declare const DEFAULT_STOP_GRACE_MS = 2000;
+export interface TurnStopClient {
+    /**
+     * The stop asked for on `turnId` by `userId`, waiting for one until `signal`
+     * aborts. Resolves null when the signal aborts first. Never rejects: a
+     * failure to ask is retried, since the request is kept and is heard late
+     * rather than lost.
+     *
+     * The first question is asked without waiting, and `onChecked` is called
+     * once it is answered, whatever the answer, or has failed: from then a stop
+     * that was asked for before the watch began has been heard.
+     */
+    watch(turnId: string, userId: string, signal: AbortSignal, onChecked?: () => void): Promise<TurnStopRecord | null>;
+}
+export interface HttpTurnStopClientConfig {
+    /** The realtime server's base URL. */
+    url: string;
+    /** Its internal key. */
+    apiKey: string;
+    /** Longest single wait the realtime server is asked to hold open. Default 25 s. */
+    maxPollMs?: number;
+    /** The longest pause between attempts while the server cannot be reached. Default 5 s. */
+    maxBackoffMs?: number;
+    /** Where a failed attempt is reported. */
+    onError?: (error: unknown, attempt: number) => void;
+    /**
+     * Called once when the server answers that it has no such route (404): a
+     * realtime server from before stops were kept. The watch then ends, since
+     * asking again cannot help; the turn runs on and cannot be stopped.
+     */
+    onUnsupported?: () => void;
+}
+/** The longest a turn waits for the answer to its first question before it starts anyway. */
+export declare const FIRST_CHECK_LIMIT_MS = 1500;
+/**
+ * The stop record over the realtime server's internal HTTP API:
+ * `GET {url}/internal/turns/{turnId}/stop?userId=&waitMs=` (200 with the
+ * record, 204 when none was asked for in `waitMs`).
+ *
+ * It fails open. A failure (the server restarting, a 5xx) is retried with a
+ * growing pause, and the turn runs on meanwhile: a turn must never fail
+ * because it could not ask whether to stop. A 404 is not a failure to retry:
+ * it is a server that keeps no stops, said once, and the watch ends.
+ */
+export declare function createHttpTurnStopClient(config: HttpTurnStopClientConfig): TurnStopClient;
+/**
+ * One turn's watch for a stop: open from before the turn reads its history
+ * until the turn ends, so a stop asked for while the turn waited in a queue
+ * is the first thing it hears.
+ */
+export interface TurnStopWatch {
+    /** The stop, once one has been heard; null until then. */
+    current(): TurnStopRecord | null;
+    /**
+     * Resolves once the watch has asked its first question and has the answer:
+     * a stop asked for before the turn started (while it waited in a queue) has
+     * been heard by then. It also resolves if the question failed, or took
+     * longer than `FIRST_CHECK_LIMIT_MS`: a turn is never held up, or failed,
+     * by not being able to ask.
+     */
+    checked(): Promise<void>;
+    /**
+     * Calls `listener` when a stop is heard, at once if one already was. At most
+     * once, and never after `close`.
+     */
+    onStop(listener: (record: TurnStopRecord) => void): void;
+    /**
+     * Stop watching, and ignore a stop that is heard from now on: the turn has
+     * begun its own end, and a stop that lands now is not one (ADR-0252 §2.4).
+     */
+    close(): void;
+}
+export declare function watchTurnStop(client: TurnStopClient | undefined, turnId: string, userId: string): TurnStopWatch;
+//# sourceMappingURL=turn-stop.d.ts.map

package/dist/stop/turn-stop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-stop.d.ts","sourceRoot":"","sources":["../../src/stop/turn-stop.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1E;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAGlC,QAAQ,CAAC,MAAM,EAAE,cAAc;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM;IAJrB,QAAQ,CAAC,KAAK,EAAG,SAAS,CAAU;gBAEzB,MAAM,EAAE,cAAc;IAC/B,uCAAuC;IAC9B,EAAE,EAAE,MAAM;CAKtB;AAED,qGAAqG;AACrG,wBAAgB,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,IAAI,CAE1E;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,MAAM,IAAI,cAAc,GAAG,IAAI,CAAC;IAChC,qGAAqG;IACrG,WAAW,IAAI,WAAW,CAAC;IAC3B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8FAA8F;AAC9F,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;OASG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CACpH;AAED,MAAM,WAAW,wBAAwB;IACvC,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;CAC5B;AAGD,6FAA6F;AAC7F,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAI1C;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,wBAAwB,GAAG,cAAc,CAsDzF;AAcD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,OAAO,IAAI,cAAc,GAAG,IAAI,CAAC;IACjC;;;;;;OAMG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,GAAG,IAAI,CAAC;IACzD;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CA6C/G"}

package/dist/stop/turn-stop.js

@@ -0,0 +1,155 @@
+import { requireRealtime } from '../emit/http-adapter.js';
+/**
+ * Why a turn's work was aborted, as its abort signal's reason. The stop path
+ * is written against this type, so another cause that should also keep what
+ * the turn produced (its deadline) is one more value of `cause`.
+ */
+export class TurnStopped extends Error {
+    reason;
+    at;
+    cause = 'stopped';
+    constructor(reason, 
+    /** When it was asked for, epoch ms. */
+    at) {
+        super(reason === 'superseded' ? 'The turn was superseded by a newer message' : 'The turn was stopped by the person');
+        this.reason = reason;
+        this.at = at;
+        this.name = 'TurnStopped';
+    }
+}
+/** The stop a signal was aborted with, or null when it was not aborted, or was for another cause. */
+export function stopOf(signal) {
+    return signal?.aborted && signal.reason instanceof TurnStopped ? signal.reason : null;
+}
+/** How long after a stop an answer already on its way is still waited for (ADR-0252 §2.2). */
+export const DEFAULT_STOP_GRACE_MS = 2_000;
+const FIRST_BACKOFF_MS = 250;
+/** The longest a turn waits for the answer to its first question before it starts anyway. */
+export const FIRST_CHECK_LIMIT_MS = 1_500;
+/** A "not yet" sooner than this was not a held request. */
+const UNHELD_ANSWER_MS = 50;
+/**
+ * The stop record over the realtime server's internal HTTP API:
+ * `GET {url}/internal/turns/{turnId}/stop?userId=&waitMs=` (200 with the
+ * record, 204 when none was asked for in `waitMs`).
+ *
+ * It fails open. A failure (the server restarting, a 5xx) is retried with a
+ * growing pause, and the turn runs on meanwhile: a turn must never fail
+ * because it could not ask whether to stop. A 404 is not a failure to retry:
+ * it is a server that keeps no stops, said once, and the watch ends.
+ */
+export function createHttpTurnStopClient(config) {
+    const { url, apiKey } = config;
+    requireRealtime(url, apiKey);
+    const maxPollMs = config.maxPollMs ?? 25_000;
+    const maxBackoffMs = config.maxBackoffMs ?? 5_000;
+    return {
+        async watch(turnId, userId, signal, onChecked) {
+            let backoff = FIRST_BACKOFF_MS;
+            let attempt = 0;
+            let checked = false;
+            const firstAnswered = () => {
+                if (checked)
+                    return;
+                checked = true;
+                onChecked?.();
+            };
+            while (!signal.aborted) {
+                attempt++;
+                const asked = Date.now();
+                // The first question does not wait: is there a stop already?
+                const waitMs = checked ? maxPollMs : 0;
+                try {
+                    const query = new URLSearchParams({ userId, waitMs: String(waitMs) });
+                    const res = await fetch(`${url}/internal/turns/${encodeURIComponent(turnId)}/stop?${query}`, {
+                        headers: { 'X-Api-Key': apiKey },
+                        signal: AbortSignal.any([signal, AbortSignal.timeout(waitMs + 5_000)]),
+                    });
+                    if (res.status === 200)
+                        return (await res.json());
+                    if (res.status === 204) {
+                        backoff = FIRST_BACKOFF_MS;
+                        // A server that answers "not yet" at once to a question that asked it to wait is not
+                        // holding the request open: asked again without a pause, this would spin.
+                        if (waitMs > 0 && Date.now() - asked < UNHELD_ANSWER_MS)
+                            await pause(FIRST_BACKOFF_MS, signal);
+                        firstAnswered();
+                        continue;
+                    }
+                    if (res.status === 404) {
+                        // A realtime server from before stops were kept: there is nothing to wait for.
+                        firstAnswered();
+                        config.onUnsupported?.();
+                        return null;
+                    }
+                    throw new Error(`HTTP ${res.status}`);
+                }
+                catch (err) {
+                    firstAnswered();
+                    if (signal.aborted)
+                        return null;
+                    config.onError?.(err, attempt);
+                    await pause(backoff, signal);
+                    backoff = Math.min(backoff * 2, maxBackoffMs);
+                }
+            }
+            return null;
+        },
+    };
+}
+function pause(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', done);
+            resolve();
+        }
+        signal.addEventListener('abort', done, { once: true });
+    });
+}
+export function watchTurnStop(client, turnId, userId) {
+    const controller = new AbortController();
+    let heard = null;
+    let closed = false;
+    let listener = null;
+    let markChecked;
+    const firstCheck = new Promise((resolve) => {
+        markChecked = resolve;
+    });
+    if (client) {
+        const limit = setTimeout(markChecked, FIRST_CHECK_LIMIT_MS);
+        void firstCheck.then(() => clearTimeout(limit));
+        void client.watch(turnId, userId, controller.signal, markChecked).then((record) => {
+            if (record && !closed) {
+                heard = record;
+                listener?.(record);
+            }
+            markChecked();
+        }, () => {
+            // `watch` does not reject; a client that does is treated as hearing nothing.
+            markChecked();
+        });
+    }
+    else {
+        markChecked();
+    }
+    return {
+        current: () => (closed ? null : heard),
+        checked: () => firstCheck,
+        onStop(next) {
+            if (closed)
+                return;
+            listener = next;
+            if (heard)
+                next(heard);
+        },
+        close() {
+            closed = true;
+            listener = null;
+            controller.abort();
+            markChecked();
+        },
+    };
+}
+//# sourceMappingURL=turn-stop.js.map

package/dist/stop/turn-stop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-stop.js","sourceRoot":"","sources":["../../src/stop/turn-stop.ts"],"names":[],"mappings":"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"}