@superjackfruitlabs/salaam 0.0.3 → 0.0.4

package/src/local-coding.ts

@@ -1,6 +1,18 @@
+import { BrokerRelay, COMMAND_NETWORK_PORT } from './command-network.js';
+import {
+  sandboxArgv,
+  seatbeltArgv,
+  UNSANDBOXED_REFUSAL,
+  type Bwrap,
+  type SandboxKind,
+  type SandboxLevel,
+  type Seatbelt,
+} from './command-sandbox.js';
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { realpathSync } from 'node:fs';
+import { mkdtempSync, realpathSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import type { Store } from './store.js';
 import type { ManagedWork } from './managed.js';
 import { digest, object, string, ServiceError, type Operation } from './protocol.js';
@@ -18,6 +30,13 @@ import {
 } from './autonomy.js';
 import { assertUndoSettled } from './local-undo.js';
 import { processIdentity } from './supervisor.js';
+import {
+  applyEditsAsTools,
+  killToolGroup,
+  serviceToolIdentity,
+  toolArgv,
+  type ToolIdentity,
+} from './tool-identity.js';
 
 interface LocalCall {
   id: string;
@@ -34,6 +53,35 @@ interface LocalCall {
   pid: number | null;
   identity: string | null;
 }
+/**
+ * Item 10: how this host runs local commands. `bwrap` (Linux) or `seatbelt` (macOS): under the OS
+ * sandbox at `level` (full-access only by explicit operator setting). `none`: a host with no usable
+ * sandbox, which refuses local commands unless the operator allowed them unsandboxed
+ * (`allowUnsandboxed`); then it runs them and says so in every approval.
+ */
+export interface LocalSandbox {
+  kind: SandboxKind;
+  level: SandboxLevel;
+  bwrap: Bwrap | null;
+  seatbelt?: Seatbelt | null;
+  /** The host config's `unsandboxed_commands: "allow"` (operator ruling 2026-10-30, option A). */
+  allowUnsandboxed?: boolean;
+  /** The host config's `command_network: "broker"`: a sandboxed command reaches the network only
+   * through this stk local-commands socket (operator rulings 2026-10-30). */
+  network?: { socket: string };
+}
+/** The proxy a broker-network command uses: only the relay on loopback, nothing direct. */
+function proxyEnv(port: number): Record<string, string> {
+  const url = `http://127.0.0.1:${port}`;
+  return {
+    HTTP_PROXY: url,
+    HTTPS_PROXY: url,
+    http_proxy: url,
+    https_proxy: url,
+    NO_PROXY: 'localhost,127.0.0.1',
+    no_proxy: 'localhost,127.0.0.1',
+  };
+}
 export class LocalCoding {
   private jobs = new Map<string, { stop: () => void; done: Promise<void> }>();
   private closed = false;
@@ -42,6 +90,9 @@ export class LocalCoding {
     readonly store: Store,
     readonly managed: ManagedWork,
     readonly active: (s: string, e: number, a: string) => void,
+    readonly tools: ToolIdentity = serviceToolIdentity(),
+    /** Chosen by the service from the host and the operator's setting. */
+    public sandbox: LocalSandbox = { kind: 'none', level: 'full-access', bwrap: null },
   ) {
     this.unregister = managed.registerMcpController('local-coding-v1', {
       owns: (op) => !!store.db.prepare('SELECT 1 FROM local_calls WHERE operation_id=?').get(op.id),
@@ -64,6 +115,8 @@ export class LocalCoding {
           /* outcome remains uncertain */
         }
       }
+      const pgid = c.result ? Number(JSON.parse(c.result).tool_pgid) : NaN;
+      if (Number.isSafeInteger(pgid)) killToolGroup(this.tools, pgid);
       store.transaction(() => {
         this.change(c, 'outcome_unknown', {
           error:
@@ -158,16 +211,43 @@ export class LocalCoding {
     const kind = string(input.action, 'action');
     let args:
       | { action: 'edit'; edits: LocalEdit[] }
-      | { action: 'command'; command: string; timeout_ms: number };
+      | {
+          action: 'command';
+          command: string;
+          timeout_ms: number;
+          sandbox: { kind: string; level: string; bwrap: string | null; network?: 'broker' };
+        };
     if (kind === 'edit') args = { action: 'edit', edits: prepareLocalEdits(root, input.edits) };
     else if (kind === 'command') {
       const timeout = input.timeout_ms ?? 30000;
       if (!Number.isInteger(timeout) || Number(timeout) < 100 || Number(timeout) > 120000)
         throw new ServiceError('invalid_field', 'Command timeout must be 100–120000 ms');
+      if (
+        this.sandbox.kind === 'bwrap' &&
+        this.sandbox.level !== 'full-access' &&
+        !this.sandbox.bwrap
+      )
+        throw new ServiceError(
+          'sandbox_unavailable',
+          'This host has no usable bubblewrap, so it cannot run a sandboxed command; an operator can choose full access explicitly',
+        );
+      if (
+        this.sandbox.kind === 'none' &&
+        this.sandbox.level !== 'full-access' &&
+        !this.sandbox.allowUnsandboxed
+      )
+        throw new ServiceError('sandbox_unavailable', UNSANDBOXED_REFUSAL);
       args = {
         action: 'command',
         command: string(input.command, 'command', 8192),
         timeout_ms: Number(timeout),
+        // Bound into the approval and the operation digest: the sandbox is part of what is approved.
+        sandbox: {
+          kind: this.sandbox.kind,
+          level: this.sandbox.level,
+          bwrap: this.sandbox.bwrap?.version ?? null,
+          ...(this.brokerNetwork() ? { network: 'broker' as const } : {}),
+        },
       };
     } else throw new ServiceError('invalid_field', 'Choose edit or command');
     c.args = JSON.stringify(args);
@@ -177,7 +257,7 @@ export class LocalCoding {
           ? args.edits
               .map((e) => `--- ${e.path}\n${e.before ?? '(new file)'}\n+++ ${e.path}\n${e.after}`)
               .join('\n\n')
-          : `Runs as your local user, outside an OS sandbox. May access files and network beyond this workspace.\nDirectory: ${root}\nTimeout: ${args.timeout_ms} ms\nCommand:\n${args.command}`;
+          : `Runs as ${this.tools.mode === 'tools-user' ? `tools user ${this.tools.user} (uid ${this.tools.uid})` : 'your local user'}, ${this.sandboxText()}\nDirectory: ${root}\nTimeout: ${args.timeout_ms} ms\nCommand:\n${args.command}`;
       const permission = this.managed.prepareWorkspaceInTransaction(
         session,
         epoch,
@@ -287,16 +367,19 @@ export class LocalCoding {
       try {
         verifyLocalEdits(c.root, args.edits as LocalEdit[]);
         entered = true;
-        applyLocalEdits(c.root, args.edits as LocalEdit[], (path) => {
+        const progress = (path: string) => {
           applied.push(path);
           this.store.transaction(() => this.change(c, 'running', { applied }));
-        });
+        };
+        if (this.tools.mode === 'tools-user')
+          applyEditsAsTools(this.tools, c.root, args.edits as LocalEdit[], progress);
+        else applyLocalEdits(c.root, args.edits as LocalEdit[], progress);
         verifyLocalEdits(
           c.root,
           (args.edits as LocalEdit[]).map((edit) => ({ ...edit, before: edit.after })),
         );
         this.store.transaction(() => {
-          const result = { applied, verified: true };
+          const result = { applied, verified: true, tool_uid: this.tools.uid };
           this.change(c, 'succeeded', result);
           this.managed.workspaceResultInTransaction(c.operation_id, result);
         });
@@ -316,17 +399,125 @@ export class LocalCoding {
     } else this.command(c, String(args.command), Number(args.timeout_ms));
     return this.view(id);
   }
+  private sandboxText(): string {
+    const { kind, level } = this.sandbox;
+    if (level === 'full-access')
+      return 'unsandboxed: the operator chose full access. May access files and network beyond this workspace.';
+    if (kind === 'none')
+      return 'unsandboxed: this host has no usable command sandbox, so the command may access files and network beyond this workspace.';
+    const name = kind === 'seatbelt' ? 'Seatbelt' : 'bubblewrap';
+    const net = this.brokerNetwork()
+      ? 'network: through the broker allowlist (hosts set by the stk policy), nothing direct.'
+      : 'has no network.';
+    return level === 'read-only'
+      ? `in a ${name} sandbox (read-only): it can read this workspace but write nothing, and ${net}`
+      : `in a ${name} sandbox (workspace-write): it can write only inside this workspace, and ${net}`;
+  }
+  /** Broker network applies only to a sandboxed command: unsandboxed ones are not confined anyway. */
+  private brokerNetwork(): { socket: string } | null {
+    return this.sandbox.network &&
+      this.sandbox.kind !== 'none' &&
+      this.sandbox.level !== 'full-access'
+      ? this.sandbox.network
+      : null;
+  }
+  /** The process a command runs as. Under the tools user, the host-side shell reports its own
+   * process group (the one a stop kills) before exec-ing bubblewrap, whose PID namespace would
+   * otherwise report a number that means nothing on the host. */
+  private commandArgv(
+    root: string,
+    script: string,
+    tmp?: string,
+    relay?: BrokerRelay | null,
+  ): string[] {
+    const sandboxed = this.sandbox.kind !== 'none' && this.sandbox.level !== 'full-access';
+    const inner = (s: string) =>
+      !sandboxed
+        ? ['/bin/sh', '-c', s]
+        : this.sandbox.kind === 'seatbelt'
+          ? seatbeltArgv(
+              this.sandbox.level,
+              root,
+              tmp ?? '',
+              ['/bin/sh', '-c', s],
+              this.sandbox.seatbelt ?? null,
+              { network: false, ...(relay?.port ? { brokerPort: relay.port } : {}) },
+            )
+          : sandboxArgv(this.sandbox.level, root, ['/bin/sh', '-c', s], this.sandbox.bwrap, {
+              network: false,
+              ...(relay?.dir ? { broker: { dir: relay.dir, node: process.execPath } } : {}),
+            });
+    if (this.tools.mode !== 'tools-user') return inner(script);
+    const marker = 'umask 0002\nprintf \'salaam-tool-pgid:%s\\n\' "$$"\n';
+    return sandboxed
+      ? toolArgv(this.tools, [
+          '/usr/bin/setsid',
+          '-w',
+          '/bin/sh',
+          '-c',
+          marker + 'exec "$@"',
+          'sh',
+          ...inner(script),
+        ])
+      : toolArgv(this.tools, ['/usr/bin/setsid', '-w', '/bin/sh', '-c', marker + script]);
+  }
   private command(c: LocalCall, command: string, timeout: number): void {
+    const broker = this.brokerNetwork();
+    // The relay is Salaam's, outside the sandbox: it forwards to stk and counts what was reached.
+    const relayStarting = broker
+      ? BrokerRelay.start(broker.socket, this.sandbox.kind === 'seatbelt' ? 'tcp' : 'unix')
+      : Promise.resolve(null);
+    // A stop that arrives while the relay starts still cancels the command once it is spawned.
+    let early = false;
+    let stop = () => {
+      early = true;
+    };
+    // Seatbelt has no tmpfs: each command gets its own private tmp, removed when it ends.
+    const tmp =
+      this.sandbox.kind === 'seatbelt' && this.sandbox.level !== 'full-access'
+        ? realpathSync(mkdtempSync(join(tmpdir(), 'salaam-cmd-')))
+        : undefined;
+    const set = (s: () => void) => {
+      stop = s;
+      if (early) s();
+    };
+    const done = relayStarting.then(
+      (relay) => this.runCommand(c, command, timeout, tmp, relay, set),
+      () => this.runCommand(c, command, timeout, tmp, null, set, !!broker),
+    );
+    this.jobs.set(c.id, { stop: () => stop(), done });
+    if (tmp) void done.finally(() => rmSync(tmp, { recursive: true, force: true }));
+  }
+  private runCommand(
+    c: LocalCall,
+    command: string,
+    timeout: number,
+    tmp: string | undefined,
+    relay: BrokerRelay | null,
+    setStop: (stop: () => void) => void,
+    relayFailed = false,
+  ): Promise<void> {
     let stop = () => {};
-    const done = new Promise<void>((resolve) => {
+    return new Promise<void>((resolve) => {
       let output = '',
         bytes = 0,
         reason: string | null = null,
         finished = false;
       // Deliberately do not inherit the daemon's provider credentials or service tokens.
       // Hold the shell before any user instruction until its identity is durably owned.
+      const tools = this.tools.mode === 'tools-user';
       const script = 'IFS= read -r salaam_start_gate || exit 125\nexec 0</dev/null\n' + command;
-      const child = spawn('/bin/sh', ['-c', script], {
+      // As the tools user, setsid makes the shell its own group leader so it can be killed by group.
+      const argv = this.commandArgv(c.root, script, tmp, relay);
+      let toolGroup: number | null = null,
+        marker = tools ? '' : null,
+        spawned = false;
+      // Release the gate only once the process is owned and, as the tools user, its group is
+      // known: otherwise a kill before the marker could miss a command already running.
+      const release = () => {
+        if (spawned && (!tools || toolGroup) && !reason && !finished) child.stdin.end('start\n');
+      };
+      const child = spawn(argv[0]!, argv.slice(1), {
         cwd: c.root,
         detached: true,
         env: {
@@ -334,11 +525,14 @@ export class LocalCoding {
           HOME: process.env.HOME ?? c.root,
           LANG: 'en_US.UTF-8',
           TMPDIR: '/tmp',
+          ...(relay ? proxyEnv(relay.port ?? COMMAND_NETWORK_PORT) : {}),
         },
         stdio: ['pipe', 'pipe', 'pipe'],
       });
       let reap: NodeJS.Timeout | undefined;
       const kill = () => {
+        if (toolGroup) killToolGroup(this.tools, toolGroup);
+        if (tools) child.stdin.destroy();
         if (child.pid)
           try {
             process.kill(-child.pid, 'SIGKILL');
@@ -347,17 +541,24 @@ export class LocalCoding {
           }
         if (!finished && !reap)
           reap = setTimeout(() => {
-            reason = 'outcome_unknown';
-            child.stdout.destroy();
-            child.stderr.destroy();
-            child.unref();
-            finish(null);
+            if (toolGroup) killToolGroup(this.tools, toolGroup);
+            // A busy event loop runs timers before pending I/O: let an already delivered close
+            // settle the outcome before declaring it unknown.
+            setImmediate(() => {
+              if (finished) return;
+              reason = 'outcome_unknown';
+              child.stdout.destroy();
+              child.stderr.destroy();
+              child.unref();
+              finish(null);
+            });
           }, 1500);
       };
       stop = () => {
         reason ??= 'cancelled';
         kill();
       };
+      setStop(stop);
       const deadline = setTimeout(() => {
         reason = 'timed_out';
         kill();
@@ -382,7 +583,35 @@ export class LocalCoding {
         reason ??= 'outcome_unknown';
         kill();
       });
-      child.stdout.on('data', collect);
+      child.stdout.on('data', (chunk: Buffer) => {
+        if (marker === null) return collect(chunk);
+        marker += chunk.toString('latin1');
+        const end = marker.indexOf('\n');
+        if (end < 0) {
+          if (marker.length > 64) {
+            reason = 'outcome_unknown';
+            kill();
+          }
+          return;
+        }
+        const found = /^salaam-tool-pgid:(\d+)$/.exec(marker.slice(0, end));
+        const rest = Buffer.from(marker.slice(end + 1), 'latin1');
+        marker = null;
+        if (!found) {
+          reason = 'outcome_unknown';
+          kill();
+          return;
+        }
+        toolGroup = Number(found[1]);
+        try {
+          this.store.transaction(() => this.change(c, 'running', { tool_pgid: toolGroup }));
+        } catch {
+          reason = 'outcome_unknown';
+          kill();
+        }
+        if (rest.length) collect(rest);
+        release();
+      });
       child.stderr.on('data', collect);
       child.once('spawn', () => {
         try {
@@ -399,7 +628,8 @@ export class LocalCoding {
             stop();
             return;
           }
-          child.stdin.end('start\n');
+          spawned = true;
+          release();
         } catch {
           reason = 'outcome_unknown';
           kill();
@@ -414,12 +644,35 @@ export class LocalCoding {
         kill();
         this.jobs.delete(c.id);
         const state = reason ?? (error ? 'failed' : code === 0 ? 'succeeded' : 'failed');
+        const network = relay
+          ? relay.summary()
+          : relayFailed
+            ? { broker: 'unavailable' as const, connections: [] }
+            : null;
+        void relay?.close();
+        // What the broker refused, in its own words, so the reason reaches the card.
+        const refusals = (network?.connections ?? [])
+          .filter((n) => n.refused && n.reason)
+          .map((n) => `[network] refused ${n.target}: ${n.reason}`)
+          .join('\n');
         const result = {
           exit_code: code,
-          output,
+          output: refusals
+            ? output + (output.endsWith('\n') || !output ? '' : '\n') + refusals + '\n'
+            : output,
           state,
           error: error ? 'Command could not start' : null,
-          isolation: 'local-user-no-os-sandbox',
+          isolation:
+            (tools ? 'tools-user-' : 'local-user-') +
+            (this.sandbox.kind !== 'none' && this.sandbox.level !== 'full-access'
+              ? this.sandbox.kind + '-' + this.sandbox.level
+              : 'no-os-sandbox'),
+          sandbox:
+            this.sandbox.kind !== 'none' && this.sandbox.level !== 'full-access'
+              ? this.sandbox.kind
+              : 'none',
+          tool_uid: this.tools.uid,
+          ...(network ? { network } : {}),
         };
         this.store.transaction(() => {
           this.change(c, state, result);
@@ -437,7 +690,6 @@ export class LocalCoding {
       child.once('error', (e) => finish(null, e));
       child.once('close', (code) => finish(code));
     });
-    this.jobs.set(c.id, { stop: () => stop(), done });
   }
   async close(): Promise<void> {
     this.closed = true;

package/src/local-edit-helper.ts

@@ -0,0 +1,26 @@
+// Runs as the tools user: applies reviewed local edits that the service has recorded and verified.
+import { closeSync, constants, fsyncSync, openSync, readFileSync, rmSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { applyLocalEdits, localPath, verifyLocalEdits } from './local-edits.js';
+import type { ToolEdit } from './tool-identity.js';
+
+const root = process.argv[2];
+if (!root) throw new Error('usage: local-edit-helper <root>');
+const edits = JSON.parse(readFileSync(0, 'utf8')) as ToolEdit[];
+for (const { remove, ...edit } of edits) {
+  if (remove) {
+    verifyLocalEdits(root, [edit]);
+    const path = localPath(root, edit.path);
+    rmSync(path);
+    const directory = openSync(dirname(path), constants.O_RDONLY);
+    try {
+      fsyncSync(directory);
+    } finally {
+      closeSync(directory);
+    }
+    process.stdout.write('applied ' + JSON.stringify(edit.path) + '\n');
+  } else
+    applyLocalEdits(root, [edit], (path) =>
+      process.stdout.write('applied ' + JSON.stringify(path) + '\n'),
+    );
+}

package/src/local-undo.ts

@@ -3,6 +3,7 @@ import { rmSync, openSync, closeSync, fsyncSync, constants } from 'node:fs';
 import { assertPermissionBinding } from './autonomy.js';
 import type { Store } from './store.js';
 import { digest, ServiceError, type Controller } from './protocol.js';
+import { applyEditsAsTools, type ToolIdentity } from './tool-identity.js';
 import { applyLocalEdits, localPath, verifyLocalEdits, type LocalEdit } from './local-edits.js';
 
 export interface UndoReview {
@@ -53,6 +54,7 @@ export function applyUndo(
   reviewed: string,
   controller: Controller,
   idle: () => void,
+  tools?: ToolIdentity,
 ) {
   const input = { kind: 'local-undo', id, reviewed };
   const saved = store.cachedRequest<{ state: string }>('local-operator', request, input);
@@ -79,20 +81,33 @@ export function applyUndo(
     return { state: 'outcome_unknown', ...review };
   });
   // Intent is durable before touching files. A lost process never repeats this mutation.
-  for (const edit of work.edits) {
-    const inverse = { ...edit, before: edit.after, after: edit.before ?? '' };
-    if (edit.before === null) {
-      verifyLocalEdits(root, [inverse]);
-      const path = localPath(root, edit.path);
-      rmSync(path);
-      const directory = openSync(dirname(path), constants.O_RDONLY);
-      try {
-        fsyncSync(directory);
-      } finally {
-        closeSync(directory);
-      }
-    } else applyLocalEdits(root, [inverse], () => {});
-  }
+  if (tools?.mode === 'tools-user')
+    applyEditsAsTools(
+      tools,
+      root,
+      work.edits.map((edit: LocalEdit) => ({
+        ...edit,
+        before: edit.after,
+        after: edit.before ?? '',
+        ...(edit.before === null ? { remove: true } : {}),
+      })),
+      () => {},
+    );
+  else
+    for (const edit of work.edits) {
+      const inverse = { ...edit, before: edit.after, after: edit.before ?? '' };
+      if (edit.before === null) {
+        verifyLocalEdits(root, [inverse]);
+        const path = localPath(root, edit.path);
+        rmSync(path);
+        const directory = openSync(dirname(path), constants.O_RDONLY);
+        try {
+          fsyncSync(directory);
+        } finally {
+          closeSync(directory);
+        }
+      } else applyLocalEdits(root, [inverse], () => {});
+    }
   verifyLocalEdits(root, work.edits);
   return store.transaction(() => {
     const result = { state: 'completed', call_id: work.call_id };

package/src/managed.ts

@@ -503,7 +503,7 @@ export class ManagedWork {
     revision: number,
     binding: string,
     decision: 'approve' | 'deny',
-    scoped?: { receipt: Record<string, unknown>; authorize: () => void },
+    scoped?: { receipt: Record<string, unknown>; authorize: () => void; decidedBy?: string },
   ): Approval {
     const requestWork = this.store.db.isTransaction
       ? this.store.requestInTransaction.bind(this.store)
@@ -553,7 +553,7 @@ export class ManagedWork {
           .prepare(
             "UPDATE approvals SET state='decided',decision=?,decided_by=?,revision=revision+1 WHERE id=?",
           )
-          .run(decision, scoped ? 'scoped-policy' : 'local-operator', id);
+          .run(decision, scoped ? (scoped.decidedBy ?? 'scoped-policy') : 'local-operator', id);
         if (decision === 'deny')
           this.transition(op, 'cancelled_before_dispatch', 'Denied by operator');
         this.store.event(

package/src/operator-mcp-cli.ts

@@ -0,0 +1,108 @@
+import {
+  declarationDigest,
+  operatorMcpPath,
+  readOperatorMcpFile,
+  validateDeclaration,
+  writeOperatorMcpFile,
+  type McpDeclaration,
+} from './operator-mcp.js';
+
+export const MCP_HELP = `salaam mcp: operator-declared MCP servers
+
+  salaam mcp add <name> [--env K='\${VAR}']... -- <command> [args...]
+  salaam mcp add <name> --url <https-url> [--header K='Bearer \${VAR}']...
+  salaam mcp list
+  salaam mcp rm <name>
+
+Options: --config <path> (default $XDG_CONFIG_HOME/salaam/mcp.json)
+Values in --env and --header must reference environment variables as \${VAR};
+inline secrets are refused. Changes apply at the next salaam service start.`;
+
+function pairs(values: string[], flag: string): Record<string, string> | undefined {
+  if (!values.length) return undefined;
+  const out: Record<string, string> = {};
+  for (const value of values) {
+    const i = value.indexOf('=');
+    if (i < 1) throw new Error(`${flag} expects K=V`);
+    const key = value.slice(0, i);
+    if (Object.hasOwn(out, key)) throw new Error(`${flag} ${key} given twice`);
+    out[key] = value.slice(i + 1);
+  }
+  return out;
+}
+
+/** `salaam mcp ...`; argv excludes the leading "mcp". Returns text for stdout. */
+export function mcpCli(argv: string[], env: NodeJS.ProcessEnv = process.env): string {
+  const dash = argv.indexOf('--');
+  const head = dash < 0 ? [...argv] : argv.slice(0, dash);
+  const command = dash < 0 ? [] : argv.slice(dash + 1);
+  const take = (flag: string, many = false): string[] => {
+    const found: string[] = [];
+    for (let i = head.indexOf(flag); i >= 0; i = head.indexOf(flag)) {
+      const value = head[i + 1];
+      if (value === undefined) throw new Error(`Missing value for ${flag}`);
+      found.push(value);
+      head.splice(i, 2);
+      if (!many) break;
+    }
+    return found;
+  };
+  const path = take('--config')[0] ?? operatorMcpPath(env);
+  const url = take('--url')[0];
+  const headers = pairs(take('--header', true), '--header');
+  const envs = pairs(take('--env', true), '--env');
+  const [verb, name, ...rest] = head;
+  if (rest.length || head.some((x) => x.startsWith('--')))
+    throw new Error('Unexpected arguments; run salaam mcp --help');
+  const file = readOperatorMcpFile(path);
+  if (verb === 'list') {
+    if (dash >= 0 || name) throw new Error('salaam mcp list takes no arguments');
+    return JSON.stringify(
+      {
+        config: path,
+        servers: file.servers.map((s) => ({ ...s, declaration_digest: declarationDigest(s) })),
+      },
+      null,
+      2,
+    );
+  }
+  if (!name) throw new Error('A server name is required');
+  if (verb === 'rm') {
+    if (dash >= 0 || url || headers || envs) throw new Error('salaam mcp rm takes only a name');
+    const servers = file.servers.filter((s) => s.name !== name);
+    if (servers.length === file.servers.length) throw new Error(`No declared server "${name}"`);
+    writeOperatorMcpFile(path, { version: 1, servers });
+    return JSON.stringify({ removed: name, config: path });
+  }
+  if (verb === 'add') {
+    if (file.servers.some((s) => s.name === name))
+      throw new Error(`Server "${name}" is already declared; rm it first`);
+    let declaration: McpDeclaration;
+    if (url) {
+      if (command.length || envs) throw new Error('Use either --url or -- <command>, not both');
+      declaration = validateDeclaration({
+        name,
+        transport: 'http',
+        url,
+        ...(headers ? { headers } : {}),
+      });
+    } else {
+      if (!command.length) throw new Error('Supply -- <command> [args...] or --url <url>');
+      if (headers) throw new Error('--header applies to --url servers');
+      declaration = validateDeclaration({
+        name,
+        transport: 'stdio',
+        command: command[0],
+        args: command.slice(1),
+        ...(envs ? { env: envs } : {}),
+      });
+    }
+    writeOperatorMcpFile(path, { version: 1, servers: [...file.servers, declaration] });
+    return JSON.stringify({
+      added: name,
+      config: path,
+      declaration_digest: declarationDigest(declaration),
+    });
+  }
+  throw new Error('Use salaam mcp add, list or rm');
+}