dsh-fast 0.1.2 → 0.2.0

package/src/estimate.ts

@@ -9,6 +9,7 @@
  */
 
 import type { EpochHeader } from '@deepseek-ai/dsh-session'
+import type { SystemPromptBreakdown } from './model.ts'
 
 /** Fixed text-density estimate (chars per token). */
 const CHARS_PER_TOKEN = 4
@@ -19,9 +20,60 @@ const ROLE_OVERHEAD = 4
 /** Per-block structural overhead for JSON framing and type tags. */
 const BLOCK_OVERHEAD = 4
 
+/** One named system-prompt section (name + resolved text). */
+export interface SystemSection {
+  name: string
+  text: string
+}
+
+/** Which tracked bucket a section name belongs to. */
+function bucketOf(name: string): 'agentsMd' | 'skills' | 'persona' | 'other' {
+  if (name === 'deployment:persona') return 'persona'
+  if (name.toLowerCase().includes('skill')) return 'skills'
+  if (/agent|instructions?/iu.test(name)) return 'agentsMd'
+  return 'other'
+}
+
+/** An empty breakdown (all buckets zeroed). */
+function emptyBreakdown(): SystemPromptBreakdown {
+  return {
+    agentsMd: { tokens: 0, chars: 0, share: 0 },
+    skills: { tokens: 0, chars: 0, share: 0 },
+    persona: { tokens: 0, chars: 0, share: 0 },
+    other: { tokens: 0, chars: 0, share: 0 },
+  }
+}
+
+/**
+ * Classify the named system-prompt sections into the AGENTS.md / skills /
+ * persona / other buckets, with heuristic tokens and per-bucket shares. The
+ * caller supplies either the real assembled sections (via the optional
+ * `systemPrompt` service) or a single synthetic `{ name: 'other' }` section
+ * carrying the rendered prompt, so the breakdown always sums to the system
+ * prompt.
+ * @param sections - named sections (never empty in practice).
+ * @returns the per-bucket breakdown.
+ */
+export function classifySystemSections(sections: readonly SystemSection[]): SystemPromptBreakdown {
+  const breakdown = emptyBreakdown()
+  for (const section of sections) {
+    const chars = section.text.length
+    if (chars === 0) continue
+    const bucket = breakdown[bucketOf(section.name)]
+    bucket.chars += chars
+    bucket.tokens += Math.ceil(chars / CHARS_PER_TOKEN)
+  }
+  const total = breakdown.agentsMd.tokens + breakdown.skills.tokens + breakdown.persona.tokens + breakdown.other.tokens
+  if (total <= 0) return breakdown
+  for (const bucket of [breakdown.agentsMd, breakdown.skills, breakdown.persona, breakdown.other] as const) {
+    bucket.share = bucket.tokens / total
+  }
+  return breakdown
+}
+
 /**
- * Price the assembled system prompt (AGENTS.md + skill directory + persona +
- * harness instructions).
+ * Price the assembled system prompt (harness identity + persona + tool
+ * guidance + plugin sections).
  * @param header - canonical request envelope, or undefined before any request.
  * @returns heuristic system-prompt tokens; 0 when absent.
  */

package/src/index.ts

@@ -21,6 +21,7 @@ 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 type { SystemSection } from './estimate.ts'
 import { buildReport, renderFastText } from './analyze.ts'
 import type { FastReport } from './model.ts'
 import { fastDomainSpec, appendSample } from './store.ts'
@@ -43,8 +44,11 @@ export type {
   ContextStats,
   CacheStats,
   StoredSample,
+  PromptBucket,
+  SystemPromptBreakdown,
 } from './model.ts'
 export { FastCollector, detectSpilledResult, flattenToolResultText, sharesOf, hitRateOf } from './collector.ts'
+export { classifySystemSections, type SystemSection } from './estimate.ts'
 export { buildReport, buildSuggestions, renderFastText } from './analyze.ts'
 export { fastDomainSpec, appendSample, historySchema } from './store.ts'
 
@@ -53,6 +57,11 @@ interface TokenMeterService {
   measure(session: Session): TokenMeasurement
 }
 
+/** The structural surface of the optional `ctx.systemPrompt` service (section assembly). */
+interface SystemPromptService {
+  assemble(): Promise<{ sections: readonly { name: string; text: string }[] }>
+}
+
 /**
  * Mount the diagnostics. The resolved config is validated first (fail loud);
  * with `enabled: false` the plugin registers nothing and stays inert.
@@ -84,9 +93,22 @@ export async function apply(ctx: Context, config: Config = {}): Promise<void> {
     }
   }
 
+  /** Assemble the named system-prompt sections for the per-section breakdown. */
+  const assembleSections = async (): Promise<readonly SystemSection[] | undefined> => {
+    const systemPrompt = ctx.get('systemPrompt') as unknown as SystemPromptService | undefined
+    if (systemPrompt === undefined) return undefined
+    try {
+      const assembly = await systemPrompt.assemble()
+      return assembly.sections.map(section => ({ name: section.name, text: section.text }))
+    } catch (error) {
+      logger.warn(`system-prompt section assembly 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)
+  const reportFor = async (session: Session): Promise<FastReport> => {
+    const snapshot = collector.snapshot(session, measure, await assembleSections())
     return buildReport(
       snapshot,
       {
@@ -100,8 +122,8 @@ export async function apply(ctx: Context, config: Config = {}): Promise<void> {
   }
 
   /** Append one snapshot to the session's durable history (fire-and-forget). */
-  const persist = (session: Session): void => {
-    const snapshot = collector.snapshot(session, measure)
+  const persist = async (session: Session): Promise<void> => {
+    const snapshot = collector.snapshot(session, measure, await assembleSections())
     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)}`)
@@ -112,8 +134,8 @@ export async function apply(ctx: Context, config: Config = {}): Promise<void> {
   ctx.commands.register({
     name: 'fast',
     description: 'Print the dsh-fast performance report for the active session.',
-    handler: (invocation) => {
-      const report = reportFor(invocation.agent.session)
+    async handler(invocation) {
+      const report = await reportFor(invocation.agent.session)
       return { kind: 'success', text: renderFastText(report) }
     },
   })
@@ -171,6 +193,17 @@ export async function apply(ctx: Context, config: Config = {}): Promise<void> {
               systemShare: { type: 'number', required: true },
               toolsShare: { type: 'number', required: true },
               surfaceShare: { type: 'number', required: true },
+              systemBreakdown: {
+                type: 'object',
+                properties: {
+                  agentsMd: { type: 'object', properties: { tokens: { type: 'number', required: true }, chars: { type: 'number', required: true }, share: { type: 'number', required: true } }, additionalProperties: false, required: true },
+                  skills: { type: 'object', properties: { tokens: { type: 'number', required: true }, chars: { type: 'number', required: true }, share: { type: 'number', required: true } }, additionalProperties: false, required: true },
+                  persona: { type: 'object', properties: { tokens: { type: 'number', required: true }, chars: { type: 'number', required: true }, share: { type: 'number', required: true } }, additionalProperties: false, required: true },
+                  other: { type: 'object', properties: { tokens: { type: 'number', required: true }, chars: { type: 'number', required: true }, share: { type: 'number', required: true } }, additionalProperties: false, required: true },
+                },
+                additionalProperties: false,
+                required: true,
+              },
             },
             additionalProperties: false,
             required: true,
@@ -199,7 +232,7 @@ export async function apply(ctx: Context, config: Config = {}): Promise<void> {
       if (session === undefined) {
         throw new Error('fast_report requires an agent-owned session')
       }
-      return reportFor(session)
+      return await reportFor(session)
     },
   }))
 
@@ -224,7 +257,7 @@ export async function apply(ctx: Context, config: Config = {}): Promise<void> {
       for (const session of collector.liveSessions()) {
         if (!collector.isDirty(session)) continue
         collector.markClean(session)
-        persist(session)
+        void persist(session)
       }
     }, resolved.snapshotIntervalMs)
     return async () => {

package/src/model.ts

@@ -44,11 +44,33 @@ export interface CompactionStats {
   shadowedTokens: number
 }
 
+/** One named bucket of the injected system prompt. */
+export interface PromptBucket {
+  /** Heuristic token estimate for this bucket (`ceil(chars / 4)`). */
+  tokens: number
+  /** Raw character count of the bucket's sections. */
+  chars: number
+  /** Fraction of the total system-prompt bucket tokens (0 when the total is 0). */
+  share: number
+}
+
+/** The system-prompt breakdown: AGENTS.md / skills / persona / other named sections. */
+export interface SystemPromptBreakdown {
+  /** Sections that carry agent instructions (AGENTS.md-style). */
+  agentsMd: PromptBucket
+  /** Sections that carry skill content. */
+  skills: PromptBucket
+  /** The `deployment:persona` section. */
+  persona: PromptBucket
+  /** Harness identity, tool guidance, and any unclassified sections. */
+  other: PromptBucket
+}
+
 /** 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. */
+  /** Assembled system-prompt tokens — harness identity, persona, tool guidance, and plugin sections. */
   systemTokens: number
   /** Tool-schema tokens. */
   toolSchemaTokens: number
@@ -60,6 +82,8 @@ export interface ContextStats {
   toolsShare: number
   /** `surfaceTokens / totalTokens` (0 when the total is 0). */
   surfaceShare: number
+  /** Per-section system-prompt breakdown (AGENTS.md / skills / persona / other). */
+  systemBreakdown: SystemPromptBreakdown
 }
 
 /** LLM cache accounting aggregated from `assistant/message` usage. */

package/src/store.ts

@@ -2,7 +2,7 @@
  * 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.8 `Session.append` offers no `ignorable` marker and no
+ * session log (the rc.2 `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
@@ -33,6 +33,21 @@ const compactionSchema = z.object({
   shadowedTokens: z.number().int().nonnegative(),
 })
 
+/** Zod schema for one prompt bucket. */
+const bucketSchema = z.object({
+  tokens: z.number().nonnegative(),
+  chars: z.number().nonnegative(),
+  share: z.number(),
+})
+
+/** Zod schema for the system-prompt breakdown. */
+const breakdownSchema = z.object({
+  agentsMd: bucketSchema,
+  skills: bucketSchema,
+  persona: bucketSchema,
+  other: bucketSchema,
+})
+
 /** Zod schema for the context section. */
 const contextSchema = z.object({
   totalTokens: z.number().nonnegative(),
@@ -42,6 +57,7 @@ const contextSchema = z.object({
   systemShare: z.number(),
   toolsShare: z.number(),
   surfaceShare: z.number(),
+  systemBreakdown: breakdownSchema,
 })
 
 /** Zod schema for the cache section. */

package/src/version.ts

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