@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/src/host-bind.ts

@@ -0,0 +1,156 @@
+import {
+  chmodSync,
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  writeFileSync,
+  existsSync,
+} from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { isAbsolute, join, resolve } from 'node:path';
+import { planHost } from './host.js';
+import { canonical, digest } from './protocol.js';
+import {
+  stationHash,
+  stationRuntimeFingerprint,
+  stationWorkspaceIdentity,
+} from './station-config.js';
+
+export interface BindInput {
+  organization_id: string;
+  node_id: string;
+  station_key: string;
+  workspace: string;
+  tools_user: string;
+  files: string;
+  runtime_root: string;
+  runtime_image_digest: string;
+  operator_group?: string;
+  dir?: string;
+  state?: string;
+  provider?: string;
+  model?: string;
+  mcp_config?: string;
+  /** Item 9: the operator's persona file (root-owned, outside the workspace). */
+  persona?: string;
+  /** AgentPod-managed MCP profile: HTTP mcpServers the node assigns to admitted sessions. */
+  managed_mcp_config?: string;
+  /** Defaults to /usr/bin/systemd-run and /usr/bin/systemctl. */
+  systemd_run?: string;
+  systemctl?: string;
+  /** Tests only: where the default per-station directories live. */
+  roots?: { config: string; state: string };
+}
+
+const userName = /^[a-z_][a-z0-9_-]{0,31}$/;
+function pin(path: string) {
+  const real = realpathSync(path);
+  return { path: real, sha256: stationHash(readFileSync(real)) };
+}
+/** Write a private file only when its content changes; report whether it did. */
+function put(path: string, value: unknown): boolean {
+  const text = JSON.stringify(value, null, 2) + '\n';
+  if (existsSync(path) && readFileSync(path, 'utf8') === text) return false;
+  const tmp = path + '.tmp',
+    fd = openSync(tmp, 'w', 0o600);
+  try {
+    writeFileSync(fd, text);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, path);
+  return true;
+}
+
+/** Bind one AgentPod station to a launcher-profile strict work host. Root on Linux.
+ * Every output is derived from the inputs; nothing is edited by hand. */
+export async function bindHost(input: BindInput) {
+  if (process.platform !== 'linux' || process.getuid?.() !== 0)
+    throw Error('host bind runs as root on Linux');
+  const workspace = input.workspace;
+  if (!isAbsolute(workspace) || realpathSync(workspace) !== workspace)
+    throw Error('Use the canonical absolute workspace path');
+  const key = 'salaam:' + createHash('sha256').update(workspace).digest('hex').slice(0, 16);
+  if (input.station_key !== key)
+    throw Error('Station key does not name this workspace (expected ' + key + ')');
+  if (!userName.test(input.tools_user)) throw Error('tools user must be a user name');
+  try {
+    execFileSync('/usr/bin/getent', ['passwd', input.tools_user], { stdio: 'ignore' });
+  } catch {
+    throw Error('tools user does not exist');
+  }
+  if (input.tools_user === 'root') throw Error('tools user must not be root');
+  const id = key.slice('salaam:'.length),
+    roots = input.roots ?? { config: '/etc/salaam/stations', state: '/var/lib/salaam/stations' },
+    dir = resolve(input.dir ?? join(roots.config, id)),
+    state = resolve(input.state ?? join(roots.state, id, 'state'));
+  mkdirSync(dir, { recursive: true, mode: 0o755 });
+  // Ancestors of state stay traversable so the operator group can reach operator.sock;
+  // state itself is the daemon's (0700, or 0710 for the operator group once served).
+  mkdirSync(join(state, '..'), { recursive: true, mode: 0o755 });
+  chmodSync(join(state, '..'), 0o755);
+  const pinsPath = join(dir, 'agentpod-pins.json'),
+    stationPath = join(dir, 'station-config.json'),
+    configPath = join(dir, 'host-config.json'),
+    manifestPath = join(dir, 'host.json');
+  let changed = put(pinsPath, {
+    version: 1,
+    organization_id: input.organization_id,
+    node_id: input.node_id,
+    station_key: key,
+    workspace,
+  });
+  const runtime = realpathSync(input.runtime_root);
+  changed =
+    put(stationPath, {
+      version: 1,
+      kind: 'linux-systemd-station-v1',
+      workspace,
+      workspace_identity: stationWorkspaceIdentity(workspace),
+      files: pin(input.files),
+      systemd_run: pin(input.systemd_run ?? '/usr/bin/systemd-run'),
+      systemctl: pin(input.systemctl ?? '/usr/bin/systemctl'),
+      runtime_root: runtime,
+      runtime_fingerprint: stationRuntimeFingerprint(runtime),
+      runtime_image_digest: input.runtime_image_digest,
+      tools_user: input.tools_user,
+    }) || changed;
+  const config = {
+    mode: 'agentpod',
+    state,
+    agentpod_config: pinsPath,
+    station_config: stationPath,
+    strict_work_version: 1,
+    ...(input.operator_group ? { operator_group: input.operator_group } : {}),
+    ...(input.provider ? { provider: input.provider } : {}),
+    ...(input.model ? { model: input.model } : {}),
+    ...(input.mcp_config ? { operator_mcp_config: realpathSync(input.mcp_config) } : {}),
+    ...(input.persona ? { persona_config: realpathSync(input.persona) } : {}),
+    ...(input.managed_mcp_config ? { mcp_config: realpathSync(input.managed_mcp_config) } : {}),
+  };
+  changed = put(configPath, config) || changed;
+  const manifest = await planHost(config);
+  const before = existsSync(manifestPath)
+    ? canonical(JSON.parse(readFileSync(manifestPath, 'utf8')))
+    : null;
+  if (before !== canonical(manifest)) {
+    put(manifestPath, manifest);
+    changed = true;
+  }
+  return {
+    version: 1,
+    station_key: key,
+    dir,
+    state,
+    manifest: manifestPath,
+    manifest_digest: digest(manifest),
+    unit: 'salaam-host@' + id + '.service',
+    changed,
+  };
+}

package/src/host-breaker.ts

@@ -0,0 +1,89 @@
+/**
+ * A circuit breaker for agent fetches (operator MCP calls whose arguments carry a `url`). After
+ * repeated consecutive failures to one host within a session, calls to that host are paused for a
+ * short while: the agent gets a tool error saying so and can do something else, and the run's
+ * activity gets one line. Nothing fails the run, and a paused call is never made, so it records no
+ * operator MCP call. One success to the host closes the breaker again.
+ */
+export const BREAKER_FAILURES = 3;
+export const BREAKER_PAUSE_MS = 60_000;
+
+export function fetchHost(args: unknown): string | null {
+  const url = (args as { url?: unknown } | null)?.url;
+  if (typeof url !== 'string') return null;
+  try {
+    const host = new URL(url).hostname.toLowerCase();
+    return host || null;
+  } catch {
+    return null;
+  }
+}
+
+export class HostBreaker {
+  private readonly hosts = new Map<string, { failures: number; until: number }>();
+  constructor(private readonly now: () => number = Date.now) {}
+  private key(session: string, host: string) {
+    return session + '\u0000' + host;
+  }
+  /** Milliseconds this host stays paused for the session, 0 when calls may go ahead. */
+  paused(session: string, host: string): number {
+    const h = this.hosts.get(this.key(session, host));
+    return h ? Math.max(0, h.until - this.now()) : 0;
+  }
+  /** Records a call's outcome; true when this failure just opened the breaker. */
+  record(session: string, host: string, ok: boolean): boolean {
+    const key = this.key(session, host);
+    if (ok) {
+      this.hosts.delete(key);
+      return false;
+    }
+    const h = this.hosts.get(key) ?? { failures: 0, until: 0 };
+    h.failures++;
+    this.hosts.set(key, h);
+    if (h.failures < BREAKER_FAILURES) return false;
+    h.failures = 0;
+    h.until = this.now() + BREAKER_PAUSE_MS;
+    return true;
+  }
+  forget(session: string): void {
+    for (const key of this.hosts.keys())
+      if (key.startsWith(session + '\u0000')) this.hosts.delete(key);
+  }
+}
+
+type McpResult = { content: { type: 'text'; text: string }[]; is_error: boolean };
+/**
+ * One operator MCP call through the breaker. A paused host returns a tool error without calling;
+ * a thrown failure or a tool error counts against the host; the call that opens the breaker
+ * records `fetch.host_paused` for the run's activity. The call's own result or error is unchanged.
+ */
+export async function callThroughBreaker(
+  breaker: HostBreaker,
+  session: string,
+  args: unknown,
+  event: (payload: Record<string, unknown>) => void,
+  call: () => Promise<McpResult>,
+): Promise<McpResult> {
+  const host = fetchHost(args);
+  if (!host) return call();
+  const wait = breaker.paused(session, host);
+  if (wait)
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Requests to ${host} are paused for ${Math.ceil(wait / 1000)}s after repeated failures; try another source or retry later.`,
+        },
+      ],
+      is_error: true,
+    };
+  let ok = false;
+  try {
+    const result = await call();
+    ok = !result.is_error;
+    return result;
+  } finally {
+    if (breaker.record(session, host, ok))
+      event({ host, failures: BREAKER_FAILURES, pause_ms: BREAKER_PAUSE_MS });
+  }
+}

package/src/host-start.ts

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { spawn, execFile } from 'node:child_process';
 import { constants, openSync, closeSync, fstatSync, mkdirSync, realpathSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { readHost, hostMcp, hostToolkit } from './host.js';
@@ -130,3 +130,53 @@ export async function startHost(path: string) {
     release();
   }
 }
+
+const launcherUnit = /^salaam-host@[a-f0-9]{16}\.service$/;
+/** Launcher profile: an unprivileged operator asks systemd to start a root-owned,
+ * provisioned unit. It names only the unit; root reads its own reviewed manifest. */
+export async function startHostUnit(
+  unit: string,
+  state: string,
+  options: { systemctl?: string; timeoutMs?: number } = {},
+) {
+  if (!launcherUnit.test(unit)) throw Error('Unit must be salaam-host@<16 hex>.service');
+  if (realpathSync(state) !== state) throw Error('Use the canonical state path');
+  const socket = join(state, 'operator.sock'),
+    deadline = Date.now() + (options.timeoutMs ?? 20000);
+  const ready = async () => {
+    let h: Record<string, any>;
+    try {
+      h = await call(socket, '/v1/health', undefined, undefined, 2000);
+    } catch {
+      return null;
+    }
+    if (!h.host_receipt || h.host_receipt.manifest_digest !== h.host_manifest_digest)
+      throw new ServiceError('host_mismatch', 'Running daemon reports no reviewed host receipt');
+    if (h.host_receipt.state !== state)
+      throw new ServiceError('host_mismatch', 'Running daemon serves another state directory');
+    if (h.host_supervisor_connected !== true || h.service !== 'healthy') return null;
+    if (
+      h.job_execution?.control_error ||
+      h.job_execution?.schedule_control_error ||
+      h.job_execution?.inbox_control_error
+    )
+      throw Error('Reviewed host controls are not ready');
+    return h.host_receipt as Record<string, unknown>;
+  };
+  let receipt = await ready();
+  if (receipt) return receipt;
+  await new Promise<void>((done, fail) =>
+    execFile(
+      options.systemctl ?? '/usr/bin/systemctl',
+      ['start', '--no-ask-password', unit],
+      { env: { PATH: '/usr/bin:/bin', LANG: 'C.UTF-8' }, timeout: 20000 },
+      (error) =>
+        error ? fail(Error('systemd refused to start ' + unit + '; inspect its journal')) : done(),
+    ),
+  );
+  while (!(receipt = await ready())) {
+    if (Date.now() >= deadline) throw Error('Host unit did not become ready; inspect its journal');
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  return receipt;
+}