@ouispec/agent-worker 0.1.0

package/dist/ui/observations.js

@@ -0,0 +1,236 @@
+/**
+ * Page state within the model's budget, problems first (ADR-0167).
+ *
+ * A surface may publish a `problems` observation: what its page cannot draw,
+ * load or read — a face it does not have and the text it therefore hides, an
+ * asset that failed, what an import could not reproduce. Those are exactly
+ * what the model must not miss before it tells the user a result, so when the
+ * page state is over budget they are kept whole and only the rest is cut. So
+ * are the statuses of the jobs the page follows: whether what an action
+ * started has finished is how the model knows it may say so.
+ */
+/** The observation id a surface reports its page's problems under. */
+export const PROBLEMS_OBSERVATION_ID = 'problems';
+/** Every surface's non-empty `problems`, by surface id; null when none reports any. */
+export function surfaceProblems(observations) {
+    const found = {};
+    for (const [surface, values] of Object.entries(observations)) {
+        const problems = values?.[PROBLEMS_OBSERVATION_ID];
+        if (Array.isArray(problems) ? problems.length > 0 : problems !== undefined && problems !== null) {
+            found[surface] = problems;
+        }
+    }
+    return Object.keys(found).length > 0 ? found : null;
+}
+/**
+ * Every job an action started that the page is following: each surface's
+ * `<surface>:<action>:status` observations (started, running, complete with
+ * what it made, failed with why), by surface id; null when there are none.
+ * The model is told an action like Generate is done only through these, so
+ * they must reach it whatever else the page reports.
+ */
+export function jobStatuses(observations) {
+    const found = {};
+    for (const [surface, values] of Object.entries(observations)) {
+        for (const [id, value] of Object.entries(values ?? {})) {
+            if (!isJobStatus(id))
+                continue;
+            (found[surface] ??= {})[id] = value;
+        }
+    }
+    return Object.keys(found).length > 0 ? found : null;
+}
+const isJobStatus = (observationId) => observationId.endsWith(':status');
+/** The observations without what is reported whole beside them: problems and job statuses. */
+function withoutKeptWhole(observations) {
+    return Object.fromEntries(Object.entries(observations).map(([surface, values]) => [
+        surface,
+        Object.fromEntries(Object.entries(values ?? {}).filter(([id]) => id !== PROBLEMS_OBSERVATION_ID && !isJobStatus(id))),
+    ]));
+}
+/** Rows past this in any list are summed up as "… and N more" at the first step of fitting an over-budget page state. */
+export const MAX_LIST_ROWS = 20;
+/**
+ * A list this short is never shortened: it is a field's choices (the engines a
+ * voice can speak with, a document's types), not a collection to browse.
+ */
+export const WHOLE_LIST_ROWS = 5;
+/** How far long lists are shortened, step by step; 0 gives only how many rows there are. */
+const LIST_STEPS = [MAX_LIST_ROWS, 10, WHOLE_LIST_ROWS, 0];
+/**
+ * What a page state reports that is never shortened: its fields, what is
+ * unavailable or busy, and a row's own schema (its options or range).
+ */
+const FIELD_KEYS = new Set(['values', 'unavailable', 'busy', 'schema']);
+/**
+ * Where a surface comes in the page state over budget: the surface the action
+ * acted on, then the pages and rooms, then shared parts of them, then anything
+ * else, and the shells (the chrome around every page: accounts, projects,
+ * navigation) last. A long project list in the shell must never crowd out the
+ * page the model is working on.
+ */
+function surfaceRank(surfaceId, acting) {
+    if (acting !== undefined && surfaceId === acting)
+        return 0;
+    if (surfaceId.startsWith('page:') || surfaceId.startsWith('room:'))
+        return 1;
+    if (surfaceId.startsWith('shared:'))
+        return 2;
+    if (surfaceId.startsWith('shell:') || surfaceId === 'app-shell')
+        return 4;
+    return 3;
+}
+/** A row the person has chosen (a selected card, the variant in use): kept however short its list gets. */
+const isChosen = (row) => row !== null && typeof row === 'object' && row.value === true;
+/** A list shortened to `limit` rows plus the chosen ones and how many more; only a count at 0. */
+function shortenRows(rows, limit) {
+    if (rows.length <= Math.max(limit, WHOLE_LIST_ROWS))
+        return rows;
+    if (limit === 0) {
+        const chosen = rows.filter(isChosen);
+        const count = `${rows.length - chosen.length}${chosen.length ? ' more' : ''} rows`;
+        return [...chosen, `${count}, not listed to fit the page state; name a row by its title`];
+    }
+    const kept = rows.slice(0, limit);
+    const chosen = rows.slice(limit).filter(isChosen);
+    return [...kept, ...chosen, `… and ${rows.length - kept.length - chosen.length} more`];
+}
+/**
+ * What the page shows (`shown`): facts that describe one row of a list (one per
+ * card) are shortened like the list; the page's own facts, such as those of the
+ * item open in a detail panel, are kept whole.
+ */
+function shortenShown(shown, limit) {
+    const perList = new Map();
+    const own = [];
+    for (const entry of shown) {
+        const item = entry?.item;
+        if (item === undefined)
+            own.push(entry);
+        else {
+            const id = String(entry.id);
+            perList.set(id, [...(perList.get(id) ?? []), entry]);
+        }
+    }
+    return [...own, ...[...perList.values()].flatMap((rows) => shortenRows(rows, limit))];
+}
+/**
+ * The value with every long list shortened to `limit` (see shortenRows); fields,
+ * what is unavailable or busy, and the page's own facts are left whole.
+ */
+function compactValue(value, limit) {
+    if (Array.isArray(value)) {
+        const rows = value.map((v) => compactValue(v, limit));
+        return shortenRows(rows, limit);
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, v]) => {
+            if (FIELD_KEYS.has(key))
+                return [key, v];
+            if (key === 'shown' && Array.isArray(v))
+                return [key, shortenShown(v, limit)];
+            return [key, compactValue(v, limit)];
+        }));
+    }
+    return value;
+}
+const size = (value) => JSON.stringify(value).length;
+/**
+ * The page state over budget, fitted step by step, cutting the least important
+ * first. The surfaces are ordered by rank. Then long lists are shortened (20
+ * rows, 10, 5, then only a count), on every other surface a step before the
+ * surface the action acted on. Lists of five rows or fewer, every field, what is
+ * unavailable or busy, the page's own facts and chosen rows are never shortened,
+ * so the item open in a detail panel stays whole beside a long list. Then whole
+ * surfaces are left out, the shells first, never the acting one. Only if that
+ * still does not fit is the rest cut.
+ */
+function fitted(observations, maxChars, acting) {
+    const base = Object.fromEntries(Object.entries(withoutKeptWhole(observations)).sort(([a], [b]) => surfaceRank(a, acting) - surfaceRank(b, acting)));
+    const actingPresent = acting !== undefined && acting in base;
+    // Each step is (others' limit, the acting surface's limit): the acting one lags a step behind.
+    const steps = [];
+    LIST_STEPS.forEach((limit, i) => {
+        if (actingPresent && i > 0)
+            steps.push([limit, LIST_STEPS[i - 1]]);
+        steps.push([limit, limit]);
+    });
+    let values = base;
+    let listStep;
+    for (const [others, own] of steps) {
+        values = Object.fromEntries(Object.entries(base).map(([id, v]) => [id, compactValue(v, id === acting ? own : others)]));
+        listStep = others;
+        if (size(values) <= maxChars)
+            return { values, listStep, omitted: [], fits: true };
+    }
+    const omitted = [];
+    const droppable = Object.keys(values)
+        .filter((id) => id !== acting)
+        .sort((a, b) => surfaceRank(b, acting) - surfaceRank(a, acting) || size(values[b]) - size(values[a]));
+    for (const id of droppable) {
+        if (Object.keys(values).length <= 1)
+            break;
+        values = Object.fromEntries(Object.entries(values).filter(([key]) => key !== id));
+        omitted.push(id);
+        if (size(values) <= maxChars)
+            return { values, listStep, omitted, fits: true };
+    }
+    return { values, listStep, omitted, fits: false };
+}
+/** What fitting did, in words. */
+function fitSummary(fit, maxChars, whole, acted) {
+    const lists = fit.listStep === undefined
+        ? ''
+        : fit.listStep === 0
+            ? `lists longer than ${WHOLE_LIST_ROWS} rows are given as a count`
+            : `long lists are shortened, to as few as ${Math.max(fit.listStep, WHOLE_LIST_ROWS)} rows, with how many more`;
+    const parts = [
+        lists,
+        'fields, the page’s own facts and chosen rows are kept whole',
+        acted ? 'the page you acted on comes first' : 'the pages come first and the shells last',
+        fit.omitted.length ? `left out to fit: ${fit.omitted.join(', ')}` : '',
+        fit.fits ? '' : `showing the first ${maxChars} characters`,
+        whole.length ? `with ${whole.join(' and ')} in full` : '',
+    ].filter(Boolean);
+    const text = parts.join('; ');
+    return `${text.charAt(0).toUpperCase()}${text.slice(1)}.`;
+}
+/**
+ * The observations as the model receives them: whole when they fit. Over
+ * budget, every surface's problems and job statuses are kept whole; the rest is
+ * fitted (see fitted): long lists shortened first, the page it acted on first
+ * and kept whole, and only if that still does not fit is the rest cut, saying so.
+ */
+export function boundObservations(observations, maxChars, actingSurfaceId) {
+    const json = JSON.stringify(observations);
+    if (json.length <= maxChars)
+        return observations;
+    const problems = surfaceProblems(observations);
+    const jobs = jobStatuses(observations);
+    const fit = fitted(observations, maxChars, actingSurfaceId);
+    const whole = [problems ? 'every surface’s problems' : '', jobs ? 'every job’s status' : ''].filter(Boolean);
+    return {
+        truncated: true,
+        note: `Page state is ${json.length} characters. ${fitSummary(fit, maxChars, whole, actingSurfaceId !== undefined)}`,
+        ...(problems ? { problems } : {}),
+        ...(jobs ? { jobs } : {}),
+        ...(fit.fits ? { values: fit.values } : { preview: JSON.stringify(fit.values).slice(0, maxChars) }),
+    };
+}
+/** The same, as the text of a `<page_state>` block. */
+export function observationsText(observations, maxChars) {
+    const json = JSON.stringify(observations);
+    if (json.length <= maxChars)
+        return json;
+    const problems = surfaceProblems(observations);
+    const jobs = jobStatuses(observations);
+    const fit = fitted(observations, maxChars, undefined);
+    const rest = JSON.stringify(fit.values);
+    const head = (problems ? `Problems (in full): ${JSON.stringify(problems)}\n` : '') +
+        (jobs ? `Jobs (in full): ${JSON.stringify(jobs)}\n` : '');
+    const tail = fit.fits
+        ? ` (fitted from ${json.length} characters. ${fitSummary(fit, maxChars, [], false)})`
+        : `… (truncated from ${json.length} characters)`;
+    return `${head}${head ? 'Values: ' : ''}${rest.slice(0, maxChars)}${tail}`;
+}
+//# sourceMappingURL=observations.js.map

package/dist/ui/observations.js.map

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

package/dist/ui/snapshot.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The client's surface snapshot, carried on the turn.
+ *
+ * A UI client puts what it can do right now — its mounted OUI surfaces and
+ * their latest observations — on the turn's context under `oui` (ADR-0209).
+ * The worker builds the turn's UI tools from it and from nothing else, so the
+ * tools always describe the client that sent the turn.
+ */
+import type { OUISurface, OUISurfaceSnapshot } from 'oui-spec/spec';
+/** The context key a UI client uses for its snapshot. */
+export declare const CLIENT_SNAPSHOT_KEY = "oui";
+/**
+ * Read and validate the snapshot from a turn's context. Returns null when the
+ * turn carries none (a client with no UI), and throws when it carries one that
+ * is malformed: a broken snapshot is a client bug that must not quietly turn
+ * into "this client has no UI".
+ */
+export declare function readClientSnapshot(context: Record<string, unknown> | null | undefined): OUISurfaceSnapshot | null;
+/** The turn's context without the snapshot. */
+export declare function withoutClientSnapshot(context: Record<string, unknown> | null | undefined): Record<string, unknown> | null | undefined;
+/**
+ * The turn's context without what the client's UI sent for the worker itself:
+ * its snapshot (the turn's UI tools) and its knowledge (rendered after the
+ * host's prompt). This is the context the host's prompt renders as prose.
+ */
+export declare function withoutClientUI(context: Record<string, unknown> | null | undefined): Record<string, unknown> | null | undefined;
+/**
+ * A stable fingerprint of what the client can do: its surface ids and each
+ * surface's action ids. Two snapshots with the same fingerprint give the
+ * model the same tools.
+ */
+export declare function capabilityFingerprint(surfaces: readonly OUISurface[]): string;
+//# sourceMappingURL=snapshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/ui/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGpE,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,kBAAkB,GAAG,IAAI,CA0BjH;AAED,+CAA+C;AAC/C,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAClD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAClD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAE5C;AAUD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAI7E"}

package/dist/ui/snapshot.js

@@ -0,0 +1,75 @@
+import { CLIENT_KNOWLEDGE_KEY } from './knowledge.js';
+/** The context key a UI client uses for its snapshot. */
+export const CLIENT_SNAPSHOT_KEY = 'oui';
+/**
+ * Read and validate the snapshot from a turn's context. Returns null when the
+ * turn carries none (a client with no UI), and throws when it carries one that
+ * is malformed: a broken snapshot is a client bug that must not quietly turn
+ * into "this client has no UI".
+ */
+export function readClientSnapshot(context) {
+    const raw = context?.[CLIENT_SNAPSHOT_KEY];
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== 'object') {
+        throw new Error(`[agent-sdk] context.${CLIENT_SNAPSHOT_KEY} must be an object`);
+    }
+    const { surfaces, observations, surfacesHash } = raw;
+    if (!Array.isArray(surfaces)) {
+        throw new Error(`[agent-sdk] context.${CLIENT_SNAPSHOT_KEY}.surfaces must be an array`);
+    }
+    for (const [i, s] of surfaces.entries()) {
+        if (!isSurface(s)) {
+            throw new Error(`[agent-sdk] context.${CLIENT_SNAPSHOT_KEY}.surfaces[${i}] is not an OUI surface manifest (id, name, description, actions[])`);
+        }
+    }
+    return {
+        surfaces: surfaces,
+        observations: observations && typeof observations === 'object'
+            ? observations
+            : {},
+        // The hash the worker sends back as `knownSurfaces` (oui-spec 0.6), when the client sent one.
+        ...(typeof surfacesHash === 'string' && surfacesHash ? { surfacesHash } : {}),
+    };
+}
+/** The turn's context without the snapshot. */
+export function withoutClientSnapshot(context) {
+    return omitKeys(context, [CLIENT_SNAPSHOT_KEY]);
+}
+/**
+ * The turn's context without what the client's UI sent for the worker itself:
+ * its snapshot (the turn's UI tools) and its knowledge (rendered after the
+ * host's prompt). This is the context the host's prompt renders as prose.
+ */
+export function withoutClientUI(context) {
+    return omitKeys(context, [CLIENT_SNAPSHOT_KEY, CLIENT_KNOWLEDGE_KEY]);
+}
+function omitKeys(context, keys) {
+    if (!context || !keys.some((k) => k in context))
+        return context;
+    return Object.fromEntries(Object.entries(context).filter(([k]) => !keys.includes(k)));
+}
+/**
+ * A stable fingerprint of what the client can do: its surface ids and each
+ * surface's action ids. Two snapshots with the same fingerprint give the
+ * model the same tools.
+ */
+export function capabilityFingerprint(surfaces) {
+    return surfaces
+        .map((s) => `${s.id}(${s.actions.map((a) => a.id).join(',')})`)
+        .join('|');
+}
+function isSurface(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const s = value;
+    return (typeof s.id === 'string' &&
+        typeof s.name === 'string' &&
+        typeof s.description === 'string' &&
+        Array.isArray(s.actions) &&
+        s.actions.every((a) => !!a &&
+            typeof a === 'object' &&
+            typeof a.id === 'string' &&
+            typeof a.description === 'string'));
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/ui/snapshot.js.map

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

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

@@ -0,0 +1,75 @@
+/**
+ * A turn's UI actions run one at a time, in the order the model called them.
+ *
+ * The model often asks for several UI actions in one response: fill a field,
+ * fill another, press the form's button. Each is a tool call, and tool calls
+ * from one response run concurrently, so a button press could reach the page
+ * before the fields were filled and find the button still disabled. UI actions
+ * act on one page, so they queue: each is dispatched only once the one before
+ * has answered, whether it succeeded or failed, and each result shows the page
+ * as the actions before it left it.
+ *
+ * The order is taken when the model's call arrives, not when the action is
+ * ready to dispatch. Whatever runs first (the orchestrator's input check, the
+ * host's tool policy, the "tool call started" emit) may finish in any order, so
+ * the caller reserves its place synchronously, before any `await`, and runs
+ * the action on that place later (`reserve`). On dev a name and a prompt called
+ * in that order ran prompt-first because the queue was joined only after those
+ * awaits.
+ *
+ * One sequence per turn, shared by every set of UI tools built during it (the
+ * tools are rebuilt when the page changes). Host tools are not queued.
+ *
+ * The sequence also holds the page's surfaces, by their hash (oui-spec 0.6):
+ * a request says which surfaces the worker holds (`knownSurfaces`), and the
+ * tab's answer then carries surfaces only when they changed. An answer
+ * without them is resolved here, from the hash it reports.
+ */
+import type { OUISurface } from 'oui-spec/spec';
+/** One place in a turn's UI order, taken when the call arrived. */
+export interface UISlot {
+    /**
+     * Run the action in this place: once every place taken before it has
+     * finished. The place is finished when the action settles, succeeded or not.
+     * Call it at most once.
+     */
+    run<T>(step: () => Promise<T>): Promise<T>;
+    /**
+     * Give the place up without running anything (the call was refused before it
+     * reached the page). Does nothing once `run` has been called: then the place
+     * is finished only when the action settles, so a caller that stops waiting
+     * (a timeout) cannot let the next action reach the page early.
+     */
+    release(): void;
+}
+export interface UISequence {
+    /** Take the next place in the order now, synchronously. Every place must be run or released. */
+    reserve(): UISlot;
+    /** Take the next place and run a UI action in it: `reserve().run(step)`. */
+    run<T>(step: () => Promise<T>): Promise<T>;
+    /** The surfaces on screen after the last answered action, or null before any has answered. */
+    latestSurfaces(): readonly OUISurface[] | null;
+    /**
+     * The hash of the surfaces the worker holds for the page — the snapshot's,
+     * or the last answer's — sent as a request's `knownSurfaces`; null when the
+     * page's surfaces are not known for certain, so the tab sends them all.
+     */
+    knownHash(): string | null;
+    /**
+     * The surfaces an answer stands for: those it carries, else those held under
+     * the hash it reports, else undefined (an answer from a tab that sends
+     * neither, or a hash the worker never held).
+     */
+    resolve(answer: {
+        surfaces?: OUISurface[];
+        surfacesHash?: string;
+    }): OUISurface[] | undefined;
+    /**
+     * Record the surfaces an answer (or the turn's snapshot) reported, with
+     * their hash. An answer whose surfaces cannot be resolved makes the page's
+     * surfaces unknown: the next request names none, and the tab sends them.
+     */
+    record(surfaces: readonly OUISurface[] | undefined, hash?: string): void;
+}
+export declare function createUISequence(): UISequence;
+//# sourceMappingURL=ui-sequence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ui-sequence.d.ts","sourceRoot":"","sources":["../../src/ui/ui-sequence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,mEAAmE;AACnE,MAAM,WAAW,MAAM;IACrB;;;;OAIG;IACH,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3C;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,gGAAgG;IAChG,OAAO,IAAI,MAAM,CAAC;IAClB,4EAA4E;IAC5E,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3C,8FAA8F;IAC9F,cAAc,IAAI,SAAS,UAAU,EAAE,GAAG,IAAI,CAAC;IAC/C;;;;OAIG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU,EAAE,GAAG,SAAS,CAAC;IAC9F;;;;OAIG;IACH,MAAM,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1E;AAKD,wBAAgB,gBAAgB,IAAI,UAAU,CAgE7C"}

package/dist/ui/ui-sequence.js

@@ -0,0 +1,73 @@
+/** How many surface sets the sequence keeps by hash: the page, and the few it was just on. */
+const HELD_SURFACE_SETS = 8;
+export function createUISequence() {
+    let tail = Promise.resolve();
+    let latest = null;
+    let latestHash = null;
+    // Surface sets by hash, oldest first, at most HELD_SURFACE_SETS.
+    const held = new Map();
+    const hold = (hash, surfaces) => {
+        held.delete(hash);
+        held.set(hash, surfaces);
+        while (held.size > HELD_SURFACE_SETS)
+            held.delete(held.keys().next().value);
+    };
+    function reserve() {
+        const before = tail;
+        let finish;
+        const finished = new Promise((resolve) => {
+            finish = resolve;
+        });
+        // The next place waits for this one, and so for every place before it,
+        // even when this one is released without running.
+        tail = before.then(() => finished);
+        let used = false;
+        return {
+            run(step) {
+                if (used)
+                    throw new Error('[agent-sdk] a UI slot runs one action');
+                used = true;
+                const next = before.then(step);
+                // A failed action does not hold up the ones after it.
+                next.then(finish, finish);
+                return next;
+            },
+            release() {
+                if (used)
+                    return;
+                used = true;
+                finish();
+            },
+        };
+    }
+    return {
+        reserve,
+        run: (step) => reserve().run(step),
+        latestSurfaces: () => latest,
+        knownHash: () => latestHash,
+        resolve(answer) {
+            if (answer.surfaces)
+                return answer.surfaces;
+            return answer.surfacesHash ? held.get(answer.surfacesHash) : undefined;
+        },
+        record(surfaces, hash) {
+            if (surfaces) {
+                latest = surfaces;
+                latestHash = hash ?? null;
+                if (hash)
+                    hold(hash, [...surfaces]);
+            }
+            else if (hash !== undefined && held.has(hash)) {
+                // Unchanged, or back to a set held before: that set is the page now.
+                latest = held.get(hash);
+                latestHash = hash;
+                hold(hash, held.get(hash));
+            }
+            else {
+                // What the page offers now is not known for certain: ask for it whole.
+                latestHash = null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=ui-sequence.js.map

package/dist/ui/ui-sequence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-sequence.js","sourceRoot":"","sources":["../../src/ui/ui-sequence.ts"],"names":[],"mappings":"AAyEA,8FAA8F;AAC9F,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B,MAAM,UAAU,gBAAgB;IAC9B,IAAI,IAAI,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5C,IAAI,MAAM,GAAiC,IAAI,CAAC;IAChD,IAAI,UAAU,GAAkB,IAAI,CAAC;IACrC,iEAAiE;IACjE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC7C,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,QAAsB,EAAE,EAAE;QACpD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAClB,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC,IAAI,GAAG,iBAAiB;YAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAe,CAAC,CAAC;IACxF,CAAC,CAAC;IAEF,SAAS,OAAO;QACd,MAAM,MAAM,GAAG,IAAI,CAAC;QACpB,IAAI,MAAmB,CAAC;QACxB,MAAM,QAAQ,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC7C,MAAM,GAAG,OAAO,CAAC;QACnB,CAAC,CAAC,CAAC;QACH,uEAAuE;QACvE,kDAAkD;QAClD,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,IAAI,GAAG,KAAK,CAAC;QACjB,OAAO;YACL,GAAG,CAAI,IAAsB;gBAC3B,IAAI,IAAI;oBAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;gBACnE,IAAI,GAAG,IAAI,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC/B,sDAAsD;gBACtD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAC1B,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO;gBACL,IAAI,IAAI;oBAAE,OAAO;gBACjB,IAAI,GAAG,IAAI,CAAC;gBACZ,MAAM,EAAE,CAAC;YACX,CAAC;SACF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO;QACP,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC;QAClC,cAAc,EAAE,GAAG,EAAE,CAAC,MAAM;QAC5B,SAAS,EAAE,GAAG,EAAE,CAAC,UAAU;QAC3B,OAAO,CAAC,MAAM;YACZ,IAAI,MAAM,CAAC,QAAQ;gBAAE,OAAO,MAAM,CAAC,QAAQ,CAAC;YAC5C,OAAO,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACzE,CAAC;QACD,MAAM,CAAC,QAAQ,EAAE,IAAI;YACnB,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,GAAG,QAAQ,CAAC;gBAClB,UAAU,GAAG,IAAI,IAAI,IAAI,CAAC;gBAC1B,IAAI,IAAI;oBAAE,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;YACtC,CAAC;iBAAM,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAChD,qEAAqE;gBACrE,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;gBACzB,UAAU,GAAG,IAAI,CAAC;gBAClB,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC,CAAC;YAC9B,CAAC;iBAAM,CAAC;gBACN,uEAAuE;gBACvE,UAAU,GAAG,IAAI,CAAC;YACpB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,59 @@
+/**
+ * UI tools: one tool per action of every surface the client has mounted.
+ *
+ * Calling one sends an OUI action request to the client that sent the turn
+ * and waits for its answer (ADR-0209 D2). The model gets what really happened
+ * — the action's result or error — and what the page offers afterwards.
+ */
+import type { OUIActionResult, OUISurface } from 'oui-spec/spec';
+import type { RegisteredTool } from '../tools/types.js';
+import type { UIActionChannel } from './channel.js';
+import { type UISequence } from './ui-sequence.js';
+export interface UIToolDependencies {
+    channel: UIActionChannel;
+    /** How long to wait for the client's answer. */
+    resultTimeoutMs: number;
+    /** The surfaces the model's current tools were built from. */
+    currentSurfaces(): readonly OUISurface[];
+    /** Called with every answer, before the model sees it. */
+    onResult(result: OUIActionResult): void;
+    /** Largest observation payload returned to the model, in characters. */
+    maxObservationChars?: number;
+    /**
+     * When the turn must stop waiting for work an action started, so the model
+     * still has time to answer: epoch ms. An action that is still running then is
+     * reported as running, never as done. Unbounded when not given.
+     */
+    waitDeadline?: () => 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
+     * one is made for these tools when none is given.
+     */
+    sequence?: UISequence;
+}
+export interface UIToolCollision {
+    actionId: string;
+    keptSurface: string;
+    droppedSurface: string;
+}
+/**
+ * When to send a request again while no tab has received it (dispatchUntilAnswered):
+ * after 1 s, then 2, 4, and every 8 s.
+ */
+export declare const FIRST_RESEND_AFTER_MS = 1000;
+export declare const MAX_RESEND_AFTER_MS = 8000;
+/**
+ * When to send a request a tab received again, if its answer has not come: by
+ * then longer than the tab waits before answering a repeat (oui-spec's
+ * `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;
+/** Build the UI tools for a set of surfaces. The first surface to declare an action id keeps it. */
+export declare function buildUITools(surfaces: readonly OUISurface[], deps: UIToolDependencies): {
+    tools: RegisteredTool[];
+    collisions: UIToolCollision[];
+};
+//# sourceMappingURL=ui-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ui-tools.d.ts","sourceRoot":"","sources":["../../src/ui/ui-tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAA+B,eAAe,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC9F,OAAO,KAAK,EAAE,cAAc,EAA6C,MAAM,mBAAmB,CAAC;AACnG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAErE,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,eAAe,CAAC;IACzB,gDAAgD;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,eAAe,IAAI,SAAS,UAAU,EAAE,CAAC;IACzC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IACxC,wEAAwE;IACxE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAGD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAC3C,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AACzC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,QAAa,CAAC;AAE9C,oGAAoG;AACpG,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,SAAS,UAAU,EAAE,EAC/B,IAAI,EAAE,kBAAkB,GACvB;IAAE,KAAK,EAAE,cAAc,EAAE,CAAC;IAAC,UAAU,EAAE,eAAe,EAAE,CAAA;CAAE,CAkB5D"}