axexec 1.6.1 → 2.0.1

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+Execution engine for AI coding agents. Translates abstract inputs to agent-specific formats, runs agents with credential/config isolation (not an OS sandbox), and normalizes output to a standard event stream.
 
 ## What axexec Does
 
@@ -8,7 +8,9 @@ axexec is the **translation layer** between high-level tooling and agent-specifi
 
 - **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
+- **Credential/config isolation**: Agents are pointed at temp directories instead of your local agent config/credential locations
+
+axexec is **not** a security boundary. It does not restrict filesystem or network access; many adapters run in permissive non-interactive modes to avoid prompts. For real enforcement, run inside an external sandbox (container/VM).
 
 ## Installation
 
@@ -16,6 +18,12 @@ axexec is the **translation layer** between high-level tooling and agent-specifi
 npm install -g axexec
 ```
 
+## Prerequisites
+
+- Node.js 22.14+
+- npx (included with Node.js) for one-off runs; pnpm (optional) for local development workflows
+- jq for JSONL pipeline examples
+
 ## Requirements
 
 Install the agent CLIs you plan to use:
@@ -43,37 +51,53 @@ export AXEXEC_COPILOT_PATH=/opt/copilot/bin/copilot
 ```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"
+axexec --agent codex "Fix the bug in main.ts"
+axexec --agent gemini "Refactor the utils module"
+axexec --agent opencode "Add logging"
+axexec --agent copilot "Write tests"
+
+# Run with explicit credentials JSON (from axauth export)
+axexec --agent claude --credentials-file ./creds.json "Review this PR"
 
 # Specify a model
-axexec -a claude --model opus "Review this PR"
-axexec -a gemini --model gemini-2.5-pro "Refactor utils"
+axexec --agent claude --model opus "Review this PR"
+axexec --agent gemini --model gemini-2.5-pro "Refactor utils"
 
 # Set permissions
-axexec -a claude --allow 'read,glob,bash:git *' "Check git history"
+axexec --agent claude --allow 'read,glob,bash:git *' "Check git history"  # best-effort
 
 # Output normalized JSONL event stream
-axexec -a claude -f jsonl "Add tests" | jq 'select(.type == "tool.call")'
+axexec --agent claude --format jsonl "Add tests" | jq 'select(.type == "tool.call")'
 
 # List available agents
 axexec --list-agents
 ```
 
+Examples use long flags for clarity; short flags like `-a`, `-m`, and `-f` are still supported.
+
+## Output Formats
+
+axexec supports `--format jsonl|tsv`:
+
+- `jsonl`: one JSON object per line (machine-friendly)
+- `tsv`: tab-separated values (human-friendly)
+- Default is TSV; when stdout is a TTY and `--format` is omitted, output is truncated for readability
+- Use `--format tsv` to force full TSV (not applicable to `--list-agents`, which always outputs TSV)
+- Always set `--format` explicitly in pipelines
+- TSV output starts with `time` and `event type` as the first two columns for all events
+
 ## Pipeline Examples
 
 ### Count event types
 
 ```bash
-axexec -a claude "Summarize the change" | cut -f2 | sort | uniq -c | sort -rn
+axexec --agent claude --format tsv "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")'
+axexec --agent claude --format jsonl "Audit dependencies" | jq 'select(.type == "tool.call")'
 ```
 
 ### Filter available agents by package
@@ -86,12 +110,14 @@ axexec --list-agents | tail -n +2 | awk -F'\t' '$3 ~ /openai/ {print $1}'
 
 ```
 -a, --agent <id>           Agent to use (claude, codex, gemini, opencode, copilot)
+--cwd <path>               Working directory for the agent process
+--credentials-file <path|-> Read credentials JSON from file (or '-' for stdin)
 -p, --prompt <text>        Prompt text (alternative to positional argument)
 -m, --model <model>        Model to use (agent-specific)
---provider <provider>      Provider for OpenCode (anthropic, openai, google)
---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)
+--provider <provider>      Provider for OpenCode (e.g., anthropic, openai, google, opencode)
+--allow <perms>            Allow permissions (best-effort, comma-separated)
+--deny <perms>             Deny permissions (best-effort, comma-separated)
+-f, --format <fmt>         Output format: jsonl, tsv (default: tsv; if stdout is TTY and --format is omitted, output is truncated)
 --raw-log <file>           Write raw agent output to file
 --debug                    Enable debug mode (logs unknown events)
 --verbose                  Show agent stderr output
@@ -103,15 +129,14 @@ axexec --list-agents | tail -n +2 | awk -F'\t' '$3 ~ /openai/ {print $1}'
 
 ## 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          |
+`axexec` supports: `claude`, `codex`, `gemini`, `opencode`, `copilot`.
+
+Canonical references:
 
-(†) OpenCode supports multiple providers via `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GEMINI_API_KEY`.
+- Agent/package metadata: `axshared` (`axshared/README.md`)
+- Credential environment variable mapping: `axauth/README.md`
+
+OpenCode requires `AX_OPENCODE_CREDENTIALS` with provider-specific credentials (see [CI/CD Usage](#cicd-usage)).
 
 ## Event Stream
 
@@ -131,7 +156,8 @@ axexec normalizes all agent output to a standard event stream:
 
 ### Using Credential Environment Variables
 
-For CI/CD pipelines, credentials can be passed via environment variables:
+For CI/CD pipelines, credentials can be passed via `AX_*_CREDENTIALS` environment variables.
+Canonical variable names are documented in `axauth/README.md`.
 
 ```bash
 # Export credentials locally (one-time setup)
@@ -143,23 +169,15 @@ axauth export --agent claude --output creds.json --no-password
 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"
+ANTHROPIC_API_KEY=sk-... axexec --agent claude "Review code"
+OPENAI_API_KEY=sk-... axexec --agent codex "Fix bug"
+GEMINI_API_KEY=... axexec --agent gemini "Refactor"
+GITHUB_TOKEN=ghp_... axexec --agent copilot "Write tests"
 ```
 
 For Claude, `CLAUDE_CODE_OAUTH_TOKEN` (generated via `claude setup-token`) also works.
@@ -170,22 +188,22 @@ For OpenCode, set `AX_OPENCODE_CREDENTIALS` with your credentials. The `provider
 field must match your `--provider` flag:
 
 ```bash
-# Anthropic (provider defaults to "anthropic" if omitted)
-AX_OPENCODE_CREDENTIALS='{"agent":"opencode","type":"api-key","data":{"apiKey":"sk-ant-..."}}' \
-  axexec -a opencode --provider anthropic -m claude-sonnet-4 "Hello"
+# Anthropic
+AX_OPENCODE_CREDENTIALS='{"agent":"opencode","type":"api-key","provider":"anthropic","data":{"apiKey":"sk-ant-..."}}' \
+  axexec --agent opencode --provider anthropic --model claude-sonnet-4 "Hello"
 
 # OpenAI (provider must be specified in credentials)
 AX_OPENCODE_CREDENTIALS='{"agent":"opencode","type":"api-key","provider":"openai","data":{"apiKey":"sk-..."}}' \
-  axexec -a opencode --provider openai -m gpt-4.1 "Hello"
+  axexec --agent opencode --provider openai --model gpt-4.1 "Hello"
 
 # OpenCode hosted models (provider must be "opencode")
 AX_OPENCODE_CREDENTIALS='{"agent":"opencode","type":"api-key","provider":"opencode","data":{"apiKey":"..."}}' \
-  axexec -a opencode --provider opencode -m glm-4.7-free "Hello"
+  axexec --agent opencode --provider opencode --model glm-4.7-free "Hello"
 ```
 
 ## Isolation
 
-axexec provides complete environment isolation:
+axexec provides credential/config isolation:
 
 1. Creates a temp directory for each session
 2. Installs credentials to the temp directory
@@ -193,11 +211,14 @@ axexec provides complete environment isolation:
 4. Sets environment variables to point agents at the temp directory
 5. Cleans up the temp directory after execution
 
-Codex runs with `--dangerously-bypass-approvals-and-sandbox`, so `--allow` /
-`--deny` do not constrain Codex. Run axexec inside an external sandbox if you
-need enforcement.
+axexec is intentionally **permissive** and should not be treated as a sandbox:
+
+- It does not enforce filesystem or network restrictions
+- `--allow` / `--deny` is best-effort and may be ignored or weakened by adapter "YOLO" switches
+- Agent-internal sandbox env vars (`GEMINI_SANDBOX`, `SEATBELT_PROFILE`) are excluded from subprocess environments
+- For enforcement, run axexec inside an external sandbox (container/VM)
 
-Agents **never** access:
+Agents are configured to avoid using your local agent config/credential locations:
 
 - User's home directory config (`~/.claude`, `~/.codex`, `~/.gemini`)
 - System keychain or credential managers
@@ -212,7 +233,7 @@ Add to your `CLAUDE.md` or `AGENTS.md`:
 
 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.
+Use `axexec` when you need to run a supported agent with credential/config isolation and consume a normalized event stream. It translates credentials and permissions to agent-specific formats so your automation stays consistent across providers.
 ```
 
 ## License

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

@@ -77,8 +77,8 @@ type ClaudeUserEvent = z.infer<typeof ClaudeUserEvent>;
 declare const ClaudeResultEvent: z.ZodObject<{
     type: z.ZodLiteral<"result">;
     subtype: z.ZodEnum<{
-        success: "success";
         error: "error";
+        success: "success";
         cancelled: "cancelled";
     }>;
     timestamp: z.ZodOptional<z.ZodString>;
@@ -153,8 +153,8 @@ declare const ClaudeEvent: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"result">;
     subtype: z.ZodEnum<{
-        success: "success";
         error: "error";
+        success: "success";
         cancelled: "cancelled";
     }>;
     timestamp: z.ZodOptional<z.ZodString>;

package/dist/agents/copilot/stream-session.js

@@ -23,13 +23,9 @@ async function main() {
     const copilotArguments = [
         "-p",
         prompt,
-        "--allow-all-tools",
-        // Enable network access without confirmation prompts.
-        // Copilot requires user approval for URL access by default, but other
-        // agents (Gemini, OpenCode) allow it by default. For unified behavior,
-        // enable it. This matches how --allow-all-tools works for other operations.
-        // See: copilot-cli-decompiled/copilot-source/index.js line 418918
-        "--allow-all-urls",
+        // Always run in "YOLO" mode (no prompts). This is equivalent to
+        // --allow-all-tools --allow-all-paths --allow-all-urls.
+        "--yolo",
         ...extraArguments,
     ];
     // Record existing session files
@@ -55,6 +51,11 @@ async function main() {
         const copilotBin = process.env["AXEXEC_COPILOT_PATH"] ?? "copilot";
         const child = spawn(copilotBin, copilotArguments, {
             stdio: ["ignore", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                // Auto-trust folders (avoids interactive trust prompts).
+                COPILOT_ALLOW_ALL: "true",
+            },
         });
         copilotProcess = child;
         // Pipe Copilot's stdout/stderr to our stderr (for debugging)

package/dist/agents/copilot/watch-session.js

@@ -13,7 +13,9 @@ import { existsSync, readdirSync, statSync, watch, } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 /** Copilot session state directory */
-const SESSION_STATE_DIR = path.join(homedir(), ".copilot", "session-state");
+const SESSION_STATE_DIR = process.env["XDG_STATE_HOME"]
+    ? path.join(process.env["XDG_STATE_HOME"], ".copilot", "session-state")
+    : path.join(homedir(), ".copilot", "session-state");
 /** Session events filename inside session directories (new format) */
 const SESSION_EVENTS_FILE = "events.jsonl";
 /**

package/dist/agents/gemini/types.d.ts

@@ -41,8 +41,8 @@ declare const GeminiToolResultEvent: z.ZodObject<{
     type: z.ZodLiteral<"tool_result">;
     tool_id: z.ZodString;
     status: z.ZodEnum<{
-        success: "success";
         error: "error";
+        success: "success";
     }>;
     output: z.ZodOptional<z.ZodString>;
     error: z.ZodOptional<z.ZodObject<{
@@ -67,8 +67,8 @@ type GeminiErrorEvent = z.infer<typeof GeminiErrorEvent>;
 declare const GeminiResultEvent: z.ZodObject<{
     type: z.ZodLiteral<"result">;
     status: z.ZodEnum<{
-        success: "success";
         error: "error";
+        success: "success";
     }>;
     error: z.ZodOptional<z.ZodObject<{
         type: z.ZodString;
@@ -109,8 +109,8 @@ declare const GeminiEvent: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"tool_result">;
     tool_id: z.ZodString;
     status: z.ZodEnum<{
-        success: "success";
         error: "error";
+        success: "success";
     }>;
     output: z.ZodOptional<z.ZodString>;
     error: z.ZodOptional<z.ZodObject<{
@@ -129,8 +129,8 @@ declare const GeminiEvent: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"result">;
     status: z.ZodEnum<{
-        success: "success";
         error: "error";
+        success: "success";
     }>;
     error: z.ZodOptional<z.ZodObject<{
         type: z.ZodString;

package/dist/agents/opencode/adapter.js

@@ -14,6 +14,7 @@
  * 7. Clean up server on completion
  */
 import { registerAdapter } from "../registry.js";
+import { buildPermissionEnvironment } from "./build-permission-environment.js";
 import { cleanupSession } from "./cleanup-session.js";
 import { createSessionStartEvent } from "./create-session-start-event.js";
 import { determineSessionSuccess } from "../../determine-session-success.js";
@@ -49,7 +50,13 @@ async function* streamSession(options) {
     process.on("SIGTERM", forwardSignal);
     try {
         // 1. Spawn server
-        const server = await spawnServer({ cwd, signal, env: options.configEnv });
+        const configEnvironment = options.configEnv ?? {};
+        const permissionEnvironment = buildPermissionEnvironment(configEnvironment);
+        const server = await spawnServer({
+            cwd,
+            signal,
+            env: { ...configEnvironment, ...permissionEnvironment },
+        });
         serverProcess = server.process;
         serverUrl = server.url;
         // 2. Connect to SSE and start streaming

package/dist/agents/opencode/build-permission-environment.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Builds permissive OpenCode environment variables for headless execution.
+ *
+ * When axconfig hasn't generated an explicit OPENCODE_CONFIG_DIR (via
+ * --allow/--deny), this injects allow-all permissions to avoid interactive
+ * prompts. OpenCode's default config includes "ask" permissions that would
+ * block headless execution.
+ */
+/**
+ * Returns environment variables for permissive OpenCode execution.
+ *
+ * Returns an empty object (don't override) if:
+ * - `OPENCODE_CONFIG_DIR` is set (axconfig's explicit permissions via --allow/--deny)
+ * - `OPENCODE_PERMISSION` is already set (caller's explicit permissions)
+ */
+declare function buildPermissionEnvironment(configEnvironment: Record<string, string>): Record<string, string>;
+export { buildPermissionEnvironment };

package/dist/agents/opencode/build-permission-environment.js

@@ -0,0 +1,31 @@
+/**
+ * Builds permissive OpenCode environment variables for headless execution.
+ *
+ * When axconfig hasn't generated an explicit OPENCODE_CONFIG_DIR (via
+ * --allow/--deny), this injects allow-all permissions to avoid interactive
+ * prompts. OpenCode's default config includes "ask" permissions that would
+ * block headless execution.
+ */
+/**
+ * Returns environment variables for permissive OpenCode execution.
+ *
+ * Returns an empty object (don't override) if:
+ * - `OPENCODE_CONFIG_DIR` is set (axconfig's explicit permissions via --allow/--deny)
+ * - `OPENCODE_PERMISSION` is already set (caller's explicit permissions)
+ */
+function buildPermissionEnvironment(configEnvironment) {
+    if (configEnvironment["OPENCODE_CONFIG_DIR"] !== undefined ||
+        configEnvironment["OPENCODE_PERMISSION"] !== undefined) {
+        return {};
+    }
+    return {
+        OPENCODE_PERMISSION: JSON.stringify({
+            "*": "allow",
+            doom_loop: "allow",
+            external_directory: "allow",
+            read: "allow",
+            question: "allow",
+        }),
+    };
+}
+export { buildPermissionEnvironment };

package/dist/agents/opencode/parse-sse-event.js

@@ -110,7 +110,9 @@ function parseSSEEvent(event, state) {
             {
                 type: "session.error",
                 code: "PERMISSION_REQUIRED",
-                message: `OpenCode requires permission: ${tool}. ${title}. Pre-configure permissions in OpenCode settings.`,
+                message: `OpenCode requires permission: ${tool}. ${title}. ` +
+                    `axexec runs OpenCode non-interactively, so permission prompts are treated as errors. ` +
+                    `Use axexec --allow/--deny to pre-configure permissions.`,
                 timestamp: Date.now(),
             },
         ];

package/dist/agents/opencode/spawn-server.js

@@ -4,6 +4,7 @@
  * Handles spawning the OpenCode server process and waiting for it to start.
  */
 import { spawn } from "node:child_process";
+import { buildBaseEnvironment } from "../../build-agent-environment.js";
 import { resolveBinary } from "../../resolve-binary.js";
 /** Error thrown when server fails to start */
 class ServerStartError extends Error {
@@ -27,10 +28,20 @@ async function spawnServer(options) {
             environmentVariable: "AXEXEC_OPENCODE_PATH",
             installHint: "npm install -g opencode-ai",
         });
+        // OpenCode supports several env-based configuration overrides (OPENCODE_*).
+        // Exclude them from the host environment so axexec can run with isolated
+        // temp config/data directories instead of inheriting user settings.
+        const baseEnvironment = buildBaseEnvironment([
+            "OPENCODE_CONFIG",
+            "OPENCODE_CONFIG_CONTENT",
+            "OPENCODE_CONFIG_DIR",
+            "OPENCODE_DATA_DIR",
+            "OPENCODE_PERMISSION",
+        ]);
         const child = spawn(bin, ["serve", "--port", "0"], {
             cwd,
             stdio: ["ignore", "pipe", "pipe"],
-            env: { ...process.env, ...env },
+            env: { ...baseEnvironment, ...env },
         });
         let stderrBuffer = "";
         let resolved = false;

package/dist/build-agent-environment.js

@@ -1,10 +1,18 @@
 const VAULT_ENV_EXCLUSIONS = ["AXVAULT", "AXVAULT_URL", "AXVAULT_API_KEY"];
+// Prevent upstream CLIs from enabling their own internal sandboxing based on
+// host environment variables. axexec is intentionally insecure-by-default and
+// does not rely on agent-internal sandboxing for enforcement.
+const AGENT_INTERNAL_SANDBOX_ENV_EXCLUSIONS = [
+    "GEMINI_SANDBOX",
+    "SEATBELT_PROFILE",
+];
 function isAxCredentialEnvironment(key) {
     return key.startsWith("AX_") && key.endsWith("_CREDENTIALS");
 }
 function buildBaseEnvironment(additionalExclusions = []) {
     const allExclusions = new Set([
         ...VAULT_ENV_EXCLUSIONS,
+        ...AGENT_INTERNAL_SANDBOX_ENV_EXCLUSIONS,
         ...additionalExclusions,
     ]);
     const entries = Object.entries(process.env).flatMap(([key, value]) => {

package/dist/build-execution-metadata.js

@@ -19,7 +19,7 @@ function buildExecutionMetadata(agentId, options, credentialResult, credentials,
     if (credentials) {
         execution.credentials = {
             type: credentials.type,
-            provider: credentials.agent === "opencode" ? credentials.provider : undefined,
+            provider: options.provider,
         };
     }
     return execution;

package/dist/cli.d.ts

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
 /**
- * axexec CLI - Unified agent execution with isolation.
+ * axexec CLI - Unified agent execution with credential/config 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
+ * axexec is a headless runner and normalization layer. It isolates agent
+ * credentials/config from your local environment via temp directories, but it
+ * is not an OS sandbox and is intentionally permissive/non-interactive by
+ * default. Use an external sandbox (container/VM) for real enforcement.
  */
 import "./agents/claude-code/adapter.js";
 import "./agents/codex/adapter.js";