dsh-fast 0.1.1

package/lib/index.js

@@ -0,0 +1,844 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import z from "@deepseek-ai/schemastery";
+import z$1 from "zod";
+import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
+//#region src/config.ts
+/**
+* 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
+*/
+/** Schemastery schema: the loader validates and fills defaults before `apply`. */
+const Config = z.object({
+	enabled: z.boolean().default(true),
+	privacy: z.object({ includeCwd: z.boolean().default(false) }).default({ includeCwd: false }),
+	sampling: z.object({
+		snapshotIntervalMs: z.number().default(6e4),
+		maxHistorySamples: z.number().default(20)
+	}).default({
+		snapshotIntervalMs: 6e4,
+		maxHistorySamples: 20
+	}),
+	thresholds: z.object({
+		systemPromptTokens: z.number().default(2e4),
+		toolSchemaTokens: z.number().default(8e3),
+		surfaceTokens: z.number().default(6e4),
+		cacheHitRateFloor: z.number().default(.1),
+		compactionCountWarn: z.number().default(10),
+		compactionShadowTokens: z.number().default(4e4)
+	}).default({
+		systemPromptTokens: 2e4,
+		toolSchemaTokens: 8e3,
+		surfaceTokens: 6e4,
+		cacheHitRateFloor: .1,
+		compactionCountWarn: 10,
+		compactionShadowTokens: 4e4
+	}),
+	spill: z.object({ detectSpilledResults: z.boolean().default(true) }).default({ detectSpilledResults: true })
+});
+/** Throw unless `value` is a positive safe integer. */
+function assertPositiveInt(name, value) {
+	if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${name} must be a positive safe integer, got ${String(value)}`);
+}
+/** Throw unless `value` is a finite number in `[min, max]`. */
+function assertFiniteRange(name, value, min, max) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) throw new TypeError(`${name} must be a finite number in [${min}, ${max}], got ${String(value)}`);
+}
+/**
+* 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.
+*/
+function resolveConfig(config = {}) {
+	const samplingRaw = config.sampling ?? {};
+	const thresholdsRaw = config.thresholds ?? {};
+	const spillRaw = config.spill ?? {};
+	const snapshotIntervalMs = samplingRaw.snapshotIntervalMs ?? 6e4;
+	assertPositiveInt("sampling.snapshotIntervalMs", snapshotIntervalMs);
+	const maxHistorySamples = samplingRaw.maxHistorySamples ?? 20;
+	assertPositiveInt("sampling.maxHistorySamples", maxHistorySamples);
+	const systemPromptTokens = thresholdsRaw.systemPromptTokens ?? 2e4;
+	const toolSchemaTokens = thresholdsRaw.toolSchemaTokens ?? 8e3;
+	const surfaceTokens = thresholdsRaw.surfaceTokens ?? 6e4;
+	const cacheHitRateFloor = thresholdsRaw.cacheHitRateFloor ?? .1;
+	const compactionCountWarn = thresholdsRaw.compactionCountWarn ?? 10;
+	const compactionShadowTokens = thresholdsRaw.compactionShadowTokens ?? 4e4;
+	assertPositiveInt("thresholds.systemPromptTokens", systemPromptTokens);
+	assertPositiveInt("thresholds.toolSchemaTokens", toolSchemaTokens);
+	assertPositiveInt("thresholds.surfaceTokens", surfaceTokens);
+	assertFiniteRange("thresholds.cacheHitRateFloor", cacheHitRateFloor, 0, 1);
+	assertPositiveInt("thresholds.compactionCountWarn", compactionCountWarn);
+	assertPositiveInt("thresholds.compactionShadowTokens", compactionShadowTokens);
+	return {
+		enabled: config.enabled ?? true,
+		includeCwd: config.privacy?.includeCwd ?? false,
+		snapshotIntervalMs,
+		maxHistorySamples,
+		detectSpilledResults: spillRaw.detectSpilledResults ?? true,
+		thresholds: {
+			systemPromptTokens,
+			toolSchemaTokens,
+			surfaceTokens,
+			cacheHitRateFloor,
+			compactionCountWarn,
+			compactionShadowTokens
+		}
+	};
+}
+//#endregion
+//#region src/estimate.ts
+/** Fixed text-density estimate (chars per token). */
+const CHARS_PER_TOKEN = 4;
+/** Role-field framing overhead added to every priced message. */
+const ROLE_OVERHEAD = 4;
+/** Per-block structural overhead for JSON framing and type tags. */
+const BLOCK_OVERHEAD = 4;
+/**
+* Price the assembled system prompt (AGENTS.md + skill directory + persona +
+* harness instructions).
+* @param header - canonical request envelope, or undefined before any request.
+* @returns heuristic system-prompt tokens; 0 when absent.
+*/
+function estimateSystemTokens(header) {
+	if (header?.system === void 0) return 0;
+	return Math.ceil(header.system.length / CHARS_PER_TOKEN) + ROLE_OVERHEAD;
+}
+/**
+* Price the tool-schema part of the request envelope.
+* @param header - canonical request envelope, or undefined before any request.
+* @returns heuristic tool-schema tokens; 0 when absent or empty.
+*/
+function estimateToolsTokens(header) {
+	if (header?.tools === void 0 || header.tools.length === 0) return 0;
+	return Math.ceil(JSON.stringify(header.tools).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
+}
+//#endregion
+//#region src/collector.ts
+/** 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. */
+function flattenToolResultText(message) {
+	const block = message.content[0];
+	if (block === void 0) 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.
+*/
+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). */
+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)`. */
+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.
+*/
+var FastCollector = class {
+	config;
+	live = /* @__PURE__ */ 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 === void 0) 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;
+			}
+		}
+	}
+	/** 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 !== void 0) 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 === void 0) return emptySnapshot();
+		const measurement = measure === void 0 ? void 0 : 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 === void 0) 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 !== void 0) 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: void 0,
+			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
+		}
+	};
+}
+//#endregion
+//#region src/sanitize.ts
+/**
+* Pure display/durable-boundary sanitization. Any free-form string that can
+* reach a session event or a model-facing report (session identity, working
+* directory, labels) passes through these functions first, so control
+* characters never enter the log and no string exceeds its budget. These are
+* pure functions of their inputs.
+* @module dsh-fast/sanitize
+*/
+/** C0 control characters plus DEL, replaced before any output. */
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/gu;
+/** Ellipsis appended when a string is truncated. */
+const ELLIPSIS = "…";
+/** Remove control characters from a string. */
+function stripControl(value) {
+	return value.replace(CONTROL_CHARS, "");
+}
+/**
+* Truncate a string to `maxChars`, appending an ellipsis when it is cut.
+* @param value - the string to bound.
+* @param maxChars - non-negative budget; 0 yields the empty string.
+* @returns the bounded string.
+*/
+function truncate(value, maxChars) {
+	if (!Number.isSafeInteger(maxChars) || maxChars < 0) throw new TypeError(`maxChars must be a non-negative safe integer, got ${String(maxChars)}`);
+	if (value.length <= maxChars) return value;
+	if (maxChars === 0) return "";
+	return value.slice(0, maxChars) + ELLIPSIS;
+}
+/**
+* Sanitize a free-form label: strip control characters, then bound length.
+* @param value - the label (e.g. a session id).
+* @param maxChars - non-negative budget.
+* @returns the sanitized label.
+*/
+function sanitizeText(value, maxChars) {
+	return truncate(stripControl(value), maxChars);
+}
+/**
+* Sanitize a path or filename, preserving its tail (basename) when truncating
+* so the most diagnostic part survives. Control characters are stripped first.
+* @param value - the path or filename.
+* @param maxChars - non-negative budget.
+* @returns the sanitized path.
+*/
+function sanitizePath(value, maxChars) {
+	const clean = stripControl(value);
+	if (clean.length <= maxChars) return clean;
+	if (maxChars <= 1) return ELLIPSIS;
+	const head = Math.ceil(maxChars / 2);
+	const tail = Math.floor(maxChars / 2);
+	return clean.slice(0, head) + ELLIPSIS + clean.slice(-tail);
+}
+//#endregion
+//#region src/analyze.ts
+/**
+* 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).
+*/
+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.
+*/
+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 !== void 0) 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.
+*/
+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 === void 0 ? {} : { cwd: sanitizePath(meta.cwd, 256) }
+	};
+}
+//#endregion
+//#region src/store.ts
+/**
+* Durable metric storage over the harness storage domain. The `dsh-fast`
+* domain keeps one bounded history per session, so `/fast` and `fast_report`
+* metrics survive a restart and the trend stays queryable without touching the
+* session log (the rc.6 `Session.append` offers no `ignorable` marker and no
+* external event-registration surface, so a custom session event would make
+* the persistence coordinator refuse the log on restore).
+* @module dsh-fast/store
+*/
+/** Zod schema for the load section. */
+const loadSchema = z$1.object({
+	kind: z$1.enum(["open", "restore"]),
+	seedEvents: z$1.number().int().nonnegative(),
+	timeToFirstRequestMs: z$1.number().int().nonnegative().nullable()
+});
+/** Zod schema for the spill section. */
+const spillSchema = z$1.object({
+	detectedSpilledResults: z$1.number().int().nonnegative(),
+	heuristic: z$1.boolean()
+});
+/** Zod schema for the compaction section. */
+const compactionSchema = z$1.object({
+	count: z$1.number().int().nonnegative(),
+	manual: z$1.number().int().nonnegative(),
+	automatic: z$1.number().int().nonnegative(),
+	shadowedTokens: z$1.number().int().nonnegative()
+});
+/** Zod schema for the context section. */
+const contextSchema = z$1.object({
+	totalTokens: z$1.number().nonnegative(),
+	systemTokens: z$1.number().nonnegative(),
+	toolSchemaTokens: z$1.number().nonnegative(),
+	surfaceTokens: z$1.number().nonnegative(),
+	systemShare: z$1.number(),
+	toolsShare: z$1.number(),
+	surfaceShare: z$1.number()
+});
+/** Zod schema for the cache section. */
+const cacheSchema = z$1.object({
+	inputTokens: z$1.number().int().nonnegative(),
+	cacheReadTokens: z$1.number().int().nonnegative(),
+	cacheWriteTokens: z$1.number().int().nonnegative(),
+	outputTokens: z$1.number().int().nonnegative(),
+	hitRate: z$1.number().nullable()
+});
+/** Zod schema for one {@link FastSnapshot}. */
+const snapshotSchema = z$1.object({
+	load: loadSchema,
+	spill: spillSchema,
+	compaction: compactionSchema,
+	context: contextSchema,
+	cache: cacheSchema
+});
+/** Zod schema for one {@link StoredSample}. */
+const sampleSchema = z$1.object({
+	at: z$1.number().int().nonnegative(),
+	snapshot: snapshotSchema
+});
+/** The per-session value: a bounded history of samples. */
+const historySchema = z$1.object({ samples: z$1.array(sampleSchema) });
+/** The `dsh-fast` storage-domain declaration. */
+const fastDomainSpec = defineDomain({
+	name: "dsh_fast",
+	version: 1,
+	tables: { sessions: domainTable(historySchema) }
+});
+/**
+* Append one snapshot to a history, keeping only the newest `maxSamples`.
+* @param history - the current history (may be absent).
+* @param sample - the sample to append.
+* @param maxSamples - the bounded length.
+* @returns the new history.
+*/
+function appendSample(history, sample, maxSamples) {
+	return { samples: [...history?.samples ?? [], sample].slice(-maxSamples) };
+}
+//#endregion
+//#region src/version.ts
+/** Single-source plugin version, bumped by `scripts/release.mjs`. @module dsh-fast/version */
+const VERSION = "0.1.1";
+//#endregion
+//#region src/index.ts
+const name = "fast";
+/** The `/fast` command, the `fast_report` tool, and the durable metric domain. */
+const inject = [
+	"commands",
+	"tools",
+	"storageDomain"
+];
+/**
+* Mount the diagnostics. The resolved config is validated first (fail loud);
+* with `enabled: false` the plugin registers nothing and stays inert.
+* @param ctx - the plugin context (host).
+* @param config - raw plugin config.
+*/
+async function apply(ctx, config = {}) {
+	const resolved = resolveConfig(config);
+	const logger = ctx.logger("fast");
+	if (!resolved.enabled) {
+		logger.info("disabled: enabled is false — no diagnostics are collected");
+		return;
+	}
+	const collector = new FastCollector(resolved);
+	const domain = await ctx.storageDomain.open(fastDomainSpec);
+	const sessions = domain.table("sessions");
+	/** Lazy, contained lookup of the optional token meter. */
+	const measure = (session) => {
+		const meter = ctx.get("tokenMeter");
+		if (meter === void 0) return void 0;
+		try {
+			const measurement = meter.measure(session);
+			return {
+				totalTokens: measurement.totalTokens,
+				surfaceTokens: measurement.surfaceTokens
+			};
+		} catch (error) {
+			logger.warn(`token meter measurement failed: ${error instanceof Error ? error.message : String(error)}`);
+			return;
+		}
+	};
+	/** Build the complete report for one session. */
+	const reportFor = (session) => {
+		return buildReport(collector.snapshot(session, measure), {
+			sessionId: session.id,
+			...resolved.includeCwd && session.header.cwd !== void 0 ? { cwd: session.header.cwd } : {},
+			generatedAt: Date.now()
+		}, resolved, VERSION);
+	};
+	/** Append one snapshot to the session's durable history (fire-and-forget). */
+	const persist = (session) => {
+		const snapshot = collector.snapshot(session, measure);
+		const next = appendSample(sessions.get(session.id), {
+			at: Date.now(),
+			snapshot
+		}, resolved.maxHistorySamples);
+		sessions.put(session.id, next).catch((error) => {
+			logger.warn(`session "${session.id}": persist failed: ${error instanceof Error ? error.message : String(error)}`);
+		});
+	};
+	ctx.commands.register({
+		name: "fast",
+		description: "Print the dsh-fast performance report for the active session.",
+		handler: (invocation) => {
+			return {
+				kind: "success",
+				text: renderFastText(reportFor(invocation.agent.session))
+			};
+		}
+	});
+	ctx.tools.register(defineTool({
+		name: "fast_report",
+		description: "Return the current dsh-fast performance report for the active session: session load timing, spill hits, compaction count and trigger, context-injection volume (AGENTS.md/skills/tool-schema token share), LLM cache hit rate, and optimization suggestions.",
+		parameters: {},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					generator: {
+						type: "string",
+						required: true
+					},
+					version: {
+						type: "string",
+						required: true
+					},
+					sessionId: {
+						type: "string",
+						required: true
+					},
+					generatedAt: {
+						type: "number",
+						required: true
+					},
+					load: {
+						type: "object",
+						properties: {
+							kind: {
+								type: "string",
+								enum: ["open", "restore"],
+								required: true
+							},
+							seedEvents: {
+								type: "number",
+								required: true
+							},
+							timeToFirstRequestMs: {
+								oneOf: [{ type: "number" }, { type: "null" }],
+								required: true
+							}
+						},
+						additionalProperties: false,
+						required: true
+					},
+					spill: {
+						type: "object",
+						properties: {
+							detectedSpilledResults: {
+								type: "number",
+								required: true
+							},
+							heuristic: {
+								type: "boolean",
+								required: true
+							}
+						},
+						additionalProperties: false,
+						required: true
+					},
+					compaction: {
+						type: "object",
+						properties: {
+							count: {
+								type: "number",
+								required: true
+							},
+							manual: {
+								type: "number",
+								required: true
+							},
+							automatic: {
+								type: "number",
+								required: true
+							},
+							shadowedTokens: {
+								type: "number",
+								required: true
+							}
+						},
+						additionalProperties: false,
+						required: true
+					},
+					context: {
+						type: "object",
+						properties: {
+							totalTokens: {
+								type: "number",
+								required: true
+							},
+							systemTokens: {
+								type: "number",
+								required: true
+							},
+							toolSchemaTokens: {
+								type: "number",
+								required: true
+							},
+							surfaceTokens: {
+								type: "number",
+								required: true
+							},
+							systemShare: {
+								type: "number",
+								required: true
+							},
+							toolsShare: {
+								type: "number",
+								required: true
+							},
+							surfaceShare: {
+								type: "number",
+								required: true
+							}
+						},
+						additionalProperties: false,
+						required: true
+					},
+					cache: {
+						type: "object",
+						properties: {
+							inputTokens: {
+								type: "number",
+								required: true
+							},
+							cacheReadTokens: {
+								type: "number",
+								required: true
+							},
+							cacheWriteTokens: {
+								type: "number",
+								required: true
+							},
+							outputTokens: {
+								type: "number",
+								required: true
+							},
+							hitRate: {
+								oneOf: [{ type: "number" }, { type: "null" }],
+								required: true
+							}
+						},
+						additionalProperties: false,
+						required: true
+					},
+					suggestions: {
+						type: "array",
+						items: { type: "string" },
+						required: true
+					},
+					cwd: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderFastText(value)
+			}]
+		},
+		async execute(_args, exec) {
+			const session = exec.agent?.session;
+			if (session === void 0) throw new Error("fast_report requires an agent-owned session");
+			return reportFor(session);
+		}
+	}));
+	ctx.on("session/created", (session) => {
+		collector.handleSessionCreated(session);
+	});
+	ctx.on("session/disposed", (session) => {
+		collector.handleSessionDisposed(session);
+	});
+	ctx.on("session/event", (session, event) => {
+		try {
+			collector.handleEvent(session, event);
+		} catch (error) {
+			logger.warn(`session "${session.id}": event handling failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	});
+	ctx.effect(() => {
+		const timer = setInterval(() => {
+			for (const session of collector.liveSessions()) {
+				if (!collector.isDirty(session)) continue;
+				collector.markClean(session);
+				persist(session);
+			}
+		}, resolved.snapshotIntervalMs);
+		return async () => {
+			clearInterval(timer);
+			await domain.close();
+		};
+	});
+}
+//#endregion
+export { Config, FastCollector, VERSION, appendSample, apply, buildReport, buildSuggestions, detectSpilledResult, fastDomainSpec, flattenToolResultText, historySchema, hitRateOf, inject, name, renderFastText, resolveConfig, sanitizePath, sanitizeText, sharesOf, stripControl, truncate };