@superjackfruitlabs/salaam 0.0.3 → 0.0.4

package/CHANGELOG.md

@@ -6,6 +6,51 @@ are forward-only: keep a stopped-daemon backup before upgrading.
 
 ## [Unreleased]
 
+## [0.0.4] - 2026-10-30
+
+Board work on a protected AgentPod station, made to match the Hermes workflow, plus a sandbox
+for local commands.
+
+### Added
+
+- Approvals: "Approve for this run", per-agent "Always allow" (offered on workspace writes, owners
+  and admins only), plain-words approval offers, and rules added at renewal joining the run in
+  flight.
+- Completion critic: a plan may declare a rubric; a read-only reviewer judges the verified
+  deliverables before the task completes. Completion hooks are required checks.
+- Checkpoints: read-only checkpoints of a station run, their diff against the live workspace, and
+  restore exactly as approved.
+- Command sandbox: bubblewrap on Linux and Seatbelt on macOS. With no usable sandbox, local
+  commands are refused unless the host config sets `unsandboxed_commands: "allow"`.
+- Command network through the broker: with `command_network: "broker"` in the host config, local
+  commands reach only the hosts the operator lists in the stk policy (`local-commands`
+  egress `hosts`). Everything direct stays blocked, and each command's result counts the hosts it
+  reached or was refused. Needs SuperToolkit v0.0.4.
+- Board parity: the work-status tool-step tail carries each step's output and a readable title;
+  plan updates reach the card; board reads are served by the hub.
+- Operator persona pinned by digest in the host manifest.
+- Budgets and retries: step request budgets, rate-limit retry then a provable stop, and
+  verification-budget stops that settle without anyone clearing them.
+- A fetch host that keeps failing is paused briefly instead of failing the run.
+- Add `--tools-user` (`SALAAM_TOOLS_USER`) to run local agent commands, edits and
+  undo as a separate unprivileged OS user via a runas-restricted sudo rule, so
+  tools cannot read the provider credential. Without it, startup warns.
+
+### Fixed
+
+- A verification read refused at spawn no longer leaves the daemon unable to start; a stuck
+  pid-less helper settles once `/proc` proves no helper runs (Linux only; elsewhere it stays
+  fenced).
+- A run stopped by its own failed acceptance check reaches the board as a failed run instead of
+  parking.
+- Readable titles for MCP steps with no input, and for finished steps.
+
+### Upgrade notes
+
+- Hosts without a usable bubblewrap (Linux) or Seatbelt (macOS) now refuse local commands. Install
+  or repair the sandbox, or set `unsandboxed_commands: "allow"` explicitly.
+- Release after AgentPod v0.1.118 (hub): the step output field and board reads need that hub.
+
 ## [0.0.3] - 2026-10-22
 
 - Update the MCP SDK and optional Hermes certificate bundle to patched releases.

package/README.md

@@ -99,17 +99,18 @@ by OS permissions. See [providers and credentials](docs/providers.md).
 
 ## What stays with the work
 
-| Capability                                       | What it means                                                                                                                |
-| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
-| [Sessions](docs/service-reference.md)            | Durable dispatch, client outboxes, controller leases and committed event replay.                                             |
-| [Coding](docs/coding.md)                         | Owned workspace copies, hash-bound patches and isolated commands through a proven Docker backend.                            |
-| [Tasks](docs/durable-tasks.md)                   | Stable steps, checked plans, budgets, checkpoints and opt-in bounded progression. Model text cannot complete a checked task. |
-| [Specialists and teams](docs/agents.md)          | Admitted profiles, isolated coding proposals, explicit integration, durable task-step claims and passive messages.           |
-| [External harnesses](docs/external-harnesses.md) | Pinned Gemini, Claude ACP and Codex workers with explicit invocation limits and shared approvals.                            |
-| [A2A peers](docs/a2a.md)                         | Authenticated, bounded peer analysis, explicit inbound grants and durable task ownership.                                    |
-| [Jobs and schedules](docs/jobs.md)               | Occurrence deduplication, immutable recurring templates and explicit missed-run and timezone/DST policies.                   |
-| [Host operation](docs/host-operation.md)         | Reviewed runtime/backend manifests, bounded supervisor restart and a shared CLI/TUI/ACP inbox.                               |
-| [Clients](docs/clients.md)                       | Terminal attachment, SSH and ACP v1 against the same service.                                                                |
+| Capability                                       | What it means                                                                                                                    |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| [Sessions](docs/service-reference.md)            | Durable dispatch, client outboxes, controller leases and committed event replay.                                                 |
+| [Coding](docs/coding.md)                         | Owned workspace copies, hash-bound patches and isolated commands through a proven Docker backend.                                |
+| [Tasks](docs/durable-tasks.md)                   | Stable steps, checked plans, budgets, checkpoints and opt-in bounded progression. Model text cannot complete a checked task.     |
+| [Specialists and teams](docs/agents.md)          | Admitted profiles, isolated coding proposals, explicit integration, durable task-step claims and passive messages.               |
+| [External harnesses](docs/external-harnesses.md) | Pinned Gemini, Claude ACP and Codex workers with explicit invocation limits and shared approvals.                                |
+| [A2A peers](docs/a2a.md)                         | Authenticated, bounded peer analysis, explicit inbound grants and durable task ownership.                                        |
+| [Jobs and schedules](docs/jobs.md)               | Occurrence deduplication, immutable recurring templates and explicit missed-run and timezone/DST policies.                       |
+| [Host operation](docs/host-operation.md)         | Reviewed runtime/backend manifests, bounded supervisor restart and a shared CLI/TUI/ACP inbox.                                   |
+| [Clients](docs/clients.md)                       | Terminal attachment, SSH and ACP v1 against the same service.                                                                    |
+| [MCP servers](docs/mcp.md)                       | Operator-declared stdio and HTTP servers (`sal mcp add`); workspaces never add tools; no inline secrets; per-session provenance. |
 
 ## Read this before trusting it
 

package/dist/src/acp-outcome.js

@@ -243,6 +243,139 @@ export function acpFailure(error, context = {}) {
         ...(kind === 'unknown' ? {} : { retryable: false }),
     };
 }
+/** ACP tool kind for an approval, so a client's modes can tell edits apart:
+ * AgentPod's accept-edits approves only kind "edit"; full-auto approves all; ask none. */
+export function permissionKind(operationKind) {
+    if (operationKind === 'workspace')
+        return 'edit';
+    if (operationKind === 'harness')
+        return 'execute';
+    return 'other';
+}
+/** An operator MCP catalog read is a read; a server's `fetch` tool is a fetch; others stay other. */
+function operatorMcpKind(action, tool) {
+    if (action === 'catalog')
+        return 'read';
+    return action === 'call' && tool === 'fetch' ? 'fetch' : 'other';
+}
+function toolArgs(input) {
+    try {
+        const value = typeof input === 'string' ? JSON.parse(input) : input;
+        if (value && typeof value === 'object' && !Array.isArray(value))
+            return value;
+    }
+    catch { }
+    return {};
+}
+const label = (v) => (typeof v === 'string' && /^[\w.-]{1,128}$/.test(v) ? v : undefined);
+/** One line of what a tool acted on, for a card title: no control characters, at most `max`. */
+function shown(v, max) {
+    if (typeof v !== 'string')
+        return undefined;
+    const t = v
+        .replace(/[\u0000-\u001f\u007f]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!t)
+        return undefined;
+    return t.length > max ? t.slice(0, max - 1) + '…' : t;
+}
+/** A URL as host and path only: never its login, query or fragment (they may carry a secret). */
+function shownUrl(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    try {
+        const u = new URL(v);
+        if (u.protocol !== 'http:' && u.protocol !== 'https:')
+            return undefined;
+        return u.host + (u.pathname === '/' ? '' : u.pathname);
+    }
+    catch {
+        return undefined;
+    }
+}
+const titled = (verb, what) => {
+    if (!what)
+        return verb;
+    const t = `${verb}: ${what}`;
+    return t.length > 80 ? t.slice(0, 79) + '…' : t;
+};
+/**
+ * The ACP title for a tool call, the way a board agent's card reads: the tool and what it acted on
+ * ("fetch: host/path", "write: runs/r/answer.md"). Every operator MCP call goes through one wrapper
+ * tool, so it is titled by the MCP tool itself. Only plain identifiers, URL host and path, paths,
+ * queries and commands are echoed, clipped to one line of 80 characters.
+ */
+/** A clipped input no longer parses: read the leading plain string fields it still carries. */
+function clippedArgs(input) {
+    if (typeof input !== 'string')
+        return {};
+    const out = {};
+    for (const key of [
+        'action',
+        'path',
+        'query',
+        'pattern',
+        'command',
+        'server',
+        'tool',
+        'item_id',
+    ]) {
+        const m = new RegExp(`"${key}"\\s*:\\s*"((?:[^"\\\\]|\\\\.){0,512})"`).exec(input);
+        if (m) {
+            try {
+                out[key] = JSON.parse(`"${m[1]}"`);
+            }
+            catch { }
+        }
+    }
+    // A clipped patch is a long one, so a write: a delete (content null) is short and never clipped.
+    return out;
+}
+export function toolTitle(name, input) {
+    const parsed = toolArgs(input);
+    const args = Object.keys(parsed).length ? parsed : clippedArgs(input);
+    const action = typeof args.action === 'string' ? args.action : '';
+    if (name === 'salaam_operator_mcp') {
+        const server = label(args.server);
+        const tool = label(args.tool);
+        if (action === 'call' && server && tool) {
+            const a = toolArgs(args.arguments);
+            return titled(tool, shownUrl(a.url) ?? shown(a.query ?? a.path ?? a.pattern, 80));
+        }
+        if (action === 'catalog')
+            return titled('MCP catalog', server);
+        if (action === 'call')
+            return titled('MCP call', server ?? tool);
+        return action ? titled('MCP request', label(action)) : 'MCP request (no input)';
+    }
+    if (name === 'salaam_board') {
+        if (action === 'card')
+            return 'read this card';
+        if (action === 'attempts')
+            return 'read this card’s runs';
+        if (action === 'library_search')
+            return titled('library_search', shown(args.query, 80));
+        if (action === 'library_get')
+            return titled('library_get', shown(args.item_id, 32));
+        return name;
+    }
+    if (['salaam_station', 'salaam_files', 'salaam_repository'].includes(name)) {
+        if (action === 'patch')
+            return titled(args.content === null ? 'delete' : 'write', shown(args.path, 80));
+        if (action === 'inspect' && args.path === undefined)
+            return 'inspect workspace';
+        if (action === 'check')
+            return titled('check', shown(args.command, 80));
+        if (['read', 'list', 'inspect', 'diff'].includes(action))
+            return titled(action, shown(args.path, 80));
+        if (action === 'search')
+            return titled('search', shown(args.query ?? args.pattern, 80));
+        if (action)
+            return action;
+    }
+    return name;
+}
 export function toolMetadata(name, input, root) {
     let args = {};
     try {
@@ -252,25 +385,29 @@ export function toolMetadata(name, input, root) {
     }
     catch { }
     const action = String(args.action ?? '');
-    const kind = name === 'salaam_command' || (name === 'salaam_station' && action === 'check')
-        ? ['start', 'cancel', 'check'].includes(action)
-            ? 'execute'
-            : ['status', 'logs'].includes(action)
-                ? 'read'
-                : 'other'
-        : ['salaam_files', 'salaam_station'].includes(name) && action === 'patch'
-            ? args.content === null
-                ? 'delete'
-                : 'edit'
-            : ['salaam_files', 'salaam_repository', 'salaam_station'].includes(name) &&
-                ['search', 'list'].includes(action)
-                ? 'search'
-                : ['salaam_files', 'salaam_repository', 'salaam_station'].includes(name) &&
-                    ['read', 'inspect', ...(name === 'salaam_repository' ? ['diff'] : [])].includes(action)
+    const kind = name === 'salaam_board'
+        ? 'read'
+        : name === 'salaam_command' || (name === 'salaam_station' && action === 'check')
+            ? ['start', 'cancel', 'check'].includes(action)
+                ? 'execute'
+                : ['status', 'logs'].includes(action)
                     ? 'read'
-                    : ['salaam_history', 'inspect_child', 'consume_child_result'].includes(name)
+                    : 'other'
+            : ['salaam_files', 'salaam_station'].includes(name) && action === 'patch'
+                ? args.content === null
+                    ? 'delete'
+                    : 'edit'
+                : ['salaam_files', 'salaam_repository', 'salaam_station'].includes(name) &&
+                    ['search', 'list'].includes(action)
+                    ? 'search'
+                    : ['salaam_files', 'salaam_repository', 'salaam_station'].includes(name) &&
+                        ['read', 'inspect', ...(name === 'salaam_repository' ? ['diff'] : [])].includes(action)
                         ? 'read'
-                        : 'other';
+                        : ['salaam_history', 'inspect_child', 'consume_child_result'].includes(name)
+                            ? 'read'
+                            : name === 'salaam_operator_mcp'
+                                ? operatorMcpKind(action, args.tool)
+                                : 'other';
     const locations = [];
     if (['salaam_files', 'salaam_station'].includes(name) &&
         root &&
@@ -286,3 +423,26 @@ export function toolMetadata(name, input, root) {
     }
     return { kind, locations };
 }
+/** A durable task's steps as the ACP `plan` session update: the whole list, replaced on every
+ * change (https://agentclientprotocol.com/protocol/agent-plan). ACP has only pending,
+ * in_progress and completed, so a step that stopped says so in its text instead. */
+export function planUpdate(task) {
+    if (!task?.steps.length)
+        return null;
+    return {
+        sessionUpdate: 'plan',
+        entries: task.steps.map((step) => {
+            const status = step.state === 'completed'
+                ? 'completed'
+                : step.state === 'running' || step.state === 'awaiting_review'
+                    ? 'in_progress'
+                    : 'pending';
+            const stopped = ['cancelled', 'failed', 'interrupted'].includes(step.state);
+            return {
+                content: stopped ? `${step.title} (${step.state})` : step.title,
+                priority: 'medium',
+                status,
+            };
+        }),
+    };
+}

package/dist/src/acp.js

@@ -1,18 +1,19 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { realpathSync } from 'node:fs';
+import { mkdirSync, realpathSync, statSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { once } from 'node:events';
 import { call } from './transport.js';
 import { acquireControl, Outbox, subscribe } from './attach.js';
 import { AcpJournal } from './acp-journal.js';
 import { VERSION } from './config.js';
-import { acpFailure, AcpFailureError, toolMetadata } from './acp-outcome.js';
+import { acpFailure, AcpFailureError, permissionKind, toolMetadata, toolTitle, planUpdate, } from './acp-outcome.js';
 import { validateManagedMcpDeclarations } from './mcp-acp.js';
 import { object, string, ServiceError, } from './protocol.js';
 /** ACP v1 newline-delimited stdio adapter. The daemon remains the only worker owner. */
 export async function acp(state, options = {}) {
     const socket = join(state, 'operator.sock');
-    const journal = new AcpJournal(state);
+    const client = acpClientState(state);
+    const journal = new AcpJournal(client);
     const admission = process.env.SALAAM_AGENTPOD_ADMISSION, admissionToken = process.env.SALAAM_AGENTPOD_TOKEN;
     delete process.env.SALAAM_AGENTPOD_ADMISSION;
     delete process.env.SALAAM_AGENTPOD_TOKEN;
@@ -60,6 +61,15 @@ export async function acp(state, options = {}) {
             params: { sessionId: id, update: out },
         });
     };
+    /** Send the session's durable task plan when it differs from the last one sent. */
+    const sendPlan = async (c, task) => {
+        const plan = planUpdate(task === undefined ? (await snapshot(c.id)).work_task : task);
+        const key = plan ? JSON.stringify(plan) : undefined;
+        if (!plan || key === c.plan)
+            return;
+        c.plan = key;
+        await update(c.id, plan);
+    };
     const promptReceipt = async (session, request, attemptId) => {
         if (!bound || !wantsReceipts)
             return;
@@ -144,7 +154,7 @@ export async function acp(state, options = {}) {
                                 await update(c.id, {
                                     sessionUpdate: 'tool_call',
                                     toolCallId: String(part.id),
-                                    title: String(part.name),
+                                    title: toolTitle(String(part.name), part.arguments),
                                     ...(await toolDetails(c.id, String(part.id), String(part.name), part.arguments)),
                                     status: 'in_progress',
                                     rawInput: part.arguments,
@@ -206,7 +216,7 @@ export async function acp(state, options = {}) {
             const toolCall = {
                 toolCallId: 'salaam-operation:' + op.id,
                 title: op.kind + ': ' + op.target,
-                kind: 'other',
+                kind: permissionKind(op.kind),
                 status: 'pending',
                 rawInput: {
                     target: op.target,
@@ -228,7 +238,7 @@ export async function acp(state, options = {}) {
                     !['allow-once', 'reject-once'].includes(String(outcome.optionId)))
                     throw new Error('Invalid permission outcome');
                 const decide = async () => {
-                    const outbox = new Outbox(state, c.id);
+                    const outbox = new Outbox(client, c.id);
                     outbox.enqueueDecision(approval.id, approval.operation_digest, approval.revision, outcome.optionId === 'allow-once' ? 'approve' : 'deny');
                     await outbox.flush(socket, c.id);
                 };
@@ -314,7 +324,7 @@ export async function acp(state, options = {}) {
                     void update(c.id, {
                         sessionUpdate: started && fresh ? 'tool_call' : 'tool_call_update',
                         toolCallId: p.tool_call_id,
-                        title: p.tool ?? 'Tool',
+                        title: p.tool ? toolTitle(p.tool, p.input) : 'Tool',
                         ...(started
                             ? {
                                 kind: p.kind ?? toolMetadata(p.tool ?? '', p.input).kind,
@@ -323,6 +333,9 @@ export async function acp(state, options = {}) {
                             : {}),
                         status: started ? 'in_progress' : p.failed ? 'failed' : 'completed',
                         ...(started && p.input ? { rawInput: p.input } : {}),
+                        ...(!started && p.output
+                            ? { content: [{ type: 'content', content: { type: 'text', text: p.output } }] }
+                            : {}),
                         ...(p.parent_tool_call_id
                             ? { _meta: { 'salaam.dev/parentToolCallId': p.parent_tool_call_id } }
                             : {}),
@@ -331,6 +344,10 @@ export async function acp(state, options = {}) {
                     });
                 }
             }
+            if (event.kind.startsWith('work_task.'))
+                void sendPlan(c).catch((error) => {
+                    c.failed = error;
+                });
             if ([
                 'inbox.changed',
                 'inbox.resolved',
@@ -432,6 +449,8 @@ export async function acp(state, options = {}) {
             if (wantsCancellations)
                 await cancellationReceipts(c);
             await approvals(c, view);
+            // The plan is visible before any step runs.
+            await sendPlan(c, view.work_task ?? null);
             watch(c);
         }
         catch (error) {
@@ -773,3 +792,18 @@ export async function acp(state, options = {}) {
         }
     }
 }
+/** A launcher-profile daemon's state belongs to root; its ACP clients keep their own
+ * journal and outbox in the caller's state home, keyed by the daemon state path. */
+export function acpClientState(state, env = process.env) {
+    let own = false;
+    try {
+        own = statSync(state).uid === process.getuid?.();
+    }
+    catch { }
+    if (own)
+        return state;
+    const home = env.XDG_STATE_HOME || join(env.HOME ?? '/nonexistent', '.local/state');
+    const dir = join(home, 'salaam/acp-clients', createHash('sha256').update(state).digest('hex').slice(0, 32));
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}

package/dist/src/agent-profiles.js

@@ -154,6 +154,51 @@ export class AgentProfiles {
             throw new ServiceError('not_found', 'Agent profile not found', 404);
         return profile;
     }
+    /**
+     * The task critic's grant (item 8): always the built-in salaam/reviewer, never another profile,
+     * with no facts. It is granted under the work admission, not by an operator controller, and
+     * only while the caller's authorize holds (the admitted plan declares a critic). The reviewer
+     * reads only the immutable snapshot it is given and can only report findings.
+     */
+    async admitCritic(session, request, authorize) {
+        const profileId = 'salaam/reviewer';
+        const profile = this.inspect(session, profileId);
+        const expectedDigest = digest(profile);
+        const input = { kind: 'critic-admit', session, profileId, expectedDigest };
+        const saved = this.store.cachedRequest('task-critic', request, input);
+        if (saved)
+            return saved;
+        if (!BUILTIN_PROFILES.some((p) => p.id === profileId && digest(p) === expectedDigest))
+            throw new ServiceError('profile_changed', 'The critic must be the built-in reviewer');
+        const prepared = await this.prepareRoute(this.route, session);
+        return this.store.request('task-critic', request, input, () => {
+            authorize();
+            const grant = {
+                schema_version: 1,
+                id: randomUUID(),
+                owner_session: session,
+                profile,
+                profile_digest: expectedDigest,
+                route: prepared.route,
+                output_cap: prepared.output_cap,
+                facts: [],
+            };
+            this.store.db
+                .prepare('INSERT INTO agent_grants(id,owner_session,profile_id,document,digest,state) VALUES (?,?,?,?,?,?)')
+                .run(grant.id, session, profileId, canonical(grant), digest(grant), 'active');
+            this.store.db
+                .prepare('INSERT OR IGNORE INTO worker_profiles(id,revision,digest,document) VALUES (?,?,?,?)')
+                .run(profile.id, profile.revision, expectedDigest, canonical(profile));
+            this.store.event(session, 'agent.admitted', {
+                grant_id: grant.id,
+                profile_id: profileId,
+                profile_digest: expectedDigest,
+                route: prepared.route,
+                critic: true,
+            });
+            return grant;
+        });
+    }
     async admit(session, request, profileId, expectedDigest, factIds, controller) {
         const input = { kind: 'agent-admit', session, profileId, expectedDigest, factIds };
         const saved = this.store.cachedRequest('local-operator', request, input);