aws-cli-agent 0.4.0

package/dist/agent.js

@@ -0,0 +1,293 @@
+import { streamText, stepCountIs } from 'ai';
+import { createModel } from './providers.js';
+import { createTools } from './tools/index.js';
+const SYSTEM_PROMPT = `You are aws-cli-agent (aca), an agentic assistant that translates natural-language requests into AWS CLI commands and executes them locally on the user's machine.
+
+Capabilities (via tools):
+- query_history: search local past commands to recover context (profiles, bucket/instance/cluster names).
+- list_aws_profiles: enumerate ~/.aws profiles to map account names to profiles.
+- execute_aws_command: run an AWS CLI call. Read-only calls (describe-/list-/get-/s3 ls) may auto-approve; mutating calls always prompt the user.
+- prompt_user: ask the user ONE question (kind: text | choice | confirm | secret) to fill in missing information mid-reasoning.
+- prompt_user_multi: ask several related questions in one round (e.g. "source profile + destination profile + region").
+- execute_bash_script: run a bash script. Use for multi-account / loop / jq workflows.
+
+CARDINAL RULE — DO NOT GUESS. If you don't know a value that's required for the user's task, ASK the user via prompt_user (or prompt_user_multi). This is non-negotiable. Concrete examples:
+
+- The user said "list buckets" but didn't say which account, and history has no obvious match → call list_aws_profiles, then prompt_user with kind="choice" listing the profiles.
+- A "describe-instances" call returned 3 instances with the requested tag → prompt_user with kind="choice" listing the 3 candidates. Do NOT pick one yourself.
+- The user said "delete the old logs bucket" but several buckets contain "logs" → prompt_user with kind="choice" showing the matches.
+- You're about to run a destructive command (delete-, terminate-, remove-, drop-, etc.) and have any doubt about the right target → prompt_user with kind="confirm" stating exactly what will be deleted.
+- The user asked for an MFA-protected action and you need the code → prompt_user with kind="secret".
+
+When you DON'T need to ask:
+- The value is unambiguous in the user's request ("in account abc-xyz" → profile is abc-xyz).
+- query_history returned a single clean match for the relevant token.
+- The value is determinable by a read-only AWS CLI call (e.g. instance id by tag, when there's exactly one match).
+
+Asking earns trust. Guessing wrong and acting on it is much worse than one extra question.
+
+Operating rules:
+1. ALWAYS start by calling query_history with the most informative tokens from the user request. Use the results to infer profile and common parameters.
+2. If the user names an account that history did not resolve, call list_aws_profiles. If still ambiguous, prompt_user with kind="choice" listing the available profiles.
+3. For multi-step requests (e.g. "ssm session to instance NAME in ACCOUNT"), first run a read-only describe/list call to resolve the resource (instance id, cluster endpoint, etc.). If exactly one match, proceed. If multiple, prompt_user with choices. If zero, prompt_user kind="text" asking for a more specific name (and offer to retry).
+4. When you need multiple unrelated parameters up front (e.g. source profile, target profile, region), call prompt_user_multi once instead of three separate prompt_user calls. When the answer to A would determine what to ask for B, use separate prompt_user calls in sequence.
+5. For tasks that span multiple AWS accounts or require composition (jq, loops), build a bash script with "set -euo pipefail" at the top and invoke execute_bash_script.
+6. Default to the user's preferred output format. For listings the user will read directly (e.g. "list buckets", "list instances"), use the AWS CLI's default text/table output, NOT JSON. Only use "--output json" when you specifically need to parse fields for a subsequent step.
+7. Region handling: if the user names a region in the request, pass it explicitly with --region. If they don't, omit --region entirely — the host CLI will inject the user's configured defaultRegion automatically when one is set. Never invent a region.
+8. Interactive commands: some AWS CLI commands require a real terminal — SSM Session Manager shells (\`ssm start-session\`), port-forwarding sessions (the same command with --document-name AWS-StartPortForwardingSession*), ECS Exec (\`ecs execute-command\`), log tails with --follow. For these, set \`interactive: true\` on the execute_aws_command call. The host will connect the user's terminal directly to the command and you will receive no stdout — DO NOT try to summarize or describe the output afterwards, since you can't see it. Common patterns auto-detect, but setting the flag explicitly is safer.
+9. The final action of a successful run MUST be either execute_aws_command (the user-requested action) or execute_bash_script. If the user cancels via prompt_user, stop gracefully and explain in one sentence.
+10. NEVER include credentials, API keys, secrets, or session tokens in commands or scripts. AWS credentials come from the user's existing profile.
+11. Keep your reasoning concise — one or two sentences per step. DO NOT summarize, restate, reformat, or describe the output of the AWS CLI. The CLI's stdout is shown to the user directly by the host program. Your only post-execution job is to stop. If anything went wrong, say so briefly; if it succeeded, you may stop without further commentary.`;
+export async function runAgent(opts) {
+    const { input, config, logger, history, audit, reasoning, usage } = opts;
+    const executions = [];
+    const record = (entry) => {
+        executions.push(entry);
+    };
+    // Whether to enable prompt caching for this run. Anthropic and Bedrock
+    // support an explicit `cacheControl` / `cachePoint` marker on the system
+    // message — see `systemMessageProviderOptions` below. OpenAI auto-caches
+    // prompts over 1,024 tokens with no opt-in needed; Google Gemini's caching
+    // API is structurally different and not wired up. If caching=false in
+    // config, we don't send markers anywhere.
+    //
+    // Note: only the system message gets cached. Marking individual tool
+    // definitions does not work — the Bedrock provider drops tool-level
+    // providerOptions before serializing the request. See the comment in
+    // tools/index.ts. So the cached prefix is the system prompt only;
+    // the tools array is sent at full cost on every request.
+    const useCaching = config.caching && (config.provider === 'anthropic' || config.provider === 'bedrock');
+    const tools = createTools({ logger, config, history, audit, record });
+    const model = createModel(config);
+    logger.info(`Starting agent (provider=${config.provider}, model=${config.model})`);
+    logger.debug('User input', input);
+    reasoning.beginRun(input);
+    // Inline a small recent-history hint so the model has soft context even
+    // before it explicitly calls query_history. Statelessness on the server
+    // side is preserved: we send the full prompt each call.
+    const recent = history.recent(5);
+    const historyHint = recent.length
+        ? '\n\nRecent past requests (most recent first):\n' +
+            recent
+                .map((e, i) => `${i + 1}. "${e.input}" -> profile=${e.profile ?? 'n/a'}` +
+                (Object.keys(e.resources).length ? ` resources=${JSON.stringify(e.resources)}` : ''))
+                .join('\n')
+        : '';
+    // The cached prefix is the SYSTEM PROMPT only — kept byte-stable across
+    // invocations. The per-invocation history hint goes in the user message
+    // where it can't invalidate the cache. Tool definitions are part of the
+    // request prefix the providers cache implicitly when the system message
+    // is marked, so we don't need a separate marker for those.
+    const systemMessageProviderOptions = useCaching
+        ? {
+            anthropic: { cacheControl: { type: 'ephemeral' } },
+            bedrock: { cachePoint: { type: 'default' } },
+        }
+        : undefined;
+    // Build the user-side content. Prepend the history hint so it stays
+    // OUTSIDE the cached system message (it varies per invocation and would
+    // bust the cache if included in the system prompt).
+    const userContent = historyHint
+        ? `${historyHint}\n\n---\n\nUser request: ${input}`
+        : input;
+    // Closure variables shared between the streamText callback and the
+    // for-await loop below. Hoisted above streamText so the callback can read
+    // them. start-step sets toolCallStepNumber to the current step number so
+    // onToolCallStart knows which step to label the tool-call line with.
+    let stepCounter = 0;
+    let toolCallStepNumber = 0;
+    let currentReasoning = '';
+    let currentToolCalls = [];
+    let reasoningEchoed = false;
+    const result = streamText({
+        model,
+        messages: [
+            {
+                role: 'system',
+                content: SYSTEM_PROMPT,
+                providerOptions: systemMessageProviderOptions,
+            },
+            { role: 'user', content: userContent },
+        ],
+        // The SDK warns when role:'system' messages appear in the messages array
+        // because that field is a potential prompt-injection vector for callers
+        // who template the system message from user input. In our case the
+        // system message is a hardcoded string literal (SYSTEM_PROMPT) and we
+        // need it in the messages array — not the top-level `system:` param —
+        // so we can attach providerOptions for prompt caching. Setting this
+        // flag is the SDK's documented way of saying "I'm aware, my system
+        // message is trusted."
+        allowSystemInMessages: true,
+        tools,
+        // AI SDK v5+ replaced the `maxSteps: number` setting with `stopWhen`,
+        // which accepts one or more stop conditions. stepCountIs(n) is the
+        // straight equivalent.
+        stopWhen: stepCountIs(config.maxSteps),
+        // Print the tool-call line synchronously before execute() runs. We use
+        // this callback rather than the `tool-call` event in fullStream because
+        // the SDK launches execute() as a concurrent task — by the time our
+        // for-await loop sees `tool-call` in the stream, execute may already
+        // be running (or done). This callback fires inline, immediately before
+        // execute(), guaranteeing the tool-call line appears above any
+        // approval prompt the tool's execute() shows.
+        experimental_onToolCallStart: (event) => {
+            const input = 'input' in event.toolCall ? event.toolCall.input : undefined;
+            reasoning.echoToolCall(toolCallStepNumber, event.toolCall.toolName, input);
+            currentToolCalls.push({ toolName: event.toolCall.toolName, args: input });
+        },
+    });
+    // Drive the agent by consuming the full stream. The reasoning text
+    // streams as text-delta events; we accumulate it and echo on text-end
+    // so the user sees it BEFORE the tool-call line (which prints from the
+    // onToolCallStart callback above, synchronously before execute()).
+    //
+    // Two execution sites collaborate to print one step:
+    //   1. text-end (here) → reasoning text line
+    //   2. onToolCallStart (callback above) → tool: line, then execute()
+    for await (const part of result.fullStream) {
+        switch (part.type) {
+            case 'start-step': {
+                stepCounter += 1;
+                toolCallStepNumber = stepCounter; // visible to onToolCallStart
+                currentReasoning = '';
+                currentToolCalls = [];
+                reasoningEchoed = false;
+                break;
+            }
+            case 'text-delta': {
+                currentReasoning += part.text;
+                break;
+            }
+            case 'text-end': {
+                if (!reasoningEchoed) {
+                    reasoning.echoReasoning(stepCounter, currentReasoning);
+                    reasoningEchoed = true;
+                }
+                break;
+            }
+            case 'tool-call': {
+                // Backup echo path: if text-end didn't fire (provider variant or
+                // text-less step), echo whatever reasoning we have when we see
+                // tool-call. The tool-call LINE itself is NOT printed here — it's
+                // printed by experimental_onToolCallStart, which fires
+                // synchronously before execute() and guarantees ordering above
+                // any approval prompt.
+                if (!reasoningEchoed) {
+                    reasoning.echoReasoning(stepCounter, currentReasoning);
+                    reasoningEchoed = true;
+                }
+                break;
+            }
+            case 'finish-step': {
+                reasoning.logStepToFile({
+                    step: stepCounter,
+                    reasoning: currentReasoning,
+                    toolCalls: currentToolCalls,
+                    finishReason: part.finishReason,
+                });
+                logger.debug(`Step ${stepCounter} finished (finishReason=${part.finishReason})`);
+                break;
+            }
+            // Other event types (reasoning-delta for thinking-models,
+            // tool-input-delta, source, file, raw, etc.) are ignored —
+            // fullStream is forward-compatible.
+        }
+    }
+    // Wait for all the post-stream promises to resolve. They're already
+    // ready by the time fullStream finishes (the stream completion is the
+    // signal), so these awaits are effectively synchronous.
+    const finalText = await result.text;
+    const finalSteps = await result.steps;
+    const totalUsage = await result.totalUsage;
+    logger.info(`Agent finished after ${finalSteps.length} step(s)`);
+    logger.debug('Final text', finalText);
+    // Token usage for this invocation.
+    //
+    // In AI SDK v5/v6, `result.usage` is only the LAST step's tokens — confusingly
+    // named. `result.totalUsage` is the sum across all steps. We want totalUsage.
+    //
+    // Cache hit/miss counts live in `totalUsage.inputTokenDetails`. The SDK
+    // normalizes these across providers — no need to dig into provider-specific
+    // metadata. The previous code path that read providerMetadata.{anthropic,
+    // bedrock}.* was looking in the wrong place; cache counts in providerMetadata
+    // are raw, per-provider, and located differently per provider (Bedrock nests
+    // them under `usage`, Anthropic doesn't). inputTokenDetails is the
+    // recommended cross-provider surface.
+    //
+    // We still dump per-step providerMetadata at trace level for debugging —
+    // useful when caching numbers look wrong and you want to see exactly what
+    // the provider returned.
+    for (const step of finalSteps) {
+        const pm = step.providerMetadata;
+        if (pm)
+            logger.trace(`step ${step.stepNumber} providerMetadata`, pm);
+    }
+    const td = totalUsage?.inputTokenDetails;
+    const cacheReadTokens = toNumber(td?.cacheReadTokens);
+    const cacheWriteTokens = toNumber(td?.cacheWriteTokens);
+    usage.log({
+        input,
+        provider: config.provider,
+        model: config.model,
+        steps: finalSteps.length,
+        promptTokens: totalUsage?.inputTokens ?? 0,
+        completionTokens: totalUsage?.outputTokens ?? 0,
+        totalTokens: totalUsage?.totalTokens ?? 0,
+        cacheReadTokens,
+        cacheWriteTokens,
+    });
+    logger.debug('Usage', { ...totalUsage, cacheReadTokens, cacheWriteTokens });
+    // Determine what to show the user as the final output. Rule: the LAST
+    // execution wins, regardless of success — and if it failed or was
+    // declined, no stdout is printed at all (we only have intermediate
+    // scaffolding output left, which the user didn't ask for).
+    //
+    // Previously we used `find((e) => e.ok)`, which selected the most recent
+    // *successful* call. That was wrong when the final intended action was
+    // declined or failed: the heuristic fell back to an earlier discovery
+    // call (describe-instances, list-buckets, etc.) and printed its JSON as
+    // if it were the user's answer — confusing because it wasn't.
+    //
+    // For an empty run (no executions, e.g. the agent just talked) we have
+    // nothing to print and `finalOutput` stays null.
+    const last = executions.length > 0 ? executions[executions.length - 1] : null;
+    const lastProfile = [...executions].reverse().find((e) => e.profile)?.profile ?? null;
+    const finalOutput = last?.ok ? last.stdout : null;
+    const finalError = last && !last.ok ? last.stderr : null;
+    const ranCommand = last?.ok === true;
+    const entry = {
+        timestamp: new Date().toISOString(),
+        input,
+        commands: executions.map((e) => e.cmd),
+        profile: lastProfile,
+        resources: {},
+        success: ranCommand,
+    };
+    history.append(entry);
+    // "Executed" = the subprocess actually ran. Declines/cancellations use
+    // exitCode -1 by convention (no process was ever spawned); successes use
+    // 0, real failures use a non-zero exit. We count anything that has a real
+    // exit code (≥ 0), so the user-facing footer reflects reality.
+    const executedCommandCount = executions.filter((e) => e.exitCode >= 0).length;
+    return {
+        text: finalText,
+        steps: finalSteps.length,
+        commands: executions.map((e) => e.cmd),
+        executedCommandCount,
+        profile: lastProfile,
+        finalOutput,
+        finalError,
+        ranCommand,
+    };
+}
+/**
+ * Coerce an unknown metadata value to a non-negative integer. Providers
+ * sometimes return null/undefined when no cache event occurred; the Bedrock
+ * provider in particular returns NaN for missing fields. All those should
+ * funnel to 0 in the usage log.
+ */
+function toNumber(v) {
+    if (typeof v !== 'number' || !Number.isFinite(v) || v < 0)
+        return 0;
+    return v;
+}

package/dist/audit.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Audit log: append-only JSONL of every command and script the agent ran on
+ * the user's behalf. The audit log is intentionally exhaustive — it captures
+ * the verbatim stdout/stderr so that, after the fact, you can reconstruct
+ * exactly what the agent did and what AWS returned. For bash scripts the full
+ * script source is included.
+ *
+ * Disable via `audit.enabled = false` in config; the writer becomes a no-op.
+ */
+export type AuditCommandEntry = {
+    timestamp: string;
+    type: 'aws_command';
+    cmd: string;
+    profile: string | null;
+    exitCode: number;
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+};
+export type AuditScriptEntry = {
+    timestamp: string;
+    type: 'bash_script';
+    cmd: string;
+    profile: string | null;
+    exitCode: number;
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    script: string;
+};
+export type AuditEntry = AuditCommandEntry | AuditScriptEntry;
+export declare class AuditLogger {
+    private readonly stream;
+    constructor(enabled: boolean);
+    logCommand(entry: Omit<AuditCommandEntry, 'timestamp' | 'type'>): void;
+    logScript(entry: Omit<AuditScriptEntry, 'timestamp' | 'type'>): void;
+    private write;
+    close(): void;
+}

package/dist/audit.js

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import { FILES, PATHS } from './paths.js';
+export class AuditLogger {
+    stream;
+    constructor(enabled) {
+        if (!enabled) {
+            this.stream = null;
+            return;
+        }
+        fs.mkdirSync(PATHS.state, { recursive: true });
+        this.stream = fs.createWriteStream(FILES.audit, { flags: 'a' });
+    }
+    logCommand(entry) {
+        this.write({ timestamp: new Date().toISOString(), type: 'aws_command', ...entry });
+    }
+    logScript(entry) {
+        this.write({ timestamp: new Date().toISOString(), type: 'bash_script', ...entry });
+    }
+    write(entry) {
+        if (!this.stream)
+            return;
+        try {
+            this.stream.write(JSON.stringify(entry) + '\n');
+        }
+        catch {
+            // Auditing must never crash the agent. Failures here are silent by
+            // design; the operational logger will still surface execution errors.
+        }
+    }
+    close() {
+        this.stream?.end();
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,179 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { loadConfig, writeDefaultConfig } from './config.js';
+import { Logger } from './logger.js';
+import { AuditLogger } from './audit.js';
+import { ReasoningLogger } from './reasoning.js';
+import { UsageLogger } from './usage.js';
+import { History } from './history.js';
+import { runAgent } from './agent.js';
+import { FILES, PATHS, DEFAULT_SCRIPT_FOLDER } from './paths.js';
+const VERSION = '0.4.0';
+/**
+ * Apply CLI flags on top of the loaded config. Flags only override; they
+ * never widen or compose with each other implicitly.
+ */
+function applyCliOverrides(cfg, opts) {
+    let next = cfg;
+    if (opts.verbose) {
+        next = { ...next, verbose: true };
+    }
+    if (opts.logLevel) {
+        next = { ...next, logging: { ...next.logging, level: opts.logLevel } };
+    }
+    if (opts.autoApprove) {
+        next = { ...next, autoApprove: { readOnly: true, all: true } };
+    }
+    if (opts.region) {
+        next = { ...next, defaultRegion: opts.region };
+    }
+    if (opts.interactive) {
+        next = { ...next, forceInteractive: true };
+    }
+    return next;
+}
+export async function main(argv) {
+    const program = new Command();
+    program
+        .name('aca')
+        .description('aws-cli-agent (aca): agentic AI assistant that turns natural language into AWS CLI commands.')
+        .version(VERSION)
+        .option('-v, --verbose', 'echo agent reasoning to the console as it runs')
+        .option('--log-level <level>', 'override logging.level for this run: silent | error | warn | info | debug | trace')
+        .option('--auto-approve', 'auto-approve all commands and scripts for this run (use with care)')
+        .option('--profile <name>', 'hint the agent to use this AWS profile')
+        .option('--region <name>', 'override defaultRegion for this run (only applies when the agent did not pick a region itself)')
+        .option('-i, --interactive', 'force AWS CLI commands to inherit your terminal (for shells, port-forwards, log tails). ' +
+        'Common patterns auto-detect; this is the manual override.');
+    program
+        .command('config')
+        .description('Print the config file path; create defaults if missing.')
+        .action(() => {
+        const p = writeDefaultConfig();
+        process.stdout.write(p + '\n');
+    });
+    program
+        .command('paths')
+        .description('Print paths used by aws-cli-agent.')
+        .action(() => {
+        const cfg = loadConfig();
+        const scriptFolder = cfg.scriptFolder ?? DEFAULT_SCRIPT_FOLDER;
+        const out = [
+            `config dir   : ${PATHS.config}`,
+            `state dir    : ${PATHS.state}`,
+            '',
+            `config file  : ${FILES.config}`,
+            `history      : ${FILES.history}`,
+            `general log  : ${FILES.log}`,
+            `audit log    : ${FILES.audit}`,
+            `reasoning log: ${FILES.reasoning}`,
+            `usage log    : ${FILES.usage}`,
+            `script folder: ${scriptFolder}`,
+        ].join('\n');
+        process.stdout.write(out + '\n');
+    });
+    program
+        .command('history')
+        .description('Print recent history entries.')
+        .option('-n, --count <number>', 'how many entries', '10')
+        .action(async (cmdOpts) => {
+        const cfg = loadConfig();
+        const h = new History(cfg.historyLimit);
+        await h.load();
+        const n = Number.parseInt(cmdOpts.count, 10);
+        for (const e of h.recent(Number.isFinite(n) ? n : 10)) {
+            process.stdout.write(`${chalk.dim(e.timestamp)} ${chalk.bold(e.input)}\n`);
+            if (e.profile)
+                process.stdout.write(`  profile: ${e.profile}\n`);
+            for (const c of e.commands) {
+                process.stdout.write(`  ${chalk.green(c)}\n`);
+            }
+        }
+    });
+    program
+        .command('run', { isDefault: true })
+        .description('Run a natural-language request (default).')
+        .argument('<request...>', 'natural-language request')
+        .action(async (requestArgs) => {
+        const globalOpts = program.opts();
+        const request = requestArgs.join(' ').trim();
+        if (!request) {
+            program.help();
+            return;
+        }
+        const cfg = applyCliOverrides(loadConfig(), globalOpts);
+        const logger = new Logger(cfg.logging.level);
+        const audit = new AuditLogger(cfg.logging.auditLog);
+        const reasoning = new ReasoningLogger({
+            enabled: cfg.logging.reasoningLog,
+            consoleEcho: cfg.verbose,
+        });
+        const usage = new UsageLogger(cfg.logging.usageLog);
+        const history = new History(cfg.historyLimit);
+        await history.load();
+        const finalRequest = globalOpts.profile
+            ? `${request}\n(Use AWS profile: ${globalOpts.profile})`
+            : request;
+        try {
+            const result = await runAgent({
+                input: finalRequest,
+                config: cfg,
+                logger,
+                history,
+                audit,
+                reasoning,
+                usage,
+            });
+            // Output policy: stdout is reserved for the AWS CLI's verbatim output.
+            // Everything else (reasoning, prompts, status, commands executed) goes
+            // to stderr via the logger. This keeps `aca ... | jq` and similar
+            // pipelines working as if the user ran aws directly.
+            // Decide what reaches the user's terminal:
+            // - Successful final command → its stdout goes to stdout (pipeable).
+            // - Genuine failure (non-zero exit, spawn error, etc.) → its stderr
+            //   goes to stderr in red, and the process exits 1.
+            // - User declined/cancelled → quiet exit. The agent's text response
+            //   (if any) tells the user the action was cancelled; no red noise.
+            // - Nothing useful → fall back to the agent's final text, if any.
+            const wasDeclined = result.finalError === '[declined by user]' ||
+                result.finalError === '[cancelled by user]';
+            if (result.ranCommand && result.finalOutput !== null) {
+                process.stdout.write(result.finalOutput);
+                if (!result.finalOutput.endsWith('\n'))
+                    process.stdout.write('\n');
+            }
+            else if (result.finalError && !wasDeclined) {
+                process.stderr.write(chalk.red(result.finalError));
+                if (!result.finalError.endsWith('\n'))
+                    process.stderr.write('\n');
+                process.exitCode = 1;
+            }
+            else if (result.text.trim().length > 0) {
+                process.stderr.write(result.text.trim() + '\n');
+            }
+            // Footer counts only commands that actually executed. Declined or
+            // cancelled commands appear in `result.commands` for the history
+            // log but don't count as "ran" since no subprocess was started.
+            if (result.executedCommandCount > 0) {
+                const tag = result.profile ? `[${result.profile}]` : '';
+                const cmds = result.executedCommandCount === 1
+                    ? '1 command'
+                    : `${result.executedCommandCount} commands`;
+                process.stderr.write(chalk.dim(`\nran ${cmds} ${tag}\n`));
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error('Agent failed', msg);
+            process.stderr.write(chalk.red('Error: ') + msg + '\n');
+            process.exitCode = 1;
+        }
+        finally {
+            logger.close();
+            audit.close();
+            reasoning.close();
+            usage.close();
+        }
+    });
+    await program.parseAsync(argv);
+}

package/dist/config.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+export declare const ConfigSchema: z.ZodObject<{
+    provider: z.ZodDefault<z.ZodEnum<{
+        bedrock: "bedrock";
+        anthropic: "anthropic";
+        openai: "openai";
+        google: "google";
+    }>>;
+    model: z.ZodDefault<z.ZodString>;
+    apiKeyEnv: z.ZodOptional<z.ZodString>;
+    bedrock: z.ZodOptional<z.ZodObject<{
+        region: z.ZodOptional<z.ZodString>;
+        profile: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    defaultRegion: z.ZodOptional<z.ZodString>;
+    maxSteps: z.ZodDefault<z.ZodNumber>;
+    logging: z.ZodDefault<z.ZodObject<{
+        level: z.ZodDefault<z.ZodEnum<{
+            silent: "silent";
+            error: "error";
+            warn: "warn";
+            info: "info";
+            debug: "debug";
+            trace: "trace";
+        }>>;
+        auditLog: z.ZodDefault<z.ZodBoolean>;
+        reasoningLog: z.ZodDefault<z.ZodBoolean>;
+        usageLog: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    caching: z.ZodDefault<z.ZodBoolean>;
+    verbose: z.ZodDefault<z.ZodBoolean>;
+    autoApprove: z.ZodDefault<z.ZodObject<{
+        readOnly: z.ZodDefault<z.ZodBoolean>;
+        all: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    forceInteractive: z.ZodDefault<z.ZodBoolean>;
+    historyLimit: z.ZodDefault<z.ZodNumber>;
+    scriptFolder: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare function loadConfig(): Config;
+/** Write a default config file if none exists. Returns the path either way. */
+export declare function writeDefaultConfig(): string;