@op1/threads 0.1.1 → 0.1.3

package/README.md

@@ -39,7 +39,7 @@ The worker opens in a native tab without taking focus. Select that tab to read i
 
 ## Tools
 
-The native tool names use namespace `threads` and individual names `spawn`, `list`, `send`, `interrupt`, and `report`.
+The native tool names use namespace `threads` and individual names `spawn`, `list`, `send`, `interrupt`, `hide`, and `report`.
 
 | Tool | Input | Result |
 | --- | --- | --- |
@@ -47,13 +47,14 @@ The native tool names use namespace `threads` and individual names `spawn`, `lis
 | `threads_list` | `{}` | `{ workers: WorkerView[] }` |
 | `threads_send` | `{ workerID, key, text }` | `{ workerID, messageID }` |
 | `threads_interrupt` | `{ workerID }` | Worker view |
+| `threads_hide` | `{ workerID }` | Worker view |
 | `threads_report` | `{ verdict, summary, evidence }` | `{ workerID, report }` |
 
 All fields are strings except `evidence`, which is an array of strings. Verdicts are `PASS`, `PASS WITH NOTES`, `FAIL`, and `INCONCLUSIVE`. Each tool returns JSON in native `content` and the same value in `output`.
 
 `directory` must exist and be absolute. Spawn uses native `subagent` permission gating. The worker uses the coordinator's agent and model, with resolved agent permissions followed by session permissions. Its actual tool actions still pass through native permission checks. There is no separate directory-approval flow or agent/model override.
 
-Tool identity comes from the calling session. Only the owning coordinator can send or interrupt. Only the exact original top-level worker can report. Native subagents and managed workers cannot spawn managed workers. Native `subagent` remains available.
+Tool identity comes from the calling session. Only the owning coordinator can send, interrupt, or hide a worker. Only the exact original top-level worker can report. Native subagents and managed workers cannot spawn managed workers. Native `subagent` remains available.
 
 ## Identity and retries
 
@@ -65,32 +66,42 @@ Send keys are scoped to the worker and determine a stable message ID. A retry wi
 
 ## Worker views and limits
 
-`WorkerView` contains `workerID`, `coordinatorID`, `key`, `title`, `directory`, `outcome`, and `report`. `outcome` is the native last execution outcome, or `null` before one exists. It is not current activity. Native tabs display current busy, attention, and unread state.
+`WorkerView` contains `workerID`, `coordinatorID`, `key`, `title`, `directory`, `outcome`, `report`, and `hidden`. `outcome` is the native last execution outcome, or `null` before one exists. It is not current activity. Native tabs display current busy, attention, and unread state.
 
 `report` is the explicit worker claim, or `null`. Native `succeeded` means the agent loop completed, not that the assigned task passed.
 
+`hidden` is the desired idle-tab visibility. Current activity, input requests, or selection can keep that tab open.
+
 Plugin option `maxWorkers` defaults to 4 and accepts integers from 1 through 32. Admission is serialized by coordinator within the loaded server process. A worker without a report continues to occupy a slot unless its native outcome is `failed` or `interrupted`. A successful run without a report does not silently free its slot.
 
 ## Terminal and RPC
 
 The terminal synchronizes workers before opening native tabs without changing focus. A TUI memory index survives plugin reloads and respects manually closed tabs. `/threads` explicitly reopens workers for open coordinator tabs. A new TUI recovers workers from durable storage. Closing the TUI does not interrupt workers.
 
-All open native root-session tabs are automatically grouped by OpenCode project ID, including sessions not managed by this plugin. Projects follow their first appearance in the current tab order; sessions keep their relative order within each project. Worktrees with the same project ID stay together. Each tab with unloaded project metadata stays in its own group until that metadata becomes available. Reconciliation moves only out-of-order tabs, without changing focus or closing and reopening them. Native tabs do not support divider rows.
+Workers with `PASS` or `PASS WITH NOTES` reports hide automatically once idle. This also applies to reports saved before upgrading. Unreported workers and `FAIL` or `INCONCLUSIVE` reports stay visible. The selected tab, running workers, and tabs needing input stay open until they are inactive.
+
+The coordinator can call `threads_hide` when a worker is no longer needed. Hiding preserves the conversation and report, survives restarts, and does not free an admission slot. `/threads` restores hidden workers and keeps them visible for inspection. A valid `threads_send` follow-up also restores its worker. Visibility overrides belong to the original report message ID, so recreating a deleted worker cannot inherit its hidden state.
+
+Reports reach the coordinator through silent synthetic messages. They remain available through `threads_list` and the session history without adding a notification row to the conversation. Older report notification rows remain in native history.
+
+All open native root-session tabs are automatically grouped by OpenCode project ID, including sessions not managed by this plugin. Projects follow their first appearance in the current tab order. Worktrees with the same project ID stay together.
+
+Within each project, running sessions, the selected tab, and sessions waiting for input come before idle sessions. Tabs with the same priority keep their relative order. Idle is a display priority, not a completion verdict. Each tab with unloaded project metadata stays in its own group until that metadata becomes available. Reconciliation moves only out-of-order tabs, without changing focus or closing and reopening them to reorder. Native tabs do not support divider rows.
 
-The read-only RPC definition is `ThreadsRpc` in `src/rpc.ts`, with ID `threads` and method `snapshot`:
+The RPC definition is `ThreadsRpc` in `src/rpc.ts`, with ID `threads`. `snapshot` is read-only. The user-invoked `restore` method clears hidden state for the supplied coordinators' workers. Both methods accept and return:
 
 ```ts
 input: { coordinatorIDs: string[] }
 result: { workers: WorkerView[] }
 ```
 
-The input accepts at most 100 coordinator IDs. Raw HTTP RPC requests wrap the input as `{ "input": { "coordinatorIDs": ["ses_..."] } }`. The method declares `errors: {}` and the RPC declares `events: {}`. The TUI subscribes to native session events and reconciles at most one snapshot at a time, with a three-second missed-event refresh.
+The input accepts at most 100 coordinator IDs. Raw HTTP RPC requests wrap the input as `{ "input": { "coordinatorIDs": ["ses_..."] } }`. Each method declares `errors: {}` and the RPC declares `events: {}`. The TUI subscribes to native session events and reconciles at most one snapshot at a time, with a three-second missed-event refresh.
 
 ## Verification and limits
 
 Run `bun run typecheck`, `bun test`, and `bun run verify:live`. The live check requires OpenCode 2.0.3, Python, and `uv`. It starts a separate local server, a deterministic model endpoint, and a terminal process with isolated configuration and data. It verifies actual tool calls, durable messages, permission restrictions, worker limits, deleted-worker cleanup, restart behavior, and native tab visibility, busy state, and focus.
 
-Run `bun run verify:tabs` to verify project grouping across real git worktrees, new worker insertion, focus preservation, and TUI reopening.
+Run `bun run verify:tabs` to verify project grouping across real git worktrees, activity-based ordering, permission prompts, completed and resumed workers, focus preservation, and TUI reopening.
 
 Pass an extracted package directory to test the release artifact: `bun run verify:live /absolute/path/to/package`.
 

package/index.ts

@@ -2,7 +2,7 @@ import { Plugin } from "@opencode/plugin";
 import type { SessionContext } from "@opencode/plugin/promise/session";
 import { z } from "zod";
 import { Report, ThreadsRpc, WorkerView } from "./src/rpc";
-import { Interrupt, Send, Spawn, threads } from "./src/threads";
+import { Send, Spawn, WorkerTarget, threads } from "./src/threads";
 
 export default Plugin.define({
   id: "op-threads",
@@ -26,6 +26,9 @@ export default Plugin.define({
       snapshot: async ({ coordinatorIDs }) => ({
         workers: (await Promise.all(coordinatorIDs.map(workers.list))).flat(),
       }),
+      restore: async ({ coordinatorIDs }) => ({
+        workers: (await Promise.all(coordinatorIDs.map(workers.restore))).flat(),
+      }),
     });
     await ctx.tool.transform((editor) => {
       editor.namespace({
@@ -81,7 +84,7 @@ export default Plugin.define({
       editor.add({
         name: "interrupt",
         description: "Interrupt your worker without claiming task success.",
-        input: Interrupt,
+        input: WorkerTarget,
         output: WorkerView,
         options: { namespace: "threads", codemode: false },
         execute: async (input, tool) => {
@@ -89,6 +92,17 @@ export default Plugin.define({
           return { content: JSON.stringify(output), output };
         },
       });
+      editor.add({
+        name: "hide",
+        description: "Hide a worker you no longer need from the sidebar without deleting its conversation or report. Only its coordinator may hide it. Running, selected, or attention-needed tabs stay open until idle. Use /threads to restore hidden tabs.",
+        input: WorkerTarget,
+        output: WorkerView,
+        options: { namespace: "threads", codemode: false },
+        execute: async (input, tool) => {
+          const output = await workers.hide(tool.sessionID, input);
+          return { content: JSON.stringify(output), output };
+        },
+      });
       editor.add({
         name: "report",
         description:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@op1/threads",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Visible top-level worker sessions for OpenCode V2, with native tabs and durable reports.",
   "type": "module",
   "main": "./index.ts",

package/skills/managed-sessions/SKILL.md

@@ -26,6 +26,7 @@ An identical spawn key retries the original admission. Different work requires a
 - Use `threads_list` for a progress snapshot when making a scheduling or delivery decision.
 - Use `threads_send` with a stable message key for a correction or follow-up within the worker's assigned task.
 - Use `threads_interrupt` to stop that worker's execution.
+- Use `threads_hide` with `workerID` when a worker is no longer needed in the sidebar. This preserves its report and conversation. Hiding does not interrupt work or free an admission slot.
 - Do not repeatedly query status while waiting. Workers report to the coordinator through OpenCode's durable inbox.
 - After a service restart, inspect existing worker IDs before deciding whether to resume them. Do not launch replacement tasks solely because a session is idle.
 
@@ -37,4 +38,4 @@ A worker report is a claim to review. Run the protocol's independent verificatio
 
 ## Visibility
 
-The TUI plugin opens managed workers as ordinary tabs without changing focus. Each tab uses OpenCode's native activity indicators. Use `/threads` to reopen managed worker tabs you closed.
+The TUI plugin opens managed workers as ordinary tabs without changing focus. Workers with `PASS` or `PASS WITH NOTES` reports hide automatically once inactive. Failed, inconclusive, and unreported workers stay visible until the coordinator hides them. Running, selected, and attention-needed tabs stay open. Use `/threads` to restore hidden tabs for inspection. Sending a valid follow-up also restores that worker. Reports are delivered silently to the coordinator and remain available through `threads_list`.

package/src/rpc.ts

@@ -17,6 +17,7 @@ export const WorkerView = z.object({
   directory: z.string(),
   outcome: z.enum(["succeeded", "failed", "interrupted"]).nullable(),
   report: Report.nullable(),
+  hidden: z.boolean(),
 });
 
 export const ThreadsRpc = Rpc.define({
@@ -29,6 +30,11 @@ export const ThreadsRpc = Rpc.define({
       output: z.object({ workers: z.array(WorkerView) }),
       errors: {},
     },
+    restore: {
+      input: z.object({ coordinatorIDs: z.array(z.string()).max(100) }).strict(),
+      output: z.object({ workers: z.array(WorkerView) }),
+      errors: {},
+    },
   },
   events: {},
 });

package/src/threads.ts

@@ -42,7 +42,7 @@ export const Send = z
     text: z.string().min(1),
   })
   .strict();
-export const Interrupt = z.object({ workerID: sessionID }).strict();
+export const WorkerTarget = z.object({ workerID: sessionID }).strict();
 
 const digest = (parts: string[]) =>
   createHash("sha256").update(JSON.stringify(parts)).digest("hex");
@@ -94,12 +94,16 @@ export function threads(
     `workers/${link.coordinatorID}/${link.workerID}`;
   const reportKey = (link: z.infer<typeof Link>) =>
     `reports/${link.workerID}/${link.reportMessageID}`;
+  const visibilityKey = (link: z.infer<typeof Link>) =>
+    `visibility/${link.workerID}/${link.reportMessageID}`;
 
   async function view(
     session: NativeSession,
   ): Promise<z.infer<typeof WorkerView>> {
     const link = workerLink(session);
     const stored = await ctx.storage.get(reportKey(link));
+    const report = stored === undefined ? null : Report.parse(stored);
+    const visibility = await ctx.storage.get(visibilityKey(link));
     return {
       workerID: link.workerID,
       coordinatorID: link.coordinatorID,
@@ -107,7 +111,11 @@ export function threads(
       title: session.title ?? link.key,
       directory: session.location.directory,
       outcome: session.outcome ?? null,
-      report: stored === undefined ? null : Report.parse(stored),
+      report,
+      hidden:
+        visibility === undefined
+          ? report?.verdict === "PASS" || report?.verdict === "PASS WITH NOTES"
+          : z.boolean().parse(visibility),
     };
   }
 
@@ -132,6 +140,7 @@ export function threads(
           if (!missing.success || missing.data.sessionID !== link.workerID)
             throw error;
           await ctx.storage.remove(reportKey(link));
+          await ctx.storage.remove(visibilityKey(link));
           await ctx.storage.remove(entry.key);
           continue;
         }
@@ -152,6 +161,22 @@ export function threads(
 
   return {
     list,
+    async hide(actor: string, input: z.infer<typeof WorkerTarget>) {
+      const { session, link } = await owned(actor, input.workerID);
+      await ctx.storage.set(visibilityKey(link), true);
+      return view(session);
+    },
+    async restore(coordinatorID: string) {
+      const workers = await list(coordinatorID);
+      return Promise.all(
+        workers.map(async (worker) => {
+          if (!worker.hidden) return worker;
+          const { session, link } = await owned(coordinatorID, worker.workerID);
+          await ctx.storage.set(visibilityKey(link), false);
+          return view(session);
+        }),
+      );
+    },
     async spawn(
       actor: string,
       input: z.infer<typeof Spawn>,
@@ -230,7 +255,7 @@ export function threads(
       });
     },
     async send(actor: string, input: z.infer<typeof Send>) {
-      await owned(actor, input.workerID);
+      const { link } = await owned(actor, input.workerID);
       const id = SessionMessage.ID.make(
         `msg_${digest([input.workerID, "send", input.key]).slice(0, 32)}`,
       );
@@ -243,9 +268,14 @@ export function threads(
       });
       if (admitted.payload.text !== input.text)
         throw new Error("This send key already belongs to different text");
+      if ((await ctx.storage.get(reportKey(link))) !== undefined) {
+        await ctx.storage.set(visibilityKey(link), false);
+      } else {
+        await ctx.storage.remove(visibilityKey(link));
+      }
       return { workerID: input.workerID, messageID: admitted.id };
     },
-    async interrupt(actor: string, input: z.infer<typeof Interrupt>) {
+    async interrupt(actor: string, input: z.infer<typeof WorkerTarget>) {
       await owned(actor, input.workerID);
       await ctx.session.interrupt({
         sessionID: input.workerID,
@@ -261,7 +291,6 @@ export function threads(
         id: link.reportMessageID,
         text: `Managed worker ${link.workerID} (${link.key}) report:\n${JSON.stringify(input)}`,
         metadata: { opThreadsReport: input, workerID: link.workerID },
-        description: `Worker report: ${link.key}`,
         delivery: "queue",
         resume: true,
       });

package/tui.ts

@@ -16,23 +16,28 @@ export default Plugin.define({
         const projectID = ctx.data.session.get(tab.sessionID)?.projectID;
         return {
           sessionID: tab.sessionID,
+          priority: tab.busy || tab.active || tab.attention,
           projectID:
             typeof projectID === "string" && projectID.length > 0
               ? projectID
               : undefined,
         };
       });
-      const groups = new Map<string, string[]>();
+      const groups = new Map<string, typeof tabs>();
       for (const tab of tabs) {
         const key =
           tab.projectID === undefined
             ? `session:${tab.sessionID}`
             : `project:${tab.projectID}`;
         const group = groups.get(key);
-        if (group) group.push(tab.sessionID);
-        else groups.set(key, [tab.sessionID]);
+        if (group) group.push(tab);
+        else groups.set(key, [tab]);
       }
-      const ordered = [...groups.values()].flat();
+      const ordered = [...groups.values()].flatMap((group) =>
+        group
+          .sort((left, right) => Number(right.priority) - Number(left.priority))
+          .map((tab) => tab.sessionID),
+      );
       for (const [index, sessionID] of ordered.entries()) {
         if (ctx.ui.tabs.list()[index]?.sessionID === sessionID) continue;
         if (!ctx.ui.tabs.move(sessionID, index)) break;
@@ -55,12 +60,30 @@ export default Plugin.define({
           ]),
         ].slice(0, 100);
         if (!coordinatorIDs.length) return;
-        const { workers } = await rpc.snapshot(
+        const { workers } = await (reopen ? rpc.restore : rpc.snapshot)(
           { coordinatorIDs },
           { location: ctx.location ?? ctx.data.location.default() },
         );
         for (const worker of workers) {
           if (stopped) return;
+          const tab = ctx.ui.tabs.list().find((tab) => tab.sessionID === worker.workerID);
+          if (
+            worker.hidden &&
+            !tab?.active &&
+            !tab?.busy &&
+            !tab?.attention &&
+            ctx.data.session.status(worker.workerID) !== "running"
+          ) {
+            if (tab && !ctx.ui.tabs.close(worker.workerID)) continue;
+            if (seen.workerIDs.includes(worker.workerID)) {
+              updateSeen((draft) => {
+                draft.workerIDs = draft.workerIDs.filter(
+                  (id) => id !== worker.workerID,
+                );
+              });
+            }
+            continue;
+          }
           if (!reopen && seen.workerIDs.includes(worker.workerID)) continue;
           await ctx.data.session.sync(worker.workerID);
           if (