@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/turn-health/index.d.ts

@@ -1,638 +1,30 @@
 /**
- * The classifier for turns that FAIL BY RETURNING SUCCESS.
- *
- * Every failure this module names shipped to a customer with HTTP 200, no
- * thrown error, and no log line anyone read. Three were measured in production
- * in a single week:
- *
- *   - a turn settled `{"outcome":{"type":"completed"},"finalText":"",
- *     "tokenUsage":{"outputTokens":0}}` — the customer saw a blank bubble;
- *   - six `submit_proposal` tool calls collapsed into ONE whose arguments were
- *     a 1,652-character non-JSON string, so zero proposals persisted and
- *     nothing errored (agent-runtime #626);
- *   - a thread took 255 user messages over 17 days and produced 2 replies,
- *     both of them error text.
- *
- * A conventional health check cannot see any of these, because it probes
- * DEPENDENCIES (is the sandbox reachable, is the router up) and every one of
- * these failures happens with all dependencies green. This classifier probes
- * the OUTCOME instead.
- *
- * It is deliberately pure and structural: it reads a settled turn's own
- * projection, so the SAME function judges a live turn through the
- * `/chat-routes` lifecycle seam and a historical row read back out of the
- * store during a sweep. One definition of "silently broken", two call sites.
- */
-/** How loudly a reason should be routed. `critical` means a customer got
- *  nothing usable; `warning` means the turn degraded but still produced
- *  something a human could read. */
-type TurnHealthSeverity = 'critical' | 'warning';
-/** One specific way a turn returned success while failing.
- *
- *  Each variant carries the evidence that identified it, so an alert can name
- *  the offending value instead of asserting a verdict the reader has to take
- *  on faith. */
-type TurnHealthReason = 
-/** Settled without error and produced nothing a user can read: no text, and
- *  no artifact part (file/image/work-product/plan/interaction). This is the
- *  verbatim blank-completion capture. */
-{
-    kind: 'empty_completion';
-    outputTokens: number | null;
-    partCount: number;
-    durationMs?: number;
-}
-/** A tool call whose arguments never parsed. The engine surfaces unparseable
- *  arguments as a RAW STRING rather than throwing, so the call is neither
- *  dropped nor errored — it silently does nothing. Detecting a string-typed
- *  tool input that fails `JSON.parse` is the exact fingerprint of the
- *  index-less parallel-tool-call collapse. */
- | {
-    kind: 'malformed_tool_call';
-    tool: string;
-    inputLength: number;
-    /** Leading characters of the offending input, for the alert body. */
-    sample: string;
-}
-/** A tool call that never reached a terminal state carrying output. The call
- *  was issued and then simply produced no effect. */
- | {
-    kind: 'tool_call_no_effect';
-    tool: string;
-    status: string;
-}
-/** The turn failed outright. Not silent by itself — but it becomes silent
- *  the moment nothing is watching, which is how 16 days of
- *  `TANGLE_HUB_URL is required` reached customers unnoticed. */
- | {
-    kind: 'turn_failed';
-    reason: string;
-}
-/** A tool call the harness REJECTED, settled as `completed`.
- *
- *  Found live in legal-agent production, and missed by every other rule here:
- *  the model called `submit_proposal`, the harness answered "Model tried to
- *  call unavailable tool 'submit_proposal'", and the part persisted as
- *  `{"tool":"invalid","state":{"status":"completed","input":{"error":"…"}}}`.
- *
- *  Status is `completed`, the arguments parse cleanly, and the turn has text —
- *  so the blank-completion, malformed-argument and no-effect rules all pass it.
- *  Six deliverables were requested and silently discarded while the product
- *  reported success six times.
- *
- *  Detected structurally, on the presence of an `error` in the settled state
- *  rather than on any harness's name for a rejected call — `invalid` is one
- *  harness's convention and must not be baked into the shell. */
- | {
-    kind: 'tool_call_rejected';
-    /** The tool the model was trying to reach, when the payload names it. */
-    tool: string;
-    error: string;
-}
-/** The turn was answered without the model ever running — a pre-producer gate
- *  short-circuited and returned the product's own response.
- *
- *  Reported as a `warning`, never `critical`: gating an unready turn is a
- *  legitimate design (an intake flow SHOULD answer before spending a model
- *  call). What is pathological is the RATE, which only the caller's own
- *  threshold can judge — so this variant exists to be COUNTED, and alerting
- *  on it is opt-in. It is the per-turn evidence behind a dead tool surface:
- *  a gate that answers every turn means the agent never runs at all. */
- | {
-    kind: 'answered_without_model';
-}
-/** The detector could not read this turn.
- *
- *  Every part carried a type outside the vocabulary this classifier
- *  understands — which is what field-level encryption at rest looks like from
- *  the outside (tax-agent persists `{"type":"__encrypted_parts__"}`, its own
- *  convention, and 32 of its 129 assistant rows are exactly that).
- *
- *  This exists because the alternative is the bug this whole module hunts.
- *  An unreadable row has no text, no artifact and no tool part, so every
- *  other rule here would happily conclude "nothing wrong" — a detector
- *  reporting health from data it cannot see. Blindness is a finding, not a
- *  pass, so it gets its own reason and its own counter. */
- | {
-    kind: 'unreadable_turn';
-    partTypes: string[];
-};
-/** A settled turn, in the narrowest shape both call sites can supply.
- *
- *  Structural on purpose: the lifecycle seam supplies `finalText`/`usage`, a
- *  store sweep supplies `content`/`parts` read back from a row, and neither
- *  has to import the other's types. */
-interface TurnOutcomeInput {
-    /** The turn's final assistant text. */
-    finalText?: string | null;
-    /** The persisted assistant parts. Untyped by design — a sweep reads these
-     *  out of a JSON column and must not be forced to validate them first. */
-    parts?: readonly unknown[] | null;
-    /** Output tokens, when the caller has usage. `null`/absent is unknown, which
-     *  is NOT the same as zero and is never treated as evidence. */
-    outputTokens?: number | null;
-    /** Set when the turn surfaced a terminal error event. */
-    failed?: boolean;
-    failureReason?: string | null;
-    durationMs?: number;
-    /** Set when a pre-producer gate answered this turn and the model never ran.
-     *  Supplied by `/chat-routes`' lifecycle seam, which stamps `gated` on the
-     *  completion it now fires for a `contextGate` short-circuit. */
-    gated?: boolean;
-}
-/** The verdict for one turn. `healthy` is exactly `reasons.length === 0`, kept
- *  as a field so callers read intent rather than an array length. */
-interface TurnHealthVerdict {
-    healthy: boolean;
-    severity: TurnHealthSeverity | null;
-    reasons: TurnHealthReason[];
-    /** How many tool parts this turn carried.
-     *
-     *  Zero is NOT a per-turn defect — plenty of good turns answer from context
-     *  without touching a tool, and paging on each one would be pure noise. It is
-     *  reported so a WINDOW can be judged: a product whose deliverable is tool
-     *  output and which produced zero tool calls across every turn in the
-     *  lookback has a dead tool surface, and that is the shape no per-turn rule
-     *  can see.
-     *
-     *  Only meaningful alongside {@link interpretedParts} > 0. Zero tool calls
-     *  read off a row that persisted NO parts is not an observation about the
-     *  tool surface — it is the absence of one. */
-    toolCalls: number;
-    /** True when nothing about this turn could be judged — no interpretable part
-     *  AND no visible text. Callers MUST exclude these from any healthy/unhealthy
-     *  ratio, because counting an unreadable turn as healthy is how a detector
-     *  reports green on data it never read. */
-    unreadable: boolean;
-    /** False when this turn carried parts that could not be interpreted.
-     *
-     *  Separate from {@link unreadable} because the two blindnesses have
-     *  different consequences, and production has a row that is one but not the
-     *  other: tax-agent persists CIPHERTEXT as `content` alongside an encrypted
-     *  `parts` blob, so the turn plainly delivered something (there is text) while
-     *  its tool calls are completely invisible.
-     *
-     *  Any conclusion ABOUT TOOLS — above all the dead-tool-surface verdict — may
-     *  only be drawn over turns where this is true. Reading "no tool parts" off an
-     *  encrypted blob and declaring the tool surface dead would be the same
-     *  crime as declaring it healthy: a finding asserted from data never read. */
-    partsReadable: boolean;
-    /** The part types that could not be interpreted. Empty when
-     *  {@link partsReadable}. Named in the alert so a reader can see EXACTLY what
-     *  the detector was blind to instead of taking "unreadable" on faith. */
-    opaquePartTypes: string[];
-    /** How many parts this module actually READ (text, artifact, tool, or a known
-     *  non-output kind).
-     *
-     *  The third blindness, and the one that shipped a false page. `partsReadable`
-     *  only says nothing was *uninterpretable*; a row that persisted NO parts at
-     *  all satisfies that vacuously. Production: 97 of tax-agent's 156 assistant
-     *  rows predate parts persistence entirely and store `[]`, and reading "zero
-     *  tool calls" off them raised a critical `dead_tool_surface` against a
-     *  product whose own `turn_events` table holds 243 `tool_call` frames.
-     *
-     *  So a tool verdict requires BOTH `partsReadable` AND this being > 0 —
-     *  evidence that was read, not merely evidence that failed to be unreadable. */
-    interpretedParts: number;
-}
-/**
- * Judge one settled turn.
- *
- * Never throws: a malformed `parts` blob is a thing this function REPORTS on,
- * so it must not be a thing it dies on. Telemetry that can crash the turn it
- * measures is worse than no telemetry.
- */
-declare function classifyTurnOutcome(input: TurnOutcomeInput): TurnHealthVerdict;
-/** One-line human summary of a reason, for an alert body. */
-declare function describeReason(reason: TurnHealthReason): string;
-
-/**
- * Where a silent-failure verdict GOES.
- *
- * The detection half is worthless without this half. Every failure this module
- * finds was already visible in the database the whole time — 255 unanswered
- * messages sat in a table for 17 days. What was missing was not the data, it
- * was delivery to a human who had not thought to look.
- *
- * So the sink is a seam, not a channel: the product supplies the transport,
- * and agent-app ships the two shapes the fleet already has credentials for
- * (an ops webhook, and stderr). No new channel is invented here.
- */
-
-/** One deliverable alert. */
-interface TurnHealthAlert {
-    /** Which product raised it (`projectId`). Alerts from four products land in
-     *  one channel, so this is what makes the message actionable. */
-    product: string;
-    severity: TurnHealthSeverity;
-    /** Stable grouping key. Throttling is keyed on this, so it must NOT contain
-     *  a turn id or a timestamp or every alert is unique and nothing dedupes. */
-    key: string;
-    title: string;
-    /** Human-readable lines. */
-    details: string[];
-    /** Structured payload for a machine consumer. */
-    data?: Record<string, unknown>;
-    at: number;
-}
-/** Deliver an alert. Implementations MUST NOT throw — see
- *  {@link createGuardedAlertSink}. */
-interface AlertSink {
-    deliver(alert: TurnHealthAlert): Promise<void>;
-}
-/** Build the alert for a set of reasons found on one turn. */
-declare function turnAlert(input: {
-    product: string;
-    severity: TurnHealthSeverity;
-    reasons: TurnHealthReason[];
-    threadId?: string;
-    turnId?: string;
-    model?: string;
-    at?: number;
-}): TurnHealthAlert;
-/** Minimal structural fetch, so this module has no lib-dom dependency and can
- *  be driven by a fake in tests. */
-type FetchLike = (url: string, init: {
-    method: string;
-    headers: Record<string, string>;
-    body: string;
-}) => Promise<{
-    ok: boolean;
-    status: number;
-    text?(): Promise<string>;
-}>;
-/**
- * POST to an incoming webhook in the Slack message format.
- *
- * Chosen because the org already runs one (`SLACK_OPS_WEBHOOK_URL`) and
- * gtm-agent's outbound webhook code already speaks this exact shape — the
- * instruction was to route somewhere humans already look, not to stand up a
- * new channel. Discord and most log drains accept the same `{text}` body.
- */
-declare function createWebhookAlertSink(options: {
-    webhookUrl: string;
-    fetchImpl?: FetchLike;
-}): AlertSink;
-/**
- * POST to Slack `chat.postMessage` with a bot token.
- *
- * This is the transport the org actually has. A survey of the four product
- * repos found NO ops alert path of any kind — no incoming webhook, no pager, no
- * notifier — which is the mechanical reason a 17-day outage never reached a
- * human. What does exist is a Slack bot token in the shared secrets store, and
- * `@tangle-network/agent-integrations` already speaks this exact API, so this
- * routes alerts through the channel the org runs rather than standing up a new
- * one.
- *
- * Slack answers `200 OK` with `{"ok": false, "error": "..."}` for an invalid
- * token or channel, so the body is checked and not just the status — a
- * transport that reports success on a rejected post would make the alerter
- * itself a silent failure.
- */
-declare function createSlackBotAlertSink(options: {
-    botToken: string;
-    channel: string;
-    fetchImpl?: FetchLike;
-}): AlertSink;
-/** stderr sink. The zero-config fallback so a product that has not yet been
- *  given a webhook still emits something a log search can find. */
-declare function createConsoleAlertSink(log?: (message: string) => void): AlertSink;
-/** Fan out to several sinks. One failing transport must not stop the others. */
-declare function createMultiAlertSink(sinks: readonly AlertSink[]): AlertSink;
-/** Records the last time a key was alerted on. A product backs this with KV,
- *  D1, or a Durable Object; the in-memory default is correct for a sweep that
- *  runs as a single cron invocation. */
-interface AlertThrottleStore {
-    lastSentAt(key: string): Promise<number | null>;
-    markSent(key: string, at: number): Promise<void>;
-}
-/** Process-local throttle store. */
-declare function createMemoryThrottleStore(): AlertThrottleStore;
-/**
- * Collapse repeats of the same `key` inside `windowMs`.
- *
- * Deliberately re-alerts once per window rather than going silent after the
- * first: an incident that is still burning must keep saying so. Going quiet
- * after one message is how a 17-day outage stays invisible after someone
- * dismisses the first notification.
- */
-declare function createThrottledAlertSink(inner: AlertSink, options: {
-    windowMs: number;
-    store?: AlertThrottleStore;
-}): AlertSink;
-/**
- * Swallow transport errors so telemetry can never fail the turn it measures.
- *
- * Use this at the LIVE lifecycle call site only. A sweep should let the error
- * surface, because a sweep that cannot deliver has done nothing at all and its
- * cron run should go red.
- */
-declare function createGuardedAlertSink(inner: AlertSink, onError?: (error: unknown) => void): AlertSink;
-
-/**
- * The LIVE half: judge each turn the moment it settles.
- *
- * This adds no control flow. `createChatTurnRoutes` already exposes a
- * `lifecycle` seam that fires exactly one of `onTurnComplete`/`onTurnError`
- * after a turn settles, and already swallows hook errors so telemetry cannot
- * fail a turn. That seam was shipped and then wired by nobody, which is a fair
- * description of why the outage lasted 17 days. This function fills it.
- *
- * The shape is declared structurally rather than imported from
- * `/chat-routes`, so `/turn-health` stays free of the server chat vertical and
- * can be used by any turn driver that reports the same three moments.
- */
-
-/** Structural mirror of `/chat-routes`' `ChatTurnLifecycle` complete payload. */
-interface TurnHealthCompleteInfo {
-    finalText: string;
-    usage?: {
-        outputTokens?: number | null;
-    } | null;
-    durationMs: number;
-    threadId?: string;
-    turnStreamId?: string;
-    executionId?: string;
-    /** `/chat-routes` sets this when a `contextGate` short-circuited the turn and
-     *  the producer never ran. */
-    gated?: boolean;
-}
-/** Structural mirror of the lifecycle error payload. */
-interface TurnHealthErrorInfo {
-    error: unknown;
-    durationMs: number;
-    threadId?: string;
-    turnStreamId?: string;
-    executionId?: string;
-}
-/** What {@link createTurnHealthLifecycle} returns — assignable to
- *  `createChatTurnRoutes`' `lifecycle` option. */
-interface TurnHealthLifecycle {
-    onTurnComplete(info: TurnHealthCompleteInfo): Promise<void>;
-    onTurnError(info: TurnHealthErrorInfo): Promise<void>;
-}
-interface TurnHealthLifecycleOptions {
-    /** Names the product in every alert. */
-    product: string;
-    sink: AlertSink;
-    /** Called for every verdict, healthy or not — the hook for a counter or a
-     *  metrics push. Alerts are for humans; this is for graphs. */
-    onVerdict?(verdict: {
-        product: string;
-        healthy: boolean;
-        kinds: string[];
-        durationMs: number;
-    }): void;
-    /** Page when a turn was answered by a gate instead of the model.
-     *
-     *  Default `false`, and the default is the honest one: gating is a legitimate
-     *  design and a product that gates its intake would otherwise page on every
-     *  healthy turn. Whether the rate is pathological is domain knowledge, so it
-     *  stays a product decision — the verdict is ALWAYS reported through
-     *  {@link TurnHealthLifecycleOptions.onVerdict} so a counter can watch the
-     *  rate even when nobody is paged. */
-    alertOnGatedTurn?: boolean;
-}
-/**
- * Build the lifecycle hooks that page on a turn which succeeded at nothing.
- *
- * The live lane sees `finalText` and usage but not the persisted parts, so it
- * catches the blank-completion and hard-failure shapes immediately. The
- * parts-dependent shapes (a tool call whose arguments never parsed, a tool
- * call that left no effect) are caught by {@link sweepSilentFailures}, which
- * reads what was actually written to the store — the honest place to ask
- * whether an effect persisted.
- */
-declare function createTurnHealthLifecycle(options: TurnHealthLifecycleOptions): TurnHealthLifecycle;
-
-/**
- * The SWEEP half: ask the store what it has been quietly accumulating.
- *
- * A live per-turn hook cannot see the failure that matters most, because the
- * worst outage produced NO turns at all to hook: gtm-agent took 9–21 user
- * messages a day for sixteen straight days and wrote zero real assistant
- * replies. Nothing crashed on a schedule; the product simply stopped
- * answering. The only thing that could have noticed is something that
- * periodically counts what arrived against what was answered.
- *
- * That is this. It runs on a cron, reads the shared `/chat-store` schema, and
- * pages when the ratio breaks.
- *
- * The queries live HERE and not in each product because all four products
- * (gtm, tax, legal, workcomp) persist to the same `message`/`thread` tables —
- * four copies of this cron is exactly the duplication the repo's engine/shell
- * rule exists to prevent.
- */
-
-/** A thread that has taken user messages with no reply since. */
-interface UnansweredThread {
-    threadId: string;
-    /** User messages newer than the newest real assistant reply. */
-    pendingMessages: number;
-    /** Age of the OLDEST unanswered user message, in ms. */
-    oldestAgeMs: number;
-}
-/** A persisted assistant row, as the sweep needs to judge it. */
-interface PersistedTurnRow {
-    id: string;
-    threadId: string;
-    content: string;
-    /** Raw `parts` column. A JSON string or an already-parsed array; the sweep
-     *  accepts both because D1 drivers differ. */
-    parts: unknown;
-    outputTokens?: number | null;
-    model?: string | null;
-    createdAt: number;
-}
-/** What the sweep needs from a store. A product on a non-standard schema
- *  implements these two reads; everything else is shared. */
-interface TurnHealthSource {
-    findUnansweredThreads(input: {
-        minAgeMs: number;
-        /** Ignore user messages older than this. See {@link SweepOptions.maxAgeMs}. */
-        maxAgeMs: number;
-        now: number;
-    }): Promise<UnansweredThread[]>;
-    listRecentAssistantTurns(input: {
-        sinceMs: number;
-        now: number;
-        limit: number;
-    }): Promise<PersistedTurnRow[]>;
-}
-interface SweepOptions {
-    product: string;
-    source: TurnHealthSource;
-    sink: AlertSink;
-    /** A user message must go unanswered this long before it counts. Guards
-     *  against alerting on a turn that is simply still streaming. Default 15 min. */
-    minAgeMs?: number;
-    /**
-     * A user message OLDER than this is abandoned, not unanswered — it stops
-     * counting. Default 7 days.
-     *
-     * Without this bound the sweep is worse than useless. gtm-agent's table
-     * holds 384 unanswered messages whose oldest is 1,676 h (70 days) old;
-     * paging hourly on a backlog nobody will ever reply to is exactly how an
-     * alert channel gets muted, and a muted channel is the state this module
-     * exists to escape. The alert has to mean "something broke recently".
-     */
-    maxAgeMs?: number;
-    /** How far back to judge settled turns. Default 24 h. */
-    lookbackMs?: number;
-    /** Cap on rows judged per sweep. Default 500. */
-    limit?: number;
-    /** Fraction of recent turns allowed to be silently broken before paging.
-     *  Default 0.05 — the measured blank-completion rate on the tax tool surface
-     *  was 12.2%, so 5% separates a real regression from noise. */
-    emptyRateThreshold?: number;
-    /** Absolute floor: never page on a rate computed from fewer turns than this. */
-    minTurnsForRate?: number;
-    /** Declare that this product's deliverable comes from TOOL calls, which
-     *  switches on the dead-tool-surface detector.
-     *
-     *  Opt-in because only the product knows: a copilot that answers from context
-     *  is perfectly healthy with zero tool calls, while an agent whose entire job
-     *  is to file, draft, or submit something is broken the moment its tool
-     *  surface goes quiet — and broken INVISIBLY, because every turn still
-     *  returns fluent prose and HTTP 200.
-     *
-     *  This is the fourth failure shape, and the only one no per-turn rule can
-     *  see.
-     *
-     *  The verdict is drawn ONLY over turns whose parts were present and
-     *  readable. An earlier revision counted rows that stored no parts, and the
-     *  production example this comment used to cite was that bug rather than a
-     *  finding: tax-agent's 97 parts-less rows all predate its parts persistence
-     *  (they stop at 2026-07-17T02:20Z, the encrypted rows start 02:58Z), while
-     *  the same database's `turn_events` table holds 243 `tool_call` frames over
-     *  15 turns. The tool surface was never dead; the rows were empty. */
-    expectsToolCalls?: boolean;
-    /** Turns needed before a dead tool surface is called. Default 10. */
-    minTurnsForToolSurface?: number;
-    /**
-     * Make an at-rest parts encoding readable, so this sweep can judge a product
-     * that does not store parts in the clear.
-     *
-     * Without it, a product that encrypts `parts` (tax-agent wraps the whole
-     * array in one `__encrypted_parts__` part) is permanently UNMEASURABLE by the
-     * tool-surface rule: every row is opaque, so the honest verdict is "cannot
-     * certify" forever. This seam is how such a product gets a real verdict
-     * instead of permanent blindness — the sweep stays domain-free and the
-     * product supplies the decoder.
-     *
-     * Return the decoded parts value (it is parsed exactly like a stored one).
-     * Returning `null`/`undefined` or THROWING leaves the row's stored value in
-     * place, so a decoder that fails reports the row as opaque. It must never
-     * report success as an empty array: that manufactures the exact absent-parts
-     * blindness this module now refuses to draw conclusions from.
-     */
-    decodeParts?: (raw: unknown, row: PersistedTurnRow) => Promise<unknown> | unknown;
-    now?: number;
-}
-/** What the sweep found. Returned as well as alerted, so a cron can log it and
- *  a test can assert on it. */
-interface SweepResult {
-    product: string;
-    unansweredThreads: number;
-    pendingUserMessages: number;
-    oldestUnansweredMs: number;
-    turnsJudged: number;
-    unhealthyTurns: number;
-    emptyCompletions: number;
-    malformedToolCalls: number;
-    toolCallsWithoutEffect: number;
-    /** Tool calls the harness rejected while settling them as `completed`. */
-    rejectedToolCalls: number;
-    /** Turns carrying at least one tool part. */
-    turnsWithToolCalls: number;
-    /** Total tool parts across the window. */
-    toolCalls: number;
-    /** Turns the classifier could not interpret at all (encrypted at rest, or a
-     *  part vocabulary this module does not know). These are EXCLUDED from
-     *  `turnsJudged`-based rates — a rate computed over rows nobody could read is
-     *  a fabricated number. */
-    unreadableTurns: number;
-    /** Turns whose PARTS could not be interpreted. A superset of
-     *  {@link unreadableTurns} (a row can have readable text and opaque parts).
-     *  No tool verdict is drawn over these. */
-    opaquePartsTurns: number;
-    /** Turns that persisted NO parts at all. Distinct from
-     *  {@link opaquePartsTurns}: nothing failed to parse, there was simply
-     *  nothing there. Also excluded from every tool verdict. */
-    noPartsTurns: number;
-    /** Turns a tool verdict may actually be drawn from — parts present AND
-     *  interpretable. The denominator behind `dead_tool_surface`. */
-    toolReadableTurns: number;
-    alerts: TurnHealthAlert[];
-}
-declare const SHELL_ERROR_REPLY_PREFIXES: readonly string[];
-/**
- * Run one sweep and deliver whatever it finds.
- *
- * Errors from the sink are NOT swallowed here (unlike the live lane): a sweep
- * that could not deliver has accomplished nothing, and its cron invocation
- * should go red rather than report a clean run.
- */
-declare function sweepSilentFailures(options: SweepOptions): Promise<SweepResult>;
-/** Minimal structural D1 contract (Cloudflare's `D1Database` satisfies it). */
-interface D1LikeForHealth {
-    prepare(sql: string): {
-        bind(...values: unknown[]): {
-            all<T = Record<string, unknown>>(): Promise<{
-                results: T[];
-            }>;
-        };
-    };
-}
-/**
- * The sweep source for products on the canonical `/chat-store` tables.
- *
- * "Answered" deliberately means an assistant row with NON-EMPTY content. A
- * blank assistant row is what a broken turn writes, so counting it as an
- * answer would let the exact failure being hunted mark itself resolved. That
- * single predicate is the difference between this catching the gtm outage and
- * sleeping through it — during those sixteen days the table was NOT empty.
- *
- * The query deliberately does NOT join the thread table. Products do not all
- * keep one: tax-agent's `thread` table holds zero rows because it groups by
- * its own `tax_sessions`, and an inner join against it silently reported "0
- * unanswered threads, healthy" while 18 real messages sat unanswered. A
- * detector that reports healthy because its join found nothing is the same
- * bug class it was built to catch.
- */
-declare function createD1TurnHealthSource(db: D1LikeForHealth, options?: {
-    messageTable?: string;
-    threadTable?: string;
-    /**
-     * Content prefixes that mark an assistant row as an ERROR SURFACE rather
-     * than an answer. A row matching one of these stops counting as a reply,
-     * so the thread keeps reporting as unanswered.
-     *
-     * This exists because the obvious rule — "an assistant row with non-empty
-     * content is an answer" — is wrong in the exact case that matters. On
-     * 2026-07-27 gtm-agent's newest assistant row read:
-     *
-     *   "The sandbox model stream stopped before a clean completion.
-     *    Error: All 2 model(s) failed. gpt-5-mini: TANGLE_HUB_URL is required …"
-     *
-     * 246 characters of well-formed prose that answers nothing. Counting it
-     * marks a dead product healthy — the same failure-returning-success shape
-     * this module exists to catch, recursing into the detector itself.
-     *
-     * There is no schema-level way to recognise it: `output_tokens IS NULL`
-     * looked promising until legal-agent showed 22 of 25 GENUINE replies with
-     * null usage — it would have reported a working product broken.
-     *
-     * Defaults to {@link SHELL_ERROR_REPLY_PREFIXES}, the openers agent-app
-     * ITSELF writes in `createSandboxChatProducer`. Those are not domain —
-     * this package composed them, so this package is what must recognise
-     * them, and every product on the shared producer is correct with no
-     * configuration. Pass your own list to ADD product-specific error prose;
-     * pass `[]` to disable the rule.
-     *
-     * Prefixes are bound as query parameters, never interpolated.
-     */
-    errorReplyPrefixes?: readonly string[];
-}): TurnHealthSource;
-
-export { type AlertSink, type AlertThrottleStore, type D1LikeForHealth, type FetchLike, type PersistedTurnRow, SHELL_ERROR_REPLY_PREFIXES, type SweepOptions, type SweepResult, type TurnHealthAlert, type TurnHealthCompleteInfo, type TurnHealthErrorInfo, type TurnHealthLifecycle, type TurnHealthLifecycleOptions, type TurnHealthReason, type TurnHealthSeverity, type TurnHealthSource, type TurnHealthVerdict, type TurnOutcomeInput, type UnansweredThread, classifyTurnOutcome, createConsoleAlertSink, createD1TurnHealthSource, createGuardedAlertSink, createMemoryThrottleStore, createMultiAlertSink, createSlackBotAlertSink, createThrottledAlertSink, createTurnHealthLifecycle, createWebhookAlertSink, describeReason, sweepSilentFailures, turnAlert };
+ * `/turn-health` — make a failure that returns success impossible to miss.
+ *
+ * Conventional health checks probe DEPENDENCIES and answer "is the sandbox
+ * reachable, is the router up". Every outage measured in this fleet happened
+ * with all dependencies green:
+ *
+ *   - gtm-agent answered 0 of ~250 user messages for sixteen consecutive days
+ *     while `/api/health` returned 200 the entire time;
+ *   - turns settled `completed` with `finalText: ""` and `outputTokens: 0`;
+ *   - six tool calls collapsed into one unparseable call, persisting nothing,
+ *     raising nothing.
+ *
+ * This module probes the OUTCOME instead, in two lanes that catch different
+ * things:
+ *
+ *   - LIVE — {@link createTurnHealthLifecycle} fills the `lifecycle` seam
+ *     `createChatTurnRoutes` already exposes, and pages the moment a turn
+ *     settles having delivered nothing.
+ *   - SWEEP — {@link sweepSilentFailures} runs on a cron and counts what
+ *     arrived against what was answered. It is the only lane that can see an
+ *     outage which produces no turns at all.
+ *
+ * Server-only, subpath-only. The alert transport is a seam; the shipped
+ * implementations target the ops webhook the org already runs.
+ */
+export { classifyTurnOutcome, describeReason, type TurnHealthReason, type TurnHealthSeverity, type TurnHealthVerdict, type TurnOutcomeInput, } from './classify.js';
+export { createTurnHealthLifecycle, type TurnHealthCompleteInfo, type TurnHealthErrorInfo, type TurnHealthLifecycle, type TurnHealthLifecycleOptions, } from './lifecycle.js';
+export { type AlertSink, type AlertThrottleStore, createConsoleAlertSink, createGuardedAlertSink, createMemoryThrottleStore, createMultiAlertSink, createSlackBotAlertSink, createThrottledAlertSink, createWebhookAlertSink, type FetchLike, type TurnHealthAlert, turnAlert, } from './sink.js';
+export { createD1TurnHealthSource, type D1LikeForHealth, SHELL_ERROR_REPLY_PREFIXES, type PersistedTurnRow, sweepSilentFailures, type SweepOptions, type SweepResult, type TurnHealthSource, type UnansweredThread, } from './sweep.js';