background-agents 0.1.1

package/dist/session.js

@@ -0,0 +1,113 @@
+import { randomUUID } from "node:crypto";
+import { debugLog } from "./debug.js";
+import { createProvider } from "./factory.js";
+import { adaptSandbox } from "./sandbox/index.js";
+const CODEAGENT_SESSION_DIR_PREFIX = "/tmp/codeagent-";
+/** Cache reattached background sessions by id so status/getEvents polls don't recreate the provider every time. */
+const backgroundSessionCache = new Map();
+async function readProviderFromMeta(sandbox, sessionDir) {
+    const adapted = adaptSandbox(sandbox);
+    if (!adapted.executeCommand)
+        return null;
+    const result = await adapted.executeCommand(`cat "${sessionDir}/meta.json" 2>/dev/null || true`, 10);
+    const raw = (result.output ?? "").trim();
+    if (!raw)
+        return null;
+    try {
+        const o = JSON.parse(raw);
+        return {
+            provider: o.provider ?? null,
+            sessionId: o.sessionId ?? null,
+        };
+    }
+    catch {
+        return { provider: null, sessionId: null };
+    }
+}
+/**
+ * Create a session: a provider with run defaults (model, timeout, env) set at creation.
+ * Returns the provider; call session.run(prompt) with just the prompt string.
+ */
+export async function createSession(name, options) {
+    debugLog("createSession", options.sessionId, name);
+    const { model, sessionId, timeout, systemPrompt, skipInstall, env, ...providerOptions } = options;
+    const runDefaults = { model, sessionId, timeout, systemPrompt, skipInstall, env };
+    const provider = createProvider(name, { ...providerOptions, skipInstall, env, runDefaults });
+    await provider.ready;
+    debugLog("createSession ready", options.sessionId, name);
+    return provider;
+}
+/**
+ * Create a background session: a provider configured for sandboxed background
+ * execution with one log file per turn and meta/cursor in the sandbox.
+ * Use start() to begin a turn and getEvents() to consume events (no cursor argument).
+ */
+export async function createBackgroundSession(name, options) {
+    const { backgroundSessionId, ...sessionOptions } = options;
+    const id = backgroundSessionId ?? randomUUID();
+    debugLog("createBackgroundSession", options.sessionId, name, "id=" + id);
+    return createBackgroundSessionWithId(name, { ...sessionOptions, backgroundSessionId: id }, id);
+}
+/** Reattach to an existing background session by id (e.g. after restart). Provider is read from sandbox meta (written at session creation). Cached per id so repeated polls don't recreate the provider. */
+export async function getBackgroundSession(options) {
+    const { backgroundSessionId, sandbox } = options;
+    const cached = backgroundSessionCache.get(backgroundSessionId);
+    if (cached) {
+        debugLog("getBackgroundSession", cached.provider.sessionId, "id=" + backgroundSessionId, "cached");
+        return cached;
+    }
+    const sessionDir = `${CODEAGENT_SESSION_DIR_PREFIX}${backgroundSessionId}`;
+    debugLog("getBackgroundSession", undefined, "id=" + backgroundSessionId, "sessionDir=" + sessionDir);
+    const meta = await readProviderFromMeta(sandbox, sessionDir);
+    if (!meta?.provider) {
+        debugLog("getBackgroundSession meta missing or no provider", meta?.sessionId ?? undefined, backgroundSessionId);
+        throw new Error("Cannot get background session: meta not found (start a turn first) or meta has no provider");
+    }
+    debugLog("getBackgroundSession reattach provider=" + meta.provider, meta.sessionId);
+    return createBackgroundSessionWithId(meta.provider, {
+        ...options,
+        // Seed sessionId so providers that support resume (e.g. Claude) can continue the same session.
+        sessionId: meta.sessionId ?? options.sessionId,
+    }, backgroundSessionId, { skipWriteInitialMeta: true });
+}
+async function createBackgroundSessionWithId(name, options, id, opts) {
+    const provider = await createSession(name, options);
+    const sessionDir = `${CODEAGENT_SESSION_DIR_PREFIX}${id}`;
+    if (!opts?.skipWriteInitialMeta) {
+        await provider.writeInitialSessionMeta(sessionDir);
+    }
+    const session = {
+        id,
+        provider,
+        async start(prompt, extraOptions) {
+            debugLog("BackgroundSession.start", provider.sessionId, "id=" + id, "sessionDir=" + sessionDir, "promptLength=" + prompt.length);
+            const result = await provider.startSandboxBackgroundTurn(sessionDir, {
+                // Re-apply core run defaults (model, timeout, env, systemPrompt) for each turn.
+                model: options.model,
+                timeout: options.timeout,
+                env: options.env,
+                systemPrompt: options.systemPrompt,
+                sessionId: options.sessionId,
+                ...(extraOptions ?? {}),
+                prompt,
+            });
+            debugLog("BackgroundSession.start returned", provider.sessionId, "id=" + id, "pid=" + result.pid, "outputFile=" + result.outputFile);
+            return result;
+        },
+        async getEvents() {
+            return provider.getEventsSandboxBackgroundFromMeta(sessionDir);
+        },
+        async isRunning() {
+            return provider.isSandboxBackgroundProcessRunning(sessionDir);
+        },
+        async getPid() {
+            return provider.getSandboxBackgroundPid(sessionDir);
+        },
+        async cancel() {
+            return provider.cancelSandboxBackground(sessionDir);
+        },
+    };
+    backgroundSessionCache.set(id, session);
+    return session;
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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

package/dist/types/events.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Event types emitted by AI coding agents
+ */
+/** Session started event - contains the session ID for resumption */
+export interface SessionEvent {
+    type: "session";
+    id: string;
+}
+/** Token event - a text token from the assistant's response */
+export interface TokenEvent {
+    type: "token";
+    text: string;
+}
+/** Normalized tool names (same across Claude, Codex, etc.) */
+export type ToolName = "write" | "read" | "edit" | "glob" | "grep" | "shell";
+/** Input for the write tool (create/overwrite file). Canonical: always include kind + content (nullable). */
+export interface WriteToolInput {
+    file_path: string;
+    content: string | null;
+    kind: "add" | "update";
+}
+/** Input for the read tool (path to file). Canonical: always file_path. */
+export interface ReadToolInput {
+    file_path: string;
+}
+/** Input for the edit tool (patch/edit file). Canonical: file_path + optional rest. */
+export interface EditToolInput {
+    file_path: string;
+    [key: string]: unknown;
+}
+/** Input for the glob tool (file search by pattern). */
+export interface GlobToolInput {
+    pattern: string;
+}
+/** Input for the grep tool (content search). */
+export interface GrepToolInput {
+    pattern: string;
+    path?: string;
+}
+/** Input for the shell tool (run a command). */
+export interface ShellToolInput {
+    command: string;
+    description?: string;
+}
+/** Tool input map for narrowing by tool name */
+export interface ToolInputMap {
+    write: WriteToolInput;
+    read: ReadToolInput;
+    edit: EditToolInput;
+    glob: GlobToolInput;
+    grep: GrepToolInput;
+    shell: ShellToolInput;
+}
+/** Tool start event – discriminated by name for typed input */
+export type ToolStartEvent = {
+    type: "tool_start";
+    name: "write";
+    input?: WriteToolInput;
+} | {
+    type: "tool_start";
+    name: "read";
+    input?: ReadToolInput;
+} | {
+    type: "tool_start";
+    name: "edit";
+    input?: EditToolInput;
+} | {
+    type: "tool_start";
+    name: "glob";
+    input?: GlobToolInput;
+} | {
+    type: "tool_start";
+    name: "grep";
+    input?: GrepToolInput;
+} | {
+    type: "tool_start";
+    name: "shell";
+    input?: ShellToolInput;
+} | {
+    type: "tool_start";
+    name: string;
+    input?: unknown;
+};
+/** Normalize raw provider payload into typed tool input and return a typed ToolStartEvent */
+export declare function createToolStartEvent(name: ToolName | string, rawInput?: unknown): ToolStartEvent;
+/** Tool delta event - partial input being streamed to a tool */
+export interface ToolDeltaEvent {
+    type: "tool_delta";
+    text: string;
+}
+/** Tool end event - indicates tool invocation is complete */
+export interface ToolEndEvent {
+    type: "tool_end";
+    /** Tool result/output when provided by the CLI */
+    output?: string;
+}
+/** End event - indicates the message/turn is complete */
+export interface EndEvent {
+    type: "end";
+    /** When the CLI failed (e.g. error_during_execution), the error message if available */
+    error?: string;
+}
+/** Agent crashed event - process exited without emitting end (e.g. crash or kill) */
+export interface AgentCrashedEvent {
+    type: "agent_crashed";
+    message?: string;
+    /** Raw tail of stdout/stderr before exit (often not valid JSONL; use for debugging only) */
+    output?: string;
+}
+/** Union type of all possible events */
+export type Event = SessionEvent | TokenEvent | ToolStartEvent | ToolDeltaEvent | ToolEndEvent | EndEvent | AgentCrashedEvent;
+/** Event type discriminator */
+export type EventType = Event["type"];
+//# sourceMappingURL=events.d.ts.map

package/dist/types/events.d.ts.map

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

package/dist/types/events.js

@@ -0,0 +1,50 @@
+/**
+ * Event types emitted by AI coding agents
+ */
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Normalize raw provider payload into typed tool input and return a typed ToolStartEvent */
+export function createToolStartEvent(name, rawInput) {
+    let input = rawInput;
+    if (name === "write" && isObject(rawInput)) {
+        const path = rawInput.file_path ?? rawInput.filePath ?? rawInput.path;
+        if (typeof path === "string") {
+            const kind = rawInput.kind === "add" || rawInput.kind === "update" ? rawInput.kind : "update";
+            input = {
+                file_path: path,
+                content: typeof rawInput.content === "string" ? rawInput.content : null,
+                kind,
+            };
+        }
+    }
+    else if (name === "read" && isObject(rawInput)) {
+        const path = rawInput.file_path ?? rawInput.filePath ?? rawInput.path;
+        if (typeof path === "string") {
+            input = { file_path: path };
+        }
+    }
+    else if (name === "edit" && isObject(rawInput)) {
+        const path = rawInput.file_path ?? rawInput.filePath ?? rawInput.path;
+        if (typeof path === "string") {
+            input = { file_path: path, ...rawInput };
+        }
+    }
+    else if (name === "shell" && isObject(rawInput) && typeof rawInput.command === "string") {
+        input = {
+            command: rawInput.command,
+            description: typeof rawInput.description === "string" ? rawInput.description : undefined,
+        };
+    }
+    else if (name === "glob" && isObject(rawInput) && typeof rawInput.pattern === "string") {
+        input = { pattern: rawInput.pattern };
+    }
+    else if (name === "grep" && isObject(rawInput) && typeof rawInput.pattern === "string") {
+        input = {
+            pattern: rawInput.pattern,
+            path: typeof rawInput.path === "string" ? rawInput.path : undefined,
+        };
+    }
+    return { type: "tool_start", name, input };
+}
+//# sourceMappingURL=events.js.map

package/dist/types/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"AAAA;;GAEG;AAwEH,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;AACjE,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,oBAAoB,CAAC,IAAuB,EAAE,QAAkB;IAC9E,IAAI,KAAK,GAAY,QAAQ,CAAA;IAC7B,IAAI,IAAI,KAAK,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,CAAA;QACrE,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,KAAK,KAAK,IAAI,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAA;YAC7F,KAAK,GAAG;gBACN,SAAS,EAAE,IAAI;gBACf,OAAO,EAAE,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;gBACvE,IAAI;aACoB,CAAA;QAC5B,CAAC;IACH,CAAC;SAAM,IAAI,IAAI,KAAK,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,CAAA;QACrE,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,KAAK,GAAG,EAAE,SAAS,EAAE,IAAI,EAA0B,CAAA;QACrD,CAAC;IACH,CAAC;SAAM,IAAI,IAAI,KAAK,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,CAAA;QACrE,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,KAAK,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAmB,CAAA;QAC3D,CAAC;IACH,CAAC;SAAM,IAAI,IAAI,KAAK,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC1F,KAAK,GAAG;YACN,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,WAAW,EAAE,OAAO,QAAQ,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;SAChE,CAAA;IAC5B,CAAC;SAAM,IAAI,IAAI,KAAK,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzF,KAAK,GAAG,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAA0B,CAAA;IAC/D,CAAC;SAAM,IAAI,IAAI,KAAK,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzF,KAAK,GAAG;YACN,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,IAAI,EAAE,OAAO,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;SAC5C,CAAA;IAC3B,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,EAAoB,CAAA;AAC9D,CAAC"}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./events.js";
+export * from "./provider.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/dist/types/index.js

@@ -0,0 +1,3 @@
+export * from "./events.js";
+export * from "./provider.js";
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/dist/types/provider.d.ts

@@ -0,0 +1,124 @@
+import type { Event } from "./events.js";
+/**
+ * Provider-related types and interfaces
+ */
+/** Supported provider names */
+export type ProviderName = "claude" | "codex" | "opencode" | "gemini";
+/** Options for starting a background command that writes to a log file and signals when done. */
+export interface ExecuteBackgroundOptions {
+    /** Full command line to run (stdout/stderr should be appended to outputFile). */
+    command: string;
+    /** Path in sandbox to append output to (e.g. /tmp/codeagent-<id>/0.jsonl). */
+    outputFile: string;
+    /** Unique run id (used for logging; PID is returned from executeBackground). */
+    runId: string;
+    timeout?: number;
+}
+/**
+ * Sandbox interface required by the SDK. Implement this yourself or use
+ * adaptDaytonaSandbox() to wrap a Daytona Sandbox from @daytonaio/sdk.
+ */
+export interface CodeAgentSandbox {
+    ensureProvider(name: ProviderName): Promise<void>;
+    setEnvVars(vars: Record<string, string>): void;
+    executeCommandStream(command: string, timeout?: number): AsyncGenerator<string, void, unknown>;
+    /** Optional: run a one-off command (used e.g. for Codex login). */
+    executeCommand?(command: string, timeout?: number): Promise<{
+        exitCode: number;
+        output: string;
+    }>;
+    /**
+     * Optional: start a command in the background and return its pid immediately.
+     * The sandbox must run the command with stdout/stderr >> outputFile and return
+     * the pid (e.g. via nohup + SSH so the channel closes right away). Implement
+     * this to avoid blocking on the command when using executeCommand.
+     */
+    executeBackground?(options: ExecuteBackgroundOptions): Promise<{
+        pid: number;
+    }>;
+    /**
+     * Optional: kill a process by pid. Must use the same execution context that
+     * started it (e.g. SSH); process API kill won't see pids started over SSH.
+     */
+    killBackgroundProcess?(pid: number): Promise<void>;
+}
+/** Command configuration for spawning a provider process */
+export interface ProviderCommand {
+    cmd: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+/** Options when adapting a Daytona sandbox for use with the SDK */
+export interface AdaptSandboxOptions {
+    /** Environment variables for CLI execution (e.g. ANTHROPIC_API_KEY) */
+    env?: Record<string, string>;
+}
+/** Options for running a provider */
+export interface RunOptions {
+    /** The prompt to send to the provider */
+    prompt?: string;
+    /**
+     * Optional system prompt / high-level instructions.
+     * When set via createSession, providers that support system prompts will use
+     * their native mechanism; others will have this string prepended to the first
+     * user prompt in the session.
+     */
+    systemPrompt?: string;
+    /** Optional session ID to resume */
+    sessionId?: string;
+    /** Whether to persist session ID to file (only for local mode) */
+    persistSession?: boolean;
+    /** Custom session file path (only for local mode) */
+    sessionFile?: string;
+    /** Working directory for the provider process */
+    cwd?: string;
+    /** Environment variables to pass to the provider */
+    env?: Record<string, string>;
+    /** Skip installing the CLI in the sandbox (default: false) */
+    skipInstall?: boolean;
+    /** Timeout in seconds for sandbox execution (default: 120) */
+    timeout?: number;
+    /** Model to use (provider-specific, e.g., "openai/gpt-4o") */
+    model?: string;
+}
+/** Default run options merged into every run (used by createSession) */
+export type RunDefaults = Partial<Omit<RunOptions, "prompt">>;
+/** Options for creating a provider */
+export interface ProviderOptions {
+    /**
+     * Sandbox for secure execution. Pass a Sandbox from @daytonaio/sdk directly
+     * (the SDK adapts it internally). Optional env here is used for CLI execution.
+     */
+    sandbox?: CodeAgentSandbox | import("@daytonaio/sdk").Sandbox;
+    /** Environment variables for CLI execution (e.g. when sandbox is a Daytona Sandbox) */
+    env?: Record<string, string>;
+    /** Skip installing the provider CLI when the provider is created (default: false) */
+    skipInstall?: boolean;
+    /**
+     * Allow running commands directly on local machine without sandbox.
+     * ⚠️ DANGEROUS: Only use this if you trust the code being executed.
+     */
+    dangerouslyAllowLocalExecution?: boolean;
+    /** Defaults merged into every run() call (model, timeout, sessionId, env). Set by createSession. */
+    runDefaults?: RunDefaults;
+}
+/** Event handler callback */
+export type EventHandler = (event: Event) => void | Promise<void>;
+/** Provider interface that all providers must implement */
+export interface IProvider {
+    /** Provider name */
+    readonly name: ProviderName;
+    /** Current session ID */
+    sessionId: string | null;
+    /** Convenience accessor for current session id */
+    getSessionId(): string | null;
+    /** Get the command to spawn the provider */
+    getCommand(options?: RunOptions): ProviderCommand;
+    /** Parse a line of output into one or more events */
+    parse(line: string): Event | Event[] | null;
+    /** Resolves when CLI install and setup (env, Codex login) have completed. Await before first run if you want "ready" UX. */
+    readonly ready: Promise<void>;
+    /** Run the provider and emit events. Pass a prompt string or full RunOptions. */
+    run(promptOrOptions?: string | RunOptions): AsyncGenerator<Event, void, unknown>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/types/provider.d.ts.map

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

package/dist/types/provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/types/provider.js.map

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

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./json.js";
+export * from "./session.js";
+export * from "./install.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA"}

package/dist/utils/index.js

@@ -0,0 +1,4 @@
+export * from "./json.js";
+export * from "./session.js";
+export * from "./install.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA"}

package/dist/utils/install.d.ts

@@ -0,0 +1,27 @@
+import type { ProviderName } from "../types/index.js";
+/**
+ * Check if a CLI command is available in PATH
+ */
+export declare function isCliInstalled(name: ProviderName): boolean;
+/**
+ * Get the npm package name for a provider
+ */
+export declare function getPackageName(name: ProviderName): string;
+/**
+ * Install a provider CLI globally via npm
+ * @returns true if installation succeeded
+ */
+export declare function installProvider(name: ProviderName): boolean;
+/**
+ * Ensure a provider CLI is installed, installing it if necessary
+ * @param name - Provider name
+ * @param autoInstall - Whether to automatically install if missing (default: false)
+ * @returns true if CLI is available (either already installed or successfully installed)
+ * @throws Error if CLI is not installed and autoInstall is false
+ */
+export declare function ensureCliInstalled(name: ProviderName, autoInstall?: boolean): boolean;
+/**
+ * Check installation status of all providers
+ */
+export declare function getInstallationStatus(): Record<ProviderName, boolean>;
+//# sourceMappingURL=install.d.ts.map

package/dist/utils/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/utils/install.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAYrD;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAU1D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAEzD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAY3D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,YAAY,EAClB,WAAW,GAAE,OAAe,GAC3B,OAAO,CA0BT;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,CASrE"}

package/dist/utils/install.js

@@ -0,0 +1,86 @@
+import { execSync, spawnSync } from "node:child_process";
+/**
+ * CLI package information for each provider
+ */
+const PROVIDER_PACKAGES = {
+    claude: "@anthropic-ai/claude-code",
+    codex: "@openai/codex",
+    opencode: "opencode",
+    gemini: "@google/gemini-cli",
+};
+/**
+ * Check if a CLI command is available in PATH
+ */
+export function isCliInstalled(name) {
+    try {
+        const result = spawnSync("which", [name], {
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get the npm package name for a provider
+ */
+export function getPackageName(name) {
+    return PROVIDER_PACKAGES[name];
+}
+/**
+ * Install a provider CLI globally via npm
+ * @returns true if installation succeeded
+ */
+export function installProvider(name) {
+    const packageName = PROVIDER_PACKAGES[name];
+    try {
+        execSync(`npm install -g ${packageName}`, {
+            stdio: "inherit",
+            encoding: "utf8",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensure a provider CLI is installed, installing it if necessary
+ * @param name - Provider name
+ * @param autoInstall - Whether to automatically install if missing (default: false)
+ * @returns true if CLI is available (either already installed or successfully installed)
+ * @throws Error if CLI is not installed and autoInstall is false
+ */
+export function ensureCliInstalled(name, autoInstall = false) {
+    if (isCliInstalled(name)) {
+        return true;
+    }
+    if (!autoInstall) {
+        const packageName = PROVIDER_PACKAGES[name];
+        throw new Error(`CLI '${name}' is not installed. ` +
+            `Install it with: npm install -g ${packageName}`);
+    }
+    console.log(`Installing ${name} CLI...`);
+    const success = installProvider(name);
+    if (!success) {
+        const packageName = PROVIDER_PACKAGES[name];
+        throw new Error(`Failed to install '${name}' CLI. ` +
+            `Try manually: npm install -g ${packageName}`);
+    }
+    console.log(`Successfully installed ${name} CLI`);
+    return true;
+}
+/**
+ * Check installation status of all providers
+ */
+export function getInstallationStatus() {
+    const providers = ["claude", "codex", "opencode", "gemini"];
+    const status = {};
+    for (const provider of providers) {
+        status[provider] = isCliInstalled(provider);
+    }
+    return status;
+}
+//# sourceMappingURL=install.js.map

package/dist/utils/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/utils/install.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAGxD;;GAEG;AACH,MAAM,iBAAiB,GAAiC;IACtD,MAAM,EAAE,2BAA2B;IACnC,KAAK,EAAE,eAAe;IACtB,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,oBAAoB;CAC7B,CAAA;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,IAAkB;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE;YACxC,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAA;QACF,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAA;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,IAAkB;IAC/C,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAA;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAkB;IAChD,MAAM,WAAW,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAA;IAE3C,IAAI,CAAC;QACH,QAAQ,CAAC,kBAAkB,WAAW,EAAE,EAAE;YACxC,KAAK,EAAE,SAAS;YAChB,QAAQ,EAAE,MAAM;SACjB,CAAC,CAAA;QACF,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAkB,EAClB,cAAuB,KAAK;IAE5B,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,WAAW,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAA;QAC3C,MAAM,IAAI,KAAK,CACb,QAAQ,IAAI,sBAAsB;YAChC,mCAAmC,WAAW,EAAE,CACnD,CAAA;IACH,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,SAAS,CAAC,CAAA;IACxC,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,CAAA;IAErC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,WAAW,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAA;QAC3C,MAAM,IAAI,KAAK,CACb,sBAAsB,IAAI,SAAS;YACjC,gCAAgC,WAAW,EAAE,CAChD,CAAA;IACH,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,MAAM,CAAC,CAAA;IACjD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,SAAS,GAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAA;IAC3E,MAAM,MAAM,GAA4B,EAAE,CAAA;IAE1C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAA;IAC7C,CAAC;IAED,OAAO,MAAuC,CAAA;AAChD,CAAC"}

package/dist/utils/json.d.ts

@@ -0,0 +1,8 @@
+/**
+ * JSON parsing utilities
+ */
+/**
+ * Safely parse JSON, returning null on failure
+ */
+export declare function safeJsonParse<T = unknown>(text: string): T | null;
+//# sourceMappingURL=json.d.ts.map

package/dist/utils/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/utils/json.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAMjE"}

package/dist/utils/json.js

@@ -0,0 +1,15 @@
+/**
+ * JSON parsing utilities
+ */
+/**
+ * Safely parse JSON, returning null on failure
+ */
+export function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=json.js.map

package/dist/utils/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/utils/json.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,UAAU,aAAa,CAAc,IAAY;IACrD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAA;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC"}

package/dist/utils/session.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Get the default session file path
+ */
+export declare function getDefaultSessionPath(providerName: string): string;
+/**
+ * Load a session ID from file
+ */
+export declare function loadSession(filePath: string): string | null;
+/**
+ * Store a session ID to file
+ */
+export declare function storeSession(filePath: string, sessionId: string): boolean;
+/**
+ * Clear a session file
+ */
+export declare function clearSession(filePath: string): boolean;
+//# sourceMappingURL=session.d.ts.map