@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/src/session-pick.ts

@@ -0,0 +1,102 @@
+import { typedText } from './shell-passthrough.js';
+import { statSync } from 'node:fs';
+import { OFFLINE_ROUTE } from './provider-config.js';
+
+/** How `salaam code` opens a folder: continue its latest session (the default), start a new
+ * coding session, or pick one from the list. */
+export type CodeStart = 'continue' | 'new' | 'resume';
+
+export function parseCodeStart(flags: string[]): CodeStart {
+  const chosen = (['continue', 'new', 'resume'] as const).filter((f) => flags.includes('--' + f));
+  if (chosen.length > 1) throw new Error('Choose one of --continue, --new or --resume.');
+  return chosen[0] ?? 'continue';
+}
+
+const folder = (path: string) => (path.length > 1 ? path.replace(/\/+$/, '') : path);
+
+/** The most recently created session in this folder; sessions come oldest first. */
+export function latestSessionFor(
+  sessions: readonly { id: string; cwd: string }[],
+  cwd: string,
+): string | undefined {
+  const want = folder(cwd);
+  return [...sessions].reverse().find((s) => folder(s.cwd) === want)?.id;
+}
+
+/** Whether a new `salaam code` session should use Anthropic: only when nothing was chosen, the
+ * running service defaults to offline (as a TUI-started one does) and a key is stored. */
+export function deskUsesAnthropic(
+  chosen: boolean,
+  serviceProvider: string | undefined,
+  hasAnthropicKey: boolean,
+): boolean {
+  return (
+    !chosen &&
+    (serviceProvider ?? OFFLINE_ROUTE.provider) === OFFLINE_ROUTE.provider &&
+    hasAnthropicKey
+  );
+}
+
+/** `salaam -c` and `salaam --continue` are short for `salaam code --continue`. */
+export function continueArgs(args: readonly string[]): string[] | undefined {
+  if (args[0] !== '-c' && args[0] !== '--continue') return;
+  return ['code', '--continue', ...args.slice(1)];
+}
+
+interface PickerSession {
+  id: string;
+  cwd: string;
+  last_active_at?: string;
+}
+const activeAt = (s: { last_active_at?: string }) =>
+  s.last_active_at ? Date.parse(s.last_active_at) : -Infinity;
+
+/** This folder's sessions first, then every other one; newest first within each. */
+export function pickerOrder<T extends PickerSession>(sessions: readonly T[], cwd: string): T[] {
+  const want = folder(cwd);
+  const newest = (a: T, b: T) => activeAt(b) - activeAt(a);
+  const here = sessions.filter((s) => folder(s.cwd) === want).sort(newest);
+  return [...here, ...sessions.filter((s) => folder(s.cwd) !== want).sort(newest)];
+}
+
+export function relativeTime(at: string | undefined, now = Date.now()): string {
+  if (!at) return '';
+  const s = Math.max(0, (now - Date.parse(at)) / 1000);
+  if (s < 60) return 'just now';
+  if (s < 3600) return `${Math.floor(s / 60)} min ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)} h ago`;
+  if (s < 2 * 86400) return 'yesterday';
+  return `${Math.floor(s / 86400)} days ago`;
+}
+
+/** One picker row: what you last asked (one short line), when, and where. */
+export function sessionDescription(
+  s: { cwd: string; state: string; last_prompt?: string; last_active_at?: string },
+  now = Date.now(),
+): string {
+  const prompt = s.last_prompt?.replace(/\s+/g, ' ').trim();
+  const quoted = prompt ? `“${prompt.length > 60 ? prompt.slice(0, 59) + '…' : prompt}”` : '';
+  return [quoted || s.state, relativeTime(s.last_active_at, now), s.cwd]
+    .filter(Boolean)
+    .join(' · ');
+}
+
+/** What the picker shows for a desk session: its newest prompt (at most 200 characters) and when
+ * its transcript last changed. Board and station sessions get nothing extra. */
+export function pickerSummary(
+  session: { id: string; capabilities: string[]; pi_session_file: string | null },
+  store: { lastPrompt(id: string): string | null },
+): { last_prompt?: string; last_active_at?: string } {
+  if (!session.capabilities.includes('local-coding-reviewed')) return {};
+  const prompt = store.lastPrompt(session.id);
+  let at: string | undefined;
+  try {
+    if (session.pi_session_file) at = statSync(session.pi_session_file).mtime.toISOString();
+  } catch {
+    /* no transcript yet */
+  }
+  return {
+    ...(prompt ? { last_prompt: typedText(prompt).slice(0, 200) } : {}),
+    ...(at ? { last_active_at: at } : {}),
+  };
+}

package/src/shell-passthrough.ts

@@ -0,0 +1,38 @@
+/**
+ * `!command` in a desk session (trial polish #12, 2026-10-31). The terminal never runs the command
+ * itself: it asks the model to run exactly that text through salaam_local. The service reads the
+ * same fixed prompt back from the turn's submission and binds the turn to the typed command, so a
+ * model that runs anything else is refused, whatever the session's mode.
+ */
+const LEAD = 'I want to run this shell command myself. Run exactly this command with salaam_local';
+
+export function shellPassthrough(text: string): string | undefined {
+  const t = text.trim();
+  if (!t.startsWith('!') || t.startsWith('!!')) return undefined;
+  const command = t.slice(1).trim();
+  if (command === '' || command.includes('\n') || command.includes('```')) return undefined;
+  return [
+    LEAD,
+    '(action "command"), unchanged: no edits, no extra flags, no other commands. Then show me its',
+    'output and exit status, and do nothing else unless I ask.',
+    '',
+    '```sh',
+    command,
+    '```',
+  ].join('\n');
+}
+
+/** The command a turn's prompt binds it to, when the prompt is exactly a `!command` request. */
+export function boundShellCommand(prompt: string): string | undefined {
+  if (!prompt.startsWith(LEAD + '\n')) return undefined;
+  const lines = prompt.split('\n');
+  if (lines.length !== 7 || lines[4] !== '```sh' || lines[6] !== '```') return undefined;
+  const command = lines[5]!;
+  return shellPassthrough('!' + command) === prompt ? command : undefined;
+}
+
+/** What the person typed, for display: `! COMMAND` for a `!command` prompt, else the text. */
+export function typedText(prompt: string): string {
+  const command = boundShellCommand(prompt);
+  return command === undefined ? prompt : '! ' + command;
+}

package/src/station-checkpoints.ts

@@ -0,0 +1,183 @@
+import type { Store } from './store.js';
+import type { WorkTask } from './task-work.js';
+import { digest, ServiceError } from './protocol.js';
+
+/**
+ * Checkpoints of a station task, derived from its own recorded writes (item 11). Each completed
+ * step ends at a checkpoint: the tree after that step's last returned station patch. A file's
+ * content at a checkpoint is known only from the run's own patches; a file that existed before
+ * the run and was first written after the checkpoint has no recorded earlier bytes, so it is
+ * "unknown" there and cannot be restored. Read-only: nothing here changes the workspace.
+ */
+export interface StationCheckpoint {
+  id: string;
+  step_id: string;
+  step_key: string;
+  tree_digest: string;
+  at: number; // the last patch call rowid at the checkpoint (0: before any write)
+  files_changed: string[];
+}
+type Patch = {
+  rowid: number;
+  path: string;
+  content: string | null;
+  expected_hash: string | null;
+  before_tree: string;
+  tree: string;
+  sha256: string | null;
+};
+export type FileAtCheckpoint =
+  { state: 'content'; content: string } | { state: 'absent' } | { state: 'unknown' };
+/** A file as the workspace holds it now, read through the protected helper's closed verbs. */
+export type FileNow =
+  | { state: 'content'; content: string; sha256: string }
+  | { state: 'absent' }
+  | { state: 'unreadable' };
+/** The live workspace: its tree digest now, and each file's bytes now. */
+export interface LiveTree {
+  tree: string;
+  file(path: string): Promise<FileNow>;
+}
+
+export class StationCheckpoints {
+  constructor(private readonly store: Store) {}
+  private patches(session: string): Patch[] {
+    return this.store.db
+      .prepare(
+        "SELECT rowid,args_json,result_json,attempt_id FROM station_calls WHERE session_id=? AND kind='patch' AND state='returned' ORDER BY rowid",
+      )
+      .all(session)
+      .map((r) => {
+        const args = JSON.parse(String(r.args_json)),
+          result = JSON.parse(String(r.result_json));
+        return {
+          rowid: Number(r.rowid),
+          path: String(args.path),
+          content: typeof args.content === 'string' ? args.content : null,
+          expected_hash: typeof args.expected_hash === 'string' ? args.expected_hash : null,
+          before_tree: String(result.before_tree_digest),
+          tree: String(result.tree_digest),
+          sha256: typeof result.sha256 === 'string' ? result.sha256 : null,
+          attempt: String(r.attempt_id),
+        } as Patch & { attempt: string };
+      });
+  }
+  list(task: WorkTask): StationCheckpoint[] {
+    const patches = this.patches(task.session_id) as (Patch & { attempt: string })[];
+    const attemptsOf = (step: string) =>
+      new Set(
+        this.store.db
+          .prepare('SELECT attempt_id FROM task_step_attempts WHERE step_id=?')
+          .all(step)
+          .map((r) => String(r.attempt_id)),
+      );
+    const out: StationCheckpoint[] = [];
+    let at = 0,
+      tree = patches[0]?.before_tree ?? '';
+    for (const step of task.steps.filter((s) => s.state === 'completed')) {
+      const mine = patches.filter((p) => attemptsOf(step.id).has(p.attempt));
+      if (mine.length) {
+        at = Math.max(at, ...mine.map((p) => p.rowid));
+        tree = patches.find((p) => p.rowid === at)!.tree;
+      }
+      out.push({
+        id: digest({ task: task.id, plan_revision: task.plan_revision, step: step.id, at, tree }),
+        step_id: step.id,
+        step_key: step.key,
+        tree_digest: tree,
+        at,
+        files_changed: [...new Set(mine.map((p) => p.path))].sort(),
+      });
+    }
+    return out;
+  }
+  get(task: WorkTask, id: string): StationCheckpoint {
+    const found = this.list(task).find((c) => c.id === id);
+    if (!found) throw new ServiceError('not_found', 'No such checkpoint for this task', 404);
+    return found;
+  }
+  /** A path's content at a checkpoint, from the run's own patches only. */
+  fileAt(task: WorkTask, at: number, path: string): FileAtCheckpoint {
+    const patches = this.patches(task.session_id).filter((p) => p.path === path);
+    const before = patches.filter((p) => p.rowid <= at).at(-1);
+    if (before)
+      return before.content === null
+        ? { state: 'absent' }
+        : { state: 'content', content: before.content };
+    const first = patches.find((p) => p.rowid > at);
+    return first && first.expected_hash === null ? { state: 'absent' } : { state: 'unknown' };
+  }
+  /**
+   * What restoring this checkpoint would do, against the LIVE workspace (never the run's own
+   * receipts alone): every path this run wrote is read as it is now, so a change made outside the
+   * run since (an edit, a deletion, a file put back) shows as what the restore would undo. The
+   * restore digest binds the live tree, so a restore refuses a workspace that moved after review.
+   * Files this run never wrote are left as they are; `drift` says when the tree moved outside it.
+   */
+  async diff(task: WorkTask, id: string, live: LiveTree) {
+    const checkpoint = this.get(task, id);
+    const patches = this.patches(task.session_id);
+    const recorded = patches.at(-1)?.tree ?? checkpoint.tree_digest;
+    const paths = [...new Set(patches.map((p) => p.path))].sort();
+    const files = [];
+    for (const path of paths) {
+      const now = await live.file(path);
+      const then = this.fileAt(task, checkpoint.at, path);
+      const change =
+        now.state === 'unreadable' || then.state === 'unknown'
+          ? ('not_restorable' as const)
+          : then.state === 'absent'
+            ? now.state === 'absent'
+              ? ('unchanged' as const)
+              : ('delete' as const)
+            : now.state === 'absent'
+              ? ('bring_back' as const)
+              : now.content === then.content
+                ? ('unchanged' as const)
+                : ('revert' as const);
+      files.push({
+        path,
+        current: now.state === 'content' ? now.content : null,
+        current_state: now.state,
+        at_checkpoint: then,
+        change,
+        expected_hash: now.state === 'content' ? now.sha256 : null,
+      });
+    }
+    const shown = files.filter((f) => f.change !== 'unchanged');
+    const restore_digest = digest({
+      task: task.id,
+      plan_revision: task.plan_revision,
+      checkpoint: checkpoint.id,
+      checkpoint_tree: checkpoint.tree_digest,
+      recorded_tree: recorded,
+      current_tree: live.tree,
+      files: shown.map((f) => ({
+        path: f.path,
+        change: f.change,
+        target: f.at_checkpoint,
+        expected: f.expected_hash,
+      })),
+    });
+    return {
+      checkpoint,
+      current_tree: live.tree,
+      recorded_tree: recorded,
+      drift: live.tree !== recorded,
+      restore_digest,
+      files: shown.map(({ expected_hash: _, ...f }) => f),
+      writes: shown
+        .filter((f) => ['revert', 'delete', 'bring_back'].includes(f.change))
+        .map((f) => ({
+          path: f.path,
+          content: f.at_checkpoint.state === 'content' ? f.at_checkpoint.content : null,
+          expected_hash: f.expected_hash,
+        })),
+    };
+  }
+  /** Item 11b: exactly what a restore of this checkpoint writes, and the digest that binds it. */
+  async restorePlan(task: WorkTask, id: string, live: LiveTree) {
+    const { restore_digest, current_tree, writes, checkpoint } = await this.diff(task, id, live);
+    return { restore_digest, current_tree, writes, checkpoint };
+  }
+}

package/src/station-config.ts

@@ -28,6 +28,8 @@ export interface StationConfig {
   runtime_root: string;
   runtime_fingerprint: string;
   runtime_image_digest: string;
+  /** OS user the agent's local tools run as (salaam --tools-user). Optional. */
+  tools_user?: string;
 }
 const hashShape = /^[a-f0-9]{64}$/;
 export const stationHash = (bytes: Uint8Array): string =>
@@ -149,9 +151,15 @@ export function readStationConfig(
 ): StationConfig {
   try {
     const v = object(JSON.parse(stationPrivateFile(path, 16384).toString('utf8')));
+    const keys = Object.keys(v)
+      .filter((k) => k !== 'tools_user')
+      .sort()
+      .join(',');
     if (
-      Object.keys(v).sort().join(',') !==
+      keys !==
         'files,kind,runtime_fingerprint,runtime_image_digest,runtime_root,systemctl,systemd_run,version,workspace,workspace_identity' ||
+      (Object.hasOwn(v, 'tools_user') &&
+        (typeof v.tools_user !== 'string' || !/^[a-z_][a-z0-9_-]{0,31}$/.test(v.tools_user))) ||
       v.version !== 1 ||
       v.kind !== 'linux-systemd-station-v1' ||
       v.workspace !== workspace ||
@@ -174,6 +182,7 @@ export function readStationConfig(
       runtime_root: v.runtime_root,
       runtime_fingerprint: v.runtime_fingerprint,
       runtime_image_digest: v.runtime_image_digest,
+      ...(Object.hasOwn(v, 'tools_user') ? { tools_user: v.tools_user as string } : {}),
     };
     if (
       workspace

package/src/station-files.ts

@@ -22,9 +22,14 @@ export function stationFileResult(
   };
   const fields = keys[String(request.action)];
   if (!fields) bad();
+  // A new file's missing parent directories, created beneath the root, are part of its effect.
+  const extra =
+    request.action === 'patch' && 'created_directories' in v ? ['created_directories'] : [];
   if (
     Object.keys(v).sort().join(',') !==
-      ['version', 'ok', 'tree_digest', 'files', 'root_identity', ...fields!].sort().join(',') ||
+      ['version', 'ok', 'tree_digest', 'files', 'root_identity', ...fields!, ...extra]
+        .sort()
+        .join(',') ||
     v.version !== 1 ||
     v.ok !== true ||
     v.root_identity !== request.root_identity ||
@@ -47,6 +52,8 @@ export function stationFileResult(
     )
       bad();
   }
+  if (extra.length && !createdParents(String(request.path), v.created_directories, request.content))
+    bad();
   if (request.action === 'patch') {
     if (
       v.path !== request.path ||
@@ -102,3 +109,15 @@ export function stationFileResult(
   }
   return v;
 }
+
+/** The created directories must be a non-empty, in-order run of the path's own
+ * ancestors ending at its parent: each one beneath the last, nothing else. Only a
+ * new file creates them. */
+function createdParents(path: string, dirs: unknown, content: unknown): boolean {
+  if (typeof content !== 'string' || !Array.isArray(dirs) || dirs.length === 0) return false;
+  const parts = path.split('/');
+  if (parts.length < 2 || parts.some((p) => p === '' || p === '.' || p === '..')) return false;
+  const ancestors = parts.slice(0, -1).map((_, i) => parts.slice(0, i + 1).join('/'));
+  const tail = ancestors.slice(ancestors.length - dirs.length);
+  return dirs.length <= ancestors.length && dirs.every((d, i) => d === tail[i]);
+}

package/src/station-task-verification.ts

@@ -1,3 +1,4 @@
+import { requiredChecks } from './task-policy.js';
 import type { Store } from './store.js';
 import type { TaskWork, WorkTask } from './task-work.js';
 import type { TaskVerification, CheckReceipt } from './task-verification.js';
@@ -163,7 +164,7 @@ export class StationTaskVerification {
   private async dispatchOwned(id: string): Promise<void> {
     const receipt = this.verification.get(id),
       task = this.tasks.get(receipt.task_id);
-    const configured = task.acceptance.find((c) => c.key === receipt.check_key);
+    const configured = requiredChecks(task).find((c) => c.key === receipt.check_key);
     if (!configured || configured.cwd !== '.') this.fail();
     const binding = this.station.ready(task.session_id);
     const validate = (inspection?: string) => {
@@ -265,6 +266,7 @@ export class StationTaskVerification {
       objective: task.objective,
       constraints: task.constraints,
       acceptance: task.acceptance,
+      ...(task.completion_gate ? { completion_gate: task.completion_gate } : {}),
       deliverables: task.deliverables,
       limits: task.limits,
       steps: task.steps.map(({ key, title, instruction, depends_on, checks }) => ({
@@ -300,7 +302,7 @@ export class StationTaskVerification {
     });
   }
   private matches(check: CheckReceipt, task: WorkTask, call: StationCall): void {
-    const configured = task.acceptance.find((c) => c.key === check.check_key);
+    const configured = requiredChecks(task).find((c) => c.key === check.check_key);
     const args = JSON.parse(call.args_json);
     if (
       check.task_id !== task.id ||
@@ -526,7 +528,8 @@ export class StationTaskVerification {
         result.root_identity !== this.station.config.workspace_identity
       )
         this.fail();
-      deliverables.push({ path, sha256: result.sha256 });
+      // The verified bytes travel with the digest; completion keeps them as an artifact.
+      deliverables.push({ path, sha256: result.sha256, content: result.content });
     }
     const final = await this.observe(
       evidence[0]!.call_id,