@superjackfruitlabs/salaam 0.0.4 → 0.0.5

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/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/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/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

@@ -42,7 +42,10 @@ export function workerTools(effects, child = false, coding, childTools, mcp = fa
         ? [...(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'] : []),