axexec 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Łukasz Jerciński
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,196 @@
+# axexec
+
+Execution engine for AI coding agents. Translates abstract inputs to agent-specific formats, runs agents in complete isolation, and normalizes output to a standard event stream.
+
+## What axexec Does
+
+axexec is the **translation layer** between high-level tooling and agent-specific details:
+
+- **Input translation**: Credentials → agent-specific files, permissions → config files, model → CLI flags
+- **Output normalization**: Claude JSONL, Codex items, Gemini events, OpenCode SSE → unified `AxexecEvent` stream
+- **Complete isolation**: Agents run in temp directories with no access to user config or global credentials
+
+## Installation
+
+```bash
+npm install -g axexec
+```
+
+## Requirements
+
+Install the agent CLIs you plan to use:
+
+- Claude Code: `npm install -g @anthropic-ai/claude-code` (bin: `claude`)
+- Codex: `npm install -g @openai/codex` (bin: `codex`)
+- Gemini: `npm install -g @google/gemini-cli` (bin: `gemini`)
+- OpenCode: `npm install -g opencode-ai` (bin: `opencode`)
+- Copilot CLI: `npm install -g @github/copilot` (bin: `copilot`)
+
+### Custom Paths
+
+If a binary is not on your PATH, set an override:
+
+```bash
+export AXEXEC_CLAUDE_PATH=/opt/claude/bin/claude
+export AXEXEC_CODEX_PATH=/opt/codex/bin/codex
+export AXEXEC_GEMINI_PATH=/opt/gemini/bin/gemini
+export AXEXEC_OPENCODE_PATH=/opt/opencode/bin/opencode
+export AXEXEC_COPILOT_PATH=/opt/copilot/bin/copilot
+```
+
+## Usage
+
+```bash
+# Run a prompt with an agent
+axexec --agent claude "Add error handling to auth.ts"
+axexec -a codex "Fix the bug in main.ts"
+axexec -a gemini "Refactor the utils module"
+axexec -a opencode "Add logging"
+axexec -a copilot "Write tests"
+
+# Specify a model
+axexec -a claude --model opus "Review this PR"
+axexec -a gemini --model gemini-2.5-pro "Refactor utils"
+
+# Set permissions
+axexec -a claude --allow 'read,glob,bash:git *' "Check git history"
+
+# Output normalized JSONL event stream
+axexec -a claude -f jsonl "Add tests" | jq 'select(.type == "tool.call")'
+
+# List available agents
+axexec --list-agents
+```
+
+## Pipeline Examples
+
+### Count event types
+
+```bash
+axexec -a claude "Summarize the change" | cut -f2 | sort | uniq -c | sort -rn
+```
+
+### Filter tool calls
+
+```bash
+axexec -a claude -f jsonl "Audit dependencies" | jq 'select(.type == "tool.call")'
+```
+
+### Filter available agents by package
+
+```bash
+axexec --list-agents | tail -n +2 | awk -F'\t' '$3 ~ /openai/ {print $1}'
+```
+
+## Options
+
+```
+-a, --agent <id>           Agent to use (claude, codex, gemini, opencode, copilot)
+-p, --prompt <text>        Prompt text (alternative to positional argument)
+-m, --model <model>        Model to use (agent-specific)
+--allow <perms>            Permission rules to allow (comma-separated)
+--deny <perms>             Permission rules to deny (comma-separated)
+-f, --format <fmt>         Output format: jsonl, tsv (default: tsv, truncated on TTY)
+--raw-log <file>           Write raw agent output to file
+--debug                    Enable debug mode (logs unknown events)
+--verbose                  Show agent stderr output
+--preserve-github-sha      Keep GITHUB_SHA env var (Gemini excludes by default)
+--list-agents              List available agents
+-V, --version              Show version number
+--help                     Show help
+```
+
+## Supported Agents
+
+| Agent    | Package                   | API Key Env Var       |
+| -------- | ------------------------- | --------------------- |
+| claude   | @anthropic-ai/claude-code | ANTHROPIC_API_KEY     |
+| codex    | @openai/codex             | OPENAI_API_KEY        |
+| gemini   | @google/gemini-cli        | GEMINI_API_KEY        |
+| opencode | opencode-ai               | ANTHROPIC_API_KEY (†) |
+| copilot  | @github/copilot           | GITHUB_TOKEN          |
+
+(†) OpenCode supports multiple providers via `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GEMINI_API_KEY`.
+
+## Event Stream
+
+axexec normalizes all agent output to a standard event stream:
+
+| Event Type         | Description                          |
+| ------------------ | ------------------------------------ |
+| `session.start`    | Agent session started                |
+| `session.complete` | Agent session completed successfully |
+| `session.error`    | Agent session failed                 |
+| `agent.message`    | Text output from the agent           |
+| `agent.reasoning`  | Reasoning/thinking from the agent    |
+| `tool.call`        | Agent invoked a tool                 |
+| `tool.result`      | Tool execution result                |
+
+## CI/CD Usage
+
+### Using Credential Environment Variables
+
+For CI/CD pipelines, credentials can be passed via environment variables:
+
+```bash
+# Export credentials locally (one-time setup)
+axauth export --agent claude --output creds.json --no-password
+
+# Store as repository secret (e.g., AX_CLAUDE_CREDENTIALS)
+
+# axexec auto-detects and installs credentials to temp directory
+axexec --agent claude --prompt "Review this PR"
+```
+
+| Agent    | Credential Env Var      |
+| -------- | ----------------------- |
+| claude   | AX_CLAUDE_CREDENTIALS   |
+| codex    | AX_CODEX_CREDENTIALS    |
+| gemini   | AX_GEMINI_CREDENTIALS   |
+| opencode | AX_OPENCODE_CREDENTIALS |
+| copilot  | AX_COPILOT_CREDENTIALS  |
+
+### Using Standard API Keys
+
+You can also use standard environment variables directly:
+
+```bash
+ANTHROPIC_API_KEY=sk-... axexec -a claude "Review code"
+OPENAI_API_KEY=sk-... axexec -a codex "Fix bug"
+GEMINI_API_KEY=... axexec -a gemini "Refactor"
+GITHUB_TOKEN=ghp_... axexec -a copilot "Write tests"
+```
+
+For Claude, `CLAUDE_CODE_OAUTH_TOKEN` (generated via `claude setup-token`) also works.
+
+## Isolation
+
+axexec provides complete environment isolation:
+
+1. Creates a temp directory for each session
+2. Installs credentials to the temp directory
+3. Generates agent-specific config files in the temp directory
+4. Sets environment variables to point agents at the temp directory
+5. Cleans up the temp directory after execution
+
+Agents **never** access:
+
+- User's home directory config (`~/.claude`, `~/.codex`, `~/.gemini`)
+- System keychain or credential managers
+- Global configuration files
+
+## Agent Rule
+
+Add to your `CLAUDE.md` or `AGENTS.md`:
+
+```markdown
+# Rule: `axexec` Usage
+
+Run `npx -y axexec --help` to learn available options.
+
+Use `axexec` when you need to run a supported agent in a fully isolated environment and consume a normalized event stream. It translates credentials and permissions to agent-specific formats so your automation stays consistent across providers.
+```
+
+## License
+
+MIT

package/bin/axexec

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point that dynamically imports the compiled TypeScript.
+ *
+ * Uses top-level await to ensure module evaluation errors are handled
+ * properly. Without await, errors during import would surface as unhandled
+ * rejections instead of clean CLI failures with appropriate exit codes.
+ */
+try {
+  await import("../dist/cli.js");
+} catch (error) {
+  console.error(
+    "Failed to start axexec:",
+    error instanceof Error ? error.message : error,
+  );
+  process.exitCode = 1;
+}

package/dist/agents/claude-code/adapter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Claude Code adapter implementation.
+ *
+ * Implements the {@link AgentAdapter} interface for Claude Code CLI.
+ */
+export {};

package/dist/agents/claude-code/adapter.js

@@ -0,0 +1,71 @@
+/**
+ * Claude Code adapter implementation.
+ *
+ * Implements the {@link AgentAdapter} interface for Claude Code CLI.
+ */
+import { determineSessionSuccess } from "../../determine-session-success.js";
+import { resolveBinary } from "../../resolve-binary.js";
+import { registerAdapter } from "../registry.js";
+import { createClaudeParser } from "./parse-event.js";
+const CLAUDE_CODE_INFO = {
+    id: "claude",
+    name: "Claude Code",
+    package: "@anthropic-ai/claude-code",
+};
+/**
+ * Prepares the command to spawn Claude Code.
+ *
+ * @see https://docs.anthropic.com/en/docs/claude-code
+ */
+function prepareCommand(options) {
+    const cliArguments = [
+        "-p",
+        options.prompt,
+        "--output-format",
+        "stream-json",
+        // Claude Code's --verbose is required for stream-json to emit all event
+        // types. This is different from axexec's --verbose flag which controls
+        // whether stderr is shown to the user.
+        "--verbose",
+        // Always skip permissions since stdin is ignored (non-interactive mode).
+        // Users who need interactive approval should use claude directly.
+        "--dangerously-skip-permissions",
+    ];
+    // Add model flag if specified
+    // Claude Code accepts aliases (sonnet, opus, haiku) or full model names
+    if (options.model) {
+        cliArguments.push("--model", options.model);
+    }
+    const environment = {};
+    // Pass through authentication environment variables.
+    // If neither is set, Claude CLI will prompt interactively or fail with its
+    // own error message - we intentionally let the agent handle auth errors
+    // rather than duplicating that validation here.
+    if (process.env["ANTHROPIC_API_KEY"]) {
+        environment["ANTHROPIC_API_KEY"] = process.env["ANTHROPIC_API_KEY"];
+    }
+    if (process.env["CLAUDE_CODE_OAUTH_TOKEN"]) {
+        environment["CLAUDE_CODE_OAUTH_TOKEN"] =
+            process.env["CLAUDE_CODE_OAUTH_TOKEN"];
+    }
+    const bin = resolveBinary({
+        name: "claude",
+        command: "claude",
+        environmentVariable: "AXEXEC_CLAUDE_PATH",
+        installHint: "npm install -g @anthropic-ai/claude-code",
+    });
+    return {
+        bin,
+        args: cliArguments,
+        env: environment,
+    };
+}
+/** Claude Code adapter */
+const claudeCodeAdapter = {
+    info: () => CLAUDE_CODE_INFO,
+    prepareCommand,
+    createParser: createClaudeParser,
+    isSuccess: determineSessionSuccess,
+};
+// Self-register on import
+registerAdapter(claudeCodeAdapter);

package/dist/agents/claude-code/parse-event.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Event parser for Claude Code.
+ *
+ * Transforms raw Claude Code JSONL events into normalized {@link AxexecEvent} types.
+ */
+import type { EventParser } from "../../types/adapter.js";
+/**
+ * Creates a parser for Claude Code events.
+ *
+ * Maintains a mapping from callId to tool name to resolve tool names
+ * in tool.result events (which only contain the callId).
+ * Uses a stateful timestamp parser to preserve event ordering when
+ * timestamps are missing.
+ */
+declare function createClaudeParser(): EventParser;
+export { createClaudeParser };

package/dist/agents/claude-code/parse-event.js

@@ -0,0 +1,185 @@
+/**
+ * Event parser for Claude Code.
+ *
+ * Transforms raw Claude Code JSONL events into normalized {@link AxexecEvent} types.
+ */
+import { createTimestampParser } from "../../parse-iso-timestamp.js";
+import { ClaudeEvent, isAssistantEvent, isResultEvent, isSystemEvent, isUserEvent, } from "./types.js";
+/**
+ * Creates a parser for Claude Code events.
+ *
+ * Maintains a mapping from callId to tool name to resolve tool names
+ * in tool.result events (which only contain the callId).
+ * Uses a stateful timestamp parser to preserve event ordering when
+ * timestamps are missing.
+ */
+function createClaudeParser() {
+    const parseTimestamp = createTimestampParser();
+    // Map from callId to tool name for correlation
+    const toolNames = new Map();
+    return (line) => {
+        const trimmed = line.trim();
+        if (trimmed === "") {
+            return undefined;
+        }
+        let json;
+        try {
+            json = JSON.parse(trimmed);
+        }
+        catch {
+            // Not valid JSON - skip
+            return undefined;
+        }
+        // Validate against schema - skip malformed events
+        const result = ClaudeEvent.safeParse(json);
+        if (!result.success) {
+            return undefined;
+        }
+        const raw = result.data;
+        // Dispatch based on event type
+        if (isSystemEvent(raw)) {
+            return parseSystemEvent(raw, parseTimestamp);
+        }
+        if (isAssistantEvent(raw)) {
+            return parseAssistantEvent(raw, toolNames, parseTimestamp);
+        }
+        if (isUserEvent(raw)) {
+            return parseUserEvent(raw, toolNames, parseTimestamp);
+        }
+        if (isResultEvent(raw)) {
+            return parseResultEvent(raw, parseTimestamp);
+        }
+        // Unknown event type - skip
+        return undefined;
+    };
+}
+/** Parses a system event (task start) */
+function parseSystemEvent(event, parseTimestamp) {
+    if (event.subtype !== "init") {
+        return undefined;
+    }
+    return {
+        type: "session.start",
+        sessionId: event.session_id ?? "unknown",
+        agent: "claude",
+        model: event.model ?? "unknown",
+        provider: "anthropic",
+        timestamp: parseTimestamp(event.timestamp),
+    };
+}
+/** Parses an assistant event (progress, tool calls) */
+function parseAssistantEvent(event, toolNames, parseTimestamp) {
+    const timestamp = parseTimestamp(event.timestamp);
+    // Handle tool use from content blocks
+    if (event.content_block?.type === "tool_use") {
+        const callId = event.content_block.id ?? "unknown";
+        const tool = event.content_block.name ?? "unknown";
+        // Store for later correlation with tool.result
+        toolNames.set(callId, tool);
+        return {
+            type: "tool.call",
+            callId,
+            tool,
+            input: event.content_block.input,
+            timestamp,
+        };
+    }
+    // Handle text content as agent message
+    if (event.content_block?.type === "text" && event.content_block.text) {
+        return {
+            type: "agent.message",
+            content: event.content_block.text,
+            timestamp,
+        };
+    }
+    // Handle message-level content.
+    // Claude Code emits separate events per content block, so we only need to
+    // process the first matching block. Multiple blocks in a single message
+    // event would indicate a change in Claude Code's event format.
+    if (event.message?.content) {
+        for (const block of event.message.content) {
+            if (block.type === "tool_use") {
+                const callId = block.id ?? "unknown";
+                const tool = block.name ?? "unknown";
+                // Store for later correlation with tool.result
+                toolNames.set(callId, tool);
+                return {
+                    type: "tool.call",
+                    callId,
+                    tool,
+                    input: block.input,
+                    timestamp,
+                };
+            }
+            if (block.type === "text" && block.text) {
+                return {
+                    type: "agent.message",
+                    content: block.text,
+                    timestamp,
+                };
+            }
+        }
+    }
+    // Skip other assistant events (thinking, etc.)
+    return undefined;
+}
+/** Parses a user event (tool results) */
+function parseUserEvent(event, toolNames, parseTimestamp) {
+    // Look for tool_result content blocks in message.content
+    if (!event.message?.content) {
+        return undefined;
+    }
+    const timestamp = parseTimestamp(event.timestamp);
+    for (const block of event.message.content) {
+        if (block.type === "tool_result" && block.tool_use_id) {
+            // Determine success from tool_use_result metadata if present
+            const isError = event.tool_use_result?.type === "error" ||
+                event.tool_use_result?.status === "error";
+            // Look up tool name from previous tool.call event
+            const tool = toolNames.get(block.tool_use_id) ?? "unknown";
+            // Clean up to prevent memory leaks
+            toolNames.delete(block.tool_use_id);
+            return {
+                type: "tool.result",
+                callId: block.tool_use_id,
+                tool,
+                output: block.content,
+                success: !isError,
+                timestamp,
+            };
+        }
+    }
+    return undefined;
+}
+/** Parses a result event (task completion) */
+function parseResultEvent(event, parseTimestamp) {
+    const timestamp = parseTimestamp(event.timestamp);
+    if (event.subtype === "success") {
+        return {
+            type: "session.complete",
+            stats: {
+                durationMs: event.duration_ms ?? 0,
+                costUsd: event.total_cost_usd,
+                inputTokens: event.usage?.input_tokens,
+                outputTokens: event.usage?.output_tokens,
+            },
+            timestamp,
+        };
+    }
+    if (event.subtype === "error") {
+        return {
+            type: "session.error",
+            code: "AGENT_ERROR",
+            message: event.error ?? event.message ?? "Unknown error",
+            timestamp,
+        };
+    }
+    // Cancelled or other - treat as error
+    return {
+        type: "session.error",
+        code: "CANCELLED",
+        message: event.message ?? "Session was cancelled",
+        timestamp,
+    };
+}
+export { createClaudeParser };