@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/src/cli.js

@@ -2,22 +2,26 @@
 
 import pkg from '../package.json' with { type: 'json' };
 import readline from 'readline';
+import { cancel, intro, isCancel, outro, select, text } from '@clack/prompts';
 import path from 'node:path';
-import { buildLocalScaffoldMeta, LANE_KEYS, RUN_TARGETS } from './lib/local-scaffold.js';
+import { buildLocalScaffoldMeta } from './lib/local-scaffold.js';
 import { writeScaffoldFiles } from './lib/write-files.js';
 import { initializeGitRepository } from './lib/init-git.js';
 import { initializeLocalSqlite } from './local/sqlite.js';
 import { printContextSummary } from './lib/detect-context.js';
 import { promptOptionalByokKeys } from './lib/prompt-byok.js';
 import { runStartLocal } from './commands/start-local.js';
+import { runOllama } from './commands/ollama.js';
+import { runModels } from './commands/models.js';
 import { runTunnel } from './commands/tunnel.js';
 import { runDeploy } from './commands/deploy.js';
+import { runConnections } from './commands/connections.js';
 import { runIdentityPreview } from './commands/identity-preview.js';
 import { runIdentityInit } from './commands/identity-init.js';
 import { runContext } from './commands/context.js';
 import { runDb } from './commands/db.js';
 import { runStatus } from './commands/status.js';
-import { runTui } from './commands/tui.js';
+import { runInteractive } from './commands/interactive.js';
 import { runShell } from './commands/shell.js';
 import { runDockerize } from './commands/dockerize.js';
 import { runMini } from './commands/mini.js';
@@ -26,13 +30,27 @@ import { runDeployReceipt } from './commands/deploy-receipt.js';
 import { runSecurity } from './commands/security.js';
 import { runRecon } from './commands/recon.js';
 import { runCad } from './commands/cad.js';
+import { runSkills } from './commands/skills.js';
+import { runEval } from './commands/eval.js';
+import { runCloudflare } from './commands/cloudflare.js';
+import { runWhoami } from './commands/whoami.js';
+import { runResume } from './commands/resume.js';
+import { runLogin, runLogout } from './commands/account-auth.js';
 import { applyPresetSelection, runAdd, runCapabilities, runDev, runInspect } from './commands/product.js';
 import { listPresets, resolvePreset } from './presets/index.js';
 import fs from 'node:fs';
 import { repositoryRoot } from './knowledge/config.js';
+import { resolveAccountSdkKey } from './lib/account-session.js';
+import { renderDiagnosticError } from './errors/index.js';
 
 const VERSION = pkg.version;
 
+function reportCliError(error) {
+  if (error?.reported) return;
+  const rendered = renderDiagnosticError(error).split('\n').map((line) => `  ${line}`).join('\n');
+  console.error(`\n${rendered}\n`);
+}
+
 function createPrompt() {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return {
@@ -46,14 +64,16 @@ function printHelp() {
   Agent Sam SDK — CLI v${VERSION}
 
   Product UX:
+    agentsam                     Enter the interactive Agent Sam experience
     agentsam create <name> --preset <fullstack|cms|prototype|data>
     agentsam add <auth|cms|knowledge|agent|deploy-cloudflare>
     agentsam dev               Run this project's existing npm dev script
-    agentsam inspect [--json]  Canonical deterministic repository.snapshot
+    agentsam inspect [--json]  Bounded repository index by default; use --view full for authority envelope
     agentsam deploy            Graduate an AgentSam project intentionally
 
   Capability discovery:
     agentsam capabilities [capability-id] [--json]
+    agentsam skills [skill-id-or-alias] [--references] [--json]
 
   Power-user UX:
     agentsam context [--json]  Git repo/revision + bridge configuration from any repo
@@ -63,15 +83,21 @@ function printHelp() {
     agentsam repo snapshot     Git composition/churn; --save retains observations
     agentsam cad blender       Programmatic Blender inspect/build/render/export (--help)
     agentsam mini <name>       Create and preview a small local gadget (--help for options)
-    agentsam merkle            File integrity, snapshots, comparisons, and TUI (--help)
+    agentsam merkle            File integrity, snapshots, comparisons, and interactive explorer (--help)
     agentsam deploy-receipt    Merkle deploy/checkpoint capture + promote/failure receipts (--help)
     agentsam recon             Bounded-worker task packets + finding-report validation (--help)
     agentsam security          Dependency scan, log triage, and verified repair (--help)
     agentsam status [--json]   Live local Git + DB + API + PTY status
     agentsam db init|status    Manage the project-local SQLite database
-    agentsam tui               Zero-dependency ANSI Agent Sam dashboard
-    agentsam tui rich          Optional Python Rich dashboard (--install for local venv)
+    agentsam models            Verify configured providers and selectable hosted/local models
+    agentsam login             Authenticate IAM and persist a secure machine-local session
+    agentsam logout            Remove the local IAM session; provider keys stay untouched
+    agentsam whoami [--json]   Authenticated IAM identity + safe credential status
+    agentsam resume [session]  Resume a saved Agent Sam session; omit id for picker
+    agentsam eval context      Offline context-strategy/economics fixtures (--help)
+    agentsam cloudflare        Native Wrangler reads + Worker CPU profile analysis (--help)
     agentsam start-local       Local PTY on ws://127.0.0.1:3099 (no tunnel, no Cloudflare)
+    agentsam ollama            Opt-in local Ollama setup/status/model management
     agentsam shell             Interactive Agent Sam slash-command shell
     agentsam tunnel            Explicitly expose local PTY when remote access is wanted
     agentsam deploy            Graduate to Cloudflare / GCP when ready
@@ -84,6 +110,21 @@ function printHelp() {
   Context options:
     --json                     Machine-readable output
     --cwd <path>               Resolve a different working directory
+
+  Inspect options:
+    --view <full|index|files>  Full authority envelope, facet index, or bounded matching files (default index)
+    --full                     Explicitly request the full authority envelope
+    --system/--package <name>  Filter semantic ownership
+    --category/--tag <value>   Filter semantic classification
+    --layer/--role <value>     Filter architecture role
+    --path <prefix|glob>       Filter repository paths (supports * and **)
+    --symbol/--import <value>  Filter AST symbols or imports
+    --match <text>             Lexical AND-match across semantic routing metadata
+    --limit <1..500>           Bound files view (default 50)
+    --facet-limit <1..200>     Bound each facet list (default 48)
+    --snapshot-file <file>     Reuse a saved canonical repository.snapshot; skips Merkle/AST rescan
+    --save-snapshot <file>     Save the canonical full snapshot while emitting the selected view
+    --pretty                   Pretty-print JSON; machine JSON is compact by default
     --remote <name>            Preferred Git remote (default origin; falls back to first remote)
 
   Init is completable with Node only — no IAM login, no OAuth, no Cloudflare.
@@ -93,7 +134,7 @@ function printHelp() {
     --quick                    Quick tunnel (default) — trycloudflare.com URL
     --named                    Named CF tunnel (needs --tunnel-name --hostname --zone-id)
     --port <n>                 Local PTY port (default 3099)
-    --token <sdk_…>            Use existing AGENTSAM_SDK_TOKEN (skip browser auth)
+    --token <sdk_…>            Use existing AGENTSAM_SDK_KEY (skip browser auth)
 
   Init options:
     --name <name>              Project directory name
@@ -121,11 +162,13 @@ function parseInitArgs(argv) {
 }
 
 function parseDeployArgs(argv) {
-  const opts = { target: '', accountId: '' };
+  const opts = { target: '', accountId: '', dryRun: false, plan: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--target') opts.target = argv[++i] || '';
     else if (arg === '--account-id') opts.accountId = argv[++i] || '';
+    else if (arg === '--dry-run') opts.dryRun = true;
+    else if (arg === '--plan') opts.plan = true;
   }
   return opts;
 }
@@ -176,7 +219,7 @@ async function runLocalInit(config) {
   ✓ Environment  ${path.join(dir, '.env')}
   ✓ SQLite       ${db.dbPath} (${db.tables.length} tables)
   ✓ Local API    Node · http://127.0.0.1:8787
-  ✓ Terminal UI  ANSI built in · Rich optional
+  ✓ Agent Sam     interactive CLI ready
 
   Next:`);
   console.log(`    cd ${meta.projectName}`);
@@ -184,9 +227,10 @@ async function runLocalInit(config) {
     console.log(`    ${step}`);
   }
 
-  if (prompt && process.env.AGENTSAM_SDK_TOKEN) {
+  const sdkKey = resolveAccountSdkKey({ env: process.env }).value;
+  if (prompt && sdkKey) {
     console.log('\n  Optional — BYOK keys for IAM dashboard Agent Sam (skip with Enter):\n');
-    await promptOptionalByokKeys(process.env.AGENTSAM_SDK_TOKEN, prompt);
+    await promptOptionalByokKeys(sdkKey, prompt);
   }
 
   console.log(`
@@ -196,58 +240,61 @@ async function runLocalInit(config) {
 }
 
 async function initInteractive(partial = {}) {
-  const prompt = createPrompt();
-
-  console.log(`
-  ╔════════════════════════════════╗
-  ║   Agent Sam SDK — Init            ║
-  ║   Local-first · Node only         ║
-  ╚════════════════════════════════╝
-  `);
-
-  const projectName =
-    partial.projectName ||
-    (await prompt.ask('  1) Project name: '));
-
-  if (!partial.lane) {
-    console.log(`
-  2) Lane:
-    1) Full Stack   2) CMS   3) Data   4) CRM   5) Creative
-  `);
-  }
-  const laneKey = partial.lane
-    ? partial.lane
-    : LANE_KEYS[await prompt.ask('  Pick lane [1-5]: ')] || 'fullstack';
+  const pick = (value) => {
+    if (!isCancel(value)) return value;
+    cancel('Agent Sam init cancelled.');
+    const error = new Error('init_cancelled');
+    error.code = 'AGENTSAM_INIT_CANCELLED';
+    throw error;
+  };
 
-  if (!partial.runTarget) {
-    console.log(`
-  3) Future deploy target?
+  intro('Create an Agent Sam project');
+
+  const projectName = partial.projectName || pick(await text({
+    message: 'Project name',
+    placeholder: 'my-agent',
+    validate(value) {
+      if (!String(value || '').trim()) return 'Project name is required';
+    },
+  }));
+
+  const laneKey = partial.lane || pick(await select({
+    message: 'Project type',
+    initialValue: 'fullstack',
+    options: [
+      { value: 'fullstack', label: 'Full Stack' },
+      { value: 'cms', label: 'CMS' },
+      { value: 'data', label: 'Data Solutions' },
+      { value: 'crm', label: 'Customer Management' },
+      { value: 'creative', label: 'Creative & Design' },
+    ],
+  }));
+
+  const runTarget = partial.runTarget || pick(await select({
+    message: 'Future deploy target',
+    initialValue: 'local',
+    options: [
+      { value: 'local', label: 'Local only / decide later' },
+      { value: 'cloudflare', label: 'Cloudflare later' },
+      { value: 'gcp', label: 'GCP later' },
+    ],
+  }));
 
-    1) Local only / decide later
-    2) Cloudflare later (Worker + D1 adapter at deploy time)
-    3) GCP later (your Google Cloud project)
-  `);
-  }
-  const runTarget = partial.runTarget
-    ? partial.runTarget
-    : RUN_TARGETS[await prompt.ask('  Select [1]: ')] || 'local';
-
-  // Credential detection is demand-driven, not unconditional. missingForInit()
-  // already knows local needs nothing (`if (runTarget === 'local') return []`)
-  // — it just never got consulted before this fix, because detectContext()
-  // used to run before runTarget was even known. runTarget alone is enough
-  // to decide whether detection is needed at all, so skip the subprocess
-  // calls entirely for local instead of just hiding their output.
   if (runTarget !== 'local') {
     const { detectContext, missingForInit } = await import('./lib/detect-context.js');
     const ctx = await detectContext();
-    if (missingForInit(ctx, process.env.AGENTSAM_SDK_TOKEN || '', { runTarget }).length) {
+    if (missingForInit(ctx, resolveAccountSdkKey({ env: process.env }).value, { runTarget }).length) {
       printContextSummary(ctx);
     }
   }
 
-  await runLocalInit({ projectName, lane: laneKey, runTarget, prompt });
-  prompt.close();
+  const prompt = resolveAccountSdkKey({ env: process.env }).value ? createPrompt() : null;
+  try {
+    await runLocalInit({ projectName, lane: laneKey, runTarget, prompt });
+  } finally {
+    prompt?.close();
+  }
+  outro(`Created ${projectName}`);
 }
 
 async function initFromArgs(argv) {
@@ -264,8 +311,20 @@ const rest = process.argv.slice(3);
 
 if (command === '--version' || command === '-v') {
   console.log(VERSION);
-} else if (command === '--help' || command === '-h' || !command) {
+} else if (command === '--help' || command === '-h') {
   printHelp();
+} else if (!command) {
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    try { await runInteractive(); }
+    catch (e) {
+      if (e?.code !== 'AGENTSAM_SETUP_CANCELLED') {
+        reportCliError(e);
+        process.exitCode = 1;
+      }
+    }
+  } else {
+    printHelp();
+  }
 } else if (command === 'create') {
   try {
     const opts = parseCreateArgs(rest);
@@ -277,86 +336,149 @@ if (command === '--version' || command === '-v') {
       applyPresetSelection(created.dir, preset);
       console.log(`  ✓ Preset      ${preset.id}\n  ✓ Features    ${preset.features.join(', ') || 'none'}\n  ✓ Capabilities ${preset.capabilities.length}\n`);
     }
-  } catch (e) { console.error(`\n  ✗ ${e?.message || e}\n`); process.exitCode = 1; }
+  } catch (e) { reportCliError(e); process.exitCode = 1; }
 } else if (command === 'add') {
   try { await runAdd(rest); }
-  catch (e) { console.error(`\n  ✗ ${e?.message || e}\n`); process.exitCode = 1; }
+  catch (e) { reportCliError(e); process.exitCode = 1; }
 } else if (command === 'dev') {
   try { await runDev(rest); }
-  catch (e) { console.error(`\n  ✗ ${e?.message || e}\n`); process.exitCode = 1; }
+  catch (e) { reportCliError(e); process.exitCode = 1; }
 } else if (command === 'inspect') {
   try { await runInspect(rest); }
-  catch (e) { console.error(`\n  ✗ ${e?.message || e}\n`); process.exitCode = 1; }
+  catch (e) { reportCliError(e); process.exitCode = 1; }
 } else if (command === 'capabilities') {
   try { await runCapabilities(rest); }
-  catch (e) { console.error(`\n  ✗ ${e?.message || e}\n`); process.exitCode = 1; }
+  catch (e) { reportCliError(e); process.exitCode = 1; }
 } else if (command === 'context') {
   try {
     await runContext(rest);
   } catch (e) {
-    console.error(`\n  ✗ ${e?.message || e}\n`);
+    reportCliError(e);
     process.exit(1);
   }
 } else if (command === 'status') {
   try {
     await runStatus(rest);
   } catch (e) {
-    console.error(`\n  ✗ ${e?.message || e}\n`);
+    reportCliError(e);
     process.exit(1);
   }
 } else if (command === 'db') {
   try {
     await runDb(rest);
   } catch (e) {
-    console.error(`\n  ✗ ${e?.message || e}\n`);
+    reportCliError(e);
     process.exit(1);
   }
-} else if (command === 'tui') {
+} else if (command === 'models') {
   try {
-    await runTui(rest);
+    await runModels(rest);
   } catch (e) {
-    console.error(`\n  ✗ ${e?.message || e}\n`);
+    reportCliError(e);
     process.exit(1);
   }
+} else if (command === 'eval') {
+  try {
+    await runEval(rest);
+  } catch (e) {
+    reportCliError(e);
+    process.exit(1);
+  }
+} else if (command === 'cloudflare' || command === 'cf') {
+  try {
+    await runCloudflare(rest);
+  } catch (e) {
+    if (!e?.reported) reportCliError(e);
+    process.exitCode = 1;
+  }
+} else if (command === 'login') {
+  try {
+    await runLogin(rest);
+  } catch (e) {
+    reportCliError(e);
+    process.exitCode = 1;
+  }
+} else if (command === 'logout') {
+  try {
+    runLogout(rest);
+  } catch (e) {
+    reportCliError(e);
+    process.exitCode = 1;
+  }
+} else if (command === 'whoami') {
+  try {
+    await runWhoami(rest);
+  } catch (e) {
+    reportCliError(e);
+    process.exitCode = 1;
+  }
+} else if (command === 'resume') {
+  try {
+    await runResume(rest);
+  } catch (e) {
+    reportCliError(e);
+    process.exitCode = 1;
+  }
 } else if (command === 'shell') {
   try {
     await runShell(rest);
   } catch (e) {
-    console.error(`\n  ✗ ${e?.message || e}\n`);
+    reportCliError(e);
     process.exit(1);
   }
 } else if (command === 'start-local') {
   await runStartLocal({});
+} else if (command === 'ollama') {
+  try {
+    await runOllama(rest);
+  } catch (e) {
+    reportCliError(e);
+    process.exitCode = 1;
+  }
 } else if (command === 'tunnel') {
   try {
     await runTunnel(rest);
   } catch (e) {
-    console.error(`\n  ✗ ${e?.message || e}\n`);
+    reportCliError(e);
+    process.exit(1);
+  }
+} else if (command === 'connections' || command === 'connection') {
+  try {
+    await runConnections(rest);
+  } catch (e) {
+    reportCliError(e);
     process.exit(1);
   }
 } else if (command === 'deploy') {
   try {
     await runDeploy(parseDeployArgs(rest));
   } catch (e) {
-    console.error(`\n  ✗ ${e?.message || e}\n`);
+    reportCliError(e);
     process.exit(1);
   }
 } else if (command === 'dockerize') {
   try {
     await runDockerize(rest);
   } catch (e) {
-    console.error(`\n  ✗ ${e?.message || e}\n`);
+    reportCliError(e);
     process.exit(1);
   }
 } else if (command === 'cad') {
   try {
     await runCad(rest);
   } catch (e) {
-    console.error(`\n  ✗ ${e?.message || e}\n`);
+    reportCliError(e);
     process.exitCode = 1;
   }
 } else if (command === 'security' || command === 'sca') {
   await runSecurity(rest);
+} else if (command === 'skills' || command === 'skill') {
+  try {
+    runSkills(rest);
+  } catch (e) {
+    reportCliError(e);
+    process.exitCode = 1;
+  }
 } else if (command === 'merkle') {
   await runMerkle(rest);
 } else if (command === 'deploy-receipt') {
@@ -367,14 +489,14 @@ if (command === '--version' || command === '-v') {
   try {
     await runMini(rest);
   } catch (e) {
-    console.error(`\n  ${e?.message || e}\n`);
+    reportCliError(e);
     process.exitCode = 1;
   }
 } else if (['index', 'search', 'repo'].includes(command)) {
   try {
     const commands = await import('./commands/knowledge.js');
     await ({ index: commands.runKnowledge, search: commands.runSearch, repo: commands.runRepository })[command](rest);
-  } catch (e) { console.error(e.message); process.exitCode = 1; }
+  } catch (e) { reportCliError(e); process.exitCode = 1; }
 } else if (command === 'init') {
   try {
     const existing = !rest.includes('--name') && (rest.includes('.') || rest.includes('--existing') || rest.includes('--cwd') || fs.existsSync(path.join(repositoryRoot(), '.git')));
@@ -382,21 +504,21 @@ if (command === '--version' || command === '-v') {
     else if (rest.includes('--help') || rest.includes('-h')) printHelp();
     else if (rest.some((a) => a.startsWith('--'))) await initFromArgs(rest);
     else await initInteractive({});
-  } catch (e) { console.error(e.message); process.exitCode = 1; }
+  } catch (e) { reportCliError(e); process.exitCode = 1; }
 } else if (command === 'identity') {
   const sub = rest[0];
   if (sub === 'preview') {
     try {
       await runIdentityPreview(rest.slice(1));
     } catch (e) {
-      console.error(`\n  ✗ ${e?.message || e}\n`);
+      reportCliError(e);
       process.exit(1);
     }
   } else if (sub === 'init') {
     try {
       await runIdentityInit(rest);
     } catch (e) {
-      console.error(`\n  ✗ ${e?.message || e}\n`);
+      reportCliError(e);
       process.exit(1);
     }
   } else {

package/src/cloudflare/cpu-profile.js

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function number(value) { const n = Number(value ?? 0); return Number.isFinite(n) && n >= 0 ? n : 0; }
+
+function parseProfile(value) {
+  if (typeof value === 'string') return JSON.parse(value);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('Cloudflare CPU profile must be a Chrome .cpuprofile object');
+  return value;
+}
+
+function frameOf(node = {}) {
+  const frame = node.callFrame || {};
+  return {
+    node_id: node.id,
+    function: clean(frame.functionName) || '(anonymous)',
+    url: clean(frame.url) || null,
+    line: Number.isInteger(frame.lineNumber) && frame.lineNumber >= 0 ? frame.lineNumber + 1 : null,
+    column: Number.isInteger(frame.columnNumber) && frame.columnNumber >= 0 ? frame.columnNumber + 1 : null,
+  };
+}
+
+export function summarizeCloudflareCpuProfile(value, options = {}) {
+  const profile = parseProfile(value);
+  if (!Array.isArray(profile.nodes) || !Array.isArray(profile.samples)) throw new TypeError('CPU profile requires nodes[] and samples[]');
+  const deltas = Array.isArray(profile.timeDeltas) ? profile.timeDeltas : [];
+  const byId = new Map(profile.nodes.map((node) => [node.id, node]));
+  const totals = new Map();
+  let totalUs = 0;
+  for (let index = 0; index < profile.samples.length; index += 1) {
+    const id = profile.samples[index];
+    const deltaUs = number(deltas[index]);
+    totalUs += deltaUs;
+    totals.set(id, (totals.get(id) || 0) + deltaUs);
+  }
+  if (!totalUs && Number.isFinite(profile.endTime) && Number.isFinite(profile.startTime)) totalUs = Math.max(0, Number(profile.endTime) - Number(profile.startTime));
+  const maxFrames = Number.isInteger(options.maxFrames) && options.maxFrames > 0 ? Math.min(options.maxFrames, 100) : 25;
+  const frames = [...totals.entries()].map(([id, selfUs]) => {
+    const frame = frameOf(byId.get(id));
+    return Object.freeze({
+      ...frame,
+      self_us: selfUs,
+      self_ms: selfUs / 1000,
+      percent: totalUs > 0 ? (selfUs / totalUs) * 100 : 0,
+      garbage_collection: /(?:garbage collector|\bgc\b)/i.test(frame.function),
+    });
+  }).sort((a, b) => b.self_us - a.self_us).slice(0, maxFrames);
+  return Object.freeze({
+    schema_version: 1,
+    profile_kind: 'chrome-cpu-profile',
+    samples: profile.samples.length,
+    total_profile_us: totalUs,
+    total_profile_ms: totalUs / 1000,
+    top_frames: Object.freeze(frames),
+    garbage_collection_ms: frames.filter((row) => row.garbage_collection).reduce((sum, row) => sum + row.self_ms, 0),
+    timer_semantics: 'Deployed Workers timers do not advance during CPU-only execution; use local workerd/DevTools CPU profiles plus production CPU metrics.',
+  });
+}
+
+function within(root, file) { return file === root || file.startsWith(`${root}${path.sep}`); }
+
+export function summarizeCloudflareCpuProfileFile(input = {}) {
+  const cwd = path.resolve(input.cwd || process.cwd());
+  const file = path.resolve(cwd, clean(input.file));
+  if (!clean(input.file)) throw new TypeError('cpu profile file is required');
+  if (!within(cwd, file)) throw new Error('cpu_profile_outside_cwd');
+  const stat = fs.statSync(file);
+  if (!stat.isFile()) throw new Error('cpu_profile_not_file');
+  if (stat.size > 64 * 1024 * 1024) throw new Error('cpu_profile_too_large');
+  return Object.freeze({ file: path.relative(cwd, file) || path.basename(file), ...summarizeCloudflareCpuProfile(fs.readFileSync(file, 'utf8'), input) });
+}
+
+function sourceItems(cwd, sources = [], maxChars = 24_000) {
+  const rows = [];
+  let chars = 0;
+  for (const source of sources.slice(0, 12)) {
+    const file = path.resolve(cwd, String(source));
+    if (!within(cwd, file) || !fs.existsSync(file) || !fs.statSync(file).isFile()) continue;
+    const text = fs.readFileSync(file, 'utf8');
+    const excerpt = text.slice(0, Math.min(8_000, Math.max(0, maxChars - chars)));
+    if (!excerpt) break;
+    rows.push(Object.freeze({ ref: `file:${path.relative(cwd, file)}`, chars: excerpt.length, content: excerpt }));
+    chars += excerpt.length;
+    if (chars >= maxChars) break;
+  }
+  return Object.freeze(rows);
+}
+
+export function buildCloudflareCpuAuditPacket(input = {}) {
+  const cwd = path.resolve(input.cwd || process.cwd());
+  const profile = input.profile ? summarizeCloudflareCpuProfile(input.profile, input) : summarizeCloudflareCpuProfileFile({ ...input, cwd });
+  return Object.freeze({
+    schema_version: 1,
+    primitive: 'cloudflare.cpu.audit',
+    rules: Object.freeze({ read_only: true, may_edit: false, may_deploy: false, production_timer_cpu_measurement_valid: false }),
+    profile,
+    source_evidence: sourceItems(cwd, input.sources || [], Number(input.maxSourceChars || 24_000)),
+    questions: Object.freeze([
+      'Which frames dominate self CPU time?',
+      'Is garbage collection material?',
+      'Which source changes are most likely to reduce CPU without changing behavior?',
+      'What local production-like request should reproduce the hotspot?',
+      'What production metric/log evidence should confirm improvement?',
+    ]),
+  });
+}
+
+export async function runCloudflareCpuAudit(input = {}) {
+  if (typeof input.reasoner !== 'function') throw new TypeError('cloudflare.cpu.audit requires an injected reasoner(packet) function');
+  const packet = buildCloudflareCpuAuditPacket(input);
+  const result = await input.reasoner(structuredClone(packet));
+  if (!result || typeof result !== 'object' || Array.isArray(result)) throw new TypeError('cloudflare.cpu.audit reasoner must return an object');
+  return Object.freeze({ schema_version: 1, primitive: 'cloudflare.cpu.audit', profile: packet.profile, analysis: result });
+}

package/src/cloudflare/index.js

@@ -0,0 +1,14 @@
+export {
+  WRANGLER_NATIVE_COMMANDS,
+  WRANGLER_OPERATION_FAMILIES,
+  buildWranglerInvocation,
+  listWranglerNativeCommands,
+  parseWranglerErrorEvidence,
+  runWranglerNative,
+} from './wrangler.js';
+export {
+  summarizeCloudflareCpuProfile,
+  summarizeCloudflareCpuProfileFile,
+  buildCloudflareCpuAuditPacket,
+  runCloudflareCpuAudit,
+} from './cpu-profile.js';