@inneranimalmedia/agentsam-sdk 2.6.10 → 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/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',
@@ -106,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';
@@ -59,6 +61,7 @@ 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 {
@@ -624,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);
@@ -756,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/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';
 

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/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