@superjackfruitlabs/salaam 0.0.4 → 0.0.5

package/src/tui-modals.ts

@@ -152,13 +152,17 @@ export class FormModal implements Component, Focusable {
         this.theme.ink(this.labels?.field ?? 'Project directory', 'muted'),
         ...this.input.render(Math.max(1, width - 4)).map((line) => this.theme.ink(line)),
         '',
-        this.theme.ink(
-          this.allowCoding
-            ? this.coding
-              ? '[✓] Coding workspace · guarded tools'
-              : '[ ] Conversation session'
-            : (this.labels?.hint ?? 'Conversation session · coding service is off'),
-          this.coding ? 'jade' : 'muted',
+        // A long hint (the YOLO warning) wraps instead of running past the frame.
+        ...wrapTextWithAnsi(
+          this.theme.ink(
+            this.allowCoding
+              ? this.coding
+                ? '[✓] Coding workspace · guarded tools'
+                : '[ ] Conversation session'
+              : (this.labels?.hint ?? 'Conversation session · coding service is off'),
+            this.coding ? 'jade' : 'muted',
+          ),
+          Math.max(1, width - 4),
         ),
         '',
         this.theme.key('enter', this.labels?.submit ?? 'create') +
@@ -191,7 +195,11 @@ export class ConfirmModal implements Component, Focusable {
     readonly renderAgain: () => void,
     readonly close: () => void,
     readonly confirm: () => void,
-  ) {}
+    /** Start on the action rather than on "Keep current state" (cancel a running turn). */
+    confirmByDefault = false,
+  ) {
+    this.selected = confirmByDefault;
+  }
   invalidate(): void {}
   render(width: number): string[] {
     return framed(
@@ -230,11 +238,40 @@ export class ConfirmModal implements Component, Focusable {
     this.renderAgain();
   }
 }
+export type ApprovalDecision = 'approve' | 'approve-session' | 'always' | 'deny' | 'deny-feedback';
+/**
+ * Why a request asks, in one plain line (trial polish #2): the danger check's verdict when it has
+ * one, otherwise what the session mode leaves to a person.
+ */
+export function approvalReason(value: string, mode: string | undefined): string {
+  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]}`;
+  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.';
+}
+/**
+ * The approval prompt (phase 2a): what will run, in plain words, with the exact binding (approval
+ * id, digest, revision, expiry) one key away rather than in the way. Desk sessions can also approve
+ * for the rest of the session or always for this repo; strict work only ever approves once. A
+ * request longer than the screen must be read to the end before anything but Deny is possible, and
+ * a request that changed or expired cannot be approved at all.
+ */
+export { onceOnlyReason } from './approval-rules.js';
 export class ApprovalModal implements Component, Focusable {
   focused = false;
   offset = 0;
   reviewed = false;
-  approve = false;
+  showDetails = false;
+  choice = 0;
   private total = 0;
   private pageSize = 1;
   private stale = false;
@@ -246,25 +283,86 @@ export class ApprovalModal implements Component, Focusable {
     readonly current: () => Approval | undefined,
     readonly renderAgain: () => void,
     readonly close: () => void,
-    readonly decide: (decision: 'approve' | 'deny') => void,
-  ) {}
+    readonly decide: (decision: ApprovalDecision) => void,
+    readonly offerRules = false,
+    /** Why only Approve once and Deny are offered, shown above the choices. */
+    readonly onceOnly?: string,
+    /**
+     * Desk sessions (trial polish #1) see the change and decide; there is no read-to-the-end gate
+     * there, since the person chose the session and its mode. Strict work keeps the gate.
+     */
+    readonly options: { desk?: boolean; reason?: string } = {},
+  ) {
+    this.choice = 1;
+  }
+  private choices(): {
+    decision: ApprovalDecision;
+    key: string;
+    label: string;
+    colour: 'amber' | 'jade';
+  }[] {
+    return [
+      { decision: 'deny', key: 'n', label: 'Deny', colour: 'amber' },
+      { decision: 'approve', key: 'y', label: 'Approve once', colour: 'jade' },
+      ...(this.options.desk
+        ? [
+            {
+              decision: 'deny-feedback' as const,
+              key: 'f',
+              label: 'Deny and tell it why',
+              colour: 'amber' as const,
+            },
+          ]
+        : []),
+      ...(this.offerRules
+        ? [
+            {
+              decision: 'approve-session' as const,
+              key: 's',
+              label: 'Approve for this session',
+              colour: 'jade' as const,
+            },
+            {
+              decision: 'always' as const,
+              key: 'a',
+              label: 'Always allow in this repo',
+              colour: 'jade' as const,
+            },
+          ]
+        : []),
+    ];
+  }
   invalidate(): void {}
   render(width: number): string[] {
     const a = this.approval,
       op = this.operation,
       t = this.theme,
       inner = Math.max(1, width - 4);
-    const details = [
-      `Operation: ${op.kind}`,
-      `Target: ${safeText(op.target)}`,
-      'Value:',
-      safeText(op.value),
-      `Expected target version: ${safeText(op.target_version)}`,
-      `Approval: ${a.id}`,
-      `Digest: ${a.operation_digest}`,
-      `Revision: ${a.revision} · worker epoch: ${a.worker_epoch}`,
-      `Expires: ${new Date(a.expires_at).toISOString()}`,
-    ].flatMap((line) => wrapTextWithAnsi(t.ink(line), inner));
+    // A diff reads as a diff: added lines jade, removed lines red, hunk headers muted.
+    const diffInk = (line: string) =>
+      /^(\+\+\+|---) /.test(line) || line.startsWith('@@')
+        ? t.ink(line, 'muted')
+        : line.startsWith('+')
+          ? t.ink(line, 'jade')
+          : line.startsWith('-')
+            ? t.ink(line, 'red')
+            : t.ink(line);
+    const body = [
+      ...[safeText(op.target), ''].flatMap((line) => wrapTextWithAnsi(t.ink(line), inner)),
+      ...safeText(op.value)
+        .split('\n')
+        .flatMap((line) => wrapTextWithAnsi(diffInk(line), inner)),
+      ...[
+        ...(this.showDetails
+          ? [
+              '',
+              `Approval ${a.id} · revision ${a.revision} · worker epoch ${a.worker_epoch}`,
+              `Digest ${a.operation_digest}`,
+              `Target version ${safeText(op.target_version)} · expires ${new Date(a.expires_at).toISOString()}`,
+            ]
+          : []),
+      ].flatMap((line) => wrapTextWithAnsi(t.ink(line), inner)),
+    ];
     const current = this.current();
     this.stale =
       !current ||
@@ -272,40 +370,67 @@ export class ApprovalModal implements Component, Focusable {
       current.operation_digest !== a.operation_digest ||
       current.revision !== a.revision ||
       Date.now() >= a.expires_at;
-    this.total = details.length;
+    this.total = body.length;
     this.pageSize = Math.max(1, Math.min(18, this.rows() - 11));
     this.offset = Math.max(0, Math.min(this.offset, Math.max(0, this.total - this.pageSize)));
-    if (this.rows() >= 12 && this.offset + this.pageSize >= this.total) this.reviewed = true;
+    if (this.options.desk || (this.rows() >= 12 && this.offset + this.pageSize >= this.total))
+      this.reviewed = true;
+    const below = this.total - (this.offset + this.pageSize);
     const disabled = !this.reviewed || this.stale;
+    const choices = this.choices();
+    this.choice = Math.max(0, Math.min(this.choice, choices.length - 1));
     return framed(
       t,
-      'Review approval',
+      'Approve?',
       [
-        ...details.slice(this.offset, this.offset + this.pageSize),
+        ...body.slice(this.offset, this.offset + this.pageSize),
         '',
-        t.ink(
-          this.stale
-            ? 'This request changed or expired. Close and refresh.'
-            : this.reviewed
-              ? 'Exact request binding reviewed.'
-              : `Scroll to the end to enable approval · ${this.offset + 1}–${Math.min(this.total, this.offset + this.pageSize)} of ${this.total}`,
-          this.stale ? 'red' : 'muted',
+        ...(this.stale
+          ? [t.ink('This request changed or expired. Close and refresh.', 'red')]
+          : this.reviewed
+            ? []
+            : [
+                t.ink(
+                  `Read to the end to approve · ${this.offset + 1}–${Math.min(this.total, this.offset + this.pageSize)} of ${this.total}`,
+                  'muted',
+                ),
+              ]),
+        ...(this.options.desk && below > 0
+          ? [t.ink(`${below} more lines · ↓ to scroll`, 'muted')]
+          : []),
+        ...(this.options.reason
+          ? wrapTextWithAnsi(t.ink(this.options.reason, 'amber'), inner)
+          : []),
+        ...(this.onceOnly ? wrapTextWithAnsi(t.ink(this.onceOnly, 'muted'), inner) : []),
+        ...choices.map((c, i) =>
+          t.ink(
+            (i === this.choice ? '› ' : '  ') + `${c.key}  ${c.label}`,
+            !c.decision.startsWith('deny') && disabled
+              ? 'muted'
+              : i === this.choice
+                ? c.colour
+                : 'muted',
+          ),
         ),
-        t.ink((this.approve ? '  ' : '› ') + 'Deny', this.approve ? 'muted' : 'amber') +
-          '     ' +
-          t.ink((this.approve ? '› ' : '  ') + 'Approve once', disabled ? 'muted' : 'jade'),
         '',
-        t.key('↑↓', 'scroll') +
-          '   ' +
-          t.key('←→', 'choose') +
+        t.key('←→', 'choose') +
           '   ' +
           t.key('enter', 'decide') +
           '   ' +
+          t.key('d', this.showDetails ? 'hide details' : 'details') +
+          '   ' +
+          t.key('↑↓', 'scroll') +
+          '   ' +
           t.key('esc', 'back'),
       ],
       width,
     );
   }
+  private pick(decision: ApprovalDecision): void {
+    if (decision !== 'deny' && decision !== 'deny-feedback' && (this.stale || !this.reviewed))
+      return;
+    this.decide(decision);
+  }
   handleInput(data: string): void {
     const current = this.current(),
       a = this.approval;
@@ -316,17 +441,22 @@ export class ApprovalModal implements Component, Focusable {
       current.revision !== a.revision ||
       current.worker_epoch !== a.worker_epoch ||
       Date.now() >= a.expires_at;
+    const choices = this.choices();
+    const byKey = choices.find((c) => c.key === data);
     if (matchesKey(data, 'escape')) this.close();
+    else if (byKey) this.pick(byKey.decision);
+    else if (data === 'd') this.showDetails = !this.showDetails;
     else if (matchesKey(data, 'down')) this.offset++;
     else if (matchesKey(data, 'up')) this.offset--;
     else if (matchesKey(data, 'pageDown')) this.offset += this.pageSize;
     else if (matchesKey(data, 'pageUp')) this.offset -= this.pageSize;
     else if (matchesKey(data, 'end')) this.offset = this.total;
     else if (matchesKey(data, 'home')) this.offset = 0;
-    else if (matchesKey(data, 'left') || matchesKey(data, 'right') || matchesKey(data, 'tab'))
-      this.approve = !this.approve;
-    else if (matchesKey(data, 'enter') && !this.stale && (!this.approve || this.reviewed))
-      this.decide(this.approve ? 'approve' : 'deny');
+    else if (matchesKey(data, 'right') || matchesKey(data, 'tab'))
+      this.choice = (this.choice + 1) % choices.length;
+    else if (matchesKey(data, 'left'))
+      this.choice = (this.choice + choices.length - 1) % choices.length;
+    else if (matchesKey(data, 'enter')) this.pick(choices[this.choice]!.decision);
     this.renderAgain();
   }
 }

package/src/tui-notify.ts

@@ -0,0 +1,77 @@
+import { spawn } from 'node:child_process';
+import type { DurableEvent } from './protocol.js';
+
+/** How the desk TUI gets a person's attention: off, a terminal bell, or a desktop notification
+ * (which also rings the bell). Set with SALAAM_NOTIFY; the bell is the default. */
+export type NotifyMode = 'off' | 'bell' | 'desktop';
+export function notifyMode(env: NodeJS.ProcessEnv = process.env): NotifyMode {
+  const v = env.SALAAM_NOTIFY;
+  return v === 'off' || v === 'desktop' ? v : 'bell';
+}
+
+/** The events worth interrupting someone for, in plain words; everything else stays quiet. */
+export function notificationFor(event: DurableEvent): string | null {
+  const p = (event.payload ?? {}) as Record<string, unknown>;
+  if (event.kind === 'approval.requested') return 'Salaam is waiting for your approval';
+  if (event.kind === 'attempt.completed') return 'Salaam finished the turn';
+  if (event.kind === 'attempt.failed') return 'Salaam’s turn failed';
+  if (event.kind === 'local.task_finished') {
+    const how =
+      p.state === 'exited'
+        ? p.exit_code === 0
+          ? 'finished'
+          : `exited with ${String(p.exit_code)}`
+        : String(p.state).replace('_', ' ');
+    return `Background command ${how}: ${String(p.command ?? '').slice(0, 80)}`;
+  }
+  return null;
+}
+
+export function notify(
+  message: string,
+  mode: NotifyMode,
+  platform: NodeJS.Platform = process.platform,
+  run: (cmd: string, args: string[]) => void = detached,
+  bell: (s: string) => void = (s) => void process.stdout.write(s),
+): void {
+  if (mode === 'off') return;
+  bell('\x07');
+  if (mode !== 'desktop') return;
+  // Passed as an argument, never interpolated into the script: a command name cannot inject.
+  if (platform === 'darwin')
+    run('osascript', [
+      '-e',
+      'on run argv\ndisplay notification (item 1 of argv) with title "Salaam"\nend run',
+      message,
+    ]);
+  else if (platform === 'linux') run('notify-send', ['Salaam', message]);
+}
+function detached(cmd: string, args: string[]): void {
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+  } catch {
+    /* the bell already rang */
+  }
+}
+
+export interface JobRow {
+  id: string;
+  command: string;
+  state: string;
+  exit_code: number | null;
+  started_at: string;
+}
+export function jobsText(tasks: JobRow[], outputs: { output: string }[]): string {
+  if (!tasks.length)
+    return 'No background commands in this session.\nThe model starts one with salaam_local background: true.';
+  return tasks
+    .map((t, i) => {
+      const state = t.state === 'exited' ? `exited ${String(t.exit_code)}` : t.state;
+      const tail = outputs[i]?.output.split('\n').slice(-12).join('\n').trimEnd();
+      return `${t.id}  ${state}  ${t.command}${tail ? '\n' + tail.replace(/^/gm, '  │ ') : ''}`;
+    })
+    .join('\n\n')
+    .concat('\n\n/jobs stop <id> stops one.');
+}

package/src/tui-review.ts

@@ -0,0 +1,76 @@
+import { relativeTime } from './session-pick.js';
+import type { CheckpointChange, CheckpointHunk } from './turn-checkpoints.js';
+import type { ChangeReview, RewindReview } from './turn-rewind.js';
+
+/** The Changes tab of a local coding session: one file selected, optionally one of its hunks. */
+export interface ReviewView {
+  data: ChangeReview | null;
+  file: number;
+  hunks?: CheckpointHunk[];
+  /** -1 means the whole file. */
+  hunk: number;
+}
+
+const SHOWN = 12;
+
+/** Background commands may keep writing while a review or rewind is open (operator ruling). */
+export function backgroundNote(running: number | undefined): string | null {
+  if (!running) return null;
+  return running === 1
+    ? '1 background task running; its writes may change files. /jobs shows it.'
+    : `${running} background tasks running; their writes may change files. /jobs shows them.`;
+}
+
+export function changeCounts(change: CheckpointChange): string {
+  return change.added === null ? 'binary' : `+${change.added} −${change.removed}`;
+}
+
+/** What one confirm of a rewind does, in words. `changes` are from the folder now to the
+ * checkpoint, so a file the checkpoint has and the folder lacks is brought back. */
+export function rewindSummary(review: RewindReview): string {
+  const lines: string[] = [];
+  if (review.mode === 'conversation') lines.push('Files are not changed.');
+  else if (!review.changes.length) lines.push('Files already match the checkpoint.');
+  else {
+    lines.push(
+      `Files: ${review.changes.length} to put back as they were before turn ${review.turn}.`,
+    );
+    for (const change of review.changes.slice(0, SHOWN))
+      lines.push(
+        '  ' +
+          (change.status === 'modified'
+            ? 'restore '
+            : change.status === 'added'
+              ? 'bring back '
+              : 'remove ') +
+          change.path +
+          ` (${changeCounts(change)})`,
+      );
+    if (review.changes.length > SHOWN)
+      lines.push(`  … and ${review.changes.length - SHOWN} more files`);
+  }
+  lines.push(
+    review.mode === 'files'
+      ? 'The conversation is kept as it is.'
+      : `The conversation continues in a new session from before turn ${review.turn}; this session stays as it is, and its instruction comes back to edit.`,
+  );
+  lines.push('Commands and anything outside this folder are not undone.');
+  const note = backgroundNote(review.background_running);
+  if (note) lines.push(note);
+  return lines.join('\n');
+}
+
+/** /rewind's turn list: newest first, with how long ago each turn started. */
+export function rewindItems(
+  points: readonly { attempt_id: string; turn: number; text: string; at: string }[],
+  now = Date.now(),
+) {
+  return points
+    .slice()
+    .reverse()
+    .map((p) => ({
+      value: p.attempt_id,
+      label: `Turn ${p.turn} · ${p.text.split('\n')[0]!.slice(0, 80)}`,
+      description: relativeTime(p.at, now),
+    }));
+}

package/src/tui-turn-keys.ts

@@ -0,0 +1,77 @@
+import { matchesKey } from '@earendil-works/pi-tui';
+
+/**
+ * Stopping and steering a running turn in an interactive coding session (operator plan
+ * 2026-10-31, Phase 2c). Esc interrupts the running turn, Enter steers it with what you typed, and
+ * Tab queues the text for after the turn. Other sessions, such as strict board work, keep plain
+ * submit and an explicit /cancel.
+ */
+export type TurnKeyAction = 'interrupt' | 'steer' | 'queue' | 'submit' | null;
+
+interface TurnSnapshot {
+  capabilities: string[];
+  attempts: { id: string; submission_id: string; state: string }[];
+  submissions: { id: string; text: string; state: string }[];
+}
+
+/** Interactive local coding: the desk-side mode, not admitted or strict work. */
+export function interactiveCoding(snapshot: TurnSnapshot | undefined): boolean {
+  return !!snapshot?.capabilities.includes('local-coding-reviewed');
+}
+
+/** The turn the model is working on now, if any. */
+export function runningAttempt(snapshot: TurnSnapshot | undefined): string | undefined {
+  return snapshot?.attempts.find((a) => a.state === 'running')?.id;
+}
+
+export function turnKeyAction(input: {
+  key: 'escape' | 'enter' | 'tab';
+  text: string;
+  snapshot: TurnSnapshot | undefined;
+  modal: boolean;
+  autocomplete: boolean;
+}): TurnKeyAction {
+  const { key, text, snapshot } = input;
+  if (input.modal || input.autocomplete) return key === 'enter' ? 'submit' : null;
+  const live = interactiveCoding(snapshot) && runningAttempt(snapshot) !== undefined;
+  const words = text.trim() !== '' && !text.trimStart().startsWith('/');
+  if (key === 'escape') return live ? 'interrupt' : null;
+  if (key === 'tab') return live && words ? 'queue' : null;
+  return live && words ? 'steer' : 'submit';
+}
+
+/** The key the TUI saw, as one of the three this module decides, or undefined for any other. */
+export function turnKey(data: string): 'escape' | 'enter' | 'tab' | undefined {
+  return matchesKey(data, 'escape')
+    ? 'escape'
+    : matchesKey(data, 'enter')
+      ? 'enter'
+      : matchesKey(data, 'tab')
+        ? 'tab'
+        : undefined;
+}
+
+/** What /cancel offers, the running turn first, then work queued behind it. */
+export function cancelChoices(snapshot: TurnSnapshot): { id: string; label: string }[] {
+  const order = ['running', 'dispatching', 'accepted'];
+  return snapshot.attempts
+    .filter((a) => order.includes(a.state))
+    .sort((a, b) => order.indexOf(a.state) - order.indexOf(b.state))
+    .map((a) => ({
+      id: a.id,
+      label: (a.state === 'accepted' ? 'queued' : a.state) + ' · ' + a.id.slice(0, 8),
+    }));
+}
+
+/** Instructions waiting behind the running turn, with their text, so they can be edited or removed. */
+export function queuedItems(
+  snapshot: TurnSnapshot,
+): { attempt: string; submission: string; text: string }[] {
+  return snapshot.attempts
+    .filter((a) => a.state === 'accepted')
+    .map((a) => ({
+      attempt: a.id,
+      submission: a.submission_id,
+      text: snapshot.submissions.find((s) => s.id === a.submission_id)?.text ?? '',
+    }));
+}