axexec 1.0.0

package/dist/credentials/write-agent-credentials.js

@@ -0,0 +1,91 @@
+/**
+ * Per-agent credential file writers.
+ *
+ * Each agent has its own credential file format. These functions
+ * write credentials in the agent-specific format.
+ */
+import path from "node:path";
+import { saveJsonFile } from "./save-json-file.js";
+/**
+ * Installs Claude credentials to a config directory.
+ *
+ * File: .credentials.json
+ * Format: { claudeAiOauth: { ... } }
+ */
+function installClaudeCredentials(configDirectory, credentials) {
+    if (!credentials.oauth && !credentials.apiKey) {
+        return;
+    }
+    const credentialsPath = path.join(configDirectory, ".credentials.json");
+    if (credentials.oauth) {
+        saveJsonFile(credentialsPath, { claudeAiOauth: credentials.oauth });
+    }
+    // API key is passed via environment variable, not file
+}
+/**
+ * Installs Codex credentials to a config directory.
+ *
+ * File: auth.json
+ * Format: { OPENAI_API_KEY: "..." } or { tokens: { ... }, last_refresh: "..." }
+ */
+function installCodexCredentials(configDirectory, credentials) {
+    if (!credentials.oauth && !credentials.apiKey) {
+        return;
+    }
+    const authPath = path.join(configDirectory, "auth.json");
+    if (credentials.apiKey) {
+        saveJsonFile(authPath, { OPENAI_API_KEY: credentials.apiKey });
+    }
+    else if (credentials.oauth) {
+        saveJsonFile(authPath, {
+            tokens: credentials.oauth,
+            last_refresh: new Date().toISOString(),
+        });
+    }
+}
+/**
+ * Installs Gemini credentials to a config directory.
+ *
+ * File: oauth_creds.json
+ * Format: { access_token: "...", refresh_token: "...", ... }
+ */
+function installGeminiCredentials(configDirectory, credentials) {
+    if (!credentials.oauth && !credentials.apiKey) {
+        return;
+    }
+    if (credentials.oauth) {
+        const credentialsPath = path.join(configDirectory, "oauth_creds.json");
+        saveJsonFile(credentialsPath, credentials.oauth);
+    }
+    // API key is passed via environment variable, not file
+}
+/**
+ * Installs OpenCode credentials to a data directory.
+ *
+ * File: auth.json
+ * Format: { anthropic: { type: "oauth", ... }, openai: { type: "api", ... } }
+ */
+function installOpenCodeCredentials(dataDirectory, credentials) {
+    if (!credentials.oauth && !credentials.apiKey) {
+        return;
+    }
+    const authPath = path.join(dataDirectory, "auth.json");
+    const authData = {};
+    if (credentials.oauth) {
+        authData.anthropic = {
+            type: "oauth",
+            ...credentials.oauth,
+        };
+    }
+    if (credentials.apiKey) {
+        authData.anthropic = {
+            type: "api",
+            key: credentials.apiKey,
+        };
+    }
+    if (Object.keys(authData).length > 0) {
+        saveJsonFile(authPath, authData);
+    }
+}
+// Note: Copilot uses environment variables (GITHUB_TOKEN), not file-based credentials.
+export { installClaudeCredentials, installCodexCredentials, installGeminiCredentials, installOpenCodeCredentials, };

package/dist/determine-session-success.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Determines session success from an event stream.
+ *
+ * Shared implementation used by all adapters to check if a session
+ * completed successfully based on the normalized event stream.
+ */
+import type { AxexecEvent } from "./types/events.js";
+/**
+ * Determines if the session completed successfully based on the event stream.
+ *
+ * Scans backwards for terminal events: returns true if session.complete
+ * is found before any session.error event.
+ */
+declare function determineSessionSuccess(events: AxexecEvent[]): boolean;
+export { determineSessionSuccess };

package/dist/determine-session-success.js

@@ -0,0 +1,25 @@
+/**
+ * Determines session success from an event stream.
+ *
+ * Shared implementation used by all adapters to check if a session
+ * completed successfully based on the normalized event stream.
+ */
+/**
+ * Determines if the session completed successfully based on the event stream.
+ *
+ * Scans backwards for terminal events: returns true if session.complete
+ * is found before any session.error event.
+ */
+function determineSessionSuccess(events) {
+    for (let index = events.length - 1; index >= 0; index--) {
+        const event = events[index];
+        if (event?.type === "session.complete") {
+            return true;
+        }
+        if (event?.type === "session.error") {
+            return false;
+        }
+    }
+    return false;
+}
+export { determineSessionSuccess };

package/dist/format-event-tsv.d.ts

@@ -0,0 +1,23 @@
+/**
+ * TSV (Tab-Separated Values) formatter for axexec events.
+ *
+ * Formats events as human-readable TSV lines with proper escaping
+ * for newlines and tabs. Supports optional truncation for interactive
+ * display.
+ */
+import type { AxexecEvent } from "./types/events.js";
+interface FormatOptions {
+    /** Whether to truncate long content (default: false) */
+    truncate?: boolean;
+    /** Maximum length before truncation (default: 80) */
+    maxLength?: number;
+}
+/**
+ * Formats an AxexecEvent as a TSV line.
+ *
+ * @param event - The event to format
+ * @param options - Formatting options
+ * @returns A single TSV line (without trailing newline)
+ */
+declare function formatEventTsv(event: AxexecEvent, options?: FormatOptions): string;
+export { formatEventTsv };

package/dist/format-event-tsv.js

@@ -0,0 +1,136 @@
+/**
+ * TSV (Tab-Separated Values) formatter for axexec events.
+ *
+ * Formats events as human-readable TSV lines with proper escaping
+ * for newlines and tabs. Supports optional truncation for interactive
+ * display.
+ */
+/** Default maximum length for content before truncation */
+const DEFAULT_MAX_LENGTH = 80;
+/**
+ * Escapes special characters in a string for TSV output.
+ * - Newlines → \n (literal backslash-n)
+ * - Tabs → \t (literal backslash-t)
+ * - Backslashes → \\ (escaped)
+ */
+function escapeTsv(value) {
+    return value
+        .replaceAll("\\", String.raw `\\`)
+        .replaceAll("\n", String.raw `\n`)
+        .replaceAll("\t", String.raw `\t`);
+}
+/**
+ * Truncates a string with a [+N] marker indicating remaining characters.
+ * Returns the original string if within maxLength.
+ */
+function truncateWithMarker(value, maxLength) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    const remaining = value.length - maxLength;
+    const marker = `[+${remaining}]`;
+    // Ensure we have room for the marker
+    const truncateAt = maxLength - marker.length;
+    if (truncateAt <= 0) {
+        return marker;
+    }
+    return value.slice(0, truncateAt) + marker;
+}
+/**
+ * Formats a timestamp (milliseconds since epoch) as HH:MM:SS local time.
+ */
+function formatTime(timestamp) {
+    const date = new Date(timestamp);
+    return date.toLocaleTimeString("en-US", {
+        hour12: false,
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    });
+}
+/**
+ * Formats a duration in milliseconds as a human-readable string.
+ */
+function formatDuration(ms) {
+    if (ms < 1000) {
+        return `${ms}ms`;
+    }
+    const seconds = ms / 1000;
+    if (seconds < 60) {
+        return `${seconds.toFixed(1)}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return `${minutes}m${remainingSeconds.toFixed(0)}s`;
+}
+/**
+ * Summarizes an unknown value for TSV display.
+ * Objects are JSON-stringified, primitives are converted to strings.
+ */
+function summarizeValue(value) {
+    if (value === null || value === undefined) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return JSON.stringify(value);
+}
+/**
+ * Formats an AxexecEvent as a TSV line.
+ *
+ * @param event - The event to format
+ * @param options - Formatting options
+ * @returns A single TSV line (without trailing newline)
+ */
+function formatEventTsv(event, options = {}) {
+    const { truncate = false, maxLength = DEFAULT_MAX_LENGTH } = options;
+    const time = formatTime(event.timestamp);
+    const processContent = (content) => {
+        const escaped = escapeTsv(content);
+        return truncate ? truncateWithMarker(escaped, maxLength) : escaped;
+    };
+    switch (event.type) {
+        case "session.start": {
+            return `${time}\t${event.type}\tagent=${event.agent}\tmodel=${event.model}`;
+        }
+        case "session.complete": {
+            const parts = [
+                time,
+                event.type,
+                `duration=${formatDuration(event.stats.durationMs)}`,
+            ];
+            if (event.stats.inputTokens !== undefined ||
+                event.stats.outputTokens !== undefined) {
+                const input = event.stats.inputTokens ?? 0;
+                const output = event.stats.outputTokens ?? 0;
+                parts.push(`tokens=${input}+${output}`);
+            }
+            if (event.stats.costUsd !== undefined) {
+                parts.push(`cost=$${event.stats.costUsd.toFixed(4)}`);
+            }
+            return parts.join("\t");
+        }
+        case "session.error": {
+            const message = processContent(event.message);
+            return `${time}\t${event.type}\tcode=${event.code}\t${message}`;
+        }
+        case "agent.reasoning":
+        case "agent.message": {
+            return `${time}\t${event.type}\t${processContent(event.content)}`;
+        }
+        case "tool.call": {
+            const inputSummary = processContent(summarizeValue(event.input));
+            return `${time}\t${event.type}\ttool=${event.tool}\t${inputSummary}`;
+        }
+        case "tool.result": {
+            const outputSummary = processContent(summarizeValue(event.output));
+            const status = event.success ? "success" : "failed";
+            return `${time}\t${event.type}\ttool=${event.tool}\t${status}\t${outputSummary}`;
+        }
+    }
+}
+export { formatEventTsv };

package/dist/parse-credentials.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Credential parsing from environment variables.
+ */
+import type { RawCredentials } from "./credentials/install-credentials.js";
+/**
+ * Parses credentials from environment variables.
+ *
+ * Environment variables checked (in order):
+ * - AX_<AGENT>_CREDENTIALS: JSON with credentials
+ * - Standard env vars: ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.
+ */
+declare function parseCredentialsFromEnvironment(agentId: string): RawCredentials;
+export { parseCredentialsFromEnvironment };

package/dist/parse-credentials.js

@@ -0,0 +1,63 @@
+/**
+ * Credential parsing from environment variables.
+ */
+/**
+ * Parses credentials from environment variables.
+ *
+ * Environment variables checked (in order):
+ * - AX_<AGENT>_CREDENTIALS: JSON with credentials
+ * - Standard env vars: ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.
+ */
+function parseCredentialsFromEnvironment(agentId) {
+    const credentials = {};
+    // Check for axexec credentials env var
+    const credEnvironmentVariable = `AX_${agentId.toUpperCase()}_CREDENTIALS`;
+    const credEnvironmentValue = process.env[credEnvironmentVariable];
+    if (credEnvironmentValue) {
+        try {
+            const parsed = JSON.parse(credEnvironmentValue);
+            return parsed;
+        }
+        catch {
+            process.stderr.write(`Warning: Failed to parse ${credEnvironmentVariable}\n`);
+        }
+    }
+    // Fall back to standard env vars
+    switch (agentId) {
+        case "claude": {
+            if (process.env["ANTHROPIC_API_KEY"]) {
+                credentials.apiKey = process.env["ANTHROPIC_API_KEY"];
+            }
+            break;
+        }
+        case "codex": {
+            if (process.env["OPENAI_API_KEY"]) {
+                credentials.apiKey = process.env["OPENAI_API_KEY"];
+            }
+            break;
+        }
+        case "gemini": {
+            if (process.env["GEMINI_API_KEY"]) {
+                credentials.apiKey = process.env["GEMINI_API_KEY"];
+            }
+            break;
+        }
+        case "opencode": {
+            if (process.env["ANTHROPIC_API_KEY"]) {
+                credentials.apiKey = process.env["ANTHROPIC_API_KEY"];
+            }
+            break;
+        }
+        case "copilot": {
+            const token = process.env["GITHUB_TOKEN"] ??
+                process.env["GH_TOKEN"] ??
+                process.env["COPILOT_GITHUB_TOKEN"];
+            if (token) {
+                credentials.githubToken = token;
+            }
+            break;
+        }
+    }
+    return credentials;
+}
+export { parseCredentialsFromEnvironment };

package/dist/parse-iso-timestamp.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ISO timestamp parsing utility.
+ *
+ * Converts ISO 8601 timestamp strings to epoch milliseconds,
+ * with stateful fallback to preserve event ordering.
+ */
+/**
+ * Creates a stateful timestamp parser that tracks the last valid timestamp.
+ *
+ * When a timestamp is missing or invalid, falls back to the previous event's
+ * timestamp to preserve ordering. Only uses `Date.now()` if no previous
+ * timestamp exists (i.e., the very first event has no timestamp).
+ *
+ * @example
+ * const parseTimestamp = createTimestampParser();
+ * parseTimestamp("2025-01-15T14:30:45.123Z") // Returns 1736951445123
+ * parseTimestamp(undefined) // Returns 1736951445123 (previous value)
+ * parseTimestamp("2025-01-15T14:30:46.000Z") // Returns 1736951446000
+ */
+declare function createTimestampParser(): (isoString: string | undefined) => number;
+export { createTimestampParser };

package/dist/parse-iso-timestamp.js

@@ -0,0 +1,37 @@
+/**
+ * ISO timestamp parsing utility.
+ *
+ * Converts ISO 8601 timestamp strings to epoch milliseconds,
+ * with stateful fallback to preserve event ordering.
+ */
+/**
+ * Creates a stateful timestamp parser that tracks the last valid timestamp.
+ *
+ * When a timestamp is missing or invalid, falls back to the previous event's
+ * timestamp to preserve ordering. Only uses `Date.now()` if no previous
+ * timestamp exists (i.e., the very first event has no timestamp).
+ *
+ * @example
+ * const parseTimestamp = createTimestampParser();
+ * parseTimestamp("2025-01-15T14:30:45.123Z") // Returns 1736951445123
+ * parseTimestamp(undefined) // Returns 1736951445123 (previous value)
+ * parseTimestamp("2025-01-15T14:30:46.000Z") // Returns 1736951446000
+ */
+function createTimestampParser() {
+    let lastTimestamp;
+    return (isoString) => {
+        if (isoString) {
+            const parsed = Date.parse(isoString);
+            if (!Number.isNaN(parsed)) {
+                lastTimestamp = parsed;
+                return parsed;
+            }
+        }
+        // Fall back to previous timestamp, or Date.now() for very first event
+        if (lastTimestamp === undefined) {
+            lastTimestamp = Date.now();
+        }
+        return lastTimestamp;
+    };
+}
+export { createTimestampParser };

package/dist/resolve-binary.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Resolve and validate external CLI binaries used by axexec.
+ */
+interface ResolveBinaryOptions {
+    /** Friendly dependency name for error messages */
+    name: string;
+    /** Default command name on PATH */
+    command: string;
+    /** Environment variable override for the binary path */
+    environmentVariable: string;
+    /** Install hint shown in error messages */
+    installHint: string;
+}
+declare class DependencyError extends Error {
+    name: string;
+    readonly dependency: string;
+    readonly environmentVariable: string;
+    readonly command: string;
+    constructor(message: string, dependency: string, environmentVariable: string, command: string);
+}
+/**
+ * Resolves a binary path and verifies it can be spawned.
+ *
+ * Checks only that the binary exists and can be spawned - does not validate
+ * exit code since we're checking availability, not correctness. Uses a short
+ * timeout to prevent hangs in CI environments.
+ */
+declare function resolveBinary(options: ResolveBinaryOptions): string;
+export { DependencyError, resolveBinary };

package/dist/resolve-binary.js

@@ -0,0 +1,46 @@
+/**
+ * Resolve and validate external CLI binaries used by axexec.
+ */
+import { spawnSync } from "node:child_process";
+class DependencyError extends Error {
+    name = "DependencyError";
+    dependency;
+    environmentVariable;
+    command;
+    constructor(message, dependency, environmentVariable, command) {
+        super(message);
+        this.dependency = dependency;
+        this.environmentVariable = environmentVariable;
+        this.command = command;
+    }
+}
+/**
+ * Resolves a binary path and verifies it can be spawned.
+ *
+ * Checks only that the binary exists and can be spawned - does not validate
+ * exit code since we're checking availability, not correctness. Uses a short
+ * timeout to prevent hangs in CI environments.
+ */
+function resolveBinary(options) {
+    const override = process.env[options.environmentVariable];
+    const candidate = override && override.trim() !== "" ? override : options.command;
+    const result = spawnSync(candidate, ["--version"], {
+        stdio: "ignore",
+        timeout: 5000,
+    });
+    if (result.error) {
+        const lines = [
+            `Error: Required dependency '${options.name}' not found.`,
+            `Looked for: ${candidate}`,
+            `Reason: ${result.error.message}`,
+            "",
+            "To fix:",
+            `  1. Install it: ${options.installHint}`,
+            `  2. Set ${options.environmentVariable}=/path/to/${options.command}`,
+            "See: axexec --help for requirements.",
+        ];
+        throw new DependencyError(lines.join("\n"), options.name, options.environmentVariable, options.command);
+    }
+    return candidate;
+}
+export { DependencyError, resolveBinary };

package/dist/resolve-output-mode.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Resolves the output mode based on CLI flags and TTY status.
+ *
+ * The output mode determines how events are formatted:
+ * - jsonl: JSON Lines format (one JSON object per line)
+ * - tsv: Tab-separated values (no truncation)
+ * - tsv-truncated: Tab-separated values with truncation for readability
+ */
+/** User-specified output format from CLI flag */
+type OutputFormat = "jsonl" | "tsv";
+/**
+ * Resolved output mode including auto-detected variants.
+ * - jsonl: Full JSON Lines output
+ * - tsv: Full TSV output (no truncation)
+ * - tsv-truncated: TSV with truncation for interactive display
+ */
+type OutputMode = "jsonl" | "tsv" | "tsv-truncated";
+/**
+ * Resolves the output mode based on format flag and TTY status.
+ *
+ * Pure function for testability - isTTY is passed as argument.
+ *
+ * @param format - User-specified format from --format flag, or undefined for auto-detect
+ * @param isTTY - Whether stdout is a TTY (interactive terminal)
+ * @returns The resolved output mode
+ *
+ * @example
+ * // Explicit format overrides TTY detection
+ * resolveOutputMode("jsonl", true)  // → "jsonl"
+ * resolveOutputMode("tsv", false)   // → "tsv"
+ *
+ * @example
+ * // Auto-detect based on TTY
+ * resolveOutputMode(undefined, true)   // → "tsv-truncated"
+ * resolveOutputMode(undefined, false)  // → "tsv"
+ */
+declare function resolveOutputMode(format: OutputFormat | undefined, isTTY: boolean): OutputMode;
+export { resolveOutputMode };
+export type { OutputFormat, OutputMode };

package/dist/resolve-output-mode.js

@@ -0,0 +1,39 @@
+/**
+ * Resolves the output mode based on CLI flags and TTY status.
+ *
+ * The output mode determines how events are formatted:
+ * - jsonl: JSON Lines format (one JSON object per line)
+ * - tsv: Tab-separated values (no truncation)
+ * - tsv-truncated: Tab-separated values with truncation for readability
+ */
+/**
+ * Resolves the output mode based on format flag and TTY status.
+ *
+ * Pure function for testability - isTTY is passed as argument.
+ *
+ * @param format - User-specified format from --format flag, or undefined for auto-detect
+ * @param isTTY - Whether stdout is a TTY (interactive terminal)
+ * @returns The resolved output mode
+ *
+ * @example
+ * // Explicit format overrides TTY detection
+ * resolveOutputMode("jsonl", true)  // → "jsonl"
+ * resolveOutputMode("tsv", false)   // → "tsv"
+ *
+ * @example
+ * // Auto-detect based on TTY
+ * resolveOutputMode(undefined, true)   // → "tsv-truncated"
+ * resolveOutputMode(undefined, false)  // → "tsv"
+ */
+function resolveOutputMode(format, isTTY) {
+    // Explicit format from flag takes precedence
+    if (format === "jsonl") {
+        return "jsonl";
+    }
+    if (format === "tsv") {
+        return "tsv";
+    }
+    // Auto-detect based on TTY
+    return isTTY ? "tsv-truncated" : "tsv";
+}
+export { resolveOutputMode };

package/dist/run-agent.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Agent execution with credential isolation and config generation.
+ */
+import type { AxexecEvent } from "./types/events.js";
+import { type OutputFormat } from "./resolve-output-mode.js";
+interface RunAgentOptions {
+    prompt: string;
+    model?: string;
+    allow?: string;
+    deny?: string;
+    format?: OutputFormat;
+    rawLog?: string;
+    debug?: boolean;
+    verbose?: boolean;
+    preserveGithubSha?: boolean;
+}
+interface RunResult {
+    events: AxexecEvent[];
+    success: boolean;
+}
+/**
+ * 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
+ */
+declare function runAgent(agentId: string, options: RunAgentOptions): Promise<RunResult>;
+export { runAgent };