narai-primitives 2.0.0-rc.1

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "narai-primitives",
+  "version": "2.0.0-rc.1",
+  "description": "Read-only connectors + planning hub + connector framework, in one package. Bundles what was @narai/connector-toolkit, @narai/connector-config, @narai/connector-hub, and the seven @narai/<svc>-agent-connector packages.",
+  "type": "module",
+  "main": "./dist/hub/index.js",
+  "types": "./dist/hub/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/hub/index.d.ts",
+      "import": "./dist/hub/index.js"
+    },
+    "./hub": {
+      "types": "./dist/hub/index.d.ts",
+      "import": "./dist/hub/index.js"
+    },
+    "./toolkit": {
+      "types": "./dist/toolkit/index.d.ts",
+      "import": "./dist/toolkit/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js"
+    },
+    "./aws": {
+      "types": "./dist/connectors/aws/index.d.ts",
+      "import": "./dist/connectors/aws/index.js"
+    },
+    "./confluence": {
+      "types": "./dist/connectors/confluence/index.d.ts",
+      "import": "./dist/connectors/confluence/index.js"
+    },
+    "./db": {
+      "types": "./dist/connectors/db/index.d.ts",
+      "import": "./dist/connectors/db/index.js"
+    },
+    "./gcp": {
+      "types": "./dist/connectors/gcp/index.d.ts",
+      "import": "./dist/connectors/gcp/index.js"
+    },
+    "./github": {
+      "types": "./dist/connectors/github/index.d.ts",
+      "import": "./dist/connectors/github/index.js"
+    },
+    "./jira": {
+      "types": "./dist/connectors/jira/index.d.ts",
+      "import": "./dist/connectors/jira/index.js"
+    },
+    "./notion": {
+      "types": "./dist/connectors/notion/index.d.ts",
+      "import": "./dist/connectors/notion/index.js"
+    }
+  },
+  "bin": {
+    "narai": "./dist/cli/narai.js",
+    "aws-agent-connector": "./dist/connectors/aws/cli.js",
+    "confluence-agent-connector": "./dist/connectors/confluence/cli.js",
+    "db-agent-connector": "./dist/connectors/db/cli.js",
+    "gcp-agent-connector": "./dist/connectors/gcp/cli.js",
+    "github-agent-connector": "./dist/connectors/github/cli.js",
+    "jira-agent-connector": "./dist/connectors/jira/cli.js",
+    "notion-agent-connector": "./dist/connectors/notion/cli.js",
+    "usage-report": "./dist/toolkit/cli/usage-report.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist/",
+    "plugins/",
+    "plugin-hooks/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/narailabs/narai-primitives.git"
+  },
+  "bugs": {
+    "url": "https://github.com/narailabs/narai-primitives/issues"
+  },
+  "homepage": "https://github.com/narailabs/narai-primitives#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.119",
+    "@narai/credential-providers": "^0.2.1",
+    "better-sqlite3": "^12.9.0",
+    "js-yaml": "^4.1.1",
+    "zod": "^3.23.0"
+  },
+  "optionalDependencies": {
+    "@aws-sdk/client-cloudwatch": "^3.1030.0",
+    "@aws-sdk/client-dynamodb": "^3.1030.0",
+    "@aws-sdk/client-lambda": "^3.1030.0",
+    "@aws-sdk/client-rds": "^3.1030.0",
+    "@aws-sdk/client-s3": "^3.1030.0",
+    "@aws-sdk/client-sts": "^3.1030.0",
+    "gpt-tokenizer": "^2.5.0",
+    "mongodb": "^7.1.1",
+    "mssql": "^12.2.1",
+    "mysql2": "^3.22.0",
+    "oracledb": "^6.10.0",
+    "pg": "^8.20.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.19.39",
+    "@types/pg": "^8.20.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "aws-sdk-client-mock": "^4.1.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
+  }
+}

package/plugin-hooks/session-summary.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// SessionEnd hook — summarize one session's usage.jsonl into a .json + .md pair.
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+function aggregate(connector, sessionId, records) {
+  if (records.length === 0) {
+    return {
+      session_id: sessionId,
+      connector,
+      start: "",
+      end: "",
+      total_calls: 0,
+      total_response_bytes: 0,
+      total_estimated_tokens: 0,
+      error_rate: 0,
+      by_action: {},
+      top_responses: [],
+    };
+  }
+  const byAction = {};
+  let totalBytes = 0, totalTokens = 0, errors = 0;
+  let start = records[0].ts, end = records[0].ts;
+  for (const r of records) {
+    totalBytes += r.response_bytes;
+    totalTokens += r.estimated_tokens;
+    if (r.status !== "success") errors++;
+    if (r.ts < start) start = r.ts;
+    if (r.ts > end) end = r.ts;
+    const s = byAction[r.action] ||= {
+      calls: 0, response_bytes: 0, estimated_tokens: 0, ms_total: 0, ms_count: 0,
+    };
+    s.calls++;
+    s.response_bytes += r.response_bytes;
+    s.estimated_tokens += r.estimated_tokens;
+    if (typeof r.execution_time_ms === "number") { s.ms_total += r.execution_time_ms; s.ms_count++; }
+  }
+  const by_action = {};
+  for (const [k, s] of Object.entries(byAction)) {
+    by_action[k] = {
+      calls: s.calls,
+      response_bytes: s.response_bytes,
+      estimated_tokens: s.estimated_tokens,
+      avg_ms: s.ms_count > 0 ? Math.round(s.ms_total / s.ms_count) : 0,
+    };
+  }
+  const top_responses = [...records]
+    .sort((a, b) => b.response_bytes - a.response_bytes)
+    .slice(0, 3)
+    .map((r) => ({ action: r.action, response_bytes: r.response_bytes }));
+  return {
+    session_id: sessionId,
+    connector,
+    start, end,
+    total_calls: records.length,
+    total_response_bytes: totalBytes,
+    total_estimated_tokens: totalTokens,
+    error_rate: errors / records.length,
+    by_action,
+    top_responses,
+  };
+}
+
+function renderMd(s) {
+  if (s.total_calls === 0) {
+    return `# ${s.connector} usage — session ${s.session_id}\n\nNo calls recorded.\n`;
+  }
+  const successes = s.total_calls - Math.round(s.error_rate * s.total_calls);
+  const errors = s.total_calls - successes;
+  const rows = Object.entries(s.by_action)
+    .sort(([, a], [, b]) => b.response_bytes - a.response_bytes)
+    .map(([action, a]) =>
+      `| ${action} | ${a.calls} | ${a.response_bytes.toLocaleString()} | ${a.estimated_tokens.toLocaleString()} | ${a.avg_ms} |`,
+    ).join("\n");
+  const top = s.top_responses.map((t, i) =>
+    `${i + 1}. ${t.action} (${t.response_bytes.toLocaleString()} bytes)`).join("\n");
+  return [
+    `# ${s.connector} usage — session ${s.session_id}`, ``,
+    `- Window: ${s.start} → ${s.end}`,
+    `- Calls: ${s.total_calls} (${successes} success, ${errors} error — ${(s.error_rate * 100).toFixed(1)}%)`,
+    `- Response bytes: ${s.total_response_bytes.toLocaleString()} | Estimated tokens: ${s.total_estimated_tokens.toLocaleString()}`,
+    ``,
+    `## By action`, ``,
+    `| action | calls | bytes | est. tokens | avg ms |`,
+    `|---|---|---|---|---|`,
+    rows, ``,
+    `## Top responses`, ``,
+    top, ``,
+  ].join("\n");
+}
+
+export function summarizeSession(baseDir, connector, sessionId) {
+  const jsonl = join(baseDir, `${sessionId}.jsonl`);
+  const summaryJson = join(baseDir, `summary-${sessionId}.json`);
+  const summaryMd = join(baseDir, `summary-${sessionId}.md`);
+  if (!existsSync(jsonl)) return;
+  if (existsSync(summaryJson)) return;
+
+  let raw;
+  try { raw = readFileSync(jsonl, "utf-8"); } catch { return; }
+  const records = raw.split("\n").filter(Boolean).map((l) => {
+    try { return JSON.parse(l); } catch { return null; }
+  }).filter(Boolean);
+
+  const summary = aggregate(connector, sessionId, records);
+  try {
+    writeFileSync(summaryJson, JSON.stringify(summary, null, 2), "utf-8");
+    writeFileSync(summaryMd, renderMd(summary), "utf-8");
+  } catch {
+    // swallow
+  }
+}
+
+function main() {
+  const connector = process.env["USAGE_CONNECTOR_NAME"];
+  if (!connector) return;
+
+  let raw;
+  try { raw = readFileSync(0, "utf-8"); } catch { return; }
+  let sessionId = "unknown";
+  try {
+    const p = JSON.parse(raw || "{}");
+    if (typeof p.session_id === "string") sessionId = p.session_id;
+  } catch {}
+
+  const baseDir =
+    process.env["USAGE_STORAGE_DIR"] ||
+    join(process.cwd(), ".claude", "connectors", connector, "usage");
+
+  summarizeSession(baseDir, connector, sessionId);
+}
+
+// Only auto-run when executed directly (not when imported by stale-summarize.mjs).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try { main(); } catch {}
+  process.exit(0);
+}

package/plugin-hooks/stale-summarize.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// SessionStart hook — summarize any orphaned <sid>.jsonl whose mtime is older
+// than USAGE_SUMMARY_STALE_HOURS and has no matching summary-<sid>.json.
+
+import { readdirSync, statSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+// Reuse summarizeSession by re-importing — but importing a sibling .mjs means
+// the same file must be runnable standalone AND exportable. Simpler: inline
+// a tiny wrapper that delegates to session-summary.mjs via dynamic import.
+
+async function main() {
+  const connector = process.env["USAGE_CONNECTOR_NAME"];
+  if (!connector) return;
+  const staleHours = Number(process.env["USAGE_SUMMARY_STALE_HOURS"] ?? "12");
+  if (!Number.isFinite(staleHours) || staleHours <= 0) return;
+
+  const baseDir =
+    process.env["USAGE_STORAGE_DIR"] ||
+    join(process.cwd(), ".claude", "connectors", connector, "usage");
+
+  let entries;
+  try { entries = readdirSync(baseDir); } catch { return; }
+
+  const cutoff = Date.now() - staleHours * 60 * 60 * 1000;
+
+  // Dynamic-import the sibling summarizer module.
+  let summarizeSession;
+  try {
+    const mod = await import(new URL("./session-summary.mjs", import.meta.url).href);
+    summarizeSession = mod.summarizeSession;
+  } catch {
+    return;
+  }
+  if (typeof summarizeSession !== "function") return;
+
+  for (const name of entries) {
+    if (!name.endsWith(".jsonl")) continue;
+    const sessionId = name.slice(0, -".jsonl".length);
+    const summaryPath = join(baseDir, `summary-${sessionId}.json`);
+    if (existsSync(summaryPath)) continue;
+    let st;
+    try { st = statSync(join(baseDir, name)); } catch { continue; }
+    if (st.mtimeMs > cutoff) continue;
+    try { summarizeSession(baseDir, connector, sessionId); } catch {}
+  }
+
+  // Retention pass — gzip old files, delete very-old gz files.
+  const gzipDays = Number(process.env["USAGE_RETENTION_GZIP_DAYS"] ?? "30");
+  const deleteDays = Number(process.env["USAGE_RETENTION_DELETE_DAYS"] ?? "180");
+  if ((Number.isFinite(gzipDays) && gzipDays > 0) || (Number.isFinite(deleteDays) && deleteDays > 0)) {
+    try {
+      const { runRetention } = await import(
+        new URL(
+          "../dist/usage/retention.js",
+          import.meta.url,
+        ).href,
+      );
+      if (typeof runRetention === "function") {
+        await runRetention(baseDir, {
+          gzipDays: Number.isFinite(gzipDays) ? gzipDays : 0,
+          deleteDays: Number.isFinite(deleteDays) ? deleteDays : 0,
+        });
+      }
+    } catch {
+      // swallow — retention is best-effort
+    }
+  }
+}
+
+main().catch(() => {}).finally(() => process.exit(0));

package/plugin-hooks/usage-record.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// Toolkit-shipped PostToolUse hook. Appends one JSONL line per Bash call
+// that invoked this plugin's connector CLI. Fail-soft: errors exit 0.
+
+import { readFileSync, appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+async function main() {
+  if (process.env["USAGE_TRACKING_ENABLED"] === "0") return;
+
+  const connector = process.env["USAGE_CONNECTOR_NAME"];
+  const hint = process.env["USAGE_BIN_HINT"];
+  if (!connector || !hint) return;
+
+  // Read hook payload from stdin (Claude Code sends JSON on stdin).
+  let raw;
+  try {
+    raw = readFileSync(0, "utf-8");
+  } catch {
+    return;
+  }
+  if (!raw) return;
+
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+
+  if (payload.tool_name !== "Bash") return;
+
+  const command =
+    (payload.tool_input && typeof payload.tool_input.command === "string"
+      ? payload.tool_input.command
+      : "") || "";
+  if (!command.includes(hint)) return;
+
+  const stdout =
+    (payload.tool_response &&
+      typeof payload.tool_response.stdout === "string" &&
+      payload.tool_response.stdout) ||
+    "";
+  const response_bytes = Buffer.byteLength(stdout, "utf-8");
+  // Tokenizer: heuristic by default, gpt-4o when opted in. Never throws.
+  let estimated_tokens = Math.ceil(response_bytes / 4);
+  let token_method = "heuristic";
+  const tokenizer = process.env["USAGE_TOKENIZER"];
+  if (tokenizer && tokenizer !== "heuristic") {
+    try {
+      if (tokenizer === "gpt-4o") {
+        const mod = await import("gpt-tokenizer").catch(() => null);
+        if (mod && typeof mod.encode === "function") {
+          estimated_tokens = mod.encode(stdout).length;
+          token_method = "gpt-4o";
+        }
+      }
+      // Unknown methods fall through; heuristic already set.
+    } catch {
+      // fallback already in place
+    }
+  }
+
+  // Parse --action from command.
+  const actionMatch = command.match(/--action\s+([A-Za-z0-9_-]+)/);
+  const action = actionMatch ? actionMatch[1] : "unknown";
+
+  // Parse envelope status.
+  let status = "unparseable";
+  try {
+    const env = JSON.parse(stdout);
+    if (env && typeof env.status === "string") status = env.status;
+  } catch {
+    // status stays "unparseable"
+  }
+
+  const execution_time_ms =
+    typeof payload.execution_time_ms === "number"
+      ? payload.execution_time_ms
+      : undefined;
+
+  const record = {
+    ts: new Date().toISOString(),
+    session_id: String(payload.session_id ?? "unknown"),
+    connector,
+    action,
+    status,
+    response_bytes,
+    estimated_tokens,
+    token_method,
+    ...(execution_time_ms !== undefined ? { execution_time_ms } : {}),
+  };
+
+  const baseDir =
+    process.env["USAGE_STORAGE_DIR"] ||
+    join(process.cwd(), ".claude", "connectors", connector, "usage");
+  const file = join(baseDir, `${record.session_id}.jsonl`);
+
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, JSON.stringify(record) + "\n", "utf-8");
+  } catch {
+    // swallow
+  }
+}
+
+try {
+  await main();
+} catch {
+  // never propagate
+}
+process.exit(0);

package/plugins/aws-agent/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "aws-agent-plugin",
+  "version": "1.0.0",
+  "description": "Read-only AWS connector for Claude Code. Wraps @narai/aws-agent-connector. Lambda, RDS, S3, CloudWatch.",
+  "author": "narai"
+}

package/plugins/aws-agent/README.md

@@ -0,0 +1,46 @@
+# aws-agent-plugin
+
+Claude Code plugin that wraps [`@narai/aws-agent-connector`](https://www.npmjs.com/package/@narai/aws-agent-connector) as a read-only AWS skill and slash command.
+
+## What it adds
+
+- **Skill** `aws-agent` — invoked automatically when the model is asked about AWS Lambda, RDS, S3, or CloudWatch.
+- **Slash command** `/aws-agent <action> <params-json>` — explicit invocation.
+- **Binary** `aws-agent` — thin shell shim that exec's the installed connector CLI.
+
+## How install works
+
+Claude Code plugins don't run `npm install`. On first `SessionStart` the
+hook in `hooks/hooks.json`:
+
+1. compares the plugin's `package.json` with whatever is in
+   `${CLAUDE_PLUGIN_DATA}/`;
+2. if different or missing, copies the manifest and runs
+   `npm install --no-audit --no-fund` inside `${CLAUDE_PLUGIN_DATA}`;
+3. if the install fails, removes the stale copy so the hook re-runs
+   next session.
+
+After a successful install,
+`${CLAUDE_PLUGIN_DATA}/node_modules/@narai/aws-agent-connector/dist/cli.js`
+exists and `bin/aws-agent` can exec it.
+
+## Usage
+
+Inside Claude Code:
+
+```
+/aws-agent list_functions {"region":"us-east-1","prefix":"acme-"}
+```
+
+Or let the `aws-agent` skill be triggered automatically by asking about
+AWS resources.
+
+## AWS credentials
+
+The connector uses the default AWS credential chain — profiles, env
+vars, instance roles, and so on. No credentials are stored by this
+plugin.
+
+## License
+
+MIT

package/plugins/aws-agent/bin/aws-agent

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# aws-agent — thin shim over @narai/aws-agent-connector.
+#
+# The SessionStart hook in hooks/hooks.json installs the npm package into
+# ${CLAUDE_PLUGIN_DATA}/node_modules on first session. This shim exec's
+# that CLI.
+set -euo pipefail
+
+if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
+  echo "aws-agent: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  exit 2
+fi
+
+CLI="${CLAUDE_PLUGIN_DATA}/node_modules/@narai/aws-agent-connector/dist/cli.js"
+
+if [ ! -f "$CLI" ]; then
+  echo "aws-agent: connector CLI not found at $CLI" >&2
+  echo "Restart your Claude Code session to re-run the SessionStart install hook." >&2
+  exit 2
+fi
+
+exec node "$CLI" "$@"

package/plugins/aws-agent/commands/aws-agent.md

@@ -0,0 +1,6 @@
+---
+description: Run a read-only AWS query via the aws-agent connector
+argument-hint: "<action> <params-json>"
+---
+
+Invoke the `aws-agent` skill with the user's $ARGUMENTS as the action name and params JSON. Return the connector's JSON envelope verbatim.

package/plugins/aws-agent/hooks/hooks.json

@@ -0,0 +1,49 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (mkdir -p \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/\" && cd \"${CLAUDE_PLUGIN_DATA}\" && npm install --no-audit --no-fund) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/plugin/hooks/reminder.mjs\" 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/stale-summarize.mjs\" 2>/dev/null || true",
+            "env": { "USAGE_CONNECTOR_NAME": "aws" }
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/usage-record.mjs\" 2>/dev/null || true",
+            "env": {
+              "USAGE_CONNECTOR_NAME": "aws",
+              "USAGE_BIN_HINT": "@narai/aws-agent-connector"
+            }
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/session-summary.mjs\" 2>/dev/null || true",
+            "env": { "USAGE_CONNECTOR_NAME": "aws" }
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/aws-agent/hooks/reminder.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * SessionStart curation reminder for the AWS connector.
+ */
+try {
+  const data = process.env.CLAUDE_PLUGIN_DATA;
+  if (!data) process.exit(0);
+  const toolkitEntry = `${data}/node_modules/@narai/connector-toolkit/dist/plugin/reminder.js`;
+  const mod = await import(toolkitEntry);
+  const decision = mod.evaluateNudge({ connectors: ["aws"] });
+  if (decision.nudge) {
+    process.stdout.write(decision.banner + "\n");
+  }
+} catch {
+  // best-effort — reminder never blocks startup
+}

package/plugins/aws-agent/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "aws-agent-plugin-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Runtime manifest for aws-agent-plugin. The SessionStart hook runs `npm install` on this manifest into ${CLAUDE_PLUGIN_DATA}.",
+  "dependencies": {
+    "@narai/aws-agent-connector": "file:.."
+  }
+}

package/plugins/aws-agent/skills/aws-agent/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: aws-agent
+description: |
+  Use when the user asks about read-only AWS inventory — Lambda functions,
+  RDS databases, S3 buckets, or CloudWatch metrics in an AWS account. Queries
+  are scoped to a single region (except list_buckets, which is account-wide).
+  Never modifies AWS resources.
+context: fork
+---
+
+# AWS Agent
+
+Answer the user's question by invoking the `aws-agent` binary exposed by
+this plugin. It delegates to `@narai/aws-agent-connector`, which speaks to
+AWS via the read-only SDK v3 surface.
+
+## Invocation
+
+```
+aws-agent --action <action> --params '<json>'
+```
+
+The CLI writes a single JSON envelope to stdout and exits 0 on success, 1 on
+a handled error, 2 on CLI misuse. Return the envelope verbatim to the
+orchestrator — do not paraphrase or re-format.
+
+## Supported actions
+
+| Action | Required params | Notes |
+|---|---|---|
+| `list_functions` | `region`, optional `prefix` | Returns Lambda functions in the region, optionally filtered by name prefix |
+| `describe_db` | `region`, `db_identifier` | Returns an RDS instance's engine, version, endpoint, storage, and status |
+| `list_buckets` | optional `prefix`, optional `region` | Returns S3 buckets across the account |
+| `get_metrics` | `region`, `namespace`, `metric_name`, `dimensions`, optional `hours` (default 24, max 168) | CloudWatch datapoints at 5-min resolution |
+
+Example:
+
+```bash
+aws-agent --action list_functions --params '{"region":"us-east-1","prefix":"acme-"}'
+```
+
+## Envelope shape
+
+Success:
+```json
+{"status": "success", "action": "<name>", "data": { ... }}
+```
+
+Error (handled):
+```json
+{"status": "error", "action": "<name>", "error_code": "<CODE>", "message": "...", "retriable": true}
+```
+
+Known error codes: `VALIDATION_ERROR`, `AUTH_ERROR`, `NOT_FOUND`,
+`RATE_LIMITED`, `TIMEOUT`, `CONNECTION_ERROR`, `CONFIG_ERROR`,
+`CONFIGURATION_ERROR`.
+
+## Credentials
+
+The connector uses the default AWS credential chain — profiles,
+environment variables, instance/container/EKS roles — whichever is
+configured on the host. If both `AWS_ACCESS_KEY_ID` and
+`AWS_SECRET_ACCESS_KEY` are set via `@narai/credential-providers`, those
+take precedence.
+
+## Safety
+
+Read-only by construction: only `Describe*`, `List*`, and `Get*` SDK
+commands are whitelisted inside the connector. Write/modify operations
+cannot be invoked through this skill.