@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/src/host.ts

@@ -1,4 +1,6 @@
-import { spawn } from 'node:child_process';
+import { DEFAULT_COMMAND_NETWORK_SOCKET } from './command-network.js';
+import { loadDangerClassifierOptions } from './danger-classifier.js';
+import { spawn, execFileSync } from 'node:child_process';
 import { once } from 'node:events';
 import {
   readFileSync,
@@ -30,6 +32,14 @@ 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,
+  resolveReadPaths,
+  sandboxLabel,
+  type SandboxKind,
+} from './command-sandbox.js';
+import { loadPersona } from './persona.js';
 interface HostIdentity {
   node: string;
   node_version: string;
@@ -53,6 +63,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 +89,135 @@ 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 };
+  /** Phase 1 (2026-10-31): operator-allowed read-only paths outside the workspace, resolved at host
+   * plan (`toolchain` expanded) so the reviewed manifest names every one. */
+  read_paths?: string[];
+  /** Phase 2b: whether an interactive session on this host may choose full access (no OS sandbox).
+   * Hosts allow it only when the operator sets `allow_full_access_sessions: true`. */
+  full_access_sessions?: 'allow';
+  /** Operator ruling 2026-10-31: whether a desk session on this host may choose YOLO (no sandbox, no
+   * approvals). Hosts allow it only when the operator sets `allow_yolo_sessions: true`. */
+  yolo_sessions?: 'allow';
+  /** Operator 2026-10-31: the command reviewer on this host. Forbidden unless the operator names a
+   * reviewed config (its digest pinned here), optionally pinning one of its options. */
+  danger_classifier?:
+    { mode: 'forbid' } | { mode: 'config'; config: string; digest: string; pin?: string };
+}
+export function hostLocalSandbox(
+  platform: NodeJS.Platform = process.platform,
+  find?: Parameters<typeof chooseLocalSandbox>[2],
+  findSb?: Parameters<typeof chooseLocalSandbox>[3],
+  allowUnsandboxed = false,
+  brokerSocket?: string,
+  readPaths: readonly string[] = [],
+  allowFullAccessSessions = false,
+  allowYoloSessions = false,
+  dangerClassifier?: HostLocalSandbox['danger_classifier'],
+): 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)',
+          },
+        }
+      : {}),
+    ...(readPaths.length ? { read_paths: [...readPaths] } : {}),
+    ...(allowFullAccessSessions ? { full_access_sessions: 'allow' as const } : {}),
+    ...(allowYoloSessions ? { yolo_sessions: 'allow' as const } : {}),
+    ...(dangerClassifier ? { danger_classifier: dangerClassifier } : {}),
+  };
+}
+/** The read-only paths outside the workspace the reviewed manifest lets local commands read. */
+export function hostReadPaths(m: HostManifest): string[] {
+  const r = (m as { local_sandbox?: HostLocalSandbox }).local_sandbox?.read_paths;
+  return Array.isArray(r) ? r.filter((p): p is string => typeof p === 'string') : [];
+}
+/** Whether the reviewed manifest lets an interactive session choose full access (Phase 2b). */
+export function hostAllowsFullAccessSessions(m: HostManifest): boolean {
+  return (
+    (m as { local_sandbox?: HostLocalSandbox }).local_sandbox?.full_access_sessions === 'allow'
+  );
+}
+/** Whether the reviewed manifest lets a desk session choose YOLO. */
+export function hostAllowsYoloSessions(m: HostManifest): boolean {
+  return (m as { local_sandbox?: HostLocalSandbox }).local_sandbox?.yolo_sessions === 'allow';
+}
+/** The command reviewer a host service may run: a reviewed config and optional pin, or none
+ * ({ pin: 'off' }). Absent means forbidden: hosts get no reviewer without the operator. */
+export function hostDangerClassifier(m: HostManifest): { config?: string; pin?: string } {
+  const d = (m as { local_sandbox?: HostLocalSandbox }).local_sandbox?.danger_classifier;
+  if (!d || d.mode !== 'config') return { pin: 'off' };
+  return { config: d.config, ...(d.pin ? { pin: d.pin } : {}) };
+}
+/** 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 +249,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 +259,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 +287,17 @@ 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',
+    'local_sandbox_read_paths',
+    'allow_full_access_sessions',
+    'allow_yolo_sessions',
+    'danger_classifier',
   ];
   if (Object.keys(c).some((k) => !fields.includes(k)))
     throw Error('Unexpected AgentPod host config field');
@@ -153,7 +306,71 @@ 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.allow_full_access_sessions !== undefined && c.allow_full_access_sessions !== true)
+    throw Error('allow_full_access_sessions is true or absent');
+  const allowFullAccessSessions = c.allow_full_access_sessions === true;
+  if (c.allow_yolo_sessions !== undefined && c.allow_yolo_sessions !== true)
+    throw Error('allow_yolo_sessions is true or absent');
+  const allowYoloSessions = c.allow_yolo_sessions === true;
+  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 dangerClassifier = parseHostDangerClassifier(c.danger_classifier);
+  let readPaths: string[] = [];
+  if (c.local_sandbox_read_paths !== undefined) {
+    const raw = c.local_sandbox_read_paths;
+    if (!Array.isArray(raw) || raw.some((p) => typeof p !== 'string'))
+      throw Error('local_sandbox_read_paths is a list of absolute paths or "toolchain"');
+    try {
+      readPaths = resolveReadPaths(raw as string[]);
+    } catch (error) {
+      throw Error((error as Error).message);
+    }
+  }
+  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 +422,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 +455,54 @@ 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,
+      readPaths,
+      allowFullAccessSessions,
+      allowYoloSessions,
+      dangerClassifier,
+    ),
+  };
+}
+function reviewerDigest(path: string): string | null {
+  try {
+    return digest(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+function parseHostDangerClassifier(raw: unknown): HostLocalSandbox['danger_classifier'] {
+  if (raw === undefined) return undefined;
+  if (raw === 'forbid') return { mode: 'forbid' };
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+    throw Error('danger_classifier is "forbid" or { config, pin? }');
+  const c = raw as Record<string, unknown>;
+  if (Object.keys(c).some((k) => k !== 'config' && k !== 'pin'))
+    throw Error('danger_classifier takes only config and pin');
+  if (typeof c.config !== 'string' || !isAbsolute(c.config) || c.config.includes('\0'))
+    throw Error('danger_classifier.config must be an absolute path');
+  let names: string[];
+  try {
+    // Keys are named by environment variable and checked when the service starts, not here.
+    const anyKey = new Proxy({}, { get: () => 'checked-at-start' }) as Record<string, string>;
+    names = loadDangerClassifierOptions(
+      JSON.parse(readFileSync(c.config, 'utf8')),
+      anyKey,
+    ).options.map((o) => o.name);
+  } catch (error) {
+    throw Error('danger_classifier.config: ' + (error as Error).message);
+  }
+  if (c.pin !== undefined && (typeof c.pin !== 'string' || !names.includes(c.pin)))
+    throw Error("danger_classifier.pin must name one of the config's options");
+  return {
+    mode: 'config',
+    config: c.config,
+    digest: reviewerDigest(c.config)!,
+    ...(typeof c.pin === 'string' ? { pin: c.pin } : {}),
   };
 }
 export function hostDigests() {
@@ -335,6 +607,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 +620,64 @@ 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,
+            hostReadPaths(m),
+            hostAllowsFullAccessSessions(m),
+            hostAllowsYoloSessions(m),
+            (m as { local_sandbox?: HostLocalSandbox }).local_sandbox?.danger_classifier,
+          ),
+        )
+    )
+      throw Error('Host command sandbox changed; run host plan again');
+    {
+      const d = (m as { local_sandbox?: HostLocalSandbox }).local_sandbox?.danger_classifier;
+      if (d?.mode === 'config' && reviewerDigest(d.config) !== d.digest)
+        throw Error('Host command reviewer config 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 +728,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),