@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

package/src/commands/go.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { cancel, confirm, intro, isCancel, outro, select } from '@clack/prompts';
+import { cancel, confirm, intro, isCancel, outro, select, text } from '@clack/prompts';
 import pc from 'picocolors';
 import {
   DEFAULT_PRODUCT,
@@ -32,6 +32,7 @@ function parse(argv = []) {
     skipDeploy: false,
     skipRegistry: false,
     accountId: null,
+    receiptRoot: null,
     officialRelease: false,
     yes: false,
     help: false,
@@ -48,6 +49,7 @@ function parse(argv = []) {
     else if (arg === '--official-release') out.officialRelease = true;
     else if (arg === '--yes' || arg === '-y') out.yes = true;
     else if (arg === '--account') out.accountId = String(argv[++i] || '').trim() || null;
+    else if (arg === '--receipt-root') out.receiptRoot = String(argv[++i] || '').trim() || null;
     else if (arg === '--cwd') out.cwd = path.resolve(argv[++i] || out.cwd);
     else if (arg === '--cloudflare') {
       out.cloudflare = true;
@@ -106,6 +108,7 @@ const HELP = `Agent Sam · Go
 
   Flags:
     --account <id>       Explicit Cloudflare account target
+    --receipt-root <path>  Base directory for AgentSam Go receipts/state
     --yes, -y            Confirm a live non-interactive deployment
     --json               Machine-readable output
     --dry-run            Build/probe + Wrangler dry-run; no live deploy or InnerAnimalMedia registry write
@@ -180,9 +183,13 @@ export async function runGo(argv = [], options = {}) {
 
   const discovery = discoverGoRuntime(args.cwd);
   const productRoot = resolveProductRoot(discovery, args.product);
-  const stateRoot = options.stateRoot
+
+  let stateRoot = options.stateRoot
     ? path.resolve(options.stateRoot)
-    : resolveGoStateRoot(discovery, args.cwd);
+    : args.receiptRoot
+      ? path.resolve(args.cwd, args.receiptRoot)
+      : resolveGoStateRoot(discovery, args.cwd);
+
   const runtimeRoot = discovery.runtime?.runtimeRoot || path.join(productRoot, 'runtime');
 
   if (args.subcommand === 'menu' && process.stdout.isTTY && !args.json) {
@@ -485,7 +492,7 @@ async function shipCloudflare({ discovery, productRoot, stateRoot, runtimeRoot,
   }
 
   const preflight = preflightToolchain({
-    requireDocker: !args.skipDeploy,
+    requireDocker: !args.skipDeploy && !args.dryRun,
     productRoot,
   });
   for (const check of preflight.checks) {
@@ -519,7 +526,7 @@ async function shipCloudflare({ discovery, productRoot, stateRoot, runtimeRoot,
   note('✓ native runtime boot/probe/shutdown');
 
   let container = null;
-  if (!args.skipDeploy) {
+  if (!args.skipDeploy && !args.dryRun) {
     if (!args.json) write('\n  Container\n');
     container = await verifyGoContainer({
       productRoot,
@@ -634,6 +641,62 @@ async function shipCloudflare({ discovery, productRoot, stateRoot, runtimeRoot,
 
 async function runInteractiveMenu({ discovery, productRoot, stateRoot, runtimeRoot, args, write }) {
   intro(pc.bgCyan(pc.black(' Agent Sam · Go ')));
+
+  const receiptChoice = await select({
+    message: 'Where should AgentSam Go store run receipts?',
+    options: [
+      {
+        value: 'project',
+        label: 'This project',
+        hint: path.join(stateRoot, '.agentsam', 'go'),
+      },
+      {
+        value: 'home',
+        label: 'Central AgentSam receipts folder',
+        hint: '~/.agentsam/receipts',
+      },
+      {
+        value: 'custom',
+        label: 'Choose another folder',
+      },
+    ],
+  });
+
+  if (isCancel(receiptChoice)) {
+    cancel('Cancelled.');
+    return { ok: false, cancelled: true };
+  }
+
+  if (receiptChoice === 'home') {
+    stateRoot = path.join(
+      process.env.HOME || process.env.USERPROFILE || stateRoot,
+      '.agentsam',
+      'receipts',
+      path.basename(path.resolve(args.cwd)),
+    );
+  } else if (receiptChoice === 'custom') {
+    const customRoot = await text({
+      message: 'Receipt/state base directory',
+      placeholder: '/path/to/agentsam-receipts',
+      validate(value) {
+        return String(value || '').trim()
+          ? undefined
+          : 'Enter a directory.';
+      },
+    });
+
+    if (isCancel(customRoot)) {
+      cancel('Cancelled.');
+      return { ok: false, cancelled: true };
+    }
+
+    stateRoot = path.resolve(
+      String(customRoot).replace(/^~(?=\/|$)/, process.env.HOME || '~'),
+    );
+  }
+
+  write(`\n  Receipts\n    ${path.join(stateRoot, '.agentsam', 'go')}\n`);
+
   const status = readLatestStatus(stateRoot);
   write(`\n  Runtime\n`);
   write(`    ${discovery.go?.ok ? '✓' : '✗'} Go ${discovery.go?.goversion || ''}\n`);
@@ -671,7 +734,14 @@ async function runInteractiveMenu({ discovery, productRoot, stateRoot, runtimeRo
     return { ok: false, cancelled: true };
   }
   outro(`Running ${action}`);
-  const forwarded = [action, args.product, '--cwd', args.cwd];
+  const forwarded = [
+    action,
+    args.product,
+    '--cwd',
+    args.cwd,
+    '--receipt-root',
+    stateRoot,
+  ];
   if (action === 'deploy') forwarded.push('--cloudflare');
   if (args.json) forwarded.push('--json');
   return runGo(forwarded, { write });

package/src/commands/hooks.js

@@ -0,0 +1,260 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  HOOK_CONFIG_SCHEMA,
+  createHookRuntime,
+  createHookRuntimeFromConfig,
+  findHookConfig,
+  loadHookConfig,
+  registerStoredHooks,
+} from '../../packages/agentsam-hooks/src/index.js';
+import { findCliProjectRoot } from '../lib/cli-preferences.js';
+import { readAccountSession } from '../lib/account-session.js';
+import {
+  listRuntimeHooks,
+  listRuntimeHookExecutions,
+  recordRuntimeHookReceipt,
+  setRuntimeHookActive,
+} from '../local/runtime-store.js';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function writeLine(write, value = '') { write(`${value}\n`); }
+function countConfigured(config) {
+  return Object.values(config?.hooks || {}).reduce((sum, rows) => sum + rows.length, 0);
+}
+
+function registerCodeHooks(runtime, hooks = {}) {
+  for (const [event, definitions] of Object.entries(hooks || {})) {
+    for (const definition of Array.isArray(definitions) ? definitions : [definitions]) {
+      if (typeof definition === 'function') {
+        runtime.register(event, { handler: definition, metadata: { hook_source: 'code' } });
+      } else {
+        runtime.register(event, {
+          ...definition,
+          metadata: { ...(definition?.metadata || {}), hook_source: 'code' },
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Resolve code, project config, and stored definitions into one ordered runtime.
+ * The source changes authoring/ownership only; dispatch semantics stay identical.
+ */
+export async function createProjectHookRuntime(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const projectRoot = path.resolve(options.projectRoot || findCliProjectRoot(cwd));
+  const accountId = clean(options.ownerId || readAccountSession({ home: options.home })?.account_id) || 'local';
+  const sourceByHook = new Map();
+  const persistReceipts = options.persistReceipts !== false;
+  const runtime = createHookRuntime({
+    clock: options.clock,
+    async onReceipt(receipt) {
+      const definition = sourceByHook.get(`${receipt.hook}:${receipt.hook_id}`) || { source: 'code', stored_hook_id: null };
+      if (persistReceipts) {
+        await recordRuntimeHookReceipt({
+          projectRoot,
+          owner_id: accountId,
+          receipt,
+          source_kind: definition.source,
+          hook_id: definition.stored_hook_id,
+          session_id: options.sessionId,
+          conversation_id: options.conversationId,
+        });
+      }
+      if (typeof options.onReceipt === 'function') await options.onReceipt(receipt);
+    },
+  });
+
+  registerCodeHooks(runtime, options.hooks);
+  const configFile = options.configFile || findHookConfig(cwd, { stopAt: projectRoot });
+  let config = null;
+  if (configFile) {
+    ({ config } = createHookRuntimeFromConfig(configFile, {
+      runtime,
+      cwd,
+      env: options.env,
+      fetchImpl: options.fetchImpl,
+      restrictCommandCwd: options.restrictCommandCwd,
+    }));
+  }
+
+  const stored = await registerStoredHooks(runtime, {
+    listHooks: (query) => listRuntimeHooks({
+      projectRoot,
+      owner_id: accountId,
+      ...query,
+    }),
+  }, {
+    cwd: projectRoot,
+    env: options.env,
+    fetchImpl: options.fetchImpl,
+    restrictCommandCwd: options.restrictCommandCwd,
+    resolveHandler: options.resolveHandler,
+    context: {
+      owner_id: accountId,
+      account_id: accountId,
+      project_id: options.projectId,
+      project_root: projectRoot,
+      repository_id: options.repositoryId,
+      session_id: options.sessionId,
+    },
+  });
+
+  for (const definition of runtime.list()) {
+    sourceByHook.set(`${definition.hook}:${definition.id}`, {
+      source: clean(definition.metadata?.hook_source) || (definition.metadata?.stored_hook_id ? 'stored' : definition.metadata?.config_source ? 'config' : 'code'),
+      stored_hook_id: clean(definition.metadata?.stored_hook_id) || null,
+    });
+  }
+  return Object.freeze({
+    runtime,
+    owner_id: accountId,
+    project_root: projectRoot,
+    config,
+    config_file: configFile || null,
+    stored,
+    definitions: runtime.list(),
+  });
+}
+
+function hookTemplate() {
+  return {
+    schema: HOOK_CONFIG_SCHEMA,
+    adapters: {},
+    hooks: {},
+  };
+}
+
+function parseLimit(argv, fallback = 30) {
+  const index = argv.indexOf('--limit');
+  if (index === -1) return fallback;
+  const value = Number(argv[index + 1]);
+  if (!Number.isInteger(value) || value < 1 || value > 500) throw new Error('hooks_limit_must_be_between_1_and_500');
+  return value;
+}
+
+function renderHookRows(rows, write) {
+  if (!rows.length) {
+    writeLine(write, '  No hooks configured. Run `agentsam hooks init` or add a stored hook.');
+    return;
+  }
+  for (const row of rows) {
+    const source = clean(row.metadata?.hook_source || row.source_kind) || 'code';
+    const state = row.enabled === false || row.is_active === false ? 'disabled' : 'active';
+    const handler = clean(row.handler_type || row.metadata?.adapter) || 'callback';
+    writeLine(write, `  ${String(row.hook || row.event_type).padEnd(25)} ${String(row.id || row.hook_key).padEnd(28)} ${source.padEnd(7)} ${handler.padEnd(10)} ${state} · p${row.priority ?? 100}`);
+  }
+}
+
+export async function runHooks(argv = [], options = {}) {
+  const write = options.write || ((text) => process.stdout.write(text));
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const projectRoot = findCliProjectRoot(cwd);
+  const jsonOutput = argv.includes('--json');
+  const command = argv.find((arg) => !arg.startsWith('-')) || 'status';
+  if (argv.includes('--help') || argv.includes('-h') || command === 'help') {
+    write([
+      'agentsam hooks [status|list|executions|validate|init|enable|disable] [--json]',
+      '',
+      'One hook concept, three authoring sources: code, project config, and stored rows.',
+      '  status                  Show active sources and execution evidence',
+      '  list                    Show the merged dispatch order with source badges',
+      '  executions [--limit N]  Show recent value-free receipts',
+      '  validate [config]       Validate a portable hook config',
+      '  init                    Create .agentsam/hooks.json (idempotent)',
+      '  enable|disable <key>    Toggle a stored hook without editing code/config',
+      '',
+    ].join('\n'));
+    return 0;
+  }
+
+  if (command === 'init') {
+    const filename = path.join(projectRoot, '.agentsam', 'hooks.json');
+    fs.mkdirSync(path.dirname(filename), { recursive: true });
+    const created = !fs.existsSync(filename);
+    if (created) fs.writeFileSync(filename, `${JSON.stringify(hookTemplate(), null, 2)}\n`, { mode: 0o600 });
+    const loaded = loadHookConfig(filename);
+    const result = { ok: true, created, source: filename, schema: loaded.schema };
+    if (jsonOutput) writeLine(write, JSON.stringify(result, null, 2));
+    else writeLine(write, `  Hooks config ready · ${filename}`);
+    return result;
+  }
+
+  if (command === 'validate') {
+    const commandIndex = argv.indexOf(command);
+    const candidate = argv.slice(commandIndex + 1).find((arg) => !arg.startsWith('-'));
+    const filename = candidate || findHookConfig(cwd, { stopAt: projectRoot });
+    if (!filename) throw new Error('agentsam_hook_config_not_found');
+    const config = loadHookConfig(filename);
+    const result = { ok: true, schema: config.schema, source: config.source, adapters: Object.keys(config.adapters).length, hooks: countConfigured(config) };
+    if (jsonOutput) writeLine(write, JSON.stringify(result, null, 2));
+    else writeLine(write, `  Valid · ${result.hooks} hooks · ${result.adapters} adapters · ${result.source}`);
+    return result;
+  }
+
+  const ownerId = clean(options.ownerId || readAccountSession({ home: options.home })?.account_id) || 'local';
+  if (command === 'enable' || command === 'disable') {
+    const key = argv[argv.indexOf(command) + 1];
+    if (!key || key.startsWith('-')) throw new Error(`hooks_${command}_requires_key`);
+    const changed = await setRuntimeHookActive({ projectRoot, owner_id: ownerId, hook_key: key, active: command === 'enable' });
+    if (!changed) throw new Error(`stored_hook_not_found:${key}`);
+    const result = { ok: true, hook_key: key, active: command === 'enable' };
+    if (jsonOutput) writeLine(write, JSON.stringify(result, null, 2));
+    else writeLine(write, `  ${key} → ${result.active ? 'enabled' : 'disabled'}`);
+    return result;
+  }
+
+  if (command === 'executions') {
+    const executions = await listRuntimeHookExecutions({ projectRoot, owner_id: ownerId, limit: parseLimit(argv) });
+    if (jsonOutput) writeLine(write, JSON.stringify({ schema: 'agentsam.hook.executions.v1', executions }, null, 2));
+    else {
+      writeLine(write, '\n  Recent hook executions');
+      if (!executions.length) writeLine(write, '  No hook receipts recorded yet.');
+      for (const row of executions) {
+        const at = new Date(Number(row.ran_at_unix) * 1000).toISOString();
+        writeLine(write, `  ${at} ${String(row.status).padEnd(9)} ${String(row.event_type).padEnd(24)} ${row.hook_key} · ${row.duration_ms}ms`);
+      }
+      writeLine(write);
+    }
+    return executions;
+  }
+
+  if (!['status', 'list'].includes(command)) throw new Error(`unknown_hooks_command:${command}`);
+  const resolved = await createProjectHookRuntime({
+    cwd,
+    projectRoot,
+    ownerId,
+    home: options.home,
+    hooks: options.hooks,
+    persistReceipts: false,
+  });
+  const storedAll = await listRuntimeHooks({ projectRoot, owner_id: ownerId, activeOnly: false });
+  const result = {
+    schema: 'agentsam.hooks.status.v1',
+    project_root: projectRoot,
+    owner_id: ownerId,
+    config: resolved.config ? { source: resolved.config_file, hooks: countConfigured(resolved.config), adapters: Object.keys(resolved.config.adapters).length } : null,
+    sources: {
+      code: resolved.definitions.filter((row) => row.metadata?.hook_source === 'code').length,
+      config: resolved.definitions.filter((row) => row.metadata?.hook_source === 'config').length,
+      stored_active: resolved.definitions.filter((row) => row.metadata?.hook_source === 'stored').length,
+      stored_total: storedAll.length,
+    },
+    hooks: resolved.definitions,
+  };
+  if (jsonOutput) writeLine(write, JSON.stringify(result, null, 2));
+  else {
+    writeLine(write, '\n  Agent Sam · hooks');
+    writeLine(write, '  One ordered lifecycle contract · code is read-only · config/stored hooks are portable.');
+    writeLine(write, `  project  ${projectRoot}`);
+    writeLine(write, `  config   ${result.config ? `${result.config.hooks} hooks · ${result.config.source}` : 'not configured'}`);
+    writeLine(write, `  stored   ${result.sources.stored_active} active · ${result.sources.stored_total} total`);
+    writeLine(write, '');
+    if (command === 'list') renderHookRows([...resolved.definitions, ...storedAll.filter((row) => !row.is_active)], write);
+    else writeLine(write, '  Use `agentsam hooks list` for dispatch order and `agentsam hooks executions` for receipts.');
+    writeLine(write);
+  }
+  return result;
+}

package/src/commands/merch.js

@@ -0,0 +1,5 @@
+import { runMerchCli } from "../../packages/agentsam-merch/src/cli.js";
+
+export async function runMerch(args = []) {
+  return runMerchCli(args);
+}

package/src/commands/mini.js

@@ -7,7 +7,7 @@ export function printMiniHelp() {
   console.log(`
   agentsam mini — small local gadgets and prototypes
 
-  agentsam mini <name>                      Create and preview a timer gadget
+  agentsam mini <name>                      Create and preview a small interactive prototype
   agentsam mini <name> --template page       Create and preview a simple page
   agentsam mini <name> --template data       Create and preview a JSON viewer
   agentsam mini <name> --write-only          Create files without starting anything

package/src/commands/models.js

@@ -17,7 +17,7 @@ export const API_PROVIDERS = Object.freeze([
   { id: 'openai', label: 'OpenAI', credential: 'OPENAI_API_KEY' },
   { id: 'anthropic', label: 'Anthropic', credential: 'ANTHROPIC_API_KEY' },
   { id: 'gemini', label: 'Gemini', credential: 'GEMINI_API_KEY' },
-  { id: 'grok', label: 'Grok / xAI', credential: 'XAI_API_KEY' },
+  { id: 'xai', label: 'Grok / xAI', credential: 'XAI_API_KEY' },
   { id: 'cursor', label: 'Cursor', credential: 'CURSOR_API_KEY' },
   { id: 'cloudflare', label: 'Cloudflare', credential: 'CLOUDFLARE_API_TOKEN' },
 ]);

package/src/commands/receipts.js

@@ -0,0 +1,140 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  pruneLocalWorkspaces,
+  validateReceiptEnvelope,
+} from "../receipts/index.js";
+
+function intFlag(args, flag, fallback) {
+  const index = args.indexOf(flag);
+  const value = index >= 0 ? Number.parseInt(args[index + 1], 10) : NaN;
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function numberFlag(args, flag, fallback) {
+  const index = args.indexOf(flag);
+  const value = index >= 0 ? Number(args[index + 1]) : NaN;
+  return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+function stringFlag(args, flag) {
+  const index = args.indexOf(flag);
+  return index >= 0 && args[index + 1] ? args[index + 1] : null;
+}
+
+async function readLocalReceipts(directory) {
+  const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+  const receipts = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    try {
+      const value = JSON.parse(
+        await readFile(path.join(directory, entry.name), "utf8"),
+      );
+      if (validateReceiptEnvelope(value).ok) receipts.push(value);
+    } catch {}
+  }
+  receipts.sort(
+    (a, b) =>
+      Number(b.metrics?.created_at_unix || 0) -
+      Number(a.metrics?.created_at_unix || 0),
+  );
+  return receipts;
+}
+
+function writeSummary(receipt) {
+  const date = new Date(
+    Number(receipt.metrics?.created_at_unix || 0) * 1000,
+  ).toISOString();
+  process.stdout.write(
+    [
+      receipt.receipt_id,
+      receipt.status,
+      receipt.kind,
+      date,
+      receipt.identity?.repository_id || "-",
+    ].join("\t") + "\n",
+  );
+}
+
+export async function runReceipts(args = [], options = {}) {
+  const [command = "list", ...rest] = args;
+  const localDir =
+    options.localDir ||
+    stringFlag(rest, "--dir") ||
+    path.join(process.cwd(), ".agentsam", "receipts");
+
+  if (command === "prune") {
+    const result = await pruneLocalWorkspaces({
+      maxTmpGb: numberFlag(rest, "--max-tmp-gb", 1),
+      dryRun: rest.includes("--dry-run"),
+    });
+    if (rest.includes("--json")) {
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    } else {
+      process.stdout.write(
+        "Scanned " +
+          result.scannedCount +
+          " AgentSam workdirs; purged " +
+          result.purgedCount +
+          "; " +
+          result.remainingBytes +
+          " bytes remain.\n",
+      );
+    }
+    return result;
+  }
+
+  const receipts = options.catalog
+    ? await options.catalog.list({
+        limit: intFlag(rest, "--limit", 20),
+        repositoryId: stringFlag(rest, "--repo"),
+        status: command === "failures" ? "failed" : undefined,
+      })
+    : await readLocalReceipts(localDir);
+
+  if (command === "show") {
+    const id = rest.find((arg) => !arg.startsWith("--"));
+    if (!id) throw new Error("agentsam receipts show requires a receipt id");
+    const receipt = options.catalog
+      ? await options.catalog.get(id)
+      : receipts.find((item) => item.receipt_id === id);
+    if (!receipt) {
+      const error = new Error("Receipt not found: " + id);
+      error.code = "AGENTSAM_RECEIPT_NOT_FOUND";
+      throw error;
+    }
+    process.stdout.write(JSON.stringify(receipt, null, 2) + "\n");
+    return receipt;
+  }
+
+  if (!["list", "failures"].includes(command)) {
+    throw new Error(
+      "Usage: agentsam receipts list [--limit 20] [--repo <id>]\n" +
+        "       agentsam receipts show <receipt-id>\n" +
+        "       agentsam receipts failures [--repo <id>]\n" +
+        "       agentsam receipts prune [--max-tmp-gb 1.0] [--dry-run]",
+    );
+  }
+
+  const repo = stringFlag(rest, "--repo");
+  const limit = intFlag(rest, "--limit", 20);
+  const filtered = receipts
+    .filter((receipt) => !repo || receipt.identity?.repository_id === repo)
+    .filter((receipt) => command !== "failures" || receipt.status === "failed")
+    .slice(0, limit);
+
+  if (rest.includes("--json")) {
+    process.stdout.write(JSON.stringify(filtered, null, 2) + "\n");
+  } else {
+    if (!options.catalog) {
+      process.stderr.write(
+        "  source: local receipt cache (" +
+          localDir +
+          "); durable D1 catalog requires a host catalog adapter\n",
+      );
+    }
+    for (const receipt of filtered) writeSummary(receipt);
+  }
+  return filtered;
+}