pi-onlyne 1.0.0 → 1.1.0

package/README.md

@@ -53,7 +53,7 @@ extension travels with it: nothing is installed globally.
 ```toml
 # spec.toml
 [server]
-agent_package = "/abs/path/to/integrations/pi-onlyne"   # read once, at generate time
+agent_package = "/abs/path/to/plugins/onlyne-agent-pi"   # read once, at generate time
 ```
 
 ```bash
@@ -63,7 +63,7 @@ onlyne server generate --root <server-root> --out <dir>
 The generated `.pi/settings.json` then carries:
 
 ```json
-{ "packages": ["../.onlyne/agent/pi-onlyne"] }
+{ "packages": ["../.onlyne/agent/onlyne-agent-pi"] }
 ```
 
 `pi list` shows the entry under "Project packages". To verify the load itself, make the
@@ -72,14 +72,26 @@ copied `index.ts` throw and watch for the failure.
 ### Manual (no generator)
 
 ```bash
-cp -R integrations/pi-onlyne <ws>/.onlyne/agent/pi-onlyne
-printf '{"packages":["../.onlyne/agent/pi-onlyne"]}\n' > <ws>/.pi/settings.json
+cp -R plugins/onlyne-agent-pi <ws>/.onlyne/agent/onlyne-agent-pi
+printf '{"packages":["../.onlyne/agent/onlyne-agent-pi"]}\n' > <ws>/.pi/settings.json
 ```
 
+### From npm
+
+```bash
+pi install pi-onlyne              # user-level: every pi process on this box loads it
+```
+
+The published package is `pi-onlyne` on npm; `pi install pi-onlyne@<version>` pins
+one. This route reaches ordinary interactive sessions too, and there the extension
+stays inert (no `ONLYNE_ROLE`, so no adapter). A role workspace needs no global
+install to get a panel: the file-level copy above, or `onlyne server generate`,
+scopes the plugin to the workspace that serves the role.
+
 ### One-off / testing
 
 ```bash
-pi --session-id <id> -e /abs/path/to/integrations/pi-onlyne -ns -nc
+pi --session-id <id> -e /abs/path/to/plugins/onlyne-agent-pi -ns -nc
 ```
 
 ### The switch file
@@ -121,8 +133,13 @@ What happens when a pi API is missing, and what the host does then:
 | no `sendMessage` | probed | the role prose from `welcome` is not injected as context; the task itself still arrives |
 | no `appendEntry` | probed | no `onlyne-assign` / `onlyne-complete` session entries are recorded |
 | no `ui.setStatus` | guarded | the footer status line is skipped |
+| no `ui.setWidget` | guarded | routine notices continue through the footer status line and the `[pi-onlyne]` stderr line |
 | no `ctx.shutdown` | guarded | `recycle` and a completion still settle the task; the process stays up for the operator to close |
 
+### 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.
+
 ## 3. Tools
 
 Registered only inside an onlyne session.
@@ -193,7 +210,7 @@ judges delivery facts only — whether a role was reached — and never the shap
 of the text that was sent.
 
 The policy lives next to the plugin's `package.json`, so it travels inside the copy a
-generated workspace loads: `<ws>/.onlyne/agent/pi-onlyne/relay.toml` in a generated
+generated workspace loads: `<ws>/.onlyne/agent/onlyne-agent-pi/relay.toml` in a generated
 workspace, `relay.toml` in a manual installation.
 
 ```toml
@@ -334,7 +351,7 @@ client injected none, §5).
 | `ready refused: internal: unknown session for …` | the plugin mounted and reported for a task the client never staged (normal when pi is started by hand outside a task) | start pi under the client, not by hand |
 | `assign` never arrives | the client's `session_command` did not spawn pi, or `inject` was dropped | the client log for the spawn line; `/onlyne status` for the capability set |
 | ledger stays `in_flight` | no completion was reported: no turn ran, or `agent_settled` never fired | the pi session file for `onlyne-assign` / `onlyne-complete` entries |
-| `onlyne_complete` answers `relay guard: missing handoff to: …` | the workspace's spec (or a `relay.toml` standing in for it) names a role this session never sent to | the plugin's stderr line `relay guard from …` names the source and `required=…` the policy; `relay guard: missing handoff …` names the delivered set |
+| `onlyne_complete` answers `relay guard: missing handoff to: …` | the workspace's spec (or a `relay.toml` standing in for it) names a role this session never sent to | routine notices appear in the `onlyne` panel; stderr keeps refusals such as `relay guard from …`, socket errors, timeouts and framing faults; `required=…` names the policy; `relay guard: missing handoff …` names the delivered set |
 | `hello … forbidden` / connection closed right after `hello` | the mount role does not match the client's role | `hello.args.mount.role` vs the workspace's role |
 | `frame_too_large` | a body above 8 MiB | only reachable through an oversize outbound image; the ceiling is the core's |
 | tools missing | `pi.registerTool` is absent in that pi version | `/onlyne status`; the capability table above |
@@ -348,7 +365,7 @@ client injected none, §5).
 ## 9. Development
 
 ```bash
-cd integrations/pi-onlyne
+cd plugins/onlyne-agent-pi
 node --test src/*.test.mjs        # framing, protocol, agent state machine, config, relay guard
 ```
 

package/README.zh.md

@@ -47,7 +47,7 @@ pi 0.85.1 只加载这个写法。项目 `packages` 里的路径以 settings 文
 ```toml
 # spec.toml
 [server]
-agent_package = "/abs/path/to/integrations/pi-onlyne"   # 只在 generate 时读一次
+agent_package = "/abs/path/to/plugins/onlyne-agent-pi"   # 只在 generate 时读一次
 ```
 
 ```bash
@@ -57,7 +57,7 @@ onlyne server generate --root <server-root> --out <dir>
 生成的 `.pi/settings.json` 形如：
 
 ```json
-{ "packages": ["../.onlyne/agent/pi-onlyne"] }
+{ "packages": ["../.onlyne/agent/onlyne-agent-pi"] }
 ```
 
 `pi list` 会把这条列在 “Project packages” 下。要验证真的加载了，就让复制进来的 `index.ts`
@@ -66,14 +66,25 @@ onlyne server generate --root <server-root> --out <dir>
 ### 手工（不经过 generate）
 
 ```bash
-cp -R integrations/pi-onlyne <ws>/.onlyne/agent/pi-onlyne
-printf '{"packages":["../.onlyne/agent/pi-onlyne"]}\n' > <ws>/.pi/settings.json
+cp -R plugins/onlyne-agent-pi <ws>/.onlyne/agent/onlyne-agent-pi
+printf '{"packages":["../.onlyne/agent/onlyne-agent-pi"]}\n' > <ws>/.pi/settings.json
 ```
 
+### 从 npm 装
+
+```bash
+pi install pi-onlyne              # 用户级：这台机器上每个 pi 进程都会加载
+```
+
+发布名是 npm 上的 `pi-onlyne`，`pi install pi-onlyne@<version>` 钉住某一版。这条路径会覆盖
+普通交互会话，那里没有 `ONLYNE_ROLE`，扩展保持静默（见 §1 的身份门）。role workspace 想要面
+板，不必装到全局：上面那份文件级复制、或者 `onlyne server generate`，都把插件限定在服务这个
+role 的 workspace 里。
+
 ### 一次性 / 测试
 
 ```bash
-pi --session-id <id> -e /abs/path/to/integrations/pi-onlyne -ns -nc
+pi --session-id <id> -e /abs/path/to/plugins/onlyne-agent-pi -ns -nc
 ```
 
 ### 开关文件
@@ -112,8 +123,13 @@ role。client 不读这个文件（计划 §11 已把旧 readiness 门降级为
 | `sendMessage` | `session_start` | `welcome` 的 role prose 不再作为上下文注入；任务本身照常到达 |
 | `appendEntry` | `session_start` | 不再写 `onlyne-assign` / `onlyne-complete` 会话条目 |
 | `ui.setStatus` | 调用点保护 | 跳过 footer 状态行 |
+| `ui.setWidget` | 调用点保护 | 日常通知继续走 footer 状态行与 `[pi-onlyne]` stderr 行 |
 | `ctx.shutdown` | 调用点保护 | `recycle` 与 completion 照常结算任务；进程留给操作者自己关闭 |
 
+### 活动面板
+
+宿主报告有 UI 时（`ctx.hasUI`：TUI 与 RPC 模式为 true，print 与 JSON 模式为 false）且 `ctx.ui.setWidget` 可用，日常 onlyne 通知显示在编辑器上方，widget key 为 `onlyne`。标题行显示 role、连接状态、generation、当前 task id 与阶段。其下最多六条事件，按最新在前排列：`<=` 入站，`=>` 出站，`!!` 警告，`..` 状态，`~~` 重复投递。连续相同事件折成一行并带 `xN`；面板最多八行，每行最多 96 个显示单元，`session_shutdown` 时清除。
+
 ## 3. 工具面
 
 仅在 onlyne session 内注册。
@@ -170,7 +186,7 @@ ack 之后、进程退出之前。completion 是按 client 手里的元组结算
 事实——某个 role 有没有被触达——绝不看发出去的文本长什么样、写得好不好。
 
 策略文件放在插件自己的 `package.json` 旁边，因此随 generate 出的工作区一起被带进去：生成的工作
-区里是 `<ws>/.onlyne/agent/pi-onlyne/relay.toml`，手工安装则是插件目录下的 `relay.toml`。
+区里是 `<ws>/.onlyne/agent/onlyne-agent-pi/relay.toml`，手工安装则是插件目录下的 `relay.toml`。
 
 ```toml
 relay_required = ["writer"]        # 这些 role 必须收到过接力
@@ -290,7 +306,7 @@ stderr 告警并忽略，把机会让回文件。
 | `ready refused: internal: unknown session for …` | 插件为 client 从未暂存的任务报了 ready（手工起 pi 时的正常现象） | 让 client 拉起 pi，而不是手工起 |
 | `assign` 一直不来 | client 的 `session_command` 没能拉起 pi，或 `inject` 被降级 | client 日志里的 spawn 行；`/onlyne status` 看能力集 |
 | ledger 停在 `in_flight` | 没有 completion：没跑 turn，或 `agent_settled` 没触发 | pi session 文件里的 `onlyne-assign` / `onlyne-complete` 条目 |
-| `onlyne_complete` 回答 `relay guard: missing handoff to: …` | 工作区的 spec（或顶替它的 `relay.toml`）点名了一个本会话从未触达的 role | 插件 stderr 的 `relay guard from …` 说明来源、`required=…` 说明策略；`relay guard: missing handoff …` 列出已投递集合 |
+| `onlyne_complete` 回答 `relay guard: missing handoff to: …` | 工作区的 spec（或顶替它的 `relay.toml`）点名了一个本会话从未触达的 role | 日常通知显示在 `onlyne` 面板；stderr 保留 `relay guard from …` 等拒绝、socket 错误、超时与帧错误；`required=…` 说明策略；`relay guard: missing handoff …` 列出已投递集合 |
 | `hello` 后立刻 `forbidden` / 断连 | mount role 与 client 的 role 不一致 | `hello.args.mount.role` 对该工作区的 role |
 | `frame_too_large` | 正文超过 8 MiB | 只会由超限的出站图片触发；上限来自核心 |
 | 工具缺失 | 该 pi 版本没有 `pi.registerTool` | `/onlyne status`；对照上面的能力表 |
@@ -304,7 +320,7 @@ stderr 告警并忽略，把机会让回文件。
 ## 9. 开发与验证
 
 ```bash
-cd integrations/pi-onlyne
+cd plugins/onlyne-agent-pi
 node --test src/*.test.mjs        # 帧编解码、协议词汇、agent 状态机、配置、接力守卫
 ```
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "pi-onlyne",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Onlyne agent adapter for pi: the session lifecycle an onlyne role client expects from a pi host.",
   "type": "module",
+  "main": "./src/index.ts",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -31,10 +32,12 @@
     ]
   },
   "scripts": {
-    "test": "node --test src/*.test.mjs"
+    "test": "node --test src/*.test.mjs",
+    "test:live": "node --test src/agent.live.test.mjs"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
-  }
+  },
+  "peerDevDependencies": {}
 }

package/relay.toml.example

@@ -1,18 +1,13 @@
-# Manual-installation escape hatch for the relay guard.
+# Onlyne relay guard policy — copy to `relay.toml` next to this package's `package.json`.
 #
-# A generated workspace gets its guard policy from spec.toml ([[client]] rows
-# `relay_required = ["writer"]`, `relay_count = 2` — `relay_required_count` is
-# accepted as the guard file's own spelling), which the client injects into
-# every session it spawns. This file is for installations that manage their
-# own workspace: drop it beside package.json and the guard reads it when the
-# environment carries no policy. Environment wins over this file; no policy in
-# either place leaves the guard off.
+# Manual installations only. A generated workspace states the same policy in the
+# server spec's `[[client]]` entry (`relay_required` / `relay_count`), which the
+# client injects as `ONLYNE_RELAY_REQUIRED` / `ONLYNE_RELAY_COUNT`. Those
+# environment variables win, and a file they shadow is ignored outright.
 #
-# relay_required wins over relay_count when both are present.
+# Closed subset: flat `key = value` lines, the two keys below, one-line arrays of
+# double-quoted strings, `#` comments. Anything outside that warns on stderr and
+# is ignored. `relay_required` wins when both keys are present.
 
-# Downstream roles one of this role's sessions must have handed work to before
-# it may report a terminal outcome:
-#   relay_required = ["writer", "auditor"]
-
-# ... or this many distinct downstream roles:
-#   relay_required_count = 2
+relay_required = ["writer"]        # these roles must have received a handoff
+relay_required_count = 2           # ... or this many distinct downstream roles

package/src/activity.mjs

@@ -0,0 +1,96 @@
+/** The widget key shared with pi-surface. */
+export const WIDGET_KEY = "onlyne";
+/** Render budget below pi's own ten-line cap. */
+export const MAX_LINES = 8;
+/** Line budget that keeps the panel inside one terminal row. */
+export const MAX_WIDTH = 96;
+/** Event text budget before the final line-width cap. */
+export const MAX_TEXT = 72;
+/** Retained newest-first activity history. */
+export const KEEP_EVENTS = 64;
+/** Default count of activity rows below the header. */
+export const SHOW_EVENTS = 6;
+
+const MARKERS = {
+  in: "<=",
+  dup: "~~",
+  out: "=>",
+  warn: "!!",
+  state: "..",
+};
+
+const clean = (value) => String(value ?? "").replace(/\s+/g, " ").trim();
+const points = (value) => Array.from(String(value ?? ""));
+
+function cut(value, width, mark = true) {
+  const chars = points(value);
+  if (chars.length <= width) return chars.join("");
+  if (width <= 0) return "";
+  if (!mark || width === 1) return chars.slice(0, width).join("");
+  return `${chars.slice(0, width - 1).join("")}…`;
+}
+
+function noteText(value) {
+  const text = clean(value);
+  const chars = points(text);
+  return chars.length > MAX_TEXT ? `${chars.slice(0, MAX_TEXT).join("")}…` : text;
+}
+
+function timeOf(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  const two = (number) => String(number).padStart(2, "0");
+  return `${two(date.getHours())}:${two(date.getMinutes())}:${two(date.getSeconds())}`;
+}
+
+function headerLine(state) {
+  const role = clean(state.role);
+  const connection = clean(state.connection) || "connecting";
+  const first = role ? `onlyne ${cut(role, 16, false)}` : "onlyne";
+  const parts = [first, connection];
+  if (state.generation !== undefined && state.generation !== null) parts.push(`gen ${state.generation}`);
+  const taskId = clean(state.taskId);
+  if (taskId) {
+    const phase = clean(state.phase);
+    parts.push(`task ${cut(taskId, 8, false)}${phase ? ` ${phase}` : ""}`);
+  }
+  return cut(parts.join(" · "), MAX_WIDTH);
+}
+
+function eventLine(event) {
+  const marker = MARKERS[event.kind] ?? MARKERS.state;
+  const count = event.repeats > 0 ? ` x${event.repeats + 1}` : "";
+  return cut(`${timeOf(event.at)}  ${marker} ${event.text}${count}`, MAX_WIDTH);
+}
+
+/**
+ * Activity is a pure panel model: header state plus newest-first event history.
+ * `lines()` reads stored state only, so identical state gives identical output.
+ */
+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));
+  const api = {
+    note(kind, text) {
+      const next = noteText(text);
+      const current = events[0];
+      if (current && current.kind === kind && current.text === next) {
+        current.repeats += 1;
+        current.at = clock();
+        return api;
+      }
+      events.unshift({ at: clock(), kind, text: next, repeats: 0 });
+      if (events.length > KEEP_EVENTS) events.length = KEEP_EVENTS;
+      return api;
+    },
+    set(patch = {}) {
+      Object.assign(state, patch);
+      return api;
+    },
+    lines() {
+      return [headerLine(state), ...events.slice(0, shown).map(eventLine)].slice(0, MAX_LINES);
+    },
+    events,
+  };
+  return api;
+}

package/src/activity.test.mjs

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { createActivity, MAX_LINES, MAX_TEXT, MAX_WIDTH, SHOW_EVENTS } from "./activity.mjs";
+
+const clock = () => new Date("2026-09-13T09:08:07");
+
+test("header renders before welcome and after state updates", () => {
+  const activity = createActivity({ clock }).set({ role: "planner" });
+  assert.deepEqual(activity.lines(), ["onlyne planner · connecting"]);
+
+  activity.set({ connection: "connected", generation: 3, taskId: "abcdef012345", phase: "running" });
+  assert.equal(activity.lines()[0], "onlyne planner · connected · gen 3 · task abcdef01 running");
+});
+
+test("task tail is absent with no task", () => {
+  const activity = createActivity({ clock }).set({ role: "planner", connection: "connected", generation: 2, phase: "running" });
+  assert.equal(activity.lines()[0], "onlyne planner · connected · gen 2");
+});
+
+test("matching events merge and new text gets a new row", () => {
+  const activity = createActivity({ clock });
+  activity.note("warn", "x").note("warn", "x");
+  assert.equal(activity.events.length, 1);
+  assert.equal(activity.events[0].repeats, 1);
+  assert.match(activity.lines()[1], /09:08:07  !! x x2$/);
+
+  activity.note("warn", "y");
+  assert.equal(activity.events.length, 2);
+  assert.match(activity.lines()[1], /09:08:07  !! y$/);
+});
+
+test("long event text is cut at MAX_TEXT", () => {
+  const activity = createActivity({ clock });
+  activity.note("state", "a".repeat(MAX_TEXT + 10));
+  assert.equal(Array.from(activity.events[0].text).length, MAX_TEXT + 1);
+  assert.ok(activity.events[0].text.endsWith("…"));
+});
+
+test("hostile input stays inside render bounds", () => {
+  const activity = createActivity({ maxEvents: 100, clock }).set({
+    role: "r".repeat(48),
+    connection: "connected",
+    generation: 999,
+    taskId: "1234567890abcdef",
+    phase: "running",
+  });
+  for (let index = 0; index < 100; index += 1) activity.note("warn", `${index} ${"x".repeat(5_000)}`);
+
+  const lines = activity.lines();
+  assert.ok(lines.length <= MAX_LINES, `line count ${lines.length}`);
+  for (const line of lines) assert.ok(Array.from(line).length <= MAX_WIDTH, line);
+});
+
+test("identical state gives identical output", () => {
+  const activity = createActivity({ clock }).set({ role: "planner", connection: "connected" });
+  activity.note("in", "build it");
+  assert.deepEqual(activity.lines(), activity.lines());
+});
+
+test("default render shows the newest SHOW_EVENTS events", () => {
+  const activity = createActivity({ clock });
+  for (let index = 0; index < SHOW_EVENTS + 4; index += 1) activity.note("state", `event ${index}`);
+
+  const lines = activity.lines();
+  assert.equal(lines.length, SHOW_EVENTS + 1);
+  assert.match(lines[1], /event 9$/);
+  assert.match(lines.at(-1), new RegExp(`event ${SHOW_EVENTS + 4 - SHOW_EVENTS}$`));
+});

package/src/agent.mjs

@@ -7,15 +7,23 @@
 // module decides *what* the protocol says and hands the *effects* to the
 // surface, which is why the whole state machine is testable against a plain
 // Node unix socket.
+//
+// What the human sees travels through one funnel, `notice` below: the pi widget
+// panel when the host has `ctx.ui.setWidget`, the footer status line plus a
+// `[pi-onlyne]` stderr line when it has not. `log` keeps the diagnostics — a
+// refused report, a socket error, a timeout, a framing fault — because those
+// matter to a host with no panel at all.
 
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createConnection } from "node:net";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { createFrameDecoder, encodeFrame } from "./frame.mjs";
+import { createActivity } from "./activity.mjs";
 import {
   DEFAULT_HEARTBEAT_MS,
   assignAckArgs,
   completeReport,
+  describePrincipal,
   detachArgs,
   heartbeatReport,
   helloArgs,
@@ -77,6 +85,7 @@ export class OnlyneAgent {
    *   taskId: string,
    *   surface: any,
    *   log?: (line: string, data?: unknown) => void,
+   *   activity?: { note: (kind: string, text: string) => any, set: (patch: any) => any, lines: () => string[], events: any[] },
    *   relay?: { required?: string[], count?: number | null },
    *   capabilities?: string[],
    *   heartbeatMs?: number,
@@ -95,6 +104,9 @@ export class OnlyneAgent {
     this.sessionId = options.sessionId;
     this.envTaskId = options.taskId;
     this.surface = options.surface;
+    /** The widget panel's model (`activity.mjs`); seeded with the local role. */
+    this.activity = options.activity ?? createActivity();
+    this.activity.set({ role: options.role });
     this.log = options.log ?? (() => {});
     /** The relay guard's policy; the default guards nothing (`relay.mjs`). */
     this.relay = options.relay ?? DEFAULT_RELAY;
@@ -181,7 +193,8 @@ export class OnlyneAgent {
     }
     this.connected = false;
     this.socket = null;
-    this.surface.status?.("onlyne: detached");
+    this.activity.set({ connection: "detached", taskId: null });
+    this.notice("state", `detached (${reason})`);
   }
 
   /** One line for `/onlyne status`. */
@@ -196,6 +209,7 @@ export class OnlyneAgent {
       tasks: this.activeTasks().map((task) => task.taskId),
       pendingCompletion: this.pendingCompletion?.taskId ?? null,
       lastError: this.lastError ? String(this.lastError.message ?? this.lastError) : null,
+      activity: this.activity.events.slice(0, 5),
       stats: { ...this.stats },
     };
   }
@@ -253,7 +267,8 @@ export class OnlyneAgent {
     this.deferredPushes = [];
     this.rejectAll("connection lost");
     this.stopHeartbeat();
-    this.surface.status?.(this.closed ? "onlyne: detached" : "onlyne: reconnecting");
+    this.activity.set({ connection: this.closed ? "detached" : "reconnecting" });
+    this.notice("state", this.closed ? "detached" : "reconnecting");
     if (socket && !socket.destroyed) socket.destroy();
     this.scheduleReconnect();
   }
@@ -263,7 +278,6 @@ export class OnlyneAgent {
     const delay = this.ladder[Math.min(this.attempt, this.ladder.length - 1)];
     this.attempt += 1;
     this.stats.reconnects += 1;
-    this.log(`reconnecting in ${delay}ms`);
     this.reconnectHandle = this.timer.set(() => {
       this.reconnectHandle = null;
       if (!this.closed) this.connect();
@@ -274,7 +288,6 @@ export class OnlyneAgent {
     this.attempt = 0;
     // From here until the welcome is adopted, pushes queue instead of running.
     this.handshaking = true;
-    this.log("connected; sending hello");
     const args = helloArgs({
       role: this.role,
       session: this.sessionId,
@@ -301,9 +314,16 @@ export class OnlyneAgent {
     // A fresh connection has reported nothing: the next beat is news.
     this.lastPhase = null;
     this.agentState = this.tasks.size > 0 ? "idle" : "ready";
-    this.surface.status?.(`onlyne: ${welcome.role}`);
-    this.log(`welcome role=${welcome.role} generation=${welcome.generation} capabilities=${welcome.hostCapabilities.join(",")}`);
-    this.surface.welcome?.(welcome);
+    this.activity.set({
+      role: welcome.role,
+      connection: "connected",
+      generation: welcome.generation,
+      // A reconnect inherits the task this process serves: the panel says so
+      // from the first beat, with the assignment still queued behind the hello.
+      taskId: this.activeTaskId() ?? null,
+      phase: this.agentState,
+    });
+    this.notice("state", `connected role=${welcome.role} gen=${welcome.generation} host=${welcome.hostCapabilities.join(",")}`);
     const prose = welcome.prose.trim();
     if (prose && !this.deliveredProse.has(prose)) {
       this.deliveredProse.add(prose);
@@ -408,7 +428,7 @@ export class OnlyneAgent {
     else if (op === "recycle") void this.onRecycle(args);
     else if (op === "config_get") void this.onConfigGet(args);
     else if (op === "bye") {
-      this.log(`host bye: ${args.reason ?? "unspecified"}`);
+      this.notice("state", `host bye: ${args.reason ?? "unspecified"}`);
       this.dropSocket();
     } else if (op) this.log(`ignoring host op ${op}`);
   }
@@ -426,6 +446,25 @@ export class OnlyneAgent {
     this.log(`socket error: ${error?.message ?? error}`);
   }
 
+  /**
+   * One human-facing event: record it, then draw the best host surface.
+   * Hosts with `ctx.ui.setWidget` redraw the panel. Other hosts keep a footer
+   * line and a `[pi-onlyne]` stderr line.
+   *
+   * @param {"in" | "dup" | "out" | "warn" | "state"} kind
+   * @param {string} text
+   */
+  notice(kind, text) {
+    this.activity.note(kind, text);
+    if (this.surface.available?.widget) {
+      this.surface.widget?.(this.activity.lines());
+      return;
+    }
+    // No panel: the footer carries the steady header line, stderr the event.
+    this.surface.status?.(this.activity.lines()[0]);
+    this.log(`${kind}: ${text}`);
+  }
+
   // --------------------------------------------------------------- reports
 
   async reportReady() {
@@ -440,7 +479,7 @@ export class OnlyneAgent {
         seq: this.seq,
       }));
       this.stats.reports += 1;
-      this.log(`ready reported for ${taskId}`);
+      this.notice("state", `ready ${taskId.slice(0, 8)}`);
     } catch (error) {
       this.log(`ready refused: ${error.message}`);
     }
@@ -527,7 +566,7 @@ export class OnlyneAgent {
     }
     if (this.injectedTasks.has(taskId)) {
       this.stats.duplicates += 1;
-      this.log(`assign for ${taskId} already injected; acking without a second injection`);
+      this.notice("dup", `task ${taskId.slice(0, 8)} already injected`);
       await this.ack(taskId, true, "duplicate");
       return;
     }
@@ -554,7 +593,6 @@ export class OnlyneAgent {
       failed: false,
     });
     this.agentState = "running";
-    this.log(`assign ${taskId} from ${JSON.stringify(envelope.from ?? null)}; injecting ${text.length} chars`);
     this.surface.wakeUser?.(text, attachments.map((item) => item.part));
     this.surface.customEntry?.("onlyne-assign", {
       taskId,
@@ -564,7 +602,8 @@ export class OnlyneAgent {
       prose,
       attachments: attachments.map((item) => item.path),
     });
-    this.surface.status?.(`onlyne: ${taskId.slice(0, 8)} running`);
+    this.activity.set({ taskId, phase: "running" });
+    this.notice("in", `task ${taskId.slice(0, 8)} from ${describePrincipal(envelope.from)} (${envelope.kind ?? "task"}): ${headOf(envelope.body?.text)}`);
     this.startHeartbeat();
     await this.ack(taskId, true, null);
   }
@@ -581,7 +620,7 @@ export class OnlyneAgent {
   async probe() {
     try {
       await this.heartbeat();
-      this.log("probe answered with a heartbeat");
+      this.notice("state", "probe answered with a heartbeat");
     } catch (error) {
       this.log(`probe heartbeat refused: ${error.message}`);
     }
@@ -591,7 +630,7 @@ export class OnlyneAgent {
     const task = stdinTaskText(args);
     if (task) {
       // The no-`inject` route: the host hands the payload over as a config key.
-      this.log("task body received through config_get/stdin");
+      this.notice("in", `stdin task: ${headOf(task.text)}`);
       this.surface.wakeUser?.(`[onlyne] task body (delivered as stdin):\n\n${task.text}`, []);
       return;
     }
@@ -601,7 +640,7 @@ export class OnlyneAgent {
   async onRecycle(args) {
     this.stats.recycles += 1;
     const taskId = args.task_id ?? this.activeTaskId();
-    this.log(`recycle task=${taskId ?? "?"} reason=${args.reason ?? "?"} outcome=${args.outcome ?? "-"}`);
+    this.notice("state", `recycled: ${args.reason ?? "operator"}`);
     if (taskId && args.outcome && this.tasks.get(taskId) && !this.tasks.get(taskId).completed) {
       await this.complete(taskId, args.outcome, `recycled: ${args.reason ?? "operator"}`, {
         exitProcess: false,
@@ -746,10 +785,11 @@ export class OnlyneAgent {
         const reason = headOf(input.reason);
         if (input.force !== true || !reason) {
           this.log(refusal);
+          this.notice("warn", refusal);
           throw new Error(`onlyne: ${refusal}`);
         }
         head = headOf(`${FORCED_PREFIX}${reason}${explicit ? ` | ${explicit}` : ""}`);
-        this.log(`relay guard waived for ${taskId}: ${reason}`);
+        this.notice("warn", `relay guard waived: ${reason}`);
       }
     }
     return this.complete(taskId, normalizeOutcome(input.outcome), head);
@@ -781,15 +821,15 @@ export class OnlyneAgent {
     const report = completeReport({ taskId, outcome: normalized, head: summary });
     if (!this.connected) {
       this.pendingCompletion = { taskId, report, outcome: normalized, exitProcess };
-      this.surface.status?.(`onlyne: ${taskId.slice(0, 8)} ${normalized} (queued)`);
-      this.log(`completion for ${taskId} queued: socket is down`);
+      this.activity.set({ taskId, phase: `${normalized} queued` });
+      this.notice("warn", `complete ${taskId.slice(0, 8)} ${normalized} queued: socket down`);
       return { taskId, outcome: normalized, head: summary, queued: true };
     }
     await this.request("report", report);
     this.stats.completions += 1;
-    this.surface.status?.(`onlyne: ${taskId.slice(0, 8)} ${normalized}`);
     this.surface.customEntry?.("onlyne-complete", { taskId, outcome: normalized, head: summary });
-    this.log(`completion ${taskId} ${normalized} head=${JSON.stringify(summary.slice(0, 60))}`);
+    this.activity.set({ taskId: this.activeTaskId() ?? null, phase: normalized });
+    this.notice("out", `complete ${taskId.slice(0, 8)} ${normalized}${summary ? `: ${summary}` : ""}`);
     if (this.activeTasks().length === 0) {
       if (exitProcess) {
         await this.reportSettled(taskId, normalized).catch((error) =>
@@ -841,7 +881,6 @@ export class OnlyneAgent {
     }));
     this.stats.reports += 1;
     this.lastPhase = "idle";
-    this.log(`settled observation for ${taskId}: agent idle, outcome ${outcome}`);
     return true;
   }
 
@@ -852,7 +891,8 @@ export class OnlyneAgent {
     try {
       await this.request("report", pending.report);
       this.stats.completions += 1;
-      this.log(`queued completion for ${pending.taskId} flushed after reconnect`);
+      this.activity.set({ taskId: this.activeTaskId() ?? null, phase: pending.outcome });
+      this.notice("out", `complete ${pending.taskId.slice(0, 8)} ${pending.outcome} flushed after reconnect`);
       if (pending.exitProcess && this.activeTasks().length === 0) {
         await this.reportSettled(pending.taskId, pending.outcome).catch((error) =>
           this.log(`settled observation refused: ${error.message}`),
@@ -903,7 +943,7 @@ export class OnlyneAgent {
       const bytes = Buffer.from(image.data_base64, "base64");
       mkdirSync(dir, { recursive: true, mode: 0o700 });
       writeFileSync(path, bytes, { mode: 0o600 });
-      this.log(`attachment written to ${path} (${bytes.length} bytes)`);
+      this.notice("state", `attachment ${basename(path)}`);
       return [{ path, part: { type: "image", mime, data: image.data_base64, name } }];
     } catch (error) {
       this.log(`attachment write failed: ${error.message}`);

package/src/agent.test.mjs

@@ -11,10 +11,13 @@ import { fileURLToPath } from "node:url";
 import { afterEach, test } from "node:test";
 
 import { OnlyneAgent } from "./agent.mjs";
+import { MAX_LINES, MAX_WIDTH } from "./activity.mjs";
 import { createFrameDecoder, encodeFrame } from "./frame.mjs";
 import { SEQ_BASE, readyReport } from "./protocol.mjs";
 
 const VECTOR_DIR = fileURLToPath(new URL("../../../crates/onlyne-proto/tests/wire_vectors/", import.meta.url));
+// The hello version is the manifest's, so a release bump travels here once.
+const PACKAGE_VERSION = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")).version;
 const ASSIGN_FRAME = existsSync(VECTOR_DIR)
   ? JSON.parse(JSON.parse(readFileSync(`${VECTOR_DIR}adapter_host_assign.json`, "utf8")).frame)
   : null;
@@ -155,13 +158,15 @@ class FakeHost {
 
 /** The effect surface the agent drives, recorded for assertions. */
 function fakeSurface(options = {}) {
-  const calls = { wakeUser: [], prose: [], entries: [], status: [], exits: [] };
+  const calls = { wakeUser: [], prose: [], entries: [], status: [], exits: [], widget: [] };
   return {
     calls,
     available: {
       wakeUser: true,
       proseContext: true,
       customEntry: true,
+      // Off by default: tests that do not opt into a panel keep the footer and log path.
+      widget: options.widget === true,
       status: true,
       exit: true,
       isIdle: true,
@@ -181,6 +186,8 @@ function fakeSurface(options = {}) {
       return true;
     },
     status: (text) => calls.status.push(text),
+    /** Every panel render, newest last; an `undefined` entry is a clear. */
+    widget: (lines) => calls.widget.push(lines),
     welcome: () => {},
     isIdle: () => (options.idle === undefined ? true : options.idle()),
     exit: (reason) => calls.exits.push(reason),
@@ -399,7 +406,7 @@ test("a fresh agent opens with hello, registers and reports ready", async () =>
   assert.deepEqual(hello, {
     protocol: 1,
     plugin: "pi-onlyne",
-    version: "1.0.0",
+    version: PACKAGE_VERSION,
     kind: "agent",
     capabilities: ["register", "report", "inject", "recycle"],
     mount: { role: "planner", session: SESSION_ID, task_id: TASK_ID, pid: process.pid },
@@ -1077,3 +1084,77 @@ test("the handoff ledger belongs to the session, not to one task", async () => {
   assert.equal(completions(host).length, 1);
 });
 
+// ---------------------------------------------------------------- the panel
+
+test("a pi with the widget gets the panel and keeps a quiet scrollback", async () => {
+  const surface = fakeSurface({ widget: true });
+  const { agent, host, logs } = await startAgent({ surface });
+  agent.start();
+  await waitFor(() => (host.of("report").length >= 1 ? true : null));
+  host.notify("assign", assignArgs());
+  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+
+  const [render] = surface.calls.widget.slice(-1);
+  // Header first, then the newest event: the assignment the host just handed over.
+  assert.match(render[0], /^onlyne planner · connected · gen 1 · task 11111111 running$/);
+  assert.match(render[1], /^\d\d:\d\d:\d\d  <= task 11111111 from role:planner \(task\)/);
+  assert.equal(agent.status().activity[0].kind, "in");
+  // The point of the panel: a routine notice reaches the screen through it, once.
+  assert.deepEqual(logs, [], "nothing about a healthy session reaches stderr");
+});
+
+test("a repeating fault folds into one panel line with a count", () => {
+  const surface = fakeSurface({ widget: true });
+  const agent = new OnlyneAgent({
+    socketPath: join(tmpdir(), "pi-onlyne-unused-socket"),
+    cwd: tmpdir(),
+    role: "planner",
+    sessionId: SESSION_ID,
+    taskId: TASK_ID,
+    surface,
+    log: (line) => {
+      throw new Error(`a host with the panel writes no stderr line: ${line}`);
+    },
+  });
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    agent.notice("warn", "heartbeat refused: connection lost");
+  }
+  const [render] = surface.calls.widget.slice(-1);
+  assert.match(render[1], /!! heartbeat refused: connection lost x3$/);
+  assert.equal(surface.calls.widget.length, 3, "every event redraws the same panel");
+});
+
+test("the panel stays inside its line and width budget", () => {
+  const surface = fakeSurface({ widget: true });
+  const agent = new OnlyneAgent({
+    socketPath: join(tmpdir(), "pi-onlyne-unused-socket"),
+    cwd: tmpdir(),
+    role: "planner",
+    sessionId: SESSION_ID,
+    taskId: TASK_ID,
+    surface,
+    log: () => {},
+  });
+  for (let index = 0; index < 40; index += 1) {
+    agent.notice("in", `task ${index} from gateway:wechat:room ${"长".repeat(400)}`);
+  }
+  const [render] = surface.calls.widget.slice(-1);
+  assert.ok(render.length <= MAX_LINES, `panel grew to ${render.length} lines`);
+  for (const line of render) {
+    assert.ok(Array.from(line).length <= MAX_WIDTH, `line overruns its width: ${line}`);
+  }
+});
+
+test("a host without the widget keeps the footer line and the stderr line", async () => {
+  const surface = fakeSurface();
+  const { agent, host, logs } = await startAgent({ surface });
+  agent.start();
+  await waitFor(() => (host.of("report").length >= 1 ? true : null));
+  host.notify("assign", assignArgs());
+  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+
+  assert.deepEqual(surface.calls.widget, [], "no panel to draw");
+  assert.match(surface.calls.status.at(-1), /^onlyne planner · connected · gen 1 · task 11111111 running$/);
+  assert.ok(logs.some((line) => line.startsWith("in: task 11111111")), logs.join(" | "));
+});
+

package/src/index.ts

@@ -56,6 +56,7 @@ interface PiSurface {
     wakeUser: boolean;
     proseContext: boolean;
     customEntry: boolean;
+    widget: boolean;
     status: boolean;
     exit: boolean;
     isIdle: boolean;
@@ -65,6 +66,7 @@ interface PiSurface {
   wakeUser(text: string, parts?: ImagePartInput[]): boolean;
   proseContext(text: string, welcome: WelcomeLike): boolean;
   customEntry(customType: string, data: unknown): boolean;
+  widget(lines: string[] | undefined): void;
   status(text: string): void;
   welcome(welcome: WelcomeLike): void;
   isIdle(): boolean;
@@ -292,6 +294,7 @@ export default function onlyne(pi: ExtensionAPI) {
 
   pi.on("session_shutdown", async (event) => {
     agent?.stop(`pi:${event.reason ?? "quit"}`);
+    surface?.widget?.(undefined);
     agent = null;
     surface = null;
     registered = false;

package/src/pi-surface.mjs

@@ -6,11 +6,14 @@
 //   wakeUser      pi.sendUserMessage(content, { deliverAs: "followUp" })
 //   proseContext  pi.sendMessage({customType,...}, { deliverAs:"followUp", triggerTurn:false })
 //   customEntry   pi.appendEntry(customType, data)
+//   widget        ctx.ui.setWidget("onlyne", lines) / ctx.ui.setWidget("onlyne", undefined)
 //   status        ctx.ui.setStatus("onlyne", text)
 //   exit          ctx.shutdown()
 //   isIdle        ctx.isIdle()
 //   registerTool / registerCommand are probed by index.ts itself.
 
+import { WIDGET_KEY } from "./activity.mjs";
+
 /**
  * @param {{ pi: any, log: (line: string) => void, context: () => any }} options
  */
@@ -28,6 +31,7 @@ export function createSurface({ pi, log, context }) {
     wakeUser: has(pi.sendUserMessage),
     proseContext: has(pi.sendMessage),
     customEntry: has(pi.appendEntry),
+    widget: has(ctx()?.ui?.setWidget),
     status: true,
     exit: true,
     isIdle: true,
@@ -35,6 +39,14 @@ export function createSurface({ pi, log, context }) {
     registerCommand: has(pi.registerCommand),
   };
 
+  const widget = (lines) => {
+    try {
+      ctx()?.ui?.setWidget?.(WIDGET_KEY, lines);
+    } catch {
+      /* widget is decoration; never let it break the protocol */
+    }
+  };
+
   const status = (text) => {
     try {
       ctx()?.ui?.setStatus?.("onlyne", text);
@@ -113,6 +125,7 @@ export function createSurface({ pi, log, context }) {
     wakeUser,
     proseContext,
     customEntry,
+    widget,
     status,
     welcome(welcome) {
       status(`onlyne: ${welcome.role}`);