dsh-tacit 0.2.2 → 0.3.0

package/lib/schema.js

@@ -21,6 +21,16 @@ export const COACH_MODELS = ['deepseek-v4-flash', 'deepseek-v4-pro']
  */
 export const COACH_PROVIDER = 'deepseek-official'
 
+/**
+ * The model-call failure codes Tacit is allowed to put on the wire. The client
+ * renders `err.<code>` for whatever the envelope carries, so a raw provider
+ * code (`RATE_LIMIT`, `ERROR`, `ABORTED`, …) would surface as a literal
+ * `err.ABORTED` banner — `coachErrorCode` (`lib/service.js`) maps anything
+ * outside this list onto one of these. Every entry has an `err.*` key in both
+ * dictionaries (`client/src/10-i18n.js`, test-enforced).
+ */
+export const COACH_ERROR_CODES = ['no-llm', 'no-api-key', 'rate-limited', 'timeout', 'empty-response', 'call-failed']
+
 /**
  * The loader-facing plugin config. Wrapped in `z.preprocess` so a patch row
  * without a `config:` block (`undefined`) resolves to all defaults — a bare
@@ -59,6 +69,16 @@ export const Config = z.preprocess((v) => v ?? {}, z.object({
   directiveTrialTurns: z.number().default(10),
   /** A candidate retires when the messy-turn rate during its trial exceeds the baseline by more than this. */
   directiveWorseBy: z.number().default(0.15),
+  /** Bootstrap analyses run at once (1 = one after another; same calls, less waiting). */
+  bootstrapConcurrency: z.number().default(1),
+  /** Also learn from a clean turn that follows a messy one (what the user included the second time). Automatic, capped. */
+  learnFromGood: z.boolean().default(true),
+  /** Days of detailed usage-ledger day files kept before they expire (7-365, clamped in mergeConfig). */
+  costHistoryDays: z.number().default(30),
+  /** Daily USD spend that triggers the warn/exceeded cost UI; 0 disables (clamped in mergeConfig). */
+  costWarnDailyUsd: z.number().default(0),
+  /** Same as `costWarnDailyUsd`, over a calendar month; 0 disables (clamped in mergeConfig). */
+  costWarnMonthlyUsd: z.number().default(0),
 }))
 
 /**
@@ -82,6 +102,11 @@ const configPatchSchema = z.object({
   enrichPrompts: z.boolean().optional(),
   directiveTrialTurns: z.number().optional(),
   directiveWorseBy: z.number().optional(),
+  bootstrapConcurrency: z.number().optional(),
+  learnFromGood: z.boolean().optional(),
+  costHistoryDays: z.number().optional(),
+  costWarnDailyUsd: z.number().optional(),
+  costWarnMonthlyUsd: z.number().optional(),
 })
 
 // ── Trajectory projection ──────────────────────────────────────────────────
@@ -160,6 +185,12 @@ export const reportSchema = z.object({
   trigger: z.string().default('manual'),
   /** The user's next message when it triggered the analysis (clipped). */
   followUp: z.string().optional(),
+  /** Absolute workspace directory of the conversation, when the harness knew it. */
+  cwd: z.string().optional(),
+  /** trigger 'good' only: what the clean prompt supplied that the messy one before it lacked. */
+  strengths: z.array(z.object({ kind: z.string(), what: z.string() })).optional(),
+  /** trigger 'good' only: the one-sentence lesson fed to the distiller. */
+  lesson: z.string().optional(),
 })
 
 /**
@@ -178,6 +209,8 @@ export const patternCountersSchema = z.object({
   verified: z.number().int().default(0),
   /** Times the next turn's outcome was same/worse than the baseline. */
   unverified: z.number().int().default(0),
+  /** Times a clean prompt right after a messy turn showed the user supplying this themselves. */
+  resolved: z.number().int().default(0),
 })
 
 /** One distilled durable style rule (from rejected-improvement reasons). */
@@ -219,6 +252,8 @@ const directiveSchema = z.object({
   status: z.enum(['candidate', 'active', 'retired']).default('active'),
   trial: directiveTrialSchema.optional(),
   retiredReason: z.string().optional(),
+  /** Absolute workspace directory this directive is limited to; absent = every conversation. */
+  workspace: z.string().optional(),
 })
 
 /** The persistent user-wide mistake profile. */
@@ -257,7 +292,7 @@ export const statsArgSchema = z.object({
 
 export const directivesArgSchema = z.discriminatedUnion('action', [
   z.object({ action: z.literal('toggle'), id: z.string().min(1).max(64), enabled: z.boolean() }),
-  z.object({ action: z.literal('add'), text: z.string().min(1).max(300) }),
+  z.object({ action: z.literal('add'), text: z.string().min(1).max(300), workspace: z.string().max(1000).optional() }),
   z.object({ action: z.literal('remove'), id: z.string().min(1).max(64) }),
 ])
 
@@ -272,6 +307,12 @@ export const analyzeArgSchema = z.object({
   turn: z.number().int().min(1),
 })
 
+/** `/api/tacit/analyze-batch`: one session, up to 50 turns analyzed under a single run. */
+export const analyzeBatchArgSchema = z.object({
+  sessionId: z.string().min(1).max(200),
+  turns: z.array(z.number().int().min(1)).min(1).max(50),
+})
+
 export const improveArgSchema = z.object({
   sessionId: z.string().min(1).max(200),
   draft: z.string().min(1).max(100000),
@@ -292,3 +333,148 @@ export const appliedArgSchema = z.object({
 export const configArgSchema = z.object({
   patch: configPatchSchema,
 })
+
+// ── Usage ledger (content-free: no prompts, no responses, no tool args) ────
+
+/** Every op a metered model call can be tagged with (Task 1's sink + the distillation/enrichment calls). */
+export const USAGE_OPS = [
+  'analysis',
+  'analysis-repair',
+  'directive-distillation',
+  'style-distillation',
+  'improve',
+  'improve-repair',
+  'enrichment',
+]
+
+/** Every kind of run the tracker groups attempts into. */
+export const USAGE_RUN_TYPES = [
+  'bootstrap',
+  'analysis',
+  'analysis-batch',
+  'improve',
+  'directive-distillation',
+  'style-distillation',
+  'prompt-enrichment',
+]
+
+/** Raw token counts, zero-filled so totals can be summed without null checks. */
+export const tokenBucketsSchema = z.object({
+  inputTokens: z.number().default(0),
+  outputTokens: z.number().default(0),
+  cacheReadTokens: z.number().default(0),
+  cacheWriteTokens: z.number().default(0),
+  reasoningTokens: z.number().default(0),
+})
+
+/**
+ * One metered model call. Mirrors the sink record `callCoachModel` hands the
+ * tracker (`startedAt`..`usage`) plus the identity fields the tracker itself
+ * assigns (`id`, `op`, `sessionId`, `turn`) and the priced result. Never
+ * carries prompt/response text, tool args, or API keys.
+ */
+export const usageAttemptSchema = z.object({
+  id: z.string(),
+  op: z.enum(USAGE_OPS),
+  startedAt: z.number(),
+  durationMs: z.number().default(0),
+  model: z.string().default(''),
+  provider: z.string().default(''),
+  reasoningEffort: z.string().nullable().default(null),
+  finish: z.string().default(''),
+  status: z.enum(['ok', 'failed', 'unmetered']),
+  code: z.string().default(''),
+  sessionId: z.string().default(''),
+  turn: z.number().nullable().default(null),
+  usage: tokenBucketsSchema.nullable().default(null),
+  /** null when no price table matched the route/model (e.g. a proxy provider). */
+  priced: z.object({
+    source: z.enum(['bundled', 'costMeter']),
+    tier: z.string(),
+    rates: z.object({ cacheHit: z.number(), cacheMiss: z.number(), output: z.number() }),
+    asOf: z.string(),
+    usd: z.number(),
+  }).nullable().default(null),
+})
+
+/**
+ * A precomputed, already-defaulted instance of a nested object schema.
+ * zod's `.default(value)` injects `value` verbatim when a field is absent —
+ * it does NOT re-run `value` through the schema — so a literal `{}` default
+ * on a nested object would skip that object's own field defaults. Passing
+ * `schema.parse({})` instead gives the same "all defaults" shape correctly.
+ */
+const emptyTokenBuckets = tokenBucketsSchema.parse({})
+
+/** Aggregate counters shared by a run's totals, the lifetime summary, and every summary bucket. */
+export const usageTotalsSchema = z.object({
+  attempts: z.number().default(0),
+  billedCalls: z.number().default(0),
+  unmeteredCalls: z.number().default(0),
+  unpricedCalls: z.number().default(0),
+  tokens: tokenBucketsSchema.default(emptyTokenBuckets),
+  usdKnown: z.number().default(0),
+})
+
+const emptyUsageTotals = usageTotalsSchema.parse({})
+
+/** One tracker run: a group of attempts sharing a trigger (a single call, an auto-analysis, a bootstrap batch, ...). */
+export const usageRunSchema = z.object({
+  runId: z.string(),
+  type: z.enum(USAGE_RUN_TYPES),
+  trigger: z.string().default(''),
+  startedAt: z.number(),
+  endedAt: z.number().default(0),
+  status: z.enum(['running', 'success', 'partial', 'failed']).default('running'),
+  sessionId: z.string().default(''),
+  turn: z.number().nullable().default(null),
+  workspace: z.string().default(''),
+  model: z.string().default(''),
+  provider: z.string().default(''),
+  results: z.record(z.number()).default({}),
+  attempts: z.array(usageAttemptSchema).default([]),
+  totals: usageTotalsSchema.default(emptyUsageTotals),
+})
+
+/** One day's `usage/YYYY-MM-DD.json` file. */
+export const usageDayFileSchema = z.object({
+  version: z.literal(1),
+  day: z.string(),
+  runs: z.array(usageRunSchema).default([]),
+})
+
+const usageDayTotalsSchema = usageTotalsSchema.extend({
+  byType: z.record(usageTotalsSchema).default({}),
+})
+
+/** `usage/summary.json`: rolling totals kept alongside the day files so reports never have to re-scan every day. */
+export const usageSummarySchema = z.object({
+  version: z.literal(1),
+  trackingSince: z.number(),
+  lifetime: usageTotalsSchema.default(emptyUsageTotals),
+  byType: z.record(usageTotalsSchema).default({}),
+  byModel: z.record(usageTotalsSchema).default({}),
+  days: z.record(usageDayTotalsSchema).default({}),
+})
+
+/**
+ * Arguments for `/api/tacit/usage`. Declared here (not next to
+ * `bootstrapArgSchema`) because `z.enum(USAGE_RUN_TYPES)` needs the run-type
+ * list above it. Every field is optional on the wire; `tracker.report()`
+ * applies the defaults (`range: '30d'`, `page: 1`, `pageSize: 20`).
+ */
+export const usageArgSchema = z.object({
+  range: z.enum(['today', '7d', '30d', 'month', 'all']).optional(),
+  type: z.enum(USAGE_RUN_TYPES).optional(),
+  status: z.enum(['success', 'partial', 'failed']).optional(),
+  model: z.string().max(64).optional(),
+  workspace: z.string().max(200).optional(),
+  sessionId: z.string().max(200).optional(),
+  page: z.number().int().min(1).max(1000).optional(),
+  pageSize: z.number().int().min(1).max(100).optional(),
+})
+
+/** Arguments for `/api/tacit/usage-run`: one run id, as minted by `beginRun`. */
+export const usageRunArgSchema = z.object({
+  runId: z.string().min(1).max(64),
+})