dsh-watcher 0.6.0 → 0.8.0

package/lib/dsh-watcher.js

@@ -1,7 +1,12 @@
 import { z } from "zod";
 import { createHash } from "node:crypto";
 //#region src/insights/engine.mjs
-/** Read-only DSH 0.1.7-rc.1 log fold. No prompt, reasoning or tool body is retained. */
+/** Read-only DSH 0.2.0-rc.2 log fold. No prompt, reasoning or tool body is retained. */
+const DAY_CAP = 400;
+const localDayKey = (ms) => {
+	const d = new Date(ms);
+	return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+};
 const record = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 const count = (v) => Number.isSafeInteger(v) && v >= 0;
 const elapsed = (start, end) => start === null ? 0 : Math.max(0, end - start);
@@ -31,7 +36,7 @@ function emptyStats() {
 }
 function initialState(header = {}, inherited = 0) {
 	return {
-		version: 1,
+		version: 2,
 		sessionId: String(header.id ?? ""),
 		skip: inherited,
 		seq: -1,
@@ -42,6 +47,7 @@ function initialState(header = {}, inherited = 0) {
 		},
 		totals: emptyStats(),
 		models: [],
+		days: [],
 		turn: null,
 		open: null,
 		tools: [],
@@ -112,6 +118,33 @@ function books(s, route = s.route) {
 		...s.turn ? [s.turn.stats] : []
 	];
 }
+function creditDay(s, time, route, u) {
+	const key = localDayKey(time);
+	let day = s.days.find((d) => d.key === key);
+	if (!day) {
+		day = {
+			key,
+			tokens: 0,
+			models: []
+		};
+		s.days.push(day);
+		s.days.sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+	}
+	day.tokens += u.tokens;
+	const effort = typeof route?.effort === "string" ? route.effort : null;
+	let row = day.models.find((m) => m.provider === route.provider && m.model === route.model && (m.effort ?? null) === effort);
+	if (!row) {
+		row = {
+			provider: route.provider,
+			model: route.model,
+			...effort ? { effort } : {},
+			tokens: 0
+		};
+		day.models.push(row);
+	}
+	row.tokens += u.tokens;
+	if (s.days.length > DAY_CAP) s.days = s.days.slice(s.days.length - DAY_CAP);
+}
 function begin(s, d, time, uncertain = false) {
 	s.open = {
 		turn: d.turn,
@@ -162,6 +195,7 @@ function settle(s, time, usage, source) {
 			}
 		}
 	}
+	if (u) creditDay(s, time, route, u);
 	s.open = null;
 }
 function applyChunk(open, chunk, time) {
@@ -368,6 +402,7 @@ function buildView(s) {
 		updatedAt: s.updatedAt,
 		totals: s.totals,
 		models: s.models,
+		days: s.days,
 		turn: s.turn,
 		pending: s.open ? {
 			turn: s.open.turn,
@@ -445,8 +480,19 @@ const pending = z.object({
 	reasoningLast: nullableTime,
 	lastContentAt: nullableTime
 }).nullable();
+const dayModels = z.array(z.object({
+	provider: z.string(),
+	model: z.string(),
+	effort: z.string().optional(),
+	tokens: number
+}));
+const days = z.array(z.object({
+	key: z.string(),
+	tokens: number,
+	models: dayModels
+}));
 const viewSchema = z.object({
-	version: z.literal(1),
+	version: z.literal(2),
 	sessionId: z.string(),
 	seq: z.number().int().min(-1),
 	updatedAt: z.number().finite(),
@@ -456,6 +502,7 @@ const viewSchema = z.object({
 		model: z.string(),
 		effort: z.string().optional()
 	})),
+	days,
 	turn,
 	pending,
 	findings: z.array(finding).max(30),
@@ -471,7 +518,7 @@ const usage = z.object({
 	exact: z.boolean()
 }).nullable();
 const stateSchema = z.object({
-	version: z.literal(1),
+	version: z.literal(2),
 	sessionId: z.string(),
 	skip: number,
 	seq: z.number().int().min(-1),
@@ -482,6 +529,7 @@ const stateSchema = z.object({
 		provider: z.string(),
 		model: z.string()
 	})),
+	days,
 	turn,
 	open: z.object({
 		turn: number,
@@ -516,7 +564,7 @@ const stateSchema = z.object({
 function installProjection(ctx) {
 	ctx.sessionProjections.register({
 		key: "watcherInsights",
-		stateVersion: 1,
+		stateVersion: 2,
 		stateSchema,
 		init: (header, inherited) => stateSchema.parse(initialState(header, inherited)),
 		apply: (state, event) => reduceEvent(state, event),

package/lib/types/client/Insights.d.ts

@@ -0,0 +1,18 @@
+import type { InsightsView } from '../insights/projection.ts';
+type Evidence = {
+    turn: number;
+    steps: number[];
+    seqs: number[];
+};
+export declare function SessionInsights({ value, now, running, waiting, onEvidence }: {
+    value: InsightsView | undefined;
+    now: number;
+    running: boolean;
+    waiting: boolean;
+    onEvidence: (e: Evidence) => void;
+}): import("react").JSX.Element | null;
+export declare function InsightsSettings(props: {
+    remote?: any;
+}): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=Insights.d.ts.map

package/lib/types/client/SidebarTab.d.ts

@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react';
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+/**
+ * Minimal structural description of the optional `dsh-better-sidebar` tab
+ * registration service (published as `ctx.betterSidebar`, see the peer's
+ * `client/service.d.ts`). Declared locally on purpose: this package must
+ * typecheck and build without the peer installed, so neither values nor types
+ * may be imported from it. Semantics mirrored here: `registerTab` takes one
+ * descriptor and returns a disposer that unregisters the tab type — hand it to
+ * `ctx.effect` so hot reload cannot register it twice.
+ */
+export interface WatcherSidebarDescriptor {
+    /** Unique tab type id; also the host tab's `type` value. */
+    id: string;
+    title: string;
+    /** Single-instance sugar: opening the tab focuses an existing one. */
+    single?: boolean;
+    /** + menu sort order (ascending); the host default is 100. */
+    order?: number;
+    component: (props: WatcherSidebarTabProps) => ReactNode;
+}
+/** The subset of the host's tab component props the Watcher page reads. */
+export interface WatcherSidebarTabProps {
+    ctx: ClientContext;
+    scope: {
+        sessionId: string;
+    };
+    /** Whether this tab is the active one AND the sidebar panel is open. */
+    visible: boolean;
+}
+/** Structural face of `ctx.betterSidebar` relevant to this plugin. */
+export interface BetterSidebarService {
+    registerTab?: (descriptor: WatcherSidebarDescriptor) => () => void;
+}
+/** Read the optional service off a context without importing the peer. */
+export declare function betterSidebarServiceOf(ctx: ClientContext): BetterSidebarService | undefined;
+/** The Watcher tab descriptor registered into dsh-better-sidebar. */
+export declare function watcherSidebarDescriptor(): WatcherSidebarDescriptor;
+/**
+ * The Better Sidebar tab body: the session-header overlay's work picture,
+ * ported onto `scope.sessionId` without the portal, the trigger, or the drag
+ * frame. Reads the same Session/Conversation stores through their binding
+ * faces; the cost/performance HUD and whole-history paging stay explicit (and
+ * `visible: false` never starts a load — only the button does).
+ */
+export declare function WatcherSidebarTab({ ctx, sessionId, visible }: {
+    ctx: ClientContext;
+    sessionId: SessionId;
+    visible: boolean;
+}): ReactNode;
+//# sourceMappingURL=SidebarTab.d.ts.map

package/lib/types/client/TimingPanel.d.ts

@@ -0,0 +1,7 @@
+import type { InsightsView } from '../insights/projection.ts';
+export declare function TimingPanel({ stats, scope, tokensPerSecond, }: {
+    stats: InsightsView['totals'];
+    scope: 'turn' | 'session';
+    tokensPerSecond?: number | null;
+}): import("react").JSX.Element;
+//# sourceMappingURL=TimingPanel.d.ts.map

package/lib/types/client/Watcher.d.ts

@@ -0,0 +1,56 @@
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { CompleteHistoryResult } from '../hub/history.ts';
+import { type WorkPicture, type WatcherSnapshot } from '../observation/fold.ts';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { InsightsView } from '../insights/projection.ts';
+import { type TurnPerformance } from '../observation/performance.ts';
+export interface WatcherInjected {
+    loadAllHistory: (signal: AbortSignal) => Promise<CompleteHistoryResult>;
+}
+export type WatcherProps = PropsRuntime<'conversation.session.header.utilities'> & WatcherInjected;
+/** Native session-header utility: exact work picture, typed evidence, no steering. */
+export declare function Watcher(props: WatcherProps): import("react").JSX.Element;
+/**
+ * Folds one Session snapshot into the work picture, merging observations that
+ * outlive the loaded window. Shared by the session-header overlay and the
+ * Better Sidebar tab so both surfaces read the same projection.
+ */
+export declare function useObservedPicture(sessionId: string, snapshot: WatcherSnapshot): {
+    picture: WorkPicture;
+    performanceByTurn: ReadonlyMap<number, TurnPerformance>;
+};
+export interface WorkPicturePanelProps {
+    /** Owning Session identity; changing it resets follow, selection, and history state. */
+    sessionId: SessionId;
+    /** Folded work picture from {@link useObservedPicture}. */
+    picture: WorkPicture;
+    performanceByTurn: ReadonlyMap<number, TurnPerformance>;
+    /** Whether older history pages remain on the Session. */
+    hasMore: boolean;
+    /** Whole-session projection totals, when the Host projection is available. */
+    stats: {
+        turns: number;
+        steps: number;
+    } | undefined;
+    /** Cost/performance HUD input; the header overlay always renders it. */
+    insights: InsightsView | undefined;
+    /** Never mount the cost/performance HUD (the sidebar tab omits it). */
+    hideInsights?: boolean;
+    /** Explicit whole-history loader; absent when no Session face is available. */
+    loadAllHistory?: (signal: AbortSignal) => Promise<CompleteHistoryResult>;
+    /** Gates the live clock: the overlay's open state, or the sidebar tab's visibility. */
+    live: boolean;
+    /** Overlay-only: freeze the floating panel frame across inspector transitions. */
+    onInspectorFrameChange?: () => void;
+    /** DOM id prefix for turn landmarks; coexisting surfaces must not share ids. */
+    domIdPrefix?: string;
+}
+/**
+ * The work picture itself: the docked inspector column plus the turns rail.
+ * Extracted from the session-header overlay so the Better Sidebar tab can
+ * render the same picture without the portal, the trigger, or the drag frame.
+ * Owns every picture-local concern (follow, disclosure, observation mode,
+ * history load, inspector lifecycle); positioning stays with the host.
+ */
+export declare function WorkPicturePanel({ sessionId, picture, performanceByTurn, hasMore, stats, insights, hideInsights, loadAllHistory, live, onInspectorFrameChange, domIdPrefix, }: WorkPicturePanelProps): import("react").JSX.Element;
+//# sourceMappingURL=Watcher.d.ts.map

package/lib/types/client/disclosure-depth.d.ts

@@ -0,0 +1,22 @@
+export type DisclosureDepth = 'overview' | 'detail';
+export type DisclosureLayer = 'phase' | 'step' | 'cluster' | 'model' | 'reasoning';
+type LayerOverrides = Readonly<Record<DisclosureLayer, Readonly<Record<string, boolean>>>>;
+export interface DisclosureState {
+    readonly depth: DisclosureDepth;
+    readonly turns: Readonly<Record<number, boolean>>;
+    readonly layers: LayerOverrides;
+}
+export declare function createDisclosureState(depth?: DisclosureDepth): DisclosureState;
+/** Overview keeps the automatic Turn policy; detail opens every Turn by default. */
+export declare function turnDisclosureOpen(state: DisclosureState, turn: number, overviewDefaultOpen: boolean): boolean;
+/** Overview stops at phase headers; detail opens every nested level by default. */
+export declare function layerDisclosureOpen(state: DisclosureState, layer: DisclosureLayer, key: string): boolean;
+export declare function setLayerDisclosure(state: DisclosureState, layer: DisclosureLayer, key: string, open: boolean): DisclosureState;
+export declare function toggleTurnDisclosure(state: DisclosureState, turn: number, overviewDefaultOpen: boolean): DisclosureState;
+export declare function toggleLayerDisclosure(state: DisclosureState, layer: DisclosureLayer, key: string): DisclosureState;
+/** Choosing a depth applies it immediately instead of inheriting stale manual folds. */
+export declare function chooseDisclosureDepth(depth: DisclosureDepth): DisclosureState;
+/** Session-specific ids may change, while the user's chosen depth remains useful. */
+export declare function resetDisclosureOverrides(state: DisclosureState): DisclosureState;
+export {};
+//# sourceMappingURL=disclosure-depth.d.ts.map

package/lib/types/client/history-loader.d.ts

@@ -0,0 +1,23 @@
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import { type CompleteHistoryResult } from '../hub/history.ts';
+/**
+ * The paging verbs the shared loader needs from one Session face. The
+ * session-header injection and the Better Sidebar tab both satisfy it from
+ * `sessions.binding(id).session`.
+ */
+export interface WatcherHistorySession {
+    loadOlder: () => Promise<void>;
+    getSnapshot: () => {
+        hasMore: boolean;
+        loadingOlder: boolean;
+    };
+}
+/**
+ * Build the explicit whole-history loader for one Session: repeat the
+ * Session's public, read-only paging verb until the head stops moving, using
+ * the same conversation head key the header overlay reports. Nothing starts
+ * it automatically — only a user action does.
+ */
+export declare function createCompleteHistoryLoader(ctx: ClientContext, sessionId: SessionId, session: WatcherHistorySession): (signal: AbortSignal) => Promise<CompleteHistoryResult>;
+//# sourceMappingURL=history-loader.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,9 @@
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+export declare const name = "dsh-watcher-client";
+export declare const inject: string[];
+/**
+ * Native session-header utility. Order 50 sits after Session log (0)
+ * and before the files-panel toggle (110). No overlay glyph.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/model-trace-definition.d.ts

@@ -0,0 +1,11 @@
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { type ModelStepTrace } from '../observation/model-trace.ts';
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+    interface ConversationStepDataMap {
+        /** Provider-exposed model activity retained for one Step. */
+        'dsh-watcher-model-stage': ModelStepTrace;
+    }
+}
+/** Register the Step-scoped, read-only model-stage projection. */
+export declare function registerModelTraceDefinition(ctx: ClientContext): void;
+//# sourceMappingURL=model-trace-definition.d.ts.map

package/lib/types/client/step-timeline.d.ts

@@ -0,0 +1,15 @@
+import type { WorkItem, WorkStep } from '../observation/fold.ts';
+import type { ModelStepTrace } from '../observation/model-trace.ts';
+type StepTimelineOccurrence = {
+    readonly kind: 'occurrence';
+    readonly item: WorkItem;
+    readonly occurrenceIndex: number;
+};
+export type StepTimelineEntry = StepTimelineOccurrence | {
+    readonly kind: 'model';
+    readonly trace: ModelStepTrace;
+};
+/** Compose the visible rows owned by one authoritative DSH Step. */
+export declare function stepTimelineEntries(step: Pick<WorkStep, 'items' | 'model'>): readonly StepTimelineEntry[];
+export {};
+//# sourceMappingURL=step-timeline.d.ts.map

package/lib/types/dsh-watcher.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "dsh-watcher";
+export declare const inject: string[];
+/** Host-owned replayable statistics; no new transport or model-facing writes. */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=dsh-watcher.d.ts.map

package/lib/types/hub/aggregation.d.ts

@@ -0,0 +1,40 @@
+import type { WorkItem, WorkStatus } from '../observation/fold.ts';
+export type WorkClusterBasis = 'mutable-target' | 'shared-target' | 'exact-call' | 'single';
+export interface WorkStatusCounts {
+    running: number;
+    waiting: number;
+    success: number;
+    failure: number;
+    returned: number;
+    interrupted: number;
+    unknown: number;
+}
+export type NonEmptyWorkItems = readonly [WorkItem, ...WorkItem[]];
+/** A reversible analysis projection. `items` always retains the source records. */
+export interface WorkCluster {
+    id: string;
+    basis: WorkClusterBasis;
+    title: string;
+    items: NonEmptyWorkItems;
+    executionCount: number;
+    stepCount: number;
+    retryCount: number;
+    iterationCount: number;
+    latestStatus: WorkStatus;
+    statusCounts: Readonly<WorkStatusCounts>;
+}
+/**
+ * Group one phase for analysis without changing evidence identity or order.
+ *
+ * - Mutable calls may group by operation + target so changed inputs remain
+ *   comparable as iterations.
+ * - Reads may group by one exact file target so different line windows stay
+ *   comparable.
+ * - Search, Glob, Grep, Bash, and every other tool require exact normalized
+ *   arguments. Sharing a cwd, broad path, tool name, or translated title is
+ *   never enough.
+ * - Messages and otherwise unsigned records remain singletons.
+ */
+export declare function clusterWorkItems(items: readonly WorkItem[]): readonly WorkCluster[];
+export declare function clusterOutcomeSummary(cluster: WorkCluster): string;
+//# sourceMappingURL=aggregation.d.ts.map

package/lib/types/hub/follow.d.ts

@@ -0,0 +1,29 @@
+import type { WorkPicture } from '../observation/fold.ts';
+export interface FollowSnapshot {
+    follow: boolean;
+    unread: number;
+    selectedId: string | null;
+}
+export interface RailScrollState {
+    atBottom: boolean;
+}
+/**
+ * Follow versus pin state for the work rail.
+ *
+ * The rail follows the newest recorded occurrence by default. Selecting
+ * history or scrolling away pins the viewport; later occurrences and result
+ * updates increment `unread` without yanking the reader away from evidence.
+ */
+export declare function createFollow(): {
+    snapshot: () => FollowSnapshot;
+    /** Counts appended occurrences or a settled live result while pinned. */
+    onPicture(picture: Pick<WorkPicture, "nodes">): FollowSnapshot;
+    onSelect(id: string): FollowSnapshot;
+    onScroll({ atBottom }: RailScrollState): FollowSnapshot;
+    setFollow(next: boolean): FollowSnapshot;
+    backToLatest(): FollowSnapshot;
+    /** Drop a pinned selection without re-arming follow: closing the inspector keeps the rail where the user left it. */
+    clearSelection(): FollowSnapshot;
+    reset(): FollowSnapshot;
+};
+//# sourceMappingURL=follow.d.ts.map

package/lib/types/hub/history.d.ts

@@ -0,0 +1,30 @@
+/** Minimal public facts needed to page one shared RC8 Session window. */
+export interface HistoryWindowState {
+    hasMore: boolean;
+    loadingOlder: boolean;
+    headKey: string;
+}
+export type CompleteHistoryResult = {
+    kind: 'complete';
+    pages: number;
+} | {
+    kind: 'cancelled';
+    pages: number;
+} | {
+    kind: 'blocked';
+    pages: number;
+    reason: 'busy' | 'no-progress' | 'page-limit';
+};
+export interface CompleteHistoryOptions {
+    read: () => HistoryWindowState;
+    loadOlder: () => Promise<void>;
+    signal: AbortSignal;
+    maxPages?: number;
+}
+/**
+ * Pull every older RC8 page in order. The Session remains the sole owner of
+ * history continuity; this helper only repeats its public, read-only paging
+ * verb and fails closed if one request does not advance the visible head.
+ */
+export declare function loadCompleteHistory({ read, loadOlder, signal, maxPages, }: CompleteHistoryOptions): Promise<CompleteHistoryResult>;
+//# sourceMappingURL=history.d.ts.map

package/lib/types/hub/overview.d.ts

@@ -0,0 +1,10 @@
+import type { WorkGroup, WorkStatus, WorkTurn } from '../observation/fold.ts';
+/** Overview progress is deliberately separate from execution evidence status. */
+export type OverviewState = 'active' | 'current' | 'waiting' | 'failure' | 'interrupted' | 'settled' | 'partial';
+export declare const OVERVIEW_STATE_LABEL: Readonly<Record<OverviewState, string>>;
+/** Project evidence status into the one question overview markers answer: where should the user look? */
+export declare function overviewStateOf(status: WorkStatus, isLatest: boolean): OverviewState;
+export declare function groupOverviewSummary(group: WorkGroup): string;
+export declare function turnOverviewSummary(turn: WorkTurn): string;
+export declare function turnNeedsDefaultDisclosure(state: OverviewState, isLatest: boolean): boolean;
+//# sourceMappingURL=overview.d.ts.map

package/lib/types/hub/watcher.d.ts

@@ -0,0 +1,4 @@
+/** Stable model entry for consumers that need Watcher's truthful work picture. */
+export { EMPTY_PICTURE, foldEvents, foldSnapshot, normalizedSignature, pairTools, parseJsonl, } from '../observation/fold.ts';
+export type { WorkGroup, WorkItem, WorkPhase, WorkPicture, WorkPresentation, WorkStatus, WorkStep, WorkTurn, } from '../observation/fold.ts';
+//# sourceMappingURL=watcher.d.ts.map