@mattstack/rt-client 0.6.1 → 0.6.2

package/README.md

@@ -74,6 +74,45 @@ doesn't error, it resolves empty. `parseIdentity` is strict — only strings
 `serializeIdentity` emitted parse — so validate payloads with it, and never
 hand-assemble or string-split a wire.
 
+## Chat
+
+The `rt chat` surface the chat viewer (`~/Documents/GitHub/chat`) is built
+on. Every call degrades to `{ ok: false, error }` instead of throwing, and a
+daemon that is down and a daemon that refused look the same to the caller;
+branch on `ok`, not on exceptions.
+
+```ts
+import { chatRooms, chatMessages, chatPost, createRelay, daemonHealth } from '@mattstack/rt-client';
+
+const rooms = await chatRooms({ handle: 'matt' });            // { ok, data: { rooms } }
+const page = await chatMessages({ room: 'build', limit: 50 }); // newest page; `before: <id>` pages older
+await chatPost({ handle: 'matt', room: 'build', body: 'on it' });
+
+const health = await daemonHealth();                           // { reachable, error? }, never throws
+const stop = createRelay({                                     // one daemon subscription, republished
+  match: t => t.startsWith('chat/'),                            // `chat/<room>/msg`, `chat/wake/<handle>`
+  topic: 'chat',
+  publish: (topic, data) => server.publish(topic, data),
+});
+```
+
+| Function | Daemon verb |
+| --- | --- |
+| `chatSignIn` / `chatSignOut` / `chatAway` / `chatBack` / `chatPulse` | presence: the buddy-list row and its heartbeats |
+| `chatBuddies` / `chatWho` / `chatRooms` | the roster, one room's members, a handle's rooms |
+| `chatJoin` / `chatLeave` | membership (`wakeOn: mention \| all \| none`) |
+| `chatPost` / `chatDm` / `chatRead` / `chatMessages` / `chatMark` | messages: post, DM, read-and-advance, page, advance the cursor |
+| `chatArm` / `chatTouch` / `chatDisarm` / `chatUnreadWaking` | the tail's wake protocol; the CLI's `rt chat tail` uses these |
+| `paneList` / `panePeek` / `paneSpawn` / `paneAccounts` / `paneDirectories` | herdr panes: list with presence joined, peek a screen, start claude in a tab, cswap accounts, directory suggestions |
+| `chatInvite` | type `/chat:join <room>` into a pane; `accepted`, `queued` or `refused` |
+| `createRelay` / `subscribe` | the event stream; `daemonHealth` the reachability probe |
+
+Pass `{ sockPath }` as the trailing options to reach a non-default daemon
+socket. The verbs, their payloads and the wake protocol are specified in
+repo-tools `docs/superpowers/specs/2026-08-23-rt-chat-design.md` and
+`2026-08-24-rt-chat-presence-design.md`; the agent-facing rules are
+`skills/rt-chat/SKILL.md`.
+
 ## License
 
 MIT

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { RtResponse, RtClientOptions } from "./transport.ts";
-import type { DemandDecl, ProjectMRsData, DiscussionsData, MrByBranchData, BranchEnrichment, ForgeSlug, ForgeTokenData, RunSummary, RunDetail, WakeMode, ChatMember, ChatMessage, RoomSummary, BuddyStatus, PresenceRow } from "./commands.ts";
+import type { DemandDecl, ProjectMRsData, DiscussionsData, MrByBranchData, BranchEnrichment, ForgeSlug, ForgeTokenData, RunSummary, RunDetail, WakeMode, ChatMember, ChatMessage, RoomSummary, BuddyStatus, PresenceRow, AgentRecord, Commands } from "./commands.ts";
 /**
  * One repo's project open-MR store. A cold repo forces a full paginated sync
  * on the daemon side when maxAgeMs demands it, which can run tens of seconds
@@ -102,6 +102,7 @@ export declare function chatArm(a: {
 }, o?: RtClientOptions): Promise<RtResponse<Record<string, never>>>;
 export declare function chatTouch(a: {
     handle: string;
+    room?: string;
     sessionId?: string;
 }, o?: RtClientOptions): Promise<RtResponse<Record<string, never>>>;
 export declare function chatDisarm(a: {
@@ -173,3 +174,20 @@ export declare function chatDm(a: {
 export declare function eventsHead(o?: RtClientOptions): Promise<RtResponse<{
     cursor: number;
 }>>;
+export declare function agentStart(a: Commands["agent:start"]["payload"], o?: RtClientOptions): Promise<RtResponse<AgentRecord>>;
+export declare function agentResume(a: Commands["agent:resume"]["payload"], o?: RtClientOptions): Promise<RtResponse<AgentRecord>>;
+export declare function agentGet(a: {
+    id: string;
+}, o?: RtClientOptions): Promise<RtResponse<AgentRecord>>;
+export declare function agentList(a: {
+    repo?: string;
+}, o?: RtClientOptions): Promise<RtResponse<{
+    agents: AgentRecord[];
+}>>;
+export declare function paneList(o?: RtClientOptions): Promise<RtResponse<Commands["pane:list"]["data"]>>;
+export declare function panePeek(a: Commands["pane:peek"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["pane:peek"]["data"]>>;
+/** The spawn waits on claude starting, so its budget is minutes, not seconds. */
+export declare function paneSpawn(a: Commands["pane:spawn"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["pane:spawn"]["data"]>>;
+export declare function paneAccounts(o?: RtClientOptions): Promise<RtResponse<Commands["pane:accounts"]["data"]>>;
+export declare function paneDirectories(a: Commands["pane:directories"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["pane:directories"]["data"]>>;
+export declare function chatInvite(a: Commands["chat:invite"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["chat:invite"]["data"]>>;

package/dist/commands.d.ts

@@ -151,6 +151,39 @@ export interface PresenceRow {
     armedAt?: number;
     signedOutAt?: number;
 }
+export type AgentStatus = "idle" | "working" | "blocked" | "done" | "unknown";
+/** Duplicated shape on purpose (see EventsBusEvent above): mirrors the daemon's pane row, which rt-client cannot import. */
+export interface ChatPane {
+    paneId: string;
+    workspace: string;
+    title?: string;
+    cwd?: string;
+    repo?: string;
+    branch?: string;
+    agentStatus: AgentStatus;
+    sessionId?: string;
+    presence?: {
+        handle: string;
+        status: BuddyStatus;
+        rooms: string[];
+    };
+}
+export interface PaneAccount {
+    slot: number;
+    email: string;
+    alias?: string;
+    headroom?: string;
+}
+export interface PaneDirectory {
+    path: string;
+    repo: string;
+    branch?: string;
+}
+export interface InviteResult {
+    paneId: string;
+    delivered: "accepted" | "queued" | "refused";
+    reason?: string;
+}
 export type Attention = {
     needs: boolean;
     reason: "failed" | "stale" | "stranded" | "blocked" | null;
@@ -223,6 +256,29 @@ export interface RunDetail {
     decisions: RunDecisionRow[];
     schemaAhead: boolean;
 }
+export type AgentSurface = "herdr" | "headless";
+export interface AgentRecord {
+    id: string;
+    repo: string;
+    cwd: string;
+    provider: string;
+    surface: AgentSurface;
+    sessionId: string;
+    model?: string;
+    effort?: string;
+    account?: string;
+    label?: string;
+    caller?: string;
+    paneId?: string;
+    tabId?: string;
+    workspaceId?: string;
+    extraArgs?: string;
+    exitCode?: number;
+    resultPath?: string;
+    createdAt: number;
+    lastResumedAt?: number;
+    finishedAt?: number;
+}
 export interface Commands {
     "project-mrs:read": {
         payload: {
@@ -456,6 +512,7 @@ export interface Commands {
     "chat:touch": {
         payload: {
             handle: string;
+            room?: string;
             sessionId?: string;
         };
         data: Record<string, never>;
@@ -554,6 +611,99 @@ export interface Commands {
             recipients: string[];
         };
     };
+    "agent:start": {
+        payload: {
+            repo: string;
+            cwd: string;
+            prompt?: string;
+            surface?: AgentSurface;
+            model?: string;
+            effort?: string;
+            account?: string;
+            label?: string;
+            caller?: string;
+            workspace?: string;
+            tab?: string;
+            extraArgs?: string;
+        };
+        data: AgentRecord;
+    };
+    "agent:resume": {
+        payload: {
+            id: string;
+            prompt?: string;
+            surface?: AgentSurface;
+        };
+        data: AgentRecord;
+    };
+    "agent:get": {
+        payload: {
+            id: string;
+        };
+        data: AgentRecord;
+    };
+    "agent:list": {
+        payload: {
+            repo?: string;
+        };
+        data: {
+            agents: AgentRecord[];
+        };
+    };
+    "chat:invite": {
+        payload: {
+            paneId: string;
+            room: string;
+            note?: string;
+            from: string;
+            callerPane?: string;
+        };
+        data: InviteResult;
+    };
+    "pane:list": {
+        payload: Record<string, never>;
+        data: {
+            panes: ChatPane[];
+        };
+    };
+    "pane:peek": {
+        payload: {
+            paneId: string;
+            lines?: number;
+        };
+        data: {
+            paneId: string;
+            lines: string[];
+        };
+    };
+    "pane:accounts": {
+        payload: Record<string, never>;
+        data: {
+            accounts: PaneAccount[];
+        };
+    };
+    "pane:directories": {
+        payload: {
+            q?: string;
+        };
+        data: {
+            directories: PaneDirectory[];
+        };
+    };
+    "pane:spawn": {
+        payload: {
+            cwd: string;
+            account?: string;
+            model?: string;
+            effort?: string;
+            prompt?: string;
+            workspace?: string;
+        };
+        data: {
+            pane: ChatPane;
+            ready: boolean;
+        };
+    };
 }
 export type CommandName = keyof Commands;
 export declare const COMMAND_NAMES: readonly CommandName[];

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { rtCommand, DEFAULT_SOCK } from "./transport.ts";
 export type { RtResponse, RtClientOptions } from "./transport.ts";
-export { readProjectMRs, readDiscussions, readMrsByBranch, readBranchCache, resolveForgeToken, listRuns, getRun, abandonRun, chatJoin, chatLeave, chatPost, chatRead, chatRooms, chatWho, chatMark, chatMessages, chatArm, chatTouch, chatDisarm, chatUnreadWaking, chatSignIn, chatSignOut, chatAway, chatBack, chatBuddies, chatPulse, chatDm, eventsHead, } from "./client.ts";
+export { readProjectMRs, readDiscussions, readMrsByBranch, readBranchCache, resolveForgeToken, listRuns, getRun, abandonRun, chatJoin, chatLeave, chatPost, chatRead, chatRooms, chatWho, chatMark, chatMessages, chatArm, chatTouch, chatDisarm, chatUnreadWaking, chatSignIn, chatSignOut, chatAway, chatBack, chatBuddies, chatPulse, chatDm, eventsHead, agentStart, agentResume, agentGet, agentList, paneList, panePeek, paneSpawn, paneAccounts, paneDirectories, chatInvite, } from "./client.ts";
 export { COMMAND_NAMES } from "./commands.ts";
-export type { Discussion, DemandDecl, ProjectMRsScope, ProjectMRsData, DiscussionsData, MrByBranchEntry, MrByBranchData, BranchEnrichment, Commands, CommandName, ForgeSlug, ForgeTokenData, Attention, RunSummary, RunStageRow, RunFieldRow, RunDecisionRow, RunDetail, WakeMode, ChatMember, ChatMessage, RoomSummary, BuddyStatus, PresenceRow, } from "./commands.ts";
+export type { Discussion, DemandDecl, ProjectMRsScope, ProjectMRsData, DiscussionsData, MrByBranchEntry, MrByBranchData, BranchEnrichment, Commands, CommandName, ForgeSlug, ForgeTokenData, Attention, RunSummary, RunStageRow, RunFieldRow, RunDecisionRow, RunDetail, WakeMode, ChatMember, ChatMessage, RoomSummary, BuddyStatus, PresenceRow, AgentRecord, AgentSurface, AgentStatus, ChatPane, PaneAccount, PaneDirectory, InviteResult, } from "./commands.ts";
 export { subscribe, createRelay, DEFAULT_WS_URL } from "./relay.ts";
 export type { RelayEventType } from "./relay.ts";
 export { daemonHealth } from "./health.ts";

package/dist/index.js

@@ -124,6 +124,8 @@ function chatArm(a, o = {}) {
 }
 function chatTouch(a, o = {}) {
   const payload = { handle: a.handle };
+  if (a.room !== undefined)
+    payload.room = a.room;
   if (a.sessionId !== undefined)
     payload.sessionId = a.sessionId;
   return rtCommand("chat:touch", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
@@ -187,6 +189,64 @@ function chatDm(a, o = {}) {
 function eventsHead(o = {}) {
   return rtCommand("events:head", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
+function agentStart(a, o = {}) {
+  const payload = { repo: a.repo, cwd: a.cwd };
+  for (const k of ["prompt", "surface", "model", "effort", "account", "label", "caller", "workspace", "tab", "extraArgs"]) {
+    if (a[k] !== undefined)
+      payload[k] = a[k];
+  }
+  return rtCommand("agent:start", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30000 });
+}
+function agentResume(a, o = {}) {
+  const payload = { id: a.id };
+  if (a.prompt !== undefined)
+    payload.prompt = a.prompt;
+  if (a.surface !== undefined)
+    payload.surface = a.surface;
+  return rtCommand("agent:resume", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30000 });
+}
+function agentGet(a, o = {}) {
+  return rtCommand("agent:get", { id: a.id }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function agentList(a, o = {}) {
+  const payload = {};
+  if (a.repo !== undefined)
+    payload.repo = a.repo;
+  return rtCommand("agent:list", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function paneList(o = {}) {
+  return rtCommand("pane:list", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function panePeek(a, o = {}) {
+  const payload = { paneId: a.paneId };
+  if (a.lines !== undefined)
+    payload.lines = a.lines;
+  return rtCommand("pane:peek", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function paneSpawn(a, o = {}) {
+  const payload = { cwd: a.cwd };
+  for (const k of ["account", "model", "effort", "prompt", "workspace"])
+    if (a[k] !== undefined)
+      payload[k] = a[k];
+  return rtCommand("pane:spawn", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 90000 });
+}
+function paneAccounts(o = {}) {
+  return rtCommand("pane:accounts", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function paneDirectories(a, o = {}) {
+  const payload = {};
+  if (a.q !== undefined)
+    payload.q = a.q;
+  return rtCommand("pane:directories", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
+}
+function chatInvite(a, o = {}) {
+  const payload = { paneId: a.paneId, room: a.room, from: a.from };
+  if (a.note !== undefined)
+    payload.note = a.note;
+  if (a.callerPane !== undefined)
+    payload.callerPane = a.callerPane;
+  return rtCommand("chat:invite", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30000 });
+}
 // src/commands.ts
 var COMMAND_NAMES = [
   "project-mrs:read",
@@ -219,7 +279,17 @@ var COMMAND_NAMES = [
   "chat:back",
   "chat:buddies",
   "chat:pulse",
-  "chat:dm"
+  "chat:dm",
+  "agent:start",
+  "agent:resume",
+  "agent:get",
+  "agent:list",
+  "chat:invite",
+  "pane:list",
+  "pane:peek",
+  "pane:accounts",
+  "pane:directories",
+  "pane:spawn"
 ];
 // src/relay.ts
 var DEFAULT_WS_URL = "ws://127.0.0.1:9401/ws";
@@ -659,7 +729,7 @@ var REGISTRY = [
     type: "array",
     scopes: ["team"],
     merge: "replace",
-    description: "The board's full member roster, including hidden-by-default entries."
+    description: "The authors tab's roster: whose MRs the classic board lists, including hidden-by-default entries. Codeowners tabs list MRs from anyone."
   },
   {
     key: "board.title",
@@ -680,14 +750,14 @@ var REGISTRY = [
     type: "array",
     scopes: ["team"],
     merge: "replace",
-    description: "Ticket key prefixes (e.g. RT, MAT) the board links out to Linear from an MR title."
+    description: "Ticket key prefixes (e.g. RT, MAT) that keep the authors tab to the team's own tickets and link out to Linear from an MR title; rows on a codeowners tab pass regardless of prefix."
   },
   {
     key: "board.slack",
     type: "object",
     scopes: ["team"],
     merge: "deep",
-    description: "The board's Slack posting config (app id, client id, channel, callback port); client secrets stay out of this store."
+    description: "The board's Slack posting config (app id, client id, channel, callback port); channel is the default that a tab's slackChannel overrides per MR. Client secrets stay out of this store."
   },
   {
     key: "board.doctorSkill",
@@ -708,7 +778,7 @@ var REGISTRY = [
     type: "array",
     scopes: ["team"],
     merge: "replace",
-    description: "Board tab definitions ({id, label, source, slackChannel?, reviewSkill?}); source.kind 'authors' is the classic roster board, 'codeowners' lists MRs blocked on an unapproved CODEOWNERS section. Absent = one implicit authors tab (fallback lives in the board reader, never here)."
+    description: "Board tabs ({id, label, source, slackChannel?, reviewSkill?}), editable from the board's settings modal. source.kind 'authors' is the classic roster board; 'codeowners' lists MRs from any author blocked on an unapproved CODEOWNERS section. Absent = one implicit authors tab (fallback lives in the board reader, never here)."
   },
   {
     key: "board.staleAfterDays",
@@ -736,7 +806,7 @@ var REGISTRY = [
     type: "array",
     scopes: ["user"],
     merge: "replace",
-    description: "Usernames this developer hides from the team roster's board.members list; overlays the team truth without editing it."
+    description: "Usernames this developer hides from the authors tab's board.members roster; overlays the team truth without editing it."
   },
   {
     key: "board.triage",
@@ -816,6 +886,21 @@ var REGISTRY = [
     merge: "replace",
     description: "The human's own chat handle, so agents can @-mention them by name."
   },
+  {
+    key: "chat.viewerUrl",
+    type: "string",
+    scopes: ["user"],
+    merge: "replace",
+    description: "Base URL of the chat viewer, no trailing slash. When set, rt chat post and the tail's wake lines end with a link to the room or message."
+  },
+  {
+    key: "chat.herdrWorkspace",
+    type: "string",
+    scopes: ["user"],
+    default: "chat",
+    merge: "replace",
+    description: "herdr workspace label that rt pane spawn opens new agent tabs in; created when missing."
+  },
   {
     key: "chat.push.provider",
     type: "string",
@@ -829,6 +914,34 @@ var REGISTRY = [
     scopes: ["user"],
     merge: "replace",
     description: "Destination (topic/URL/token) the configured chat.push.provider sends to."
+  },
+  {
+    key: "agent.model",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default --model for rt agent launches; unset omits the flag."
+  },
+  {
+    key: "agent.effort",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default --effort for rt agent launches; unset omits the flag."
+  },
+  {
+    key: "agent.account",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "cswap account email rt agent launches under; unset uses the default claude profile."
+  },
+  {
+    key: "agent.extraArgs",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Opaque extra claude arguments appended to every rt agent launch (escape hatch)."
   }
 ];
 
@@ -1624,6 +1737,11 @@ export {
   readDiscussions,
   readBranchCache,
   parseIdentity,
+  paneSpawn,
+  panePeek,
+  paneList,
+  paneDirectories,
+  paneAccounts,
   normalizeRemote,
   listTeams,
   listSettings,
@@ -1653,6 +1771,7 @@ export {
   chatMark,
   chatLeave,
   chatJoin,
+  chatInvite,
   chatDm,
   chatDisarm,
   chatBuddies,
@@ -1660,6 +1779,10 @@ export {
   chatAway,
   chatArm,
   allDefs,
+  agentStart,
+  agentResume,
+  agentList,
+  agentGet,
   abandonRun,
   SCOPE_ORDER,
   REGISTRY,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mattstack/rt-client",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "type": "module",
   "exports": {
     ".": {

package/src/client.ts

@@ -21,6 +21,8 @@ import type {
   RoomSummary,
   BuddyStatus,
   PresenceRow,
+  AgentRecord,
+  Commands,
 } from "./commands.ts";
 
 /**
@@ -227,10 +229,11 @@ export function chatArm(
 }
 
 export function chatTouch(
-  a: { handle: string; sessionId?: string },
+  a: { handle: string; room?: string; sessionId?: string },
   o: RtClientOptions = {},
 ): Promise<RtResponse<Record<string, never>>> {
   const payload: Record<string, unknown> = { handle: a.handle };
+  if (a.room !== undefined) payload.room = a.room;
   if (a.sessionId !== undefined) payload.sessionId = a.sessionId;
   return rtCommand<Record<string, never>>("chat:touch", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
@@ -323,3 +326,77 @@ export function chatDm(
 export function eventsHead(o: RtClientOptions = {}): Promise<RtResponse<{ cursor: number }>> {
   return rtCommand<{ cursor: number }>("events:head", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
+
+// ─── Agent handoff (rt agent) ─────────────────────────────────────────────
+
+export function agentStart(
+  a: Commands["agent:start"]["payload"], o: RtClientOptions = {},
+): Promise<RtResponse<AgentRecord>> {
+  const payload: Record<string, unknown> = { repo: a.repo, cwd: a.cwd };
+  for (const k of ["prompt", "surface", "model", "effort", "account", "label", "caller", "workspace", "tab", "extraArgs"] as const) {
+    if (a[k] !== undefined) payload[k] = a[k];
+  }
+  return rtCommand<AgentRecord>("agent:start", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
+}
+
+export function agentResume(
+  a: Commands["agent:resume"]["payload"], o: RtClientOptions = {},
+): Promise<RtResponse<AgentRecord>> {
+  const payload: Record<string, unknown> = { id: a.id };
+  if (a.prompt !== undefined) payload.prompt = a.prompt;
+  if (a.surface !== undefined) payload.surface = a.surface;
+  return rtCommand<AgentRecord>("agent:resume", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
+}
+
+export function agentGet(a: { id: string }, o: RtClientOptions = {}): Promise<RtResponse<AgentRecord>> {
+  return rtCommand<AgentRecord>("agent:get", { id: a.id }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function agentList(a: { repo?: string }, o: RtClientOptions = {}): Promise<RtResponse<{ agents: AgentRecord[] }>> {
+  const payload: Record<string, unknown> = {};
+  if (a.repo !== undefined) payload.repo = a.repo;
+  return rtCommand<{ agents: AgentRecord[] }>("agent:list", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+// ─── Panes (rt chat invite) ────────────────────────────────────────────────
+// herdr-facing verbs; the daemon answers `herdr unavailable` without herdr.
+
+export function paneList(o: RtClientOptions = {}): Promise<RtResponse<Commands["pane:list"]["data"]>> {
+  return rtCommand<Commands["pane:list"]["data"]>("pane:list", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function panePeek(a: Commands["pane:peek"]["payload"], o: RtClientOptions = {}): Promise<RtResponse<Commands["pane:peek"]["data"]>> {
+  const payload: Record<string, unknown> = { paneId: a.paneId };
+  if (a.lines !== undefined) payload.lines = a.lines;
+  return rtCommand<Commands["pane:peek"]["data"]>("pane:peek", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+/** The spawn waits on claude starting, so its budget is minutes, not seconds. */
+export function paneSpawn(
+  a: Commands["pane:spawn"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["pane:spawn"]["data"]>> {
+  const payload: Record<string, unknown> = { cwd: a.cwd };
+  for (const k of ["account", "model", "effort", "prompt", "workspace"] as const) if (a[k] !== undefined) payload[k] = a[k];
+  return rtCommand<Commands["pane:spawn"]["data"]>("pane:spawn", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 90_000 });
+}
+
+export function paneAccounts(o: RtClientOptions = {}): Promise<RtResponse<Commands["pane:accounts"]["data"]>> {
+  return rtCommand<Commands["pane:accounts"]["data"]>("pane:accounts", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function paneDirectories(a: Commands["pane:directories"]["payload"], o: RtClientOptions = {}): Promise<RtResponse<Commands["pane:directories"]["data"]>> {
+  const payload: Record<string, unknown> = {};
+  if (a.q !== undefined) payload.q = a.q;
+  return rtCommand<Commands["pane:directories"]["data"]>("pane:directories", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function chatInvite(
+  a: Commands["chat:invite"]["payload"],
+  o: RtClientOptions = {},
+): Promise<RtResponse<Commands["chat:invite"]["data"]>> {
+  const payload: Record<string, unknown> = { paneId: a.paneId, room: a.room, from: a.from };
+  if (a.note !== undefined) payload.note = a.note;
+  if (a.callerPane !== undefined) payload.callerPane = a.callerPane;
+  return rtCommand<Commands["chat:invite"]["data"]>("chat:invite", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
+}

package/src/commands.ts

@@ -146,6 +146,25 @@ export interface PresenceRow {
   signedOutAt?: number;
 }
 
+export type AgentStatus = "idle" | "working" | "blocked" | "done" | "unknown";
+
+/** Duplicated shape on purpose (see EventsBusEvent above): mirrors the daemon's pane row, which rt-client cannot import. */
+export interface ChatPane {
+  paneId: string;
+  workspace: string;
+  title?: string;
+  cwd?: string;
+  repo?: string;
+  branch?: string;
+  agentStatus: AgentStatus;
+  sessionId?: string;
+  presence?: { handle: string; status: BuddyStatus; rooms: string[] };
+}
+
+export interface PaneAccount { slot: number; email: string; alias?: string; headroom?: string }
+export interface PaneDirectory { path: string; repo: string; branch?: string }
+export interface InviteResult { paneId: string; delivered: "accepted" | "queued" | "refused"; reason?: string }
+
 // SKILLS-53: one judgment, computed once in rt, so the console and the tray
 // never derive two verdicts that can disagree.
 export type Attention = {
@@ -192,6 +211,18 @@ export interface RunFieldRow { key: string; value: string; produced_by: string;
 export interface RunDecisionRow { contract: string; scope: string; selection: string; decided_by: string; decided_at: number; }
 export interface RunDetail { run: RunSummary; stages: RunStageRow[]; fields: RunFieldRow[]; decisions: RunDecisionRow[]; schemaAhead: boolean; }
 
+export type AgentSurface = "herdr" | "headless";
+
+export interface AgentRecord {
+  id: string; repo: string; cwd: string; provider: string;
+  surface: AgentSurface; sessionId: string;
+  model?: string; effort?: string; account?: string;
+  label?: string; caller?: string;
+  paneId?: string; tabId?: string; workspaceId?: string;
+  extraArgs?: string; exitCode?: number; resultPath?: string;
+  createdAt: number; lastResumedAt?: number; finishedAt?: number;
+}
+
 export interface Commands {
   "project-mrs:read": { payload: { repoName: string; maxAgeMs?: number; demand?: DemandDecl }; data: ProjectMRsData };
   "discussions:read": { payload: { repoName: string; iid: number }; data: DiscussionsData };
@@ -257,7 +288,7 @@ export interface Commands {
   "chat:mark": { payload: { handle: string; room?: string }; data: Record<string, never> };
   "chat:messages": { payload: { room: string; before?: number; limit?: number }; data: { messages: ChatMessage[] } };
   "chat:arm": { payload: { handle: string; room?: string; sessionId?: string }; data: Record<string, never> };
-  "chat:touch": { payload: { handle: string; sessionId?: string }; data: Record<string, never> };
+  "chat:touch": { payload: { handle: string; room?: string; sessionId?: string }; data: Record<string, never> };
   "chat:disarm": { payload: { handle: string; sessionId?: string }; data: Record<string, never> };
   "chat:unread-waking": { payload: { handle: string; room?: string }; data: { rooms: { room: string; count: number; mentions: number; maxId: number }[] } };
 
@@ -277,6 +308,21 @@ export interface Commands {
     data: { unread: { dms: number; mentions: number; rooms: number }; status: BuddyStatus };
   };
   "chat:dm": { payload: { from: string; to: string; body: string; sessionId?: string }; data: { room: string; id: number; recipients: string[] } };
+
+  // ─── Agent handoff (rt agent) ────────────────────────────────────────────
+  "agent:start": { payload: { repo: string; cwd: string; prompt?: string; surface?: AgentSurface; model?: string; effort?: string; account?: string; label?: string; caller?: string; workspace?: string; tab?: string; extraArgs?: string }; data: AgentRecord };
+  "agent:resume": { payload: { id: string; prompt?: string; surface?: AgentSurface }; data: AgentRecord };
+  "agent:get": { payload: { id: string }; data: AgentRecord };
+  "agent:list": { payload: { repo?: string }; data: { agents: AgentRecord[] } };
+  "chat:invite": { payload: { paneId: string; room: string; note?: string; from: string; callerPane?: string }; data: InviteResult };
+  "pane:list": { payload: Record<string, never>; data: { panes: ChatPane[] } };
+  "pane:peek": { payload: { paneId: string; lines?: number }; data: { paneId: string; lines: string[] } };
+  "pane:accounts": { payload: Record<string, never>; data: { accounts: PaneAccount[] } };
+  "pane:directories": { payload: { q?: string }; data: { directories: PaneDirectory[] } };
+  "pane:spawn": {
+    payload: { cwd: string; account?: string; model?: string; effort?: string; prompt?: string; workspace?: string };
+    data: { pane: ChatPane; ready: boolean };
+  };
 }
 
 export type CommandName = keyof Commands;
@@ -313,4 +359,14 @@ export const COMMAND_NAMES: readonly CommandName[] = [
   "chat:buddies",
   "chat:pulse",
   "chat:dm",
+  "agent:start",
+  "agent:resume",
+  "agent:get",
+  "agent:list",
+  "chat:invite",
+  "pane:list",
+  "pane:peek",
+  "pane:accounts",
+  "pane:directories",
+  "pane:spawn",
 ];

package/src/index.ts

@@ -30,6 +30,16 @@ export {
   chatPulse,
   chatDm,
   eventsHead,
+  agentStart,
+  agentResume,
+  agentGet,
+  agentList,
+  paneList,
+  panePeek,
+  paneSpawn,
+  paneAccounts,
+  paneDirectories,
+  chatInvite,
 } from "./client.ts";
 
 export { COMMAND_NAMES } from "./commands.ts";
@@ -58,6 +68,13 @@ export type {
   RoomSummary,
   BuddyStatus,
   PresenceRow,
+  AgentRecord,
+  AgentSurface,
+  AgentStatus,
+  ChatPane,
+  PaneAccount,
+  PaneDirectory,
+  InviteResult,
 } from "./commands.ts";
 
 export { subscribe, createRelay, DEFAULT_WS_URL } from "./relay.ts";

package/src/settings/registry-defs.ts

@@ -308,7 +308,7 @@ export const REGISTRY: readonly SettingDef[] = [
     type: "array",
     scopes: ["team"],
     merge: "replace",
-    description: "The board's full member roster, including hidden-by-default entries.",
+    description: "The authors tab's roster: whose MRs the classic board lists, including hidden-by-default entries. Codeowners tabs list MRs from anyone.",
   },
   {
     key: "board.title",
@@ -329,14 +329,14 @@ export const REGISTRY: readonly SettingDef[] = [
     type: "array",
     scopes: ["team"],
     merge: "replace",
-    description: "Ticket key prefixes (e.g. RT, MAT) the board links out to Linear from an MR title.",
+    description: "Ticket key prefixes (e.g. RT, MAT) that keep the authors tab to the team's own tickets and link out to Linear from an MR title; rows on a codeowners tab pass regardless of prefix.",
   },
   {
     key: "board.slack",
     type: "object",
     scopes: ["team"],
     merge: "deep",
-    description: "The board's Slack posting config (app id, client id, channel, callback port); client secrets stay out of this store.",
+    description: "The board's Slack posting config (app id, client id, channel, callback port); channel is the default that a tab's slackChannel overrides per MR. Client secrets stay out of this store.",
   },
   {
     key: "board.doctorSkill",
@@ -357,7 +357,7 @@ export const REGISTRY: readonly SettingDef[] = [
     type: "array",
     scopes: ["team"],
     merge: "replace",
-    description: "Board tab definitions ({id, label, source, slackChannel?, reviewSkill?}); source.kind 'authors' is the classic roster board, 'codeowners' lists MRs blocked on an unapproved CODEOWNERS section. Absent = one implicit authors tab (fallback lives in the board reader, never here).",
+    description: "Board tabs ({id, label, source, slackChannel?, reviewSkill?}), editable from the board's settings modal. source.kind 'authors' is the classic roster board; 'codeowners' lists MRs from any author blocked on an unapproved CODEOWNERS section. Absent = one implicit authors tab (fallback lives in the board reader, never here).",
   },
 
   // --- board (user) ----------------------------------------------------------
@@ -387,7 +387,7 @@ export const REGISTRY: readonly SettingDef[] = [
     type: "array",
     scopes: ["user"],
     merge: "replace",
-    description: "Usernames this developer hides from the team roster's board.members list; overlays the team truth without editing it.",
+    description: "Usernames this developer hides from the authors tab's board.members roster; overlays the team truth without editing it.",
   },
   {
     key: "board.triage",
@@ -473,6 +473,21 @@ export const REGISTRY: readonly SettingDef[] = [
     merge: "replace",
     description: "The human's own chat handle, so agents can @-mention them by name.",
   },
+  {
+    key: "chat.viewerUrl",
+    type: "string",
+    scopes: ["user"],
+    merge: "replace",
+    description: "Base URL of the chat viewer, no trailing slash. When set, rt chat post and the tail's wake lines end with a link to the room or message.",
+  },
+  {
+    key: "chat.herdrWorkspace",
+    type: "string",
+    scopes: ["user"],
+    default: "chat",
+    merge: "replace",
+    description: "herdr workspace label that rt pane spawn opens new agent tabs in; created when missing.",
+  },
   {
     key: "chat.push.provider",
     type: "string",
@@ -487,4 +502,36 @@ export const REGISTRY: readonly SettingDef[] = [
     merge: "replace",
     description: "Destination (topic/URL/token) the configured chat.push.provider sends to.",
   },
+
+  // --- agent (rt agent handoff) --------------------------------------------
+  // No defaults by design: an unset key means the flag is omitted from the
+  // claude invocation entirely (spec "Settings").
+  {
+    key: "agent.model",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default --model for rt agent launches; unset omits the flag.",
+  },
+  {
+    key: "agent.effort",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default --effort for rt agent launches; unset omits the flag.",
+  },
+  {
+    key: "agent.account",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "cswap account email rt agent launches under; unset uses the default claude profile.",
+  },
+  {
+    key: "agent.extraArgs",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Opaque extra claude arguments appended to every rt agent launch (escape hatch).",
+  },
 ];