@volter/supercode-teams 0.3.85 → 0.3.87

package/mail/reads.mjs

@@ -0,0 +1,389 @@
+// The mail reads the daemon answers (docs/architecture/overview.md, "The mail operations", 3a): `message list`, `show`,
+// `inbox` and the machine record's mail, from the live-session map, the header index and the records of the team's
+// other machines the daemon holds. One local call, no process. Ported from crates/cli/src/message.rs (session_rows,
+// team_rows, list, show_rows, show, show_replies, inbox, inbox_rows): the same rows, the same text.
+import { statSync, openSync, readSync, closeSync } from 'node:fs';
+import { listed, messageRow, questionDeliveredAt } from './envelope.mjs';
+import { deliveries, readTranscript, transcriptPath } from './transcript.mjs';
+
+export const EXIT_REFUSED = 2;
+export const EXIT_UNKNOWN = 3;
+export const EXIT_FAILED = 5;
+/** A whole message id: its kind, a dash and 24 hex digits. */
+const FULL_ID_LEN = 26;
+/** How many receivers' transcripts one listing reads for the state of the messages it sent. */
+const MAX_RECEIVERS_READ = 6;
+/** A message held in a record's mail window: each mailbox's unread mail and its newest RECENT_PER_MAILBOX. */
+export const RECENT_PER_MAILBOX = 20;
+
+const isDaemonPane = (name) => /^p_[A-Za-z0-9_-]+$/.test(name);
+/** The parts of a machine's record its session list comes from: one not read leaves the list not current. */
+const SESSION_SOURCES = ['sessions', 'sessions_index', 'sessions_index_parts', 'claude_registry_watch'];
+const at = (ms) => (Number.isFinite(ms) ? new Date(ms).toISOString() : 'never');
+
+/**
+ * The records of the other machines this daemon follows, each with how current it is (mailbox.rs `held_records`): a
+ * machine that is offline is left out (never a reading that is incomplete); a record whose stream is not open is stale,
+ * with why; a machine never read is unread, with why; and `*` when the daemon follows no machine at all.
+ */
+export function heldRecords({ records, unread, self }) {
+  const held = Object.entries(records ?? {}).filter(([machine, entry]) => machine !== self && entry?.stream !== 'unlinked').map(([machine, entry]) => {
+    const stream = entry?.stream ?? 'unknown';
+    const why = entry?.why ?? 'no reason given';
+    const record = entry?.record && typeof entry.record === 'object' ? entry.record : null;
+    const stale = stream !== 'open' && record ? (stream === 'too-old' ? `its record is held from ${at(entry.received_at)} and may be out of date: too old to read (${why})` : `its record is held from ${at(entry.received_at)} and may be out of date: its record stream is ${stream} since ${at(entry.since)}: ${why}`) : null;
+    const notRead = record ? null : stream === 'too-old' ? `too old to read (${why})` : `not read: its record stream ${stream} since ${at(entry.since)}: ${why}`;
+    return { machine, record, stale, unread: notRead };
+  });
+  held.sort((a, b) => (a.machine < b.machine ? -1 : a.machine > b.machine ? 1 : 0));
+  if (typeof unread === 'string') held.push({ machine: '*', record: null, stale: null, unread });
+  return held;
+}
+
+/** A held machine's session list when it is current; otherwise why not (mailbox.rs `current_sessions`). */
+function currentSessions(entry) {
+  if (entry.unread) return { why: entry.unread };
+  if (entry.stale) return { why: entry.stale };
+  if (!entry.record) return { why: 'its record was never read' };
+  const lost = SESSION_SOURCES.filter((source) => typeof entry.record.unread?.[source] === 'string').map((source) => `${source}: ${entry.record.unread[source]}`);
+  if (lost.length) return { why: `its session list may be out of date (${lost.join('; ')})` };
+  return Array.isArray(entry.record.sessions) ? { sessions: entry.record.sessions } : { why: 'its record holds no session list' };
+}
+
+/** What a pane's screen asks, when it shows a selector (mail_route.rs `pane_prompt`): the options' block of non-empty
+ *  lines and the block above it (the question), at most 20 lines; null when it shows none. */
+export function panePrompt(screen) {
+  if (typeof screen !== 'string') return null;
+  const lines = screen.split('\n').map((line) => line.trimEnd());
+  const isOption = (line) => {
+    let rest = line.trimStart();
+    for (const mark of ['❯', '›', '>']) if (rest.startsWith(mark)) { rest = rest.slice(mark.length); break; }
+    rest = rest.trimStart();
+    const digits = /^\d*/.exec(rest)[0].length;
+    return digits > 0 && ['.', ')'].includes(rest[digits]);
+  };
+  const selected = lines.findIndex((line) => { const trimmed = line.trimStart(); return ['❯', '›', '>'].some((mark) => trimmed.startsWith(mark)) && isOption(line); });
+  if (selected < 0) return null;
+  const blockStart = (end) => { for (let n = end - 1; n >= 0; n--) if (!lines[n].trim()) return n + 1; return 0; };
+  const options = blockStart(selected);
+  let last = -1; for (let n = options - 1; n >= 0; n--) if (lines[n].trim()) { last = n; break; }
+  const start = last >= 0 ? blockStart(last) : options;
+  let end = lines.length; for (let n = selected; n < lines.length; n++) if (!lines[n].trim()) { end = n; break; }
+  return lines.slice(start, end).map((line) => line.trim()).filter(Boolean).slice(0, 20);
+}
+
+/** The end of a file, at most `bytes` (a transcript's tail). */
+function tail(path, bytes) {
+  const fd = openSync(path, 'r');
+  try {
+    const size = statSync(path).size;
+    const start = Math.max(0, size - bytes);
+    const buffer = Buffer.alloc(size - start);
+    readSync(fd, buffer, 0, buffer.length, start);
+    return buffer.toString('utf8');
+  } finally { closeSync(fd); }
+}
+
+/** The newest tool call in a Claude transcript with no result yet (mail_route.rs `pending_request`). */
+function pendingFromTranscript(path) {
+  let text; try { text = tail(path, 512 * 1024); } catch { return null; }
+  const answered = new Set();
+  for (const line of text.split('\n').reverse()) {
+    let record; try { record = JSON.parse(line); } catch { continue; }
+    if (record?.isSidechain === true || !Array.isArray(record?.message?.content)) continue;
+    const content = record.message.content;
+    if (record.type === 'user') { for (const item of content) if (item?.type === 'tool_result' && typeof item.tool_use_id === 'string') answered.add(item.tool_use_id); continue; }
+    if (record.type !== 'assistant') continue;
+    const call = [...content].reverse().find((item) => item?.type === 'tool_use');
+    if (!call) continue;
+    if (typeof call.id === 'string' && answered.has(call.id)) return null;
+    const tool = typeof call.name === 'string' ? call.name : '';
+    if (tool === 'AskUserQuestion') {
+      const questions = (Array.isArray(call.input?.questions) ? call.input.questions : []).map((question) => ({ question: question?.question ?? null, header: question?.header ?? null, options: (Array.isArray(question?.options) ? question.options : []).map((option) => option?.label ?? null) }));
+      return { tool, questions };
+    }
+    return { tool, input: [...JSON.stringify(call.input ?? null)].slice(0, 500).join('') };
+  }
+  return null;
+}
+
+/**
+ * The mail reads, over `live` (the live-session map), `store` (the header index), `records` (the records of the team's
+ * other machines), `descriptors` (the session index's rows by address), `homes` (where transcripts are),
+ * `paneQuestion(pane)` (what a waiting session's pane asks, read off its screen) and `askMachine(machine, request)`
+ * (one named read of another machine's mail door).
+ */
+export class MailReads {
+  /** `records()` answers `{ records, unread, self }`: the records this daemon holds (machine-records.mjs `read`), why
+   *  it holds none when it follows no machine, and this machine's name. */
+  constructor({ machine, live, store, records, descriptors, homes, paneQuestion = async () => null, askMachine }) {
+    Object.assign(this, { machine, live, store, records, descriptors, homes, paneQuestion, askMachine });
+  }
+
+  // ---- list ------------------------------------------------------------------------------------------------------
+
+  /** What a waiting session asks: its transcript's pending tool call, else its pane's prompt (`pending_request`). */
+  async #pending(session) {
+    if (session.status !== 'waiting') return null;
+    const harness = session.address.split(':')[2];
+    if (harness === 'claude-code') {
+      const path = transcriptPath(session.address, this.homes);
+      const found = path ? pendingFromTranscript(path) : null;
+      if (found) return found;
+    } else if (harness !== 'codex') return null;
+    const pane = this.#paneOf(session);
+    const prompt = pane ? await this.paneQuestion(pane) : null;
+    return prompt ? { prompt, source: 'screen' } : null;
+  }
+
+  /** The daemon pane a live session runs in, or null. */
+  paneOf(session) { return this.#paneOf(session); }
+
+  #paneOf(session) {
+    const pane = typeof session.pane === 'string' ? session.pane.split(':')[0] : null;
+    return pane && isDaemonPane(pane) ? pane : null;
+  }
+
+  /** This machine's live sessions as `message list` rows (`session_rows`). */
+  async localRows() {
+    return Promise.all(this.live.sessions().map(async (session) => ({
+      name: session.name,
+      harness: session.address.split(':')[2],
+      status: session.status,
+      delivery: session.door,
+      address: session.address,
+      pane: this.#paneOf(session),
+      last_message_at_ms: this.descriptors.get(session.address)?.updated_at_ms ?? null,
+      pending_request: await this.#pending(session),
+    })));
+  }
+
+  /** The team's other machines' sessions from the records this daemon holds (`team_rows`): a machine not read is
+   *  unknown (with why), never one with no sessions; a record not current is listed and said stale. */
+  teamRows() {
+    const team = { rows: [], unread: [], stale: [] };
+    for (const machine of heldRecords(this.records())) {
+      if (machine.unread) { team.unread.push([machine.machine, machine.unread]); continue; }
+      const current = currentSessions(machine);
+      if (current.sessions) { team.rows.push(...current.sessions); continue; }
+      const sessions = machine.record?.sessions;
+      if (Array.isArray(sessions)) { team.rows.push(...sessions.map((row) => ({ ...row, stale: current.why }))); team.stale.push([machine.machine, current.why]); }
+      else team.unread.push([machine.machine, current.why]);
+    }
+    return team;
+  }
+
+  /**
+   * A bare name (or a daemon pane's id, `p_…`) no session here answers to, looked up in the records this daemon holds of
+   * the team's other machines (message.rs `team_address`): `{ to }` its address there (with `notes` for the sender:
+   * found only in a stale record, or unique only among the machines read), `{ to: null }` when it is this machine's to
+   * resolve, or `{ error }`. `remembered(name)` is the names ledger's address for a name.
+   */
+  teamAddress(to, remembered) {
+    if (to.includes('@') || to.startsWith('sc:') || to.startsWith('operator:')) return { to: null };
+    const pane = to.startsWith('p_');
+    const names = (row) => (pane ? row.pane === to : String(row.name ?? '').split('@')[0] === to);
+    const here = this.live.sessions().map((session) => ({ name: session.name, pane: this.#paneOf(session), address: session.address }));
+    if (here.some(names)) return { to: null };
+    // a name a session running here ran under before is the mail door's to resolve and say
+    if (!pane) { const address = remembered(to); if (address && here.some((row) => row.address === address)) return { to: null }; }
+    const team = this.teamRows();
+    const incomplete = team.unread.length ? team.unread.map(([machine, why]) => `${machine}: ${why}`).join('; ') : null;
+    const held = (stale) => {
+      const found = [];
+      for (const row of team.rows.filter((item) => names(item) && (item.stale !== undefined) === stale)) {
+        if (typeof row.address !== 'string') continue;
+        const machine = row.address.split(':')[1] ?? '';
+        if (!found.some(([known]) => known === machine)) found.push([machine, row.address]);
+      }
+      return found;
+    };
+    const current = held(false);
+    const [found, stale] = current.length ? [current, false] : [held(true), true];
+    if (found.length === 1) {
+      const [[machine, only]] = found;
+      const notes = [];
+      if (stale) notes.push(`\`${to}\` is ${only}, found only in a stale record of ${machine}: it may no longer run there`);
+      if (!pane && incomplete) notes.push(`\`${to}\` is ${only}, the only session of that name on the machines read; not read: ${incomplete}`);
+      return { to: only, notes };
+    }
+    if (!found.length) return incomplete ? { error: `\`${to}\` is on no machine of the team that was read; not read: ${incomplete}` } : { to: null };
+    return { error: `\`${to}\` names a session on ${found.length} machines (${found.map(([, address]) => address).join(', ')})${stale ? ', each in a stale record' : ''}: not a unique answer` };
+  }
+
+  /** `message list`: this machine's sessions, then the team's, then each machine not read or not current (`list`). */
+  async list() {
+    const rows = await this.localRows();
+    const team = this.teamRows();
+    rows.push(...team.rows);
+    for (const [machine, why] of team.unread) rows.push({ machine: machine === '*' ? null : machine, status: 'unavailable', error: why });
+    for (const [machine, why] of team.stale) rows.push({ machine, status: 'stale', error: why });
+    return rows;
+  }
+
+  // ---- show ------------------------------------------------------------------------------------------------------
+
+  /** One stored envelope whole (its body from its file); null when it is gone. */
+  #whole(stored) { const envelope = this.store.body(stored); return envelope ? { ...stored, envelope } : null; }
+
+  /** `show` rows for the messages this machine holds (`show_rows`). */
+  async showRows(ids) {
+    const transcripts = new Map();
+    return Promise.all(ids.map(async (id) => {
+      const found = this.store.find(id);
+      if (found.length === 0) return { id, found: false };
+      if (found.length > 1) return { id, found: false, ambiguous: found.map(({ stored }) => stored.envelope.id) };
+      const { address } = found[0];
+      const stored = this.#whole(found[0].stored);
+      if (!stored) return { id, found: false };
+      if (!transcripts.has(address)) transcripts.set(address, readTranscript(address, this.homes));
+      const delivered = deliveries(address, [stored], await transcripts.get(address), (envelope) => questionDeliveredAt(envelope, this.homes.mailRoot));
+      return { id, found: true, machine: this.machine, message: messageRow(address, stored, delivered, this.homes.mailRoot) };
+    }));
+  }
+
+  /**
+   * `message show`: each id here, else on the one machine whose held record names it (one named, bounded read, never
+   * every machine). A machine that could not be searched makes an id not found unknown, never absent (`show`). Answers
+   * `{ rows, code }`.
+   */
+  async show(ids) {
+    const rows = await this.showRows(ids);
+    const wanted = rows.filter((row) => row.found === false && !row.ambiguous).map((row) => row.id);
+    const unsearched = [];
+    if (wanted.length) {
+      const held = heldRecords(this.records());
+      const holds = (record, id) => Object.values(record?.mail ?? {}).some((box) => ['unread', 'recent'].some((part) => (Array.isArray(box?.[part]) ? box[part] : []).some((header) => typeof header?.id === 'string' && (header.id === id || header.id.startsWith(id)))));
+      const asks = new Map(), placed = new Set(), shorts = [];
+      for (const entry of held) {
+        if (entry.unread) { unsearched.push([entry.machine, entry.unread]); continue; }
+        const record = entry.record;
+        if (!record) continue;
+        const short = [];
+        if (entry.stale) short.push(entry.stale);
+        for (const source of ['mail', 'mail_watch', 'mail_boxes']) if (typeof record.unread?.[source] === 'string') short.push(record.unread[source]);
+        for (const [address, box] of Object.entries(record.mail ?? {})) { const why = box?.unread_reason ?? box?.partial; if (typeof why === 'string') short.push(`${address}: ${why}`); }
+        for (const id of wanted) if (holds(record, id)) { if (!asks.has(entry.machine)) asks.set(entry.machine, []); asks.get(entry.machine).push(id); placed.add(id); }
+        if (short.length) shorts.push([entry.machine, short]);
+      }
+      if (wanted.some((id) => id.length < FULL_ID_LEN || !placed.has(id))) for (const [machine, short] of shorts) unsearched.push([machine, `its mail window may be incomplete: ${short.join('; ')}`]);
+      const answers = await Promise.all([...asks].map(async ([machine, asked]) => {
+        try { return [machine, await this.askMachine(machine, { op: 'show', ids: asked })]; } catch (error) { return [machine, error]; }
+      }));
+      for (const [machine, answer] of answers) {
+        if (answer instanceof Error) { unsearched.push([machine, answer.message]); continue; }
+        if (!Array.isArray(answer?.rows)) { unsearched.push([machine, 'it answered no search result']); continue; }
+        for (const there of answer.rows) {
+          if (there?.found !== true && !there?.ambiguous) continue;
+          const at = rows.findIndex((row) => row.id === there.id && row.found === false);
+          if (at >= 0) rows[at] = there;
+        }
+      }
+      const older = wanted.filter((id) => !placed.has(id));
+      if (older.length) {
+        const followed = held.filter((entry) => entry.machine !== '*').map((entry) => entry.machine);
+        unsearched.push(['*', `${older.join(', ')} ${older.length === 1 ? 'is' : 'are'} in no pushed mail window (each machine's record holds its unread mail and the last ${RECENT_PER_MAILBOX} messages of each mailbox): an older message is shown by \`supercode message show\` on the machine that holds it${followed.length ? ` (${followed.join(', ')})` : ''}`]);
+      }
+    }
+    const missing = rows.some((row) => row.found !== true);
+    const notSearched = unsearched.map(([machine, why]) => (machine === '*' ? why : `${machine}: ${why}`));
+    if (notSearched.length) for (const row of rows) if (row.found === false && !row.ambiguous) { row.found = null; row.unsearched = notSearched; }
+    return { rows, unsearched: notSearched, code: missing && notSearched.length ? EXIT_FAILED : missing ? EXIT_UNKNOWN : 0 };
+  }
+
+  /** `show --replies`: for each message here, the messages in its sender's mailbox that answer it (`show_replies`). */
+  showReplies(ids) {
+    const rows = ids.map((id) => {
+      const found = this.store.find(id);
+      if (found.length !== 1) return { id, found: false };
+      const asked = found[0].stored.envelope;
+      const namesIt = (reply) => reply === asked.id || (reply.length >= 10 && asked.id.startsWith(reply));
+      const replies = this.store.inventory(asked.from).stored
+        .filter((stored) => typeof stored.envelope.in_reply_to === 'string' && namesIt(stored.envelope.in_reply_to))
+        .map((stored) => this.#whole(stored)).filter(Boolean)
+        .map(({ envelope }) => ({ id: envelope.id, from: envelope.from, from_name: envelope.from_name, created_at_ms: envelope.created_at_ms, body: envelope.body }));
+      return { id, found: true, message: asked.id, session: found[0].address, asker: asked.from, replies };
+    });
+    return { rows, code: rows.some((row) => row.found !== true) ? EXIT_UNKNOWN : 0 };
+  }
+
+  // ---- inbox -----------------------------------------------------------------------------------------------------
+
+  /**
+   * A session's own `message inbox`: its unread mail claimed first (the claim hands it over), then, with `all`, its read
+   * mail with when each reached the model, from its transcript; the newest `last` of the read only (`inbox`). Answers
+   * `{ stored, deliveries, claimed }`; the caller acknowledges each claimed one once it is printed (`acknowledge`).
+   */
+  async inbox(address, { all = false, last = null, pid = process.pid } = {}) {
+    const claimed = this.store.claimUnread(address, 'inbox', address, pid).map((stored) => this.#whole(stored) ?? stored);
+    const transcript = all ? await readTranscript(address, this.homes) : null;
+    let stored;
+    if (all) {
+      stored = this.store.inventory(address).stored
+        .filter((item) => item.state === 'read' || (item.envelope.kind === 'user' && item.part === 'claimed'))
+        .map((item) => this.#whole(item)).filter(Boolean);
+      if (last !== null) stored = stored.slice(Math.max(0, stored.length - last));
+      stored.push(...claimed);
+      stored.sort((a, b) => a.envelope.created_at_ms - b.envelope.created_at_ms);
+    } else stored = claimed;
+    const delivered = deliveries(address, stored, transcript, (envelope) => questionDeliveredAt(envelope, this.homes.mailRoot));
+    const now = Date.now();
+    for (const item of claimed) delivered.set(item.envelope.id, { state: 'by_this_read', at_ms: now });
+    return { stored, deliveries: delivered, claimed, rendered: stored.map((item) => listed(item.envelope, delivered, this.homes.mailRoot)), rows: stored.map((item) => messageRow(address, item, delivered, this.homes.mailRoot)) };
+  }
+
+  /** The live session a name or address names here (mail_route.rs `resolve`, without the ledger of earlier names). */
+  resolve(name) {
+    const sessions = this.live.sessions();
+    if (String(name).startsWith('sc:')) return sessions.find((session) => session.address === name) ? { address: name } : { error: `${name} is no longer running. Nothing was sent. Run supercode message list for the live sessions.` };
+    const [wanted, at] = String(name).split('@');
+    if (at !== undefined && at !== this.machine) return { error: `Not sent: ${name} is on machine ${at}, not this one. Nothing was sent.` };
+    const matching = sessions.filter((session) => session.name.split('@')[0] === wanted);
+    return matching.length === 1 ? { address: matching[0].address } : { error: matching.length ? `${name} names ${matching.length} sessions here; give its address.` : `No running session here is named "${name}".` };
+  }
+
+  /** Claimed mail printed: it reached its reader (moved to `cur/`). */
+  acknowledge(address, claimed) { for (const item of claimed) this.store.acknowledge(address, item); }
+
+  /** Everything into and out of the session at `address` here, oldest first, read without marking anything read:
+   *  `inbox --session` rows (`inbox_rows`), the newest `last` only when given. */
+  async inboxRows(address, last = null) {
+    const transcript = await readTranscript(address, this.homes);
+    const received = this.store.inventory(address).stored.filter((item) => !(item.envelope.kind === 'question' && item.envelope.from === address)).map((item) => this.#whole(item)).filter(Boolean);
+    const delivered = deliveries(address, received, transcript, (envelope) => questionDeliveredAt(envelope, this.homes.mailRoot));
+    const sent = [];
+    for (const to of this.store.addresses()) {
+      if (to === address) continue;
+      for (const item of this.store.inventory(to).stored) if (item.envelope.from === address) { const whole = this.#whole(item); if (whole) sent.push([to, whole]); }
+    }
+    let timeline = [...received.map((item) => [address, item, 'in']), ...sent.map(([to, item]) => [to, item, 'out'])];
+    timeline.sort((a, b) => a[1].envelope.created_at_ms - b[1].envelope.created_at_ms);
+    if (last !== null) timeline = timeline.slice(Math.max(0, timeline.length - last));
+    // where a message it sent stands is read from its receiver's transcript, the newest receivers' only
+    const receivers = [];
+    for (const [to, , direction] of [...timeline].reverse()) if (direction === 'out' && !receivers.includes(to) && receivers.length < MAX_RECEIVERS_READ) receivers.push(to);
+    for (const to of receivers) {
+      const theirs = timeline.filter(([receiver, , direction]) => direction === 'out' && receiver === to).map(([, item]) => item);
+      for (const [id, delivery] of deliveries(to, theirs, await readTranscript(to, this.homes), (envelope) => questionDeliveredAt(envelope, this.homes.mailRoot))) delivered.set(id, delivery);
+    }
+    for (const [, item, direction] of timeline) if (direction === 'out' && !delivered.has(item.envelope.id)) delivered.set(item.envelope.id, { state: 'not_read' });
+    return timeline.map(([box, item, direction]) => ({ ...messageRow(box, item, delivered, this.homes.mailRoot), direction }));
+  }
+
+  // ---- the machine record's mail ---------------------------------------------------------------------------------
+
+  /** Each named mailbox's headers (all with none named): its unread mail, its newest `recent` and how many it holds,
+   *  never a body; a mailbox read partially says so (the `headers` operation). */
+  headers({ recent = RECENT_PER_MAILBOX, mailboxes = null } = {}) {
+    const header = (item) => ({ id: item.envelope.id, from: item.envelope.from, from_name: item.envelope.from_name, kind: item.envelope.kind, subject: item.envelope.subject ?? null, thread: item.envelope.thread ?? item.envelope.id, in_reply_to: item.envelope.in_reply_to ?? null, created_at_ms: item.envelope.created_at_ms, unread: item.state === 'unread' });
+    const mail = {};
+    for (const address of mailboxes ?? this.store.addresses()) {
+      const { stored, skipped } = this.store.inventory(address);
+      const answer = { unread: stored.filter((item) => item.state === 'unread').map(header), recent: [...stored].reverse().slice(0, recent).map(header), count: stored.length };
+      if (skipped.length) answer.partial = `${skipped.length} envelope file${skipped.length === 1 ? '' : 's'} could not be read (${skipped.slice(0, 5).join(', ')}); its unread mail may be more than listed`;
+      mail[address] = answer;
+    }
+    return { mail, unread_boxes: this.store.unread ? [this.store.unread] : [] };
+  }
+}
+

package/mail/relay.mjs

@@ -0,0 +1,233 @@
+// A Claude session supercode does not control is reached through Claude's own SendMessage, made by a relay: a `claude
+// --print` runtime that speaks for the sender, hosted by this daemon's `harness serve` (crates/harness/src/claude_relay.rs).
+// The daemon drives a relay send through the relay's folder, as the native sender did: `queue.json` names the one send its
+// gate allows, the relay's hooks write Claude's answer to `receipt.json`, and the turn that makes the send goes in by
+// harness serve's own `runtimes.send_input`; its runtime is started and closed by `runtimes.start` and `runtimes.close`.
+// No native process runs per delivery. The relay's hooks (`message gate`, `relay-inbound`, `relay-receipt`) stay native
+// doors, run by the relay's Claude (docs/architecture/overview.md, "Pinned native doors"). Its folder is the native
+// sender's own (`<mail>/relays/<blake3(name)[..24]>/`, its record, settings and send log), so the native `message
+// watch`, which retires relays until step 4, reads what the daemon writes.
+import { mkdirSync, readFileSync, rmSync, utimesSync, watch, writeFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { join } from 'node:path';
+import { blake3Hex } from './envelope.mjs';
+
+/** Model name a relay's requests carry; the relay endpoint answers them without any model. */
+const RELAY_MODEL = 'haiku';
+/** Prefix marking a registry name as a relay rather than a session. */
+export const RELAY_NAME_PREFIX = 'sc-';
+/** How long a send waits for Claude's own receipt. */
+const SEND_TIMEOUT_MS = 90_000;
+/** Largest message relayed into a Claude session: the relay copies it into a model turn byte for byte. */
+export const MAX_RELAYED_BYTES = 100_000;
+
+const alive = (pid) => { if (!Number.isInteger(pid) || pid <= 0) return false; try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; } };
+const readJson = (path) => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; } };
+const shellQuote = (value) => `'${String(value).replaceAll("'", "'\\''")}'`;
+
+/** Registry name of the relay that represents `name` on `machine` (not `name@machine`: SendMessage refuses an `@`). */
+export function relayName(name, machine) {
+  const base = name.startsWith(RELAY_NAME_PREFIX) ? name.slice(RELAY_NAME_PREFIX.length) : name;
+  return `${RELAY_NAME_PREFIX}${base}-on-${machine}`;
+}
+
+/** The host turn asking a relay to make one send (claude_relay.rs `send_turn`). */
+const sendTurn = ({ to, message }) => `Send one message with SendMessage.\nto: ${to}\nmessage: the exact text between the markers, without the markers\n---BEGIN MESSAGE---\n${message}\n---END MESSAGE---`;
+
+/** Claude's answer as the relay's hooks wrote it (claude_relay.rs `read_receipt`): `{ delivered: true }` or `{ delivered:
+ *  false, detail }`. */
+export function readReceipt(value) {
+  if (typeof value?.denied === 'string') return { delivered: false, detail: `the relay's gate refused the send: ${value.denied}` };
+  if (typeof value?.send_failed === 'string') return { delivered: false, detail: `Claude Code refused the relay's send: ${value.send_failed.trim()}` };
+  if (value?.turn_ended === true) {
+    const said = typeof value.said === 'string' && value.said.trim() ? `; it said: ${value.said.trim()}` : '';
+    return { delivered: false, detail: `the Claude relay ended its turn without sending; nothing was sent${said}` };
+  }
+  let response = value?.tool_response ?? null;
+  if (typeof response === 'string') { try { response = JSON.parse(response); } catch { /* a text answer */ } }
+  else if (Array.isArray(response)) { const text = response.find((block) => typeof block?.text === 'string')?.text; if (text) { try { response = JSON.parse(text); } catch { /* as it is */ } } }
+  if (response?.success !== true) return { delivered: false, detail: `Claude did not report the send as successful: ${JSON.stringify(response)}` };
+  return { delivered: true, detail: typeof response.message === 'string' ? response.message : '', native_msg_id: typeof response.msg_id === 'string' ? response.msg_id : null };
+}
+
+export class Relays {
+  /**
+   * `serve(method, params, timeoutMs)` is one `harness.v1` request to this daemon's harness serve; `runtimeOf(harness,
+   * id)` the live-runtime receipt the live-session map holds for a runtime id (its file read whole), or null;
+   * `runtimeNamed(receiptId)` one receipt read by its own name.
+   */
+  constructor({ mailRoot, machine, supercodeBin, serve, runtimeOf, runtimeNamed = () => null }) {
+    Object.assign(this, { mailRoot, machine, supercodeBin, serve, runtimeOf, runtimeNamed });
+    this.sending = new Map(); // relay folder → the send in progress through it (one at a time per relay)
+  }
+
+  /** The relay that speaks for `represented`, known as `representedName`: its name and its files. */
+  spec(represented, representedName) {
+    const name = relayName(String(representedName).split('@')[0], String(represented).split(':')[1]);
+    const directory = join(this.mailRoot, 'relays', blake3Hex(name).slice(0, 24));
+    return {
+      represented, name, directory,
+      queue: join(directory, 'queue.json'), receipt: join(directory, 'receipt.json'), settings: join(directory, 'settings.json'),
+      record: join(directory, 'relay.json'), sent: join(directory, 'sent.json'),
+    };
+  }
+
+  /** The relay endpoint's base URL, when it answers (claude_relay.rs `relay_endpoint`; the native watch serves it until
+   *  step 4, its port in `<mail>/relay-endpoint.json`). */
+  async endpoint() {
+    const port = readJson(join(this.mailRoot, 'relay-endpoint.json'))?.port;
+    if (!Number.isInteger(port)) return null;
+    return (await answers(port)) ? `http://127.0.0.1:${port}` : null;
+  }
+
+  /** Settings installing a relay's hooks: its gate on every tool, its receipt on SendMessage and on a turn's end, and its
+   *  inbound filing (claude_relay.rs `relay_settings`). */
+  #settings(spec) {
+    const program = shellQuote(this.supercodeBin), directory = shellQuote(spec.directory), represented = shellQuote(spec.represented);
+    const command = (verb) => `${program} message ${verb} ${directory}`;
+    const receipt = { hooks: [{ type: 'command', command: command('relay-receipt') }] };
+    return {
+      hooks: {
+        PreToolUse: [{ matcher: '.*', hooks: [{ type: 'command', command: command('gate') }] }],
+        PostToolUse: [{ matcher: 'SendMessage', ...receipt }],
+        PostToolUseFailure: [{ matcher: 'SendMessage', ...receipt }],
+        Stop: [receipt],
+        StopFailure: [receipt],
+        UserPromptSubmit: [{ hooks: [{ type: 'command', command: `${program} message relay-inbound ${represented} ${directory}` }] }],
+      },
+    };
+  }
+
+  /** The relay's process: the runtime receipt's child, else its record's, so a relay that ended is seen. */
+  #pid(spec, runtime) {
+    const child = runtime?.metadata?.child_pid;
+    if (Number.isInteger(child)) return child;
+    const record = readJson(spec.record);
+    return record?.runtime_id === runtime?.runtime_session_id && Number.isInteger(record?.pid) ? record.pid : null;
+  }
+
+  /** The relay's runtime, started in this daemon's harness serve when it is not running (claude_relay.rs
+   *  `ensure_relay_runtime`): `{ runtime (its receipt), connection }`. */
+  async #ensure(spec) {
+    const endpoint = await this.endpoint();
+    if (!endpoint) throw new Error('the relay endpoint is not answering; the machine daemon\'s `supercode message watch` serves it (see mail/machine-daemon.log)');
+    // written on every send: Claude Code reloads a changed settings file, so a running relay takes the hooks this
+    // supercode installs
+    writeFileSync(spec.settings, JSON.stringify(this.#settings(spec), null, 2));
+    const record = readJson(spec.record);
+    if (record?.runtime_id) {
+      const runtime = this.runtimeOf('claude-code', record.runtime_id);
+      if (runtime && alive(this.#pid(spec, runtime)) && record.connection && (record.endpoint === endpoint || await answers(Number(String(record.endpoint ?? '').split(':').pop())))) {
+        return { runtime, connection: record.connection };
+      }
+      // closed through the owner's door even after its receipt went
+      try { await this.serve('harness.v1.runtimes.close', { connection: record.connection, runtime_id: record.runtime_id }, 15_000); }
+      catch (error) { if (this.runtimeOf('claude-code', record.runtime_id)) throw new Error(`could not retire the old relay: ${error.message}`); }
+    }
+    const key = spec.directory.split(/[\\/]/).pop();
+    const started = await this.serve('harness.v1.runtimes.start', {
+      harness: 'claude-code',
+      launch: {
+        program: 'claude',
+        arguments: ['--print', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose', '--permission-prompt-tool', 'stdio', '--model', RELAY_MODEL, '--name', spec.name, '--permission-mode', 'bypassPermissions', '--setting-sources', 'project', '--settings', spec.settings, '--tools', 'ListAgents,SendMessage', '--no-session-persistence'],
+        // its API is the relay endpoint, its key the relay's folder there (which also keeps account connectors out)
+        env: { ANTHROPIC_API_KEY: key, ANTHROPIC_BASE_URL: endpoint, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1', SUPERCODE_CLAUDE_RELAY: '1' },
+      },
+      cwd: spec.directory,
+    }, 60_000);
+    const runtimeId = started?.handle?.runtime_id;
+    if (typeof runtimeId !== 'string') throw new Error(`the machine daemon did not start the relay: ${JSON.stringify(started)}`);
+    const connection = typeof started.connection === 'string' ? started.connection : '';
+    const pid = Number.isInteger(started?.handle?.endpoint?.pid) ? started.handle.endpoint.pid : null;
+    writeFileSync(spec.record, JSON.stringify({ runtime_id: runtimeId, pid, endpoint, connection }));
+    // harness serve writes its receipt before it answers the start; the map learns it from its watch a moment later, so
+    // one it does not hold yet is read by its own name (the receipt the runtime's terminal launch opens), never waited on
+    const known = this.runtimeOf('claude-code', runtimeId);
+    if (known) return { runtime: known, connection };
+    let receiptId = null;
+    try {
+      const launch = (await this.serve('harness.v1.runtimes.terminal_instructions', { connection }, 5000))?.launch;
+      receiptId = (Array.isArray(launch?.arguments) ? launch.arguments : []).find((arg) => typeof arg === 'string' && arg.startsWith('supercode-live://'))?.slice('supercode-live://'.length) ?? null;
+    } catch { /* said below */ }
+    const runtime = receiptId ? this.runtimeNamed(receiptId) : null;
+    if (!runtime) throw new Error('the relay started but registered no live runtime');
+    return { runtime, connection };
+  }
+
+  /** Claude's receipt for the queued send, waited on by a watch of the relay's folder (and its process checked at least
+   *  every half second): a relay that ended or a send not confirmed within SEND_TIMEOUT_MS is said. */
+  #receipt(spec, pid) {
+    return new Promise((resolve) => {
+      let done = false, watcher = null, timer = null, deadline = null;
+      const finish = (answer) => { if (done) return; done = true; clearInterval(timer); clearTimeout(deadline); try { watcher?.close(); } catch { /* closed */ } resolve(answer); };
+      const check = () => {
+        const value = readJson(spec.receipt);
+        if (value) return finish(readReceipt(value));
+        if (pid && !alive(pid)) finish({ delivered: false, detail: 'the Claude relay process exited before confirming the send' });
+      };
+      try { watcher = watch(spec.directory, () => check()); watcher.on('error', () => {}); } catch { /* checked on the timer */ }
+      timer = setInterval(check, 500);
+      deadline = setTimeout(() => finish({ delivered: false, detail: `the Claude relay did not confirm the send within ${SEND_TIMEOUT_MS / 1000} seconds; it may still arrive` }), SEND_TIMEOUT_MS);
+      check();
+    });
+  }
+
+  /**
+   * Send `message` to the Claude session `receiver` (`{ sessionId, name, socket }`) from `sender` through its relay
+   * (claude_relay.rs `send_through_relay`): the receiver is named by its own socket (`uds:<path>`), unique to it, never
+   * by its name. One send at a time per relay; a relay whose process is proven dead is started again once.
+   */
+  async send(sender, senderName, receiver, message, messageId) {
+    const spec = this.spec(sender, senderName);
+    mkdirSync(spec.directory, { recursive: true });
+    const previous = this.sending.get(spec.directory) ?? Promise.resolve();
+    let release;
+    const mine = new Promise((resolve) => { release = resolve; });
+    const turn = previous.then(() => mine);
+    this.sending.set(spec.directory, turn);
+    await previous;
+    try {
+      // its record is the relay's last use: the native sweep that keeps the most recently used relays running reads its
+      // time, and a relay carrying a send is the most recent
+      try { const now = new Date(); utimesSync(spec.record, now, now); } catch { /* none yet */ }
+      const queued = { to: receiver.socket ? `uds:${receiver.socket}` : receiver.name, message };
+      let { runtime, connection } = await this.#ensure(spec);
+      rmSync(spec.receipt, { force: true });
+      writeFileSync(spec.queue, JSON.stringify(queued));
+      let receipt;
+      for (let attempt = 0; ; attempt++) {
+        try { await this.serve('harness.v1.runtimes.send_input', { connection, text: sendTurn(queued) }, 30_000); receipt = await this.#receipt(spec, this.#pid(spec, runtime)); }
+        catch (error) { receipt = { delivered: false, detail: `could not reach the Claude relay: ${error.message}` }; }
+        const pid = this.#pid(spec, runtime);
+        // only a relay proven dead is started again; one alive but slow may still deliver
+        if (receipt.delivered || attempt === 1 || pid == null || alive(pid)) break;
+        try { ({ runtime, connection } = await this.#ensure(spec)); } catch (error) { receipt = { delivered: false, detail: error.message }; break; }
+        rmSync(spec.receipt, { force: true });
+      }
+      rmSync(spec.queue, { force: true });
+      if (receipt.delivered) {
+        const sent = readJson(spec.sent) ?? {};
+        sent[receiver.sessionId] = messageId;
+        writeFileSync(spec.sent, JSON.stringify(sent));
+      }
+      return receipt;
+    } catch (error) {
+      rmSync(spec.queue, { force: true });
+      return { delivered: false, detail: error.message };
+    } finally {
+      release();
+      if (this.sending.get(spec.directory) === turn) this.sending.delete(spec.directory);
+    }
+  }
+}
+
+/** Whether a local port answers a connection within 300 ms. */
+function answers(port) {
+  if (!Number.isInteger(port) || port <= 0) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const socket = connect({ host: '127.0.0.1', port });
+    const timer = setTimeout(() => { socket.destroy(); resolve(false); }, 300);
+    socket.once('connect', () => { clearTimeout(timer); socket.end(); resolve(true); });
+    socket.once('error', () => { clearTimeout(timer); resolve(false); });
+  });
+}

package/mail/runtime.mjs

@@ -0,0 +1,20 @@
+// The default tier: a session supercode hosts as a runtime is reached through the runtime's own doors, the ones every
+// frontend uses: `steer` while a turn runs, `send_input` to start one (crates/harness/src/runtime_mail.rs). The text is
+// the rendered envelope. The bearer token is read from the runtime's receipt at the delivery, never kept.
+import { FrontendClient } from '@volter/supercode-frontend';
+
+/** Deliver `text` into the hosted runtime `receipt` names: steered into a running turn, or a turn started when `wake`
+ *  (an idle runtime is left alone otherwise). Answers 'steered', 'started' or 'not_woken'. */
+export async function deliverToRuntime(receipt, text, wake) {
+  const client = new FrontendClient({ baseUrl: receipt.base_url, token: receipt.token, clientId: `mail-${receipt.receipt_id}`, permissions: ['observe', 'interact'] });
+  const descriptor = await client.describe();
+  if (descriptor.session_id !== receipt.runtime_session_id) throw new Error('the live runtime\'s identity did not match its receipt');
+  if (descriptor.turn_state === 'busy') {
+    if (!descriptor.actions?.steer) throw new Error('a turn is running and this runtime does not accept steering; the message was not delivered into it');
+    await client.steer(text);
+    return 'steered';
+  }
+  if (!wake) return 'not_woken';
+  await client.sendInput(text);
+  return 'started';
+}