dsh-tacit 0.3.0 → 0.5.0

package/lib/schema.js

@@ -29,7 +29,7 @@ export const COACH_PROVIDER = 'deepseek-official'
  * 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']
+export const COACH_ERROR_CODES = ['no-llm', 'no-api-key', 'no-credit', 'rate-limited', 'timeout', 'empty-response', 'call-failed']
 
 /**
  * The loader-facing plugin config. Wrapped in `z.preprocess` so a patch row
@@ -79,6 +79,8 @@ export const Config = z.preprocess((v) => v ?? {}, z.object({
   costWarnDailyUsd: z.number().default(0),
   /** Same as `costWarnDailyUsd`, over a calendar month; 0 disables (clamped in mergeConfig). */
   costWarnMonthlyUsd: z.number().default(0),
+  /** Opt-in: a distilled directive stays queued until *Start trial* is pressed on it. */
+  reviewCandidates: z.boolean().default(false),
 }))
 
 /**
@@ -107,6 +109,7 @@ const configPatchSchema = z.object({
   costHistoryDays: z.number().optional(),
   costWarnDailyUsd: z.number().optional(),
   costWarnMonthlyUsd: z.number().optional(),
+  reviewCandidates: z.boolean().optional(),
 })
 
 // ── Trajectory projection ──────────────────────────────────────────────────
@@ -232,29 +235,77 @@ const feedbackEntrySchema = z.object({
  * system prompt). `distilled` entries come from analyses; `user` entries are
  * typed in Settings and survive every distillation.
  */
-const directiveTrialSchema = z.object({
-  /** Finished turns observed while the candidate was injected. */
-  turns: z.number().int().min(0),
-  /** How many of those were messy. */
-  messy: z.number().int().min(0),
-  /** Messy-turn rate over the 20 turns before the trial started. */
-  baselineRate: z.number(),
-  startedAt: z.number(),
+const directiveTrialSchema = z.preprocess(
+  // Profiles written before corrections were graded named the messy baseline `baselineRate`.
+  (raw) => (raw !== null && typeof raw === 'object' && 'baselineRate' in raw && !('baselineMessyRate' in raw) ? { ...raw, baselineMessyRate: raw.baselineRate } : raw),
+  z.object({
+    /** Finished turns observed while the candidate was injected. */
+    turns: z.number().int().min(0),
+    /** How many of those were messy. */
+    messy: z.number().int().min(0),
+    /** How many of those the user corrected with their next message. */
+    corrected: z.number().int().min(0).default(0),
+    /** Messy-turn rate over the 20 turns before the trial started. */
+    baselineMessyRate: z.number(),
+    /** Correction rate over those 20 turns; -1 = unknown (older profile), recomputed when the trial next advances. */
+    baselineCorrectionRate: z.number().default(-1),
+    startedAt: z.number(),
+  }),
+)
+
+/** One analysis report a distillation read: ids only, never the prompt. */
+const directiveEvidenceSchema = z.object({
+  sessionId: z.string(),
+  turn: z.number(),
+  trigger: z.string(),
 })
 
-const directiveSchema = z.object({
-  id: z.string(),
-  text: z.string(),
-  enabled: z.boolean().default(true),
-  source: z.enum(['distilled', 'user']).default('distilled'),
-  createdAt: z.number(),
-  /** candidate = injected on trial; active = proven (or user-made); retired = made things worse. */
-  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(),
-})
+/**
+ * queued = waiting for its scope's trial slot (or, under `reviewCandidates`, for the user's *Start trial*);
+ * candidate = injected on trial; active = proven (or user-made); retired = made things worse;
+ * removed = deleted by the user. Retired and removed records are kept so the distiller is told
+ * not to propose them again.
+ */
+export const DIRECTIVE_STATUSES = ['queued', 'candidate', 'active', 'retired', 'removed']
+
+const directiveSchema = z.preprocess(
+  (raw) => {
+    if (raw === null || typeof raw !== 'object') return raw
+    const entry = { ...raw }
+    // Profiles written before provenance was recorded: the text is as old as the record.
+    if (typeof entry.updatedAt !== 'number') entry.updatedAt = entry.createdAt
+    // A candidate is always enabled: switched off, it leaves the trial slot and queues again.
+    if (entry.status === 'candidate' && entry.enabled === false) {
+      entry.status = 'queued'
+      delete entry.trial
+    }
+    return entry
+  },
+  z.object({
+    id: z.string(),
+    text: z.string(),
+    enabled: z.boolean().default(true),
+    source: z.enum(['distilled', 'user']).default('distilled'),
+    createdAt: z.number(),
+    /** Last time the text changed (a reword) or the record moved state. */
+    updatedAt: z.number(),
+    /** Bumped on every reword of the text. */
+    version: z.number().int().min(1).default(1),
+    status: z.enum(DIRECTIVE_STATUSES).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 reports the distillation that wrote this text read (newest first, capped). */
+    evidence: z.array(directiveEvidenceSchema).default([]),
+    /** The usage-ledger run of that distillation, so its cost is one lookup away. '' for user-typed. */
+    distillationRunId: z.string().default(''),
+    /** When the trial reached its verdict; 0 = never. */
+    evaluatedAt: z.number().default(0),
+    /** When the user pressed *Start trial* under `reviewCandidates`; 0 = not yet. */
+    approvedAt: z.number().default(0),
+  }),
+)
 
 /** The persistent user-wide mistake profile. */
 export const profileSchema = z.object({
@@ -277,6 +328,8 @@ export const profileSchema = z.object({
   directives: z.array(directiveSchema).default([]),
   /** New analyses since the last directive distillation. */
   analysesSinceDirectives: z.number().int().min(0).default(0),
+  /** When a session was last loaded in each directive's workspace, so the least recently seen one is dropped first. */
+  workspaceSeenAt: z.record(z.string(), z.number()).default({}),
 })
 
 // ── Route argument codecs ──────────────────────────────────────────────────
@@ -293,9 +346,16 @@ 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), workspace: z.string().max(1000).optional() }),
+  z.object({ action: z.literal('rescope'), id: z.string().min(1).max(64), workspace: z.string().max(1000) }),
   z.object({ action: z.literal('remove'), id: z.string().min(1).max(64) }),
+  z.object({ action: z.literal('start-trial'), id: z.string().min(1).max(64) }),
 ])
 
+/** `/api/tacit/directive-receipt`: one directive's provenance and cost, by id. */
+export const directiveReceiptArgSchema = z.object({
+  id: z.string().min(1).max(64),
+})
+
 // ── Route argument codecs ──────────────────────────────────────────────────
 
 export const sessionArgSchema = z.object({
@@ -305,12 +365,15 @@ export const sessionArgSchema = z.object({
 export const analyzeArgSchema = z.object({
   sessionId: z.string().min(1).max(200),
   turn: z.number().int().min(1),
+  /** Re-analyze a turn that already has a report (otherwise `already-analyzed`, at no cost). */
+  force: z.boolean().optional(),
 })
 
 /** `/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),
+  force: z.boolean().optional(),
 })
 
 export const improveArgSchema = z.object({
@@ -347,6 +410,12 @@ export const USAGE_OPS = [
   'enrichment',
 ]
 
+/** Every state one recorded attempt can end in. */
+export const USAGE_ATTEMPT_STATUSES = ['ok', 'failed', 'unmetered']
+
+/** Every state a run can be in. `running` is written too: the flush persists live runs. */
+export const USAGE_RUN_STATUSES = ['running', 'success', 'partial', 'failed']
+
 /** Every kind of run the tracker groups attempts into. */
 export const USAGE_RUN_TYPES = [
   'bootstrap',
@@ -382,7 +451,7 @@ export const usageAttemptSchema = z.object({
   provider: z.string().default(''),
   reasoningEffort: z.string().nullable().default(null),
   finish: z.string().default(''),
-  status: z.enum(['ok', 'failed', 'unmetered']),
+  status: z.enum(USAGE_ATTEMPT_STATUSES),
   code: z.string().default(''),
   sessionId: z.string().default(''),
   turn: z.number().nullable().default(null),
@@ -410,10 +479,12 @@ const emptyTokenBuckets = tokenBucketsSchema.parse({})
 export const usageTotalsSchema = z.object({
   attempts: z.number().default(0),
   billedCalls: z.number().default(0),
+  failedCalls: z.number().default(0),
   unmeteredCalls: z.number().default(0),
   unpricedCalls: z.number().default(0),
   tokens: tokenBucketsSchema.default(emptyTokenBuckets),
   usdKnown: z.number().default(0),
+  failedUsd: z.number().default(0),
 })
 
 const emptyUsageTotals = usageTotalsSchema.parse({})
@@ -425,7 +496,7 @@ export const usageRunSchema = z.object({
   trigger: z.string().default(''),
   startedAt: z.number(),
   endedAt: z.number().default(0),
-  status: z.enum(['running', 'success', 'partial', 'failed']).default('running'),
+  status: z.enum(USAGE_RUN_STATUSES).default('running'),
   sessionId: z.string().default(''),
   turn: z.number().nullable().default(null),
   workspace: z.string().default(''),
@@ -454,6 +525,8 @@ export const usageSummarySchema = z.object({
   lifetime: usageTotalsSchema.default(emptyUsageTotals),
   byType: z.record(usageTotalsSchema).default({}),
   byModel: z.record(usageTotalsSchema).default({}),
+  byProvider: z.record(usageTotalsSchema).default({}),
+  byTrigger: z.record(usageTotalsSchema).default({}),
   days: z.record(usageDayTotalsSchema).default({}),
 })
 
@@ -466,7 +539,7 @@ export const usageSummarySchema = z.object({
 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(),
+  status: z.enum(USAGE_RUN_STATUSES).optional(),
   model: z.string().max(64).optional(),
   workspace: z.string().max(200).optional(),
   sessionId: z.string().max(200).optional(),