@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.0

package/src/cli.js

@@ -15,6 +15,7 @@ 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';
@@ -30,14 +31,26 @@ 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 { resolveSdkKey } from '../packages/identity/src/contracts/auth-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 {
@@ -76,7 +89,13 @@ function printHelp() {
     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 models            Show configured providers and local model inventory
+    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
@@ -143,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;
 }
@@ -206,7 +227,7 @@ async function runLocalInit(config) {
     console.log(`    ${step}`);
   }
 
-  const sdkKey = resolveSdkKey(process.env);
+  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(sdkKey, prompt);
@@ -262,12 +283,12 @@ async function initInteractive(partial = {}) {
   if (runTarget !== 'local') {
     const { detectContext, missingForInit } = await import('./lib/detect-context.js');
     const ctx = await detectContext();
-    if (missingForInit(ctx, resolveSdkKey(process.env), { runTarget }).length) {
+    if (missingForInit(ctx, resolveAccountSdkKey({ env: process.env }).value, { runTarget }).length) {
       printContextSummary(ctx);
     }
   }
 
-  const prompt = resolveSdkKey(process.env) ? createPrompt() : null;
+  const prompt = resolveAccountSdkKey({ env: process.env }).value ? createPrompt() : null;
   try {
     await runLocalInit({ projectName, lane: laneKey, runTarget, prompt });
   } finally {
@@ -297,7 +318,7 @@ if (command === '--version' || command === '-v') {
     try { await runInteractive(); }
     catch (e) {
       if (e?.code !== 'AGENTSAM_SETUP_CANCELLED') {
-        console.error(`\n  ✗ ${e?.message || e}\n`);
+        reportCliError(e);
         process.exitCode = 1;
       }
     }
@@ -315,52 +336,94 @@ 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 === 'models') {
   try {
     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') {
@@ -369,35 +432,42 @@ if (command === '--version' || command === '-v') {
   try {
     await runOllama(rest);
   } catch (e) {
-    console.error(`\n  ✗ ${e?.message || e}\n`);
+    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') {
@@ -406,7 +476,7 @@ if (command === '--version' || command === '-v') {
   try {
     runSkills(rest);
   } catch (e) {
-    console.error(`\n  ✗ ${e?.message || e}\n`);
+    reportCliError(e);
     process.exitCode = 1;
   }
 } else if (command === 'merkle') {
@@ -419,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')));
@@ -434,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';

package/src/cloudflare/wrangler.js

@@ -0,0 +1,132 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { runProcess } from '../security/process.js';
+import { AgentSamDiagnosticError, redactDiagnosticValue } from '../errors/index.js';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function positiveInteger(value, fallback) { const n = Number(value); return Number.isInteger(n) && n > 0 ? n : fallback; }
+
+export const WRANGLER_NATIVE_COMMANDS = Object.freeze([
+  Object.freeze({ id: 'whoami', argv: ['whoami', '--json'], risk: 'read', output: 'json', description: 'Read authenticated Cloudflare user/account membership without exposing the auth token.' }),
+  Object.freeze({ id: 'deployments.list', argv: ['deployments', 'list', '--json'], risk: 'read', output: 'json', description: 'List recent Worker deployments.' }),
+  Object.freeze({ id: 'versions.list', argv: ['versions', 'list', '--json'], risk: 'read', output: 'json', description: 'List recent Worker versions.' }),
+  Object.freeze({ id: 'types.check', argv: ['types', '--check'], risk: 'read', output: 'text', description: 'Check generated Worker binding/runtime types without rewriting them.' }),
+  Object.freeze({ id: 'queues.list', argv: ['queues', 'list'], risk: 'read', output: 'text', description: 'List Workers Queues visible to the active Cloudflare identity.' }),
+]);
+
+export const WRANGLER_OPERATION_FAMILIES = Object.freeze([
+  Object.freeze({ family: 'identity', examples: ['whoami', 'auth list', 'auth activate'], default_risk: 'read/config' }),
+  Object.freeze({ family: 'development', examples: ['dev', 'types --check'], default_risk: 'local-runtime' }),
+  Object.freeze({ family: 'observability', examples: ['tail --format json', 'deployments list', 'versions list'], default_risk: 'read/stream' }),
+  Object.freeze({ family: 'delivery', examples: ['deploy', 'versions deploy', 'rollback'], default_risk: 'remote-write' }),
+  Object.freeze({ family: 'data', examples: ['d1', 'r2', 'kv', 'queues', 'hyperdrive', 'vectorize'], default_risk: 'read-or-remote-write' }),
+  Object.freeze({ family: 'compute', examples: ['containers', 'browser', 'ai', 'workflows'], default_risk: 'read-or-remote-write' }),
+]);
+
+export function listWranglerNativeCommands() { return WRANGLER_NATIVE_COMMANDS.map((row) => ({ ...row, argv: [...row.argv] })); }
+
+function descriptor(id) {
+  const row = WRANGLER_NATIVE_COMMANDS.find((item) => item.id === clean(id));
+  if (!row) throw new RangeError(`unsupported_wrangler_native_command:${id}`);
+  return row;
+}
+
+function resolveConfig(cwd, explicit = '') {
+  if (clean(explicit)) {
+    const file = path.resolve(cwd, explicit);
+    if (!file.startsWith(`${cwd}${path.sep}`) && file !== cwd) throw new Error('cloudflare_config_outside_cwd');
+    if (!fs.existsSync(file)) throw new Error(`cloudflare_config_not_found:${explicit}`);
+    return file;
+  }
+  for (const name of ['wrangler.jsonc', 'wrangler.json', 'wrangler.toml']) {
+    const file = path.join(cwd, name);
+    if (fs.existsSync(file)) return file;
+  }
+  return '';
+}
+
+export function buildWranglerInvocation(id, input = {}) {
+  const row = descriptor(id);
+  const cwd = path.resolve(input.cwd || process.cwd());
+  const args = [...row.argv];
+  if (id === 'whoami' && clean(input.account)) args.push('--account', clean(input.account));
+  if ((id === 'deployments.list' || id === 'versions.list') && clean(input.name)) args.push('--name', clean(input.name));
+  if (id === 'types.check' && clean(input.path)) args.splice(1, 0, clean(input.path));
+  if (id === 'queues.list' && input.page != null) args.push('--page', String(positiveInteger(input.page, 1)));
+  const config = resolveConfig(cwd, input.config);
+  if (config) args.push('--config', config);
+  if (clean(input.env)) args.push('--env', clean(input.env));
+  if (clean(input.profile)) args.push('--profile', clean(input.profile));
+  return Object.freeze({ command_id: row.id, command: 'wrangler', args: Object.freeze(args), cwd, risk: row.risk, output: row.output });
+}
+
+function parseJsonOutput(text) {
+  const source = clean(text);
+  if (!source) return null;
+  try { return JSON.parse(source); } catch { return null; }
+}
+
+function stripAnsi(value) { return String(value || '').replace(/\x1b\[[0-?]*[ -\/]*[@-~]/g, ''); }
+function nestedError(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  const rows = [payload.error, ...(Array.isArray(payload.errors) ? payload.errors : [])].filter((row) => row && typeof row === 'object');
+  return rows[0] || payload;
+}
+
+export function parseWranglerErrorEvidence(stderr = '', stdout = '') {
+  const errorText = stripAnsi(stderr);
+  const outputText = stripAnsi(stdout);
+  let payload = parseJsonOutput(outputText) || parseJsonOutput(errorText);
+  const error = nestedError(payload);
+  const combined = `${errorText}\n${outputText}`;
+  const regexCode = combined.match(/\[code:\s*([A-Za-z0-9_.:-]+)\]/i)?.[1] || combined.match(/\bcode[:=\s]+([A-Za-z0-9_.:-]+)/i)?.[1] || '';
+  const code = clean(error?.code || regexCode) || null;
+  const requestId = clean(error?.request_id || error?.requestId || combined.match(/\brequest[_ -]?id[:=\s]+([A-Za-z0-9_-]+)/i)?.[1]) || null;
+  const rayId = clean(error?.ray_id || error?.rayId || combined.match(/\b(?:cf[- ]?ray|ray id)[:=\s]+([A-Za-z0-9-]+)/i)?.[1]) || null;
+  const message = clean(error?.message || error?.error || errorText.split('\n').find((line) => clean(line)) || outputText.split('\n').find((line) => clean(line))) || 'Wrangler operation failed';
+  return Object.freeze({ code, request_id: requestId, ray_id: rayId, message, details: payload ? redactDiagnosticValue(payload) : null });
+}
+
+export async function runWranglerNative(id, input = {}, options = {}) {
+  const plan = buildWranglerInvocation(id, input);
+  const runner = options.run || runProcess;
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : 30_000;
+  const result = await runner(options.bin || 'npx', ['--yes', 'wrangler', ...plan.args], {
+    cwd: plan.cwd,
+    timeoutMs,
+    signal: options.signal,
+    maxBytes: options.maxBytes || 2 * 1024 * 1024,
+  });
+  if (result.code !== 0) {
+    const evidence = parseWranglerErrorEvidence(result.stderr, result.stdout);
+    throw new AgentSamDiagnosticError({
+      source: 'cloudflare',
+      kind: 'wrangler_error',
+      code: evidence.code || 'wrangler_exit_nonzero',
+      message: evidence.message || `Wrangler ${plan.command_id} exited ${result.code}`,
+      retriable: false,
+      retry_strategy: 'inspect_error',
+      operation: plan.command_id,
+      exit_code: result.code,
+      request_id: evidence.request_id,
+      ray_id: evidence.ray_id,
+      cwd: plan.cwd,
+      stderr: redactDiagnosticValue(String(result.stderr || '').slice(0, 12_000)) || null,
+      stdout: redactDiagnosticValue(String(result.stdout || '').slice(0, 4_000)) || null,
+      details: evidence.details,
+    });
+  }
+  const parsed = plan.output === 'json' ? parseJsonOutput(result.stdout) : null;
+  return Object.freeze({
+    ok: true,
+    schema_version: 1,
+    command_id: plan.command_id,
+    risk: plan.risk,
+    cwd: plan.cwd,
+    exit_code: result.code,
+    format: parsed == null ? 'text' : 'json',
+    data: parsed == null ? undefined : redactDiagnosticValue(parsed),
+    stdout: parsed == null ? String(result.stdout || '').slice(0, 24_000) : undefined,
+    stderr: String(result.stderr || '').slice(0, 8_000) || undefined,
+  });
+}

package/src/commands/account-auth.js

@@ -0,0 +1,47 @@
+import { authenticateViaBrowser } from '../lib/auth.js';
+import { clearAccountSession, readAccountSession, saveAccountSession } from '../lib/account-session.js';
+import { collectWhoami, renderWhoami } from './whoami.js';
+
+function writeLine(write, value = '') { write(`${value}\n`); }
+
+export async function runLogin(argv = [], options = {}) {
+  const allowed = new Set(['--json']);
+  const unknown = argv.filter((arg) => !allowed.has(arg));
+  if (unknown.length) throw new Error(`unknown login option: ${unknown[0]}`);
+  const write = options.write || ((text) => process.stdout.write(text));
+  const authenticate = options.authenticateImpl || authenticateViaBrowser;
+  const session = await authenticate();
+  if (!String(session?.access_token || '').trim().startsWith('sdk_')) throw new Error('Agent Sam login did not return a valid SDK session');
+  // authenticateViaBrowser persists by default. Keep injected transports/test flows equivalent.
+  if (!readAccountSession({ home: options.home })) saveAccountSession(session, { home: options.home });
+  const status = await collectWhoami({ home: options.home, env: options.env || process.env, contextLoader: options.contextLoader });
+  if (argv.includes('--json')) writeLine(write, JSON.stringify(status, null, 2));
+  else {
+    writeLine(write, '');
+    writeLine(write, '  Agent Sam login complete.');
+    write(renderWhoami(status));
+  }
+  return status;
+}
+
+export function runLogout(argv = [], options = {}) {
+  const allowed = new Set(['--json']);
+  const unknown = argv.filter((arg) => !allowed.has(arg));
+  if (unknown.length) throw new Error(`unknown logout option: ${unknown[0]}`);
+  const write = options.write || ((text) => process.stdout.write(text));
+  const removed = clearAccountSession({ home: options.home });
+  const result = {
+    schema_version: 1,
+    local_session_removed: removed,
+    provider_credentials_unchanged: true,
+    note: 'Local IAM session removed. Provider credentials were not deleted or revoked.',
+  };
+  if (argv.includes('--json')) writeLine(write, JSON.stringify(result, null, 2));
+  else {
+    writeLine(write, '');
+    writeLine(write, removed ? '  Signed out of the local Agent Sam IAM session.' : '  No local Agent Sam IAM session was stored.');
+    writeLine(write, '  Provider credentials were not deleted or revoked.');
+    writeLine(write, '');
+  }
+  return result;
+}

package/src/commands/cloudflare.js

@@ -0,0 +1,58 @@
+import path from 'node:path';
+import { listWranglerNativeCommands, runWranglerNative, summarizeCloudflareCpuProfileFile, WRANGLER_OPERATION_FAMILIES } from '../cloudflare/index.js';
+import { renderDiagnosticError } from '../errors/index.js';
+
+function parse(argv = []) {
+  const subcommand = argv[0] || 'status';
+  const takesAction = subcommand === 'run' || subcommand === 'cpu';
+  const out = { subcommand, action: takesAction ? (argv[1] || '') : '', cwd: process.cwd(), json: false, name: '', account: '', config: '', env: '', profile: '', path: '', page: null, file: '' };
+  for (let i = takesAction ? 2 : 1; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') out.json = true;
+    else if (arg === '--cwd') out.cwd = argv[++i] || out.cwd;
+    else if (arg === '--name') out.name = argv[++i] || '';
+    else if (arg === '--account') out.account = argv[++i] || '';
+    else if (arg === '--config') out.config = argv[++i] || '';
+    else if (arg === '--env') out.env = argv[++i] || '';
+    else if (arg === '--profile') out.profile = argv[++i] || '';
+    else if (arg === '--path') out.path = argv[++i] || '';
+    else if (arg === '--page') out.page = Number(argv[++i] || 1);
+    else if (arg === '--file') out.file = argv[++i] || '';
+    else if (arg === '--help' || arg === '-h') out.help = true;
+    else if (out.subcommand === 'cpu' && out.action === 'analyze' && !out.file) out.file = arg;
+    else throw new Error(`unknown cloudflare option: ${arg}`);
+  }
+  return out;
+}
+
+const help = `Agent Sam · Cloudflare\n\n  agentsam cloudflare status [--cwd PATH] [--json]\n  agentsam cloudflare commands [--json]\n  agentsam cloudflare run <whoami|deployments.list|versions.list|types.check|queues.list> [options] [--json]\n  agentsam cloudflare cpu analyze <profile.cpuprofile> [--cwd PATH] [--json]\n\nSafe native runner is read-only. Deploy, rollback, secret reads, D1 mutation, R2 writes, and long-running tail/dev sessions remain explicit operator actions.\n`;
+
+export async function runCloudflare(argv = [], options = {}) {
+  const args = parse(argv);
+  if (options.cwd && !argv.includes('--cwd')) args.cwd = path.resolve(options.cwd);
+  const write = options.write || ((value) => process.stdout.write(value));
+  if (args.help) { write(help); return null; }
+  try {
+    let result;
+    if (args.subcommand === 'status') {
+      result = await runWranglerNative('whoami', args, options);
+    } else if (args.subcommand === 'commands') {
+      result = { schema_version: 1, native: listWranglerNativeCommands(), families: WRANGLER_OPERATION_FAMILIES };
+    } else if (args.subcommand === 'run') {
+      if (!args.action) throw new Error('cloudflare native command id required');
+      result = await runWranglerNative(args.action, args, options);
+    } else if (args.subcommand === 'cpu' && args.action === 'analyze') {
+      result = summarizeCloudflareCpuProfileFile({ cwd: path.resolve(args.cwd), file: args.file });
+    } else {
+      write(help);
+      return null;
+    }
+    write(args.json ? `${JSON.stringify(result)}\n` : `${JSON.stringify(result, null, 2)}\n`);
+    return result;
+  } catch (error) {
+    if (args.json) write(`${JSON.stringify({ ok: false, error: error?.diagnostic || { code: error?.code || 'cloudflare_operation_failed', message: error?.message || String(error) } })}\n`);
+    else write(`${renderDiagnosticError(error)}\n`);
+    error.reported = true;
+    throw error;
+  }
+}