@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/src/commands/machine.js

@@ -0,0 +1,137 @@
+/**
+ * agentsam machine — graduate the native Machine engine to the product CLI.
+ *
+ * Graduation rule: capability is complete when reachable through
+ * `agentsam machine …`, emits bounded deterministic receipts, and preserves evidence.
+ *
+ * Asset perception rule: discovery is read-only and network-free by default.
+ */
+
+import path from 'node:path';
+import { resolveMachineBinary, spawnMachine } from './machine-binary.js';
+
+function usage() {
+  return `agentsam machine — deterministic local perception (native engine)
+
+Usage:
+  agentsam machine inspect <path> [--json] [--run-id <id>] [--include-generated]
+  agentsam machine doctor [--json]
+  agentsam machine --help
+
+Notes:
+  Default inspect is read-only and network-free.
+  Large detail is externalized under <target>/.agentsam/machine/runs/<run_id>/.
+  Generated/cache trees are summarized unless --include-generated is set.
+  Remote fetch/probe, optimization, storage, and reference rewriting are separate explicit actions.
+  Set AGENTSAM_MACHINE_BIN to force a specific agentsam-machine binary.`;
+}
+
+function parseArgs(argv = []) {
+  const out = {
+    help: false,
+    json: false,
+    includeGenerated: false,
+    runId: null,
+    subcommand: null,
+    target: null,
+    positionals: [],
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') out.help = true;
+    else if (arg === '--json') out.json = true;
+    else if (arg === '--include-generated') out.includeGenerated = true;
+    else if (arg === '--run-id') {
+      const value = argv[++i];
+      if (value == null || value.startsWith('--')) {
+        throw new Error('--run-id requires a value');
+      }
+      out.runId = value;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`unknown machine option: ${arg}`);
+    } else {
+      out.positionals.push(arg);
+    }
+  }
+  out.subcommand = out.positionals[0] || null;
+  out.target = out.positionals[1] || null;
+  return out;
+}
+
+function printTextDoctor(resolution) {
+  if (resolution.kind === 'binary') {
+    console.log(`agentsam-machine available (${resolution.source}): ${resolution.path}`);
+    console.log('capability: machine.inspect');
+    return;
+  }
+  if (resolution.kind === 'cargo') {
+    console.log(`agentsam-machine via cargo run (${resolution.source}): ${resolution.manifest}`);
+    console.log('capability: machine.inspect (dev fallback)');
+    return;
+  }
+  console.log('agentsam-machine unavailable');
+  console.log(`tried: ${(resolution.tried || []).join(', ')}`);
+}
+
+/**
+ * @param {string[]} argv
+ */
+export async function runMachine(argv = []) {
+  const args = parseArgs(argv);
+  if (args.help || !args.subcommand) {
+    console.log(usage());
+    return 0;
+  }
+
+  const resolution = resolveMachineBinary();
+
+  if (args.subcommand === 'doctor') {
+    const payload = {
+      capability: 'machine.doctor',
+      available: resolution.kind !== 'missing',
+      resolution,
+    };
+    if (args.json) console.log(JSON.stringify(payload));
+    else printTextDoctor(resolution);
+    return resolution.kind === 'missing' ? 1 : 0;
+  }
+
+  if (args.subcommand === 'inspect') {
+    const target = args.target || process.cwd();
+    const abs = path.resolve(target);
+    const machineArgv = ['inspect', abs];
+    if (args.runId) machineArgv.push('--run-id', args.runId);
+    if (args.includeGenerated) machineArgv.push('--include-generated');
+    if (args.json) machineArgv.push('--json');
+
+    const result = spawnMachine(resolution, machineArgv, {
+      stdio: args.json ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+      // Large donors still emit bounded compact JSON; raise buffer for safety.
+      maxBuffer: 32 * 1024 * 1024,
+    });
+
+    if (result.error) throw result.error;
+    if (args.json) {
+      const stdout = String(result.stdout || '');
+      const stderr = String(result.stderr || '');
+      if (result.status && result.status !== 0) {
+        const err = new Error(stderr.trim() || `agentsam-machine exited with code ${result.status}`);
+        err.exitCode = result.status;
+        throw err;
+      }
+      try {
+        const parsed = JSON.parse(stdout);
+        console.log(JSON.stringify(parsed));
+      } catch {
+        process.stdout.write(stdout);
+      }
+      if (stderr.trim()) process.stderr.write(stderr);
+    }
+    return result.status ?? 0;
+  }
+
+  console.log(usage());
+  const err = new Error(`Unknown machine subcommand: ${args.subcommand}`);
+  err.exitCode = 1;
+  throw err;
+}

package/src/commands/mcp.js

@@ -1,19 +1,24 @@
 import {
   deleteMcpServer,
   detectInstalledClients,
+  getCloudflareMcpBundle,
   inspectClientAdapter,
-  isClientRegistered,
+  listCloudflareMcpBundles,
   listKnownServers,
   listMcpServers,
   listMcpTools,
+  listOfferableMcpServerConnections,
   listRegisteredClients,
   pingMcpServer,
   readMcpServer,
   removeServerFromClient,
   resolveServerPreset,
+  scopesForCloudflareMcpBundle,
   syncServerToClient,
   writeMcpServer,
 } from '../mcp/index.js';
+import { createMcpServerProject } from '../lib/scaffold/mcp-server.js';
+import { listMcpServerPresets } from '../lib/scaffold/templates/mcp-server/presets.js';
 
 function clean(value) {
   return value == null ? '' : String(value).trim();
@@ -32,14 +37,33 @@ export function parseMcpArgs(argv = []) {
   let token = '';
   let json = false;
   let catalog = false;
+  let bundles = false;
+  let pack = '';
+  let preset = '';
+  let output = '';
+  let issuer = '';
+  let audience = '';
+  let displayName = '';
+  let authMode = '';
+  let force = false;
 
   for (let i = 1; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--client') client = argv[++i] || '';
     else if (arg === '--url') url = argv[++i] || '';
     else if (arg === '--token') token = argv[++i] || '';
+    else if (arg === '--pack') pack = argv[++i] || '';
+    else if (arg === '--preset') preset = argv[++i] || '';
+    else if (arg === '--output' || arg === '--out') output = argv[++i] || '';
+    else if (arg === '--issuer') issuer = argv[++i] || '';
+    else if (arg === '--audience') audience = argv[++i] || '';
+    else if (arg === '--display-name') displayName = argv[++i] || '';
+    else if (arg === '--public') authMode = 'public';
+    else if (arg === '--oauth') authMode = 'oauth';
+    else if (arg === '--force') force = true;
     else if (arg === '--json') json = true;
     else if (arg === '--catalog' || arg === '--all') catalog = true;
+    else if (arg === '--bundles' || arg === '--cloudflare') bundles = true;
     else if (arg === '--help' || arg === '-h') help = true;
   }
 
@@ -49,41 +73,72 @@ export function parseMcpArgs(argv = []) {
     client: client.toLowerCase(),
     url,
     token,
+    pack: pack.toLowerCase(),
+    preset: preset.toLowerCase(),
+    output,
+    issuer,
+    audience,
+    displayName,
+    authMode,
+    force,
     json,
     catalog,
+    bundles,
     help,
   };
 }
 
 function renderHelp(options = {}) {
   const clients = listRegisteredClients(options);
-  const servers = listKnownServers(options);
-
-  const presetRows = servers.map((s) => {
-    const key = (s.name || s.server_key || '').padEnd(24);
-    const desc = s.description || s.display_name || s.health_status || '';
-    return `    ${key} ${s.url} (${desc})`;
+  const cfBundles = listCloudflareMcpBundles();
+  const offerable = listOfferableMcpServerConnections();
+  const templateRows = listMcpServerPresets().map((preset) =>
+    `    ${preset.key.padEnd(18)} ${preset.display_name}`
+  ).join('\n');
+
+  const presetRows = offerable.map((s) => {
+    const key = (s.connection_key || '').padEnd(28);
+    return `    ${key} ${s.url}`;
   }).join('\n');
 
   const clientRows = clients.map((c) => {
     const key = c.client_key.padEnd(24);
-    const note = c.notes || c.display_name;
-    return `    ${key} ${c.display_name} (${note})`;
+    return `    ${key} ${c.display_name}`;
+  }).join('\n');
+
+  const bundleRows = cfBundles.map((b) => {
+    const key = b.name.padEnd(28);
+    const packs = (b.feature_packs || []).join(',') || '—';
+    return `    ${key} packs=[${packs}]  manage=${(b.portal_manage_scopes || []).join(',')}`;
   }).join('\n');
 
   return `
-  AgentSam · MCP Client Management
+  AgentSam · MCP Factory + Client Management
 
   Usage:
+    agentsam mcp create <name> [--preset <preset>] [--output <dir>] [--issuer <url>] [--audience <url>] [--oauth|--public] [--force]
     agentsam mcp add <name> [--client <client>|all] [--url <url>] [--token <token>]
-    agentsam mcp list [--catalog|--all] [--json]
+    agentsam mcp list [--catalog|--bundles] [--json]
     agentsam mcp status [<name>] [--json]
     agentsam mcp doctor [<name>] [--json]
     agentsam mcp remove <name> [--client <client>|all]
+    agentsam mcp scopes <cloudflare-bundle> [--json]
+
+  Notes:
+    • Client adapters = IDE hosts (cursor, claude, chatgpt, agentsam).
+    • Offerable MCP server connections include every CF portal hostname (see below).
+    • CF OAuth: pick packs (agentsam, developer_platform, zero_trust, …) or pack \`all\` (~315 scopes).
+    • mcp-portals.read/write come with the agentsam pack for CF-connected portal management.
+
+  MCP server templates:
+${templateRows}
 
-  Known server presets:
+  Offerable MCP server connections:
 ${presetRows}
 
+  Cloudflare MCP bundles (granular packs):
+${bundleRows}
+
   Recognized client adapters:
 ${clientRows}
 `;
@@ -100,19 +155,68 @@ export async function runMcp(argv = [], options = {}) {
 
   const { subcommand, target } = args;
 
+  if (subcommand === 'create') {
+    if (!target) throw new Error('mcp_project_name_required');
+    const preset = args.preset || 'heuristics';
+    const result = await createMcpServerProject({
+      projectName: target,
+      preset,
+      output: args.output || target,
+      issuer: args.issuer || undefined,
+      audience: args.audience || undefined,
+      displayName: args.displayName || undefined,
+      authMode: args.authMode || undefined,
+      force: args.force,
+    }, {
+      cwd: options.cwd || process.cwd(),
+    });
+
+    if (args.json) {
+      write(JSON.stringify(result, null, 2) + '\n');
+      return result;
+    }
+
+    write(`\n  ✓ Generated MCP server: ${result.display_name}\n`);
+    write(`      preset:    ${result.preset}\n`);
+    write(`      output:    ${result.output_dir}\n`);
+    write(`      manifest:  ${result.manifest_path}\n`);
+    write(`      endpoint:  ${result.transport} ${result.endpoint_path}\n\n`);
+    return result;
+  }
+
   if (subcommand === 'list') {
+    if (args.bundles) {
+      const bundles = listCloudflareMcpBundles().map((b) => ({
+        ...b,
+        suggested_oauth_scopes: scopesForCloudflareMcpBundle(b.name),
+      }));
+      if (args.json) {
+        write(JSON.stringify({ bundles }, null, 2) + '\n');
+        return bundles;
+      }
+      write('\n  Cloudflare MCP portal bundles\n\n');
+      for (const b of bundles) {
+        write(`  • ${b.name} — ${b.display_name}\n`);
+        write(`      url:     ${b.url}\n`);
+        write(`      packs:   ${(b.feature_packs || []).join(', ') || '(portal OAuth only)'}\n`);
+        write(`      manage:  ${(b.portal_manage_scopes || []).join(', ')}\n`);
+        write(`      scopes:  ${b.suggested_oauth_scopes.slice(0, 8).join(' ')}${b.suggested_oauth_scopes.length > 8 ? ' …' : ''}\n\n`);
+      }
+      return bundles;
+    }
+
     if (args.catalog) {
       const catalog = listKnownServers(options);
       if (args.json) {
         write(JSON.stringify({ catalog }, null, 2) + '\n');
         return catalog;
       }
-      write('\n  Known MCP Server Catalog (Registry: agentsam_mcp_servers)\n\n');
+      write('\n  Known MCP Server Catalog\n\n');
       for (const s of catalog) {
         write(`  • ${s.name || s.server_key} (${s.display_name || s.name})\n`);
         write(`      url:       ${s.url}\n`);
         write(`      auth_type: ${s.auth_type || 'none'}\n`);
-        write(`      health:    ${s.health_status || 'unknown'}${s.avg_latency_ms != null ? ` · ${s.avg_latency_ms}ms` : ''}\n\n`);
+        write(`      protocol:  ${s.protocol || 'streamable_http'}\n\n`);
       }
       return catalog;
     }
@@ -124,6 +228,7 @@ export async function runMcp(argv = [], options = {}) {
     }
     if (servers.length === 0) {
       write('  No MCP servers configured yet. Add one with: agentsam mcp add inneranimalmedia\n');
+      write('  Cloudflare portals: agentsam mcp list --bundles\n');
       return servers;
     }
     write('\n  Configured MCP Servers (Authority: ~/.agentsam/mcp/)\n\n');
@@ -137,13 +242,49 @@ export async function runMcp(argv = [], options = {}) {
     return servers;
   }
 
+  if (subcommand === 'scopes') {
+    const name = target;
+    if (!name) throw new Error('mcp_bundle_name_required');
+    const bundle = getCloudflareMcpBundle(name);
+    if (!bundle) {
+      throw new Error(`unknown_cloudflare_mcp_bundle:${name}`);
+    }
+    const scopes = scopesForCloudflareMcpBundle(name);
+    const payload = {
+      bundle: bundle.name,
+      url: bundle.url,
+      feature_packs: bundle.feature_packs,
+      capability_ids: bundle.capability_ids,
+      portal_manage_scopes: bundle.portal_manage_scopes,
+      oauth_scopes: scopes,
+      authorize_hint: `agentsam cloudflare permissions authorize --packs ${(bundle.feature_packs || ['agentsam']).join(',')}`,
+      note: 'Never request CLOUDFLARE_ALL_SCOPES (~315) at once — upgrade by pack.',
+    };
+    if (args.json) {
+      write(JSON.stringify(payload, null, 2) + '\n');
+      return payload;
+    }
+    write(`\n  OAuth scopes for MCP bundle: ${name}\n`);
+    write(`      URL:    ${bundle.url}\n`);
+    write(`      Packs:  ${(bundle.feature_packs || []).join(', ') || '(none)'}\n`);
+    write(`      Manage: ${(bundle.portal_manage_scopes || []).join(', ')}\n`);
+    write(`      Scopes (${scopes.length}):\n`);
+    for (const s of scopes) write(`        • ${s}\n`);
+    write(`\n  ${payload.authorize_hint}\n\n`);
+    return payload;
+  }
+
   if (subcommand === 'add') {
-    const name = target || 'inneranimalmedia';
+    const name = target;
+    if (!name) {
+      throw new Error('mcp_server_name_required: agentsam mcp add <name> [--url <url>]');
+    }
+
     const preset = resolveServerPreset(name, options);
     const url = args.url || preset?.url;
 
     if (!url) {
-      throw new Error(`missing_url: specify --url for custom MCP server "${name}"`);
+      throw new Error(`missing_url: specify --url for custom MCP server "${name}" (or use a catalog name from: agentsam mcp list --catalog)`);
     }
 
     let requestedClients = ['cursor'];
@@ -158,30 +299,58 @@ export async function runMcp(argv = [], options = {}) {
       requestedClients = preset.defaultClients;
     }
 
+    const cfBundle = getCloudflareMcpBundle(name);
+    const packHint = args.pack || (cfBundle?.feature_packs || [])[0] || '';
+
     const serverConfig = {
       name,
       url,
-      protocol: preset?.protocol || 'sse',
-      auth: args.token ? { type: preset?.auth_type || 'bearer', token: args.token } : null,
+      protocol: preset?.protocol || 'streamable_http',
+      auth: args.token
+        ? { type: preset?.auth_type === 'none' ? 'bearer' : (preset?.auth_type || 'bearer'), token: args.token }
+        : null,
       clients: requestedClients,
-      metadata: preset ? { preset: name, description: preset.description, health_status: preset.health_status } : {},
+      metadata: {
+        ...(preset
+          ? {
+              preset: name,
+              description: preset.description,
+              provider: preset.provider || null,
+              kind: preset.kind || null,
+              feature_packs: preset.feature_packs || [],
+              capability_ids: preset.capability_ids || [],
+              portal_manage_scopes: preset.portal_manage_scopes || [],
+            }
+          : {}),
+        pack_hint: packHint || null,
+      },
     };
 
-    // Store in AgentSam authority
     const written = writeMcpServer(name, serverConfig, options);
 
-    // Materialize client adapters
     const syncedAdapters = [];
     for (const c of requestedClients) {
       const res = syncServerToClient(c, name, serverConfig, options);
       syncedAdapters.push(res);
     }
 
-    // Ping to verify connectivity
     const ping = await pingMcpServer(serverConfig, options);
+    const scopePreview = cfBundle ? scopesForCloudflareMcpBundle(name) : null;
 
     if (args.json) {
-      const payload = { ok: true, server: written, syncedAdapters, ping };
+      const payload = {
+        ok: true,
+        server: written,
+        syncedAdapters,
+        ping,
+        cloudflare_bundle: cfBundle
+          ? {
+              feature_packs: cfBundle.feature_packs,
+              portal_manage_scopes: cfBundle.portal_manage_scopes,
+              suggested_oauth_scopes: scopePreview,
+            }
+          : null,
+      };
       write(JSON.stringify(payload, null, 2) + '\n');
       return payload;
     }
@@ -189,16 +358,23 @@ export async function runMcp(argv = [], options = {}) {
     write(`\n  ✓ Configured MCP server: ${name}\n`);
     write(`      Authority:   ~/.agentsam/mcp/${name}.json\n`);
     write(`      URL:         ${url}\n`);
+    write(`      Protocol:    ${serverConfig.protocol}\n`);
     for (const a of syncedAdapters) {
       write(`      Adapter:     ${a.client} -> ${a.configPath}\n`);
     }
     if (ping.ok) {
-      write(`      Ping:        ✓ Connected (${ping.latencyMs}ms)\n`);
+      write(`      Ping:        ✓ Connected (${ping.latencyMs}ms${ping.transport ? `, ${ping.transport}` : ''})\n`);
     } else {
       write(`      Ping:        ⚠ Warning (${ping.error || 'unreachable'})\n`);
     }
+    if (cfBundle) {
+      write(`      CF packs:    ${(cfBundle.feature_packs || []).join(', ') || '(portal-hosted OAuth)'}\n`);
+      write(`      Portal:      ${(cfBundle.portal_manage_scopes || []).join(', ')}\n`);
+      write(`      Upgrade:     agentsam mcp scopes ${name}\n`);
+      write(`                  (CF-connected users: ensure agentsam pack includes mcp-portals.*)\n`);
+    }
     write('\n');
-    return { server: written, syncedAdapters, ping };
+    return { ok: true, server: written, syncedAdapters, ping };
   }
 
   if (subcommand === 'status') {
@@ -221,9 +397,11 @@ export async function runMcp(argv = [], options = {}) {
     const report = {
       name,
       url: server.url,
+      protocol: server.protocol,
       ping,
       clients: clientStatuses,
       hasAuth: Boolean(server.auth?.token),
+      metadata: server.metadata || {},
     };
 
     if (args.json) {
@@ -261,21 +439,34 @@ export async function runMcp(argv = [], options = {}) {
     const toolsProbe = ping.ok ? await listMcpTools(server, options) : { count: 0, tools: [] };
 
     const detectedClients = detectInstalledClients(options);
+    const cfBundle = getCloudflareMcpBundle(name);
     const diagnostics = {
       name,
       authorityPath: `~/.agentsam/mcp/${name}.json`,
       url: server.url,
       connectivity: ping.ok ? 'pass' : 'fail',
       latencyMs: ping.latencyMs,
+      transport: ping.transport || null,
       authConfigured: Boolean(server.auth?.token),
       discoveredTools: toolsProbe.count,
       clients: clientStatuses,
       detectedHostClients: detectedClients,
-      catalogHealth: preset ? {
-        health_status: preset.health_status,
-        avg_latency_ms: preset.avg_latency_ms,
-        error_rate: preset.error_rate,
-      } : null,
+      catalog: preset
+        ? {
+            auth_type: preset.auth_type,
+            protocol: preset.protocol,
+            provider: preset.provider,
+            feature_packs: preset.feature_packs || [],
+            portal_manage_scopes: preset.portal_manage_scopes || [],
+          }
+        : null,
+      cloudflare_oauth_hint: cfBundle
+        ? {
+            packs: cfBundle.feature_packs,
+            scopes: scopesForCloudflareMcpBundle(name),
+            note: 'Authorize packs via agentsam cloudflare permissions — not the full scope catalog.',
+          }
+        : null,
     };
 
     if (args.json) {
@@ -286,15 +477,17 @@ export async function runMcp(argv = [], options = {}) {
     write(`\n  AgentSam MCP Doctor · ${name}\n\n`);
     write(`  [1] Authority state:   ✓ Valid (~/.agentsam/mcp/${name}.json)\n`);
     write(`  [2] Endpoint ping:     ${ping.ok ? `✓ Reachable (${ping.latencyMs}ms)` : `✗ Unreachable (${ping.error})`}\n`);
-    if (preset?.health_status) {
-      write(`  [3] Live health data:  ${preset.health_status} (avg latency: ${preset.avg_latency_ms ?? 0}ms, error rate: ${preset.error_rate ?? 0}%)\n`);
-    }
+    write(`  [3] Catalog:           ${preset ? `${preset.auth_type} / ${preset.protocol}` : 'custom'}\n`);
     write(`  [4] Auth credential:   ${diagnostics.authConfigured ? '✓ Token configured' : '○ Unauthenticated / public'}\n`);
     write(`  [5] Tool discovery:    ${toolsProbe.count > 0 ? `✓ Found ${toolsProbe.count} tools` : '○ 0 tools discovered'}\n`);
     write(`  [6] Client adapters:\n`);
     for (const c of clientStatuses) {
       write(`        • ${c.client}: ${c.configured ? '✓ Synced' : '✗ Desynced'} (${c.path})\n`);
     }
+    if (cfBundle) {
+      write(`  [7] CF portal packs:   ${(cfBundle.feature_packs || []).join(', ') || '—'}\n`);
+      write(`      Portal manage:     ${(cfBundle.portal_manage_scopes || []).join(', ')}\n`);
+    }
     write('\n');
     return diagnostics;
   }

package/src/commands/ollama.js

@@ -2,9 +2,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { readProjectConfig, setLocalModelCapability, writeProjectConfig } from '../lib/project-config.js';
+import { OLLAMA_DEFAULT_ENDPOINT, resolveOllamaEndpoint } from '../../packages/agentsam-knowledge/src/providers/ollama-endpoint.js';
 
 export const OLLAMA_DEFAULTS = Object.freeze({
-  baseUrl: 'http://127.0.0.1:11434',
+  baseUrl: OLLAMA_DEFAULT_ENDPOINT,
   model: 'qwen2.5-coder',
   embedModel: 'mxbai-embed-large',
 });
@@ -50,7 +51,7 @@ export function parseOllamaArgs(argv = []) {
 
 export function resolveOllamaConfig(opts = {}, env = process.env) {
   return {
-    baseUrl: clean(opts.baseUrl || env.OLLAMA_BASE_URL || OLLAMA_DEFAULTS.baseUrl).replace(/\/+$/, ''),
+    baseUrl: resolveOllamaEndpoint({ endpoint: opts.baseUrl, env }),
     model: clean(opts.model || env.OLLAMA_MODEL || OLLAMA_DEFAULTS.model),
     embedModel: clean(opts.embedModel || env.OLLAMA_EMBED_MODEL || OLLAMA_DEFAULTS.embedModel),
   };

package/src/commands/plugins.js

@@ -27,7 +27,7 @@ function installMigration(cwd) {
 function parse(argv) {
   const out = {
     action: argv[0] || 'list', key: '', cwd: process.cwd(), json: false,
-    origin: process.env.AGENTSAM_ORIGIN || process.env.AGENTSAM_API_ORIGIN || 'https://agentsam.inneranimalmedia.com',
+    origin: '',
     timeoutMs: 180_000, noOpen: false,
   };
   for (let i = 1; i < argv.length; i += 1) {
@@ -59,7 +59,12 @@ async function resolveCliBearer(opts) {
 }
 
 async function fetchConnector(opts, token, pathname, init = {}) {
-  const origin = String(opts.origin).replace(/\/$/, '');
+  const origin = String(opts.origin || '').replace(/\/$/, '');
+  if (!origin) {
+    throw new Error(
+      'origin_required: pass --origin https://<your-local-studio-host> (no AGENTSAM_ORIGIN / hardcoded host fallback).',
+    );
+  }
   const headers = new Headers(init.headers || {});
   headers.set('accept', 'application/json');
   headers.set('authorization', `Bearer ${token}`);

package/src/commands/product.js

@@ -16,7 +16,40 @@ function parseCommon(argv = []) {
   return out;
 }
 
+export function printInspectHelp() {
+  console.log(`
+  agentsam inspect — deterministic repository world state
+
+  agentsam inspect [path]                    Inspect a repository or directory
+  agentsam inspect [path] --json             Machine-readable bounded index
+  agentsam inspect [path] --full --json      Full snapshot authority
+  agentsam inspect [path] --view files       File evidence view
+  agentsam inspect [path] --match <text>     Filter files by path/symbol/import metadata
+  agentsam inspect [path] --save-snapshot <file>
+                                               Save the content-addressed snapshot
+
+  --cwd <path>            Explicit root (legacy/automation form; positional path is preferred)
+  --view <index|files|full>
+  --index                 Bounded repository index (default)
+  --full                  Full repository snapshot
+  --limit <1-500>         File result limit
+  --facet-limit <1-200>   Facet result limit
+  --churn-days <days>     Git churn window (default: 30)
+  --system/--package/--category/--layer/--kind/--language/--role
+  --execution-domain/--tag/--path/--symbol/--import/--match <value>
+                          Deterministic metadata filters
+  --snapshot-file <file>  Project a previously saved snapshot instead of scanning
+  --save-snapshot <file>  Save the newly scanned snapshot
+  --pretty                Pretty JSON when --json is used
+
+  No model, embeddings, network, provider spend, deploy, or mutation is required.
+  Output includes content hashes, Merkle identity, file metadata, AST-derived symbols/imports,
+  packages, systems, facets, revision evidence, and trust-boundary analysis when available.
+`);
+}
+
 export async function runInspect(argv = []) {
+  if (argv.includes('--help') || argv.includes('-h')) { printInspectHelp(); return; }
   const opts = parseCommon(argv);
   let churnDays = 30;
   let view = 'index';
@@ -27,6 +60,7 @@ export async function runInspect(argv = []) {
   let snapshotFile = '';
   let saveSnapshot = '';
   const filters = {};
+  let positionalRoot = '';
   const addFilter = (field, value) => {
     const clean = String(value || '').trim();
     if (!clean) throw new Error(`inspect_${field}_value_required`);
@@ -50,8 +84,10 @@ export async function runInspect(argv = []) {
     else if (arg === '--save-snapshot') saveSnapshot = String(opts.positionals[++i] || '').trim();
     else if (filterFlags.has(arg)) addFilter(filterFlags.get(arg), opts.positionals[++i]);
     else if (arg === 'repository') continue;
+    else if (!arg.startsWith('-') && !positionalRoot) positionalRoot = arg;
     else throw new Error(`unknown inspect option: ${arg}`);
   }
+  if (positionalRoot) opts.cwd = path.resolve(opts.cwd, positionalRoot);
   if (!['full', 'index', 'files'].includes(view)) throw new Error(`invalid inspect view: ${view}`);
   if (!Number.isInteger(limit) || limit < 1 || limit > 500) throw new Error('inspect limit must be an integer from 1..500');
   if (!Number.isInteger(facetLimit) || facetLimit < 1 || facetLimit > 200) throw new Error('inspect facet limit must be an integer from 1..200');