@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

package/src/acp/runs.js

@@ -0,0 +1,125 @@
+import { randomUUID } from 'node:crypto';
+import { appendAgentRunEvent, createLocalQueueControl } from './dependencies.js';
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function object(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+/**
+ * Create a portable root AgentSam run and schedule it as an agent.run job.
+ *
+ * This is a control-plane operation only. It does not call a model. A runtime
+ * consumer later claims the queued job and performs execution.
+ */
+export async function createRootRun(database, {
+  runId = null,
+  accountId = null,
+  conversationId = null,
+  objective = '',
+  role = 'lead',
+  mode = 'agent',
+  modelKey = null,
+  reasoningEffort = null,
+  serviceTier = null,
+  runtimeRequirements = {},
+  metadata = {},
+  priority = 'normal',
+  sourceClient = 'agentsam-acp',
+  surface = 'control-plane',
+} = {}) {
+  if (!database || typeof database.prepare !== 'function') {
+    throw new TypeError('database with prepare() is required');
+  }
+
+  const id = clean(runId) || `arun_${randomUUID()}`;
+  const account = clean(accountId) || 'local';
+  const now = Math.floor(Date.now() / 1000);
+  const resolvedMode = clean(mode) || 'agent';
+  const resolvedRole = clean(role) || 'lead';
+  const resolvedObjective = clean(objective);
+  const requirements = object(runtimeRequirements);
+  const meta = object(metadata);
+
+  await database.prepare(`
+    INSERT INTO agentsam_agent_run (
+      id, account_id, conversation_id, source_client, surface, mode, model_key,
+      reasoning_effort, requested_service_tier, selected_by, status,
+      created_at_unix, updated_at_unix
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'automatic', 'queued', ?, ?)
+  `).bind(
+    id,
+    account,
+    clean(conversationId) || null,
+    clean(sourceClient) || 'agentsam-acp',
+    clean(surface) || 'control-plane',
+    resolvedMode,
+    clean(modelKey) || null,
+    clean(reasoningEffort) || null,
+    clean(serviceTier) || null,
+    now,
+    now,
+  ).run();
+
+  await appendAgentRunEvent(database, {
+    runId: id,
+    eventType: 'run.created',
+    phase: 'boot',
+    label: 'Agent run created',
+    evidence: {
+      objective: resolvedObjective || null,
+      role: resolvedRole,
+      runtime_requirements: requirements,
+    },
+    dedupeKey: `root:${id}:created`,
+    createdAt: now,
+  });
+
+  await appendAgentRunEvent(database, {
+    runId: id,
+    eventType: 'run.queued',
+    phase: 'boot',
+    label: 'Agent run queued',
+    evidence: { role: resolvedRole },
+    dedupeKey: `root:${id}:queued`,
+    createdAt: now,
+  });
+
+  const queueControl = createLocalQueueControl(database);
+  const queued = await queueControl.enqueue(
+    {
+      kind: 'agent.run',
+      account_id: account,
+      priority,
+      payload: {
+        run_id: id,
+        parent_run_id: null,
+        objective: resolvedObjective || null,
+        role: resolvedRole,
+        runtime_requirements: requirements,
+        metadata: meta,
+      },
+    },
+    {
+      id: `job_agent_run_${id}`,
+      account_id: account,
+      source_run_id: id,
+      conversation_id: clean(conversationId) || null,
+      idempotency_key: `agent-run:${id}`,
+      priority,
+      metadata: meta,
+    },
+  );
+
+  return {
+    schema: 'agentsam.run-start.v1',
+    run_id: id,
+    status: 'queued',
+    queue: queued.plan?.physical_queue || null,
+    queue_job: queued.job,
+    published: queued.published,
+  };
+}

package/src/acp/runtime-selection.js

@@ -0,0 +1,180 @@
+import { capabilitiesSatisfy, RUNTIME_PROTOCOL_SCHEMA } from '../../packages/runtime-protocol/src/index.js';
+
+const DEFAULT_RUNNABLE_STATUSES = Object.freeze(['ready', 'online', 'sleeping']);
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function stringList(value) {
+  if (Array.isArray(value)) return value.map(clean).filter(Boolean);
+  const one = clean(value);
+  return one ? [one] : [];
+}
+
+export function normalizeRequiredCapabilities(value = {}) {
+  if (Array.isArray(value)) {
+    return Object.freeze(Object.fromEntries(value.map(clean).filter(Boolean).map((key) => [key, true])));
+  }
+  if (!value || typeof value !== 'object') return Object.freeze({});
+  return Object.freeze(Object.fromEntries(
+    Object.entries(value).map(([key, enabled]) => [clean(key), Boolean(enabled)]).filter(([key]) => key),
+  ));
+}
+
+export function normalizeRuntimeRequirements(value = {}) {
+  const input = value && typeof value === 'object' ? value : {};
+  const exact = {};
+  for (const field of [
+    'provider',
+    'substrate',
+    'provider_product',
+    'lifecycle',
+    'runtime_adapter',
+    'architecture',
+    'os',
+    'transport',
+    'auth_mode',
+  ]) {
+    const resolved = clean(input[field]);
+    if (resolved) exact[field] = resolved;
+  }
+
+  return Object.freeze({
+    schema: 'agentsam.runtime-requirements.v1',
+    exact: Object.freeze(exact),
+    capabilities: normalizeRequiredCapabilities(input.capabilities),
+    statuses: Object.freeze(
+      stringList(input.statuses ?? input.status).length
+        ? stringList(input.statuses ?? input.status)
+        : [...DEFAULT_RUNNABLE_STATUSES],
+    ),
+    preferredProviders: Object.freeze(stringList(input.preferred_providers ?? input.preferredProviders)),
+    preferredSubstrates: Object.freeze(stringList(input.preferred_substrates ?? input.preferredSubstrates)),
+  });
+}
+
+function unwrapRuntime(candidate) {
+  if (candidate?.runtime && typeof candidate.runtime === 'object') {
+    return { id: clean(candidate.id || candidate.runtime_id || candidate.runtime.id) || null, runtime: candidate.runtime };
+  }
+  return { id: clean(candidate?.id || candidate?.runtime_id) || null, runtime: candidate || {} };
+}
+
+export function matchRuntimeCandidate(candidate, requirements = {}) {
+  const normalized = requirements?.schema === 'agentsam.runtime-requirements.v1'
+    ? requirements
+    : normalizeRuntimeRequirements(requirements);
+  const { id, runtime } = unwrapRuntime(candidate);
+  const mismatches = [];
+
+  if (runtime.schema && runtime.schema !== RUNTIME_PROTOCOL_SCHEMA) {
+    mismatches.push({ field: 'schema', required: RUNTIME_PROTOCOL_SCHEMA, actual: runtime.schema });
+  }
+
+  for (const [field, required] of Object.entries(normalized.exact)) {
+    if (clean(runtime[field]) !== required) {
+      mismatches.push({ field, required, actual: clean(runtime[field]) || null });
+    }
+  }
+
+  const capabilityMatch = capabilitiesSatisfy(normalized.capabilities, runtime.capabilities || {});
+  for (const missing of capabilityMatch.missing) {
+    mismatches.push({ field: 'capabilities.' + missing, required: true, actual: runtime.capabilities?.[missing] ?? false });
+  }
+
+  if (normalized.statuses.length && !normalized.statuses.includes(clean(runtime.status))) {
+    mismatches.push({
+      field: 'status',
+      required: normalized.statuses,
+      actual: clean(runtime.status) || null,
+    });
+  }
+
+  return Object.freeze({
+    ok: mismatches.length === 0,
+    id,
+    runtime,
+    mismatches: Object.freeze(mismatches),
+    missingCapabilities: Object.freeze(capabilityMatch.missing),
+  });
+}
+
+function preferenceIndex(list, value) {
+  const index = list.indexOf(clean(value));
+  return index === -1 ? Number.MAX_SAFE_INTEGER : index;
+}
+
+function readinessIndex(status) {
+  const value = clean(status);
+  if (value === 'ready') return 0;
+  if (value === 'online') return 1;
+  if (value === 'sleeping') return 2;
+  return 3;
+}
+
+/**
+ * Hard-filter using agentsam.runtime.v1, then apply only explicit preferences.
+ * There is no cloud-provider-specific hidden score.
+ */
+export function selectRuntimeCandidate(candidates = [], requirements = {}) {
+  const normalized = normalizeRuntimeRequirements(requirements);
+  const evaluations = candidates.map((candidate, index) => ({
+    index,
+    candidate,
+    match: matchRuntimeCandidate(candidate, normalized),
+  }));
+  const eligible = evaluations.filter((row) => row.match.ok);
+
+  eligible.sort((a, b) => {
+    const ap = preferenceIndex(normalized.preferredProviders, a.match.runtime.provider);
+    const bp = preferenceIndex(normalized.preferredProviders, b.match.runtime.provider);
+    if (ap !== bp) return ap - bp;
+
+    const as = preferenceIndex(normalized.preferredSubstrates, a.match.runtime.substrate);
+    const bs = preferenceIndex(normalized.preferredSubstrates, b.match.runtime.substrate);
+    if (as !== bs) return as - bs;
+
+    const ar = readinessIndex(a.match.runtime.status);
+    const br = readinessIndex(b.match.runtime.status);
+    if (ar !== br) return ar - br;
+
+    const aid = a.match.id || '';
+    const bid = b.match.id || '';
+    if (aid && bid && aid !== bid) return aid.localeCompare(bid);
+    return a.index - b.index;
+  });
+
+  if (!eligible.length) {
+    const error = new Error('runtime_unavailable');
+    error.code = 'runtime_unavailable';
+    error.requirements = normalized;
+    error.diagnostics = evaluations.map(({ match }) => ({
+      id: match.id,
+      provider: match.runtime.provider ?? null,
+      substrate: match.runtime.substrate ?? null,
+      status: match.runtime.status ?? null,
+      mismatches: match.mismatches,
+    }));
+    throw error;
+  }
+
+  const selected = eligible[0].match;
+  return Object.freeze({
+    schema: 'agentsam.runtime-selection.v1',
+    runtime_id: selected.id,
+    runtime: selected.runtime,
+    requirements: normalized,
+    eligible_count: eligible.length,
+    rejected_count: evaluations.length - eligible.length,
+  });
+}
+
+export function createRuntimeSelector({ listRuntimes } = {}) {
+  if (typeof listRuntimes !== 'function') throw new TypeError('listRuntimes function is required');
+  return async function resolveRuntime(requirements = {}, context = {}) {
+    const candidates = await listRuntimes(context);
+    if (!Array.isArray(candidates)) throw new TypeError('runtime registry must return an array');
+    return selectRuntimeCandidate(candidates, requirements);
+  };
+}

package/src/agent/responses-runner.js

@@ -7,6 +7,11 @@ import { searchToolCards, hydrateToolSchemas } from '../tools/index.js';
 import { createAgentEvent } from '../telemetry/index.js';
 import { diagnosticFromError } from '../errors/index.js';
 import { runAgentSamModelTurn } from './model-turn.js';
+import {
+  createHookedCapabilityAdapter,
+  createHookedProviderAdapter,
+  ensureHookRuntime,
+} from '../../packages/agentsam-hooks/src/index.js';
 
 const RUNTIME_OWNED_KEYS = new Set(['account_id', 'user_id', 'tenant_id', 'workspace_id', 'connection_id', 'runtime_lease_id', 'execution_id']);
 
@@ -229,7 +234,7 @@ function toolOutputInput(outputs) {
   }));
 }
 
-export async function runAgentSamTurn(options = {}) {
+async function runAgentSamTurnCore(options = {}) {
   const provider = options.provider;
   if (!provider?.create || !provider?.continueWithToolOutputs) throw new TypeError('Responses provider adapter is required');
   if (!options.capabilityAdapter) throw new TypeError('capabilityAdapter is required');
@@ -615,5 +620,144 @@ export async function runAgentSamTurn(options = {}) {
   });
 }
 
+function hookInvocation(options = {}) {
+  return {
+    session_id: options.sessionId,
+    run_id: options.runId,
+    turn_id: options.turnId,
+    message_id: options.messageId,
+    agent_id: options.agentId,
+    source: options.source || 'agentsam-sdk',
+    metadata: options.hookMetadata,
+  };
+}
+
+/**
+ * Provider-neutral AgentSam turn with optional lifecycle instrumentation.
+ *
+ * Passing `hookRuntime` (or a plain `hooks` registry) instruments the model
+ * and capability adapters without teaching the orchestration loop any
+ * provider, MCP, LSP, or sub-agent wire format. An agent_stop hook may request
+ * another bounded turn; continuation reuses provider state and cumulative
+ * usage instead of constructing a hidden second session.
+ */
+export async function runAgentSamTurn(options = {}) {
+  const hookSource = options.hookRuntime || options.hooks;
+  if (!hookSource) return runAgentSamTurnCore(options);
+
+  const hooks = ensureHookRuntime(hookSource);
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const invocation = hookInvocation(options);
+  const submitted = await hooks.dispatch('user_prompt_submitted', {
+    prompt: clean(options.prompt),
+    cwd,
+  }, invocation, { cwd });
+  const submittedPrompt = clean(submitted.input.prompt);
+  if (!submittedPrompt) throw new TypeError('prompt is required');
+  const transformed = await hooks.dispatch('user_prompt_transformed', {
+    original_prompt: clean(options.prompt),
+    transformed_prompt: submittedPrompt,
+    cwd,
+  }, invocation, { cwd });
+  const prompt = clean(transformed.input.transformed_prompt);
+  if (!prompt) throw new TypeError('transformed prompt is required');
+  const additionalContext = [submitted.output.additional_context, transformed.output.additional_context]
+    .filter(Boolean).join('\n\n');
+  const instrumented = {
+    ...options,
+    prompt,
+    provider: createHookedProviderAdapter(options.provider, {
+      hookRuntime: hooks,
+      invocation,
+      cwd,
+      requestPermission: options.requestPermission,
+      maxRetries: options.maxHookRetries,
+    }),
+    capabilityAdapter: createHookedCapabilityAdapter(options.capabilityAdapter, {
+      hookRuntime: hooks,
+      invocation,
+      cwd,
+      requestPermission: options.requestPermission,
+      maxRetries: options.maxHookRetries,
+    }),
+    ...(additionalContext && options.instructions != null
+      ? { instructions: [String(options.instructions), additionalContext].filter(Boolean).join('\n\n') }
+      : {}),
+    ...(additionalContext && options.instructions == null
+      ? {
+          contextItems: [
+            ...(options.contextItems || []),
+            { kind: 'hook', ref: 'hook://user-prompt/context', priority: 95, content: additionalContext },
+          ],
+        }
+      : {}),
+  };
+
+  const maxContinuations = Number.isInteger(options.maxHookContinuations)
+    ? Math.max(0, Math.min(options.maxHookContinuations, 8))
+    : 4;
+  const continuationReceipts = [];
+  let current = instrumented;
+  let result;
+  let totalCost = 0;
+  let totalRounds = 0;
+  let totalCalls = 0;
+  let totalElapsedMs = 0;
+  let hookContinuations = 0;
+  const costBreakdown = { input: 0, cached_input: 0, cache_write: 0, output: 0 };
+  const allToolReceipts = [];
+  const allContinuationCompactions = [];
+
+  for (let continuationIndex = 0; ; continuationIndex += 1) {
+    result = await runAgentSamTurnCore(current);
+    totalCost += Number(result.total_cost_usd || 0);
+    totalRounds += Number(result.run_budget?.tool_rounds || 0);
+    totalCalls += Number(result.run_budget?.tool_calls || 0);
+    totalElapsedMs += Number(result.run_budget?.elapsed_ms || 0);
+    for (const key of Object.keys(costBreakdown)) costBreakdown[key] += Number(result.cost_breakdown_usd?.[key] || 0);
+    allToolReceipts.push(...(result.tool_receipts || []));
+    allContinuationCompactions.push(...(result.continuation_compactions || []));
+    const stopped = await hooks.dispatch('agent_stop', {
+      stop_reason: result.output_text ? 'completed' : 'no_output',
+      stop_hook_active: continuationIndex > 0,
+      output_text: result.output_text,
+      continuation_index: continuationIndex,
+      run_budget: result.run_budget,
+    }, invocation, { cwd });
+    continuationReceipts.push(...stopped.receipts);
+    if (stopped.output.decision !== 'block') break;
+    if (continuationIndex >= maxContinuations) throw new Error(`hook_continuation_limit_exceeded:${maxContinuations}`);
+    const reason = clean(stopped.output.reason);
+    if (!reason) throw new Error('hook_continuation_reason_required');
+    hookContinuations += 1;
+    current = {
+      ...instrumented,
+      prompt: reason,
+      previousProviderState: result.provider_state,
+      previousUsageSnapshot: result.usage_snapshot,
+      cumulativeUsage: result.cumulative_usage,
+    };
+  }
+
+  return Object.freeze({
+    ...result,
+    ...(submitted.output.suppress_output === true || transformed.output.suppress_output === true
+      ? { output_text: '', suppressed_by_hook: true } : {}),
+    total_cost_usd: totalCost,
+    cost_breakdown_usd: Object.freeze(costBreakdown),
+    tool_receipts: Object.freeze(allToolReceipts),
+    continuation_compactions: Object.freeze(allContinuationCompactions),
+    run_budget: Object.freeze({
+      ...result.run_budget,
+      tool_rounds: totalRounds,
+      tool_calls: totalCalls,
+      elapsed_ms: totalElapsedMs,
+      hook_continuations: hookContinuations,
+      max_hook_continuations: maxContinuations,
+    }),
+    hook_receipts: Object.freeze([...submitted.receipts, ...transformed.receipts, ...continuationReceipts]),
+  });
+}
+
 /** @deprecated Use runAgentSamTurn(). */
 export const runResponsesAgent = runAgentSamTurn;

package/src/cli/command-catalog.js

@@ -16,6 +16,8 @@ export const CLI_COMMAND_CATALOG = Object.freeze([
   { id: 'machine', summary: 'Deterministic local machine perception (inspect / asset discovery)', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'machine.inspect', common: true },
   { id: 'engine', summary: 'Discover, audit, benchmark, and govern local AI engines', topic: 'runtime', skill: 'agentsam-app-fundamentals', operation: 'engine.audit', common: true },
   { id: 'package', summary: 'Audit, verify, and plan publication of distributable packages', topic: 'work', skill: 'agentsam-progression-guard', operation: 'package.audit', common: true, usage: ['agentsam package audit [--public] [--offline] [--json]', 'agentsam package status <name> [--offline] [--json]', 'agentsam package verify <name> [--offline] [--json]', 'agentsam package publish-plan [--offline] [--json]'] },
+  { id: 'merch', summary: 'Preflight designs against portable manufacturing profiles', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'merch.preflight', common: true, usage: ['agentsam merch profiles', 'agentsam merch build <manifest.json> [--all-compatible]'] },
+  { id: 'receipts', summary: 'Inspect receipt proofs and prune ephemeral AgentSam workdirs', topic: 'runtime', skill: 'agentsam-progression-guard', operation: 'receipts.inspect', common: true, usage: ['agentsam receipts list [--limit 20] [--repo <id>]', 'agentsam receipts show <receipt-id>', 'agentsam receipts failures [--repo <id>]', 'agentsam receipts prune [--max-tmp-gb 1.0] [--dry-run]'] },
   { id: 'capabilities', summary: 'Inspect capability contracts', topic: 'create', skill: 'agentsam-app-fundamentals' },
   {
     id: 'setup',
@@ -47,6 +49,7 @@ export const CLI_COMMAND_CATALOG = Object.freeze([
   },
   { id: 'db', summary: 'Project-local SQLite status/init', topic: 'runtime', skill: 'agentsam-app-fundamentals' },
   { id: 'models', summary: 'Probe hosted/local model availability', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },
+  { id: 'hooks', aliases: ['hook'], summary: 'Inspect lifecycle hooks, sources, and execution receipts', topic: 'runtime', skill: 'agentsam-app-fundamentals', common: true, usage: ['agentsam hooks status', 'agentsam hooks list', 'agentsam hooks executions [--limit N]', 'agentsam hooks init'] },
   { id: 'providers', summary: 'Configure machine provider credentials', topic: 'start', skill: 'agentsam-app-fundamentals' },
   { id: 'credentials', aliases: ['credential'], summary: 'Audit credentials, drift, and failure remediation (never prints secrets)', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },
   { id: 'cheat-sheet', aliases: ['cheatsheet'], summary: 'Organized command groups (gcloud-like)', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },
@@ -105,6 +108,7 @@ export const CLI_COMMAND_CATALOG = Object.freeze([
   { id: 'autorag', summary: 'AutoRAG configure/probe helpers', topic: 'work', skill: 'agentsam-codebaseindex' },
   { id: 'identity', summary: 'Identity portal, providers, protocol surfaces', topic: 'create', skill: 'agentsam-app-fundamentals' },
   { id: 'scaffold', summary: 'Generate CMS or worker-api starter', topic: 'create', skill: 'agentsam-jr-dev' },
+  { id: 'run', aliases: ['runs'], summary: 'Inspect and control AgentSam runs across local or hosted control planes', topic: 'work', skill: 'agentsam-app-fundamentals' },
   { id: 'goap', summary: 'GOAP blackboard status/plan', topic: 'inside', skill: 'agentsam-app-fundamentals' },
   { id: 'app', aliases: ['apps'], summary: 'Bundled AgentSam apps launcher', topic: 'create', skill: 'agentsam-app-fundamentals' },
 ]);

package/src/cli.js

@@ -33,6 +33,8 @@ import { runMerkle } from './commands/merkle.js';
 import { runDeployReceipt } from './commands/deploy-receipt.js';
 import { runSecurity } from './commands/security.js';
 import { runPackage } from './commands/package.js';
+import { runMerch } from './commands/merch.js';
+import { runReceipts } from './commands/receipts.js';
 import { runRecon } from './commands/recon.js';
 import { runCad } from './commands/cad.js';
 import { runMachine } from './commands/machine.js';
@@ -52,12 +54,14 @@ import { runLogin, runLogout } from './commands/account-auth.js';
 import { runPlugins } from './commands/plugins.js';
 import { runCredentials } from './commands/credentials.js';
 import { runCheatSheet } from './commands/cheat-sheet.js';
+import { runHooks } from './commands/hooks.js';
 import { runCompute } from './commands/compute.js';
 import { runGoogleCloud } from './commands/google-cloud.js';
 import { runBilling } from './commands/billing.js';
 import { runUpdate } from './commands/update.js';
 import { runSetup } from './commands/setup.js';
 import { runRuntime } from './commands/runtime.js';
+import { runRun } from './commands/run.js';
 import { applyPresetSelection, runAdd, runCapabilities, runDev, runInspect } from './commands/product.js';
 import { listPresets, resolvePreset } from './presets/index.js';
 import {
@@ -503,6 +507,14 @@ if (command === '--version' || command === '-v') {
     reportCliError(e);
     process.exit(1);
   }
+} else if (command === 'hooks' || command === 'hook') {
+  try {
+    const code = await runHooks(rest);
+    if (typeof code === 'number' && code !== 0) process.exitCode = code;
+  } catch (e) {
+    reportCliError(e);
+    process.exitCode = 1;
+  }
 } else if (command === 'app' || command === 'apps') {
   try {
     await runApp(rest);
@@ -615,6 +627,13 @@ if (command === '--version' || command === '-v') {
     if (!e?.reported) reportCliError(e);
     process.exitCode = 1;
   }
+} else if (command === 'run' || command === 'runs') {
+  try {
+    await runRun(rest);
+  } catch (e) {
+    if (!e?.reported) reportCliError(e);
+    process.exitCode = 1;
+  }
 } else if (command === 'rust' || command === 'wasm' || command === 'rapid-rust') {
   try {
     await runRust(rest);
@@ -747,6 +766,20 @@ if (command === '--version' || command === '-v') {
     reportCliError(e);
     process.exitCode = 1;
   }
+} else if (command === 'merch') {
+  try {
+    await runMerch(rest);
+  } catch (e) {
+    reportCliError(e);
+    process.exitCode = 1;
+  }
+} else if (command === 'receipts') {
+  try {
+    await runReceipts(rest);
+  } catch (e) {
+    reportCliError(e);
+    process.exitCode = 1;
+  }
 } else if (command === 'security' || command === 'sca') {
   await runSecurity(rest);
 } else if (command === 'skills') {

package/src/commands/cheat-sheet.js

@@ -75,6 +75,7 @@ const GROUPS = Object.freeze([
     label: 'AI',
     commands: [
       ['models', 'Hosted + local model probes'],
+      ['hooks', 'Lifecycle sources, dispatch order, and receipts'],
       ['skills', 'Portable skill vocabulary'],
       ['context', 'Context economics + git bridge'],
       ['usage / session', 'Spend and resume receipts'],

package/src/commands/cloudflare-login.js

@@ -16,7 +16,7 @@ import {
   getCloudflareFeaturePack,
   scopesForFeaturePacks,
   scopesForCapabilities,
-} from '../../packages/connectors/cloudflare/src/index.js';
+} from '../../packages/connectors/cfoa/src/index.js';
 
 function clean(value) {
   return value == null ? '' : String(value).trim();

package/src/commands/cloudflare.js

@@ -21,8 +21,8 @@ import {
   tokenValidation,
   pages,
   snippets,
-} from '../../packages/connectors/cloudflare/src/index.js';
-import { AGENTSAM_TAG_VOCABULARY as TAG_VOCAB } from '../../packages/connectors/cloudflare/src/families/tags.js';
+} from '../../packages/connectors/cfoa/src/index.js';
+import { AGENTSAM_TAG_VOCABULARY as TAG_VOCAB } from '../../packages/connectors/cfoa/src/families/tags.js';
 import {
   isCloudflareLoginFamily,
   runCloudflareBrowserOAuthLogin,

package/src/commands/connections.js

@@ -7,7 +7,7 @@ import {
   CLOUDFLARE_FIXTURE_CLIENT_ID,
   cloudflareConnectionSafeStatus,
   resolveCloudflareOAuthClient,
-} from '../../packages/connectors/cloudflare/src/index.js';
+} from '../../packages/connectors/cfoa/src/index.js';
 import { resolveIamIssuer } from '../../packages/identity/src/contracts/auth-config.js';
 import { collectRuntimeStatus } from './runtime-status.js';