dsh-fast 0.1.1

package/lib/types/analyze.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure report assembly: threshold-driven suggestions, the human-readable
+ * `/fast` text, and the final {@link FastReport}. Every function is pure of its
+ * inputs (no I/O, clock, random, or live-service access), so it is trivially
+ * unit-tested and safe to replay.
+ * @module dsh-fast/analyze
+ */
+import type { FastReport, FastSnapshot } from './model.ts';
+import type { ResolvedConfig } from './config.ts';
+/** Report metadata supplied by the caller (identity, optional cwd, time). */
+export interface ReportMeta {
+    sessionId: string;
+    cwd?: string;
+    generatedAt: number;
+}
+/**
+ * Build the optimization suggestions for a snapshot against the config
+ * thresholds. Suggestions are plain strings, one per distinct finding.
+ * @param snapshot - the metric snapshot.
+ * @param config - the resolved config (thresholds).
+ * @returns the ordered suggestions (may be empty).
+ */
+export declare function buildSuggestions(snapshot: FastSnapshot, config: ResolvedConfig): string[];
+/**
+ * Render a report as the human-readable `/fast` body.
+ * @param report - the assembled report.
+ * @returns the report text.
+ */
+export declare function renderFastText(report: FastReport): string;
+/**
+ * Assemble the final report from a snapshot plus caller metadata. Suggestions
+ * are computed here and the identity/cwd fields are sanitized before any model
+ * or durable surface sees them.
+ * @param snapshot - the metric snapshot.
+ * @param meta - session identity, optional cwd, and generation time.
+ * @param config - the resolved config (thresholds).
+ * @param version - the plugin version.
+ * @returns the complete report.
+ */
+export declare function buildReport(snapshot: FastSnapshot, meta: ReportMeta, config: ResolvedConfig, version: string): FastReport;
+//# sourceMappingURL=analyze.d.ts.map

package/lib/types/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/analyze.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAGjD,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,EAAE,CA4CzF;AAYD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAsCzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAUzH"}

package/lib/types/analyze.js

@@ -0,0 +1,121 @@
+/**
+ * Pure report assembly: threshold-driven suggestions, the human-readable
+ * `/fast` text, and the final {@link FastReport}. Every function is pure of its
+ * inputs (no I/O, clock, random, or live-service access), so it is trivially
+ * unit-tested and safe to replay.
+ * @module dsh-fast/analyze
+ */
+import { sanitizePath, sanitizeText } from "./sanitize.js";
+/**
+ * Build the optimization suggestions for a snapshot against the config
+ * thresholds. Suggestions are plain strings, one per distinct finding.
+ * @param snapshot - the metric snapshot.
+ * @param config - the resolved config (thresholds).
+ * @returns the ordered suggestions (may be empty).
+ */
+export function buildSuggestions(snapshot, config) {
+    const suggestions = [];
+    const t = config.thresholds;
+    const { context, compaction, cache, spill } = snapshot;
+    if (context.systemTokens > t.systemPromptTokens) {
+        suggestions.push(`System prompt is large (${context.systemTokens} tokens, threshold ${t.systemPromptTokens}); consider trimming AGENTS.md, the skill directory, or persona.`);
+    }
+    if (context.toolSchemaTokens > t.toolSchemaTokens) {
+        suggestions.push(`Tool schema is large (${context.toolSchemaTokens} tokens, threshold ${t.toolSchemaTokens}); consider mounting fewer tools or tightening parameter descriptions.`);
+    }
+    if (context.surfaceTokens > t.surfaceTokens) {
+        suggestions.push(`Session surface is large (${context.surfaceTokens} tokens, threshold ${t.surfaceTokens}); consider /compact or clearing old tool results.`);
+    }
+    if (compaction.count >= t.compactionCountWarn) {
+        suggestions.push(`This session has triggered ${compaction.count} compactions; context pressure is high — compact earlier or raise the compaction threshold.`);
+    }
+    if (compaction.count > 0) {
+        const average = compaction.shadowedTokens / compaction.count;
+        if (average > t.compactionShadowTokens) {
+            suggestions.push(`Average compaction shadows ${Math.round(average)} tokens (threshold ${t.compactionShadowTokens}); the compaction threshold may be too conservative.`);
+        }
+    }
+    if (cache.hitRate !== null && cache.hitRate < t.cacheHitRateFloor) {
+        suggestions.push(`LLM cache hit rate is only ${Math.round(cache.hitRate * 100)}% (threshold ${Math.round(t.cacheHitRateFloor * 100)}%); consider enabling or tuning prompt caching.`);
+    }
+    if (spill.detectedSpilledResults === 0 && context.surfaceTokens > t.surfaceTokens / 2) {
+        suggestions.push('Surface volume is high with no spill hits; if spill-policy is not enabled, consider enabling it to protect the context window.');
+    }
+    return suggestions;
+}
+/** Format one nullable millisecond duration. */
+function formatMs(value) {
+    return value === null ? 'n/a' : `${value} ms`;
+}
+/** Format one nullable ratio as a percentage. */
+function formatPercent(value) {
+    return value === null ? 'n/a' : `${Math.round(value * 100)}%`;
+}
+/**
+ * Render a report as the human-readable `/fast` body.
+ * @param report - the assembled report.
+ * @returns the report text.
+ */
+export function renderFastText(report) {
+    const { load, spill, compaction, context, cache } = report;
+    const lines = [
+        `dsh-fast ${report.version} — performance report`,
+        `session: ${report.sessionId}`,
+        '',
+        '## Session load',
+        `kind: ${load.kind}`,
+        `seed events: ${load.seedEvents}`,
+        `time to first request: ${formatMs(load.timeToFirstRequestMs)}`,
+        '',
+        '## Spill',
+        `detected spilled results: ${spill.detectedSpilledResults} (heuristic)`,
+        '',
+        '## Compaction',
+        `count: ${compaction.count} (manual: ${compaction.manual}, automatic: ${compaction.automatic})`,
+        `shadowed tokens: ${compaction.shadowedTokens}`,
+        '',
+        '## Context volume',
+        `total: ${context.totalTokens} tokens`,
+        `system (AGENTS.md/skills/persona): ${context.systemTokens} (${formatPercent(context.systemShare)})`,
+        `tool schema: ${context.toolSchemaTokens} (${formatPercent(context.toolsShare)})`,
+        `surface: ${context.surfaceTokens} (${formatPercent(context.surfaceShare)})`,
+        '',
+        '## LLM cache',
+        `input: ${cache.inputTokens}, cache read: ${cache.cacheReadTokens}, cache write: ${cache.cacheWriteTokens}, output: ${cache.outputTokens}`,
+        `hit rate: ${formatPercent(cache.hitRate)}`,
+    ];
+    if (report.cwd !== undefined) {
+        lines.splice(lines.length, 0, `cwd: ${report.cwd}`);
+    }
+    lines.push('', '## Suggestions');
+    if (report.suggestions.length === 0) {
+        lines.push('- none');
+    }
+    else {
+        for (const suggestion of report.suggestions)
+            lines.push(`- ${suggestion}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Assemble the final report from a snapshot plus caller metadata. Suggestions
+ * are computed here and the identity/cwd fields are sanitized before any model
+ * or durable surface sees them.
+ * @param snapshot - the metric snapshot.
+ * @param meta - session identity, optional cwd, and generation time.
+ * @param config - the resolved config (thresholds).
+ * @param version - the plugin version.
+ * @returns the complete report.
+ */
+export function buildReport(snapshot, meta, config, version) {
+    return {
+        ...snapshot,
+        generator: 'dsh-fast',
+        version,
+        sessionId: sanitizeText(meta.sessionId, 128),
+        generatedAt: meta.generatedAt,
+        suggestions: buildSuggestions(snapshot, config),
+        ...(meta.cwd === undefined ? {} : { cwd: sanitizePath(meta.cwd, 256) }),
+    };
+}
+//# sourceMappingURL=analyze.js.map

package/lib/types/analyze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.js","sourceRoot":"","sources":["../../src/analyze.ts"],"names":[],"mappings":"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"}

package/lib/types/collector.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The session/event collector: folds the durable session log into per-session
+ * counters and builds {@link FastSnapshot}s. All inline work is O(1) per event
+ * (increment counters, record the latest header) — the expensive context
+ * measurement is deferred to {@link snapshot}, which runs on the async
+ * sampling timer or on demand, never in the append hot path. State lives in a
+ * `Map` keyed by the live Session so the timer can iterate it.
+ * @module dsh-fast/collector
+ */
+import type { Session, SessionEvent, ToolResultMessage } from '@deepseek-ai/dsh-session';
+import type { FastSnapshot, ContextStats } from './model.ts';
+import type { ResolvedConfig } from './config.ts';
+/**
+ * The structural surface of the optional `ctx.tokenMeter` service. Only the
+ * fields dsh-fast reads are declared; the service is optional, so a host
+ * without it still reports system/tool-schema volumes (surface/total fall back
+ * to the header heuristic).
+ */
+export interface TokenMeasurement {
+    readonly totalTokens: number;
+    readonly surfaceTokens: number;
+}
+/** Lazy lookup of the optional token meter. */
+export type MeasureFn = (session: Session) => TokenMeasurement | undefined;
+/** Flatten a tool result's model-facing text blocks to one string. */
+export declare function flattenToolResultText(message: ToolResultMessage): string;
+/**
+ * Best-effort spill detection: a spilled tool result is one whose durable text
+ * carries the spill-policy notice (`Full … stored at: <locator>`). No dedicated
+ * session event exists, so this is a documented heuristic, not a hard signal.
+ * @param message - the tool result message.
+ * @returns true when the result looks spilled.
+ */
+export declare function detectSpilledResult(message: ToolResultMessage): boolean;
+/** Fraction of `total` each bucket represents (0 when the total is 0). */
+export declare function sharesOf(total: number, system: number, tools: number, surface: number): Pick<ContextStats, 'systemShare' | 'toolsShare' | 'surfaceShare'>;
+/** Cache hit rate from aggregate tokens: `cacheRead / (input + cacheRead)`. */
+export declare function hitRateOf(input: number, cacheRead: number): number | null;
+/**
+ * The event → snapshot collector over real Sessions. State is adopted lazily on
+ * the first event so an HMR reload (which does not replay `session/created`)
+ * still adopts existing live sessions.
+ */
+export declare class FastCollector {
+    private readonly config;
+    private readonly live;
+    /** @param config - the resolved plugin config. */
+    constructor(config: ResolvedConfig);
+    /** Adopt a session at its creation announcement. */
+    handleSessionCreated(session: Session): void;
+    /** Drop a session leaving the store. */
+    handleSessionDisposed(session: Session): void;
+    /**
+     * Fold one appended session event (O(1) per event).
+     * @param session - the session the event belongs to.
+     * @param event - the appended event.
+     */
+    handleEvent(session: Session, event: SessionEvent): void;
+    /** The live sessions the sampling timer iterates. */
+    liveSessions(): IterableIterator<Session>;
+    /** Whether a session is still live (adopted and not disposed). */
+    has(session: Session): boolean;
+    /** Whether a session has un-persisted changes. */
+    isDirty(session: Session): boolean;
+    /** Clear the dirty flag after a snapshot is appended. */
+    markClean(session: Session): void;
+    /**
+     * Build the current metric snapshot for one session. This is the only place
+     * the optional token meter is consulted, so it never runs in the append path.
+     * @param session - the session to snapshot.
+     * @param measure - optional token-meter measure function.
+     * @returns the snapshot.
+     */
+    snapshot(session: Session, measure?: MeasureFn): FastSnapshot;
+    /** Aggregate cache counters into the report shape. */
+    private cacheStats;
+    /** Fold one provider usage record. */
+    private foldUsage;
+    /** Adopt (or return the existing) live state for one session. */
+    private adopt;
+}
+//# sourceMappingURL=collector.d.ts.map

package/lib/types/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../src/collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAGxF,OAAO,KAAK,EAAE,YAAY,EAAc,YAAY,EAAE,MAAM,YAAY,CAAA;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAGjD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED,+CAA+C;AAC/C,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,gBAAgB,GAAG,SAAS,CAAA;AAK1E,sEAAsE;AACtE,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAQxE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAGvE;AAED,0EAA0E;AAC1E,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,IAAI,CAAC,YAAY,EAAE,aAAa,GAAG,YAAY,GAAG,cAAc,CAAC,CAOnE;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIzE;AAsBD;;;;GAIG;AACH,qBAAa,aAAa;IAIZ,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgC;IAErD,kDAAkD;gBACrB,MAAM,EAAE,cAAc;IAEnD,oDAAoD;IACpD,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI5C,wCAAwC;IACxC,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI7C;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI;IAmCxD,qDAAqD;IACrD,YAAY,IAAI,gBAAgB,CAAC,OAAO,CAAC;IAIzC,kEAAkE;IAClE,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAI9B,kDAAkD;IAClD,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAIlC,yDAAyD;IACzD,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAKjC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,SAAS,GAAG,YAAY;IAgC7D,sDAAsD;IACtD,OAAO,CAAC,UAAU;IAUlB,sCAAsC;IACtC,OAAO,CAAC,SAAS;IAYjB,iEAAiE;IACjE,OAAO,CAAC,KAAK;CAwBd"}

package/lib/types/collector.js

@@ -0,0 +1,236 @@
+/**
+ * The session/event collector: folds the durable session log into per-session
+ * counters and builds {@link FastSnapshot}s. All inline work is O(1) per event
+ * (increment counters, record the latest header) — the expensive context
+ * measurement is deferred to {@link snapshot}, which runs on the async
+ * sampling timer or on demand, never in the append hot path. State lives in a
+ * `Map` keyed by the live Session so the timer can iterate it.
+ * @module dsh-fast/collector
+ */
+import { estimateSystemTokens, estimateToolsTokens } from "./estimate.js";
+/** The durable marker every spill notice carries (`... Full ... stored at: <locator> ...`). */
+const SPILL_NOTICE_MARKERS = ['Full', 'stored at:'];
+/** Flatten a tool result's model-facing text blocks to one string. */
+export function flattenToolResultText(message) {
+    const block = message.content[0];
+    if (block === undefined)
+        return '';
+    let text = '';
+    for (const inner of block.content) {
+        if (inner.type === 'text')
+            text += inner.text;
+    }
+    return text;
+}
+/**
+ * Best-effort spill detection: a spilled tool result is one whose durable text
+ * carries the spill-policy notice (`Full … stored at: <locator>`). No dedicated
+ * session event exists, so this is a documented heuristic, not a hard signal.
+ * @param message - the tool result message.
+ * @returns true when the result looks spilled.
+ */
+export function detectSpilledResult(message) {
+    const text = flattenToolResultText(message);
+    return SPILL_NOTICE_MARKERS.every(marker => text.includes(marker));
+}
+/** Fraction of `total` each bucket represents (0 when the total is 0). */
+export function sharesOf(total, system, tools, surface) {
+    if (total <= 0)
+        return { systemShare: 0, toolsShare: 0, surfaceShare: 0 };
+    return {
+        systemShare: system / total,
+        toolsShare: tools / total,
+        surfaceShare: surface / total,
+    };
+}
+/** Cache hit rate from aggregate tokens: `cacheRead / (input + cacheRead)`. */
+export function hitRateOf(input, cacheRead) {
+    const denominator = input + cacheRead;
+    if (denominator <= 0)
+        return null;
+    return cacheRead / denominator;
+}
+/**
+ * The event → snapshot collector over real Sessions. State is adopted lazily on
+ * the first event so an HMR reload (which does not replay `session/created`)
+ * still adopts existing live sessions.
+ */
+export class FastCollector {
+    config;
+    live = new Map();
+    /** @param config - the resolved plugin config. */
+    constructor(config) {
+        this.config = config;
+    }
+    /** Adopt a session at its creation announcement. */
+    handleSessionCreated(session) {
+        this.adopt(session);
+    }
+    /** Drop a session leaving the store. */
+    handleSessionDisposed(session) {
+        this.live.delete(session);
+    }
+    /**
+     * Fold one appended session event (O(1) per event).
+     * @param session - the session the event belongs to.
+     * @param event - the appended event.
+     */
+    handleEvent(session, event) {
+        const state = this.adopt(session);
+        switch (event.type) {
+            case 'request/header':
+                state.lastHeader = event.data.header;
+                if (state.timeToFirstRequestMs === null) {
+                    state.timeToFirstRequestMs = Math.max(0, event.time - state.createdAtMs);
+                    state.dirty = true;
+                }
+                break;
+            case 'assistant/message':
+                this.foldUsage(state, event.data.usage);
+                break;
+            case 'compaction/start':
+                state.compactionCount += 1;
+                if (event.data.sourceCommandId === undefined)
+                    state.compactionAutomatic += 1;
+                else
+                    state.compactionManual += 1;
+                state.dirty = true;
+                break;
+            case 'compaction/summary':
+                state.compactionShadowedTokens += event.data.shadowedTokenCount;
+                state.dirty = true;
+                break;
+            case 'tool/result':
+                if (this.config.detectSpilledResults && detectSpilledResult(event.data.message)) {
+                    state.spilledResults += 1;
+                    state.dirty = true;
+                }
+                break;
+            default:
+                // Unknown or plugin-owned session events: nothing to fold.
+                break;
+        }
+    }
+    /** The live sessions the sampling timer iterates. */
+    liveSessions() {
+        return this.live.keys();
+    }
+    /** Whether a session is still live (adopted and not disposed). */
+    has(session) {
+        return this.live.has(session);
+    }
+    /** Whether a session has un-persisted changes. */
+    isDirty(session) {
+        return this.live.get(session)?.dirty ?? false;
+    }
+    /** Clear the dirty flag after a snapshot is appended. */
+    markClean(session) {
+        const state = this.live.get(session);
+        if (state !== undefined)
+            state.dirty = false;
+    }
+    /**
+     * Build the current metric snapshot for one session. This is the only place
+     * the optional token meter is consulted, so it never runs in the append path.
+     * @param session - the session to snapshot.
+     * @param measure - optional token-meter measure function.
+     * @returns the snapshot.
+     */
+    snapshot(session, measure) {
+        const state = this.live.get(session);
+        if (state === undefined)
+            return emptySnapshot();
+        const measurement = measure === undefined ? undefined : measure(session);
+        const systemTokens = estimateSystemTokens(state.lastHeader);
+        const toolSchemaTokens = estimateToolsTokens(state.lastHeader);
+        const surfaceTokens = measurement?.surfaceTokens ?? 0;
+        const totalTokens = measurement?.totalTokens ?? (systemTokens + toolSchemaTokens + surfaceTokens);
+        return {
+            load: {
+                kind: state.kind,
+                seedEvents: state.firstLiveSeq,
+                timeToFirstRequestMs: state.timeToFirstRequestMs,
+            },
+            spill: { detectedSpilledResults: state.spilledResults, heuristic: true },
+            compaction: {
+                count: state.compactionCount,
+                manual: state.compactionManual,
+                automatic: state.compactionAutomatic,
+                shadowedTokens: state.compactionShadowedTokens,
+            },
+            context: {
+                totalTokens,
+                systemTokens,
+                toolSchemaTokens,
+                surfaceTokens,
+                ...sharesOf(totalTokens, systemTokens, toolSchemaTokens, surfaceTokens),
+            },
+            cache: this.cacheStats(state),
+        };
+    }
+    /** Aggregate cache counters into the report shape. */
+    cacheStats(state) {
+        return {
+            inputTokens: state.inputTokens,
+            cacheReadTokens: state.cacheReadTokens,
+            cacheWriteTokens: state.cacheWriteTokens,
+            outputTokens: state.outputTokens,
+            hitRate: hitRateOf(state.inputTokens, state.cacheReadTokens),
+        };
+    }
+    /** Fold one provider usage record. */
+    foldUsage(state, usage) {
+        if (usage === undefined)
+            return;
+        state.inputTokens += usage.inputTokens;
+        state.outputTokens += usage.outputTokens;
+        state.cacheReadTokens += usage.cacheReadTokens ?? 0;
+        state.cacheWriteTokens += usage.cacheWriteTokens ?? 0;
+        state.dirty = true;
+    }
+    /** Adopt (or return the existing) live state for one session. */
+    adopt(session) {
+        const existing = this.live.get(session);
+        if (existing !== undefined)
+            return existing;
+        const state = {
+            session,
+            createdAtMs: Date.now(),
+            kind: session.firstLiveSeq > 0 ? 'restore' : 'open',
+            firstLiveSeq: session.firstLiveSeq,
+            timeToFirstRequestMs: null,
+            spilledResults: 0,
+            compactionCount: 0,
+            compactionManual: 0,
+            compactionAutomatic: 0,
+            compactionShadowedTokens: 0,
+            inputTokens: 0,
+            cacheReadTokens: 0,
+            cacheWriteTokens: 0,
+            outputTokens: 0,
+            lastHeader: undefined,
+            dirty: true,
+        };
+        this.live.set(session, state);
+        return state;
+    }
+}
+/** A zeroed snapshot for a session that is no longer live. */
+function emptySnapshot() {
+    return {
+        load: { kind: 'open', seedEvents: 0, timeToFirstRequestMs: null },
+        spill: { detectedSpilledResults: 0, heuristic: true },
+        compaction: { count: 0, manual: 0, automatic: 0, shadowedTokens: 0 },
+        context: {
+            totalTokens: 0,
+            systemTokens: 0,
+            toolSchemaTokens: 0,
+            surfaceTokens: 0,
+            systemShare: 0,
+            toolsShare: 0,
+            surfaceShare: 0,
+        },
+        cache: { inputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, outputTokens: 0, hitRate: null },
+    };
+}
+//# sourceMappingURL=collector.js.map

package/lib/types/collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.js","sourceRoot":"","sources":["../../src/collector.ts"],"names":[],"mappings":"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"}

package/lib/types/config.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Config schema and resolution for `dsh-fast`. Every tunable is a validated
+ * {@link Config} field changeable from cordis.yml; the resolution step
+ * validates numeric bounds so misconfiguration fails loud at mount. The plugin
+ * is read-only and safe, so it defaults to enabled — but `enabled: false`
+ * mounts nothing.
+ * @module dsh-fast/config
+ */
+import z from '@deepseek-ai/schemastery';
+/** Privacy switches for the report surfaces. */
+export interface PrivacyConfig {
+    /** Include the sanitized session working directory in `/fast` and `fast_report`. Off by default: a local path is sensitive. */
+    includeCwd?: boolean;
+}
+/** Async sampling policy (off the model path). */
+export interface SamplingConfig {
+    /** How often active sessions are sampled, in milliseconds. */
+    snapshotIntervalMs?: number;
+    /** How many samples to retain per session in the durable domain history. */
+    maxHistorySamples?: number;
+}
+/** Suggestion thresholds — the values that decide which optimization notes appear. */
+export interface ThresholdConfig {
+    /** Warn when assembled system-prompt tokens (AGENTS.md + skills + persona) exceed this. */
+    systemPromptTokens?: number;
+    /** Warn when tool-schema tokens exceed this. */
+    toolSchemaTokens?: number;
+    /** Warn when conversation-surface tokens exceed this. */
+    surfaceTokens?: number;
+    /** Warn when the LLM cache hit rate falls below this (0..1). */
+    cacheHitRateFloor?: number;
+    /** Warn once the session has triggered this many compactions. */
+    compactionCountWarn?: number;
+    /** Warn when the average shadowed token count per completed summary exceeds this. */
+    compactionShadowTokens?: number;
+}
+/** Spill-detection switch. */
+export interface SpillConfig {
+    /** Detect spilled tool results from the durable spill-notice marker. Best-effort; see README "Known limitations". */
+    detectSpilledResults?: boolean;
+}
+/** Raw plugin config — every field optional; {@link resolveConfig} supplies the defaults. */
+export interface Config {
+    /** Master switch. Off by default? No — diagnostics are read-only and safe, so on by default. */
+    enabled?: boolean;
+    privacy?: PrivacyConfig;
+    sampling?: SamplingConfig;
+    thresholds?: ThresholdConfig;
+    spill?: SpillConfig;
+}
+/** Fully resolved config handed to the runtime. */
+export interface ResolvedConfig {
+    readonly enabled: boolean;
+    readonly includeCwd: boolean;
+    readonly snapshotIntervalMs: number;
+    readonly maxHistorySamples: number;
+    readonly detectSpilledResults: boolean;
+    readonly thresholds: {
+        readonly systemPromptTokens: number;
+        readonly toolSchemaTokens: number;
+        readonly surfaceTokens: number;
+        readonly cacheHitRateFloor: number;
+        readonly compactionCountWarn: number;
+        readonly compactionShadowTokens: number;
+    };
+}
+/** Schemastery schema: the loader validates and fills defaults before `apply`. */
+export declare const Config: z<Config>;
+/**
+ * Validate raw values and fill explicit defaults. Invalid bounds throw here —
+ * misconfiguration fails loud at mount even without the Schemastery loader.
+ * @param config - raw (possibly partial) plugin config.
+ * @returns the fully resolved config.
+ */
+export declare function resolveConfig(config?: Config): ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,+HAA+H;IAC/H,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC9B,2FAA2F;IAC3F,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,qFAAqF;IACrF,sBAAsB,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,8BAA8B;AAC9B,MAAM,WAAW,WAAW;IAC1B,qHAAqH;IACrH,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B;AAED,6FAA6F;AAC7F,MAAM,WAAW,MAAM;IACrB,gGAAgG;IAChG,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,UAAU,CAAC,EAAE,eAAe,CAAA;IAC5B,KAAK,CAAC,EAAE,WAAW,CAAA;CACpB;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAA;IACtC,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;QACnC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;QACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;QAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;QAClC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;QACpC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAA;KACxC,CAAA;CACF;AAED,kFAAkF;AAClF,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CA2B3B,CAAA;AAgBF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,MAAW,GAAG,cAAc,CAsCjE"}