@ouispec/agent-worker 0.13.0 → 0.13.1

package/dist/openapi/x-agent.js

@@ -1,10 +1,10 @@
 /**
- * `x-agent`: how an operation opts in as an agent tool (ADR-0181 §3, ADR-0227 §2.1).
+ * `x-agent`: how an operation opts in as an agent tool.
  *
  * ```yaml
  * x-agent:
  *   expose: true            # without it, the operation is not a tool
- *   effect: mutate          # ADR-0226 §2.6: view | file | mutate | job | transaction, or its object form
+ *   effect: mutate          # view | file | mutate | job | transaction, or its object form
  *   destructive: true       # optional, on a write: removes or replaces something the person made
  *   consequence: "..."      # optional: what happens, for the tool's description and an approval's preview
  *   pa: true                # optional: the product's own assistant may call it; only on a read

package/dist/orchestrator.d.ts

@@ -5,7 +5,7 @@ import type { AgentWorkerConfig, AgentTurnInput, AgentTurnResult } from './types
  * A turn runs in one or more segments. Each segment is one `streamText` call
  * with a fixed tool set. When a UI action changes what the client's page
  * offers (navigating is the common case), the segment ends and the turn
- * continues in a new one whose tools are the new page's (ADR-0209 D3). The
+ * continues in a new one whose tools are the new page's. The
  * round cap counts across segments.
  */
 export declare function runAgentTurn(config: AgentWorkerConfig, input: AgentTurnInput): Promise<AgentTurnResult>;

package/dist/orchestrator.js

@@ -2,7 +2,7 @@
  * Agent Orchestrator — powered by Vercel AI SDK.
  *
  * The model is the host's: any `ai` library model, passed in configuration
- * (ADR-0227 §2.2, "Model"). The core names no provider. The AI SDK handles:
+ * ("Model"). The core names no provider. The AI SDK handles:
  *   - each provider's wire format (internal, never exposed)
  *   - tool_use / tool_result pairing (automatic, no manual repair needed)
  *   - Multi-round tool loops (via stopWhen)
@@ -11,7 +11,7 @@
  *   - Error categorization and retries
  *
  * Our value-add stays:
- *   - UI tools from the client's OUI surfaces, answered by the client (ADR-0209)
+ *   - UI tools from the client's OUI surfaces, answered by the client
  *   - Schema-based tool loading
  *   - Persona/prompt compilation
  *   - Emit adapter (realtime socket streaming)
@@ -93,7 +93,7 @@ const notRun = (payload) => ({ text: JSON.stringify(payload), ran: false });
  * A turn runs in one or more segments. Each segment is one `streamText` call
  * with a fixed tool set. When a UI action changes what the client's page
  * offers (navigating is the common case), the segment ends and the turn
- * continues in a new one whose tools are the new page's (ADR-0209 D3). The
+ * continues in a new one whose tools are the new page's. The
  * round cap counts across segments.
  */
 export async function runAgentTurn(config, input) {
@@ -107,7 +107,7 @@ export async function runAgentTurn(config, input) {
     const uiResultTimeoutMs = config.ui?.resultTimeoutMs ?? DEFAULT_UI_RESULT_TIMEOUT_MS;
     const uiJobWaitMs = jobWaitOf({ jobWaitMs: config.ui?.jobWaitMs });
     if (!config.model) {
-        throw new Error('[agent-sdk] config.model is required: pass an `ai` library model (ADR-0227 §2.2)');
+        throw new Error('[agent-sdk] config.model is required: pass an `ai` library model');
     }
     const { turnId, socketRoom } = input;
     log('info', 'agent:turn', 'Turn started', {
@@ -120,7 +120,7 @@ export async function runAgentTurn(config, input) {
         maxTokens,
         temperature,
     });
-    // ─── The client's UI (ADR-0209 D1) ─────────────────────────────────────────
+    // ─── The client's UI ─────────────────────────────────────────
     // The turn carries the surfaces of the client that sent it. They are the only
     // source of UI tools, so the tools always describe the page the user is on.
     const client = readClientPage(input.context ?? null);
@@ -128,7 +128,7 @@ export async function runAgentTurn(config, input) {
         throw new Error('[agent-sdk] The turn carries UI surfaces but the worker has no UI action channel (config.ui): ' +
             'its UI actions could be sent but never answered.');
     }
-    // What the page offers, in index (ADR-0245 §2.1): kept current by every answer.
+    // What the page offers, in index: kept current by every answer.
     let currentPage = client?.page ?? [];
     // The turn's UI actions run one at a time, in the order the model called them (ui-sequence.ts).
     const uiSequence = createUISequence();
@@ -137,14 +137,14 @@ export async function runAgentTurn(config, input) {
         uiSequence.record(client.page, client.surfacesHash);
     // The definitions the turn holds: those a client sent, and those fetched since.
     const heldDefinitions = client?.held ?? new Map();
-    // Whether the page can be seen (ADR-0245 §2.5): nothing that changes it runs while it cannot.
+    // Whether the page can be seen: nothing that changes it runs while it cannot.
     const sight = createPageSight();
     const uiCounts = { describes: 0, reads: 0, acts: 0, guides: 0 };
     // Answers whose page state was moved to the end of what the model reads, summed over the turn's steps.
     let pageStatesMoved = 0;
     // The knowledge the client sent for its page goes after the host's prompt.
     const knowledge = readClientKnowledge(input.context ?? null);
-    // ─── Files (ADR-0252 §2.11, §2.12) ─────────────────────────────────────────
+    // ─── Files ─────────────────────────────────────────
     // With the host's file area, the turn's files go to the model with its
     // message, the attachment tools reach every file of the conversation, and the
     // cost guard caps what the model is given of them.
@@ -201,7 +201,7 @@ export async function runAgentTurn(config, input) {
     const hostPrompt = typeof config.systemPrompt === 'function'
         ? config.systemPrompt({ userId: input.userId, accountId: input.accountId, context: withoutClientUI(input.context) })
         : config.systemPrompt;
-    // With a file area, the model is told a file's name and content are data, never instructions (ADR-0252 §2.11).
+    // With a file area, the model is told a file's name and content are data, never instructions.
     const systemPrompt = withClientKnowledge(fileArea ? `${hostPrompt}\n\n${ATTACHMENT_DATA_NOTE}` : hostPrompt, input.context);
     log('debug', 'agent:prompt', 'System prompt built', { turnId, promptLength: systemPrompt.length, hostPromptLength: hostPrompt.length });
     // Wall-clock deadline: abort the entire streamText call if it exceeds turnDeadlineMs.
@@ -209,14 +209,14 @@ export async function runAgentTurn(config, input) {
     // A UI tool waiting on work it started stops in time for the model to answer.
     const uiWaitDeadline = () => turnStartedAt + turnDeadlineMs - UI_ANSWER_MARGIN_MS;
     const abortController = new AbortController();
-    // ─── Stopping (ADR-0252) ───────────────────────────────────────────────────
+    // ─── Stopping ───────────────────────────────────────────────────
     // The person's Stop, or a newer message superseding this turn, is kept by the
     // realtime server; the watch asks for it for as long as the turn runs. A stop
     // aborts the turn's signal with a typed reason, which is what everything that
     // waits (the model stream, a UI action's answer, a job's outcome) already
     // honours. What the turn had produced is then stored and announced (below).
     const stopWatch = input.stopWatch ?? watchTurnStop(config.stops, turnId, input.userId);
-    /** Set when the turn begins its own end: a stop that lands after is not one (§2.4). */
+    /** Set when the turn begins its own end: a stop that lands after is not one. */
     let ending = false;
     /** Kept back from a stopped turn's grace for storing and announcing it. */
     const STOP_STORE_MARGIN_MS = 3_000;
@@ -251,10 +251,10 @@ export async function runAgentTurn(config, input) {
         abortController.abort(stop);
     };
     stopWatch.onStop((record) => stopTurn(new TurnStopped(record.reason, record.at)));
-    // The turn's deadline ends it on the same path (ADR-0252 §6.4): what it did
+    // The turn's deadline ends it on the same path: what it did
     // before it ran out of time is kept, marked, and the next turn is told.
     const deadlineTimer = setTimeout(() => stopTurn(new TurnStopped('deadline', Date.now())), turnDeadlineMs);
-    // Before the deadline, the turn hands back with an answer when time is short (ADR-0269 §2.1).
+    // Before the deadline, the turn hands back with an answer when time is short.
     const stepClock = createStepClock({
         deadlineAt: turnStartedAt + turnDeadlineMs,
         turnDeadlineMs,
@@ -304,16 +304,16 @@ export async function runAgentTurn(config, input) {
     const toolInvocationCounts = new Map();
     const DEFAULT_TOOL_QUOTA = 12;
     const SIDE_EFFECT_TOOL_QUOTA = 2;
-    // A UI action is not counted (session 24611234: filling 12 slides of 3 values each
+    // A UI action is not counted (filling 12 slides of 3 values each
     // ran one action 36 times, and a cap of 12 stopped it). What is refused is a loop:
     // the same call with the same input, made again after it changed nothing three
     // times in a row. Undo five times, or nudge a layer five times, is work: each changes the page.
     const UNCHANGED_REPEATS = 3;
     const uiRepeats = new Map();
     // What each call of the turn did: said back to the model before every step
-    // after one did not succeed, so its reply matches it (ADR-0244 §2.5).
+    // after one did not succeed, so its reply matches it.
     const ledger = createTurnLedger();
-    // ─── Approvals (ADR-0228) ──────────────────────────────────────────────────
+    // ─── Approvals ──────────────────────────────────────────────────
     // The first call in a turn that needs the user's approval stops the turn:
     // it is stored as a pending approval, the card is shown, and nothing else
     // runs until they decide. Each call is approved separately.
@@ -348,7 +348,7 @@ export async function runAgentTurn(config, input) {
          * A call refused before its tool ran: invalid input, over its quota, or
          * denied by policy. The model gets the reason; so does the client, as a
          * call that started and failed, so a session's record holds every call
-         * the model made with its arguments (ADR-0244 §2.7).
+         * the model made with its arguments.
          */
         const refused = async (payload, given) => {
             ledger.record({ tool: t.name, ok: false, error: payload.error });
@@ -377,7 +377,7 @@ export async function runAgentTurn(config, input) {
         const timeoutMs = isUI
             ? Math.max(toolTimeoutMs, uiResultTimeoutMs + 5_000, Math.min(uiJobWaitMs, Math.max(0, uiWaitDeadline() - Date.now())) + uiResultTimeoutMs + 5_000)
             : toolTimeoutMs;
-        // ── No changes while blind (ADR-0245 §2.5) ──
+        // ── No changes while blind ──
         // After an answer that came without the page's state, or no answer, only
         // reading runs until a read shows the page again. A change called then is
         // refused here, before its definition is fetched or policy is asked; one
@@ -395,7 +395,7 @@ export async function runAgentTurn(config, input) {
         // Before quota and policy: an invalid call consumes no quota and never
         // reaches the host. The model gets the errors so it can correct the call.
         // A UI action's schema is its definition's, fetched from the page when the
-        // action is first used (ADR-0245 §2.1).
+        // action is first used.
         let schema = (t.inputSchema ?? {});
         if (t.resolveInputSchema) {
             try {
@@ -428,7 +428,7 @@ export async function runAgentTurn(config, input) {
             }, rawArgs);
         }
         const args = validation.value;
-        // ── Attached files named in the call (ADR-0252 §2.13) ──
+        // ── Attached files named in the call ──
         // Each must be a file of this turn's conversation, ready, and of a type the
         // input takes, checked before anything is dispatched; the page then
         // resolves it through its own host. An action declaring a file where none
@@ -492,13 +492,13 @@ export async function runAgentTurn(config, input) {
         // The call as a repeat is judged by: its name and its exact input. Set for a UI action that changes the page.
         let repeatKey = null;
         // ── Quota enforcement ──
-        // UI actions run as the user in their own session (ADR-0182 §3), so the
-        // backend side-effect cap does not apply to them (ADR-0209 D5). They are
+        // UI actions run as the user in their own session, so the
+        // backend side-effect cap does not apply to them. They are
         // bounded by the turn's steps and deadline; only a repeated identical call is refused.
         const currentCount = toolInvocationCounts.get(t.name) ?? 0;
         const isSideEffecting = schema.sideEffects !== false; // fail-closed: undefined = side-effecting
         if (isUI) {
-            // A UI action that only reads (a room's inspect and query, ADR-0244 §2.2)
+            // A UI action that only reads (a room's inspect and query)
             // changes nothing however often it is called.
             if (!reads) {
                 let input;
@@ -530,7 +530,7 @@ export async function runAgentTurn(config, input) {
             toolInvocationCounts.set(t.name, currentCount + 1);
         }
         // ── Policy enforcement ──
-        // A deny always wins, over an approval too (ADR-0228 §2.1).
+        // A deny always wins, over an approval too.
         const requirement = approvalRequirement(t);
         let policyRequiresApproval = false;
         if (config.toolPolicy) {
@@ -551,7 +551,7 @@ export async function runAgentTurn(config, input) {
             }
             policyRequiresApproval = decision.action === 'require_approval';
         }
-        // ── Approval (ADR-0228) ──
+        // ── Approval ──
         // Checked and set with no await in between, so of the calls in one
         // response exactly the first that needs approval stops the turn.
         if (approvalHold && !approved) {
@@ -696,12 +696,12 @@ export async function runAgentTurn(config, input) {
         };
     };
     /**
-     * Stops the turn at a call that needs the user's approval (ADR-0228 §2.2.1):
+     * Stops the turn at a call that needs the user's approval:
      * stores it as a pending approval, shows the card, and tells the model only
      * that it is waiting. The model never sees a token.
      */
     const requestApproval = async (t, args, toolUseId, requirement, files) => {
-        // A file is shown by its name and size; the approval stays bound to its id (ADR-0252 §2.13).
+        // A file is shown by its name and size; the approval stays bound to its id.
         const preview = buildApprovalPreview(t, args, files);
         approvalHold = { approvalId: toolUseId, title: preview.title };
         const refuse = (why) => {
@@ -842,7 +842,7 @@ export async function runAgentTurn(config, input) {
         return builtUI;
     }
     // The host's tools the model is given. A host tool with a UI tool's name, or
-    // with the id of an action of the page, is withheld (ADR-0209 D6): for a
+    // with the id of an action of the page, is withheld: for a
     // UI-only agent, the page is the authority.
     function hostTools(ui) {
         const sdkOwned = new Set(fileTools.map((t) => t.name));
@@ -952,7 +952,7 @@ export async function runAgentTurn(config, input) {
         return tools;
     }
     /**
-     * The turn after the user's decision on an approval card (ADR-0228 §2.2.5):
+     * The turn after the user's decision on an approval card:
      * redeem the token and run exactly the stored call, or learn that they
      * declined. What happened goes to the model as an `<approval>` note.
      *
@@ -1130,7 +1130,7 @@ export async function runAgentTurn(config, input) {
         const stoppedBeforeStart = stopOf(abortController.signal);
         if (stoppedBeforeStart)
             return await finishStopped(stoppedBeforeStart, { expired: null, continued: null });
-        // ─── The turn after an approval decision (ADR-0228 §2.2.5) ────────────────
+        // ─── The turn after an approval decision ────────────────
         const continued = input.approval ? await continueApproval(input.approval) : null;
         // ─── Calls still stored as waiting, whose approval expired undecided ──────
         //
@@ -1170,7 +1170,7 @@ export async function runAgentTurn(config, input) {
                     continue;
                 // The user had approved it and it was never run, or nobody decided: the result says which.
                 const wasApproved = answer.decided === 'approved';
-                // Withdrawn (a new message, or its turn stopped) is said as that, not as time running out (ADR-0252 §2.6).
+                // Withdrawn (a new message, or its turn stopped) is said as that, not as time running out.
                 const content = notRunResult(answer.withdrawn
                     ? withdrawnMarker(answer.withdrawn, wasApproved)
                     : wasApproved
@@ -1224,7 +1224,7 @@ export async function runAgentTurn(config, input) {
             turnFilesGiven && input.history?.at(-1)?.role === 'user' ? input.history.length - 1 : null),
             ...(continued?.messages ?? []),
         ];
-        // The turn's files go with its message, after everything said about it (ADR-0252 §2.11).
+        // The turn's files go with its message, after everything said about it.
         // A file that cannot be had is named with why; the turn goes on with the others.
         if (fileArea && turnFilesGiven) {
             try {
@@ -1363,9 +1363,9 @@ export async function runAgentTurn(config, input) {
                 stopWhen: [
                     isStepCount(maxRounds - allSteps.length),
                     ...USER_INPUT_TOOLS.map((name) => hasToolCall(name)),
-                    // A call is waiting for the user's approval: the turn ends here (ADR-0228).
+                    // A call is waiting for the user's approval: the turn ends here.
                     () => approvalHold !== null,
-                    // The step that handed the turn back for time was its last (ADR-0269 §2.1).
+                    // The step that handed the turn back for time was its last.
                     () => handedBackForTime,
                 ],
                 ...(temperature !== undefined ? { temperature } : {}),
@@ -1464,7 +1464,7 @@ export async function runAgentTurn(config, input) {
                         if (trimmed.newest !== undefined)
                             newestAnswerState = trimmed.newest;
                     }
-                    // The files this step would carry, within the turn's and the conversation's caps (ADR-0252 §2.11).
+                    // The files this step would carry, within the turn's and the conversation's caps.
                     const leftOutNow = fileGuard.beforeStep();
                     if (leftOutNow.length > 0) {
                         log('info', 'agent:tool', 'Files left out of the next step to keep within the cap', {
@@ -1580,7 +1580,7 @@ export async function runAgentTurn(config, input) {
                 if (!stopOf(abortController.signal))
                     throw err;
             }
-            // The model's tools no longer change with the page (ADR-0245 §2.2): what
+            // The model's tools no longer change with the page: what
             // the page offers reaches it in each answer, so the turn runs as one segment.
             break;
         }
@@ -1655,7 +1655,7 @@ export async function runAgentTurn(config, input) {
             promptTokens: usage.promptTokens,
             cacheReadTokens: usage.cacheReadTokens,
             cacheWriteTokens: usage.cacheWriteTokens,
-            // How the page was worked (ADR-0245 §2.6).
+            // How the page was worked.
             ...(client
                 ? {
                     ui: {
@@ -1726,7 +1726,7 @@ export async function runAgentTurn(config, input) {
         stopWatch.close();
     }
     /**
-     * The end of a stopped turn (ADR-0252 §2.4): settle what was in flight, store
+     * The end of a stopped turn: settle what was in flight, store
      * what the turn had produced, then say so. Persist first, announce after, as
      * a turn that ends by itself does.
      *
@@ -1757,7 +1757,7 @@ export async function runAgentTurn(config, input) {
                 clearTimeout(timer);
         }
         // A stopped turn leaves no live card: an approval it asked for as the stop came
-        // is withdrawn now, and a later turn records it as that (§2.6).
+        // is withdrawn now, and a later turn records it as that.
         const held = approvalHold;
         if (held && config.approvals?.withdraw) {
             try {
@@ -1835,7 +1835,7 @@ export async function runAgentTurn(config, input) {
             return true;
         };
         // Whether what the turn had produced was stored: a deadline stop that could not store it is
-        // not a stopped turn but one that ran out of time with nothing kept (ADR-0252 §6.4).
+        // not a stopped turn but one that ran out of time with nothing kept.
         let stored = true;
         if (config.beforeTurnComplete) {
             try {
@@ -1936,11 +1936,11 @@ turnMessageAt = null) {
     for (let idx = 0; idx < history.length; idx++) {
         const msg = history[idx];
         if (msg.role === 'user') {
-            // A message's files are in history as their reference lines, never their content (ADR-0252 §2.11).
+            // A message's files are in history as their reference lines, never their content.
             messages.push({ role: 'user', content: idx === turnMessageAt ? msg.content : withReferenceLines(msg.content, msg.attachments ?? undefined) });
         }
         else if (msg.role === 'assistant') {
-            // A stopped turn's last message says so after its text (ADR-0252 §2.3).
+            // A stopped turn's last message says so after its text.
             // A message that has only that carries the line as its whole text: an
             // empty text block is refused by a model provider.
             const stoppedLine = msg.stopped ? turnStoppedNote(msg.stopped) : null;