axexec 1.0.0 → 1.1.0

package/dist/run-agent.d.ts

@@ -1,32 +1,16 @@
 /**
  * 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;
-}
+import type { RunAgentOptions, RunResult } from "./types/run-result.js";
 /**
  * Runs an agent with full isolation.
  *
  * 1. Validates the agent ID
- * 2. Parses credentials from environment
- * 3. Installs credentials to temp directory
+ * 2. Uses provided credentials or parses from environment
+ * 3. Creates isolated temp directories and installs credentials if provided
  * 4. Builds config if permissions specified
  * 5. Streams events from agent
- * 6. Cleans up temp directory
+ * 6. Cleans up temp directory (unless preserveConfigDirectory is true)
  */
 declare function runAgent(agentId: string, options: RunAgentOptions): Promise<RunResult>;
 export { runAgent };

package/dist/run-agent.js

@@ -1,146 +1,104 @@
 /**
  * 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 { buildPermissionsConfig } from "./build-permissions-config.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";
+import { buildExecutionMetadata } from "./build-execution-metadata.js";
+import { executeAgent } from "./execute-agent.js";
+import { resolveDiagnostics, resolveExitCodeSetter, } from "./resolve-run-diagnostics.js";
 /**
  * Runs an agent with full isolation.
  *
  * 1. Validates the agent ID
- * 2. Parses credentials from environment
- * 3. Installs credentials to temp directory
+ * 2. Uses provided credentials or parses from environment
+ * 3. Creates isolated temp directories and installs credentials if provided
  * 4. Builds config if permissions specified
  * 5. Streams events from agent
- * 6. Cleans up temp directory
+ * 6. Cleans up temp directory (unless preserveConfigDirectory is true)
  */
 async function runAgent(agentId, options) {
+    const diagnostics = resolveDiagnostics(options);
+    const setExitCode = resolveExitCodeSetter(options);
+    const preserveConfigDirectory = options.preserveConfigDirectory ?? false;
     // Validate agent
     const validation = validateAgent(agentId);
     if (!validation.ok) {
-        process.stderr.write(validation.message + "\n");
-        process.exitCode = validation.exitCode;
-        return { events: [], success: false };
+        diagnostics.error(validation.message);
+        setExitCode(validation.exitCode);
+        // Return minimal execution metadata for failed validation
+        return {
+            events: [],
+            success: false,
+            execution: { agent: "unknown", invalidAgentId: agentId },
+        };
     }
     const { adapter } = validation;
-    // Parse credentials from environment
-    const credentials = parseCredentialsFromEnvironment(agentId);
-    // Install credentials to temp directory
+    // Use provided credentials or parse from environment
+    const credentialsResult = options.credentials
+        ? { ok: true, credentials: options.credentials }
+        : parseCredentialsFromEnvironment(validation.agentId, options.model);
+    if (!credentialsResult.ok) {
+        diagnostics.error(credentialsResult.message);
+        setExitCode(credentialsResult.exitCode);
+        return {
+            events: [],
+            success: false,
+            execution: { agent: validation.agentId, model: options.model },
+        };
+    }
+    // Credentials are optional; isolation still applies even when none are found.
+    const credentials = credentialsResult.credentials;
+    if (credentials && credentials.agent !== validation.agentId) {
+        diagnostics.error("Error: Credentials agent mismatch. " +
+            `Expected ${validation.agentId}, got ${credentials.agent}.`);
+        setExitCode(2);
+        return {
+            events: [],
+            success: false,
+            execution: { agent: validation.agentId, model: options.model },
+        };
+    }
+    // Always create isolated runtime directories; install credentials if provided.
     let credentialResult;
     try {
-        credentialResult = await installCredentials(validation.agentId, credentials);
+        credentialResult = await installCredentials(validation.agentId, credentials, diagnostics.warn);
     }
     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 };
+        diagnostics.error(`Error installing credentials: ${message}`);
+        setExitCode(1);
+        return {
+            events: [],
+            success: false,
+            execution: { agent: validation.agentId, model: options.model },
+        };
     }
     // 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,
-        });
+        const configResult = buildPermissionsConfig(validation.agentId, options, credentialResult);
         if (!configResult.ok) {
-            if ("message" in configResult) {
-                process.stderr.write(`Error: ${configResult.message}\n`);
+            for (const error of configResult.errors) {
+                diagnostics.error(error);
             }
-            else {
-                process.stderr.write(`Error building config: permission errors\n`);
-                for (const error of configResult.errors) {
-                    process.stderr.write(`  - ${error.reason}\n`);
-                }
+            if (!preserveConfigDirectory) {
+                await cleanupCredentials(credentialResult.baseDirectory);
             }
-            return { ok: false, exitCode: configResult.exitCode };
+            setExitCode(configResult.exitCode);
+            return {
+                events: [],
+                success: false,
+                execution: buildExecutionMetadata(validation.agentId, options, credentialResult, credentials, preserveConfigDirectory),
+            };
         }
-        // Log warnings
         for (const warning of configResult.warnings) {
-            process.stderr.write(`Warning: ${warning.reason}\n`);
+            diagnostics.warn(warning);
         }
-        // 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);
+        configEnvironment = configResult.env;
     }
+    // Execute agent
+    return executeAgent(validation.agentId, adapter, options, configEnvironment, credentialResult, credentials, preserveConfigDirectory, diagnostics.error);
 }
 export { runAgent };

package/dist/stream-agent.js

@@ -7,14 +7,7 @@
 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"];
+import { buildBaseEnvironment } from "./build-agent-environment.js";
 /** Error thrown when agent binary is not found */
 class AgentNotFoundError extends Error {
     bin;
@@ -56,13 +49,10 @@ async function* streamAgent(adapter, options) {
             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)));
+    // Build environment: start with process.env, exclude vault vars,
+    // AX_*_CREDENTIALS, and any adapter-specified vars, then merge adapter
+    // env and config env.
+    const baseEnvironment = buildBaseEnvironment(environmentExclusions ?? []);
     const child = spawn(bin, args, {
         env: { ...baseEnvironment, ...env, ...options.configEnv },
         cwd: options.cwd,

package/dist/types/run-result.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Types for run-agent results and options.
+ */
+import type { AgentCli, AxexecEvent } from "./events.js";
+import type { OutputFormat } from "../resolve-output-mode.js";
+import type { Credentials } from "../credentials/credentials.js";
+interface RunAgentDiagnostics {
+    error: (message: string) => void;
+    warn: (message: string) => void;
+}
+interface RunAgentOptions {
+    prompt: string;
+    /**
+     * Credentials to use. If not provided, parses from environment variables.
+     * Accepts the canonical Credentials shape shared across ax* packages.
+     */
+    credentials?: Credentials;
+    model?: string;
+    allow?: string;
+    deny?: string;
+    format?: OutputFormat;
+    rawLog?: string;
+    debug?: boolean;
+    verbose?: boolean;
+    preserveGithubSha?: boolean;
+    /**
+     * Override diagnostic output (errors, warnings) emitted during setup.
+     * Messages include a trailing newline.
+     */
+    diagnostics?: RunAgentDiagnostics;
+    /**
+     * When false, runAgent will not mutate process.exitCode on failures.
+     */
+    setExitCode?: boolean;
+    /**
+     * When true, the temporary config directory is NOT cleaned up after execution.
+     * The caller is responsible for cleanup via `cleanupCredentials()`.
+     * Use this when you need to read files from the config directory after
+     * execution (e.g., refreshed credentials).
+     */
+    preserveConfigDirectory?: boolean;
+}
+/** Directory information from execution */
+interface ExecutionDirectories {
+    /** Base temp directory (parent of config/data dirs) */
+    base: string;
+    /** Config directory where settings/credentials were installed */
+    config: string;
+    /** Data directory (may be same as config for some agents) */
+    data: string;
+    /** Whether directories were preserved (not cleaned up) */
+    preserved: boolean;
+}
+/** Credential information from execution */
+interface ExecutionCredentials {
+    /** Type of credential used */
+    type: "api-key" | "oauth-credentials" | "oauth-token";
+    /** Provider (for multi-provider agents like OpenCode) */
+    provider?: string;
+}
+type ExecutionAgent = AgentCli | "unknown";
+/** Execution metadata - always present in RunResult */
+interface ExecutionMetadata {
+    /** Agent that was executed */
+    agent: ExecutionAgent;
+    /** Invalid agent ID when validation fails */
+    invalidAgentId?: string;
+    /** Temporary directory paths (present when isolation dirs were created) */
+    directories?: ExecutionDirectories;
+    /** Credential information (present if credentials were provided) */
+    credentials?: ExecutionCredentials;
+    /** Model used (if specified) */
+    model?: string;
+}
+interface RunResult {
+    events: AxexecEvent[];
+    success: boolean;
+    /** Execution metadata - always present */
+    execution: ExecutionMetadata;
+}
+export type { ExecutionCredentials, ExecutionDirectories, ExecutionMetadata, RunAgentDiagnostics, RunAgentOptions, RunResult, };

package/dist/types/run-result.js

@@ -0,0 +1,4 @@
+/**
+ * Types for run-agent results and options.
+ */
+export {};

package/package.json

@@ -2,7 +2,7 @@
   "name": "axexec",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Unified CLI runner for AI coding agents with normalized event streaming",
   "repository": {
     "type": "git",
@@ -13,6 +13,14 @@
     "url": "https://github.com/Jercik/axexec/issues"
   },
   "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "bin": {
     "axexec": "bin/axexec"
   },
@@ -58,7 +66,7 @@
   "dependencies": {
     "@commander-js/extra-typings": "^14.0.0",
     "axconfig": "^3.6.0",
-    "axshared": "^1.9.0",
+    "axshared": "^2.0.0",
     "commander": "^14.0.2",
     "zod": "^4.3.5"
   },