@framers/agentos 0.1.120 → 0.1.121

package/dist/core/media/ProviderPreferences.js

@@ -0,0 +1,183 @@
+/**
+ * @file ProviderPreferences.ts
+ * Shared resolver for media provider selection across image, video, and audio
+ * subsystems.
+ *
+ * Provides two complementary mechanisms:
+ *
+ * 1. **Deterministic ordering** via {@link resolveProviderOrder} — filters and
+ *    reorders an "available" list according to user preferences (preferred
+ *    providers first, blocked providers removed).
+ *
+ * 2. **Weighted random selection** via {@link selectWeightedProvider} — picks a
+ *    single provider from a resolved list using optional per-provider weights
+ *    (useful for load-balancing or A/B testing across providers).
+ *
+ * These utilities are intentionally stateless and side-effect-free so they can
+ * be called from any subsystem without lifecycle concerns.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   resolveProviderOrder,
+ *   resolveProviderChain,
+ *   selectWeightedProvider,
+ * } from './ProviderPreferences.js';
+ *
+ * const available = ['openai', 'stability', 'replicate'];
+ *
+ * // Deterministic: preferred order with blocklist
+ * const ordered = resolveProviderOrder(available, {
+ *   preferred: ['replicate', 'openai'],
+ *   blocked: ['stability'],
+ * });
+ * // => ['replicate', 'openai']
+ *
+ * // Weighted primary selection with deterministic fallback ordering
+ * const chain = resolveProviderChain(ordered, {
+ *   weights: {
+ *     replicate: 9,
+ *     openai: 1,
+ *   },
+ * });
+ * // => ['replicate', 'openai'] most of the time
+ *
+ * // Or pick a single weighted provider directly
+ * const chosen = selectWeightedProvider(chain, {
+ *   replicate: 9,
+ *   openai: 1,
+ * });
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// resolveProviderOrder
+// ---------------------------------------------------------------------------
+/**
+ * Filter and reorder an "available" provider list according to user
+ * preferences.
+ *
+ * Resolution rules (applied in order):
+ *
+ * 1. If `preferences` is `undefined` or empty, return `available` unchanged.
+ * 2. If `preferred` is set, keep only providers that appear in **both**
+ *    `available` and `preferred`, preserving the order of `preferred`.
+ * 3. If `blocked` is set, remove any provider whose ID appears in `blocked`.
+ *
+ * The result is never longer than `available` and never contains duplicates.
+ *
+ * @param available - Provider IDs currently available in the system.
+ * @param preferences - Optional preference configuration.
+ * @returns Filtered and reordered provider ID list.
+ *
+ * @example
+ * ```ts
+ * resolveProviderOrder(['a', 'b', 'c'], { preferred: ['c', 'a'] });
+ * // => ['c', 'a']
+ *
+ * resolveProviderOrder(['a', 'b', 'c'], { blocked: ['b'] });
+ * // => ['a', 'c']
+ * ```
+ */
+export function resolveProviderOrder(available, preferences) {
+    if (!preferences) {
+        return available;
+    }
+    const blockedSet = new Set(preferences.blocked ?? []);
+    // When preferred is specified, reorder to preferred order and keep only
+    // providers that are actually available.
+    let ordered;
+    if (preferences.preferred && preferences.preferred.length > 0) {
+        const availableSet = new Set(available);
+        ordered = preferences.preferred.filter((id) => availableSet.has(id));
+    }
+    else {
+        ordered = [...available];
+    }
+    // Remove blocked providers.
+    if (blockedSet.size > 0) {
+        ordered = ordered.filter((id) => !blockedSet.has(id));
+    }
+    return ordered;
+}
+// ---------------------------------------------------------------------------
+// resolveProviderChain
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a full provider chain from the available providers and preferences.
+ *
+ * This combines deterministic filtering/reordering via
+ * {@link resolveProviderOrder} with optional weighted primary selection via
+ * {@link selectWeightedProvider}. When `weights` are present, a single primary
+ * provider is chosen from the ordered list and moved to the front while the
+ * remaining providers preserve their relative order as fallbacks.
+ *
+ * @param available - Provider IDs currently available in the system.
+ * @param preferences - Optional preference configuration.
+ * @returns Ordered provider chain with the chosen primary first.
+ */
+export function resolveProviderChain(available, preferences) {
+    const ordered = resolveProviderOrder(available, preferences);
+    if (ordered.length <= 1 || !preferences?.weights) {
+        return ordered;
+    }
+    const primary = selectWeightedProvider(ordered, preferences.weights);
+    return [primary, ...ordered.filter((id) => id !== primary)];
+}
+// ---------------------------------------------------------------------------
+// selectWeightedProvider
+// ---------------------------------------------------------------------------
+/**
+ * Select a single provider from a list using optional per-provider weights.
+ *
+ * Selection rules:
+ *
+ * - If `providers` is empty, throws an `Error`.
+ * - If `weights` is `undefined` or `providers` has exactly one entry, the
+ *   first provider is returned deterministically.
+ * - Otherwise a weighted random selection is performed: each provider's
+ *   weight is looked up in `weights` (defaulting to `1` for unlisted
+ *   providers), weights are summed, and a random value in `[0, sum)` picks
+ *   the winner proportionally.
+ *
+ * @param providers - Non-empty list of provider IDs to choose from.
+ * @param weights - Optional weight map. Providers not listed get weight `1`.
+ * @returns The selected provider ID.
+ * @throws {Error} When `providers` is empty.
+ *
+ * @example
+ * ```ts
+ * // 90% suno, 10% udio (approximately)
+ * selectWeightedProvider(['suno', 'udio'], { suno: 9, udio: 1 });
+ * ```
+ */
+export function selectWeightedProvider(providers, weights) {
+    if (providers.length === 0) {
+        throw new Error('Cannot select from an empty provider list');
+    }
+    if (!weights || providers.length === 1) {
+        return providers[0];
+    }
+    const resolved = providers
+        .map((id) => {
+        const weight = weights[id] ?? 1;
+        if (!Number.isFinite(weight) || weight < 0) {
+            throw new Error(`Invalid weight for provider "${id}". Expected a finite non-negative number.`);
+        }
+        return { id, weight };
+    })
+        .filter(({ weight }) => weight > 0);
+    if (resolved.length === 0) {
+        throw new Error('Cannot select from providers with zero total weight');
+    }
+    const totalWeight = resolved.reduce((sum, p) => sum + p.weight, 0);
+    let random = Math.random() * totalWeight;
+    for (const { id, weight } of resolved) {
+        random -= weight;
+        if (random <= 0) {
+            return id;
+        }
+    }
+    // Floating-point edge case — return the last provider.
+    return providers[providers.length - 1];
+}
+//# sourceMappingURL=ProviderPreferences.js.map

package/dist/core/media/ProviderPreferences.js.map

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

package/dist/core/subprocess/CLIRegistry.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview CLI discovery registry — scans PATH for known binaries
+ * so AgentOS can auto-detect available tools, LLM CLIs, and utilities.
+ *
+ * Providers and extensions register their CLI dependencies at startup.
+ * A curated set of well-known CLIs ships as defaults.
+ *
+ * @module agentos/core/subprocess/CLIRegistry
+ */
+import type { CLIDescriptor, CLIScanResult } from './types';
+/**
+ * Curated set of well-known CLIs that AgentOS scans for by default.
+ * Extensions and providers can register additional descriptors at runtime.
+ */
+export declare const WELL_KNOWN_CLIS: CLIDescriptor[];
+/**
+ * Registry of known CLI binaries with PATH scanning capabilities.
+ *
+ * Usage:
+ * 1. Create a registry and register well-known CLIs (done automatically if using defaults).
+ * 2. Providers/extensions register additional CLIs via {@link register}.
+ * 3. Call {@link scan} to discover what's installed on the user's machine.
+ * 4. Results feed into `wunderland doctor`, capability discovery, and provider auto-detection.
+ *
+ * @example
+ * const registry = new CLIRegistry();
+ * registry.registerAll(WELL_KNOWN_CLIS);
+ * registry.register({ binaryName: 'my-tool', ... });
+ *
+ * const results = await registry.scan();
+ * for (const r of results) {
+ *   console.log(`${r.displayName}: ${r.installed ? `v${r.version}` : 'not installed'}`);
+ * }
+ */
+export declare class CLIRegistry {
+    private descriptors;
+    /**
+     * Create a registry, optionally pre-populated with well-known CLIs.
+     * @param loadDefaults — whether to register {@link WELL_KNOWN_CLIS} (default true)
+     */
+    constructor(loadDefaults?: boolean);
+    /** Register a single CLI descriptor. Overwrites existing entry for the same binaryName. */
+    register(descriptor: CLIDescriptor): void;
+    /** Register multiple descriptors at once. */
+    registerAll(descriptors: CLIDescriptor[]): void;
+    /** Remove a descriptor by binary name. */
+    unregister(binaryName: string): boolean;
+    /**
+     * Scan PATH for all registered CLIs.
+     * Runs `which` + `--version` for each descriptor in parallel.
+     * @returns scan results for every registered CLI (installed or not)
+     */
+    scan(): Promise<CLIScanResult[]>;
+    /**
+     * Check a single binary by name.
+     * @param binaryName — the binary to look for (must be registered)
+     * @returns scan result with installation status, path, and version
+     */
+    check(binaryName: string): Promise<CLIScanResult>;
+    /** Get all registered descriptors (installed or not). */
+    list(): CLIDescriptor[];
+    /** Get only installed CLIs. */
+    installed(): Promise<CLIScanResult[]>;
+    /** Get CLIs by category. */
+    byCategory(category: string): Promise<CLIScanResult[]>;
+    /** Check if a binary is registered (not whether it's installed). */
+    has(binaryName: string): boolean;
+    /** Get a descriptor by binary name. */
+    get(binaryName: string): CLIDescriptor | undefined;
+}
+//# sourceMappingURL=CLIRegistry.d.ts.map

package/dist/core/subprocess/CLIRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CLIRegistry.d.ts","sourceRoot":"","sources":["../../../src/core/subprocess/CLIRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAM5D;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,aAAa,EA6E1C,CAAC;AAMF;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,WAAW,CAAyC;IAE5D;;;OAGG;gBACS,YAAY,GAAE,OAAc;IAMxC,2FAA2F;IAC3F,QAAQ,CAAC,UAAU,EAAE,aAAa,GAAG,IAAI;IAIzC,6CAA6C;IAC7C,WAAW,CAAC,WAAW,EAAE,aAAa,EAAE,GAAG,IAAI;IAI/C,0CAA0C;IAC1C,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAIvC;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAMtC;;;;OAIG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAkCvD,yDAAyD;IACzD,IAAI,IAAI,aAAa,EAAE;IAIvB,+BAA+B;IACzB,SAAS,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAK3C,4BAA4B;IACtB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAK5D,oEAAoE;IACpE,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAIhC,uCAAuC;IACvC,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;CAGnD"}

package/dist/core/subprocess/CLIRegistry.js

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview CLI discovery registry — scans PATH for known binaries
+ * so AgentOS can auto-detect available tools, LLM CLIs, and utilities.
+ *
+ * Providers and extensions register their CLI dependencies at startup.
+ * A curated set of well-known CLIs ships as defaults.
+ *
+ * @module agentos/core/subprocess/CLIRegistry
+ */
+import { execa } from 'execa';
+/* ------------------------------------------------------------------ */
+/*  Well-known CLIs                                                    */
+/* ------------------------------------------------------------------ */
+/**
+ * Curated set of well-known CLIs that AgentOS scans for by default.
+ * Extensions and providers can register additional descriptors at runtime.
+ */
+export const WELL_KNOWN_CLIS = [
+    // ── LLM CLIs ──
+    {
+        binaryName: 'claude',
+        displayName: 'Claude Code',
+        description: 'Anthropic Claude via Max subscription — no API key required',
+        category: 'llm',
+        installGuidance: 'npm install -g @anthropic-ai/claude-code — or download from https://claude.ai/download',
+    },
+    {
+        binaryName: 'gemini',
+        displayName: 'Gemini CLI',
+        description: 'Google Gemini via Google account login — no API key required',
+        category: 'llm',
+        installGuidance: 'npm install -g @google/gemini-cli',
+    },
+    // ── Dev tools ──
+    {
+        binaryName: 'git',
+        displayName: 'Git',
+        description: 'Distributed version control system',
+        category: 'devtools',
+        installGuidance: 'https://git-scm.com/downloads',
+    },
+    {
+        binaryName: 'gh',
+        displayName: 'GitHub CLI',
+        description: 'GitHub API from the terminal — PRs, issues, actions',
+        category: 'devtools',
+        installGuidance: 'https://cli.github.com/',
+    },
+    {
+        binaryName: 'docker',
+        displayName: 'Docker',
+        description: 'Container runtime for building and running applications',
+        category: 'devtools',
+        installGuidance: 'https://docs.docker.com/get-docker/',
+    },
+    // ── Runtimes ──
+    {
+        binaryName: 'node',
+        displayName: 'Node.js',
+        description: 'JavaScript runtime built on V8',
+        category: 'runtime',
+        installGuidance: 'https://nodejs.org/',
+    },
+    {
+        binaryName: 'python3',
+        displayName: 'Python 3',
+        description: 'Python interpreter',
+        category: 'runtime',
+        installGuidance: 'https://www.python.org/downloads/',
+    },
+    // ── Media ──
+    {
+        binaryName: 'ffmpeg',
+        displayName: 'FFmpeg',
+        description: 'Audio/video processing and conversion toolkit',
+        category: 'media',
+        installGuidance: 'https://ffmpeg.org/download.html',
+    },
+    // ── Cloud ──
+    {
+        binaryName: 'gcloud',
+        displayName: 'Google Cloud SDK',
+        description: 'Google Cloud resource management',
+        category: 'cloud',
+        installGuidance: 'https://cloud.google.com/sdk/docs/install',
+        versionFlag: '--version',
+    },
+    {
+        binaryName: 'aws',
+        displayName: 'AWS CLI',
+        description: 'Amazon Web Services resource management',
+        category: 'cloud',
+        installGuidance: 'https://aws.amazon.com/cli/',
+    },
+];
+/* ------------------------------------------------------------------ */
+/*  Registry                                                           */
+/* ------------------------------------------------------------------ */
+/**
+ * Registry of known CLI binaries with PATH scanning capabilities.
+ *
+ * Usage:
+ * 1. Create a registry and register well-known CLIs (done automatically if using defaults).
+ * 2. Providers/extensions register additional CLIs via {@link register}.
+ * 3. Call {@link scan} to discover what's installed on the user's machine.
+ * 4. Results feed into `wunderland doctor`, capability discovery, and provider auto-detection.
+ *
+ * @example
+ * const registry = new CLIRegistry();
+ * registry.registerAll(WELL_KNOWN_CLIS);
+ * registry.register({ binaryName: 'my-tool', ... });
+ *
+ * const results = await registry.scan();
+ * for (const r of results) {
+ *   console.log(`${r.displayName}: ${r.installed ? `v${r.version}` : 'not installed'}`);
+ * }
+ */
+export class CLIRegistry {
+    /**
+     * Create a registry, optionally pre-populated with well-known CLIs.
+     * @param loadDefaults — whether to register {@link WELL_KNOWN_CLIS} (default true)
+     */
+    constructor(loadDefaults = true) {
+        this.descriptors = new Map();
+        if (loadDefaults) {
+            this.registerAll(WELL_KNOWN_CLIS);
+        }
+    }
+    /** Register a single CLI descriptor. Overwrites existing entry for the same binaryName. */
+    register(descriptor) {
+        this.descriptors.set(descriptor.binaryName, descriptor);
+    }
+    /** Register multiple descriptors at once. */
+    registerAll(descriptors) {
+        for (const d of descriptors)
+            this.register(d);
+    }
+    /** Remove a descriptor by binary name. */
+    unregister(binaryName) {
+        return this.descriptors.delete(binaryName);
+    }
+    /**
+     * Scan PATH for all registered CLIs.
+     * Runs `which` + `--version` for each descriptor in parallel.
+     * @returns scan results for every registered CLI (installed or not)
+     */
+    async scan() {
+        return Promise.all(Array.from(this.descriptors.values()).map(d => this.check(d.binaryName)));
+    }
+    /**
+     * Check a single binary by name.
+     * @param binaryName — the binary to look for (must be registered)
+     * @returns scan result with installation status, path, and version
+     */
+    async check(binaryName) {
+        const descriptor = this.descriptors.get(binaryName);
+        if (!descriptor) {
+            return {
+                binaryName,
+                displayName: binaryName,
+                description: '',
+                category: 'unknown',
+                installGuidance: '',
+                installed: false,
+            };
+        }
+        try {
+            const whichResult = await execa('which', [binaryName]);
+            const binaryPath = whichResult.stdout.trim();
+            const versionFlag = descriptor.versionFlag ?? '--version';
+            let version = 'unknown';
+            try {
+                const versionResult = await execa(binaryName, [versionFlag]);
+                const pattern = descriptor.versionPattern ?? /(\d+\.\d+\.\d+)/;
+                const match = versionResult.stdout.match(pattern);
+                version = match ? match[1] : 'unknown';
+            }
+            catch {
+                /* version check failed — binary still exists though */
+            }
+            return { ...descriptor, installed: true, binaryPath, version };
+        }
+        catch {
+            return { ...descriptor, installed: false };
+        }
+    }
+    /** Get all registered descriptors (installed or not). */
+    list() {
+        return Array.from(this.descriptors.values());
+    }
+    /** Get only installed CLIs. */
+    async installed() {
+        const results = await this.scan();
+        return results.filter(r => r.installed);
+    }
+    /** Get CLIs by category. */
+    async byCategory(category) {
+        const results = await this.scan();
+        return results.filter(r => r.category === category);
+    }
+    /** Check if a binary is registered (not whether it's installed). */
+    has(binaryName) {
+        return this.descriptors.has(binaryName);
+    }
+    /** Get a descriptor by binary name. */
+    get(binaryName) {
+        return this.descriptors.get(binaryName);
+    }
+}
+//# sourceMappingURL=CLIRegistry.js.map

package/dist/core/subprocess/CLIRegistry.js.map

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

package/dist/core/subprocess/CLISubprocessBridge.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Abstract base class for CLI subprocess bridges.
+ * Uses the template method pattern: owns subprocess lifecycle (spawn, pipe,
+ * parse NDJSON, timeout/abort) while subclasses implement CLI-specific
+ * flag assembly, error classification, and stream event parsing.
+ *
+ * This is a first-class AgentOS core capability — any provider, extension,
+ * tool, or skill can extend this to manage external CLI binaries.
+ *
+ * @module agentos/core/subprocess/CLISubprocessBridge
+ * @see ClaudeCodeCLIBridge
+ */
+import { CLISubprocessError } from './errors';
+import type { BridgeOptions, BridgeResult, StreamEvent, OutputFormat, InstallCheckResult } from './types';
+/**
+ * Abstract base class for managing CLI subprocesses via execa.
+ *
+ * Subclasses implement four methods:
+ * - {@link binaryName} — the CLI binary on PATH
+ * - {@link buildArgs} — CLI-specific flag assembly
+ * - {@link classifyError} — error classification with guidance
+ * - {@link parseStreamEvent} — stream-json event parsing
+ *
+ * The base class handles:
+ * - Binary installation detection (`which` + version parsing)
+ * - Authentication health checks
+ * - Non-streaming execution with JSON result parsing
+ * - Streaming execution with NDJSON line splitting
+ * - Timeout and abort signal management
+ *
+ * @example
+ * class MyToolBridge extends CLISubprocessBridge {
+ *   protected readonly binaryName = 'mytool';
+ *   protected buildArgs(opts, fmt) { return ['-p', '--format', fmt]; }
+ *   protected classifyError(err) { return new CLISubprocessError(...); }
+ *   protected parseStreamEvent(raw) { return { type: 'text_delta', text: raw.text }; }
+ * }
+ */
+export declare abstract class CLISubprocessBridge {
+    /** The CLI binary name on PATH (e.g. 'claude', 'gemini', 'ffmpeg'). */
+    protected abstract readonly binaryName: string;
+    /**
+     * Build the CLI argument array for a given call.
+     * Called by {@link execute} and {@link stream} with the appropriate output format.
+     *
+     * @param options — caller-provided bridge options
+     * @param format — 'json' for execute(), 'stream-json' for stream()
+     * @returns array of CLI arguments
+     */
+    protected abstract buildArgs(options: BridgeOptions, format: OutputFormat): string[];
+    /**
+     * Classify a subprocess error into a typed {@link CLISubprocessError}.
+     * Examines stderr, exit code, error.code to produce actionable guidance.
+     *
+     * @param error — the raw error from execa
+     * @returns a CLISubprocessError (or subclass) with guidance and recoverability
+     */
+    protected abstract classifyError(error: any): CLISubprocessError;
+    /**
+     * Parse a raw JSON object from stream-json output into a typed {@link StreamEvent}.
+     * Returns null for events that should be skipped (progress spinners, etc.).
+     *
+     * @param raw — a parsed JSON object from one line of NDJSON stdout
+     * @returns a typed StreamEvent, or null to skip
+     */
+    protected abstract parseStreamEvent(raw: any): StreamEvent | null;
+    /**
+     * Parse the JSON stdout from `--output-format json`.
+     * Default implementation: JSON.parse with graceful fallback to raw text.
+     * Override if your CLI's JSON output has a different shape.
+     */
+    protected parseJsonResult(stdout: string, durationMs: number): BridgeResult;
+    /**
+     * Build args and stdin for the lightweight authentication check.
+     * Override for CLI-specific flags (e.g. Claude needs --bare --max-turns 1).
+     */
+    protected buildAuthCheckArgs(): {
+        args: string[];
+        stdin: string;
+    };
+    /**
+     * Parse a version string from the CLI's --version output.
+     * Default: extracts first semver-like pattern (/\d+\.\d+\.\d+/).
+     */
+    protected parseVersion(stdout: string): string;
+    /**
+     * Check if the binary is installed and on PATH.
+     * Returns the resolved path and parsed version string if found.
+     */
+    checkBinaryInstalled(): Promise<InstallCheckResult>;
+    /**
+     * Check if the CLI is authenticated via a lightweight ping.
+     * Uses {@link buildAuthCheckArgs} for CLI-specific flags.
+     */
+    checkAuthenticated(): Promise<boolean>;
+    /**
+     * Non-streaming execution.
+     * Spawns the binary with `--output-format json`, pipes prompt via stdin,
+     * and returns the parsed result.
+     *
+     * @param options — bridge options (prompt, system prompt, model, etc.)
+     * @returns parsed result with text, session ID, usage, and timing
+     * @throws {CLISubprocessError} on subprocess failure (via {@link classifyError})
+     */
+    execute(options: BridgeOptions): Promise<BridgeResult>;
+    /**
+     * Streaming execution.
+     * Spawns the binary with `--output-format stream-json` and yields
+     * {@link StreamEvent}s parsed from newline-delimited JSON on stdout.
+     *
+     * @param options — bridge options
+     * @yields typed stream events (text_delta, result, error, system)
+     * @throws {CLISubprocessError} on subprocess failure (via {@link classifyError})
+     */
+    stream(options: BridgeOptions): AsyncGenerator<StreamEvent, void, undefined>;
+}
+//# sourceMappingURL=CLISubprocessBridge.d.ts.map

package/dist/core/subprocess/CLISubprocessBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CLISubprocessBridge.d.ts","sourceRoot":"","sources":["../../../src/core/subprocess/CLISubprocessBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAKjB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,mBAAmB;IAIvC,uEAAuE;IACvE,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE/C;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE;IAEpF;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,kBAAkB;IAEhE;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,WAAW,GAAG,IAAI;IAIjE;;;;OAIG;IACH,SAAS,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY;IAiB3E;;;OAGG;IACH,SAAS,CAAC,kBAAkB,IAAI;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAOjE;;;OAGG;IACH,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAO9C;;;OAGG;IACG,oBAAoB,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAczD;;;OAGG;IACG,kBAAkB,IAAI,OAAO,CAAC,OAAO,CAAC;IAU5C;;;;;;;;OAQG;IACG,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAmB5D;;;;;;;;OAQG;IACI,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,SAAS,CAAC;CAkDpF"}