aws-cli-agent 0.4.0

package/dist/config.js

@@ -0,0 +1,131 @@
+import fs from 'node:fs';
+import { z } from 'zod';
+import { FILES, PATHS } from './paths.js';
+/**
+ * Logging configuration. All three keys are optional in the file; defaults
+ * tilt toward "quiet but auditable" — a tool that writes to your AWS account
+ * should leave a paper trail by default, but shouldn't be noisy on the
+ * console unless you ask.
+ */
+const LoggingSchema = z
+    .object({
+    level: z
+        .enum(['silent', 'error', 'warn', 'info', 'debug', 'trace'])
+        .default('error'),
+    auditLog: z.boolean().default(true),
+    reasoningLog: z.boolean().default(false),
+    usageLog: z.boolean().default(true),
+})
+    // zod v4 requires .default() to receive a fully-typed value, not `{}`.
+    // We list every field explicitly here; values must match the inner
+    // .default()s above to avoid silently changing defaults.
+    .default({
+    level: 'error',
+    auditLog: true,
+    reasoningLog: false,
+    usageLog: true,
+});
+/**
+ * Bedrock-specific configuration. Only meaningful when `provider = bedrock`;
+ * both keys are optional within that.
+ */
+const BedrockSchema = z
+    .object({
+    region: z.string().optional(),
+    profile: z.string().optional(),
+})
+    .optional();
+export const ConfigSchema = z.object({
+    /** Which remote AI provider to call. */
+    provider: z
+        .enum(['anthropic', 'openai', 'google', 'bedrock'])
+        .default('anthropic'),
+    /** Model identifier passed to the provider. */
+    model: z.string().default('claude-sonnet-4-5-20250929'),
+    /**
+     * Optional override for the env var name that holds the API key.
+     * Ignored when provider = "bedrock" (Bedrock uses the AWS credential chain).
+     */
+    apiKeyEnv: z.string().optional(),
+    /**
+     * Bedrock provider settings (region + profile). Only used when
+     * provider = "bedrock". See providers.ts for fallback chain.
+     */
+    bedrock: BedrockSchema,
+    /**
+     * Default AWS region for AWS CLI commands the agent executes. Used when the
+     * user didn't mention a region in the request and history didn't supply one.
+     * Overridable per-run with --region. Independent of `bedrock.region`.
+     */
+    defaultRegion: z.string().optional(),
+    /** Max reasoning/tool-use steps before the agent must conclude. */
+    maxSteps: z.number().int().min(1).max(50).default(15),
+    /** All logging knobs live here — see LoggingSchema for details. */
+    logging: LoggingSchema,
+    /**
+     * Prompt caching. When true, the system prompt + tool definitions (the
+     * long-lived prefix sent on every step) are marked cacheable for providers
+     * that support it. Cache hits cost ~10% of normal input tokens (Anthropic
+     * direct and Bedrock-via-Anthropic). OpenAI auto-caches large prompts and
+     * ignores this flag. Google Gemini's caching API isn't supported yet —
+     * this flag is silently ignored for that provider. Default true: most
+     * users invoke `aca` more than once every 5 minutes, so the cache pays
+     * for itself quickly; users running it rarely can disable it to avoid
+     * the small cache-write premium on each first call.
+     */
+    caching: z.boolean().default(true),
+    /**
+     * When true, reasoning steps are echoed to stderr in real time. Independent
+     * of `logging.reasoningLog`: you can have file logging on and console echo
+     * off, or vice versa. Overridable per-run with --verbose.
+     */
+    verbose: z.boolean().default(false),
+    /** Auto-approval policy for command/script execution. */
+    autoApprove: z
+        .object({
+        /** Auto-approve read-only AWS commands (describe-*, list-*, get-*, s3 ls). */
+        readOnly: z.boolean().default(true),
+        /** Auto-approve every command and script. Dangerous. */
+        all: z.boolean().default(false),
+    })
+        .default({ readOnly: true, all: false }),
+    /**
+     * When true, every AWS CLI command runs in interactive mode (stdio inherited
+     * from the parent terminal). This is the persistent equivalent of the
+     * `--interactive` / `-i` CLI flag — useful in rare edge cases where the
+     * pattern-based auto-detection misses a command that needs a TTY. Almost
+     * always you want to leave this unset and rely on either the CLI flag for
+     * one-off invocations or the per-tool-call override the agent can set.
+     */
+    forceInteractive: z.boolean().default(false),
+    /** Maximum number of history entries kept in memory. */
+    historyLimit: z.number().int().min(0).default(200),
+    /**
+     * Directory where the user may save generated bash scripts (offered as an
+     * alternative to executing them inline). Defaults to
+     * $XDG_DATA_HOME/aws-cli-agent/scripts.
+     */
+    scriptFolder: z.string().optional(),
+});
+export function loadConfig() {
+    if (!fs.existsSync(FILES.config)) {
+        return ConfigSchema.parse({});
+    }
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(FILES.config, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`Config file at ${FILES.config} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    return ConfigSchema.parse(raw);
+}
+/** Write a default config file if none exists. Returns the path either way. */
+export function writeDefaultConfig() {
+    fs.mkdirSync(PATHS.config, { recursive: true });
+    if (!fs.existsSync(FILES.config)) {
+        const defaults = ConfigSchema.parse({});
+        fs.writeFileSync(FILES.config, JSON.stringify(defaults, null, 2) + '\n');
+    }
+    return FILES.config;
+}

package/dist/history.d.ts

@@ -0,0 +1,34 @@
+export type HistoryEntry = {
+    timestamp: string;
+    input: string;
+    commands: string[];
+    profile: string | null;
+    /**
+     * Resources is currently not used.
+     * Intention: Capture the named resources the agent worked with on each run, keyed by type.
+     * So a history entry for "list buckets in my-account" might end up as:
+     * json{
+     *   "input": "list buckets in my-account",
+     *   "commands": ["aws s3 ls --profile my-account"],
+     *   "profile": "my-account",
+     *   "resources": {
+     *     "account": "my-account"
+     *   }
+     * }
+     */
+    resources: Record<string, string>;
+    success: boolean;
+};
+export declare class History {
+    private entries;
+    private readonly limit;
+    constructor(limit?: number);
+    load(): Promise<void>;
+    append(entry: HistoryEntry): void;
+    /**
+     * Simple token-overlap search across input, commands, profile, and resources.
+     * Returns highest-scoring entries first, newest as tiebreak.
+     */
+    search(query: string, limit?: number): HistoryEntry[];
+    recent(limit?: number): HistoryEntry[];
+}

package/dist/history.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import readline from 'node:readline';
+import { FILES, PATHS } from './paths.js';
+export class History {
+    entries = [];
+    limit;
+    constructor(limit = 200) {
+        this.limit = limit;
+    }
+    async load() {
+        if (!fs.existsSync(FILES.history))
+            return;
+        const lines = [];
+        const rl = readline.createInterface({
+            input: fs.createReadStream(FILES.history),
+            crlfDelay: Infinity,
+        });
+        for await (const line of rl) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                lines.push(JSON.parse(trimmed));
+            }
+            catch {
+                // ignore malformed lines so a corrupt entry doesn't break everything
+            }
+        }
+        this.entries = lines.slice(-this.limit);
+    }
+    append(entry) {
+        fs.mkdirSync(PATHS.state, { recursive: true });
+        fs.appendFileSync(FILES.history, JSON.stringify(entry) + '\n');
+        this.entries.push(entry);
+        if (this.entries.length > this.limit) {
+            this.entries = this.entries.slice(-this.limit);
+        }
+    }
+    /**
+     * Simple token-overlap search across input, commands, profile, and resources.
+     * Returns highest-scoring entries first, newest as tiebreak.
+     */
+    search(query, limit = 10) {
+        const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+        if (tokens.length === 0)
+            return this.recent(limit);
+        const scored = this.entries.map((e, idx) => {
+            const hay = [
+                e.input,
+                ...e.commands,
+                e.profile ?? '',
+                ...Object.values(e.resources),
+            ]
+                .join(' ')
+                .toLowerCase();
+            let score = 0;
+            for (const t of tokens)
+                if (hay.includes(t))
+                    score += 1;
+            return { entry: e, score, idx };
+        });
+        return scored
+            .filter((s) => s.score > 0)
+            .sort((a, b) => b.score - a.score || b.idx - a.idx)
+            .slice(0, limit)
+            .map((s) => s.entry);
+    }
+    recent(limit = 10) {
+        return this.entries.slice(-limit).reverse();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from './cli.js';
+main(process.argv).catch((err) => {
+    process.stderr.write('Fatal: ' + (err instanceof Error ? err.message : String(err)) + '\n');
+    process.exit(1);
+});

package/dist/logger.d.ts

@@ -0,0 +1,29 @@
+declare const LEVELS: readonly ["silent", "error", "warn", "info", "debug", "trace"];
+export type LogLevel = (typeof LEVELS)[number];
+/**
+ * The general operational logger. Writes ONLY to `general.log`. Never echoes
+ * to the console — console output is reserved for:
+ *
+ *   1. The AWS CLI's verbatim stdout (on stdout).
+ *   2. Agent reasoning steps via ReasoningLogger.consoleEcho, gated by the
+ *      `verbose` config / `--verbose` CLI flag (on stderr).
+ *   3. Approval prompts, errors, and the final status line (on stderr,
+ *      written directly by callers in cli.ts and the execute tools).
+ *
+ * Everything operational (agent start, exit codes, debug info, warnings)
+ * goes exclusively to general.log. To watch it live:
+ *   tail -f ~/.local/state/aws-cli-agent/general.log
+ */
+export declare class Logger {
+    private readonly level;
+    private readonly fileStream;
+    constructor(level?: LogLevel);
+    private write;
+    error(msg: string, data?: unknown): void;
+    warn(msg: string, data?: unknown): void;
+    info(msg: string, data?: unknown): void;
+    debug(msg: string, data?: unknown): void;
+    trace(msg: string, data?: unknown): void;
+    close(): void;
+}
+export {};

package/dist/logger.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import { FILES, PATHS } from './paths.js';
+const LEVELS = ['silent', 'error', 'warn', 'info', 'debug', 'trace'];
+function safeStringify(data) {
+    if (typeof data === 'string')
+        return data;
+    try {
+        return JSON.stringify(data, null, 2);
+    }
+    catch {
+        return String(data);
+    }
+}
+/**
+ * The general operational logger. Writes ONLY to `general.log`. Never echoes
+ * to the console — console output is reserved for:
+ *
+ *   1. The AWS CLI's verbatim stdout (on stdout).
+ *   2. Agent reasoning steps via ReasoningLogger.consoleEcho, gated by the
+ *      `verbose` config / `--verbose` CLI flag (on stderr).
+ *   3. Approval prompts, errors, and the final status line (on stderr,
+ *      written directly by callers in cli.ts and the execute tools).
+ *
+ * Everything operational (agent start, exit codes, debug info, warnings)
+ * goes exclusively to general.log. To watch it live:
+ *   tail -f ~/.local/state/aws-cli-agent/general.log
+ */
+export class Logger {
+    level;
+    fileStream;
+    constructor(level = 'error') {
+        this.level = LEVELS.indexOf(level);
+        if (level !== 'silent') {
+            fs.mkdirSync(PATHS.state, { recursive: true });
+            this.fileStream = fs.createWriteStream(FILES.log, { flags: 'a' });
+        }
+        else {
+            this.fileStream = null;
+        }
+    }
+    write(lvl, msg, data) {
+        const lvlIdx = LEVELS.indexOf(lvl);
+        if (lvlIdx === 0 || lvlIdx > this.level)
+            return;
+        const ts = new Date().toISOString();
+        const dataStr = data !== undefined ? ' ' + safeStringify(data) : '';
+        const line = `[${ts}] ${lvl.toUpperCase()} ${msg}${dataStr}\n`;
+        this.fileStream?.write(line);
+    }
+    error(msg, data) {
+        this.write('error', msg, data);
+    }
+    warn(msg, data) {
+        this.write('warn', msg, data);
+    }
+    info(msg, data) {
+        this.write('info', msg, data);
+    }
+    debug(msg, data) {
+        this.write('debug', msg, data);
+    }
+    trace(msg, data) {
+        this.write('trace', msg, data);
+    }
+    close() {
+        this.fileStream?.end();
+    }
+}

package/dist/paths.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Directories aws-cli-agent uses:
+ *
+ *   config — user config (`~/.config/aws-cli-agent`)
+ *   state  — history + logs (`~/.local/state/aws-cli-agent`)
+ *   data   — user-curated artifacts: default location for saved scripts
+ *            (`~/.local/share/aws-cli-agent`). Only created on demand.
+ */
+export declare const PATHS: {
+    readonly config: string;
+    readonly state: string;
+    readonly data: string;
+};
+export declare const FILES: {
+    readonly config: string;
+    readonly history: string;
+    readonly log: string;
+    readonly audit: string;
+    readonly reasoning: string;
+    readonly usage: string;
+};
+/** Default location for user-saved bash scripts. */
+export declare const DEFAULT_SCRIPT_FOLDER: string;

package/dist/paths.js

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import os from 'node:os';
+/**
+ * Resolve an XDG path strictly per the Base Directory Specification.
+ * Falls back to the canonical default if the env var is unset OR empty.
+ * (env-paths is not used here because it diverges from XDG on macOS.)
+ */
+function xdg(envVar, fallback) {
+    const v = process.env[envVar];
+    return v && v.length > 0 ? v : fallback;
+}
+const home = os.homedir();
+const APP = 'aws-cli-agent';
+/**
+ * Directories aws-cli-agent uses:
+ *
+ *   config — user config (`~/.config/aws-cli-agent`)
+ *   state  — history + logs (`~/.local/state/aws-cli-agent`)
+ *   data   — user-curated artifacts: default location for saved scripts
+ *            (`~/.local/share/aws-cli-agent`). Only created on demand.
+ */
+export const PATHS = {
+    config: path.join(xdg('XDG_CONFIG_HOME', path.join(home, '.config')), APP),
+    state: path.join(xdg('XDG_STATE_HOME', path.join(home, '.local', 'state')), APP),
+    data: path.join(xdg('XDG_DATA_HOME', path.join(home, '.local', 'share')), APP),
+};
+export const FILES = {
+    config: path.join(PATHS.config, 'config.json'),
+    history: path.join(PATHS.state, 'history.jsonl'),
+    log: path.join(PATHS.state, 'general.log'),
+    audit: path.join(PATHS.state, 'audit.log'),
+    reasoning: path.join(PATHS.state, 'reasoning.log'),
+    usage: path.join(PATHS.state, 'usage.log'),
+};
+/** Default location for user-saved bash scripts. */
+export const DEFAULT_SCRIPT_FOLDER = path.join(PATHS.data, 'scripts');

package/dist/providers.d.ts

@@ -0,0 +1,16 @@
+import type { LanguageModel } from 'ai';
+import type { Config } from './config.js';
+/**
+ * Build a LanguageModel from config.
+ *
+ * For anthropic / openai / google: API keys are read from environment
+ * variables only — never from the config file — to keep secrets out of disk
+ * state we don't own.
+ *
+ * For bedrock: no API key is needed. Authentication uses the standard AWS
+ * credential chain (env vars, AWS_PROFILE, ~/.aws/credentials, SSO, IMDS,
+ * container roles). Optionally `bedrockProfile` pins a specific named profile,
+ * which is useful when the account hosting Bedrock model access is different
+ * from the accounts the agent operates against.
+ */
+export declare function createModel(config: Config): LanguageModel;

package/dist/providers.js

@@ -0,0 +1,59 @@
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { createAmazonBedrock } from '@ai-sdk/amazon-bedrock';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+const DEFAULT_KEY_ENV = {
+    anthropic: 'ANTHROPIC_API_KEY',
+    openai: 'OPENAI_API_KEY',
+    google: 'GOOGLE_GENERATIVE_AI_API_KEY',
+};
+/**
+ * Build a LanguageModel from config.
+ *
+ * For anthropic / openai / google: API keys are read from environment
+ * variables only — never from the config file — to keep secrets out of disk
+ * state we don't own.
+ *
+ * For bedrock: no API key is needed. Authentication uses the standard AWS
+ * credential chain (env vars, AWS_PROFILE, ~/.aws/credentials, SSO, IMDS,
+ * container roles). Optionally `bedrockProfile` pins a specific named profile,
+ * which is useful when the account hosting Bedrock model access is different
+ * from the accounts the agent operates against.
+ */
+export function createModel(config) {
+    switch (config.provider) {
+        case 'anthropic': {
+            const apiKey = requireKey(config, 'anthropic');
+            return createAnthropic({ apiKey })(config.model);
+        }
+        case 'openai': {
+            const apiKey = requireKey(config, 'openai');
+            return createOpenAI({ apiKey })(config.model);
+        }
+        case 'google': {
+            const apiKey = requireKey(config, 'google');
+            return createGoogleGenerativeAI({ apiKey })(config.model);
+        }
+        case 'bedrock': {
+            const region = config.bedrock?.region ??
+                process.env.AWS_REGION ??
+                process.env.AWS_DEFAULT_REGION;
+            if (!region) {
+                throw new Error('Bedrock requires a region. Set "bedrock.region" in config or AWS_REGION env var.');
+            }
+            const credentialProvider = config.bedrock?.profile
+                ? fromNodeProviderChain({ profile: config.bedrock.profile })
+                : fromNodeProviderChain();
+            return createAmazonBedrock({ region, credentialProvider })(config.model);
+        }
+    }
+}
+function requireKey(config, provider) {
+    const envName = config.apiKeyEnv ?? DEFAULT_KEY_ENV[provider];
+    const apiKey = process.env[envName];
+    if (!apiKey) {
+        throw new Error(`Missing API key. Set environment variable ${envName} (or override "apiKeyEnv" in config).`);
+    }
+    return apiKey;
+}

package/dist/reasoning.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Reasoning log: human-readable record of the agent's per-step reasoning text
+ * and tool selections.
+ *
+ * Design note: in v0.3.0 we switched the agent loop from `generateText` to
+ * `streamText` so that reasoning text chunks arrive in stream order, BEFORE
+ * the model finalizes its tool call. The streaming loop in agent.ts is now
+ * the orchestrator: it decides when to print reasoning (after each step's
+ * text-end event, before the tool-call event). This class is a dumb printer
+ * — no state buffering, no step counter — so the streaming loop has clean
+ * control over ordering.
+ *
+ * The file log (reasoning.log) is written separately at the end of each
+ * step with the full text + tool calls in one block.
+ */
+export declare class ReasoningLogger {
+    private readonly stream;
+    private readonly consoleEcho;
+    constructor(opts: {
+        enabled: boolean;
+        consoleEcho: boolean;
+    });
+    /** Whether the agent should call the echo* methods at all. Lets the
+     * streaming loop skip work when verbose is off. */
+    get echoEnabled(): boolean;
+    /** Mark the start of a new agent run with the user's input. */
+    beginRun(input: string): void;
+    /**
+     * Echo a step's reasoning text to the console. Called by the streaming
+     * loop AFTER the model's text stream ends for that step, BEFORE the
+     * tool-call event for that same step. The reasoning therefore appears
+     * above its associated tool call line — and above any approval prompt
+     * the tool's execute() might display.
+     */
+    echoReasoning(step: number, text: string): void;
+    /**
+     * Echo a step's tool call line to the console. Called by the streaming
+     * loop on the tool-call event, AFTER any reasoning for that step has
+     * been echoed, BEFORE the SDK invokes the tool's execute() function.
+     */
+    echoToolCall(step: number, toolName: string, toolInput: unknown): void;
+    /**
+     * Append a completed step to the reasoning file. Called by the streaming
+     * loop on the finish-step event. Ordering doesn't matter for the file —
+     * it's append-only and read post-hoc — so we batch the whole step's
+     * data into one block here.
+     */
+    logStepToFile(args: {
+        step: number;
+        reasoning: string;
+        toolCalls: Array<{
+            toolName: string;
+            args: unknown;
+        }>;
+        finishReason?: string;
+    }): void;
+    private writeFile;
+    close(): void;
+}

package/dist/reasoning.js

@@ -0,0 +1,125 @@
+import fs from 'node:fs';
+import chalk from 'chalk';
+import { FILES, PATHS } from './paths.js';
+/**
+ * Reasoning log: human-readable record of the agent's per-step reasoning text
+ * and tool selections.
+ *
+ * Design note: in v0.3.0 we switched the agent loop from `generateText` to
+ * `streamText` so that reasoning text chunks arrive in stream order, BEFORE
+ * the model finalizes its tool call. The streaming loop in agent.ts is now
+ * the orchestrator: it decides when to print reasoning (after each step's
+ * text-end event, before the tool-call event). This class is a dumb printer
+ * — no state buffering, no step counter — so the streaming loop has clean
+ * control over ordering.
+ *
+ * The file log (reasoning.log) is written separately at the end of each
+ * step with the full text + tool calls in one block.
+ */
+export class ReasoningLogger {
+    stream;
+    consoleEcho;
+    constructor(opts) {
+        this.consoleEcho = opts.consoleEcho;
+        if (!opts.enabled) {
+            this.stream = null;
+            return;
+        }
+        fs.mkdirSync(PATHS.state, { recursive: true });
+        this.stream = fs.createWriteStream(FILES.reasoning, { flags: 'a' });
+    }
+    /** Whether the agent should call the echo* methods at all. Lets the
+     * streaming loop skip work when verbose is off. */
+    get echoEnabled() {
+        return this.consoleEcho;
+    }
+    /** Mark the start of a new agent run with the user's input. */
+    beginRun(input) {
+        const ts = new Date().toISOString();
+        const block = `\n========== run @ ${ts} ==========\n` +
+            `input: ${input}\n`;
+        this.writeFile(block);
+        // Don't echo the run header to console — already visible from the prompt.
+    }
+    /**
+     * Echo a step's reasoning text to the console. Called by the streaming
+     * loop AFTER the model's text stream ends for that step, BEFORE the
+     * tool-call event for that same step. The reasoning therefore appears
+     * above its associated tool call line — and above any approval prompt
+     * the tool's execute() might display.
+     */
+    echoReasoning(step, text) {
+        if (!this.consoleEcho)
+            return;
+        if (text.trim().length === 0)
+            return;
+        process.stderr.write(chalk.dim(`[${pad2(step)}] `) + text.trim() + '\n');
+    }
+    /**
+     * Echo a step's tool call line to the console. Called by the streaming
+     * loop on the tool-call event, AFTER any reasoning for that step has
+     * been echoed, BEFORE the SDK invokes the tool's execute() function.
+     */
+    echoToolCall(step, toolName, toolInput) {
+        if (!this.consoleEcho)
+            return;
+        const argStr = safeStringify(toolInput, 120);
+        process.stderr.write(chalk.dim(`[${pad2(step)}] `) + `tool: ${toolName}(${argStr})\n`);
+    }
+    /**
+     * Append a completed step to the reasoning file. Called by the streaming
+     * loop on the finish-step event. Ordering doesn't matter for the file —
+     * it's append-only and read post-hoc — so we batch the whole step's
+     * data into one block here.
+     */
+    logStepToFile(args) {
+        const ts = new Date().toISOString();
+        const lines = [];
+        lines.push(`[${ts}] step ${pad2(args.step)} (finish=${args.finishReason ?? 'n/a'})`);
+        if (args.reasoning.trim().length > 0) {
+            for (const l of args.reasoning.trim().split('\n')) {
+                lines.push(`  reasoning: ${l}`);
+            }
+        }
+        for (const call of args.toolCalls) {
+            const argStr = safeStringify(call.args, 200);
+            lines.push(`  tool_call: ${call.toolName}(${argStr})`);
+        }
+        const block = lines.join('\n') + '\n';
+        this.writeFile(block);
+    }
+    writeFile(text) {
+        if (!this.stream)
+            return;
+        try {
+            this.stream.write(text);
+        }
+        catch {
+            // Same philosophy as audit: never crash the agent on log failure.
+        }
+    }
+    close() {
+        this.stream?.end();
+    }
+}
+function safeStringify(v, limit) {
+    let s;
+    try {
+        s = JSON.stringify(v);
+    }
+    catch {
+        s = String(v);
+    }
+    if (s.length <= limit)
+        return s;
+    return s.slice(0, limit) + '…';
+}
+/**
+ * Format an integer as a 2-digit zero-padded string. Used so step labels
+ * line up visually: "step 01" through "step 09" align with "step 10" and
+ * beyond. For numbers ≥ 100 the value is emitted as-is (we don't truncate),
+ * so a runaway 150-step run is still readable, just unaligned.
+ */
+function pad2(n) {
+    return n.toString().padStart(2, '0');
+}