dsh-tacit 0.2.3 → 0.3.0

package/lib/routes.js

@@ -10,7 +10,14 @@
  * into one ctx.effect so a fiber unload removes every route.
  */
 
-function withService(ctx, serviceName, fn) {
+/**
+ * Run `fn(service)` as soon as `serviceName` exists — immediately when it is
+ * already registered, otherwise once on the next `internal/service` event for
+ * it (the listener removes itself). Exported so the service layer can wait on
+ * optional siblings (e.g. `costMeter`) the same way the routes wait on
+ * `webServer`.
+ */
+export function withService(ctx, serviceName, fn) {
   const existing = ctx.get !== undefined && typeof ctx.get === 'function' ? ctx.get(serviceName) : undefined
   if (existing !== undefined && existing !== null) {
     fn(existing)
@@ -130,14 +137,20 @@ export function registerWebRoutes(ctx, service) {
     route('POST', '/api/tacit/reports', (body) => service.getReports(body))
     route('POST', '/api/tacit/history', (body) => service.listHistory(body))
     route('POST', '/api/tacit/analyze', (body) => service.analyzeTurn(body))
+    route('POST', '/api/tacit/analyze-batch', (body) => service.analyzeBatch(body))
     route('POST', '/api/tacit/improve', (body) => service.improveDraft(body))
     route('POST', '/api/tacit/feedback', (body) => service.feedback(body))
     route('POST', '/api/tacit/applied', (body) => service.applied(body))
     route('POST', '/api/tacit/directives', (body) => service.directives(body))
     route('POST', '/api/tacit/stats', (body) => service.stats(body))
     route('POST', '/api/tacit/bootstrap', (body) => service.bootstrap(body))
+    route('POST', '/api/tacit/bootstrap-preview', (body) => service.bootstrapPreview(body))
     route('POST', '/api/tacit/config', (body) => service.updateConfig(body))
     route('POST', '/api/tacit/clear', () => service.clearReports())
+    route('POST', '/api/tacit/usage', (body) => service.usageReport(body))
+    route('POST', '/api/tacit/usage-run', (body) => service.usageRun(body))
+    route('POST', '/api/tacit/usage-clear', () => service.usageClear())
+    route('POST', '/api/tacit/pricing-refresh', () => service.pricingRefresh())
 
     ctx.effect(() => () => {
       for (const dispose of disposers.splice(0).reverse()) {

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
@@ -63,6 +73,12 @@ export const Config = z.preprocess((v) => v ?? {}, z.object({
   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),
 }))
 
 /**
@@ -88,6 +104,9 @@ const configPatchSchema = z.object({
   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 ──────────────────────────────────────────────────
@@ -288,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),
@@ -308,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),
+})