@superjackfruitlabs/salaam 0.0.3 → 0.0.4

package/dist/src/command-sandbox.js

@@ -0,0 +1,217 @@
+import { COMMAND_NETWORK_PORT, inSandboxRelaySource } from './command-network.js';
+import { existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { isAbsolute } from 'node:path';
+import { ServiceError } from './protocol.js';
+/**
+ * Item 10: the sandbox a local command runs in. `workspace-write` (the default) and `read-only` run
+ * the command under the host's OS sandbox, with the system read-only, a private tmp, the workspace
+ * writable or read-only, and no network unless declared:
+ * - Linux: bubblewrap, with an empty root and user, PID, IPC, UTS and network namespaces unshared,
+ *   dying with its parent;
+ * - macOS: Seatbelt (`sandbox-exec`), with a deny-by-default profile.
+ * `full-access` runs the command as is and must be chosen explicitly by the operator. A host with
+ * no usable sandbox refuses local commands (operator ruling 2026-10-30, option A) unless the host
+ * config sets `unsandboxed_commands: "allow"`; then it runs them unsandboxed and says so:
+ * "unsandboxed" in host plan and in every approval, and kind `none` in the approved arguments and
+ * the execution result.
+ */
+export const SANDBOX_LEVELS = ['read-only', 'workspace-write', 'full-access'];
+/** The pinned bubblewrap: its absolute path and the version it reports, or null when unusable. */
+export function findBwrap(candidates = ['/usr/bin/bwrap', '/bin/bwrap']) {
+    for (const path of candidates) {
+        if (!existsSync(path))
+            continue;
+        try {
+            const version = execFileSync(path, ['--version'], { encoding: 'utf8', timeout: 5000 }).trim();
+            // Usable means it can actually make the namespaces we ask for, not just that it exists.
+            execFileSync(path, ['--unshare-user', '--unshare-net', '--ro-bind', '/', '/', '--', '/bin/true'], {
+                timeout: 5000,
+                stdio: 'ignore',
+            });
+            return { path, version };
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+export function sandboxArgv(level, root, argv, bwrap, options) {
+    if (level === 'full-access')
+        return argv;
+    if (!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 (!isAbsolute(root) || root.includes('\0'))
+        throw new ServiceError('invalid_field', 'A sandboxed command needs an absolute workspace path');
+    // Optional system directories, bound read-only only where the host has them.
+    const optional = ['/lib', '/lib64', '/lib32', '/bin', '/sbin', '/etc/alternatives'].flatMap((dir) => ['--ro-bind-try', dir, dir]);
+    return [
+        bwrap.path,
+        '--unshare-user',
+        '--unshare-pid',
+        '--unshare-ipc',
+        '--unshare-uts',
+        ...(options.network ? [] : ['--unshare-net']),
+        '--die-with-parent',
+        '--new-session',
+        '--tmpfs',
+        '/',
+        // The system read-only; /usr and /etc/ssl always asked for, the rest only where present.
+        '--ro-bind',
+        '/usr',
+        '/usr',
+        '--ro-bind',
+        '/etc/ssl',
+        '/etc/ssl',
+        ...optional,
+        '--proc',
+        '/proc',
+        '--dev',
+        '/dev',
+        '--tmpfs',
+        '/tmp',
+        level === 'read-only' ? '--ro-bind' : '--bind',
+        root,
+        root,
+        // Broker network: only the host relay's socket directory and the node that bridges to it.
+        ...(options.broker
+            ? [
+                '--bind',
+                options.broker.dir,
+                '/run/salaam-net',
+                '--ro-bind',
+                options.broker.node,
+                '/run/salaam-node',
+            ]
+            : []),
+        // The empty root itself is read-only too: only the workspace (and the private /tmp) is writable.
+        '--remount-ro',
+        '/',
+        '--chdir',
+        root,
+        '--',
+        ...(options.broker
+            ? [
+                '/run/salaam-node',
+                '-e',
+                inSandboxRelaySource,
+                '/run/salaam-net/relay.sock',
+                String(COMMAND_NETWORK_PORT),
+            ]
+            : []),
+        ...argv,
+    ];
+}
+function brokerPort(port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new ServiceError('invalid_field', 'A broker relay port is 1–65535');
+    return port;
+}
+/** The pinned Seatbelt launcher, or null when this host cannot apply a deny-by-default profile. */
+export function findSeatbelt(path = '/usr/bin/sandbox-exec') {
+    if (!existsSync(path))
+        return null;
+    try {
+        // Usable means it applies a deny-by-default profile and the command still runs.
+        execFileSync(path, [
+            '-p',
+            '(version 1)(deny default)(allow process-exec process-fork)(allow file-read*)(allow sysctl-read)',
+            '/usr/bin/true',
+        ], { timeout: 5000, stdio: 'ignore' });
+        return { path };
+    }
+    catch {
+        return null;
+    }
+}
+/** A path Seatbelt can quote: absolute, with no quote, backslash or control character. */
+function sbplPath(path, what) {
+    if (!isAbsolute(path) || /["\\\x00-\x1f\x7f]/.test(path))
+        throw new ServiceError('invalid_field', `A sandboxed command needs a plain absolute ${what}`);
+    return `"${path}"`;
+}
+/**
+ * The deny-by-default Seatbelt profile for a level. Reads: the system, developer tools and
+ * package prefixes, the workspace and the private tmp (file metadata anywhere, so paths resolve).
+ * Writes: the workspace (workspace-write only), the private tmp and the standard devices. No
+ * network unless declared, no mach services, no home directory.
+ */
+export function seatbeltProfile(level, root, tmp, 
+/** brokerPort: the host relay's loopback port, the only place a broker-network command may connect. */
+options) {
+    const w = sbplPath(root, 'workspace path'), t = sbplPath(tmp, 'tmp path');
+    const system = [
+        '/usr',
+        '/bin',
+        '/sbin',
+        '/System',
+        '/Library/Apple',
+        '/Library/Developer/CommandLineTools',
+        '/Applications/Xcode.app',
+        '/opt/homebrew',
+        '/usr/local',
+        '/private/etc',
+        '/private/var/db/dyld',
+        '/private/var/db/timezone',
+        '/dev',
+    ]
+        .map((p) => `(subpath "${p}")`)
+        .join(' ');
+    const devices = ['/dev/null', '/dev/zero', '/dev/stdout', '/dev/stderr', '/dev/tty']
+        .map((p) => `(literal "${p}")`)
+        .join(' ');
+    return [
+        '(version 1)',
+        '(deny default)',
+        '(allow process-exec process-fork)',
+        '(allow signal (target same-sandbox))',
+        '(allow sysctl-read)',
+        '(allow file-read-metadata)',
+        `(allow file-read* (literal "/") ${system} (subpath ${w}) (subpath ${t}))`,
+        level === 'workspace-write'
+            ? `(allow file-write* (subpath ${w}) (subpath ${t}) ${devices} (regex #"^/dev/fd/"))`
+            : `(allow file-write* (subpath ${t}) ${devices} (regex #"^/dev/fd/"))`,
+        `(allow file-ioctl ${devices} (regex #"^/dev/fd/"))`,
+        ...(options.network ? ['(allow network*)'] : []),
+        ...(options.brokerPort !== undefined && !options.network
+            ? [`(allow network-outbound (remote tcp "localhost:${brokerPort(options.brokerPort)}"))`]
+            : []),
+    ].join('\n');
+}
+export function seatbeltArgv(level, root, tmp, argv, seatbelt, options) {
+    if (level === 'full-access')
+        return argv;
+    if (!seatbelt)
+        throw new ServiceError('sandbox_unavailable', 'This host has no usable Seatbelt, so it cannot run a sandboxed command; an operator can choose full access explicitly');
+    return [
+        seatbelt.path,
+        '-p',
+        seatbeltProfile(level, root, tmp, options),
+        '/usr/bin/env',
+        `TMPDIR=${tmp}/`,
+        ...argv,
+    ];
+}
+/** The sandbox this host gives local commands: bubblewrap on Linux and Seatbelt on macOS when
+ * usable, otherwise none. */
+export function chooseLocalSandbox(level, platform = process.platform, find = findBwrap, findSb = findSeatbelt) {
+    const none = { kind: 'none', level, bwrap: null, seatbelt: null };
+    if (level === 'full-access')
+        return none;
+    if (platform === 'linux') {
+        const bwrap = find();
+        return bwrap ? { ...none, kind: 'bwrap', bwrap } : none;
+    }
+    if (platform === 'darwin') {
+        const seatbelt = findSb();
+        return seatbelt ? { ...none, kind: 'seatbelt', seatbelt } : none;
+    }
+    return none;
+}
+/** How host plan and approvals name a sandbox kind. */
+export function sandboxLabel(kind) {
+    return kind === 'bwrap' ? 'bubblewrap' : kind === 'seatbelt' ? 'seatbelt' : 'unsandboxed';
+}
+/** The refusal for a local command on a host with no usable sandbox and no operator opt-in. */
+export const UNSANDBOXED_REFUSAL = 'Local commands are refused: this host has no usable command sandbox (bubblewrap on Linux, Seatbelt on macOS). Install or repair bubblewrap, or have the operator set unsandboxed_commands: "allow" in the host config to run them unsandboxed.';

package/dist/src/execution-evidence.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { digest, ServiceError, textDigest } from './protocol.js';
 import { verifyReadinessFingerprint } from './readiness-fingerprint.js';
 import { committedToolkitResolutionEvidence } from './toolkit-evidence.js';
@@ -181,6 +182,34 @@ export function executionEvidence(store, artifacts, admission, taskId, session)
     const artifactRows = bounded('artifacts', owned(`
     SELECT id,session_id,digest,bytes FROM artifacts
     WHERE session_id IN (SELECT id FROM tree) ORDER BY id LIMIT 257`));
+    // A verified completion names each deliverable's artifact with the sha256 of its bytes.
+    // Only an artifact whose bytes match that digest counts as produced; dispositions are
+    // computed for this session's own artifacts alone, so another session's id names nothing.
+    const deliverables = new Set();
+    const completed = store.db
+        .prepare("SELECT artifact_id FROM task_completions WHERE task_id=? AND state='succeeded'")
+        .get(taskId);
+    if (completed?.artifact_id) {
+        let record = {};
+        try {
+            record = JSON.parse(artifacts.read(String(completed.artifact_id)));
+        }
+        catch {
+            record = {};
+        }
+        for (const d of Array.isArray(record.deliverables) ? record.deliverables : []) {
+            const id = d.artifact_id, sha = d.sha256;
+            if (typeof id !== 'string' || typeof sha !== 'string')
+                continue;
+            try {
+                if (createHash('sha256').update(artifacts.read(id)).digest('hex') === sha)
+                    deliverables.add(id);
+            }
+            catch {
+                /* a missing or corrupt artifact is not a deliverable */
+            }
+        }
+    }
     const artifactEvidence = artifactRows.map((row) => {
         // Check actual immutable bytes, not just a database's claimed fingerprint.
         const content = artifacts.read(String(row.id));
@@ -207,7 +236,10 @@ export function executionEvidence(store, artifacts, admission, taskId, session)
             ? 'integrated'
             : children.some((child) => child.artifact_id === row.id)
                 ? 'proposed'
-                : appliedPatch || completion || checks.some((check) => check.artifact_id === row.id)
+                : appliedPatch ||
+                    completion ||
+                    deliverables.has(String(row.id)) ||
+                    checks.some((check) => check.artifact_id === row.id)
                     ? 'produced'
                     : 'observed';
         return { ...row, disposition };

package/dist/src/host-bind.js

@@ -0,0 +1,111 @@
+import { chmodSync, closeSync, fsyncSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, writeFileSync, existsSync, } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { isAbsolute, join, resolve } from 'node:path';
+import { planHost } from './host.js';
+import { canonical, digest } from './protocol.js';
+import { stationHash, stationRuntimeFingerprint, stationWorkspaceIdentity, } from './station-config.js';
+const userName = /^[a-z_][a-z0-9_-]{0,31}$/;
+function pin(path) {
+    const real = realpathSync(path);
+    return { path: real, sha256: stationHash(readFileSync(real)) };
+}
+/** Write a private file only when its content changes; report whether it did. */
+function put(path, value) {
+    const text = JSON.stringify(value, null, 2) + '\n';
+    if (existsSync(path) && readFileSync(path, 'utf8') === text)
+        return false;
+    const tmp = path + '.tmp', fd = openSync(tmp, 'w', 0o600);
+    try {
+        writeFileSync(fd, text);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, path);
+    return true;
+}
+/** Bind one AgentPod station to a launcher-profile strict work host. Root on Linux.
+ * Every output is derived from the inputs; nothing is edited by hand. */
+export async function bindHost(input) {
+    if (process.platform !== 'linux' || process.getuid?.() !== 0)
+        throw Error('host bind runs as root on Linux');
+    const workspace = input.workspace;
+    if (!isAbsolute(workspace) || realpathSync(workspace) !== workspace)
+        throw Error('Use the canonical absolute workspace path');
+    const key = 'salaam:' + createHash('sha256').update(workspace).digest('hex').slice(0, 16);
+    if (input.station_key !== key)
+        throw Error('Station key does not name this workspace (expected ' + key + ')');
+    if (!userName.test(input.tools_user))
+        throw Error('tools user must be a user name');
+    try {
+        execFileSync('/usr/bin/getent', ['passwd', input.tools_user], { stdio: 'ignore' });
+    }
+    catch {
+        throw Error('tools user does not exist');
+    }
+    if (input.tools_user === 'root')
+        throw Error('tools user must not be root');
+    const id = key.slice('salaam:'.length), roots = input.roots ?? { config: '/etc/salaam/stations', state: '/var/lib/salaam/stations' }, dir = resolve(input.dir ?? join(roots.config, id)), state = resolve(input.state ?? join(roots.state, id, 'state'));
+    mkdirSync(dir, { recursive: true, mode: 0o755 });
+    // Ancestors of state stay traversable so the operator group can reach operator.sock;
+    // state itself is the daemon's (0700, or 0710 for the operator group once served).
+    mkdirSync(join(state, '..'), { recursive: true, mode: 0o755 });
+    chmodSync(join(state, '..'), 0o755);
+    const pinsPath = join(dir, 'agentpod-pins.json'), stationPath = join(dir, 'station-config.json'), configPath = join(dir, 'host-config.json'), manifestPath = join(dir, 'host.json');
+    let changed = put(pinsPath, {
+        version: 1,
+        organization_id: input.organization_id,
+        node_id: input.node_id,
+        station_key: key,
+        workspace,
+    });
+    const runtime = realpathSync(input.runtime_root);
+    changed =
+        put(stationPath, {
+            version: 1,
+            kind: 'linux-systemd-station-v1',
+            workspace,
+            workspace_identity: stationWorkspaceIdentity(workspace),
+            files: pin(input.files),
+            systemd_run: pin(input.systemd_run ?? '/usr/bin/systemd-run'),
+            systemctl: pin(input.systemctl ?? '/usr/bin/systemctl'),
+            runtime_root: runtime,
+            runtime_fingerprint: stationRuntimeFingerprint(runtime),
+            runtime_image_digest: input.runtime_image_digest,
+            tools_user: input.tools_user,
+        }) || changed;
+    const config = {
+        mode: 'agentpod',
+        state,
+        agentpod_config: pinsPath,
+        station_config: stationPath,
+        strict_work_version: 1,
+        ...(input.operator_group ? { operator_group: input.operator_group } : {}),
+        ...(input.provider ? { provider: input.provider } : {}),
+        ...(input.model ? { model: input.model } : {}),
+        ...(input.mcp_config ? { operator_mcp_config: realpathSync(input.mcp_config) } : {}),
+        ...(input.persona ? { persona_config: realpathSync(input.persona) } : {}),
+        ...(input.managed_mcp_config ? { mcp_config: realpathSync(input.managed_mcp_config) } : {}),
+    };
+    changed = put(configPath, config) || changed;
+    const manifest = await planHost(config);
+    const before = existsSync(manifestPath)
+        ? canonical(JSON.parse(readFileSync(manifestPath, 'utf8')))
+        : null;
+    if (before !== canonical(manifest)) {
+        put(manifestPath, manifest);
+        changed = true;
+    }
+    return {
+        version: 1,
+        station_key: key,
+        dir,
+        state,
+        manifest: manifestPath,
+        manifest_digest: digest(manifest),
+        unit: 'salaam-host@' + id + '.service',
+        changed,
+    };
+}

package/dist/src/host-breaker.js

@@ -0,0 +1,88 @@
+/**
+ * A circuit breaker for agent fetches (operator MCP calls whose arguments carry a `url`). After
+ * repeated consecutive failures to one host within a session, calls to that host are paused for a
+ * short while: the agent gets a tool error saying so and can do something else, and the run's
+ * activity gets one line. Nothing fails the run, and a paused call is never made, so it records no
+ * operator MCP call. One success to the host closes the breaker again.
+ */
+export const BREAKER_FAILURES = 3;
+export const BREAKER_PAUSE_MS = 60_000;
+export function fetchHost(args) {
+    const url = args?.url;
+    if (typeof url !== 'string')
+        return null;
+    try {
+        const host = new URL(url).hostname.toLowerCase();
+        return host || null;
+    }
+    catch {
+        return null;
+    }
+}
+export class HostBreaker {
+    now;
+    hosts = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    key(session, host) {
+        return session + '\u0000' + host;
+    }
+    /** Milliseconds this host stays paused for the session, 0 when calls may go ahead. */
+    paused(session, host) {
+        const h = this.hosts.get(this.key(session, host));
+        return h ? Math.max(0, h.until - this.now()) : 0;
+    }
+    /** Records a call's outcome; true when this failure just opened the breaker. */
+    record(session, host, ok) {
+        const key = this.key(session, host);
+        if (ok) {
+            this.hosts.delete(key);
+            return false;
+        }
+        const h = this.hosts.get(key) ?? { failures: 0, until: 0 };
+        h.failures++;
+        this.hosts.set(key, h);
+        if (h.failures < BREAKER_FAILURES)
+            return false;
+        h.failures = 0;
+        h.until = this.now() + BREAKER_PAUSE_MS;
+        return true;
+    }
+    forget(session) {
+        for (const key of this.hosts.keys())
+            if (key.startsWith(session + '\u0000'))
+                this.hosts.delete(key);
+    }
+}
+/**
+ * One operator MCP call through the breaker. A paused host returns a tool error without calling;
+ * a thrown failure or a tool error counts against the host; the call that opens the breaker
+ * records `fetch.host_paused` for the run's activity. The call's own result or error is unchanged.
+ */
+export async function callThroughBreaker(breaker, session, args, event, call) {
+    const host = fetchHost(args);
+    if (!host)
+        return call();
+    const wait = breaker.paused(session, host);
+    if (wait)
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Requests to ${host} are paused for ${Math.ceil(wait / 1000)}s after repeated failures; try another source or retry later.`,
+                },
+            ],
+            is_error: true,
+        };
+    let ok = false;
+    try {
+        const result = await call();
+        ok = !result.is_error;
+        return result;
+    }
+    finally {
+        if (breaker.record(session, host, ok))
+            event({ host, failures: BREAKER_FAILURES, pause_ms: BREAKER_PAUSE_MS });
+    }
+}

package/dist/src/host-start.js

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { spawn, execFile } from 'node:child_process';
 import { constants, openSync, closeSync, fstatSync, mkdirSync, realpathSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { readHost, hostMcp, hostToolkit } from './host.js';
@@ -118,3 +118,43 @@ export async function startHost(path) {
         release();
     }
 }
+const launcherUnit = /^salaam-host@[a-f0-9]{16}\.service$/;
+/** Launcher profile: an unprivileged operator asks systemd to start a root-owned,
+ * provisioned unit. It names only the unit; root reads its own reviewed manifest. */
+export async function startHostUnit(unit, state, options = {}) {
+    if (!launcherUnit.test(unit))
+        throw Error('Unit must be salaam-host@<16 hex>.service');
+    if (realpathSync(state) !== state)
+        throw Error('Use the canonical state path');
+    const socket = join(state, 'operator.sock'), deadline = Date.now() + (options.timeoutMs ?? 20000);
+    const ready = async () => {
+        let h;
+        try {
+            h = await call(socket, '/v1/health', undefined, undefined, 2000);
+        }
+        catch {
+            return null;
+        }
+        if (!h.host_receipt || h.host_receipt.manifest_digest !== h.host_manifest_digest)
+            throw new ServiceError('host_mismatch', 'Running daemon reports no reviewed host receipt');
+        if (h.host_receipt.state !== state)
+            throw new ServiceError('host_mismatch', 'Running daemon serves another state directory');
+        if (h.host_supervisor_connected !== true || h.service !== 'healthy')
+            return null;
+        if (h.job_execution?.control_error ||
+            h.job_execution?.schedule_control_error ||
+            h.job_execution?.inbox_control_error)
+            throw Error('Reviewed host controls are not ready');
+        return h.host_receipt;
+    };
+    let receipt = await ready();
+    if (receipt)
+        return receipt;
+    await new Promise((done, fail) => execFile(options.systemctl ?? '/usr/bin/systemctl', ['start', '--no-ask-password', unit], { env: { PATH: '/usr/bin:/bin', LANG: 'C.UTF-8' }, timeout: 20000 }, (error) => error ? fail(Error('systemd refused to start ' + unit + '; inspect its journal')) : done()));
+    while (!(receipt = await ready())) {
+        if (Date.now() >= deadline)
+            throw Error('Host unit did not become ready; inspect its journal');
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    return receipt;
+}