@zenalexa/unicli 0.213.0 → 0.213.3

package/dist/mcp/tools.js

@@ -0,0 +1,237 @@
+/**
+ * MCP tool-definition builders.
+ *
+ * Three build modes:
+ *   1. `buildDefaultTools()`  — 4 meta-tools (~200 tokens handshake)
+ *   2. `buildExpandedTools()` — one tool per adapter command (~160K tokens)
+ *   3. `buildDeferredTools()` — stubs for ToolSearch/deferred clients (~8K)
+ *
+ * Extracted from `server.ts` to keep that file's responsibility limited to
+ * JSON-RPC transport wiring.
+ */
+import { getAllAdapters } from "../registry.js";
+import { buildInputSchema, buildOutputSchema, buildToolName, truncateDescription, } from "./schema.js";
+/**
+ * Reverse-lookup registry for expanded-mode tool calls. Maps the normalized
+ * tool name to the resolved adapter + original command name.
+ */
+export const expandedRegistry = new Map();
+export const DEFAULT_TOOL_NAMES = new Set([
+    "unicli_run",
+    "unicli_list",
+    "unicli_search",
+    "unicli_explore",
+    "unicli_discover",
+]);
+export function buildDefaultTools() {
+    return [
+        {
+            name: "unicli_run",
+            description: "Execute any Uni-CLI command. Returns JSON results.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    site: {
+                        type: "string",
+                        description: "Site name (e.g. hackernews, github, bilibili)",
+                    },
+                    command: {
+                        type: "string",
+                        description: "Command to run (e.g. top, search, hot)",
+                    },
+                    args: {
+                        type: "object",
+                        description: 'Key-value arguments (e.g. {"query": "ai", "limit": 10})',
+                        additionalProperties: true,
+                    },
+                },
+                required: ["site", "command"],
+            },
+            _meta: {
+                "anthropic/searchHint": "Execute CLI commands on 200+ websites and desktop apps. Run adapters by site and command name.",
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: true,
+            },
+        },
+        {
+            name: "unicli_list",
+            description: "List available commands. Filter by site or adapter type.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    site: {
+                        type: "string",
+                        description: "Filter by site name (partial match)",
+                    },
+                    type: {
+                        type: "string",
+                        description: "Filter by adapter type",
+                        enum: ["web-api", "desktop", "browser", "bridge", "service"],
+                    },
+                },
+            },
+            _meta: {
+                "anthropic/searchHint": "Browse available Uni-CLI sites and commands. Filter by site name or adapter type.",
+                "anthropic/alwaysLoad": true,
+            },
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        },
+        {
+            name: "unicli_search",
+            description: "Search 200+ sites and 956 commands by intent. Bilingual (EN/ZH). Returns top matches with usage examples.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "Natural language intent (e.g. 'download video', '推特热门', 'stock price')",
+                    },
+                    limit: {
+                        type: "integer",
+                        description: "Max results (default 5)",
+                        default: 5,
+                    },
+                },
+                required: ["query"],
+            },
+            _meta: {
+                "anthropic/searchHint": "Find CLI commands by intent. Semantic search across websites, desktop apps, macOS. Bilingual Chinese/English.",
+                "anthropic/alwaysLoad": true,
+            },
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        },
+        {
+            name: "unicli_explore",
+            description: "Auto-discover API endpoints for any URL. Navigates the page, captures network requests, generates YAML adapters.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    url: { type: "string", description: "Website URL to explore" },
+                    goal: {
+                        type: "string",
+                        description: "Capability to find (e.g. 'search', 'hot', 'feed')",
+                    },
+                },
+                required: ["url"],
+            },
+            _meta: {
+                "anthropic/searchHint": "Auto-discover API endpoints for any website URL. Generate YAML adapters for new sites.",
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: true,
+            },
+        },
+    ];
+}
+/**
+ * Build the expanded tool set: 4 default meta-tools + one full tool per
+ * adapter command. Clients see the complete Uni-CLI surface area.
+ *
+ * Token cost: ~160K for 956 commands. Use only when the client can handle it.
+ */
+export function buildExpandedTools() {
+    const tools = [];
+    tools.push(...buildDefaultTools());
+    expandedRegistry.clear();
+    const seen = new Set(DEFAULT_TOOL_NAMES);
+    for (const adapter of getAllAdapters()) {
+        for (const [cmdName, cmd] of Object.entries(adapter.commands)) {
+            const rawDesc = cmd.description?.trim() ||
+                adapter.description?.trim() ||
+                `${cmdName} for ${adapter.name}`;
+            const toolName = buildToolName(adapter.name, cmdName);
+            if (seen.has(toolName)) {
+                process.stderr.write(`unicli MCP: tool name collision: ${toolName} — shadowing ${adapter.name}/${cmdName}\n`);
+                continue;
+            }
+            seen.add(toolName);
+            expandedRegistry.set(toolName, { adapter, cmdName, cmd });
+            tools.push({
+                name: toolName,
+                description: truncateDescription(`[${adapter.name}] ${rawDesc}`),
+                inputSchema: buildInputSchema(cmd),
+                outputSchema: buildOutputSchema(cmd),
+                _meta: {
+                    "anthropic/searchHint": `${adapter.name}: ${rawDesc}`,
+                },
+                annotations: {
+                    readOnlyHint: true,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
+            });
+        }
+    }
+    return tools;
+}
+/**
+ * Build deferred tool set: 4 default meta-tools with full schemas, plus
+ * lightweight stubs for all adapter commands (name + searchHint only,
+ * minimal inputSchema). Clients like Claude Code's ToolSearch can discover
+ * tools by searchHint and then call them — the handler resolves the full
+ * command at call time via the expandedRegistry.
+ *
+ * Token cost: ~8K (vs ~160K for expanded). 95% reduction.
+ */
+export function buildDeferredTools() {
+    const tools = [];
+    tools.push(...buildDefaultTools());
+    expandedRegistry.clear();
+    const seen = new Set(DEFAULT_TOOL_NAMES);
+    for (const adapter of getAllAdapters()) {
+        for (const [cmdName, cmd] of Object.entries(adapter.commands)) {
+            const rawDesc = cmd.description?.trim() ||
+                adapter.description?.trim() ||
+                `${cmdName} for ${adapter.name}`;
+            const toolName = buildToolName(adapter.name, cmdName);
+            if (seen.has(toolName)) {
+                process.stderr.write(`unicli MCP: tool name collision: ${toolName} — shadowing ${adapter.name}/${cmdName}\n`);
+                continue;
+            }
+            seen.add(toolName);
+            // Register in the lookup table for runtime dispatch
+            expandedRegistry.set(toolName, { adapter, cmdName, cmd });
+            // Lightweight stub: name + searchHint + minimal schema.
+            // Full inputSchema is resolved at call time via expandedRegistry.
+            tools.push({
+                name: toolName,
+                description: truncateDescription(`[${adapter.name}] ${rawDesc}`),
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        _args: {
+                            type: "object",
+                            description: "Command arguments (pass key-value pairs)",
+                            additionalProperties: true,
+                        },
+                    },
+                },
+                _meta: {
+                    "anthropic/searchHint": `${adapter.name}: ${rawDesc}`,
+                },
+                annotations: {
+                    readOnlyHint: true,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
+            });
+        }
+    }
+    return tools;
+}
+//# sourceMappingURL=tools.js.map

package/dist/mcp/tools.js.map

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

package/dist/output/envelope.d.ts

@@ -10,6 +10,12 @@
 export declare const SCHEMA_VERSION: "2";
 export type SchemaVersion = "2";
 export type Surface = "web" | "desktop" | "system" | "mobile";
+/**
+ * Default surface for v0.213.x. Will expand to "desktop" / "system" / "mobile"
+ * when v0.214 Nikolayev lands Computer Use operators. Until then every adapter
+ * execution path runs on a web surface (CDP browser + HTTP).
+ */
+export declare const DEFAULT_SURFACE: Surface;
 /** MCP-style content block carried alongside structured data. */
 export interface AgentContent {
     type: "text" | "image" | "resource";
@@ -17,6 +23,31 @@ export interface AgentContent {
     data?: string;
     uri?: string;
 }
+/**
+ * HATEOAS action hint — a templated command the agent can run next, with
+ * typed parameter metadata (value / default / enum / description). Lets
+ * the response itself drive navigation without the agent having to
+ * reconstruct command shape from memory. Pattern from joelclaw.com
+ * "CLI Design for AI Agents" (2026-02).
+ */
+export interface AgentNextActionParam {
+    /** Concrete value already filled in from the current response context. */
+    value?: string | number | boolean;
+    /** Default applied when the agent omits the flag entirely. */
+    default?: string | number | boolean;
+    /** Valid closed-set choices the agent must pick from. */
+    enum?: Array<string | number>;
+    /** What this parameter means. */
+    description?: string;
+}
+export interface AgentNextAction {
+    /** POSIX-style template (e.g. `unicli repair <site> <cmd>`) or literal command. */
+    command: string;
+    /** One-line description of when/why to run this. */
+    description: string;
+    /** Presence of `params` marks the `command` as a template to be filled. */
+    params?: Record<string, AgentNextActionParam>;
+}
 /** Timing, pagination, and provenance metadata on every envelope. */
 export interface AgentMeta {
     duration_ms: number;
@@ -29,7 +60,38 @@ export interface AgentMeta {
         has_more?: boolean;
     };
 }
-/** Structured error payload following sysexits.h / self-repair contract. */
+/**
+ * Structured error payload following sysexits.h / self-repair contract.
+ *
+ * `code` is an open string to preserve forward compatibility. The canonical
+ * 15-value enum emitted by the current codebase, grouped by category:
+ *
+ * Transport / network (5):
+ *   - `network_error`      — TCP/TLS/DNS failure, socket closed, timeout at transport layer
+ *   - `rate_limited`       — 429 or upstream quota exhausted
+ *   - `upstream_error`     — 5xx or gateway returned malformed body
+ *   - `api_error`          — 4xx non-auth response from upstream API
+ *   - `not_authenticated`  — request rejected because no/expired credentials were sent
+ *
+ * Input / validation (3):
+ *   - `invalid_input`      — caller-supplied args failed validation
+ *   - `selector_miss`      — CSS/XPath selector didn't match any element
+ *   - `not_found`          — HTTP 404 or upstream "no such resource"
+ *
+ * Authorization (2):
+ *   - `auth_required`      — endpoint needs auth and cookie file is missing
+ *   - `permission_denied`  — authenticated but lacks capability for this resource
+ *
+ * Runtime (2):
+ *   - `internal_error`     — uncaught exception / invariant violation inside unicli
+ *   - `quarantined`        — adapter is gated by `quarantine:` in YAML; fix + repair
+ *
+ * Ref-locator (3, added v0.213.1 per Task T1):
+ *   - `stale_ref`          — snapshot ref exists but the element it mapped to has detached
+ *   - `ambiguous`          — ref resolves to multiple elements (fingerprint non-unique)
+ *   - `ref_not_found`      — snapshot ref does not appear in the fingerprint map at all;
+ *                            deliberately distinct from the HTTP-404 `not_found` code
+ */
 export interface AgentError {
     code: string;
     message: string;
@@ -49,6 +111,8 @@ export interface AgentContext {
     pagination?: AgentMeta["pagination"];
     /** Set on the error path in format() — makeEnvelope ignores this field. */
     error?: AgentError;
+    /** Optional HATEOAS hints attached to the resulting envelope. */
+    next_actions?: AgentNextAction[];
 }
 /** Success arm of the discriminated union. */
 export interface AgentEnvelopeOk {
@@ -59,6 +123,7 @@ export interface AgentEnvelopeOk {
     data: unknown[] | Record<string, unknown>;
     error: null;
     content?: AgentContent[];
+    next_actions?: AgentNextAction[];
 }
 /** Error arm of the discriminated union. */
 export interface AgentEnvelopeErr {
@@ -69,10 +134,36 @@ export interface AgentEnvelopeErr {
     data: null;
     error: AgentError;
     content?: AgentContent[];
+    next_actions?: AgentNextAction[];
 }
 export type AgentEnvelope = AgentEnvelopeOk | AgentEnvelopeErr;
-/** Build a success envelope from context + payload. */
-export declare function makeEnvelope(ctx: AgentContext, data: unknown[] | Record<string, unknown>): AgentEnvelopeOk;
+/**
+ * Build an {@link AgentContext} with conventional defaults.
+ *
+ * Every caller passes `command` plus a `startedAt` timestamp (typically
+ * `Date.now()` captured before dispatch); most callers accept the
+ * {@link DEFAULT_SURFACE}. `opts` lets specific surfaces (desktop, mcp) or
+ * versioned adapters override the defaults.
+ *
+ * The returned context has `duration_ms = Date.now() - startedAt` evaluated
+ * at call time, so invoke `makeCtx` at envelope-emit time (not at dispatch
+ * entry) — one of the two points where the 10 pre-existing call sites
+ * already built the `AgentContext` literal.
+ */
+export declare function makeCtx(command: string, startedAt: number, opts?: {
+    surface?: Surface;
+    adapterVersion?: string;
+    operator?: string;
+}): AgentContext;
+/**
+ * Build a success envelope from context + payload.
+ *
+ * Optional `content` plumbs Anthropic-compatible content blocks (text / image /
+ * resource) alongside the structured `data` payload. Populated via the YAML
+ * adapter opt-in `emit_content: true` (v0.213.1+) so download-step file
+ * metadata surfaces as `{type:"resource", uri:"file://…"}` entries.
+ */
+export declare function makeEnvelope(ctx: AgentContext, data: unknown[] | Record<string, unknown>, content?: AgentContent[]): AgentEnvelopeOk;
 /** Build an error envelope. `data` is forced to null. */
 export declare function makeError(ctx: AgentContext, err: AgentError): AgentEnvelopeErr;
 /**

package/dist/output/envelope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/output/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,cAAc,EAAG,GAAY,CAAC;AAC3C,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC;AAEhC,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9D,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE;QACX,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;CACH;AAED,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;IACrC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,IAAI,CAAC;IACT,cAAc,EAAE,aAAa,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,KAAK,EAAE,IAAI,CAAC;IACZ,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,KAAK,CAAC;IACV,cAAc,EAAE,aAAa,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,gBAAgB,CAAC;AAE/D,uDAAuD;AACvD,wBAAgB,YAAY,CAC1B,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACxC,eAAe,CAuBjB;AAED,yDAAyD;AACzD,wBAAgB,SAAS,CACvB,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,UAAU,GACd,gBAAgB,CAgBlB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CA6CzD"}
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/output/envelope.ts"],"names":[],"mappings":"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"}

package/dist/output/envelope.js

@@ -8,8 +8,43 @@
  * EnvelopeMeta / EnvelopeError re-exported from src/errors.ts (src/core/envelope.ts).
  */
 export const SCHEMA_VERSION = "2";
-/** Build a success envelope from context + payload. */
-export function makeEnvelope(ctx, data) {
+/**
+ * Default surface for v0.213.x. Will expand to "desktop" / "system" / "mobile"
+ * when v0.214 Nikolayev lands Computer Use operators. Until then every adapter
+ * execution path runs on a web surface (CDP browser + HTTP).
+ */
+export const DEFAULT_SURFACE = "web";
+/**
+ * Build an {@link AgentContext} with conventional defaults.
+ *
+ * Every caller passes `command` plus a `startedAt` timestamp (typically
+ * `Date.now()` captured before dispatch); most callers accept the
+ * {@link DEFAULT_SURFACE}. `opts` lets specific surfaces (desktop, mcp) or
+ * versioned adapters override the defaults.
+ *
+ * The returned context has `duration_ms = Date.now() - startedAt` evaluated
+ * at call time, so invoke `makeCtx` at envelope-emit time (not at dispatch
+ * entry) — one of the two points where the 10 pre-existing call sites
+ * already built the `AgentContext` literal.
+ */
+export function makeCtx(command, startedAt, opts) {
+    return {
+        command,
+        duration_ms: Date.now() - startedAt,
+        surface: opts?.surface ?? DEFAULT_SURFACE,
+        adapter_version: opts?.adapterVersion,
+        operator: opts?.operator,
+    };
+}
+/**
+ * Build a success envelope from context + payload.
+ *
+ * Optional `content` plumbs Anthropic-compatible content blocks (text / image /
+ * resource) alongside the structured `data` payload. Populated via the YAML
+ * adapter opt-in `emit_content: true` (v0.213.1+) so download-step file
+ * metadata surfaces as `{type:"resource", uri:"file://…"}` entries.
+ */
+export function makeEnvelope(ctx, data, content) {
     const count = Array.isArray(data) ? data.length : undefined;
     return {
         ok: true,
@@ -31,6 +66,10 @@ export function makeEnvelope(ctx, data) {
         },
         data,
         error: null,
+        ...(content !== undefined && content.length > 0 ? { content } : {}),
+        ...(ctx.next_actions !== undefined && ctx.next_actions.length > 0
+            ? { next_actions: ctx.next_actions }
+            : {}),
     };
 }
 /** Build an error envelope. `data` is forced to null. */
@@ -49,6 +88,9 @@ export function makeError(ctx, err) {
         },
         data: null,
         error: err,
+        ...(ctx.next_actions !== undefined && ctx.next_actions.length > 0
+            ? { next_actions: ctx.next_actions }
+            : {}),
     };
 }
 /**

package/dist/output/envelope.js.map

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

package/dist/output/error-map.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Error-to-envelope mapping helpers.
+ *
+ * Translates caught exceptions into the fields required by the v2 AgentError
+ * envelope (`code`, `adapter_path`, `step`, `suggestion`, `retryable`,
+ * `alternatives`) and into sysexits.h-style exit codes.
+ *
+ * Lives alongside `envelope.ts` because the output here is strictly envelope-
+ * shaped — no dispatch-specific state. Extracted from `src/commands/dispatch.ts`
+ * in v0.213.1 Task T4 to collapse the 7-way `err instanceof` ternary into one
+ * call to `errorToAgentFields`.
+ */
+/**
+ * Ref-locator error codes that pass through to the v2 envelope verbatim
+ * (TargetError.detail.code → PipelineError.detail.errorType → AgentError.code).
+ * Centralised as a Set so adding a 4th code is a one-line change and can't
+ * drift out of sync with target-errors.ts.
+ */
+export declare const REF_LOCATOR_CODES: Set<string>;
+/**
+ * Map a caught error to an AgentError code string following the self-repair
+ * contract. Covers the most common pipeline / network / HTTP failure modes.
+ */
+export declare function errorTypeToCode(err: unknown): string;
+/** Map a caught error to the appropriate sysexits exit code. */
+export declare function mapErrorToExitCode(err: unknown): number;
+/**
+ * Destructure a caught error into the AgentError payload fields.
+ *
+ * All three branches (PipelineError / BridgeConnectionError / generic Error)
+ * produce the same shape; callers no longer need to re-case on the class.
+ *
+ * `adapterPath` is the full YAML path (e.g. `src/adapters/twitter/search.yaml`)
+ * used to populate `adapter_path` on the PipelineError branch. `siteName` is
+ * the bare adapter name (e.g. `twitter`) interpolated into the default-branch
+ * `unicli test <site>` suggestion.
+ */
+export declare function errorToAgentFields(err: unknown, adapterPath: string, siteName: string): {
+    adapter_path: string | undefined;
+    step: number | undefined;
+    suggestion: string;
+    retryable: boolean;
+    alternatives: string[];
+};
+//# sourceMappingURL=error-map.d.ts.map

package/dist/output/error-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-map.d.ts","sourceRoot":"","sources":["../../src/output/error-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,aAI5B,CAAC;AAEH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CA0BpD;AAED,gEAAgE;AAChE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAgBvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf;IACD,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CA8BA"}

package/dist/output/error-map.js

@@ -0,0 +1,119 @@
+/**
+ * Error-to-envelope mapping helpers.
+ *
+ * Translates caught exceptions into the fields required by the v2 AgentError
+ * envelope (`code`, `adapter_path`, `step`, `suggestion`, `retryable`,
+ * `alternatives`) and into sysexits.h-style exit codes.
+ *
+ * Lives alongside `envelope.ts` because the output here is strictly envelope-
+ * shaped — no dispatch-specific state. Extracted from `src/commands/dispatch.ts`
+ * in v0.213.1 Task T4 to collapse the 7-way `err instanceof` ternary into one
+ * call to `errorToAgentFields`.
+ */
+import { PipelineError } from "../engine/executor.js";
+import { BridgeConnectionError } from "../browser/bridge.js";
+import { ExitCode } from "../types.js";
+/**
+ * Ref-locator error codes that pass through to the v2 envelope verbatim
+ * (TargetError.detail.code → PipelineError.detail.errorType → AgentError.code).
+ * Centralised as a Set so adding a 4th code is a one-line change and can't
+ * drift out of sync with target-errors.ts.
+ */
+export const REF_LOCATOR_CODES = new Set([
+    "stale_ref",
+    "ambiguous",
+    "ref_not_found",
+]);
+/**
+ * Map a caught error to an AgentError code string following the self-repair
+ * contract. Covers the most common pipeline / network / HTTP failure modes.
+ */
+export function errorTypeToCode(err) {
+    if (err instanceof PipelineError) {
+        const { errorType, statusCode } = err.detail;
+        if (statusCode === 401 ||
+            statusCode === 403 ||
+            (errorType === "http_error" && (statusCode === 401 || statusCode === 403)))
+            return "auth_required";
+        if (statusCode === 404)
+            return "not_found";
+        if (statusCode === 429)
+            return "rate_limited";
+        if (REF_LOCATOR_CODES.has(errorType))
+            return errorType;
+        if (errorType === "selector_miss")
+            return "selector_miss";
+        if (errorType === "empty_result")
+            return "empty_result";
+        if (errorType === "timeout")
+            return "network_error";
+        return "internal_error";
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    if (/ETIMEDOUT|ENOTFOUND|ECONNREFUSED|ECONNRESET|socket hang up/i.test(message))
+        return "network_error";
+    if (/401|403|auth/i.test(message))
+        return "auth_required";
+    if (/404/i.test(message))
+        return "not_found";
+    if (/429|rate.?limit/i.test(message))
+        return "rate_limited";
+    return "internal_error";
+}
+/** Map a caught error to the appropriate sysexits exit code. */
+export function mapErrorToExitCode(err) {
+    if (err instanceof PipelineError) {
+        const { errorType, statusCode } = err.detail;
+        if (statusCode === 401 || statusCode === 403)
+            return ExitCode.AUTH_REQUIRED;
+        if (errorType === "empty_result")
+            return ExitCode.EMPTY_RESULT;
+        return ExitCode.GENERIC_ERROR;
+    }
+    if (err instanceof BridgeConnectionError)
+        return ExitCode.SERVICE_UNAVAILABLE;
+    const message = err instanceof Error ? err.message : String(err);
+    if (/ETIMEDOUT|ENOTFOUND|ECONNREFUSED|ECONNRESET|socket hang up|daemon failed/i.test(message))
+        return ExitCode.TEMP_FAILURE;
+    return ExitCode.GENERIC_ERROR;
+}
+/**
+ * Destructure a caught error into the AgentError payload fields.
+ *
+ * All three branches (PipelineError / BridgeConnectionError / generic Error)
+ * produce the same shape; callers no longer need to re-case on the class.
+ *
+ * `adapterPath` is the full YAML path (e.g. `src/adapters/twitter/search.yaml`)
+ * used to populate `adapter_path` on the PipelineError branch. `siteName` is
+ * the bare adapter name (e.g. `twitter`) interpolated into the default-branch
+ * `unicli test <site>` suggestion.
+ */
+export function errorToAgentFields(err, adapterPath, siteName) {
+    if (err instanceof PipelineError) {
+        return {
+            adapter_path: adapterPath,
+            step: err.detail.step,
+            suggestion: err.detail.suggestion,
+            retryable: err.detail.retryable ?? false,
+            alternatives: err.detail.alternatives ?? [],
+        };
+    }
+    if (err instanceof BridgeConnectionError) {
+        return {
+            adapter_path: undefined,
+            step: undefined,
+            suggestion: err.suggestion,
+            retryable: err.retryable,
+            alternatives: err.alternatives,
+        };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        adapter_path: undefined,
+        step: undefined,
+        suggestion: `Run 'unicli test ${siteName}' to diagnose, or report this error.`,
+        retryable: /timeout|ETIMEDOUT|ECONNREFUSED|ECONNRESET|socket hang up|daemon failed/i.test(message),
+        alternatives: [],
+    };
+}
+//# sourceMappingURL=error-map.js.map

package/dist/output/error-map.js.map

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