@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/dist/src/local-edit-helper.js

@@ -0,0 +1,25 @@
+// 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';
+const root = process.argv[2];
+if (!root)
+    throw new Error('usage: local-edit-helper <root>');
+const edits = JSON.parse(readFileSync(0, 'utf8'));
+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/dist/src/local-edits.js

@@ -78,16 +78,178 @@ export function prepareLocalEdits(root, input) {
         const expected = item.sha256;
         if (expected !== (original.text === null ? null : localHash(original.text)))
             throw new ServiceError('workspace_changed', 'Read the file first and supply its current sha256; null is only for a new file');
-        if (typeof item.content !== 'string' ||
-            Buffer.byteLength(item.content) > 262144 ||
-            item.content.includes('\0'))
-            throw new ServiceError('invalid_field', 'Provide UTF-8 replacement content up to 256 KiB');
-        return { path, before: original.text, after: item.content, mode: original.mode };
+        // An existing file changes by exact replacements; whole content is for new files (or a
+        // deliberate rewrite). Either way the edit resolves to the exact before and after texts, so
+        // the approval binding, apply, verify and undo paths are unchanged.
+        let after;
+        if (item.replacements !== undefined) {
+            if (item.content !== undefined)
+                throw new ServiceError('invalid_field', 'Use replacements or content for a file, not both');
+            if (original.text === null)
+                throw new ServiceError('invalid_field', 'Replacements edit an existing file; give a new file its whole content');
+            after = applyReplacements(path, original.text, item.replacements);
+        }
+        else
+            after = item.content;
+        if (typeof after !== 'string' || Buffer.byteLength(after) > 262144 || after.includes('\0'))
+            throw new ServiceError('invalid_field', 'Provide UTF-8 file content up to 256 KiB');
+        return { path, before: original.text, after, mode: original.mode };
     });
-    if (Buffer.byteLength(JSON.stringify(edits)) > 32768)
+    // What a person reviews is the change, so the change is what is bounded, not the files.
+    if (Buffer.byteLength(reviewLocalEdits(edits, Infinity)) > 32768)
         throw new ServiceError('workspace_limit', 'Split this edit into smaller reviewable changes (32 KiB per review)');
     return edits;
 }
+/** Applies exact replacements in order. Each `old` must occur exactly once in the text as it is
+ * at that point; the message tells the model how to fix a miss. */
+function applyReplacements(path, text, input) {
+    if (!Array.isArray(input) || !input.length || input.length > 20)
+        throw new ServiceError('invalid_field', 'Provide one to twenty replacements');
+    input.forEach((raw, i) => {
+        const r = object(raw), n = `Replacement ${i + 1} in ${path}`;
+        if (typeof r.old !== 'string' || typeof r.new !== 'string')
+            throw new ServiceError('invalid_field', `${n}: give old and new as text`);
+        if (!r.old)
+            throw new ServiceError('invalid_field', `${n}: old is empty; quote the exact lines to change`);
+        let count = 0;
+        for (let at = text.indexOf(r.old); at !== -1; at = text.indexOf(r.old, at + r.old.length))
+            count++;
+        if (count === 0)
+            throw new ServiceError('edit_mismatch', `${n}: old text not found. Read the file again and copy the exact lines, including whitespace`);
+        if (count > 1)
+            throw new ServiceError('edit_mismatch', `${n}: old text occurs ${count} times. Include more surrounding lines so it matches exactly once`);
+        if (r.old === r.new)
+            throw new ServiceError('invalid_field', `${n}: changes nothing`);
+        text = text.replace(r.old, () => r.new);
+    });
+    return text;
+}
+const CONTEXT = 3, REVIEW_LINES = 200;
+/** A unified diff of each file's change with a few lines of context: what an approval shows.
+ * Long reviews stop at `limit` lines and say how much they left out; the approval still binds
+ * the exact full change. */
+export function reviewLocalEdits(edits, limit = REVIEW_LINES) {
+    const out = [];
+    let hidden = 0;
+    for (const edit of edits) {
+        const lines = edit.before === null
+            ? [`+++ ${edit.path} (new file)`, ...split(edit.after).map((l) => '+' + l)]
+            : [`--- ${edit.path}`, `+++ ${edit.path}`, ...hunks(split(edit.before), split(edit.after))];
+        for (const line of lines) {
+            if (out.length < limit)
+                out.push(line);
+            else if (/^[+-]/.test(line) && !/^(\+\+\+|---) /.test(line))
+                hidden++;
+        }
+    }
+    if (hidden)
+        out.push(`… ${hidden} more changed lines not shown; the approval covers the exact full change`);
+    return out.join('\n');
+}
+function split(text) {
+    const lines = text.split('\n');
+    if (lines.at(-1) === '')
+        lines.pop();
+    return lines;
+}
+/** Unified-diff hunks from a line-level Myers diff (prefix and suffix trimmed first, so a small
+ * change to a big file stays cheap). A diff too large to compute in budget is shown whole. */
+function hunks(a, b) {
+    let pre = 0;
+    while (pre < a.length && pre < b.length && a[pre] === b[pre])
+        pre++;
+    let suf = 0;
+    while (suf < a.length - pre &&
+        suf < b.length - pre &&
+        a[a.length - 1 - suf] === b[b.length - 1 - suf])
+        suf++;
+    const ops = myers(a.slice(pre, a.length - suf), b.slice(pre, b.length - suf));
+    // Full op list over the whole file: equal prefix, the diffed middle, equal suffix.
+    const all = [];
+    for (let i = 0; i < pre; i++)
+        all.push({ t: ' ', s: a[i], ai: i, bi: i });
+    let ai = pre, bi = pre;
+    for (const o of ops) {
+        all.push({ ...o, ai, bi });
+        if (o.t !== '+')
+            ai++;
+        if (o.t !== '-')
+            bi++;
+    }
+    for (let i = 0; i < suf; i++)
+        all.push({ t: ' ', s: a[ai + i], ai: ai + i, bi: bi + i });
+    const out = [];
+    let i = 0;
+    while (i < all.length) {
+        if (all[i].t === ' ') {
+            i++;
+            continue;
+        }
+        let start = Math.max(0, i - CONTEXT), end = i;
+        // Extend while the next change is within 2*CONTEXT equal lines.
+        for (;;) {
+            while (end < all.length && all[end].t !== ' ')
+                end++;
+            let gap = end;
+            while (gap < all.length && all[gap].t === ' ' && gap - end < 2 * CONTEXT)
+                gap++;
+            if (gap < all.length && all[gap].t !== ' ' && gap - end < 2 * CONTEXT)
+                end = gap;
+            else
+                break;
+        }
+        const stop = Math.min(all.length, end + CONTEXT), part = all.slice(start, stop), aStart = part.find((o) => o.t !== '+')?.ai ?? part[0].ai, bStart = part.find((o) => o.t !== '-')?.bi ?? part[0].bi, aLen = part.filter((o) => o.t !== '+').length, bLen = part.filter((o) => o.t !== '-').length;
+        out.push(`@@ -${aStart + 1},${aLen} +${bStart + 1},${bLen} @@`, ...part.map((o) => o.t + o.s));
+        i = stop;
+    }
+    return out;
+}
+function myers(a, b) {
+    const n = a.length, m = b.length, max = n + m;
+    if (max > 20000)
+        return [...a.map((s) => ({ t: '-', s })), ...b.map((s) => ({ t: '+', s }))];
+    const v = new Map([[1, 0]]), trace = [];
+    for (let d = 0; d <= max; d++) {
+        trace.push(new Map(v));
+        for (let k = -d; k <= d; k += 2) {
+            let x = k === -d || (k !== d && (v.get(k - 1) ?? -1) < (v.get(k + 1) ?? -1))
+                ? v.get(k + 1)
+                : v.get(k - 1) + 1;
+            let y = x - k;
+            while (x < n && y < m && a[x] === b[y]) {
+                x++;
+                y++;
+            }
+            v.set(k, x);
+            if (x >= n && y >= m)
+                return backtrack(a, b, trace, n, m);
+        }
+        if (d > 2000)
+            break;
+    }
+    return [...a.map((s) => ({ t: '-', s })), ...b.map((s) => ({ t: '+', s }))];
+}
+function backtrack(a, b, trace, n, m) {
+    const ops = [];
+    let x = n, y = m;
+    for (let d = trace.length - 1; d >= 0; d--) {
+        const v = trace[d], k = x - y, prevK = k === -d || (k !== d && (v.get(k - 1) ?? -1) < (v.get(k + 1) ?? -1)) ? k + 1 : k - 1, prevX = v.get(prevK) ?? 0, prevY = prevX - prevK;
+        while (x > prevX && y > prevY) {
+            ops.push({ t: ' ', s: a[x - 1] });
+            x--;
+            y--;
+        }
+        if (d > 0) {
+            if (x === prevX)
+                ops.push({ t: '+', s: b[y - 1] });
+            else
+                ops.push({ t: '-', s: a[x - 1] });
+        }
+        x = prevX;
+        y = prevY;
+    }
+    return ops.reverse();
+}
 export function verifyLocalEdits(root, edits) {
     for (const edit of edits) {
         const actual = contents(localPath(root, edit.path));

package/dist/src/local-undo.js

@@ -2,6 +2,7 @@ import { dirname } from 'node:path';
 import { rmSync, openSync, closeSync, fsyncSync, constants } from 'node:fs';
 import { assertPermissionBinding } from './autonomy.js';
 import { digest, ServiceError } from './protocol.js';
+import { applyEditsAsTools } from './tool-identity.js';
 import { applyLocalEdits, localPath, verifyLocalEdits } from './local-edits.js';
 /** Unfinished inverse edits fence every local session sharing the root, including after a crash. */
 export function assertUndoSettled(store, root) {
@@ -24,7 +25,7 @@ export function reviewUndo(store, id) {
     verifyLocalEdits(session.cwd, edits.map((e) => ({ ...e, before: e.after })));
     return { call_id: row.id, digest: digest({ root: session.cwd, call: row.id, edits }), edits };
 }
-export function applyUndo(store, id, request, reviewed, controller, idle) {
+export function applyUndo(store, id, request, reviewed, controller, idle, tools) {
     const input = { kind: 'local-undo', id, reviewed };
     const saved = store.cachedRequest('local-operator', request, input);
     if (saved)
@@ -47,23 +48,31 @@ export function applyUndo(store, id, request, reviewed, controller, idle) {
         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);
+    if (tools?.mode === 'tools-user')
+        applyEditsAsTools(tools, root, work.edits.map((edit) => ({
+            ...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], () => { });
         }
-        else
-            applyLocalEdits(root, [inverse], () => { });
-    }
     verifyLocalEdits(root, work.edits);
     return store.transaction(() => {
         const result = { state: 'completed', call_id: work.call_id };

package/dist/src/managed.js

@@ -383,7 +383,7 @@ export class ManagedWork {
             this.fresh(op);
             this.store.db
                 .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(approval.session_id, 'approval.decided', { approval_id: id, operation_id: op.id, decision }, request);

package/dist/src/mentions.js

@@ -0,0 +1,277 @@
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, isAbsolute, relative, resolve, sep } from 'node:path';
+import { ServiceError } from './protocol.js';
+/** `@path` mentions attach workspace files to a desk prompt (Phase 3b). */
+export const MENTION_LIMITS = {
+    perFile: 64 * 1024,
+    total: 256 * 1024,
+    image: 512 * 1024,
+    listing: 5000,
+    entries: 200,
+};
+const SENSITIVE = [
+    /(^|\/)\.env(\..+)?$/,
+    /\.(pem|key|p12|pfx|keystore|jks)$/i,
+    /(^|\/)id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/,
+    /(^|\/)\.(netrc|npmrc|pypirc)$/,
+    /(^|\/)(credentials|secrets?)(\.[a-z]+)?$/i,
+];
+export function isSensitivePath(path) {
+    return SENSITIVE.some((pattern) => pattern.test(path));
+}
+/** `@token` at a word start; `@"a b"` may hold spaces; trailing punctuation is dropped. */
+export function extractMentions(text) {
+    const found = [];
+    const pattern = /(^|[\s([{])@(?:"([^"]+)"|([^\s"]+))/g;
+    for (const match of text.matchAll(pattern)) {
+        const value = match[2] ?? match[3].replace(/[.,;:!?)\]}]+$/, '');
+        if (value && !value.startsWith('@') && !found.includes(value))
+            found.push(value);
+    }
+    return found;
+}
+function inside(root, path) {
+    const rel = relative(root, path);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+/** Tracked and untracked-but-not-ignored files; a symlink is listed only if it stays inside. */
+export function listWorkspaceFiles(root) {
+    let names;
+    try {
+        names = execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z'], {
+            cwd: root,
+            maxBuffer: 32 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .toString('utf8')
+            .split('\0')
+            .filter(Boolean);
+    }
+    catch {
+        names = walk(root, root);
+    }
+    const real = realpathSync(root);
+    const kept = [];
+    for (const name of names) {
+        if (kept.length >= MENTION_LIMITS.listing)
+            break;
+        try {
+            if (lstatSync(resolve(root, name)).isSymbolicLink() &&
+                !inside(real, realpathSync(resolve(root, name))))
+                continue;
+        }
+        catch {
+            continue;
+        }
+        kept.push(name);
+    }
+    return kept;
+}
+function walk(root, dir, out = []) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (out.length >= MENTION_LIMITS.listing)
+            break;
+        if (entry.name === '.git' || entry.name === 'node_modules')
+            continue;
+        const full = resolve(dir, entry.name);
+        if (entry.isDirectory())
+            walk(root, full, out);
+        else
+            out.push(relative(root, full).split(sep).join('/'));
+    }
+    return out;
+}
+/** Basename hits first, then path substrings, then in-order subsequences. */
+export function rankFiles(files, query) {
+    if (!query)
+        return files;
+    const q = query.toLowerCase();
+    const score = (file) => {
+        const f = file.toLowerCase();
+        const base = basename(f);
+        if (base.startsWith(q))
+            return 4;
+        if (base.includes(q))
+            return 3;
+        if (f.includes(q))
+            return 2;
+        let i = 0;
+        for (const ch of f)
+            if (ch === q[i])
+                i++;
+        return i === q.length ? 1 : 0;
+    };
+    return files
+        .map((file) => ({ file, s: score(file) }))
+        .filter((x) => x.s > 0)
+        .sort((a, b) => b.s - a.s || a.file.length - b.file.length || a.file.localeCompare(b.file))
+        .map((x) => x.file);
+}
+function imageMime(bytes) {
+    if (bytes.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex')))
+        return 'image/png';
+    if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return 'image/jpeg';
+    if (bytes.subarray(0, 4).toString('latin1') === 'GIF8')
+        return 'image/gif';
+    if (bytes.subarray(0, 4).toString('latin1') === 'RIFF' &&
+        bytes.subarray(8, 12).toString('latin1') === 'WEBP')
+        return 'image/webp';
+    return undefined;
+}
+function truncate(text, limit) {
+    const buf = Buffer.from(text, 'utf8');
+    if (buf.length <= limit)
+        return text;
+    // Cut on a character boundary so the byte bound holds.
+    return buf.subarray(0, limit).toString('utf8').replace(/�$/, '');
+}
+/** Read each mention under the workspace; nothing outside it, through a symlink or not. */
+export function resolveMentions(root, mentions) {
+    const real = realpathSync(root);
+    let budget = MENTION_LIMITS.total;
+    return mentions.map((path) => {
+        const target = resolve(real, path);
+        if (isAbsolute(path) || !inside(real, target))
+            return { path, kind: 'refused', reason: 'outside the workspace' };
+        let resolved;
+        try {
+            resolved = realpathSync(target);
+        }
+        catch {
+            return { path, kind: 'missing' };
+        }
+        if (!inside(real, resolved))
+            return { path, kind: 'refused', reason: 'links outside the workspace' };
+        const sensitive = isSensitivePath(path) || undefined;
+        const stat = lstatSync(resolved);
+        if (stat.isDirectory()) {
+            const names = readdirSync(resolved, { withFileTypes: true })
+                .filter((e) => e.name !== '.git')
+                .slice(0, MENTION_LIMITS.entries)
+                .map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
+            const content = truncate(names.join('\n'), Math.min(MENTION_LIMITS.perFile, budget));
+            budget -= Buffer.byteLength(content);
+            return { path, kind: 'listing', content };
+        }
+        if (!stat.isFile())
+            return { path, kind: 'refused', reason: 'not a regular file' };
+        const bytes = readFileSync(resolved);
+        const sha256 = createHash('sha256').update(bytes).digest('hex');
+        const mime = imageMime(bytes);
+        if (mime) {
+            if (bytes.length > MENTION_LIMITS.image)
+                return {
+                    path,
+                    kind: 'skipped',
+                    reason: 'image larger than 512 KiB',
+                    bytes: bytes.length,
+                    sha256,
+                };
+            return {
+                path,
+                kind: 'image',
+                mime,
+                data: bytes.toString('base64'),
+                sha256,
+                bytes: bytes.length,
+                sensitive,
+            };
+        }
+        if (bytes.subarray(0, 8192).includes(0))
+            return { path, kind: 'binary', sha256, bytes: bytes.length, sensitive };
+        if (budget <= 0)
+            return {
+                path,
+                kind: 'skipped',
+                reason: 'attachment budget used up',
+                sha256,
+                bytes: bytes.length,
+                sensitive,
+            };
+        const limit = Math.min(MENTION_LIMITS.perFile, budget);
+        const content = truncate(bytes.toString('utf8'), limit);
+        budget -= Buffer.byteLength(content);
+        return {
+            path,
+            kind: 'text',
+            content,
+            sha256,
+            bytes: bytes.length,
+            ...(Buffer.byteLength(content) < bytes.length ? { truncated: true } : {}),
+            ...(sensitive ? { sensitive } : {}),
+        };
+    });
+}
+/** The text the model reads; image bytes travel separately as image content. */
+export function attachmentContext(attachments) {
+    if (!attachments.length)
+        return '';
+    const parts = attachments.map((a) => {
+        const digest = a.sha256 ? `, sha256 ${a.sha256.slice(0, 12)}` : '';
+        switch (a.kind) {
+            case 'text':
+                return `@${a.path} (${a.bytes} bytes${digest}${a.truncated ? ', truncated' : ''})\n\`\`\`\n${a.content}\n\`\`\``;
+            case 'listing':
+                return `@${a.path} (directory)\n\`\`\`\n${a.content}\n\`\`\``;
+            case 'image':
+                return `@${a.path} (image, attached)${digest ? ` [${digest.slice(2)}]` : ''}`;
+            case 'binary':
+                return `@${a.path} (binary, ${a.bytes} bytes${digest}; not attached)`;
+            default:
+                return `@${a.path} (${a.kind}${a.reason ? `: ${a.reason}` : ''})`;
+        }
+    });
+    return `<attached-files>\n${parts.join('\n\n')}\n</attached-files>`;
+}
+export const MAX_IMAGES = 4;
+/**
+ * Expand a desk prompt's mentions. A secret-looking file is attached only after the user
+ * confirms it; the refusal names the files so the client can ask.
+ */
+export function expandPrompt(root, text, confirmSensitive) {
+    const mentions = extractMentions(text);
+    if (!mentions.length)
+        return { text, images: [], attachments: [] };
+    const attachments = resolveMentions(root, mentions);
+    const sensitive = attachments
+        .filter((a) => a.sensitive && a.kind !== 'binary')
+        .map((a) => a.path);
+    if (sensitive.length && !confirmSensitive)
+        throw new ServiceError('sensitive_attachment', `Confirm attaching secret-looking files: ${sensitive.join(', ')}`, 409);
+    const images = [];
+    for (const a of attachments) {
+        if (a.kind !== 'image')
+            continue;
+        if (images.length >= MAX_IMAGES) {
+            a.kind = 'skipped';
+            a.reason = `more than ${MAX_IMAGES} images`;
+            delete a.data;
+            continue;
+        }
+        images.push({ type: 'image', data: a.data, mimeType: a.mime });
+    }
+    return { text: `${text}\n\n${attachmentContext(attachments)}`, images, attachments };
+}
+function imageTable(db) {
+    db.exec('CREATE TABLE IF NOT EXISTS submission_images(submission_id TEXT NOT NULL,position INTEGER NOT NULL,mime TEXT NOT NULL,data TEXT NOT NULL,PRIMARY KEY(submission_id,position))');
+}
+export function storeImages(db, submissionId, images) {
+    if (!images.length)
+        return;
+    imageTable(db);
+    const insert = db.prepare('INSERT INTO submission_images VALUES (?,?,?,?)');
+    images.forEach((image, i) => insert.run(submissionId, i, image.mimeType, image.data));
+}
+/** Images ride with their submission once; they are dropped after dispatch. */
+export function takeImages(db, submissionId) {
+    imageTable(db);
+    const rows = db
+        .prepare('SELECT mime,data FROM submission_images WHERE submission_id=? ORDER BY position')
+        .all(submissionId);
+    if (rows.length)
+        db.prepare('DELETE FROM submission_images WHERE submission_id=?').run(submissionId);
+    return rows.map((r) => ({ type: 'image', data: r.data, mimeType: r.mime }));
+}

package/dist/src/operator-mcp-cli.js

@@ -0,0 +1,107 @@
+import { declarationDigest, operatorMcpPath, readOperatorMcpFile, validateDeclaration, writeOperatorMcpFile, } 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, flag) {
+    if (!values.length)
+        return undefined;
+    const out = {};
+    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, env = process.env) {
+    const dash = argv.indexOf('--');
+    const head = dash < 0 ? [...argv] : argv.slice(0, dash);
+    const command = dash < 0 ? [] : argv.slice(dash + 1);
+    const take = (flag, many = false) => {
+        const found = [];
+        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;
+        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');
+}