@phenx-inc/ctlsurf 0.13.6 → 0.14.0

package/src/main/observer/tier1.ts

@@ -0,0 +1,306 @@
+import type {
+  Finding,
+  LedgerEvent,
+  ModelCaller,
+  Sensitivity,
+  SpanKind,
+  Tier0Tag,
+  Tier1Output,
+} from './types'
+import { SEVERITY_ORDER } from './types'
+import { truncateForTier1 } from './tier0'
+
+/**
+ * Tier 1 — Haiku windowed reviewer (spec §3.2).
+ *
+ * Triggers: every N ledger events (default 20) OR T seconds of debounce
+ * (default 120s) OR immediately on any Tier-0 tag with severity ≥ warn.
+ *
+ * Input: cached system prompt (taxonomy + output contract + license policy)
+ * + the truncated event window + a compact rolling state object. Output:
+ * strict JSON via structured outputs. Malformed output → one retry with the
+ * error appended; second failure → health event (spec §6.3).
+ */
+
+const MAX_OUTPUT_TOKENS = 1_500
+const RETRY_LIMIT = 1
+
+export interface Tier1Options {
+  session: string
+  model: string
+  windowEvents: number
+  debounceMs: number
+  callModel: ModelCaller
+  /** Degrade to Tier-0-only when true (budget breach). */
+  isOverBudget: () => boolean
+  onUsage: (model: string, usage: { inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number }) => void
+  onFindings: (findings: Array<Omit<Finding, 'id' | 'session'>>) => void
+  onSpanBoundary: (newWorkRef: string | undefined, kind: SpanKind | undefined) => void
+  onEscalate: (reason: string, windowIds: string[]) => void
+  onHealth: (message: string) => void
+  /** Called after each completed review with what it looked at/found —
+   * feeds the panel's "it ran" heartbeat. */
+  onReviewed?: (eventCount: number, findingCount: number) => void
+  /** Review in-flight signal (true at start, false when settled) —
+   * drives the panel's processing animation. Always called in pairs. */
+  onReviewState?: (running: boolean) => void
+  /** Detection threshold lever; read per call so the panel lever applies
+   * to reviews already scheduled. */
+  getSensitivity?: () => Sensitivity
+  /** Rolling state seed. */
+  getSpanHypothesis: () => string
+}
+
+const TIER1_SYSTEM = `You are Observer, a supervision layer reviewing a coding agent's session ledger. You are NOT the coding agent. You review process, not product.
+
+You receive a window of ledger events (JSON, one per line) plus a rolling state object. Each event has an id (evt_N) — these are the ONLY valid receipts.
+
+Report findings in these categories only:
+- assumption: the agent made an unstated or weakly-stated assumption that could bite later (timezone, idempotency, "for simplicity" scope cuts, hardcoded placeholder left in).
+- unverified_claim: the agent claimed something the window does not support (says tests pass but no passing test run visible; says deployed but no deploy command).
+- license: a dependency change introduces license risk. Policy: AGPL, SSPL, and unknown/unlicensed dependencies are flagged (high). LGPL is flagged (warn). MIT/Apache-2.0/BSD/ISC are fine.
+- dependency: new dependency for trivial functionality, unpinned/wildcard versions in manifests, or a dep bump with suspicious scope.
+
+Precision over recall: only report findings a busy human supervisor would want to see. Do not report style nits, normal tool usage, or things the human explicitly asked for. Confidence is your honest probability the finding is real and worth attention. Severity: info (worth a digest line), warn (should be reviewed), high (needs attention soon), critical (drop everything — almost never from this tier).
+
+Every finding MUST cite receipts: event ids from THIS window that support it.
+
+Span tracking: the state object carries the current span hypothesis (which work item the session time is attributed to). If the window shows the human switching to a different work item (new ticket id, clearly different task), set span_action.boundary=true with new_work_ref and kind (feature|bug|chore|tangent|unticketed). Otherwise boundary=false.
+
+Escalate (escalate=true, with reason) only when judgment exceeds your pay grade: an apparent contradiction with earlier human instructions, ambiguous scope drift, or suspected test-integrity issues.
+
+Update state_updates.span_hypothesis (one line: what work item is active) and state_updates.human_instructions_summary (2-3 sentences: what the human has asked for so far, cumulative).
+
+Output strict JSON matching the provided schema. No prose.`
+
+/** Sensitivity addendum appended to the system block. Stable per level, so
+ * the prompt cache only re-primes when the user moves the lever. */
+const SENSITIVITY_ADDENDUM: Record<Sensitivity, string> = {
+  severe:
+    '\n\nSENSITIVITY: SEVERE. Report only findings a supervisor must act on: severity high or critical with confidence >= 0.75. When in doubt, stay silent.',
+  balanced:
+    '\n\nSENSITIVITY: BALANCED. Report clearly-supported findings of severity warn and above; skip marginal info-level observations.',
+  all:
+    '\n\nSENSITIVITY: ALL SIGNALS. Report every plausible signal, including low-confidence and info-level observations — recall over precision at this level.',
+}
+
+export const TIER1_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  properties: {
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          category: { type: 'string', enum: ['assumption', 'unverified_claim', 'license', 'dependency'] },
+          severity: { type: 'string', enum: ['info', 'warn', 'high', 'critical'] },
+          confidence: { type: 'number' },
+          title: { type: 'string' },
+          detail: { type: 'string' },
+          receipts: { type: 'array', items: { type: 'string' } },
+        },
+        required: ['category', 'severity', 'confidence', 'title', 'detail', 'receipts'],
+        additionalProperties: false,
+      },
+    },
+    span_action: {
+      type: 'object',
+      properties: {
+        boundary: { type: 'boolean' },
+        new_work_ref: { type: 'string' },
+        kind: { type: 'string', enum: ['feature', 'bug', 'chore', 'tangent', 'unticketed', 'idle'] },
+      },
+      required: ['boundary'],
+      additionalProperties: false,
+    },
+    escalate: { type: 'boolean' },
+    escalate_reason: { type: 'string' },
+    state_updates: {
+      type: 'object',
+      properties: {
+        span_hypothesis: { type: 'string' },
+        human_instructions_summary: { type: 'string' },
+      },
+      required: ['span_hypothesis', 'human_instructions_summary'],
+      additionalProperties: false,
+    },
+  },
+  required: ['findings', 'span_action', 'escalate', 'state_updates'],
+  additionalProperties: false,
+}
+
+export class Tier1Reviewer {
+  private readonly opts: Tier1Options
+  private buffer: LedgerEvent[] = []
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null
+  private running: Promise<void> = Promise.resolve()
+  private degraded = false
+
+  /** Rolling state (spec §3.2): kept compact, fed back each call. */
+  private humanInstructionsSummary = ''
+  private openFindingTitles: string[] = []
+
+  constructor(opts: Tier1Options) {
+    this.opts = opts
+  }
+
+  /** Feed a tagged ledger event into the window. */
+  push(event: LedgerEvent): void {
+    this.buffer.push(event)
+    const urgent = (event.tags || []).some((t) => SEVERITY_ORDER[t.severity] >= SEVERITY_ORDER.warn)
+    if (urgent || this.buffer.length >= this.opts.windowEvents) {
+      this.schedule()
+      return
+    }
+    if (!this.debounceTimer) {
+      this.debounceTimer = setTimeout(() => {
+        this.debounceTimer = null
+        this.schedule()
+      }, this.opts.debounceMs)
+    }
+  }
+
+  /** Review whatever is buffered right now, without waiting for the window
+   * to fill or the debounce to expire. Used at turn boundaries — the agent
+   * just handed control back to the human. */
+  reviewNow(): void {
+    this.schedule()
+  }
+
+  /** Flush any pending window and wait for in-flight calls (session end). */
+  async flush(): Promise<void> {
+    this.schedule()
+    await this.running
+  }
+
+  dispose(): void {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer)
+      this.debounceTimer = null
+    }
+  }
+
+  // Serialize reviews: one in flight at a time, windows drain in order.
+  private schedule(): void {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer)
+      this.debounceTimer = null
+    }
+    if (this.buffer.length === 0) return
+    const window = this.buffer
+    this.buffer = []
+    this.running = this.running.then(() => this.review(window)).catch(() => { /* handled inside */ })
+  }
+
+  private async review(window: LedgerEvent[]): Promise<void> {
+    if (this.opts.isOverBudget()) {
+      if (!this.degraded) {
+        this.degraded = true
+        this.opts.onHealth('Daily budget cap reached; Tier 1 degraded to Tier-0-only for the rest of the day.')
+      }
+      return
+    }
+    this.degraded = false
+
+    const windowIds = window.map((e) => e.id)
+    const user = this.buildUser(window)
+    const system = TIER1_SYSTEM + SENSITIVITY_ADDENDUM[this.opts.getSensitivity?.() || 'all']
+
+    this.opts.onReviewState?.(true)
+    try {
+      let lastError = ''
+      for (let attempt = 0; attempt <= RETRY_LIMIT; attempt++) {
+        try {
+          const result = await this.opts.callModel({
+            model: this.opts.model,
+            maxTokens: MAX_OUTPUT_TOKENS,
+            system,
+            user: lastError
+              ? `${user}\n\nYour previous output was invalid (${lastError}). Return valid JSON matching the schema.`
+              : user,
+            schema: TIER1_SCHEMA,
+          })
+          this.opts.onUsage(this.opts.model, result.usage)
+          const parsed = this.parse(result.text, windowIds)
+          this.apply(parsed)
+          this.opts.onReviewed?.(window.length, parsed.findings.length)
+          return
+        } catch (err: any) {
+          lastError = String(err?.message || err).slice(0, 300)
+        }
+      }
+      this.opts.onHealth(`Tier 1 review failed after retry: ${lastError}. Window ${windowIds[0]}..${windowIds[windowIds.length - 1]} unreviewed.`)
+    } finally {
+      this.opts.onReviewState?.(false)
+    }
+  }
+
+  private buildUser(window: LedgerEvent[]): string {
+    const compact = window.map((e) => {
+      const out: Record<string, unknown> = { id: e.id, ts: e.ts, type: e.type }
+      if (e.text) out.text = truncateForTier1(e.text)
+      if (e.tool) out.tool = e.tool
+      if (e.input) out.input = truncateForTier1(e.input)
+      if (e.toolUseId) out.tool_use_id = e.toolUseId
+      if (e.isError !== undefined) out.is_error = e.isError
+      if (e.state) out.state = e.state
+      if (e.tags?.length) out.tags = e.tags
+      return JSON.stringify(out)
+    })
+    const state = {
+      span_hypothesis: this.opts.getSpanHypothesis(),
+      open_findings: this.openFindingTitles.slice(-10),
+      human_instructions_summary: this.humanInstructionsSummary,
+    }
+    return `STATE:\n${JSON.stringify(state)}\n\nWINDOW (${window.length} events):\n${compact.join('\n')}`
+  }
+
+  private parse(text: string, windowIds: string[]): Tier1Output {
+    const parsed = JSON.parse(text) as Tier1Output
+    if (!Array.isArray(parsed.findings) || !parsed.span_action || !parsed.state_updates) {
+      throw new Error('missing required fields')
+    }
+    // Receipts must resolve to events in this window; drop hallucinated ids.
+    const valid = new Set(windowIds)
+    for (const f of parsed.findings) {
+      f.receipts = (f.receipts || []).filter((r) => valid.has(r))
+    }
+    return parsed
+  }
+
+  private apply(out: Tier1Output): void {
+    if (out.findings.length > 0) {
+      const ts = new Date().toISOString()
+      this.opts.onFindings(
+        out.findings.map((f) => ({
+          type: 'observer.finding' as const,
+          ts,
+          category: f.category,
+          severity: f.severity,
+          confidence: Math.max(0, Math.min(1, f.confidence)),
+          title: f.title,
+          detail: f.detail,
+          receipts: f.receipts,
+          tier: 1 as const,
+          status: 'open' as const,
+          delivery: ['digest' as const],
+          resolution: null,
+        })),
+      )
+      this.openFindingTitles.push(...out.findings.map((f) => f.title))
+    }
+    if (out.span_action.boundary) {
+      this.opts.onSpanBoundary(out.span_action.new_work_ref, out.span_action.kind)
+    }
+    if (out.escalate) {
+      this.opts.onEscalate(out.escalate_reason || 'unspecified', [])
+    }
+    if (out.state_updates?.human_instructions_summary) {
+      this.humanInstructionsSummary = out.state_updates.human_instructions_summary.slice(0, 1_000)
+    }
+  }
+
+  get instructionsSummary(): string {
+    return this.humanInstructionsSummary
+  }
+}

package/src/main/observer/tier2.ts

@@ -0,0 +1,125 @@
+import type { Finding, ModelCaller, Span } from './types'
+
+/**
+ * Tier 2 — session-end digest (spec §3.3, §7.1; Phase 1 cut item 4).
+ *
+ * The 30-second supervisor summary: what happened, what deserves attention,
+ * where the time went — every item backed by receipts already recorded in
+ * the ledger. The model call adjudicates escalations and writes the prose;
+ * if it fails, a deterministic fallback digest is produced from counts so a
+ * session never ends silently.
+ */
+
+const MAX_OUTPUT_TOKENS = 1_000
+
+export interface DigestInput {
+  session: string
+  agentName: string
+  cwd: string
+  startedAt: string
+  endedAt: string
+  findings: Finding[]
+  spans: Span[]
+  humanInstructionsSummary: string
+  escalations: string[]
+  /** Recent user messages, for the contradiction sweep. */
+  userMessages: string[]
+}
+
+export interface DigestResult {
+  digest: string
+  /** True when the model produced it; false for the deterministic fallback. */
+  fromModel: boolean
+}
+
+const DIGEST_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  properties: {
+    digest: { type: 'string' },
+  },
+  required: ['digest'],
+  additionalProperties: false,
+}
+
+const DIGEST_SYSTEM = `You are Observer, writing the end-of-session digest for a human supervising a coding agent. Target: a 30-second read.
+
+Write 3-8 plain sentences (no headers, no markdown tables):
+1. What the session worked on and roughly how the time split (agent-active vs human vs idle), from the spans.
+2. The findings worth the supervisor's attention, most severe first, each with its receipt ids in parentheses. Merge duplicates. Skip pure noise.
+3. If any escalation or user message suggests the agent contradicted an earlier human instruction, say so explicitly — this is the highest-value check.
+4. If there is nothing concerning, say so in one sentence — do not invent concerns.
+
+Be concrete and specific. Never soften a real problem; never inflate a non-problem.`
+
+export async function generateDigest(
+  input: DigestInput,
+  callModel: ModelCaller | null,
+  model: string,
+  onUsage: (model: string, usage: { inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number }) => void,
+): Promise<DigestResult> {
+  if (callModel) {
+    try {
+      const result = await callModel({
+        model,
+        maxTokens: MAX_OUTPUT_TOKENS,
+        system: DIGEST_SYSTEM,
+        user: JSON.stringify({
+          session: input.session,
+          agent: input.agentName,
+          project: input.cwd,
+          window: { start: input.startedAt, end: input.endedAt },
+          human_instructions_summary: input.humanInstructionsSummary,
+          recent_user_messages: input.userMessages.slice(-8).map((m) => m.slice(0, 500)),
+          escalations: input.escalations,
+          findings: input.findings.map((f) => ({
+            id: f.id, category: f.category, severity: f.severity,
+            confidence: f.confidence, title: f.title, detail: f.detail, receipts: f.receipts,
+          })),
+          spans: input.spans.map((s) => ({
+            id: s.id, work_ref: s.work_ref, kind: s.kind,
+            start: s.start, end: s.end, activity: s.activity,
+          })),
+        }),
+        schema: DIGEST_SCHEMA,
+      })
+      onUsage(model, result.usage)
+      const parsed = JSON.parse(result.text)
+      if (typeof parsed?.digest === 'string' && parsed.digest.trim()) {
+        return { digest: parsed.digest.trim(), fromModel: true }
+      }
+    } catch { /* fall through to deterministic digest */ }
+  }
+  return { digest: fallbackDigest(input), fromModel: false }
+}
+
+/** Counts-only digest so delivery never depends on a model call succeeding. */
+export function fallbackDigest(input: DigestInput): string {
+  const bySeverity = new Map<string, number>()
+  for (const f of input.findings) bySeverity.set(f.severity, (bySeverity.get(f.severity) || 0) + 1)
+  const sevSummary = [...bySeverity.entries()].map(([s, n]) => `${n} ${s}`).join(', ') || 'none'
+
+  const activity = input.spans.reduce(
+    (acc, s) => ({
+      agent: acc.agent + s.activity.agent_active_s,
+      human: acc.human + s.activity.human_active_s,
+      idle: acc.idle + s.activity.idle_s,
+    }),
+    { agent: 0, human: 0, idle: 0 },
+  )
+  const min = (s: number) => Math.round(s / 60)
+
+  const workItems = [...new Set(input.spans.map((s) => s.work_ref.external.join(',') || '(unticketed)'))]
+  const top = input.findings
+    .filter((f) => f.severity === 'high' || f.severity === 'critical')
+    .slice(0, 3)
+    .map((f) => `${f.title} (${f.receipts.join(', ')})`)
+
+  const parts = [
+    `Session ${input.session} (${input.agentName}): ${input.spans.length} span(s) across ${workItems.join('; ')}.`,
+    `Activity: ~${min(activity.agent)}min agent-active, ~${min(activity.human)}min human, ~${min(activity.idle)}min idle.`,
+    `Findings: ${sevSummary}.`,
+  ]
+  if (top.length > 0) parts.push(`Needs attention: ${top.join(' | ')}.`)
+  if (input.escalations.length > 0) parts.push(`Escalations (unadjudicated): ${input.escalations.join(' | ')}.`)
+  return parts.join(' ')
+}

package/src/main/observer/types.ts

@@ -0,0 +1,224 @@
+/**
+ * Observer — shared types (spec §4–§6).
+ *
+ * All Observer outputs are ledger events themselves: append-only JSONL,
+ * namespaced (`observer.*`) so consumers can filter. Findings and spans
+ * always carry receipts — ledger event ids linking to the exact moment.
+ */
+
+export type Severity = 'info' | 'warn' | 'high' | 'critical'
+
+export const SEVERITY_ORDER: Record<Severity, number> = {
+  info: 0,
+  warn: 1,
+  high: 2,
+  critical: 3,
+}
+
+/** Full taxonomy (spec §4). Phase 1 Tier-1 emits only the subset in
+ * TIER1_CATEGORIES; the rest are reserved for Tier 0 ground-truth checks
+ * (`unverified_claim`, `destructive`) and later phases. */
+export type FindingCategory =
+  | 'assumption'
+  | 'license'
+  | 'security'
+  | 'destructive'
+  | 'scope_drift'
+  | 'unverified_claim'
+  | 'test_integrity'
+  | 'contradiction'
+  | 'bad_practice'
+  | 'dependency'
+
+export const TIER1_CATEGORIES: FindingCategory[] = [
+  'assumption',
+  'unverified_claim',
+  'license',
+  'dependency',
+]
+
+/** Tier-0 tag attached to a ledger event for downstream tiers. */
+export interface Tier0Tag {
+  rule: string
+  severity: Severity
+  /** Short human-readable annotation (matched text, path, ticket id…). */
+  note?: string
+}
+
+/** Normalized ledger event. The `observer.*` types are Observer outputs
+ * appended to the same substrate. */
+export type LedgerEventType =
+  | 'user_message'
+  | 'agent_message'
+  | 'tool_use'
+  | 'tool_result'
+  | 'agent_state'
+  | 'observer.finding'
+  | 'observer.span'
+  | 'observer.digest'
+  | 'observer.health'
+
+export interface LedgerEvent {
+  id: string
+  ts: string
+  session: string
+  type: LedgerEventType
+  /** user_message / agent_message text, or truncated tool_result output. */
+  text?: string
+  /** tool_use: tool name (Bash, Edit, …). */
+  tool?: string
+  /** tool_use: compact input summary (command, file_path, …). */
+  input?: string
+  /** tool_result: id linking back to the tool_use. */
+  toolUseId?: string
+  /** tool_result: the agent's runtime reported failure. */
+  isError?: boolean
+  /** agent_state: busy | awaiting_input | awaiting_decision | idle. */
+  state?: string
+  tags?: Tier0Tag[]
+  /** observer.* events carry their payload here. */
+  payload?: unknown
+}
+
+/** Finding (spec §6.1). */
+export interface Finding {
+  type: 'observer.finding'
+  id: string
+  ts: string
+  session: string
+  category: FindingCategory
+  severity: Severity
+  confidence: number
+  title: string
+  detail: string
+  receipts: string[]
+  tier: 0 | 1 | 2
+  status: 'open' | 'ack' | 'dismissed' | 'resolved' | 'escalated'
+  delivery: Array<'interrupt' | 'digest' | 'agent_channel'>
+  resolution: string | null
+}
+
+export type SpanKind = 'feature' | 'bug' | 'chore' | 'tangent' | 'unticketed' | 'idle'
+
+export interface WorkRef {
+  /** ctlsurf task-tree node id (primary key when known). */
+  node: string | null
+  /** External ticket ids (JIRA:AUTH-231, …) — attributes, not the key. */
+  external: string[]
+}
+
+/** Span (spec §6.2). */
+export interface Span {
+  type: 'observer.span'
+  id: string
+  session: string
+  work_ref: WorkRef
+  kind: SpanKind
+  start: string
+  end: string
+  activity: { agent_active_s: number; human_active_s: number; idle_s: number }
+  boundary_source: 'tier0' | 'tier1' | 'tier2_retro' | 'human_edit'
+  receipts: string[]
+}
+
+/** Tier-1 call output contract (spec §6.3), enforced via structured outputs. */
+export interface Tier1Output {
+  findings: Array<{
+    category: FindingCategory
+    severity: Severity
+    confidence: number
+    title: string
+    detail: string
+    receipts: string[]
+  }>
+  span_action: {
+    boundary: boolean
+    new_work_ref?: string
+    kind?: SpanKind
+  }
+  escalate: boolean
+  escalate_reason?: string
+  state_updates: {
+    span_hypothesis: string
+    human_instructions_summary: string
+  }
+}
+
+/** Observer block in settings.json (all optional; observer is off unless
+ * `enabled` is true and an API key is resolvable). */
+export interface ObserverSettings {
+  enabled?: boolean
+  /** Falls back to ANTHROPIC_API_KEY in the environment. */
+  anthropicApiKey?: string
+  tier1Model?: string
+  tier2Model?: string
+  /** Tier-1 window size in events (default 20). */
+  windowEvents?: number
+  /** Tier-1 debounce in seconds (default 120). */
+  debounceSec?: number
+  /** Daily spend cap in USD (default 1). On breach Tier 1 degrades to
+   * Tier-0-only and an observer.health event is emitted. */
+  dailyCapUsd?: number
+  /** Detection threshold (default 'all' — every signal surfaces). */
+  sensitivity?: Sensitivity
+}
+
+/** Detection threshold lever: `severe` surfaces only what a supervisor must
+ * act on; `all` relaxes for maximum signals. Applies to what is surfaced
+ * (panel + ctlsurf delivery) and steers the Tier-1 prompt; the local ledger
+ * keeps every finding regardless. */
+export type Sensitivity = 'severe' | 'balanced' | 'all'
+
+/** Minimum severity surfaced per sensitivity level. */
+export function severityFloor(sensitivity: Sensitivity): Severity {
+  if (sensitivity === 'severe') return 'high'
+  if (sensitivity === 'balanced') return 'warn'
+  return 'info'
+}
+
+export const OBSERVER_DEFAULTS = {
+  tier1Model: 'claude-haiku-4-5',
+  tier2Model: 'claude-sonnet-4-6',
+  windowEvents: 20,
+  debounceSec: 120,
+  dailyCapUsd: 1,
+  sensitivity: 'all' as Sensitivity,
+} as const
+
+/** One entry in the live feed shown by the in-app Observer panel. Findings,
+ * digests, and health events map 1:1 to their ledger records; `status` items
+ * are UI-only heartbeats (attached, review ran, …) and are not persisted. */
+export interface ObserverFeedItem {
+  id: string
+  ts: string
+  kind: 'finding' | 'digest' | 'health' | 'status'
+  tabId?: string
+  session?: string
+  title: string
+  detail?: string
+  category?: FindingCategory
+  severity?: Severity
+  confidence?: number
+  receipts?: string[]
+  tier?: 0 | 1 | 2
+}
+
+/** Model call abstraction so tiers are testable without the network.
+ * The production implementation (anthropic.ts) wraps @anthropic-ai/sdk. */
+export interface ModelCallRequest {
+  model: string
+  maxTokens: number
+  /** Stable system text; the caller marks it for prompt caching. */
+  system: string
+  /** Single user turn content. */
+  user: string
+  /** JSON schema for structured output (output_config.format). */
+  schema?: Record<string, unknown>
+}
+
+export interface ModelCallResult {
+  text: string
+  usage: { inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number }
+}
+
+export type ModelCaller = (req: ModelCallRequest) => Promise<ModelCallResult>