@volter/supercode-teams 0.3.85 → 0.3.87

package/mail/transcript.mjs

@@ -0,0 +1,287 @@
+// What a session's transcript says about its mail (crates/harness/src/mail_transcript.rs, ported line for line): the
+// lines its own user typed, the lines it took from its harness's own channels, its answers, and when each filed message
+// first reached the model. The mailbox records a message as sent; only the transcript records it delivered. A transcript
+// is read only when a call names the message or the session it is about (one named read, never a sweep).
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { blake3Hex } from './envelope.mjs';
+
+// A transcript is read off the daemon's event loop (its file read awaited) and parsed in turns of YIELD_LINES lines: one
+// large session's history never holds every other door while it is read.
+const YIELD_LINES = 2000;
+const yieldTurn = () => new Promise((resolve) => setImmediate(resolve));
+
+const TYPED_ID_PREFIX = 'u-';
+const CHANNEL_ID_PREFIX = 'c-';
+const ANSWER_ID_PREFIX = 'a-';
+
+/** The id of a line the user of the session at `address` typed at `sentAtMs`: `u-` and 24 hex digits. */
+export const typedLineId = (address, sentAtMs, text) => `${TYPED_ID_PREFIX}${blake3Hex(`${address}\n${sentAtMs}\n${text}`).slice(0, 24)}`;
+/** The id of the channel line with `header` in the session at `address`. */
+export const channelLineId = (address, header) => `${CHANNEL_ID_PREFIX}${blake3Hex(`${address}\n${header}`).slice(0, 24)}`;
+/** The id of the answer the transcript entry `nativeId` records in the session at `address`. */
+export const answerId = (address, nativeId) => `${ANSWER_ID_PREFIX}${blake3Hex(`${address}\n${nativeId}`).slice(0, 24)}`;
+
+/** An RFC 3339 time as epoch milliseconds (0 when it is not one): the native binary's own reading of a stamp. */
+function atMs(value) {
+  if (typeof value !== 'string') return 0;
+  const match = /^(\d+)-(\d+)-(\d+)T(\d+):(\d+):(\d+)(?:\.(\d+))?Z?$/.exec(value.trim());
+  if (!match) return 0;
+  const [, y, mo, d, h, mi, s, fraction] = match;
+  const millis = fraction ? Number(fraction.slice(0, 3).padEnd(3, '0')) : 0;
+  const ms = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s), millis);
+  return Number.isFinite(ms) && ms > 0 ? ms : 0;
+}
+
+/** A prompt's words: a string, or its text parts joined; none when blank. */
+function promptText(content) {
+  let text;
+  if (typeof content === 'string') text = content;
+  else if (Array.isArray(content)) text = content.filter((part) => part?.type === 'text' && typeof part.text === 'string').map((part) => part.text).join('\n');
+  else return null;
+  return text.trim() ? text : null;
+}
+
+/** The channel lines in a prompt, each from its `[channel: …]` header to the next. */
+function channelLines(text, fallbackMs, deliveredAtMs) {
+  const starts = [];
+  for (let at = text.indexOf('[channel: '); at >= 0; at = text.indexOf('[channel: ', at + 1)) if (at === 0 || text[at - 1] === '\n') starts.push(at);
+  const lines = [];
+  starts.forEach((start, n) => {
+    const end = starts[n + 1] ?? text.length;
+    const line = text.slice(start, end).trimEnd();
+    const close = line.indexOf(']');
+    if (close < 0) return;
+    const header = line.slice(0, close + 1);
+    const field = (name) => { const part = header.split(' · ').find((item) => item.startsWith(name)); return part === undefined ? null : part.slice(name.length).replace(/\]+$/, '').trim(); };
+    const sent = field('at: ');
+    lines.push({ header, from: field('from: ') ?? 'a channel', sent_at_ms: (sent !== null && atMs(sent)) || fallbackMs, delivered_at_ms: deliveredAtMs, text: line });
+  });
+  return lines;
+}
+
+/** Mail ids rendered into a Claude transcript line: the envelope's own (escaped once) or the relay's `(message m-…)`. */
+function renderedMailIds(line) {
+  const ids = [];
+  for (const mark of ['cross-session-message id=\\"', '(message ']) {
+    for (let at = line.indexOf(mark); at >= 0; at = line.indexOf(mark, at + 1)) {
+      const rest = line.slice(at + mark.length);
+      const id = /^[A-Za-z0-9-]*/.exec(rest)[0];
+      if (id.startsWith('m-')) ids.push(id);
+    }
+  }
+  return ids;
+}
+
+/** Whether a line a harness queued is machine-made on its face. */
+const machineMade = (text) => text.includes('<cross-session-message') || text.startsWith('[Cross-session') || text.startsWith('[channel: ') || text.startsWith('<task-notification>');
+
+/** Read a Claude Code transcript for its typed lines, channel lines, answers and delivered mail (`read_claude`). */
+export async function readClaude(path) {
+  const mail = { typed: [], answers: [], channel: [], delivered: new Map() };
+  const queued = []; // [words, index of mail.typed or null]
+  let dequeued = 0;
+  const absorbed = [];
+  const take = (waiting, text) => { const at = waiting.findIndex(([words]) => words === text); if (at < 0) return undefined; return waiting.splice(at, 1)[0][1]; };
+  const notTyped = new Set();
+  const takenIn = new Map(); // words → [times]
+  const early = []; // [words, ids, index, at]
+  const deliver = (id, at) => { if (!mail.delivered.has(id)) mail.delivered.set(id, at); };
+  const lines = (await readFile(path, 'utf8')).split('\n');
+  for (let index = 0; index < lines.length; index++) {
+    if (index && index % YIELD_LINES === 0) await yieldTurn();
+    const line = lines[index];
+    const prompt = line.includes('"promptSource"') || line.includes('"type":"user"');
+    const queue = line.includes('"queue-operation"');
+    const attachment = line.includes('"queued_command"');
+    const answer = line.includes('"stop_reason":"end_turn"') || line.includes('"stop_reason":"stop_sequence"');
+    const rendered = line.includes('cross-session-message id=') || line.includes('(message m-');
+    if (!(prompt || queue || attachment || rendered || answer)) continue;
+    let record; try { record = JSON.parse(line); } catch { continue; }
+    if (record?.isSidechain === true) continue;
+    const kind = typeof record.type === 'string' ? record.type : '';
+    let at = atMs(record.timestamp);
+    if (kind === 'queue-operation' && record.operation === 'remove' && typeof record.content === 'string') {
+      const found = early.findIndex(([words]) => words === record.content);
+      if (found >= 0) {
+        const [, ids, index] = early.splice(found, 1)[0];
+        for (const id of ids) deliver(id, at);
+        if (index !== null && index !== undefined) mail.typed[index].delivered_at_ms = at;
+        continue;
+      }
+      if (!takenIn.has(record.content)) takenIn.set(record.content, []);
+      takenIn.get(record.content).push(at);
+    }
+    let waitsForRemove = false;
+    if (kind === 'attachment' && record.attachment?.type === 'queued_command') {
+      const taken = typeof record.attachment.prompt === 'string' ? takenIn.get(record.attachment.prompt)?.shift() : undefined;
+      if (taken !== undefined) at = taken; else waitsForRemove = true;
+    }
+    if (waitsForRemove) {
+      const attached = record.attachment;
+      const words = typeof attached.prompt === 'string' ? attached.prompt : '';
+      const human = attached.origin?.kind === 'human' || attached.humanTurn === true;
+      const ids = renderedMailIds(line);
+      let index = null;
+      const took = take(queued, words);
+      if (took !== undefined) {
+        if (took !== null && !human) notTyped.add(took);
+        else index = took;
+      } else if (human && words.trim()) {
+        mail.typed.push({ sent_at_ms: at, delivered_at_ms: null, withdrawn: false, text: words });
+        index = mail.typed.length - 1;
+      }
+      early.push([words, ids, index, at]);
+      continue;
+    }
+    if (rendered && (kind === 'user' || kind === 'attachment')) for (const id of renderedMailIds(line)) deliver(id, at);
+    if (kind === 'assistant' && answer && ['end_turn', 'stop_sequence'].includes(record.message?.stop_reason)) {
+      const words = promptText(record.message?.content);
+      if (typeof record.uuid === 'string' && words !== null) mail.answers.push({ native_id: record.uuid, at_ms: at, text: words });
+      continue;
+    }
+    if (kind === 'queue-operation' && record.operation === 'dequeue') { dequeued += 1; continue; }
+    if (kind === 'queue-operation') {
+      if (typeof record.content !== 'string') continue;
+      const words = record.content;
+      if (record.operation === 'enqueue') {
+        let index = null;
+        if (!machineMade(words) && words.trim()) { mail.typed.push({ sent_at_ms: at, delivered_at_ms: null, withdrawn: false, text: words }); index = mail.typed.length - 1; }
+        queued.push([words, index]);
+      } else if (record.operation === 'remove') {
+        const index = take(queued, words);
+        if (index === undefined) continue;
+        if (['absorbed_mid_turn', 'delivered_to_agent'].includes(record.reason)) {
+          if (index !== null) mail.typed[index].delivered_at_ms = at;
+          absorbed.push([words, index]);
+        } else if (index !== null) mail.typed[index].withdrawn = true;
+      }
+      continue;
+    }
+    if (kind === 'attachment') {
+      const attached = record.attachment ?? {};
+      const words = attached.prompt;
+      if (typeof words !== 'string' || attached.type !== 'queued_command' || !words.trim()) continue;
+      const human = attached.origin?.kind === 'human' || attached.humanTurn === true;
+      const took = take(absorbed, words);
+      if (took !== undefined) { if (took !== null && !human) notTyped.add(took); }
+      else if (human) mail.typed.push({ sent_at_ms: Math.min(atMs(attached.timestamp), at), delivered_at_ms: at, withdrawn: false, text: words });
+      continue;
+    }
+    if (kind === 'user') {
+      const words = promptText(record.message?.content);
+      if (words === null) continue;
+      const human = ['typed', 'queued'].includes(record.promptSource) && record.isMeta !== true;
+      if (!human) mail.channel.push(...channelLines(words, at, at));
+      const landing = [];
+      const letGo = dequeued; dequeued = 0;
+      if (letGo === 0) { const took = take(queued, words); if (took !== undefined) landing.push(took); }
+      while (landing.length < letGo) {
+        const found = queued.findIndex(([queuedWords]) => words.includes(queuedWords));
+        if (found < 0) break;
+        landing.push(queued.splice(found, 1)[0][1]);
+      }
+      if (!landing.length && letGo > 0) for (let n = 0; n < letGo; n++) { const head = queued.shift(); if (head) landing.push(head[1]); }
+      if (landing.length) {
+        for (const index of landing) { if (index === null) continue; if (human) mail.typed[index].delivered_at_ms = at; else notTyped.add(index); }
+        continue;
+      }
+      if (human) mail.typed.push({ sent_at_ms: at, delivered_at_ms: at, withdrawn: false, text: words });
+    }
+  }
+  for (const [, ids, index, at] of early) {
+    for (const id of ids) deliver(id, at);
+    if (index !== null && index !== undefined) mail.typed[index].delivered_at_ms ??= at;
+  }
+  for (const [words] of queued) if (words.startsWith('[channel: ')) mail.channel.push(...channelLines(words, 0, null));
+  mail.typed = mail.typed.filter((_, index) => !notTyped.has(index));
+  return mail;
+}
+
+/** Mail ids rendered into a Codex rollout line, its quote escaped once or more. */
+function codexRenderedMailIds(line) {
+  const ids = [];
+  const mark = 'cross-session-message id=';
+  for (let at = line.indexOf(mark); at >= 0; at = line.indexOf(mark, at + 1)) {
+    const rest = line.slice(at + mark.length).replace(/^[\\"]+/, '');
+    const id = /^[A-Za-z0-9-]*/.exec(rest)[0];
+    if (id.startsWith('m-')) ids.push(id);
+  }
+  return ids;
+}
+
+/** Final answers and delivered mail from a Codex session's own transcript (`read_codex_answers`). */
+export async function readCodex(path) {
+  const mail = { typed: [], answers: [], channel: [], delivered: new Map() };
+  const lines = (await readFile(path, 'utf8')).split('\n');
+  for (let index = 0; index < lines.length; index++) {
+    if (index && index % YIELD_LINES === 0) await yieldTurn();
+    const line = lines[index];
+    const rendered = line.includes('cross-session-message id=');
+    if (!rendered && !line.includes('"final_answer"')) continue;
+    let record; try { record = JSON.parse(line); } catch { continue; }
+    const item = record?.payload ?? {};
+    if (rendered && record.type === 'response_item' && ((item.type === 'message' && item.role === 'user') || ['function_call_output', 'custom_tool_call_output'].includes(item.type))) {
+      const at = atMs(record.timestamp);
+      for (const id of codexRenderedMailIds(line)) if (!mail.delivered.has(id)) mail.delivered.set(id, at);
+    }
+    if (record.type !== 'response_item' || item.type !== 'message' || item.role !== 'assistant' || item.phase !== 'final_answer' || typeof item.id !== 'string') continue;
+    const words = (Array.isArray(item.content) ? item.content : []).filter((part) => part?.type === 'output_text' && typeof part.text === 'string').map((part) => part.text).join('\n');
+    if (words) mail.answers.push({ native_id: item.id, at_ms: atMs(record.timestamp), text: words });
+  }
+  return mail;
+}
+
+/** The transcript of the session at `address` on this machine, when its harness's records are read here. */
+export function transcriptPath(address, { claudeProjects, mailRoot }) {
+  const [, , harness, sessionId] = String(address).split(':');
+  if (harness === 'codex') {
+    try { return JSON.parse(readFileSync(join(mailRoot, 'native-questions', `binding-${blake3Hex(address)}.json`), 'utf8')).transcript_path ?? null; }
+    catch { return null; }
+  }
+  if (harness !== 'claude-code') return null;
+  const file = `${sessionId}.jsonl`;
+  for (const roots of claudeProjects) {
+    let projects = [];
+    try { projects = readdirSync(roots); } catch { continue; }
+    for (const project of projects) { const path = join(roots, project, file); try { if (statSync(path).isFile()) return path; } catch { /* not here */ } }
+  }
+  return null;
+}
+
+/** The transcript's reading of the session at `address`, when it can be read (`mail_transcript::read`). */
+export async function readTranscript(address, homes) {
+  const path = transcriptPath(address, homes);
+  if (!path) return null;
+  try { return await (String(address).split(':')[2] === 'codex' ? readCodex(path) : readClaude(path)); } catch { return null; }
+}
+
+/** Where each of `stored` (the mailbox of the session at `address`) stands, by id, as the transcript reading `mail`
+ *  shows it (`deliveries`). `deliveredAt(envelope)` is a native question reply's own delivery. */
+export function deliveries(address, stored, mail, deliveredAt) {
+  const result = new Map();
+  if (!mail) {
+    for (const { envelope } of stored) { const at = deliveredAt(envelope); result.set(envelope.id, at !== null ? { state: 'delivered', at_ms: at } : { state: 'unknown' }); }
+    return result;
+  }
+  const typed = new Map(mail.typed.map((line) => [typedLineId(address, line.sent_at_ms, line.text), line]));
+  const channel = new Map(mail.channel.map((line) => [channelLineId(address, line.header), line]));
+  const used = new Set();
+  const short = (id) => { const at = id.indexOf('-'); return at >= 0 && id.length - at - 1 > 8 ? id.slice(0, at + 9) : id; };
+  for (const { envelope } of stored) {
+    const line = typed.get(envelope.id);
+    if (line?.withdrawn) { result.set(envelope.id, { state: 'withdrawn' }); continue; }
+    let at;
+    if (line) at = line.delivered_at_ms;
+    else if (channel.has(envelope.id)) at = channel.get(envelope.id).delivered_at_ms;
+    else if (mail.delivered.has(envelope.id) || mail.delivered.has(short(envelope.id))) at = mail.delivered.get(envelope.id) ?? mail.delivered.get(short(envelope.id));
+    else if (envelope.kind === 'user' && typeof envelope.in_reply_to === 'string' && envelope.in_reply_to.startsWith('q-')) at = deliveredAt(envelope);
+    else if (envelope.kind === 'user') {
+      const index = mail.typed.findIndex((typedLine, n) => !used.has(n) && typedLine.sent_at_ms + 1000 >= envelope.created_at_ms && typedLine.text.trim() === String(envelope.body ?? '').trim());
+      if (index >= 0) { used.add(index); at = mail.typed[index].delivered_at_ms; }
+    }
+    result.set(envelope.id, at !== null && at !== undefined ? { state: 'delivered', at_ms: at } : { state: 'sent' });
+  }
+  return result;
+}

package/mail/verbs.mjs

@@ -0,0 +1,232 @@
+// An agent's verbs (docs/architecture/overview.md, "The mail operations", 3b-2): reading a conversation (`message
+// thread`), listing an agent's threads (`message threads`), handing a root to a new session of the agent (`message
+// delegate`), and declaring or showing an agent (`supercode agent declare|show`), answered by the daemon as
+// crates/cli/src/message.rs answered them, their texts kept. Each read answers from the header index; a body is read from
+// its one file when its message is shown.
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { listed, messageRow, rfc3339, shortId } from './envelope.mjs';
+import { makeAddress, parseAddress, threadOf } from './compose.mjs';
+
+export const EXIT_REFUSED = 2;
+export const EXIT_UNKNOWN = 3;
+export const EXIT_FAILED = 5;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export class AgentVerbs {
+  /** `machine` this machine's name; `store` the mail store; `agents` an agent's records; `live` the live-session map;
+   *  `supercodeBin` the native binary (`supercode open` starts a session in a pane); `paneOf(session)` the daemon pane a
+   *  live session runs in; `mailRoot` the mail folder. */
+  constructor({ machine, store, agents, live, supercodeBin, env = process.env, paneOf, mailRoot }) {
+    Object.assign(this, { machine, store, agents, live, supercodeBin, env, paneOf, mailRoot });
+  }
+
+  #whole(stored) { const envelope = this.store.body(stored); return envelope ? { ...stored, envelope } : null; }
+
+  // ---- message thread -------------------------------------------------------------------------------------------
+
+  /**
+   * The conversation a message belongs to, oldest first (message.rs `thread`): every message here is a node, a reply's
+   * `in_reply_to` its edge to what it answers, and a stored thread id joins a message whose parent is not filed here.
+   * Answers `{ code, rows, rendered }` or `{ code, text }`.
+   */
+  thread(id) {
+    const all = new Map(); // id → { address, stored }
+    for (const address of this.store.addresses()) {
+      for (const stored of this.store.inventory(address).stored) if (!all.has(stored.envelope.id)) all.set(stored.envelope.id, { address, stored });
+    }
+    const matches = [...all.keys()].filter((key) => key.startsWith(id));
+    if (matches.length !== 1) return { code: EXIT_UNKNOWN, text: `${id} names ${matches.length} messages here; give one message's id.` };
+    // up to the root: the oldest ancestor filed here
+    let root = matches[0];
+    const seen = new Set();
+    for (;;) {
+      const parent = all.get(root)?.stored.envelope.in_reply_to;
+      if (!parent || !all.has(parent) || seen.has(parent)) break;
+      seen.add(parent); root = parent;
+    }
+    const threadOfRoot = threadOf(all.get(root).stored.envelope);
+    // down from the root: every reply, and every message naming the same thread
+    const children = new Map();
+    for (const [key, { stored }] of all) {
+      const parent = stored.envelope.in_reply_to;
+      if (parent) children.set(parent, [...(children.get(parent) ?? []), key]);
+    }
+    const members = new Set();
+    const queue = [root, ...[...all].filter(([, { stored }]) => stored.envelope.thread === threadOfRoot).map(([key]) => key)];
+    while (queue.length) {
+      const next = queue.pop();
+      if (members.has(next)) continue;
+      members.add(next);
+      queue.push(...(children.get(next) ?? []));
+    }
+    const conversation = [...members].map((key) => all.get(key)).map(({ address, stored }) => ({ address, stored: this.#whole(stored) })).filter((item) => item.stored)
+      .sort((a, b) => a.stored.envelope.created_at_ms - b.stored.envelope.created_at_ms);
+    const deliveries = new Map();
+    return {
+      code: 0,
+      rows: conversation.map(({ address, stored }) => messageRow(address, stored, deliveries, this.mailRoot)),
+      rendered: conversation.map(({ address, stored }) => `To ${address}:\n${listed(stored.envelope, deliveries, this.mailRoot)}\n`),
+    };
+  }
+
+  // ---- message threads ------------------------------------------------------------------------------------------
+
+  /** An agent's threads, oldest first (message.rs `threads`): the agent named, else the caller's own agent. */
+  threads(agent, caller) {
+    let name = agent;
+    if (!name) {
+      name = caller ? this.agents.agentOfSession(caller)?.name : null;
+      if (!name) return { code: EXIT_REFUSED, text: 'Name the agent with --agent: this session is not one of an agent\'s.' };
+    }
+    const threads = this.agents.threadsOf(name);
+    // every root's first line from the index in one pass: no walk of the index per thread, no body read
+    const roots = this.store.firstLines(threads.map((thread) => thread.id));
+    const rows = threads.map((thread) => ({
+      id: thread.id, holder: thread.holder,
+      participants: thread.participants.map((p) => ({ address: p.address, role: p.role })),
+      surface: thread.surface ?? null, opened_at: rfc3339(thread.created_at_ms),
+      root: roots.has(thread.id) ? roots.get(thread.id) : null,
+    }));
+    const text = rows.length
+      ? rows.map((row) => `${shortId(row.id)}  opened ${row.opened_at}  held by ${row.holder}\n  ${row.participants.map((p) => `${p.address} (${p.role})`).join(', ')}\n  ${row.root ?? '(no root message)'}`).join('\n')
+      : `Agent ${name} has no threads.`;
+    return { code: 0, rows, text };
+  }
+
+  // ---- a new session of an agent ----------------------------------------------------------------------------------
+
+  /**
+   * Start `program` in a new pane in `directory`, typed `input` once ready, and answer the session it runs (message.rs
+   * `open_session`): a Claude session is given its id up front, so `ready(address)` runs before it starts; another is
+   * found in the live-session map by the pane it opened in, within a minute.
+   */
+  async openSession(program, directory, key, input, ready) {
+    const stem = String(program).split(/[\\/]/).pop().replace(/\.[^.]*$/, '');
+    const claude = stem === 'claude' || stem === 'claude-code';
+    let known = null;
+    const extra = [];
+    if (claude) {
+      const bytes = randomBytes(16);
+      bytes[6] = (bytes[6] & 0x0f) | 0x40; bytes[8] = (bytes[8] & 0x3f) | 0x80;
+      const hex = bytes.toString('hex');
+      const id = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+      known = makeAddress(this.machine, 'claude-code', id);
+      extra.push('--', '--session-id', id);
+      await ready(known);
+    }
+    const run = await new Promise((resolve) => {
+      const child = spawn(this.supercodeBin, ['--cwd', directory, 'open', '--new', program, '--key', key, '--input', input, '--detach', ...extra], { stdio: ['ignore', 'pipe', 'pipe'], env: this.env });
+      let out = '', err = '';
+      child.stdout.on('data', (chunk) => { out += chunk; });
+      child.stderr.on('data', (chunk) => { err += chunk; });
+      child.on('error', (error) => resolve({ code: 1, out, err: error.message }));
+      child.on('close', (code) => resolve({ code, out, err }));
+    });
+    if (run.code !== 0) throw new Error(`the session did not start: ${run.err.trim()}`);
+    if (known) return known;
+    let pane = null;
+    try { pane = JSON.parse(run.out).pane; } catch { /* not reported */ }
+    if (typeof pane !== 'string') throw new Error('the new pane was not reported');
+    const started = Date.now();
+    while (Date.now() - started < 60_000) {
+      const session = this.live.sessions().find((row) => this.paneOf(row) === pane);
+      if (session) { await ready(session.address); return session.address; }
+      await sleep(500);
+    }
+    throw new Error(`${program} started in pane ${pane}, but no session appeared there within a minute`);
+  }
+
+  /**
+   * Hand a root the caller received as an agent's main session to a new session of the agent (message.rs `delegate`):
+   * it opens in a pane with the root, holds the thread (every reply wakes it), and main stays CC. Answers `{ code, text }`.
+   */
+  async delegate(caller, root, { folder = null, harness = null } = {}) {
+    const found = this.store.findPrefixIn(caller, root);
+    if (found.length !== 1) return { code: EXIT_REFUSED, text: `Not delegated: ${root} names ${found.length} messages in your mailbox. Name the root as your inbox shows it.` };
+    const stored = found[0].envelope;
+    const threadId = threadOf(stored);
+    // a line in main's own session (its terminal, its DM) is a root of the agent: main opens its thread to delegate it
+    const thread = this.agents.thread(threadId) ?? await this.agents.rootOfMain(caller, stored);
+    if (!thread) return { code: EXIT_REFUSED, text: `Not delegated: ${shortId(stored.id)} is not in a thread of an agent. Only a root an agent received can be delegated.` };
+    const agent = this.agents.load(thread.agent);
+    if (!agent) return { code: EXIT_REFUSED, text: `Not delegated: agent ${thread.agent} is no longer declared.` };
+    if (agent.main_session !== caller || thread.holder !== caller) return { code: EXIT_REFUSED, text: `Not delegated: only ${agent.name}'s main session delegates a thread it holds.` };
+    const program = harness ?? agent.harness ?? 'claude';
+    const directory = folder ?? agent.folder ?? null;
+    if (!directory) return { code: EXIT_FAILED, text: 'Not delegated: no directory to start the session in (give --folder, or declare the agent with one).' };
+    const shownRoot = shortId(thread.id);
+    const input = `You are a session of agent ${agent.name}, holding its thread ${shownRoot}. Read it: supercode message thread ${shownRoot}. Answer in it with supercode message reply <id>; what you send stays in this thread, and ${agent.name}'s main session is CC on it.`;
+    // the new session holds the thread and has its messages before it starts, so its first turn finds its root
+    const handOver = async (holder) => {
+      for (const line of this.store.inventory(caller).stored) {
+        if (threadOf(line.envelope) !== thread.id) continue;
+        const whole = this.#whole(line);
+        if (!whole) continue;
+        // a line typed into main's terminal reaches the holder as one typed in another session (`typed`, ADR 0008)
+        const envelope = whole.envelope.kind === 'user' ? { ...whole.envelope, kind: 'typed' } : whole.envelope;
+        this.store.deliverRead(holder, envelope);
+      }
+      await this.agents.delegateTo(thread.id, holder, true);
+    };
+    let holder;
+    try { holder = await this.openSession(program, directory, `delegate:${thread.id}`, input, handOver); }
+    catch (error) {
+      // the thread goes back to main, so nothing waits on a session that never started
+      await this.agents.delegateTo(thread.id, caller, false);
+      return { code: EXIT_FAILED, text: `Not delegated: ${error.message}` };
+    }
+    const sessionId = parseAddress(holder).session;
+    return { code: 0, text: `Delegated thread ${shownRoot} to a new session of ${agent.name} (${holder}) in ${directory}. You are CC on it. Continue there: supercode open ${sessionId}` };
+  }
+
+  // ---- supercode agent declare | show ---------------------------------------------------------------------------
+
+  /** Declare an agent, or replace its record (message.rs `run_agent` Declare): its main session an address, a name
+   *  running here, or one started (`open`) when the declared main is neither running nor resumable. */
+  async declare({ name, main = null, open = null, input = null, folder = null, harness = null, idle_minutes = null, owners_account_manager = false }) {
+    const directory = folder ? (() => { try { return realpathSync(folder); } catch { return null; } })() : null;
+    if (folder && !directory) return { code: 1, text: `${folder}: no such directory` };
+    let mainSession = main;
+    if (!mainSession) {
+      if (!open) return { code: EXIT_REFUSED, text: 'Name its main session with --main, or start one with --open.' };
+      const kept = this.agents.load(name)?.main_session ?? null;
+      const live = kept && this.live.sessions().some((row) => row.address === kept);
+      if (kept && (live || await this.agents.resumable(kept))) mainSession = kept;
+      else {
+        const first = input ?? `You are the main session of agent ${name}. Roots addressed to it reach you: answer each or delegate it (supercode message delegate).`;
+        try { mainSession = await this.openSession(open, directory ?? process.cwd(), `agent:${name}`, first, async () => {}); }
+        catch (error) { return { code: EXIT_FAILED, text: `Not declared: ${error.message}` }; }
+      }
+    }
+    if (!parseAddress(mainSession)) {
+      const sessions = this.live.sessions();
+      const wanted = mainSession.split('@')[0];
+      const matching = sessions.filter((row) => row.name.split('@')[0] === wanted);
+      if (matching.length !== 1) return { code: EXIT_UNKNOWN, text: matching.length ? `${mainSession} names ${matching.length} sessions here; give its address.` : `No session named "${mainSession}" is reachable. Run supercode message list. Nothing was sent.` };
+      mainSession = matching[0].address;
+    }
+    try {
+      this.agents.declare({ name, main_session: mainSession, folder: directory, harness, idle_minutes });
+      if (owners_account_manager) this.agents.setOwnersAccountManager(name);
+    } catch (error) { return { code: 1, text: error.message }; }
+    return { code: 0, text: `Declared agent ${name} (${makeAddress(this.machine, 'agent', name)}): roots go to ${mainSession}.${owners_account_manager ? ' It is the owner\'s account manager.' : ''}` };
+  }
+
+  /** One declared agent, or all of them (message.rs `run_agent` Show). */
+  show(name) {
+    let agents;
+    if (name) {
+      const agent = this.agents.load(name);
+      if (!agent) return { code: EXIT_UNKNOWN, text: `No agent named ${name} is declared on this machine.` };
+      agents = [agent];
+    } else agents = this.agents.all();
+    const manager = this.agents.ownersAccountManager()?.name ?? null;
+    const text = agents.length
+      ? agents.map((agent) => `${agent.name}  ${makeAddress(this.machine, 'agent', agent.name)}\n  main: ${agent.main_session}\n  folder: ${agent.folder ?? '(none)'}\n  threads: ${this.agents.threadsOf(agent.name).length}${manager === agent.name ? '\n  the owner\'s account manager' : ''}`).join('\n')
+      : 'No agents are declared on this machine.';
+    return { code: 0, agents, text };
+  }
+}

package/mail-history.mjs

@@ -67,7 +67,7 @@ export function machineName(env) {
 export async function readMailHistory({ mail, env, harness, session }) {
   if (!/^[a-z0-9-]+$/.test(harness) || !/^[a-zA-Z0-9_-]+$/.test(session)) throw new Error('invalid session address');
   const address = `sc:${machineName(env)}:${harness}:${session}`;
-  const rows = mail.inboxRows(address, 100).filter(row => ['peer', 'channel'].includes(row.envelope?.kind));
+  const rows = (await mail.inboxRows(address, 100)).filter(row => ['peer', 'channel'].includes(row.envelope?.kind));
   const [sessions, answered] = await Promise.all([sessionDirectory(mail), answeredMail(rows, mail)]);
   return mailActors(rows, sessions, address, answered);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-teams",
-  "version": "0.3.85",
+  "version": "0.3.87",
   "type": "module",
   "description": "A machine daemon serving this machine's doors, and a local or remote Teams server for shared session discovery, OpenTelemetry ingestion and access to enrolled machines.",
   "license": "MIT",
@@ -51,6 +51,7 @@
     "server",
     "worker",
     "connector",
+    "mail",
     "contracts",
     "remote",
     "README.md"