aws-cli-agent 0.4.0

package/dist/tools/index.d.ts

@@ -0,0 +1,157 @@
+import type { Logger } from '../logger.js';
+import type { Config } from '../config.js';
+import type { History } from '../history.js';
+import type { AuditLogger } from '../audit.js';
+export type ExecutionRecord = {
+    cmd: string;
+    profile: string | null;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    ok: boolean;
+};
+export type ToolContext = {
+    logger: Logger;
+    config: Config;
+    history: History;
+    audit: AuditLogger;
+    record: (entry: ExecutionRecord) => void;
+};
+/**
+ * Build the agent's tool set.
+ *
+ * Note on caching: there is no per-tool cache marker here. We previously
+ * marked the last tool with `providerOptions.{anthropic.cacheControl,
+ * bedrock.cachePoint}` hoping the SDK would translate that into a cache
+ * breakpoint after the tools section of the request body. Investigation of
+ * `@ai-sdk/amazon-bedrock` v4 showed it only reads `name`, `description`,
+ * `strict`, and `inputSchema` when serializing function tools — it ignores
+ * `providerOptions`, so the marker had no effect. Confirmed via trace logs:
+ * `cacheDetails` always had one entry (the system message), never two.
+ *
+ * So the prompt cache currently captures only the system message. The
+ * tools array is re-sent at full cost on every request. If/when the SDK
+ * starts propagating tool-level providerOptions to cachePoints, the right
+ * place to add markers is on the last entry in this object — Anthropic
+ * recommends a single breakpoint at the end of the tools block.
+ */
+export declare function createTools(ctx: ToolContext): {
+    query_history: import("ai").Tool<{
+        query: string;
+        limit: number;
+    }, {
+        count: number;
+        entries: {
+            timestamp: string;
+            input: string;
+            commands: string[];
+            profile: string | null;
+            resources: Record<string, string>;
+        }[];
+    }>;
+    list_aws_profiles: import("ai").Tool<Record<string, never>, {
+        profiles: string[];
+        count: number;
+    }>;
+    prompt_user: import("ai").Tool<{
+        kind: "text" | "choice" | "confirm" | "secret";
+        message: string;
+        key?: string | undefined;
+        choices?: string[] | undefined;
+        defaultValue?: string | undefined;
+    }, {
+        answer: string;
+    }>;
+    prompt_user_multi: import("ai").Tool<{
+        questions: {
+            kind: "text" | "choice" | "confirm" | "secret";
+            message: string;
+            key?: string | undefined;
+            choices?: string[] | undefined;
+            defaultValue?: string | undefined;
+        }[];
+    }, {
+        answers: Record<string, string>;
+    }>;
+    execute_aws_command: 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;
+    }>;
+    execute_bash_script: 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/index.js

@@ -0,0 +1,43 @@
+import { awsCliTool } from './aws-cli.js';
+import { bashScriptTool } from './bash.js';
+import { listProfilesTool } from './profiles.js';
+import { historyTool } from './history.js';
+import { promptUserTool, promptUserMultiTool } from './prompt.js';
+/**
+ * Build the agent's tool set.
+ *
+ * Note on caching: there is no per-tool cache marker here. We previously
+ * marked the last tool with `providerOptions.{anthropic.cacheControl,
+ * bedrock.cachePoint}` hoping the SDK would translate that into a cache
+ * breakpoint after the tools section of the request body. Investigation of
+ * `@ai-sdk/amazon-bedrock` v4 showed it only reads `name`, `description`,
+ * `strict`, and `inputSchema` when serializing function tools — it ignores
+ * `providerOptions`, so the marker had no effect. Confirmed via trace logs:
+ * `cacheDetails` always had one entry (the system message), never two.
+ *
+ * So the prompt cache currently captures only the system message. The
+ * tools array is re-sent at full cost on every request. If/when the SDK
+ * starts propagating tool-level providerOptions to cachePoints, the right
+ * place to add markers is on the last entry in this object — Anthropic
+ * recommends a single breakpoint at the end of the tools block.
+ */
+export function createTools(ctx) {
+    return {
+        query_history: historyTool({ history: ctx.history, logger: ctx.logger }),
+        list_aws_profiles: listProfilesTool({ logger: ctx.logger }),
+        prompt_user: promptUserTool({ logger: ctx.logger }),
+        prompt_user_multi: promptUserMultiTool({ logger: ctx.logger }),
+        execute_aws_command: awsCliTool({
+            logger: ctx.logger,
+            config: ctx.config,
+            audit: ctx.audit,
+            record: ctx.record,
+        }),
+        execute_bash_script: bashScriptTool({
+            logger: ctx.logger,
+            config: ctx.config,
+            audit: ctx.audit,
+            record: ctx.record,
+        }),
+    };
+}

package/dist/tools/profiles.d.ts

@@ -0,0 +1,7 @@
+import type { Logger } from '../logger.js';
+export declare function listProfilesTool(opts: {
+    logger: Logger;
+}): import("ai").Tool<Record<string, never>, {
+    profiles: string[];
+    count: number;
+}>;

package/dist/tools/profiles.js

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { tool } from 'ai';
+import { z } from 'zod';
+export function listProfilesTool(opts) {
+    return tool({
+        description: 'List AWS named profiles configured locally in ~/.aws/config and ~/.aws/credentials. Use this when the user references an account by name and history did not resolve it.',
+        inputSchema: z.object({}),
+        execute: async () => {
+            opts.logger.debug('Listing AWS profiles');
+            const profiles = new Set();
+            const files = [
+                path.join(os.homedir(), '.aws', 'config'),
+                path.join(os.homedir(), '.aws', 'credentials'),
+            ];
+            for (const f of files) {
+                if (!fs.existsSync(f))
+                    continue;
+                const content = fs.readFileSync(f, 'utf8');
+                // [profile foo] in config, [foo] in credentials
+                const re = /^\s*\[(?:profile\s+)?([^\]]+)\]/gm;
+                let m;
+                while ((m = re.exec(content)) !== null) {
+                    const name = m[1].trim();
+                    if (name && name !== 'default')
+                        profiles.add(name);
+                    if (name === 'default')
+                        profiles.add('default');
+                }
+            }
+            const result = Array.from(profiles).sort();
+            opts.logger.trace('Profiles found', result);
+            return { profiles: result, count: result.length };
+        },
+    });
+}

package/dist/tools/prompt.d.ts

@@ -0,0 +1,37 @@
+import type { Logger } from '../logger.js';
+/**
+ * Single-question prompt. The agent calls this whenever a required parameter
+ * cannot be inferred from history or discovered via the AWS CLI. Strong
+ * preference for kind="choice" when the candidate set is enumerable —
+ * picking from a list is faster and less error-prone than typing.
+ */
+export declare function promptUserTool(opts: {
+    logger: Logger;
+}): import("ai").Tool<{
+    kind: "text" | "choice" | "confirm" | "secret";
+    message: string;
+    key?: string | undefined;
+    choices?: string[] | undefined;
+    defaultValue?: string | undefined;
+}, {
+    answer: string;
+}>;
+/**
+ * Multi-question prompt. Ask several related questions in one tool call —
+ * cuts model round-trips when the agent already knows it needs N pieces of
+ * info (e.g. "I need a source bucket, a destination bucket, and a region").
+ * Each question's `key` becomes the field name in the returned object.
+ */
+export declare function promptUserMultiTool(opts: {
+    logger: Logger;
+}): import("ai").Tool<{
+    questions: {
+        kind: "text" | "choice" | "confirm" | "secret";
+        message: string;
+        key?: string | undefined;
+        choices?: string[] | undefined;
+        defaultValue?: string | undefined;
+    }[];
+}, {
+    answers: Record<string, string>;
+}>;

package/dist/tools/prompt.js

@@ -0,0 +1,145 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { confirm, input, password, select } from '@inquirer/prompts';
+import chalk from 'chalk';
+/**
+ * Schema for a single question. Used both by `prompt_user` directly (single
+ * question per call) and `prompt_user_multi` (batch of questions in one call).
+ *
+ * `kind` is explicit so the model picks the right UI control instead of
+ * inferring it from prose. The default `text` keeps simple uses simple.
+ */
+const QuestionSchema = z.object({
+    /** Optional key — only used by prompt_user_multi to label answers. */
+    key: z
+        .string()
+        .optional()
+        .describe('Identifier for this question in the returned answers object. Required for prompt_user_multi.'),
+    kind: z
+        .enum(['text', 'choice', 'confirm', 'secret'])
+        .default('text')
+        .describe('choice = pick one of `choices` (best for finite sets like profiles or buckets). ' +
+        'confirm = yes/no decision. ' +
+        'secret = same as text but input is hidden (use for tokens, MFA codes, never for AWS creds — those come from the profile). ' +
+        'text = free-form input.'),
+    message: z.string().describe('Question shown to the user.'),
+    choices: z
+        .array(z.string())
+        .optional()
+        .describe('Required when kind = "choice". Ignored otherwise.'),
+    defaultValue: z
+        .string()
+        .optional()
+        .describe('Default for kind=text/secret (typed-in default), or kind=choice (pre-selected option). ' +
+        'For kind=confirm, use "yes" or "no".'),
+});
+async function askOne(q, logger) {
+    logger.debug('Prompt', { kind: q.kind, message: q.message });
+    // Render the question header on stderr first so the user sees a clear
+    // visual break between agent reasoning and a question that wants input.
+    // Inquirer renders its own prompt line; the header is a visual anchor.
+    process.stderr.write('\n' + chalk.bold.cyan('? Agent needs input:') + '\n');
+    switch (q.kind) {
+        case 'choice': {
+            if (!q.choices || q.choices.length === 0) {
+                throw new Error('kind="choice" requires non-empty `choices`.');
+            }
+            const answer = await select({
+                message: q.message,
+                choices: q.choices.map((c) => ({ value: c, name: c })),
+                default: q.defaultValue,
+            });
+            return answer;
+        }
+        case 'confirm': {
+            const def = (q.defaultValue ?? 'yes').toLowerCase().startsWith('y');
+            const answer = await confirm({ message: q.message, default: def });
+            return answer ? 'yes' : 'no';
+        }
+        case 'secret': {
+            // Inquirer's password prompt masks input. Used for short secrets like
+            // MFA codes; long-lived AWS credentials should always come from the
+            // user's profile, not be typed here.
+            const answer = await password({ message: q.message, mask: '*' });
+            return answer;
+        }
+        case 'text':
+        default: {
+            const answer = await input({ message: q.message, default: q.defaultValue });
+            return answer;
+        }
+    }
+}
+/**
+ * Single-question prompt. The agent calls this whenever a required parameter
+ * cannot be inferred from history or discovered via the AWS CLI. Strong
+ * preference for kind="choice" when the candidate set is enumerable —
+ * picking from a list is faster and less error-prone than typing.
+ */
+export function promptUserTool(opts) {
+    return tool({
+        description: `Ask the user ONE question to gather missing information mid-reasoning. ` +
+            `Strongly prefer kind="choice" with explicit options when the set of valid answers is finite (e.g. matching profiles, bucket names, AZ ids). ` +
+            `Use kind="confirm" for yes/no decisions before risky actions. ` +
+            `Use kind="secret" only for short secrets typed at the moment of use (e.g. MFA codes); never solicit long-lived AWS credentials this way — they come from the user's profile. ` +
+            `Use kind="text" only when free-form input is genuinely required (e.g. a new tag value the user is inventing). ` +
+            `Whenever you are about to guess a value, call this tool instead.`,
+        inputSchema: QuestionSchema,
+        execute: async (q) => {
+            const answer = await askOne(q, opts.logger);
+            opts.logger.debug('Got answer', { answer: q.kind === 'secret' ? '***' : answer });
+            return { answer };
+        },
+    });
+}
+/**
+ * Multi-question prompt. Ask several related questions in one tool call —
+ * cuts model round-trips when the agent already knows it needs N pieces of
+ * info (e.g. "I need a source bucket, a destination bucket, and a region").
+ * Each question's `key` becomes the field name in the returned object.
+ */
+export function promptUserMultiTool(opts) {
+    return tool({
+        description: `Ask the user MULTIPLE related questions in one round, returning a map of key → answer. ` +
+            `Use this when the agent knows up front that several values are missing and asking them together is less disruptive than one-by-one. ` +
+            `Each question MUST have a unique \`key\` — that becomes the field in the returned \`answers\` object. ` +
+            `Same kind options as prompt_user: text, choice, confirm, secret. ` +
+            `For unrelated questions or when the answer to question A determines what to ask in question B, use prompt_user (single) instead.`,
+        inputSchema: z.object({
+            questions: z
+                .array(QuestionSchema)
+                .min(1)
+                .max(8)
+                .describe('1–8 related questions. Each must have a unique `key`.'),
+        }),
+        execute: async ({ questions }) => {
+            // Surface duplicate keys early — the model occasionally re-uses keys
+            // and the answers map would silently overwrite.
+            const seen = new Set();
+            for (const q of questions) {
+                if (!q.key)
+                    throw new Error('Every question in prompt_user_multi requires a `key`.');
+                if (seen.has(q.key))
+                    throw new Error(`Duplicate question key: ${q.key}`);
+                seen.add(q.key);
+            }
+            // Tell the user how many questions are coming up front. Less jarring
+            // than a surprise series of prompts.
+            process.stderr.write('\n' + chalk.dim(`(agent has ${questions.length} questions)`) + '\n');
+            const answers = {};
+            for (const q of questions) {
+                // q.key is guaranteed non-undefined here (checked above) but
+                // narrowing through Set membership isn't enough for the type system.
+                const key = q.key;
+                answers[key] = await askOne(q, opts.logger);
+            }
+            // Don't log secret values, but do confirm the keys we got.
+            const safeForLog = Object.fromEntries(Object.entries(answers).map(([k, v]) => {
+                const q = questions.find((qq) => qq.key === k);
+                return [k, q?.kind === 'secret' ? '***' : v];
+            }));
+            opts.logger.debug('Got multi answers', safeForLog);
+            return { answers };
+        },
+    });
+}

package/dist/usage.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Usage log: append-only JSONL of token totals per `aca` invocation. One line
+ * per run. Totals only — per-step breakdown is intentionally omitted to keep
+ * entries small and forward-compatible across providers.
+ *
+ * Disable via `logging.usageLog = false` in config; the writer becomes a no-op.
+ *
+ * Analytical use: this file is grep/jq-friendly. Sum tokens for the day:
+ *   cat ~/.local/state/aws-cli-agent/usage.log | jq -s 'map(.totalTokens) | add'
+ */
+export type UsageEntry = {
+    timestamp: string;
+    input: string;
+    provider: string;
+    model: string;
+    steps: number;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    /**
+     * Tokens served from prompt cache (cache hit). Available on Anthropic and
+     * Bedrock when caching was enabled and the provider returned the count.
+     * 0 when caching was disabled, the provider didn't report it, or this
+     * was a first-time request with no cache to hit.
+     */
+    cacheReadTokens: number;
+    /**
+     * Tokens written to prompt cache (cache miss + store). Counts the prefix
+     * length on cache-write events. 0 when caching was disabled or the
+     * provider didn't write a cache entry on this call.
+     */
+    cacheWriteTokens: number;
+};
+export declare class UsageLogger {
+    private readonly stream;
+    constructor(enabled: boolean);
+    log(entry: Omit<UsageEntry, 'timestamp'>): void;
+    close(): void;
+}

package/dist/usage.js

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import { FILES, PATHS } from './paths.js';
+export class UsageLogger {
+    stream;
+    constructor(enabled) {
+        if (!enabled) {
+            this.stream = null;
+            return;
+        }
+        fs.mkdirSync(PATHS.state, { recursive: true });
+        this.stream = fs.createWriteStream(FILES.usage, { flags: 'a' });
+    }
+    log(entry) {
+        if (!this.stream)
+            return;
+        try {
+            const full = { timestamp: new Date().toISOString(), ...entry };
+            this.stream.write(JSON.stringify(full) + '\n');
+        }
+        catch {
+            // Same philosophy as the other loggers: never crash the agent on
+            // log failures. Usage tracking is observability, not load-bearing.
+        }
+    }
+    close() {
+        this.stream?.end();
+    }
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "aws-cli-agent",
+  "version": "0.4.0",
+  "description": "Agentic AI assistant that turns natural-language requests into AWS CLI commands and runs them locally.",
+  "type": "module",
+  "bin": {
+    "aws-cli-agent": "dist/index.js",
+    "aca": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "test": "node scripts/smoke-test.mjs",
+    "ci": "npm run lint && npm run typecheck && npm run build && npm test",
+    "prepublishOnly": "npm run ci"
+  },
+  "keywords": [
+    "aws",
+    "aws-cli",
+    "aws-cli-agent",
+    "aca",
+    "ai",
+    "agent",
+    "llm",
+    "natural-language",
+    "cli",
+    "anthropic",
+    "openai",
+    "bedrock"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trstnk/aws-cli-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/trstnk/aws-cli-agent/issues"
+  },
+  "homepage": "https://github.com/trstnk/aws-cli-agent#readme",
+  "dependencies": {
+    "@ai-sdk/amazon-bedrock": "^4.0.106",
+    "@ai-sdk/anthropic": "^3.0.78",
+    "@ai-sdk/google": "^3.0.74",
+    "@ai-sdk/openai": "^3.0.64",
+    "@aws-sdk/credential-providers": "^3.1046.0",
+    "@inquirer/prompts": "^7.3.0",
+    "ai": "^6.0.183",
+    "chalk": "^5.4.0",
+    "commander": "^13.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.8.0",
+    "eslint": "^10.4.0",
+    "tsx": "^4.22.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.3"
+  }
+}