@ouispec/agent-worker 0.4.0 → 0.8.0

package/dist/types.d.ts.map

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

package/dist/ui/knowledge.d.ts

@@ -10,10 +10,24 @@
  * The worker renders it into the system prompt after the host's own prompt, for
  * every host: a persona or a `systemPrompt` callback never sees it as context
  * and never has to render it.
+ *
+ * It is bounded, as the page's index is (ADR-0245): in session 24611234 the
+ * video editor's knowledge was 117,000 characters, most of it a page detail
+ * that repeats what the index already lists, in every model call of every
+ * turn. What fits in `KNOWLEDGE_PROMPT_CHARS` is sent; the rest of an entry,
+ * and a workflow's steps, are read with `ui_guide` when they are needed, and
+ * the prompt says what is not shown and how to read it.
  */
 import type { ResolvedKnowledge } from '@ouispec/bindings';
+import type { RegisteredTool } from '../tools/types.js';
 /** The context key a UI client uses for its knowledge. */
 export declare const CLIENT_KNOWLEDGE_KEY = "uiKnowledge";
+/** The tool that reads the rest of the knowledge. */
+export declare const KNOWLEDGE_TOOL = "ui_guide";
+/** The knowledge the system prompt carries at most, in characters. One constant. */
+export declare const KNOWLEDGE_PROMPT_CHARS = 12000;
+/** What one `ui_guide` answer gives at most. */
+export declare const KNOWLEDGE_PAGE_CHARS = 12000;
 /** What a UI client sends: the knowledge for the page the user is on. */
 export type ClientKnowledge = ResolvedKnowledge;
 /**
@@ -23,8 +37,20 @@ export type ClientKnowledge = ResolvedKnowledge;
  * become "this client knows nothing".
  */
 export declare function readClientKnowledge(context: Record<string, unknown> | null | undefined): ClientKnowledge | null;
-/** The knowledge as a prompt section: every entry, then every workflow with its numbered steps. */
-export declare function renderClientKnowledge(knowledge: ClientKnowledge): string;
+/**
+ * The knowledge as a prompt section, within `maxChars`: every entry whole when
+ * all of it fits, and every workflow with its steps. Over that, small entries
+ * stay whole, a large one is cut at a line with a note saying how much is left
+ * and how to read it, and the workflows are listed by name to be read one at a
+ * time.
+ */
+export declare function renderClientKnowledge(knowledge: ClientKnowledge, maxChars?: number): string;
+/**
+ * Reads what the prompt leaves out of the client's knowledge: the rest of an
+ * entry, a page at a time, or a workflow in full. It reads only what the turn's
+ * client sent, so it changes nothing and needs no approval.
+ */
+export declare function knowledgeTool(knowledge: ClientKnowledge): RegisteredTool;
 /** The host's system prompt, followed by the knowledge the turn's client sent, if any. */
 export declare function withClientKnowledge(systemPrompt: string, context: Record<string, unknown> | null | undefined): string;
 //# sourceMappingURL=knowledge.d.ts.map

package/dist/ui/knowledge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../src/ui/knowledge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAElD,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,eAAe,GAAG,IAAI,CAe/G;AAED,mGAAmG;AACnG,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,eAAe,GAAG,MAAM,CAgBxE;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAIrH"}
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../src/ui/knowledge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAClD,qDAAqD;AACrD,eAAO,MAAM,cAAc,aAAa,CAAC;AACzC,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAG7C,gDAAgD;AAChD,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,eAAe,GAAG,IAAI,CAe/G;AAcD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,eAAe,EAAE,QAAQ,SAAyB,GAAG,MAAM,CAqC3G;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,eAAe,GAAG,cAAc,CAmDxE;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAIrH"}

package/dist/ui/knowledge.js

@@ -1,5 +1,13 @@
 /** The context key a UI client uses for its knowledge. */
 export const CLIENT_KNOWLEDGE_KEY = 'uiKnowledge';
+/** The tool that reads the rest of the knowledge. */
+export const KNOWLEDGE_TOOL = 'ui_guide';
+/** The knowledge the system prompt carries at most, in characters. One constant. */
+export const KNOWLEDGE_PROMPT_CHARS = 12_000;
+/** An entry this size or smaller is never cut: a map, a frame, a neighbouring page's summary. */
+const WHOLE_ENTRY_CHARS = 1_500;
+/** What one `ui_guide` answer gives at most. */
+export const KNOWLEDGE_PAGE_CHARS = 12_000;
 /**
  * Read and validate the knowledge from a turn's context. Returns null when the
  * turn carries none (a client with no UI), and throws when it carries knowledge
@@ -28,19 +36,115 @@ export function readClientKnowledge(context) {
     });
     return { entries, workflows };
 }
-/** The knowledge as a prompt section: every entry, then every workflow with its numbered steps. */
-export function renderClientKnowledge(knowledge) {
-    const sections = [];
-    if (knowledge.entries.length > 0) {
-        sections.push('## Platform Knowledge (Context-Aware)\n\n' + knowledge.entries.map((e) => `### ${e.title}\n${e.content}`).join('\n\n'));
-    }
-    if (knowledge.workflows.length > 0) {
-        sections.push('## Active Workflows\n\n' +
-            knowledge.workflows
-                .map((w) => `### ${w.name}\nTrigger: ${w.trigger}\nSteps:\n${w.steps.map((s, i) => `${i + 1}. ${s}`).join('\n')}`)
-                .join('\n\n'));
-    }
-    return sections.join('\n\n');
+/** A workflow in full: its trigger and numbered steps. */
+function workflowText(w) {
+    return `Trigger: ${w.trigger}\nSteps:\n${w.steps.map((step, i) => `${i + 1}. ${step}`).join('\n')}`;
+}
+/** `text` cut at a line end at most `max` characters in, never mid-line when a line end is near. */
+function cutAt(text, max) {
+    if (text.length <= max)
+        return text;
+    const end = text.lastIndexOf('\n', max);
+    return text.slice(0, end > max / 2 ? end : max);
+}
+/**
+ * The knowledge as a prompt section, within `maxChars`: every entry whole when
+ * all of it fits, and every workflow with its steps. Over that, small entries
+ * stay whole, a large one is cut at a line with a note saying how much is left
+ * and how to read it, and the workflows are listed by name to be read one at a
+ * time.
+ */
+export function renderClientKnowledge(knowledge, maxChars = KNOWLEDGE_PROMPT_CHARS) {
+    const entryHead = '## Platform Knowledge (Context-Aware)\n\n';
+    const workflowHead = '## Active Workflows\n\n';
+    const whole = (e) => `### ${e.title}\n${e.content}`;
+    const wholeWorkflows = knowledge.workflows.map((w) => `### ${w.name}\n${workflowText(w)}`).join('\n\n');
+    const sections = (entries, workflows) => [entries.length ? entryHead + entries.join('\n\n') : '', workflows ? workflowHead + workflows : '']
+        .filter(Boolean)
+        .join('\n\n');
+    const all = sections(knowledge.entries.map(whole), wholeWorkflows);
+    if (all.length <= maxChars)
+        return all;
+    // The workflows by name: each read whole with the tool.
+    const named = knowledge.workflows.length
+        ? `Each is read in full, with its steps, by \`${KNOWLEDGE_TOOL}\` with \`workflow\` set to its name.\n` +
+            knowledge.workflows.map((w) => `- ${w.name}`).join('\n')
+        : '';
+    const workflowsSize = named ? workflowHead.length + named.length + 2 : 0;
+    // The small entries whole; the large ones share what is left, each cut at a line.
+    const small = knowledge.entries.filter((e) => whole(e).length <= WHOLE_ENTRY_CHARS);
+    const large = knowledge.entries.filter((e) => whole(e).length > WHOLE_ENTRY_CHARS);
+    const fixed = entryHead.length + small.reduce((n, e) => n + whole(e).length + 2, 0);
+    const share = Math.max(0, Math.floor((maxChars - workflowsSize - fixed) / Math.max(large.length, 1)) - 200);
+    const rendered = knowledge.entries.map((e) => {
+        if (!large.includes(e))
+            return whole(e);
+        const shown = cutAt(e.content, share);
+        const rest = e.content.length - shown.length;
+        return (`### ${e.title}\n${shown}` +
+            (rest > 0
+                ? `\n(${rest} more characters of "${e.title}" are not shown: \`${KNOWLEDGE_TOOL}\` with \`entry\` set to this title and \`from: ${shown.length}\` reads them.)`
+                : ''));
+    });
+    return sections(rendered, named);
+}
+/**
+ * Reads what the prompt leaves out of the client's knowledge: the rest of an
+ * entry, a page at a time, or a workflow in full. It reads only what the turn's
+ * client sent, so it changes nothing and needs no approval.
+ */
+export function knowledgeTool(knowledge) {
+    const titles = knowledge.entries.map((e) => e.title);
+    const names = knowledge.workflows.map((w) => w.name);
+    const listed = (items) => items.slice(0, 40).map((t) => `"${t}"`).join(', ') + (items.length > 40 ? ', …' : '');
+    return {
+        name: KNOWLEDGE_TOOL,
+        kind: 'ui',
+        effect: 'view',
+        description: 'Reads the part of what the app knows about this page that your instructions do not show: the rest of a ' +
+            'knowledge entry (`entry`, its title, and `from`, where to continue), or one workflow with its steps (`workflow`, its name). ' +
+            'Your instructions say what is not shown and give the title or name.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                entry: { type: 'string', description: 'A knowledge entry’s title, as your instructions give it.' },
+                workflow: { type: 'string', description: 'A workflow’s name, as your instructions list it.' },
+                from: { type: 'integer', minimum: 0, description: 'Where in the entry to begin. Default 0.' },
+            },
+        },
+        async execute(input) {
+            const workflow = typeof input.workflow === 'string' ? input.workflow.trim() : '';
+            const entry = typeof input.entry === 'string' ? input.entry.trim() : '';
+            if (workflow) {
+                const found = knowledge.workflows.find((w) => w.name === workflow) ??
+                    knowledge.workflows.find((w) => w.name.toLowerCase() === workflow.toLowerCase());
+                if (!found)
+                    return { success: false, error: `No workflow is named "${workflow}". Workflows: ${listed(names)}.` };
+                return { success: true, data: { workflow: found.name, text: workflowText(found) } };
+            }
+            if (entry) {
+                const found = knowledge.entries.find((e) => e.title === entry) ??
+                    knowledge.entries.find((e) => e.title.toLowerCase() === entry.toLowerCase());
+                if (!found)
+                    return { success: false, error: `No knowledge entry has the title "${entry}". Entries: ${listed(titles)}.` };
+                const from = typeof input.from === 'number' && input.from > 0 ? Math.min(input.from, found.content.length) : 0;
+                const text = cutAt(found.content.slice(from), KNOWLEDGE_PAGE_CHARS);
+                const next = from + text.length;
+                return {
+                    success: true,
+                    data: {
+                        entry: found.title,
+                        from,
+                        total: found.content.length,
+                        text,
+                        ...(next < found.content.length ? { next } : {}),
+                    },
+                };
+            }
+            return { success: false, error: 'Give an `entry` title or a `workflow` name.' };
+        },
+    };
 }
 /** The host's system prompt, followed by the knowledge the turn's client sent, if any. */
 export function withClientKnowledge(systemPrompt, context) {

package/dist/ui/knowledge.js.map

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

package/dist/ui/newest-page-state.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Only the newest UI answer carries the page's state to the model.
+ *
+ * Every UI answer comes with the page's state (`state`, up to the page-state
+ * budget), so the model sees what its action did. Kept on every answer, a turn
+ * of many actions resends every earlier page with every step: in session
+ * 24611234 a turn of 24 editor actions peaked at 205,000 prompt tokens, about
+ * 5,000 for each answer kept. An earlier page is not what the page is now, and
+ * the newest answer holds that.
+ *
+ * So before each step, every earlier answer keeps what it did (its result, the
+ * rows it changed, what the page offers since, any error) and its `state` is
+ * replaced with one line that says where the page's state is.
+ */
+import type { ModelMessage } from 'ai';
+export declare const SUPERSEDED_STATE = "Not repeated: a later answer in this conversation carries the page\u2019s state, which is what the page is now.";
+/**
+ * `messages` with the page's state kept on the newest answer that carries one
+ * and replaced on every earlier one, or null when there is nothing to replace.
+ */
+export declare function withNewestPageStateOnly(messages: readonly ModelMessage[]): {
+    messages: ModelMessage[];
+    replaced: number;
+} | null;
+//# sourceMappingURL=newest-page-state.d.ts.map

package/dist/ui/newest-page-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"newest-page-state.d.ts","sourceRoot":"","sources":["../../src/ui/newest-page-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAEvC,eAAO,MAAM,gBAAgB,oHACiF,CAAC;AAgD/G;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG;IAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAkChI"}

package/dist/ui/newest-page-state.js

@@ -0,0 +1,91 @@
+export const SUPERSEDED_STATE = 'Not repeated: a later answer in this conversation carries the page’s state, which is what the page is now.';
+/** The JSON text of an answer, when it is a UI answer that carries the page's state. */
+function stateful(text) {
+    if (!text.includes('"state"'))
+        return null;
+    try {
+        const value = JSON.parse(text);
+        return value && typeof value === 'object' && !Array.isArray(value) && 'state' in value
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The answer's text, wherever its output keeps it. */
+function textOf(output) {
+    if (output.type === 'text')
+        return output.value;
+    if (output.type === 'json')
+        return JSON.stringify(output.value);
+    if (output.type === 'content') {
+        const part = output.value.find((p) => p.type === 'text');
+        return part?.text ?? null;
+    }
+    return null;
+}
+function withText(output, text) {
+    if (output.type === 'text')
+        return { ...output, value: text };
+    if (output.type === 'json')
+        return { ...output, value: JSON.parse(text) };
+    if (output.type === 'content') {
+        let done = false;
+        return {
+            ...output,
+            value: output.value.map((p) => {
+                if (done || p.type !== 'text')
+                    return p;
+                done = true;
+                return { ...p, text };
+            }),
+        };
+    }
+    return output;
+}
+/**
+ * `messages` with the page's state kept on the newest answer that carries one
+ * and replaced on every earlier one, or null when there is nothing to replace.
+ */
+export function withNewestPageStateOnly(messages) {
+    // The newest answer with a state, found from the end.
+    let newest = null;
+    for (let i = messages.length - 1; i >= 0 && newest === null; i--) {
+        const m = messages[i];
+        if (m.role !== 'tool')
+            continue;
+        for (let j = m.content.length - 1; j >= 0; j--) {
+            const part = m.content[j];
+            if (part.type !== 'tool-result')
+                continue;
+            const text = textOf(part.output);
+            if (text !== null && stateful(text)) {
+                newest = part.toolCallId;
+                break;
+            }
+        }
+    }
+    if (newest === null)
+        return null;
+    let replaced = 0;
+    const out = messages.map((m) => {
+        if (m.role !== 'tool')
+            return m;
+        let changed = false;
+        const content = m.content.map((part) => {
+            if (part.type !== 'tool-result' || part.toolCallId === newest)
+                return part;
+            const text = textOf(part.output);
+            const answer = text === null ? null : stateful(text);
+            if (!answer || answer.state === SUPERSEDED_STATE)
+                return part;
+            changed = true;
+            replaced++;
+            return { ...part, output: withText(part.output, JSON.stringify({ ...answer, state: SUPERSEDED_STATE })) };
+        });
+        return changed ? { ...m, content } : m;
+    });
+    return replaced ? { messages: out, replaced } : null;
+}
+//# sourceMappingURL=newest-page-state.js.map

package/dist/ui/newest-page-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"newest-page-state.js","sourceRoot":"","sources":["../../src/ui/newest-page-state.ts"],"names":[],"mappings":"AAgBA,MAAM,CAAC,MAAM,gBAAgB,GAC3B,4GAA4G,CAAC;AAO/G,wFAAwF;AACxF,SAAS,QAAQ,CAAC,IAAY;IAC5B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;QAC1C,OAAO,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,IAAI,KAAK;YACpF,CAAC,CAAE,KAAiC;YACpC,CAAC,CAAC,IAAI,CAAC;IACX,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,uDAAuD;AACvD,SAAS,MAAM,CAAC,MAAgC;IAC9C,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC;IAChD,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChE,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAiC,CAAC;QACzF,OAAO,IAAI,EAAE,IAAI,IAAI,IAAI,CAAC;IAC5B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,QAAQ,CAAC,MAAgC,EAAE,IAAY;IAC9D,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC9D,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;IAC1E,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,IAAI,GAAG,KAAK,CAAC;QACjB,OAAO;YACL,GAAG,MAAM;YACT,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC5B,IAAI,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;oBAAE,OAAO,CAAC,CAAC;gBACxC,IAAI,GAAG,IAAI,CAAC;gBACZ,OAAO,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC;YACxB,CAAC,CAAC;SACH,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAiC;IACvE,sDAAsD;IACtD,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;QACjE,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;YAAE,SAAS;QAChC,KAAK,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/C,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa;gBAAE,SAAS;YAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACjC,IAAI,IAAI,KAAK,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpC,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;gBACzB,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAEjC,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC7B,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,CAAC,CAAC;QAChC,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YACrC,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa,IAAI,IAAI,CAAC,UAAU,KAAK,MAAM;gBAAE,OAAO,IAAI,CAAC;YAC3E,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACjC,MAAM,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACrD,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,KAAK,KAAK,gBAAgB;gBAAE,OAAO,IAAI,CAAC;YAC9D,OAAO,GAAG,IAAI,CAAC;YACf,QAAQ,EAAE,CAAC;YACX,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC,CAAC,EAAE,CAAC;QAC5G,CAAC,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACvD,CAAC"}

package/dist/ui/ui-tools.d.ts

@@ -55,6 +55,12 @@ export interface UIToolDependencies {
      * reported as running, never as done. Unbounded when not given.
      */
     waitDeadline?: () => number;
+    /**
+     * The longest a call waits for the outcome of work its action started, in ms;
+     * `DEFAULT_JOB_WAIT_MS` when not given. Never longer than the action's own
+     * limit or `waitDeadline`.
+     */
+    jobWaitMs?: number;
     /**
      * The turn's UI action queue, shared by every set of UI tools built during the
      * turn, so the actions run one at a time in the order they were called. A new
@@ -85,8 +91,18 @@ export declare const MAX_RESEND_AFTER_MS = 8000;
  * `reanswerAfterMs`, 8 s), so the repeat recovers an answer that was lost.
  */
 export declare const RECEIVED_RESEND_AFTER_MS = 10000;
-/** How long to wait for an async action's outcome when it declares no limit of its own. */
-export declare const DEFAULT_JOB_WAIT_MS: number;
+/**
+ * The longest a UI tool waits, in the call, for the outcome of work an action
+ * started (a GPU job, an export): `UIToolDependencies.jobWaitMs` by default.
+ *
+ * Work that ends within it is reported done in the call. Work that does not is
+ * reported still running, and the turn goes on and ends: its outcome reaches
+ * the conversation through the page state, where the app's job tracker lists
+ * it, in the next turn. The call never waits on the action's own limit (its
+ * `maxDurationMs`), which can be many minutes for a job queued behind a live
+ * conversation: a turn held open that long could not be stopped or answered.
+ */
+export declare const DEFAULT_JOB_WAIT_MS = 20000;
 /** The most actions one `ui_describe` call describes. */
 export declare const MAX_DESCRIBED_ACTIONS = 8;
 /**
@@ -103,6 +119,8 @@ export declare function buildUITools(page: readonly PageSurface[], deps: UIToolD
 /** Thrown when an action's definition cannot be had: the model is told why. */
 export declare class DefinitionUnavailable extends Error {
 }
+/** The call's wait for a started action's outcome. */
+export declare function jobWaitOf(deps: Pick<UIToolDependencies, 'jobWaitMs'>): number;
 /** What of the page's state the client left out to fit its answer, and how to read each part (oui-spec §7.3.9). */
 export declare function fitNotes(cuts: NonNullable<OUIFit['observations']>): string[];
 export {};

package/dist/ui/ui-tools.d.ts.map

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

package/dist/ui/ui-tools.js

@@ -14,6 +14,7 @@
  * tools built here are what `ui_act` runs, so every check a tool call goes
  * through — input, quota, policy, approval — sees the action itself.
  */
+import { stoppedBeforeAnswer, stoppedNotRun, stoppedNotTaken, stoppedOutcomeUnknown } from '../stop/results.js';
 import { randomUUID } from 'node:crypto';
 import { AGENT_UI_TOOLS } from '@ouispec/agent-core';
 import { jsonBytes, OUI_DESCRIBE_ACTION, OUI_READ_ACTION, OUI_RUNTIME_SURFACE, } from 'oui-spec/spec';
@@ -79,8 +80,18 @@ export const MAX_RESEND_AFTER_MS = 8_000;
  * `reanswerAfterMs`, 8 s), so the repeat recovers an answer that was lost.
  */
 export const RECEIVED_RESEND_AFTER_MS = 10_000;
-/** How long to wait for an async action's outcome when it declares no limit of its own. */
-export const DEFAULT_JOB_WAIT_MS = 5 * 60_000;
+/**
+ * The longest a UI tool waits, in the call, for the outcome of work an action
+ * started (a GPU job, an export): `UIToolDependencies.jobWaitMs` by default.
+ *
+ * Work that ends within it is reported done in the call. Work that does not is
+ * reported still running, and the turn goes on and ends: its outcome reaches
+ * the conversation through the page state, where the app's job tracker lists
+ * it, in the next turn. The call never waits on the action's own limit (its
+ * `maxDurationMs`), which can be many minutes for a job queued behind a live
+ * conversation: a turn held open that long could not be stopped or answered.
+ */
+export const DEFAULT_JOB_WAIT_MS = 20_000;
 /** The most actions one `ui_describe` call describes. */
 export const MAX_DESCRIBED_ACTIONS = 8;
 /**
@@ -137,6 +148,9 @@ function actionTool(action, shared) {
                 // Checked here, in the action's place in the turn's order, and not when
                 // the model's call arrived: of two changes called in one response, the
                 // first's answer decides whether the second may run (ADR-0245 §2.5).
+                // A stopped turn sends nothing more: said first, since why it did not run is the stop.
+                if (ctx.stop?.reason())
+                    return stoppedNotRun(entry.id);
                 const refusal = entry.effect === 'view' ? null : shared.sight.refuseChange();
                 if (refusal) {
                     shared.deps.log?.('warn', 'UI action refused: the page cannot be seen', { action: entry.id, stopped: refusal.stopped });
@@ -174,14 +188,21 @@ async function definitionsOf(wanted, shared, ctx) {
         const room = ctx.socketRoom;
         if (!room)
             throw new Error('[agent-sdk] Describing a UI action needs the turn’s room');
+        // A stopped turn asks the page nothing more.
+        if (ctx.stop?.reason())
+            throw new DefinitionUnavailable(stoppedBeforeAnswer('what the action takes').error);
         const request = {
             requestId: `describe-${randomUUID()}`,
             surfaceId: OUI_RUNTIME_SURFACE,
             actionId: OUI_DESCRIBE_ACTION,
             params: { actions: missing.map((a) => ({ surface: a.surface.id, action: a.entry.id })) },
             timestamp: Date.now(),
+            turnId: ctx.turnId,
         };
         const answered = await dispatchUntilAnswered(shared.deps, room, request, ctx);
+        if (!answered.result && ctx.stop?.reason()) {
+            throw new DefinitionUnavailable(stoppedBeforeAnswer('what the action takes').error);
+        }
         if (!answered.result) {
             // A page that does not answer cannot be seen either: nothing is changed in it until it is read.
             shared.sight.lost('the page is not answering');
@@ -332,14 +353,20 @@ function readTool(shared) {
                 const room = ctx.socketRoom;
                 if (!room)
                     throw new Error('[agent-sdk] Reading the page needs the turn’s room');
+                // A stopped turn asks the page nothing more.
+                if (ctx.stop?.reason())
+                    return stoppedBeforeAnswer('the read');
                 const request = {
                     requestId: ctx.toolCallId ?? `read-${randomUUID()}`,
                     surfaceId: OUI_RUNTIME_SURFACE,
                     actionId: OUI_READ_ACTION,
                     params: input,
                     timestamp: Date.now(),
+                    turnId: ctx.turnId,
                 };
                 const answered = await dispatchUntilAnswered(shared.deps, room, request, ctx);
+                if (!answered.result && ctx.stop?.reason())
+                    return stoppedBeforeAnswer('the read');
                 if (!answered.result) {
                     shared.sight.lost('the page did not answer a read');
                     return {
@@ -366,6 +393,10 @@ async function runAction(action, shared, input, ctx) {
     if (!requestId || !room) {
         throw new Error(`[agent-sdk] UI tool ${entry.id} needs the tool call id and the turn's room`);
     }
+    // A stopped turn sends nothing more: an action that was waiting its place in
+    // the turn's UI order has not reached the page, and now never does.
+    if (ctx.stop?.reason())
+        return stoppedNotRun(entry.id);
     // The page as the actions before this one left it.
     const before = sequence.latestSurfaces() ?? deps.currentPage();
     // What the worker holds of the page, so the answer repeats it only if it changed (oui-spec §7.3.4).
@@ -378,8 +409,29 @@ async function runAction(action, shared, input, ctx) {
         timestamp: Date.now(),
         ...(ctx.approval ? { approval: ctx.approval } : {}),
         ...(knownSurfaces ? { knownSurfaces } : {}),
+        // The tab runs a request only for its current turn (oui-spec §7.3.1).
+        turnId: ctx.turnId,
     };
-    const answered = await dispatchUntilAnswered(deps, room, request, ctx);
+    let answered = await dispatchUntilAnswered(deps, room, request, ctx);
+    // The turn was stopped while the request was out (ADR-0252 §2.2).
+    if (!answered.result && ctx.stop?.reason()) {
+        // Tabs answered that they got it, and none took it: it did not run.
+        if (answered.receipts && !answered.received)
+            return stoppedNotTaken(entry.id);
+        // The page may be running it. One last look, on the stop's own signal (the
+        // turn's is aborted), so an action that did run has its answer stored and
+        // the next turn does not do it again.
+        const late = await deps.channel.awaitResult(requestId, {
+            userId: ctx.userId,
+            timeoutMs: ctx.stop.graceMs,
+            signal: ctx.stop.graceSignal(),
+        });
+        if (!late) {
+            sight.lost(`the turn was stopped before the page answered "${entry.id}"`);
+            return stoppedOutcomeUnknown(entry.id);
+        }
+        answered = { ...answered, result: late };
+    }
     if (!answered.result) {
         const within = `within ${Math.round(deps.resultTimeoutMs / 1000)}s`;
         const sent = `${answered.sends} time${answered.sends === 1 ? '' : 's'}`;
@@ -489,11 +541,13 @@ function withPage(result, shared) {
 }
 /**
  * The final answer to a started action: its outcome once the work is done or
- * has failed, or `'running'` when it has not finished by its own limit (its
- * polling's `maxDurationMs`) or by when the turn must stop waiting.
+ * has failed, or `'running'` when it has not finished within the call's wait
+ * (`jobWaitMs`), its own limit (its polling's `maxDurationMs`), or by when the
+ * turn must stop waiting, whichever comes first.
  */
 async function awaitOutcome(entry, deps, requestId, ctx) {
-    const until = Math.min(Date.now() + (entry.maxDurationMs ?? DEFAULT_JOB_WAIT_MS), deps.waitDeadline?.() ?? Infinity);
+    const waitMs = Math.min(entry.maxDurationMs ?? Infinity, jobWaitOf(deps));
+    const until = Math.min(Date.now() + waitMs, deps.waitDeadline?.() ?? Infinity);
     const timeoutMs = until - Date.now();
     if (timeoutMs <= 0)
         return 'running';
@@ -508,6 +562,11 @@ async function awaitOutcome(entry, deps, requestId, ctx) {
         return 'running';
     return final;
 }
+/** The call's wait for a started action's outcome. */
+export function jobWaitOf(deps) {
+    const ms = deps.jobWaitMs;
+    return typeof ms === 'number' && Number.isFinite(ms) && ms >= 0 ? ms : DEFAULT_JOB_WAIT_MS;
+}
 function stillRunningNote(entry) {
     return (`"${entry.id}" started and has not finished yet, so it is not done: tell the person it is still running, ` +
         'never that it is done. Its status and result appear in the page state when it finishes.');