@framers/agentos 0.1.119 → 0.1.121

package/dist/core/subprocess/CLISubprocessBridge.js

@@ -0,0 +1,199 @@
+/**
+ * @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 { execa } from 'execa';
+/** Default subprocess timeout (2 minutes). */
+const DEFAULT_TIMEOUT_MS = 120000;
+/**
+ * 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 class CLISubprocessBridge {
+    /* ---- Virtual: override if your CLI differs ---- */
+    /**
+     * 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.
+     */
+    parseJsonResult(stdout, durationMs) {
+        try {
+            const parsed = JSON.parse(stdout.trim());
+            return {
+                result: parsed.result ?? parsed.message ?? parsed.response ?? stdout.trim(),
+                sessionId: parsed.session_id,
+                usage: parsed.usage
+                    ? { input_tokens: parsed.usage.input_tokens ?? 0, output_tokens: parsed.usage.output_tokens ?? 0 }
+                    : undefined,
+                isError: parsed.is_error === true,
+                durationMs,
+            };
+        }
+        catch {
+            return { result: stdout.trim(), isError: false, durationMs };
+        }
+    }
+    /**
+     * Build args and stdin for the lightweight authentication check.
+     * Override for CLI-specific flags (e.g. Claude needs --bare --max-turns 1).
+     */
+    buildAuthCheckArgs() {
+        return {
+            args: ['-p', '--output-format', 'json'],
+            stdin: 'Reply with exactly: pong',
+        };
+    }
+    /**
+     * Parse a version string from the CLI's --version output.
+     * Default: extracts first semver-like pattern (/\d+\.\d+\.\d+/).
+     */
+    parseVersion(stdout) {
+        const match = stdout.match(/(\d+\.\d+\.\d+)/);
+        return match ? match[1] : 'unknown';
+    }
+    /* ---- Concrete: shared lifecycle ---- */
+    /**
+     * Check if the binary is installed and on PATH.
+     * Returns the resolved path and parsed version string if found.
+     */
+    async checkBinaryInstalled() {
+        try {
+            const whichResult = await execa('which', [this.binaryName]);
+            const binaryPath = whichResult.stdout.trim();
+            const versionResult = await execa(this.binaryName, ['--version']);
+            const version = this.parseVersion(versionResult.stdout);
+            return { installed: true, binaryPath, version };
+        }
+        catch {
+            return { installed: false };
+        }
+    }
+    /**
+     * Check if the CLI is authenticated via a lightweight ping.
+     * Uses {@link buildAuthCheckArgs} for CLI-specific flags.
+     */
+    async checkAuthenticated() {
+        try {
+            const { args, stdin } = this.buildAuthCheckArgs();
+            await execa(this.binaryName, args, { input: stdin, timeout: 30000 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 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})
+     */
+    async execute(options) {
+        const args = this.buildArgs(options, 'json');
+        const startMs = Date.now();
+        try {
+            const result = await execa(this.binaryName, args, {
+                input: options.prompt,
+                timeout: options.timeout ?? DEFAULT_TIMEOUT_MS,
+                cancelSignal: options.abortSignal,
+                ...(options.env ? { env: { ...process.env, ...options.env } } : {}),
+            });
+            const durationMs = Date.now() - startMs;
+            return this.parseJsonResult(result.stdout, durationMs);
+        }
+        catch (error) {
+            throw this.classifyError(error);
+        }
+    }
+    /**
+     * 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})
+     */
+    async *stream(options) {
+        const args = this.buildArgs(options, 'stream-json');
+        let subprocess;
+        try {
+            subprocess = execa(this.binaryName, args, {
+                input: options.prompt,
+                timeout: options.timeout ?? DEFAULT_TIMEOUT_MS,
+                cancelSignal: options.abortSignal,
+                ...(options.env ? { env: { ...process.env, ...options.env } } : {}),
+            });
+        }
+        catch (error) {
+            throw this.classifyError(error);
+        }
+        let buffer = '';
+        try {
+            for await (const chunk of subprocess.stdout) {
+                buffer += chunk.toString();
+                const lines = buffer.split('\n');
+                buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed)
+                        continue;
+                    try {
+                        const event = this.parseStreamEvent(JSON.parse(trimmed));
+                        if (event)
+                            yield event;
+                    }
+                    catch {
+                        /* skip unparseable lines (progress spinners, etc.) */
+                    }
+                }
+            }
+            /* flush remaining buffer */
+            if (buffer.trim()) {
+                try {
+                    const event = this.parseStreamEvent(JSON.parse(buffer.trim()));
+                    if (event)
+                        yield event;
+                }
+                catch { /* ignore */ }
+            }
+            /* Ensure non-zero exits after stdout drains still surface as errors. */
+            await subprocess;
+        }
+        catch (error) {
+            throw this.classifyError(error);
+        }
+    }
+}
+//# sourceMappingURL=CLISubprocessBridge.js.map

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

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

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

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Base error class for CLI subprocess operations.
+ * Fully generic — works for any binary (LLM CLIs, dev tools, media tools, etc.).
+ * Error codes are open strings so each consumer can define their own.
+ *
+ * @module agentos/core/subprocess/errors
+ */
+/**
+ * Base error for ANY CLI subprocess managed by {@link CLISubprocessBridge}.
+ * Not specific to LLM CLIs — works for ffmpeg, git, docker, or any binary.
+ *
+ * Carries actionable {@link guidance} so the user knows how to fix the problem,
+ * and a {@link recoverable} flag so callers know whether to retry or fall back.
+ *
+ * @example
+ * throw new CLISubprocessError(
+ *   'ffmpeg not found.',
+ *   CLI_ERROR.BINARY_NOT_FOUND,
+ *   'ffmpeg',
+ *   'Install ffmpeg: brew install ffmpeg',
+ *   false,
+ * );
+ */
+export declare class CLISubprocessError extends Error {
+    /** Error code — open string, not a fixed union. Each CLI defines its own. */
+    readonly code: string;
+    /** The binary that failed (e.g. 'claude', 'gemini', 'ffmpeg'). */
+    readonly binaryName: string;
+    /** Human-readable fix instructions shown to the user. */
+    readonly guidance: string;
+    /** Whether the caller can retry or fall back. */
+    readonly recoverable: boolean;
+    /** Optional underlying error or extra context. */
+    readonly details?: unknown;
+    /**
+     * @param message — human-readable error description
+     * @param code — error code string (use {@link CLI_ERROR} constants or your own)
+     * @param binaryName — the CLI binary that failed
+     * @param guidance — actionable fix instructions shown to the user
+     * @param recoverable — true if the caller should attempt retry/fallback (default false)
+     * @param details — optional underlying error or extra context
+     */
+    constructor(message: string, code: string, binaryName: string, guidance: string, recoverable?: boolean, details?: unknown);
+}
+/**
+ * Common error code constants shared across many CLIs.
+ * Consumers can use these or define their own — these are suggestions, not constraints.
+ *
+ * @example
+ * // Use a common code
+ * new CLISubprocessError('Not found', CLI_ERROR.BINARY_NOT_FOUND, 'claude', '...');
+ *
+ * // Use a custom code
+ * new CLISubprocessError('Codec missing', 'CODEC_NOT_FOUND', 'ffmpeg', '...');
+ */
+export declare const CLI_ERROR: {
+    /** Binary not found on PATH. */
+    readonly BINARY_NOT_FOUND: "BINARY_NOT_FOUND";
+    /** Binary installed but not authenticated / logged in. */
+    readonly NOT_AUTHENTICATED: "NOT_AUTHENTICATED";
+    /** Binary version too old for required features. */
+    readonly VERSION_OUTDATED: "VERSION_OUTDATED";
+    /** Process failed to start (permissions, missing deps, etc.). */
+    readonly SPAWN_FAILED: "SPAWN_FAILED";
+    /** Process exceeded timeout. */
+    readonly TIMEOUT: "TIMEOUT";
+    /** Process exited with non-zero exit code. */
+    readonly CRASHED: "CRASHED";
+    /** Rate limit / quota exceeded. */
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    /** Permission denied (EACCES). */
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    /** Input/context too long for the CLI to handle. */
+    readonly CONTEXT_TOO_LONG: "CONTEXT_TOO_LONG";
+};
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/subprocess/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,6EAA6E;IAC7E,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,kEAAkE;IAClE,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC,yDAAyD;IACzD,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC,iDAAiD;IACjD,SAAgB,WAAW,EAAE,OAAO,CAAC;IAErC,kDAAkD;IAClD,SAAgB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElC;;;;;;;OAOG;gBAED,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,WAAW,GAAE,OAAe,EAC5B,OAAO,CAAC,EAAE,OAAO;CAYpB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS;IACpB,gCAAgC;;IAEhC,0DAA0D;;IAE1D,oDAAoD;;IAEpD,iEAAiE;;IAEjE,gCAAgC;;IAEhC,8CAA8C;;IAE9C,mCAAmC;;IAEnC,kCAAkC;;IAElC,oDAAoD;;CAE5C,CAAC"}

package/dist/core/subprocess/errors.js

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Base error class for CLI subprocess operations.
+ * Fully generic — works for any binary (LLM CLIs, dev tools, media tools, etc.).
+ * Error codes are open strings so each consumer can define their own.
+ *
+ * @module agentos/core/subprocess/errors
+ */
+/**
+ * Base error for ANY CLI subprocess managed by {@link CLISubprocessBridge}.
+ * Not specific to LLM CLIs — works for ffmpeg, git, docker, or any binary.
+ *
+ * Carries actionable {@link guidance} so the user knows how to fix the problem,
+ * and a {@link recoverable} flag so callers know whether to retry or fall back.
+ *
+ * @example
+ * throw new CLISubprocessError(
+ *   'ffmpeg not found.',
+ *   CLI_ERROR.BINARY_NOT_FOUND,
+ *   'ffmpeg',
+ *   'Install ffmpeg: brew install ffmpeg',
+ *   false,
+ * );
+ */
+export class CLISubprocessError extends Error {
+    /**
+     * @param message — human-readable error description
+     * @param code — error code string (use {@link CLI_ERROR} constants or your own)
+     * @param binaryName — the CLI binary that failed
+     * @param guidance — actionable fix instructions shown to the user
+     * @param recoverable — true if the caller should attempt retry/fallback (default false)
+     * @param details — optional underlying error or extra context
+     */
+    constructor(message, code, binaryName, guidance, recoverable = false, details) {
+        super(message);
+        this.name = 'CLISubprocessError';
+        this.code = code;
+        this.binaryName = binaryName;
+        this.guidance = guidance;
+        this.recoverable = recoverable;
+        this.details = details;
+        Object.setPrototypeOf(this, CLISubprocessError.prototype);
+    }
+}
+/**
+ * Common error code constants shared across many CLIs.
+ * Consumers can use these or define their own — these are suggestions, not constraints.
+ *
+ * @example
+ * // Use a common code
+ * new CLISubprocessError('Not found', CLI_ERROR.BINARY_NOT_FOUND, 'claude', '...');
+ *
+ * // Use a custom code
+ * new CLISubprocessError('Codec missing', 'CODEC_NOT_FOUND', 'ffmpeg', '...');
+ */
+export const CLI_ERROR = {
+    /** Binary not found on PATH. */
+    BINARY_NOT_FOUND: 'BINARY_NOT_FOUND',
+    /** Binary installed but not authenticated / logged in. */
+    NOT_AUTHENTICATED: 'NOT_AUTHENTICATED',
+    /** Binary version too old for required features. */
+    VERSION_OUTDATED: 'VERSION_OUTDATED',
+    /** Process failed to start (permissions, missing deps, etc.). */
+    SPAWN_FAILED: 'SPAWN_FAILED',
+    /** Process exceeded timeout. */
+    TIMEOUT: 'TIMEOUT',
+    /** Process exited with non-zero exit code. */
+    CRASHED: 'CRASHED',
+    /** Rate limit / quota exceeded. */
+    RATE_LIMITED: 'RATE_LIMITED',
+    /** Permission denied (EACCES). */
+    PERMISSION_DENIED: 'PERMISSION_DENIED',
+    /** Input/context too long for the CLI to handle. */
+    CONTEXT_TOO_LONG: 'CONTEXT_TOO_LONG',
+};
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/core/subprocess/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAgB3C;;;;;;;OAOG;IACH,YACE,OAAe,EACf,IAAY,EACZ,UAAkB,EAClB,QAAgB,EAChB,cAAuB,KAAK,EAC5B,OAAiB;QAEjB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAEvB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAC5D,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,gCAAgC;IAChC,gBAAgB,EAAE,kBAAkB;IACpC,0DAA0D;IAC1D,iBAAiB,EAAE,mBAAmB;IACtC,oDAAoD;IACpD,gBAAgB,EAAE,kBAAkB;IACpC,iEAAiE;IACjE,YAAY,EAAE,cAAc;IAC5B,gCAAgC;IAChC,OAAO,EAAE,SAAS;IAClB,8CAA8C;IAC9C,OAAO,EAAE,SAAS;IAClB,mCAAmC;IACnC,YAAY,EAAE,cAAc;IAC5B,kCAAkC;IAClC,iBAAiB,EAAE,mBAAmB;IACtC,oDAAoD;IACpD,gBAAgB,EAAE,kBAAkB;CAC5B,CAAC"}

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

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Core subprocess management — first-class AgentOS capability
+ * for spawning and managing external CLI binaries.
+ *
+ * @module agentos/core/subprocess
+ */
+export { CLISubprocessBridge } from './CLISubprocessBridge';
+export { CLIRegistry, WELL_KNOWN_CLIS } from './CLIRegistry';
+export { CLISubprocessError, CLI_ERROR } from './errors';
+export type { BridgeOptions, BridgeResult, StreamEvent, OutputFormat, InstallCheckResult, CLIDescriptor, CLIScanResult, } from './types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/subprocess/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACzD,YAAY,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,aAAa,GACd,MAAM,SAAS,CAAC"}

package/dist/core/subprocess/index.js

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Core subprocess management — first-class AgentOS capability
+ * for spawning and managing external CLI binaries.
+ *
+ * @module agentos/core/subprocess
+ */
+export { CLISubprocessBridge } from './CLISubprocessBridge.js';
+export { CLIRegistry, WELL_KNOWN_CLIS } from './CLIRegistry.js';
+export { CLISubprocessError, CLI_ERROR } from './errors.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/subprocess/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}

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

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Shared types for the CLI subprocess bridge system.
+ * These types are CLI-agnostic — they work for any binary managed
+ * by {@link CLISubprocessBridge} (LLM CLIs, dev tools, media tools, etc.).
+ *
+ * @module agentos/core/subprocess/types
+ */
+/** Output format supported by CLI subprocess bridges. */
+export type OutputFormat = 'json' | 'stream-json' | 'text';
+/** Options for {@link CLISubprocessBridge.execute} and {@link CLISubprocessBridge.stream}. */
+export interface BridgeOptions {
+    /** The prompt or input text to pipe via stdin. */
+    prompt: string;
+    /** System prompt — how it's passed depends on the CLI (flag, file, env var). */
+    systemPrompt?: string;
+    /** Model ID for LLM CLIs. */
+    model?: string;
+    /** JSON schema for structured output (if the CLI supports it). */
+    jsonSchema?: object;
+    /** Maximum agentic turns (if the CLI supports it). */
+    maxTurns?: number;
+    /** Subprocess timeout in milliseconds (default 120 000). */
+    timeout?: number;
+    /** AbortSignal to cancel the subprocess. */
+    abortSignal?: AbortSignal;
+    /** Extra CLI flags specific to a particular bridge. */
+    extraArgs?: string[];
+    /** Extra environment variables merged into the subprocess env. */
+    env?: Record<string, string>;
+}
+/** Result from a non-streaming {@link CLISubprocessBridge.execute} call. */
+export interface BridgeResult {
+    /** The text result returned by the CLI. */
+    result: string;
+    /** Session ID for potential future use. */
+    sessionId?: string;
+    /** Token usage stats if available. */
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    /** Whether the CLI reported an error. */
+    isError: boolean;
+    /** Wall-clock duration of the subprocess in ms. */
+    durationMs: number;
+}
+/** Typed events yielded by {@link CLISubprocessBridge.stream}. */
+export type StreamEvent = {
+    type: 'text_delta';
+    text: string;
+} | {
+    type: 'result';
+    result: string;
+    sessionId?: string;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+} | {
+    type: 'error';
+    error: string;
+} | {
+    type: 'system';
+    message: string;
+};
+/** Result from {@link CLISubprocessBridge.checkBinaryInstalled}. */
+export type InstallCheckResult = {
+    installed: true;
+    binaryPath: string;
+    version: string;
+} | {
+    installed: false;
+};
+/** Descriptor for a known CLI binary. Used by {@link CLIRegistry}. */
+export interface CLIDescriptor {
+    /** Binary name on PATH (e.g. 'claude', 'gemini', 'docker', 'ffmpeg'). */
+    binaryName: string;
+    /** Human-readable display name. */
+    displayName: string;
+    /** What this CLI does. */
+    description: string;
+    /** Category for grouping (e.g. 'llm', 'media', 'devtools', 'cloud', 'runtime'). */
+    category: string;
+    /** How to install if missing. */
+    installGuidance: string;
+    /** Version flag override if not --version. */
+    versionFlag?: string;
+    /** Regex to parse version from output (default: /(\d+\.\d+\.\d+)/). */
+    versionPattern?: RegExp;
+}
+/** Result from {@link CLIRegistry.scan} or {@link CLIRegistry.check}. */
+export interface CLIScanResult extends CLIDescriptor {
+    /** Whether the binary was found on PATH. */
+    installed: boolean;
+    /** Resolved absolute path to the binary. */
+    binaryPath?: string;
+    /** Parsed version string. */
+    version?: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/subprocess/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,yDAAyD;AACzD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,aAAa,GAAG,MAAM,CAAC;AAE3D,8FAA8F;AAC9F,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,KAAK,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,kEAAkE;AAClE,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC/G;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,oEAAoE;AACpE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,SAAS,EAAE,KAAK,CAAA;CAAE,CAAC;AAMzB,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,4CAA4C;IAC5C,SAAS,EAAE,OAAO,CAAC;IACnB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/core/subprocess/types.js

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Shared types for the CLI subprocess bridge system.
+ * These types are CLI-agnostic — they work for any binary managed
+ * by {@link CLISubprocessBridge} (LLM CLIs, dev tools, media tools, etc.).
+ *
+ * @module agentos/core/subprocess/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/subprocess/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}