@deepseek-ai/dsh-tool-session-list 0.0.0-stage → 0.2.3-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 DeepSeek
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,55 @@
1
+ # Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
2
+ # section, a hash of its English and Chinese blocks outside code blocks and generated regions.
3
+ # After editing either side, bring the other along and re-record with:
4
+ # pnpm run verify-translation-pairing --write packages/session-query/tool-session-list/README.md
5
+ /:
6
+ en: 3475319e48226347
7
+ zh: 68361c3ff00d966f
8
+ /deepseek-ai-dsh-tool-session-list:
9
+ en: 963f03d1ba483ea9
10
+ zh: 4809b66477752fe9
11
+ /deepseek-ai-dsh-tool-session-list/summary:
12
+ en: e4e61ecb4f56e250
13
+ zh: 815fd87f03e766f1
14
+ /deepseek-ai-dsh-tool-session-list/table-of-contents:
15
+ en: d152484eb41ac6b4
16
+ zh: 5acc0d3807846b6e
17
+ /deepseek-ai-dsh-tool-session-list/use-this-package:
18
+ en: 388849d88b975263
19
+ zh: df6db1e31c9bba7c
20
+ /deepseek-ai-dsh-tool-session-list/use-this-package/access-and-composition:
21
+ en: 0bf65fbc8660134a
22
+ zh: f4f7b3a0049d3196
23
+ /deepseek-ai-dsh-tool-session-list/use-this-package/listing-behavior:
24
+ en: bd85d03043393832
25
+ zh: 9c57bdd92461c1e1
26
+ /deepseek-ai-dsh-tool-session-list/use-this-package/failures:
27
+ en: 95ee3e3c0ecedadd
28
+ zh: 933d267402ceec74
29
+ /deepseek-ai-dsh-tool-session-list/understand-the-implementation:
30
+ en: ac9f08e72d3f7e64
31
+ zh: 231196ddbb82b779
32
+ /deepseek-ai-dsh-tool-session-list/further-exploration:
33
+ en: 06d8fa5cb2d63b6b
34
+ zh: 2635b93fccf3dbc9
35
+ /deepseek-ai-dsh-tool-session-list/model-experience:
36
+ en: 215e7ba838619b7b
37
+ zh: a311da3843709f90
38
+ /deepseek-ai-dsh-tool-session-list/model-experience/tool-schemas-and-results:
39
+ en: cadc497841430a21
40
+ zh: af4cc374d7d16917
41
+ /deepseek-ai-dsh-tool-session-list/model-experience/tool-schemas-and-results/what-the-model-sees:
42
+ en: 6ffb21f59acadc4e
43
+ zh: 258cded3677be923
44
+ /deepseek-ai-dsh-tool-session-list/model-experience/tool-schemas-and-results/token-effect:
45
+ en: e699317cafee83d9
46
+ zh: 912c0ce1a9f3957f
47
+ /deepseek-ai-dsh-tool-session-list/model-experience/tool-schemas-and-results/kv-cache-effect:
48
+ en: 0e201fbbe37798d8
49
+ zh: fd4bd41e7393c234
50
+ /deepseek-ai-dsh-tool-session-list/known-limitations-and-deferred-work:
51
+ en: 2c53c1fc603e0ff2
52
+ zh: 99a58f1e0e3c27fc
53
+ /deepseek-ai-dsh-tool-session-list/known-limitations-and-deferred-work/dev-note:
54
+ en: e67f633dc6fe7773
55
+ zh: e88aeb617ffb74ea
package/README.md CHANGED
@@ -1,3 +1,126 @@
1
- # Temporary Holding Version
1
+ ---
2
+ description: "List Workspace and Session metadata through optional read-only tools, with pagination and cached titles and activity times."
3
+ kind: "package-reference"
4
+ ---
2
5
 
3
- 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.
6
+ # @deepseek-ai/dsh-tool-session-list
7
+
8
+ English | [中文](README.zh.md)
9
+
10
+ ## Summary
11
+
12
+ Discover workspaces and sessions without resuming an agent or reading cold conversation logs. List empty workspaces, find sessions in a workspace, or list archived sessions. Results contain identifiers and lightweight metadata, with bounded page sizes. Enable these tools when callers may inspect the metadata of the whole mounted runtime.
13
+
14
+ ## Table of Contents
15
+
16
+ - [Use this package](#use-this-package)
17
+ - [Understand the implementation](#understand-the-implementation)
18
+ - [Further Exploration](#further-exploration)
19
+ - [Model Experience](#model-experience)
20
+ - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
21
+ - [Dev Note](#dev-note)
22
+
23
+ -----
24
+
25
+ <a id="use-this-package"></a>
26
+ ## Use this package
27
+
28
+ Mount this optional plugin where the intended callers receive tools. It has no configuration fields and is absent from the default profiles.
29
+
30
+ ### Access and composition
31
+
32
+ Granting these tools grants read access to every Workspace and Session in the mounted runtime. Tool availability is the access control; there is no per-agent Workspace ACL or implicit restriction to the caller's working directory. LiveShare's tool allowlist does not include these tools.
33
+
34
+ The plugin requires `tools`, `sessions`, `sessionQuery`, `workspaceRegistry`, and `sessionProjections`. A projection cache supplies metadata for cold sessions; without it, cold rows use the documented missing-metadata values. In a headless profile, the base bundle supplies the other dependencies; add the Workspace registry and this plugin in a profile patch:
35
+
36
+ ```yaml
37
+ - insert:
38
+ - id: workspace-registry
39
+ name: '@deepseek-ai/dsh-workspace'
40
+ - id: tool-session-list
41
+ name: '@deepseek-ai/dsh-tool-session-list'
42
+ ```
43
+
44
+ When the composition already mounts `workspaceRegistry`, add only the tool row. Workspace initialization follows the [registry's existing history bootstrap](../../workspace/workspace/README.md); listing calls do not create or attach sessions or change registry records.
45
+
46
+ ### Listing behavior
47
+
48
+ Both tools return an array directly. The [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-session-list) defines arguments. Pagination follows filtering and ordering; each call defaults to 20 entries, accepts at most 100, and starts at offset zero. Increase the offset by the number of returned entries to continue; an empty array ends the traversal.
49
+
50
+ `list_workspace` preserves registry order and includes workspaces with no sessions. `list_session` never returns subagent sessions. It includes unarchived sessions by default, including sessions outside every Workspace when no `workspace_id` is supplied. Explicit Workspace selection uses recorded membership, not a matching working directory. Archival matches each Session's own ID.
51
+
52
+ Session order is descending `updated_at`, then ascending Session ID for ties. Activity time is the later of creation and the latest human-authored prompt; assistant activity and title changes do not advance it. Titles come from live projections or persisted projection metadata. Unavailable titles are `null`, and unavailable activity metadata falls back to creation time. Timestamps are ISO 8601 strings. Pin order and manual sidebar order do not affect the results.
53
+
54
+ With `workspace_id`, the call reads its members' headers from the Workspace registry index without persistence I/O, so its work grows with the member count. Without `workspace_id`, it first enumerates every stored and live Session header. Filtering, metadata reads, and sorting then run synchronously. The call does not promise prompt handling of new cancellation requests during this work or one snapshot across all Sessions.
55
+
56
+ ### Failures
57
+
58
+ Invalid pagination and an unknown `workspace_id` fail with `ToolArgsError` (`INVALID_ARGS`); use `list_workspace` to find a registered ID. Query and storage failures fail the call. Cancellation returns no partial result. These failures leave sessions and Workspace records untouched.
59
+
60
+ -----
61
+
62
+ <a id="understand-the-implementation"></a>
63
+ ## Understand the implementation
64
+
65
+ <details>
66
+ <summary>Implementation internals — click to expand</summary>
67
+
68
+ A Workspace selection reads `Workspace.getSessionHeaders()`; an unscoped call uses the existing header-only query listing. Both combine headers with projected metadata. Live rows read blankness and prompt recency through `ctx.sessionQuery.getListMetadata`, the same projection the Session API reads. The title projection remains owned by `dsh-session-title`. Cold rows read the projection cache without opening the underlying log, including on a cache miss. No Session Controller or Agent activation is required.
69
+
70
+ | File | Role |
71
+ |---|---|
72
+ | [`src/index.ts`](src/index.ts) | Tool schemas, registration, JSON result rendering, and generic tool cards |
73
+ | [`src/list.ts`](src/list.ts) | Pagination, membership selection, and live or cached metadata reads |
74
+
75
+ </details>
76
+
77
+ -----
78
+
79
+ <a id="further-exploration"></a>
80
+ ## Further Exploration
81
+
82
+ - [Workspace registry](../../workspace/workspace/README.md) — recorded membership, registry order, and archival.
83
+ - [Session query](../session-query/README.md) — corpus header enumeration and the shared list metadata reader.
84
+ - [Session projection cache](../../session/session-projection-cache/README.md) — persisted metadata and cache availability.
85
+ - [Session query package map](../README.md) — adjacent retrieval capabilities.
86
+
87
+ -----
88
+
89
+ <a id="model-experience"></a>
90
+ ## Model Experience
91
+
92
+ ### Tool schemas and results
93
+
94
+ #### What the model sees
95
+
96
+ The [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-session-list) owns the `list_workspace` and `list_session` schemas. Each result renders as a JSON array. The plugin adds no separate system-prompt section.
97
+
98
+ #### Token effect
99
+
100
+ Available tool schemas contribute request tokens; each invocation adds its arguments and returned metadata. The page limit bounds the number of returned entries, while title and path lengths still affect result size.
101
+
102
+ #### KV Cache effect
103
+
104
+ The schemas remain stable while tool availability is unchanged. Calls append ordinary tool call and result history without replacing prior messages; enabling or disabling the tools changes the schema prefix.
105
+
106
+ ## Known Limitations and Deferred Work
107
+
108
+ <a id="known-limitations-and-deferred-work"></a>
109
+
110
+ These constraints affect consumers of the lists.
111
+
112
+ - **Cold metadata can be missing or stale** — listing never rebuilds it by reading the full log. A `null` title can mean either no title or unavailable title metadata.
113
+ - **Pagination is not a stable snapshot** — concurrent registry or Session changes can move entries between calls. Session listing reads every candidate before selecting a page, so the page size does not bound total work; an unscoped call scales with the Session count.
114
+ - **Blank sessions are listed** — a Session without a turn, such as a Workspace's unused new Session, is a regular result; its `updated_at` equals `created_at` and its title is usually `null`.
115
+ - **Unscoped listing has unit coverage only** — the recorded headless replay passes `workspace_id` on every `list_session` call, so enumeration without a Workspace runs only in unit tests.
116
+ - **Metadata access is runtime-wide** — callers needing per-agent Workspace authorization require a separately defined access policy before these tools are enabled for them.
117
+
118
+ <a id="dev-note"></a>
119
+ ### Dev Note
120
+
121
+ <details>
122
+ <summary>Working context for maintainers — click to expand</summary>
123
+
124
+ None.
125
+
126
+ </details>
package/README.zh.md ADDED
@@ -0,0 +1,126 @@
1
+ ---
2
+ description: "通过可选的只读工具列出 Workspace 和 Session 元数据,支持分页以及缓存中的标题和活动时间。"
3
+ kind: "package-reference"
4
+ ---
5
+
6
+ # @deepseek-ai/dsh-tool-session-list
7
+
8
+ [English](README.md) | 中文
9
+
10
+ ## 概述
11
+
12
+ 无需恢复 agent(智能体)运行或读取冷会话的日志,即可发现工作区和会话。可以列出空工作区、查找某工作区中的会话,或列出已归档会话。结果包含标识符及轻量元数据,并限制每页条目数。当调用者可以查看整个已挂载运行时的元数据时,启用这些工具。
13
+
14
+ ## 目录
15
+
16
+ - [使用本包](#use-this-package)
17
+ - [理解实现](#understand-the-implementation)
18
+ - [进一步探索](#further-exploration)
19
+ - [模型体验](#model-experience)
20
+ - [已知限制与待办工作](#known-limitations-and-deferred-work)
21
+ - [开发备注](#dev-note)
22
+
23
+ -----
24
+
25
+ <a id="use-this-package"></a>
26
+ ## 使用本包
27
+
28
+ 在预期调用者获取工具的作用域中挂载此可选插件。它没有配置字段,默认配置方案不包含它。
29
+
30
+ ### 访问范围与组合
31
+
32
+ 授予这些工具即授予读取已挂载运行时中全部 Workspace 和 Session 的权限。工具可用性就是访问控制;没有逐 agent 的 Workspace ACL,也不会隐式限制到调用者的工作目录。LiveShare 的工具允许列表不包含这些工具。
33
+
34
+ 插件需要 `tools`、`sessions`、`sessionQuery`、`workspaceRegistry` 和 `sessionProjections`。投影缓存为冷会话提供元数据;没有缓存时,冷条目使用下文规定的元数据缺失值。在 headless 配置方案中,基础 bundle 已提供其他依赖;在配置方案补丁中添加 Workspace 注册表和此插件:
35
+
36
+ ```yaml
37
+ - insert:
38
+ - id: workspace-registry
39
+ name: '@deepseek-ai/dsh-workspace'
40
+ - id: tool-session-list
41
+ name: '@deepseek-ai/dsh-tool-session-list'
42
+ ```
43
+
44
+ 如果组合已经挂载 `workspaceRegistry`,只添加工具条目。Workspace 初始化遵循[注册表现有的历史引导行为](../../workspace/workspace/README.zh.md);列表调用不会创建或接入会话,也不会修改注册表记录。
45
+
46
+ ### 列表行为
47
+
48
+ 两个工具都直接返回数组。[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-session-list)定义参数。先过滤和排序,再分页;每次调用默认返回 20 条,最多接受 100 条,起始偏移为零。继续遍历时,将偏移增加已返回的条目数;空数组表示遍历结束。
49
+
50
+ `list_workspace` 保留注册表顺序,并包含没有会话的工作区。`list_session` 从不返回 subagent 会话。它默认包含未归档会话;没有指定 `workspace_id` 时,也包含不属于任何 Workspace 的会话。显式选择 Workspace 时使用已记录的成员关系,而非相同的工作目录。归档筛选匹配每个 Session 自身的 ID。
51
+
52
+ 会话按 `updated_at` 降序排列,时间相同则按 Session ID 升序排列。活动时间取创建时间与最近人工提示词时间的较晚值;助手活动和标题变化不会推进它。标题来自实时投影或持久化投影元数据。标题不可用时为 `null`,活动元数据不可用时回退到创建时间。时间戳使用 ISO 8601 字符串。置顶顺序和侧边栏手动顺序不影响结果。
53
+
54
+ 指定 `workspace_id` 时,调用从 Workspace 注册表索引读取成员 header,不做持久化 I/O,因此工作量随成员数增长。不指定 `workspace_id` 时,先枚举所有已存储和 live Session 的 header。随后的筛选、元数据读取和排序同步执行。调用不承诺在这段工作中及时处理新收到的取消请求,也不承诺所有 Session 共享同一个快照。
55
+
56
+ ### 失败
57
+
58
+ 无效分页参数或未知的 `workspace_id` 以 `ToolArgsError`(`INVALID_ARGS`)失败;使用 `list_workspace` 查找已注册的 ID。查询和存储故障使调用失败。取消不返回部分结果。这些失败不会修改会话或 Workspace 记录。
59
+
60
+ -----
61
+
62
+ <a id="understand-the-implementation"></a>
63
+ ## 理解实现
64
+
65
+ <details>
66
+ <summary>实现细节——点击展开</summary>
67
+
68
+ 选定 Workspace 时读取 `Workspace.getSessionHeaders()`;不指定范围时使用现有的仅 header 查询列表。两者都把 header 与投影元数据结合。实时条目通过 `ctx.sessionQuery.getListMetadata` 读取空白状态与提示词活动时间,与 Session API 读取同一个投影。标题投影仍由 `dsh-session-title` 拥有。冷条目读取投影缓存,不打开底层日志,缓存未命中时也一样。不需要 Session 控制器,也不会激活 agent。
69
+
70
+ | 文件 | 职责 |
71
+ |---|---|
72
+ | [`src/index.ts`](src/index.ts) | 工具 schema、注册、JSON 结果渲染与通用工具卡片 |
73
+ | [`src/list.ts`](src/list.ts) | 分页、成员筛选以及实时或缓存元数据读取 |
74
+
75
+ </details>
76
+
77
+ -----
78
+
79
+ <a id="further-exploration"></a>
80
+ ## 进一步探索
81
+
82
+ - [Workspace 注册表](../../workspace/workspace/README.zh.md)——已记录的成员关系、注册表顺序与归档。
83
+ - [Session 查询](../session-query/README.zh.md)——全量 header 枚举与共享列表元数据读取函数。
84
+ - [Session 投影缓存](../../session/session-projection-cache/README.zh.md)——持久化元数据与缓存可用性。
85
+ - [Session 查询包映射](../README.zh.md)——相邻的检索能力。
86
+
87
+ -----
88
+
89
+ <a id="model-experience"></a>
90
+ ## 模型体验
91
+
92
+ ### 工具 schema 与结果
93
+
94
+ #### 模型可见内容
95
+
96
+ [工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-session-list)拥有 `list_workspace` 和 `list_session` 的 schema。每个结果渲染为 JSON 数组。插件不增加独立的系统提示词段落。
97
+
98
+ #### Token 影响
99
+
100
+ 可用工具的 schema 占用请求 token;每次调用增加其参数和返回的元数据。每页上限限制返回的条目数,标题和路径长度仍会影响结果大小。
101
+
102
+ #### KV Cache 影响
103
+
104
+ 工具可用性不变时,schema 保持稳定。调用追加普通工具调用与结果历史,不替换之前的消息;启用或禁用工具会改变 schema 前缀。
105
+
106
+ ## 已知限制与待办工作
107
+
108
+ <a id="known-limitations-and-deferred-work"></a>
109
+
110
+ 以下约束影响列表消费方。
111
+
112
+ - **冷元数据可能缺失或过期**——列表不会通过读取完整日志重建它。标题为 `null` 可能表示没有标题,也可能表示标题元数据不可用。
113
+ - **分页不是稳定快照**——并发的注册表或 Session 变化可能让条目在多次调用间移动。会话列表先读取全部候选项,再选取一页,因此每页大小不限制总工作量;不指定范围的调用随 Session 总数增长。
114
+ - **空白会话也会列出**——还没有 turn 的 Session(例如 Workspace 中未使用的新 Session)是普通结果;它的 `updated_at` 等于 `created_at`,标题通常为 `null`。
115
+ - **不指定范围的列表只有单测覆盖**——录制的 headless 回放中每次 `list_session` 调用都带 `workspace_id`,因此不指定 Workspace 的枚举只在单元测试中运行。
116
+ - **元数据访问覆盖整个运行时**——需要逐 agent Workspace 授权的调用者,必须先定义独立的访问策略,再为其启用这些工具。
117
+
118
+ <a id="dev-note"></a>
119
+ ### 开发备注
120
+
121
+ <details>
122
+ <summary>维护者工作上下文——点击展开</summary>
123
+
124
+ 无。
125
+
126
+ </details>
package/lib/index.js ADDED
@@ -0,0 +1,228 @@
1
+ import { ToolArgsError, defineTool } from "@deepseek-ai/dsh-tools";
2
+ import { WorkspaceId } from "@deepseek-ai/dsh-workspace";
3
+ /**
4
+ * Resolve pagination before reading any registry or persistence data.
5
+ * @param input - model pagination arguments.
6
+ * @returns the validated count and starting index.
7
+ */
8
+ function resolvePage(input) {
9
+ const limit = input.limit ?? 20;
10
+ const offset = input.offset ?? 0;
11
+ if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new ToolArgsError([`limit must be an integer from 1 to ${String(100)}`]);
12
+ if (!Number.isSafeInteger(offset) || offset < 0) throw new ToolArgsError(["offset must be a non-negative safe integer"]);
13
+ return {
14
+ limit,
15
+ offset
16
+ };
17
+ }
18
+ /**
19
+ * Read one page of the authoritative Workspace order, including empty records.
20
+ * @param ctx - context providing the Workspace registry.
21
+ * @param input - pagination arguments.
22
+ * @param signal - caller cancellation.
23
+ * @returns Workspace metadata with ISO timestamps.
24
+ */
25
+ function listWorkspaces(ctx, input, signal) {
26
+ const { limit, offset } = resolvePage(input);
27
+ signal.throwIfAborted();
28
+ return ctx.workspaceRegistry.list().slice(offset, offset + limit).map((workspace) => ({
29
+ workspace_id: workspace.id,
30
+ title: workspace.title,
31
+ path: workspace.path,
32
+ created_at: workspace.createdAt,
33
+ updated_at: workspace.updatedAt
34
+ }));
35
+ }
36
+ /**
37
+ * List live and persisted Session metadata without opening cold logs or activating Agents.
38
+ * A Workspace selection reads only its members' indexed headers; an unscoped call enumerates
39
+ * the corpus headers. Subagent Sessions are excluded.
40
+ * @param ctx - context providing query, Workspace, and projection services.
41
+ * @param input - filters and pagination arguments.
42
+ * @param signal - caller cancellation, forwarded to the corpus listing.
43
+ * @returns filtered Session metadata ordered by activity, then identity.
44
+ */
45
+ async function listSessions(ctx, input, signal) {
46
+ const { limit, offset } = resolvePage(input);
47
+ signal.throwIfAborted();
48
+ let headers;
49
+ if (input.workspace_id === void 0) {
50
+ headers = (await ctx.sessionQuery.listSessions(signal)).map((record) => record.header);
51
+ signal.throwIfAborted();
52
+ } else {
53
+ const workspace = ctx.workspaceRegistry.get(WorkspaceId(input.workspace_id));
54
+ if (workspace === void 0) throw new ToolArgsError([`workspace_id ${JSON.stringify(input.workspace_id)} is not registered; use list_workspace to find a workspace`]);
55
+ headers = workspace.getSessionHeaders();
56
+ }
57
+ const archived = new Set(ctx.workspaceRegistry.archivedSessionIds);
58
+ const items = [];
59
+ for (const header of headers) {
60
+ if (header.origin === "subagent") continue;
61
+ if (archived.has(header.id) !== (input.archived ?? false)) continue;
62
+ const metadata = readListMetadata(ctx, header);
63
+ items.push({
64
+ session_id: header.id,
65
+ title: metadata.title,
66
+ created_at: new Date(header.createdAt).toISOString(),
67
+ updatedAt: Math.max(header.createdAt, metadata.lastPromptAt ?? 0)
68
+ });
69
+ }
70
+ items.sort((left, right) => right.updatedAt - left.updatedAt || (left.session_id < right.session_id ? -1 : 1));
71
+ return items.slice(offset, offset + limit).map(({ updatedAt, ...item }) => ({
72
+ ...item,
73
+ updated_at: new Date(updatedAt).toISOString()
74
+ }));
75
+ }
76
+ function readListMetadata(ctx, header) {
77
+ const live = ctx.sessions.get(header.id);
78
+ if (live !== void 0) return {
79
+ title: ctx.sessionProjections.snapshot(live, ["title"]).values.title ?? null,
80
+ lastPromptAt: ctx.sessionQuery.getListMetadata(live).lastPromptAt
81
+ };
82
+ const cache = ctx.get("sessionProjectionCache");
83
+ const snapshot = cache?.cachedSnapshot(header, ["title", "sessionListMetadata"]) ?? cache?.cachedPredecessorTitle(header);
84
+ return {
85
+ title: snapshot?.values.title ?? null,
86
+ lastPromptAt: snapshot?.values.sessionListMetadata?.lastPromptAt ?? null
87
+ };
88
+ }
89
+ //#endregion
90
+ //#region lib/types/index.js
91
+ /**
92
+ * Opt-in read-only Workspace and Session metadata tools for the mounted runtime.
93
+ * @module @deepseek-ai/dsh-tool-session-list
94
+ */
95
+ /** Cordis plugin identity. */
96
+ const name = "tool-session-list";
97
+ /** Services needed for header-only listing and live metadata. */
98
+ const inject = [
99
+ "tools",
100
+ "sessions",
101
+ "sessionQuery",
102
+ "workspaceRegistry",
103
+ "sessionProjections"
104
+ ];
105
+ const pagination = {
106
+ limit: {
107
+ type: "integer",
108
+ description: `Maximum entries to return, from 1 to ${String(100)}. Defaults to ${String(20)}.`
109
+ },
110
+ offset: {
111
+ type: "integer",
112
+ description: "Number of matching entries to skip. Defaults to 0."
113
+ }
114
+ };
115
+ /**
116
+ * Grant tools access to all Workspace and Session metadata in this runtime.
117
+ * @param ctx - scoped context granting these tools to its callers.
118
+ */
119
+ function apply(ctx) {
120
+ ctx.tools.register(defineTool({
121
+ name: "list_workspace",
122
+ description: "List workspaces in registry order, including empty workspaces. Returns IDs, titles, paths, and creation and update times.",
123
+ parameters: pagination,
124
+ output: {
125
+ schema: {
126
+ type: "array",
127
+ items: {
128
+ type: "object",
129
+ additionalProperties: false,
130
+ properties: {
131
+ workspace_id: {
132
+ type: "string",
133
+ required: true
134
+ },
135
+ title: {
136
+ type: "string",
137
+ required: true
138
+ },
139
+ path: {
140
+ type: "string",
141
+ required: true
142
+ },
143
+ created_at: {
144
+ type: "string",
145
+ required: true,
146
+ description: "ISO 8601 creation time."
147
+ },
148
+ updated_at: {
149
+ type: "string",
150
+ required: true,
151
+ description: "ISO 8601 update time."
152
+ }
153
+ }
154
+ }
155
+ },
156
+ render: (_args, value) => [{
157
+ type: "text",
158
+ text: JSON.stringify(value)
159
+ }]
160
+ },
161
+ isConcurrencySafe: () => true,
162
+ execute: (args, exec) => Promise.resolve(listWorkspaces(ctx, args, exec.signal)),
163
+ presentCall: (args) => ({
164
+ card: "generic",
165
+ title: "List workspaces",
166
+ kind: "read",
167
+ rawInput: args
168
+ })
169
+ }));
170
+ ctx.tools.register(defineTool({
171
+ name: "list_session",
172
+ description: "List non-subagent sessions by latest human prompt time, newest first, then by ID. Returns IDs, available titles, and ISO creation and update times. Missing activity metadata uses creation time; unavailable titles are null.",
173
+ parameters: {
174
+ workspace_id: {
175
+ type: "string",
176
+ description: "Workspace ID from list_workspace. Lists only its member sessions. Omit to list sessions in every workspace and outside all workspaces."
177
+ },
178
+ archived: {
179
+ type: "boolean",
180
+ description: "Return only archived sessions when true, otherwise only unarchived sessions. Defaults to false."
181
+ },
182
+ ...pagination
183
+ },
184
+ output: {
185
+ schema: {
186
+ type: "array",
187
+ items: {
188
+ type: "object",
189
+ additionalProperties: false,
190
+ properties: {
191
+ session_id: {
192
+ type: "string",
193
+ required: true
194
+ },
195
+ title: {
196
+ oneOf: [{ type: "string" }, { type: "null" }],
197
+ required: true
198
+ },
199
+ created_at: {
200
+ type: "string",
201
+ required: true,
202
+ description: "ISO 8601 creation time."
203
+ },
204
+ updated_at: {
205
+ type: "string",
206
+ required: true,
207
+ description: "ISO 8601 latest human prompt time, or creation time when unavailable."
208
+ }
209
+ }
210
+ }
211
+ },
212
+ render: (_args, value) => [{
213
+ type: "text",
214
+ text: JSON.stringify(value)
215
+ }]
216
+ },
217
+ isConcurrencySafe: () => true,
218
+ execute: (args, exec) => listSessions(ctx, args, exec.signal),
219
+ presentCall: (args) => ({
220
+ card: "generic",
221
+ title: "List sessions",
222
+ kind: "read",
223
+ rawInput: args
224
+ })
225
+ }));
226
+ }
227
+ //#endregion
228
+ export { apply, inject, name };
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Opt-in read-only Workspace and Session metadata tools for the mounted runtime.
3
+ * @module @deepseek-ai/dsh-tool-session-list
4
+ */
5
+ import type { Context } from '@deepseek-ai/cordis';
6
+ /** Cordis plugin identity. */
7
+ export declare const name = "tool-session-list";
8
+ /** Services needed for header-only listing and live metadata. */
9
+ export declare const inject: string[];
10
+ /**
11
+ * Grant tools access to all Workspace and Session metadata in this runtime.
12
+ * @param ctx - scoped context granting these tools to its callers.
13
+ */
14
+ export declare function apply(ctx: Context): void;
15
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIlD,8BAA8B;AAC9B,eAAO,MAAM,IAAI,sBAAsB,CAAA;AACvC,iEAAiE;AACjE,eAAO,MAAM,MAAM,UAAmF,CAAA;AAOtG;;;GAGG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAsDxC"}
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAE5F,8BAA8B;AAC9B,MAAM,CAAC,MAAM,IAAI,GAAG,mBAAmB,CAAA;AACvC,iEAAiE;AACjE,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,mBAAmB,EAAE,oBAAoB,CAAC,CAAA;AAEtG,MAAM,UAAU,GAAG;IACjB,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,wCAAwC,MAAM,CAAC,cAAc,CAAC,iBAAiB,MAAM,CAAC,kBAAkB,CAAC,GAAG,EAAE;IACrJ,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,oDAAoD,EAAE;CACtF,CAAA;AAEV;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAC,GAAY;IAChC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC5B,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,2HAA2H;QACxI,UAAU,EAAE,UAAU;QACtB,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,oBAAoB,EAAE,KAAK;oBAC3B,UAAU,EAAE;wBACV,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;wBAChD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;wBACzC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;wBACxC,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,yBAAyB,EAAE;wBACtF,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,uBAAuB,EAAE;qBACrF;iBACF;aACF;YACD,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;SAC1E;QACD,iBAAiB,EAAE,GAAG,EAAE,CAAC,IAAI;QAC7B,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAChF,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;KACnG,CAAC,CAAC,CAAA;IACH,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC5B,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,gOAAgO;QAC7O,UAAU,EAAE;YACV,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,wIAAwI,EAAE;YACvL,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,iGAAiG,EAAE;YAC7I,GAAG,UAAU;SACd;QACD,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,oBAAoB,EAAE,KAAK;oBAC3B,UAAU,EAAE;wBACV,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;wBAC9C,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE;wBACxE,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,yBAAyB,EAAE;wBACtF,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,uEAAuE,EAAE;qBACrI;iBACF;aACF;YACD,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;SAC1E;QACD,iBAAiB,EAAE,GAAG,EAAE,CAAC,IAAI;QAC7B,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;QAC7D,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;KACjG,CAAC,CAAC,CAAA;AACL,CAAC"}
@@ -0,0 +1,60 @@
1
+ /** Header-only selection and cached metadata for the read-only listing tools. */
2
+ import type { Context } from '@deepseek-ai/cordis';
3
+ import type { SessionId } from '@deepseek-ai/dsh-session';
4
+ import { WorkspaceId } from '@deepseek-ai/dsh-workspace';
5
+ /** Optional model pagination arguments. */
6
+ export interface PageInput {
7
+ readonly limit?: number;
8
+ readonly offset?: number;
9
+ }
10
+ /** Optional Session selection arguments. */
11
+ export interface SessionListInput extends PageInput {
12
+ readonly workspace_id?: string;
13
+ readonly archived?: boolean;
14
+ }
15
+ interface WorkspaceListItem {
16
+ workspace_id: WorkspaceId;
17
+ title: string;
18
+ path: string;
19
+ created_at: string;
20
+ updated_at: string;
21
+ }
22
+ interface SessionListItem {
23
+ session_id: SessionId;
24
+ title: string | null;
25
+ created_at: string;
26
+ updated_at: string;
27
+ }
28
+ /** Entries per page when the model passes no `limit`; part of the model-visible schema. */
29
+ export declare const DEFAULT_PAGE_LIMIT = 20;
30
+ /** Largest accepted `limit`; part of the model-visible schema. */
31
+ export declare const MAX_PAGE_LIMIT = 100;
32
+ /**
33
+ * Resolve pagination before reading any registry or persistence data.
34
+ * @param input - model pagination arguments.
35
+ * @returns the validated count and starting index.
36
+ */
37
+ export declare function resolvePage(input: PageInput): {
38
+ limit: number;
39
+ offset: number;
40
+ };
41
+ /**
42
+ * Read one page of the authoritative Workspace order, including empty records.
43
+ * @param ctx - context providing the Workspace registry.
44
+ * @param input - pagination arguments.
45
+ * @param signal - caller cancellation.
46
+ * @returns Workspace metadata with ISO timestamps.
47
+ */
48
+ export declare function listWorkspaces(ctx: Context, input: PageInput, signal: AbortSignal): WorkspaceListItem[];
49
+ /**
50
+ * List live and persisted Session metadata without opening cold logs or activating Agents.
51
+ * A Workspace selection reads only its members' indexed headers; an unscoped call enumerates
52
+ * the corpus headers. Subagent Sessions are excluded.
53
+ * @param ctx - context providing query, Workspace, and projection services.
54
+ * @param input - filters and pagination arguments.
55
+ * @param signal - caller cancellation, forwarded to the corpus listing.
56
+ * @returns filtered Session metadata ordered by activity, then identity.
57
+ */
58
+ export declare function listSessions(ctx: Context, input: SessionListInput, signal: AbortSignal): Promise<SessionListItem[]>;
59
+ export {};
60
+ //# sourceMappingURL=list.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/list.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAEjF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAKxE,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAA;AAExD,2CAA2C;AAC3C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAC5B;AAED,UAAU,iBAAiB;IACzB,YAAY,EAAE,WAAW,CAAA;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,UAAU,eAAe;IACvB,UAAU,EAAE,SAAS,CAAA;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,2FAA2F;AAC3F,eAAO,MAAM,kBAAkB,KAAK,CAAA;AACpC,kEAAkE;AAClE,eAAO,MAAM,cAAc,MAAM,CAAA;AAEjC;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAU/E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,iBAAiB,EAAE,CAUvG;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,eAAe,EAAE,CAAC,CAiC5B"}
@@ -0,0 +1 @@
1
+ {"version":3,"file":"list.js","sourceRoot":"","sources":["../../src/list.ts"],"names":[],"mappings":"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"}
package/locale/de.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "Werkzeuge zur Sitzungsauflistung",
4
+ "description": "Listet Arbeitsbereiche und Sitzungen auf, ohne Agenten fortzusetzen."
5
+ }
6
+ }
package/locale/en.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "Session listing tools",
4
+ "description": "List workspaces and sessions without resuming agents."
5
+ }
6
+ }
package/locale/es.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "Herramientas de listado de sesiones",
4
+ "description": "Lista espacios de trabajo y sesiones sin reanudar los agentes."
5
+ }
6
+ }
package/locale/fr.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "Outils de liste des sessions",
4
+ "description": "Liste les espaces de travail et les sessions sans relancer les agents."
5
+ }
6
+ }
package/locale/ja.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "セッション一覧ツール",
4
+ "description": "エージェントを再開せずにワークスペースとセッションを一覧表示します。"
5
+ }
6
+ }
package/locale/pt.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "Ferramentas de listagem de sessões",
4
+ "description": "Lista espaços de trabalho e sessões sem retomar os agentes."
5
+ }
6
+ }
package/locale/ru.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "Инструменты списка сеансов",
4
+ "description": "Показывает рабочие пространства и сеансы без возобновления работы агентов."
5
+ }
6
+ }
package/locale/zh.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "会话列表工具",
4
+ "description": "列出工作区和会话,无需恢复智能体运行。"
5
+ }
6
+ }
package/package.json CHANGED
@@ -1,6 +1,71 @@
1
1
  {
2
2
  "name": "@deepseek-ai/dsh-tool-session-list",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "description": "Read-only paginated Workspace and Session metadata tools",
4
+ "version": "0.2.3-alpha.1",
5
+ "publishConfig": {
6
+ "access": "public"
7
+ },
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
11
+ "directory": "packages/session-query/tool-session-list"
12
+ },
13
+ "type": "module",
14
+ "main": "lib/index.js",
15
+ "types": "lib/types/index.d.ts",
16
+ "exports": {
17
+ ".": {
18
+ "types": "./lib/types/index.d.ts",
19
+ "default": "./lib/index.js"
20
+ },
21
+ "./src/*": "./src/*",
22
+ "./locale/*.json": "./locale/*.json",
23
+ "./package.json": "./package.json"
24
+ },
25
+ "files": [
26
+ "locale/*.json",
27
+ "lib/index.js",
28
+ "lib/types/**/*.d.ts",
29
+ "lib/types/**/*.d.ts.map",
30
+ "lib/**/*.js.map",
31
+ "src"
32
+ ],
33
+ "license": "MIT",
34
+ "peerDependencies": {
35
+ "@deepseek-ai/cordis": "~4.1.0",
36
+ "@deepseek-ai/dsh-tools": "0.2.3-alpha.1",
37
+ "@deepseek-ai/dsh-session": "0.2.3-alpha.1",
38
+ "@deepseek-ai/dsh-session-query": "0.2.3-alpha.1",
39
+ "@deepseek-ai/dsh-session-projection": "0.2.3-alpha.1",
40
+ "@deepseek-ai/dsh-session-projection-cache": "0.2.3-alpha.1",
41
+ "@deepseek-ai/dsh-workspace": "0.2.3-alpha.1",
42
+ "@deepseek-ai/dsh-session-title": "0.2.3-alpha.1"
43
+ },
44
+ "devDependencies": {
45
+ "@deepseek-ai/cordis": "~4.1.0",
46
+ "@deepseek-ai/dsh-tools": "0.2.3-alpha.1",
47
+ "@deepseek-ai/dsh-session": "0.2.3-alpha.1",
48
+ "@deepseek-ai/dsh-session-query": "0.2.3-alpha.1",
49
+ "@deepseek-ai/dsh-session-projection": "0.2.3-alpha.1",
50
+ "@deepseek-ai/dsh-session-projection-cache": "0.2.3-alpha.1",
51
+ "@deepseek-ai/dsh-workspace": "0.2.3-alpha.1",
52
+ "@deepseek-ai/dsh-agent": "0.2.3-alpha.1",
53
+ "@deepseek-ai/dsh-llm": "0.2.3-alpha.1",
54
+ "@deepseek-ai/dsh-session-title": "0.2.3-alpha.1",
55
+ "@deepseek-ai/dsh-session-persistence": "0.2.3-alpha.1",
56
+ "@deepseek-ai/dsh-storage": "0.2.3-alpha.1",
57
+ "@deepseek-ai/dsh-storage-domain": "0.2.3-alpha.1",
58
+ "@deepseek-ai/dsh-system-prompt": "0.2.3-alpha.1",
59
+ "@deepseek-ai/dsh-tool-executor-native": "0.2.3-alpha.1",
60
+ "@deepseek-ai/dsh-tool-testkit": "0.2.3-alpha.1",
61
+ "@deepseek-ai/dsh-storage-json": "0.2.3-alpha.1"
62
+ },
63
+ "peerDependenciesMeta": {
64
+ "@deepseek-ai/dsh-session-projection-cache": {
65
+ "optional": true
66
+ },
67
+ "@deepseek-ai/dsh-session-title": {
68
+ "optional": true
69
+ }
70
+ }
6
71
  }
package/src/index.ts ADDED
@@ -0,0 +1,78 @@
1
+ /**
2
+ * Opt-in read-only Workspace and Session metadata tools for the mounted runtime.
3
+ * @module @deepseek-ai/dsh-tool-session-list
4
+ */
5
+
6
+ import type { Context } from '@deepseek-ai/cordis'
7
+ import { defineTool } from '@deepseek-ai/dsh-tools'
8
+ import { DEFAULT_PAGE_LIMIT, listSessions, listWorkspaces, MAX_PAGE_LIMIT } from './list.ts'
9
+
10
+ /** Cordis plugin identity. */
11
+ export const name = 'tool-session-list'
12
+ /** Services needed for header-only listing and live metadata. */
13
+ export const inject = ['tools', 'sessions', 'sessionQuery', 'workspaceRegistry', 'sessionProjections']
14
+
15
+ const pagination = {
16
+ limit: { type: 'integer', description: `Maximum entries to return, from 1 to ${String(MAX_PAGE_LIMIT)}. Defaults to ${String(DEFAULT_PAGE_LIMIT)}.` },
17
+ offset: { type: 'integer', description: 'Number of matching entries to skip. Defaults to 0.' },
18
+ } as const
19
+
20
+ /**
21
+ * Grant tools access to all Workspace and Session metadata in this runtime.
22
+ * @param ctx - scoped context granting these tools to its callers.
23
+ */
24
+ export function apply(ctx: Context): void {
25
+ ctx.tools.register(defineTool({
26
+ name: 'list_workspace',
27
+ description: 'List workspaces in registry order, including empty workspaces. Returns IDs, titles, paths, and creation and update times.',
28
+ parameters: pagination,
29
+ output: {
30
+ schema: {
31
+ type: 'array',
32
+ items: {
33
+ type: 'object',
34
+ additionalProperties: false,
35
+ properties: {
36
+ workspace_id: { type: 'string', required: true },
37
+ title: { type: 'string', required: true },
38
+ path: { type: 'string', required: true },
39
+ created_at: { type: 'string', required: true, description: 'ISO 8601 creation time.' },
40
+ updated_at: { type: 'string', required: true, description: 'ISO 8601 update time.' },
41
+ },
42
+ },
43
+ },
44
+ render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
45
+ },
46
+ isConcurrencySafe: () => true,
47
+ execute: (args, exec) => Promise.resolve(listWorkspaces(ctx, args, exec.signal)),
48
+ presentCall: args => ({ card: 'generic', title: 'List workspaces', kind: 'read', rawInput: args }),
49
+ }))
50
+ ctx.tools.register(defineTool({
51
+ name: 'list_session',
52
+ description: 'List non-subagent sessions by latest human prompt time, newest first, then by ID. Returns IDs, available titles, and ISO creation and update times. Missing activity metadata uses creation time; unavailable titles are null.',
53
+ parameters: {
54
+ workspace_id: { type: 'string', description: 'Workspace ID from list_workspace. Lists only its member sessions. Omit to list sessions in every workspace and outside all workspaces.' },
55
+ archived: { type: 'boolean', description: 'Return only archived sessions when true, otherwise only unarchived sessions. Defaults to false.' },
56
+ ...pagination,
57
+ },
58
+ output: {
59
+ schema: {
60
+ type: 'array',
61
+ items: {
62
+ type: 'object',
63
+ additionalProperties: false,
64
+ properties: {
65
+ session_id: { type: 'string', required: true },
66
+ title: { oneOf: [{ type: 'string' }, { type: 'null' }], required: true },
67
+ created_at: { type: 'string', required: true, description: 'ISO 8601 creation time.' },
68
+ updated_at: { type: 'string', required: true, description: 'ISO 8601 latest human prompt time, or creation time when unavailable.' },
69
+ },
70
+ },
71
+ },
72
+ render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
73
+ },
74
+ isConcurrencySafe: () => true,
75
+ execute: (args, exec) => listSessions(ctx, args, exec.signal),
76
+ presentCall: args => ({ card: 'generic', title: 'List sessions', kind: 'read', rawInput: args }),
77
+ }))
78
+ }
package/src/list.ts ADDED
@@ -0,0 +1,145 @@
1
+ /** Header-only selection and cached metadata for the read-only listing tools. */
2
+
3
+ import type { Context } from '@deepseek-ai/cordis'
4
+ import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
5
+ import type {} from '@deepseek-ai/dsh-session-query'
6
+ import type {} from '@deepseek-ai/dsh-session-projection-cache'
7
+ import type {} from '@deepseek-ai/dsh-session-title'
8
+ import { ToolArgsError } from '@deepseek-ai/dsh-tools'
9
+ import { WorkspaceId } from '@deepseek-ai/dsh-workspace'
10
+
11
+ /** Optional model pagination arguments. */
12
+ export interface PageInput {
13
+ readonly limit?: number
14
+ readonly offset?: number
15
+ }
16
+
17
+ /** Optional Session selection arguments. */
18
+ export interface SessionListInput extends PageInput {
19
+ readonly workspace_id?: string
20
+ readonly archived?: boolean
21
+ }
22
+
23
+ interface WorkspaceListItem {
24
+ workspace_id: WorkspaceId
25
+ title: string
26
+ path: string
27
+ created_at: string
28
+ updated_at: string
29
+ }
30
+
31
+ interface SessionListItem {
32
+ session_id: SessionId
33
+ title: string | null
34
+ created_at: string
35
+ updated_at: string
36
+ }
37
+
38
+ /** Entries per page when the model passes no `limit`; part of the model-visible schema. */
39
+ export const DEFAULT_PAGE_LIMIT = 20
40
+ /** Largest accepted `limit`; part of the model-visible schema. */
41
+ export const MAX_PAGE_LIMIT = 100
42
+
43
+ /**
44
+ * Resolve pagination before reading any registry or persistence data.
45
+ * @param input - model pagination arguments.
46
+ * @returns the validated count and starting index.
47
+ */
48
+ export function resolvePage(input: PageInput): { limit: number; offset: number } {
49
+ const limit = input.limit ?? DEFAULT_PAGE_LIMIT
50
+ const offset = input.offset ?? 0
51
+ if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_PAGE_LIMIT) {
52
+ throw new ToolArgsError([`limit must be an integer from 1 to ${String(MAX_PAGE_LIMIT)}`])
53
+ }
54
+ if (!Number.isSafeInteger(offset) || offset < 0) {
55
+ throw new ToolArgsError(['offset must be a non-negative safe integer'])
56
+ }
57
+ return { limit, offset }
58
+ }
59
+
60
+ /**
61
+ * Read one page of the authoritative Workspace order, including empty records.
62
+ * @param ctx - context providing the Workspace registry.
63
+ * @param input - pagination arguments.
64
+ * @param signal - caller cancellation.
65
+ * @returns Workspace metadata with ISO timestamps.
66
+ */
67
+ export function listWorkspaces(ctx: Context, input: PageInput, signal: AbortSignal): WorkspaceListItem[] {
68
+ const { limit, offset } = resolvePage(input)
69
+ signal.throwIfAborted()
70
+ return ctx.workspaceRegistry.list().slice(offset, offset + limit).map(workspace => ({
71
+ workspace_id: workspace.id,
72
+ title: workspace.title,
73
+ path: workspace.path,
74
+ created_at: workspace.createdAt,
75
+ updated_at: workspace.updatedAt,
76
+ }))
77
+ }
78
+
79
+ /**
80
+ * List live and persisted Session metadata without opening cold logs or activating Agents.
81
+ * A Workspace selection reads only its members' indexed headers; an unscoped call enumerates
82
+ * the corpus headers. Subagent Sessions are excluded.
83
+ * @param ctx - context providing query, Workspace, and projection services.
84
+ * @param input - filters and pagination arguments.
85
+ * @param signal - caller cancellation, forwarded to the corpus listing.
86
+ * @returns filtered Session metadata ordered by activity, then identity.
87
+ */
88
+ export async function listSessions(
89
+ ctx: Context,
90
+ input: SessionListInput,
91
+ signal: AbortSignal,
92
+ ): Promise<SessionListItem[]> {
93
+ const { limit, offset } = resolvePage(input)
94
+ signal.throwIfAborted()
95
+ let headers: readonly SessionHeader[]
96
+ if (input.workspace_id === undefined) {
97
+ headers = (await ctx.sessionQuery.listSessions(signal)).map(record => record.header)
98
+ signal.throwIfAborted()
99
+ } else {
100
+ const workspace = ctx.workspaceRegistry.get(WorkspaceId(input.workspace_id))
101
+ if (workspace === undefined) {
102
+ throw new ToolArgsError([`workspace_id ${JSON.stringify(input.workspace_id)} is not registered; use list_workspace to find a workspace`])
103
+ }
104
+ headers = workspace.getSessionHeaders()
105
+ }
106
+ const archived = new Set(ctx.workspaceRegistry.archivedSessionIds)
107
+ const items: Array<Omit<SessionListItem, 'updated_at'> & { updatedAt: number }> = []
108
+ for (const header of headers) {
109
+ if (header.origin === 'subagent') continue
110
+ if (archived.has(header.id) !== (input.archived ?? false)) continue
111
+ const metadata = readListMetadata(ctx, header)
112
+ items.push({
113
+ session_id: header.id,
114
+ title: metadata.title,
115
+ created_at: new Date(header.createdAt).toISOString(),
116
+ updatedAt: Math.max(header.createdAt, metadata.lastPromptAt ?? 0),
117
+ })
118
+ }
119
+ items.sort((left, right) => right.updatedAt - left.updatedAt
120
+ || (left.session_id < right.session_id ? -1 : 1))
121
+ return items.slice(offset, offset + limit).map(({ updatedAt, ...item }) => ({
122
+ ...item,
123
+ updated_at: new Date(updatedAt).toISOString(),
124
+ }))
125
+ }
126
+
127
+ function readListMetadata(
128
+ ctx: Context,
129
+ header: SessionHeader,
130
+ ): { title: string | null; lastPromptAt: number | null } {
131
+ const live = ctx.sessions.get(header.id)
132
+ if (live !== undefined) {
133
+ return {
134
+ title: ctx.sessionProjections.snapshot(live, ['title']).values.title ?? null,
135
+ lastPromptAt: ctx.sessionQuery.getListMetadata(live).lastPromptAt,
136
+ }
137
+ }
138
+ const cache = ctx.get('sessionProjectionCache')
139
+ const snapshot = cache?.cachedSnapshot(header, ['title', 'sessionListMetadata'])
140
+ ?? cache?.cachedPredecessorTitle(header)
141
+ return {
142
+ title: snapshot?.values.title ?? null,
143
+ lastPromptAt: snapshot?.values.sessionListMetadata?.lastPromptAt ?? null,
144
+ }
145
+ }