@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/src/project-instructions.ts

@@ -0,0 +1,229 @@
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, sep } from 'node:path';
+import { canonical, digest, textDigest } from './protocol.js';
+import type { Artifacts } from './artifacts.js';
+import type { Store } from './store.js';
+
+/** One file's bound, and the bound on everything loaded together. */
+export const INSTRUCTION_FILE_BYTES = 32 * 1024;
+export const INSTRUCTION_TOTAL_BYTES = 64 * 1024;
+/** AGENTS.md is the shared convention; CLAUDE.md is read only where a directory has no AGENTS.md. */
+const NAMES = ['AGENTS.md', 'CLAUDE.md'];
+
+export interface InstructionFile {
+  scope: 'user' | 'project';
+  /** Shown to people: relative to the session folder, or ~/… for the user file. */
+  path: string;
+  sha256: string;
+  bytes: number;
+  text: string;
+}
+export interface InstructionSkip {
+  path: string;
+  reason: string;
+}
+export interface InstructionsSummary {
+  digest: string;
+  revision: number;
+  files: Omit<InstructionFile, 'text'>[];
+  skipped: InstructionSkip[];
+}
+interface InstructionsDocument {
+  version: 1;
+  files: InstructionFile[];
+  skipped: InstructionSkip[];
+}
+
+/** The user-level instructions file: $XDG_CONFIG_HOME/salaam/AGENTS.md, else ~/.config/salaam/AGENTS.md. */
+export function userInstructionsPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'salaam', 'AGENTS.md');
+}
+
+function repositoryRoot(cwd: string): string | null {
+  let dir = cwd;
+  for (let i = 0; i < 64; i++) {
+    if (existsSync(join(dir, '.git'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Project instructions for an interactive session, the way other harnesses read them: the
+ * user-level file, then AGENTS.md (or CLAUDE.md) in every directory from the repository root down
+ * to the session folder. Bounded, regular UTF-8 files only; anything skipped says why.
+ */
+export function discoverInstructions(
+  cwd: string,
+  userFile: string | null = userInstructionsPath(),
+): { files: InstructionFile[]; skipped: InstructionSkip[] } {
+  const files: InstructionFile[] = [];
+  const skipped: InstructionSkip[] = [];
+  let total = 0;
+  /** Returns whether the file exists (so CLAUDE.md is not read beside an AGENTS.md). */
+  const take = (scope: InstructionFile['scope'], abs: string, shown: string): boolean => {
+    let st;
+    try {
+      st = lstatSync(abs);
+    } catch {
+      return false;
+    }
+    if (!st.isFile()) {
+      skipped.push({
+        path: shown,
+        reason: st.isSymbolicLink() ? 'symbolic links are not loaded' : 'not a regular file',
+      });
+      return true;
+    }
+    if (st.size > INSTRUCTION_FILE_BYTES) {
+      skipped.push({ path: shown, reason: `larger than ${INSTRUCTION_FILE_BYTES / 1024} KiB` });
+      return true;
+    }
+    const bytes = readFileSync(abs);
+    const text = bytes.toString('utf8');
+    if (!Buffer.from(text).equals(bytes) || text.includes('\0')) {
+      skipped.push({ path: shown, reason: 'not UTF-8 text' });
+      return true;
+    }
+    if (total + bytes.length > INSTRUCTION_TOTAL_BYTES) {
+      skipped.push({
+        path: shown,
+        reason: `instructions together exceed ${INSTRUCTION_TOTAL_BYTES / 1024} KiB`,
+      });
+      return true;
+    }
+    total += bytes.length;
+    files.push({ scope, path: shown, sha256: textDigest(text), bytes: bytes.length, text });
+    return true;
+  };
+  if (userFile) {
+    const home = homedir();
+    take(
+      'user',
+      userFile,
+      userFile.startsWith(home + sep) ? '~/' + relative(home, userFile) : userFile,
+    );
+  }
+  const root = repositoryRoot(cwd) ?? cwd;
+  const dirs = [root];
+  for (const part of relative(root, cwd).split(sep).filter(Boolean))
+    dirs.push(join(dirs.at(-1)!, part));
+  for (const dir of dirs)
+    for (const name of NAMES) {
+      const abs = join(dir, name);
+      if (take('project', abs, relative(cwd, abs) || name)) break;
+    }
+  return { files, skipped };
+}
+
+/**
+ * Interactive sessions load project instructions automatically and reload them when they change.
+ * Each loaded set is kept as an artifact and announced by an `instructions.loaded` event with its
+ * digest, so a turn's guidance is traceable to exact bytes. Strict work (board, AgentPod, child
+ * workers) never uses this: it keeps explicitly reviewed context only.
+ */
+export class ProjectInstructions {
+  private readonly loaded = new Map<string, { digest: string; document: InstructionsDocument }>();
+  constructor(
+    readonly store: Store,
+    readonly artifacts: Artifacts,
+    readonly userFile: string | null = userInstructionsPath(),
+  ) {}
+  applies(id: string): boolean {
+    const has = (table: string) =>
+      !!this.store.db
+        .prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?")
+        .get(table);
+    return (
+      this.store.localWorkspace(id) &&
+      !(
+        has('child_tasks') &&
+        this.store.db.prepare('SELECT 1 FROM child_tasks WHERE child_session=?').get(id)
+      ) &&
+      !(
+        has('agentpod_admissions') &&
+        this.store.db.prepare('SELECT 1 FROM agentpod_admissions WHERE session_id=?').get(id)
+      )
+    );
+  }
+  private latest(id: string): (InstructionsSummary & { artifact_id: string }) | null {
+    const row = this.store.db
+      .prepare(
+        "SELECT seq,payload FROM events WHERE session_id=? AND kind='instructions.loaded' ORDER BY seq DESC LIMIT 1",
+      )
+      .get(id) as { seq: number; payload: string } | undefined;
+    if (!row) return null;
+    const p = JSON.parse(row.payload);
+    return { ...p, revision: p.revision ?? 1 };
+  }
+  /** Discover the current files; record a new revision only when they changed. */
+  refresh(id: string): InstructionsSummary | null {
+    if (!this.applies(id)) return null;
+    const found = discoverInstructions(this.store.session(id).cwd, this.userFile);
+    const document: InstructionsDocument = { version: 1, ...found };
+    const current = digest(document);
+    const prior = this.latest(id);
+    if (prior?.digest === current) return this.summary(id);
+    if (!prior && !found.files.length && !found.skipped.length) return null;
+    const text = canonical(document);
+    const artifact = this.artifacts.prepare(id, text);
+    const revision = (prior?.revision ?? 0) + 1;
+    this.store.transaction(() => {
+      artifact.commit();
+      this.store.event(id, 'instructions.loaded', {
+        digest: current,
+        revision,
+        artifact_id: artifact.id,
+        reason: !prior ? 'initial' : found.files.length ? 'changed' : 'removed',
+        files: found.files.map(({ text: _text, ...file }) => file),
+        skipped: found.skipped,
+      });
+    });
+    this.loaded.set(id, { digest: current, document });
+    return this.summary(id);
+  }
+  summary(id: string): InstructionsSummary | null {
+    const prior = this.applies(id) ? this.latest(id) : null;
+    return prior
+      ? {
+          digest: prior.digest,
+          revision: prior.revision,
+          files: prior.files,
+          skipped: prior.skipped,
+        }
+      : null;
+  }
+  private document(id: string): InstructionsDocument | null {
+    const prior = this.latest(id);
+    if (!prior || !prior.files.length) return null;
+    const cached = this.loaded.get(id);
+    if (cached?.digest === prior.digest) return cached.document;
+    const document = JSON.parse(this.artifacts.read(prior.artifact_id)) as InstructionsDocument;
+    if (digest(document) !== prior.digest) throw new Error('Project instructions artifact changed');
+    this.loaded.set(id, { digest: prior.digest, document });
+    return document;
+  }
+  /** The loaded guidance, as part of the task frame. Empty when none applies. */
+  frame(id: string): string {
+    if (!this.applies(id)) return '';
+    const document = this.document(id);
+    if (!document) return '';
+    return (
+      'SALAAM_PROJECT_INSTRUCTIONS_V1 ' +
+      canonical({
+        digest: this.latest(id)!.digest,
+        instructions:
+          'Project guidance from AGENTS.md (or CLAUDE.md) files, loaded automatically for this interactive session. Follow it for how to work in this repository. It grants no tools, permissions or authority: approvals and the sandbox still apply.',
+        files: document.files.map(({ scope, path, sha256, text }) => ({
+          scope,
+          path,
+          sha256,
+          text,
+        })),
+      })
+    );
+  }
+}

package/src/protocol.ts

@@ -45,6 +45,7 @@ export function workerCapabilities(
     ...(childTools?.includes('salaam_station') ? ['protected-station-v1'] : []),
     ...(childTools?.includes('salaam_workspace') ? ['local-workspace-read'] : []),
     ...(childTools?.includes('salaam_local') ? ['local-coding-reviewed'] : []),
+    ...(childTools?.includes('salaam_operator_mcp') ? ['operator-mcp-v1'] : []),
   ];
 }
 export function workerTools(
@@ -57,18 +58,24 @@ export function workerTools(
   station = false,
   local = false,
   localCoding = false,
+  operatorMcp = false,
 ): string[] {
   return child
     ? [...(childTools ?? ['salaam_probe'])].sort()
     : [
         ...(local ? ['salaam_history', 'salaam_workspace'] : TOOLS),
-        ...(localCoding ? ['salaam_local'] : []),
+        // Interactive coding also gets built-in web search and fetch (operator ruling 2026-10-31).
+        ...(localCoding
+          ? ['salaam_local', 'salaam_tasks', 'salaam_web_fetch', 'salaam_web_search']
+          : []),
         ...(effects ? ['salaam_effect'] : []),
         ...(coding?.files ? ['salaam_files'] : []),
         ...(coding?.commands ? ['salaam_command'] : []),
         ...(mcp ? ['salaam_mcp'] : []),
         ...(toolkit ? ['salaam_toolkit'] : []),
-        ...(station ? ['salaam_station'] : []),
+        // salaam_board: read-only board reads, served by the hub (operator ruling 2026-10-28).
+        ...(station ? ['salaam_board', 'salaam_station'] : []),
+        ...(operatorMcp ? ['salaam_operator_mcp'] : []),
       ].sort();
 }
 export interface ChildTask {
@@ -89,6 +96,7 @@ export interface ChildTask {
 }
 export type WorkerState = 'stopped' | 'starting' | 'ready' | 'unhealthy' | 'exited';
 export interface Session {
+  mcp_servers?: import('./operator-mcp.js').McpServerProvenance[];
   id: string;
   cwd: string;
   revision: number;
@@ -102,6 +110,11 @@ export interface Session {
   capabilities: string[];
   seq: number;
   provider_route?: ProviderRoute;
+  /** Interactive sessions: the AGENTS.md set loaded automatically (project-instructions.ts). */
+  project_instructions?: import('./project-instructions.js').InstructionsSummary;
+  /** Desk sessions in the session list: the newest prompt and when the transcript last changed. */
+  last_prompt?: string;
+  last_active_at?: string;
   provider_capabilities?: {
     output_token_cap: boolean;
     durable_tasks: boolean;
@@ -174,7 +187,16 @@ export interface SessionSnapshot extends Session {
   control: ControlView;
   attempts: (Attempt & { result_truncated: boolean })[];
   submissions: (Submission & { text_truncated: boolean })[];
-  messages: { entry_id: string; role: string; text: string; truncated: boolean }[];
+  messages: {
+    entry_id: string;
+    role: string;
+    text: string;
+    truncated: boolean;
+    /** Tool calls made just before this message, oldest first. */
+    tool_calls?: string[];
+  }[];
+  /** Tool calls after the last message, e.g. a turn still running. */
+  trailing_tool_calls?: string[];
   history_truncated: boolean;
   approvals: Approval[];
   operations: Operation[];

package/src/rate-limit-retries.ts

@@ -0,0 +1,69 @@
+import type { Store } from './store.js';
+
+/**
+ * A provider 429 on a step is retried as a fresh admitted attempt of that step, after a backoff,
+ * up to RATE_LIMIT_MAX_FAILURES rate-limited attempts in all. Each retry is a new attempt with its
+ * own admission and budget charge, never a replay of the refused request. After the last one the
+ * task stops with RATE_LIMIT_STOP, a block the stopped-run recovery can prove and settle.
+ */
+export const RATE_LIMIT_MAX_FAILURES = 3;
+export const RATE_LIMIT_BACKOFF_MS = [30_000, 60_000, 120_000];
+export const RATE_LIMIT_STOP = 'Provider rate limit reached';
+
+type Step = { id: string; state: string; attempt_id: string | null };
+export type RetryDecision =
+  | { action: 'none' }
+  | { action: 'wait' }
+  | { action: 'retry'; step: string; n: number }
+  | { action: 'stop'; reason: string };
+
+export class RateLimitRetries {
+  constructor(private readonly store: Store) {
+    store.db.exec(`CREATE TABLE IF NOT EXISTS task_rate_limits(
+      task_id TEXT NOT NULL,
+      step_id TEXT NOT NULL,
+      attempt_id TEXT NOT NULL UNIQUE,
+      failures INTEGER NOT NULL,
+      retry_at INTEGER NOT NULL,
+      PRIMARY KEY(task_id, step_id, failures))`);
+  }
+  /** Whether this attempt failed because the provider rate-limited it. */
+  rateLimited(attempt: string): boolean {
+    const row = this.store.db.prepare('SELECT state,outcome FROM attempts WHERE id=?').get(attempt);
+    if (!row || row.state !== 'failed' || typeof row.outcome !== 'string') return false;
+    try {
+      return JSON.parse(row.outcome)?.failure?.kind === 'rate_limit';
+    } catch {
+      return false;
+    }
+  }
+  /** What the driver does with a task whose step failed. Records each rate-limited attempt once. */
+  decide(task: { id: string; steps: Step[] }, now = Date.now()): RetryDecision {
+    const failed = task.steps.filter((s) =>
+      ['failed', 'interrupted', 'cancelled'].includes(s.state),
+    );
+    const step = failed[0];
+    if (failed.length !== 1 || !step || step.state !== 'failed' || !step.attempt_id)
+      return { action: 'none' };
+    if (!this.rateLimited(step.attempt_id)) return { action: 'none' };
+    let row = this.store.db
+      .prepare('SELECT failures,retry_at FROM task_rate_limits WHERE attempt_id=?')
+      .get(step.attempt_id) as { failures: number; retry_at: number } | undefined;
+    if (!row) {
+      const prior = Number(
+        this.store.db
+          .prepare('SELECT count(*) AS n FROM task_rate_limits WHERE task_id=? AND step_id=?')
+          .get(task.id, step.id)!.n,
+      );
+      const failures = prior + 1;
+      const retry_at = now + (RATE_LIMIT_BACKOFF_MS[failures - 1] ?? RATE_LIMIT_BACKOFF_MS.at(-1)!);
+      this.store.db
+        .prepare('INSERT INTO task_rate_limits VALUES (?,?,?,?,?)')
+        .run(task.id, step.id, step.attempt_id, failures, retry_at);
+      row = { failures, retry_at };
+    }
+    if (row.failures >= RATE_LIMIT_MAX_FAILURES) return { action: 'stop', reason: RATE_LIMIT_STOP };
+    if (now < row.retry_at) return { action: 'wait' };
+    return { action: 'retry', step: step.id, n: row.failures };
+  }
+}

package/src/recurring-work.ts

@@ -165,6 +165,7 @@ export class RecurringWork {
           checks,
         })),
         acceptance: task.acceptance,
+        ...(task.completion_gate ? { completion_gate: task.completion_gate } : {}),
         deliverables: task.deliverables,
         limits: task.limits,
       };

package/src/repository-snapshots.ts

@@ -71,9 +71,12 @@ export class RepositorySnapshots {
     const tree = this.tree(binding),
       action = string(args.action, 'action', 32),
       offset = integer(args.offset ?? 0, 'offset');
+    // A snapshot-only reviewer (the critic) has no workspace; leave those fields out rather than
+    // undefined, since every read result is digested into the journal (card_5dcbd5d9be5c4183).
     const identity = {
-      workspace_id: binding.workspace?.id,
-      revision: binding.workspace?.revision,
+      ...(binding.workspace
+        ? { workspace_id: binding.workspace.id, revision: binding.workspace.revision }
+        : {}),
       digest: binding.repository!.digest,
       artifact_id: binding.repository!.artifact_id,
     };

package/src/run-grants.ts

@@ -0,0 +1,107 @@
+import { randomUUID } from 'node:crypto';
+import type { Store } from './store.js';
+
+/**
+ * "Approve for this run" (approval scopes, item B). A person answering one workspace-write approval
+ * may cover the rest of the run's writes inside the run's own directory. Each later write is still
+ * prepared, digest-bound and journaled as its own operation; the grant only answers its approval.
+ *
+ * A grant covers a station patch only when it is a write (never a delete: every delete asks), its
+ * path lies under `runs/<runId>/`, and no segment is empty, `.`, `..` or hidden (a leading dot).
+ * It is bound to the session, task, plan revision and binding digest it was given under, and ends
+ * when any of them changes or the task settles. Anything outside it asks as before.
+ */
+export interface RunGrant {
+  id: string;
+  session_id: string;
+  task_id: string;
+  plan_revision: number;
+  binding_digest: string;
+  path_prefix: string;
+  approval_id: string;
+  granted_by: string;
+  created_at: string;
+  revoked_at: string | null;
+}
+
+export const runGrantPrefix = (runId: string): string | null =>
+  /^run_[A-Za-z0-9]{6,}$/.test(runId) ? `runs/${runId}/` : null;
+
+/** Whether a station patch's arguments are a write a grant for this prefix may answer. */
+export function runGrantCovers(prefix: string, args: Record<string, unknown>): boolean {
+  if (args.action !== 'patch' || typeof args.content !== 'string') return false;
+  const path = args.path;
+  if (typeof path !== 'string' || !path.startsWith(prefix) || path.length === prefix.length)
+    return false;
+  return path.split('/').every((s) => s !== '' && s !== '.' && s !== '..' && !s.startsWith('.'));
+}
+
+export class RunGrants {
+  constructor(private readonly store: Store) {
+    store.db.exec(`CREATE TABLE IF NOT EXISTS run_grants(
+      id TEXT PRIMARY KEY NOT NULL,
+      session_id TEXT NOT NULL,
+      task_id TEXT NOT NULL,
+      plan_revision INTEGER NOT NULL,
+      binding_digest TEXT NOT NULL,
+      path_prefix TEXT NOT NULL,
+      approval_id TEXT NOT NULL UNIQUE,
+      granted_by TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      revoked_at TEXT)`);
+  }
+  /** Within the caller's transaction, next to the decision that granted it. Idempotent per approval. */
+  createInTransaction(input: Omit<RunGrant, 'id' | 'created_at' | 'revoked_at'>): RunGrant {
+    if (!this.store.db.isTransaction) throw Error('A run grant is created with its decision');
+    const saved = this.store.db
+      .prepare('SELECT * FROM run_grants WHERE approval_id=?')
+      .get(input.approval_id) as RunGrant | undefined;
+    if (saved) return saved;
+    const grant: RunGrant = {
+      ...input,
+      id: randomUUID(),
+      created_at: new Date().toISOString(),
+      revoked_at: null,
+    };
+    this.store.db
+      .prepare('INSERT INTO run_grants VALUES (?,?,?,?,?,?,?,?,?,?)')
+      .run(
+        grant.id,
+        grant.session_id,
+        grant.task_id,
+        grant.plan_revision,
+        grant.binding_digest,
+        grant.path_prefix,
+        grant.approval_id,
+        grant.granted_by,
+        grant.created_at,
+        null,
+      );
+    this.store.event(grant.session_id, 'run_grant.created', {
+      grant_id: grant.id,
+      approval_id: grant.approval_id,
+      task_id: grant.task_id,
+      path_prefix: grant.path_prefix,
+    });
+    return grant;
+  }
+  /** The live grant for exactly this session, task, plan revision and binding, if any. */
+  active(scope: {
+    session_id: string;
+    task_id: string;
+    plan_revision: number;
+    binding_digest: string;
+    task_state: string;
+  }): RunGrant | null {
+    if (['cancelled', 'succeeded', 'succeeded_with_exception'].includes(scope.task_state))
+      return null;
+    return (
+      (this.store.db
+        .prepare(
+          'SELECT * FROM run_grants WHERE session_id=? AND task_id=? AND plan_revision=? AND binding_digest=? AND revoked_at IS NULL ORDER BY created_at DESC LIMIT 1',
+        )
+        .get(scope.session_id, scope.task_id, scope.plan_revision, scope.binding_digest) as
+        RunGrant | undefined) ?? null
+    );
+  }
+}