@cerebriline/core 4.100.240

package/dist/runtime/safety/mistake-tracker.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Per-session consecutive-mistake tracker.
+ *
+ * @see PLAN.md §3.1 — wrapped around `recordMistake` moved from
+ *                    `packages/agents/src/api/error-handling.ts` lines 147–311.
+ * @see PLAN.md §3.2.3 — public surface of `MistakeTracker`.
+ *
+ * The pure procedural `recordMistake(input, deps)` becomes `record(input)`
+ * on the class; `consecutiveMistakes` is internal state. Other deps flow
+ * through the constructor instead.
+ *
+ * NOTE: the §3.2.3 constructor shape omits some fields (agentId,
+ * conversationId/runId getters, appendRecoveryNotice). They are retained
+ * here for log + notice parity per PLAN.md §3.4.3/§3.4.5. Step 8
+ * (`impl-runtime-porter`) may refactor once SessionRuntime is wired up.
+ */
+import type { AgentEvent, BasicLogMetadata, ConsecutiveMistakeLimitContext, ConsecutiveMistakeLimitDecision } from "@cerebriline/shared";
+/**
+ * Legacy-agents-style leveled log function. The sdk-re `BasicLogger`
+ * does not carry a level argument (§shared/logging/logger.ts); callers
+ * are expected to bridge via `metadata.severity` or dispatch to
+ * `debug`/`log`/`error`. `MistakeTracker` accepts a leveled callable
+ * here so Step 8 can plug in whichever bridging shape `SessionRuntime`
+ * ends up using.
+ */
+export type LeveledLog = (level: "debug" | "info" | "warn" | "error", message: string, metadata?: BasicLogMetadata) => void;
+export type MistakeReason = "api_error" | "invalid_tool_call" | "tool_execution_failed";
+export interface RecordMistakeInput {
+    iteration: number;
+    reason: MistakeReason;
+    details?: string;
+    /**
+     * Stop now, whatever the count says.
+     *
+     * This used to jump the counter to the limit, which forced the stop but also
+     * made the count a lie: a repeated-call loop stopped a run that had two
+     * failures behind it and the user was told Cline "ran into 6 errors in a
+     * row", with two successful edits among the turns it was counting. The stop
+     * is forced here instead, so the number stays the number.
+     */
+    forceAtLimit?: boolean;
+}
+export type MistakeOutcome = {
+    action: "continue";
+    guidance?: string;
+} | {
+    action: "stop";
+    message: string;
+    reason?: string;
+};
+export interface MistakeTrackerOptions {
+    readonly maxConsecutiveMistakes: number;
+    readonly onLimitReached?: (ctx: ConsecutiveMistakeLimitContext) => Promise<ConsecutiveMistakeLimitDecision> | ConsecutiveMistakeLimitDecision;
+    /**
+     * Observability hook fired exactly once per limit hit, right before the
+     * limit decision is resolved — regardless of whether `onLimitReached` is
+     * configured or what it decides. Used for telemetry.
+     */
+    readonly onLimitTelemetry?: (ctx: ConsecutiveMistakeLimitContext) => void;
+    readonly emit: (event: AgentEvent) => void;
+    readonly log: LeveledLog;
+    readonly agentId: string;
+    readonly getConversationId: () => string;
+    readonly getActiveRunId: () => string;
+    readonly appendRecoveryNotice: (message: string, reason: MistakeReason) => void;
+}
+export declare class MistakeTracker {
+    private consecutiveMistakes;
+    private readonly options;
+    constructor(options: MistakeTrackerOptions);
+    record(input: RecordMistakeInput): Promise<MistakeOutcome>;
+    reset(): void;
+    get value(): number;
+}
+export declare function buildMistakeLimitStopMessage(input: {
+    iteration: number;
+    consecutiveMistakes: number;
+    maxConsecutiveMistakes: number;
+    reason: "api_error" | "invalid_tool_call" | "completion_without_submit" | "tool_execution_failed";
+    details?: string;
+    stopReason?: string;
+    /** Stopped on demand rather than by reaching the limit. */
+    forced?: boolean;
+}): string;

package/dist/runtime/safety/rules.d.ts

@@ -0,0 +1,6 @@
+import type { RuleConfig, UserInstructionConfigWatcher } from "../../extensions/config/user-instruction-config-loader";
+export declare function isRuleEnabled(rule: RuleConfig): boolean;
+export declare function formatRulesForSystemPrompt(rules: ReadonlyArray<RuleConfig>): string;
+export declare function mergeRulesForSystemPrompt(primaryRules?: string, additionalRules?: string): string | undefined;
+export declare function listEnabledRulesFromWatcher(watcher: UserInstructionConfigWatcher): RuleConfig[];
+export declare function loadRulesForSystemPromptFromWatcher(watcher: UserInstructionConfigWatcher): string;

package/dist/runtime/safety/struggle-detector.d.ts

@@ -0,0 +1,414 @@
+/**
+ * Per-session scorer for "this run is not going anywhere".
+ *
+ * Built from 360 harness run digests, replayed against every run's iteration
+ * timeline. Two findings shaped it, and both cut against the obvious design:
+ *
+ * - **Absolute hedging does not separate anything.** `wait` spans 5.4 to 11.9
+ *   per 1,000 reasoning words across thirteen cohorts with no relation to
+ *   outcome: the highest rate in the study belongs to a mediocre model and the
+ *   lowest to the weakest one in it. What separates a converging run from a
+ *   stuck one is whether hedging *decays* -- `hmm` collapses to 14% of its
+ *   opening rate in runs that end FIXED and holds at 57% in runs that do not.
+ *   So the feature is the ratio of the current window to the run's own opening,
+ *   which needs no cross-model calibration.
+ * - **Lexical evidence alone is unusable.** `distress10 >= 2` catches 86% of
+ *   failures and fires on 62% of successes -- 46% of successes by the good
+ *   models, which should almost never be told they are struggling. Behavioural
+ *   evidence alone is precise and far too late: `f10 >= 5` arrives with 46
+ *   iterations left of a 300-iteration run.
+ *
+ * The conjunction is what earns its place. Replayed over the corpus it fires at
+ * 42% of the way in, leaves 91 iterations of budget to spend differently, and
+ * troubles a healthy good-model run once in twenty-five: 56% recall, 15% false
+ * alarm overall, 4% on the good models.
+ *
+ * Diagnosis only, never the consequence -- the same separation the loop
+ * detector next door keeps. What this says is what it measured; whether that
+ * earns an offer of help, and in what words, belongs to the caller.
+ */
+import type { AgentEvent } from "@cerebriline/shared";
+/** Iterations of history the trigger reads. */
+export declare const STRUGGLE_WINDOW = 10;
+/**
+ * Failed tool calls in that window before the behavioural half is satisfied.
+ *
+ * **Six, raised from four when the signal underneath it was corrected.** Four
+ * was fitted against `content_end.error`, and our tools almost never set it: a
+ * tool that refuses returns `{success: false, error: ...}` as its output and
+ * the call is reported as a success. `refusalIn` below now counts both, which
+ * moved the measurement by an order of magnitude rather than a little.
+ *
+ * Replayed over 288 harness runs -- 219 that reached FIXED, 69 that ended
+ * broken or timed out -- with the old signal against the new one, at the same
+ * thresholds:
+ *
+ * ```
+ *          error only            error + refusal
+ *   N=3    3% / 19%              47% / 91%          (false alarm / recall)
+ *   N=4    3% / 10%              35% / 87%
+ *   N=5    2% /  4%              25% / 74%
+ *   N=6    1% /  3%              13% / 57%
+ * ```
+ *
+ * The old four was not a conservative operating point, it was an unreachable
+ * one: it caught 10% of the runs that failed. The new four is the opposite
+ * problem -- the nudge fires one below the trigger, so four here means the
+ * model is nudged on 47% of the runs that go on to succeed. Six restores the
+ * intended rarity with 57% recall, which is better than the old number ever
+ * delivered, and `STRUGGLE_EDIT_STREAK` covers the loops it gives up.
+ */
+export declare const STRUGGLE_FAILED_CALLS = 6;
+/** Distress-lexicon hits in the window that satisfy the lexical half. */
+export declare const STRUGGLE_DISTRESS_HITS = 2;
+/**
+ * Before this iteration nothing fires, whatever the evidence says.
+ *
+ * A run that is genuinely stuck at iteration 12 is indistinguishable from one
+ * that is still reading the problem, and the corpus has no operating point
+ * below 20 that is worth its false alarms.
+ */
+export declare const STRUGGLE_MIN_ITERATION = 20;
+/** Suggestions per task. Two, and at most one per transaction. */
+export declare const STRUGGLE_MAX_PER_TASK = 2;
+/**
+ * Consecutive failing edits before the model is told to consider the expert.
+ *
+ * Separate from `STRUGGLE_FAILED_CALLS` because it is a different measurement,
+ * not a smaller one. That threshold reads a ten-turn window of every tool the
+ * session called; this one reads an unbroken run of calls to the tools that
+ * change a file, and it does not care how far apart the turns are.
+ *
+ * Three, measured. Across 307 harness runs and one 829-message plugin session,
+ * the longest unbroken run of refused calls is 2 in a run that finishes and 4
+ * to 8 in the three that do not, so 3 is the first value that separates them.
+ * Two would fire on healthy runs; four arrives after the loop is established.
+ */
+export declare const STRUGGLE_EDIT_STREAK = 3;
+/**
+ * Attempts the change protocol threw away before the model is told.
+ *
+ * A discarded transaction is an attempt that ran, failed its check and was put
+ * back; an empty submission is one spent with nothing changed. Both are counted
+ * because both are an attempt the run no longer has.
+ *
+ * **Two, measured, and it is the only signal here the protocol emits.** The
+ * failed-call window is structurally blind to it: a model failing the protocol
+ * calls its tools *successfully* and is told by the result that the check did
+ * not pass. Replayed over 335 harness runs with a verdict (236 FIXED, 99
+ * broken/timed out), false alarm / recall:
+ *
+ * ```
+ *   >= 1 thrown away    2.5% / 18%
+ *   >= 2 thrown away    0.0% / 15%     <- this
+ *   >= 3 thrown away    0.0% / 13%
+ * ```
+ *
+ * Zero of 236 runs that reached FIXED ever threw away two. That is what buys
+ * it a place beside `STRUGGLE_FAILED_CALLS` rather than in place of it: the two
+ * signals fire on different populations, because a run without the protocol has
+ * no transactions and a run with it fails half as many tool calls (8.2% against
+ * 18.6%). Read together they catch 59% of the failures at the 9% false alarm
+ * the window already costs on its own -- nine more runs, and not one new false
+ * alarm.
+ */
+export declare const STRUGGLE_FAILED_TRANSACTIONS = 2;
+/**
+ * The operating point, as the user may set it.
+ *
+ * These are load-bearing and the right numbers are an empirical question we
+ * have not finished answering -- the constants above are the best corpus fit
+ * so far, and one measured arm (jackod4ac, oracle, n=3) fired the trigger zero
+ * times because the change protocol produces no failed tool calls at all.
+ * Rather than keep guessing centrally, they are exposed so a run can set them
+ * and the defaults can be chosen from evidence.
+ *
+ * Every field is optional and falls back to the constant, so a host that says
+ * nothing behaves exactly as it did.
+ */
+export interface StruggleThresholds {
+    /** Iterations of history the trigger reads. */
+    window?: number;
+    /** Failed tool calls in that window before the behavioural half is satisfied. */
+    failedCalls?: number;
+    /** Distress-lexicon hits in the window that satisfy the lexical half. */
+    distressHits?: number;
+    /** Before this iteration nothing fires, whatever the evidence says. */
+    minIteration?: number;
+    /** Suggestions per task. */
+    maxPerTask?: number;
+    /** Consecutive failing edits before the model is told to consider the expert. */
+    editStreak?: number;
+    /** Attempts the protocol threw away before the model is told. */
+    failedTransactions?: number;
+}
+export interface ResolvedStruggleThresholds {
+    readonly window: number;
+    readonly failedCalls: number;
+    readonly distressHits: number;
+    readonly minIteration: number;
+    readonly maxPerTask: number;
+    readonly editStreak: number;
+    readonly failedTransactions: number;
+}
+export declare function resolveStruggleThresholds(given: StruggleThresholds | undefined): ResolvedStruggleThresholds;
+/**
+ * The refusal a tool reported inside a successful envelope, if it did.
+ *
+ * `content_end.error` is set only where the runtime marked the whole call an
+ * error, and our own tools almost never are: a tool that refuses returns
+ * `{success: false, error: "..."}` as its *output* and the call is reported as
+ * having succeeded. Measured on one 829-message session, that gap is the whole
+ * signal -- 3 calls carried `error`, 50 carried a refusal in the output, and
+ * 46 of 162 `editor` calls were refused. A detector reading only the first
+ * number is looking at 6% of what the model experienced.
+ *
+ * A call counts as refused only when nothing in it succeeded. The list-shaped
+ * tools return one result per item, so a `read_files` that found two paths of
+ * three did work the model can use and is not a failure.
+ */
+export declare function refusalIn(output: unknown): string | undefined;
+export interface StruggleSignals {
+    /** The iteration the verdict was asked for. */
+    iteration: number;
+    /** Failed tool calls in the last `STRUGGLE_WINDOW` iterations. */
+    failedCalls: number;
+    /** Distress-lexicon hits in the same window. */
+    distress: number;
+    /**
+     * Hedging in the window as a multiple of the run's own opening rate, or
+     * undefined where there is not yet an opening rate to compare against.
+     */
+    hedgingRatio?: number;
+}
+export interface StruggleVerdict {
+    /**
+     * `nudge` is the quieter one, and it arrives first.
+     *
+     * The offer at `suggest` is a real proposal: it costs money or somebody
+     * else's hardware, so it fires late and only on the disjunction. That left
+     * the turn before it silent, which is the turn where saying something is
+     * cheapest. A nudge is one failure short of the trigger, carries no
+     * proposal of its own, and stops as soon as the offer takes over.
+     */
+    kind: "ok" | "nudge" | "suggest";
+    /**
+     * Which measurement produced it, for a caller that words them differently.
+     *
+     * `failures` is the ten-turn window; `edit-streak` is an unbroken run of
+     * refused edits, which says something the window cannot -- that the model
+     * is not merely failing often but failing at the same thing, in a row.
+     * `transactions` is the protocol's own evidence, and it is the only one of
+     * the three that survives the protocol being on.
+     */
+    reason?: "failures" | "edit-streak" | "transactions";
+    /** What was measured. Never what should be done about it. */
+    message?: string;
+    signals?: StruggleSignals;
+    /**
+     * Files this session has changed, for a caller that can say something about
+     * them the detector cannot -- their complexity, which needs to read them.
+     */
+    files?: readonly string[];
+}
+export interface StruggleTurn {
+    iteration: number;
+    /** The model's reasoning for that turn, where the provider reports it. */
+    reasoning?: string;
+}
+export interface StruggleToolOutcome {
+    iteration: number;
+    failed: boolean;
+    /** The tool that ran, where the caller knows it. */
+    tool?: string;
+    /** What the tool said when it refused, where it said anything. */
+    refusal?: string;
+}
+export interface StruggleInspection {
+    iteration: number;
+}
+/**
+ * What the detector measured, in the model's own terms.
+ *
+ * Written as observation and nothing else. The loop detector's header explains
+ * why at length: a message that names a consequence the caller has not decided
+ * on describes something that did not happen.
+ */
+export declare function describeStruggle(signals: StruggleSignals, thresholds?: StruggleThresholds): string;
+/**
+ * What an unbroken run of refused edits looks like, in the model's own terms.
+ *
+ * Observation, like `describeStruggle` next door, and for the same reason: the
+ * caller owns what follows from it. What this adds over the window is the word
+ * *row* -- a model failing four calls out of ten is having a bad patch, and a
+ * model whose last three edits were all refused is trying the same thing.
+ */
+export declare function describeEditStreak(streak: number, lastRefusal?: string): string;
+/**
+ * What a run of thrown-away attempts looks like, in the model's own terms.
+ *
+ * Observation, like the two beside it. What this adds over both is *cost*: a
+ * failed tool call is a turn, and a discarded transaction is a whole attempt
+ * the task does not get back.
+ */
+export declare function describeFailedTransactions(thrownAway: number, discarded: number, empty: number): string;
+/**
+ * Per-session struggle scorer.
+ *
+ * The caller feeds it turns and tool outcomes and asks `inspect` at a boundary
+ * of its choosing. Nothing here reads the clock, the provider or the workspace.
+ */
+export declare class StruggleDetector {
+    private readonly limits;
+    private readonly history;
+    /** The run's opening hedging rate, frozen once the baseline window closes. */
+    private baseline?;
+    private baselineHedging;
+    private baselineWords;
+    private firedInTask;
+    private firedInTransaction;
+    private transaction;
+    private lastFiredKey?;
+    /**
+     * The nudge repeats while the evidence holds, and the evidence holds for
+     * many calls at a time. Keyed so that saying the same thing twice in a row
+     * -- which inspecting after every tool call would otherwise do several
+     * times per turn -- says it once.
+     */
+    private lastNudgeKey?;
+    /** Consecutive refused edits, counted over edit calls and nothing else. */
+    private editStreak;
+    /**
+     * Attempts the protocol threw away, over the whole task.
+     *
+     * Cumulative on purpose, and deliberately not reset by `noteTransaction`:
+     * what was measured is how many attempts a run has spent without keeping
+     * one, and a transaction that passes does not give back the two before it.
+     */
+    private discardedTransactions;
+    private emptyTransactions;
+    private lastEditRefusal?;
+    /**
+     * Files the session has changed, for the rule that a diagnosis is never
+     * repeated over an unchanged file set.
+     *
+     * A model told it is struggling, which then changes nothing, has been told
+     * everything this can tell it -- and the two-per-task allowance is there
+     * for a run that moved on to different code, not for one saying the same
+     * thing about the same file twice.
+     */
+    private readonly changedFiles;
+    constructor(thresholds?: StruggleThresholds);
+    /** The operating point in force, for whoever has to report it. */
+    get thresholds(): ResolvedStruggleThresholds;
+    /** Record a file this session has changed. */
+    noteFileChanged(path: string): void;
+    /** Record a turn's reasoning, which is where both lexicons are counted. */
+    noteTurn(turn: StruggleTurn): void;
+    /** Record one tool call's outcome. Only the failures are counted. */
+    noteToolOutcome(outcome: StruggleToolOutcome): void;
+    /**
+     * The change protocol closed an attempt.
+     *
+     * Only the two outcomes that cost the task an attempt are counted; `kept`
+     * is recorded and counts for nothing, which is what the corpus measured.
+     */
+    noteTransactionOutcome(outcome: "kept" | "discarded" | "empty"): void;
+    /**
+     * Context was compacted.
+     *
+     * Never fire across one. Compaction is normal for a long task -- 545
+     * occurrences in the corpus -- and the reasoning the window was counting is
+     * no longer in the conversation, so the evidence for a diagnosis the model
+     * would now be reading for the first time has been deleted. The window
+     * rebuilds from here.
+     */
+    noteCompaction(): void;
+    /**
+     * The change protocol opened a transaction.
+     *
+     * At most one suggestion per transaction: a second inside the same one is a
+     * repeat of a diagnosis the model has already been given and has not been
+     * able to act on yet.
+     */
+    noteTransaction(transaction: number): void;
+    /** The signals as they stand, without the caps or the firing decision. */
+    signalsAt(iteration: number): StruggleSignals;
+    inspect(input: StruggleInspection): StruggleVerdict;
+    /**
+     * The quieter verdict, one failure short of the offer.
+     *
+     * `failedCalls - 1`, derived rather than configured: the point of it is to
+     * speak on the turn before the trigger, so it has to move when the trigger
+     * moves. A host that sets `failedCalls: 1` gets no nudge at all, which is
+     * right -- there is no turn before the first one.
+     *
+     * It repeats while the count stays in the band, and the band is one wide by
+     * construction, so "repeats" is bounded by how long the model sits at
+     * exactly that many failures.
+     */
+    private nudgeAt;
+    /**
+     * Two attempts thrown away, said once per new pair.
+     *
+     * The same rule the streak uses and for the same reason: a model told about
+     * the second discard learns nothing from being told about the third, and it
+     * speaks again only once as much evidence has accumulated again.
+     */
+    private thrownAwayVerdict;
+    /**
+     * Three refused edits in a row, said once per new value of "three".
+     *
+     * It speaks again only once as much evidence has accumulated again -- at
+     * three, then six, then nine. A model that has already been told about the
+     * third refusal learns nothing from being told about the fourth, and a
+     * nudge that arrives on every one of them is how a diagnosis stops being
+     * read. The longest streak in the corpus is nine, so this is at most three
+     * messages in the worst run measured.
+     */
+    private editStreakVerdict;
+    /**
+     * Emit a nudge, or nothing if it would repeat the last one verbatim.
+     *
+     * `inspect` is asked after every tool call and every block of reasoning, so
+     * the same evidence is read many times per turn. Without this the model
+     * would be told the same thing four times in one reply, which is how a
+     * diagnosis stops being read.
+     */
+    private nudge;
+    private recordFor;
+    /**
+     * Fold a turn into the run's opening rate while the baseline is still open.
+     *
+     * Frozen after the first `STRUGGLE_WINDOW` iterations, because the
+     * comparison is against how this run started and a baseline that kept
+     * moving would converge on the window it is being compared to.
+     */
+    private absorbBaseline;
+}
+export interface StruggleFeed {
+    /** Fold one agent event into the detector, and inspect at a turn's end. */
+    observe(event: AgentEvent): void;
+}
+/**
+ * Drive a detector from the session's own event stream.
+ *
+ * Everything the trigger needs is already on the wire: `iteration_start`
+ * carries the cursor, `content_end` carries the turn's reasoning and each tool
+ * call's error, and `content_start` carries the tool input the file set is read
+ * from. Nothing here reaches into the runtime.
+ *
+ * `onVerdict` fires after every tool result, after every block of reasoning,
+ * and at the end of a turn. It used to fire only at the turn boundary, on the
+ * argument that a diagnosis arriving between two tool calls of one reply lands
+ * in the middle of work the model has already decided on. That argument was
+ * wrong about where the message goes: the caller holds the verdict and attaches
+ * it to the next tool result, so inspecting sooner does not interrupt anything
+ * -- it only stops the evidence waiting for a turn that a looping model may
+ * take hundreds of calls to end. The detector dedupes, so reading the same
+ * evidence four times in one reply still says it once.
+ *
+ * It receives both verdicts that carry something -- the offer and the nudge
+ * below it -- and never `ok`.
+ */
+export declare function createStruggleFeed(detector: StruggleDetector, onVerdict: (verdict: StruggleVerdict) => void): StruggleFeed;

package/dist/runtime/safety/worker-struggle-stop.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A struggle supervisor's stop, in words: what a delegated run's abort reason
+ * carries when the supervisor ended it (`worker-struggle.ts`).
+ *
+ * Its own module, importing nothing, because the iteration cap reads it
+ * (`agent-iteration-cap.ts`, which suspends such a run for the lead, as it
+ * does the loop guard's) and sits under every spawn path, while the
+ * supervisor itself reaches back into the tools through the struggle offer.
+ */
+/** Which signal moved a supervisor's phase. */
+export type WorkerStruggleReason = "struggle" | "non-progress" | "thinking-budget";
+/** Whether a run's abort reason is a supervisor stop. */
+export declare function isWorkerStruggleStop(reason: string | undefined): boolean;
+/**
+ * The supervisor's stop, in words the lead reads when it decides: what was
+ * measured, and that the worker had been told to commit a SUMMARY first.
+ */
+export declare function describeWorkerStop(reason: WorkerStruggleReason, counts?: {
+    spentAfterNudge?: number;
+}): string;