@deepseek-ai/dsh-session-stats 0.0.1-rc.5

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/session/session-stats/README.md
+README.md: 81b0de17e335b67936afd6fb11f15411beee3b76
+README.zh.md: 606628ea09bc34203a5374e49db62c1646293846

package/README.md

@@ -0,0 +1,39 @@
+# @deepseek-ai/dsh-session-stats
+
+English | [中文](README.zh.md)
+
+Function plugin registering the `sessionStats` projection unit: whole-log conversation figures — turn/step counts and the LLM, tool, first-token, and decode wall times — folded from step boundaries, stream chunks, tool pairs, and assembled assistant messages, and served through the session-projection seam (registry snapshot, change feed, and every projection carrier: history tail page, `session/projection` push frames, session list rows). Clients render full-session figures that paging and compaction cannot change; the reference consumer is the web chat stats strip, whose window fold mirrors these field names as its no-unit fallback.
+
+## Fold semantics
+
+- `steps` counts `step/end` events. The agent loop appends exactly one per entered step, in a `finally`, so completed, failed, cancelled, and max-tokens steps all count. Counting assembled assistant messages instead would overcount max-tokens usage-host messages (empty content, excluded from the surface) and undercount cancelled steps (aborted before the message assembles).
+- `turns` counts distinct turns carrying at least one closed step; rejected or empty turns (closed with no step) are uncounted. Turn numbers are host-assigned and monotonic per session, so the fold keeps only the last counted turn.
+- `llmMs` sums `step/start` → `assistant/message` per step that assembled a message (retry waits inside the step are model time, as in the window fold).
+- `ttftMs`/`ttftSteps` sum and count `step/start` → first non-empty delta chunk; the first attempt's boundary survives an in-step `llm/retry` (window `resetForRetry` parity).
+- `decodeMs`/`decodeTokens` sum first token → assembled message and the provider-reported output tokens, only over steps carrying both.
+- `toolMs` sums `tool/call` → `tool/result` pairs matched by callId; unresolved calls are dropped at `turn/end` (results land within their turn).
+- Every field is 0 until its first contributing event. A composed registry always serves the key, so clients read the value, never key presence.
+
+## Composition
+
+```yaml
+- id: session-stats
+  name: '@deepseek-ai/dsh-session-stats'
+```
+
+Injects `sessionProjections` — the plugin's whole purpose; in assemblies without the registry the fiber stays pending and nothing registers.
+
+## Model Experience
+
+None, as the plugin only computes a client-facing read model of already-logged session events and touches no prompt, message, schema, stream, or tool result.
+
+#### KV Cache effect
+
+None; the plugin never assembles or sends provider requests.
+
+## Known Limitations and Deferred Work
+
+- **Steps count work attempted, not visible output** — a step that failed before producing any visible content still closed with `step/end` and counts; a step interrupted by a crash counts after the session reloads, when crash recovery appends its synthetic `step/end` (`interruptedTurnClosers` in dsh-session).
+- **A cancelled step is counted but untimed** — no assistant message assembles, so its partial stream time enters no wall-time figure, matching the window fold's untimed interrupted node; a max-tokens usage-host message conversely contributes model time the surface does not show.
+- **Counts are log-scoped, not surface-scoped** — steps whose messages were later compacted away stay counted; the figures describe the whole session, not the current model-visible surface.
+- **Mounted only in the web-app bundle** — other assemblies serve no `sessionStats` key, and their consumers fall back to window-scoped counting (the web stats strip's fallback path).

package/README.zh.md

@@ -0,0 +1,39 @@
+# @deepseek-ai/dsh-session-stats
+
+[English](README.md) | 中文
+
+注册 `sessionStats` projection 单元的函数插件：从步边界、流式 chunk、工具配对与已组装的 assistant 消息折叠出全日志会话数字——轮/步计数以及 LLM、工具、首 token、解码墙钟时间——经 session-projection 缝对外提供（registry 快照、变更流，以及每一个 projection 载体：history 尾页、`session/projection` 推送帧、会话列表行）。客户端由此渲染分页与压缩都无法改变的全会话数字；参考消费者是 Web 聊天统计条，其窗口折叠以相同字段名充当无单元时的回退。
+
+## 折叠语义
+
+- `steps` 统计 `step/end` 事件。agent loop 对每个进入的步在 `finally` 中恰好追加一条，因此完成、失败、取消、max-tokens 的步全部计入。若改按已组装的 assistant 消息计数，则会多算 max-tokens 的 usage 宿主消息（空内容、被排除在 surface 之外），并少算被取消的步（在消息组装前已中止）。
+- `turns` 统计含至少一个已关闭步的不同 turn；被拒绝或空轮（未进入任何步即关闭）不计。turn 号由宿主分配、按会话单调递增，因此折叠只需保留最近计入的 turn。
+- `llmMs` 按步累加 `step/start` → `assistant/message`（组装出消息的步；步内重试的等待与窗口折叠一样计入模型时间）。
+- `ttftMs`/`ttftSteps` 累加并统计 `step/start` → 首个非空 delta chunk；首次尝试的边界在步内 `llm/retry` 后保留（与窗口 `resetForRetry` 对齐）。
+- `decodeMs`/`decodeTokens` 累加首 token → 已组装消息的时长与提供方上报的输出 token，仅统计两者兼备的步。
+- `toolMs` 按 callId 配对累加 `tool/call` → `tool/result`；未解决的调用在 `turn/end` 时丢弃（结果总在其轮内落地）。
+- 每个字段在首个贡献事件之前均为 0。已装配的 registry 恒提供该键，客户端读取值本身，而非键的存在性。
+
+## 组合
+
+```yaml
+- id: session-stats
+  name: '@deepseek-ai/dsh-session-stats'
+```
+
+注入 `sessionProjections`——这是插件的全部用途；在没有 registry 的装配中 fiber 保持挂起，不注册任何内容。
+
+## 模型体验
+
+无，因为插件只计算面向客户端的、由已写入日志的会话事件派生的读模型，不触碰任何提示词、消息、schema、流或工具结果。
+
+#### KV Cache 影响
+
+无；插件从不组装或发送提供方请求。
+
+## 已知局限与延后工作
+
+- **步数统计的是已发生的工作，而非可见输出**——在产生任何可见内容前就失败的步仍以 `step/end` 关闭并计入；被崩溃打断的步在会话重新加载后计入，届时崩溃恢复为其补写合成的 `step/end`（dsh-session 的 `interruptedTurnClosers`）。
+- **被取消的步计数但不计时**——没有组装出 assistant 消息，其部分流式时间不进入任何墙钟数字，与窗口折叠的无计时 interrupted 节点一致；反之 max-tokens 的 usage 宿主消息贡献 surface 上看不到的模型时间。
+- **计数是日志口径，不是 surface 口径**——消息后来被压缩掉的步仍然计入；数字描述整个会话，而非当前模型可见 surface。
+- **仅挂载于 web-app bundle**——其他装配不提供 `sessionStats` 键，其消费者回退到窗口口径计数（Web 统计条的回退路径）。

package/lib/index.js

@@ -0,0 +1,177 @@
+import { z } from "zod";
+import { isTokenDelta } from "@deepseek-ai/dsh-llm/message";
+//#region lib/types/projection.js
+/**
+* The `sessionStats` projection unit: a pure fold of step boundaries, stream
+* chunks, tool pairs, and assembled assistant messages into whole-log counts
+* and wall times.
+*
+* `step/end` — not `assistant/message` — is the counted step event because it
+* is the step lifecycle authority: the loop appends exactly one per entered
+* step, in a `finally`, so completed, failed, cancelled, and max-tokens steps
+* all land one. Counting assembled assistant messages instead would overcount
+* max-tokens usage-host messages (empty content, excluded from the surface)
+* and undercount cancelled steps (aborted before the message assembles).
+*
+* The wall-time folds mirror the client window fold field by field
+* (`deriveStats` in dsh-client-ui-conversation, that fold's whole-window
+* fallback role): model time is `step/start` → `assistant/message`, first
+* token is the first non-empty delta chunk and survives an in-step
+* `llm/retry`, decode spans first token → assembled message on steps that
+* also report output tokens, and tool time pairs `tool/call` → `tool/result`
+* by callId. A cancelled step assembles no message, so its partial stream
+* time stays uncounted in every time figure — matching the window, which
+* renders it as an untimed interrupted node.
+*
+* @module @deepseek-ai/dsh-session-stats/projection
+*/
+const sessionStatsSchema = z.object({
+	turns: z.number().int().nonnegative(),
+	steps: z.number().int().nonnegative(),
+	llmMs: z.number().nonnegative(),
+	toolMs: z.number().nonnegative(),
+	ttftMs: z.number().nonnegative(),
+	ttftSteps: z.number().int().nonnegative(),
+	decodeMs: z.number().nonnegative(),
+	decodeTokens: z.number().nonnegative()
+}).strict();
+/**
+* Provider-reported completion tokens, guarded the way the window fold guards
+* node usage.
+* @param usage - the assistant/message event's optional usage record.
+* @returns the output-token count, or null when unreported or invalid.
+*/
+function usageOutputTokens(usage) {
+	if (typeof usage !== "object" || usage === null) return null;
+	const value = usage.outputTokens;
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+/** The `sessionStats` unit registered on `ctx.sessionProjections` (exported for the unit spec). */
+const sessionStatsProjectionDefinition = {
+	key: "sessionStats",
+	schema: sessionStatsSchema,
+	init: () => ({
+		turns: 0,
+		steps: 0,
+		llmMs: 0,
+		toolMs: 0,
+		ttftMs: 0,
+		ttftSteps: 0,
+		decodeMs: 0,
+		decodeTokens: 0,
+		lastTurn: null,
+		openStep: null,
+		pendingCalls: {}
+	}),
+	apply: (state, event) => {
+		switch (event.type) {
+			case "step/start": return {
+				...state,
+				openStep: {
+					turn: event.data.turn,
+					step: event.data.step,
+					startTime: event.time,
+					firstTokenTime: null
+				}
+			};
+			case "assistant/chunk": {
+				const open = state.openStep;
+				if (open === null || open.turn !== event.data.turn || open.step !== event.data.step) return state;
+				if (open.firstTokenTime !== null || !isTokenDelta(event.data.chunk)) return state;
+				return {
+					...state,
+					openStep: {
+						...open,
+						firstTokenTime: event.time
+					}
+				};
+			}
+			case "assistant/message": {
+				const open = state.openStep;
+				if (open === null || open.turn !== event.data.turn || open.step !== event.data.step) return state;
+				const next = {
+					...state,
+					llmMs: state.llmMs + Math.max(0, event.time - open.startTime),
+					openStep: null
+				};
+				if (open.firstTokenTime !== null) {
+					next.ttftMs += Math.max(0, open.firstTokenTime - open.startTime);
+					next.ttftSteps += 1;
+					const outputTokens = usageOutputTokens(event.data.usage);
+					if (outputTokens !== null) {
+						next.decodeMs += Math.max(0, event.time - open.firstTokenTime);
+						next.decodeTokens += outputTokens;
+					}
+				}
+				return next;
+			}
+			case "tool/call": return {
+				...state,
+				pendingCalls: {
+					...state.pendingCalls,
+					[event.data.callId]: event.time
+				}
+			};
+			case "tool/result": {
+				const callId = event.data.message.source.callId;
+				const dispatched = Object.hasOwn(state.pendingCalls, callId) ? state.pendingCalls[callId] : void 0;
+				if (dispatched === void 0) return state;
+				const pendingCalls = Object.fromEntries(Object.entries(state.pendingCalls).filter(([id]) => id !== callId));
+				return {
+					...state,
+					toolMs: state.toolMs + Math.max(0, event.time - dispatched),
+					pendingCalls
+				};
+			}
+			case "step/end": return {
+				...state,
+				turns: state.lastTurn === event.data.turn ? state.turns : state.turns + 1,
+				steps: state.steps + 1,
+				lastTurn: event.data.turn,
+				openStep: null
+			};
+			case "turn/end": return Object.keys(state.pendingCalls).length === 0 ? state : {
+				...state,
+				pendingCalls: {}
+			};
+			default: return state;
+		}
+	},
+	view: (state) => ({
+		turns: state.turns,
+		steps: state.steps,
+		llmMs: state.llmMs,
+		toolMs: state.toolMs,
+		ttftMs: state.ttftMs,
+		ttftSteps: state.ttftSteps,
+		decodeMs: state.decodeMs,
+		decodeTokens: state.decodeTokens
+	}),
+	stateVersion: 1
+};
+//#endregion
+//#region lib/types/index.js
+/**
+* Function plugin registering the `sessionStats` projection unit: whole-log
+* turn/step counts and LLM/tool/first-token/decode wall times served through
+* the session-projection seam (registry snapshot, change feed, and every
+* projection carrier), so clients render full-session figures that paging and
+* compaction cannot change. The plugin owns only the fold; delivery is the
+* seam's.
+*
+* @module @deepseek-ai/dsh-session-stats
+*/
+/** Cordis plugin name. */
+const name = "session-stats";
+/** The projection registry is the plugin's whole purpose; without it the fiber stays pending. */
+const inject = ["sessionProjections"];
+/**
+* Register the `sessionStats` unit; the registration is an effect on this
+* plugin's fiber, so unloading removes the key.
+* @param ctx - registrant context carrying the projection registry.
+*/
+function apply(ctx) {
+	ctx.sessionProjections.register(sessionStatsProjectionDefinition);
+}
+//#endregion
+export { apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,28 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-session-stats`.
+* @module @deepseek-ai/dsh-session-stats/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-session-stats";
+/** Cordis companion plugin name. */
+const name = "session-stats-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the package owns a single pure projection fold whose
+* wire payload is schema-validated by the projection registry at every
+* snapshot and change-feed emission, and the event relations the fold relies
+* on (`step/end` exactly once per entered step, monotonic host-assigned turn
+* numbers, chunk and tool events carrying their step coordinates and call
+* ids) are owned and runtime-checked by dsh-agent-loop and the session
+* surface, not here.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the session-stats domain: a pure re-export
+ * of the package's types outlet. Client code imports ONLY the client
+ * namespace (repo discipline), so `./client` projects the same single-source
+ * content `./types` serves to host consumers — zero duplication.
+ *
+ * @module @deepseek-ai/dsh-session-stats/client
+ */
+export type * from './types.ts';
+//# sourceMappingURL=client.d.ts.map

package/lib/types/client.js

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the session-stats domain: a pure re-export
+ * of the package's types outlet. Client code imports ONLY the client
+ * namespace (repo discipline), so `./client` projects the same single-source
+ * content `./types` serves to host consumers — zero duplication.
+ *
+ * @module @deepseek-ai/dsh-session-stats/client
+ */
+export {};
+//# sourceMappingURL=client.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Function plugin registering the `sessionStats` projection unit: whole-log
+ * turn/step counts and LLM/tool/first-token/decode wall times served through
+ * the session-projection seam (registry snapshot, change feed, and every
+ * projection carrier), so clients render full-session figures that paging and
+ * compaction cannot change. The plugin owns only the fold; delivery is the
+ * seam's.
+ *
+ * @module @deepseek-ai/dsh-session-stats
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export type * from './types.ts';
+/** Cordis plugin name. */
+export declare const name = "session-stats";
+/** The projection registry is the plugin's whole purpose; without it the fiber stays pending. */
+export declare const inject: string[];
+/**
+ * Register the `sessionStats` unit; the registration is an effect on this
+ * plugin's fiber, so unloading removes the key.
+ * @param ctx - registrant context carrying the projection registry.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,24 @@
+/**
+ * Function plugin registering the `sessionStats` projection unit: whole-log
+ * turn/step counts and LLM/tool/first-token/decode wall times served through
+ * the session-projection seam (registry snapshot, change feed, and every
+ * projection carrier), so clients render full-session figures that paging and
+ * compaction cannot change. The plugin owns only the fold; delivery is the
+ * seam's.
+ *
+ * @module @deepseek-ai/dsh-session-stats
+ */
+import { sessionStatsProjectionDefinition } from "./projection.js";
+/** Cordis plugin name. */
+export const name = 'session-stats';
+/** The projection registry is the plugin's whole purpose; without it the fiber stays pending. */
+export const inject = ['sessionProjections'];
+/**
+ * Register the `sessionStats` unit; the registration is an effect on this
+ * plugin's fiber, so unloading removes the key.
+ * @param ctx - registrant context carrying the projection registry.
+ */
+export function apply(ctx) {
+    ctx.sessionProjections.register(sessionStatsProjectionDefinition);
+}
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-stats`.
+ * @module @deepseek-ai/dsh-session-stats/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "session-stats-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,27 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-stats`.
+ * @module @deepseek-ai/dsh-session-stats/invariant
+ */
+const PACKAGE_NAME = '@deepseek-ai/dsh-session-stats';
+/** Cordis companion plugin name. */
+export const name = 'session-stats-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: the package owns a single pure projection fold whose
+ * wire payload is schema-validated by the projection registry at every
+ * snapshot and change-feed emission, and the event relations the fold relies
+ * on (`step/end` exactly once per entered step, monotonic host-assigned turn
+ * numbers, chunk and tool events carrying their step coordinates and call
+ * ids) are owned and runtime-checked by dsh-agent-loop and the session
+ * surface, not here.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/types/projection.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The `sessionStats` projection unit: a pure fold of step boundaries, stream
+ * chunks, tool pairs, and assembled assistant messages into whole-log counts
+ * and wall times.
+ *
+ * `step/end` — not `assistant/message` — is the counted step event because it
+ * is the step lifecycle authority: the loop appends exactly one per entered
+ * step, in a `finally`, so completed, failed, cancelled, and max-tokens steps
+ * all land one. Counting assembled assistant messages instead would overcount
+ * max-tokens usage-host messages (empty content, excluded from the surface)
+ * and undercount cancelled steps (aborted before the message assembles).
+ *
+ * The wall-time folds mirror the client window fold field by field
+ * (`deriveStats` in dsh-client-ui-conversation, that fold's whole-window
+ * fallback role): model time is `step/start` → `assistant/message`, first
+ * token is the first non-empty delta chunk and survives an in-step
+ * `llm/retry`, decode spans first token → assembled message on steps that
+ * also report output tokens, and tool time pairs `tool/call` → `tool/result`
+ * by callId. A cancelled step assembles no message, so its partial stream
+ * time stays uncounted in every time figure — matching the window, which
+ * renders it as an untimed interrupted node.
+ *
+ * @module @deepseek-ai/dsh-session-stats/projection
+ */
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection';
+/** Accumulated whole-log figures (the view is exactly these totals). */
+interface SessionStatsTotals {
+    /** Distinct turns with at least one closed step so far. */
+    turns: number;
+    /** Closed steps so far. */
+    steps: number;
+    /** Summed model wall time over message-assembling steps, ms. */
+    llmMs: number;
+    /** Summed matched tool call→result wall time, ms. */
+    toolMs: number;
+    /** Summed first-token latency over `ttftSteps`, ms. */
+    ttftMs: number;
+    /** Steps carrying a recorded first token. */
+    ttftSteps: number;
+    /** Summed decode wall time over usage-reporting steps, ms. */
+    decodeMs: number;
+    /** Summed provider output tokens over the same steps. */
+    decodeTokens: number;
+}
+/**
+ * Fold state: the totals plus the in-flight boundaries they accrue from.
+ * Turn numbers are host-assigned and monotonic per session, so a single
+ * `lastTurn` slot decides "first closed step of a new turn"; the state is
+ * plain JSON per the unit contract (persisted-cache precondition).
+ */
+interface SessionStatsState extends SessionStatsTotals {
+    /** Turn of the last counted `step/end`; null before the first. */
+    lastTurn: number | null;
+    /** The open step's boundary facts; null outside a step or after its message assembled. */
+    openStep: {
+        turn: number;
+        step: number;
+        startTime: number;
+        firstTokenTime: number | null;
+    } | null;
+    /** Dispatch times of tool calls whose result has not landed, by callId. */
+    pendingCalls: Record<string, number>;
+}
+/** The `sessionStats` unit registered on `ctx.sessionProjections` (exported for the unit spec). */
+export declare const sessionStatsProjectionDefinition: ProjectionDefinition<'sessionStats', SessionStatsState>;
+export {};
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/projection.js

@@ -0,0 +1,147 @@
+/**
+ * The `sessionStats` projection unit: a pure fold of step boundaries, stream
+ * chunks, tool pairs, and assembled assistant messages into whole-log counts
+ * and wall times.
+ *
+ * `step/end` — not `assistant/message` — is the counted step event because it
+ * is the step lifecycle authority: the loop appends exactly one per entered
+ * step, in a `finally`, so completed, failed, cancelled, and max-tokens steps
+ * all land one. Counting assembled assistant messages instead would overcount
+ * max-tokens usage-host messages (empty content, excluded from the surface)
+ * and undercount cancelled steps (aborted before the message assembles).
+ *
+ * The wall-time folds mirror the client window fold field by field
+ * (`deriveStats` in dsh-client-ui-conversation, that fold's whole-window
+ * fallback role): model time is `step/start` → `assistant/message`, first
+ * token is the first non-empty delta chunk and survives an in-step
+ * `llm/retry`, decode spans first token → assembled message on steps that
+ * also report output tokens, and tool time pairs `tool/call` → `tool/result`
+ * by callId. A cancelled step assembles no message, so its partial stream
+ * time stays uncounted in every time figure — matching the window, which
+ * renders it as an untimed interrupted node.
+ *
+ * @module @deepseek-ai/dsh-session-stats/projection
+ */
+import { z } from 'zod';
+import { isTokenDelta } from '@deepseek-ai/dsh-llm/message';
+const sessionStatsSchema = z.object({
+    turns: z.number().int().nonnegative(),
+    steps: z.number().int().nonnegative(),
+    llmMs: z.number().nonnegative(),
+    toolMs: z.number().nonnegative(),
+    ttftMs: z.number().nonnegative(),
+    ttftSteps: z.number().int().nonnegative(),
+    decodeMs: z.number().nonnegative(),
+    decodeTokens: z.number().nonnegative(),
+}).strict();
+/**
+ * Provider-reported completion tokens, guarded the way the window fold guards
+ * node usage.
+ * @param usage - the assistant/message event's optional usage record.
+ * @returns the output-token count, or null when unreported or invalid.
+ */
+function usageOutputTokens(usage) {
+    if (typeof usage !== 'object' || usage === null)
+        return null;
+    const value = usage.outputTokens;
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+}
+/** The `sessionStats` unit registered on `ctx.sessionProjections` (exported for the unit spec). */
+export const sessionStatsProjectionDefinition = {
+    key: 'sessionStats',
+    schema: sessionStatsSchema,
+    init: () => ({
+        turns: 0,
+        steps: 0,
+        llmMs: 0,
+        toolMs: 0,
+        ttftMs: 0,
+        ttftSteps: 0,
+        decodeMs: 0,
+        decodeTokens: 0,
+        lastTurn: null,
+        openStep: null,
+        pendingCalls: {},
+    }),
+    apply: (state, event) => {
+        // Every uninteresting event returns the same reference (Object.is gates the change feed).
+        switch (event.type) {
+            case 'step/start':
+                return {
+                    ...state,
+                    openStep: { turn: event.data.turn, step: event.data.step, startTime: event.time, firstTokenTime: null },
+                };
+            case 'assistant/chunk': {
+                const open = state.openStep;
+                if (open === null || open.turn !== event.data.turn || open.step !== event.data.step)
+                    return state;
+                if (open.firstTokenTime !== null || !isTokenDelta(event.data.chunk))
+                    return state;
+                return { ...state, openStep: { ...open, firstTokenTime: event.time } };
+            }
+            case 'assistant/message': {
+                const open = state.openStep;
+                if (open === null || open.turn !== event.data.turn || open.step !== event.data.step)
+                    return state;
+                // One assembled message per step: closing the boundary means a
+                // defensive duplicate cannot accrue twice.
+                const next = {
+                    ...state,
+                    llmMs: state.llmMs + Math.max(0, event.time - open.startTime),
+                    openStep: null,
+                };
+                if (open.firstTokenTime !== null) {
+                    next.ttftMs += Math.max(0, open.firstTokenTime - open.startTime);
+                    next.ttftSteps += 1;
+                    const outputTokens = usageOutputTokens(event.data.usage);
+                    if (outputTokens !== null) {
+                        next.decodeMs += Math.max(0, event.time - open.firstTokenTime);
+                        next.decodeTokens += outputTokens;
+                    }
+                }
+                return next;
+            }
+            case 'tool/call':
+                return { ...state, pendingCalls: { ...state.pendingCalls, [event.data.callId]: event.time } };
+            case 'tool/result': {
+                // Own-key check: callId is provider-minted (model/tool JSON boundary),
+                // so a prototype property name ('constructor', 'toString') on a result
+                // with no recorded call must read as unmatched, not as an inherited
+                // function that would poison toolMs with NaN.
+                const callId = event.data.message.source.callId;
+                const dispatched = Object.hasOwn(state.pendingCalls, callId) ? state.pendingCalls[callId] : undefined;
+                if (dispatched === undefined)
+                    return state;
+                const pendingCalls = Object.fromEntries(Object.entries(state.pendingCalls).filter(([id]) => id !== callId));
+                return { ...state, toolMs: state.toolMs + Math.max(0, event.time - dispatched), pendingCalls };
+            }
+            case 'step/end':
+                return {
+                    ...state,
+                    turns: state.lastTurn === event.data.turn ? state.turns : state.turns + 1,
+                    steps: state.steps + 1,
+                    lastTurn: event.data.turn,
+                    openStep: null,
+                };
+            case 'turn/end':
+                // A call whose result never landed belongs to a cancelled or failed
+                // turn; results always land within their turn, so drop the leftovers
+                // instead of growing persisted state forever.
+                return Object.keys(state.pendingCalls).length === 0 ? state : { ...state, pendingCalls: {} };
+            default:
+                return state;
+        }
+    },
+    view: state => ({
+        turns: state.turns,
+        steps: state.steps,
+        llmMs: state.llmMs,
+        toolMs: state.toolMs,
+        ttftMs: state.ttftMs,
+        ttftSteps: state.ttftSteps,
+        decodeMs: state.decodeMs,
+        decodeTokens: state.decodeTokens,
+    }),
+    stateVersion: 1,
+};
+//# sourceMappingURL=projection.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure types of the session-stats domain: the ONE home of the `sessionStats`
+ * projection-key declaration, free of this package's host-side value imports
+ * (cordis context, zod, the llm chunk predicate). Two namespace projections
+ * serve it — `./types` for host consumers, `./client` for client aggregates —
+ * with zero content duplication.
+ *
+ * @module @deepseek-ai/dsh-session-stats/types
+ */
+export {};
+/**
+ * Whole-log conversation figures, independent of how much history a client
+ * has paged in. Counts and wall times all fold from the complete durable log;
+ * every field is 0 until its first contributing event lands. Field names
+ * mirror the client window fold so an assembly without this unit can fall
+ * back to it wholesale.
+ */
+export interface SessionStatsProjection {
+    /** Distinct turns carrying at least one closed step (`step/end`); rejected or empty turns are uncounted. */
+    turns: number;
+    /** Closed steps (`step/end` events) — completed, failed, and cancelled steps alike. */
+    steps: number;
+    /** Summed model wall time (`step/start` → `assistant/message`) over steps that assembled a message. */
+    llmMs: number;
+    /** Summed tool wall time over `tool/call` → `tool/result` pairs matched by callId. */
+    toolMs: number;
+    /** Summed first-token latency (`step/start` → first non-empty delta chunk) over `ttftSteps`. */
+    ttftMs: number;
+    /** Steps carrying a recorded first token. */
+    ttftSteps: number;
+    /** Summed decode wall time (first token → `assistant/message`) over steps that also report output tokens. */
+    decodeMs: number;
+    /** Summed provider output tokens over the same decode-timed steps. */
+    decodeTokens: number;
+}
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionMap {
+        /** Whole-log turn/step counts and wall times; see {@link SessionStatsProjection}. */
+        sessionStats: SessionStatsProjection;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,11 @@
+/**
+ * Pure types of the session-stats domain: the ONE home of the `sessionStats`
+ * projection-key declaration, free of this package's host-side value imports
+ * (cordis context, zod, the llm chunk predicate). Two namespace projections
+ * serve it — `./types` for host consumers, `./client` for client aggregates —
+ * with zero content duplication.
+ *
+ * @module @deepseek-ai/dsh-session-stats/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@deepseek-ai/dsh-session-stats",
+  "description": "Whole-log conversation counts and wall times projection (sessionStats) for the DeepSeek Harness",
+  "version": "0.0.1-rc.5",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/session/session-stats"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./client": {
+      "types": "./lib/types/client.d.ts",
+      "default": "./lib/types/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-session-projection": "^0.0.1-rc.5",
+    "@deepseek-ai/cordis": "^4.0.1-rc.4"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2-rc.4",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-session-projection": "^0.0.1-rc.5",
+    "@deepseek-ai/cordis": "^4.0.1-rc.4",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.6-rc.4"
+  }
+}