@hydraharness/harness-session-stats 0.1.1-rc.6

package/LICENSE

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

package/README.md

@@ -0,0 +1,37 @@
+# @hydraharness/harness-session-stats
+
+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: '@hydraharness/harness-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 @hydraharness/harness-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/lib/index.js

@@ -0,0 +1,196 @@
+import { z } from "zod";
+import { isTokenDelta } from "@hydraharness/harness-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 @hydraharness/harness-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 @hydraharness/harness-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();
+/**
+* The fold state's shape (totals plus in-flight boundaries), validated on
+* persisted-cache rows after their `ver` gate — the unit's input boundary.
+* The view is a strict subset of the state, so this schema extends
+* `sessionStatsSchema` (the wire output boundary) with the boundary fields.
+*/
+const sessionStatsStateSchema = sessionStatsSchema.extend({
+	lastTurn: z.number().int().nonnegative().nullable(),
+	openStep: z.object({
+		turn: z.number().int().nonnegative(),
+		step: z.number().int().nonnegative(),
+		startTime: z.number().nonnegative(),
+		firstTokenTime: z.number().nonnegative().nullable()
+	}).nullable(),
+	pendingCalls: z.record(z.string(), z.number().nonnegative())
+});
+/**
+* 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",
+	stateVersion: 1,
+	stateSchema: sessionStatsStateSchema,
+	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;
+		}
+	},
+	wire: {
+		viewSchema: sessionStatsSchema,
+		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
+		})
+	}
+};
+//#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 @hydraharness/harness-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 `@hydraharness/harness-session-stats`.
+* @module @hydraharness/harness-session-stats/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-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 @hydraharness/harness-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 @hydraharness/harness-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 @hydraharness/harness-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 @hydraharness/harness-session-stats
+ */
+import type { Context } from '@hydraharness/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 @hydraharness/harness-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 `@hydraharness/harness-session-stats`.
+ * @module @hydraharness/harness-session-stats/invariant
+ */
+import type { Context } from '@hydraharness/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 `@hydraharness/harness-session-stats`.
+ * @module @hydraharness/harness-session-stats/invariant
+ */
+const PACKAGE_NAME = '@hydraharness/harness-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 @hydraharness/harness-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,129 @@
+/**
+ * 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 @hydraharness/harness-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 @hydraharness/harness-session-stats/projection
+ */
+import { z } from 'zod';
+/** 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>;
+}
+declare module '@hydraharness/harness-session-projection/types' {
+    interface SessionProjectionStateMap {
+        sessionStats: SessionStatsState;
+    }
+}
+/** The `sessionStats` unit registered on `ctx.sessionProjections` (exported for the unit spec). */
+export declare const sessionStatsProjectionDefinition: {
+    key: "sessionStats";
+    stateVersion: number;
+    stateSchema: z.ZodObject<{
+        turns: z.ZodNumber;
+        steps: z.ZodNumber;
+        llmMs: z.ZodNumber;
+        toolMs: z.ZodNumber;
+        ttftMs: z.ZodNumber;
+        ttftSteps: z.ZodNumber;
+        decodeMs: z.ZodNumber;
+        decodeTokens: z.ZodNumber;
+        lastTurn: z.ZodNullable<z.ZodNumber>;
+        openStep: z.ZodNullable<z.ZodObject<{
+            turn: z.ZodNumber;
+            step: z.ZodNumber;
+            startTime: z.ZodNumber;
+            firstTokenTime: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+        pendingCalls: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$strict>;
+    init: () => {
+        turns: number;
+        steps: number;
+        llmMs: number;
+        toolMs: number;
+        ttftMs: number;
+        ttftSteps: number;
+        decodeMs: number;
+        decodeTokens: number;
+        lastTurn: null;
+        openStep: null;
+        pendingCalls: {};
+    };
+    apply: (state: NoInfer<SessionStatsState>, event: import("@hydraharness/harness-session").SessionEvent) => SessionStatsState;
+    wire: {
+        viewSchema: z.ZodObject<{
+            turns: z.ZodNumber;
+            steps: z.ZodNumber;
+            llmMs: z.ZodNumber;
+            toolMs: z.ZodNumber;
+            ttftMs: z.ZodNumber;
+            ttftSteps: z.ZodNumber;
+            decodeMs: z.ZodNumber;
+            decodeTokens: z.ZodNumber;
+        }, z.core.$strict>;
+        view: (state: NoInfer<SessionStatsState>) => {
+            turns: number;
+            steps: number;
+            llmMs: number;
+            toolMs: number;
+            ttftMs: number;
+            ttftSteps: number;
+            decodeMs: number;
+            decodeTokens: number;
+        };
+    };
+};
+export {};
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/projection.js

@@ -0,0 +1,166 @@
+/**
+ * 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 @hydraharness/harness-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 @hydraharness/harness-session-stats/projection
+ */
+import { z } from 'zod';
+import { isTokenDelta } from '@hydraharness/harness-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();
+/**
+ * The fold state's shape (totals plus in-flight boundaries), validated on
+ * persisted-cache rows after their `ver` gate — the unit's input boundary.
+ * The view is a strict subset of the state, so this schema extends
+ * `sessionStatsSchema` (the wire output boundary) with the boundary fields.
+ */
+const sessionStatsStateSchema = sessionStatsSchema.extend({
+    lastTurn: z.number().int().nonnegative().nullable(),
+    openStep: z.object({
+        turn: z.number().int().nonnegative(),
+        step: z.number().int().nonnegative(),
+        startTime: z.number().nonnegative(),
+        firstTokenTime: z.number().nonnegative().nullable(),
+    }).nullable(),
+    pendingCalls: z.record(z.string(), z.number().nonnegative()),
+});
+/**
+ * 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',
+    stateVersion: 1,
+    stateSchema: sessionStatsStateSchema,
+    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;
+        }
+    },
+    wire: {
+        viewSchema: sessionStatsSchema,
+        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,
+        }),
+    },
+};
+//# 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 @hydraharness/harness-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 '@hydraharness/harness-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 @hydraharness/harness-session-stats/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@hydraharness/harness-session-stats",
+  "description": "Whole-log conversation counts and wall times projection (sessionStats) for the Hydra harness",
+  "hydra": {
+    "plugin": {
+      "application": "Show conversation counts and elapsed times derived from the session history."
+    }
+  },
+  "version": "0.1.1-rc.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-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": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-session": "^0.1.1-rc.6",
+    "@hydraharness/harness-session-projection": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@hydraharness/cordis-plugin-loader": "^1.0.3",
+    "@hydraharness/cordis-plugin-include": "^1.0.7",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-session": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-session-projection": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2"
+  }
+}