@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.8

package/src/commands/machine-runtime.js

@@ -0,0 +1,266 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const MACHINE_RUNTIME_SCHEMA = 'agentsam.machine.runtime.v1';
+export const MACHINE_PACKAGE = 'agentsam-machine-cli';
+
+function expandHome(value, home) {
+  if (!value) return value;
+  if (value === '~') return home;
+  if (value.startsWith('~/')) return path.join(home, value.slice(2));
+  return value;
+}
+
+export function agentsamHome(env = process.env) {
+  const home = os.homedir();
+  const configured = String(env.AGENTSAM_HOME || '').trim();
+  return configured ? path.resolve(expandHome(configured, home)) : path.join(home, '.agentsam');
+}
+
+export function machineRuntimeRoot(env = process.env) {
+  return path.join(agentsamHome(env), 'runtimes', 'machine');
+}
+
+export function machineRuntimeStatePath(env = process.env) {
+  return path.join(machineRuntimeRoot(env), 'current.json');
+}
+
+export function machineBinaryName() {
+  return process.platform === 'win32' ? 'agentsam-machine.exe' : 'agentsam-machine';
+}
+
+export function machineManagedAliasPath(env = process.env) {
+  return path.join(agentsamHome(env), 'bin', machineBinaryName());
+}
+
+export function readMachineRuntimeState(env = process.env) {
+  const file = machineRuntimeStatePath(env);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (parsed?.schema !== MACHINE_RUNTIME_SCHEMA) return null;
+    if (typeof parsed?.current_version !== 'string' || !parsed.current_version.trim()) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function managedMachineResolution(env = process.env) {
+  const statePath = machineRuntimeStatePath(env);
+  const state = readMachineRuntimeState(env);
+  const tried = [statePath];
+  if (!state) return { available: false, state: null, path: null, tried };
+
+  const binary = path.join(
+    machineRuntimeRoot(env),
+    'versions',
+    state.current_version,
+    'bin',
+    machineBinaryName(),
+  );
+  tried.push(binary);
+
+  if (!fs.existsSync(binary) || !fs.statSync(binary).isFile()) {
+    return { available: false, state, path: binary, tried };
+  }
+  return { available: true, state, path: binary, tried };
+}
+
+export function findExecutable(command, env = process.env) {
+  const probe = process.platform === 'win32' ? ['where', [command]] : ['which', [command]];
+  const result = spawnSync(probe[0], probe[1], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    env,
+  });
+  if (result.status !== 0) return null;
+  return String(result.stdout || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean) || null;
+}
+
+export function machineBinaryVersion(binary, env = process.env) {
+  const result = spawnSync(binary, ['--version'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env,
+  });
+  if (result.status !== 0) return null;
+  const output = String(result.stdout || result.stderr || '').trim();
+  const match = output.match(/(?:^|\s)(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)(?:\s|$)/);
+  return match?.[1] || null;
+}
+
+export function machineRuntimeStatus(env = process.env) {
+  const managed = managedMachineResolution(env);
+  const cargo = findExecutable('cargo', env);
+  return {
+    schema: MACHINE_RUNTIME_SCHEMA,
+    manager: 'agentsam',
+    runtime_root: machineRuntimeRoot(env),
+    state_path: machineRuntimeStatePath(env),
+    installed: managed.available,
+    current_version: managed.state?.current_version || null,
+    binary: managed.path,
+    source: managed.state?.source || null,
+    installed_at_iso: managed.state?.installed_at_iso || null,
+    stable_alias: machineManagedAliasPath(env),
+    cargo: { available: Boolean(cargo), path: cargo },
+  };
+}
+
+export function discoverLatestMachineVersion(env = process.env) {
+  const cargo = findExecutable('cargo', env);
+  if (!cargo) {
+    const error = new Error('Cargo is required to install the current agentsam-machine crates.io distribution.');
+    error.code = 'AGENTSAM_MACHINE_CARGO_MISSING';
+    throw error;
+  }
+
+  const result = spawnSync(cargo, ['search', MACHINE_PACKAGE, '--limit', '1'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env,
+  });
+  if (result.status !== 0) {
+    const error = new Error(
+      String(result.stderr || '').trim() ||
+      'Unable to resolve latest ' + MACHINE_PACKAGE + ' version from crates.io.',
+    );
+    error.code = 'AGENTSAM_MACHINE_REGISTRY_LOOKUP_FAILED';
+    throw error;
+  }
+
+  const match = String(result.stdout || '').match(/^agentsam-machine-cli\s*=\s*"([^"]+)"/m);
+  if (!match) {
+    const error = new Error('Unable to parse crates.io version for ' + MACHINE_PACKAGE + '.');
+    error.code = 'AGENTSAM_MACHINE_REGISTRY_PARSE_FAILED';
+    throw error;
+  }
+  return match[1];
+}
+
+function writeCurrentState(version, env = process.env) {
+  const root = machineRuntimeRoot(env);
+  fs.mkdirSync(root, { recursive: true });
+  const state = {
+    schema: MACHINE_RUNTIME_SCHEMA,
+    manager: 'agentsam',
+    package: MACHINE_PACKAGE,
+    current_version: version,
+    source: 'crates.io',
+    installed_at_iso: new Date().toISOString(),
+  };
+  const target = machineRuntimeStatePath(env);
+  const temp = target + '.tmp-' + process.pid;
+  fs.writeFileSync(temp, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(temp, target);
+  return state;
+}
+
+function syncManagedAlias(binary, env = process.env) {
+  const alias = machineManagedAliasPath(env);
+  fs.mkdirSync(path.dirname(alias), { recursive: true });
+  try { fs.rmSync(alias, { force: true }); } catch {}
+  if (process.platform === 'win32') fs.copyFileSync(binary, alias);
+  else fs.symlinkSync(binary, alias);
+  return alias;
+}
+
+export function installManagedMachine({
+  env = process.env,
+  version = null,
+  force = false,
+  write = () => {},
+} = {}) {
+  const cargo = findExecutable('cargo', env);
+  if (!cargo) {
+    const error = new Error(
+      'Cargo is required by the current Machine distribution. Install Rust/Cargo, then rerun agentsam machine install.',
+    );
+    error.code = 'AGENTSAM_MACHINE_CARGO_MISSING';
+    throw error;
+  }
+
+  const desired = version || discoverLatestMachineVersion(env);
+  const root = machineRuntimeRoot(env);
+  const versionsRoot = path.join(root, 'versions');
+  const finalRoot = path.join(versionsRoot, desired);
+  const finalBinary = path.join(finalRoot, 'bin', machineBinaryName());
+  fs.mkdirSync(versionsRoot, { recursive: true });
+
+  if (!force && fs.existsSync(finalBinary)) {
+    const actual = machineBinaryVersion(finalBinary, env);
+    if (actual === desired) {
+      const state = writeCurrentState(desired, env);
+      const alias = syncManagedAlias(finalBinary, env);
+      return { changed: false, version: desired, binary: finalBinary, alias, state, source: 'managed-cache' };
+    }
+  }
+
+  const stage = fs.mkdtempSync(path.join(root, '.install-'));
+  write('Installing ' + MACHINE_PACKAGE + '@' + desired + ' from crates.io…\n');
+
+  const result = spawnSync(
+    cargo,
+    ['install', MACHINE_PACKAGE, '--root', stage, '--version', desired, '--locked', '--force'],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env },
+  );
+  if (result.status !== 0) {
+    fs.rmSync(stage, { recursive: true, force: true });
+    const error = new Error(
+      String(result.stderr || result.stdout || '').trim() ||
+      'cargo install failed for ' + MACHINE_PACKAGE + '@' + desired,
+    );
+    error.code = 'AGENTSAM_MACHINE_INSTALL_FAILED';
+    throw error;
+  }
+
+  const stagedBinary = path.join(stage, 'bin', machineBinaryName());
+  if (!fs.existsSync(stagedBinary)) {
+    fs.rmSync(stage, { recursive: true, force: true });
+    const error = new Error('cargo install completed without ' + machineBinaryName());
+    error.code = 'AGENTSAM_MACHINE_INSTALL_BINARY_MISSING';
+    throw error;
+  }
+
+  const actual = machineBinaryVersion(stagedBinary, env);
+  if (actual !== desired) {
+    fs.rmSync(stage, { recursive: true, force: true });
+    const error = new Error(
+      'installed Machine version mismatch: expected ' + desired + ', received ' + (actual || 'unknown'),
+    );
+    error.code = 'AGENTSAM_MACHINE_INSTALL_VERSION_MISMATCH';
+    throw error;
+  }
+
+  if (fs.existsSync(finalRoot)) fs.rmSync(finalRoot, { recursive: true, force: true });
+  fs.renameSync(stage, finalRoot);
+  const state = writeCurrentState(desired, env);
+  const alias = syncManagedAlias(finalBinary, env);
+  return { changed: true, version: desired, binary: finalBinary, alias, state, source: 'crates.io' };
+}
+
+export function updateManagedMachine({
+  env = process.env,
+  force = false,
+  write = () => {},
+} = {}) {
+  const latest = discoverLatestMachineVersion(env);
+  const status = machineRuntimeStatus(env);
+  if (!force && status.installed && status.current_version === latest) {
+    return {
+      changed: false,
+      version: latest,
+      binary: status.binary,
+      alias: machineManagedAliasPath(env),
+      state: readMachineRuntimeState(env),
+      source: 'already-current',
+    };
+  }
+  return installManagedMachine({ env, version: latest, force, write });
+}

package/src/commands/machine.js

@@ -1,81 +1,131 @@
 /**
- * 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.
+ * agentsam machine — deterministic native Machine lifecycle + perception.
  */
 
 import path from 'node:path';
 import { resolveMachineBinary, spawnMachine } from './machine-binary.js';
+import {
+  installManagedMachine,
+  machineBinaryVersion,
+  machineRuntimeStatus,
+  updateManagedMachine,
+} from './machine-runtime.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.`;
+  return 'agentsam machine — deterministic local perception (native engine)\n\n' +
+    'Usage:\n' +
+    '  agentsam machine status [--json]\n' +
+    '  agentsam machine doctor [--json]\n' +
+    '  agentsam machine install [--version <semver>] [--force] [--json]\n' +
+    '  agentsam machine update [--force] [--json]\n' +
+    '  agentsam machine inspect <path> [--json] [--run-id <id>] [--include-generated]\n' +
+    '  agentsam machine --help\n\n' +
+    'Runtime authority:\n' +
+    '  AgentSam manages one user-level Machine runtime under ~/.agentsam/runtimes/machine/.\n' +
+    '  Every repository uses that managed runtime first; PATH and SDK source are fallbacks only.\n' +
+    '  Install/update are explicit and never run merely because you entered a repository.\n\n' +
+    'Notes:\n' +
+    '  Default inspect is read-only and network-free.\n' +
+    '  Large detail is externalized under <target>/.agentsam/machine/runs/<run_id>/.\n' +
+    '  Generated/cache trees are summarized unless --include-generated is set.\n' +
+    '  Current registry distribution uses crates.io and therefore requires Cargo for install/update.\n';
 }
 
 function parseArgs(argv = []) {
   const out = {
     help: false,
     json: false,
+    force: false,
     includeGenerated: false,
     runId: null,
+    version: 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 === '--force') out.force = 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');
-      }
+      if (value == null || value.startsWith('--')) throw new Error('--run-id requires a value');
       out.runId = value;
+    } else if (arg === '--version') {
+      const value = argv[++i];
+      if (value == null || value.startsWith('--')) throw new Error('--version requires a value');
+      out.version = value;
     } else if (arg.startsWith('-')) {
-      throw new Error(`unknown machine option: ${arg}`);
+      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;
+function statusPayload() {
+  const managed = machineRuntimeStatus();
+  const resolution = resolveMachineBinary();
+  let effectiveVersion = null;
+  if (resolution.kind === 'binary') effectiveVersion = machineBinaryVersion(resolution.path);
+
+  return {
+    capability: 'machine.status',
+    managed,
+    effective: {
+      ...resolution,
+      version: resolution.version || effectiveVersion,
+    },
+  };
+}
+
+function printTextStatus(payload) {
+  console.log('AgentSam Machine');
+  console.log('');
+  console.log('  managed      ' + (payload.managed.installed ? 'installed' : 'not installed'));
+  console.log('  version      ' + (payload.managed.current_version || '—'));
+  console.log('  binary       ' + (payload.managed.binary || '—'));
+  console.log('  runtime      ' + payload.managed.runtime_root);
+  console.log('  effective    ' + payload.effective.source);
+  console.log('  effective v  ' + (payload.effective.version || 'unknown'));
+  console.log('  cargo        ' + (payload.managed.cargo.available ? payload.managed.cargo.path : 'not found'));
+  if (!payload.managed.installed) {
+    console.log('');
+    console.log('  Run agentsam machine install to adopt the user-managed runtime.');
   }
-  if (resolution.kind === 'cargo') {
-    console.log(`agentsam-machine via cargo run (${resolution.source}): ${resolution.manifest}`);
-    console.log('capability: machine.inspect (dev fallback)');
-    return;
+}
+
+function printTextDoctor(payload) {
+  printTextStatus(payload);
+  console.log('');
+  if (payload.effective.kind === 'missing') {
+    console.log('  ✕ Machine unavailable');
+    console.log('  tried        ' + (payload.effective.tried || []).join(', '));
+  } else if (payload.managed.installed) {
+    console.log('  ✓ managed Machine runtime is available');
+  } else {
+    console.log('  ○ Machine works through fallback source: ' + payload.effective.source);
+    console.log('  ○ install the managed runtime to make resolution consistent across repositories');
   }
-  console.log('agentsam-machine unavailable');
-  console.log(`tried: ${(resolution.tried || []).join(', ')}`);
 }
 
-/**
- * @param {string[]} argv
- */
+function printInstallResult(action, result) {
+  console.log('AgentSam Machine ' + action);
+  console.log('');
+  console.log('  version      ' + result.version);
+  console.log('  binary       ' + result.binary);
+  console.log('  alias        ' + result.alias);
+  console.log('  source       ' + result.source);
+  console.log('  changed      ' + (result.changed ? 'yes' : 'no'));
+}
+
 export async function runMachine(argv = []) {
   const args = parseArgs(argv);
   if (args.help || !args.subcommand) {
@@ -83,20 +133,43 @@ export async function runMachine(argv = []) {
     return 0;
   }
 
-  const resolution = resolveMachineBinary();
+  if (args.subcommand === 'status') {
+    const payload = statusPayload();
+    if (args.json) console.log(JSON.stringify(payload));
+    else printTextStatus(payload);
+    return 0;
+  }
 
   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;
+    const payload = statusPayload();
+    if (args.json) console.log(JSON.stringify({ ...payload, capability: 'machine.doctor' }));
+    else printTextDoctor(payload);
+    return payload.effective.kind === 'missing' ? 1 : 0;
+  }
+
+  if (args.subcommand === 'install') {
+    const result = installManagedMachine({
+      version: args.version,
+      force: args.force,
+      write: args.json ? () => {} : (value) => process.stdout.write(value),
+    });
+    if (args.json) console.log(JSON.stringify({ capability: 'machine.install', ...result }));
+    else printInstallResult('install', result);
+    return 0;
+  }
+
+  if (args.subcommand === 'update') {
+    const result = updateManagedMachine({
+      force: args.force,
+      write: args.json ? () => {} : (value) => process.stdout.write(value),
+    });
+    if (args.json) console.log(JSON.stringify({ capability: 'machine.update', ...result }));
+    else printInstallResult('update', result);
+    return 0;
   }
 
   if (args.subcommand === 'inspect') {
+    const resolution = resolveMachineBinary();
     const target = args.target || process.cwd();
     const abs = path.resolve(target);
     const machineArgv = ['inspect', abs];
@@ -106,7 +179,6 @@ export async function runMachine(argv = []) {
 
     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,
     });
 
@@ -115,13 +187,12 @@ export async function runMachine(argv = []) {
       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}`);
+        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));
+        console.log(JSON.stringify(JSON.parse(stdout)));
       } catch {
         process.stdout.write(stdout);
       }
@@ -131,7 +202,7 @@ export async function runMachine(argv = []) {
   }
 
   console.log(usage());
-  const err = new Error(`Unknown machine subcommand: ${args.subcommand}`);
+  const err = new Error('Unknown machine subcommand: ' + args.subcommand);
   err.exitCode = 1;
   throw err;
 }