@inneranimalmedia/agentsam-sdk 2.6.5 → 2.6.8

package/src/commands/machine-binary.js

@@ -0,0 +1,109 @@
+/**
+ * Resolve the agentsam-machine native binary.
+ * Preference order:
+ *   1. AgentSam-managed user runtime under ~/.agentsam/runtimes/machine
+ *   2. AGENTSAM_MACHINE_BIN explicit override
+ *   3. agentsam-machine on PATH
+ *   4. Built binary under native/agentsam-machine/target/{release,debug}
+ *   5. cargo run --manifest-path (SDK contributor fallback)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { findExecutable, managedMachineResolution } from './machine-runtime.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const sdkRoot = path.resolve(here, '../..');
+const machineCrate = path.join(sdkRoot, 'native/agentsam-machine');
+const machineManifest = path.join(machineCrate, 'Cargo.toml');
+
+/**
+ * @typedef {{ kind: 'binary', path: string, source: string, version?: string } | { kind: 'cargo', manifest: string, source: string } | { kind: 'missing', tried: string[] }} MachineBinaryResolution
+ */
+
+/**
+ * @returns {MachineBinaryResolution}
+ */
+export function resolveMachineBinary(env = process.env) {
+  const tried = [];
+
+  const managed = managedMachineResolution(env);
+  tried.push(...managed.tried);
+  if (managed.available) {
+    return {
+      kind: 'binary',
+      path: managed.path,
+      source: 'managed-runtime',
+      version: managed.state.current_version,
+    };
+  }
+
+  const explicit = String(env.AGENTSAM_MACHINE_BIN || '').trim();
+  if (explicit) {
+    tried.push(explicit);
+    if (fs.existsSync(explicit) && fs.statSync(explicit).isFile()) {
+      return { kind: 'binary', path: explicit, source: 'AGENTSAM_MACHINE_BIN' };
+    }
+  }
+
+  const pathHit = findExecutable('agentsam-machine', env);
+  if (pathHit) return { kind: 'binary', path: pathHit, source: 'PATH' };
+  tried.push('PATH:agentsam-machine');
+
+  for (const rel of ['target/release/agentsam-machine', 'target/debug/agentsam-machine']) {
+    const candidate = path.join(machineCrate, rel);
+    tried.push(candidate);
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return {
+        kind: 'binary',
+        path: candidate,
+        source: rel.includes('release') ? 'crate-release' : 'crate-debug',
+      };
+    }
+  }
+
+  if (fs.existsSync(machineManifest)) {
+    const cargo = findExecutable('cargo', env);
+    if (cargo) return { kind: 'cargo', manifest: machineManifest, source: 'cargo-run' };
+    tried.push('cargo');
+  }
+
+  return { kind: 'missing', tried };
+}
+
+/**
+ * @param {MachineBinaryResolution} resolution
+ * @param {string[]} machineArgv
+ * @param {{ stdio?: import('node:child_process').StdioOptions, env?: NodeJS.ProcessEnv }} [options]
+ */
+export function spawnMachine(resolution, machineArgv, options = {}) {
+  const env = options.env || process.env;
+  const stdio = options.stdio || 'inherit';
+  const maxBuffer = options.maxBuffer || 32 * 1024 * 1024;
+
+  if (resolution.kind === 'binary') {
+    return spawnSync(resolution.path, machineArgv, { stdio, env, encoding: 'utf8', maxBuffer });
+  }
+
+  if (resolution.kind === 'cargo') {
+    return spawnSync(
+      'cargo',
+      ['run', '--quiet', '--manifest-path', resolution.manifest, '--bin', 'agentsam-machine', '--', ...machineArgv],
+      { stdio, env, encoding: 'utf8', maxBuffer },
+    );
+  }
+
+  const err = new Error(
+    'agentsam-machine is not installed. Run: agentsam machine install. ' +
+    'Standalone Cargo users can run: cargo install agentsam-machine-cli. ' +
+    'Tried: ' + ((resolution.tried || []).join(', ') || '(none)'),
+  );
+  err.code = 'AGENTSAM_MACHINE_BINARY_MISSING';
+  throw err;
+}
+
+export function machineSdkRoot() {
+  return sdkRoot;
+}

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

@@ -0,0 +1,208 @@
+/**
+ * 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)\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');
+      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);
+    } else {
+      out.positionals.push(arg);
+    }
+  }
+
+  out.subcommand = out.positionals[0] || null;
+  out.target = out.positionals[1] || null;
+  return out;
+}
+
+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.');
+  }
+}
+
+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');
+  }
+}
+
+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) {
+    console.log(usage());
+    return 0;
+  }
+
+  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 = 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];
+    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',
+      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 {
+        console.log(JSON.stringify(JSON.parse(stdout)));
+      } 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;
+}