aws-cli-agent 0.4.0

package/dist/tools/aws-cli.d.ts

@@ -0,0 +1,48 @@
+import type { Logger } from '../logger.js';
+import type { Config } from '../config.js';
+export declare function awsCliTool(opts: {
+    logger: Logger;
+    config: Config;
+    audit: import('../audit.js').AuditLogger;
+    record: (entry: import('./index.js').ExecutionRecord) => void;
+}): import("ai").Tool<{
+    args: string[];
+    purpose: string;
+    interactive?: boolean | undefined;
+}, {
+    ok: boolean;
+    declined: boolean;
+    error: string;
+    exitCode?: undefined;
+    interactive?: undefined;
+    note?: undefined;
+    stdout?: undefined;
+    stderr?: undefined;
+} | {
+    ok: boolean;
+    exitCode: number;
+    interactive: boolean;
+    note: string;
+    declined?: undefined;
+    error?: undefined;
+    stdout?: undefined;
+    stderr?: undefined;
+} | {
+    ok: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    declined?: undefined;
+    error?: undefined;
+    interactive?: undefined;
+    note?: undefined;
+} | {
+    ok: boolean;
+    error: string;
+    declined?: undefined;
+    exitCode?: undefined;
+    interactive?: undefined;
+    note?: undefined;
+    stdout?: undefined;
+    stderr?: undefined;
+}>;

package/dist/tools/aws-cli.js

@@ -0,0 +1,279 @@
+import { spawn } from 'node:child_process';
+import { tool } from 'ai';
+import { z } from 'zod';
+import { confirm } from '@inquirer/prompts';
+import chalk from 'chalk';
+const READ_ONLY_VERBS = [
+    /^describe-/,
+    /^list-/,
+    /^get-/,
+    /^lookup-/,
+    /^batch-get-/,
+    /^head-/,
+    /^filter-/,
+    /^scan$/,
+    /^query$/,
+];
+const READ_ONLY_FULL = [
+    /^s3\s+ls(\s|$)/,
+];
+/**
+ * Commands that need direct terminal access — either because they open a TTY
+ * (interactive shells), bind a local port and wait for connections, or stream
+ * indefinitely until the user interrupts. For these we connect the child's
+ * stdio to the parent's terminal instead of capturing stdout/stderr into
+ * strings. The agent doesn't get to "see" the output, which is correct:
+ * data flow is user ↔ AWS, not user ↔ agent ↔ AWS.
+ *
+ * If a command should be interactive but isn't listed here, the user can
+ * force it with the `--interactive` / `-i` CLI flag or the agent can set
+ * `interactive: true` in the tool call.
+ */
+const INTERACTIVE_FULL = [
+    // SSM Session Manager — opens a shell or a port-forward listener. Both
+    // need stdio inheritance: the shell case needs stdin connected, the
+    // port-forward case needs to print "Waiting for connections" and survive.
+    /^ssm\s+start-session(\s|$)/,
+    // CloudShell — interactive shell in AWS console replica.
+    /^cloudshell\s+(start|connect)(-.*|\s|$)/,
+    // ECS Exec — runs a command inside a container, often a shell.
+    /^ecs\s+execute-command(\s|$)/,
+    // EKS exec via aws — wraps kubectl exec for cluster pods.
+    /^eks\s+(exec|kubeconfig)(\s|$)/,
+    // CloudWatch Logs tail with --follow runs until Ctrl-C.
+    /^logs\s+tail(\s|$).*--follow/,
+];
+function isReadOnly(args) {
+    const joined = args.join(' ');
+    if (READ_ONLY_FULL.some((re) => re.test(joined)))
+        return true;
+    const verb = args[1];
+    if (verb && READ_ONLY_VERBS.some((re) => re.test(verb)))
+        return true;
+    return false;
+}
+function isInteractive(args) {
+    const joined = args.join(' ');
+    return INTERACTIVE_FULL.some((re) => re.test(joined));
+}
+function shellQuote(arg) {
+    if (/^[a-zA-Z0-9_\-/.=:]+$/.test(arg))
+        return arg;
+    return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+function extractProfile(args) {
+    const i = args.indexOf('--profile');
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : null;
+}
+function hasRegion(args) {
+    return args.includes('--region');
+}
+// Default cap is generous because list/describe output for a real AWS account
+// can easily exceed 50 KB (hundreds of buckets, dozens of instances with full
+// describe-instances JSON). The model needs the full data to surface it to the
+// user. If you hit memory pressure, lower this — but the model's own context
+// window is the real limiter.
+function truncate(s, max = 200_000) {
+    return s.length <= max ? s : s.slice(0, max) + `\n... [truncated ${s.length - max} bytes]`;
+}
+/**
+ * Run aws CLI with stdout/stderr captured into strings. Right for discovery
+ * calls where the agent (and the host program) need to read the output.
+ */
+function runCaptured(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(cmd, args, { env: process.env });
+        let stdout = '';
+        let stderr = '';
+        proc.stdout.on('data', (c) => {
+            stdout += c.toString();
+        });
+        proc.stderr.on('data', (c) => {
+            stderr += c.toString();
+        });
+        proc.on('error', reject);
+        proc.on('close', (code) => resolve({ stdout, stderr, code: code ?? 0 }));
+    });
+}
+/**
+ * Run aws CLI with the child's stdio connected directly to the parent's
+ * terminal. Used for interactive sessions (ssm start-session shells),
+ * commands that bind local ports and wait (ssm port-forwarding sessions),
+ * and long-running streams (logs tail --follow).
+ *
+ * Returns no stdout/stderr — the bytes went straight to the user's terminal
+ * and we never see them. This is correct: data flow is user ↔ AWS, not
+ * user ↔ agent ↔ AWS.
+ */
+function runInteractive(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(cmd, args, {
+            env: process.env,
+            stdio: 'inherit', // ← the fix: child reuses parent's stdin/stdout/stderr
+        });
+        proc.on('error', reject);
+        proc.on('close', (code) => 
+        // We can't observe stdout/stderr — they went to the user's terminal.
+        resolve({ stdout: '', stderr: '', code: code ?? 0 }));
+    });
+}
+export function awsCliTool(opts) {
+    return tool({
+        description: 'Execute an AWS CLI command. `args` does NOT include the leading "aws" - just the subcommand and parameters, e.g. ["ec2","describe-instances","--profile","my-profile","--output","json"]. ALWAYS use --output json on discovery calls so you can parse results. Read-only commands (describe-/list-/get-/s3 ls) auto-approve if allowed by config; mutating commands always prompt. ' +
+            'Set `interactive: true` for commands that need direct terminal access — interactive shells (ssm start-session, ecs execute-command), port-forwarding sessions, log tails with --follow. Common interactive patterns auto-detect, but you can force it. When interactive, the child process is connected directly to the user\'s terminal; you will not see the output and should not attempt to parse it.',
+        inputSchema: z.object({
+            args: z.array(z.string()).min(1).describe('Arguments after the "aws" binary.'),
+            purpose: z
+                .string()
+                .describe('Brief explanation of why this call is being made (shown to the user).'),
+            interactive: z
+                .boolean()
+                .optional()
+                .describe('Force interactive mode (inherit terminal stdio). Use for shells, port-forwards, and long-running streams. ' +
+                'If unset, the host auto-detects common patterns (ssm start-session, ecs execute-command, logs tail --follow, etc.).'),
+        }),
+        execute: async ({ args, purpose, interactive }) => {
+            // Inject defaultRegion if the agent didn't pass --region.
+            let effectiveArgs = args;
+            if (!hasRegion(args) && opts.config.defaultRegion) {
+                effectiveArgs = [...args, '--region', opts.config.defaultRegion];
+            }
+            const display = 'aws ' + effectiveArgs.map(shellQuote).join(' ');
+            opts.logger.info(`AWS CLI requested: ${purpose}`);
+            opts.logger.debug('Command', display);
+            // Decide interactive mode. Priority: explicit override on the tool
+            // call > CLI flag (via config.forceInteractive) > pattern detection.
+            // The CLI flag is the user's escape hatch for cases not in our
+            // INTERACTIVE_FULL list.
+            const useInteractive = interactive === true ||
+                opts.config.forceInteractive === true ||
+                isInteractive(effectiveArgs);
+            const readOnly = isReadOnly(effectiveArgs);
+            // Interactive commands are never auto-approved. The user is about to
+            // hand their terminal over to a subprocess — that always warrants a
+            // confirmation, regardless of autoApprove settings.
+            const autoApprove = !useInteractive &&
+                (opts.config.autoApprove.all || (opts.config.autoApprove.readOnly && readOnly));
+            // Extract profile up-front so the declined-branch audit/record
+            // entries can include it. extractProfile just scans args, no I/O.
+            const profile = extractProfile(effectiveArgs);
+            if (!autoApprove) {
+                process.stderr.write('\n');
+                process.stderr.write(`${chalk.bold('  Reason:  ')}${purpose}\n`);
+                process.stderr.write(`${chalk.bold('  Command: ')}${chalk.green(display)}\n`);
+                if (useInteractive) {
+                    process.stderr.write(`${chalk.bold('  Mode:    ')}${chalk.yellow('interactive')} (your terminal will be connected to the command)\n`);
+                }
+                const ok = await confirm({ message: 'Execute this command?', default: true });
+                if (!ok) {
+                    opts.logger.warn('User declined command');
+                    // Record the declined call so the agent's end-of-run logic sees
+                    // that the last action was a refusal, not the most recent
+                    // successful intermediate call. Without this, cli.ts would print
+                    // the stdout of an earlier describe/list call as if it were the
+                    // final answer — confusing the user with scaffolding output.
+                    // Audit log gets a separate marker for the same reason: clear
+                    // trail of "user said no" rather than absence-of-record.
+                    opts.audit.logCommand({
+                        cmd: display,
+                        profile,
+                        exitCode: -1,
+                        ok: false,
+                        stdout: '',
+                        stderr: '[declined by user]',
+                    });
+                    opts.record({
+                        cmd: display,
+                        profile,
+                        stdout: '',
+                        stderr: '[declined by user]',
+                        exitCode: -1,
+                        ok: false,
+                    });
+                    return { ok: false, declined: true, error: 'User declined to execute this command.' };
+                }
+            }
+            else {
+                opts.logger.debug(`Auto-approved (${readOnly ? 'read-only' : 'all'})`);
+            }
+            try {
+                const { stdout, stderr, code } = useInteractive
+                    ? await runInteractive('aws', effectiveArgs)
+                    : await runCaptured('aws', effectiveArgs);
+                opts.logger.debug('Exit code', code);
+                if (!useInteractive) {
+                    opts.logger.trace('stdout', stdout);
+                    if (code !== 0) {
+                        opts.logger.warn(`AWS CLI failed (exit ${code})`);
+                        opts.logger.trace('stderr', stderr);
+                    }
+                }
+                else if (code !== 0) {
+                    opts.logger.warn(`Interactive AWS CLI exited non-zero (${code})`);
+                }
+                // Audit captures whatever we have. For interactive runs stdout/stderr
+                // are empty — that's accurate, the bytes went to the terminal — and
+                // the audit entry serves as a record that "an interactive session
+                // ran" rather than a transcript of what happened in it.
+                opts.audit.logCommand({
+                    cmd: display,
+                    profile,
+                    exitCode: code,
+                    ok: code === 0,
+                    stdout: useInteractive ? '[interactive session — output not captured]' : stdout,
+                    stderr: useInteractive ? '' : stderr,
+                });
+                opts.record({
+                    cmd: display,
+                    profile,
+                    // For interactive runs, give the host CLI a one-line summary to
+                    // emit instead of empty output. Users finishing an SSM session see
+                    // their shell ouptut as it happens; this just confirms it ended.
+                    stdout: useInteractive
+                        ? `[interactive session ended, exit ${code}]\n`
+                        : stdout,
+                    stderr: useInteractive ? '' : stderr,
+                    exitCode: code,
+                    ok: code === 0,
+                });
+                // For the agent's context, return a clear signal that interactive
+                // mode ran so it doesn't try to parse fictional stdout.
+                if (useInteractive) {
+                    return {
+                        ok: code === 0,
+                        exitCode: code,
+                        interactive: true,
+                        note: 'Interactive session ran. Output went directly to the user\'s terminal and was not captured. Do not summarize or describe its contents.',
+                    };
+                }
+                return {
+                    ok: code === 0,
+                    exitCode: code,
+                    stdout: truncate(stdout),
+                    stderr: truncate(stderr),
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                opts.logger.error('Failed to spawn aws CLI', msg);
+                opts.audit.logCommand({
+                    cmd: display,
+                    profile,
+                    exitCode: -1,
+                    ok: false,
+                    stdout: '',
+                    stderr: msg,
+                });
+                opts.record({
+                    cmd: display,
+                    profile,
+                    stdout: '',
+                    stderr: msg,
+                    exitCode: -1,
+                    ok: false,
+                });
+                return { ok: false, error: msg };
+            }
+        },
+    });
+}

package/dist/tools/bash.d.ts

@@ -0,0 +1,47 @@
+import type { Logger } from '../logger.js';
+import type { Config } from '../config.js';
+export declare function bashScriptTool(opts: {
+    logger: Logger;
+    config: Config;
+    audit: import('../audit.js').AuditLogger;
+    record: (entry: import('./index.js').ExecutionRecord) => void;
+}): import("ai").Tool<{
+    script: string;
+    purpose: string;
+}, {
+    ok: boolean;
+    declined: boolean;
+    error: string;
+    saved?: undefined;
+    path?: undefined;
+    stdout?: undefined;
+    exitCode?: undefined;
+    stderr?: undefined;
+} | {
+    ok: boolean;
+    error: string;
+    declined?: undefined;
+    saved?: undefined;
+    path?: undefined;
+    stdout?: undefined;
+    exitCode?: undefined;
+    stderr?: undefined;
+} | {
+    ok: boolean;
+    saved: boolean;
+    path: string;
+    stdout: string;
+    declined?: undefined;
+    error?: undefined;
+    exitCode?: undefined;
+    stderr?: undefined;
+} | {
+    ok: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    declined?: undefined;
+    error?: undefined;
+    saved?: undefined;
+    path?: undefined;
+}>;

package/dist/tools/bash.js

@@ -0,0 +1,197 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { tool } from 'ai';
+import { z } from 'zod';
+import { select } from '@inquirer/prompts';
+import chalk from 'chalk';
+import { DEFAULT_SCRIPT_FOLDER } from '../paths.js';
+function runProcess(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(cmd, args, { env: process.env });
+        let stdout = '';
+        let stderr = '';
+        proc.stdout.on('data', (c) => {
+            stdout += c.toString();
+        });
+        proc.stderr.on('data', (c) => {
+            stderr += c.toString();
+        });
+        proc.on('error', reject);
+        proc.on('close', (code) => resolve({ stdout, stderr, code: code ?? 0 }));
+    });
+}
+function truncate(s, max = 200_000) {
+    return s.length <= max ? s : s.slice(0, max) + `\n... [truncated]`;
+}
+function indent(s, prefix) {
+    return s
+        .split('\n')
+        .map((l) => prefix + l)
+        .join('\n');
+}
+/**
+ * Compute a filesystem-friendly filename for a saved script.
+ * Combines a timestamp (so files sort chronologically) with a short slug
+ * derived from the purpose (so a directory listing is humanly scannable).
+ */
+function scriptFileName(purpose) {
+    const slug = purpose
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40) || 'script';
+    const ts = new Date()
+        .toISOString()
+        .replace(/[:.]/g, '-')
+        .replace(/T/, '_')
+        .slice(0, 19);
+    return `${ts}_${slug}.sh`;
+}
+export function bashScriptTool(opts) {
+    return tool({
+        description: 'Execute a bash script. Use this for multi-step / multi-account workflows that need looping, jq filtering, or composition (e.g. "list all RDS Aurora databases in all accounts of org X"). The user is prompted to (a) execute the script now, (b) save it to disk for later review or scheduled execution, or (c) cancel. Always start scripts with `set -euo pipefail`.',
+        inputSchema: z.object({
+            script: z.string().min(1).describe('Full bash script source.'),
+            purpose: z.string().describe('What this script accomplishes.'),
+        }),
+        execute: async ({ script, purpose }) => {
+            opts.logger.info(`Bash script requested: ${purpose}`);
+            opts.logger.debug('Script', script);
+            // Show what would run so the user can make an informed choice.
+            process.stderr.write('\n');
+            process.stderr.write(`${chalk.bold('  Reason: ')}${purpose}\n`);
+            process.stderr.write(`${chalk.bold('  Script:')}\n`);
+            process.stderr.write(chalk.green(indent(script, '    ')) + '\n');
+            // The save-to-disk option respects the configured folder, or falls back
+            // to the XDG default. Compute the would-be path *before* prompting so
+            // the user can see exactly where it'll land.
+            const scriptFolder = opts.config.scriptFolder ?? DEFAULT_SCRIPT_FOLDER;
+            const savePath = path.join(scriptFolder, scriptFileName(purpose));
+            // Scripts always go through the three-way prompt regardless of
+            // autoApprove. Scripts are arbitrary code with shell-level capability
+            // — auto-approving them would defeat a primary safety boundary. The
+            // autoApprove flag remains in effect for individual aws CLI commands
+            // (where read-only is a meaningful and enforceable category).
+            const action = await select({
+                message: 'What would you like to do with this script?',
+                choices: [
+                    { value: 'execute', name: 'Execute now' },
+                    { value: 'save', name: `Save to disk (${savePath})` },
+                    { value: 'cancel', name: 'Cancel' },
+                ],
+                default: 'execute',
+            });
+            if (action === 'cancel') {
+                opts.logger.warn('User cancelled script');
+                // Record the cancelled call so the agent's end-of-run logic sees
+                // refusal as the final action, not an earlier successful step.
+                // See the parallel comment in aws-cli.ts for the reasoning.
+                const cmdLabel = `[bash script: ${purpose}]`;
+                opts.audit.logCommand({
+                    cmd: cmdLabel,
+                    profile: null,
+                    exitCode: -1,
+                    ok: false,
+                    stdout: '',
+                    stderr: '[cancelled by user]',
+                });
+                opts.record({
+                    cmd: cmdLabel,
+                    profile: null,
+                    stdout: '',
+                    stderr: '[cancelled by user]',
+                    exitCode: -1,
+                    ok: false,
+                });
+                return {
+                    ok: false,
+                    declined: true,
+                    error: 'User cancelled. No script was executed or saved.',
+                };
+            }
+            if (action === 'save') {
+                try {
+                    fs.mkdirSync(scriptFolder, { recursive: true });
+                    fs.writeFileSync(savePath, script, { mode: 0o700 });
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    opts.logger.error('Failed to save script', msg);
+                    return { ok: false, error: `Failed to save script: ${msg}` };
+                }
+                opts.logger.info(`Script saved to ${savePath}`);
+                // Still audit the save action so the trail is complete. exitCode=0
+                // is honest here: the user-visible action succeeded.
+                opts.audit.logScript({
+                    cmd: `saved ${savePath}`,
+                    profile: null,
+                    exitCode: 0,
+                    ok: true,
+                    stdout: '',
+                    stderr: '',
+                    script,
+                });
+                // Record so the CLI can print a confirmation in place of stdout —
+                // the script wasn't run, so there's no real stdout to forward.
+                opts.record({
+                    cmd: `saved ${savePath}`,
+                    profile: null,
+                    stdout: `Script saved to ${savePath}\n`,
+                    stderr: '',
+                    exitCode: 0,
+                    ok: true,
+                });
+                return {
+                    ok: true,
+                    saved: true,
+                    path: savePath,
+                    stdout: `Script saved to ${savePath}`,
+                };
+            }
+            // action === 'execute' — same path as before.
+            const tmp = path.join(os.tmpdir(), `aws-cli-agent-${Date.now()}-${process.pid}.sh`);
+            fs.writeFileSync(tmp, script, { mode: 0o700 });
+            const cmdLabel = `bash ${tmp}`;
+            try {
+                const { stdout, stderr, code } = await runProcess('bash', [tmp]);
+                opts.logger.debug('Script exit code', code);
+                opts.logger.trace('stdout', stdout);
+                if (code !== 0)
+                    opts.logger.trace('stderr', stderr);
+                opts.audit.logScript({
+                    cmd: cmdLabel,
+                    profile: null,
+                    exitCode: code,
+                    ok: code === 0,
+                    stdout,
+                    stderr,
+                    script,
+                });
+                opts.record({
+                    cmd: cmdLabel,
+                    profile: null,
+                    stdout,
+                    stderr,
+                    exitCode: code,
+                    ok: code === 0,
+                });
+                return {
+                    ok: code === 0,
+                    exitCode: code,
+                    stdout: truncate(stdout),
+                    stderr: truncate(stderr),
+                };
+            }
+            finally {
+                try {
+                    fs.unlinkSync(tmp);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        },
+    });
+}

package/dist/tools/history.d.ts

@@ -0,0 +1,18 @@
+import type { History } from '../history.js';
+import type { Logger } from '../logger.js';
+export declare function historyTool(opts: {
+    history: History;
+    logger: Logger;
+}): import("ai").Tool<{
+    query: string;
+    limit: number;
+}, {
+    count: number;
+    entries: {
+        timestamp: string;
+        input: string;
+        commands: string[];
+        profile: string | null;
+        resources: Record<string, string>;
+    }[];
+}>;

package/dist/tools/history.js

@@ -0,0 +1,27 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+export function historyTool(opts) {
+    return tool({
+        description: 'Search the local history of past requests/commands to recover context — e.g. which AWS profile was used for a given account name, common bucket/instance names, etc. Run this EARLY (typically first) when a request mentions an account, resource, or scope by name.',
+        inputSchema: z.object({
+            query: z
+                .string()
+                .describe('Search tokens. Matched against past input, commands, profile, and resources.'),
+            limit: z.number().int().min(1).max(20).default(5),
+        }),
+        execute: async ({ query, limit }) => {
+            opts.logger.debug('History search', { query, limit });
+            const results = opts.history.search(query, limit);
+            return {
+                count: results.length,
+                entries: results.map((e) => ({
+                    timestamp: e.timestamp,
+                    input: e.input,
+                    commands: e.commands,
+                    profile: e.profile,
+                    resources: e.resources,
+                })),
+            };
+        },
+    });
+}