opencode-collaboration 0.2.3 → 0.3.0

package/README.md

@@ -26,23 +26,24 @@ Run several opencode terminals in parallel (different repos, worktrees, or tasks
 - Command results and notifications are shown **inline in the session** — no toast popups
 - **Explicit TUI controls**: palette actions use host dialogs for selection and confirmation; slash wrappers remain available for automation and compatibility
 - Local only: everything stays on your machine (Unix-domain sockets on macOS/Linux, loopback TCP on Windows, plus a compatibility loopback listener for v1 peers)
+- The peer name is appended to this process's root session titles, so every opencode window shows who it is at a glance
 
 ## Install
 
-This fork is **not published to npm** — it is maintained as a git repository and installed straight from Gitee. The repo ships prebuilt `dist/`, so no build step runs at install time (opencode's Bun installer does not run `prepare` for git dependencies).
+```bash
+opencode plugin -g opencode-collaboration
+```
 
-Add to your `opencode.json`:
+or add to your `opencode.json`:
 
 ```json
 {
-  "plugin": ["opencode-collaboration@git+https://gitee.com/cqy0/opencode-collaboration.git"]
+  "plugin": ["opencode-collaboration"]
 }
 ```
 
 Requires opencode >= 1.18.0.
 
-> **Updating:** opencode caches git plugins under `~/.cache/opencode/packages/`. After a newer commit is pushed, delete the cached `opencode-collaboration@git+...` folder (or bump the repo ref) and restart opencode to pick it up — git plugins are not re-fetched on every launch.
-
 **Single-Enter commands (optional but recommended).** The package ships a TUI entry that makes the plugin's slash commands execute on the first Enter. opencode's TUI loads plugins from `~/.config/opencode/tui.json` (a separate list from `opencode.json`), so add the plugin there too:
 
 ```json
@@ -112,7 +113,7 @@ Options can be passed via the tuple form in `opencode.json`:
 ```json
 {
   "plugin": [
-    ["opencode-collaboration@git+https://gitee.com/cqy0/opencode-collaboration.git", { "inboundPolicy": "hold", "name": "frontend" }]
+    ["opencode-collaboration", { "inboundPolicy": "hold", "name": "frontend" }]
   ]
 }
 ```
@@ -122,6 +123,7 @@ Options can be passed via the tuple form in `opencode.json`:
 | `inboundPolicy` | `"accept"` | `accept` delivers immediately; `auto` accepts only when sender and receiver directories match and otherwise holds; `hold` parks messages for review; `refuse` rejects them |
 | `peerPermissions` | `"allow"` | Peer-origin permission requests: `allow` auto-approves ordinary requests, `ask` leaves native prompts untouched, `deny` rejects. Even in `allow`, OpenCode/plugin permission configuration, `AGENTS.md`, credentials/secrets and permission escalation are never auto-approved; existing OpenCode deny rules always win |
 | `name` | `<dir>-<hex4>` | display name other peers use to address you; the default appends a short hex suffix (from the instance ID) to the directory basename so same-directory instances are distinguishable, matching Claude Code's `my-app-3f` pattern |
+| `showNameInTitle` | `true` | Append this process's peer name to its root session titles (e.g. `Fix login bug(张三)`); the suffix is removed on graceful exit |
 | `storageDir` | `$XDG_DATA_HOME/opencode-collaboration` | where the registry and held inbox live |
 | `heartbeatMs` | `10000` | registry heartbeat interval |
 | `staleMs` | `30000` | peer is offline if its heartbeat is older than this |

package/README.zh-CN.md

@@ -26,23 +26,24 @@
 - 命令结果和通知**内联显示在会话中** —— 没有 toast 弹窗
 - **明确的 TUI 控制**：面板操作使用宿主对话框进行选择确认；斜杠命令封装仍可用于自动化和兼容性场景
 - 纯本地运行：一切都在你的机器上（macOS/Linux 使用 Unix 域套接字，Windows 使用回环 TCP，另有一个兼容 v1 对端的回环监听器）
+- 本进程的 peer 名字会追加到根会话标题后面，一眼就能看出每个 opencode 窗口是谁
 
 ## 安装
 
-本 fork **未发布到 npm** —— 它作为 git 仓库维护，直接从 Gitee 安装。仓库自带构建好的 `dist/`，安装时不需要构建步骤（opencode 的 Bun 安装器对 git 依赖不会执行 `prepare`）。
+```bash
+opencode plugin -g opencode-collaboration
+```
 
-加入你的 `opencode.json`：
+或者加入你的 `opencode.json`：
 
 ```json
 {
-  "plugin": ["opencode-collaboration@git+https://gitee.com/cqy0/opencode-collaboration.git"]
+  "plugin": ["opencode-collaboration"]
 }
 ```
 
 要求 opencode >= 1.18.0。
 
-> **更新方式：** opencode 会把 git 插件缓存在 `~/.cache/opencode/packages/` 下。推送新提交后，删除缓存的 `opencode-collaboration@git+...` 目录（或改动仓库 ref），再重启 opencode 才会拉取最新 —— git 插件不会每次启动都重新拉取。
-
 **单回车执行命令（可选但推荐）。** 本包附带一个 TUI 入口，让插件的斜杠命令按一次回车即可执行。opencode 的 TUI 从 `~/.config/opencode/tui.json` 加载插件（这是与 `opencode.json` 相互独立的另一个列表），所以请把插件也加进去：
 
 ```json
@@ -112,7 +113,7 @@ Use send_message to tell "backend" that the login form now posts to /v2/login.
 ```json
 {
   "plugin": [
-    ["opencode-collaboration@git+https://gitee.com/cqy0/opencode-collaboration.git", { "inboundPolicy": "hold", "name": "frontend" }]
+    ["opencode-collaboration", { "inboundPolicy": "hold", "name": "frontend" }]
   ]
 }
 ```
@@ -122,6 +123,7 @@ Use send_message to tell "backend" that the login form now posts to /v2/login.
 | `inboundPolicy` | `"accept"` | `accept` 立即投递；`auto` 仅当发送方与接收方目录相同时接受，否则进入待审；`hold` 暂存消息供人工审阅；`refuse` 直接拒绝 |
 | `peerPermissions` | `"allow"` | 对端来源的权限请求：`allow` 自动批准普通请求，`ask` 保持原生提示不变，`deny` 拒绝。即使在 `allow` 模式下，OpenCode/插件权限配置、`AGENTS.md`、凭据/密钥以及权限升级也永远不会被自动批准；已存在的 OpenCode 拒绝规则始终优先 |
 | `name` | `<dir>-<hex4>` | 其他对端用来寻址你的显示名；默认值在目录名后追加一个短十六进制后缀（取自实例 ID），使同目录的多个实例可以区分，与 Claude Code 的 `my-app-3f` 命名方式一致 |
+| `showNameInTitle` | `true` | 把本进程的 peer 名字追加到根会话标题后面（如 `Fix login bug(张三)`）；优雅退出时会自动移除该后缀 |
 | `storageDir` | `$XDG_DATA_HOME/opencode-collaboration` | 注册表与待审收件箱的存储目录 |
 | `heartbeatMs` | `10000` | 注册表心跳间隔 |
 | `staleMs` | `30000` | 心跳早于该时长则视为对端离线 |

package/dist/commands.js

@@ -17,7 +17,8 @@ export async function handlePeersCommand(ctx, command, args) {
         const suffix = held.length > 0 || pending > 0
             ? `\n(${pending} queued, ${held.length} held — /peers-inbox to review)`
             : "";
-        return { handled: true, message: `📋 ${listing}${suffix}` };
+        const selfLine = `You are "${ctx.getName()}" — /peers-name to change.`;
+        return { handled: true, message: `📋 ${selfLine}\n${listing}${suffix}` };
     }
     if (command === "peers-name") {
         const desired = args.trim();

package/dist/config.d.ts

@@ -5,6 +5,7 @@ export interface ResolvedConfig {
     inboxFile: string;
     spoolDir: string;
     name: string | undefined;
+    showNameInTitle: boolean;
     inboundPolicy: "accept" | "auto" | "hold" | "refuse";
     peerPermissions: PeerPermissionMode;
     heartbeatMs: number;

package/dist/config.js

@@ -14,6 +14,7 @@ export function resolveConfig(opts, env = process.env) {
         inboxFile: join(storageDir, "inbox.json"),
         spoolDir: join(storageDir, "spool"),
         name: opts?.name,
+        showNameInTitle: opts?.showNameInTitle ?? true,
         inboundPolicy: opts?.inboundPolicy ?? "accept",
         peerPermissions: opts?.peerPermissions ?? "allow",
         heartbeatMs: opts?.heartbeatMs ?? 10_000,

package/dist/index.js

@@ -302,6 +302,7 @@ export const PeersPlugin = async (ctx, pluginOptions) => {
                     setName: async (name) => {
                         if (name === currentName) {
                             await registry.heartbeat();
+                            await runtime.retitleRoots(currentName);
                             return { name, taken: false };
                         }
                         const peers = await registry.list();
@@ -311,6 +312,7 @@ export const PeersPlugin = async (ctx, pluginOptions) => {
                         }
                         currentName = name;
                         await registry.heartbeat();
+                        await runtime.retitleRoots(currentName);
                         return { name, taken: false };
                     },
                     selfInstanceId: instanceId,
@@ -353,14 +355,17 @@ export const PeersPlugin = async (ctx, pluginOptions) => {
             clearTimeout(discoveryTimer);
         discoveryTimer = null;
         clearInterval(sweeper);
-        const registryStopping = registry.stop();
-        const runtimeStopping = runtime.stop();
-        disposePromise = Promise.all([
-            registryStopping,
-            runtimeStopping,
-            listener.stop(),
-            acknowledgementTransport.close(),
-        ]).then(() => undefined);
+        const cleanup = (async () => {
+            // Titles must be stripped while the runtime is still live.
+            await runtime.clearSuffixes();
+            await Promise.all([
+                registry.stop(),
+                runtime.stop(),
+                listener.stop(),
+                acknowledgementTransport.close(),
+            ]);
+        })().catch(() => undefined);
+        disposePromise = cleanup.then(() => undefined);
         return disposePromise;
     };
     await logger("info", "opencode-collaboration started", {
@@ -379,6 +384,8 @@ export const PeersPlugin = async (ctx, pluginOptions) => {
             return;
         void runtime.initialize()
             .then(async () => {
+            if (!disposing)
+                await runtime.retitleRoots(currentName);
             if (!disposing)
                 await registry.heartbeat();
         })

package/dist/session-runtime.d.ts

@@ -31,6 +31,8 @@ export interface SessionRuntimeInstance {
     queueForSession: (sessionId: string) => QueueInstance | null;
     deliveryForSession: (sessionId: string) => DeliveryInstance | null;
     sweep: () => Promise<void>;
+    retitleRoots: (name: string) => Promise<void>;
+    clearSuffixes: () => Promise<void>;
     pendingAcknowledgements: () => Array<{
         queue: QueueInstance;
         acknowledgement: PeerAcknowledgementV2;

package/dist/session-runtime.js

@@ -2,6 +2,7 @@ import { Delivery } from "./delivery.js";
 import { gateMessage } from "./gating.js";
 import { createSessionMessageQueue, hasSpoolRecords, migrateWorkspaceSpool, stableSessionEndpointId, } from "./queue.js";
 import { SessionTracker } from "./session-tracker.js";
+import { stripNameSuffix, withNameSuffix } from "./title-suffix.js";
 function responseData(response) {
     return response?.data;
 }
@@ -118,6 +119,57 @@ export function SessionRuntime(opts) {
             return null;
         }
     }
+    function rootEndpoints() {
+        return [...endpoints.values()].filter((endpoint) => !endpoint.session.parentID);
+    }
+    async function updateTitle(endpoint, title) {
+        const api = opts.client.session;
+        if (typeof api.update !== "function")
+            return;
+        await api.update({
+            path: { id: endpoint.session.id },
+            query: { directory: endpoint.session.directory || opts.directory },
+            body: { title },
+        });
+        endpoint.session = { ...endpoint.session, title };
+    }
+    async function applyNameToTitle(endpoint, name) {
+        const current = endpoint.session.title ?? "";
+        const desired = withNameSuffix(current, name);
+        if (desired === current)
+            return;
+        try {
+            await updateTitle(endpoint, desired);
+        }
+        catch (err) {
+            await opts.logger("warn", "failed to update session title", {
+                error: String(err),
+                sessionId: endpoint.session.id,
+            });
+        }
+    }
+    async function retitleRootsImpl(name) {
+        if (!opts.config.showNameInTitle)
+            return;
+        await Promise.all(rootEndpoints().map((endpoint) => applyNameToTitle(endpoint, name)));
+    }
+    async function clearSuffixesImpl() {
+        await Promise.all(rootEndpoints().map(async (endpoint) => {
+            const current = endpoint.session.title ?? "";
+            const stripped = stripNameSuffix(current);
+            if (stripped === current)
+                return;
+            try {
+                await updateTitle(endpoint, stripped);
+            }
+            catch (err) {
+                await opts.logger("warn", "failed to clear session title suffix", {
+                    error: String(err),
+                    sessionId: endpoint.session.id,
+                });
+            }
+        }));
+    }
     return {
         initialize() {
             if (!readyPromise) {
@@ -293,6 +345,11 @@ export function SessionRuntime(opts) {
                     await upsert(info);
                     if (event.type === "session.created")
                         await loadChildren(info);
+                    if (opts.config.showNameInTitle && !info.parentID) {
+                        const endpoint = endpoints.get(info.id);
+                        if (endpoint)
+                            await applyNameToTitle(endpoint, opts.name());
+                    }
                     return true;
                 }
                 if (event.type === "session.deleted") {
@@ -351,5 +408,13 @@ export function SessionRuntime(opts) {
             return [...endpoints.values()].flatMap((endpoint) => endpoint.queue.pendingAcknowledgements()
                 .map((acknowledgement) => ({ queue: endpoint.queue, acknowledgement })));
         },
+        retitleRoots(name) {
+            return whileRunning(undefined, () => retitleRootsImpl(name));
+        },
+        clearSuffixes() {
+            // Runs during dispose, possibly after lifecycle moved to "stopping",
+            // so it deliberately bypasses whileRunning().
+            return clearSuffixesImpl();
+        },
     };
 }

package/dist/title-suffix.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Session-title suffix helpers. The peer name is appended in parentheses,
+ * e.g. "Fix login bug(张三)", so a user can always see which opencode process
+ * a session belongs to. The suffix is stripped again on graceful exit.
+ *
+ * A trailing "(...)" is only treated as our suffix when its content is a
+ * valid peer name; ordinary parenthetical text is left alone.
+ */
+/** Remove a trailing "(name)" suffix whose content is a valid peer name. */
+export declare function stripNameSuffix(title: string): string;
+/** Append the name suffix, replacing any existing name suffix. */
+export declare function withNameSuffix(title: string, name: string): string;

package/dist/title-suffix.js

@@ -0,0 +1,23 @@
+/**
+ * Session-title suffix helpers. The peer name is appended in parentheses,
+ * e.g. "Fix login bug(张三)", so a user can always see which opencode process
+ * a session belongs to. The suffix is stripped again on graceful exit.
+ *
+ * A trailing "(...)" is only treated as our suffix when its content is a
+ * valid peer name; ordinary parenthetical text is left alone.
+ */
+import { validateName } from "./config.js";
+/** Remove a trailing "(name)" suffix whose content is a valid peer name. */
+export function stripNameSuffix(title) {
+    const match = title.match(/^(.*?)\s*\(([^()]*)\)$/);
+    if (!match)
+        return title;
+    if (validateName(match[2].trim()) !== null)
+        return title;
+    return match[1].trimEnd();
+}
+/** Append the name suffix, replacing any existing name suffix. */
+export function withNameSuffix(title, name) {
+    const base = stripNameSuffix(title).trim();
+    return base ? `${base}(${name})` : `(${name})`;
+}

package/dist/types.d.ts

@@ -127,6 +127,12 @@ export interface PluginConfig {
     storageDir?: string;
     /** Display name for this instance (default: basename of directory). */
     name?: string;
+    /**
+     * Append this process's peer name to its root session titles, e.g.
+     * "Fix login bug(张三)". The suffix is removed again on graceful exit.
+     * Default true.
+     */
+    showNameInTitle?: boolean;
     /** What to do with inbound messages. Default "accept". */
     inboundPolicy?: InboundPolicy;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-collaboration",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Cross-session messaging for opencode — let independent sessions discover and text each other, modeled after Claude Code's cross-session messaging",
   "type": "module",
   "main": "./dist/index.js",