@superjackfruitlabs/salaam 0.0.3 → 0.0.4

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;
+}

package/src/host.ts

@@ -1,4 +1,5 @@
-import { spawn } from 'node:child_process';
+import { DEFAULT_COMMAND_NETWORK_SOCKET } from './command-network.js';
+import { spawn, execFileSync } from 'node:child_process';
 import { once } from 'node:events';
 import {
   readFileSync,
@@ -30,6 +31,9 @@ import { acquireStateLock } from './state-lock.js';
 import { call } from './transport.js';
 import { readStationConfig } from './station-config.js';
 import { readToolkitConfig } from './toolkit-config.js';
+import { OperatorMcp } from './operator-mcp.js';
+import { chooseLocalSandbox, sandboxLabel, type SandboxKind } from './command-sandbox.js';
+import { loadPersona } from './persona.js';
 interface HostIdentity {
   node: string;
   node_version: string;
@@ -53,6 +57,7 @@ interface AgentPodHostIdentity extends HostIdentity {
   pins_digest: string;
   workspace: string;
   cli_digest: string;
+  local_sandbox?: HostLocalSandbox;
 }
 export interface AgentPodHostManifest extends AgentPodHostIdentity {
   schema: 2;
@@ -78,6 +83,92 @@ export interface AgentPodStrictWorkHostManifest extends Omit<
 > {
   schema: 6;
   strict_work: { version: 1 };
+  /** Launcher profile: a root host whose operator socket one unprivileged group may use. */
+  operator_access?: OperatorAccess;
+  /** Operator-declared MCP servers (docs/mcp.md), pinned by declaration digest. */
+  operator_mcp?: { config: string; digest: string };
+  /** Item 9: the operator's persona file, pinned by content digest. */
+  persona?: { config: string; digest: string };
+  /** How long a strict approval offer stays answerable; the daemon default when absent. */
+  approval_ttl_ms?: number;
+}
+/** Item 10: the command sandbox this host gives local commands, as reviewed at host plan. With no
+ * usable sandbox the host refuses local commands (label "refused") unless the operator set
+ * `unsandboxed_commands: "allow"`, which the manifest pins (operator ruling 2026-10-30, option A). */
+export interface HostLocalSandbox {
+  kind: SandboxKind;
+  label: string;
+  unsandboxed_commands?: 'allow';
+  /** Network allowlist (operator rulings 2026-10-30): local commands reach the network only
+   * through stk's local-commands socket, whose egress.hosts the host operator sets. */
+  command_network?: { mode: 'broker'; socket: string; label: string };
+}
+export function hostLocalSandbox(
+  platform: NodeJS.Platform = process.platform,
+  find?: Parameters<typeof chooseLocalSandbox>[2],
+  findSb?: Parameters<typeof chooseLocalSandbox>[3],
+  allowUnsandboxed = false,
+  brokerSocket?: string,
+): HostLocalSandbox {
+  const { kind } = chooseLocalSandbox('workspace-write', platform, find, findSb);
+  return {
+    kind,
+    label: kind === 'none' && !allowUnsandboxed ? 'refused' : sandboxLabel(kind),
+    ...(allowUnsandboxed ? { unsandboxed_commands: 'allow' as const } : {}),
+    ...(brokerSocket
+      ? {
+          command_network: {
+            mode: 'broker' as const,
+            socket: brokerSocket,
+            label: 'broker (hosts set by the stk policy)',
+          },
+        }
+      : {}),
+  };
+}
+/** The broker socket local commands reach the network through, or null for no network. */
+export function hostCommandNetwork(m: HostManifest): { socket: string } | null {
+  const n = (m as { local_sandbox?: HostLocalSandbox }).local_sandbox?.command_network;
+  return n?.mode === 'broker' && typeof n.socket === 'string' ? { socket: n.socket } : null;
+}
+/** Whether the reviewed manifest lets local commands run unsandboxed on a host without a sandbox. */
+export function hostAllowsUnsandboxed(m: HostManifest): boolean {
+  return (
+    (m as { local_sandbox?: HostLocalSandbox }).local_sandbox?.unsandboxed_commands === 'allow'
+  );
+}
+export interface OperatorAccess {
+  group: string;
+  gid: number;
+}
+const groupName = /^[a-z_][a-z0-9_-]{0,31}$/;
+/** Resolve a system group by name. The launcher profile never accepts a numeric id alone. */
+export function resolveOperatorGroup(group: unknown): OperatorAccess {
+  if (typeof group !== 'string' || !groupName.test(group))
+    throw Error('operator_group must be a system group name');
+  let line: string;
+  try {
+    line = execFileSync('/usr/bin/getent', ['group', group], { encoding: 'utf8' }).trim();
+  } catch {
+    throw Error('operator_group does not exist');
+  }
+  const [name, , id] = line.split(':');
+  const gid = Number(id);
+  if (name !== group || !Number.isInteger(gid) || gid <= 0)
+    throw Error('operator_group must name a non-root group');
+  return { group, gid };
+}
+/** One minute to one day: long enough for a person to answer, short enough to free the station. */
+function approvalTtl(value: unknown): number {
+  if (!Number.isInteger(value) || (value as number) < 60000 || (value as number) > 86400000)
+    throw Error('approval_ttl_ms must be an integer from 60000 to 86400000');
+  return value as number;
+}
+export function hostApprovalTtlMs(m: HostManifest): number | undefined {
+  return m.schema === 6 ? m.approval_ttl_ms : undefined;
+}
+export function hostOperatorAccess(m: HostManifest): OperatorAccess | undefined {
+  return m.schema === 6 ? m.operator_access : undefined;
 }
 export type HostManifest =
   | CodingHostManifest
@@ -109,7 +200,7 @@ function privateDocument(path: string): Record<string, unknown> {
     closeSync(fd);
   }
 }
-function privateState(path: string): string {
+function privateState(path: string, gid?: number): string {
   if (!isAbsolute(path) || resolve(path) !== path)
     throw Error('Use canonical absolute private state paths');
   // Existing ancestors must resolve to their literal identity; never follow a workspace symlink.
@@ -119,7 +210,9 @@ function privateState(path: string): string {
     throw Error('Private state path must not contain symlinks');
   if (existsSync(path)) {
     const st = lstatSync(path);
-    if (!st.isDirectory() || st.uid !== process.getuid?.() || st.mode & 0o077)
+    // The launcher profile lets exactly one group traverse (x) to the operator socket.
+    const shared = gid !== undefined && (st.mode & 0o077) === 0o010 && st.gid === gid;
+    if (!st.isDirectory() || st.uid !== process.getuid?.() || (st.mode & 0o077 && !shared))
       throw Error('Host state must be a private owner-held directory');
   }
   return path;
@@ -145,6 +238,13 @@ async function planAgentPod(
     'toolkit_config',
     'station_config',
     'strict_work_version',
+    'operator_group',
+    'operator_mcp_config',
+    'persona_config',
+    'approval_ttl_ms',
+    'unsandboxed_commands',
+    'command_network',
+    'command_network_socket',
   ];
   if (Object.keys(c).some((k) => !fields.includes(k)))
     throw Error('Unexpected AgentPod host config field');
@@ -153,7 +253,53 @@ async function planAgentPod(
     (c.strict_work_version !== 1 || c.station_config === undefined)
   )
     throw Error('Strict work version1 requires reviewed protected station config');
-  const state = privateState(string(c.state, 'state'));
+  let access: OperatorAccess | undefined;
+  if (c.operator_group !== undefined) {
+    if (c.strict_work_version !== 1)
+      throw Error('operator_group is only for the strict work launcher profile');
+    if (process.platform !== 'linux' || process.getuid?.() !== 0)
+      throw Error('The launcher profile is planned by root on Linux');
+    access = resolveOperatorGroup(c.operator_group);
+  }
+  let operatorMcp: { config: string; digest: string } | undefined;
+  if (c.operator_mcp_config !== undefined) {
+    if (c.strict_work_version !== 1)
+      throw Error('operator_mcp_config is only for the strict work host profile');
+    const config = string(c.operator_mcp_config, 'operator_mcp_config');
+    if (!isAbsolute(config) || realpathSync(config) !== config)
+      throw Error('Use a canonical absolute operator MCP config path');
+    operatorMcp = { config, digest: OperatorMcp.load(config).digest };
+  }
+  let persona: { config: string; digest: string } | undefined;
+  if (c.persona_config !== undefined) {
+    if (c.strict_work_version !== 1)
+      throw Error('persona_config is only for the strict work host profile');
+    const config = string(c.persona_config, 'persona_config');
+    persona = { config, digest: loadPersona(config).digest };
+  }
+  let ttl: number | undefined;
+  if (c.approval_ttl_ms !== undefined) {
+    if (c.strict_work_version !== 1)
+      throw Error('approval_ttl_ms is only for the strict work host profile');
+    ttl = approvalTtl(c.approval_ttl_ms);
+  }
+  if (c.unsandboxed_commands !== undefined && c.unsandboxed_commands !== 'allow')
+    throw Error('unsandboxed_commands is "allow" or absent');
+  const allowUnsandboxed = c.unsandboxed_commands === 'allow';
+  if (c.command_network !== undefined && c.command_network !== 'broker')
+    throw Error('command_network is "broker" or absent');
+  if (c.command_network_socket !== undefined) {
+    if (c.command_network !== 'broker')
+      throw Error('command_network_socket is only for command_network "broker"');
+    const sock = c.command_network_socket;
+    if (typeof sock !== 'string' || !isAbsolute(sock) || sock.includes('\0'))
+      throw Error('command_network_socket must be an absolute path');
+  }
+  const brokerSocket =
+    c.command_network === 'broker'
+      ? String(c.command_network_socket ?? DEFAULT_COMMAND_NETWORK_SOCKET)
+      : undefined;
+  const state = privateState(string(c.state, 'state'), access?.gid);
   const config = string(c.agentpod_config, 'agentpod_config');
   if (!isAbsolute(config) || realpathSync(config) !== config)
     throw Error('Use a canonical absolute pins path');
@@ -205,7 +351,14 @@ async function planAgentPod(
     ...(station
       ? {
           ...(c.strict_work_version === 1
-            ? { schema: 6 as const, strict_work: { version: 1 as const } }
+            ? {
+                schema: 6 as const,
+                strict_work: { version: 1 as const },
+                ...(access ? { operator_access: access } : {}),
+                ...(operatorMcp ? { operator_mcp: operatorMcp } : {}),
+                ...(persona ? { persona } : {}),
+                ...(ttl !== undefined ? { approval_ttl_ms: ttl } : {}),
+              }
             : { schema: 5 as const }),
           station_execution: station,
           ...(toolkit ? { managed_toolkit: toolkit } : {}),
@@ -231,6 +384,13 @@ async function planAgentPod(
     pins_digest: digest(pins),
     workspace: pins.workspace,
     cli_digest: digest(readFileSync(join(ROOT, 'bin/salaam.mjs'), 'utf8')),
+    local_sandbox: hostLocalSandbox(
+      undefined,
+      undefined,
+      undefined,
+      allowUnsandboxed,
+      brokerSocket,
+    ),
   };
 }
 export function hostDigests() {
@@ -335,6 +495,11 @@ export function readHost(path: string): HostManifest {
         : []),
       ...([5, 6].includes(m.schema) ? ['station_execution'] : []),
       ...(m.schema === 6 ? ['strict_work'] : []),
+      ...(m.schema === 6 && Object.hasOwn(m, 'operator_access') ? ['operator_access'] : []),
+      ...(m.schema === 6 && Object.hasOwn(m, 'operator_mcp') ? ['operator_mcp'] : []),
+      ...(m.schema === 6 && Object.hasOwn(m, 'persona') ? ['persona'] : []),
+      ...(m.schema === 6 && Object.hasOwn(m, 'approval_ttl_ms') ? ['approval_ttl_ms'] : []),
+      ...(Object.hasOwn(m, 'local_sandbox') ? ['local_sandbox'] : []),
     ];
     if (m.mode !== 'agentpod' || Object.keys(m).sort().join(',') !== fields.sort().join(','))
       throw Error('Unsupported AgentPod host manifest fields');
@@ -343,9 +508,55 @@ export function readHost(path: string): HostManifest {
       (Object.keys(object(m.strict_work)).join(',') !== 'version' || m.strict_work.version !== 1)
     )
       throw Error('Unsupported strict work host contract');
-    privateState(m.state);
+    const access = hostOperatorAccess(m);
+    if (access !== undefined) {
+      const a = object(access);
+      if (
+        Object.keys(a).sort().join(',') !== 'gid,group' ||
+        canonical(resolveOperatorGroup(a.group)) !== canonical({ group: a.group, gid: a.gid })
+      )
+        throw Error('Host operator group changed');
+    }
+    privateState(m.state, access?.gid);
+    if (m.schema === 6 && Object.hasOwn(m, 'approval_ttl_ms')) approvalTtl(m.approval_ttl_ms);
+    if (m.schema === 6 && Object.hasOwn(m, 'operator_mcp')) {
+      const o = object(m.operator_mcp);
+      if (
+        Object.keys(o).sort().join(',') !== 'config,digest' ||
+        typeof o.config !== 'string' ||
+        !isAbsolute(o.config) ||
+        realpathSync(o.config) !== o.config ||
+        OperatorMcp.load(o.config).digest !== o.digest
+      )
+        throw Error('Operator MCP declarations changed');
+    }
+    if (m.schema === 6 && Object.hasOwn(m, 'persona')) {
+      const p = object(m.persona);
+      let current: string | null = null;
+      try {
+        current = loadPersona(String(p.config)).digest;
+      } catch {
+        current = null;
+      }
+      if (Object.keys(p).sort().join(',') !== 'config,digest' || current !== p.digest)
+        throw Error('Host persona changed; run host plan again');
+    }
     if (m.cli_digest !== digest(readFileSync(join(ROOT, 'bin/salaam.mjs'), 'utf8')))
       throw Error('Host CLI changed');
+    if (
+      Object.hasOwn(m, 'local_sandbox') &&
+      canonical(m.local_sandbox) !==
+        canonical(
+          hostLocalSandbox(
+            undefined,
+            undefined,
+            undefined,
+            hostAllowsUnsandboxed(m),
+            hostCommandNetwork(m)?.socket,
+          ),
+        )
+    )
+      throw Error('Host command sandbox changed; run host plan again');
     const pins = readAgentPodPins(m.agentpod_config, m.state);
     const managed = hostMcp(m);
     if (m.schema === 3 || ([4, 5, 6].includes(m.schema) && Object.hasOwn(m, 'managed_mcp'))) {
@@ -396,6 +607,33 @@ export function readHost(path: string): HostManifest {
   }
   return m;
 }
+/** What the daemon reports about itself so that a caller which cannot read the
+ * manifest (the launcher profile) receives the same receipt as host start. */
+export function hostReceipt(m: HostManifest) {
+  if (m.schema === 1) return undefined;
+  const pins = readAgentPodPins(m.agentpod_config, m.state);
+  return {
+    version: 1,
+    ready: true,
+    manifest_digest: digest(m),
+    node: m.node,
+    cli: join(m.repo, 'bin/salaam.mjs'),
+    state: m.state,
+    workspace: m.workspace,
+    node_id: pins.node_id,
+    pins_digest: m.pins_digest,
+    strict_work: m.schema === 6 ? m.strict_work : null,
+  };
+}
+/** The tools user a reviewed station config names, for host serve's --tools-user. */
+export function hostToolsUser(m: HostManifest): string | undefined {
+  if (m.schema !== 5 && m.schema !== 6) return undefined;
+  return readStationConfig(
+    m.station_execution.config,
+    m.workspace,
+    m.station_execution.configuration_digest,
+  ).tools_user;
+}
 export function hostUnit(path: string, platform: string): string {
   const m = readHost(path),
     manifest = realpathSync(path),