@volter/supercode-orchestrator 0.5.9 → 0.5.10

package/README.md

@@ -318,6 +318,16 @@ daemon start attaches the `rh2` channel for that profile. Uninstalling in RH2 re
 the channel stops. A `platforms: rh2` block grants no integration authority and the runtime reports
 it as unsupported. Native Hermes channel configuration remains the worker's configuration.
 
+A mail agent the RH2 organization declares is one participant there, as its own agent principal: an admin issues that
+agent a token at RH2's agent-token door, and the home keeps it for the agent's channel, which then joins its Room's
+conversation answering every line:
+
+```sh
+supercode orchestrator apps install rh2-agent --origin https://pilot.runhuman.com --organization volter \
+  --principal prn_… --token-file ./account-manager.token --profile account-manager
+supercode orchestrator apps remove rh2-agent.account-manager
+```
+
 **The Chat SDK sidecar** mounts `chat@4.39.0` (npm package `chat`, repo `vercel/chat`; a
 devDependency of this package, installed alongside `@chat-adapter/state-memory@4.39.0`). The
 platform packages (`@chat-adapter/slack`, …) are **not** dependencies: the one the block names is

package/activation.mjs

@@ -206,7 +206,10 @@ export const APPROVAL_POLICY = Object.freeze({ codex: 'untrusted' });
  * policy on `thread/start` and its sandbox as a launch override.
  */
 export const OPEN_POLICY = Object.freeze({ codex: 'never' });
-export const OPEN_ARGUMENTS = Object.freeze({ codex: ['-c', 'sandbox_mode="danger-full-access"'] });
+// Claude Code takes its open policy at launch (its permission mode), as supercode's relay runs it: with approvals off a
+// dispatched Claude worker otherwise asks for every tool and, with nobody attending, is denied (measured: the review
+// World's Claude coder could not run one command).
+export const OPEN_ARGUMENTS = Object.freeze({ codex: ['-c', 'sandbox_mode="danger-full-access"'], 'claude-code': ['--permission-mode', 'bypassPermissions'] });
 
 const approvalsOff = (profile) => String(profile?.residue?.config?.approvals?.mode ?? 'manual').trim().toLowerCase() === 'off';
 

package/adapters/agent-mailbox.mjs

@@ -0,0 +1,124 @@
+// A channel carried to an agent's one mailbox (docs/adr/0008-agent-mailbox.md, decisions 15 and 16).
+//
+// Any channel adapter (connect(emit) / send(target, content)) is the transport. Each line a person posts is filed as
+// channel mail to the agent (`harness.v1.sessions.message` to `{harness: 'agent', session_id: <name>}`), with the
+// platform's id as its marker and, for a reply, its parent's id as its reply marker: the mailbox makes a line with no
+// known parent a root, which goes to the agent's main session, and puts a reply in its parent's thread, which reaches
+// every participant. This bridge's own mailbox (`fromName`) is a participant of every thread it opens, so the agent's
+// answers are filed there; each is posted back anchored at its thread's root, so the agent never posts directly in
+// the channel. Where a thread's root was posted, and which root each posted answer belongs to, is kept in `state` (a
+// JSON file when `statePath` is given), so answers find their anchor after a restart, and a person's reply to one of the
+// agent's answers (whose platform id the mailbox never saw) is filed in that answer's thread.
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const DEFAULT_POLL_MS = 2000;
+const ANSWER_MEMORY = 2000;
+
+export class AgentMailboxBridge {
+  constructor({ adapter, client, agent, platform = adapter?.platform ?? 'channel', fromName = `${platform}-channel`, statePath = null, log = () => {}, pollMs = DEFAULT_POLL_MS, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+    if (!adapter || !client || !agent) throw new Error('AgentMailboxBridge needs an adapter, a harness client and an agent name');
+    this.adapter = adapter;
+    this.client = client;
+    this.agent = agent;
+    this.platform = platform;
+    this.fromName = fromName;
+    this.statePath = statePath;
+    this.log = log;
+    this.pollMs = pollMs;
+    this.sleep = sleep;
+    this.running = false;
+    this.loop = null;
+    /** mailbox thread id -> { chat_id, root }: where the thread's root was posted. */
+    this.threads = new Map();
+    /** platform id of an answer this bridge posted -> its thread's root (a platform id the mailbox knows as a marker). */
+    this.answers = new Map();
+    if (statePath) {
+      try {
+        const state = JSON.parse(readFileSync(statePath, 'utf8'));
+        for (const [thread, where] of Object.entries(state.threads ?? {})) this.threads.set(thread, where);
+        for (const [answer, root] of Object.entries(state.answers ?? {})) this.answers.set(answer, root);
+      } catch { /* a first start has no state */ }
+    }
+  }
+
+  save() {
+    if (!this.statePath) return;
+    mkdirSync(dirname(this.statePath), { recursive: true });
+    const temporary = `${this.statePath}.${process.pid}.tmp`;
+    writeFileSync(temporary, JSON.stringify({ threads: Object.fromEntries(this.threads), answers: Object.fromEntries(this.answers) }));
+    renameSync(temporary, this.statePath);
+  }
+
+  async start() {
+    await this.adapter.connect((event) => { this.inbound(event).catch((error) => this.log('warn', `${this.platform}: not filed: ${error.message}`)); });
+    this.running = true;
+    this.loop = this.pollAnswers();
+  }
+
+  async stop() {
+    this.running = false;
+    await this.adapter.close?.();
+    if (this.loop) { try { await this.loop; } catch { /* stopping */ } this.loop = null; }
+  }
+
+  /** One line from the channel, filed as mail to the agent. */
+  async inbound(event) {
+    if (event.is_me || !event.message_id) return;
+    const marker = `${this.platform}:${event.message_id}`;
+    const result = await this.client.messageSession({ harness: 'agent', session_id: this.agent }, event.text, {
+      fromName: this.fromName,
+      senderName: event.sender_name ?? event.sender,
+      channel: true,
+      marker,
+      // The parent a platform names (RH2's `parentMessageId`), else the thread the line is in (Slack's `thread_ts` is its
+      // root's own id). A person's line is one the mailbox filed, so its marker is known; an answer this bridge posted is
+      // not, so a reply to one is filed against that answer's root.
+      replyMarker: this.replyMarkerOf(event),
+      surface: `${this.platform}:${event.key.chat_id}`,
+      idempotencyKey: marker,
+    });
+    if (result.delivered_to_bus === false && result.refusal) {
+      this.log('warn', `${this.platform}: ${this.agent} did not take ${marker}: ${result.refusal.message}`);
+      return;
+    }
+    const thread = result.thread ?? result.message_id;
+    if (thread && !this.threads.has(thread)) {
+      this.threads.set(thread, { chat_id: event.key.chat_id, root: event.key.thread_id ?? event.message_id });
+      this.save();
+    }
+  }
+
+  /** The mailbox marker a line replies to, or none for a root. */
+  replyMarkerOf(event) {
+    const parent = event.parent_id ?? event.key.thread_id;
+    if (!parent) return undefined;
+    return `${this.platform}:${this.answers.get(String(parent)) ?? parent}`;
+  }
+
+  /** The agent's answers, filed in this bridge's mailbox, posted in their threads. */
+  async pollAnswers() {
+    while (this.running) {
+      try {
+        const inbox = await this.client.sessionInbox({ fromName: this.fromName });
+        for (const { envelope } of inbox.messages ?? []) {
+          if (envelope.kind === 'notice') continue;
+          const where = this.threads.get(envelope.thread ?? envelope.in_reply_to ?? '');
+          if (!where) {
+            this.log('warn', `${this.platform}: ${envelope.id} names no thread this channel opened; not posted`);
+            continue;
+          }
+          const posted = await this.adapter.send({ platform: this.platform, kind: 'channel', chat_id: where.chat_id, thread_id: where.root }, { text: envelope.body });
+          if (posted?.message_id) {
+            this.answers.set(String(posted.message_id), String(where.root));
+            if (this.answers.size > ANSWER_MEMORY) this.answers.delete(this.answers.keys().next().value);
+            this.save();
+          }
+        }
+      } catch (error) {
+        this.log('warn', `${this.platform}: answers not read: ${error.message}`);
+      }
+      await this.sleep(this.pollMs);
+    }
+  }
+}

package/adapters/rh2.mjs

@@ -19,11 +19,12 @@
 // The Room-chat app (docs/adr/0017-room-chat-is-an-installed-app.md) attaches it with its RH2 installation's
 // origin, organization, principal and token; a `platforms:` block never does.
 //
-// The surface key is `{platform: 'rh2', kind: 'channel', chat_id: '<roomId>'}`: a Room is one surface, so the agent it
-// seats is one session however many of the Room's conversations it takes part in. A line wakes it where RH2 says the bot
-// answers every line (its participation, `answers: all`) or where the line mentions it; the line arrives labelled with its
-// conversation, and a reply goes back to the conversation of the Room's last line (`<roomId>/<conversationId>` names one)
-// unless the agent begins it with a conversation's label, `[Work]`, which sends it there.
+// The surface is the thread (docs/adr/0008-agent-mailbox.md, decision 16): `{platform: 'rh2', kind: 'channel',
+// chat_id: '<roomId>/<conversationId>'}` for a line posted directly in a conversation, which is a root, and the same key
+// with `thread_id: '<root message id>'` for a reply, which belongs to its anchor's thread (RH2's `parentMessageId`; a
+// reply to a reply joins the thread its parent is in). Each line also carries `parent_id`, the platform id it answers. A
+// line wakes the bot where RH2 says it answers every line (its participation, `answers: all`) or where the line mentions
+// it. A reply to a thread posts anchored at the thread's root, so the bot never posts directly in the conversation.
 import { chunks } from './chunks.mjs';
 
 const DEFAULT_POLL_MS = 2000;
@@ -32,6 +33,7 @@ const MAX_BODY = 4000;
 const MESSAGE_PAGE = 100;
 const CLOCK_SKEW_MS = 60_000;
 const ECHO_MEMORY = 500;
+const THREAD_MEMORY = 5000;
 
 export class Rh2Adapter {
   constructor({ platform = 'rh2', profile = 'default', channel = null, vault = new Map(), refreshVault = () => false, log = () => {}, fetchImpl = globalThis.fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
@@ -49,8 +51,8 @@ export class Rh2Adapter {
     this.cursors = new Map();
     /** room id -> { name, names: Map<principalId, displayName>, conversations: Map<id, name> } */
     this.rooms = new Map();
-    /** roomId -> the conversation of the last line that woke the Room's session: where a reply goes. */
-    this.replyTo = new Map();
+    /** message id -> the root of the thread it is in (its own id for a root). */
+    this.threadOf = new Map();
     this.roomsRefreshedAt = 0;
     this.ownMessageIds = [];
     this.postedIn = new Map(); // message id -> the conversation it was posted in, for its edits
@@ -232,18 +234,27 @@ export class Rh2Adapter {
     const mentions = Array.isArray(message.mentions) ? message.mentions.map(String) : [];
     const mentioned = me !== '' && mentions.includes(me);
     // RH2 decides who hears a line: the bot answers where it takes every line, and elsewhere only when named.
+    // A line posted directly in the conversation is a root; a reply belongs to its anchor's thread.
+    const parentId = message.parentMessageId === undefined || message.parentMessageId === null ? null : String(message.parentMessageId);
+    const root = parentId === null ? messageId : (this.threadOf.get(parentId) ?? parentId);
+    if (messageId !== null && root !== null) {
+      this.threadOf.set(messageId, root);
+      if (this.threadOf.size > THREAD_MEMORY) this.threadOf.delete(this.threadOf.keys().next().value);
+    }
     if (!isMe && conversation?.answers !== 'all' && !mentioned) return;
-    if (!isMe) this.replyTo.set(roomId, conversationId);
+    const chatId = `${roomId}/${conversationId}`;
     // A person's line opens a turn: show typing here until the reply lands (the loop has no
     // typing effect by design — the adapter, which knows both ends of the turn, carries it).
-    if (!isMe) this.startTyping(`${roomId}/${conversationId}`);
-    const labelled = room && room.conversations.size > 1 && conversation ? `[${conversation.name}] ${text}` : text;
+    if (!isMe) this.startTyping(chatId);
+    const key = { platform: this.platform, kind: 'channel', chat_id: chatId };
+    if (parentId !== null && root !== null) key.thread_id = root;
     this.emit({
       profile: this.profile,
-      key: { platform: this.platform, kind: 'channel', chat_id: roomId },
+      key,
+      parent_id: parentId,
       sender: author || 'unknown',
       sender_name: room?.names.get(author) ?? null,
-      text: labelled,
+      text,
       at: typeof message.createdAt === 'string' ? message.createdAt : new Date().toISOString(),
       message_id: messageId,
       is_me: isMe,
@@ -256,11 +267,7 @@ export class Rh2Adapter {
 
   split(chatId) {
     const [roomId, conversationId] = String(chatId).split('/');
-    if (conversationId) return { roomId, conversationId };
-    const last = this.replyTo.get(roomId);
-    if (last) return { roomId, conversationId: last };
-    for (const [id, cursor] of this.cursors) if (cursor.roomId === roomId) return { roomId, conversationId: id };
-    return { roomId, conversationId: undefined };
+    return { roomId, conversationId };
   }
 
   startTyping(chatId) {
@@ -277,35 +284,23 @@ export class Rh2Adapter {
     if (timer) { clearInterval(timer); this.typingTimers.delete(chatId); }
   }
 
-  /**
-   * Where a message goes: the conversation the agent names by beginning it with `[<name>]`, as each line reaches it
-   * labelled, or else the one it last answered. A turn a tester's line opened is still the agent's to narrate in Work.
-   */
-  addressed(roomId, conversationId, text) {
-    const named = /^\[([^\]\n]{1,64})\]\s*/.exec(text);
-    const room = this.rooms.get(roomId);
-    if (!named || !room) return { conversationId, text };
-    for (const [id, conversation] of room.conversations) {
-      if (conversation.name.toLowerCase() === named[1].trim().toLowerCase()) return { conversationId: id, text: text.slice(named[0].length) };
-    }
-    return { conversationId, text };
-  }
-
   async send(target, content) {
     this.stopTyping(String(target.chat_id));
-    const split = this.split(target.chat_id);
-    if (!split.conversationId) throw new Error(`${this.platform}: no conversation for ${target.chat_id}`);
-    const { roomId } = split;
-    const { conversationId, text } = this.addressed(roomId, split.conversationId, String(content.text ?? ''));
+    const { roomId, conversationId } = this.split(target.chat_id);
+    if (!conversationId) throw new Error(`${this.platform}: no conversation for ${target.chat_id}`);
+    const text = String(content.text ?? '');
+    // Every line of a reply is anchored at its thread's root, so it stays in the thread.
+    const anchor = content.reply_to ?? target.thread_id ?? null;
     // A reply longer than one line holds goes out as consecutive lines, split where a paragraph (or a line) ends.
     let messageId;
-    for (const [index, part] of chunks(text, MAX_BODY).entries()) {
+    for (const part of chunks(text, MAX_BODY)) {
       const body = { body: part, correlationId: `orchestrator:${crypto.randomUUID()}`, kind: 'agent' };
-      if (content.reply_to && index === 0) body.parentMessageId = String(content.reply_to);
+      if (anchor) body.parentMessageId = String(anchor);
       const res = await this.post(`/rooms/${roomId}/conversations/${conversationId}/messages`, body);
       if (!res.ok) throw new Error(`${this.platform}: post -> HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
       const posted = (await res.json()).data ?? {};
       messageId = String(posted.messageId ?? crypto.randomUUID());
+      if (anchor) this.threadOf.set(messageId, this.threadOf.get(String(anchor)) ?? String(anchor));
       this.ownMessageIds.push(messageId);
       this.postedIn.set(messageId, conversationId);
       if (this.postedIn.size > ECHO_MEMORY) this.postedIn.delete(this.postedIn.keys().next().value);
@@ -321,10 +316,10 @@ export class Rh2Adapter {
   async edit(target, messageId, content) {
     const split = this.split(target.chat_id);
     // An edit goes to the conversation the message was posted in, whichever the agent named then.
-    const posted = this.postedIn.get(String(messageId)) ?? split.conversationId;
-    if (!posted) throw new Error(`${this.platform}: no conversation for ${target.chat_id}`);
+    const conversationId = this.postedIn.get(String(messageId)) ?? split.conversationId;
+    if (!conversationId) throw new Error(`${this.platform}: no conversation for ${target.chat_id}`);
     const { roomId } = split;
-    const { conversationId, text } = { conversationId: posted, text: this.addressed(roomId, posted, String(content.text ?? '')).text };
+    const text = String(content.text ?? '');
     const res = await this.fetch(`${this.apiUrl()}/api/v3/rooms/${roomId}/conversations/${conversationId}/messages/${encodeURIComponent(messageId)}`, { method: 'PATCH', headers: this.headers(), body: JSON.stringify({ body: text.slice(0, MAX_BODY) }) });
     if (!res.ok) throw new Error(`${this.platform}: edit -> HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
     return { ok: true, message_id: messageId };

package/bin/agent-channel.mjs

@@ -0,0 +1,116 @@
+// `supercode-orchestrator agent-channel --agent <name>`: an agent's account Room, carried to its one mailbox
+// (docs/adr/0008-agent-mailbox.md, decisions 24-25). The Room sits on the organization's floor (the RH2 bot's
+// organization), with the agent as its one participant: every line a person posts there is filed as mail to the agent,
+// and every answer is posted back anchored at its thread's root, by `AgentMailboxBridge` over the RH2 adapter.
+//
+// The Room is found by its key (`--room-key`, default `account-<agent>`), or opened once when the organization has
+// none: the principal (`--principal`, RH2's principal id) as its operator, and the bot seated in its conversation
+// answering every line. `--room <id>` names an existing Room instead and opens nothing.
+//
+// RH2 is reached as the agent's own principal where the organization declares the agent (docs/adr/0017: `supercode
+// orchestrator apps install rh2-agent … --profile <agent>` in the home, `--root` or HERMES_HOME), so its threads, its DM
+// and its call are one participant; otherwise through the Room-chat app's installation for this agent (`apps install
+// room-chat … --profile <agent>`). The record's origin, organization, principal and token are the agent's identity in
+// the Room. The bridge's thread anchors are kept in `--state`.
+//
+// The agent's DM in its Room is its main session (RFC 0020 decision 26): where this machine is in a Teams team, the
+// participant's seat is bound to the main session (`supercode sessions bind`, the session owner's view binding for the
+// Room's DM with that participant), and rebound to each new main session, as the Agents → Room agents app binds an
+// arc's agent. Until the main session is in the team's catalog the binding is retried.
+import { parseArgs } from 'node:util';
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
+import { Rh2Adapter } from '../adapters/rh2.mjs';
+import { AgentMailboxBridge } from '../adapters/agent-mailbox.mjs';
+import { installedApps } from '../installed-apps.mjs';
+
+const { values } = parseArgs({
+  args: process.argv.slice(3),
+  options: { agent: { type: 'string' }, root: { type: 'string' }, room: { type: 'string' }, 'room-key': { type: 'string' }, 'room-name': { type: 'string' }, principal: { type: 'string' }, state: { type: 'string' }, help: { type: 'boolean' } },
+});
+if (values.help || !values.agent) {
+  console.log('supercode-orchestrator agent-channel --agent <name> [--root <home>] [--room <id> | --room-key <key> --principal <rh2 principal id> [--room-name <name>]] [--state <file>]');
+  process.exit(values.help ? 0 : 2);
+}
+const log = (level, line) => (level === 'debug' ? undefined : console.error(`${new Date().toISOString()} ${level} ${line}`));
+const root = values.root ?? process.env.HERMES_HOME;
+const apps = root ? installedApps(root).filter((app) => app.profile === values.agent) : [];
+const installation = apps.find((app) => app.app === 'rh2-agent') ?? apps.find((app) => app.app === 'room-chat');
+if (!installation) {
+  console.error(`agent-channel: ${values.agent} has no RH2 identity in ${root ?? '(no home: --root or HERMES_HOME)'}; install its agent (supercode orchestrator apps install rh2-agent … --profile ${values.agent}) or Room chat for it (apps install room-chat … --profile ${values.agent})`);
+  process.exit(1);
+}
+const identity = { api_url: installation.origin, organization: installation.organizationId, principal_id: installation.principalId, token: installation.token };
+const adapter = new Rh2Adapter({ log, channel: { enabled: true, extra: identity } });
+/** One RH2 write, its `data` returned; a refusal throws with its status. */
+async function post(path, body) {
+  const res = await adapter.post(path, body);
+  if (!res.ok) throw new Error(`POST ${path} -> HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+  return (await res.json()).data ?? {};
+}
+
+/** The account Room: named, found by its key, or opened once. */
+async function accountRoom() {
+  if (values.room) return values.room;
+  const key = values['room-key'] ?? `account-${values.agent}`;
+  const listing = await adapter.get('/rooms');
+  const found = (Array.isArray(listing) ? listing : listing.rooms ?? []).map((entry) => entry.room ?? entry).find((room) => room?.key === key && room.state === 'active');
+  if (found) return String(found.roomId);
+  if (!values.principal) throw new Error(`no active Room with key ${key}, and no --principal to open it for`);
+  const { room } = await post('/rooms', {
+    key,
+    name: values['room-name'] ?? `${values.agent}`,
+    members: [{ principalId: values.principal, roleKeys: ['operator'] }],
+  });
+  const view = await adapter.get(`/rooms/${encodeURIComponent(room.roomId)}`);
+  const conversation = view.room?.defaultConversationId;
+  if (!conversation) throw new Error(`Room ${room.roomId} was opened without a conversation`);
+  await post(`/rooms/${encodeURIComponent(room.roomId)}/conversations/${encodeURIComponent(conversation)}/participants`, { answers: 'all', principalId: adapter.principalId() });
+  log('info', `opened the account Room ${room.roomId} (${key}) for ${values.agent}`);
+  return String(room.roomId);
+}
+
+const roomId = await accountRoom();
+// The agent answers every line of its Room's conversation (the Room shows it as the conversation's agent); a seat it
+// already holds answers 409.
+{
+  const view = await adapter.get(`/rooms/${encodeURIComponent(roomId)}`);
+  const conversation = view.room?.defaultConversationId;
+  if (conversation) {
+    const res = await adapter.post(`/rooms/${encodeURIComponent(roomId)}/conversations/${encodeURIComponent(conversation)}/participants`, { answers: 'all', principalId: adapter.principalId() });
+    if (!res.ok && res.status !== 409) log('warn', `could not answer every line of ${conversation}: HTTP ${res.status}`);
+  }
+}
+// The adapter follows only this Room.
+adapter.channel = { enabled: true, extra: { ...identity, rooms: [roomId] } };
+const client = new SupercodeHarnessClient(process.env.SUPERCODE_BIN ? { command: process.env.SUPERCODE_BIN } : {});
+const bridge = new AgentMailboxBridge({
+  adapter, client, agent: values.agent, fromName: `rh2-${values.agent}`, log,
+  statePath: values.state ?? join(homedir(), '.config', 'supercode', 'agent-channels', `${values.agent}.json`),
+});
+await bridge.start();
+log('info', `${values.agent}: the account Room ${roomId} is carried to its mailbox`);
+
+const supercode = process.env.SUPERCODE_BIN || 'supercode';
+const sc = (args) => JSON.parse(execFileSync(supercode, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }));
+let boundTo = null;
+/** The participant's seat bound to the agent's current main session; a new main session rebinds it. */
+async function bindDm() {
+  let main;
+  try { main = [sc(['agent', 'show', values.agent, '--json'])].flat().find((a) => a.name === values.agent)?.main_session; } catch { return; }
+  const session = typeof main === 'string' ? main.split(':').pop() : null;
+  if (!session || session === boundTo) return;
+  let bound;
+  try { bound = sc(['sessions', 'bind', session, '--room', roomId, '--agent', adapter.principalId(), '--rh2', adapter.apiUrl(), '--json']).data; }
+  catch (error) { log('debug', `${values.agent}: its DM is not bound yet (${String(error.stderr ?? error.message).trim().split('\n').at(-1)})`); return; }
+  await post(`/rooms/${encodeURIComponent(roomId)}/members`, { principalId: adapter.principalId(), roleKeys: ['member'], session: { harness: bound.harness, sessionId: bound.sessionId, team: bound.team, teamsUrl: bound.teamsUrl } });
+  boundTo = session;
+  log('info', `${values.agent}: its DM in the account Room is its main session ${session}`);
+}
+await bindDm();
+const rebinding = setInterval(() => { void bindDm().catch((error) => log('warn', `${values.agent}: binding its DM: ${error.message}`)); }, 15_000);
+const stop = async () => { clearInterval(rebinding); await bridge.stop(); await client.close?.(); process.exit(0); };
+process.on('SIGTERM', stop);
+process.on('SIGINT', stop);

package/bin/orchestrator.mjs

@@ -8,6 +8,8 @@ if (process.argv[2] === 'workflow') {
   finally {await closeWorld();}
   await Promise.all([process.stdout,process.stderr].map(stream=>new Promise(done=>stream.write('',done))));
   process.exit(code);
+} else if (process.argv[2] === 'agent-channel') {
+  await import('./agent-channel.mjs');
 } else {
   await import('./runtime.mjs');
 }

package/bin/runtime.mjs

@@ -55,7 +55,7 @@
 import { SenderIdentityRecord } from '@volter/teams/sender-identity';
 import { existsSync, mkdirSync, rmdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { LOCK_FILE, leaseIsLive, readLease, thisHost } from '../lease.mjs';
@@ -70,7 +70,7 @@ import {
   TICK_MS, accessPolicy, applyOperator, performRemoveProfileDir, OPERATOR_OPS,
 } from '../index.mjs';
 import * as events from '../events.mjs';
-import { appView, installApp, installedApps, removeApp } from '../installed-apps.mjs';
+import { appView, installAgent, installApp, installedApps, removeApp } from '../installed-apps.mjs';
 import { httpJobExecutor } from '../hosted.mjs';
 import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
 
@@ -356,6 +356,9 @@ function buildAdapters(state, vault = new Map(), log = () => {}, root = null) {
   // installed for. Uninstalling on the other side revokes the token and the channel stops.
   for (const app of root ? installedApps(root) : []) {
     if (app.app !== 'room-chat') continue;
+    // An installation for a mail agent (its name as the profile) is carried to the agent's mailbox by its own channel
+    // (`agent-channel`, docs/adr/0008-agent-mailbox.md): its Room's lines are the agent's mail, never a worker's turns.
+    if (mailAgentNamed(app.profile)) { report.push({ platform: 'rh2', profile: app.profile, app: app.name, state: 'carried by the agent\'s channel' }); continue; }
     if (!state.profiles[app.profile]) { report.push({ platform: 'rh2', profile: app.profile, app: app.name, state: 'unsupported (its profile does not exist)' }); continue; }
     if (adapters.rh2) { report.push({ platform: 'rh2', profile: app.profile, app: app.name, state: 'already owned by another profile' }); continue; }
     adapters.rh2 = new Rh2Adapter({ platform: 'rh2', profile: app.profile, log, vault, channel: { enabled: true, extra: { api_url: app.origin, organization: app.organizationId, principal_id: app.principalId, token: app.token } } });
@@ -364,6 +367,12 @@ function buildAdapters(state, vault = new Map(), log = () => {}, root = null) {
   return { adapters, report };
 }
 
+/** Whether `name` is a declared mail agent on this machine (`supercode agent show`). */
+function mailAgentNamed(name) {
+  const shown = spawnSync(process.env.SUPERCODE_BIN || 'supercode', ['agent', 'show', name, '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  try { return shown.status === 0 && [JSON.parse(shown.stdout)].flat().some((agent) => agent?.name === name); } catch { return false; }
+}
+
 function profileReport(name, profile) {
   return {
     profile: name,
@@ -445,7 +454,9 @@ const ACCESS_OPS = {
  * `access <verb> ...`: the COLD path. Access lives in Hermes's stores, so each verb is performed through
  * Hermes's own pairing store and writers, then the home is loaded again to report what stands.
  */
-/** `apps install NAME --origin URL --client-id ID --client-secret-file FILE --code CODE [--profile P]`, `apps list`, `apps remove NAME`. */
+/** `apps install NAME --origin URL --client-id ID --client-secret-file FILE --code CODE [--profile P]`,
+ * `apps install rh2-agent --origin URL --organization ORG --principal PRN --token-file FILE --profile AGENT`, `apps list`,
+ * `apps remove NAME`. */
 async function appsMain(argv) {
   const [verb, ...rest] = argv;
   const flags = {}, positional = [];
@@ -456,6 +467,12 @@ async function appsMain(argv) {
   try {
     if (verb === 'list') { say('apps', { root, apps: installedApps(root).map(appView) }); return; }
     if (verb === 'remove') { say('apps', { root, removed: removeApp(root, positional[0] ?? '') }); return; }
+    if (verb === 'install' && positional[0] === 'rh2-agent') {
+      for (const name of ['origin', 'organization', 'principal', 'token-file', 'profile']) if (!flags[name]) throw new Error(`apps install rh2-agent needs --${name}`);
+      const token = readFileSync(flags['token-file'], 'utf8').trim();
+      say('apps', { root, installed: appView(await installAgent({ root, origin: flags.origin, organization: flags.organization, principal: flags.principal, token, profile: flags.profile })) });
+      return;
+    }
     if (verb === 'install') {
       for (const name of ['origin', 'client-id', 'client-secret-file', 'code']) if (!flags[name]) throw new Error(`apps install needs --${name}`);
       const clientSecret = readFileSync(flags['client-secret-file'], 'utf8').trim();

package/board/ci.mjs

@@ -96,7 +96,8 @@ export function reviewCandidate(board, id) {
 
 /** The PRs an evidence record covers: every PR of one arc review (the first is also its top-level PR). */
 export const candidatePullRequests = (ci) => ci?.prs ?? (ci?.pr ? [{ repository: ci.repository, branch: ci.branch, commit: ci.commit, source_sha: ci.source_sha ?? ci.commit, pr: ci.pr }] : []);
-const originOf = (path) => /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(run('git', ['remote', 'get-url', 'origin'], path))?.[1] ?? null;
+// The repository a checkout declares (remote.origin.url), not where a URL rewrite sends its transport.
+const originOf = (path) => /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(run('git', ['config', '--get', 'remote.origin.url'], path))?.[1] ?? null;
 
 function repositoryWorkspace(board, id) {
   const task = board.db.prepare('SELECT t.*,c.subtask_of,c.workspace_anchor,c.machine FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(id);
@@ -354,7 +355,7 @@ export function workflowRevision(root) {
     const workflow = realpathSync(join(root, 'workflow.yaml'));
     const checkout = run('git', ['rev-parse', '--show-toplevel'], dirname(workflow));
     const head = run('git', ['rev-parse', 'HEAD'], checkout);
-    const repository = /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(run('git', ['remote', 'get-url', 'origin'], checkout))?.[1];
+    const repository = /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(run('git', ['config', '--get', 'remote.origin.url'], checkout))?.[1];
     const name = relative(checkout, workflow).replaceAll('\\', '/');
     const source = readFileSync(workflow, 'utf8').trimEnd();
     if (run('git', ['show', `${head}:${name}`], checkout) !== source) return null;

package/board/cli.mjs

@@ -8,7 +8,7 @@ import { taskStatusOf } from './published.mjs';
 import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { basename, join, resolve } from 'node:path';
-import { tmpdir, userInfo } from 'node:os';
+import { homedir, tmpdir, userInfo } from 'node:os';
 import { read } from '../orchestration.mjs';
 import { actorOf, view, backingPaths, layOut, backingOf, boardExists, boardPath, DEFAULT_BOARD, event, json, listBoards, logsDir, now, openBoard, setActor, setPrincipal, principalOf, isCaller, tx } from './store.mjs';
 import { isLocalWorkspace } from './workspace.mjs';
@@ -1243,6 +1243,17 @@ function ownCard(db, sessionId) {
 
 const READS = new Set(['list', 'ls', 'show', 'context', 'runs', 'log', 'tail', 'watch', 'stats', 'assignees', 'diagnostics', 'diag', 'attachments', 'notify-list', 'capacity', 'help', 'init']);
 
+/** The main session of the agent an address names (`sc:<machine>:agent:<name>`, supercode docs/adr/0008-agent-mailbox.md),
+ * from its record in the machine's mail root; null for any other address. A manager named by its agent address is
+ * that agent's main session on the board. */
+function agentMain(address) {
+  const name = /^sc:[^:\s]+:agent:([^:\s]+)$/.exec(address)?.[1];
+  if (!name) return null;
+  const root = process.env.SUPERCODE_HOME || join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'supercode');
+  try { return String(JSON.parse(readFileSync(join(root, 'mail', 'agents', `${name}.json`), 'utf8')).main_session ?? '') || null; }
+  catch { return null; }
+}
+
 /**
  * Who a caller is on card `cardId`, in the workflow's roles: a signed-in terminal person retains their creator role;
  * the manager acts from its named session; the session of the card's current run has that run's role; the card's working session between runs
@@ -1251,7 +1262,7 @@ const READS = new Set(['list', 'ls', 'show', 'context', 'runs', 'log', 'tail', '
 function rolesFor(db, cardId, sessionId, params = {}) {
   // a session the workflow names as the board's manager (params.managers: its addresses) is the manager on every card
   const managers = Array.isArray(params.managers) ? params.managers.map(String) : [];
-  if (managers.some((m) => m === sessionId || m.endsWith(`:${sessionId}`))) return ['manager'];
+  if (managers.some((m) => m === sessionId || m.endsWith(`:${sessionId}`) || agentMain(m)?.endsWith(`:${sessionId}`))) return ['manager'];
   const task = engine.getTask(db, cardId);
   if (!task) return [];
   const roles = [];

package/board/dispatch.mjs

@@ -1998,7 +1998,7 @@ function readMailbox(board, address, report) {
     try { renameSync(path, join(box, 'cur', name)); } catch { continue; } // another reader took it
     // an answer to a question the board asked is what a card waits on (read by the card's workflow), not a verb
     if (envelope.in_reply_to) continue;
-    if (envelope.from === `sc:${localMachine()}:operator:teams-events` && json(envelope.body, {})?.machine_event) { report.mailed.push([envelope.from, 'machine_event']); continue; }
+    if (envelope.from === `sc:${localMachine()}:operator:teams-events` && envelope.kind === 'notice') { report.mailed.push([envelope.from, 'machine_event']); continue; }
     const argv = json(envelope.body, {})?.workflow;
     let answer;
     if (!Array.isArray(argv) || !argv.length || NOT_BY_MAIL.has(argv[0])) answer = `not applied: a mailed card update is one \`supercode workflow\` verb other than ${[...NOT_BY_MAIL].join(', ')}`;

package/board/store.mjs

@@ -174,6 +174,9 @@ export function openBoard(root, slug = DEFAULT_BOARD, { create = false, backing
   if (!kept) mkdirSync(dirname(path), { recursive: true });
   const db = new DatabaseSync(path);
   db.exec('PRAGMA foreign_keys = OFF');
+  // Every statement waits out another process's write instead of failing: the store keeps a rollback journal, so a read
+  // outside a transaction (a verb resolving its caller) is refused while the dispatcher writes ("database is locked").
+  db.exec('PRAGMA busy_timeout = 10000');
   // The check and the layout are one write transaction: a board another process is laying out is not mistaken for a
   // laid-out one (its `tasks` table made, the rest not), and a layout cut short by that process leaves nothing behind.
   for (;;) {

package/index.d.ts

@@ -320,6 +320,31 @@ export class ApiServerAdapter implements ChannelAdapter {
 export const API_SERVER_HOST: string;
 export const API_SERVER_PORT: number;
 
+/**
+ * A channel carried to an agent's one mailbox (supercode docs/adr/0008-agent-mailbox.md):
+ * each person's line is filed as channel mail to the agent (a root to its main session,
+ * a reply into its parent's thread), and the agent's answers, filed in this bridge's
+ * mailbox, are posted back anchored at their thread's root.
+ */
+export class AgentMailboxBridge {
+  constructor(o: {
+    adapter: ChannelAdapter;
+    /** A harness client (`SupercodeHarnessClient`): `messageSession` and `sessionInbox`. */
+    client: unknown;
+    /** The agent's name (`sc:<machine>:agent:<name>`). */
+    agent: string;
+    platform?: Platform;
+    /** This bridge's mailbox, a participant of every thread it opens. */
+    fromName?: string;
+    /** Where each thread's root was posted, and each posted answer's root, kept across restarts. */
+    statePath?: string | null;
+    log?: (level: string, message: string) => void;
+    pollMs?: number;
+  });
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+
 export class Orchestrator {
   constructor(o: {
     state: OrchestratorState;

package/index.mjs

@@ -22,6 +22,7 @@ export { LoopbackAdapter } from './adapters/loopback.mjs';
 export { ChatSdkAdapter, toInbound, toAttachment, chatType, CHAT_SDK_VERSION, CHAT_SDK_PACKAGE, CHAT_SDK_STATE_PACKAGE } from './adapters/chat-sdk.mjs';
 export { ApiServerAdapter, DEFAULT_HOST as API_SERVER_HOST, DEFAULT_PORT as API_SERVER_PORT } from './adapters/api-server.mjs';
 export { Rh2Adapter } from './adapters/rh2.mjs';
+export { AgentMailboxBridge } from './adapters/agent-mailbox.mjs';
 export { TOOLS, TOOL_NAMES, SERVER_NAME, PROTOCOL_VERSION } from './mcp/tools.mjs';
 export { mountOrchestratorMcp, doorFor, MCP_DOORS, SERVER_PATH } from './mcp/mount.mjs';
 export { startBridge } from './mcp/bridge.mjs';

package/installed-apps.mjs

@@ -10,9 +10,12 @@ export const APPS_DIR = 'apps';
 /** The apps this orchestrator can host, by name: what each installs and which adapter it attaches. */
 export const INSTALLABLE_APPS = Object.freeze({
   'room-chat': { side: 'rh2', adapter: 'rh2', describe: 'Room chat → orchestrator: a person\'s line in an RH2 Room reaches the agent seated there' },
+  // An agent the RH2 organization declares is one participant there: its chat, its DM and its call are its own agent
+  // principal, never an automation beside it. One record per agent (`rh2-agent.<agent>`).
+  'rh2-agent': { side: 'rh2', adapter: 'rh2', perProfile: true, describe: 'An agent the RH2 organization declares, in its Rooms as its own principal' },
 });
 
-const recordPath = (root, name) => join(root, APPS_DIR, `${name}.json`);
+const recordPath = (root, name, profile) => join(root, APPS_DIR, INSTALLABLE_APPS[name]?.perProfile ? `${name}.${profile}.json` : `${name}.json`);
 
 export function installedApps(root) {
   const dir = join(root, APPS_DIR);
@@ -20,7 +23,25 @@ export function installedApps(root) {
   return readdirSync(dir).filter((file) => file.endsWith('.json')).map((file) => {
     const record = JSON.parse(readFileSync(join(dir, file), 'utf8'));
     return { ...record, name: file.slice(0, -5) };
-  }).filter((record) => INSTALLABLE_APPS[record.name]);
+  }).filter((record) => INSTALLABLE_APPS[record.app ?? record.name]);
+}
+
+/** An RH2 agent's own identity for a mail agent: the token the organization's admin issued that agent principal (RH2's
+ * agent-token door), kept once RH2 answers it in that organization. */
+export async function installAgent({ root, origin, organization, principal, token, profile, fetchImpl = globalThis.fetch }) {
+  if (!profile) throw new Error('an RH2 agent is installed for a profile (--profile <agent>)');
+  if (!/^prn_/.test(String(principal))) throw new Error('--principal is the RH2 agent\'s principal id (prn_…)');
+  if (!/^https:\/\/|^http:\/\/(localhost|127\.0\.0\.1)(:|\/|$)/.test(String(origin))) throw new Error('the RH2 origin is an https URL');
+  const base = new URL(origin).origin;
+  const response = await fetchImpl(`${base}/api/v3/rooms`, { headers: { authorization: `Bearer ${token}`, 'x-rh2-organization': organization, origin: base, accept: 'application/json' } });
+  if (!response.ok) throw new Error(`RH2 refused the agent's token in ${organization}: HTTP ${response.status}`);
+  const record = { app: 'rh2-agent', side: 'rh2', origin: base, organizationId: organization, principalId: principal, profile, token, installedAt: new Date().toISOString() };
+  mkdirSync(join(root, APPS_DIR), { recursive: true, mode: 0o700 });
+  const path = recordPath(root, 'rh2-agent', profile);
+  const pending = `${path}.${process.pid}.tmp`;
+  writeFileSync(pending, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  renameSync(pending, path);
+  return { ...record, name: `rh2-agent.${profile}`, token: undefined };
 }
 
 /** Exchange an RH2 install code for the installation's token and keep the record. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.9",
+  "version": "0.5.10",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@volter/supercode-harness-sdk": "^0.3.41",
-    "@volter/teams": "0.2.5",
+    "@volter/teams": "0.2.6",
     "@volter/ztrack": "^2.4.23",
     "yaml": "^2.9.0"
   },