axexec 1.0.0

package/dist/agents/opencode/sse-client.js

@@ -0,0 +1,145 @@
+/**
+ * SSE client for OpenCode server mode.
+ *
+ * Connects to the OpenCode server's /event endpoint and streams
+ * parsed SSE events.
+ */
+import { OpenCodeSSEEvent as OpenCodeSSEEventSchema } from "./server-types.js";
+/** Error when SSE connection fails */
+class SSEConnectionError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.name = "SSEConnectionError";
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * Connects to OpenCode server's SSE endpoint and yields events.
+ *
+ * The generator will yield events until:
+ * - The connection is closed by the server
+ * - The abort signal is triggered
+ * - An error occurs
+ */
+async function* streamSSE(options) {
+    const url = `${options.baseUrl}/event`;
+    const response = await fetch(url, {
+        headers: {
+            Accept: "text/event-stream",
+            "Cache-Control": "no-cache",
+            "x-opencode-directory": options.directory,
+        },
+        signal: options.signal,
+    });
+    if (!response.ok) {
+        throw new SSEConnectionError(`SSE connection failed: ${response.status} ${response.statusText}`, response.status);
+    }
+    if (!response.body) {
+        throw new SSEConnectionError("SSE response has no body");
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    // Expose reader for manual cancellation
+    options.onReader?.(reader);
+    // Create a single abort promise that rejects when abort signal fires
+    // This is more efficient than creating a new promise on each iteration
+    const abortPromise = new Promise((_, reject) => {
+        if (options.signal?.aborted) {
+            reject(new Error("Aborted"));
+            return;
+        }
+        options.signal?.addEventListener("abort", () => {
+            reject(new Error("Aborted"));
+        }, { once: true });
+    });
+    try {
+        for (;;) {
+            // Check abort signal before reading
+            if (options.signal?.aborted) {
+                break;
+            }
+            // Race the read against the abort signal
+            let result;
+            try {
+                result = await Promise.race([reader.read(), abortPromise]);
+            }
+            catch {
+                // Aborted
+                break;
+            }
+            if (result.done) {
+                break;
+            }
+            buffer += decoder.decode(result.value, { stream: true });
+            // Normalize CRLF to LF (SSE spec allows both line ending styles)
+            buffer = buffer.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
+            // Process complete SSE messages (separated by double newline)
+            const messages = buffer.split("\n\n");
+            buffer = messages.pop() ?? ""; // Keep incomplete message in buffer
+            for (const message of messages) {
+                // Check abort signal before yielding
+                if (options.signal?.aborted) {
+                    return;
+                }
+                const event = parseSSEMessage(message);
+                if (event) {
+                    yield event;
+                }
+            }
+        }
+        // Process any remaining buffer (only if not aborted)
+        if (!options.signal?.aborted && buffer.trim()) {
+            const event = parseSSEMessage(buffer);
+            if (event) {
+                yield event;
+            }
+        }
+    }
+    finally {
+        // Cancel any pending read
+        reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+/**
+ * Parses a single SSE message into an OpenCode event.
+ *
+ * SSE format:
+ * ```
+ * data: {"type": "...", "properties": {...}}
+ * ```
+ */
+function parseSSEMessage(message) {
+    const lines = message.split("\n");
+    const dataLines = [];
+    for (const line of lines) {
+        if (line.startsWith("data: ")) {
+            dataLines.push(line.slice(6));
+        }
+        else if (line.startsWith("data:")) {
+            dataLines.push(line.slice(5));
+        }
+        // Ignore other SSE fields (event:, id:, retry:)
+    }
+    // Per SSE spec, multiple data lines are joined with newlines
+    const data = dataLines.join("\n");
+    if (!data) {
+        return undefined;
+    }
+    try {
+        const json = JSON.parse(data);
+        const result = OpenCodeSSEEventSchema.safeParse(json);
+        if (result.success) {
+            return result.data;
+        }
+        // Unknown event type - log for debugging but don't fail
+        return undefined;
+    }
+    catch {
+        // Invalid JSON - skip
+        return undefined;
+    }
+}
+export { SSEConnectionError, streamSSE };

package/dist/agents/registry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Adapter registry for agent lookup and registration.
+ *
+ * Adapters self-register on import, allowing new agents to be added
+ * without modifying core code.
+ */
+import type { AgentAdapter, AgentInfo } from "../types/adapter.js";
+import type { AgentCli } from "../types/events.js";
+/** Registers an adapter in the registry */
+declare function registerAdapter(adapter: AgentAdapter): void;
+/** Retrieves an adapter by ID, or undefined if not found */
+declare function getAdapter(id: AgentCli): AgentAdapter | undefined;
+/** Returns metadata for all registered adapters */
+declare function listAdapters(): AgentInfo[];
+export { getAdapter, listAdapters, registerAdapter };

package/dist/agents/registry.js

@@ -0,0 +1,24 @@
+/**
+ * Adapter registry for agent lookup and registration.
+ *
+ * Adapters self-register on import, allowing new agents to be added
+ * without modifying core code.
+ */
+const adapters = new Map();
+/** Registers an adapter in the registry */
+function registerAdapter(adapter) {
+    const { id } = adapter.info();
+    if (adapters.has(id)) {
+        throw new Error(`Adapter already registered: ${id}`);
+    }
+    adapters.set(id, adapter);
+}
+/** Retrieves an adapter by ID, or undefined if not found */
+function getAdapter(id) {
+    return adapters.get(id);
+}
+/** Returns metadata for all registered adapters */
+function listAdapters() {
+    return [...adapters.values()].map((adapter) => adapter.info());
+}
+export { getAdapter, listAdapters, registerAdapter };

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * axexec CLI - Unified agent execution with isolation.
+ *
+ * Executes AI coding agents with complete environment isolation:
+ * - Credentials written to temp directory
+ * - Config/permissions written to temp directory
+ * - Agent pointed at temp directory via env vars
+ * - Normalized event stream output
+ */
+import "./agents/claude-code/adapter.js";
+import "./agents/codex/adapter.js";
+import "./agents/gemini/adapter.js";
+import "./agents/opencode/adapter.js";
+import "./agents/copilot/adapter.js";

package/dist/cli.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * axexec CLI - Unified agent execution with isolation.
+ *
+ * Executes AI coding agents with complete environment isolation:
+ * - Credentials written to temp directory
+ * - Config/permissions written to temp directory
+ * - Agent pointed at temp directory via env vars
+ * - Normalized event stream output
+ */
+import { Command } from "@commander-js/extra-typings";
+import packageJson from "../package.json" with { type: "json" };
+// Import all adapters to trigger self-registration
+import "./agents/claude-code/adapter.js";
+import "./agents/codex/adapter.js";
+import "./agents/gemini/adapter.js";
+import "./agents/opencode/adapter.js";
+import "./agents/copilot/adapter.js";
+import { listAdapters } from "./agents/registry.js";
+import { runAgent } from "./run-agent.js";
+async function readStdin() {
+    let data = "";
+    for await (const chunk of process.stdin) {
+        data += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    }
+    return data.trimEnd();
+}
+const program = new Command()
+    .name(packageJson.name)
+    .description(packageJson.description)
+    .version(packageJson.version, "-V, --version")
+    .showHelpAfterError("(add --help for additional information)")
+    .showSuggestionAfterError()
+    .option("--list-agents", "List available agents")
+    .option("-a, --agent <id>", "Agent to use (required)")
+    .option("-p, --prompt <text>", "Prompt text")
+    .option("-m, --model <model>", "Model to use")
+    .option("--allow <perms>", "Permission rules to allow (comma-separated)")
+    .option("--deny <perms>", "Permission rules to deny (comma-separated)")
+    .option("-f, --format <fmt>", "Output format: jsonl, tsv (default: tsv, truncated on TTY)")
+    .option("--raw-log <file>", "Write raw agent output to file")
+    .option("--debug", "Enable debug mode")
+    .option("--verbose", "Show agent stderr output")
+    .option("--preserve-github-sha", "Preserve GITHUB_SHA env var (Gemini)")
+    .argument("[prompt]", "Prompt text (alternative to -p)")
+    .addHelpText("after", `
+Requirements:
+  Install the agent CLIs you plan to use: claude, codex, gemini, opencode, copilot.
+  Override paths: AXEXEC_CLAUDE_PATH, AXEXEC_CODEX_PATH, AXEXEC_GEMINI_PATH, AXEXEC_OPENCODE_PATH, AXEXEC_COPILOT_PATH
+
+Examples:
+  axexec -a claude "Refactor auth flow"
+  axexec -a claude -f jsonl "Audit deps" | jq 'select(.type=="tool.call")'
+  axexec --list-agents | tail -n +2 | cut -f1
+`)
+    .action(async (positionalPrompt, options) => {
+    // Handle --list-agents
+    if (options.listAgents) {
+        const agents = listAdapters();
+        process.stdout.write("ID\tNAME\tPACKAGE\n");
+        for (const agent of agents) {
+            process.stdout.write(`${agent.id}\t${agent.name}\t${agent.package}\n`);
+        }
+        return;
+    }
+    // Get prompt from flag, positional argument, or stdin (in priority order)
+    // Only read stdin if no prompt was provided via CLI arguments to avoid
+    // blocking in CI environments with open but unused stdin.
+    const needsStdinPrompt = !options.prompt && !positionalPrompt;
+    const stdinPrompt = needsStdinPrompt && !process.stdin.isTTY ? await readStdin() : undefined;
+    const prompt = (options.prompt ??
+        positionalPrompt ??
+        stdinPrompt)?.trimEnd();
+    if (!prompt) {
+        process.stderr.write("Error: prompt is required\n");
+        process.stderr.write("Usage: axexec --agent <id> <prompt>\n");
+        process.stderr.write("Try 'axexec --help' for more information.\n");
+        process.exitCode = 2;
+        return;
+    }
+    if (!options.agent) {
+        process.stderr.write("Error: --agent is required\n");
+        process.stderr.write("Usage: axexec --agent <id> <prompt>\n");
+        process.stderr.write("Try 'axexec --help' for more information.\n");
+        process.exitCode = 2;
+        return;
+    }
+    // Validate format option
+    let format;
+    if (options.format) {
+        if (options.format === "jsonl" || options.format === "tsv") {
+            format = options.format;
+        }
+        else {
+            process.stderr.write(`Error: Invalid format '${options.format}'\n`);
+            process.stderr.write("Valid formats: jsonl, tsv\n");
+            process.exitCode = 2;
+            return;
+        }
+    }
+    // Run agent
+    const result = await runAgent(options.agent, {
+        prompt,
+        model: options.model,
+        allow: options.allow,
+        deny: options.deny,
+        format,
+        rawLog: options.rawLog,
+        debug: options.debug,
+        verbose: options.verbose,
+        preserveGithubSha: options.preserveGithubSha,
+    });
+    // Set exit code based on success
+    if (!result.success) {
+        process.exitCode = 1;
+    }
+});
+// Parse CLI arguments
+await program.parseAsync();

package/dist/credentials/get-credential-environment.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Environment variable helpers for credential-based auth.
+ */
+import type { AgentCli } from "axshared";
+import type { RawCredentials } from "./types.js";
+/**
+ * Gets additional environment variables for credential-based auth.
+ *
+ * Some agents use environment variables for API keys in addition to
+ * or instead of file-based credentials.
+ */
+declare function getCredentialEnvironment(agentId: AgentCli, credentials: RawCredentials): Record<string, string>;
+export { getCredentialEnvironment };

package/dist/credentials/get-credential-environment.js

@@ -0,0 +1,46 @@
+/**
+ * Environment variable helpers for credential-based auth.
+ */
+/**
+ * Gets additional environment variables for credential-based auth.
+ *
+ * Some agents use environment variables for API keys in addition to
+ * or instead of file-based credentials.
+ */
+function getCredentialEnvironment(agentId, credentials) {
+    const environment = {};
+    switch (agentId) {
+        case "claude": {
+            if (credentials.apiKey) {
+                environment["ANTHROPIC_API_KEY"] = credentials.apiKey;
+            }
+            break;
+        }
+        case "codex": {
+            if (credentials.apiKey) {
+                environment["OPENAI_API_KEY"] = credentials.apiKey;
+            }
+            break;
+        }
+        case "gemini": {
+            if (credentials.apiKey) {
+                environment["GEMINI_API_KEY"] = credentials.apiKey;
+            }
+            break;
+        }
+        case "opencode": {
+            if (credentials.apiKey) {
+                environment["ANTHROPIC_API_KEY"] = credentials.apiKey;
+            }
+            break;
+        }
+        case "copilot": {
+            if (credentials.githubToken) {
+                environment["GITHUB_TOKEN"] = credentials.githubToken;
+            }
+            break;
+        }
+    }
+    return environment;
+}
+export { getCredentialEnvironment };

package/dist/credentials/install-credentials.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Credential installation for isolated agent execution.
+ *
+ * Writes raw credentials to a temporary directory in agent-specific formats,
+ * then returns the environment variables needed to point the agent at that
+ * directory. This ensures complete isolation - agents never discover or use
+ * locally installed credentials.
+ */
+import { type AgentCli } from "axshared";
+import type { InstallResult, RawCredentials } from "./types.js";
+export type { RawCredentials } from "./types.js";
+/**
+ * Installs credentials to a temporary directory and returns isolation env vars.
+ *
+ * This function:
+ * 1. Creates a temp directory structure appropriate for the agent
+ * 2. Writes credential files in the agent-specific format
+ * 3. Returns environment variables that point the agent at the temp directory
+ *
+ * The caller is responsible for cleaning up the temp directory after use.
+ */
+declare function installCredentials(agentId: AgentCli, credentials: RawCredentials): Promise<InstallResult>;
+/**
+ * Cleanup for use in finally blocks.
+ */
+declare function cleanupCredentials(baseDirectory: string): Promise<void>;
+export { cleanupCredentials, installCredentials };

package/dist/credentials/install-credentials.js

@@ -0,0 +1,102 @@
+/**
+ * Credential installation for isolated agent execution.
+ *
+ * Writes raw credentials to a temporary directory in agent-specific formats,
+ * then returns the environment variables needed to point the agent at that
+ * directory. This ensures complete isolation - agents never discover or use
+ * locally installed credentials.
+ */
+import { mkdirSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { buildAgentRuntimeEnvironment, getAgentConfigSubdirectory, } from "axshared";
+import { getCredentialEnvironment } from "./get-credential-environment.js";
+import { installClaudeCredentials, installCodexCredentials, installGeminiCredentials, installOpenCodeCredentials, } from "./write-agent-credentials.js";
+/**
+ * Creates a temporary directory structure for an agent.
+ */
+async function createTemporaryDirectories(agentId) {
+    const baseDirectory = await mkdtemp(path.join(tmpdir(), `axexec-${agentId}-`));
+    const subdirectory = getAgentConfigSubdirectory(agentId);
+    let configDirectory;
+    let dataDirectory;
+    if (subdirectory) {
+        configDirectory = path.join(baseDirectory, subdirectory);
+        dataDirectory = configDirectory;
+        mkdirSync(configDirectory, { recursive: true, mode: 0o700 });
+    }
+    else {
+        configDirectory = baseDirectory;
+        dataDirectory = baseDirectory;
+    }
+    // OpenCode needs separate data directory
+    if (agentId === "opencode") {
+        dataDirectory = path.join(baseDirectory, "opencode");
+        if (dataDirectory !== configDirectory) {
+            mkdirSync(dataDirectory, { recursive: true, mode: 0o700 });
+        }
+    }
+    return { baseDirectory, configDirectory, dataDirectory };
+}
+/**
+ * Installs agent-specific credentials to the appropriate directory.
+ */
+function installAgentCredentials(agentId, configDirectory, dataDirectory, credentials) {
+    switch (agentId) {
+        case "claude": {
+            installClaudeCredentials(configDirectory, credentials);
+            break;
+        }
+        case "codex": {
+            installCodexCredentials(configDirectory, credentials);
+            break;
+        }
+        case "gemini": {
+            installGeminiCredentials(configDirectory, credentials);
+            break;
+        }
+        case "opencode": {
+            installOpenCodeCredentials(dataDirectory, credentials);
+            break;
+        }
+        case "copilot": {
+            // Copilot uses GITHUB_TOKEN env var, not file-based credentials
+            break;
+        }
+    }
+}
+/**
+ * Installs credentials to a temporary directory and returns isolation env vars.
+ *
+ * This function:
+ * 1. Creates a temp directory structure appropriate for the agent
+ * 2. Writes credential files in the agent-specific format
+ * 3. Returns environment variables that point the agent at the temp directory
+ *
+ * The caller is responsible for cleaning up the temp directory after use.
+ */
+async function installCredentials(agentId, credentials) {
+    const { baseDirectory, configDirectory, dataDirectory } = await createTemporaryDirectories(agentId);
+    installAgentCredentials(agentId, configDirectory, dataDirectory, credentials);
+    const runtimeEnvironment = buildAgentRuntimeEnvironment(agentId, configDirectory, dataDirectory);
+    const credentialEnvironment = getCredentialEnvironment(agentId, credentials);
+    return {
+        env: { ...runtimeEnvironment, ...credentialEnvironment },
+        configDirectory,
+        dataDirectory,
+        baseDirectory,
+    };
+}
+/**
+ * Cleanup for use in finally blocks.
+ */
+async function cleanupCredentials(baseDirectory) {
+    try {
+        await rm(baseDirectory, { recursive: true, force: true });
+    }
+    catch {
+        // Ignore cleanup errors - best effort
+    }
+}
+export { cleanupCredentials, installCredentials };

package/dist/credentials/save-json-file.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Atomic JSON file writing utility.
+ */
+/**
+ * Saves JSON data to a file atomically.
+ *
+ * Creates parent directories if needed, writes to a temp file first,
+ * then atomically renames to the target path.
+ */
+declare function saveJsonFile(filePath: string, data: unknown, mode?: number): void;
+export { saveJsonFile };

package/dist/credentials/save-json-file.js

@@ -0,0 +1,21 @@
+/**
+ * Atomic JSON file writing utility.
+ */
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+/**
+ * Saves JSON data to a file atomically.
+ *
+ * Creates parent directories if needed, writes to a temp file first,
+ * then atomically renames to the target path.
+ */
+function saveJsonFile(filePath, data, mode = 0o600) {
+    const directory = path.dirname(filePath);
+    if (!existsSync(directory)) {
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+    }
+    const temporaryFile = `${filePath}.tmp.${Date.now()}`;
+    writeFileSync(temporaryFile, JSON.stringify(data, undefined, 2), { mode });
+    renameSync(temporaryFile, filePath);
+}
+export { saveJsonFile };

package/dist/credentials/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Credential types for axexec.
+ */
+/** Raw credentials that can be installed for any agent */
+interface RawCredentials {
+    /** OAuth credentials (access token, refresh token, etc.) */
+    oauth?: Record<string, unknown>;
+    /** API key for direct API access */
+    apiKey?: string;
+    /** GitHub token for Copilot */
+    githubToken?: string;
+}
+/** Result of credential installation */
+interface InstallResult {
+    /** Environment variables to pass to the agent subprocess */
+    env: Record<string, string>;
+    /** Configuration directory path (for cleanup) */
+    configDirectory: string;
+    /** Data directory path (for cleanup, may equal configDirectory) */
+    dataDirectory: string;
+    /** Base temporary directory (for cleanup) */
+    baseDirectory: string;
+}
+export type { InstallResult, RawCredentials };

package/dist/credentials/types.js

@@ -0,0 +1,4 @@
+/**
+ * Credential types for axexec.
+ */
+export {};

package/dist/credentials/write-agent-credentials.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Per-agent credential file writers.
+ *
+ * Each agent has its own credential file format. These functions
+ * write credentials in the agent-specific format.
+ */
+import type { RawCredentials } from "./types.js";
+/**
+ * Installs Claude credentials to a config directory.
+ *
+ * File: .credentials.json
+ * Format: { claudeAiOauth: { ... } }
+ */
+declare function installClaudeCredentials(configDirectory: string, credentials: RawCredentials): void;
+/**
+ * Installs Codex credentials to a config directory.
+ *
+ * File: auth.json
+ * Format: { OPENAI_API_KEY: "..." } or { tokens: { ... }, last_refresh: "..." }
+ */
+declare function installCodexCredentials(configDirectory: string, credentials: RawCredentials): void;
+/**
+ * Installs Gemini credentials to a config directory.
+ *
+ * File: oauth_creds.json
+ * Format: { access_token: "...", refresh_token: "...", ... }
+ */
+declare function installGeminiCredentials(configDirectory: string, credentials: RawCredentials): void;
+/**
+ * Installs OpenCode credentials to a data directory.
+ *
+ * File: auth.json
+ * Format: { anthropic: { type: "oauth", ... }, openai: { type: "api", ... } }
+ */
+declare function installOpenCodeCredentials(dataDirectory: string, credentials: RawCredentials): void;
+export { installClaudeCredentials, installCodexCredentials, installGeminiCredentials, installOpenCodeCredentials, };