dsh-session-matrix 0.0.0-stage → 0.16.3

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.
@@ -0,0 +1,158 @@
1
+ /**
2
+ * Peak / off-peak usage split, reconstructed from a session log.
3
+ *
4
+ * DSH's projections carry usage **totals** only: `tokenUsage.totals` has the
5
+ * four buckets but no time axis, and `sessionStats` has durations but no
6
+ * tokens. The billing window is a fixed rule (Beijing time, Mon–Fri
7
+ * 09:00–12:00 and 14:00–18:00, holidays excluded), so the only missing piece is
8
+ * *when* each request happened — and the session log has it: every
9
+ * `assistant/message` event carries `time` and `data.usage`.
10
+ *
11
+ * The log is a sequence of concatenated zstd frames, one per append. A single
12
+ * `zstdDecompressSync` on the whole file stops after the first frame, so this
13
+ * walks the frame magic instead. Parsing a 20 MB session takes under a second;
14
+ * results are cached by (mtime, size) by the caller.
15
+ */
16
+
17
+ const MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd])
18
+ const BEIJING_OFFSET_MS = 8 * 60 * 60 * 1000
19
+
20
+ /**
21
+ * DeepSeek's peak windows in Beijing time: weekday mornings and afternoons.
22
+ * Public holidays are not modelled — the host does not expose a calendar.
23
+ * @param epochMs - event timestamp.
24
+ * @returns true when the request bills at the peak rate.
25
+ */
26
+ export function isPeakTime(epochMs) {
27
+ if (!Number.isFinite(epochMs)) return false
28
+ const shifted = new Date(epochMs + BEIJING_OFFSET_MS)
29
+ const weekday = shifted.getUTCDay()
30
+ if (weekday === 0 || weekday === 6) return false
31
+ const hour = shifted.getUTCHours()
32
+ return (hour >= 9 && hour < 12) || (hour >= 14 && hour < 18)
33
+ }
34
+
35
+ /** Decompress every concatenated zstd frame in a buffer. */
36
+ export function decompressFrames(buffer, zstd) {
37
+ let text = ''
38
+ let pos = 0
39
+ while (pos < buffer.length) {
40
+ const start = buffer.indexOf(MAGIC, pos)
41
+ if (start < 0) break
42
+ const next = buffer.indexOf(MAGIC, start + 4)
43
+ const frame = buffer.subarray(start, next < 0 ? buffer.length : next)
44
+ try {
45
+ text += zstd(frame).toString('utf8')
46
+ } catch {
47
+ // Two cases land here: a genuinely broken frame, and a false magic that
48
+ // split a real frame in two. Skipping one candidate and retrying keeps
49
+ // the rest of the log readable instead of truncating the whole file.
50
+ if (next < 0) break
51
+ pos = start + 4
52
+ continue
53
+ }
54
+ if (next < 0) break
55
+ pos = next
56
+ }
57
+ return text
58
+ }
59
+
60
+ const emptyUsage = () => ({ uncached: 0, cacheRead: 0, cacheWrite: 0, output: 0 })
61
+
62
+ /**
63
+ * Pull the settled usage out of one model-settlement event.
64
+ *
65
+ * Two event types exist (`packages/core/session/src/types.ts`):
66
+ * `assistant/message` carries an optional top-level `usage` plus the timed
67
+ * `stream`; `assistant/attempt` carries **only** the stream — it is how a
68
+ * failed, retried or cancelled call reaches settlement without a message.
69
+ *
70
+ * Numbers and time come from different places on purpose:
71
+ * - the value prefers the top-level `usage` (it is the settled summary);
72
+ * - the timestamp always prefers the usage chunk's own `time`, because the
73
+ * settlement event is written after the call finishes and can land on the
74
+ * other side of a peak/off-peak boundary. This holds even when the top-level
75
+ * usage exists — an earlier version returned `event.time` in that case and
76
+ * priced the boundary minute wrong.
77
+ *
78
+ * Across 5,456 real settlement events the stream held 0 or 1 usage chunk and
79
+ * never more, so "the chunk" is unambiguous. If a host ever emits several, the
80
+ * last one wins: they would be cumulative snapshots of one request, not
81
+ * separate requests, and summing them would double count.
82
+ * @param event - one `assistant/message` or `assistant/attempt` line.
83
+ * @returns `{ usage, time }` or null when the event carries no usage at all.
84
+ */
85
+ export function usageOfEvent(event) {
86
+ const data = event?.data
87
+ if (!data || typeof data !== 'object') return null
88
+ const stream = Array.isArray(data.stream) ? data.stream : []
89
+ let chunk = null
90
+ for (const record of stream) {
91
+ if (record?.chunk?.type === 'usage' && record.chunk.usage && typeof record.chunk.usage === 'object') {
92
+ chunk = record
93
+ }
94
+ }
95
+ const top = data.usage
96
+ const usage = (top && typeof top === 'object') ? top : (chunk?.chunk?.usage ?? null)
97
+ if (!usage) return null
98
+ const time = Number.isFinite(chunk?.time) ? chunk.time : event.time
99
+ return { usage, time }
100
+ }
101
+
102
+ /**
103
+ * Walk decoded events and sum usage into peak / off-peak buckets.
104
+ *
105
+ * Events may come from the session log (parsed JSONL) or straight from
106
+ * `sessionPersistence.open(id,'read')`, which returns them already parsed.
107
+ * @param events - `assistant/message` / `assistant/attempt` records.
108
+ * @returns `{ peak, off, requests }` or null when there is no usage.
109
+ */
110
+ export function splitUsageEvents(events) {
111
+ const peak = emptyUsage()
112
+ const off = emptyUsage()
113
+ let requests = 0
114
+ // Logs are append-only; a resumed session can repeat an event after a crash.
115
+ // Counting it is intentional: the provider billed the request, and `tokenUsage`
116
+ // totals include it too.
117
+ for (const event of events) {
118
+ if (!event || typeof event !== 'object') continue
119
+ if (event.type !== 'assistant/message' && event.type !== 'assistant/attempt') continue
120
+ const picked = usageOfEvent(event)
121
+ if (!picked) continue
122
+ const { usage } = picked
123
+ const bucket = isPeakTime(picked.time) ? peak : off
124
+ // Negative or non-numeric values are corruption, not credit.
125
+ const take = v => {
126
+ const n = Number(v)
127
+ return Number.isFinite(n) && n > 0 ? n : 0
128
+ }
129
+ // `reasoningTokens` is already inside `outputTokens`; adding it again would
130
+ // double-count. Only the four billable buckets are summed.
131
+ bucket.uncached += take(usage.inputTokens)
132
+ bucket.cacheRead += take(usage.cacheReadTokens)
133
+ bucket.cacheWrite += take(usage.cacheWriteTokens)
134
+ bucket.output += take(usage.outputTokens)
135
+ requests += 1
136
+ }
137
+ const total = peak.uncached + peak.cacheRead + peak.cacheWrite + peak.output
138
+ + off.uncached + off.cacheRead + off.cacheWrite + off.output
139
+ return total > 0 ? { peak, off, requests } : null
140
+ }
141
+
142
+ /**
143
+ * Same as {@link splitUsageEvents}, for raw JSONL.
144
+ * @param text - decompressed log lines.
145
+ * @returns `{ peak, off, requests }` or null when the log has no usage.
146
+ */
147
+ export function splitUsageText(text) {
148
+ const events = []
149
+ for (const line of text.split('\n')) {
150
+ if (!line.includes('"usage"')) continue
151
+ try {
152
+ events.push(JSON.parse(line))
153
+ } catch {
154
+ // A half-written tail line is normal while a session is appending.
155
+ }
156
+ }
157
+ return splitUsageEvents(events)
158
+ }
package/locale/en.json ADDED
@@ -0,0 +1,12 @@
1
+ {
2
+ "meta": {
3
+ "title": "Session Matrix",
4
+ "description": "Multi-session Agent workbench: 1–4 native conversation panes, a rectangular layered session network, context warnings derived from each session's real compaction point, plus prompt-cache hit rate and estimated cost.",
5
+ "detail": "README.md"
6
+ },
7
+ "view": { "cockpit": "Agent Graph", "workspace": "Workspace" },
8
+ "panel": { "title": "Session Matrix" },
9
+ "action": { "open": "Open workbench", "refresh": "Refresh", "enter": "Enter session" },
10
+ "risk": { "ok": "Normal", "warn": "Watch", "crit": "Critical", "unknown": "No data" },
11
+ "empty": { "noSession": "No sessions to show", "pickNode": "Select any node to inspect its context" }
12
+ }
package/locale/zh.json ADDED
@@ -0,0 +1,12 @@
1
+ {
2
+ "meta": {
3
+ "title": "会话矩阵工作台",
4
+ "description": "多会话 Agent 工作台:1–4 格原生对话窗格、矩形分层会话链路图,按各自压缩点换算上下文预警,附带缓存命中与预估费用。",
5
+ "detail": "README.md"
6
+ },
7
+ "view": { "cockpit": "智能体脉络", "workspace": "工作区" },
8
+ "panel": { "title": "会话矩阵工作台" },
9
+ "action": { "open": "打开工作台", "refresh": "刷新", "enter": "进入会话" },
10
+ "risk": { "ok": "正常", "warn": "注意", "crit": "预警", "unknown": "数据未知" },
11
+ "empty": { "noSession": "没有可显示的会话", "pickNode": "点击任一节点查看上下文详情" }
12
+ }
package/package.json CHANGED
@@ -1,6 +1,74 @@
1
1
  {
2
2
  "name": "dsh-session-matrix",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.16.3",
4
+ "description": "A multi-agent workspace for DeepSeek Harness: run parallel sessions, visualize agent relationships, monitor context usage, and manage task handoffs.",
5
+ "keywords": [
6
+ "deepseek-harness",
7
+ "dsh",
8
+ "dsh-plugin",
9
+ "multi-agent",
10
+ "multi-session",
11
+ "session-management",
12
+ "parallel-sessions",
13
+ "context-monitoring",
14
+ "agent-graph",
15
+ "agent-handoff",
16
+ "agent-network",
17
+ "多智能体工作台",
18
+ "多会话管理",
19
+ "会话关系图谱",
20
+ "上下文监控"
21
+ ],
22
+ "homepage": "https://github.com/Wanqiu12345/dsh-session-matrix#readme",
23
+ "repository": {
24
+ "type": "git",
25
+ "url": "git+https://github.com/Wanqiu12345/dsh-session-matrix.git"
26
+ },
27
+ "bugs": {
28
+ "url": "https://github.com/Wanqiu12345/dsh-session-matrix/issues"
29
+ },
30
+ "author": "Wanqiu12345",
31
+ "license": "MIT",
32
+ "type": "module",
33
+ "main": "lib/index.js",
34
+ "exports": {
35
+ ".": "./lib/index.js",
36
+ "./client": "./lib/client.js",
37
+ "./locale/zh.json": "./locale/zh.json",
38
+ "./locale/en.json": "./locale/en.json",
39
+ "./icon": "./icon.svg",
40
+ "./package.json": "./package.json"
41
+ },
42
+ "files": [
43
+ "lib",
44
+ "locale",
45
+ "icon.svg",
46
+ "README.md",
47
+ "LICENSE",
48
+ "cordis.patch.yml",
49
+ "test/"
50
+ ],
51
+ "engines": {
52
+ "node": "^22.19.0 || >=24.0.0",
53
+ "dsh": ">=0.2.2-rc.1"
54
+ },
55
+ "dsh": {
56
+ "bundle": {
57
+ "patch": "./cordis.patch.yml"
58
+ },
59
+ "client": {
60
+ "platform": "web",
61
+ "inject": [
62
+ "@deepseek-ai/dsh-client-ui-layout"
63
+ ]
64
+ },
65
+ "compatibility": {
66
+ "dshReleases": {
67
+ "0.2.2-rc.1+": "compatible"
68
+ }
69
+ }
70
+ },
71
+ "scripts": {
72
+ "test": "node test/host.test.mjs && node test/usage-split.test.mjs && node test/usage-vs-projection.test.mjs"
73
+ }
74
+ }