@anweat/dsh-browser 0.1.17 → 0.2.0-rc.1

package/lib/actions/run.js

@@ -0,0 +1,226 @@
+/**
+ * Action dispatch: validate arguments, check availability, run the executor
+ * under a deadline, and wrap everything in the result envelope.
+ *
+ * Both tool surfaces call {@link runAction}, so the envelope and the error
+ * codes are identical whether the model reaches an action through
+ * `browser_call` or through a flat per-action tool.
+ * @module dsh-browser/actions/run
+ */
+import { outcomeOf } from "./types.js";
+import { ACTIONS, findAction, traitsFor } from "./registry.js";
+import { actionUnavailableReason } from "../freedom.js";
+import { compactSchema, validateArgs } from "./schema.js";
+import { targetOf } from "./shared.js";
+import { DeadlineError, abortedByDeadline, hintFor, mapError } from "./errors.js";
+import { effectsOf, isJournaled, isObservation, redactUrl, scrubCall, summarize } from "../journal.js";
+/** Serialized-result cap; larger results get their longest strings shortened. */
+export const RESULT_CHAR_LIMIT = 100_000;
+function failure(action, executionStatus, error) {
+    return { ok: false, action, executionStatus, error };
+}
+/** Normalize an executor's return value into an object result. */
+function asResult(value) {
+    // A JSON round trip drops `undefined` members, which the Host's lossless-JSON output check would reject.
+    const plain = JSON.parse(JSON.stringify(value ?? null));
+    if (plain !== null && typeof plain === 'object' && !Array.isArray(plain))
+        return plain;
+    if (Array.isArray(plain))
+        return { items: plain };
+    return { value: plain };
+}
+/**
+ * Shorten the longest string fields until the serialized result fits. The
+ * result stays valid JSON; the envelope reports how much text was dropped.
+ */
+export function truncateResult(result, limit = RESULT_CHAR_LIMIT) {
+    if (JSON.stringify(result).length <= limit)
+        return { result };
+    let omitted = 0;
+    const copy = structuredClone(result);
+    const strings = [];
+    const walk = (value) => {
+        if (Array.isArray(value))
+            value.forEach((entry, index) => { if (typeof entry === 'string')
+                strings.push({ holder: value, key: index, length: entry.length });
+            else
+                walk(entry); });
+        else if (value && typeof value === 'object') {
+            for (const [key, entry] of Object.entries(value)) {
+                if (typeof entry === 'string')
+                    strings.push({ holder: value, key, length: entry.length });
+                else
+                    walk(entry);
+            }
+        }
+    };
+    walk(copy);
+    strings.sort((a, b) => b.length - a.length);
+    for (const slot of strings) {
+        const size = JSON.stringify(copy).length;
+        if (size <= limit)
+            break;
+        const text = slot.holder[slot.key];
+        const excess = size - limit;
+        const keep = Math.max(200, text.length - excess - 80);
+        if (keep >= text.length)
+            continue;
+        omitted += text.length - keep;
+        slot.holder[slot.key] = text.slice(0, keep) + '…[truncated]';
+    }
+    return { result: copy, truncation: { omitted, reason: `result exceeded ${limit} characters; longest text fields were shortened` } };
+}
+function withDeadline(run, timeoutMs, parent, settleMs = 0) {
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(parent.reason);
+    if (parent.aborted)
+        controller.abort(parent.reason);
+    else
+        parent.addEventListener('abort', onAbort, { once: true });
+    const work = run(controller.signal).then(value => ({ timedOut: false, value }));
+    // If the deadline wins, the work may still reject later; swallow it.
+    work.catch(() => { });
+    let timer;
+    let settleTimer;
+    const deadline = new Promise(resolve => {
+        timer = setTimeout(() => {
+            controller.abort(new DeadlineError('deadline'));
+            // A cooperative executor gets a bounded window to stop at its next safe point; if it returns inside the window, `work` wins the race below.
+            if (settleMs > 0)
+                settleTimer = setTimeout(() => resolve({ timedOut: true }), settleMs);
+            else
+                resolve({ timedOut: true });
+        }, timeoutMs);
+    });
+    return Promise.race([work, deadline]).finally(() => {
+        clearTimeout(timer);
+        clearTimeout(settleTimer);
+        parent.removeEventListener('abort', onAbort);
+    });
+}
+/** The session's journal, when the service keeps one (test doubles of the service may not). */
+function journalOf(ctx) {
+    try {
+        return ctx.service.journalFor?.(ctx.session);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Note the page the call is about to act on. Never fails the call. */
+async function beginJournal(name, args, ctx) {
+    const call = { args, sensitiveControl: false };
+    try {
+        call.before = ctx.service.pageStamp?.(ctx.session);
+        // A typed value's sensitivity depends on the control (type=password...), which only the page knows, and only before the call.
+        if (name === 'act.fill' || name === 'act.type') {
+            const target = targetOf(args, false);
+            if (target !== undefined && ctx.service.inputSensitivity)
+                call.sensitiveControl = await ctx.service.inputSensitivity(target, { session: ctx.session });
+        }
+    }
+    catch { /* the journal is evidence, not a precondition */ }
+    return call;
+}
+/** Record the finished call and return its seq (undefined for a call refused for its arguments: it never touched the page). Never fails the call. */
+function finishJournal(journal, call, name, mutating, envelope, ctx) {
+    try {
+        if (envelope.error?.code === 'INVALID_ARGS')
+            return undefined;
+        const seq = journal.allocate();
+        const after = ctx.service.pageStamp?.(ctx.session);
+        const scrubbed = scrubCall(name, call.args, seq, call.sensitiveControl);
+        const outcome = { ok: envelope.ok, executionStatus: envelope.executionStatus, ...envelope.error ? { errorCode: envelope.error.code } : {} };
+        const observation = isObservation(name);
+        const targetId = name === 'target.select' ? after?.targetId ?? call.before?.targetId : call.before?.targetId ?? after?.targetId;
+        const url = after?.url ? redactUrl(after.url).url : undefined;
+        const text = envelope.result?.text;
+        journal.add({
+            seq, action: name,
+            ...targetId !== undefined ? { targetId } : {},
+            ...call.before?.generation !== undefined ? { generationBefore: call.before.generation } : {},
+            ...after?.generation !== undefined ? { generationAfter: after.generation } : {},
+            ...scrubbed.locator ? { locator: scrubbed.locator } : {},
+            params: scrubbed.params, outcome, effects: effectsOf(mutating, outcome),
+            summary: summarize(name, envelope),
+            ...observation ? { observation: true } : {},
+            ...url ? { url } : {},
+            ...observation && envelope.ok && typeof text === 'string' ? { size: text.length } : {},
+        }, scrubbed.raw);
+        return seq;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Run one action and return the envelope. Never throws: every failure is a
+ * structured error the model can act on.
+ */
+export async function runAction(name, rawArgs, ctx, env) {
+    const label = typeof name === 'string' ? name : String(name);
+    const action = findAction(name);
+    if (!action) {
+        const close = typeof name === 'string' ? ACTIONS.filter(candidate => candidate.name.includes(name.split('.').pop() ?? name) || name.includes(candidate.group)).slice(0, 5).map(candidate => candidate.name) : [];
+        return failure(label, 'failed', {
+            code: 'UNKNOWN_ACTION',
+            message: `Unknown action: ${label}`,
+            hint: `Actions are named group.action. Call browser_index() to list groups${close.length ? `; similar: ${close.join(', ')}` : ''}.`,
+        });
+    }
+    const unavailable = actionUnavailableReason(action, env.mode, env.options, env.enabled);
+    if (unavailable) {
+        return failure(action.name, 'failed', { code: 'POLICY_DENIED', message: `Action ${action.name} is ${unavailable}`, hint: hintFor('POLICY_DENIED') });
+    }
+    const validation = validateArgs(action.params, rawArgs);
+    if (!validation.ok) {
+        return failure(action.name, 'failed', {
+            code: 'INVALID_ARGS',
+            message: validation.errors.join('; '),
+            hint: 'Fix the arguments to match the schema below and call again.',
+            schema: compactSchema(action.name, action.params),
+        });
+    }
+    // The mode may allow some operations of an action and not others (automation.develop: get yes, test no).
+    const operationUnavailable = actionUnavailableReason(action, env.mode, env.options, env.enabled, validation.value);
+    if (operationUnavailable) {
+        return failure(action.name, 'failed', { code: 'POLICY_DENIED', message: `Action ${action.name} is ${operationUnavailable}`, hint: hintFor('POLICY_DENIED') });
+    }
+    const traits = traitsFor(action, validation.value);
+    if (ctx.signal.aborted)
+        return failure(action.name, 'cancelled', { code: 'CANCELLED', message: 'cancelled before start', hint: hintFor('CANCELLED') });
+    const execute = async () => {
+        let workSignal = ctx.signal;
+        try {
+            const outcome = await withDeadline(signal => { workSignal = signal; return action.execute(validation.value, { ...ctx, signal }); }, action.timeoutMs, ctx.signal, action.settleMs);
+            if (outcome.timedOut) {
+                // The work may still finish after the deadline, so a side-effecting action has an unknown outcome.
+                const status = traits.mutating ? 'outcome_unknown' : 'failed';
+                return failure(action.name, status, {
+                    code: 'DEADLINE',
+                    message: `${action.name} did not finish within ${action.timeoutMs} ms`,
+                    hint: traits.mutating ? 'Outcome unknown: verify the page state with observe.read before retrying; do not blindly repeat a submit.' : hintFor('DEADLINE'),
+                });
+            }
+            // A result may carry its own outcome (a recipe that ran and failed still returns its whole report).
+            const own = outcomeOf(outcome.value);
+            const { result, truncation } = truncateResult(asResult(outcome.value));
+            return { ok: own?.ok ?? true, action: action.name, executionStatus: own?.executionStatus ?? 'completed', result, ...own?.error ? { error: own.error } : {}, ...truncation ? { truncation } : {} };
+        }
+        catch (error) {
+            const body = mapError(error, action.name, { signal: workSignal });
+            // The deadline stopped work that had not returned: for a side-effecting action the outcome is unknown.
+            if (abortedByDeadline(workSignal) && traits.mutating)
+                return failure(action.name, 'outcome_unknown', { ...body, code: 'DEADLINE', hint: 'Outcome unknown: verify the page state with observe.read before retrying; do not blindly repeat a submit.' });
+            return failure(action.name, body.code === 'CANCELLED' ? 'cancelled' : 'failed', body);
+        }
+    };
+    const journaled = isJournaled(action.name) ? journalOf(ctx) : undefined;
+    const call = journaled ? await beginJournal(action.name, validation.value, ctx) : undefined;
+    const envelope = await execute();
+    if (!journaled || !call)
+        return envelope;
+    const seq = finishJournal(journaled, call, action.name, traits.mutating, envelope, ctx);
+    return seq === undefined ? envelope : { ...envelope, seq };
+}
+//# sourceMappingURL=run.js.map

package/lib/actions/run.js.map

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

package/lib/actions/runtime.d.ts

@@ -0,0 +1,3 @@
+/** `runtime` group: runtime status and the Chromium installer. @module dsh-browser/actions/runtime */
+import type { ActionDef } from './types.ts';
+export declare const RUNTIME_ACTIONS: ActionDef[];

package/lib/actions/runtime.js

@@ -0,0 +1,33 @@
+/** `runtime` group: runtime status and the Chromium installer. @module dsh-browser/actions/runtime */
+const cap = (text) => text.slice(0, 2000);
+export const RUNTIME_ACTIONS = [
+    {
+        name: 'runtime.status',
+        group: 'runtime',
+        summary: 'Report runtime status: install state, automationMode, approval policies, usage buffer, this session\'s active page.',
+        notes: 'A page opened by another session is not reported.',
+        params: {},
+        approval: 'none', readOnly: true, mutating: false, concurrencySafe: true, timeoutMs: 15_000,
+        examples: [{ args: {} }],
+        async execute(_args, ctx) {
+            // Loaded here, not at the top: prompts.ts measures the catalog and so imports the registry that imports this file.
+            const { describePrompts } = await import("../prompts.js");
+            const status = await ctx.service.status({ session: ctx.session });
+            // The overrides in force (keys and lengths only) and what was ignored or is over budget, read from the live config.
+            return { ...status, prompts: describePrompts({ prompts: ctx.config.prompts, mode: ctx.config.automationMode, options: ctx.config.automationAssets, enabled: ctx.config.enabled }) };
+        },
+    },
+    {
+        name: 'runtime.install',
+        group: 'runtime',
+        summary: 'Install the bundled Playwright Chromium (large download). Run once if runtime.status reports chromium not installed.',
+        params: {},
+        approval: 'install', readOnly: false, mutating: false, concurrencySafe: false, timeoutMs: 600_000,
+        examples: [{ args: {} }],
+        async execute(_args, ctx) {
+            const result = await ctx.service.installChromium();
+            return { code: result.code, timedOut: result.timedOut, stdout: cap(result.stdout ?? ''), stderr: cap(result.stderr ?? '') };
+        },
+    },
+];
+//# sourceMappingURL=runtime.js.map

package/lib/actions/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/actions/runtime.ts"],"names":[],"mappings":"AAAA,sGAAsG;AAItG,MAAM,GAAG,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;AAEzD,MAAM,CAAC,MAAM,eAAe,GAAgB;IAC1C;QACE,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,SAAS;QAChB,OAAO,EAAE,qHAAqH;QAC9H,KAAK,EAAE,mDAAmD;QAC1D,MAAM,EAAE,EAAE;QACV,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM;QAC3F,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACxB,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;YACtB,mHAAmH;YACnH,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAA;YACzD,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAA;YACjE,oHAAoH;YACpH,OAAO,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,cAAc,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,gBAAgB,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,CAAA;QACrL,CAAC;KACF;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,KAAK,EAAE,SAAS;QAChB,OAAO,EAAE,sHAAsH;QAC/H,MAAM,EAAE,EAAE;QACV,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO;QACjG,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACxB,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;YACtB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,eAAe,EAAE,CAAA;YAClD,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAA;QAC7H,CAAC;KACF;CACF,CAAA"}

package/lib/actions/schema.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared sub-schemas plus the validator and renderers for action parameters.
+ *
+ * `LOCATOR_SCHEMA` and friends are defined exactly once. Actions reference them
+ * with `{ ref: 'locator' }`; the flat tool surface expands the reference inline
+ * (the Host needs a self-contained schema per tool) and the indexed surface
+ * prints them once in the L2 detail.
+ * @module dsh-browser/actions/schema
+ */
+import type { ParamNode, ParamSchema, SharedSchemaName } from './types.ts';
+export declare const SHARED_SCHEMAS: Record<SharedSchemaName, ParamNode>;
+/** The two params every element-targeting action accepts. */
+export declare const TARGET_PARAMS: ParamSchema;
+/** Optional guard of the act.* actions that change or press into the page. */
+export declare const EXPECT_PARAMS: ParamSchema;
+/** Expand every `ref` inline: the self-contained shape a flat tool needs. */
+export declare function expandNode(node: ParamNode): ParamNode;
+export declare function expandParams(params: ParamSchema): ParamSchema;
+export interface ValidationResult {
+    ok: boolean;
+    value: Record<string, unknown>;
+    errors: string[];
+}
+/** Validate call arguments against an action's parameter schema. */
+export declare function validateArgs(params: ParamSchema, args: unknown): ValidationResult;
+/** One-line parameter summary: `selector?: string, locator?: $locator`. */
+export declare function compactParams(params: ParamSchema): string;
+/** Compact schema block attached to INVALID_ARGS replies. */
+export declare function compactSchema(action: string, params: ParamSchema): string;
+/** Full parameter listing with descriptions, followed by each shared sub-schema once. */
+export declare function describeParams(params: ParamSchema): string[];

package/lib/actions/schema.js

@@ -0,0 +1,309 @@
+/**
+ * Shared sub-schemas plus the validator and renderers for action parameters.
+ *
+ * `LOCATOR_SCHEMA` and friends are defined exactly once. Actions reference them
+ * with `{ ref: 'locator' }`; the flat tool surface expands the reference inline
+ * (the Host needs a self-contained schema per tool) and the indexed surface
+ * prints them once in the L2 detail.
+ * @module dsh-browser/actions/schema
+ */
+const FRAME_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    description: 'Iframe to search inside. Use exactly one field.',
+    properties: {
+        selector: { type: 'string', description: 'CSS selector for an iframe.' },
+        name: { type: 'string', description: 'Frame name.' },
+        url: { type: 'string', description: 'Playwright frame URL/glob.' },
+    },
+};
+const LOCATOR_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    description: 'Element locator, strict: it must match exactly one element, else LOCATOR_AMBIGUOUS lists candidates. Use exactly one of selector, role, text, label, or testId.',
+    properties: {
+        selector: { type: 'string', description: 'CSS selector.' },
+        role: { type: 'string', description: 'Accessible role used by Playwright getByRole.' },
+        name: { type: 'string', description: 'Optional accessible name; valid only with role.' },
+        text: { type: 'string', description: 'Visible text used by Playwright getByText.' },
+        label: { type: 'string', description: 'Form label used by Playwright getByLabel.' },
+        exact: { type: 'boolean', description: 'Require an exact semantic match. Defaults to false.' },
+        testId: { type: 'string', description: 'data-testid value.' },
+        framePath: { type: 'array', items: { type: 'string' }, description: 'Nested iframes, outermost first, each a CSS selector. Alternative to frame.' },
+        index: { type: 'number', description: 'Pick the n-th match (0-based) of an ambiguous locator. Requires indexReason.' },
+        indexReason: { type: 'string', description: 'Why that match and not the others. Required with index.' },
+        frame: { ref: 'frame' },
+    },
+};
+const RECIPE_LOCATOR_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    description: 'v2, strict: one match or LOCATOR_AMBIGUOUS. One of role (+name, exact), label, text, testId, css.',
+    properties: {
+        role: { type: 'string' },
+        name: { type: 'string', description: 'with role' },
+        exact: { type: 'boolean' },
+        label: { type: 'string' },
+        text: { type: 'string' },
+        testId: { type: 'string' },
+        css: { type: 'string' },
+        framePath: { type: 'array', items: { type: 'string' }, description: 'iframe selectors, outermost first' },
+        index: { type: 'number', description: '0-based; needs indexReason' },
+        indexReason: { type: 'string' },
+        explicitFirst: { type: 'boolean', description: 'v1 converter marker' },
+    },
+};
+const RECIPE_STEP_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    description: 'v1: selector (first match). v2: locator (strict).',
+    properties: {
+        type: { type: 'string', required: true, enum: ['wait', 'click', 'fill', 'clear', 'type', 'press', 'select', 'check', 'hover', 'scroll', 'goto', 'extract', 'assert', 'screenshot'] },
+        condition: { type: 'string', enum: ['selector', 'locator', 'text', 'url', 'load', 'time'], description: 'wait kind' },
+        selector: { type: 'string', description: 'v1 CSS' },
+        locator: { ref: 'recipeLocator' },
+        value: { type: 'string', description: 'fill/type/select; wait text/url' },
+        allowEmpty: { type: 'boolean', description: 'v2 fill ""' },
+        text: { type: 'string', description: 'assert' },
+        urlIncludes: { type: 'string', description: 'v2 assert' },
+        url: { type: 'string', description: 'v2 goto, inside domains' },
+        key: { type: 'string' },
+        timeoutMs: { type: 'number', description: '1-30000; v2 extract/assert 5000' },
+        waitMs: { type: 'number' },
+        deltaY: { type: 'number' },
+        checked: { type: 'boolean' },
+        mode: { type: 'string', enum: ['text', 'html', 'links', 'attribute'] },
+        attribute: { type: 'string' },
+        limit: { type: 'number' },
+        as: { type: 'string', description: 'v2 extract output name' },
+    },
+};
+const POSTCONDITION_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    description: 'One of selector, text, urlIncludes, output (+ nonEmpty or allowEmpty true).',
+    properties: {
+        selector: { type: 'string', description: 'visible CSS' },
+        text: { type: 'string', description: 'visible text' },
+        urlIncludes: { type: 'string' },
+        output: { type: 'string', description: 'an extract as name' },
+        nonEmpty: { type: 'boolean' },
+        allowEmpty: { type: 'boolean' },
+        timeoutMs: { type: 'number', description: 'default 5000' },
+    },
+};
+const INPUT_SPEC_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    description: 'Typed input, checked and converted before running.',
+    properties: {
+        name: { type: 'string', required: true, description: 'placeholder name (double curly braces in steps)' },
+        type: { type: 'string', required: true, enum: ['string', 'number', 'enum'] },
+        required: { type: 'boolean', description: 'default true' },
+        example: { type: 'string', description: 'sample, as text' },
+        enumValues: { type: 'array', items: { type: 'string' }, description: 'for enum' },
+    },
+};
+const OUTPUT_SPEC_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    description: 'Named output of the extract step with the same as.',
+    properties: {
+        name: { type: 'string', required: true },
+        type: { type: 'string', required: true, enum: ['string', 'number', 'json'] },
+        dedupe: { type: 'boolean', description: 'drop repeated lines/elements' },
+    },
+};
+export const SHARED_SCHEMAS = {
+    frame: FRAME_SCHEMA,
+    locator: LOCATOR_SCHEMA,
+    recipeStep: RECIPE_STEP_SCHEMA,
+    recipeLocator: RECIPE_LOCATOR_SCHEMA,
+    postcondition: POSTCONDITION_SCHEMA,
+    inputSpec: INPUT_SPEC_SCHEMA,
+    outputSpec: OUTPUT_SPEC_SCHEMA,
+};
+/** The two params every element-targeting action accepts. */
+export const TARGET_PARAMS = {
+    selector: { type: 'string', description: 'CSS selector. Omit when locator is given; pass exactly one of selector or locator.' },
+    locator: { ref: 'locator' },
+};
+/** Optional guard of the act.* actions that change or press into the page. */
+export const EXPECT_PARAMS = {
+    expectGeneration: { type: 'number', description: 'generation from the last observe.read/act result; if the page navigated since, fails TARGET_STALE and does nothing.' },
+};
+function resolve(node) {
+    if (!node.ref)
+        return node;
+    const shared = SHARED_SCHEMAS[node.ref];
+    return { ...shared, ...node.description ? { description: node.description } : {} };
+}
+/** Expand every `ref` inline: the self-contained shape a flat tool needs. */
+export function expandNode(node) {
+    const resolved = resolve(node);
+    const { ref: _ref, ...rest } = resolved;
+    const out = { ...rest };
+    if (resolved.items)
+        out.items = expandNode(resolved.items);
+    if (resolved.properties)
+        out.properties = Object.fromEntries(Object.entries(resolved.properties).map(([key, value]) => [key, expandNode(value)]));
+    return out;
+}
+export function expandParams(params) {
+    return Object.fromEntries(Object.entries(params).map(([key, value]) => [key, expandNode(value)]));
+}
+const MAX_ERRORS = 6;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function describeType(value) {
+    if (Array.isArray(value))
+        return 'array';
+    if (value === null)
+        return 'null';
+    return typeof value;
+}
+function validateObject(properties, open, value, path, errors) {
+    if (!isRecord(value)) {
+        errors.push(`${path || 'args'}: expected object, got ${describeType(value)}`);
+        return undefined;
+    }
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        const node = properties[key];
+        if (!node) {
+            if (open)
+                out[key] = entry;
+            else
+                errors.push(`${path ? path + '.' : ''}${key}: unknown argument (allowed: ${Object.keys(properties).join(', ') || 'none'})`);
+            continue;
+        }
+        // Models often send null for an omitted optional value; treat it as absent.
+        if (entry === null || entry === undefined)
+            continue;
+        const checked = validateNode(node, entry, `${path ? path + '.' : ''}${key}`, errors);
+        if (checked !== undefined)
+            out[key] = checked;
+    }
+    for (const [key, node] of Object.entries(properties)) {
+        if (node.required && !(key in out) && !errors.some(error => error.startsWith(`${path ? path + '.' : ''}${key}:`))) {
+            errors.push(`${path ? path + '.' : ''}${key}: required`);
+        }
+    }
+    return out;
+}
+function validateNode(raw, value, path, errors) {
+    if (errors.length >= MAX_ERRORS)
+        return undefined;
+    const node = resolve(raw);
+    switch (node.type) {
+        case 'string':
+            if (typeof value !== 'string') {
+                errors.push(`${path}: expected string, got ${describeType(value)}`);
+                return undefined;
+            }
+            if (node.enum && !node.enum.includes(value)) {
+                errors.push(`${path}: must be one of ${node.enum.join(' | ')}`);
+                return undefined;
+            }
+            return value;
+        case 'number':
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                errors.push(`${path}: expected number, got ${describeType(value)}`);
+                return undefined;
+            }
+            return value;
+        case 'boolean':
+            if (typeof value !== 'boolean') {
+                errors.push(`${path}: expected boolean, got ${describeType(value)}`);
+                return undefined;
+            }
+            return value;
+        case 'array': {
+            if (!Array.isArray(value)) {
+                errors.push(`${path}: expected array, got ${describeType(value)}`);
+                return undefined;
+            }
+            if (!node.items)
+                return value;
+            const items = [];
+            value.forEach((entry, index) => {
+                const checked = validateNode(node.items, entry, `${path}[${index}]`, errors);
+                if (checked !== undefined)
+                    items.push(checked);
+            });
+            return items;
+        }
+        case 'object':
+            return validateObject(node.properties ?? {}, node.additionalProperties === true || !node.properties, value, path, errors);
+        default:
+            return value;
+    }
+}
+/** Validate call arguments against an action's parameter schema. */
+export function validateArgs(params, args) {
+    const errors = [];
+    const input = args === undefined || args === null ? {} : args;
+    const value = validateObject(params, false, input, '', errors) ?? {};
+    return { ok: errors.length === 0, value, errors };
+}
+// --- rendering ------------------------------------------------------------
+function refsOf(node, into) {
+    if (node.ref) {
+        into.add(node.ref);
+        refsOf(SHARED_SCHEMAS[node.ref], into);
+    }
+    if (node.items)
+        refsOf(node.items, into);
+    for (const child of Object.values(node.properties ?? {}))
+        refsOf(child, into);
+}
+function usedRefs(params) {
+    const refs = new Set();
+    for (const node of Object.values(params))
+        refsOf(node, refs);
+    return [...refs];
+}
+function compactNode(node) {
+    if (node.ref)
+        return '$' + node.ref;
+    switch (node.type) {
+        case 'string': return node.enum ? node.enum.map(value => JSON.stringify(value)).join('|') : 'string';
+        case 'number': return 'number';
+        case 'boolean': return 'boolean';
+        case 'array': return (node.items ? compactNode(node.items) : 'any') + '[]';
+        case 'object': return node.properties ? '{' + compactFields(node.properties) + '}' : 'object';
+        default: return 'any';
+    }
+}
+function compactFields(properties) {
+    return Object.entries(properties).map(([key, node]) => `${key}${node.required ? '' : '?'}: ${compactNode(node)}`).join(', ');
+}
+/** One-line parameter summary: `selector?: string, locator?: $locator`. */
+export function compactParams(params) {
+    return compactFields(params);
+}
+/** Compact schema block attached to INVALID_ARGS replies. */
+export function compactSchema(action, params) {
+    const lines = [`${action}(${compactFields(params)})`];
+    for (const ref of usedRefs(params))
+        lines.push(`$${ref} = {${compactFields(SHARED_SCHEMAS[ref].properties ?? {})}}`);
+    return lines.join('\n');
+}
+function describedFields(properties, indent) {
+    return Object.entries(properties).map(([key, node]) => {
+        const note = node.description ? ' - ' + node.description : '';
+        return `${indent}${key}${node.required ? '' : '?'}: ${compactNode(node)}${note}`;
+    });
+}
+/** Full parameter listing with descriptions, followed by each shared sub-schema once. */
+export function describeParams(params) {
+    const lines = Object.keys(params).length ? describedFields(params, '  ') : ['  (no arguments)'];
+    for (const ref of usedRefs(params)) {
+        const shared = SHARED_SCHEMAS[ref];
+        lines.push(`$${ref}${shared.description ? ' - ' + shared.description : ''}`);
+        lines.push(...describedFields(shared.properties ?? {}, '  '));
+    }
+    return lines;
+}
+//# sourceMappingURL=schema.js.map