@ouispec/agent-worker 0.4.0 → 0.8.0

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 { TurnStoppedReason, 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: TurnStoppedReason;
+    /** When it was asked for, or the deadline passed: epoch ms. */
+    readonly at: number;
+    readonly cause: "stopped";
+    constructor(reason: TurnStoppedReason, 
+    /** When it was asked for, or the deadline passed: 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(): TurnStoppedReason | 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,iBAAiB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG7E;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAGlC,QAAQ,CAAC,MAAM,EAAE,iBAAiB;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM;IAJrB,QAAQ,CAAC,KAAK,EAAG,SAAS,CAAU;gBAEzB,MAAM,EAAE,iBAAiB;IAClC,+DAA+D;IACtD,EAAE,EAAE,MAAM;CAWtB;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,iBAAiB,GAAG,IAAI,CAAC;IACnC,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,159 @@
+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, or the deadline passed: epoch ms. */
+    at) {
+        super(reason === 'superseded'
+            ? 'The turn was superseded by a newer message'
+            : reason === 'deadline'
+                ? 'The turn ran out of time'
+                : '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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"}

package/dist/tools/input-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"input-validation.d.ts","sourceRoot":"","sources":["../../src/tools/input-validation.ts"],"names":[],"mappings":"AA+BA,MAAM,MAAM,mBAAmB,GAC3B;IACE,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEpC,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,mBAAmB,CAAC;AA6DzE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC/C,kBAAkB,CAiCpB"}
+{"version":3,"file":"input-validation.d.ts","sourceRoot":"","sources":["../../src/tools/input-validation.ts"],"names":[],"mappings":"AAgCA,MAAM,MAAM,mBAAmB,GAC3B;IACE,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEpC,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,mBAAmB,CAAC;AA+DzE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC/C,kBAAkB,CAiCpB"}

package/dist/tools/input-validation.js

@@ -11,6 +11,7 @@
  * properties says so with `additionalProperties: false`, as the schema loader and the
  * entity tool generator now do.
  */
+import { ATTACHMENT_ID_PATTERN, OUI_ATTACHMENT_FORMAT } from 'oui-spec/spec';
 import { Ajv } from 'ajv';
 import formatsPlugin from 'ajv-formats';
 // ajv-formats is CommonJS; under ESM interop its function is on `default`.
@@ -26,6 +27,8 @@ const addFormats = formatsPlugin.default ??
 const NON_VALIDATION_KEYS = ['sideEffects', '$schema', '$id'];
 const ajv = new Ajv({ allErrors: true, strict: false, useDefaults: false, coerceTypes: false });
 addFormats(ajv);
+// An input that takes a file the person attached is given the file's id (OUI spec §7.3.11).
+ajv.addFormat(OUI_ATTACHMENT_FORMAT, ATTACHMENT_ID_PATTERN);
 function describeError(error) {
     const at = error.instancePath || '(input)';
     const params = error.params;

package/dist/tools/input-validation.js.map

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

package/dist/tools/types.d.ts

@@ -1,3 +1,4 @@
+import type { TurnStopState } from '../stop/turn-stop.js';
 import type { ActionRequestApproval, AgentApiSurface } from '@ouispec/agent-core';
 import type { EffectOrKind } from '@ouispec/bindings';
 import type { UISlot } from '../ui/ui-sequence.js';
@@ -18,6 +19,12 @@ export interface RegisteredTool {
      * side-effect quota. Default `backend`.
      */
     kind?: 'ui' | 'backend';
+    /**
+     * The SDK's class for a tool it owns (ADR-0252 §2.12): `attachment` for the
+     * attachment tools. A host's tool policy may admit a class as well as a name,
+     * so a tool the SDK adds later in that class needs no change in the host.
+     */
+    toolClass?: 'attachment';
     /**
      * What calling the tool changes (ADR-0226 §2.6). A tool that declares none is
      * treated as a write. Approvals key on this and `destructive` (ADR-0228).
@@ -75,6 +82,12 @@ export interface ToolExecutionContext {
      * the grant from the user's own click.
      */
     approval?: ActionRequestApproval;
+    /**
+     * Whether the turn has been asked to stop (ADR-0252). A tool that waits on
+     * something it sent reads it when `abortSignal` aborts, to say what became
+     * of the call: not run, or sent with its outcome unknown.
+     */
+    stop?: TurnStopState;
     [key: string]: unknown;
 }
 export interface ToolExecutionResult {
@@ -90,6 +103,12 @@ export interface ToolExecutionResult {
         mediaType: string;
         base64: string;
     };
+    /**
+     * Text the model is given beside the result's text, as a text part of the
+     * tool result: a file's text, which is the model's for this call only. Like
+     * `image`, it is in no event, record or stored message: `data` says what it is.
+     */
+    modelText?: string;
 }
 export interface ToolRegistry {
     tools: RegisteredTool[];

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;GAGG;AAEH;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,YAAY,CAAC;AAEtC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,yEAAyE;IACzE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrF,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrG,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,0FAA0F;IAC1F,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAChH;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,YAAY,CAiBxE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;GAGG;AAEH;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,YAAY,CAAC;AAEtC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,yEAAyE;IACzE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrF,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrG,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,0FAA0F;IAC1F,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC;;;;OAIG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAChH;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,YAAY,CAiBxE"}

package/dist/tools/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAqGA;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAuB;IACxD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAErD,OAAO;QACL,KAAK;QACL,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,KAA8B,EAAE,GAAyB;YACnF,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,IAAI,EAAE,EAAE,CAAC;YAC5D,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACxC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YACrF,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAwHA;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAuB;IACxD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAErD,OAAO;QACL,KAAK;QACL,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,KAA8B,EAAE,GAAyB;YACnF,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,IAAI,EAAE,EAAE,CAAC;YAC5D,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACxC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YACrF,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/turn-policy.d.ts

@@ -9,6 +9,18 @@
  *   1. classifyTurn — called once at turn start to classify the user's intent
  *   2. prepareStep  — called before each LLM step to control tool selection
  */
+/**
+ * A tool the model can be given at a step, as a policy sees it: its name, what
+ * kind of tool it is, and its class when it has one (the SDK's attachment
+ * tools are `attachment`). A policy that picks a step's active tools by name
+ * can keep a whole class, such as the attachment tools, by this.
+ */
+export interface StepTool {
+    name: string;
+    /** `ui`: a page action, or a UI tool (`ui_act`, `ui_describe`, `ui_read`). `backend`: the host's or the SDK's own. `builtin`: the worker's. */
+    kind: 'ui' | 'backend' | 'builtin';
+    toolClass?: string;
+}
 export interface TurnPolicy {
     /**
      * Classify the current turn to determine orchestration behavior.
@@ -31,6 +43,8 @@ export interface TurnPolicy {
         }>;
         turnClass: string;
         allToolNames: string[];
+        /** The same tools with their kind and class, in the same order. */
+        allTools: StepTool[];
     }): Promise<{
         toolChoice?: 'auto' | 'none' | 'required' | {
             type: 'tool';

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

@@ -1 +1 @@
-{"version":3,"file":"turn-policy.d.ts","sourceRoot":"","sources":["../src/turn-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,YAAY,CACV,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GACjD,MAAM,CAAC;IAEV;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE;QACf,KAAK,EAAE,KAAK,CAAC;YAAE,SAAS,CAAC,EAAE,KAAK,CAAC;gBAAE,QAAQ,EAAE,MAAM,CAAA;aAAE,CAAC,CAAA;SAAE,CAAC,CAAC;QAC1D,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,EAAE,CAAC;KACxB,GAAG,OAAO,CAAC;QACV,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAC;QAC/E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB;;;;;WAKG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;IAEH;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE;QACvB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE;YAAE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;SAAE,CAAC;QAC9E,UAAU,EAAE,MAAM,CAAC;KACpB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,UAG/B,CAAC"}
+{"version":3,"file":"turn-policy.d.ts","sourceRoot":"","sources":["../src/turn-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,+IAA+I;IAC/I,IAAI,EAAE,IAAI,GAAG,SAAS,GAAG,SAAS,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,YAAY,CACV,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GACjD,MAAM,CAAC;IAEV;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE;QACf,KAAK,EAAE,KAAK,CAAC;YAAE,SAAS,CAAC,EAAE,KAAK,CAAC;gBAAE,QAAQ,EAAE,MAAM,CAAA;aAAE,CAAC,CAAA;SAAE,CAAC,CAAC;QAC1D,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,mEAAmE;QACnE,QAAQ,EAAE,QAAQ,EAAE,CAAC;KACtB,GAAG,OAAO,CAAC;QACV,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAC;QAC/E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB;;;;;WAKG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;IAEH;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE;QACvB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE;YAAE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;SAAE,CAAC;QAC9E,UAAU,EAAE,MAAM,CAAC;KACpB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,UAG/B,CAAC"}

package/dist/turn-policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"turn-policy.js","sourceRoot":"","sources":["../src/turn-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA8CH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAe;IAC3C,YAAY,EAAE,GAAG,EAAE,CAAC,QAAQ;IAC5B,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;CAC9B,CAAC"}
+{"version":3,"file":"turn-policy.js","sourceRoot":"","sources":["../src/turn-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA6DH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAe;IAC3C,YAAY,EAAE,GAAG,EAAE,CAAC,QAAQ;IAC5B,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;CAC9B,CAAC"}

package/dist/types.d.ts

@@ -1,3 +1,7 @@
+import type { AttachmentRef, TurnStoppedReason, TurnStoppedMarker } from '@ouispec/agent-core';
+import type { AttachmentWorkerConfig } from './attachments/store.js';
+import type { AttachmentUsage } from './attachments/guard.js';
+import type { TurnStopClient, TurnStopWatch } from './stop/turn-stop.js';
 import type { LanguageModel, ProviderOptions } from './model.js';
 import type { RealtimeEmitAdapter } from './emit/types.js';
 import type { ToolRegistry } from './tools/types.js';
@@ -61,6 +65,14 @@ export interface AgentWorkerConfig {
         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;
         /** Largest index of the page's actions given to the model, in characters. Default 60000 (`DEFAULT_INDEX_CHARS`). */
@@ -76,8 +88,28 @@ export interface AgentWorkerConfig {
      *
      * It is awaited. If it rejects, the rejection is logged and the turn still
      * completes: a turn that answered is not turned into a failure by its record.
+     *
+     * A stopped turn calls it too, with what it had produced and `stopped`
+     * (ADR-0252 §2.4): stored first, announced after, on both paths.
+     */
+    beforeTurnComplete?: (turn: Pick<AgentTurnResult, 'rounds' | 'usage' | 'newMessages' | 'stopped'>) => Promise<void>;
+    /**
+     * Where the turn hears that it was asked to stop (ADR-0252 §2.1): the
+     * person's Stop, or a newer message superseding it. Without one, or without
+     * `stopWatch` on the turn's input, a turn cannot be stopped.
+     */
+    stops?: TurnStopClient;
+    /**
+     * How long after a stop an answer already on its way is still waited for,
+     * before its call is stored as sent with its outcome unknown. Default 2 s.
      */
-    beforeTurnComplete?: (turn: Pick<AgentTurnResult, 'rounds' | 'usage' | 'newMessages'>) => Promise<void>;
+    stopGraceMs?: number;
+    /**
+     * The host's file area (ADR-0252 §3). With it, a turn's files are given to
+     * the model with its message, and the attachment tools reach the
+     * conversation's files. Without it a turn's attachments are left out.
+     */
+    attachments?: AttachmentWorkerConfig;
 }
 export interface SystemPromptContext {
     userId: string;
@@ -103,6 +135,23 @@ export interface AgentTurnInput {
      * message text.
      */
     approval?: ApprovalContinuation;
+    /**
+     * The turn's watch for a stop, when the caller opened it before this call:
+     * the turn runner does, before it reads history, so a stop asked for while
+     * the turn waited is heard first. Without it, one is opened from
+     * `config.stops`.
+     */
+    stopWatch?: TurnStopWatch;
+    /**
+     * How long this process has left, in ms, when the host knows (a Lambda's
+     * remaining time). A stopped turn stores and announces within it.
+     */
+    remainingMs?: () => number;
+    /**
+     * The files attached to the turn's message, by reference (ADR-0252 §2.8):
+     * given to the model with it, through `config.attachments`.
+     */
+    attachments?: AttachmentRef[];
 }
 /**
  * Rich history message — supports full conversation state including tool calls and results.
@@ -111,10 +160,18 @@ export interface AgentTurnInput {
 export type TurnHistoryMessage = {
     role: 'user';
     content: string;
+    /** The files the person attached to this message: the model reads their reference lines. */
+    attachments?: AttachmentRef[] | null;
 } | {
     role: 'assistant';
     content: string | null;
     tool_calls?: ToolCallRef[];
+    /**
+     * Set on the last assistant message of a turn that was stopped
+     * (`TurnMessage.stopped`, as the host stored it). The model is told so
+     * after the message's text.
+     */
+    stopped?: TurnStoppedMarker | null;
 } | {
     role: 'tool';
     content: string;
@@ -161,8 +218,25 @@ export interface AgentTurnResult {
      */
     settledApprovals?: string[];
     maxRoundsReached: boolean;
-    /** Why the turn ended: which bound or condition terminated the loop */
-    stopReason: 'present_options' | 'awaiting_approval' | 'step_count' | 'token_budget' | 'deadline' | 'complete' | 'error';
+    /**
+     * Why the turn ended: which bound or condition terminated the loop, or
+     * that it was stopped (`user_stop`, `superseded`: ADR-0252).
+     */
+    stopReason: 'present_options' | 'awaiting_approval' | 'step_count' | 'token_budget' | 'deadline' | 'complete' | 'error' | TurnStoppedReason;
+    /**
+     * Set when the turn was stopped: `newMessages` is what it had produced, each
+     * call with exactly one result, the last assistant message marked.
+     */
+    stopped?: TurnStoppedMarker;
+    /**
+     * `false` when the turn was stopped and what it had produced could not be
+     * stored (`beforeTurnComplete` failed or ran out of time). A turn that ran
+     * out of time and stored nothing is recorded as such, not as stopped
+     * (ADR-0252 §6.4).
+     */
+    stored?: false;
+    /** What the turn gave the model of its files, when the host has a file area (ADR-0252 §2.11). */
+    attachments?: AttachmentUsage;
 }
 export interface TurnMessage {
     role: 'assistant' | 'tool';
@@ -174,5 +248,12 @@ export interface TurnMessage {
     }>;
     toolCallId?: string;
     name?: string;
+    /**
+     * On the last assistant message of a stopped turn (ADR-0252 §2.3). The host
+     * stores it with the message and hands it back in history
+     * (`TurnHistoryMessage.stopped`). A message that has only the marker carries
+     * the marker's line as its `content`, so it is never empty.
+     */
+    stopped?: TurnStoppedMarker;
 }
 //# sourceMappingURL=types.d.ts.map