@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/src/task-work.ts

@@ -98,6 +98,80 @@ export class TaskWork {
       .prepare('UPDATE task_runtime SET remaining_steps=remaining_steps-1 WHERE task_id=?')
       .run(task.id);
   }
+  /** Item 8: re-run the last completed step with the critic's findings added to its instruction,
+   * under its own re-prepared progression grant and a request of its own. */
+  reopenForCritic(
+    taskId: string,
+    stepId: string,
+    round: number,
+    epoch: number,
+    findings: string,
+  ): unknown {
+    const task = this.get(taskId);
+    const step = task.steps.find((s) => s.id === stepId);
+    const grant = this.store.db
+      .prepare(
+        "SELECT id FROM task_grants WHERE task_id=? AND step_id=? AND plan_revision=? AND epoch=? AND state='accepted'",
+      )
+      .get(task.id, stepId, task.plan_revision, epoch) as { id: string } | undefined;
+    if (!grant || !step || step.state !== 'completed' || task.steps.at(-1)?.id !== stepId)
+      throw new ServiceError('task_authority', 'Only the completed last step can be reopened');
+    this.store.transaction(() => {
+      this.store.db.prepare("UPDATE task_steps SET state='pending' WHERE id=?").run(stepId);
+      this.store.db.prepare("UPDATE task_grants SET state='prepared' WHERE id=?").run(grant.id);
+      this.store.event(task.session_id, 'work_task.step_reopened', {
+        task_id: task.id,
+        step_id: stepId,
+        grant_id: grant.id,
+        round,
+        reason: 'Critic requested changes',
+      });
+    });
+    return this.run(
+      task.id,
+      stepId,
+      'task-grant:' + grant.id + ':critic-reopen:' + round,
+      this.get(task.id).revision,
+      step.instruction +
+        '\n\nBefore this work is accepted, a reviewer asked for these changes:\n' +
+        findings,
+      null,
+      null,
+      grant.id,
+    );
+  }
+  /** Re-run a step the provider rate-limited, as a fresh attempt under its own progression grant
+   * (re-prepared, with a request of its own, so it is never a replay of the refused attempt). */
+  retryStep(taskId: string, stepId: string, n: number, epoch: number): unknown {
+    const task = this.get(taskId);
+    const grant = this.store.db
+      .prepare(
+        "SELECT id FROM task_grants WHERE task_id=? AND step_id=? AND plan_revision=? AND epoch=? AND state='accepted'",
+      )
+      .get(task.id, stepId, task.plan_revision, epoch) as { id: string } | undefined;
+    if (!grant || task.steps.find((s) => s.id === stepId)?.state !== 'failed')
+      throw new ServiceError('task_authority', 'No settled grant for this rate-limited step');
+    this.store.transaction(() => {
+      this.store.db.prepare("UPDATE task_grants SET state='prepared' WHERE id=?").run(grant.id);
+      this.store.event(task.session_id, 'work_task.step_retried', {
+        task_id: task.id,
+        step_id: stepId,
+        grant_id: grant.id,
+        retry: n,
+        reason: 'Provider rate limit',
+      });
+    });
+    return this.run(
+      task.id,
+      stepId,
+      'task-grant:' + grant.id + ':rate-limit-retry:' + n,
+      task.revision,
+      null,
+      null,
+      null,
+      grant.id,
+    );
+  }
   advance(grantId: string): unknown {
     const grant = this.store.db.prepare('SELECT * FROM task_grants WHERE id=?').get(grantId) as
       { task_id: string; step_id: string; expected_revision: number } | undefined;
@@ -693,6 +767,7 @@ export class TaskWork {
           objective: task.objective,
           constraints: task.constraints,
           acceptance: task.acceptance,
+          ...(task.completion_gate ? { completion_gate: task.completion_gate } : {}),
           deliverables: task.deliverables,
           limits: task.limits,
           active_step_id: task.steps.find((s) => s.state === 'running')?.id ?? null,

package/src/terminal-status.ts

@@ -0,0 +1,103 @@
+import { execFile } from 'node:child_process';
+
+/**
+ * Salaam tells the terminal what it is doing (trial polish C, 2026-10-31): the window title says
+ * working / needs you, and inside Herdr the pane reports its state through Herdr's documented
+ * `pane report-agent` command (herdrdev/herdr, docs/next/.../add-herdr-support.mdx). Herdr's
+ * docs define no OSC 7501 sequence, so none is sent. SALAAM_TERMINAL_STATUS=off turns both off.
+ * Neither carries prompt text, command text or anything secret: only the state and a short
+ * session name.
+ */
+export type TerminalState = 'idle' | 'working' | 'blocked';
+
+export function terminalState(
+  snapshot: { attempts?: { state: string }[]; approvals?: { state: string }[] } | undefined,
+): TerminalState {
+  if (!snapshot) return 'idle';
+  if ((snapshot.approvals ?? []).some((a) => a.state === 'pending')) return 'blocked';
+  if (
+    (snapshot.attempts ?? []).some((a) => ['accepted', 'dispatching', 'running'].includes(a.state))
+  )
+    return 'working';
+  return 'idle';
+}
+
+export function titleFor(state: TerminalState, name: string | undefined): string {
+  // eslint-disable-next-line no-control-regex
+  const clean = name
+    ?.replace(/[\x00-\x1f\x7f-\x9f]/g, '')
+    .trim()
+    .slice(0, 32);
+  if (!clean) return 'Salaam';
+  const words = state === 'blocked' ? 'needs you' : state === 'working' ? 'working' : 'idle';
+  return `Salaam · ${clean} · ${words}`;
+}
+
+export function statusEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.SALAAM_TERMINAL_STATUS !== 'off';
+}
+
+type Run = (bin: string, args: string[], done: () => void) => void;
+const run: Run = (bin, args, done) => {
+  // Short timeout, failures ignored: Herdr must never slow Salaam down.
+  execFile(bin, args, { timeout: 2000, windowsHide: true }, () => done());
+};
+
+/** Reports to Herdr only inside a Herdr pane; one report in flight, newest state wins. */
+export class HerdrReporter {
+  readonly enabled: boolean;
+  private seq = 0;
+  private busy = false;
+  private queued?: string[];
+  private last?: string;
+  constructor(
+    private readonly env: NodeJS.ProcessEnv = process.env,
+    private readonly exec: Run = run,
+    private readonly now: () => number = Date.now,
+  ) {
+    this.enabled = !!(env.HERDR_ENV === '1' && env.HERDR_PANE_ID && env.HERDR_BIN_PATH);
+  }
+  private nextSeq(): string {
+    this.seq = Math.max(this.seq + 1, this.now());
+    return String(this.seq);
+  }
+  private head(verb: string): string[] {
+    return ['pane', verb, this.env.HERDR_PANE_ID!, '--source', 'salaam', '--agent', 'salaam'];
+  }
+  report(state: TerminalState, session: string | undefined): void {
+    if (!this.enabled) return;
+    const key = state + ' ' + (session ?? '');
+    if (key === this.last) return;
+    this.last = key;
+    this.queued = [
+      ...this.head('report-agent'),
+      '--state',
+      state,
+      '--seq',
+      '',
+      ...(state === 'blocked' ? ['--message', 'Waiting for your approval'] : []),
+      ...(session ? ['--agent-session-id', session, '--', 'salaam', '--session', session] : []),
+    ];
+    this.flush();
+  }
+  release(): void {
+    if (!this.enabled) return;
+    this.queued = undefined;
+    this.exec(
+      this.env.HERDR_BIN_PATH!,
+      [...this.head('release-agent'), '--seq', this.nextSeq()],
+      () => {},
+    );
+  }
+  private flush(): void {
+    if (this.busy || !this.queued) return;
+    const args = this.queued;
+    this.queued = undefined;
+    args[args.indexOf('--seq') + 1] = this.nextSeq();
+    this.busy = true;
+    this.exec(this.env.HERDR_BIN_PATH!, args, () => {
+      this.busy = false;
+      this.flush();
+    });
+  }
+}

package/src/tool-identity.ts

@@ -0,0 +1,110 @@
+import { spawnSync } from 'node:child_process';
+import { userInfo } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { ServiceError } from './protocol.js';
+import type { LocalEdit } from './local-edits.js';
+
+/**
+ * The OS identity that agent-initiated local commands and file effects run as.
+ * `service-user` is the single-user default; `tools-user` switches through a
+ * runas-restricted `sudo -n -u <user>` rule so the daemon needs no capability.
+ */
+export interface ToolIdentity {
+  mode: 'service-user' | 'tools-user';
+  user: string;
+  uid: number;
+  /** argv prefix that runs a program as the tool identity; empty for service-user. */
+  prefix: string[];
+  warning: string | null;
+}
+export const sharedUserWarning = (user: string) =>
+  `Tool execution runs as ${user}, the same OS user that holds the provider credential. Set --tools-user to separate them.`;
+
+export function serviceToolIdentity(): ToolIdentity {
+  const user = userInfo().username;
+  return {
+    mode: 'service-user',
+    user,
+    uid: process.getuid?.() ?? -1,
+    prefix: [],
+    warning: sharedUserWarning(user),
+  };
+}
+
+const run = (argv: string[], input?: string) =>
+  spawnSync(argv[0]!, argv.slice(1), {
+    env: { PATH: '/usr/local/bin:/usr/bin:/bin', LANG: 'C' },
+    input,
+    encoding: 'utf8',
+    timeout: 10000,
+    killSignal: 'SIGKILL',
+    maxBuffer: 1 << 20,
+  });
+
+/** Fail closed unless the tools user exists, is reachable without a password, and cannot read state. */
+export function probeToolsUser(
+  user: string,
+  stateDir: string,
+  prefix = ['sudo', '-n', '-u', user, '--'],
+): ToolIdentity {
+  if (!/^[a-z_][a-z0-9_-]{0,31}$/.test(user))
+    throw new Error('--tools-user must be a plain Unix user name');
+  if (process.platform !== 'linux' && prefix[0] === 'sudo')
+    throw new Error('--tools-user is supported on Linux hosts only');
+  const id = run([...prefix, '/usr/bin/id', '-u']);
+  const uid = Number(String(id.stdout).trim());
+  if (id.status !== 0 || !Number.isSafeInteger(uid))
+    throw new Error(
+      `Cannot run as tools user ${user} (sudo -n -u ${user} failed); see docs/security.md host setup`,
+    );
+  if (uid === 0 || uid === process.getuid?.())
+    throw new Error('The tools user must be an unprivileged user distinct from the service user');
+  if (run([...prefix, '/usr/bin/test', '-r', stateDir]).status === 0)
+    throw new Error(`Tools user ${user} can read the Salaam state directory; restrict it to 0700`);
+  return { mode: 'tools-user', user, uid, prefix, warning: null };
+}
+
+export function toolArgv(identity: ToolIdentity, argv: string[]): string[] {
+  return [...identity.prefix, ...argv];
+}
+
+/** Kill a tool process group owned by the tools user; the daemon cannot signal another uid. */
+export function killToolGroup(identity: ToolIdentity, pgid: number): void {
+  if (identity.mode !== 'tools-user' || !Number.isSafeInteger(pgid) || pgid < 2) return;
+  run(toolArgv(identity, ['/bin/kill', '-KILL', '--', '-' + pgid]));
+}
+
+const here = fileURLToPath(import.meta.url);
+/** Source runs (tests) use the built helper; packages ship it beside this file. */
+export const EDIT_HELPER = here.endsWith('.ts')
+  ? join(dirname(here), '..', 'dist/src/local-edit-helper.js')
+  : join(dirname(here), 'local-edit-helper.js');
+
+export interface ToolEdit extends LocalEdit {
+  remove?: boolean;
+}
+/** Apply reviewed edits as the tools user. Reports each applied path; any failure throws. */
+export function applyEditsAsTools(
+  identity: ToolIdentity,
+  root: string,
+  edits: ToolEdit[],
+  applied: (path: string) => void,
+): void {
+  if (!existsSync(EDIT_HELPER)) throw new ServiceError('tool_identity', 'Edit helper is missing');
+  const result = run(
+    toolArgv(identity, [process.execPath, EDIT_HELPER, root]),
+    JSON.stringify(edits),
+  );
+  for (const line of String(result.stdout ?? '').split('\n')) {
+    if (line.startsWith('applied ')) applied(JSON.parse(line.slice(8)) as string);
+  }
+  if (result.status !== 0)
+    throw new ServiceError(
+      'tool_identity',
+      `Edit as ${identity.user} failed: ${String(result.stderr ?? '')
+        .trim()
+        .slice(0, 400)}`,
+    );
+}

package/src/tui-activity.ts

@@ -0,0 +1,133 @@
+import { humanTool, safeText } from './tui-theme.js';
+
+/**
+ * One compact line per tool call in the conversation (trial polish #9): what ran and how it
+ * ended, e.g. `Edit src/x.ts +3 −1` or `Bash npm test ✓ exit 0` with the last output lines.
+ * Built only from the recorded tool activity; it never reads the workspace.
+ */
+export interface ToolLine {
+  state: 'running' | 'finished' | 'failed';
+  label: string;
+  /** The last output lines of a finished command (at most `tail` lines). */
+  tail: string[];
+  /** A command's full output as text, for the transcript; absent when only the raw record exists. */
+  full?: string;
+}
+const lineCount = (text: string) => (text === '' ? 0 : text.replace(/\n$/, '').split('\n').length);
+function short(text: string, max = 60): string {
+  const first = safeText(text).split('\n')[0]!.trim();
+  return first.length > max ? first.slice(0, max - 1) + '…' : first;
+}
+/** The recorded result of a local command: its exit code and output, even from a truncated record. */
+function commandResult(output?: string): { exit?: number | null; text?: string } {
+  if (!output) return {};
+  try {
+    const parsed = JSON.parse(output) as { exit_code?: number | null; output?: string };
+    return { exit: parsed.exit_code, text: parsed.output };
+  } catch {
+    const exit = /"exit_code":(-?\d+|null)/.exec(output)?.[1];
+    return exit === undefined ? {} : { exit: exit === 'null' ? null : Number(exit) };
+  }
+}
+export function toolLine(
+  tool: string,
+  input: string | undefined,
+  finished: { failed?: boolean; output?: string } | undefined,
+  tail = 3,
+): ToolLine {
+  const state = !finished ? 'running' : finished.failed ? 'failed' : 'finished';
+  let args: {
+    action?: string;
+    command?: string;
+    background?: boolean;
+    edits?: {
+      path?: string;
+      content?: string;
+      sha256?: string | null;
+      replacements?: { old: string; new: string }[];
+    }[];
+  } = {};
+  try {
+    args = JSON.parse(input ?? '{}');
+  } catch {}
+  if (tool === 'salaam_local' && args.action === 'edit' && Array.isArray(args.edits)) {
+    let added = 0,
+      removed = 0,
+      created = false;
+    for (const edit of args.edits) {
+      if (edit.replacements?.length)
+        for (const r of edit.replacements) {
+          added += lineCount(r.new);
+          removed += lineCount(r.old);
+        }
+      else if (typeof edit.content === 'string') {
+        added += lineCount(edit.content);
+        if (edit.sha256 === null) created = true;
+      }
+    }
+    const what =
+      args.edits.length === 1
+        ? safeText(String(args.edits[0]!.path ?? ''))
+        : `${args.edits.length} files`;
+    return {
+      state,
+      label: `Edit ${what} +${added} −${removed}${created ? ' (new)' : ''}`,
+      tail: [],
+    };
+  }
+  if (tool === 'salaam_local' && args.action === 'command' && typeof args.command === 'string') {
+    const result = commandResult(finished?.output);
+    const ended =
+      !finished || args.background
+        ? args.background && finished
+          ? ' · background'
+          : ''
+        : result.exit === 0
+          ? ' ✓ exit 0'
+          : result.exit === undefined || result.exit === null
+            ? finished.failed
+              ? ' × did not finish'
+              : ''
+            : ` × exit ${result.exit}`;
+    const lines = (result.text ?? '')
+      .replace(/\n+$/, '')
+      .split('\n')
+      .filter((l) => l.trim() !== '');
+    return {
+      state:
+        finished && result.exit !== undefined && result.exit !== null && result.exit !== 0
+          ? 'failed'
+          : state,
+      label: `Bash ${short(args.command)}${ended}`,
+      tail: finished ? lines.slice(-tail).map((l) => short(l, 120)) : [],
+      ...(result.text !== undefined ? { full: result.text.replace(/\n+$/, '') } : {}),
+    };
+  }
+  return { state, label: humanTool(tool, input), tail: [] };
+}
+
+/** The verb the progress line shows for what the agent is doing now. */
+export function activityVerb(running?: ToolLine): string {
+  if (!running) return 'Thinking';
+  if (running.label.startsWith('Edit ')) return 'Editing';
+  if (running.label.startsWith('Bash ')) return 'Running ' + running.label.slice(5);
+  return running.label;
+}
+
+const SPIN = ['◐', '◓', '◑', '◒'];
+/** The live progress line while a turn runs: spinner, verb, elapsed seconds, tokens, interrupt hint. */
+export function progressLine(
+  verb: string,
+  startedAt: number,
+  now: number,
+  tokens?: string,
+): string {
+  const seconds = Math.max(0, Math.floor((now - startedAt) / 1000));
+  const elapsed = seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+  return [
+    SPIN[seconds % SPIN.length] + ' ' + safeText(verb) + '…',
+    elapsed,
+    ...(tokens ? [tokens + ' tokens'] : []),
+    'esc to interrupt',
+  ].join(' · ');
+}

package/src/tui-classifier.ts

@@ -0,0 +1,38 @@
+/** /classifier (operator 2026-10-31): the command reviewer has its own model selection. */
+export interface ClassifierView {
+  configured: boolean;
+  enabled: boolean;
+  choice: string;
+  pinned: boolean;
+  model?: string;
+  on_unavailable?: string;
+  options: { name: string; provider: string; model: string }[];
+}
+
+/** Picker rows: every configured reviewer, then Off. Empty when there is nothing to choose. */
+export function classifierItems(v: ClassifierView) {
+  if (!v.configured || v.pinned) return [];
+  const mark = (on: boolean) => (on ? '● ' : '○ ');
+  return [
+    ...v.options.map((o) => ({
+      value: o.name,
+      label: mark(v.choice === o.name) + o.name,
+      description: `${o.provider} · ${o.model}`,
+    })),
+    { value: 'off', label: mark(v.choice === 'off') + 'Off', description: 'Rules only' },
+  ];
+}
+
+export function classifierNotice(v: ClassifierView): string {
+  if (!v.configured && v.choice === 'off' && !v.pinned)
+    return 'No command reviewer is configured; set --danger-classifier-config on the service.';
+  const what = v.enabled
+    ? `Command reviewer ${v.choice} (${v.model}) is on for this session` +
+      ` (if it does not answer: ${v.on_unavailable === 'ask' ? 'ask' : 'rules only'})`
+    : 'Command reviewer is off for this session';
+  return (
+    what +
+    (v.pinned ? ', pinned by this host' : '') +
+    '. It can only make a command ask, never let one run.'
+  );
+}