dsh-fast 0.1.1

package/lib/types/store.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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
+ */
+import z from 'zod';
+import type { StoredSample } from './model.ts';
+/** The per-session value: a bounded history of samples. */
+export declare const historySchema: z.ZodObject<{
+    samples: z.ZodArray<z.ZodObject<{
+        at: z.ZodNumber;
+        snapshot: z.ZodObject<{
+            load: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    open: "open";
+                    restore: "restore";
+                }>;
+                seedEvents: z.ZodNumber;
+                timeToFirstRequestMs: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>;
+            spill: z.ZodObject<{
+                detectedSpilledResults: z.ZodNumber;
+                heuristic: z.ZodBoolean;
+            }, z.core.$strip>;
+            compaction: z.ZodObject<{
+                count: z.ZodNumber;
+                manual: z.ZodNumber;
+                automatic: z.ZodNumber;
+                shadowedTokens: z.ZodNumber;
+            }, z.core.$strip>;
+            context: z.ZodObject<{
+                totalTokens: z.ZodNumber;
+                systemTokens: z.ZodNumber;
+                toolSchemaTokens: z.ZodNumber;
+                surfaceTokens: z.ZodNumber;
+                systemShare: z.ZodNumber;
+                toolsShare: z.ZodNumber;
+                surfaceShare: z.ZodNumber;
+            }, z.core.$strip>;
+            cache: z.ZodObject<{
+                inputTokens: z.ZodNumber;
+                cacheReadTokens: z.ZodNumber;
+                cacheWriteTokens: z.ZodNumber;
+                outputTokens: z.ZodNumber;
+                hitRate: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** The per-session history value type. */
+export interface HistoryValue {
+    samples: StoredSample[];
+}
+/** The `dsh-fast` storage-domain declaration. */
+export declare const fastDomainSpec: {
+    name: string;
+    version: number;
+    tables: {
+        sessions: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, HistoryValue>;
+    };
+};
+/**
+ * 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.
+ */
+export declare function appendSample(history: HistoryValue | undefined, sample: StoredSample, maxSamples: number): HistoryValue;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,CAAC,MAAM,KAAK,CAAA;AAEnB,OAAO,KAAK,EAAgB,YAAY,EAAE,MAAM,YAAY,CAAA;AA0D5D,2DAA2D;AAC3D,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAExB,CAAA;AAEF,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,YAAY,EAAE,CAAA;CACxB;AAED,iDAAiD;AACjD,eAAO,MAAM,cAAc;;;;;;CAMzB,CAAA;AAEF;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,CAGtH"}

package/lib/types/store.js

@@ -0,0 +1,84 @@
+/**
+ * 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
+ */
+import z from 'zod';
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
+/** Zod schema for the load section. */
+const loadSchema = z.object({
+    kind: z.enum(['open', 'restore']),
+    seedEvents: z.number().int().nonnegative(),
+    timeToFirstRequestMs: z.number().int().nonnegative().nullable(),
+});
+/** Zod schema for the spill section. */
+const spillSchema = z.object({
+    detectedSpilledResults: z.number().int().nonnegative(),
+    heuristic: z.boolean(),
+});
+/** Zod schema for the compaction section. */
+const compactionSchema = z.object({
+    count: z.number().int().nonnegative(),
+    manual: z.number().int().nonnegative(),
+    automatic: z.number().int().nonnegative(),
+    shadowedTokens: z.number().int().nonnegative(),
+});
+/** Zod schema for the context section. */
+const contextSchema = z.object({
+    totalTokens: z.number().nonnegative(),
+    systemTokens: z.number().nonnegative(),
+    toolSchemaTokens: z.number().nonnegative(),
+    surfaceTokens: z.number().nonnegative(),
+    systemShare: z.number(),
+    toolsShare: z.number(),
+    surfaceShare: z.number(),
+});
+/** Zod schema for the cache section. */
+const cacheSchema = z.object({
+    inputTokens: z.number().int().nonnegative(),
+    cacheReadTokens: z.number().int().nonnegative(),
+    cacheWriteTokens: z.number().int().nonnegative(),
+    outputTokens: z.number().int().nonnegative(),
+    hitRate: z.number().nullable(),
+});
+/** Zod schema for one {@link FastSnapshot}. */
+const snapshotSchema = z.object({
+    load: loadSchema,
+    spill: spillSchema,
+    compaction: compactionSchema,
+    context: contextSchema,
+    cache: cacheSchema,
+});
+/** Zod schema for one {@link StoredSample}. */
+const sampleSchema = z.object({
+    at: z.number().int().nonnegative(),
+    snapshot: snapshotSchema,
+});
+/** The per-session value: a bounded history of samples. */
+export const historySchema = z.object({
+    samples: z.array(sampleSchema),
+});
+/** The `dsh-fast` storage-domain declaration. */
+export 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.
+ */
+export function appendSample(history, sample, maxSamples) {
+    const samples = [...(history?.samples ?? []), sample];
+    return { samples: samples.slice(-maxSamples) };
+}
+//# sourceMappingURL=store.js.map

package/lib/types/store.js.map

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

package/lib/types/version.d.ts

@@ -0,0 +1,3 @@
+/** Single-source plugin version, bumped by `scripts/release.mjs`. @module dsh-fast/version */
+export declare const VERSION = "0.1.1";
+//# sourceMappingURL=version.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,eAAO,MAAM,OAAO,UAAU,CAAA"}

package/lib/types/version.js

@@ -0,0 +1,3 @@
+/** Single-source plugin version, bumped by `scripts/release.mjs`. @module dsh-fast/version */
+export const VERSION = '0.1.1';
+//# sourceMappingURL=version.js.map

package/lib/types/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAA"}

package/package.json

@@ -0,0 +1,147 @@
+{
+  "name": "dsh-fast",
+  "version": "0.1.1",
+  "description": "Read-only performance diagnostics for DeepSeek Harness: session load (open/restore) timing, spill-hit counts, compaction count and trigger, context-injection volume (AGENTS.md/skills/tool-schema token share), and LLM cache hit rate — surfaced via the /fast command and the fast_report tool, persisted as reconstructable fast/* session events with async sampling off the model path.",
+  "author": "dsh-fast contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PerryLink/dsh-fast.git"
+  },
+  "homepage": "https://github.com/PerryLink/dsh-fast#readme",
+  "bugs": {
+    "url": "https://github.com/PerryLink/dsh-fast/issues"
+  },
+  "private": false,
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md",
+    "README.md",
+    "README.zh.md",
+    "README.es.md",
+    "README.pt.md",
+    "README.hi.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dshWorkshop": {
+    "schema": "omdsh-workshop-package/v1",
+    "type": "plugin",
+    "integration": {
+      "protocol": "harness-profile",
+      "artifact": "cordis.patch.yml"
+    },
+    "install": {
+      "mode": "transactional",
+      "adapter": "profile-bundle",
+      "failurePolicy": "generation-rollback",
+      "touchesCurrentBeforeActivation": false
+    },
+    "lifecycle": {
+      "activation": "restart-profile",
+      "dispose": "supported"
+    },
+    "permissions": [
+      "session:read",
+      "session:write",
+      "native-code:none"
+    ],
+    "compatibility": {
+      "dshVersions": [
+        "0.1.0-rc.6"
+      ]
+    },
+    "capability": {
+      "id": "fast",
+      "kind": "diagnostics",
+      "invocation": "mount the dsh-fast bundle row",
+      "expected": "observes session events read-only, persists fast/* metrics, and serves /fast plus the fast_report tool"
+    },
+    "evidence": {
+      "install": null,
+      "failureIsolation": null,
+      "hotReload": null,
+      "remove": null
+    }
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "deepseek",
+    "cordis",
+    "performance",
+    "diagnostics",
+    "profiling",
+    "context-engineering",
+    "llm-cache"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "packageManager": "pnpm@11.7.0",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "^3.18.0",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-commands": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-compaction": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage-json": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage-domain": "0.1.0-rc.6"
+  },
+  "dependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "^3.18.0",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-commands": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-system-prompt": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-token-meter": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-compaction": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage-domain": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage-json": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
+    "@types/node": "^22.19.0",
+    "@vitest/coverage-v8": "^3.2.0",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "node scripts/prepare.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "typecheck:ci": "tsc -p tsconfig.ci.json --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "node scripts/prepare.mjs",
+    "verify:self-contained": "node scripts/verify-self-contained.mjs",
+    "verify:artifacts": "node scripts/verify-artifacts.mjs",
+    "verify:readme-sync": "node scripts/check-readme-sync.mjs",
+    "pack:check": "node scripts/prepare.mjs && pnpm pack"
+  },
+  "license": "Apache-2.0"
+}

package/src/analyze.ts

@@ -0,0 +1,148 @@
+/**
+ * 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'
+import { sanitizePath, sanitizeText } from './sanitize.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 function buildSuggestions(snapshot: FastSnapshot, config: ResolvedConfig): string[] {
+  const suggestions: string[] = []
+  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: number | null): string {
+  return value === null ? 'n/a' : `${value} ms`
+}
+
+/** Format one nullable ratio as a percentage. */
+function formatPercent(value: number | null): string {
+  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: FastReport): string {
+  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: FastSnapshot, meta: ReportMeta, config: ResolvedConfig, version: string): FastReport {
+  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) }),
+  }
+}