@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/dist/src/operator-mcp.js

@@ -0,0 +1,342 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, isAbsolute, join } from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { digest, ServiceError } from './protocol.js';
+const NAME = /^[a-z][a-z0-9_-]{0,63}$/;
+const REF = /\$\{([A-Za-z_][A-Za-z0-9_]{0,127})\}/g;
+// Literal text around references may only be a short scheme word such as "Bearer ".
+const LITERAL = /^(?:[A-Za-z][A-Za-z-]{0,15} ?)?$/;
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]']);
+const HEADER = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,128}$/;
+const ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+export function operatorMcpPath(env = process.env) {
+    const base = env.XDG_CONFIG_HOME && isAbsolute(env.XDG_CONFIG_HOME)
+        ? env.XDG_CONFIG_HOME
+        : join(env.HOME || homedir(), '.config');
+    return join(base, 'salaam', 'mcp.json');
+}
+function fail(message) {
+    throw new ServiceError('invalid_mcp_config', message, 400);
+}
+function keys(value, allowed, where) {
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            fail(`${where}: unknown key "${key}"`);
+}
+function record(value, where) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail(`${where} must be an object`);
+    return value;
+}
+/** A value must be built from ${VAR} references; inline secrets are refused. */
+export function assertReference(value, where) {
+    if (typeof value !== 'string' || value.length > 1024)
+        fail(`${where} must be a string`);
+    const names = [...value.matchAll(REF)].map((m) => m[1]);
+    const literal = value.replace(REF, '');
+    if (!names.length || !LITERAL.test(literal))
+        fail(`${where} must reference an environment variable as \${VAR}; inline secrets are refused`);
+    return names;
+}
+function referenceMap(value, where, key) {
+    const map = record(value, where);
+    for (const [k, v] of Object.entries(map)) {
+        if (!key.test(k))
+            fail(`${where}: invalid name "${k}"`);
+        assertReference(v, `${where}.${k}`);
+    }
+    return map;
+}
+/** Shape validation shared by the CLI and the service. Does not touch PATH or env. */
+export function validateDeclaration(input, index = 0) {
+    const where = `servers[${index}]`;
+    const s = record(input, where);
+    if (typeof s.name !== 'string' || !NAME.test(s.name))
+        fail(`${where}.name must match ${NAME.source}`);
+    const at = `server "${s.name}"`;
+    if (s.transport === 'stdio') {
+        keys(s, ['name', 'transport', 'command', 'args', 'cwd', 'env'], at);
+        if (typeof s.command !== 'string' || !s.command || s.command.length > 4096)
+            fail(`${at}: command is required`);
+        if (!isAbsolute(s.command) && s.command.includes('/'))
+            fail(`${at}: command must be absolute or a bare name on PATH`);
+        if (s.args !== undefined &&
+            (!Array.isArray(s.args) ||
+                s.args.length > 256 ||
+                s.args.some((a) => typeof a !== 'string' || a.length > 4096)))
+            fail(`${at}: args must be a list of strings`);
+        if (s.cwd !== undefined && (typeof s.cwd !== 'string' || !isAbsolute(s.cwd)))
+            fail(`${at}: cwd must be absolute`);
+        if (s.env !== undefined)
+            referenceMap(s.env, `${at}: env`, ENV_KEY);
+        return {
+            name: s.name,
+            transport: 'stdio',
+            command: s.command,
+            ...(s.args ? { args: [...s.args] } : {}),
+            ...(s.cwd ? { cwd: s.cwd } : {}),
+            ...(s.env ? { env: { ...s.env } } : {}),
+        };
+    }
+    if (s.transport === 'http') {
+        keys(s, ['name', 'transport', 'url', 'headers'], at);
+        if (typeof s.url !== 'string' || !URL.canParse(s.url))
+            fail(`${at}: url is invalid`);
+        const url = new URL(s.url);
+        if (url.username || url.password)
+            fail(`${at}: url must not carry credentials`);
+        if (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOOPBACK.has(url.hostname)))
+            fail(`${at}: url must be https (http only on loopback)`);
+        if (s.headers !== undefined)
+            referenceMap(s.headers, `${at}: headers`, HEADER);
+        return {
+            name: s.name,
+            transport: 'http',
+            url: s.url,
+            ...(s.headers ? { headers: { ...s.headers } } : {}),
+        };
+    }
+    fail(`${at}: transport must be "stdio" or "http"`);
+}
+export function validateOperatorMcp(input) {
+    const file = record(input, 'mcp.json');
+    keys(file, ['version', 'servers'], 'mcp.json');
+    if (file.version !== 1)
+        fail('mcp.json: version must be 1');
+    if (!Array.isArray(file.servers) || file.servers.length > 64)
+        fail('mcp.json: servers must be a list of at most 64');
+    const servers = file.servers.map((s, i) => validateDeclaration(s, i));
+    const seen = new Set();
+    for (const s of servers) {
+        if (seen.has(s.name))
+            fail(`mcp.json: duplicate server name "${s.name}"`);
+        seen.add(s.name);
+    }
+    return { version: 1, servers };
+}
+export function readOperatorMcpFile(path) {
+    if (!existsSync(path))
+        return { version: 1, servers: [] };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        fail(`${path} is not valid JSON`);
+    }
+    return validateOperatorMcp(parsed);
+}
+export function writeOperatorMcpFile(path, file) {
+    const valid = validateOperatorMcp(file);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temp = `${path}.${process.pid}.tmp`;
+    writeFileSync(temp, JSON.stringify(valid, null, 2) + '\n', { mode: 0o600 });
+    renameSync(temp, path);
+}
+export const declarationDigest = (d) => digest(d);
+export function resolveCommand(command, env) {
+    const executable = (path) => {
+        try {
+            return statSync(path).isFile() && (statSync(path).mode & 0o111) !== 0;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (isAbsolute(command)) {
+        if (!executable(command))
+            fail(`command ${command} is not an executable file`);
+        return command;
+    }
+    for (const dir of (env.PATH ?? '').split(delimiter))
+        if (dir && isAbsolute(dir) && executable(join(dir, command)))
+            return join(dir, command);
+    fail(`command "${command}" is not on PATH`);
+}
+function resolveReferences(map, env, where) {
+    if (!map)
+        return undefined;
+    return Object.fromEntries(Object.entries(map).map(([k, v]) => [
+        k,
+        v.replace(REF, (_m, name) => {
+            const value = env[name];
+            if (value === undefined)
+                fail(`${where}.${k} references unset variable ${name}`);
+            return value;
+        }),
+    ]));
+}
+const CALL_TIMEOUT_MS = 120_000;
+const RESULT_LIMIT = 262_144;
+export class OperatorMcp {
+    file;
+    servers;
+    digest;
+    sessions = new Map();
+    secrets;
+    /** Resolves commands and references now, so a bad declaration refuses service start. */
+    constructor(file, env = process.env) {
+        this.file = file;
+        const valid = validateOperatorMcp(file);
+        this.servers = valid.servers.map((declaration) => {
+            const declaration_digest = declarationDigest(declaration);
+            if (declaration.transport === 'stdio') {
+                const command = resolveCommand(declaration.command, env);
+                return {
+                    declaration,
+                    command,
+                    env: resolveReferences(declaration.env, env, `server "${declaration.name}": env`),
+                    provenance: {
+                        name: declaration.name,
+                        source: 'operator',
+                        transport: 'stdio',
+                        command,
+                        args: declaration.args ?? [],
+                        declaration_digest,
+                    },
+                };
+            }
+            return {
+                declaration,
+                headers: resolveReferences(declaration.headers, env, `server "${declaration.name}": headers`),
+                provenance: {
+                    name: declaration.name,
+                    source: 'operator',
+                    transport: 'http',
+                    url: declaration.url,
+                    declaration_digest,
+                },
+            };
+        });
+        this.digest = digest(valid);
+        this.secrets = this.servers
+            .flatMap((s) => [...Object.values(s.env ?? {}), ...Object.values(s.headers ?? {})])
+            .filter((v) => v.length >= 8);
+    }
+    static load(path, env = process.env) {
+        return new OperatorMcp(readOperatorMcpFile(path), env);
+    }
+    provenance() {
+        return this.servers.map((s) => structuredClone(s.provenance));
+    }
+    get empty() {
+        return this.servers.length === 0;
+    }
+    server(name) {
+        const server = this.servers.find((s) => s.declaration.name === name);
+        if (!server)
+            throw new ServiceError('invalid_mcp_server', 'Unknown declared MCP server', 400);
+        return server;
+    }
+    connection(session, server) {
+        let owned = this.sessions.get(session);
+        if (!owned)
+            this.sessions.set(session, (owned = new Map()));
+        const existing = owned.get(server.declaration.name);
+        if (existing)
+            return existing;
+        const client = new Client({ name: 'salaam', version: '1' }, { capabilities: {} });
+        const d = server.declaration;
+        const transport = d.transport === 'stdio'
+            ? new StdioClientTransport({
+                command: server.command,
+                args: d.args ?? [],
+                ...(d.cwd ? { cwd: d.cwd } : {}),
+                ...(server.env ? { env: server.env } : {}),
+                stderr: 'ignore',
+            })
+            : new StreamableHTTPClientTransport(new URL(d.url), {
+                requestInit: { headers: server.headers ?? {}, redirect: 'error' },
+            });
+        const connection = {
+            client,
+            transport,
+            ready: client.connect(transport, { timeout: 30_000 }),
+        };
+        connection.ready.catch(() => owned.delete(d.name));
+        owned.set(d.name, connection);
+        return connection;
+    }
+    redact(text) {
+        let out = text;
+        for (const secret of this.secrets)
+            out = out.split(secret).join('[redacted]');
+        return out;
+    }
+    failure(error) {
+        if (error instanceof ServiceError)
+            throw error;
+        throw new ServiceError('mcp_server_failed', this.redact(`Declared MCP server failed: ${error?.message ?? 'unknown'}`).slice(0, 512), 502);
+    }
+    async catalog(session, serverName, tool) {
+        if (serverName === undefined || serverName === null || serverName === '')
+            return { servers: this.provenance().map(({ name, transport }) => ({ name, transport })) };
+        const server = this.server(serverName);
+        try {
+            const c = this.connection(session, server);
+            await c.ready;
+            const { tools } = await c.client.listTools(undefined, { timeout: 30_000 });
+            if (tool === undefined || tool === null || tool === '')
+                return {
+                    server: server.declaration.name,
+                    tools: tools.map((t) => ({ name: t.name, description: t.description ?? '' })),
+                };
+            const found = tools.find((t) => t.name === tool);
+            if (!found)
+                throw new ServiceError('invalid_mcp_tool', 'Unknown tool on that server', 400);
+            return { server: server.declaration.name, tool: found };
+        }
+        catch (error) {
+            this.failure(error);
+        }
+    }
+    async call(session, serverName, tool, args, signal) {
+        const server = this.server(serverName);
+        if (typeof tool !== 'string' || !tool || tool.length > 128)
+            throw new ServiceError('invalid_mcp_tool', 'A tool name is required', 400);
+        if (args !== undefined && (args === null || typeof args !== 'object' || Array.isArray(args)))
+            throw new ServiceError('invalid_mcp_arguments', 'Arguments must be an object', 400);
+        try {
+            const c = this.connection(session, server);
+            await c.ready;
+            const result = await c.client.callTool({ name: tool, arguments: (args ?? {}) }, undefined, { timeout: CALL_TIMEOUT_MS, ...(signal ? { signal } : {}) });
+            const parts = Array.isArray(result.content) ? result.content : [];
+            let budget = RESULT_LIMIT;
+            const content = parts.map((part) => {
+                const text = this.redact(part.type === 'text' ? String(part.text) : JSON.stringify(part)).slice(0, Math.max(0, budget));
+                budget -= text.length;
+                return { type: 'text', text };
+            });
+            if (result.structuredContent && !content.length)
+                content.push({
+                    type: 'text',
+                    text: this.redact(JSON.stringify(result.structuredContent)).slice(0, RESULT_LIMIT),
+                });
+            return { content, is_error: !!result.isError };
+        }
+        catch (error) {
+            this.failure(error);
+        }
+    }
+    async stopSession(session) {
+        const owned = this.sessions.get(session);
+        this.sessions.delete(session);
+        if (!owned)
+            return;
+        await Promise.allSettled([...owned.values()].map((c) => c.client.close()));
+    }
+    async close() {
+        await Promise.allSettled([...this.sessions.keys()].map((s) => this.stopSession(s)));
+    }
+}
+/** Both sources may serve one session; a shared name is refused rather than shadowed. */
+export function mergeMcpProvenance(operator, agentpod) {
+    const names = new Set(agentpod.map((s) => s.name));
+    const clash = operator.find((s) => names.has(s.name));
+    if (clash)
+        throw new ServiceError('mcp_name_collision', `Declared MCP server "${clash.name}" collides with an AgentPod-assigned server`, 409);
+    return [...operator, ...agentpod];
+}

package/dist/src/persona.js

@@ -0,0 +1,31 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { digest } from './protocol.js';
+/**
+ * Item 9: the operator's persona for this host's agent. A plain UTF-8 text file the operator
+ * reviews at `host plan`; the manifest pins its path and digest, `host start` refuses a changed
+ * file, and every worker on the host gets it as a final system-prompt section. It shapes voice and
+ * conduct only: it grants no tool, path or permission, and no workspace file can supply it.
+ */
+export const PERSONA_MAX_BYTES = 16 * 1024;
+export function loadPersona(path) {
+    if (!isAbsolute(path) || realpathSync(path) !== path)
+        throw Error('Use a canonical absolute persona path');
+    const st = statSync(path);
+    if (!st.isFile() || st.size > PERSONA_MAX_BYTES)
+        throw Error('A persona is a regular file of at most 16 KiB');
+    const raw = readFileSync(path);
+    const text = raw.toString('utf8');
+    if (Buffer.from(text, 'utf8').compare(raw) !== 0 || text.includes('\0'))
+        throw Error('A persona is UTF-8 text');
+    if (!text.trim())
+        throw Error('A persona must not be empty');
+    return { text, digest: digest({ persona: text }) };
+}
+/** The section appended to the system prompt. */
+export function personaSection(p) {
+    return ("\n\n## Persona (set by this host's operator)\n" +
+        'This shapes your voice and conduct only. It grants no tools, paths or permissions, and it never ' +
+        'overrides approvals, policy or the facts of a tool result.\n\n' +
+        p.text.trim());
+}

package/dist/src/pi-sessions.js

@@ -1,9 +1,13 @@
 import { SessionManager } from '@earendil-works/pi-coding-agent';
 /** Session files are written only by Pi's pinned session manager, never edited as JSONL. */
-export function forkPiSession(source, cwd, directory, id) {
+export function forkPiSession(source, cwd, directory, id, 
+/** Continue from this earlier entry (a rewind) instead of the latest one. */
+at) {
     const branch = SessionManager.forkFrom(source, cwd, directory, { id, parentSession: source });
     const file = branch.getSessionFile();
     if (!file || branch.getSessionId() !== id)
         throw new Error('Pi did not create the requested branch identity');
+    if (at)
+        branch.branchWithSummary(at.leaf, at.summary);
     return file;
 }

package/dist/src/pi.js

@@ -1,9 +1,30 @@
+import { redactFailureText } from './acp-outcome.js';
 import { spawn } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
 import { ServiceError, object, textDigest } from './protocol.js';
 export class PiCommandError extends Error {
 }
+/**
+ * The text a finished tool returned, for the board's activity stream. A card showed every step
+ * with `result: null` because only the status crossed over. Images are left out, known secret
+ * shapes are redacted, and the text is clipped to 2 KiB.
+ */
+function toolOutput(result) {
+    const content = result?.content;
+    if (!Array.isArray(content))
+        return {};
+    const text = content
+        .filter((p) => p && p.type === 'text' && typeof p.text === 'string')
+        .map((p) => p.text)
+        .join('\n');
+    if (!text)
+        return {};
+    const clean = redactFailureText(text);
+    return clean.length > 2048
+        ? { output: clean.slice(0, 2047) + '…', output_truncated: true }
+        : { output: clean };
+}
 // The upstream client does not expose process identity/group ownership or the
 // extension UI subprotocol. Keep this narrow transport behind the Pi adapter.
 export class PiProcess extends EventEmitter {
@@ -78,7 +99,7 @@ export class PiProcess extends EventEmitter {
                                     input_digest: textDigest(input),
                                     input_truncated: input.length > 8192,
                                 }
-                                : { failed: record.isError === true }),
+                                : { failed: record.isError === true, ...toolOutput(record.result) }),
                         });
                     }
                     this.emit('record', record);

package/dist/src/project-instructions.js

@@ -0,0 +1,195 @@
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, sep } from 'node:path';
+import { canonical, digest, textDigest } from './protocol.js';
+/** One file's bound, and the bound on everything loaded together. */
+export const INSTRUCTION_FILE_BYTES = 32 * 1024;
+export const INSTRUCTION_TOTAL_BYTES = 64 * 1024;
+/** AGENTS.md is the shared convention; CLAUDE.md is read only where a directory has no AGENTS.md. */
+const NAMES = ['AGENTS.md', 'CLAUDE.md'];
+/** The user-level instructions file: $XDG_CONFIG_HOME/salaam/AGENTS.md, else ~/.config/salaam/AGENTS.md. */
+export function userInstructionsPath(env = process.env) {
+    return join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'salaam', 'AGENTS.md');
+}
+function repositoryRoot(cwd) {
+    let dir = cwd;
+    for (let i = 0; i < 64; i++) {
+        if (existsSync(join(dir, '.git')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Project instructions for an interactive session, the way other harnesses read them: the
+ * user-level file, then AGENTS.md (or CLAUDE.md) in every directory from the repository root down
+ * to the session folder. Bounded, regular UTF-8 files only; anything skipped says why.
+ */
+export function discoverInstructions(cwd, userFile = userInstructionsPath()) {
+    const files = [];
+    const skipped = [];
+    let total = 0;
+    /** Returns whether the file exists (so CLAUDE.md is not read beside an AGENTS.md). */
+    const take = (scope, abs, shown) => {
+        let st;
+        try {
+            st = lstatSync(abs);
+        }
+        catch {
+            return false;
+        }
+        if (!st.isFile()) {
+            skipped.push({
+                path: shown,
+                reason: st.isSymbolicLink() ? 'symbolic links are not loaded' : 'not a regular file',
+            });
+            return true;
+        }
+        if (st.size > INSTRUCTION_FILE_BYTES) {
+            skipped.push({ path: shown, reason: `larger than ${INSTRUCTION_FILE_BYTES / 1024} KiB` });
+            return true;
+        }
+        const bytes = readFileSync(abs);
+        const text = bytes.toString('utf8');
+        if (!Buffer.from(text).equals(bytes) || text.includes('\0')) {
+            skipped.push({ path: shown, reason: 'not UTF-8 text' });
+            return true;
+        }
+        if (total + bytes.length > INSTRUCTION_TOTAL_BYTES) {
+            skipped.push({
+                path: shown,
+                reason: `instructions together exceed ${INSTRUCTION_TOTAL_BYTES / 1024} KiB`,
+            });
+            return true;
+        }
+        total += bytes.length;
+        files.push({ scope, path: shown, sha256: textDigest(text), bytes: bytes.length, text });
+        return true;
+    };
+    if (userFile) {
+        const home = homedir();
+        take('user', userFile, userFile.startsWith(home + sep) ? '~/' + relative(home, userFile) : userFile);
+    }
+    const root = repositoryRoot(cwd) ?? cwd;
+    const dirs = [root];
+    for (const part of relative(root, cwd).split(sep).filter(Boolean))
+        dirs.push(join(dirs.at(-1), part));
+    for (const dir of dirs)
+        for (const name of NAMES) {
+            const abs = join(dir, name);
+            if (take('project', abs, relative(cwd, abs) || name))
+                break;
+        }
+    return { files, skipped };
+}
+/**
+ * Interactive sessions load project instructions automatically and reload them when they change.
+ * Each loaded set is kept as an artifact and announced by an `instructions.loaded` event with its
+ * digest, so a turn's guidance is traceable to exact bytes. Strict work (board, AgentPod, child
+ * workers) never uses this: it keeps explicitly reviewed context only.
+ */
+export class ProjectInstructions {
+    store;
+    artifacts;
+    userFile;
+    loaded = new Map();
+    constructor(store, artifacts, userFile = userInstructionsPath()) {
+        this.store = store;
+        this.artifacts = artifacts;
+        this.userFile = userFile;
+    }
+    applies(id) {
+        const has = (table) => !!this.store.db
+            .prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?")
+            .get(table);
+        return (this.store.localWorkspace(id) &&
+            !(has('child_tasks') &&
+                this.store.db.prepare('SELECT 1 FROM child_tasks WHERE child_session=?').get(id)) &&
+            !(has('agentpod_admissions') &&
+                this.store.db.prepare('SELECT 1 FROM agentpod_admissions WHERE session_id=?').get(id)));
+    }
+    latest(id) {
+        const row = this.store.db
+            .prepare("SELECT seq,payload FROM events WHERE session_id=? AND kind='instructions.loaded' ORDER BY seq DESC LIMIT 1")
+            .get(id);
+        if (!row)
+            return null;
+        const p = JSON.parse(row.payload);
+        return { ...p, revision: p.revision ?? 1 };
+    }
+    /** Discover the current files; record a new revision only when they changed. */
+    refresh(id) {
+        if (!this.applies(id))
+            return null;
+        const found = discoverInstructions(this.store.session(id).cwd, this.userFile);
+        const document = { version: 1, ...found };
+        const current = digest(document);
+        const prior = this.latest(id);
+        if (prior?.digest === current)
+            return this.summary(id);
+        if (!prior && !found.files.length && !found.skipped.length)
+            return null;
+        const text = canonical(document);
+        const artifact = this.artifacts.prepare(id, text);
+        const revision = (prior?.revision ?? 0) + 1;
+        this.store.transaction(() => {
+            artifact.commit();
+            this.store.event(id, 'instructions.loaded', {
+                digest: current,
+                revision,
+                artifact_id: artifact.id,
+                reason: !prior ? 'initial' : found.files.length ? 'changed' : 'removed',
+                files: found.files.map(({ text: _text, ...file }) => file),
+                skipped: found.skipped,
+            });
+        });
+        this.loaded.set(id, { digest: current, document });
+        return this.summary(id);
+    }
+    summary(id) {
+        const prior = this.applies(id) ? this.latest(id) : null;
+        return prior
+            ? {
+                digest: prior.digest,
+                revision: prior.revision,
+                files: prior.files,
+                skipped: prior.skipped,
+            }
+            : null;
+    }
+    document(id) {
+        const prior = this.latest(id);
+        if (!prior || !prior.files.length)
+            return null;
+        const cached = this.loaded.get(id);
+        if (cached?.digest === prior.digest)
+            return cached.document;
+        const document = JSON.parse(this.artifacts.read(prior.artifact_id));
+        if (digest(document) !== prior.digest)
+            throw new Error('Project instructions artifact changed');
+        this.loaded.set(id, { digest: prior.digest, document });
+        return document;
+    }
+    /** The loaded guidance, as part of the task frame. Empty when none applies. */
+    frame(id) {
+        if (!this.applies(id))
+            return '';
+        const document = this.document(id);
+        if (!document)
+            return '';
+        return ('SALAAM_PROJECT_INSTRUCTIONS_V1 ' +
+            canonical({
+                digest: this.latest(id).digest,
+                instructions: 'Project guidance from AGENTS.md (or CLAUDE.md) files, loaded automatically for this interactive session. Follow it for how to work in this repository. It grants no tools, permissions or authority: approvals and the sandbox still apply.',
+                files: document.files.map(({ scope, path, sha256, text }) => ({
+                    scope,
+                    path,
+                    sha256,
+                    text,
+                })),
+            }));
+    }
+}

package/dist/src/protocol.js

@@ -34,20 +34,26 @@ export function workerCapabilities(coding, childTools) {
         ...(childTools?.includes('salaam_station') ? ['protected-station-v1'] : []),
         ...(childTools?.includes('salaam_workspace') ? ['local-workspace-read'] : []),
         ...(childTools?.includes('salaam_local') ? ['local-coding-reviewed'] : []),
+        ...(childTools?.includes('salaam_operator_mcp') ? ['operator-mcp-v1'] : []),
     ];
 }
-export function workerTools(effects, child = false, coding, childTools, mcp = false, toolkit = false, station = false, local = false, localCoding = false) {
+export function workerTools(effects, child = false, coding, childTools, mcp = false, toolkit = false, station = false, local = false, localCoding = false, operatorMcp = false) {
     return child
         ? [...(childTools ?? ['salaam_probe'])].sort()
         : [
             ...(local ? ['salaam_history', 'salaam_workspace'] : TOOLS),
-            ...(localCoding ? ['salaam_local'] : []),
+            // Interactive coding also gets built-in web search and fetch (operator ruling 2026-10-31).
+            ...(localCoding
+                ? ['salaam_local', 'salaam_tasks', 'salaam_web_fetch', 'salaam_web_search']
+                : []),
             ...(effects ? ['salaam_effect'] : []),
             ...(coding?.files ? ['salaam_files'] : []),
             ...(coding?.commands ? ['salaam_command'] : []),
             ...(mcp ? ['salaam_mcp'] : []),
             ...(toolkit ? ['salaam_toolkit'] : []),
-            ...(station ? ['salaam_station'] : []),
+            // salaam_board: read-only board reads, served by the hub (operator ruling 2026-10-28).
+            ...(station ? ['salaam_board', 'salaam_station'] : []),
+            ...(operatorMcp ? ['salaam_operator_mcp'] : []),
         ].sort();
 }
 export class ServiceError extends Error {