@superjackfruitlabs/salaam 0.0.3 → 0.0.4

package/src/board-reads.ts

@@ -0,0 +1,148 @@
+import { randomUUID } from 'node:crypto';
+import type { Store } from './store.js';
+import { ServiceError } from './protocol.js';
+
+/**
+ * Board reads (operator ruling 2026-10-28, option iii). While it works, the agent may read its own
+ * card, its card's runs, and search or open library items, the way an agent with board tools does.
+ * Salaam holds no SuperPipeline or SuperLibrary credential: it records the read, the hub sees it in
+ * work status, serves it with its own clients, and answers. A read names no card, board or
+ * credential; the hub decides scope from the run it is serving. Read-only: nothing here asks for
+ * approval, and nothing a read returns authorizes anything.
+ */
+export type BoardReadAction = 'card' | 'attempts' | 'library_search' | 'library_get';
+export interface BoardRead {
+  id: string;
+  action: BoardReadAction;
+  args: Record<string, string>;
+  state: 'pending' | 'answered';
+  ok?: boolean;
+  text?: string;
+  error?: string;
+}
+const ITEM = /^itm_[0-9a-f]{16}$/;
+/** The most a hub answer may carry back to the agent. */
+export const BOARD_READ_MAX_BYTES = 256 * 1024;
+
+const bad = (message: string) => new ServiceError('invalid_board_read', message, 400);
+
+/** Closed arguments per action; anything else is refused. */
+export function boardReadArgs(input: Record<string, unknown>): {
+  action: BoardReadAction;
+  args: Record<string, string>;
+} {
+  const { action, ...rest } = input;
+  const keys = Object.keys(rest).filter((k) => rest[k] !== undefined);
+  if (action === 'card' || action === 'attempts') {
+    if (keys.length) throw bad(`${action} takes no arguments: it is always this run's own card`);
+    return { action, args: {} };
+  }
+  if (action === 'library_search') {
+    const q = rest.query;
+    if (keys.join() !== 'query' || typeof q !== 'string' || !q.trim() || q.length > 500)
+      throw bad('library_search takes one query of 1 to 500 characters');
+    return { action, args: { query: q.trim() } };
+  }
+  if (action === 'library_get') {
+    const id = rest.item_id;
+    if (keys.join() !== 'item_id' || typeof id !== 'string' || !ITEM.test(id))
+      throw bad('library_get takes one item_id (itm_ and 16 hex characters)');
+    return { action, args: { item_id: id } };
+  }
+  throw bad('Board reads are card, attempts, library_search or library_get');
+}
+
+export class BoardReads {
+  constructor(private readonly store: Store) {
+    store.db.exec(`CREATE TABLE IF NOT EXISTS board_reads(
+      id TEXT PRIMARY KEY, session_id TEXT NOT NULL, tool_call_id TEXT NOT NULL, action TEXT NOT NULL,
+      args TEXT NOT NULL, state TEXT NOT NULL, ok INTEGER, text TEXT, error TEXT,
+      created_at TEXT NOT NULL, answered_at TEXT, UNIQUE(session_id, tool_call_id))`);
+  }
+  private view(row: Record<string, unknown>): BoardRead {
+    return {
+      id: String(row.id),
+      action: String(row.action) as BoardReadAction,
+      args: JSON.parse(String(row.args)) as Record<string, string>,
+      state: String(row.state) as BoardRead['state'],
+      ...(row.state === 'answered'
+        ? {
+            ok: row.ok === 1,
+            ...(row.text !== null ? { text: String(row.text) } : {}),
+            ...(row.error !== null ? { error: String(row.error) } : {}),
+          }
+        : {}),
+    };
+  }
+  /** Record a read for this session, once per tool call. */
+  request(session: string, toolCallId: string, input: Record<string, unknown>): BoardRead {
+    const { action, args } = boardReadArgs(input);
+    const existing = this.store.db
+      .prepare('SELECT * FROM board_reads WHERE session_id=? AND tool_call_id=?')
+      .get(session, toolCallId);
+    if (existing) return this.view(existing);
+    const id = randomUUID();
+    this.store.db
+      .prepare(
+        "INSERT INTO board_reads(id,session_id,tool_call_id,action,args,state,created_at) VALUES (?,?,?,?,?,'pending',?)",
+      )
+      .run(id, session, toolCallId, action, JSON.stringify(args), new Date().toISOString());
+    return this.get(session, id);
+  }
+  get(session: string, id: string): BoardRead {
+    const row = this.store.db
+      .prepare('SELECT * FROM board_reads WHERE id=? AND session_id=?')
+      .get(id, session);
+    if (!row) throw new ServiceError('board_read_not_found', 'No such board read', 404);
+    return this.view(row);
+  }
+  /** What the hub should serve for this session, oldest first. */
+  pending(
+    session: string,
+  ): { id: string; action: BoardReadAction; args: Record<string, string> }[] {
+    return this.store.db
+      .prepare(
+        "SELECT * FROM board_reads WHERE session_id=? AND state='pending' ORDER BY rowid LIMIT 8",
+      )
+      .all(session)
+      .map((r) => {
+        const v = this.view(r);
+        return { id: v.id, action: v.action, args: v.args };
+      });
+  }
+  /** The hub's answer: once, for a read of this session, bounded. */
+  answer(session: string, value: unknown): BoardRead {
+    const a = (value ?? {}) as Record<string, unknown>;
+    const keys = Object.keys(a).sort().join();
+    const ok = a.ok === true;
+    if (
+      typeof a.read_id !== 'string' ||
+      (ok
+        ? keys !== 'ok,read_id,text' || typeof a.text !== 'string'
+        : keys !== 'error,ok,read_id' || a.ok !== false || typeof a.error !== 'string')
+    )
+      throw bad('Closed board read answer required');
+    const body = ok ? (a.text as string) : (a.error as string);
+    if (Buffer.byteLength(body) > (ok ? BOARD_READ_MAX_BYTES : 2048))
+      throw bad('Board read answer too large');
+    const done = this.store.db
+      .prepare(
+        "UPDATE board_reads SET state='answered',ok=?,text=?,error=?,answered_at=? WHERE id=? AND session_id=? AND state='pending'",
+      )
+      .run(
+        ok ? 1 : 0,
+        ok ? body : null,
+        ok ? null : body,
+        new Date().toISOString(),
+        a.read_id,
+        session,
+      );
+    if (done.changes !== 1)
+      throw new ServiceError(
+        'board_read_settled',
+        'That board read is not pending for this run',
+        409,
+      );
+    return this.get(session, a.read_id);
+  }
+}

package/src/children.ts

@@ -7,6 +7,8 @@ import type { RepositorySnapshots } from './repository-snapshots.js';
 import type { WorkerWorkspaces } from './worker-workspaces.js';
 import type { ExternalRuntime } from './external-runtime.js';
 import type { ExternalWork } from './external-work.js';
+import type { AgentGrant } from './agent-profiles.js';
+import type { WorkspaceTree } from './workspaces.js';
 
 export class ChildWork {
   external?: ExternalWork;
@@ -222,6 +224,116 @@ export class ChildWork {
       this.start(child);
     return child;
   }
+  /**
+   * The task critic (item 8): a reviewer child over an immutable snapshot of the verified
+   * deliverables. No parent attempt is active at completion, so it is linked to the task's last
+   * step attempt and charged to its own bounded budget, never to an attempt's reservation. The
+   * grant must be the built-in reviewer; the child can read the snapshot and report findings only.
+   */
+  spawnCritic(
+    parent: string,
+    parentAttempt: string,
+    step: string,
+    prompt: string,
+    budget: number,
+    grant: AgentGrant,
+    snapshot: WorkspaceTree,
+  ): ChildTask {
+    if (!Number.isSafeInteger(budget) || budget < 1 || budget > 8)
+      throw new ServiceError('invalid_budget', 'Critic request budget must be 1–8');
+    if (grant.profile.id !== 'salaam/reviewer' || grant.owner_session !== parent)
+      throw new ServiceError('authority_denied', 'The critic must be the built-in reviewer');
+    if (!Object.keys(snapshot).length)
+      throw new ServiceError(
+        'invalid_child',
+        'A critic needs a snapshot of the verified deliverables',
+      );
+    if (!prompt.trim() || prompt.length > 32768)
+      throw new ServiceError('invalid_child', 'Invalid critic prompt');
+    const authority = [...grant.profile.tools].sort();
+    const input = digest({
+      prompt,
+      budget,
+      critic: grant.profile_digest,
+      snapshot: digest(snapshot),
+    });
+    const prepare = () => {
+      const old = this.store.db
+        .prepare('SELECT * FROM child_tasks WHERE parent_session=? AND step_key=?')
+        .get(parent, step) as unknown as ChildTask | undefined;
+      if (old) {
+        if (old.input_digest !== input)
+          throw new ServiceError('spawn_conflict', 'Critic step already binds a different review');
+        return { child: old, fresh: false };
+      }
+      if (this.paused) throw new ServiceError('stopping', 'Child dispatch is stopping');
+      this.store.execution.assert(parent);
+      if (this.activeCount() >= 8)
+        throw new ServiceError('child_limit', 'Daemon worker admission limit reached');
+      const effectivePrompt = `${grant.profile.prompt}\n\nGoal:\n${prompt}`;
+      const id = randomUUID(),
+        session = randomUUID(),
+        submission = randomUUID(),
+        childAttempt = randomUUID();
+      this.store.db
+        .prepare('INSERT INTO sessions(id,cwd,pi_session_id) VALUES (?,?,?)')
+        .run(session, this.store.session(parent).cwd, session);
+      this.store.db
+        .prepare('INSERT INTO submissions(id,session_id,text,attempt_id) VALUES (?,?,?,?)')
+        .run(submission, session, effectivePrompt, childAttempt);
+      this.store.db
+        .prepare(
+          "INSERT INTO attempts(id,session_id,submission_id,state) VALUES (?,?,?,'accepted')",
+        )
+        .run(childAttempt, session, submission);
+      this.store.db
+        .prepare(
+          "INSERT INTO child_tasks(id,parent_session,parent_attempt,step_key,input_digest,child_session,child_attempt,authority,budget,state) VALUES (?,?,?,?,?,?,?,?,?,'accepted')",
+        )
+        .run(
+          id,
+          parent,
+          parentAttempt,
+          step,
+          input,
+          session,
+          childAttempt,
+          JSON.stringify(authority),
+          budget,
+        );
+      this.store.taskChildReserve?.(parent, childAttempt, budget);
+      this.store.usage.budget(childAttempt, budget);
+      const artifact = this.artifacts.prepare(session, effectivePrompt);
+      artifact.commit();
+      // The reviewed snapshot is the verified bytes; its base is empty, so its diff is all of it.
+      const current = this.artifacts.prepare(session, JSON.stringify(snapshot)),
+        base = this.artifacts.prepare(session, JSON.stringify({}));
+      current.commit();
+      base.commit();
+      this.store.workerBoundary.freeze(this.owned(session)!, artifact.id, false, grant, {
+        artifact_id: current.id,
+        base_artifact: base.id,
+        digest: digest(snapshot),
+      });
+      this.store.event(session, 'session.created', { parent_session: parent, child_id: id });
+      this.store.event(session, 'submission.accepted', {
+        attempt_id: childAttempt,
+        submission_id: submission,
+      });
+      this.store.event(parent, 'child.spawned', {
+        child_id: id,
+        child_session: session,
+        step_key: step,
+        budget,
+        authority,
+        critic: true,
+      });
+      return { child: this.inspect(parent, id), fresh: true };
+    };
+    const { child, fresh } = this.store.transaction(prepare);
+    if (fresh) this.start(child);
+    return child;
+  }
   activeCount(parent?: string): number {
     return Number(
       this.store.db

package/src/cli-help.ts

@@ -103,6 +103,10 @@ salaam host inspect --manifest host-manifest.json
 salaam host unit --manifest host-manifest.json --platform systemd|launchd
 salaam host run --manifest host-manifest.json
 salaam host start --manifest host-manifest.json
+salaam host unit-start --unit salaam-host@STATION.service --state DIR
+salaam host bind --organization ORG --node NODE --station-key KEY --workspace DIR \
+  --tools-user USER --files HELPER --runtime-root DIR --runtime-image-digest sha256:… \
+  [--operator-group GROUP] [--provider P --model M] [--mcp-config FILE] [--persona FILE] [--managed-mcp-config FILE] [--dir DIR] [--state DIR]
 
 Config requires absolute state, coding_root and coding_socket paths; optional
 provider, model, max_output_tokens and workspace_id. Planning probes the existing
@@ -116,7 +120,18 @@ For a bound AgentPod host, use mode="agentpod", state and agentpod_config instea
 of coding_root/coding_socket. This profile enables no station tools. The private
 manifest pins Node, CLI, source/build, Pi, provider and authority pins. Invoke the
 canonical Node executable explicitly. host start waits for matching live health
-and safely coalesces concurrent callers; it never installs or upgrades packages.`,
+and safely coalesces concurrent callers; it never installs or upgrades packages.
+
+Launcher profile (Linux): root plans a strict work host with operator_group set.
+A root-owned unit runs host run from that root-held manifest. The daemon lets that
+one group traverse its state and use operator.sock. An unprivileged member then
+runs host unit-start, which asks systemd to start the named salaam-host@ unit and
+prints the receipt the running daemon reports. It cannot choose what root runs.
+
+host bind (root, Linux) writes everything a launcher-profile station needs into
+--dir (default /etc/salaam/stations/<key>): agentpod-pins.json, station-config.json
+(with tools_user), host-config.json, and host.json from host plan. It is
+idempotent: the same inputs leave the files and the manifest digest unchanged.`,
   schedules: `salaam schedules create TASK_ID --name NAME --revision N --max-steps N [--schedule FILE] [--compact]
 salaam schedules list [--offset N]
 salaam schedules inspect JOB_ID
@@ -208,10 +223,18 @@ Status prints metadata only. Existing Anthropic keys remain compatible.`,
                      [--coding-root PRIVATE_DIR] [--coding-socket DOCKER_SOCKET]
                      [--harness-config OWNER_ONLY_FILE] [--a2a-config OWNER_ONLY_FILE]
                      [--a2a-listen-config OWNER_ONLY_FILE]
-                     [--agentpod-config OWNER_ONLY_FILE]
+                     [--agentpod-config OWNER_ONLY_FILE] [--mcp-config FILE]
+                     [--tools-user USER]
 salaam service status
 salaam service stop
 
+--tools-user USER (or SALAAM_TOOLS_USER) runs local agent commands and edits as
+USER through sudo -n -u USER on Linux. Without it, tools share the provider
+credential's OS user and start prints a warning.
+
+Without --agentpod-config, start binds to ~/.config/salaam/agentpod-pins.json
+($XDG_CONFIG_HOME/salaam) when that file exists.
+
 The default provider is offline. Anthropic defaults to claude-sonnet-5-5.
 Other providers require --model; use salaam providers list and salaam models list PROVIDER.
 Start with --foreground for process-supervisor use; otherwise the service detaches.
@@ -286,6 +309,7 @@ Commands:
   auth          Configure provider credentials or OAuth
   service       Start, inspect or stop the session service
   session       Create, inspect, submit, resume or cancel work
+  mcp           Declare operator MCP servers (add, list, rm)
   attach        Open an interactive terminal on a session
   acp           Connect an editor over ACP v1 stdio
   approvals     Inspect, approve or deny managed operations
@@ -356,6 +380,7 @@ const valueOptions = new Set([
   '--a2a-config',
   '--agentpod-config',
   '--a2a-listen-config',
+  '--tools-user',
   '--assignment',
   '--peer',
   '--peer-client',

package/src/cli.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { SANDBOX_LEVELS, type SandboxLevel } from './command-sandbox.js';
 import { acp } from './acp.js';
 import { homedir } from 'node:os';
 import { join, resolve, dirname } from 'node:path';
@@ -14,9 +15,13 @@ import {
   realpathSync,
   writeFileSync,
   fsyncSync,
+  existsSync,
 } from 'node:fs';
 import { ROOT, VERSION } from './config.js';
 import { cliHelp, hasHelpFlag } from './cli-help.js';
+import { mcpCli, MCP_HELP } from './operator-mcp-cli.js';
+import { operatorMcpPath, readOperatorMcpFile } from './operator-mcp.js';
+import { defaultAgentPodConfig } from './agentpod-default-config.js';
 import { SalaamService } from './service.js';
 import { call } from './transport.js';
 import { attach, acquireControl, Outbox } from './attach.js';
@@ -62,6 +67,15 @@ async function main(): Promise<void> {
     console.log('salaam ' + VERSION);
     return;
   }
+  if (args[0] === 'mcp') {
+    // Parsed before global help: a declared command's own flags follow "--".
+    const rest = args.slice(1);
+    const dash = rest.indexOf('--');
+    const flags = dash < 0 ? rest : rest.slice(0, dash);
+    if (!rest.length || flags.includes('--help') || flags.includes('-h')) console.log(MCP_HELP);
+    else console.log(mcpCli(rest));
+    return;
+  }
   if (
     (!args.length && !(process.stdin.isTTY && process.stdout.isTTY)) ||
     args[0] === 'help' ||
@@ -494,7 +508,17 @@ async function main(): Promise<void> {
     return;
   }
   if (group === 'host') {
-    const { planHost, readHost, hostUnit, runHost } = await import('./host.js');
+    const {
+      planHost,
+      readHost,
+      hostUnit,
+      runHost,
+      hostReceipt,
+      hostToolsUser,
+      hostApprovalTtlMs,
+      hostAllowsUnsandboxed,
+      hostCommandNetwork,
+    } = await import('./host.js');
     if (verb?.startsWith('config-')) {
       const file = option('--manifest');
       if (!file) throw Error('Supply --manifest FILE');
@@ -526,6 +550,44 @@ async function main(): Promise<void> {
       );
       return;
     }
+    if (verb === 'bind') {
+      const { bindHost } = await import('./host-bind.js');
+      const required = (name: string) => {
+        const v = option(name);
+        if (!v) throw new Error('Supply ' + name);
+        return v;
+      };
+      console.log(
+        JSON.stringify(
+          await bindHost({
+            organization_id: required('--organization'),
+            node_id: required('--node'),
+            station_key: required('--station-key'),
+            workspace: required('--workspace'),
+            tools_user: required('--tools-user'),
+            files: required('--files'),
+            runtime_root: required('--runtime-root'),
+            runtime_image_digest: required('--runtime-image-digest'),
+            operator_group: option('--operator-group'),
+            dir: option('--dir'),
+            state: explicitState ? state : undefined,
+            provider: option('--provider'),
+            model: option('--model'),
+            mcp_config: option('--mcp-config'),
+            persona: option('--persona'),
+            managed_mcp_config: option('--managed-mcp-config'),
+          }),
+        ),
+      );
+      return;
+    }
+    if (verb === 'unit-start') {
+      const { startHostUnit } = await import('./host-start.js');
+      const unit = option('--unit');
+      if (!unit || !explicitState) throw new Error('Supply --unit UNIT and --state DIR');
+      console.log(JSON.stringify(await startHostUnit(unit, state)));
+      return;
+    }
     const file = option('--manifest');
     if (!file) throw new Error('Supply --manifest FILE');
     if (verb === 'inspect') {
@@ -585,9 +647,21 @@ async function main(): Promise<void> {
                   : {}),
                 ...(m.schema === 5 || m.schema === 6 ? { stationConfig: m.station_execution } : {}),
                 ...(m.schema === 6 ? { agentpodWorkProgression: true } : {}),
+                ...(m.schema === 6 && m.operator_access
+                  ? { operatorAccess: m.operator_access }
+                  : {}),
+                ...(m.schema === 6 && m.operator_mcp
+                  ? { operatorMcpConfig: m.operator_mcp.config }
+                  : {}),
+                ...(m.schema === 6 && m.persona ? { personaConfig: m.persona } : {}),
               }),
           hostManifestDigest: digest(m),
+          hostReceipt: hostReceipt(m),
+          toolsUser: hostToolsUser(m),
           providerRoute: m.provider,
+          approvalTtlMs: hostApprovalTtlMs(m),
+          ...(hostAllowsUnsandboxed(m) ? { unsandboxedCommands: 'allow' as const } : {}),
+          ...(hostCommandNetwork(m) ? { commandNetwork: hostCommandNetwork(m)! } : {}),
         });
       if (process.connected) process.once('disconnect', () => void service.close());
       for (const signal of ['SIGTERM', 'SIGINT'] as const)
@@ -1553,24 +1627,41 @@ async function main(): Promise<void> {
       codingSocket = option('--coding-socket'),
       harnessConfig = option('--harness-config'),
       a2aConfig = option('--a2a-config'),
-      agentpodConfig = option('--agentpod-config'),
-      a2aListenConfig = option('--a2a-listen-config');
+      agentpodConfig =
+        option('--agentpod-config') ?? defaultAgentPodConfig(process.env, existsSync),
+      a2aListenConfig = option('--a2a-listen-config'),
+      mcpConfig = resolve(option('--mcp-config') ?? operatorMcpPath(process.env)),
+      toolsUser = option('--tools-user') ?? (process.env.SALAAM_TOOLS_USER || undefined),
+      localSandbox = option('--local-sandbox') ?? (process.env.SALAAM_LOCAL_SANDBOX || undefined),
+      unsandboxedCommands =
+        option('--unsandboxed-commands') ?? (process.env.SALAAM_UNSANDBOXED_COMMANDS || undefined);
+    if (localSandbox !== undefined && !(SANDBOX_LEVELS as readonly string[]).includes(localSandbox))
+      throw Error('--local-sandbox is read-only, workspace-write or full-access');
+    if (unsandboxedCommands !== undefined && unsandboxedCommands !== 'allow')
+      throw Error('--unsandboxed-commands is allow or absent');
     if (foreground) {
       const service = await SalaamService.open({
         stateDir: state,
         providerRoute: route,
         agentpodConfig: agentpodConfig ? resolve(agentpodConfig) : undefined,
+        operatorMcpConfig: mcpConfig,
         codingRoot: codingRoot ? resolve(codingRoot) : undefined,
         codingSocket: codingSocket ? resolve(codingSocket) : undefined,
         harnessConfig: harnessConfig ? resolve(harnessConfig) : undefined,
         a2aConfig: a2aConfig ? resolve(a2aConfig) : undefined,
         a2aListenConfig: a2aListenConfig ? resolve(a2aListenConfig) : undefined,
+        toolsUser,
+        ...(localSandbox ? { localSandbox: localSandbox as SandboxLevel } : {}),
+        ...(unsandboxedCommands ? { unsandboxedCommands: 'allow' as const } : {}),
         effectConnector: effectSocket
           ? new SocketEffectConnector(resolve(effectSocket), { opaque })
           : undefined,
       });
       const warning = service.supervisor.providerCapabilities().warning;
       if (warning) console.error(warning);
+      // Only a live provider has a credential to share; the offline proof route stays quiet.
+      if (service.toolIdentity.warning && route.provider !== 'salaam-proof')
+        console.error('warning: ' + service.toolIdentity.warning);
       process.stdout.write(JSON.stringify({ socket, service: 'started' }) + '\n');
       for (const signal of ['SIGINT', 'SIGTERM'] as const)
         process.once(signal, () => {
@@ -1589,6 +1680,7 @@ async function main(): Promise<void> {
           coding_socket?: string | null;
           agentpod_config?: string | null;
           agentpod_pins_digest?: string | null;
+          operator_mcp?: { config: string; digest: string } | null;
         }
       | undefined;
     try {
@@ -1613,6 +1705,15 @@ async function main(): Promise<void> {
         throw new Error(
           'Service is already running with another coding configuration; stop it first',
         );
+      if ((health.operator_mcp?.config ?? null) !== mcpConfig)
+        throw new Error('Service is already running with another MCP config; stop it first');
+      if (
+        health.operator_mcp &&
+        health.operator_mcp.digest !== digest(readOperatorMcpFile(mcpConfig))
+      )
+        console.error(
+          'Declared MCP servers changed since the service started; run salaam service stop, then start, to apply them',
+        );
       console.log('Salaam service already running');
       return;
     }
@@ -1640,6 +1741,11 @@ async function main(): Promise<void> {
         ...(a2aConfig ? ['--a2a-config', resolve(a2aConfig)] : []),
         ...(agentpodConfig ? ['--agentpod-config', resolve(agentpodConfig)] : []),
         ...(a2aListenConfig ? ['--a2a-listen-config', resolve(a2aListenConfig)] : []),
+        '--mcp-config',
+        mcpConfig,
+        ...(toolsUser ? ['--tools-user', toolsUser] : []),
+        ...(localSandbox ? ['--local-sandbox', localSandbox] : []),
+        ...(unsandboxedCommands ? ['--unsandboxed-commands', 'allow'] : []),
       ],
       { detached: true, stdio: ['ignore', fd, fd] },
     );