axexec 1.0.0

package/dist/run-agent.js

@@ -0,0 +1,146 @@
+/**
+ * Agent execution with credential isolation and config generation.
+ */
+import { buildAgentConfig } from "axconfig";
+import { isStreamableAdapter } from "./types/adapter.js";
+import { installCredentials, cleanupCredentials, } from "./credentials/install-credentials.js";
+import { streamAgent } from "./stream-agent.js";
+import { validateAgent } from "./validate-agent.js";
+import { resolveOutputMode } from "./resolve-output-mode.js";
+import { createEventWriter } from "./write-event.js";
+import { parseCredentialsFromEnvironment } from "./parse-credentials.js";
+import { DependencyError } from "./resolve-binary.js";
+/**
+ * Runs an agent with full isolation.
+ *
+ * 1. Validates the agent ID
+ * 2. Parses credentials from environment
+ * 3. Installs credentials to temp directory
+ * 4. Builds config if permissions specified
+ * 5. Streams events from agent
+ * 6. Cleans up temp directory
+ */
+async function runAgent(agentId, options) {
+    // Validate agent
+    const validation = validateAgent(agentId);
+    if (!validation.ok) {
+        process.stderr.write(validation.message + "\n");
+        process.exitCode = validation.exitCode;
+        return { events: [], success: false };
+    }
+    const { adapter } = validation;
+    // Parse credentials from environment
+    const credentials = parseCredentialsFromEnvironment(agentId);
+    // Install credentials to temp directory
+    let credentialResult;
+    try {
+        credentialResult = await installCredentials(validation.agentId, credentials);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`Error installing credentials: ${message}\n`);
+        process.exitCode = 1;
+        return { events: [], success: false };
+    }
+    // Build config if permissions specified
+    let configEnvironment = credentialResult.env;
+    if (options.allow || options.deny) {
+        const configResult = buildConfig(validation.agentId, options, credentialResult);
+        if (!configResult.ok) {
+            await cleanupCredentials(credentialResult.baseDirectory);
+            process.exitCode = configResult.exitCode;
+            return { events: [], success: false };
+        }
+        configEnvironment = configResult.env;
+    }
+    // Execute agent
+    return executeAgent(adapter, options, configEnvironment, credentialResult);
+}
+/**
+ * Builds agent config with permissions.
+ */
+function buildConfig(agentId, options, credentialResult) {
+    try {
+        const configResult = buildAgentConfig({
+            agentId,
+            allow: options.allow,
+            deny: options.deny,
+            output: credentialResult.configDirectory,
+        });
+        if (!configResult.ok) {
+            if ("message" in configResult) {
+                process.stderr.write(`Error: ${configResult.message}\n`);
+            }
+            else {
+                process.stderr.write(`Error building config: permission errors\n`);
+                for (const error of configResult.errors) {
+                    process.stderr.write(`  - ${error.reason}\n`);
+                }
+            }
+            return { ok: false, exitCode: configResult.exitCode };
+        }
+        // Log warnings
+        for (const warning of configResult.warnings) {
+            process.stderr.write(`Warning: ${warning.reason}\n`);
+        }
+        // Merge config env with credential env (config env takes precedence)
+        return {
+            ok: true,
+            env: { ...credentialResult.env, ...configResult.env },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`Error parsing permissions: ${message}\n`);
+        return { ok: false, exitCode: 1 };
+    }
+}
+/**
+ * Executes agent and streams events.
+ */
+async function executeAgent(adapter, options, configEnvironment, credentialResult) {
+    const runOptions = {
+        prompt: options.prompt,
+        verbose: options.verbose ?? false,
+        model: options.model,
+        rawLogPath: options.rawLog,
+        debug: options.debug,
+        configEnv: configEnvironment,
+        preserveGithubSha: options.preserveGithubSha,
+    };
+    const outputMode = resolveOutputMode(options.format, process.stdout.isTTY);
+    const writeEvent = createEventWriter(outputMode);
+    const events = [];
+    try {
+        const eventStream = isStreamableAdapter(adapter)
+            ? adapter.streamSession(runOptions)
+            : streamAgent(adapter, runOptions);
+        for await (const event of eventStream) {
+            events.push(event);
+            writeEvent(event);
+        }
+        const success = adapter.isSuccess(events);
+        return { events, success };
+    }
+    catch (error) {
+        if (error instanceof DependencyError) {
+            process.stderr.write(error.message + "\n");
+            return { events, success: false };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        const errorEvent = {
+            type: "session.error",
+            code: "SPAWN_ERROR",
+            message,
+            timestamp: Date.now(),
+        };
+        events.push(errorEvent);
+        writeEvent(errorEvent);
+        return { events, success: false };
+    }
+    finally {
+        // Safe to await - executeAgent is async so finally block can use await
+        await cleanupCredentials(credentialResult.baseDirectory);
+    }
+}
+export { runAgent };

package/dist/stream-agent.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Core runner for executing agents.
+ *
+ * This module is the imperative shell that handles all I/O:
+ * process spawning, streaming, and event collection.
+ */
+import type { AgentAdapter } from "./types/adapter.js";
+import type { AxexecEvent } from "./types/events.js";
+import type { RunOptions } from "./types/options.js";
+/**
+ * Runs an agent and streams normalized events.
+ *
+ * @param adapter - The agent adapter to use
+ * @param options - Run options including prompt and flags
+ * @yields Normalized events as they arrive from the agent
+ * @throws {AgentNotFoundError} If the agent binary is not found
+ * @throws {AgentSpawnError} If the process fails to start
+ */
+declare function streamAgent(adapter: AgentAdapter, options: RunOptions): AsyncGenerator<AxexecEvent>;
+export { streamAgent };

package/dist/stream-agent.js

@@ -0,0 +1,207 @@
+/**
+ * Core runner for executing agents.
+ *
+ * This module is the imperative shell that handles all I/O:
+ * process spawning, streaming, and event collection.
+ */
+import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import { createInterface } from "node:readline";
+/**
+ * Environment variables to always exclude from agent subprocess.
+ *
+ * Vault credentials are excluded to prevent prompt injection attacks from
+ * exfiltrating secrets. The credentials are resolved before spawning and
+ * passed via agent-specific env vars (e.g., ANTHROPIC_API_KEY).
+ */
+const VAULT_ENV_EXCLUSIONS = ["AXVAULT", "AXVAULT_URL", "AXVAULT_API_KEY"];
+/** Error thrown when agent binary is not found */
+class AgentNotFoundError extends Error {
+    bin;
+    constructor(bin, cause) {
+        super(`Agent binary not found: ${bin}`);
+        this.name = "AgentNotFoundError";
+        this.bin = bin;
+        this.cause = cause;
+    }
+}
+/** Error thrown when agent process fails to start */
+class AgentSpawnError extends Error {
+    bin;
+    constructor(bin, cause) {
+        super(`Failed to spawn agent: ${bin}`);
+        this.name = "AgentSpawnError";
+        this.bin = bin;
+        this.cause = cause;
+    }
+}
+/**
+ * Runs an agent and streams normalized events.
+ *
+ * @param adapter - The agent adapter to use
+ * @param options - Run options including prompt and flags
+ * @yields Normalized events as they arrive from the agent
+ * @throws {AgentNotFoundError} If the agent binary is not found
+ * @throws {AgentSpawnError} If the process fails to start
+ */
+async function* streamAgent(adapter, options) {
+    const { bin, args, env, envExclusions: environmentExclusions, } = adapter.prepareCommand(options);
+    const parseEvent = adapter.createParser(options);
+    // Open raw log file if requested.
+    // Errors are logged to stderr but don't interrupt the main stream.
+    let rawLogStream;
+    if (options.rawLogPath) {
+        rawLogStream = createWriteStream(options.rawLogPath, { flags: "w" });
+        rawLogStream.on("error", (error) => {
+            process.stderr.write(`Warning: raw log error: ${error.message}\n`);
+        });
+    }
+    // Build environment: start with process.env, exclude vault vars and any
+    // adapter-specified vars, then merge adapter env and config env.
+    const allExclusions = new Set([
+        ...VAULT_ENV_EXCLUSIONS,
+        ...(environmentExclusions ?? []),
+    ]);
+    const baseEnvironment = Object.fromEntries(Object.entries(process.env).filter(([key]) => !allExclusions.has(key)));
+    const child = spawn(bin, args, {
+        env: { ...baseEnvironment, ...env, ...options.configEnv },
+        cwd: options.cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    // Consume stderr to prevent pipe buffer deadlock.
+    // Capture output for error diagnostics when process fails.
+    // stderr is guaranteed non-null since stdio is set to "pipe".
+    let stderrBuffer = "";
+    const STDERR_LIMIT = 50 * 1024 * 1024; // 50 MB limit to prevent OOM
+    if (options.verbose) {
+        child.stderr.pipe(process.stderr);
+    }
+    else {
+        child.stderr.on("data", (chunk) => {
+            // Limit buffer size to prevent memory exhaustion from verbose agents
+            if (stderrBuffer.length < STDERR_LIMIT) {
+                stderrBuffer += chunk.toString();
+                if (stderrBuffer.length >= STDERR_LIMIT) {
+                    stderrBuffer =
+                        stderrBuffer.slice(0, STDERR_LIMIT) + "\n... (truncated)";
+                }
+            }
+        });
+    }
+    // Wait for spawn or error
+    await new Promise((resolve, reject) => {
+        child.once("error", (error) => {
+            if (error.code === "ENOENT") {
+                reject(new AgentNotFoundError(bin, error));
+            }
+            else {
+                reject(new AgentSpawnError(bin, error));
+            }
+        });
+        child.once("spawn", () => {
+            resolve();
+        });
+    });
+    // Forward termination signals to the child process.
+    // Registered after spawn succeeds to prevent handler leak on spawn failure.
+    const forwardSignal = (signal) => {
+        child.kill(signal);
+    };
+    process.on("SIGINT", forwardSignal);
+    process.on("SIGTERM", forwardSignal);
+    try {
+        // Stream stdout line-by-line.
+        // stdout is guaranteed non-null since stdio is set to "pipe".
+        const stdout = child.stdout;
+        // Handle stream errors that readline's for-await-of doesn't forward
+        let streamError;
+        stdout.on("error", (error) => {
+            streamError = error;
+        });
+        const rl = createInterface({ input: stdout });
+        for await (const line of rl) {
+            // Write raw line to log file if enabled
+            if (rawLogStream) {
+                rawLogStream.write(line + "\n");
+            }
+            const event = parseEvent(line);
+            if (event) {
+                yield event;
+            }
+            else if (options.debug && line.trim() !== "") {
+                // Log unknown events in debug mode
+                // Try to extract event type for better diagnostics
+                let eventType = "unknown";
+                try {
+                    const parsed = JSON.parse(line);
+                    if (typeof parsed.type === "string") {
+                        eventType = parsed.type;
+                    }
+                }
+                catch {
+                    // Not valid JSON, use raw preview
+                    eventType = `(invalid JSON: ${line.slice(0, 50)}...)`;
+                }
+                process.stderr.write(`[debug] Unhandled event type: ${eventType}\n`);
+            }
+        }
+        // Drain any buffered events from parsers that queue multiple events per line.
+        // Some parsers (e.g., OpenCode) produce multiple events from a single line
+        // but return them one at a time. Calling with empty string drains the queue.
+        let bufferedEvent;
+        while ((bufferedEvent = parseEvent("")) !== undefined) {
+            yield bufferedEvent;
+        }
+        // Check if we had a stream error during iteration
+        if (streamError) {
+            yield {
+                type: "session.error",
+                code: "STREAM_ERROR",
+                message: streamError.message,
+                timestamp: Date.now(),
+            };
+        }
+        // Wait for process to exit
+        const { exitCode, signal } = await new Promise((resolve) => {
+            child.once("close", (code, sig) => {
+                resolve({
+                    exitCode: code ?? undefined,
+                    signal: sig ?? undefined,
+                });
+            });
+        });
+        // If process was terminated by a signal, yield a signal error event
+        if (signal) {
+            yield {
+                type: "session.error",
+                code: "SIGNAL",
+                message: `Agent terminated by ${signal}`,
+                timestamp: Date.now(),
+            };
+        }
+        else if (exitCode !== 0 && exitCode !== undefined) {
+            // If process exited with non-zero, yield an exit-code error event.
+            // Note: This may emit after a stream error - consumers handle both.
+            const stderrTrimmed = stderrBuffer.trim();
+            const message = stderrTrimmed
+                ? `Agent exited with code ${exitCode}: ${stderrTrimmed}`
+                : `Agent exited with code ${exitCode}`;
+            yield {
+                type: "session.error",
+                code: "EXIT_CODE",
+                message,
+                timestamp: Date.now(),
+            };
+        }
+    }
+    finally {
+        // Clean up signal handlers - guaranteed to run even if consumer breaks early
+        process.off("SIGINT", forwardSignal);
+        process.off("SIGTERM", forwardSignal);
+        // Close raw log stream if open
+        if (rawLogStream) {
+            rawLogStream.end();
+        }
+    }
+}
+export { streamAgent };

package/dist/types/adapter.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Adapter interface and related types.
+ *
+ * Each agent implements the {@link AgentAdapter} interface to provide
+ * a consistent way to prepare commands and parse events.
+ *
+ * Adapters may optionally implement {@link StreamableAdapter} to provide
+ * custom streaming behavior (e.g., for server-mode agents).
+ */
+import type { AgentCli, AxexecEvent } from "./events.js";
+import type { RunOptions } from "./options.js";
+/** Metadata about an agent */
+interface AgentInfo {
+    /** Unique identifier for the agent */
+    id: AgentCli;
+    /** Human-readable name */
+    name: string;
+    /** CLI package name (e.g., "@anthropic-ai/claude-code") */
+    package: string;
+    /** Detected version of the installed CLI, if available */
+    version?: string;
+}
+/** Command prepared for execution by spawn() */
+interface PreparedCommand {
+    /** Binary to execute */
+    bin: string;
+    /** Arguments to pass to the binary */
+    args: string[];
+    /** Environment variables to set */
+    env: Record<string, string>;
+    /**
+     * Environment variables to exclude from process.env.
+     *
+     * These keys will be removed from the inherited environment before
+     * the adapter's env values are merged in. Useful for agents that need
+     * to work around CI environment variable conflicts.
+     */
+    envExclusions?: string[];
+}
+/** Function that parses a single JSONL line into a normalized event */
+type EventParser = (line: string) => AxexecEvent | undefined;
+/**
+ * Adapter interface that each agent must implement.
+ *
+ * Adapters are responsible for:
+ * - Providing agent metadata
+ * - Preparing the spawn command with appropriate flags
+ * - Parsing raw JSONL lines into normalized events
+ * - Determining task success from the event stream
+ */
+interface AgentAdapter {
+    /** Returns agent metadata */
+    info(): AgentInfo;
+    /** Prepares the spawn command with environment and arguments */
+    prepareCommand(options: RunOptions): PreparedCommand;
+    /**
+     * Creates a parser for a single session.
+     *
+     * The returned function may maintain state across calls (e.g., to correlate
+     * tool calls with their results). A new parser should be created for each
+     * agent invocation.
+     *
+     * @param options - Run options (optional, for agents that need model info)
+     * @returns A function that parses JSONL lines into normalized events
+     */
+    createParser(options?: RunOptions): EventParser;
+    /**
+     * Determines if the task completed successfully from the event stream.
+     *
+     * Called after the process exits to interpret the final state.
+     */
+    isSuccess(events: AxexecEvent[]): boolean;
+}
+/**
+ * Extended adapter interface for agents that provide custom streaming.
+ *
+ * Agents implementing this interface handle their own execution flow
+ * (e.g., server-mode agents that use HTTP/SSE instead of stdout).
+ *
+ * When an adapter implements `streamSession`, the CLI will use it
+ * instead of the default spawn+parse pattern.
+ */
+interface StreamableAdapter extends AgentAdapter {
+    /**
+     * Streams events from a custom execution flow.
+     *
+     * This method handles the full lifecycle:
+     * - Starting any required processes/servers
+     * - Connecting to event sources
+     * - Yielding normalized events
+     * - Cleanup on completion or error
+     *
+     * @param options - Run options including prompt and flags
+     * @yields Normalized events as they arrive
+     */
+    streamSession(options: RunOptions): AsyncGenerator<AxexecEvent>;
+}
+/** Type guard to check if an adapter implements StreamableAdapter */
+declare function isStreamableAdapter(adapter: AgentAdapter): adapter is StreamableAdapter;
+export type { AgentAdapter, AgentInfo, EventParser, PreparedCommand, StreamableAdapter, };
+export { isStreamableAdapter };

package/dist/types/adapter.js

@@ -0,0 +1,14 @@
+/**
+ * Adapter interface and related types.
+ *
+ * Each agent implements the {@link AgentAdapter} interface to provide
+ * a consistent way to prepare commands and parse events.
+ *
+ * Adapters may optionally implement {@link StreamableAdapter} to provide
+ * custom streaming behavior (e.g., for server-mode agents).
+ */
+/** Type guard to check if an adapter implements StreamableAdapter */
+function isStreamableAdapter(adapter) {
+    return ("streamSession" in adapter && typeof adapter.streamSession === "function");
+}
+export { isStreamableAdapter };

package/dist/types/events.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Normalized event types for axexec.
+ *
+ * All agent adapters transform their raw JSONL events into these
+ * normalized types, providing a consistent interface regardless
+ * of which underlying agent is used.
+ *
+ * Events are grouped by semantic category:
+ * - session.*: Session lifecycle (start, complete, error)
+ * - agent.*: Agent content output (reasoning, message)
+ * - tool.*: Tool execution (call, result)
+ */
+export type { AgentCli } from "axshared";
+type AgentCli = import("axshared").AgentCli;
+/** Statistics collected during session execution */
+interface SessionStats {
+    durationMs: number;
+    costUsd?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+/** Emitted when a session begins */
+interface SessionStartEvent {
+    type: "session.start";
+    /** Unique identifier for this session */
+    sessionId: string;
+    agent: AgentCli;
+    /** Model used for this session (e.g., "claude-sonnet-4-5-20250929", "gpt-4") */
+    model: string;
+    /** Provider of the model, if known (e.g., "anthropic", "openai", "google") */
+    provider?: string;
+    timestamp: number;
+}
+/** Emitted when a session completes successfully */
+interface SessionCompleteEvent {
+    type: "session.complete";
+    stats: SessionStats;
+    timestamp: number;
+}
+/** Emitted when a session ends with an error */
+interface SessionErrorEvent {
+    type: "session.error";
+    code: string;
+    message: string;
+    timestamp: number;
+}
+/** Emitted when the agent produces internal reasoning (chain-of-thought) */
+interface AgentReasoningEvent {
+    type: "agent.reasoning";
+    content: string;
+    timestamp: number;
+}
+/** Emitted when the agent produces a message/response to the user */
+interface AgentMessageEvent {
+    type: "agent.message";
+    content: string;
+    timestamp: number;
+}
+/** Emitted when the agent invokes a tool */
+interface ToolCallEvent {
+    type: "tool.call";
+    /** Unique identifier for this tool invocation, used to correlate with result */
+    callId: string;
+    /** Human-readable tool name */
+    tool: string;
+    input: unknown;
+    timestamp: number;
+}
+/** Emitted when a tool returns its result */
+interface ToolResultEvent {
+    type: "tool.result";
+    /** Matches the callId from the corresponding tool.call event */
+    callId: string;
+    /** Human-readable tool name (resolved via correlation with tool.call) */
+    tool: string;
+    output: unknown;
+    success: boolean;
+    timestamp: number;
+}
+/** Discriminated union of all normalized event types */
+type AxexecEvent = SessionStartEvent | SessionCompleteEvent | SessionErrorEvent | AgentReasoningEvent | AgentMessageEvent | ToolCallEvent | ToolResultEvent;
+export type { AxexecEvent };

package/dist/types/events.js

@@ -0,0 +1,13 @@
+/**
+ * Normalized event types for axexec.
+ *
+ * All agent adapters transform their raw JSONL events into these
+ * normalized types, providing a consistent interface regardless
+ * of which underlying agent is used.
+ *
+ * Events are grouped by semantic category:
+ * - session.*: Session lifecycle (start, complete, error)
+ * - agent.*: Agent content output (reasoning, message)
+ * - tool.*: Tool execution (call, result)
+ */
+export {};

package/dist/types/options.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Options types for running agents.
+ */
+/** Options for running an agent */
+interface RunOptions {
+    /** The prompt to send to the agent */
+    prompt: string;
+    /** Show verbose/debug output from the agent */
+    verbose: boolean;
+    /** Working directory for the agent process */
+    cwd?: string;
+    /** Path to write raw agent JSONL output for debugging/fixtures */
+    rawLogPath?: string;
+    /** Enable debug mode (logs unknown events, additional diagnostics) */
+    debug?: boolean;
+    /**
+     * Additional environment variables for agent configuration.
+     * Generated by ConfigBuilder to point to temp config files.
+     */
+    configEnv?: Record<string, string>;
+    /**
+     * Model to use. Format varies by agent:
+     * - Claude Code: aliases ('sonnet', 'opus', 'haiku') or full model names
+     * - Codex: model names ('o4-mini', 'gpt-5.1-codex')
+     * - Gemini: aliases ('pro', 'flash') or full names ('gemini-2.5-pro')
+     * - Copilot: model names ('gpt-5', 'claude-sonnet-4.5')
+     * - OpenCode: provider/model format ('anthropic/claude-sonnet-4')
+     */
+    model?: string;
+    /**
+     * Preserve GITHUB_SHA environment variable.
+     *
+     * When false (default), Gemini excludes GITHUB_SHA to work around a CLI bug
+     * where strict environment sanitization blocks GH_TOKEN from reaching shell
+     * commands when GITHUB_SHA is set.
+     *
+     * Set to true to preserve GITHUB_SHA in the child process environment.
+     */
+    preserveGithubSha?: boolean;
+}
+export type { RunOptions };

package/dist/types/options.js

@@ -0,0 +1,4 @@
+/**
+ * Options types for running agents.
+ */
+export {};

package/dist/validate-agent.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Agent validation utilities.
+ */
+import { type AgentCli } from "axshared";
+import type { AgentAdapter } from "./types/adapter.js";
+/** Result of validating an agent */
+type ValidateAgentResult = {
+    ok: true;
+    agentId: AgentCli;
+    adapter: AgentAdapter;
+} | {
+    ok: false;
+    exitCode: number;
+    message: string;
+};
+/**
+ * Validate that an agent ID is valid and the adapter is available.
+ */
+declare function validateAgent(agentId: string | undefined): ValidateAgentResult;
+export { validateAgent };