@kernel.chat/kbot 4.1.1 → 4.4.0

package/dist/adapters/agent-sdk/from-agent-sdk.d.ts

@@ -0,0 +1,28 @@
+import type { ToolDefinition } from '../../tools/index.js';
+import type { AgentSdkExecutableTool, AgentSdkTool } from './types.js';
+export interface FromAgentSdkOptions {
+    /** kbot tier to assign to the imported tool. Default 'free'. */
+    tier?: ToolDefinition['tier'];
+    /** Custom timeout (ms). */
+    timeout?: number;
+    /** Max result size (bytes). */
+    maxResultSize?: number;
+    /**
+     * Fallback executor when the source tool ships no handler. Useful when the
+     * caller routes execution elsewhere (e.g., back through the Anthropic SDK).
+     */
+    fallbackExecutor?: (toolName: string, args: Record<string, unknown>) => Promise<string> | string;
+}
+/**
+ * Convert a non-executable Agent SDK tool definition into a kbot ToolDefinition.
+ * Because the source has no handler, an executor must be supplied via opts.fallbackExecutor
+ * — otherwise the resulting tool will return a structured "no handler" error string when invoked.
+ */
+export declare function fromAgentSdkTool(tool: AgentSdkTool, opts?: FromAgentSdkOptions): ToolDefinition;
+/**
+ * Convert an executable Agent SDK tool (schema + handler) into a kbot ToolDefinition.
+ * Preferred over fromAgentSdkTool() when the caller has the implementation in process.
+ */
+export declare function fromAgentSdkExecutableTool(tool: AgentSdkExecutableTool, opts?: Omit<FromAgentSdkOptions, 'fallbackExecutor'>): ToolDefinition;
+export declare function fromAgentSdkTools(tools: AgentSdkTool[], opts?: FromAgentSdkOptions): ToolDefinition[];
+//# sourceMappingURL=from-agent-sdk.d.ts.map

package/dist/adapters/agent-sdk/from-agent-sdk.js

@@ -0,0 +1,107 @@
+// Anthropic Agent SDK tool → kbot ToolDefinition
+//
+// Lets a kbot host import third-party Agent SDK tools (or hand-written
+// schema/handler pairs) and register them in the kbot tool registry. Schema
+// is downconverted from JSON Schema to kbot's flatter parameter shape.
+//
+// Inverse of to-agent-sdk.ts. Round-trip is lossy in general (JSON Schema is
+// strictly richer than kbot's shape), but is stable for the param shapes
+// that kbot itself uses.
+const JSON_TO_KBOT = {
+    string: 'string',
+    number: 'number',
+    integer: 'integer',
+    boolean: 'boolean',
+    object: 'object',
+    array: 'array',
+    null: 'null',
+};
+function pickType(t) {
+    if (typeof t === 'string')
+        return JSON_TO_KBOT[t] ?? 'string';
+    if (Array.isArray(t)) {
+        // Pick the first non-null type to keep parity with kbot's single-type shape.
+        const first = t.find((x) => x !== 'null');
+        return first ? JSON_TO_KBOT[first] ?? 'string' : 'string';
+    }
+    return 'string';
+}
+function mapProperty(p, required) {
+    const out = {
+        type: pickType(p.type),
+        description: typeof p.description === 'string' ? p.description : '',
+        required,
+    };
+    if (p.default !== undefined)
+        out.default = p.default;
+    if (p.items !== undefined)
+        out.items = p.items;
+    if (p.properties)
+        out.properties = p.properties;
+    return out;
+}
+function buildParameters(schema) {
+    if (!schema || typeof schema !== 'object')
+        return {};
+    const required = new Set(schema.required ?? []);
+    const out = {};
+    for (const [name, prop] of Object.entries(schema.properties ?? {})) {
+        out[name] = mapProperty(prop, required.has(name));
+    }
+    return out;
+}
+/**
+ * Convert a non-executable Agent SDK tool definition into a kbot ToolDefinition.
+ * Because the source has no handler, an executor must be supplied via opts.fallbackExecutor
+ * — otherwise the resulting tool will return a structured "no handler" error string when invoked.
+ */
+export function fromAgentSdkTool(tool, opts = {}) {
+    const fallback = opts.fallbackExecutor;
+    return {
+        name: tool.name,
+        description: tool.description,
+        parameters: buildParameters(tool.input_schema),
+        tier: opts.tier ?? 'free',
+        timeout: opts.timeout,
+        maxResultSize: opts.maxResultSize,
+        async execute(args) {
+            if (fallback) {
+                try {
+                    const result = await fallback(tool.name, args);
+                    return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+                }
+                catch (e) {
+                    return `Error: ${e.message}`;
+                }
+            }
+            return `Error: tool "${tool.name}" was imported without a handler. Provide opts.fallbackExecutor when calling fromAgentSdkTool().`;
+        },
+    };
+}
+/**
+ * Convert an executable Agent SDK tool (schema + handler) into a kbot ToolDefinition.
+ * Preferred over fromAgentSdkTool() when the caller has the implementation in process.
+ */
+export function fromAgentSdkExecutableTool(tool, opts = {}) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        parameters: buildParameters(tool.input_schema),
+        tier: opts.tier ?? 'free',
+        timeout: opts.timeout,
+        maxResultSize: opts.maxResultSize,
+        async execute(args) {
+            try {
+                const result = await tool.handler(args);
+                return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            }
+            catch (e) {
+                return `Error: ${e.message}`;
+            }
+        },
+    };
+}
+export function fromAgentSdkTools(tools, opts = {}) {
+    return tools.map((t) => fromAgentSdkTool(t, opts));
+}
+//# sourceMappingURL=from-agent-sdk.js.map

package/dist/adapters/agent-sdk/index.d.ts

@@ -0,0 +1,4 @@
+export type { AgentSdkTool, AgentSdkExecutableTool, AgentSdkInputSchema, JsonSchemaProperty, JsonSchemaType, } from './types.js';
+export { toAgentSdkTool, toAgentSdkTools, type ToAgentSdkOptions, } from './to-agent-sdk.js';
+export { fromAgentSdkTool, fromAgentSdkExecutableTool, fromAgentSdkTools, type FromAgentSdkOptions, } from './from-agent-sdk.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/agent-sdk/index.js

@@ -0,0 +1,14 @@
+// Anthropic Agent SDK adapter — bidirectional schema translation between
+// kbot's ToolDefinition surface and the Agent SDK / Messages API tool surface.
+//
+// kbot stays provider-agnostic — this adapter takes no runtime dependency
+// on @anthropic-ai/sdk. It only translates schemas and (for the from-side)
+// wraps optional executors. Round-trip kbot → Agent SDK → kbot is stable
+// for the parameter shapes kbot itself uses.
+//
+// Background: with the Anthropic Agent SDK opening to external developers
+// in May 2026, kbot tools can now be advertised to that ecosystem and
+// vice-versa — without coupling the registry to one provider's runtime.
+export { toAgentSdkTool, toAgentSdkTools, } from './to-agent-sdk.js';
+export { fromAgentSdkTool, fromAgentSdkExecutableTool, fromAgentSdkTools, } from './from-agent-sdk.js';
+//# sourceMappingURL=index.js.map

package/dist/adapters/agent-sdk/to-agent-sdk.d.ts

@@ -0,0 +1,13 @@
+import type { ToolDefinition } from '../../tools/index.js';
+import type { AgentSdkTool } from './types.js';
+export interface ToAgentSdkOptions {
+    /** If true (default), kbot tool names are passed through unchanged. */
+    preserveName?: boolean;
+    /** Optional rename hook. Wins over preserveName. */
+    renameTool?: (name: string) => string;
+    /** If true, pass `additionalProperties: false` on the input schema. Default true. */
+    strict?: boolean;
+}
+export declare function toAgentSdkTool(tool: ToolDefinition, opts?: ToAgentSdkOptions): AgentSdkTool;
+export declare function toAgentSdkTools(tools: ToolDefinition[], opts?: ToAgentSdkOptions): AgentSdkTool[];
+//# sourceMappingURL=to-agent-sdk.d.ts.map

package/dist/adapters/agent-sdk/to-agent-sdk.js

@@ -0,0 +1,73 @@
+// kbot ToolDefinition → Anthropic Agent SDK tool
+//
+// One-way schema translation. The Agent SDK delivers tool_use blocks and
+// expects the host to route them to a handler — that routing belongs in the
+// caller's agent loop, not in the adapter. This file only produces the
+// schema half so kbot tools can be advertised to the Agent SDK / Messages
+// API without taking a runtime dependency on @anthropic-ai/sdk.
+const KBOT_TYPE_TO_JSON = {
+    string: 'string',
+    number: 'number',
+    integer: 'integer',
+    boolean: 'boolean',
+    object: 'object',
+    array: 'array',
+    null: 'null',
+};
+function mapType(t) {
+    const lc = t.toLowerCase();
+    return KBOT_TYPE_TO_JSON[lc] ?? 'string';
+}
+function mapParameter(p) {
+    const out = {
+        type: mapType(p.type),
+        description: p.description,
+    };
+    if (p.default !== undefined)
+        out.default = p.default;
+    if (p.items)
+        out.items = p.items;
+    if (p.properties) {
+        const nested = {};
+        for (const [k, v] of Object.entries(p.properties)) {
+            // Best-effort: nested properties in kbot params are loosely typed.
+            const vv = v;
+            nested[k] = {
+                type: vv.type ? mapType(vv.type) : 'string',
+                description: vv.description ?? '',
+            };
+        }
+        out.properties = nested;
+    }
+    return out;
+}
+export function toAgentSdkTool(tool, opts = {}) {
+    const properties = {};
+    const required = [];
+    for (const [name, param] of Object.entries(tool.parameters)) {
+        properties[name] = mapParameter(param);
+        if (param.required)
+            required.push(name);
+    }
+    const input_schema = {
+        type: 'object',
+        properties,
+        additionalProperties: opts.strict === false ? true : false,
+    };
+    if (required.length > 0)
+        input_schema.required = required;
+    const name = opts.renameTool
+        ? opts.renameTool(tool.name)
+        : opts.preserveName === false
+            ? tool.name.replace(/[^A-Za-z0-9_-]/g, '_')
+            : tool.name;
+    return {
+        name,
+        description: tool.description,
+        input_schema,
+    };
+}
+export function toAgentSdkTools(tools, opts = {}) {
+    return tools.map((t) => toAgentSdkTool(t, opts));
+}
+//# sourceMappingURL=to-agent-sdk.js.map

package/dist/adapters/agent-sdk/types.d.ts

@@ -0,0 +1,41 @@
+export type JsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+export interface JsonSchemaProperty {
+    type?: JsonSchemaType | JsonSchemaType[];
+    description?: string;
+    enum?: unknown[];
+    items?: JsonSchemaProperty | Record<string, unknown>;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    default?: unknown;
+    [k: string]: unknown;
+}
+export interface AgentSdkInputSchema {
+    type: 'object';
+    properties: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+/**
+ * The on-the-wire tool definition the Agent SDK and the Messages API both
+ * accept. Names are snake_case by convention; the SDK does not enforce.
+ */
+export interface AgentSdkTool {
+    name: string;
+    description: string;
+    input_schema: AgentSdkInputSchema;
+}
+/**
+ * Optional executable companion. The SDK delivers `tool_use` blocks; the
+ * caller is responsible for routing them to a handler. `AgentSdkExecutableTool`
+ * couples the schema with a handler so the from-adapter can hand back something
+ * the kbot registry can run.
+ */
+export interface AgentSdkExecutableTool extends AgentSdkTool {
+    /**
+     * Handler may return a string (passed through) or arbitrary JSON-serializable
+     * value (stringified by the adapter). Mirrors what real Agent SDK handlers
+     * return in practice.
+     */
+    handler: (input: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/adapters/agent-sdk/types.js

@@ -0,0 +1,9 @@
+// Anthropic Agent SDK tool surface — minimal type model.
+//
+// Mirrors the Tool shape used by @anthropic-ai/sdk and the Agent SDK
+// without taking a runtime dependency. kbot stays provider-agnostic;
+// this adapter only ever speaks JSON Schema and JSON.
+//
+// Reference: https://docs.anthropic.com/en/api/messages#tools
+export {};
+//# sourceMappingURL=types.js.map

package/dist/adapters/peekaboo/commands.d.ts

@@ -0,0 +1,42 @@
+import type { PeekabooAgentResult, PeekabooClickResult, PeekabooOutcome, PeekabooPerformActionResult, PeekabooSeeResult, PeekabooSetValueResult, PeekabooTypeResult } from './types.js';
+export interface SeeOptions {
+    app?: string;
+    mode?: 'screen' | 'window';
+    retina?: boolean;
+}
+export declare function see(opts?: SeeOptions): Promise<PeekabooOutcome<PeekabooSeeResult>>;
+export interface ClickOptions {
+    snapshot: string;
+    on?: string;
+    coords?: [number, number];
+    wait?: number;
+}
+export declare function click(opts: ClickOptions): Promise<PeekabooOutcome<PeekabooClickResult>>;
+export interface TypeOptions {
+    text: string;
+    clear?: boolean;
+    delayMs?: number;
+}
+export declare function type_(opts: TypeOptions): Promise<PeekabooOutcome<PeekabooTypeResult>>;
+export interface SetValueOptions {
+    snapshot: string;
+    on: string;
+    value: string;
+}
+export declare function setValue(opts: SetValueOptions): Promise<PeekabooOutcome<PeekabooSetValueResult>>;
+export interface PerformActionOptions {
+    snapshot: string;
+    on: string;
+    action: string;
+}
+export declare function performAction(opts: PerformActionOptions): Promise<PeekabooOutcome<PeekabooPerformActionResult>>;
+export interface AgentOptions {
+    prompt: string;
+}
+/**
+ * Runs `peekaboo agent "$prompt"` and returns the final stdout. Unlike the
+ * structured commands the agent subcommand may emit free-form text, so we
+ * surface stdout verbatim under `output`.
+ */
+export declare function agent(opts: AgentOptions): Promise<PeekabooOutcome<PeekabooAgentResult>>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/adapters/peekaboo/commands.js

@@ -0,0 +1,209 @@
+// Peekaboo high-level helpers — typed wrappers around the JSON CLI.
+//
+// Each helper assembles argv for `peekaboo <subcommand> --json`, runs it
+// through `runPeekaboo`, and parses stdout into the appropriate result
+// type. Non-zero exits and malformed JSON are returned as `PeekabooError`
+// rather than thrown — callers fan out via discriminated unions.
+import { runPeekaboo } from './runner.js';
+function failNonZero(code, stdout, stderr) {
+    return {
+        ok: false,
+        error: {
+            code: 'non-zero-exit',
+            message: `peekaboo exited ${code}`,
+            stdout,
+            stderr,
+            exitCode: code,
+        },
+    };
+}
+function failParse(message, stdout) {
+    return {
+        ok: false,
+        error: {
+            code: 'malformed-json',
+            message,
+            stdout,
+        },
+    };
+}
+function parseJson(stdout) {
+    try {
+        return { ok: true, value: JSON.parse(stdout) };
+    }
+    catch (e) {
+        return { ok: false, err: failParse(e.message, stdout) };
+    }
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function asString(v, fallback = '') {
+    return typeof v === 'string' ? v : fallback;
+}
+function asBool(v, fallback = false) {
+    return typeof v === 'boolean' ? v : fallback;
+}
+function asNumber(v, fallback = 0) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : fallback;
+}
+export async function see(opts = {}) {
+    const args = ['see', '--json'];
+    if (opts.app)
+        args.push('--app', opts.app);
+    if (opts.mode)
+        args.push('--mode', opts.mode);
+    if (opts.retina)
+        args.push('--retina');
+    const { stdout, stderr, code } = await runPeekaboo(args);
+    if (code !== 0)
+        return failNonZero(code, stdout, stderr);
+    const parsed = parseJson(stdout);
+    if (!parsed.ok)
+        return parsed.err;
+    const v = parsed.value;
+    if (!isRecord(v))
+        return failParse('see: expected object at root', stdout);
+    const rawElements = Array.isArray(v.elements) ? v.elements : [];
+    const elements = rawElements.flatMap((el) => {
+        if (!isRecord(el))
+            return [];
+        const frameRaw = isRecord(el.frame) ? el.frame : {};
+        return [
+            {
+                id: asString(el.id),
+                role: asString(el.role),
+                label: typeof el.label === 'string' ? el.label : undefined,
+                frame: {
+                    x: asNumber(frameRaw.x),
+                    y: asNumber(frameRaw.y),
+                    width: asNumber(frameRaw.width),
+                    height: asNumber(frameRaw.height),
+                },
+                settable: typeof el.settable === 'boolean' ? el.settable : undefined,
+                named_actions: Array.isArray(el.named_actions)
+                    ? el.named_actions.filter((a) => typeof a === 'string')
+                    : undefined,
+            },
+        ];
+    });
+    return {
+        ok: true,
+        snapshot: asString(v.snapshot),
+        app: typeof v.app === 'string' ? v.app : undefined,
+        window: typeof v.window === 'string' ? v.window : undefined,
+        elements,
+        screenshot_path: typeof v.screenshot_path === 'string' ? v.screenshot_path : undefined,
+    };
+}
+export async function click(opts) {
+    const args = ['click', '--json', '--snapshot', opts.snapshot];
+    if (opts.on)
+        args.push('--on', opts.on);
+    if (opts.coords)
+        args.push('--coords', `${opts.coords[0]},${opts.coords[1]}`);
+    if (typeof opts.wait === 'number')
+        args.push('--wait', String(opts.wait));
+    const { stdout, stderr, code } = await runPeekaboo(args);
+    if (code !== 0)
+        return failNonZero(code, stdout, stderr);
+    const parsed = parseJson(stdout);
+    if (!parsed.ok)
+        return parsed.err;
+    if (!isRecord(parsed.value))
+        return failParse('click: expected object at root', stdout);
+    const v = parsed.value;
+    return {
+        ok: true,
+        target: typeof v.target === 'string' ? v.target : undefined,
+        coords: Array.isArray(v.coords) && v.coords.length === 2
+            ? [asNumber(v.coords[0]), asNumber(v.coords[1])]
+            : undefined,
+    };
+}
+// `type` is reserved in TS; export the helper as `type_`.
+export async function type_(opts) {
+    const args = ['type', '--json', '--text', opts.text];
+    if (opts.clear)
+        args.push('--clear');
+    if (typeof opts.delayMs === 'number')
+        args.push('--delay', String(opts.delayMs));
+    const { stdout, stderr, code } = await runPeekaboo(args);
+    if (code !== 0)
+        return failNonZero(code, stdout, stderr);
+    const parsed = parseJson(stdout);
+    if (!parsed.ok)
+        return parsed.err;
+    if (!isRecord(parsed.value))
+        return failParse('type: expected object at root', stdout);
+    const v = parsed.value;
+    return {
+        ok: true,
+        typed: asString(v.typed, opts.text),
+        cleared: typeof v.cleared === 'boolean' ? v.cleared : undefined,
+    };
+}
+export async function setValue(opts) {
+    const args = [
+        'set-value',
+        '--json',
+        '--snapshot',
+        opts.snapshot,
+        '--on',
+        opts.on,
+        '--value',
+        opts.value,
+    ];
+    const { stdout, stderr, code } = await runPeekaboo(args);
+    if (code !== 0)
+        return failNonZero(code, stdout, stderr);
+    const parsed = parseJson(stdout);
+    if (!parsed.ok)
+        return parsed.err;
+    if (!isRecord(parsed.value))
+        return failParse('set-value: expected object at root', stdout);
+    const v = parsed.value;
+    return {
+        ok: true,
+        target: asString(v.target, opts.on),
+        value: asString(v.value, opts.value),
+    };
+}
+export async function performAction(opts) {
+    const args = [
+        'perform-action',
+        '--json',
+        '--snapshot',
+        opts.snapshot,
+        '--on',
+        opts.on,
+        '--action',
+        opts.action,
+    ];
+    const { stdout, stderr, code } = await runPeekaboo(args);
+    if (code !== 0)
+        return failNonZero(code, stdout, stderr);
+    const parsed = parseJson(stdout);
+    if (!parsed.ok)
+        return parsed.err;
+    if (!isRecord(parsed.value))
+        return failParse('perform-action: expected object at root', stdout);
+    const v = parsed.value;
+    return {
+        ok: true,
+        target: asString(v.target, opts.on),
+        action: asString(v.action, opts.action),
+    };
+}
+/**
+ * Runs `peekaboo agent "$prompt"` and returns the final stdout. Unlike the
+ * structured commands the agent subcommand may emit free-form text, so we
+ * surface stdout verbatim under `output`.
+ */
+export async function agent(opts) {
+    const { stdout, stderr, code } = await runPeekaboo(['agent', opts.prompt]);
+    if (code !== 0)
+        return failNonZero(code, stdout, stderr);
+    return { ok: true, output: stdout };
+}
+//# sourceMappingURL=commands.js.map

package/dist/adapters/peekaboo/index.d.ts

@@ -0,0 +1,4 @@
+export type { PeekabooFrame, PeekabooElement, PeekabooSeeResult, PeekabooClickResult, PeekabooTypeResult, PeekabooSetValueResult, PeekabooPerformActionResult, PeekabooAgentResult, PeekabooError, PeekabooOutcome, } from './types.js';
+export { runPeekaboo, peekabooAvailable, type RunOptions, type RunResult } from './runner.js';
+export { see, click, type_, setValue, performAction, agent, type SeeOptions, type ClickOptions, type TypeOptions, type SetValueOptions, type PerformActionOptions, type AgentOptions, } from './commands.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/peekaboo/index.js

@@ -0,0 +1,9 @@
+// Peekaboo adapter — public surface.
+//
+// Wraps the `peekaboo` macOS CLI behind a typed interface so kbot tools and
+// agents can drive the screen-capture + GUI-automation features without
+// taking a runtime dependency on the binary or the @steipete/peekaboo
+// distribution. All execution flows through `runPeekaboo`.
+export { runPeekaboo, peekabooAvailable } from './runner.js';
+export { see, click, type_, setValue, performAction, agent, } from './commands.js';
+//# sourceMappingURL=index.js.map

package/dist/adapters/peekaboo/runner.d.ts

@@ -0,0 +1,25 @@
+export interface RunOptions {
+    /** Optional stdin payload. */
+    input?: string;
+    /** Working directory for the child. */
+    cwd?: string;
+    /** Hard timeout in milliseconds. */
+    timeoutMs?: number;
+}
+export interface RunResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+/**
+ * Run the peekaboo CLI with the given args. Resolves with stdout/stderr/code
+ * regardless of exit status; never rejects on non-zero exit. Rejects only
+ * when the binary cannot be spawned at all (ENOENT, permissions, etc.).
+ */
+export declare function runPeekaboo(args: string[], opts?: RunOptions): Promise<RunResult>;
+/**
+ * Returns true when the peekaboo binary responds to `--version`. Used by
+ * higher-level tools to gate Peekaboo features without crashing the host.
+ */
+export declare function peekabooAvailable(): Promise<boolean>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/adapters/peekaboo/runner.js

@@ -0,0 +1,75 @@
+// Peekaboo binary runner — thin child_process wrapper.
+//
+// All execution of the `peekaboo` CLI flows through `runPeekaboo`. The
+// binary path is resolved from the PEEKABOO_BIN env var (default: 'peekaboo')
+// so tests can stub it and hosts can pin a specific install. No shell is
+// involved — args go through execFile to keep arg quoting predictable.
+import { execFile } from 'node:child_process';
+function resolveBinary() {
+    return process.env.PEEKABOO_BIN && process.env.PEEKABOO_BIN.trim().length > 0
+        ? process.env.PEEKABOO_BIN
+        : 'peekaboo';
+}
+/**
+ * Run the peekaboo CLI with the given args. Resolves with stdout/stderr/code
+ * regardless of exit status; never rejects on non-zero exit. Rejects only
+ * when the binary cannot be spawned at all (ENOENT, permissions, etc.).
+ */
+export function runPeekaboo(args, opts = {}) {
+    const bin = resolveBinary();
+    return new Promise((resolve, reject) => {
+        const child = execFile(bin, args, {
+            cwd: opts.cwd,
+            timeout: opts.timeoutMs,
+            maxBuffer: 64 * 1024 * 1024,
+        }, (err, stdout, stderr) => {
+            // execFile populates err for non-zero exit too. We surface the result
+            // either way and only reject when the spawn itself failed.
+            const out = stdout;
+            const errOut = stderr;
+            const stdoutStr = typeof out === 'string'
+                ? out
+                : out instanceof Buffer
+                    ? out.toString('utf8')
+                    : '';
+            const stderrStr = typeof errOut === 'string'
+                ? errOut
+                : errOut instanceof Buffer
+                    ? errOut.toString('utf8')
+                    : '';
+            if (err) {
+                const errno = err.code;
+                // Spawn-level failures (binary missing, EACCES, etc.) reject.
+                if (errno === 'ENOENT' || errno === 'EACCES' || errno === 'EPERM') {
+                    reject(err);
+                    return;
+                }
+                // Otherwise treat as "process ran, exited non-zero".
+                const code = typeof err.code === 'number'
+                    ? (err.code)
+                    : 1;
+                resolve({ stdout: stdoutStr, stderr: stderrStr, code });
+                return;
+            }
+            resolve({ stdout: stdoutStr, stderr: stderrStr, code: 0 });
+        });
+        if (opts.input !== undefined && child.stdin) {
+            child.stdin.write(opts.input);
+            child.stdin.end();
+        }
+    });
+}
+/**
+ * Returns true when the peekaboo binary responds to `--version`. Used by
+ * higher-level tools to gate Peekaboo features without crashing the host.
+ */
+export async function peekabooAvailable() {
+    try {
+        const r = await runPeekaboo(['--version'], { timeoutMs: 5000 });
+        return r.code === 0;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=runner.js.map