@sema-agent/core/dist/brain/terminal-cause.d.ts

Stateless, task-oriented AI agent core

import type { AssistantMessage } from "../internal/llm.js";
/**
 * RB-464 — the DELIBERATE brain-side cut, read as a TYPED cause instead of by comparing the
 * turn's human-readable `errorMessage` against an exported sentinel string.
 *
 * Why this file exists at all. The cut is a cross-LAYER signal: a brain stamps it, the loop's
 * recovery lane reacts, and the assembler maps it to a terminal code. Carrying it as sentinel prose
 * — even an exported constant compared by identity, which at least reworders freely — makes the
 * CAUSE a string: a brain that stamps the same sentence without importing the constant (a custom
 * `Brain`, a message rebuilt from a field whitelist, a re-encode through a host that normalizes
 * whitespace) is invisible to every reading site at once, silently, with the tests still green
 * because they import the constant too. `errorKind` carries the cause as data instead; these
 * predicates are the single place that knows how to read it.
 *
 * There is no `errorMessage`-sentinel fallback: `errorKind` is the ONE read. The two shapes such a
 * fallback served are closed the documented way — older stored turns are the sacrificed-replay class,
 * and stamping `errorKind` on every cut turn is a documented Brain obligation (see the field's
 * contract note on AssistantMessage). A custom brain that stamps only the sentinel prose is not
 * recognized; the retirement was declared in the 5.1.0 CHANGELOG.
 */
/** The subset of an assistant turn that carries a terminal cause. Accepts a full {@link AssistantMessage}. */
export type TerminalCauseCarrier = Pick<AssistantMessage, "errorKind">;
/**
 * True when this turn is the brain's DEGENERATE-REPETITION cutoff (design/39): the model looped on the
 * same text and the brain cancelled the stream, keeping the salvageable prefix.
 *
 * Deliberately does NOT also require `stopReason === "error"`. Callers that need the terminal shape
 * check it themselves (the assembler does); the recovery lanes are handed an already-errored turn.
 * Folding the check in here would silently change those call sites' meaning.
 */
export declare function isDegenerateCutMessage(message: TerminalCauseCarrier): boolean;