@qilin-agent/client-ui-sidebar-tasks 0.0.0-stage → 3.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,40 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/ui-sidebar-tasks/README.md
+/:
+  en: fa8df2be1a2abb55
+  zh: 645982177f34ed56
+/qilin-agent-client-ui-sidebar-tasks:
+  en: ddc75afc1f09c154
+  zh: 1f7471744e2040af
+/qilin-agent-client-ui-sidebar-tasks/summary:
+  en: 5c11f1be552069fc
+  zh: 0130685e0d40f647
+/qilin-agent-client-ui-sidebar-tasks/table-of-contents:
+  en: 141356e3f3160484
+  zh: 356e83d7b100f3d4
+/qilin-agent-client-ui-sidebar-tasks/what-it-registers:
+  en: eb1b6682267a8237
+  zh: 9a1380a307df5924
+/qilin-agent-client-ui-sidebar-tasks/the-two-sections:
+  en: 39ef0b5fed55cfa3
+  zh: 0b441bf7d6152951
+/qilin-agent-client-ui-sidebar-tasks/the-graph-form:
+  en: 4ec2916d34654437
+  zh: 66a656ca97d91687
+/qilin-agent-client-ui-sidebar-tasks/the-chip-badge:
+  en: 0274f26ca136cbd7
+  zh: 91920d0e208382d1
+/qilin-agent-client-ui-sidebar-tasks/model-experience:
+  en: 2b74e414d5340310
+  zh: bb5fc0f0859f73ba
+/qilin-agent-client-ui-sidebar-tasks/model-experience/kv-cache-effect:
+  en: aa7bf62b7a2515e2
+  zh: 16f9bbe19901ab33
+/qilin-agent-client-ui-sidebar-tasks/known-limitations-and-deferred-work:
+  en: dcdd21c1e8cb54d6
+  zh: 213b0ecf61355b7c
+/qilin-agent-client-ui-sidebar-tasks/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 1f09535637464bbe

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+---
+description: "The right Sidebar's tasks page for the qilin web client: the session's subagent topology and its background jobs as a list or a task-management graph, read from the Session list the page already holds."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/client-ui-sidebar-tasks
+
+English | [中文](README.zh.md)
+
+## Summary
+
+The right Sidebar's tasks page: this Session's subagent topology and its background jobs in one column. It is a page type reached from the guide and claims no address. The section content draws either as a list or as a task-management graph. Everything drawn is read from the Session list snapshot — the page issues no read of its own — and every action travels through the Session service or the subagent Remote. Nothing in `ui-sidebar-right` knows this package.
+
+## Table of Contents
+
+- [What it registers](#what-it-registers)
+- [The two sections](#the-two-sections)
+- [The graph form](#the-graph-form)
+- [The chip badge](#the-chip-badge)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="what-it-registers"></a>
+## What it registers
+
+- **The type** — `ctx.sidebarRightTabs.register(...)` with kind `tasks`, id `@qilin-agent/client-ui-sidebar-tasks`, band `builtin`, no patterns, `single`, and one guide entry (order 40, its title and description from the `sidebarTasks` namespace, its glyph the shared checklist icon) that opens the type.
+- **The body** — the keyed `sidebar.right.pane.tab` seat under that id, declaring the graph's view store so folds, arrangement, and camera survive the body's unmounts.
+- **The chip badge** — the keyed `sidebar.right.pane.tab.badge` seat under the same id.
+
+Eleven source files under `src/client/`: `definition.tsx` (the type), `rows.ts` and `lineage.ts` (pure projections of the two snapshots), `face.ts` (the actions and their Remote binding), `tasks-graph-model.ts`, `tasks-graph-layout.ts`, and `tasks-graph-store.ts` (the graph's pure model, pure layout, and view store), `TasksBody.tsx`, `TasksGraphView.tsx`, and `TasksBadge.tsx` (what is drawn), `locales.ts` (what it says), and `index.ts` (the wiring).
+
+<a id="the-two-sections"></a>
+## The two sections
+
+**Subagents** flattens the direct-child catalogs the Session list holds, depth-first: a level is one parent's catalog, siblings are newest-first because the Host orders a catalog by durable creation time, and the walk descends only into a child whose own catalog has been read — an unopened branch contributes its row and nothing below it. A row the Host could not describe is drawn as a diagnostic and never counted. The section's stated total is the greater of the children the catalogs report and the descendants the summary lineage records (`indexSubagentDescendants` over the Session summaries), so the header never undercounts while the lineage is still converging.
+
+**Background jobs** keeps live jobs first in start order, then settled jobs newest-first, a finish-time tie falling back to the later start. A live row's duration ticks against a one-second clock; a settled row measures its own span.
+
+Both sections open on arrival. A section past its preview count — five subagent rows, three job rows — folds the rest behind one control. Section and fold state is the body's own and never leaves it.
+
+Three actions exist, each performed by the injected face at call time: reveal a child as the current Session, re-read one parent's catalog, and stop a continuable child through `subagents.interruptByParent`.
+
+<a id="the-graph-form"></a>
+## The graph form
+
+The subagents section renders instead as a card tree. `buildTasksGraphModel` walks the same catalogs depth-first and emits one card per catalog child, with a main card for the page's Session; a child of six or more settled one-shot cards folds into one aggregate card until it is clicked open, an unread branch shows a placeholder card, and standby-mode children fold the same way. The card set arranges as a tree, a compact horizontal grouping, or a fixed six-column grid, and a card can be dragged — with its whole subtree under the default gesture, alone under Alt — to any offset the model keeps.
+
+The canvas steers like a document viewer: the wheel zooms toward the cursor, a drag on the background pans, double-click or the fit control reframes the content, and a resize reframes only while the user holds no camera. Card clicks route by kind: an aggregate card folds or unfolds, a placeholder card re-reads its parent's catalog, a catalog card opens the child, and the main card opens the page's Session. View state — form, per-aggregate folds, arrangement mode, drag offsets, and camera — lives in one store declared at the body's seat, so leaving the tab and coming back restores it.
+
+<a id="the-chip-badge"></a>
+## The chip badge
+
+The badge is how much work this Session has running: direct-child catalog rows whose activity is `running`, plus jobs the registry still holds open. A running grandchild implies its parent is running too, so the direct children already account for work below them, and the badge reads the two snapshots straight through the standard `useSessions` hook rather than walking the lineage. Zero is the idle state, not a count: the chip draws no empty pill for it.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this package draws Session-side work in the browser and registers nothing model-facing.
+
+#### KV Cache effect
+
+None; both snapshots arrive on the Session list the client already holds, and the page assembles no model request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+- **No job output.** The job snapshot carries status, timing, and detail — not a stream — so a running job's output is not shown here; reading it is a tool's job, and the page performs no tool call.
+- **One-shot children cannot be stopped here.** The interrupt action addresses a continuable child through its durable parent; a one-shot child is drawn and openable, and nothing more.
+- **Depth stops at read catalogs.** The page issues no catalog read of its own, so a branch the Session list has never read contributes one row and no rows below it; the refresh action is how a branch opens up.
+- **The badge counts direct children only**, for the same reason it does not walk the lineage: a strip render must not.
+- **The graph draws catalogs, not runs.** The model accepts run, phase, and member cards for a Session list that reports them, but the page feeds it no workflow-run feed today, so every subagent draws as a plain catalog card or folds as done or standby; the run vocabulary exists so a future feed lands without a model change.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,84 @@
+---
+description: "qilin 网页客户端右侧边栏的任务页：本会话的子代理拓扑与后台任务，以列表或任务管理图呈现，全部读自页面已持有的会话列表。"
+kind: "package-reference"
+---
+
+# @qilin-agent/client-ui-sidebar-tasks
+
+[English](README.md) | 中文
+
+## 概述
+
+右侧边栏的任务页：本会话的子代理拓扑与后台任务收进同一栏。它是一个页面类型，从启动页进入，不认领任何地址。区块内容可以画成列表，也可以画成任务管理图。画出的所有内容都读自会话列表快照——页面自己不发起任何读取——每个动作都经由会话服务或 subagent Remote。`ui-sidebar-right` 不知道这个包的存在。
+
+## 目录
+
+- [注册了什么](#what-it-registers)
+- [两个区块](#the-two-sections)
+- [图形形态](#the-graph-form)
+- [chip 徽标](#the-chip-badge)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="what-it-registers"></a>
+## 注册了什么
+
+- **类型** —— `ctx.sidebarRightTabs.register(...)`：kind `tasks`、id `@qilin-agent/client-ui-sidebar-tasks`、band `builtin`、无 patterns、`single`，以及一个启动页条目（order 40，标题与描述来自 `sidebarTasks` 命名空间，图形用共享的清单图标）。
+- **页面主体** —— 同一 id 下的 keyed `sidebar.right.pane.tab` 席位，声明图形视图的 store，让折叠、排布与镜头在主体卸载后仍然存活。
+- **chip 徽标** —— 同一 id 下的 keyed `sidebar.right.pane.tab.badge` 席位。
+
+`src/client/` 下十一个源文件：`definition.tsx`（类型）、`rows.ts` 与 `lineage.ts`（两份快照的纯投影）、`face.ts`（动作及其 Remote 绑定）、`tasks-graph-model.ts`、`tasks-graph-layout.ts` 与 `tasks-graph-store.ts`（图形的纯模型、纯布局与视图 store）、`TasksBody.tsx`、`TasksGraphView.tsx` 与 `TasksBadge.tsx`（画什么）、`locales.ts`（说什么）、`index.ts`（接线）。
+
+<a id="the-two-sections"></a>
+## 两个区块
+
+**子代理**把会话列表已持有的直接子目录目录（catalog）深度优先摊平：一层就是一个 parent 的 catalog，同层按宿主的持久创建时间 newest-first，只会走进「自己的 catalog 已被读过」的子项——没打开过的分支贡献它自己这一行，下面什么都没有。宿主教不出来的行画成诊断行，且不计数。区块声明的总数取两者中较大者：catalog 报告的子项数，与会话摘要谱系（`indexSubagentDescendants`）记录的后代数——所以谱系尚未收敛时，表头也不会少报。
+
+**后台任务**把进行中的任务按开始时间放前面，已结束的按最新优先；结束时间打平的时候后开始者在前。进行中的行按一秒的时钟走表；已结束的行量它自己的时长。
+
+两个区块到达即展开。超过预览数量的区块——子代理五行、任务三行——把其余的折叠进一个控件。区块与折叠状态是主体自己的，从不离开它。
+
+共三个动作，都由注入的 face 在调用时执行：把某个子代理显现为当前会话、重读某个 parent 的 catalog、以及经 `subagents.interruptByParent` 停掉一个 continuable 子项。
+
+<a id="the-graph-form"></a>
+## 图形形态
+
+子代理区块可以改画成一棵卡片树。`buildTasksGraphModel` 走同一批 catalog，深度优先，每个 catalog 子项一张卡，页面会话另有一张主卡；六张及以上的已结束 one-shot 卡折叠成一张聚合卡，点击才展开，没读过的分支显示占位卡，standby 子项同样折叠。卡片的排布可以是树形、紧凑横向分组或固定六列网格；卡片可以拖动——默认手势连同整棵子树，Alt 则只拖单卡——模型会记住每个偏移。
+
+画布像文档查看器一样操控：滚轮朝光标缩放，背景拖拽平移，双击或适配控件重新取景，且只在用户未持有镜头时才随窗口尺寸重取景。卡片点击按种类路由：聚合卡折叠或展开，占位卡重读其 parent 的 catalog，catalog 卡打开该子项，主卡打开页面的会话。视图状态——形态、逐聚合折叠、排布模式、拖拽偏移与镜头——收在主体席位声明的一个 store 里，离开页签再回来时原样恢复。
+
+<a id="the-chip-badge"></a>
+## chip 徽标
+
+徽标是本会话正在进行的工工作量：activity 为 `running` 的直接子 catalog 行，加上注册表仍持有的任务。孙辈在跑意味着父辈也在跑，所以直接子项已经覆盖了下面的事，徽标因此直接经标准的 `useSessions` 钩子读两份快照，而不去走谱系。零是空闲态而不是计数：chip 不会为它画一个空药丸。
+
+<a id="model-experience"></a>
+## 模型体验
+
+无；本包在浏览器里画会话侧的工作量，不注册任何面向模型的东西。
+
+#### KV Cache 影响
+
+无；两份快照都来自客户端已持有的会话列表，页面不组装任何模型请求。
+
+## 已知限制与暂缓事项
+
+<a id="known-limitations-and-deferred-work"></a>
+- **没有任务输出。** 任务快照带的是状态、时间与 detail，不是流，所以这里看不到进行中任务的输出；读输出是工具的职责，页面不发工具调用。
+- **one-shot 子项不能在这里停。** 中断动作通过持久 parent 寻址 continuable 子项；one-shot 子项可以画出来、可以打开，仅此而已。
+- **深度止步于已读的 catalog。** 页面自己不发起 catalog 读取，所以会话列表从没读过的分支只贡献一行；想展开分支靠刷新动作。
+- **徽标只数直接子项**，理由同上：一次条带渲染不该去走谱系。
+- **图形画的是 catalog，不是 run。** 模型接受会话列表上报的 run、phase 与 member 卡，但页面今天不喂给它任何工作流运行流，所以每个子代理都画成普通的 catalog 卡，或折叠为 done 与 standby；run 词汇先备好，是为了将来接入 feed 时不必改模型。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作台上下文——点开查看</summary>
+
+无。
+
+</details>