pi-onlyne 2.2.0 → 2.4.0

package/README.md

@@ -17,7 +17,11 @@ ordinary pi session: the plugin registers nothing and opens nothing.
 Only the session whose own id equals `ONLYNE_SESSION_ID` mounts. A pi process runs more
 than one session — a `task` subagent's sidechain, `/new` — and each of them loads this
 extension with the same inherited environment, so a session that is not the bound one
-stays inert and every onlyne tool it calls is refused.
+stays inert and every onlyne tool it calls is refused. In resident mode (`ONLYNE_ROLE` or
+`.pi/onlyne.json` `"resident": true` / `.onlyne/config.toml` `placement = "external"`), the
+extension also tracks top-level `session_switch`, `session_branch`, and `session_tree`
+events so `/resume`, `/new`, and context rollover keep the tools bound to the active
+top-level session.
 
 ```
 pi session (spawned by onlyne-client)
@@ -30,14 +34,17 @@ hello{protocol:1, plugin:"pi-onlyne", kind:"agent", capabilities:[…], mount:{r
   ├─ report.ready ──► the barrier the task payload waits behind
   ◀── assign{envelope, prose, text, attachments, task_id, generation}
   ├─ prose, when the welcome did not already deliver it ──► the same section
-  ├─ text ──► pi user message (deliverAs:"followUp"), byte for byte; `body.image`
-  │    rides as a pi image part, and `attachments` names files the client wrote
+  ├─ text ──► one `onlyne_assign` card (`From <sender> · <kind> · <id>`), byte for byte:
+  │    `triggerTurn` starts the turn an idle session owes it and `deliverAs:"followUp"` queues
+  │    while busy, so the delivery is one message and never also a user prompt; a pi without
+  │    `sendMessage` takes it as a plain user message instead. `body.image` rides as a pi image
+  │    part, and `attachments` names files the client wrote
   ├─ assign_ack{accepted:true}
   ├─ report.heartbeat{agent} — `running` per turn and every 10s while a task is live,
   │    `idle` only while pi waits for input; every beat re-derives it from pi
   ├─ the client owns the turn-end rule: a turn that ends without a completion
   │    earns one nudge, and the second such ending settles the delivery
-  ◀── nudge{task_id, text} ──► pi user message, byte for byte (the client's sentence)
+  ◀── nudge{task_id, text} ──► the same card route, byte for byte (the client's sentence)
   ├─ report.complete{outcome, head, details, files} — the ledger's terminal fact, and the last report
   │    └─ the client's answer is the handover: pi is asked to shut down, then detaches
   ├─ probe ──► one heartbeat
@@ -114,6 +121,9 @@ pi --session-id <id> -e /abs/path/to/plugins/onlyne-agent-pi -ns -nc
 | --- | --- | --- |
 | `enabled` | `true` | `false` turns the extension off for this workspace |
 | `watch.autoStart` | `true` | `false` registers the tools but opens no socket until `/onlyne connect` |
+| `role` | — | the role this session serves when the client injected no `ONLYNE_ROLE`; also what makes the file a resident opt-in |
+| `workspace` | — | the role workspace, when the session did not start inside it; a relative path resolves against the pi working directory |
+| `cluster` | — | the cluster whose client this session dials — the serving server's `[server] name`; unset means the tree decides |
 
 A missing file means every default. A malformed file prints one warning on stderr and
 keeps the defaults: a typo must not silently disable a role. The client does not read
@@ -121,6 +131,13 @@ this file (§11 of the plan downgraded the old readiness gates to generate-time
 advice), so only this extension consumes it; the key shape stays the one the templates
 carry.
 
+`cluster` is the answer for a session whose body runs in one cluster's tree while the
+role workspace belongs to another: with the key set, the client registered for this role
+in that cluster is dialed first, whatever tree the session runs in. A cluster holding two
+clients of the role is refused by name rather than picked from. With the key absent — or
+naming a cluster no client has registered — resolution falls back to the tree, exactly as
+it did before the key existed.
+
 Nothing else is needed. The workspace's `session_command` in `spec.toml` already spawns
 `pi` per task (`["pi", "--session-id", "{session}"]`), and the client injects the
 environment this extension keys on.
@@ -150,7 +167,7 @@ What happens when a pi API is missing, and what the host does then:
 
 ### Activity panel
 
-When the host reports a UI (`ctx.hasUI`, true in the TUI and RPC modes, false in print and JSON modes) and `ctx.ui.setWidget` is available, routine onlyne notices draw in the panel above the editor with widget key `onlyne`. The header shows role, connection state, generation, the current task id, and phase. Below it, up to six newest-first events use `<=` for inbound frames, `=>` for outbound frames, `!!` for warnings, `..` for state changes, and `~~` for duplicate deliveries. Repeated identical events fold into one line with `xN`; the panel holds at most eight lines, each capped at 96 cells, and `session_shutdown` clears it.
+When the host reports a UI (`ctx.hasUI`, true in the TUI and RPC modes, false in print and JSON modes) and `ctx.ui.setWidget` is available, routine onlyne notices draw in the panel above the editor with widget key `onlyne`. The widget registers a dual-surface component: on ANSI terminals it renders theme-styled lines (`accent` role badge, status-toned connection state, dimmed timestamps, and semantic event markers), and on Tern Surface Protocol (TSP) hosts it implements `describe()` to emit a native collapsible `card` (`role: "omp.widget.onlyne"`, `variant: "bare"`) with structured spans. An inbound delivery (`assign` and `nudge`) travels as the visible `onlyne_assign` custom message card (`From <sender> · <kind> · <id>`) that `registerMessageRenderer("onlyne_assign", ...)` draws: it reaches the model as that one message, so a delivery is never both drawn twice and read twice. `wakeUser` passes `{ triggerTurn: true }` when `ctx.isIdle()` is true, which is what starts the turn an empty or settled resident session owes the card (and `{ deliverAs: "followUp" }` while busy). The header shows role, connection state, generation, the current task id, and phase. Below it, up to six newest-first events use `<=` for inbound frames, `=>` for outbound frames, `!!` for warnings, `..` for state changes, and `~~` for duplicate deliveries. Repeated identical events fold into one line with `xN` (and pre-connection resident polling stays quiet until a socket connects); the panel holds at most eight lines, each capped at 96 cells, and `session_shutdown` clears it.
 
 ## 3. Tools
 
@@ -172,8 +189,10 @@ connected.
 
 ### `onlyne_send{to, text, kind?, image?}`
 
-Sends one envelope on the `send` frame. `kind: "note"` (the default) is free text and
-carries no `op_id`. `kind: "task"` hands work to a role, so it carries an `o-<uuid>`
+Sends one envelope on the `send` frame. `kind: "note"` (the default) sends stateless
+conversational text to a working, idle, or parked resident session, carries no `op_id`,
+opens no task record, and requires no `onlyne_complete`. `kind: "task"` hands tracked work
+to a role, so it carries an `o-<uuid>`
 idempotency key and a fresh `causality.task`. `image` is an absolute path to a
 png/jpeg/gif/webp file: the plugin reads it, base64-encodes it and attaches it as
 `body.image`. The core caps that at 2 MiB and accepts four mime types. The result is

package/README.zh.md

@@ -12,7 +12,10 @@ socket——机器级运行目录里的 `<digest>.sock`（`/tmp/onlyne-<uid>/`
 
 只有自身 session id 等于 `ONLYNE_SESSION_ID` 的那个 session 才会挂载。一个 pi 进程会跑不止一个
 session——`task` 子代理的 sidechain、`/new`——它们都会带着同一份继承来的环境变量加载本扩展；
-因此不是被绑定 session 的那个保持静默，它发出的每一次 onlyne 工具调用都会被拒绝。
+因此不是被绑定 session 的那个保持静默，它发出的每一次 onlyne 工具调用都会被拒绝。在常驻模式
+（`ONLYNE_ROLE`、`.pi/onlyne.json` `"resident": true` 或 `.onlyne/config.toml`
+`placement = "external"`）下，扩展同时监听顶层 `session_switch`、`session_branch` 与
+`session_tree` 事件，使 `/resume`、`/new` 及上下文切换后工具自动跟随当前顶层会话。
 
 ```
 pi session（由 onlyne-client spawn）
@@ -25,8 +28,11 @@ hello{protocol:1, plugin:"pi-onlyne", kind:"agent", capabilities:[…], mount:{r
   ├─ report.ready ──► 载荷等待的那道 barrier
   ◀── assign{envelope, prose, text, attachments, task_id, generation}
   ├─ prose（仅当 welcome 尚未投递过） ──► 同一个 section
-  ├─ text ──► pi user message（deliverAs:"followUp"），逐字节原样；`body.image`
-  │    作为 pi image part 同行，`attachments` 里的路径是 client 已写好的文件
+  ├─ text ──► 一张 `onlyne_assign` 卡片（`From <sender> · <kind> · <id>`），逐字节原样：
+  │    `triggerTurn` 让空闲会话就此起一个 turn，繁忙时改 `deliverAs:"followUp"` 排队，
+  │    于是投递只有这一条消息、不会同时再是一条 user prompt；没有 `sendMessage` 的 pi 退回
+  │    普通 user message。`body.image` 作为 pi image part 同行，`attachments` 里的路径是
+  │    client 已写好的文件
   ├─ assign_ack{accepted:true}
   ├─ report.heartbeat{agent} —— 每个 turn 以及任务存续期间每 10 秒发 `running`，
   │    只有 pi 等待输入时才发 `idle`；每次心跳都重新向 pi 推导
@@ -106,6 +112,8 @@ pi --session-id <id> -e /abs/path/to/plugins/onlyne-agent-pi -ns -nc
 | --- | --- | --- |
 | `enabled` | `true` | `false` 时该工作区禁用扩展 |
 | `watch.autoStart` | `true` | `false` 时注册工具但不建连接，需 `/onlyne connect` |
+| `workspace` | — | 角色工作区路径（当会话未在其中启动时生效；相对路径相对 pi 工作目录解析） |
+| `cluster` | — | 本会话要连接的集群名（对应服务端的 `[server] name`；未设时由工作区目录树决定） |
 
 文件缺失即取各自默认值。文件格式错误时打印一行警告，并保留默认值：一个笔误不该静默关掉一个
 role。client 不读这个文件（计划 §11 已把旧 readiness 门降级为 generate 期模板提示），所以
@@ -114,6 +122,11 @@ role。client 不读这个文件（计划 §11 已把旧 readiness 门降级为
 其余无需配置。工作区 `spec.toml` 的 `session_command` 已经按任务拉起 `pi`
 （`["pi", "--session-id", "{session}"]`），client 负责注入本扩展识别的环境变量。
 
+`cluster` 专门解决“会话主体在一个集群的目录树下运行、但挂载的角色工作区属于另一个集群”的夹心代理场景：
+配置该键后，无论会话当前处于哪棵目录树下，都会优先连接该集群中为该角色注册的客户端。若同一集群内存在
+两个同名角色客户端，会直接显式报错拒绝，绝不随意选取。若未配置该键（或指定的集群未发现注册客户端），
+则优雅回退至原有的工作区目录树收敛规则。
+
 ## 2. 能力表
 
 `hello` 只声明真实实现的能力：
@@ -139,7 +152,7 @@ role。client 不读这个文件（计划 §11 已把旧 readiness 门降级为
 
 ### 活动面板
 
-宿主报告有 UI 时（`ctx.hasUI`：TUI 与 RPC 模式为 true，print 与 JSON 模式为 false）且 `ctx.ui.setWidget` 可用，日常 onlyne 通知显示在编辑器上方，widget key 为 `onlyne`。标题行显示 role、连接状态、generation、当前 task id 与阶段。其下最多六条事件，按最新在前排列：`<=` 入站，`=>` 出站，`!!` 警告，`..` 状态，`~~` 重复投递。连续相同事件折成一行并带 `xN`；面板最多八行，每行最多 96 个显示单元，`session_shutdown` 时清除。
+宿主报告有 UI 时（`ctx.hasUI`：TUI 与 RPC 模式为 true，print 与 JSON 模式为 false）且 `ctx.ui.setWidget` 可用，日常 onlyne 通知显示在编辑器上方，widget key 为 `onlyne`。小组件支持 ANSI 与 Tern Surface Protocol（TSP）双渲染面：在 ANSI 终端下使用主题令牌为标题、连接状态、时间戳和方向标记着色排版；在支持 TSP 的 Tern 终端下通过 `describe()` 输出原生可折叠 `card` 组件（`role: "omp.widget.onlyne"`，`variant: "bare"`）与语义化 span。入站投递（`assign` 与 `nudge`）走的就是那张带 `From <sender> · <kind> · <id>` 抬头的 `onlyne_assign` 卡片：`wakeUser` 用 `pi.sendMessage({ customType: "onlyne_assign", display: true, details })` 发出它，`registerMessageRenderer("onlyne_assign", ...)` 画它，模型读到的也正是这一条——投递不会被画两遍又读两遍。`ctx.isIdle()` 为真时 `wakeUser` 传 `{ triggerTurn: true }`，把空闲或已结算的常驻会话欠这张卡片的那个 turn 起起来；繁忙时改传 `{ deliverAs: "followUp" }` 排队。标题行显示 role、连接状态、generation、当前 task id 与阶段。其下最多六条事件，按最新在前排列：`<=` 入站，`=>` 出站，`!!` 警告，`..` 状态，`~~` 重复投递。连续相同事件折成一行并带 `xN`（常驻会话在客户端首次连通前的后台探测保持静默，不刷屏 `reconnecting`）；面板最多八行，每行最多 96 个显示单元，`session_shutdown` 时清除。
 
 ## 3. 工具面
 
@@ -157,7 +170,8 @@ sidechain、`/new`——它们都会带着同一份继承来的环境变量加
 
 ### `onlyne_send{to, text, kind?, image?}`
 
-经 `send` 帧提交一个 envelope。`kind: "note"`（默认）是自由文本，不带 `op_id`。
+经 `send` 帧提交一个 envelope。`kind: "note"`（默认）向运行中、空闲或常驻待命的会话发送无状态交流消息，
+不带 `op_id`，不创建任务记录，也不要求调用 `onlyne_complete`。
 `kind: "task"` 是派人办事，因此带 `o-<uuid>` 幂等键和新生成的 `causality.task`。`image` 是
 png/jpeg/gif/webp 的绝对路径：插件读出内容，base64 编码后挂成 `body.image`。核心限 2 MiB，
 只收四种 mime。结果是 `sent to <role>`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-onlyne",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Onlyne agent adapter for pi: the session lifecycle an onlyne role client expects from a pi host.",
   "type": "module",
   "license": "MIT",

package/src/activity.mjs

@@ -1,5 +1,7 @@
 /** The widget key shared with pi-surface. */
 export const WIDGET_KEY = "onlyne";
+/** The custom message type registered for visible inbound delivery cards. */
+export const ASSIGN_MESSAGE_TYPE = "onlyne_assign";
 /** Render budget below pi's own ten-line cap. */
 export const MAX_LINES = 8;
 /** Line budget that keeps the panel inside one terminal row. */
@@ -19,6 +21,21 @@ const MARKERS = {
   state: "..",
 };
 
+const EVENT_STYLES = {
+  in: { fg: "accent" },
+  dup: { fg: "dim" },
+  out: { fg: "success" },
+  warn: { fg: "warning" },
+  state: { fg: "muted" },
+};
+
+const CONNECTION_STYLES = {
+  connected: { fg: "success", status: "done" },
+  reconnecting: { fg: "warning", status: "running" },
+  detached: { fg: "muted", status: "cancelled" },
+  connecting: { fg: "accent", status: "pending" },
+};
+
 const clean = (value) => String(value ?? "").replace(/\s+/g, " ").trim();
 const points = (value) => Array.from(String(value ?? ""));
 
@@ -62,6 +79,237 @@ function eventLine(event) {
   return cut(`${timeOf(event.at)}  ${marker} ${event.text}${count}`, MAX_WIDTH);
 }
 
+function toneFg(theme, color, text) {
+  if (!theme || typeof theme.fg !== "function") return text;
+  try {
+    return theme.fg(color, text);
+  } catch {
+    return text;
+  }
+}
+
+function toneBold(theme, text) {
+  if (!theme || typeof theme.bold !== "function") return text;
+  try {
+    return theme.bold(text);
+  } catch {
+    return text;
+  }
+}
+
+function styledHeaderLine(state, theme, width) {
+  if (!theme || typeof theme.fg !== "function") return headerLine(state);
+  const role = clean(state.role);
+  const connection = clean(state.connection) || "connecting";
+  const connStyle = CONNECTION_STYLES[connection] ?? CONNECTION_STYLES.connecting;
+  const sep = toneFg(theme, "dim", " · ");
+  const head = role
+    ? `${toneBold(theme, toneFg(theme, "accent", "onlyne"))} ${toneBold(theme, cut(role, 16, false))}`
+    : toneBold(theme, toneFg(theme, "accent", "onlyne"));
+  const parts = [head, toneFg(theme, connStyle.fg, connection)];
+  if (state.generation !== undefined && state.generation !== null) {
+    parts.push(toneFg(theme, "muted", `gen ${state.generation}`));
+  }
+  const taskId = clean(state.taskId);
+  if (taskId) {
+    const phase = clean(state.phase);
+    const phaseTone = phase === "done"
+      ? "success"
+      : phase === "failed" || phase === "blocked"
+        ? "error"
+        : phase.includes("queued") || phase === "running"
+          ? "warning"
+          : "muted";
+    const taskPart = `${toneFg(theme, "muted", "task")} ${toneFg(theme, "accent", cut(taskId, 8, false))}${
+      phase ? ` ${toneFg(theme, phaseTone, phase)}` : ""
+    }`;
+    parts.push(taskPart);
+  }
+  return parts.join(sep);
+}
+
+function styledEventLine(event, theme, maxTextWidth) {
+  if (!theme || typeof theme.fg !== "function") return eventLine(event);
+  const marker = MARKERS[event.kind] ?? MARKERS.state;
+  const style = EVENT_STYLES[event.kind] ?? EVENT_STYLES.state;
+  const count = event.repeats > 0 ? toneFg(theme, "warning", ` ×${event.repeats + 1}`) : "";
+  const bodyBudget = Math.max(12, maxTextWidth - 14 - (event.repeats > 0 ? String(event.repeats + 1).length + 2 : 0));
+  const body = cut(event.text, bodyBudget);
+  const bodyStyled = event.kind === "warn"
+    ? toneFg(theme, "warning", body)
+    : event.kind === "dup"
+      ? toneFg(theme, "dim", body)
+      : body;
+  return `${toneFg(theme, "dim", timeOf(event.at))}  ${toneFg(theme, style.fg, marker)} ${bodyStyled}${count}`;
+}
+
+function describeHeaderSpans(state) {
+  const role = clean(state.role);
+  const connection = clean(state.connection) || "connecting";
+  const connStyle = CONNECTION_STYLES[connection] ?? CONNECTION_STYLES.connecting;
+  const spans = [{ t: "onlyne", s: "accent strong" }];
+  if (role) spans.push({ t: ` ${cut(role, 16, false)}`, s: "strong" });
+  spans.push({ t: " · ", s: "dim" }, { t: connection, s: connStyle.fg });
+  if (state.generation !== undefined && state.generation !== null) {
+    spans.push({ t: " · ", s: "dim" }, { t: `gen ${state.generation}`, s: "muted" });
+  }
+  const taskId = clean(state.taskId);
+  if (taskId) {
+    const phase = clean(state.phase);
+    const phaseTone = phase === "done"
+      ? "success"
+      : phase === "failed" || phase === "blocked"
+        ? "error"
+        : phase.includes("queued") || phase === "running"
+          ? "warning"
+          : "muted";
+    spans.push(
+      { t: " · ", s: "dim" },
+      { t: "task ", s: "muted" },
+      { t: cut(taskId, 8, false), s: "accent mono" },
+    );
+    if (phase) spans.push({ t: ` ${phase}`, s: phaseTone });
+  }
+  return spans;
+}
+
+function describeEventRow(event, index) {
+  const marker = MARKERS[event.kind] ?? MARKERS.state;
+  const style = EVENT_STYLES[event.kind] ?? EVENT_STYLES.state;
+  const bodyTone = event.kind === "warn" ? "warning" : event.kind === "dup" ? "dim" : undefined;
+  const spans = [
+    { t: timeOf(event.at), s: "dim mono" },
+    { t: `  ${marker} `, s: `${style.fg} mono strong` },
+    bodyTone ? { t: event.text, s: bodyTone } : { t: event.text },
+  ];
+  if (event.repeats > 0) {
+    spans.push({ t: ` ×${event.repeats + 1}`, s: "warning mono" });
+  }
+  return {
+    k: "text",
+    p: { spans, truncate: "end", role: `onlyne.event.${event.kind}` },
+    key: `ev-${index}`,
+  };
+}
+
+/**
+ * Build a TSP `NativeNode` card for Tern surfaces (`Component.describe()`).
+ */
+export function describeActivityNode(state, events, shown = SHOW_EVENTS, collapsed = false) {
+  const connection = clean(state.connection) || "connecting";
+  const connStyle = CONNECTION_STYLES[connection] ?? CONNECTION_STYLES.connecting;
+  const visible = events.slice(0, shown);
+  return {
+    k: "card",
+    p: {
+      role: "omp.widget.onlyne",
+      variant: "bare",
+      status: connStyle.status,
+      head: describeHeaderSpans(state),
+      collapsible: visible.length > 0,
+      collapsed: visible.length > 0 ? Boolean(collapsed) : false,
+    },
+    c: visible.map((ev, index) => describeEventRow(ev, index)),
+  };
+}
+
+/**
+ * Render an inbound Onlyne delivery (`customType: "onlyne_assign"`) as a
+ * framed transcript block on ANSI terminals and a native TSP card on Tern.
+ */
+export function createAssignMessageComponent(details, messageContent, theme, collapsed = false) {
+  const from = clean(details?.from) || "cluster";
+  const kind = clean(details?.kind) || "task";
+  const taskId = clean(details?.taskId);
+  const shortId = taskId ? cut(taskId, 8, false) : "";
+  const rawBody = clean(details?.bodyText)
+    || (typeof messageContent === "string"
+      ? messageContent
+      : Array.isArray(messageContent)
+        ? messageContent.filter((p) => p?.type === "text" && typeof p.text === "string").map((p) => p.text).join("\n")
+        : "");
+  const bodyLines = String(details?.bodyText ?? (typeof messageContent === "string" ? messageContent : rawBody))
+    .replace(/\r\n/g, "\n")
+    .split("\n");
+  const headLabel = `From ${from} · ${kind}${shortId ? ` · ${shortId}` : ""}`;
+  const kindTone = kind === "note" ? "info" : kind === "nudge" ? "warning" : "accent";
+  let cachedWidth = -1;
+  let cachedRows = null;
+  let cachedNode = null;
+  let isCollapsed = Boolean(collapsed);
+
+  const buildNode = () => {
+    const headSpans = [
+      { t: `From ${from}`, s: "accent strong" },
+      { t: " · ", s: "dim" },
+      { t: kind, s: `${kindTone} mono` },
+    ];
+    if (shortId) {
+      headSpans.push({ t: " · ", s: "dim" }, { t: shortId, s: "muted mono" });
+    }
+    const mdText = String(details?.bodyText ?? (typeof messageContent === "string" ? messageContent : rawBody)).trim();
+    return {
+      k: "card",
+      p: {
+        role: `omp.custom.onlyne.${kind}`,
+        tone: kind === "nudge" ? "warning" : "accent",
+        head: headSpans,
+        collapsible: true,
+        collapsed: isCollapsed,
+      },
+      c: mdText ? [{ k: "md", p: { text: mdText }, key: "body" }] : [],
+    };
+  };
+
+  const buildRows = (width = MAX_WIDTH) => {
+    const w = Math.max(16, Math.min(width, MAX_WIDTH));
+    const inner = Math.max(12, w - 4);
+    const topText = ` ${cut(headLabel, inner - 2)} `;
+    const topFill = "─".repeat(Math.max(0, w - 2 - points(topText).length));
+    const rows = [
+      `${toneFg(theme, "muted", "╭")}${toneBold(theme, toneFg(theme, "accent", topText))}${toneFg(theme, "muted", `${topFill}╮`)}`,
+    ];
+    const visibleBody = isCollapsed
+      ? [cut(clean(rawBody), inner)]
+      : bodyLines.flatMap((line) => {
+          const trimmed = line.replace(/\t/g, "  ");
+          return trimmed.length === 0 ? [""] : [cut(trimmed, inner)];
+        });
+    for (const line of visibleBody) {
+      const pad = " ".repeat(Math.max(0, inner - points(line).length));
+      rows.push(`${toneFg(theme, "muted", "│")} ${toneFg(theme, "text", line)}${pad} ${toneFg(theme, "muted", "│")}`);
+    }
+    rows.push(`${toneFg(theme, "muted", `╰${"─".repeat(Math.max(0, w - 2))}╯`)}`);
+    return rows;
+  };
+
+  return {
+    render(width = MAX_WIDTH) {
+      if (cachedRows && cachedWidth === width) return cachedRows;
+      cachedWidth = width;
+      cachedRows = buildRows(width);
+      return cachedRows;
+    },
+    describe() {
+      cachedNode ??= buildNode();
+      return cachedNode;
+    },
+    handleNativeEvent(event) {
+      if (event?.type === "toggle" && typeof event.collapsed === "boolean") {
+        isCollapsed = event.collapsed;
+        cachedRows = null;
+        cachedNode = null;
+      }
+    },
+    invalidate() {
+      cachedWidth = -1;
+      cachedRows = null;
+      cachedNode = null;
+    },
+    dispose() {},
+  };
+}
+
 /**
  * Activity is a pure panel model: header state plus newest-first event history.
  * `lines()` reads stored state only, so identical state gives identical output.
@@ -70,6 +318,7 @@ export function createActivity({ maxEvents = SHOW_EVENTS, clock = () => new Date
   const state = { connection: "connecting" };
   const events = [];
   const shown = Math.max(0, Math.min(Number(maxEvents) || 0, MAX_LINES - 1));
+  let collapsed = false;
   const api = {
     note(kind, text) {
       const next = noteText(text);
@@ -90,6 +339,51 @@ export function createActivity({ maxEvents = SHOW_EVENTS, clock = () => new Date
     lines() {
       return [headerLine(state), ...events.slice(0, shown).map(eventLine)].slice(0, MAX_LINES);
     },
+    ansiLines(theme, width = MAX_WIDTH) {
+      const padX = width >= 4 ? " " : "";
+      const innerWidth = Math.max(24, Math.min(MAX_WIDTH, width - padX.length * 2));
+      if (collapsed) {
+        return [`${padX}${styledHeaderLine(state, theme, innerWidth)}`];
+      }
+      return [
+        `${padX}${styledHeaderLine(state, theme, innerWidth)}`,
+        ...events.slice(0, shown).map((ev) => `${padX}${styledEventLine(ev, theme, innerWidth)}`),
+      ].slice(0, MAX_LINES);
+    },
+    describe() {
+      return describeActivityNode(state, events, shown, collapsed);
+    },
+    component(theme, tui = null) {
+      let cachedWidth = -1;
+      let cachedRows = null;
+      let cachedNode = null;
+      return {
+        render(width = MAX_WIDTH) {
+          if (cachedRows && cachedWidth === width) return cachedRows;
+          cachedWidth = width;
+          cachedRows = api.ansiLines(theme, width);
+          return cachedRows;
+        },
+        describe() {
+          cachedNode ??= api.describe();
+          return cachedNode;
+        },
+        handleNativeEvent(event) {
+          if (event?.type === "toggle" && typeof event.collapsed === "boolean") {
+            collapsed = event.collapsed;
+            cachedRows = null;
+            cachedNode = null;
+            tui?.requestRender?.();
+          }
+        },
+        invalidate() {
+          cachedWidth = -1;
+          cachedRows = null;
+          cachedNode = null;
+        },
+        dispose() {},
+      };
+    },
     events,
   };
   return api;

package/src/activity.test.mjs

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 
-import { createActivity, MAX_LINES, MAX_TEXT, MAX_WIDTH, SHOW_EVENTS } from "./activity.mjs";
+import { createActivity, createAssignMessageComponent, MAX_LINES, MAX_TEXT, MAX_WIDTH, SHOW_EVENTS } from "./activity.mjs";
 
 const clock = () => new Date("2026-09-13T09:08:07");
 
@@ -61,3 +61,71 @@ test("default render shows the newest SHOW_EVENTS events", () => {
   assert.match(lines[1], /event 9$/);
   assert.match(lines.at(-1), new RegExp(`event ${SHOW_EVENTS + 4 - SHOW_EVENTS}$`));
 });
+
+test("describe() produces a Tern TSP card node and component() supports toggle", () => {
+  const activity = createActivity({ clock }).set({
+    role: "dpdp",
+    connection: "connected",
+    generation: 1,
+    taskId: "abcdef012345",
+    phase: "running",
+  });
+  activity.note("state", "connected role=dpdp gen=1 host=probe,recycle");
+  activity.note("warn", "heartbeat refused").note("warn", "heartbeat refused");
+
+  const node = activity.describe();
+  assert.equal(node.k, "card");
+  assert.equal(node.p.role, "omp.widget.onlyne");
+  assert.equal(node.p.variant, "bare");
+  assert.equal(node.p.status, "done");
+  assert.equal(node.p.collapsible, true);
+  assert.equal(node.p.collapsed, false);
+  assert.equal(node.c.length, 2);
+  assert.equal(node.c[0].k, "text");
+  assert.equal(node.c[0].p.role, "onlyne.event.warn");
+  assert.ok(node.c[0].p.spans.some((s) => s.t === " ×2"));
+
+  const theme = {
+    fg: (color, text) => `<${color}>${text}</${color}>`,
+    bold: (text) => `<b>${text}</b>`,
+  };
+  let rendered = 0;
+  const comp = activity.component(theme, { requestRender: () => { rendered += 1; } });
+  const rows = comp.render(80);
+  assert.equal(rows.length, 3);
+  assert.ok(rows[0].startsWith(" <b><accent>onlyne</accent></b> <b>dpdp</b>"));
+  assert.equal(comp.render(80), rows, "same width returns cached rows reference");
+
+  comp.handleNativeEvent({ type: "toggle", collapsed: true });
+  assert.equal(rendered, 1);
+  assert.equal(comp.describe().p.collapsed, true);
+  assert.equal(comp.render(80).length, 1);
+});
+
+test("createAssignMessageComponent renders ANSI box and TSP card for onlyne_assign", () => {
+  const theme = {
+    fg: (color, text) => `<${color}>${text}</${color}>`,
+    bold: (text) => `<b>${text}</b>`,
+  };
+  const comp = createAssignMessageComponent(
+    {
+      role: "caerulea",
+      taskId: "97971b93-1111-2222-3333-444444444444",
+      kind: "note",
+      from: "role:_supervisor",
+      bodyText: "hello caerulea",
+    },
+    "From _supervisor:\n\nhello caerulea",
+    theme,
+    false,
+  );
+  const rows = comp.render(72);
+  assert.ok(rows[0].includes("From role:_supervisor · note · 97971b93"));
+  assert.ok(rows.some((r) => r.includes("hello caerulea")));
+
+  const node = comp.describe();
+  assert.equal(node.k, "card");
+  assert.equal(node.p.role, "omp.custom.onlyne.note");
+  assert.equal(node.c[0].k, "md");
+  assert.equal(node.c[0].p.text, "hello caerulea");
+});