@e2edev/e2e 0.2.0

package/dist/agent/default-agent.js

@@ -0,0 +1,354 @@
+/**
+ * The default step executor (RFC0001, layer 4 golden path): the tool-loop
+ * chassis plus the grammar toolset. Every mutating tool returns the
+ * updated screen; verdicts, budgets, hard stops, loop guards, wind-down, and
+ * the transcript come from the chassis (`tool-loop.ts`) unchanged.
+ */
+import { z } from 'zod';
+import { aiSdk } from './ai-sdk.js';
+import { AgentError, isAgentError } from './error.js';
+import { RUNTIME_CODES, } from './executor.js';
+import { createToolLoopExecutor } from './tool-loop.js';
+import { isDefinedTool, toolAppliesTo } from './tool.js';
+const BASE_RULES = `You are an autonomous end-to-end testing agent executing exactly one test step against a real application.
+
+Rules:
+- Work only toward the given step; do not start the next step or explore beyond it.
+- Use the tools to inspect and act. Node ids like "n42" are valid only for the newest observation; after any action, use ids from the latest "Updated screen" snapshot.
+- Issue at most ONE mutating tool call per turn: every mutation refreshes the screen and invalidates all earlier node ids, so a second action batched in the same turn targets a stale screen and fails.
+- Never invent node ids. If the target is not on screen, bring it on screen with the tools you have (scroll, navigate) or conclude.`;
+/** How many trailing screen snapshots stay verbatim in the transcript. */
+const SNAPSHOT_PRESERVE_COUNT = 2;
+const SNAPSHOT_PATTERN = /(?:Updated|Current) screen \(revision /;
+/** Builds the default AI SDK step executor. */
+export function createAgent(options = {}) {
+    const userTools = validateUserTools(options.tools);
+    const system = [BASE_RULES, options.system]
+        .filter((part) => part !== undefined && part.trim() !== '')
+        .join('\n\n');
+    return createToolLoopExecutor({
+        name: 'e2e-default-agent',
+        version: '2',
+        ...(options.model === undefined ? {} : { model: options.model }),
+        system,
+        ...(options.maxTurns === undefined ? {} : { maxTurns: options.maxTurns }),
+        compactMessages: compactSnapshotHistory,
+        tools: (context, helpers) => ({
+            ...wrapUserTools(context, helpers, userTools),
+            ...buildGrammarTools(context, helpers),
+        }),
+        buildPrompt: async (context) => {
+            const observation = await context.observe();
+            const parts = [
+                context.step.kind === 'assert'
+                    ? `Judge whether this assertion holds; do not change application state: ${context.step.instruction}`
+                    : `Execute this test step: ${context.step.instruction}`,
+            ];
+            if (context.step.params !== undefined) {
+                parts.push(`Step parameters:\n${JSON.stringify(context.step.params)}`);
+            }
+            if (context.replayedPrefix !== undefined) {
+                parts.push(formatReplayedPrefix(context.replayedPrefix));
+            }
+            if (context.ledger !== '') {
+                parts.push(`Previously completed steps:\n${context.ledger}`);
+            }
+            parts.push(`Current screen (revision ${observation.revision}):\n${observation.text}`);
+            return parts.join('\n\n');
+        },
+    });
+}
+/**
+ * The mid-step hand-off notice (RFC0001 layer 4): prose summaries and a reason
+ * token, replacing any ordinary prior-run hint. The agent continues from live
+ * state; redoing a replayed action would double-commit a mutation.
+ */
+function formatReplayedPrefix(prefix) {
+    const lines = prefix.replayedActions.map((summary, index) => `${index + 1}. ${summary}`);
+    return [
+        'Cached replay already performed these recorded actions for this step:',
+        ...lines,
+        `Replay stopped (${prefix.stopReason}) after ${prefix.replayedActions.length} of ${prefix.totalActions} recorded actions.`,
+        ...(prefix.stopReason === 'end-mismatch'
+            ? [
+                'Every recorded action ran, but the screen does not show the recorded end state. ' +
+                    'Check whether the step actually took effect before doing anything — the recorded flow may have silently failed to commit.',
+            ]
+            : []),
+        ...(prefix.uncertainAction === undefined
+            ? []
+            : [
+                `WARNING: the next action (${prefix.uncertainAction}) failed with an UNKNOWN commit state — ` +
+                    'its input may have reached the app. Verify the current state before doing anything like it again.',
+            ]),
+        'Continue the step from the CURRENT screen state shown below — do NOT redo the actions above.',
+    ].join('\n');
+}
+/**
+ * The default toolset: thin AI SDK tools over the harness action grammar,
+ * limited to the verbs the target's backend declared. A verb the surface cannot
+ * honor is not offered at all, so the model never learns vocabulary it can only
+ * be rejected on.
+ */
+function buildGrammarTools(context, helpers) {
+    const { guard } = helpers;
+    const { verbs } = context.target;
+    /** Re-observes after a mutating action so the model always sees the result. */
+    const acted = async (description) => {
+        const observation = await context.observe();
+        return `${description}\n\nUpdated screen (revision ${observation.revision}):\n${observation.text}`;
+    };
+    const target = z
+        .string()
+        .min(1)
+        .describe('Node id from the newest observation, e.g. "n42"');
+    // The chassis loads the AI SDK before building tools, so reading the
+    // cached instance here cannot race the optional-peer loader.
+    const { tool } = aiSdk();
+    const tools = {
+        observe: tool({
+            description: 'Capture a fresh observation of the current screen without acting.',
+            inputSchema: z.object({}),
+            execute: () => guard(async () => {
+                const observation = await context.observe();
+                return `Current screen (revision ${observation.revision}):\n${observation.text}`;
+            }),
+        }),
+    };
+    if (verbs.has('tap')) {
+        tools['tap'] = tool({
+            description: 'Tap or click one node.',
+            inputSchema: z.object({ target }),
+            execute: ({ target: id }) => guard(async () => {
+                await context.actions.tap({ id });
+                return acted(`Tapped #${id}.`);
+            }),
+        });
+    }
+    if (verbs.has('type')) {
+        tools['type'] = tool({
+            description: 'Type a plain-text value into one input node. Replaces the current value.',
+            inputSchema: z.object({ target, value: z.string() }),
+            execute: ({ target: id, value }) => guard(async () => {
+                await context.actions.type({ id }, value);
+                return acted(`Typed into #${id}.`);
+            }),
+        });
+    }
+    if (verbs.has('press')) {
+        tools['press'] = tool({
+            description: 'Send one key (e.g. "Enter", "Escape", "Tab") to one node.',
+            inputSchema: z.object({ target, key: z.string().min(1).max(64) }),
+            execute: ({ target: id, key }) => guard(async () => {
+                await context.actions.press({ id }, key);
+                return acted(`Pressed ${key} on #${id}.`);
+            }),
+        });
+    }
+    if (verbs.has('select')) {
+        tools['select'] = tool({
+            description: 'Pick one option from a select-like control by its visible label.',
+            inputSchema: z.object({ target, value: z.string().min(1) }),
+            execute: ({ target: id, value }) => guard(async () => {
+                await context.actions.select({ id }, value);
+                return acted(`Selected "${value}" in #${id}.`);
+            }),
+        });
+    }
+    if (verbs.has('scroll')) {
+        const direction = z.enum(['up', 'down', 'left', 'right']);
+        // Node-targeted scrolling rides `perform`; without it only the viewport scrolls.
+        tools['scroll'] = verbs.has('tap')
+            ? tool({
+                description: 'Scroll the viewport, or one scrollable node when target is given.',
+                inputSchema: z.object({ direction, target: target.optional() }),
+                execute: ({ direction: way, target: id }) => guard(async () => {
+                    await context.actions.scroll(way, id === undefined ? undefined : { id });
+                    return acted(`Scrolled ${way}.`);
+                }),
+            })
+            : tool({
+                description: 'Scroll the viewport.',
+                inputSchema: z.object({ direction }),
+                execute: ({ direction: way }) => guard(async () => {
+                    await context.actions.scroll(way);
+                    return acted(`Scrolled ${way}.`);
+                }),
+            });
+    }
+    if (verbs.has('navigate')) {
+        tools['navigate'] = tool({
+            description: 'Navigate to a URL or app-relative path within the allowed origins.',
+            inputSchema: z.object({ url: z.string().min(1) }),
+            execute: ({ url }) => guard(async () => {
+                await context.actions.navigate(url);
+                return acted(`Navigated to ${url}.`);
+            }),
+        });
+    }
+    // Offered only when the step declared secrets and the surface can fill: an
+    // empty vocabulary is better than a tool the model can only be rejected on.
+    if (verbs.has('typeSecret') && context.step.secrets.length > 0) {
+        tools['type_secret'] = tool({
+            description: 'Fill one declared secret credential into a secure input field; the plaintext never passes through you. Available: ' +
+                context.step.secrets.map((secret) => `"${secret.name}" (${secret.purpose})`).join(', ') +
+                '.',
+            inputSchema: z.object({ target, name: z.string().min(1) }),
+            execute: ({ target: id, name }) => guard(async () => {
+                await context.actions.typeSecret({ id }, name);
+                return acted(`Filled secret "${name}" into #${id}.`);
+            }),
+        });
+    }
+    return tools;
+}
+/**
+ * Compacts stale screen snapshots out of the history: the initial prompt's
+ * `Current screen` and every tool result's `Updated screen`.
+ *
+ * Only the newest observations describe the screen the model is acting on;
+ * every older tree is dead weight that grows the prompt linearly with turn
+ * count - and the very first tree, in the user prompt, is the oldest of all.
+ * A stale snapshot keeps what preceded the tree (the instruction, or what
+ * the action did) and loses the tree. Returns the input array unchanged when
+ * there is nothing to compact, so the caller can skip the messages override.
+ */
+function compactSnapshotHistory(messages) {
+    const total = messages.reduce((count, message) => count + snapshotParts(message).filter((text) => text !== undefined).length, 0);
+    let stale = total - SNAPSHOT_PRESERVE_COUNT;
+    if (stale <= 0)
+        return messages;
+    return messages.map((message) => {
+        if (stale <= 0)
+            return message;
+        if (message.role === 'user') {
+            if (typeof message.content === 'string') {
+                if (!SNAPSHOT_PATTERN.test(message.content))
+                    return message;
+                stale -= 1;
+                return { ...message, content: elideSnapshot(message.content) };
+            }
+            const content = message.content.map((part) => {
+                if (stale <= 0 || part.type !== 'text' || !SNAPSHOT_PATTERN.test(part.text))
+                    return part;
+                stale -= 1;
+                return { ...part, text: elideSnapshot(part.text) };
+            });
+            return { ...message, content };
+        }
+        if (message.role !== 'tool')
+            return message;
+        const texts = snapshotParts(message);
+        if (!texts.some((text) => text !== undefined))
+            return message;
+        const content = message.content.map((part, index) => {
+            const text = texts[index];
+            if (text === undefined || stale <= 0)
+                return part;
+            stale -= 1;
+            return { ...part, output: { type: 'text', value: elideSnapshot(text) } };
+        });
+        return { ...message, content };
+    });
+}
+/** Everything before the snapshot marker, then the elision notice in place of the tree. */
+function elideSnapshot(text) {
+    const at = text.search(SNAPSHOT_PATTERN);
+    const head = at <= 0 ? (text.split('\n', 1)[0] ?? '') : text.slice(0, at).trimEnd();
+    return `${head}\n[stale screen snapshot elided; act on the newest observation]`;
+}
+/** Per-part snapshot text of one message; undefined for non-snapshot parts. */
+function snapshotParts(message) {
+    if (message.role === 'user') {
+        if (typeof message.content === 'string') {
+            return [SNAPSHOT_PATTERN.test(message.content) ? message.content : undefined];
+        }
+        return message.content.map((part) => part.type === 'text' && SNAPSHOT_PATTERN.test(part.text) ? part.text : undefined);
+    }
+    if (message.role !== 'tool')
+        return [];
+    return message.content.map((part) => {
+        if (part.type !== 'tool-result')
+            return undefined;
+        const output = part.output;
+        if (output.type !== 'text' || typeof output.value !== 'string')
+            return undefined;
+        return SNAPSHOT_PATTERN.test(output.value) ? output.value : undefined;
+    });
+}
+/** Validates `defineTool` values and reserved names once, at construction. */
+function validateUserTools(tools) {
+    if (tools === undefined)
+        return {};
+    for (const [name, defined] of Object.entries(tools)) {
+        if (!isDefinedTool(defined)) {
+            throw new AgentError('POLICY_DENIED', `tool "${name}" was not created with defineTool; undeclared semantics are not trusted`);
+        }
+        if (name === 'complete_step') {
+            throw new AgentError('POLICY_DENIED', 'the complete_step tool name is reserved');
+        }
+        if (defined.tool.execute === undefined) {
+            throw new AgentError('POLICY_DENIED', `tool "${name}" has no execute function`);
+        }
+    }
+    return tools;
+}
+/**
+ * Wraps project tools so they run the same accounting pipeline as the
+ * grammar: every call is recorded, a mutating tool consumes an action-budget
+ * slot - refused before it runs once the ceiling is reached, consumed whether
+ * it succeeds or fails, exactly like a grammar action - and a runtime hard
+ * stop ends the loop. Any other failure goes back to the model as text it can
+ * react to, never as a provider failure of the step.
+ */
+function wrapUserTools(context, helpers, tools) {
+    const wrapped = {};
+    for (const [name, defined] of Object.entries(tools)) {
+        // A tool scoped to other platforms is not offered, so the model never
+        // learns a verb the surface cannot honor.
+        if (!toolAppliesTo(defined, context.target.platform))
+            continue;
+        // validateUserTools rejected any tool without execute at construction.
+        const execute = defined.tool.execute.bind(defined.tool);
+        const mutates = defined.annotations.mutates;
+        wrapped[name] = {
+            ...defined.tool,
+            execute: async (input, executionOptions) => {
+                if (helpers.concluding()) {
+                    return 'The step is already concluding; no further actions run.';
+                }
+                if (mutates && context.budgets.actionsUsed() >= context.budgets.maxActions) {
+                    const stop = new AgentError('STEP_BUDGET_EXHAUSTED', `the step exhausted its action budget of ${context.budgets.maxActions}`);
+                    helpers.reportHardStop(stop);
+                    return `HARD STOP (${stop.code}): ${stop.message}`;
+                }
+                const startedMs = Date.now();
+                let attempted = false;
+                try {
+                    attempted = true;
+                    return await execute(input, executionOptions);
+                }
+                catch (cause) {
+                    if (isAgentError(cause) && RUNTIME_CODES.has(cause.code)) {
+                        helpers.reportHardStop(cause);
+                        return `HARD STOP (${cause.code}): ${cause.message}`;
+                    }
+                    return `Tool "${name}" failed: ${cause instanceof Error ? cause.message : String(cause)}`;
+                }
+                finally {
+                    if (attempted) {
+                        try {
+                            context.budgets.recordToolCall({ name, mutates, durationMs: Date.now() - startedMs });
+                        }
+                        catch (cause) {
+                            if (isAgentError(cause) && RUNTIME_CODES.has(cause.code))
+                                helpers.reportHardStop(cause);
+                        }
+                    }
+                }
+            },
+        };
+    }
+    return wrapped;
+}
+//# sourceMappingURL=default-agent.js.map

package/dist/agent/default-agent.js.map

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

package/dist/agent/error.d.ts

@@ -0,0 +1,53 @@
+/** Runner-owned agent error classification (spec 02-test-api.md, 06-cli.md). */
+import { E2EError, type ErrorCategory } from '../internal/errors.ts';
+import type { AgentErrorCode } from '../types.ts';
+/**
+ * What a `blocked` verdict names as the obstacle. Mirrors the platform's
+ * categories exactly: the first four have external owners (fix the
+ * credential, the environment, the seed data, the setup); `automation` means
+ * the agent itself ran out of room and says nothing about the product.
+ */
+export type BlockedCategory = 'credentials' | 'environment' | 'seed_data' | 'test_setup' | 'automation';
+/**
+ * The single source of truth for the closed agent code set: exit/result class
+ * per 06-cli.md, plus the blocked category for codes a `blocked` verdict may
+ * carry. The model never selects a code, a category, or a blocked category —
+ * everything derives from this table.
+ */
+export declare const AGENT_CODE_TABLE: Readonly<Record<AgentErrorCode, {
+    category: ErrorCategory;
+    blockedCategory?: BlockedCategory;
+}>>;
+/** Exit/result class per code; derived from the one table. */
+export declare const CATEGORY_BY_CODE: Readonly<Record<AgentErrorCode, ErrorCategory>>;
+/** The blocked category a code names, or undefined when it is not blockable. */
+export declare function blockedCategoryOf(code: AgentErrorCode): BlockedCategory | undefined;
+/**
+ * Runner-classified agent failure (spec api/e2e.d.ts). It extends the internal
+ * error base so category, exit code, retry eligibility, and report
+ * serialization stay consistent with every other runner error.
+ */
+export declare class AgentError extends E2EError {
+    readonly code: AgentErrorCode;
+    readonly explanation: string;
+    readonly screenshot?: string;
+    /** True when this failure reports a blocked step, not a product failure. */
+    readonly blocked: boolean;
+    constructor(code: AgentErrorCode, explanation: string, options?: {
+        screenshot?: string;
+        cause?: unknown;
+        blocked?: boolean;
+    });
+}
+/**
+ * Maps any runner error raised inside an invocation onto the closed agent code
+ * set. Model prose can never select a code.
+ */
+export declare function toAgentError(cause: unknown): AgentError;
+/**
+ * True when a thrown value is an agent error from this or another realm.
+ * Identity rides on a global symbol marker, not the class name, so subclasses
+ * keep honest names and `instanceof` never spans realms.
+ */
+export declare function isAgentError(value: unknown): value is AgentError;
+//# sourceMappingURL=error.d.ts.map

package/dist/agent/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/agent/error.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,OAAO,EAAiB,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GACvB,aAAa,GACb,aAAa,GACb,WAAW,GACX,YAAY,GACZ,YAAY,CAAC;AAEjB;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CACrC,MAAM,CAAC,cAAc,EAAE;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,eAAe,CAAC,EAAE,eAAe,CAAA;CAAE,CAAC,CAuBvF,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,aAAa,CAAC,CAGjC,CAAC;AAE7C,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,eAAe,GAAG,SAAS,CAEnF;AAKD;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,QAAQ;IACtC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,YACE,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,EAS1E;CACF;AAKD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAavD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAOhE"}

package/dist/agent/error.js

@@ -0,0 +1,94 @@
+/** Runner-owned agent error classification (spec 02-test-api.md, 06-cli.md). */
+import { classifyError, E2EError } from '../internal/errors.js';
+/**
+ * The single source of truth for the closed agent code set: exit/result class
+ * per 06-cli.md, plus the blocked category for codes a `blocked` verdict may
+ * carry. The model never selects a code, a category, or a blocked category —
+ * everything derives from this table.
+ */
+export const AGENT_CODE_TABLE = {
+    AUTH_CREDENTIAL_UNAVAILABLE: { category: 'configuration', blockedCategory: 'credentials' },
+    AUTH_CREDENTIAL_INVALID: { category: 'configuration', blockedCategory: 'credentials' },
+    ENVIRONMENT_UNAVAILABLE: { category: 'infrastructure', blockedCategory: 'environment' },
+    APP_UNREACHABLE: { category: 'infrastructure', blockedCategory: 'environment' },
+    SEED_DATA_MISSING: { category: 'configuration', blockedCategory: 'seed_data' },
+    TEST_SETUP_FAILED: { category: 'configuration', blockedCategory: 'test_setup' },
+    APP_NOT_OPEN: { category: 'test', blockedCategory: 'test_setup' },
+    POLICY_DENIED: { category: 'configuration', blockedCategory: 'test_setup' },
+    MODEL_UNAVAILABLE: { category: 'configuration', blockedCategory: 'automation' },
+    AUTOMATION_UNSUPPORTED: { category: 'test', blockedCategory: 'automation' },
+    STEP_BUDGET_EXHAUSTED: { category: 'test', blockedCategory: 'automation' },
+    STEP_TIMEOUT: { category: 'test', blockedCategory: 'automation' },
+    MODEL_PROVIDER_FAILED: { category: 'infrastructure' },
+    CANCELLED: { category: 'infrastructure' },
+    AUTHENTICATION_FAILED: { category: 'test' },
+    MODEL_OUTPUT_INVALID: { category: 'test' },
+    LOCATOR_NOT_FOUND: { category: 'test' },
+    LOCATOR_AMBIGUOUS: { category: 'test' },
+    ACTION_FAILED: { category: 'test' },
+    STEP_NO_CONCLUSION: { category: 'test' },
+    ASSERTION_FAILED: { category: 'test' },
+};
+/** Exit/result class per code; derived from the one table. */
+export const CATEGORY_BY_CODE = Object.fromEntries(Object.entries(AGENT_CODE_TABLE).map(([code, entry]) => [code, entry.category]));
+/** The blocked category a code names, or undefined when it is not blockable. */
+export function blockedCategoryOf(code) {
+    return AGENT_CODE_TABLE[code]?.blockedCategory;
+}
+/** Cross-realm identity marker, mirroring `internal/errors.ts`. */
+const AGENT_ERROR_MARKER = Symbol.for('e2e.agent-error.v1');
+/**
+ * Runner-classified agent failure (spec api/e2e.d.ts). It extends the internal
+ * error base so category, exit code, retry eligibility, and report
+ * serialization stay consistent with every other runner error.
+ */
+export class AgentError extends E2EError {
+    code;
+    explanation;
+    screenshot;
+    /** True when this failure reports a blocked step, not a product failure. */
+    blocked;
+    constructor(code, explanation, options = {}) {
+        super(CATEGORY_BY_CODE[code], code, explanation, options);
+        this.name = new.target.name;
+        Object.defineProperty(this, AGENT_ERROR_MARKER, { value: true });
+        this.code = code;
+        this.explanation = explanation;
+        this.blocked = options.blocked === true;
+        if (options.screenshot !== undefined)
+            this.screenshot = options.screenshot;
+    }
+}
+/** The closed agent code set, derived from the one classification table. */
+const AGENT_CODES = new Set(Object.keys(CATEGORY_BY_CODE));
+/**
+ * Maps any runner error raised inside an invocation onto the closed agent code
+ * set. Model prose can never select a code.
+ */
+export function toAgentError(cause) {
+    if (isAgentError(cause))
+        return cause;
+    const classified = cause instanceof E2EError ? cause : classifyError(cause);
+    if (AGENT_CODES.has(classified.code)) {
+        return new AgentError(classified.code, classified.message, { cause });
+    }
+    if (classified.code === 'UNSUPPORTED_CAPABILITY' || classified.code === 'INVALID_CONFIG') {
+        return new AgentError('POLICY_DENIED', classified.message, { cause });
+    }
+    if (classified.category === 'infrastructure') {
+        return new AgentError('APP_UNREACHABLE', classified.message, { cause });
+    }
+    return new AgentError('ACTION_FAILED', classified.message, { cause });
+}
+/**
+ * True when a thrown value is an agent error from this or another realm.
+ * Identity rides on a global symbol marker, not the class name, so subclasses
+ * keep honest names and `instanceof` never spans realms.
+ */
+export function isAgentError(value) {
+    return (value instanceof Error &&
+        AGENT_ERROR_MARKER in value &&
+        typeof value.code === 'string' &&
+        value.code in CATEGORY_BY_CODE);
+}
+//# sourceMappingURL=error.js.map

package/dist/agent/error.js.map

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