@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.5

package/src/lib/setup/runtime-persist.js

@@ -0,0 +1,197 @@
+/**
+ * Platform persistence for agentsamd (LaunchAgent / Windows Scheduled Task).
+ * Pure builders are exported for tests; side-effect helpers call OS tools.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { runtimeStateDir, ensureRuntimeStateDir } from './runtime.js';
+
+const execFileAsync = promisify(execFile);
+
+export const DARWIN_LAUNCH_LABEL = 'com.inneranimalmedia.agentsamd';
+export const WINDOWS_TASK_NAME = 'InnerAnimalMedia\\agentsamd';
+export const WINDOWS_TASK_FOLDER = 'InnerAnimalMedia';
+
+/**
+ * @param {{ binary: string, listen: string, stdoutLog: string, stderrLog: string, label?: string }} opts
+ */
+export function buildLaunchAgentPlist(opts) {
+  const label = opts.label || DARWIN_LAUNCH_LABEL;
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${label}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${opts.binary}</string>
+    <string>--listen</string>
+    <string>${opts.listen}</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${opts.stdoutLog}</string>
+  <key>StandardErrorPath</key><string>${opts.stderrLog}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>AGENTSAMD_ROLE</key><string>machine</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * User-level Scheduled Task XML (InteractiveToken, at logon, restart on failure).
+ * @param {{ binary: string, listen: string, workingDirectory: string, author?: string }} opts
+ */
+export function buildWindowsScheduledTaskXml(opts) {
+  const author = opts.author || 'Inner Animal Media';
+  const bin = String(opts.binary).replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+  const cwd = String(opts.workingDirectory).replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+  const listen = String(opts.listen).replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+  // Arguments must not include the executable path — Command contains the .exe.
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Author>${author}</Author>
+    <Description>AgentSam machine runtime daemon (agentsamd). Protocol agentsam.runtime.v1.</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>3</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${bin}</Command>
+      <Arguments>--listen ${listen}</Arguments>
+      <WorkingDirectory>${cwd}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+
+/**
+ * @returns {{ kind: 'launch_agent', label: string, plist: string } | null}
+ */
+export function writeLaunchAgent(home, binary, listen) {
+  if (process.platform !== 'darwin') return null;
+  const label = DARWIN_LAUNCH_LABEL;
+  const plistDir = path.join(home, 'Library', 'LaunchAgents');
+  fs.mkdirSync(plistDir, { recursive: true });
+  const plist = path.join(plistDir, `${label}.plist`);
+  const logDir = path.join(runtimeStateDir(home), 'logs');
+  fs.mkdirSync(logDir, { recursive: true });
+  const contents = buildLaunchAgentPlist({
+    binary,
+    listen,
+    label,
+    stdoutLog: path.join(logDir, 'agentsamd.stdout.log'),
+    stderrLog: path.join(logDir, 'agentsamd.stderr.log'),
+  });
+  fs.writeFileSync(plist, contents);
+  return { kind: 'launch_agent', label, plist };
+}
+
+/**
+ * Write task XML under ~/.agentsam/runtime/ and register via schtasks.
+ * @returns {Promise<{ kind: 'scheduled_task', taskName: string, xmlPath: string, registered: boolean, error?: string } | null>}
+ */
+export async function writeWindowsScheduledTask(home, binary, listen, options = {}) {
+  if (process.platform !== 'win32' && options.forcePlatform !== 'win32') return null;
+  ensureRuntimeStateDir(home);
+  const xmlPath = path.join(runtimeStateDir(home), 'agentsamd.scheduled-task.xml');
+  const workingDirectory = path.dirname(binary);
+  const xml = buildWindowsScheduledTaskXml({ binary, listen, workingDirectory });
+  // Node writes UTF-8; schtasks accepts UTF-8 when /XML is used on modern Windows.
+  fs.writeFileSync(xmlPath, xml, 'utf8');
+
+  const taskName = WINDOWS_TASK_NAME;
+  const execImpl = options.execFileAsync || execFileAsync;
+  if (options.skipRegister === true) {
+    return { kind: 'scheduled_task', taskName, xmlPath, registered: false };
+  }
+  try {
+    await execImpl('schtasks', ['/Create', '/TN', taskName, '/XML', xmlPath, '/F'], {
+      timeout: 30000,
+      windowsHide: true,
+    });
+    return { kind: 'scheduled_task', taskName, xmlPath, registered: true };
+  } catch (err) {
+    return {
+      kind: 'scheduled_task',
+      taskName,
+      xmlPath,
+      registered: false,
+      error: String(err?.message || err),
+    };
+  }
+}
+
+export async function startWindowsScheduledTask(options = {}) {
+  const execImpl = options.execFileAsync || execFileAsync;
+  const taskName = options.taskName || WINDOWS_TASK_NAME;
+  await execImpl('schtasks', ['/Run', '/TN', taskName], { timeout: 15000, windowsHide: true });
+  return { ok: true, taskName };
+}
+
+export async function stopWindowsScheduledTask(options = {}) {
+  const execImpl = options.execFileAsync || execFileAsync;
+  const taskName = options.taskName || WINDOWS_TASK_NAME;
+  try {
+    await execImpl('schtasks', ['/End', '/TN', taskName], { timeout: 15000, windowsHide: true });
+  } catch {
+    /* task may not be running */
+  }
+  return { ok: true, taskName };
+}
+
+export async function bootstrapDarwinLaunchAgent(plist, label = DARWIN_LAUNCH_LABEL) {
+  if (process.platform !== 'darwin' || !plist) return { ok: false };
+  try {
+    await execFileAsync('launchctl', ['unload', plist], { timeout: 10000 }).catch(() => {});
+    await execFileAsync('launchctl', ['load', plist], { timeout: 10000 });
+    return { ok: true, label, plist };
+  } catch (err) {
+    return { ok: false, error: String(err?.message || err), label, plist };
+  }
+}
+
+export async function unloadDarwinLaunchAgent(plist) {
+  if (process.platform !== 'darwin' || !plist) return { ok: false };
+  try {
+    await execFileAsync('launchctl', ['unload', plist], { timeout: 10000 });
+    return { ok: true, plist };
+  } catch (err) {
+    return { ok: false, error: String(err?.message || err), plist };
+  }
+}

package/src/lib/setup/runtime.js

@@ -0,0 +1,394 @@
+/**
+ * agentsam setup runtime — goal profiles → hard constraints → GOAP → utility → receipts.
+ * Physical registry remains terminal_* (Studio/IAM). This CLI owns local plan/install receipts.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { planGoap, GOAP_ENGINE } from '../../sam/planning/goap.js';
+import {
+  RUNTIME_PROTOCOL_SCHEMA,
+  RUNTIME_ADAPTERS,
+  RUNTIME_TRANSPORTS,
+  capabilitiesSatisfy,
+} from '../../../packages/runtime-protocol/src/index.js';
+import { discoverEnvironment } from './discover.js';
+
+export const RUNTIME_SETUP_SCHEMA = 'agentsam.runtime-setup.v1';
+
+/** Five goal profiles (+ advanced). */
+export const RUNTIME_PROFILES = Object.freeze([
+  {
+    id: 'my_computer',
+    label: 'My Computer',
+    description: 'This Mac/Linux host as a persistent agentsamd machine.',
+    provider: 'local',
+    substrate: 'host',
+    lifecycle: 'persistent',
+    runtime_adapter: 'agentsamd',
+    transport: 'direct_https',
+    required_capabilities: { exec: true, pty: true, filesystem: true, process: true },
+  },
+  {
+    id: 'isolated_local',
+    label: 'Isolated Local',
+    description: 'Local Docker container running agentsamd.',
+    provider: 'local',
+    substrate: 'container',
+    lifecycle: 'persistent',
+    provider_product: 'docker',
+    runtime_adapter: 'agentsamd',
+    transport: 'direct_https',
+    required_capabilities: { exec: true, pty: true, filesystem: true, docker: true },
+  },
+  {
+    id: 'cloud_computer',
+    label: 'Cloud Computer',
+    description: 'Persistent cloud VM (GCP today) with agentsamd.',
+    provider: 'google_cloud',
+    substrate: 'vm',
+    lifecycle: 'persistent',
+    provider_product: 'compute_engine',
+    runtime_adapter: 'agentsamd',
+    transport: 'cloudflare_tunnel',
+    required_capabilities: { exec: true, pty: true, filesystem: true, process: true },
+  },
+  {
+    id: 'on_demand',
+    label: 'On-demand',
+    description: 'Scale-to-zero cloud container (CF Containers / Cloud Run).',
+    provider: 'cloudflare',
+    substrate: 'container',
+    lifecycle: 'scale_to_zero',
+    provider_product: 'containers',
+    runtime_adapter: 'agentsamd',
+    transport: 'service_binding',
+    required_capabilities: { exec: true, filesystem: true },
+  },
+  {
+    id: 'safe_sandbox',
+    label: 'Safe Sandbox',
+    description: 'Ephemeral Cloudflare Sandbox adapter (no full daemon required).',
+    provider: 'cloudflare',
+    substrate: 'sandbox',
+    lifecycle: 'ephemeral',
+    provider_product: 'sandbox',
+    runtime_adapter: 'cloudflare_sandbox',
+    transport: 'service_binding',
+    required_capabilities: { exec: true },
+  },
+]);
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+export function runtimeStateDir(home = os.homedir()) {
+  return path.join(home, '.agentsam', 'runtime');
+}
+
+export function ensureRuntimeStateDir(home = os.homedir()) {
+  const dir = runtimeStateDir(home);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Discover facts for runtime placement (providers as adapters).
+ */
+export async function discoverRuntimeFacts(options = {}) {
+  const env = await discoverEnvironment(options);
+  const home = options.home || os.homedir();
+  const stateDir = runtimeStateDir(home);
+  const receiptPath = path.join(stateDir, 'latest.install-receipt.json');
+  let prior = null;
+  try {
+    if (fs.existsSync(receiptPath)) prior = JSON.parse(fs.readFileSync(receiptPath, 'utf8'));
+  } catch {
+    prior = null;
+  }
+
+  const agentsamdBin =
+    (await whichBinary('agentsamd')) ||
+    (fs.existsSync(path.join(home, '.agentsam', 'bin', 'agentsamd'))
+      ? path.join(home, '.agentsam', 'bin', 'agentsamd')
+      : null);
+
+  return {
+    schema: RUNTIME_SETUP_SCHEMA,
+    discovered_at: new Date().toISOString(),
+    protocol: RUNTIME_PROTOCOL_SCHEMA,
+    host: {
+      hostname: env.hostname,
+      platform: env.platform,
+      arch: env.arch,
+      label: env.host_label,
+    },
+    tools: {
+      docker: Boolean(env.tools?.docker),
+      gcloud: Boolean(env.tools?.gcloud),
+      wrangler: Boolean(env.tools?.wrangler),
+      go: Boolean(await whichBinary('go')),
+    },
+    agentsamd: {
+      binary: agentsamdBin,
+      installed: Boolean(agentsamdBin),
+      prior_receipt: prior?.product || prior?.profile_id || null,
+    },
+    available_capabilities: {
+      exec: true,
+      pty: env.platform !== 'win32',
+      filesystem: true,
+      process: true,
+      git: Boolean(env.tools?.git),
+      docker: Boolean(env.tools?.docker),
+      gpu: false,
+      browser: false,
+      gui: env.platform === 'darwin',
+      ports: true,
+      snapshot: false,
+      persistent_filesystem: true,
+    },
+  };
+}
+
+async function whichBinary(bin) {
+  const { execFile } = await import('node:child_process');
+  const { promisify } = await import('node:util');
+  const execFileAsync = promisify(execFile);
+  try {
+    const cmd = process.platform === 'win32' ? 'where' : 'which';
+    const { stdout } = await execFileAsync(cmd, [bin], { timeout: 4000 });
+    return String(stdout || '').trim().split(/\r?\n/)[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+function hardConstraintsOk(profile, facts) {
+  const caps = capabilitiesSatisfy(profile.required_capabilities || {}, facts.available_capabilities || {});
+  const missingTools = [];
+  if (profile.substrate === 'container' && profile.provider === 'local' && !facts.tools.docker) {
+    missingTools.push('docker');
+  }
+  if (profile.provider === 'google_cloud' && !facts.tools.gcloud && !facts.tools.wrangler) {
+    // tunnel path can work with wrangler alone later; flag soft for now
+  }
+  if (profile.runtime_adapter === 'agentsamd' && !facts.tools.go && !facts.agentsamd.installed) {
+    missingTools.push('go_or_agentsamd_binary');
+  }
+  return {
+    ok: caps.ok && missingTools.length === 0,
+    missing_capabilities: caps.missing,
+    missing_tools: missingTools,
+  };
+}
+
+/**
+ * GOAP install actions for a profile.
+ */
+function goapCatalogFor(profile) {
+  return [
+    {
+      id: 'ensure_agentsamd_binary',
+      cost: 3,
+      preconditions: { need_agentsamd: true, has_agentsamd: false },
+      effects: { has_agentsamd: true },
+    },
+    {
+      id: 'ensure_docker',
+      cost: 2,
+      preconditions: { need_docker: true, has_docker: false },
+      effects: { has_docker: true },
+    },
+    {
+      id: 'create_instance_record',
+      cost: 1,
+      preconditions: { has_plan: true },
+      effects: { instance_planned: true },
+    },
+    {
+      id: 'create_connection_record',
+      cost: 1,
+      preconditions: { instance_planned: true },
+      effects: { connection_planned: true },
+    },
+    {
+      id: 'configure_transport',
+      cost: 2,
+      preconditions: { connection_planned: true },
+      effects: { transport_ready: true },
+    },
+    {
+      id: 'install_launch_agent',
+      cost: 2,
+      preconditions: { has_agentsamd: true, need_launchd: true },
+      effects: { launch_agent_installed: true },
+    },
+    {
+      id: 'enroll_runtime',
+      cost: 2,
+      preconditions: { transport_ready: true, has_agentsamd: true },
+      effects: { enrolled: true },
+    },
+    {
+      id: 'health_probe',
+      cost: 1,
+      preconditions: { enrolled: true },
+      effects: { healthy: true },
+    },
+  ];
+}
+
+function utilityScore(profile, facts, constraints) {
+  let score = 50;
+  if (constraints.ok) score += 40;
+  else score -= 30;
+  if (profile.id === 'my_computer' && facts.host.platform === 'darwin') score += 10;
+  if (profile.runtime_adapter === 'agentsamd' && facts.agentsamd.installed) score += 15;
+  if (profile.substrate === 'container' && facts.tools.docker) score += 8;
+  if (profile.provider === 'google_cloud' && facts.tools.gcloud) score += 8;
+  if (!constraints.ok) score -= constraints.missing_capabilities.length * 5;
+  return score;
+}
+
+/**
+ * Rank eligible profiles and build GOAP install plans.
+ */
+export async function planRuntimeSetup(options = {}) {
+  const facts = options.facts || (await discoverRuntimeFacts(options));
+  const profileId = clean(options.profileId || options.profile);
+  const profiles = profileId
+    ? RUNTIME_PROFILES.filter((p) => p.id === profileId)
+    : [...RUNTIME_PROFILES];
+
+  const candidates = [];
+  for (const profile of profiles) {
+    const constraints = hardConstraintsOk(profile, facts);
+    const initialState = {
+      has_plan: true,
+      need_agentsamd: profile.runtime_adapter === 'agentsamd',
+      has_agentsamd: Boolean(facts.agentsamd.installed),
+      need_docker: profile.substrate === 'container' && profile.provider === 'local',
+      has_docker: Boolean(facts.tools.docker),
+      need_launchd: profile.substrate === 'host' && facts.host.platform === 'darwin',
+      instance_planned: false,
+      connection_planned: false,
+      transport_ready: false,
+      launch_agent_installed: facts.host.platform !== 'darwin',
+      enrolled: false,
+      healthy: false,
+    };
+    const goal = {
+      healthy: true,
+      enrolled: true,
+      ...(profile.runtime_adapter === 'agentsamd' ? { has_agentsamd: true } : {}),
+    };
+    const goap = planGoap({
+      initialState,
+      goal,
+      actions: goapCatalogFor(profile),
+      maxExpansions: 200,
+    });
+    const score = utilityScore(profile, facts, constraints);
+    candidates.push({
+      profile,
+      eligible: constraints.ok,
+      constraints,
+      utility: score,
+      goap: {
+        engine: goap.engine || GOAP_ENGINE,
+        ok: goap.ok,
+        status: goap.status,
+        action_ids: goap.action_ids || [],
+        total_cost: goap.total_cost || 0,
+        error: goap.error || null,
+      },
+      target: {
+        protocol: RUNTIME_PROTOCOL_SCHEMA,
+        provider: profile.provider,
+        substrate: profile.substrate,
+        lifecycle: profile.lifecycle,
+        provider_product: profile.provider_product || null,
+        runtime_adapter: profile.runtime_adapter,
+        transport: profile.transport,
+        auth_mode: profile.runtime_adapter === 'agentsamd' ? 'connection_token' : 'service_binding',
+      },
+    });
+  }
+
+  candidates.sort((a, b) => {
+    if (a.eligible !== b.eligible) return a.eligible ? -1 : 1;
+    return b.utility - a.utility;
+  });
+
+  return {
+    schema: RUNTIME_SETUP_SCHEMA,
+    protocol: RUNTIME_PROTOCOL_SCHEMA,
+    facts,
+    candidates,
+    recommended: candidates.find((c) => c.eligible) || candidates[0] || null,
+    adapters: RUNTIME_ADAPTERS,
+    transports: RUNTIME_TRANSPORTS,
+  };
+}
+
+export function writeRuntimePlanReceipt(plan, home = os.homedir()) {
+  const dir = ensureRuntimeStateDir(home);
+  const file = path.join(dir, 'latest.plan.json');
+  const body = {
+    ...plan,
+    written_at: new Date().toISOString(),
+  };
+  fs.writeFileSync(file, `${JSON.stringify(body, null, 2)}\n`);
+  return file;
+}
+
+export function writeRuntimeInstallReceipt(receipt, home = os.homedir()) {
+  const dir = ensureRuntimeStateDir(home);
+  const file = path.join(dir, 'latest.install-receipt.json');
+  const body = {
+    schema: 'agentsam.runtime-install-receipt.v1',
+    written_at: new Date().toISOString(),
+    ...receipt,
+  };
+  fs.writeFileSync(file, `${JSON.stringify(body, null, 2)}\n`);
+  return file;
+}
+
+export function renderRuntimePlan(plan) {
+  const lines = [
+    '',
+    '  Agent Sam · setup runtime',
+    '  ────────────────────────────────────────',
+    '',
+    `  Host     ${plan.facts.host.label} · ${plan.facts.host.hostname} · ${plan.facts.host.platform}/${plan.facts.host.arch}`,
+    `  Protocol ${plan.protocol}`,
+    `  agentsamd ${plan.facts.agentsamd.installed ? `✓ ${plan.facts.agentsamd.binary}` : '○ not installed'}`,
+    '',
+    '  Profiles (hard constraints → GOAP → utility)',
+    '',
+  ];
+  for (const c of plan.candidates) {
+    const mark = c.eligible ? '✓' : '✕';
+    lines.push(`  ${mark} ${c.profile.label.padEnd(18)} utility ${String(c.utility).padStart(3)}  adapter=${c.target.runtime_adapter}  ${c.target.provider}/${c.target.substrate}`);
+    if (!c.eligible) {
+      if (c.constraints.missing_capabilities.length) {
+        lines.push(`      missing caps: ${c.constraints.missing_capabilities.join(', ')}`);
+      }
+      if (c.constraints.missing_tools.length) {
+        lines.push(`      missing tools: ${c.constraints.missing_tools.join(', ')}`);
+      }
+    } else if (c.goap.action_ids.length) {
+      lines.push(`      plan: ${c.goap.action_ids.join(' → ')}`);
+    }
+  }
+  lines.push('');
+  if (plan.recommended) {
+    lines.push(`  Recommended  ${plan.recommended.profile.label} (${plan.recommended.profile.id})`);
+    lines.push(`  Next         agentsam setup runtime --profile ${plan.recommended.profile.id} --yes`);
+    lines.push(`               agentsam runtime install`);
+  }
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}

package/src/lib/slash-commands.js

@@ -13,6 +13,8 @@ export const SLASH_COMMANDS = [
   { cmd: '/status', description: 'Honest project awareness: account, models, terminal, live deploy', lane: 'local' },
   { cmd: '/models', description: 'Probe providers and provider-verified known models', lane: 'model' },
   { cmd: '/providers', description: 'Configure and verify machine provider credentials', lane: 'model' },
+  { cmd: '/credentials', description: 'Audit credentials, drift, and remediation (never prints secrets)', lane: 'identity' },
+  { cmd: '/cheat-sheet', description: 'Organized Agent Sam command groups', lane: 'local' },
   { cmd: '/login', description: 'Sign in to Inner Animal Media and save the machine-local Agent Sam session', lane: 'identity' },
   { cmd: '/logout', description: 'Sign out locally without deleting provider credentials', lane: 'identity' },
   { cmd: '/whoami', description: 'Show authenticated account identity and safe credential status', lane: 'identity' },

package/src/lib/terminal/machine-identity.js

@@ -0,0 +1,95 @@
+/**
+ * Host identity the CLI sends when enrolling a device.
+ * Same vocabulary as ExecOS heartbeat: macos|linux|windows and arm64|x86_64|x86.
+ */
+import { execFile } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { arch as osArch, hostname as osHostname, platform as osPlatform } from 'node:os';
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+export function normalizeTerminalPlatform(value) {
+  const raw = clean(value).toLowerCase();
+  if (raw === 'darwin' || raw === 'macos' || raw === 'mac' || raw === 'osx') return 'macos';
+  if (raw === 'win32' || raw === 'windows' || raw === 'win') return 'windows';
+  if (raw === 'linux') return 'linux';
+  return null;
+}
+
+export function normalizeTerminalArch(value) {
+  const raw = clean(value).toLowerCase().replace(/-/g, '_');
+  if (raw === 'arm64' || raw === 'aarch64') return 'arm64';
+  if (raw === 'x64' || raw === 'x86_64' || raw === 'amd64') return 'x86_64';
+  if (raw === 'ia32' || raw === 'i386' || raw === 'i686' || raw === 'x86') return 'x86';
+  return null;
+}
+
+export function normalizeHostname(value) {
+  const raw = clean(value).replace(/\.local$/i, '').replace(/[\u0000\r\n]/g, '');
+  if (!raw) return null;
+  return raw.slice(0, 255);
+}
+
+export function normalizeHardwareModel(value) {
+  const raw = clean(value).replace(/[\u0000\r\n]/g, ' ').replace(/\s+/g, ' ');
+  if (!raw) return null;
+  const lower = raw.toLowerCase();
+  if (lower === 'unknown' || lower === 'to be filled by o.e.m.' || lower === 'system product name') return null;
+  return raw.slice(0, 128);
+}
+
+function runText(file, args) {
+  return new Promise((resolve) => {
+    execFile(file, args, { timeout: 3000, encoding: 'utf8', windowsHide: true }, (error, stdout) => {
+      if (error) {
+        resolve(null);
+        return;
+      }
+      resolve(String(stdout || '').trim() || null);
+    });
+  });
+}
+
+async function readHardwareModel(platform) {
+  try {
+    if (platform === 'darwin') return runText('sysctl', ['-n', 'hw.model']);
+    if (platform === 'win32') {
+      return runText('powershell.exe', [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        '(Get-CimInstance Win32_ComputerSystem).Model',
+      ]);
+    }
+    if (platform === 'linux') {
+      if (existsSync('/.dockerenv') || process.env.KUBERNETES_SERVICE_HOST) return 'container';
+      try {
+        return readFileSync('/sys/class/dmi/id/product_name', 'utf8').trim() || null;
+      } catch {
+        return null;
+      }
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+export async function collectMachineIdentity() {
+  let platform = '';
+  let arch = '';
+  let hostname = '';
+  try { platform = osPlatform(); } catch { platform = ''; }
+  try { arch = osArch(); } catch { arch = ''; }
+  try { hostname = osHostname(); } catch { hostname = ''; }
+  let model = null;
+  try { model = await readHardwareModel(platform); } catch { model = null; }
+  return {
+    hostname: normalizeHostname(hostname),
+    platform: normalizeTerminalPlatform(platform),
+    arch: normalizeTerminalArch(arch),
+    model: normalizeHardwareModel(model),
+  };
+}