@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/src/board-reads.ts

@@ -0,0 +1,148 @@
+import { randomUUID } from 'node:crypto';
+import type { Store } from './store.js';
+import { ServiceError } from './protocol.js';
+
+/**
+ * Board reads (operator ruling 2026-10-28, option iii). While it works, the agent may read its own
+ * card, its card's runs, and search or open library items, the way an agent with board tools does.
+ * Salaam holds no SuperPipeline or SuperLibrary credential: it records the read, the hub sees it in
+ * work status, serves it with its own clients, and answers. A read names no card, board or
+ * credential; the hub decides scope from the run it is serving. Read-only: nothing here asks for
+ * approval, and nothing a read returns authorizes anything.
+ */
+export type BoardReadAction = 'card' | 'attempts' | 'library_search' | 'library_get';
+export interface BoardRead {
+  id: string;
+  action: BoardReadAction;
+  args: Record<string, string>;
+  state: 'pending' | 'answered';
+  ok?: boolean;
+  text?: string;
+  error?: string;
+}
+const ITEM = /^itm_[0-9a-f]{16}$/;
+/** The most a hub answer may carry back to the agent. */
+export const BOARD_READ_MAX_BYTES = 256 * 1024;
+
+const bad = (message: string) => new ServiceError('invalid_board_read', message, 400);
+
+/** Closed arguments per action; anything else is refused. */
+export function boardReadArgs(input: Record<string, unknown>): {
+  action: BoardReadAction;
+  args: Record<string, string>;
+} {
+  const { action, ...rest } = input;
+  const keys = Object.keys(rest).filter((k) => rest[k] !== undefined);
+  if (action === 'card' || action === 'attempts') {
+    if (keys.length) throw bad(`${action} takes no arguments: it is always this run's own card`);
+    return { action, args: {} };
+  }
+  if (action === 'library_search') {
+    const q = rest.query;
+    if (keys.join() !== 'query' || typeof q !== 'string' || !q.trim() || q.length > 500)
+      throw bad('library_search takes one query of 1 to 500 characters');
+    return { action, args: { query: q.trim() } };
+  }
+  if (action === 'library_get') {
+    const id = rest.item_id;
+    if (keys.join() !== 'item_id' || typeof id !== 'string' || !ITEM.test(id))
+      throw bad('library_get takes one item_id (itm_ and 16 hex characters)');
+    return { action, args: { item_id: id } };
+  }
+  throw bad('Board reads are card, attempts, library_search or library_get');
+}
+
+export class BoardReads {
+  constructor(private readonly store: Store) {
+    store.db.exec(`CREATE TABLE IF NOT EXISTS board_reads(
+      id TEXT PRIMARY KEY, session_id TEXT NOT NULL, tool_call_id TEXT NOT NULL, action TEXT NOT NULL,
+      args TEXT NOT NULL, state TEXT NOT NULL, ok INTEGER, text TEXT, error TEXT,
+      created_at TEXT NOT NULL, answered_at TEXT, UNIQUE(session_id, tool_call_id))`);
+  }
+  private view(row: Record<string, unknown>): BoardRead {
+    return {
+      id: String(row.id),
+      action: String(row.action) as BoardReadAction,
+      args: JSON.parse(String(row.args)) as Record<string, string>,
+      state: String(row.state) as BoardRead['state'],
+      ...(row.state === 'answered'
+        ? {
+            ok: row.ok === 1,
+            ...(row.text !== null ? { text: String(row.text) } : {}),
+            ...(row.error !== null ? { error: String(row.error) } : {}),
+          }
+        : {}),
+    };
+  }
+  /** Record a read for this session, once per tool call. */
+  request(session: string, toolCallId: string, input: Record<string, unknown>): BoardRead {
+    const { action, args } = boardReadArgs(input);
+    const existing = this.store.db
+      .prepare('SELECT * FROM board_reads WHERE session_id=? AND tool_call_id=?')
+      .get(session, toolCallId);
+    if (existing) return this.view(existing);
+    const id = randomUUID();
+    this.store.db
+      .prepare(
+        "INSERT INTO board_reads(id,session_id,tool_call_id,action,args,state,created_at) VALUES (?,?,?,?,?,'pending',?)",
+      )
+      .run(id, session, toolCallId, action, JSON.stringify(args), new Date().toISOString());
+    return this.get(session, id);
+  }
+  get(session: string, id: string): BoardRead {
+    const row = this.store.db
+      .prepare('SELECT * FROM board_reads WHERE id=? AND session_id=?')
+      .get(id, session);
+    if (!row) throw new ServiceError('board_read_not_found', 'No such board read', 404);
+    return this.view(row);
+  }
+  /** What the hub should serve for this session, oldest first. */
+  pending(
+    session: string,
+  ): { id: string; action: BoardReadAction; args: Record<string, string> }[] {
+    return this.store.db
+      .prepare(
+        "SELECT * FROM board_reads WHERE session_id=? AND state='pending' ORDER BY rowid LIMIT 8",
+      )
+      .all(session)
+      .map((r) => {
+        const v = this.view(r);
+        return { id: v.id, action: v.action, args: v.args };
+      });
+  }
+  /** The hub's answer: once, for a read of this session, bounded. */
+  answer(session: string, value: unknown): BoardRead {
+    const a = (value ?? {}) as Record<string, unknown>;
+    const keys = Object.keys(a).sort().join();
+    const ok = a.ok === true;
+    if (
+      typeof a.read_id !== 'string' ||
+      (ok
+        ? keys !== 'ok,read_id,text' || typeof a.text !== 'string'
+        : keys !== 'error,ok,read_id' || a.ok !== false || typeof a.error !== 'string')
+    )
+      throw bad('Closed board read answer required');
+    const body = ok ? (a.text as string) : (a.error as string);
+    if (Buffer.byteLength(body) > (ok ? BOARD_READ_MAX_BYTES : 2048))
+      throw bad('Board read answer too large');
+    const done = this.store.db
+      .prepare(
+        "UPDATE board_reads SET state='answered',ok=?,text=?,error=?,answered_at=? WHERE id=? AND session_id=? AND state='pending'",
+      )
+      .run(
+        ok ? 1 : 0,
+        ok ? body : null,
+        ok ? null : body,
+        new Date().toISOString(),
+        a.read_id,
+        session,
+      );
+    if (done.changes !== 1)
+      throw new ServiceError(
+        'board_read_settled',
+        'That board read is not pending for this run',
+        409,
+      );
+    return this.get(session, a.read_id);
+  }
+}

package/src/children.ts

@@ -7,6 +7,8 @@ import type { RepositorySnapshots } from './repository-snapshots.js';
 import type { WorkerWorkspaces } from './worker-workspaces.js';
 import type { ExternalRuntime } from './external-runtime.js';
 import type { ExternalWork } from './external-work.js';
+import type { AgentGrant } from './agent-profiles.js';
+import type { WorkspaceTree } from './workspaces.js';
 
 export class ChildWork {
   external?: ExternalWork;
@@ -222,6 +224,116 @@ export class ChildWork {
       this.start(child);
     return child;
   }
+  /**
+   * The task critic (item 8): a reviewer child over an immutable snapshot of the verified
+   * deliverables. No parent attempt is active at completion, so it is linked to the task's last
+   * step attempt and charged to its own bounded budget, never to an attempt's reservation. The
+   * grant must be the built-in reviewer; the child can read the snapshot and report findings only.
+   */
+  spawnCritic(
+    parent: string,
+    parentAttempt: string,
+    step: string,
+    prompt: string,
+    budget: number,
+    grant: AgentGrant,
+    snapshot: WorkspaceTree,
+  ): ChildTask {
+    if (!Number.isSafeInteger(budget) || budget < 1 || budget > 8)
+      throw new ServiceError('invalid_budget', 'Critic request budget must be 1–8');
+    if (grant.profile.id !== 'salaam/reviewer' || grant.owner_session !== parent)
+      throw new ServiceError('authority_denied', 'The critic must be the built-in reviewer');
+    if (!Object.keys(snapshot).length)
+      throw new ServiceError(
+        'invalid_child',
+        'A critic needs a snapshot of the verified deliverables',
+      );
+    if (!prompt.trim() || prompt.length > 32768)
+      throw new ServiceError('invalid_child', 'Invalid critic prompt');
+    const authority = [...grant.profile.tools].sort();
+    const input = digest({
+      prompt,
+      budget,
+      critic: grant.profile_digest,
+      snapshot: digest(snapshot),
+    });
+    const prepare = () => {
+      const old = this.store.db
+        .prepare('SELECT * FROM child_tasks WHERE parent_session=? AND step_key=?')
+        .get(parent, step) as unknown as ChildTask | undefined;
+      if (old) {
+        if (old.input_digest !== input)
+          throw new ServiceError('spawn_conflict', 'Critic step already binds a different review');
+        return { child: old, fresh: false };
+      }
+      if (this.paused) throw new ServiceError('stopping', 'Child dispatch is stopping');
+      this.store.execution.assert(parent);
+      if (this.activeCount() >= 8)
+        throw new ServiceError('child_limit', 'Daemon worker admission limit reached');
+      const effectivePrompt = `${grant.profile.prompt}\n\nGoal:\n${prompt}`;
+      const id = randomUUID(),
+        session = randomUUID(),
+        submission = randomUUID(),
+        childAttempt = randomUUID();
+      this.store.db
+        .prepare('INSERT INTO sessions(id,cwd,pi_session_id) VALUES (?,?,?)')
+        .run(session, this.store.session(parent).cwd, session);
+      this.store.db
+        .prepare('INSERT INTO submissions(id,session_id,text,attempt_id) VALUES (?,?,?,?)')
+        .run(submission, session, effectivePrompt, childAttempt);
+      this.store.db
+        .prepare(
+          "INSERT INTO attempts(id,session_id,submission_id,state) VALUES (?,?,?,'accepted')",
+        )
+        .run(childAttempt, session, submission);
+      this.store.db
+        .prepare(
+          "INSERT INTO child_tasks(id,parent_session,parent_attempt,step_key,input_digest,child_session,child_attempt,authority,budget,state) VALUES (?,?,?,?,?,?,?,?,?,'accepted')",
+        )
+        .run(
+          id,
+          parent,
+          parentAttempt,
+          step,
+          input,
+          session,
+          childAttempt,
+          JSON.stringify(authority),
+          budget,
+        );
+      this.store.taskChildReserve?.(parent, childAttempt, budget);
+      this.store.usage.budget(childAttempt, budget);
+      const artifact = this.artifacts.prepare(session, effectivePrompt);
+      artifact.commit();
+      // The reviewed snapshot is the verified bytes; its base is empty, so its diff is all of it.
+      const current = this.artifacts.prepare(session, JSON.stringify(snapshot)),
+        base = this.artifacts.prepare(session, JSON.stringify({}));
+      current.commit();
+      base.commit();
+      this.store.workerBoundary.freeze(this.owned(session)!, artifact.id, false, grant, {
+        artifact_id: current.id,
+        base_artifact: base.id,
+        digest: digest(snapshot),
+      });
+      this.store.event(session, 'session.created', { parent_session: parent, child_id: id });
+      this.store.event(session, 'submission.accepted', {
+        attempt_id: childAttempt,
+        submission_id: submission,
+      });
+      this.store.event(parent, 'child.spawned', {
+        child_id: id,
+        child_session: session,
+        step_key: step,
+        budget,
+        authority,
+        critic: true,
+      });
+      return { child: this.inspect(parent, id), fresh: true };
+    };
+    const { child, fresh } = this.store.transaction(prepare);
+    if (fresh) this.start(child);
+    return child;
+  }
   activeCount(parent?: string): number {
     return Number(
       this.store.db

package/src/cli-help.ts

@@ -53,12 +53,22 @@ salaam agents revoke GRANT_ID --session SESSION_ID
 Profiles are data in .salaam/agents/*.md with JSON front matter and a prompt body.
 Inspect the effective tools and digest before admission. Project definitions cannot
 grant themselves authority. Mutations accept --request-id and --takeover.`,
+  code: `salaam code [--continue | --new | --resume] [--cwd DIR] [--takeover]
+salaam here   (the same)
+salaam -c     (short for salaam code --continue)
+
+Work in this folder with one command: start the service if it is not running, then continue
+the folder's latest session (the default), start a new local coding session (--new), or pick
+any session from a list (--resume), this folder's sessions first. No session id needed.
+SALAAM_TERMINAL_STATUS=off stops the window-title and Herdr status reports.`,
   tui: `salaam tui [--session SESSION_ID] [--observe|--takeover] [--theme night|paper]
            [--cwd DIR] [--coding-root PRIVATE_DIR] [--coding-socket DOCKER_SOCKET]
 
 Bare sal opens the same Salaam terminal interface in a TTY.
-Ctrl+K actions · Ctrl+P sessions · Ctrl+N new · Ctrl+O approvals
-Ctrl+G changes · Ctrl+T commands · Ctrl+E external editor · Ctrl+C detach.
+Ctrl+K (empty composer) or F2 actions · Ctrl+P sessions · Ctrl+N new · Ctrl+O approvals
+Alt+G changes · Ctrl+T commands · Ctrl+G external editor · Ctrl+R history search
+F5 refresh · !command shell · Ctrl+C stops/clears, twice to detach.
+? on an empty composer (or F1) shows the keys for where you are.
 Work continues in the service when the terminal closes.`,
   remote: `salaam remote SSH_HOST [--remote-bin ABSOLUTE_PATH] [--state REMOTE_DIR]
               [--session SESSION_ID] [--observe|--takeover] [--theme night|paper]
@@ -88,9 +98,11 @@ Run the M9.1 boundary proof on a pre-provisioned local Linux Docker engine.
 Only disposable fixtures are mounted. The pinned image must already be present.
 No coding tools are enabled. A failed/unavailable backend exits nonzero.
 Cleanup reconciles the saved proof run without replaying commands.`,
-  acp: `salaam acp [--state DIR] [--coding]
+  acp: `salaam acp [--state DIR] [--local | --coding]
 
 Run the ACP v1 stdio client adapter against an already running Salaam service.
+--local creates your desk session in the editor's project folder, the same as
+salaam in a terminal there: modes, approvals with diffs, rules and /rewind.
 --coding creates owned coding sessions; the service must have --coding-root.
 Loading an existing session preserves its original tool authority.`,
   artifacts: `salaam artifacts put SESSION_ID --text TEXT [--request-id ID] [--takeover]
@@ -103,6 +115,10 @@ salaam host inspect --manifest host-manifest.json
 salaam host unit --manifest host-manifest.json --platform systemd|launchd
 salaam host run --manifest host-manifest.json
 salaam host start --manifest host-manifest.json
+salaam host unit-start --unit salaam-host@STATION.service --state DIR
+salaam host bind --organization ORG --node NODE --station-key KEY --workspace DIR \
+  --tools-user USER --files HELPER --runtime-root DIR --runtime-image-digest sha256:… \
+  [--operator-group GROUP] [--provider P --model M] [--mcp-config FILE] [--persona FILE] [--managed-mcp-config FILE] [--dir DIR] [--state DIR]
 
 Config requires absolute state, coding_root and coding_socket paths; optional
 provider, model, max_output_tokens and workspace_id. Planning probes the existing
@@ -116,7 +132,18 @@ For a bound AgentPod host, use mode="agentpod", state and agentpod_config instea
 of coding_root/coding_socket. This profile enables no station tools. The private
 manifest pins Node, CLI, source/build, Pi, provider and authority pins. Invoke the
 canonical Node executable explicitly. host start waits for matching live health
-and safely coalesces concurrent callers; it never installs or upgrades packages.`,
+and safely coalesces concurrent callers; it never installs or upgrades packages.
+
+Launcher profile (Linux): root plans a strict work host with operator_group set.
+A root-owned unit runs host run from that root-held manifest. The daemon lets that
+one group traverse its state and use operator.sock. An unprivileged member then
+runs host unit-start, which asks systemd to start the named salaam-host@ unit and
+prints the receipt the running daemon reports. It cannot choose what root runs.
+
+host bind (root, Linux) writes everything a launcher-profile station needs into
+--dir (default /etc/salaam/stations/<key>): agentpod-pins.json, station-config.json
+(with tools_user), host-config.json, and host.json from host plan. It is
+idempotent: the same inputs leave the files and the manifest digest unchanged.`,
   schedules: `salaam schedules create TASK_ID --name NAME --revision N --max-steps N [--schedule FILE] [--compact]
 salaam schedules list [--offset N]
 salaam schedules inspect JOB_ID
@@ -208,10 +235,32 @@ Status prints metadata only. Existing Anthropic keys remain compatible.`,
                      [--coding-root PRIVATE_DIR] [--coding-socket DOCKER_SOCKET]
                      [--harness-config OWNER_ONLY_FILE] [--a2a-config OWNER_ONLY_FILE]
                      [--a2a-listen-config OWNER_ONLY_FILE]
-                     [--agentpod-config OWNER_ONLY_FILE]
+                     [--agentpod-config OWNER_ONLY_FILE] [--mcp-config FILE]
+                     [--tools-user USER]
+                     [--local-sandbox read-only|workspace-write|full-access]
+                     [--local-sandbox-read PATH,…|toolchain] [--unsandboxed-commands allow]
 salaam service status
 salaam service stop
 
+--tools-user USER (or SALAAM_TOOLS_USER) runs local agent commands and edits as
+USER through sudo -n -u USER on Linux. Without it, tools share the provider
+credential's OS user and start prints a warning.
+
+Local commands (session create --local-coding) run under the host OS sandbox:
+bubblewrap on Linux, Seatbelt on macOS. --local-sandbox (or SALAAM_LOCAL_SANDBOX)
+picks the level: workspace-write (default) writes only inside the workspace,
+read-only writes nothing, full-access runs commands unsandboxed with network. A
+sandboxed command has no network and cannot read outside the workspace and the
+system; --local-sandbox-read (or SALAAM_LOCAL_SANDBOX_READ) lists read-only paths
+it may also read, comma-separated, and "toolchain" adds this host's node prefix,
+~/.npm, ~/.nvm, ~/.cargo, ~/.rustup, ~/go and ~/.gitconfig where present. Home
+itself and credential directories (~/.ssh, ~/.aws, keychains …) are refused. On
+macOS commands get the real git from the active developer dir. A host with no
+usable sandbox refuses commands unless --unsandboxed-commands allow.
+
+Without --agentpod-config, start binds to ~/.config/salaam/agentpod-pins.json
+($XDG_CONFIG_HOME/salaam) when that file exists.
+
 The default provider is offline. Anthropic defaults to claude-sonnet-5-5.
 Other providers require --model; use salaam providers list and salaam models list PROVIDER.
 Start with --foreground for process-supervisor use; otherwise the service detaches.
@@ -219,7 +268,8 @@ An AgentPod daemon requires node-bound admissions and a fresh authority lease.
 Keep its private state outside the pinned workspace. Coding, external runtimes,
 effect connectors and managed MCP are unavailable in this profile.`,
   session: `salaam session create [--cwd DIR] [--request-id ID] [--coding | --local | --local-coding]
-  --local-coding allows reviewed edits and native commands (no OS sandbox)
+  --local-coding allows reviewed edits and native commands, each under the host OS sandbox
+                 (see salaam help service for levels and read paths)
   --local allows bounded local file inspection; optionally select --provider ID --model ID
 salaam session list
 salaam session inspect SESSION_ID
@@ -272,6 +322,7 @@ const globalOptions = `Global options:
   -h, --help     Show help without starting a service or model request.
   -V, --version  Show the installed version.`;
 export function cliHelp(group?: string): string | undefined {
+  if (group === 'here') group = 'code';
   if (group) return commands[group] ? `${commands[group]}\n\n${globalOptions}` : undefined;
   return `Salaam — persistent coding sessions
 
@@ -279,6 +330,7 @@ Usage: salaam <command> [options]
        sal <command> [options]
 
 Commands:
+  code          Work in this folder: continue its session or start one (also: here, -c)
   tui           Open the Salaam terminal interface (also bare sal)
   remote        Open the same session over SSH
   providers     List pinned Pi providers and capabilities
@@ -286,6 +338,7 @@ Commands:
   auth          Configure provider credentials or OAuth
   service       Start, inspect or stop the session service
   session       Create, inspect, submit, resume or cancel work
+  mcp           Declare operator MCP servers (add, list, rm)
   attach        Open an interactive terminal on a session
   acp           Connect an editor over ACP v1 stdio
   approvals     Inspect, approve or deny managed operations
@@ -356,6 +409,7 @@ const valueOptions = new Set([
   '--a2a-config',
   '--agentpod-config',
   '--a2a-listen-config',
+  '--tools-user',
   '--assignment',
   '--peer',
   '--peer-client',