dsh-context 0.29.0 → 0.30.1

package/lib/index.d.ts

@@ -2,29 +2,24 @@ import { ZodType, z } from "zod";
 import { Session, SessionEvent } from "@deepseek-ai/dsh-session";
 import { Context, Service } from "@deepseek-ai/cordis";
 //#region src/host/config.d.ts
-/** dsh-context host config. All fields optional; defaults below. */
 interface Config {
   /** Cap on kept per-step request records (the hard step backstop). */
   maxRequestSteps?: number;
   /** Newest whole-turn window kept; trimming crosses whole turns, never mid-turn. */
   maxKeptTurns?: number;
-  /** Newest context-event records kept. */
   maxEvents?: number;
   /**
-   * Surface nodes served to the browser (newest carry the signal; live
-   * inject nodes are always served — they are few and land first). The
-   * default is deliberately generous: auto-compaction keeps the live
-   * surface far below it in healthy sessions, so the browser effectively
-   * lists EVERY live node; the bound stays as a backstop for pathological
-   * sessions (every projection push ships the whole value, ~150B per node).
+   * Served surface nodes (newest carry the signal; live inject nodes are pinned — they land first and are few). Deliberately generous:
+   * auto-compaction keeps healthy surfaces far below it, so the browser effectively lists every live node; the bound is a
+   * pathological-session backstop (each push ships the whole value, ~150B/node).
    */
   maxNodes?: number;
   /** Removed (shadowed) surface nodes kept for per-step reconstruction. */
   maxArchiveNodes?: number;
 }
 /**
- * The cordis `Config` validator: strict on keys, defaults on the schema fields.
- * Tolerates `undefined` (a patch row without a `config:` block — defaults win).
+ * The cordis `Config` validator: strict on keys, defaults on the schema fields; tolerates `undefined` (a patch row without a `config:`
+ * block — defaults win).
  */
 declare const Config: z.ZodPreprocess<z.ZodObject<{
   maxRequestSteps: z.ZodDefault<z.ZodNumber>;
@@ -36,19 +31,10 @@ declare const Config: z.ZodPreprocess<z.ZodObject<{
 //#endregion
 //#region src/shared/types.d.ts
 /**
- * Shared wire contract — the snapshot model exchanged between the Host and
- * Client halves.
- *
- * The Host half no longer serves this over a custom RPC channel: it is the
- * `view()` payload of the `contextTimeline` session projection, registered on
- * the harness's `ctx.sessionProjections` registry. The registry drives
- * `apply(state, event)` over every committed session event, persists the state
- * through `ctx.sessionProjectionCache`, and pushes the finished value to the
- * browser as a `session/projection` frame (with a tail-page baseline), where
- * the Client reads it through the framework-standard `useProjection` seat.
- *
- * TYPE-ONLY host-side module: both halves import these as `import type`, so
- * nothing from here ever reaches the runtime bundles.
+ * Shared wire contract — the snapshot model exchanged between the Host and Client halves. Delivered as the `view()` payload of the
+ * `contextTimeline`/`contextHeaders` session projections (registered on `ctx.sessionProjections`; the registry pushes finished views as
+ * `session/projection` frames — see host/timeline.ts). TYPE-ONLY host-side module: both halves import these as `import type`, so nothing
+ * from here ever reaches the runtime bundles.
  */
 declare module '@deepseek-ai/dsh-session-projection/types' {
   interface SessionProjectionMap {
@@ -70,7 +56,6 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
     contextHeaders: ContextHeaders;
   }
 }
-/** The five priced context categories (plus system/tools handled separately). */
 type Category = 'user' | 'inject' | 'assistant' | 'tool';
 interface Snapshot {
   ok: boolean;
@@ -93,15 +78,10 @@ interface Snapshot {
    * instead. Kept optional for wire compatibility with older clients.
    */
   occupancy?: {
-    /** Provider-reported prompt size of the most recent request (input + cache). */
     pressureTokens?: number;
-    /** Heuristic total over the current model-visible surface. */
     surfaceTokens: number;
-    /** `surfaceTokens` at the newest usage sample. */
     sampledSurfaceTokens?: number;
-    /** pressureTokens + surface movement since the sample (clamped ≥ 0). */
     projectedTokens?: number;
-    /** Newest recorded route capacity (last-wins). */
     contextWindow?: number;
   };
   toolList: {
@@ -131,10 +111,9 @@ interface Snapshot {
    */
   cost?: SessionCostUsage;
   /**
-   * The served live surface: the newest `maxNodes` tail PLUS every live
-   * inject node older than the tail (injections land first and are few, so
-   * they are pinned — otherwise a long session would price them while the
-   * browser could list none). Seq-ordered, oldest first.
+   * The served live surface: the newest `maxNodes` tail PLUS every live inject node older than the tail (injections land first and are
+   * few,
+   * so they are pinned). Seq-ordered, oldest first.
    */
   nodes: SurfaceNode[];
   /** Live nodes not served (the overflow beyond `maxNodes`, minus pinned injects — see `nodes`). */
@@ -159,11 +138,8 @@ interface Snapshot {
   archiveFloor?: number;
 }
 /**
- * The `contextTimeline` projection's whole value — the same snapshot the
- * Client has always rendered, now delivered through the session-projection
- * pipeline. `ok` is always `true` here (a delivered projection is by
- * definition available); it is kept for wire compatibility with the
- * snapshot shape.
+ * The `contextTimeline` projection's whole value — the same snapshot the Client has always rendered. `ok` is always `true` here (a
+ * delivered projection is by definition available); kept for wire compatibility with the snapshot shape.
  */
 type ContextTimeline = Snapshot;
 /**
@@ -172,20 +148,14 @@ type ContextTimeline = Snapshot;
  * session log, immune to the request/event retention bounds).
  */
 interface CostBucketTotals {
-  /** Billed prompt tokens that missed the provider cache. */
   uncached: number;
-  /** Billed prompt tokens served from the provider cache. */
   cacheRead: number;
-  /** Billed prompt tokens written into the provider cache. */
   cacheWrite: number;
-  /** Billed output tokens (reasoning included). */
   output: number;
 }
 /** One model family's totals split by DeepSeek's pricing period (Beijing Time). */
 interface CostFamilyUsage {
-  /** Peak windows: 09:00-12:00 and 14:00-18:00 Beijing Time, weekdays only. */
   peak?: CostBucketTotals;
-  /** All other hours plus all of Saturday/Sunday (half the peak rate). */
   off?: CostBucketTotals;
 }
 /**
@@ -202,7 +172,6 @@ interface SessionCostUsage {
 /** One model-visible message on the surface, with its heuristic token price. */
 interface SurfaceNode {
   seq: number;
-  /** Event timestamp (ms epoch); the Client shows it when present. */
   time?: number;
   cat: Category;
   tokens: number;
@@ -236,6 +205,12 @@ interface RequestRecord {
   tool: number;
   total: number;
   prompt?: number;
+  /**
+   * Billed cache-read (served) prompt tokens of this request — the
+   * hit-rate numerator against `prompt` (input + cacheRead + cacheWrite).
+   * Absent on older hosts / usage-less requests; zero is a real value.
+   */
+  cacheRead?: number;
   output?: number;
   /**
    * Turn-mode aggregate marker, set by the Client's aggregateByTurn (one bar
@@ -280,10 +255,7 @@ interface HeaderTool {
   schema?: unknown;
 }
 /**
- * One request-header epoch: the full system prompt and tool schemas in force
- * from this event's seq until the next epoch. Headers change rarely (the loop
- * only logs `request/header` on change), so this unit's pushes are rare and
- * carrying full content is cheap.
+ * One request-header epoch: the full system prompt and tool schemas in force from this event's seq until the next epoch.
  */
 interface HeaderRecord {
   seq: number;
@@ -307,11 +279,9 @@ interface ContextHeaders {
  * (not only when the raw step bound is), so the bounded state stays at the
  * newest ~`maxKeptTurns` turns deterministically as a live log grows.
  */
-/** The projection unit's persisted state (plain JSON, bounded see above). */
 interface TimelineState {
   /** Model-visible surface, newest last. */
   surface: SurfaceNode[];
-  /** Live per-category token sums over the surface. */
   sums: Record<Category, number>;
   systemTokens: number;
   toolsTokens: number;
@@ -351,7 +321,6 @@ interface TimelineState {
    * Absent until a v4-flash / v4-pro request reports usage.
    */
   cost?: SessionCostUsage;
-  /** Newest `gone` among archive entries dropped by the retention bounds. */
   archiveFloor?: number;
   /**
    * Tool callId → name, armed by `tool/call` and DELETED when its
@@ -608,14 +577,12 @@ declare class SessionProjectionRegistry extends Service {
 }
 //#endregion
 //#region src/host/headers.d.ts
-/** The unit's persisted state (plain JSON, bounded). */
 interface HeadersState {
   headers: HeaderRecord[];
 }
 //#endregion
 //#region src/host/index.d.ts
 declare const name = "dsh-context";
-/** Required services: the session-projection registry that drives the unit. */
 declare const inject: string[];
 declare function apply(ctx: Context, config: Config): void;
 //#endregion

package/lib/index.js

@@ -17,7 +17,6 @@ import { deriveEventMessage } from "@deepseek-ai/dsh-session";
 * only tune the fold's retention / presentation slice, so changing them never
 * requires a projection `stateVersion` bump.
 */
-/** Defaults — the exact bounds the fold used before they became configurable. */
 const DEFAULT_BOUNDS = {
 	maxRequestSteps: 1500,
 	maxKeptTurns: 300,
@@ -26,8 +25,8 @@ const DEFAULT_BOUNDS = {
 	maxArchiveNodes: 400
 };
 /**
-* The cordis `Config` validator: strict on keys, defaults on the schema fields.
-* Tolerates `undefined` (a patch row without a `config:` block — defaults win).
+* The cordis `Config` validator: strict on keys, defaults on the schema fields; tolerates `undefined` (a patch row without a `config:`
+* block — defaults win).
 */
 const Config = z.preprocess((v) => v ?? {}, z.object({
 	maxRequestSteps: z.number().int().min(1).default(DEFAULT_BOUNDS.maxRequestSteps),
@@ -36,7 +35,6 @@ const Config = z.preprocess((v) => v ?? {}, z.object({
 	maxNodes: z.number().int().min(1).default(DEFAULT_BOUNDS.maxNodes),
 	maxArchiveNodes: z.number().int().min(1).default(DEFAULT_BOUNDS.maxArchiveNodes)
 }).strict());
-/** Validate (and default) the entry config into concrete fold bounds. */
 function resolveBounds(config) {
 	return Config.parse(config ?? {});
 }
@@ -69,7 +67,6 @@ const MAX_WH_RATIO = 8;
 const MIN_PIXELS = 147456;
 const floorDiv = (a, b) => Math.floor(a / b);
 const ceilDiv = (a, b) => Math.floor((a + b - 1) / b);
-/** Token count of one patch grid (rows×cols) under the v4 layout rule. */
 function gridTokens(rows, cols) {
 	let n = rows * (cols + 1) + 2;
 	if (rows % 2 === 1) n += cols + 1;
@@ -151,10 +148,8 @@ function calcResizeInner(width, height) {
 	return safeResize(h, w, paddedHeight, paddedWidth);
 }
 /**
-* Estimate the tokens one image consumes in a DeepSeek vision request, from
-* its pixel dimensions. Returns null for non-positive/non-finite dimensions
-* or when the official iteration fails to converge — callers fall back to
-* the generic structural price.
+* Estimate the tokens one image consumes in a DeepSeek vision request from its pixel dimensions. Returns null for non-positive/non-finite
+* dimensions or when the official iteration fails to converge — callers fall back to the generic structural price.
 */
 function estimateImageTokens(width, height) {
 	if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return null;
@@ -188,7 +183,6 @@ function estimateImageTokens(width, height) {
 const CHARS_PER_TOKEN = 4;
 const BLOCK_OVERHEAD = 4;
 const ROLE_OVERHEAD = 4;
-/** Whole-array tool-schema price (the header's tools total). */
 function estimateToolsTotal(tools) {
 	return tools.length > 0 ? Math.ceil(JSON.stringify(tools).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD : 0;
 }
@@ -234,9 +228,8 @@ function estimateToolSchema(tool) {
 	return Math.ceil(JSON.stringify(tool).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
 }
 /**
-* Count image blocks in a message payload, recursing into nested content
-* (tool-result blocks carry their inner blocks) — feeds the stats board's
-* whole-session image-file cell.
+* Count image blocks in a message payload, recursing into nested content (tool-result blocks carry their inner blocks) — seeds each node's
+* `imgs`, which the stats board's image cell sums over the LIVE surface (compacted/pruned messages stop counting).
 */
 function imageCountOf(blocks) {
 	let count = 0;
@@ -312,12 +305,10 @@ const contextHeadersSchema = z.object({ headers: z.array(z.object({
 	tools: z.array(headerToolSchema)
 }).strict()) }).strict();
 /**
-* The persisted state and the wire view are the same shape here (the view
-* only shallow-copies each record), so one schema validates both under the
-* dsh 0.1.1-rc.1+ `stateSchema`/`wire` contract.
+* State and wire are the same shape (the view only shallow-copies each record), so one schema validates both under the dsh 0.1.1-rc.1+
+* `stateSchema`/`wire` contract.
 */
 const contextHeadersStateSchema = contextHeadersSchema;
-/** Fold one `request/header` payload into an epoch record (display-priced). */
 function recordOf(event) {
 	if (event.type !== "request/header") return null;
 	const rawHeader = event.data.header;
@@ -342,14 +333,9 @@ function recordOf(event) {
 	return record;
 }
 /**
-* The context-headers projection unit. Registered alongside the timeline
-* unit (host/index.ts); clients read it through `useProjection('contextHeaders')`
-* and degrade to tokens-only header sections when the key is absent.
-*
-* Dual-contract definition (see compat.ts): `schema`/`view` for
-* dsh <= 0.1.0-rc.8, `stateSchema`/`wire` for dsh >= 0.1.1-rc.1. Without
-* `wire`, the 0.1.1-rc.1+ registry treats the unit as host-only and the
-* Context browser's system/tools sections would degrade.
+* The context-headers projection unit; registered alongside the timeline unit (host/index.ts); clients read it through
+* `useProjection('contextHeaders')` and degrade to tokens-only header sections when the key is absent. Dual-contract definition (see
+* compat.ts).
 */
 function createContextHeadersDefinition() {
 	const view = (state) => ({ headers: state.headers.map((h) => ({
@@ -394,7 +380,6 @@ function installSettings(ctx) {
 }
 //#endregion
 //#region src/host/fold.ts
-/** Keep only the trailing `maxTurns` turn-runs of a request timeline. */
 function trimToLastTurns(requests, maxTurns) {
 	let runs = 0;
 	let start = requests.length;
@@ -410,7 +395,6 @@ function trimToLastTurns(requests, maxTurns) {
 	}
 	return requests.slice(start);
 }
-/** Distinct turn runs in a request timeline (consecutive equal-turn runs). */
 function countTurnRuns(requests) {
 	let runs = 0;
 	let prevTurn;
@@ -420,7 +404,6 @@ function countTurnRuns(requests) {
 	}
 	return runs;
 }
-/** Retain the newest tail of the two unbounded lists (bounded persisted state). */
 function trimState(st, bounds) {
 	if (countTurnRuns(st.requests) > bounds.maxKeptTurns) st.requests = trimToLastTurns(st.requests, bounds.maxKeptTurns);
 	if (st.requests.length > bounds.maxRequestSteps) st.requests = st.requests.slice(-bounds.maxRequestSteps);
@@ -767,6 +750,7 @@ function applyTimeline(state, event, bounds) {
 			if (data && typeof data.step === "number") record.step = data.step;
 			if (usage && typeof usage.inputTokens === "number") {
 				record.prompt = usage.inputTokens + (usage.cacheReadTokens || 0) + (usage.cacheWriteTokens || 0);
+				if (typeof usage.cacheReadTokens === "number") record.cacheRead = usage.cacheReadTokens;
 				if (typeof usage.outputTokens === "number") record.output = usage.outputTokens;
 				accumulateCost(s, event.time, usage);
 			}
@@ -808,10 +792,9 @@ function applyTimeline(state, event, bounds) {
 	return state;
 }
 /**
-* Build the wire snapshot served to the browser — the projection's `view()`.
-* Bounds the surface nodes (newest carry the signal), and attributes each
-* event to the request around it by stamping COPIES (the persisted state
-* objects are never mutated).
+* Serve the projection's wire view: bound the surface nodes to the newest tail and attach each event to the request around it; stamp
+* COPIES
+* — the persisted state objects are never mutated.
 */
 function buildTimelineView(state, bounds) {
 	const surfaceTotal = state.sums.user + state.sums.inject + state.sums.assistant + state.sums.tool;
@@ -936,6 +919,7 @@ const requestRecordSchema = z.object({
 	tool: z.number().int().nonnegative(),
 	total: z.number().int().nonnegative(),
 	prompt: z.number().int().nonnegative().optional(),
+	cacheRead: z.number().int().nonnegative().optional(),
 	output: z.number().int().nonnegative().optional(),
 	stepCount: z.number().int().positive().optional()
 }).strict();
@@ -1072,13 +1056,12 @@ function createContextTimelineDefinition(config) {
 		},
 		init: () => createTimelineState(),
 		apply: (state, event) => applyTimeline(state, event, bounds),
-		stateVersion: 8
+		stateVersion: 9
 	};
 }
 //#endregion
 //#region src/host/index.ts
 const name = "dsh-context";
-/** Required services: the session-projection registry that drives the unit. */
 const inject = ["sessionProjections"];
 function apply(ctx, config) {
 	ctx.sessionProjections.register(createContextTimelineDefinition(config));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-context",
-  "version": "0.29.0",
+  "version": "0.30.1",
   "description": "A DeepSeek Harness plugin for context insight and management, with context dashboard and context command, for understanding how the context is made of, and how it evolves.",
   "author": "bowenliang123",
   "repository": {