@tangle-network/agent-app 0.44.7 → 0.44.9

package/dist/turn-health/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/turn-health/classify.ts","../../src/turn-health/sink.ts","../../src/turn-health/lifecycle.ts","../../src/turn-health/sweep.ts"],"sourcesContent":["/**\n * The classifier for turns that FAIL BY RETURNING SUCCESS.\n *\n * Every failure this module names shipped to a customer with HTTP 200, no\n * thrown error, and no log line anyone read. Three were measured in production\n * in a single week:\n *\n *   - a turn settled `{\"outcome\":{\"type\":\"completed\"},\"finalText\":\"\",\n *     \"tokenUsage\":{\"outputTokens\":0}}` — the customer saw a blank bubble;\n *   - six `submit_proposal` tool calls collapsed into ONE whose arguments were\n *     a 1,652-character non-JSON string, so zero proposals persisted and\n *     nothing errored (agent-runtime #626);\n *   - a thread took 255 user messages over 17 days and produced 2 replies,\n *     both of them error text.\n *\n * A conventional health check cannot see any of these, because it probes\n * DEPENDENCIES (is the sandbox reachable, is the router up) and every one of\n * these failures happens with all dependencies green. This classifier probes\n * the OUTCOME instead.\n *\n * It is deliberately pure and structural: it reads a settled turn's own\n * projection, so the SAME function judges a live turn through the\n * `/chat-routes` lifecycle seam and a historical row read back out of the\n * store during a sweep. One definition of \"silently broken\", two call sites.\n */\n\n/** How loudly a reason should be routed. `critical` means a customer got\n *  nothing usable; `warning` means the turn degraded but still produced\n *  something a human could read. */\nexport type TurnHealthSeverity = 'critical' | 'warning'\n\n/** One specific way a turn returned success while failing.\n *\n *  Each variant carries the evidence that identified it, so an alert can name\n *  the offending value instead of asserting a verdict the reader has to take\n *  on faith. */\nexport type TurnHealthReason =\n  /** Settled without error and produced nothing a user can read: no text, and\n   *  no artifact part (file/image/work-product/plan/interaction). This is the\n   *  verbatim blank-completion capture. */\n  | {\n      kind: 'empty_completion'\n      outputTokens: number | null\n      partCount: number\n      durationMs?: number\n    }\n  /** A tool call whose arguments never parsed. The engine surfaces unparseable\n   *  arguments as a RAW STRING rather than throwing, so the call is neither\n   *  dropped nor errored — it silently does nothing. Detecting a string-typed\n   *  tool input that fails `JSON.parse` is the exact fingerprint of the\n   *  index-less parallel-tool-call collapse. */\n  | {\n      kind: 'malformed_tool_call'\n      tool: string\n      inputLength: number\n      /** Leading characters of the offending input, for the alert body. */\n      sample: string\n    }\n  /** A tool call that never reached a terminal state carrying output. The call\n   *  was issued and then simply produced no effect. */\n  | {\n      kind: 'tool_call_no_effect'\n      tool: string\n      status: string\n    }\n  /** The turn failed outright. Not silent by itself — but it becomes silent\n   *  the moment nothing is watching, which is how 16 days of\n   *  `TANGLE_HUB_URL is required` reached customers unnoticed. */\n  | { kind: 'turn_failed'; reason: string }\n\n/** A settled turn, in the narrowest shape both call sites can supply.\n *\n *  Structural on purpose: the lifecycle seam supplies `finalText`/`usage`, a\n *  store sweep supplies `content`/`parts` read back from a row, and neither\n *  has to import the other's types. */\nexport interface TurnOutcomeInput {\n  /** The turn's final assistant text. */\n  finalText?: string | null\n  /** The persisted assistant parts. Untyped by design — a sweep reads these\n   *  out of a JSON column and must not be forced to validate them first. */\n  parts?: readonly unknown[] | null\n  /** Output tokens, when the caller has usage. `null`/absent is unknown, which\n   *  is NOT the same as zero and is never treated as evidence. */\n  outputTokens?: number | null\n  /** Set when the turn surfaced a terminal error event. */\n  failed?: boolean\n  failureReason?: string | null\n  durationMs?: number\n}\n\n/** The verdict for one turn. `healthy` is exactly `reasons.length === 0`, kept\n *  as a field so callers read intent rather than an array length. */\nexport interface TurnHealthVerdict {\n  healthy: boolean\n  severity: TurnHealthSeverity | null\n  reasons: TurnHealthReason[]\n}\n\n/** Part kinds that count as something a user actually receives.\n *\n *  A tool part is deliberately NOT here. A turn that ran six tools and said\n *  nothing, with no artifact to show for it, is the malformed-tool-call\n *  disaster — counting a tool chip as output would suppress the very alert\n *  this module exists to raise. */\nconst ARTIFACT_PART_KINDS = new Set(['file', 'image', 'work-product', 'plan', 'interaction'])\n\nconst SAMPLE_CHARS = 120\n\nfunction asRecord(value: unknown): Record<string, unknown> | null {\n  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : null\n}\n\nfunction nonEmptyString(value: unknown): string | null {\n  return typeof value === 'string' && value.trim().length > 0 ? value : null\n}\n\n/** True when a string is not parseable JSON.\n *\n *  Only meaningful for tool INPUT, where the engine's contract is that a\n *  well-formed call carries an object (or a string that parses into one). A\n *  string that fails to parse means the arguments were concatenated or\n *  truncated upstream. */\nfunction isUnparseableJson(value: string): boolean {\n  const trimmed = value.trim()\n  if (trimmed.length === 0) return false\n  try {\n    JSON.parse(trimmed)\n    return false\n  } catch {\n    return true\n  }\n}\n\n/** Tool statuses that mean the call actually landed.\n *\n *  Anything else — `pending`, `running`, `error`, an unknown string — left no\n *  persisted effect by the time the turn settled. */\nconst SETTLED_TOOL_STATUSES = new Set(['completed', 'complete', 'success', 'done'])\n\n/**\n * Judge one settled turn.\n *\n * Never throws: a malformed `parts` blob is a thing this function REPORTS on,\n * so it must not be a thing it dies on. Telemetry that can crash the turn it\n * measures is worse than no telemetry.\n */\nexport function classifyTurnOutcome(input: TurnOutcomeInput): TurnHealthVerdict {\n  const reasons: TurnHealthReason[] = []\n\n  if (input.failed) {\n    reasons.push({\n      kind: 'turn_failed',\n      reason: nonEmptyString(input.failureReason) ?? 'unspecified',\n    })\n  }\n\n  const parts = Array.isArray(input.parts) ? input.parts : []\n\n  let hasVisibleText = nonEmptyString(input.finalText) !== null\n  let artifactCount = 0\n\n  for (const raw of parts) {\n    const part = asRecord(raw)\n    if (!part) continue\n    const type = typeof part.type === 'string' ? part.type : ''\n\n    if (type === 'text' && nonEmptyString(part.text) !== null) {\n      hasVisibleText = true\n      continue\n    }\n    if (ARTIFACT_PART_KINDS.has(type)) {\n      artifactCount += 1\n      continue\n    }\n    if (type !== 'tool') continue\n\n    const tool = nonEmptyString(part.tool) ?? 'unknown'\n    const state = asRecord(part.state)\n    const status = typeof state?.status === 'string' ? state.status : 'unknown'\n\n    // The #626 fingerprint: arguments surfaced as a raw string because they\n    // failed to parse upstream. Checked before the status gate — a malformed\n    // call can still be marked completed, which is precisely why it is silent.\n    const toolInput = state?.input\n    if (typeof toolInput === 'string' && isUnparseableJson(toolInput)) {\n      reasons.push({\n        kind: 'malformed_tool_call',\n        tool,\n        inputLength: toolInput.length,\n        sample: toolInput.slice(0, SAMPLE_CHARS),\n      })\n      continue\n    }\n\n    if (!SETTLED_TOOL_STATUSES.has(status)) {\n      reasons.push({ kind: 'tool_call_no_effect', tool, status })\n    }\n  }\n\n  // `outputTokens` is corroborating evidence, never the trigger: a turn can\n  // spend tokens on reasoning and still deliver nothing, and a turn with\n  // unknown usage can still be perfectly fine.\n  if (!input.failed && !hasVisibleText && artifactCount === 0) {\n    reasons.push({\n      kind: 'empty_completion',\n      outputTokens: input.outputTokens ?? null,\n      partCount: parts.length,\n      ...(input.durationMs !== undefined ? { durationMs: input.durationMs } : {}),\n    })\n  }\n\n  return {\n    healthy: reasons.length === 0,\n    severity: severityOf(reasons),\n    reasons,\n  }\n}\n\n/** `critical` when the customer got nothing usable out of the turn. A\n *  malformed tool call alongside readable text is a `warning` — degraded, but\n *  a human still received an answer. */\nfunction severityOf(reasons: TurnHealthReason[]): TurnHealthSeverity | null {\n  if (reasons.length === 0) return null\n  const critical = reasons.some((r) => r.kind === 'empty_completion' || r.kind === 'turn_failed')\n  return critical ? 'critical' : 'warning'\n}\n\n/** One-line human summary of a reason, for an alert body. */\nexport function describeReason(reason: TurnHealthReason): string {\n  switch (reason.kind) {\n    case 'empty_completion':\n      return `completed with NO output (${reason.partCount} parts, outputTokens=${\n        reason.outputTokens ?? 'unknown'\n      })`\n    case 'malformed_tool_call':\n      return `tool \\`${reason.tool}\\` arguments did not parse (${reason.inputLength} chars): ${reason.sample}`\n    case 'tool_call_no_effect':\n      return `tool \\`${reason.tool}\\` left no effect (status=${reason.status})`\n    case 'turn_failed':\n      return `turn failed: ${reason.reason}`\n  }\n}\n","/**\n * Where a silent-failure verdict GOES.\n *\n * The detection half is worthless without this half. Every failure this module\n * finds was already visible in the database the whole time — 255 unanswered\n * messages sat in a table for 17 days. What was missing was not the data, it\n * was delivery to a human who had not thought to look.\n *\n * So the sink is a seam, not a channel: the product supplies the transport,\n * and agent-app ships the two shapes the fleet already has credentials for\n * (an ops webhook, and stderr). No new channel is invented here.\n */\n\nimport { describeReason, type TurnHealthReason, type TurnHealthSeverity } from './classify.js'\n\n/** One deliverable alert. */\nexport interface TurnHealthAlert {\n  /** Which product raised it (`projectId`). Alerts from four products land in\n   *  one channel, so this is what makes the message actionable. */\n  product: string\n  severity: TurnHealthSeverity\n  /** Stable grouping key. Throttling is keyed on this, so it must NOT contain\n   *  a turn id or a timestamp or every alert is unique and nothing dedupes. */\n  key: string\n  title: string\n  /** Human-readable lines. */\n  details: string[]\n  /** Structured payload for a machine consumer. */\n  data?: Record<string, unknown>\n  at: number\n}\n\n/** Deliver an alert. Implementations MUST NOT throw — see\n *  {@link createGuardedAlertSink}. */\nexport interface AlertSink {\n  deliver(alert: TurnHealthAlert): Promise<void>\n}\n\n/** Build the alert for a set of reasons found on one turn. */\nexport function turnAlert(input: {\n  product: string\n  severity: TurnHealthSeverity\n  reasons: TurnHealthReason[]\n  threadId?: string\n  turnId?: string\n  model?: string\n  at?: number\n}): TurnHealthAlert {\n  const kinds = [...new Set(input.reasons.map((r) => r.kind))].sort()\n  return {\n    product: input.product,\n    severity: input.severity,\n    // Keyed by product + reason kinds ONLY. A blank-completion storm across\n    // 200 turns is one incident, not 200 pages.\n    key: `turn:${input.product}:${kinds.join('+')}`,\n    title: `${input.product}: turn completed but delivered nothing (${kinds.join(', ')})`,\n    details: input.reasons.map(describeReason),\n    data: {\n      kinds,\n      ...(input.threadId ? { threadId: input.threadId } : {}),\n      ...(input.turnId ? { turnId: input.turnId } : {}),\n      ...(input.model ? { model: input.model } : {}),\n    },\n    at: input.at ?? Date.now(),\n  }\n}\n\n// ── transports ────────────────────────────────────────────────────────────\n\n/** Minimal structural fetch, so this module has no lib-dom dependency and can\n *  be driven by a fake in tests. */\nexport type FetchLike = (\n  url: string,\n  init: { method: string; headers: Record<string, string>; body: string },\n) => Promise<{ ok: boolean; status: number; text?(): Promise<string> }>\n\n/**\n * POST to an incoming webhook in the Slack message format.\n *\n * Chosen because the org already runs one (`SLACK_OPS_WEBHOOK_URL`) and\n * gtm-agent's outbound webhook code already speaks this exact shape — the\n * instruction was to route somewhere humans already look, not to stand up a\n * new channel. Discord and most log drains accept the same `{text}` body.\n */\nexport function createWebhookAlertSink(options: {\n  webhookUrl: string\n  fetchImpl?: FetchLike\n}): AlertSink {\n  const fetchImpl = options.fetchImpl ?? (globalThis.fetch as unknown as FetchLike)\n  return {\n    async deliver(alert) {\n      const icon = alert.severity === 'critical' ? ':rotating_light:' : ':warning:'\n      const lines = [\n        `${icon} *${alert.title}*`,\n        ...alert.details.map((d) => `• ${d}`),\n        `_${new Date(alert.at).toISOString()}_`,\n      ]\n      const response = await fetchImpl(options.webhookUrl, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ text: lines.join('\\n') }),\n      })\n      if (!response.ok) {\n        // A dropped alert is a silent failure of the silent-failure detector.\n        // It must be loud in the one place that is still working: the log.\n        throw new Error(`alert webhook responded ${response.status}`)\n      }\n    },\n  }\n}\n\n/** stderr sink. The zero-config fallback so a product that has not yet been\n *  given a webhook still emits something a log search can find. */\nexport function createConsoleAlertSink(log: (message: string) => void = console.error): AlertSink {\n  return {\n    async deliver(alert) {\n      log(\n        `[turn-health] ${alert.severity.toUpperCase()} ${alert.title} :: ${alert.details.join(' | ')}`,\n      )\n    },\n  }\n}\n\n/** Fan out to several sinks. One failing transport must not stop the others. */\nexport function createMultiAlertSink(sinks: readonly AlertSink[]): AlertSink {\n  return {\n    async deliver(alert) {\n      const settled = await Promise.allSettled(sinks.map((s) => s.deliver(alert)))\n      const failures = settled.filter((r) => r.status === 'rejected')\n      if (failures.length === sinks.length && sinks.length > 0) {\n        throw new Error('every alert sink failed')\n      }\n    },\n  }\n}\n\n// ── throttling ────────────────────────────────────────────────────────────\n\n/** Records the last time a key was alerted on. A product backs this with KV,\n *  D1, or a Durable Object; the in-memory default is correct for a sweep that\n *  runs as a single cron invocation. */\nexport interface AlertThrottleStore {\n  lastSentAt(key: string): Promise<number | null>\n  markSent(key: string, at: number): Promise<void>\n}\n\n/** Process-local throttle store. */\nexport function createMemoryThrottleStore(): AlertThrottleStore {\n  const seen = new Map<string, number>()\n  return {\n    async lastSentAt(key) {\n      return seen.get(key) ?? null\n    },\n    async markSent(key, at) {\n      seen.set(key, at)\n    },\n  }\n}\n\n/**\n * Collapse repeats of the same `key` inside `windowMs`.\n *\n * Deliberately re-alerts once per window rather than going silent after the\n * first: an incident that is still burning must keep saying so. Going quiet\n * after one message is how a 17-day outage stays invisible after someone\n * dismisses the first notification.\n */\nexport function createThrottledAlertSink(\n  inner: AlertSink,\n  options: { windowMs: number; store?: AlertThrottleStore },\n): AlertSink {\n  const store = options.store ?? createMemoryThrottleStore()\n  return {\n    async deliver(alert) {\n      const last = await store.lastSentAt(alert.key)\n      if (last !== null && alert.at - last < options.windowMs) return\n      await inner.deliver(alert)\n      await store.markSent(alert.key, alert.at)\n    },\n  }\n}\n\n/**\n * Swallow transport errors so telemetry can never fail the turn it measures.\n *\n * Use this at the LIVE lifecycle call site only. A sweep should let the error\n * surface, because a sweep that cannot deliver has done nothing at all and its\n * cron run should go red.\n */\nexport function createGuardedAlertSink(\n  inner: AlertSink,\n  onError: (error: unknown) => void = (e) => console.error('[turn-health] alert delivery failed', e),\n): AlertSink {\n  return {\n    async deliver(alert) {\n      try {\n        await inner.deliver(alert)\n      } catch (error) {\n        onError(error)\n      }\n    },\n  }\n}\n","/**\n * The LIVE half: judge each turn the moment it settles.\n *\n * This adds no control flow. `createChatTurnRoutes` already exposes a\n * `lifecycle` seam that fires exactly one of `onTurnComplete`/`onTurnError`\n * after a turn settles, and already swallows hook errors so telemetry cannot\n * fail a turn. That seam was shipped and then wired by nobody, which is a fair\n * description of why the outage lasted 17 days. This function fills it.\n *\n * The shape is declared structurally rather than imported from\n * `/chat-routes`, so `/turn-health` stays free of the server chat vertical and\n * can be used by any turn driver that reports the same three moments.\n */\n\nimport { classifyTurnOutcome } from './classify.js'\nimport { type AlertSink, createGuardedAlertSink, turnAlert } from './sink.js'\n\n/** Structural mirror of `/chat-routes`' `ChatTurnLifecycle` complete payload. */\nexport interface TurnHealthCompleteInfo {\n  finalText: string\n  usage?: { outputTokens?: number | null } | null\n  durationMs: number\n  threadId?: string\n  turnStreamId?: string\n  executionId?: string\n}\n\n/** Structural mirror of the lifecycle error payload. */\nexport interface TurnHealthErrorInfo {\n  error: unknown\n  durationMs: number\n  threadId?: string\n  turnStreamId?: string\n  executionId?: string\n}\n\n/** What {@link createTurnHealthLifecycle} returns — assignable to\n *  `createChatTurnRoutes`' `lifecycle` option. */\nexport interface TurnHealthLifecycle {\n  onTurnComplete(info: TurnHealthCompleteInfo): Promise<void>\n  onTurnError(info: TurnHealthErrorInfo): Promise<void>\n}\n\nexport interface TurnHealthLifecycleOptions {\n  /** Names the product in every alert. */\n  product: string\n  sink: AlertSink\n  /** Called for every verdict, healthy or not — the hook for a counter or a\n   *  metrics push. Alerts are for humans; this is for graphs. */\n  onVerdict?(verdict: {\n    product: string\n    healthy: boolean\n    kinds: string[]\n    durationMs: number\n  }): void\n}\n\nfunction errorText(error: unknown): string {\n  if (error instanceof Error) return error.message\n  if (typeof error === 'string') return error\n  return String(error)\n}\n\n/**\n * Build the lifecycle hooks that page on a turn which succeeded at nothing.\n *\n * The live lane sees `finalText` and usage but not the persisted parts, so it\n * catches the blank-completion and hard-failure shapes immediately. The\n * parts-dependent shapes (a tool call whose arguments never parsed, a tool\n * call that left no effect) are caught by {@link sweepSilentFailures}, which\n * reads what was actually written to the store — the honest place to ask\n * whether an effect persisted.\n */\nexport function createTurnHealthLifecycle(\n  options: TurnHealthLifecycleOptions,\n): TurnHealthLifecycle {\n  // Guarded: a paging failure must never take down a customer's turn.\n  const sink = createGuardedAlertSink(options.sink)\n\n  return {\n    async onTurnComplete(info) {\n      const verdict = classifyTurnOutcome({\n        finalText: info.finalText,\n        outputTokens: info.usage?.outputTokens ?? null,\n        durationMs: info.durationMs,\n      })\n      options.onVerdict?.({\n        product: options.product,\n        healthy: verdict.healthy,\n        kinds: verdict.reasons.map((r) => r.kind),\n        durationMs: info.durationMs,\n      })\n      if (verdict.healthy || verdict.severity === null) return\n      await sink.deliver(\n        turnAlert({\n          product: options.product,\n          severity: verdict.severity,\n          reasons: verdict.reasons,\n          ...(info.threadId ? { threadId: info.threadId } : {}),\n          ...(info.executionId ? { turnId: info.executionId } : {}),\n        }),\n      )\n    },\n\n    async onTurnError(info) {\n      const verdict = classifyTurnOutcome({\n        failed: true,\n        failureReason: errorText(info.error),\n        durationMs: info.durationMs,\n      })\n      options.onVerdict?.({\n        product: options.product,\n        healthy: false,\n        kinds: verdict.reasons.map((r) => r.kind),\n        durationMs: info.durationMs,\n      })\n      await sink.deliver(\n        turnAlert({\n          product: options.product,\n          severity: 'critical',\n          reasons: verdict.reasons,\n          ...(info.threadId ? { threadId: info.threadId } : {}),\n          ...(info.executionId ? { turnId: info.executionId } : {}),\n        }),\n      )\n    },\n  }\n}\n","/**\n * The SWEEP half: ask the store what it has been quietly accumulating.\n *\n * A live per-turn hook cannot see the failure that matters most, because the\n * worst outage produced NO turns at all to hook: gtm-agent took 9–21 user\n * messages a day for sixteen straight days and wrote zero real assistant\n * replies. Nothing crashed on a schedule; the product simply stopped\n * answering. The only thing that could have noticed is something that\n * periodically counts what arrived against what was answered.\n *\n * That is this. It runs on a cron, reads the shared `/chat-store` schema, and\n * pages when the ratio breaks.\n *\n * The queries live HERE and not in each product because all four products\n * (gtm, tax, legal, workcomp) persist to the same `message`/`thread` tables —\n * four copies of this cron is exactly the duplication the repo's engine/shell\n * rule exists to prevent.\n */\n\nimport { classifyTurnOutcome, describeReason, type TurnHealthReason } from './classify.js'\nimport type { AlertSink, TurnHealthAlert } from './sink.js'\n\n/** A thread that has taken user messages with no reply since. */\nexport interface UnansweredThread {\n  threadId: string\n  /** User messages newer than the newest real assistant reply. */\n  pendingMessages: number\n  /** Age of the OLDEST unanswered user message, in ms. */\n  oldestAgeMs: number\n}\n\n/** A persisted assistant row, as the sweep needs to judge it. */\nexport interface PersistedTurnRow {\n  id: string\n  threadId: string\n  content: string\n  /** Raw `parts` column. A JSON string or an already-parsed array; the sweep\n   *  accepts both because D1 drivers differ. */\n  parts: unknown\n  outputTokens?: number | null\n  model?: string | null\n  createdAt: number\n}\n\n/** What the sweep needs from a store. A product on a non-standard schema\n *  implements these two reads; everything else is shared. */\nexport interface TurnHealthSource {\n  findUnansweredThreads(input: { minAgeMs: number; now: number }): Promise<UnansweredThread[]>\n  listRecentAssistantTurns(input: { sinceMs: number; now: number; limit: number }): Promise<\n    PersistedTurnRow[]\n  >\n}\n\nexport interface SweepOptions {\n  product: string\n  source: TurnHealthSource\n  sink: AlertSink\n  /** A user message must go unanswered this long before it counts. Guards\n   *  against alerting on a turn that is simply still streaming. Default 15 min. */\n  minAgeMs?: number\n  /** How far back to judge settled turns. Default 24 h. */\n  lookbackMs?: number\n  /** Cap on rows judged per sweep. Default 500. */\n  limit?: number\n  /** Fraction of recent turns allowed to be silently broken before paging.\n   *  Default 0.05 — the measured blank-completion rate on the tax tool surface\n   *  was 12.2%, so 5% separates a real regression from noise. */\n  emptyRateThreshold?: number\n  /** Absolute floor: never page on a rate computed from fewer turns than this. */\n  minTurnsForRate?: number\n  now?: number\n}\n\n/** What the sweep found. Returned as well as alerted, so a cron can log it and\n *  a test can assert on it. */\nexport interface SweepResult {\n  product: string\n  unansweredThreads: number\n  pendingUserMessages: number\n  oldestUnansweredMs: number\n  turnsJudged: number\n  unhealthyTurns: number\n  emptyCompletions: number\n  malformedToolCalls: number\n  toolCallsWithoutEffect: number\n  alerts: TurnHealthAlert[]\n}\n\nfunction parseParts(raw: unknown): unknown[] {\n  if (Array.isArray(raw)) return raw\n  if (typeof raw !== 'string' || raw.trim().length === 0) return []\n  try {\n    const parsed = JSON.parse(raw)\n    return Array.isArray(parsed) ? parsed : []\n  } catch {\n    // A parts column that is not JSON is itself a corruption worth seeing, but\n    // it is not this detector's job — treat as no parts rather than throwing.\n    return []\n  }\n}\n\nconst HOUR_MS = 3_600_000\n\n/**\n * Run one sweep and deliver whatever it finds.\n *\n * Errors from the sink are NOT swallowed here (unlike the live lane): a sweep\n * that could not deliver has accomplished nothing, and its cron invocation\n * should go red rather than report a clean run.\n */\nexport async function sweepSilentFailures(options: SweepOptions): Promise<SweepResult> {\n  const now = options.now ?? Date.now()\n  const minAgeMs = options.minAgeMs ?? 15 * 60_000\n  const lookbackMs = options.lookbackMs ?? 24 * HOUR_MS\n  const limit = options.limit ?? 500\n  const emptyRateThreshold = options.emptyRateThreshold ?? 0.05\n  const minTurnsForRate = options.minTurnsForRate ?? 10\n\n  const [unanswered, turns] = await Promise.all([\n    options.source.findUnansweredThreads({ minAgeMs, now }),\n    options.source.listRecentAssistantTurns({ sinceMs: now - lookbackMs, now, limit }),\n  ])\n\n  const alerts: TurnHealthAlert[] = []\n\n  // ── silence: messages in, nothing out ──────────────────────────────────\n  const pendingUserMessages = unanswered.reduce((sum, t) => sum + t.pendingMessages, 0)\n  const oldestUnansweredMs = unanswered.reduce((max, t) => Math.max(max, t.oldestAgeMs), 0)\n\n  if (unanswered.length > 0) {\n    const hours = (oldestUnansweredMs / HOUR_MS).toFixed(1)\n    alerts.push({\n      product: options.product,\n      // A day of total silence is not a warning.\n      severity: oldestUnansweredMs >= 24 * HOUR_MS ? 'critical' : 'warning',\n      key: `sweep:${options.product}:unanswered_threads`,\n      title: `${options.product}: ${pendingUserMessages} user message(s) unanswered across ${unanswered.length} thread(s)`,\n      details: [\n        `oldest unanswered message: ${hours}h`,\n        ...unanswered\n          .slice(0, 5)\n          .map(\n            (t) =>\n              `thread ${t.threadId}: ${t.pendingMessages} pending, oldest ${(\n                t.oldestAgeMs / HOUR_MS\n              ).toFixed(1)}h`,\n          ),\n      ],\n      data: {\n        unansweredThreads: unanswered.length,\n        pendingUserMessages,\n        oldestUnansweredMs,\n      },\n      at: now,\n    })\n  }\n\n  // ── success that delivered nothing ─────────────────────────────────────\n  let emptyCompletions = 0\n  let malformedToolCalls = 0\n  let toolCallsWithoutEffect = 0\n  let unhealthyTurns = 0\n  const malformedSamples: TurnHealthReason[] = []\n\n  for (const row of turns) {\n    const verdict = classifyTurnOutcome({\n      finalText: row.content,\n      parts: parseParts(row.parts),\n      outputTokens: row.outputTokens ?? null,\n    })\n    if (verdict.healthy) continue\n    unhealthyTurns += 1\n    for (const reason of verdict.reasons) {\n      if (reason.kind === 'empty_completion') emptyCompletions += 1\n      if (reason.kind === 'malformed_tool_call') {\n        malformedToolCalls += 1\n        if (malformedSamples.length < 3) malformedSamples.push(reason)\n      }\n      if (reason.kind === 'tool_call_no_effect') toolCallsWithoutEffect += 1\n    }\n  }\n\n  // A malformed tool call is never acceptable at any rate — it means a\n  // deliverable was requested and silently discarded. Page on the first one.\n  if (malformedToolCalls > 0) {\n    alerts.push({\n      product: options.product,\n      severity: 'critical',\n      key: `sweep:${options.product}:malformed_tool_call`,\n      title: `${options.product}: ${malformedToolCalls} tool call(s) had unparseable arguments — deliverables silently dropped`,\n      details: malformedSamples.map(describeReason),\n      data: { malformedToolCalls, turnsJudged: turns.length },\n      at: now,\n    })\n  }\n\n  if (turns.length >= minTurnsForRate) {\n    const rate = emptyCompletions / turns.length\n    if (rate > emptyRateThreshold) {\n      alerts.push({\n        product: options.product,\n        severity: 'critical',\n        key: `sweep:${options.product}:empty_completion_rate`,\n        title: `${options.product}: ${(rate * 100).toFixed(1)}% of turns completed with no output`,\n        details: [\n          `${emptyCompletions} of ${turns.length} settled turns delivered nothing`,\n          `threshold ${(emptyRateThreshold * 100).toFixed(1)}%`,\n        ],\n        data: { emptyCompletions, turnsJudged: turns.length, rate },\n        at: now,\n      })\n    }\n  }\n\n  for (const alert of alerts) await options.sink.deliver(alert)\n\n  return {\n    product: options.product,\n    unansweredThreads: unanswered.length,\n    pendingUserMessages,\n    oldestUnansweredMs,\n    turnsJudged: turns.length,\n    unhealthyTurns,\n    emptyCompletions,\n    malformedToolCalls,\n    toolCallsWithoutEffect,\n    alerts,\n  }\n}\n\n// ── D1 source for the shared chat-store schema ────────────────────────────\n\n/** Minimal structural D1 contract (Cloudflare's `D1Database` satisfies it). */\nexport interface D1LikeForHealth {\n  prepare(sql: string): {\n    bind(...values: unknown[]): {\n      all<T = Record<string, unknown>>(): Promise<{ results: T[] }>\n    }\n  }\n}\n\n/**\n * The sweep source for products on the canonical `/chat-store` tables.\n *\n * \"Answered\" deliberately means an assistant row with NON-EMPTY content. A\n * blank assistant row is what a broken turn writes, so counting it as an\n * answer would let the exact failure being hunted mark itself resolved. That\n * single predicate is the difference between this catching the gtm outage and\n * sleeping through it — during those sixteen days the table was NOT empty.\n *\n * The query deliberately does NOT join the thread table. Products do not all\n * keep one: tax-agent's `thread` table holds zero rows because it groups by\n * its own `tax_sessions`, and an inner join against it silently reported \"0\n * unanswered threads, healthy\" while 18 real messages sat unanswered. A\n * detector that reports healthy because its join found nothing is the same\n * bug class it was built to catch.\n */\nexport function createD1TurnHealthSource(\n  db: D1LikeForHealth,\n  options: { messageTable?: string; threadTable?: string } = {},\n): TurnHealthSource {\n  // Table names are identifiers and cannot be bound as parameters. They come\n  // from deploy-time product config, never from a request, and are validated\n  // here so this can never become an injection point.\n  const message = safeIdentifier(options.messageTable ?? 'message')\n  const thread = safeIdentifier(options.threadTable ?? 'thread')\n\n  return {\n    async findUnansweredThreads({ minAgeMs, now }) {\n      const cutoffSeconds = Math.floor((now - minAgeMs) / 1000)\n      const { results } = await db\n        .prepare(\n          `SELECT m.thread_id AS threadId,\n                  COUNT(*) AS pendingMessages,\n                  MIN(m.created_at) AS oldestCreatedAt\n             FROM ${message} m\n            WHERE m.role = 'user'\n              AND m.created_at <= ?1\n              AND m.created_at > COALESCE(\n                    (SELECT MAX(a.created_at)\n                       FROM ${message} a\n                      WHERE a.thread_id = m.thread_id\n                        AND a.role = 'assistant'\n                        AND length(trim(a.content)) > 0), 0)\n            GROUP BY m.thread_id\n            ORDER BY oldestCreatedAt ASC`,\n        )\n        .bind(cutoffSeconds)\n        .all<{ threadId: string; pendingMessages: number; oldestCreatedAt: number }>()\n\n      return results.map((row) => ({\n        threadId: row.threadId,\n        pendingMessages: Number(row.pendingMessages),\n        oldestAgeMs: now - Number(row.oldestCreatedAt) * 1000,\n      }))\n    },\n\n    async listRecentAssistantTurns({ sinceMs, limit }) {\n      const sinceSeconds = Math.floor(sinceMs / 1000)\n      const { results } = await db\n        .prepare(\n          `SELECT id, thread_id AS threadId, content, parts,\n                  output_tokens AS outputTokens, model, created_at AS createdAt\n             FROM ${message}\n            WHERE role = 'assistant' AND created_at >= ?1\n            ORDER BY created_at DESC\n            LIMIT ?2`,\n        )\n        .bind(sinceSeconds, limit)\n        .all<Record<string, unknown>>()\n\n      return results.map((row) => ({\n        id: String(row.id),\n        threadId: String(row.threadId),\n        content: typeof row.content === 'string' ? row.content : '',\n        parts: row.parts,\n        outputTokens: row.outputTokens === null ? null : Number(row.outputTokens),\n        model: (row.model as string | null) ?? null,\n        createdAt: Number(row.createdAt) * 1000,\n      }))\n    },\n  }\n\n  function safeIdentifier(name: string): string {\n    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {\n      throw new Error(`unsafe table identifier: ${name}`)\n    }\n    return name\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/turn-health/classify.ts","../../src/turn-health/sink.ts","../../src/turn-health/lifecycle.ts","../../src/turn-health/sweep.ts"],"sourcesContent":["/**\n * The classifier for turns that FAIL BY RETURNING SUCCESS.\n *\n * Every failure this module names shipped to a customer with HTTP 200, no\n * thrown error, and no log line anyone read. Three were measured in production\n * in a single week:\n *\n *   - a turn settled `{\"outcome\":{\"type\":\"completed\"},\"finalText\":\"\",\n *     \"tokenUsage\":{\"outputTokens\":0}}` — the customer saw a blank bubble;\n *   - six `submit_proposal` tool calls collapsed into ONE whose arguments were\n *     a 1,652-character non-JSON string, so zero proposals persisted and\n *     nothing errored (agent-runtime #626);\n *   - a thread took 255 user messages over 17 days and produced 2 replies,\n *     both of them error text.\n *\n * A conventional health check cannot see any of these, because it probes\n * DEPENDENCIES (is the sandbox reachable, is the router up) and every one of\n * these failures happens with all dependencies green. This classifier probes\n * the OUTCOME instead.\n *\n * It is deliberately pure and structural: it reads a settled turn's own\n * projection, so the SAME function judges a live turn through the\n * `/chat-routes` lifecycle seam and a historical row read back out of the\n * store during a sweep. One definition of \"silently broken\", two call sites.\n */\n\n/** How loudly a reason should be routed. `critical` means a customer got\n *  nothing usable; `warning` means the turn degraded but still produced\n *  something a human could read. */\nexport type TurnHealthSeverity = 'critical' | 'warning'\n\n/** One specific way a turn returned success while failing.\n *\n *  Each variant carries the evidence that identified it, so an alert can name\n *  the offending value instead of asserting a verdict the reader has to take\n *  on faith. */\nexport type TurnHealthReason =\n  /** Settled without error and produced nothing a user can read: no text, and\n   *  no artifact part (file/image/work-product/plan/interaction). This is the\n   *  verbatim blank-completion capture. */\n  | {\n      kind: 'empty_completion'\n      outputTokens: number | null\n      partCount: number\n      durationMs?: number\n    }\n  /** A tool call whose arguments never parsed. The engine surfaces unparseable\n   *  arguments as a RAW STRING rather than throwing, so the call is neither\n   *  dropped nor errored — it silently does nothing. Detecting a string-typed\n   *  tool input that fails `JSON.parse` is the exact fingerprint of the\n   *  index-less parallel-tool-call collapse. */\n  | {\n      kind: 'malformed_tool_call'\n      tool: string\n      inputLength: number\n      /** Leading characters of the offending input, for the alert body. */\n      sample: string\n    }\n  /** A tool call that never reached a terminal state carrying output. The call\n   *  was issued and then simply produced no effect. */\n  | {\n      kind: 'tool_call_no_effect'\n      tool: string\n      status: string\n    }\n  /** The turn failed outright. Not silent by itself — but it becomes silent\n   *  the moment nothing is watching, which is how 16 days of\n   *  `TANGLE_HUB_URL is required` reached customers unnoticed. */\n  | { kind: 'turn_failed'; reason: string }\n\n/** A settled turn, in the narrowest shape both call sites can supply.\n *\n *  Structural on purpose: the lifecycle seam supplies `finalText`/`usage`, a\n *  store sweep supplies `content`/`parts` read back from a row, and neither\n *  has to import the other's types. */\nexport interface TurnOutcomeInput {\n  /** The turn's final assistant text. */\n  finalText?: string | null\n  /** The persisted assistant parts. Untyped by design — a sweep reads these\n   *  out of a JSON column and must not be forced to validate them first. */\n  parts?: readonly unknown[] | null\n  /** Output tokens, when the caller has usage. `null`/absent is unknown, which\n   *  is NOT the same as zero and is never treated as evidence. */\n  outputTokens?: number | null\n  /** Set when the turn surfaced a terminal error event. */\n  failed?: boolean\n  failureReason?: string | null\n  durationMs?: number\n}\n\n/** The verdict for one turn. `healthy` is exactly `reasons.length === 0`, kept\n *  as a field so callers read intent rather than an array length. */\nexport interface TurnHealthVerdict {\n  healthy: boolean\n  severity: TurnHealthSeverity | null\n  reasons: TurnHealthReason[]\n}\n\n/** Part kinds that count as something a user actually receives.\n *\n *  A tool part is deliberately NOT here. A turn that ran six tools and said\n *  nothing, with no artifact to show for it, is the malformed-tool-call\n *  disaster — counting a tool chip as output would suppress the very alert\n *  this module exists to raise. */\nconst ARTIFACT_PART_KINDS = new Set(['file', 'image', 'work-product', 'plan', 'interaction'])\n\nconst SAMPLE_CHARS = 120\n\nfunction asRecord(value: unknown): Record<string, unknown> | null {\n  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : null\n}\n\nfunction nonEmptyString(value: unknown): string | null {\n  return typeof value === 'string' && value.trim().length > 0 ? value : null\n}\n\n/** True when a string is not parseable JSON.\n *\n *  Only meaningful for tool INPUT, where the engine's contract is that a\n *  well-formed call carries an object (or a string that parses into one). A\n *  string that fails to parse means the arguments were concatenated or\n *  truncated upstream. */\nfunction isUnparseableJson(value: string): boolean {\n  const trimmed = value.trim()\n  if (trimmed.length === 0) return false\n  try {\n    JSON.parse(trimmed)\n    return false\n  } catch {\n    return true\n  }\n}\n\n/** Tool statuses that mean the call actually landed.\n *\n *  Anything else — `pending`, `running`, `error`, an unknown string — left no\n *  persisted effect by the time the turn settled. */\nconst SETTLED_TOOL_STATUSES = new Set(['completed', 'complete', 'success', 'done'])\n\n/**\n * Judge one settled turn.\n *\n * Never throws: a malformed `parts` blob is a thing this function REPORTS on,\n * so it must not be a thing it dies on. Telemetry that can crash the turn it\n * measures is worse than no telemetry.\n */\nexport function classifyTurnOutcome(input: TurnOutcomeInput): TurnHealthVerdict {\n  const reasons: TurnHealthReason[] = []\n\n  if (input.failed) {\n    reasons.push({\n      kind: 'turn_failed',\n      reason: nonEmptyString(input.failureReason) ?? 'unspecified',\n    })\n  }\n\n  const parts = Array.isArray(input.parts) ? input.parts : []\n\n  let hasVisibleText = nonEmptyString(input.finalText) !== null\n  let artifactCount = 0\n\n  for (const raw of parts) {\n    const part = asRecord(raw)\n    if (!part) continue\n    const type = typeof part.type === 'string' ? part.type : ''\n\n    if (type === 'text' && nonEmptyString(part.text) !== null) {\n      hasVisibleText = true\n      continue\n    }\n    if (ARTIFACT_PART_KINDS.has(type)) {\n      artifactCount += 1\n      continue\n    }\n    if (type !== 'tool') continue\n\n    const tool = nonEmptyString(part.tool) ?? 'unknown'\n    const state = asRecord(part.state)\n    const status = typeof state?.status === 'string' ? state.status : 'unknown'\n\n    // The #626 fingerprint: arguments surfaced as a raw string because they\n    // failed to parse upstream. Checked before the status gate — a malformed\n    // call can still be marked completed, which is precisely why it is silent.\n    const toolInput = state?.input\n    if (typeof toolInput === 'string' && isUnparseableJson(toolInput)) {\n      reasons.push({\n        kind: 'malformed_tool_call',\n        tool,\n        inputLength: toolInput.length,\n        sample: toolInput.slice(0, SAMPLE_CHARS),\n      })\n      continue\n    }\n\n    if (!SETTLED_TOOL_STATUSES.has(status)) {\n      reasons.push({ kind: 'tool_call_no_effect', tool, status })\n    }\n  }\n\n  // `outputTokens` is corroborating evidence, never the trigger: a turn can\n  // spend tokens on reasoning and still deliver nothing, and a turn with\n  // unknown usage can still be perfectly fine.\n  if (!input.failed && !hasVisibleText && artifactCount === 0) {\n    reasons.push({\n      kind: 'empty_completion',\n      outputTokens: input.outputTokens ?? null,\n      partCount: parts.length,\n      ...(input.durationMs !== undefined ? { durationMs: input.durationMs } : {}),\n    })\n  }\n\n  return {\n    healthy: reasons.length === 0,\n    severity: severityOf(reasons),\n    reasons,\n  }\n}\n\n/** `critical` when the customer got nothing usable out of the turn. A\n *  malformed tool call alongside readable text is a `warning` — degraded, but\n *  a human still received an answer. */\nfunction severityOf(reasons: TurnHealthReason[]): TurnHealthSeverity | null {\n  if (reasons.length === 0) return null\n  const critical = reasons.some((r) => r.kind === 'empty_completion' || r.kind === 'turn_failed')\n  return critical ? 'critical' : 'warning'\n}\n\n/** One-line human summary of a reason, for an alert body. */\nexport function describeReason(reason: TurnHealthReason): string {\n  switch (reason.kind) {\n    case 'empty_completion':\n      return `completed with NO output (${reason.partCount} parts, outputTokens=${\n        reason.outputTokens ?? 'unknown'\n      })`\n    case 'malformed_tool_call':\n      return `tool \\`${reason.tool}\\` arguments did not parse (${reason.inputLength} chars): ${reason.sample}`\n    case 'tool_call_no_effect':\n      return `tool \\`${reason.tool}\\` left no effect (status=${reason.status})`\n    case 'turn_failed':\n      return `turn failed: ${reason.reason}`\n  }\n}\n","/**\n * Where a silent-failure verdict GOES.\n *\n * The detection half is worthless without this half. Every failure this module\n * finds was already visible in the database the whole time — 255 unanswered\n * messages sat in a table for 17 days. What was missing was not the data, it\n * was delivery to a human who had not thought to look.\n *\n * So the sink is a seam, not a channel: the product supplies the transport,\n * and agent-app ships the two shapes the fleet already has credentials for\n * (an ops webhook, and stderr). No new channel is invented here.\n */\n\nimport { describeReason, type TurnHealthReason, type TurnHealthSeverity } from './classify.js'\n\n/** One deliverable alert. */\nexport interface TurnHealthAlert {\n  /** Which product raised it (`projectId`). Alerts from four products land in\n   *  one channel, so this is what makes the message actionable. */\n  product: string\n  severity: TurnHealthSeverity\n  /** Stable grouping key. Throttling is keyed on this, so it must NOT contain\n   *  a turn id or a timestamp or every alert is unique and nothing dedupes. */\n  key: string\n  title: string\n  /** Human-readable lines. */\n  details: string[]\n  /** Structured payload for a machine consumer. */\n  data?: Record<string, unknown>\n  at: number\n}\n\n/** Deliver an alert. Implementations MUST NOT throw — see\n *  {@link createGuardedAlertSink}. */\nexport interface AlertSink {\n  deliver(alert: TurnHealthAlert): Promise<void>\n}\n\n/** Build the alert for a set of reasons found on one turn. */\nexport function turnAlert(input: {\n  product: string\n  severity: TurnHealthSeverity\n  reasons: TurnHealthReason[]\n  threadId?: string\n  turnId?: string\n  model?: string\n  at?: number\n}): TurnHealthAlert {\n  const kinds = [...new Set(input.reasons.map((r) => r.kind))].sort()\n  return {\n    product: input.product,\n    severity: input.severity,\n    // Keyed by product + reason kinds ONLY. A blank-completion storm across\n    // 200 turns is one incident, not 200 pages.\n    key: `turn:${input.product}:${kinds.join('+')}`,\n    title: `${input.product}: turn completed but delivered nothing (${kinds.join(', ')})`,\n    details: input.reasons.map(describeReason),\n    data: {\n      kinds,\n      ...(input.threadId ? { threadId: input.threadId } : {}),\n      ...(input.turnId ? { turnId: input.turnId } : {}),\n      ...(input.model ? { model: input.model } : {}),\n    },\n    at: input.at ?? Date.now(),\n  }\n}\n\n// ── transports ────────────────────────────────────────────────────────────\n\n/** Minimal structural fetch, so this module has no lib-dom dependency and can\n *  be driven by a fake in tests. */\nexport type FetchLike = (\n  url: string,\n  init: { method: string; headers: Record<string, string>; body: string },\n) => Promise<{ ok: boolean; status: number; text?(): Promise<string> }>\n\n/**\n * POST to an incoming webhook in the Slack message format.\n *\n * Chosen because the org already runs one (`SLACK_OPS_WEBHOOK_URL`) and\n * gtm-agent's outbound webhook code already speaks this exact shape — the\n * instruction was to route somewhere humans already look, not to stand up a\n * new channel. Discord and most log drains accept the same `{text}` body.\n */\nexport function createWebhookAlertSink(options: {\n  webhookUrl: string\n  fetchImpl?: FetchLike\n}): AlertSink {\n  const fetchImpl = options.fetchImpl ?? (globalThis.fetch as unknown as FetchLike)\n  return {\n    async deliver(alert) {\n      const icon = alert.severity === 'critical' ? ':rotating_light:' : ':warning:'\n      const lines = [\n        `${icon} *${alert.title}*`,\n        ...alert.details.map((d) => `• ${d}`),\n        `_${new Date(alert.at).toISOString()}_`,\n      ]\n      const response = await fetchImpl(options.webhookUrl, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ text: lines.join('\\n') }),\n      })\n      if (!response.ok) {\n        // A dropped alert is a silent failure of the silent-failure detector.\n        // It must be loud in the one place that is still working: the log.\n        throw new Error(`alert webhook responded ${response.status}`)\n      }\n    },\n  }\n}\n\n/** stderr sink. The zero-config fallback so a product that has not yet been\n *  given a webhook still emits something a log search can find. */\nexport function createConsoleAlertSink(log: (message: string) => void = console.error): AlertSink {\n  return {\n    async deliver(alert) {\n      log(\n        `[turn-health] ${alert.severity.toUpperCase()} ${alert.title} :: ${alert.details.join(' | ')}`,\n      )\n    },\n  }\n}\n\n/** Fan out to several sinks. One failing transport must not stop the others. */\nexport function createMultiAlertSink(sinks: readonly AlertSink[]): AlertSink {\n  return {\n    async deliver(alert) {\n      const settled = await Promise.allSettled(sinks.map((s) => s.deliver(alert)))\n      const failures = settled.filter((r) => r.status === 'rejected')\n      if (failures.length === sinks.length && sinks.length > 0) {\n        throw new Error('every alert sink failed')\n      }\n    },\n  }\n}\n\n// ── throttling ────────────────────────────────────────────────────────────\n\n/** Records the last time a key was alerted on. A product backs this with KV,\n *  D1, or a Durable Object; the in-memory default is correct for a sweep that\n *  runs as a single cron invocation. */\nexport interface AlertThrottleStore {\n  lastSentAt(key: string): Promise<number | null>\n  markSent(key: string, at: number): Promise<void>\n}\n\n/** Process-local throttle store. */\nexport function createMemoryThrottleStore(): AlertThrottleStore {\n  const seen = new Map<string, number>()\n  return {\n    async lastSentAt(key) {\n      return seen.get(key) ?? null\n    },\n    async markSent(key, at) {\n      seen.set(key, at)\n    },\n  }\n}\n\n/**\n * Collapse repeats of the same `key` inside `windowMs`.\n *\n * Deliberately re-alerts once per window rather than going silent after the\n * first: an incident that is still burning must keep saying so. Going quiet\n * after one message is how a 17-day outage stays invisible after someone\n * dismisses the first notification.\n */\nexport function createThrottledAlertSink(\n  inner: AlertSink,\n  options: { windowMs: number; store?: AlertThrottleStore },\n): AlertSink {\n  const store = options.store ?? createMemoryThrottleStore()\n  return {\n    async deliver(alert) {\n      const last = await store.lastSentAt(alert.key)\n      if (last !== null && alert.at - last < options.windowMs) return\n      await inner.deliver(alert)\n      await store.markSent(alert.key, alert.at)\n    },\n  }\n}\n\n/**\n * Swallow transport errors so telemetry can never fail the turn it measures.\n *\n * Use this at the LIVE lifecycle call site only. A sweep should let the error\n * surface, because a sweep that cannot deliver has done nothing at all and its\n * cron run should go red.\n */\nexport function createGuardedAlertSink(\n  inner: AlertSink,\n  onError: (error: unknown) => void = (e) => console.error('[turn-health] alert delivery failed', e),\n): AlertSink {\n  return {\n    async deliver(alert) {\n      try {\n        await inner.deliver(alert)\n      } catch (error) {\n        onError(error)\n      }\n    },\n  }\n}\n","/**\n * The LIVE half: judge each turn the moment it settles.\n *\n * This adds no control flow. `createChatTurnRoutes` already exposes a\n * `lifecycle` seam that fires exactly one of `onTurnComplete`/`onTurnError`\n * after a turn settles, and already swallows hook errors so telemetry cannot\n * fail a turn. That seam was shipped and then wired by nobody, which is a fair\n * description of why the outage lasted 17 days. This function fills it.\n *\n * The shape is declared structurally rather than imported from\n * `/chat-routes`, so `/turn-health` stays free of the server chat vertical and\n * can be used by any turn driver that reports the same three moments.\n */\n\nimport { classifyTurnOutcome } from './classify.js'\nimport { type AlertSink, createGuardedAlertSink, turnAlert } from './sink.js'\n\n/** Structural mirror of `/chat-routes`' `ChatTurnLifecycle` complete payload. */\nexport interface TurnHealthCompleteInfo {\n  finalText: string\n  usage?: { outputTokens?: number | null } | null\n  durationMs: number\n  threadId?: string\n  turnStreamId?: string\n  executionId?: string\n}\n\n/** Structural mirror of the lifecycle error payload. */\nexport interface TurnHealthErrorInfo {\n  error: unknown\n  durationMs: number\n  threadId?: string\n  turnStreamId?: string\n  executionId?: string\n}\n\n/** What {@link createTurnHealthLifecycle} returns — assignable to\n *  `createChatTurnRoutes`' `lifecycle` option. */\nexport interface TurnHealthLifecycle {\n  onTurnComplete(info: TurnHealthCompleteInfo): Promise<void>\n  onTurnError(info: TurnHealthErrorInfo): Promise<void>\n}\n\nexport interface TurnHealthLifecycleOptions {\n  /** Names the product in every alert. */\n  product: string\n  sink: AlertSink\n  /** Called for every verdict, healthy or not — the hook for a counter or a\n   *  metrics push. Alerts are for humans; this is for graphs. */\n  onVerdict?(verdict: {\n    product: string\n    healthy: boolean\n    kinds: string[]\n    durationMs: number\n  }): void\n}\n\nfunction errorText(error: unknown): string {\n  if (error instanceof Error) return error.message\n  if (typeof error === 'string') return error\n  return String(error)\n}\n\n/**\n * Build the lifecycle hooks that page on a turn which succeeded at nothing.\n *\n * The live lane sees `finalText` and usage but not the persisted parts, so it\n * catches the blank-completion and hard-failure shapes immediately. The\n * parts-dependent shapes (a tool call whose arguments never parsed, a tool\n * call that left no effect) are caught by {@link sweepSilentFailures}, which\n * reads what was actually written to the store — the honest place to ask\n * whether an effect persisted.\n */\nexport function createTurnHealthLifecycle(\n  options: TurnHealthLifecycleOptions,\n): TurnHealthLifecycle {\n  // Guarded: a paging failure must never take down a customer's turn.\n  const sink = createGuardedAlertSink(options.sink)\n\n  return {\n    async onTurnComplete(info) {\n      const verdict = classifyTurnOutcome({\n        finalText: info.finalText,\n        outputTokens: info.usage?.outputTokens ?? null,\n        durationMs: info.durationMs,\n      })\n      options.onVerdict?.({\n        product: options.product,\n        healthy: verdict.healthy,\n        kinds: verdict.reasons.map((r) => r.kind),\n        durationMs: info.durationMs,\n      })\n      if (verdict.healthy || verdict.severity === null) return\n      await sink.deliver(\n        turnAlert({\n          product: options.product,\n          severity: verdict.severity,\n          reasons: verdict.reasons,\n          ...(info.threadId ? { threadId: info.threadId } : {}),\n          ...(info.executionId ? { turnId: info.executionId } : {}),\n        }),\n      )\n    },\n\n    async onTurnError(info) {\n      const verdict = classifyTurnOutcome({\n        failed: true,\n        failureReason: errorText(info.error),\n        durationMs: info.durationMs,\n      })\n      options.onVerdict?.({\n        product: options.product,\n        healthy: false,\n        kinds: verdict.reasons.map((r) => r.kind),\n        durationMs: info.durationMs,\n      })\n      await sink.deliver(\n        turnAlert({\n          product: options.product,\n          severity: 'critical',\n          reasons: verdict.reasons,\n          ...(info.threadId ? { threadId: info.threadId } : {}),\n          ...(info.executionId ? { turnId: info.executionId } : {}),\n        }),\n      )\n    },\n  }\n}\n","/**\n * The SWEEP half: ask the store what it has been quietly accumulating.\n *\n * A live per-turn hook cannot see the failure that matters most, because the\n * worst outage produced NO turns at all to hook: gtm-agent took 9–21 user\n * messages a day for sixteen straight days and wrote zero real assistant\n * replies. Nothing crashed on a schedule; the product simply stopped\n * answering. The only thing that could have noticed is something that\n * periodically counts what arrived against what was answered.\n *\n * That is this. It runs on a cron, reads the shared `/chat-store` schema, and\n * pages when the ratio breaks.\n *\n * The queries live HERE and not in each product because all four products\n * (gtm, tax, legal, workcomp) persist to the same `message`/`thread` tables —\n * four copies of this cron is exactly the duplication the repo's engine/shell\n * rule exists to prevent.\n */\n\nimport { classifyTurnOutcome, describeReason, type TurnHealthReason } from './classify.js'\nimport type { AlertSink, TurnHealthAlert } from './sink.js'\n\n/** A thread that has taken user messages with no reply since. */\nexport interface UnansweredThread {\n  threadId: string\n  /** User messages newer than the newest real assistant reply. */\n  pendingMessages: number\n  /** Age of the OLDEST unanswered user message, in ms. */\n  oldestAgeMs: number\n}\n\n/** A persisted assistant row, as the sweep needs to judge it. */\nexport interface PersistedTurnRow {\n  id: string\n  threadId: string\n  content: string\n  /** Raw `parts` column. A JSON string or an already-parsed array; the sweep\n   *  accepts both because D1 drivers differ. */\n  parts: unknown\n  outputTokens?: number | null\n  model?: string | null\n  createdAt: number\n}\n\n/** What the sweep needs from a store. A product on a non-standard schema\n *  implements these two reads; everything else is shared. */\nexport interface TurnHealthSource {\n  findUnansweredThreads(input: {\n    minAgeMs: number\n    /** Ignore user messages older than this. See {@link SweepOptions.maxAgeMs}. */\n    maxAgeMs: number\n    now: number\n  }): Promise<UnansweredThread[]>\n  listRecentAssistantTurns(input: { sinceMs: number; now: number; limit: number }): Promise<\n    PersistedTurnRow[]\n  >\n}\n\nexport interface SweepOptions {\n  product: string\n  source: TurnHealthSource\n  sink: AlertSink\n  /** A user message must go unanswered this long before it counts. Guards\n   *  against alerting on a turn that is simply still streaming. Default 15 min. */\n  minAgeMs?: number\n  /**\n   * A user message OLDER than this is abandoned, not unanswered — it stops\n   * counting. Default 7 days.\n   *\n   * Without this bound the sweep is worse than useless. gtm-agent's table\n   * holds 384 unanswered messages whose oldest is 1,676 h (70 days) old;\n   * paging hourly on a backlog nobody will ever reply to is exactly how an\n   * alert channel gets muted, and a muted channel is the state this module\n   * exists to escape. The alert has to mean \"something broke recently\".\n   */\n  maxAgeMs?: number\n  /** How far back to judge settled turns. Default 24 h. */\n  lookbackMs?: number\n  /** Cap on rows judged per sweep. Default 500. */\n  limit?: number\n  /** Fraction of recent turns allowed to be silently broken before paging.\n   *  Default 0.05 — the measured blank-completion rate on the tax tool surface\n   *  was 12.2%, so 5% separates a real regression from noise. */\n  emptyRateThreshold?: number\n  /** Absolute floor: never page on a rate computed from fewer turns than this. */\n  minTurnsForRate?: number\n  now?: number\n}\n\n/** What the sweep found. Returned as well as alerted, so a cron can log it and\n *  a test can assert on it. */\nexport interface SweepResult {\n  product: string\n  unansweredThreads: number\n  pendingUserMessages: number\n  oldestUnansweredMs: number\n  turnsJudged: number\n  unhealthyTurns: number\n  emptyCompletions: number\n  malformedToolCalls: number\n  toolCallsWithoutEffect: number\n  alerts: TurnHealthAlert[]\n}\n\nfunction parseParts(raw: unknown): unknown[] {\n  if (Array.isArray(raw)) return raw\n  if (typeof raw !== 'string' || raw.trim().length === 0) return []\n  try {\n    const parsed = JSON.parse(raw)\n    return Array.isArray(parsed) ? parsed : []\n  } catch {\n    // A parts column that is not JSON is itself a corruption worth seeing, but\n    // it is not this detector's job — treat as no parts rather than throwing.\n    return []\n  }\n}\n\nconst HOUR_MS = 3_600_000\n\n/**\n * Assistant-row openers agent-app writes ITSELF when a sandbox turn fails.\n *\n * Kept byte-identical to the strings `createSandboxChatProducer` composes\n * (`src/chat-routes/sandbox-producer.ts`). They are shell vocabulary, not\n * product domain, so recognising them is this package's job — a product on\n * the shared producer gets a correct sweep with no configuration.\n *\n * `tests/turn-health/turn-health.test.ts` pins these against the producer, so\n * changing the producer's wording without changing this list fails CI rather\n * than silently making dead threads look answered.\n */\nexport const SHELL_ERROR_REPLY_PREFIXES: readonly string[] = [\n  'The sandbox model stream stopped before a clean completion.',\n  'The sandbox agent returned an error before producing a visible answer.',\n]\n\n/**\n * Run one sweep and deliver whatever it finds.\n *\n * Errors from the sink are NOT swallowed here (unlike the live lane): a sweep\n * that could not deliver has accomplished nothing, and its cron invocation\n * should go red rather than report a clean run.\n */\nexport async function sweepSilentFailures(options: SweepOptions): Promise<SweepResult> {\n  const now = options.now ?? Date.now()\n  const minAgeMs = options.minAgeMs ?? 15 * 60_000\n  const maxAgeMs = options.maxAgeMs ?? 7 * 24 * HOUR_MS\n  const lookbackMs = options.lookbackMs ?? 24 * HOUR_MS\n  const limit = options.limit ?? 500\n  const emptyRateThreshold = options.emptyRateThreshold ?? 0.05\n  const minTurnsForRate = options.minTurnsForRate ?? 10\n\n  const [unanswered, turns] = await Promise.all([\n    options.source.findUnansweredThreads({ minAgeMs, maxAgeMs, now }),\n    options.source.listRecentAssistantTurns({ sinceMs: now - lookbackMs, now, limit }),\n  ])\n\n  const alerts: TurnHealthAlert[] = []\n\n  // ── silence: messages in, nothing out ──────────────────────────────────\n  const pendingUserMessages = unanswered.reduce((sum, t) => sum + t.pendingMessages, 0)\n  const oldestUnansweredMs = unanswered.reduce((max, t) => Math.max(max, t.oldestAgeMs), 0)\n\n  if (unanswered.length > 0) {\n    const hours = (oldestUnansweredMs / HOUR_MS).toFixed(1)\n    alerts.push({\n      product: options.product,\n      // A day of total silence is not a warning.\n      severity: oldestUnansweredMs >= 24 * HOUR_MS ? 'critical' : 'warning',\n      key: `sweep:${options.product}:unanswered_threads`,\n      title: `${options.product}: ${pendingUserMessages} user message(s) unanswered across ${unanswered.length} thread(s)`,\n      details: [\n        `oldest unanswered message: ${hours}h`,\n        ...unanswered\n          .slice(0, 5)\n          .map(\n            (t) =>\n              `thread ${t.threadId}: ${t.pendingMessages} pending, oldest ${(\n                t.oldestAgeMs / HOUR_MS\n              ).toFixed(1)}h`,\n          ),\n      ],\n      data: {\n        unansweredThreads: unanswered.length,\n        pendingUserMessages,\n        oldestUnansweredMs,\n      },\n      at: now,\n    })\n  }\n\n  // ── success that delivered nothing ─────────────────────────────────────\n  let emptyCompletions = 0\n  let malformedToolCalls = 0\n  let toolCallsWithoutEffect = 0\n  let unhealthyTurns = 0\n  const malformedSamples: TurnHealthReason[] = []\n\n  for (const row of turns) {\n    const verdict = classifyTurnOutcome({\n      finalText: row.content,\n      parts: parseParts(row.parts),\n      outputTokens: row.outputTokens ?? null,\n    })\n    if (verdict.healthy) continue\n    unhealthyTurns += 1\n    for (const reason of verdict.reasons) {\n      if (reason.kind === 'empty_completion') emptyCompletions += 1\n      if (reason.kind === 'malformed_tool_call') {\n        malformedToolCalls += 1\n        if (malformedSamples.length < 3) malformedSamples.push(reason)\n      }\n      if (reason.kind === 'tool_call_no_effect') toolCallsWithoutEffect += 1\n    }\n  }\n\n  // A malformed tool call is never acceptable at any rate — it means a\n  // deliverable was requested and silently discarded. Page on the first one.\n  if (malformedToolCalls > 0) {\n    alerts.push({\n      product: options.product,\n      severity: 'critical',\n      key: `sweep:${options.product}:malformed_tool_call`,\n      title: `${options.product}: ${malformedToolCalls} tool call(s) had unparseable arguments — deliverables silently dropped`,\n      details: malformedSamples.map(describeReason),\n      data: { malformedToolCalls, turnsJudged: turns.length },\n      at: now,\n    })\n  }\n\n  if (turns.length >= minTurnsForRate) {\n    const rate = emptyCompletions / turns.length\n    if (rate > emptyRateThreshold) {\n      alerts.push({\n        product: options.product,\n        severity: 'critical',\n        key: `sweep:${options.product}:empty_completion_rate`,\n        title: `${options.product}: ${(rate * 100).toFixed(1)}% of turns completed with no output`,\n        details: [\n          `${emptyCompletions} of ${turns.length} settled turns delivered nothing`,\n          `threshold ${(emptyRateThreshold * 100).toFixed(1)}%`,\n        ],\n        data: { emptyCompletions, turnsJudged: turns.length, rate },\n        at: now,\n      })\n    }\n  }\n\n  for (const alert of alerts) await options.sink.deliver(alert)\n\n  return {\n    product: options.product,\n    unansweredThreads: unanswered.length,\n    pendingUserMessages,\n    oldestUnansweredMs,\n    turnsJudged: turns.length,\n    unhealthyTurns,\n    emptyCompletions,\n    malformedToolCalls,\n    toolCallsWithoutEffect,\n    alerts,\n  }\n}\n\n// ── D1 source for the shared chat-store schema ────────────────────────────\n\n/** Minimal structural D1 contract (Cloudflare's `D1Database` satisfies it). */\nexport interface D1LikeForHealth {\n  prepare(sql: string): {\n    bind(...values: unknown[]): {\n      all<T = Record<string, unknown>>(): Promise<{ results: T[] }>\n    }\n  }\n}\n\n/**\n * The sweep source for products on the canonical `/chat-store` tables.\n *\n * \"Answered\" deliberately means an assistant row with NON-EMPTY content. A\n * blank assistant row is what a broken turn writes, so counting it as an\n * answer would let the exact failure being hunted mark itself resolved. That\n * single predicate is the difference between this catching the gtm outage and\n * sleeping through it — during those sixteen days the table was NOT empty.\n *\n * The query deliberately does NOT join the thread table. Products do not all\n * keep one: tax-agent's `thread` table holds zero rows because it groups by\n * its own `tax_sessions`, and an inner join against it silently reported \"0\n * unanswered threads, healthy\" while 18 real messages sat unanswered. A\n * detector that reports healthy because its join found nothing is the same\n * bug class it was built to catch.\n */\nexport function createD1TurnHealthSource(\n  db: D1LikeForHealth,\n  options: {\n    messageTable?: string\n    threadTable?: string\n    /**\n     * Content prefixes that mark an assistant row as an ERROR SURFACE rather\n     * than an answer. A row matching one of these stops counting as a reply,\n     * so the thread keeps reporting as unanswered.\n     *\n     * This exists because the obvious rule — \"an assistant row with non-empty\n     * content is an answer\" — is wrong in the exact case that matters. On\n     * 2026-07-27 gtm-agent's newest assistant row read:\n     *\n     *   \"The sandbox model stream stopped before a clean completion.\n     *    Error: All 2 model(s) failed. gpt-5-mini: TANGLE_HUB_URL is required …\"\n     *\n     * 246 characters of well-formed prose that answers nothing. Counting it\n     * marks a dead product healthy — the same failure-returning-success shape\n     * this module exists to catch, recursing into the detector itself.\n     *\n     * There is no schema-level way to recognise it: `output_tokens IS NULL`\n     * looked promising until legal-agent showed 22 of 25 GENUINE replies with\n     * null usage — it would have reported a working product broken.\n     *\n     * Defaults to {@link SHELL_ERROR_REPLY_PREFIXES}, the openers agent-app\n     * ITSELF writes in `createSandboxChatProducer`. Those are not domain —\n     * this package composed them, so this package is what must recognise\n     * them, and every product on the shared producer is correct with no\n     * configuration. Pass your own list to ADD product-specific error prose;\n     * pass `[]` to disable the rule.\n     *\n     * Prefixes are bound as query parameters, never interpolated.\n     */\n    errorReplyPrefixes?: readonly string[]\n  } = {},\n): TurnHealthSource {\n  // Table names are identifiers and cannot be bound as parameters. They come\n  // from deploy-time product config, never from a request, and are validated\n  // here so this can never become an injection point.\n  const message = safeIdentifier(options.messageTable ?? 'message')\n  const thread = safeIdentifier(options.threadTable ?? 'thread')\n  const errorPrefixes = [...(options.errorReplyPrefixes ?? SHELL_ERROR_REPLY_PREFIXES)]\n\n  return {\n    async findUnansweredThreads({ minAgeMs, maxAgeMs, now }) {\n      const cutoffSeconds = Math.floor((now - minAgeMs) / 1000)\n      const floorSeconds = Math.floor((now - maxAgeMs) / 1000)\n      // Each prefix becomes one bound `NOT LIKE ?||'%'` term. Parameters, not\n      // interpolation — a product-supplied string never reaches the SQL text.\n      const errorClause = errorPrefixes\n        .map((_, i) => ` AND a.content NOT LIKE ?${i + 3} || '%'`)\n        .join('')\n      const { results } = await db\n        .prepare(\n          `SELECT m.thread_id AS threadId,\n                  COUNT(*) AS pendingMessages,\n                  MIN(m.created_at) AS oldestCreatedAt\n             FROM ${message} m\n            WHERE m.role = 'user'\n              AND m.created_at <= ?1\n              AND m.created_at >= ?2\n              AND m.created_at > COALESCE(\n                    (SELECT MAX(a.created_at)\n                       FROM ${message} a\n                      WHERE a.thread_id = m.thread_id\n                        AND a.role = 'assistant'\n                        AND length(trim(a.content)) > 0${errorClause}), 0)\n            GROUP BY m.thread_id\n            ORDER BY oldestCreatedAt ASC`,\n        )\n        .bind(cutoffSeconds, floorSeconds, ...errorPrefixes)\n        .all<{ threadId: string; pendingMessages: number; oldestCreatedAt: number }>()\n\n      return results.map((row) => ({\n        threadId: row.threadId,\n        pendingMessages: Number(row.pendingMessages),\n        oldestAgeMs: now - Number(row.oldestCreatedAt) * 1000,\n      }))\n    },\n\n    async listRecentAssistantTurns({ sinceMs, limit }) {\n      const sinceSeconds = Math.floor(sinceMs / 1000)\n      const { results } = await db\n        .prepare(\n          `SELECT id, thread_id AS threadId, content, parts,\n                  output_tokens AS outputTokens, model, created_at AS createdAt\n             FROM ${message}\n            WHERE role = 'assistant' AND created_at >= ?1\n            ORDER BY created_at DESC\n            LIMIT ?2`,\n        )\n        .bind(sinceSeconds, limit)\n        .all<Record<string, unknown>>()\n\n      return results.map((row) => ({\n        id: String(row.id),\n        threadId: String(row.threadId),\n        content: typeof row.content === 'string' ? row.content : '',\n        parts: row.parts,\n        outputTokens: row.outputTokens === null ? null : Number(row.outputTokens),\n        model: (row.model as string | null) ?? null,\n        createdAt: Number(row.createdAt) * 1000,\n      }))\n    },\n  }\n\n  function safeIdentifier(name: string): string {\n    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {\n      throw new Error(`unsafe table identifier: ${name}`)\n    }\n    return name\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{types-XIZqIdX1.d.ts → types-DeEOhQbv.d.ts}

@@ -38,13 +38,35 @@ interface WorkProductArtifact {
     /** The structured field map lineage targets anchor to (tax: form-line ids). */
     fields?: Record<string, unknown>;
 }
-/** Point into a source document: page, free-form range, verbatim quote */
+/** A half-open `[start, end)` character range into the source document's text.
+ *  Offsets index exactly the string the product's `readSourceText` seam
+ *  returns for the same `sourceRef` — which is the string its document-reading
+ *  tool pages with an `offset`. The PLATFORM slices `locator.quote` out of it,
+ *  so a span citation cannot name text the document does not contain. */
+interface EvidenceSpan {
+    start: number;
+    end: number;
+}
+/** How `locator.quote` got there. Server-set on every path — never read from
+ *  model args, because the whole value of the distinction is that a reviewer
+ *  can trust it:
+ *   - `span`  the platform sliced it out of the source bytes (unfalsifiable)
+ *   - `model` the model supplied the text and the platform PROVED it occurs */
+type QuoteBasis = 'span' | 'model';
+/** Point into a source document: page, free-form range, span, verbatim quote */
 interface EvidenceLocator {
     page?: number;
     /** 'L120-L134' | 'B7' | '¶4' — free-form, non-empty when present. */
     range?: string;
-    /** Verbatim supporting quote from the source. */
+    /** Verbatim supporting quote from the source. Model-supplied and verified,
+     *  or platform-sliced from {@link EvidenceLocator.span} — read `quoteBasis`
+     *  to tell which. */
     quote?: string;
+    /** Character range the quote is sliced from. The preferred citation form:
+     *  two integers cannot be a fabricated quote. */
+    span?: EvidenceSpan;
+    /** Server-set provenance for `quote`; a model-supplied value is discarded. */
+    quoteBasis?: QuoteBasis;
 }
 /** One lineage row: a source document location supporting one artifact claim */
 interface EvidenceEntry {
@@ -265,4 +287,4 @@ declare function workProductToPersistedPart(record: WorkProductRecord): WorkProd
 /** Re-validate a stored/wire part into the typed anchor; null for junk. */
 declare function persistedPartToWorkProduct(part: Record<string, unknown>): WorkProductPersistedPart | null;
 
-export { type AgentCheckInput as A, type EvidenceEntry as E, type ProfileBacktestSummary as P, type QualityCheck as Q, type WorkProductRef as W, type WorkProductProvenance as a, type WorkProductRecord as b, type WorkProductPersistedPart as c, type WorkProductStorePort as d, type WorkProductAuditEvent as e, type WorkProductArtifact as f, type ExceptionEntry as g, type WorkProductStatus as h, type EvidenceLocator as i, type ExceptionSeverity as j, type WorkProductParseResult as k, type WorkProductPatch as l, type WorkProductUpdateGuard as m, type WorkProductVersionEntry as n, isWorkProductStatus as o, parseAgentCheckInput as p, parseArtifactInput as q, parseEvidenceInput as r, parseExceptionInput as s, persistedPartToWorkProduct as t, unresolvedBlockingExceptions as u, workProductToPersistedPart as w };
+export { type AgentCheckInput as A, type EvidenceEntry as E, type ProfileBacktestSummary as P, type QualityCheck as Q, type WorkProductRef as W, type WorkProductProvenance as a, type WorkProductRecord as b, type WorkProductPersistedPart as c, type WorkProductStorePort as d, type WorkProductAuditEvent as e, type WorkProductArtifact as f, type ExceptionEntry as g, type WorkProductStatus as h, type EvidenceLocator as i, type EvidenceSpan as j, type ExceptionSeverity as k, type QuoteBasis as l, type WorkProductParseResult as m, type WorkProductPatch as n, type WorkProductUpdateGuard as o, type WorkProductVersionEntry as p, isWorkProductStatus as q, parseAgentCheckInput as r, parseArtifactInput as s, parseEvidenceInput as t, parseExceptionInput as u, persistedPartToWorkProduct as v, unresolvedBlockingExceptions as w, workProductToPersistedPart as x };

package/dist/web-react/index.d.ts

@@ -5,17 +5,17 @@ export { f as ChatFreeTextField, g as ComposerAnswerDelivery, h as INTERACTION_C
 import { ChatPlan } from '../plans/index.js';
 import { InteractionData } from '@tangle-network/agent-interface';
 export { InteractionData, InteractionOutcome, InteractionRequest } from '@tangle-network/agent-interface';
-import { M as FileMention, g as ChatMentionPart, b as ChatAttachmentPart, a as ChatAttachmentKind, Q as ChatAttachmentInput } from '../parts-Co_lFgLI.js';
-export { f as ChatMentionKind, P as ChatTurnFilePartInput, O as ChatTurnPartInput, N as ChatTurnRequestPayload, U as DISPATCH_MAX_MEDIA_PARTS, V as DISPATCH_MAX_PARTS, W as DISPATCH_REQUEST_MAX_BYTES, X as DISPATCH_STRUCTURAL_RESERVE_BYTES, $ as ProducerErrorEvent, a0 as ProducerNoticeEvent, a1 as ProducerPassthroughEvent, a2 as ProducerPassthroughEventType, a3 as ProducerReasoningEvent, a4 as ProducerTextEvent, a5 as ProducerToolCallEvent, a6 as ProducerToolResultEvent, a7 as ProducerUsageEvent, a8 as ProducerWireEvent, u as attachmentInputToPart, v as attachmentKindForMime, w as attachmentPartsFromMessageParts, ab as base64WireLen, ac as buildMentionPromptBlock, ad as chatTurnRequestInit, ae as fileMentionsToParts, z as isChatAttachmentPart, ag as mediaTypeForMentionPath, J as mentionInputToPart, ah as mentionKindForPath, K as mentionPartsFromMessageParts } from '../parts-Co_lFgLI.js';
-import { E as EvidenceEntry, g as ExceptionEntry, a as WorkProductProvenance, P as ProfileBacktestSummary, Q as QualityCheck, c as WorkProductPersistedPart, h as WorkProductStatus } from '../types-XIZqIdX1.js';
+import { M as FileMention, g as ChatMentionPart, b as ChatAttachmentPart, a as ChatAttachmentKind, Q as ChatAttachmentInput } from '../parts-DIKcC1p6.js';
+export { f as ChatMentionKind, P as ChatTurnFilePartInput, O as ChatTurnPartInput, N as ChatTurnRequestPayload, U as DISPATCH_MAX_MEDIA_PARTS, V as DISPATCH_MAX_PARTS, W as DISPATCH_REQUEST_MAX_BYTES, X as DISPATCH_STRUCTURAL_RESERVE_BYTES, $ as ProducerErrorEvent, a0 as ProducerNoticeEvent, a1 as ProducerPassthroughEvent, a2 as ProducerPassthroughEventType, a3 as ProducerReasoningEvent, a4 as ProducerTextEvent, a5 as ProducerToolCallEvent, a6 as ProducerToolResultEvent, a7 as ProducerUsageEvent, a8 as ProducerWireEvent, u as attachmentInputToPart, v as attachmentKindForMime, w as attachmentPartsFromMessageParts, ab as base64WireLen, ac as buildMentionPromptBlock, ad as chatTurnRequestInit, ae as fileMentionsToParts, z as isChatAttachmentPart, ag as mediaTypeForMentionPath, J as mentionInputToPart, ah as mentionKindForPath, K as mentionPartsFromMessageParts } from '../parts-DIKcC1p6.js';
+import { E as EvidenceEntry, g as ExceptionEntry, a as WorkProductProvenance, P as ProfileBacktestSummary, Q as QualityCheck, c as WorkProductPersistedPart, h as WorkProductStatus } from '../types-DeEOhQbv.js';
 import { S as StepAgentActivity } from '../agent-activity-C8ZG0F0M.js';
 import { F as FlowTrace } from '../flow-types-CJxEmaRy.js';
-import { a as ReviewQueueItem, c as ReviewQueueState } from '../queue-CD5-_VTX.js';
-export { p as parseReviewQueueItem } from '../queue-CD5-_VTX.js';
+import { a as ReviewQueueItem, c as ReviewQueueState } from '../queue-DBkulxW1.js';
+export { p as parseReviewQueueItem } from '../queue-DBkulxW1.js';
 export { S as SandboxTerminalConnection, a as SandboxTerminalConnectionResponse, U as UseSandboxTerminalConnectionOptions, b as UseSandboxTerminalConnectionResult, t as tabTerminalConnectionId, u as useSandboxTerminalConnection } from '../sandbox-terminal-ChNEdHF8.js';
 import { CatalogModel } from '../catalog/index.js';
 import { Harness } from '../harness/index.js';
-export { a as ATTACHMENT_ACCEPT, e as FileIndexReadyResponse, f as FileIndexResponse, g as FileIndexWarmingResponse } from '../attachment-validation-DRuLEjAE.js';
+export { a as ATTACHMENT_ACCEPT, e as FileIndexReadyResponse, f as FileIndexResponse, g as FileIndexWarmingResponse } from '../attachment-validation-yJ6Id4pR.js';
 export { a as attachmentPartKey } from '../stream-normalizer-DnuqkZvw.js';
 
 /** Represent durable plan decisions as either approved or rejected */

package/dist/web-react/index.js

@@ -74,7 +74,7 @@ import {
   useSmoothText,
   useThinkingSeconds,
   waterfallLayout
-} from "../chunk-TKRI463Z.js";
+} from "../chunk-J6TNPRQN.js";
 import "../chunk-FBVLEGEG.js";
 import {
   EvidenceLineageTable,
@@ -87,17 +87,17 @@ import {
   reviewQueueStateLabel,
   workProductPartsFromMessageParts,
   workProductStatusLabel
-} from "../chunk-UDSY2F6N.js";
+} from "../chunk-72TPRENZ.js";
 import {
   parseReviewQueueItem
-} from "../chunk-UP33Z633.js";
+} from "../chunk-ZRSUCTST.js";
 import {
   tabTerminalConnectionId,
   useSandboxTerminalConnection
 } from "../chunk-HCOROIRT.js";
 import {
   ATTACHMENT_ACCEPT
-} from "../chunk-V55WJSR4.js";
+} from "../chunk-5GA3MKOC.js";
 import {
   DISPATCH_MAX_MEDIA_PARTS,
   DISPATCH_MAX_PARTS,
@@ -115,8 +115,8 @@ import {
   mentionInputToPart,
   mentionKindForPath,
   mentionPartsFromMessageParts
-} from "../chunk-AFNTRJQ7.js";
-import "../chunk-F2CBC4DY.js";
+} from "../chunk-FEUW4G2L.js";
+import "../chunk-V3HO43PG.js";
 import {
   attachmentPartKey
 } from "../chunk-5EPIPT4V.js";

package/dist/work-product/index.d.ts

@@ -1,9 +1,9 @@
-import { a as WorkProductProvenance, d as WorkProductStorePort, e as WorkProductAuditEvent, b as WorkProductRecord, f as WorkProductArtifact, Q as QualityCheck, E as EvidenceEntry, g as ExceptionEntry, h as WorkProductStatus, c as WorkProductPersistedPart } from '../types-XIZqIdX1.js';
-export { A as AgentCheckInput, i as EvidenceLocator, j as ExceptionSeverity, P as ProfileBacktestSummary, k as WorkProductParseResult, l as WorkProductPatch, W as WorkProductRef, m as WorkProductUpdateGuard, n as WorkProductVersionEntry, o as isWorkProductStatus, p as parseAgentCheckInput, q as parseArtifactInput, r as parseEvidenceInput, s as parseExceptionInput, t as persistedPartToWorkProduct, u as unresolvedBlockingExceptions, w as workProductToPersistedPart } from '../types-XIZqIdX1.js';
+import { a as WorkProductProvenance, d as WorkProductStorePort, e as WorkProductAuditEvent, b as WorkProductRecord, f as WorkProductArtifact, Q as QualityCheck, E as EvidenceEntry, g as ExceptionEntry, h as WorkProductStatus, c as WorkProductPersistedPart } from '../types-DeEOhQbv.js';
+export { A as AgentCheckInput, i as EvidenceLocator, j as EvidenceSpan, k as ExceptionSeverity, P as ProfileBacktestSummary, l as QuoteBasis, m as WorkProductParseResult, n as WorkProductPatch, W as WorkProductRef, o as WorkProductUpdateGuard, p as WorkProductVersionEntry, q as isWorkProductStatus, r as parseAgentCheckInput, s as parseArtifactInput, t as parseEvidenceInput, u as parseExceptionInput, v as persistedPartToWorkProduct, w as unresolvedBlockingExceptions, x as workProductToPersistedPart } from '../types-DeEOhQbv.js';
 import { a as AppToolContext, c as AppToolDefinition } from '../types-BCxK0wyS.js';
 import { JudgeVerdict } from '@tangle-network/agent-eval';
 import { T as TrustItem } from '../trust-gate-Dcm5xSva.js';
-export { R as ReviewQueueInputs, a as ReviewQueueItem, b as ReviewQueuePendingAsk, c as ReviewQueueState, d as ReviewQueueThread, p as parseReviewQueueItem, e as projectReviewQueue } from '../queue-CD5-_VTX.js';
+export { R as ReviewQueueInputs, a as ReviewQueueItem, b as ReviewQueuePendingAsk, c as ReviewQueueState, d as ReviewQueueThread, p as parseReviewQueueItem, e as projectReviewQueue } from '../queue-DBkulxW1.js';
 
 /**
  * The guarded work-product status machine — the `/missions` service PATTERN
@@ -242,8 +242,22 @@ interface WorkProductToolConfig {
      *  Omit the seam entirely and no quote is checked. */
     readSourceText?: (ref: string, ctx: AppToolContext) => Promise<string | null>;
     /** The material targets the platform coverage check requires evidence for.
-     *  Product-owned vocabulary; omit to skip the coverage gate. */
+     *  Product-owned vocabulary; omit to skip the coverage gate.
+     *
+     *  Return ONLY targets a source document can actually evidence. A gate that
+     *  demands document lineage for a value the session COMPUTED is not
+     *  satisfiable by any honest answer, and an unsatisfiable gate does not stop
+     *  a submit — it selects for an invented one. Computed values belong to a
+     *  product's own computation check, where "matches what we already
+     *  calculated" is satisfiable by construction. */
     materialTargets?: (artifact: WorkProductArtifact) => string[];
+    /** Require every material target to carry a SOURCE ANCHOR — a span-sliced or
+     *  verified quote — not merely an evidence row. Off by default (a bare
+     *  `claim` is legitimate lineage for products with no readable sources);
+     *  turn it ON once `readSourceText` is wired and `materialTargets` names only
+     *  document-derived targets, and coverage stops being satisfiable by
+     *  assertion. */
+    requireAnchoredEvidence?: boolean;
     /** Per-turn provenance closure the ROUTE supplies (profileHash + runId are
      *  known at dispatch; trusted, never read from model args). */
     provenance: (ctx: AppToolContext) => WorkProductProvenanceBase;
@@ -292,6 +306,60 @@ declare function normalizeQuoteText(value: string): string;
  * substring of every document and pass the gate vacuously.
  */
 declare function sourceContainsQuote(sourceText: string, quote: string): boolean;
+/**
+ * Slice a citation out of the source text by character offset — the reason
+ * this module exists in its stronger form.
+ *
+ * Verification above is a REJECTION gate: the model retypes a quote and the
+ * shell refuses it when the characters do not occur. That gate is correct and
+ * it works, but a model that reproduces a line character-for-character only
+ * some of the time cannot USE it — every miss is a refusal, and the package
+ * ends up with no lineage at all rather than false lineage. A measured 9 of 59
+ * on the live tax surface is what "some of the time" meant in practice.
+ *
+ * A span inverts it. The model names two integers into text it just read; the
+ * PLATFORM produces the quote from the bytes it already holds. There is no
+ * retyping step to get wrong, so a fabricated quote is not rejected — it is
+ * unrepresentable. `sourceContainsQuote(text, sliceSourceSpan(text, span))` is
+ * true for every span this function returns, by construction.
+ *
+ * Offsets index the SAME string the product's document-reading tool pages
+ * with an offset, which is the same string its `readSourceText` seam returns.
+ * That is the one contract a product must keep; violate it and spans point at
+ * the wrong characters (still real characters of that document — never
+ * invented text, but the wrong line).
+ *
+ * Half-open `[start, end)`, matching `String.prototype.slice` and the
+ * `offset`/`offset + text.length` window a paged read already reports.
+ */
+type SourceSpanFailure = {
+    reason: 'not_integer';
+    field: 'start' | 'end';
+} | {
+    reason: 'negative';
+    field: 'start' | 'end';
+} | {
+    reason: 'inverted';
+} | {
+    reason: 'out_of_range';
+    totalChars: number;
+} | {
+    reason: 'blank';
+};
+type SourceSpanResult = {
+    ok: true;
+    quote: string;
+} | {
+    ok: false;
+    failure: SourceSpanFailure;
+};
+/** Resolve `[start, end)` against `sourceText`. Every rejection is a caller
+ *  mistake the model can correct from the paged read it already has, so each
+ *  carries the discriminator a tool layer turns into a specific message. */
+declare function sliceSourceSpan(sourceText: string, span: {
+    start: number;
+    end: number;
+}): SourceSpanResult;
 
 /**
  * Framework-neutral work-product review endpoints — the
@@ -382,4 +450,4 @@ interface WorkProductRoutes {
 /** Create the work-product review endpoints over the store port and product seams */
 declare function createWorkProductRoutes(options: WorkProductRoutesOptions): WorkProductRoutes;
 
-export { type CreateWorkProductInput, EVIDENCE_COVERAGE_CHECK, EvidenceEntry, ExceptionEntry, type FinalizeWorkProductProvenanceInput, type InMemoryWorkProductStore, MAX_WORK_PRODUCT_BATCH, QUOTE_VERIFICATION_CHECK, QualityCheck, type SubmitWorkProductInput, TrustItem, WorkProductArtifact, WorkProductAuditEvent, type WorkProductAuthorizeArgs, type WorkProductOutcome, WorkProductPersistedPart, WorkProductProvenance, type WorkProductProvenanceBase, WorkProductRecord, type WorkProductRouteAuthorization, type WorkProductRoutes, type WorkProductRoutesOptions, type WorkProductService, type WorkProductServiceOptions, WorkProductStatus, WorkProductStorePort, type WorkProductToolConfig, type WorkProductVerdictBody, type WorkProductVerdictInput, buildWorkProductTools, canTransitionWorkProduct, createInMemoryWorkProductStore, createWorkProductRoutes, createWorkProductService, finalizeWorkProductProvenance, isWorkProductTerminal, normalizeQuoteText, sourceContainsQuote, stampProvenance, validateWorkProductVerdictBody, workProductTrustInputs };
+export { type CreateWorkProductInput, EVIDENCE_COVERAGE_CHECK, EvidenceEntry, ExceptionEntry, type FinalizeWorkProductProvenanceInput, type InMemoryWorkProductStore, MAX_WORK_PRODUCT_BATCH, QUOTE_VERIFICATION_CHECK, QualityCheck, type SourceSpanFailure, type SourceSpanResult, type SubmitWorkProductInput, TrustItem, WorkProductArtifact, WorkProductAuditEvent, type WorkProductAuthorizeArgs, type WorkProductOutcome, WorkProductPersistedPart, WorkProductProvenance, type WorkProductProvenanceBase, WorkProductRecord, type WorkProductRouteAuthorization, type WorkProductRoutes, type WorkProductRoutesOptions, type WorkProductService, type WorkProductServiceOptions, WorkProductStatus, WorkProductStorePort, type WorkProductToolConfig, type WorkProductVerdictBody, type WorkProductVerdictInput, buildWorkProductTools, canTransitionWorkProduct, createInMemoryWorkProductStore, createWorkProductRoutes, createWorkProductService, finalizeWorkProductProvenance, isWorkProductTerminal, normalizeQuoteText, sliceSourceSpan, sourceContainsQuote, stampProvenance, validateWorkProductVerdictBody, workProductTrustInputs };