dsh-fast 0.1.1

package/src/index.ts

@@ -0,0 +1,235 @@
+/**
+ * `dsh-fast` — read-only performance diagnostics for DeepSeek Harness. Folds
+ * the `session/event` stream into session-load timing, spill-hit counts,
+ * compaction count and trigger, context-injection volume (AGENTS.md / skill
+ * directory / tool schema / surface token share), and LLM cache hit rate;
+ * surfaces them via the `/fast` slash command and the `fast_report` tool; and
+ * persists them to the harness storage domain on an async sampling timer
+ * (never on the append hot path).
+ *
+ * Function plugin — no default export (the Loader unwraps
+ * `exports.default ?? exports`, and a stray default would discard
+ * `name`/`inject`/`Config`/`apply`).
+ * @module dsh-fast
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+// Type-only: registers the `ctx.commands` Context merge for the inject.
+import type {} from '@deepseek-ai/dsh-commands'
+import { Config, resolveConfig } from './config.ts'
+import { FastCollector } from './collector.ts'
+import type { MeasureFn, TokenMeasurement } from './collector.ts'
+import { buildReport, renderFastText } from './analyze.ts'
+import type { FastReport } from './model.ts'
+import { fastDomainSpec, appendSample } from './store.ts'
+import { VERSION } from './version.ts'
+
+export const name = 'fast'
+/** The `/fast` command, the `fast_report` tool, and the durable metric domain. */
+export const inject = ['commands', 'tools', 'storageDomain']
+
+export { Config, resolveConfig } from './config.ts'
+export type { Config as FastConfig, ResolvedConfig } from './config.ts'
+export { VERSION } from './version.ts'
+export { stripControl, truncate, sanitizeText, sanitizePath } from './sanitize.ts'
+export type {
+  FastReport,
+  FastSnapshot,
+  LoadStats,
+  SpillStats,
+  CompactionStats,
+  ContextStats,
+  CacheStats,
+  StoredSample,
+} from './model.ts'
+export { FastCollector, detectSpilledResult, flattenToolResultText, sharesOf, hitRateOf } from './collector.ts'
+export { buildReport, buildSuggestions, renderFastText } from './analyze.ts'
+export { fastDomainSpec, appendSample, historySchema } from './store.ts'
+
+/** The structural surface of the optional `ctx.tokenMeter` service. */
+interface TokenMeterService {
+  measure(session: Session): TokenMeasurement
+}
+
+/**
+ * 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.
+ */
+export async function apply(ctx: Context, config: Config = {}): Promise<void> {
+  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: MeasureFn = (session) => {
+    const meter = ctx.get('tokenMeter') as unknown as TokenMeterService | undefined
+    if (meter === undefined) return undefined
+    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 undefined
+    }
+  }
+
+  /** Build the complete report for one session. */
+  const reportFor = (session: Session): FastReport => {
+    const snapshot = collector.snapshot(session, measure)
+    return buildReport(
+      snapshot,
+      {
+        sessionId: session.id,
+        ...(resolved.includeCwd && session.header.cwd !== undefined ? { cwd: session.header.cwd } : {}),
+        generatedAt: Date.now(),
+      },
+      resolved,
+      VERSION,
+    )
+  }
+
+  /** Append one snapshot to the session's durable history (fire-and-forget). */
+  const persist = (session: Session): void => {
+    const snapshot = collector.snapshot(session, measure)
+    const next = appendSample(sessions.get(session.id), { at: Date.now(), snapshot }, resolved.maxHistorySamples)
+    void sessions.put(session.id, next).catch((error: unknown) => {
+      logger.warn(`session "${session.id}": persist failed: ${error instanceof Error ? error.message : String(error)}`)
+    })
+  }
+
+  // Human slash command: the on-demand report.
+  ctx.commands.register({
+    name: 'fast',
+    description: 'Print the dsh-fast performance report for the active session.',
+    handler: (invocation) => {
+      const report = reportFor(invocation.agent.session)
+      return { kind: 'success', text: renderFastText(report) }
+    },
+  })
+
+  // Model tool: the same report as structured data.
+  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 as FastReport) }],
+    },
+    async execute(_args, exec) {
+      const session = exec.agent?.session
+      if (session === undefined) {
+        throw new Error('fast_report requires an agent-owned session')
+      }
+      return reportFor(session)
+    },
+  }))
+
+  // Session lifecycle: adopt and fold.
+  ctx.on('session/created', (session: Session) => {
+    collector.handleSessionCreated(session)
+  })
+  ctx.on('session/disposed', (session: Session) => {
+    collector.handleSessionDisposed(session)
+  })
+  ctx.on('session/event', (session: Session, event: SessionEvent) => {
+    try {
+      collector.handleEvent(session, event)
+    } catch (error) {
+      logger.warn(`session "${session.id}": event handling failed: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  })
+
+  // Async sampling: one effect owns the timer and the domain teardown.
+  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()
+    }
+  })
+}

package/src/model.ts

@@ -0,0 +1,98 @@
+/**
+ * Owned JSON data model shared by the `/fast` command, the `fast_report` tool,
+ * and the `fast/*` session events. Everything here is plain lossless-JSON data
+ * already detached from live harness objects, so a `FastSnapshot` is exactly
+ * what gets appended to the session log and a `FastReport` is exactly what the
+ * model-facing tool returns. No Cordis/Session reference crosses the tool or
+ * the session-log boundary.
+ * @module dsh-fast/model
+ */
+
+/** One session-load measurement: how a session became ready to serve. */
+export interface LoadStats {
+  /** `open` for a fresh session, `restore` for a resumed/seeded one. */
+  kind: 'open' | 'restore'
+  /** Number of restored/replayed seed events at construction (0 for a fresh open). */
+  seedEvents: number
+  /** Publication-to-first-request latency in milliseconds; `null` before the first request. */
+  timeToFirstRequestMs: number | null
+}
+
+/** One durable sample persisted to the storage domain, with its capture time. */
+export interface StoredSample {
+  at: number
+  snapshot: FastSnapshot
+}
+
+/** Spill-hit statistics derived from the durable tool results. */
+export interface SpillStats {
+  /** Tool results detected as spilled to a session-scoped artifact (best-effort heuristic). */
+  detectedSpilledResults: number
+  /** Always true: spill detection reads the durable notice marker, not a dedicated event. */
+  heuristic: boolean
+}
+
+/** Compaction count and trigger attribution over the durable log. */
+export interface CompactionStats {
+  /** Total compaction attempts (one `compaction/start` each). */
+  count: number
+  /** Compactions started by a slash command (`sourceCommandId` present). */
+  manual: number
+  /** Compactions started by automatic pressure (`sourceCommandId` absent). */
+  automatic: number
+  /** Sum of `shadowedTokenCount` across completed summaries. */
+  shadowedTokens: number
+}
+
+/** Context-injection volume: where the request context's tokens live. */
+export interface ContextStats {
+  /** Canonical current pressure (token-meter total), or the heuristic header+surface sum. */
+  totalTokens: number
+  /** Assembled system-prompt tokens — AGENTS.md, skill directory, persona, and harness instructions. */
+  systemTokens: number
+  /** Tool-schema tokens. */
+  toolSchemaTokens: number
+  /** Conversation-surface tokens (message history). */
+  surfaceTokens: number
+  /** `systemTokens / totalTokens` (0 when the total is 0). */
+  systemShare: number
+  /** `toolSchemaTokens / totalTokens` (0 when the total is 0). */
+  toolsShare: number
+  /** `surfaceTokens / totalTokens` (0 when the total is 0). */
+  surfaceShare: number
+}
+
+/** LLM cache accounting aggregated from `assistant/message` usage. */
+export interface CacheStats {
+  inputTokens: number
+  cacheReadTokens: number
+  cacheWriteTokens: number
+  outputTokens: number
+  /** `cacheRead / (input + cacheRead)`; `null` when no input-plus-cache-read tokens exist. */
+  hitRate: number | null
+}
+
+/** The complete metric snapshot persisted to the storage domain. */
+export interface FastSnapshot {
+  load: LoadStats
+  spill: SpillStats
+  compaction: CompactionStats
+  context: ContextStats
+  cache: CacheStats
+}
+
+/** The complete model- and human-facing report (`/fast` and `fast_report`). */
+export interface FastReport extends FastSnapshot {
+  /** `dsh-fast`. */
+  generator: string
+  /** Plugin version. */
+  version: string
+  /** Sanitized session identity. */
+  sessionId: string
+  /** Epoch milliseconds of report generation. */
+  generatedAt: number
+  /** Optimization suggestions, already localized to plain strings. */
+  suggestions: string[]
+  /** Sanitized session working directory; present only when `privacy.includeCwd` is enabled. */
+  cwd?: string
+}

package/src/sanitize.ts

@@ -0,0 +1,60 @@
+/**
+ * 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. */
+export function stripControl(value: string): string {
+  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.
+ */
+export function truncate(value: string, maxChars: number): string {
+  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.
+ */
+export function sanitizeText(value: string, maxChars: number): string {
+  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.
+ */
+export function sanitizePath(value: string, maxChars: number): string {
+  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)
+}

package/src/store.ts

@@ -0,0 +1,100 @@
+/**
+ * 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'
+import type { FastSnapshot, StoredSample } from './model.ts'
+
+/** 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 per-session history value type. */
+export interface HistoryValue {
+  samples: StoredSample[]
+}
+
+/** The `dsh-fast` storage-domain declaration. */
+export const fastDomainSpec = defineDomain({
+  name: 'dsh_fast',
+  version: 1,
+  tables: {
+    sessions: domainTable<string, HistoryValue>(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: HistoryValue | undefined, sample: StoredSample, maxSamples: number): HistoryValue {
+  const samples = [...(history?.samples ?? []), sample]
+  return { samples: samples.slice(-maxSamples) }
+}

package/src/version.ts

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