@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -6,6 +6,92 @@ are forward-only: keep a stopped-daemon backup before upgrading.
 
 ## [Unreleased]
 
+## [0.0.5] - 2026-11-01
+
+Salaam as a desk-side coding driver: an interactive terminal session in your own checkout, the same
+session in Zed, and the approvals, sandbox and recovery to work in it daily.
+
+### Added
+
+- Modes: Shift+Tab cycles review → accept edits → auto. `/full-access` runs commands without the
+  OS sandbox and asks only for dangerous ones; `/yolo` (typed confirmation, host setting
+  `allow_yolo_sessions`) asks for nothing and records everything.
+- Approvals: Enter approves once, approve for the session or always in this repo, deny with a
+  reason that reaches the agent, and rules in `/permissions`. Each prompt says why it asks.
+- Danger check: a parser-based check of commands (it unwraps `sudo`, `env`, `xargs`, `sh -c` and
+  more; anything unreadable is dangerous), plus an optional small-model classifier that can only
+  make a command ask (`/classifier`, off by default, hosts can pin or forbid it).
+- Run one command outside the sandbox: a command may ask, saying why. It always asks except in
+  YOLO; auto mode and repo rules never approve it.
+- Listening: a command you approve to listen may serve a dev server; macOS cannot limit it to
+  localhost, and the approval says so. Refused on Linux.
+- Pushes and pull requests always ask, except in YOLO or your own rule.
+- Rewind to any turn (files, conversation or both) and a per-file review of changes.
+- `@` mentions attach files and images; background commands (`/jobs`) and desk notifications.
+- Git helpers `/commit`, `/branch`, `/pr`, `/diff`; your own slash commands; hooks (a repo's hooks
+  run only after you trust them).
+- Terminal: compact tool lines with Ctrl+X for the full transcript, a progress line with Esc to
+  stop, Ctrl+C to clear, Ctrl+R history, Ctrl+G editor, readline keys, `!command`, `salaam -c`,
+  a session picker, the `?` key sheet and the window title.
+- Zed and other ACP editors: `salaam acp --local` opens your desk session in the project folder,
+  with the mode picker, approvals that show diffs and offer Allow for this session, finished edits
+  as diffs, and `/rewind` for files.
+
+### Fixed
+
+- Salaam starts in Zed when you have MCP servers configured: the desk session ignores the editor's
+  own MCP servers instead of refusing them.
+- Tool calls show in the turn they belong to, and the full transcript shows command output as text.
+- Usage counts cached input and the whole cost.
+- Choosing a model that needs a new session opens one with that model instead of the old one.
+- A failed session shows its error; leftover background commands are stopped after a restart on
+  macOS.
+
+## [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-desk.js

@@ -0,0 +1,140 @@
+import { isAbsolute, join } from 'node:path';
+import { relativeTime } from './session-pick.js';
+const MODES = [
+    { id: 'review', name: 'Review', description: 'Asks before every edit and command' },
+    {
+        id: 'accept-edits',
+        name: 'Accept edits',
+        description: 'Edits in the project apply at once; commands ask',
+    },
+    {
+        id: 'auto',
+        name: 'Auto',
+        description: 'Project edits and sandboxed commands run at once; the rest asks',
+    },
+    {
+        id: 'full-access',
+        name: 'Full access',
+        description: 'No OS sandbox; only dangerous commands ask',
+    },
+];
+const YOLO = {
+    id: 'yolo',
+    name: 'YOLO',
+    description: 'No approvals at all and no sandbox. Turn it off in the terminal with /yolo',
+};
+export function deskMode(policy) {
+    if (policy.access === 'yolo')
+        return 'yolo';
+    if (policy.access === 'full')
+        return 'full-access';
+    return policy.mode;
+}
+/** `modes` and the matching `configOptions`, kept in step (ACP asks agents to send both). */
+export function modeState(p) {
+    const current = deskMode(p.policy);
+    const list = MODES.filter((m) => m.id !== 'full-access' || p.full_access_allowed !== false);
+    if (current === 'yolo')
+        list.push(YOLO);
+    else if (!list.some((m) => m.id === current))
+        list.unshift({ id: current, name: current, description: 'Set in the terminal' });
+    return {
+        modes: { currentModeId: current, availableModes: list },
+        configOptions: [
+            {
+                id: 'mode',
+                name: 'Mode',
+                category: 'mode',
+                type: 'select',
+                currentValue: current,
+                options: list.map((m) => ({ value: m.id, name: m.name, description: m.description })),
+            },
+        ],
+    };
+}
+/** The policy a chosen mode asks for. Picking a mode turns full access off; full access runs in
+ * auto, so edits and commands go ahead and only dangerous commands ask. */
+export function policyFor(mode, allowed = {}) {
+    if (mode === 'review' || mode === 'accept-edits' || mode === 'auto')
+        return { mode, paths: [] };
+    if (mode === 'full-access') {
+        if (allowed.full === false)
+            throw new Error('The operator does not allow full access on this host. Commands stay in the OS sandbox.');
+        return { mode: 'auto', paths: [], access: 'full' };
+    }
+    if (mode === 'yolo')
+        throw new Error('YOLO is turned on only in the terminal: run /yolo there and type yolo.');
+    throw new Error('Unknown mode ' + JSON.stringify(mode));
+}
+export const FULL_ACCESS_WARNING = 'Later commands in this session run WITHOUT the OS sandbox: they can read and change any file your user can, and reach the network directly. They run without asking, except commands the danger check calls dangerous (force pushes, deletes, publishing, credentials, anything it cannot read), which still ask and say why. Pick another mode to turn it off.';
+/** ACP diff content for an edit request: absolute paths, null old text for a new file. */
+export function editDiffs(root, edits) {
+    return edits.map((e) => ({
+        type: 'diff',
+        path: isAbsolute(e.path) ? e.path : join(root, e.path),
+        oldText: e.before,
+        newText: e.after,
+    }));
+}
+/** Why an approval asks, from the reviewed text and the mode, in one line. */
+export function askReason(value, mode) {
+    const danger = /^Dangerous \(([^)]+)\): (.*)$/m.exec(value);
+    if (danger)
+        return `Asks because this command is dangerous (${danger[1]}): ${danger[2]}`;
+    const outside = /^Outside the sandbox: (.*?)\. This one command/m.exec(value);
+    if (outside)
+        return `Asks because it wants to run outside the sandbox: ${outside[1]}`;
+    if (/^Publishes: /m.test(value))
+        return 'Asks because pushing and opening pull requests always ask.';
+    if (/^May listen: /m.test(value))
+        return 'Asks because this command may accept network connections; macOS cannot limit it to localhost.';
+    const edit = /^(---|\+\+\+) /m.test(value) && !/\nCommand:\n/.test(value);
+    if (mode === 'review')
+        return 'Asks because review mode asks before every edit and command.';
+    if (mode === 'accept-edits' && !edit)
+        return 'Asks because accept edits still asks before commands.';
+    if (mode === 'auto')
+        return edit
+            ? 'Asks because this edit is outside what auto mode approves on its own.'
+            : 'Asks because auto mode approves only sandboxed commands it can read.';
+    return 'Asks because nothing approves this request on its own.';
+}
+export const DESK_COMMANDS = [
+    {
+        name: 'rewind',
+        description: 'Put the files back as they were before an earlier turn',
+        input: { hint: 'turn number (leave empty to list turns)' },
+    },
+];
+/** `/rewind`, `/rewind 3`. Anything else is not a desk command and goes to the model. */
+export function parseDeskCommand(text) {
+    const match = /^\/rewind(?:\s+(\S+))?\s*$/.exec(text.trim());
+    if (!match)
+        return null;
+    if (match[1] === undefined)
+        return { command: 'rewind' };
+    const turn = Number(match[1]);
+    if (!Number.isSafeInteger(turn) || turn < 1)
+        throw new Error('Use /rewind with a turn number from the list, e.g. /rewind 3.');
+    return { command: 'rewind', turn };
+}
+export function checkpointList(points, now = Date.now()) {
+    if (!points.length)
+        return 'No turns to go back to yet.';
+    return [
+        'Turns you can go back to (the files as they were before each turn ran):',
+        '',
+        ...points
+            .slice()
+            .reverse()
+            .map((p) => `- Turn ${p.turn} · ${relativeTime(p.at, now)} · ${p.text.split('\n')[0].slice(0, 80)}`),
+        '',
+        'Run /rewind followed by a turn number to review and restore its files.',
+    ].join('\n');
+}
+/** Zed cannot follow a rewind into a new session, so from the editor only files are restored. */
+export const REWIND_CHOICES = [
+    { optionId: 'files', name: 'Restore files', kind: 'allow_once' },
+    { optionId: 'cancel', name: 'Cancel', kind: 'reject_once' },
+];
+export const CONVERSATION_REWIND_NOTE = 'To go back in the conversation too, run /rewind in the terminal (salaam -c opens this session): it continues in a new session.';

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,33 @@ 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)
-                    ? 'read'
-                    : ['salaam_history', 'inspect_child', 'consume_child_result'].includes(name)
+    const kind = name === 'salaam_board'
+        ? 'read'
+        : name === 'salaam_local' && ['edit', 'command'].includes(action)
+            ? action === 'edit'
+                ? 'edit'
+                : 'execute'
+            : name === 'salaam_command' || (name === 'salaam_station' && action === 'check')
+                ? ['start', 'cancel', 'check'].includes(action)
+                    ? 'execute'
+                    : ['status', 'logs'].includes(action)
                         ? 'read'
-                        : 'other';
+                        : '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'
+                            : ['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 +427,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,
+            };
+        }),
+    };
+}