@cerebriline/core 4.100.240

package/dist/runtime/escalation/assessment.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The harness's own reading of why the model says it is stuck.
+ *
+ * The model's account of its own difficulty is the one piece of evidence it
+ * has an interest in. So this is computed beside it, from things that were
+ * counted rather than described, and both are shown: to the user before an
+ * approval, and to the expert in the brief, where a disagreement between the
+ * two is itself worth reading.
+ *
+ * Every line here is a measurement with a known error rate, taken from the
+ * replay of 360 harness runs that produced the trigger next door. What is
+ * deliberately absent is a verdict: none of these separates a hard task from a
+ * stuck model on its own, and a line that said "this model cannot do it" would
+ * be claiming a precision nothing in the study supports.
+ */
+import type { StruggleSignals } from "../safety/struggle-detector";
+export interface EscalationAssessmentInput {
+    /** Where the run is, so the reader can weigh the rest. */
+    iteration?: number;
+    /** The struggle detector's window, whether or not it fired. */
+    signals?: StruggleSignals;
+    transactions?: {
+        /** Transactions opened so far, including the one that is open. */
+        opened: number;
+        /** Judged and rolled back. */
+        discarded: number;
+        /** Judged, not kept, and left on disk because the check's answer moved. */
+        carried?: number;
+    };
+    /** A terminal guard has already stood down once for this task. */
+    guardStoodDown?: boolean;
+    /**
+     * What the complexity walker made of the files in play, already worded.
+     *
+     * A tiebreaker and nothing more. It measures how hard the code is to read,
+     * not how likely this model is to fix it, and each line says so where it is
+     * read -- the same discipline `check_file` keeps about its own bound.
+     */
+    complexity?: readonly string[];
+    /**
+     * An outside scorer's reading of the task, already worded -- Jev's
+     * complexity and "stuck" scores, where the host configured it. Each line
+     * says whose reading it is and what it saw; it is not one of the counts.
+     */
+    appraisal?: readonly string[];
+}
+/**
+ * Render the assessment, or nothing when nothing was measured.
+ *
+ * Nothing is a real answer: an escalation on turn three has no window behind
+ * it, and a section reading "0 failures, no transactions" would be presented
+ * as evidence of health when it is evidence of a run that has not started.
+ */
+export declare function buildEscalationAssessment(input: EscalationAssessmentInput): string | undefined;

package/dist/runtime/escalation/brief.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The one message that starts an escalation.
+ *
+ * The expert gets the brief, not the transcript. That is a decision, and worth
+ * stating: handing over the conversation would be cheaper to write and worse in
+ * both directions — it is the most expensive thing this feature can send, it
+ * arrives as thousands of tokens of a stuck model's reasoning, and a fresh
+ * model reading another model's dead ends adopts them. What the expert needs is
+ * the task, the goal, the standard it will be held to, and the record of what
+ * has already been tried and thrown away. Everything else it can read for
+ * itself: it has the same tools.
+ *
+ * The record is the part that is not obvious. A discarded transaction leaves no
+ * trace on disk — the files are byte-for-byte as they were before it — so an
+ * expert told only "it is still broken" will re-derive the plan that was just
+ * rolled back. The base model's own prompt carries this record for exactly that
+ * reason; so does this.
+ */
+import { type Oracle } from "../atomic/oracle";
+import type { TransactionOutcome } from "../atomic/protocol";
+/** What the open transaction looks like, when the change protocol is on. */
+export interface EscalationTransactionState {
+    /** One-based number of the open transaction. */
+    transaction: number;
+    maxTransactions: number;
+    maxChanges: number;
+    /** Changes already declared in it, when the host is counting them. */
+    changesUsed?: number;
+    /** The check the transaction will be judged by, when there is one. */
+    oracle?: Oracle;
+    /** What the base model said it would change in this transaction. */
+    plan?: string;
+    /** Transactions already tried and settled. */
+    history: readonly TransactionOutcome[];
+}
+export interface EscalationBriefInput {
+    /** What the base model wants done, in its own words. */
+    goal: string;
+    /** What it will accept as a correct delivery, in its own words. */
+    expectation?: string;
+    /** The task as the user stated it. */
+    task?: string;
+    workspaceRoot?: string;
+    /** Files the base model has been working in, as workspace-relative paths. */
+    filesInPlay?: readonly string[];
+    transaction?: EscalationTransactionState;
+    /**
+     * The harness's own reading of the code, when it has one.
+     *
+     * Attributed to the harness rather than folded into the goal, because it is
+     * the one piece of evidence here the base model did not write.
+     */
+    assessment?: string;
+    /** Which escalation this is, and how many this task gets. */
+    escalation: {
+        index: number;
+        of: number;
+    };
+    /** Follow-ups available after this delivery. */
+    followUpsAllowed: number;
+    /**
+     * Whether escalation took a snapshot of the workspace before handing over.
+     *
+     * Only with the change protocol off. With it on, the open transaction's own
+     * snapshot already covers the expert's edits and a second one would be a
+     * copy of a copy.
+     */
+    snapshotTaken?: boolean;
+}
+export declare function buildEscalationBrief(input: EscalationBriefInput): string;

package/dist/runtime/escalation/escalate-tool.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `escalate` — hand the task to a better model, and pay for it.
+ *
+ * The description below is the whole feature as far as the model is concerned,
+ * and it has to hold two things at once that pull in opposite directions.
+ *
+ * The expert costs more. It is a bigger model, often on a metered account, often
+ * shared, and always slower; a model that reads `escalate` as "ask for help"
+ * calls it on its first failed edit and the account pays for a question it could
+ * have answered by reading the file.
+ *
+ * And an expert nobody calls is worth nothing. The measured failure this feature
+ * exists for is not over-asking — it is a model looping until a guard ends the
+ * run: 25 of 61 jackod4ac runs broken and 5 timed out, with the loop guard
+ * ending more of them than any other cohort in the study. A description that
+ * only warns about cost produces a model that never escalates and stops anyway,
+ * having spent the same hours to fail.
+ *
+ * So it says both, in that order, and gives concrete conditions rather than a
+ * disposition: what to try first, and what being stuck actually looks like.
+ */
+import { type AgentTool } from "@cerebriline/shared";
+export declare const ESCALATE_TOOL_NAME = "escalate";
+export declare const ESCALATE_TOOL_DESCRIPTION = "Hand this task to the expert: a larger, more capable model that works in this same workspace and can edit it directly.\n\nWHAT IT COSTS. The expert is more expensive than you are. It may be a paid, metered account, a limited allowance, or hardware shared with other people, and it is slower than you. Your task gets a small, fixed number of escalations and no more. So do not escalate to save yourself reading a file, running the check, or thinking a problem through \u2014 that is the work, and it is yours.\n\nWHEN TO USE IT ANYWAY. The expert is there to help, and not calling it is not a virtue. You are not being scored on doing this alone: a task that runs out of turns and stops is a worse outcome than one that cost an escalation and worked. Escalate when you are actually stuck, which looks like this \u2014 the same fix attempted and rolled back more than once; a symptom you have read the code for and still cannot explain; a check that keeps failing for a reason you cannot name; or a piece of the task that needs knowledge you do not have. When one of those is true, escalate now rather than after three more attempts: the earlier you hand over, the more budget is left to act on what comes back.\n\nHOW TO USE IT. Say what you want done (`goal`) and how you will know it is right (`expectation`). Be specific \u2014 the expert starts with none of your conversation, only what you write here plus the task, the workspace state and what has already been tried and discarded. Name the files you have been working in (`files`).\n\nWHAT COMES BACK. The expert's own account of what it changed and what it ran, as its reply. Read it and check it: run the check yourself, look at the files it says it edited, and satisfy yourself the change is a fix rather than a way around the symptom. You are still the one accountable for this task.\n\nIf the delivery does not hold up, say so \u2014 call this tool again with `message` to push back, quote what you found, and ask for the specific thing that is wrong. That is what the conversation is for, and it is much cheaper than a second escalation. When you are satisfied, call it once more with `finished: true` to end the exchange and release the expert.";
+export declare const ESCALATE_TOOL_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly goal: {
+            readonly type: "string";
+            readonly description: "What you want the expert to achieve, in your own words. Required when you are starting an escalation. Be concrete: the symptom, what you have already established, and what you want done about it.";
+        };
+        readonly expectation: {
+            readonly type: "string";
+            readonly description: "What you will accept as a correct delivery, and how you intend to check it. The expert is told this, so it knows what it is being held to.";
+        };
+        readonly files: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Files you have been working in, as paths relative to the workspace root. A starting point for the expert, not a boundary.";
+        };
+        readonly message: {
+            readonly type: "string";
+            readonly description: "Your reply to the expert, once an escalation is open: a push-back on what it delivered, an answer to a question it asked, or a narrower follow-up. Quote what you actually found.";
+        };
+        readonly finished: {
+            readonly type: "boolean";
+            readonly description: "Set when you are done with the expert. Ends the exchange and releases it. Nothing else ends it, and an exchange left open holds the expert's slot for the rest of the task.";
+        };
+    };
+    readonly required: readonly [];
+};
+/** What the model asked for, after the input has been read. */
+export interface EscalationRequest {
+    /** The goal, when this call is opening an escalation. */
+    goal?: string;
+    expectation?: string;
+    files?: string[];
+    /** The model's reply, when an exchange is already open. */
+    message?: string;
+    /** The model says it is done with the expert. */
+    finished?: boolean;
+}
+export interface EscalationExchangeResult {
+    /** What the expert said. */
+    reply: string;
+    /** Whether this call opened an escalation rather than continuing one. */
+    opened: boolean;
+    followUpsLeft: number;
+    escalationsLeft: number;
+    /** Whether the exchange is over — because the model said so, or the host. */
+    closed?: boolean;
+    /**
+     * The expert has the work and is still doing it.
+     *
+     * The non-blocking hand-over. `reply` is then the hand-over notice rather
+     * than a delivery, and wrapping it in "check this before you build on it"
+     * would have the base model checking work that has not happened yet.
+     */
+    handedOver?: boolean;
+}
+export interface EscalateToolOptions {
+    /**
+     * Runs the exchange: budget, brief, the expert's conversation, and the
+     * accounting. Owned by the session, as `submit_transaction`'s settle is,
+     * because everything it touches outlives one tool call.
+     */
+    consult: (request: EscalationRequest) => Promise<EscalationExchangeResult>;
+    onError?: (message: string, error: unknown) => void;
+}
+export declare function readEscalationRequest(input: unknown): EscalationRequest;
+export declare function createEscalateTool(options: EscalateToolOptions): AgentTool;

package/dist/runtime/escalation/escalation-controller.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What a task is allowed to spend on the expert, and what happens to the
+ * conversation between escalations.
+ *
+ * Two bounds, and they answer different questions. The follow-up cap inside
+ * {@link ExpertSession} stops one exchange running away — two models talking to
+ * each other until something times out. This one stops a *task* running away:
+ * three hand-overs is a model that has been given real help three times and is
+ * still stuck, and a fourth is not what that task needs.
+ *
+ * Running out is not a failure state that needs explaining away. It restores
+ * exactly the behaviour every build before this one had: the guards stop the
+ * run. The message says so, because a model told only "denied" will spend its
+ * remaining turns trying to find the wording that works.
+ */
+import type { ExpertSession, ExpertUsage } from "./expert-session";
+export interface EscalationControllerOptions {
+    /** Hand-overs allowed in this task. */
+    maxEscalations: number;
+    /**
+     * Release the expert's conversation at the end of each escalation.
+     *
+     * See {@link ExpertSession} for why both answers are right on different
+     * hardware. Off means hold.
+     */
+    closeAfterEscalation: boolean;
+    /** Builds a fresh expert conversation. Called only when one is needed. */
+    createSession: () => ExpertSession;
+}
+export interface EscalationController {
+    /** Hand-overs made so far. */
+    readonly used: number;
+    /** Hand-overs still allowed. */
+    readonly remaining: number;
+    /** The conversation now open, if any. */
+    readonly session: ExpertSession | undefined;
+    /** Everything the expert has spent in this task, open conversations included. */
+    readonly usage: ExpertUsage;
+    /** Spends one escalation and returns the conversation to ask through. */
+    begin(): ExpertSession;
+    /**
+     * Gives back an escalation that bought nothing.
+     *
+     * A hand-over is charged at {@link begin}, before the expert has been asked
+     * anything, because that is the only place that can refuse one. When the ask
+     * then fails outright -- the endpoint is down, the model is unavailable, the
+     * run finished on `error` -- no expert saw the task and the budget must not
+     * record that it did. Floors at zero: refunding what was never spent would
+     * hand the task a fourth escalation out of a budget of three.
+     *
+     * The conversation goes with it when it has delivered nothing. A held
+     * session that never opened still reads as live to the next `escalate`,
+     * which would then arrive as a follow-up -- the model's raw goal, into an
+     * empty context, instead of the brief a hand-over builds.
+     */
+    refund(): Promise<void>;
+    /** Ends the current escalation: closes the conversation, or holds it. */
+    end(): Promise<void>;
+    /** Task teardown. Releases whatever is held, whatever the setting says. */
+    dispose(): Promise<void>;
+}
+export declare function createEscalationController(options: EscalationControllerOptions): EscalationController;

package/dist/runtime/escalation/escalation-session.d.ts

@@ -0,0 +1,241 @@
+/**
+ * The escalation path, assembled: the tool, the budget, the brief, and what
+ * happens to the workspace while a second model is editing it.
+ *
+ * Built the way the atomic protocol is built — decorated onto a session at
+ * construction rather than registered as a default tool — for the same reason.
+ * A default tool has to be declared in six places, is offered to every session
+ * whether or not the feature is configured, and would answer "no expert is
+ * configured" to a model that is stuck, which is the one state in which it will
+ * keep calling. Here the tool exists only where an expert does.
+ *
+ * Three things this owns that nothing else can:
+ *
+ *   the budget       a stuck model with an unmetered escalate is a stuck model
+ *                    with a larger bill. See `escalation-controller.ts`.
+ *   the read drop    the expert moves lines the base model has already read,
+ *                    and the editor's read-before-edit guard is all that stands
+ *                    between a stale line number and the file on disk.
+ *   the snapshot     the expert edits. With the change protocol on, the open
+ *                    transaction already covers that. With it off, nothing did
+ *                    until this: handing edit rights to a second model with no
+ *                    way back is not a feature, it is a liability.
+ */
+import type { AgentEvent, AgentTool } from "@cerebriline/shared";
+import type { AgentSlotGate } from "../../extensions/tools/team/agent-slot-gate";
+import type { CoreEscalationConfig } from "../../types/config";
+import { type RestoreReport, type Snapshot } from "../atomic/snapshot";
+import type { EscalationTransactionState } from "./brief";
+import type { ExpertMailbox } from "./expert-mailbox";
+import type { ExpertNotes } from "./expert-notes";
+import type { ExpertRevisions } from "./expert-revisions";
+import { type ExpertRuntime, type ExpertUsage } from "./expert-session";
+import { type StandDown } from "./stand-down";
+/** Escalations one task gets. */
+export declare const DEFAULT_MAX_ESCALATIONS = 3;
+/** Follow-ups within one escalation, after the first delivery. */
+export declare const DEFAULT_MAX_FOLLOW_UPS = 20;
+/**
+ * What the host is told, as it happens.
+ *
+ * Events rather than log lines because the exchange belongs in the chat: the
+ * user is paying for this model and is entitled to read what it was asked and
+ * what it said, in the transcript, beside the work it produced.
+ */
+export type EscalationEvent = {
+    type: "escalation_started";
+    index: number;
+    of: number;
+    brief: string;
+} | {
+    type: "expert_asked";
+    message: string;
+} | {
+    type: "expert_replied";
+    reply: string;
+    /** Workspace-relative paths the expert changed. */
+    changed: string[];
+    usage: ExpertUsage;
+} | {
+    type: "expert_said";
+    index: number;
+    of: number;
+    kind: "thinking" | "message";
+    text: string;
+} | {
+    type: "expert_progress";
+    index: number;
+    of: number;
+    toolCalls: number;
+    lastTool?: string;
+    usage: ExpertUsage;
+} | {
+    type: "escalation_ended";
+    held: boolean;
+    usage: ExpertUsage;
+} | {
+    /**
+     * The expert's run failed. Before this nothing reached the chat: the
+     * base model read the failure in its tool result, and the user's
+     * "working" row spun on (Chris's .213 session, a usage limit after
+     * 70 minutes).
+     */
+    type: "escalation_failed";
+    index: number;
+    of: number;
+    reason: string;
+    /** Workspace-relative paths the expert changed before it failed. */
+    changed: string[];
+    /** What the failed turn had spent, as its last progress report said. */
+    usage?: ExpertUsage;
+    /** The provider refused for the account's usage limit. */
+    limitReached: boolean;
+};
+/**
+ * What the user said when the escalation was put to them.
+ *
+ * A bare boolean is still accepted because a host with only a yes/no to offer
+ * should not have to wrap it, and every host did exactly that until the
+ * approval moved out of a modal dialog and into the chat, where there is room
+ * to say why.
+ */
+export type EscalationApproval = boolean | {
+    approved: boolean;
+    feedback?: string;
+};
+export interface EscalationSessionOptions {
+    workspaceRoot: string;
+    config: CoreEscalationConfig | undefined;
+    /** Builds the expert's runtime on the escalation connection. */
+    openExpert: (context: {
+        onEvent: (event: AgentEvent) => void;
+    }) => Promise<ExpertRuntime>;
+    /** The open transaction, read at hand-over. Absent means the protocol is off. */
+    readTransaction?: () => EscalationTransactionState | undefined;
+    /** The task as the user stated it. */
+    readTask?: () => string | undefined;
+    /**
+     * The harness's own reading of the run, and of the code in play.
+     *
+     * Given the files the model named so the reading can cover them, and the
+     * model's goal and reason so a scorer can read what is being handed over.
+     * What comes back is opaque text for the brief and the approval dialog.
+     */
+    assess?: (context: {
+        files?: readonly string[];
+        goal?: string;
+        reason?: string;
+    }) => Promise<string | undefined>;
+    /** Retires what the base model had read about a file the expert changed. */
+    forgetReads?: (absolutePath: string) => void;
+    /**
+     * Where the expert's writes are recorded, when the host wired one up.
+     *
+     * Opened on the first ask of an escalation and purged when that escalation
+     * ends. The session owns the lifecycle because it is the only thing that
+     * knows both -- the host builds the log and decorates the expert's tools
+     * with it, but it never sees an escalation begin or finish.
+     */
+    revisions?: ExpertRevisions;
+    /**
+     * The base model's stand-down, and with it the non-blocking hand-over.
+     *
+     * Its presence is the switch. Given one, `escalate` returns as soon as the
+     * expert has been handed the work and the base model stays live, watching
+     * through `wait_for_expert` and barred from writing. Left out, the tool
+     * blocks until the expert delivers, which is what it did before any of this
+     * existed and what the "alternate usage" setting asks for: one model in
+     * memory at a time, and no supervision to pay for.
+     */
+    standDown?: StandDown;
+    /** Where the expert's activity is collected for the base model. */
+    notes?: ExpertNotes;
+    /**
+     * The guards watching the expert's own channels, for their reset.
+     *
+     * The session owns the reset for the same reason it owns the revision
+     * log's: it is the only thing that knows an escalation has ended, and
+     * evidence carried from one escalation into the next would have the base
+     * model told the expert is looping before it has done anything.
+     */
+    guards?: {
+        reset(): void;
+    };
+    /**
+     * Where a message for a still-working expert waits for its next turn.
+     *
+     * Without one, `escalate` with a `message` during a hand-over can only say
+     * "it is still working" -- which is true and useless, because the two
+     * things the base model is watching for are exactly the two that cannot
+     * wait for the delivery: a question the expert asked, and an expert going
+     * round in circles that should stop now rather than in forty turns.
+     */
+    mailbox?: ExpertMailbox;
+    /** How long `wait_for_expert` sleeps between looks. Tests override it. */
+    watchTickMs?: number;
+    /** Overridable for tests; the real one is a timer. */
+    wait?: (ms: number) => Promise<void>;
+    /**
+     * Takes whatever the user has typed since it was last asked, if anything.
+     *
+     * The same queue the turn boundary drains, drained here because that
+     * boundary will not come round: while the expert is working the base model
+     * is blocked inside a tool call, so a steering message would otherwise wait
+     * out the entire exchange it was written about.
+     */
+    takeSteering?: () => string | undefined;
+    /**
+     * Puts the escalation to the user before it happens.
+     *
+     * Only consulted where the host set `requireApproval`. A refusal spends
+     * nothing: the budget rations the model, and a person saying no is not the
+     * model overspending.
+     */
+    approve?: (request: {
+        brief: string;
+        index: number;
+        of: number;
+    }) => Promise<EscalationApproval>;
+    /** The escalation endpoint's slot gate, when the host resolved one. */
+    gate?: Pick<AgentSlotGate, "run" | "active">;
+    onEvent?: (event: EscalationEvent) => void;
+    logger?: {
+        log?: (message: string) => void;
+    };
+    /** Overridable for tests; the real ones read and write the workspace. */
+    takeSnapshot?: (root: string) => Promise<Snapshot>;
+    restoreSnapshot?: (snapshot: Snapshot) => Promise<RestoreReport>;
+}
+export interface EscalationSession {
+    /** `escalate`, where an expert is configured. Empty where none is. */
+    readonly tools: AgentTool[];
+    /** Escalations made. */
+    readonly used: number;
+    /**
+     * Escalations still available.
+     *
+     * Read by the struggle detector's offer, which must not suggest a tool call
+     * the budget would refuse -- an offer the model takes and is turned down on
+     * is worse than no offer.
+     */
+    readonly remaining: number;
+    /** What the expert has spent in this task. */
+    readonly usage: ExpertUsage;
+    /**
+     * Puts the workspace back as the first escalation found it.
+     *
+     * Only meaningful where escalation took a snapshot — that is, where the
+     * change protocol was off. Undefined when there is nothing to go back to.
+     */
+    restore(): Promise<RestoreReport | undefined>;
+    /** Task teardown. Releases a held expert. */
+    dispose(): Promise<void>;
+}
+/**
+ * The provider refused because the account ran out of allowance.
+ *
+ * Ollama's cloud says "you have reached your session usage limit" (and 402 on
+ * the wire); hosted APIs say quota or limit with a 402 or 429.
+ */
+export declare function isUsageLimit(reason: string): boolean;
+export declare function createEscalationSession(options: EscalationSessionOptions): EscalationSession;

package/dist/runtime/escalation/expert-failure.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The expert's run failing after it had already written files.
+ */
+/**
+ * An expert run that failed, with the files it changed before it did.
+ *
+ * `changed` holds workspace-relative paths. The escalate and wait tools read it
+ * so that "the escalation did not happen" is not followed by "nothing has
+ * changed" when the expert had in fact written files.
+ */
+export declare class ExpertRunFailedError extends Error {
+    readonly changed: string[];
+    constructor(message: string, changed: string[], options?: ErrorOptions);
+}
+/**
+ * What the base is told about a failed expert run's edits.
+ *
+ * Empty when the run changed nothing, so the caller can keep saying so.
+ */
+export declare function describeFailedExpertChanges(error: unknown): string;

package/dist/runtime/escalation/expert-guards.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The same guards that decide the base model is stuck, run on the expert.
+ *
+ * The escalation path has always had one direction. A guard notices the base
+ * model going round in circles and offers it an expert; nothing then watches
+ * the expert, and the measured failure that motivated this is an expert doing
+ * exactly what the base was doing -- the nemotron 3 nano run the user named,
+ * which rewrote the same file over and over while the base sat blocked inside
+ * a tool call with no way to see it or stop it.
+ *
+ * So the guards run in both directions (user, 2026-09-14: "the same that
+ * triggered an escalation can be used on the expert to trigger deescalation").
+ * What comes out is NOT a decision. These verdicts do not end the expert's run,
+ * do not cancel the escalation and do not roll anything back: they become a
+ * note, the note wakes the base model, and the base model -- which can read the
+ * files, run the check and see what the expert actually delivered -- decides.
+ * That is deliberate. A guard that ended an expert's run would be the same
+ * automation the base model is there to replace, and every threshold here has a
+ * known false-positive rate that is fine for a nudge and not fine for a kill.
+ *
+ * THE WORDING IS FOR THE READER, NOT THE SUBJECT. Both detectors write their
+ * messages at the model being measured -- "this call was refused, move on to
+ * the next thing". Handed to the base model unchanged, that reads as an
+ * instruction to the base about its own work, which it is not doing. Each
+ * verdict is re-framed here as an observation about somebody else.
+ */
+import type { AgentEvent } from "@cerebriline/shared";
+import { type StruggleThresholds } from "../safety/struggle-detector";
+export interface ExpertGuardVerdict {
+    /** Which guard spoke. */
+    kind: "loop" | "struggle";
+    /** Worded for the base model, as an observation about the expert. */
+    text: string;
+}
+export interface ExpertGuardOptions {
+    onVerdict: (verdict: ExpertGuardVerdict) => void;
+    /** The struggle detector's operating point, where the host sets one. */
+    thresholds?: Partial<StruggleThresholds>;
+}
+export interface ExpertGuards {
+    /** Fold one of the expert's events in. */
+    observe(event: AgentEvent): void;
+    /** A new escalation is a new question. Forget the last one's evidence. */
+    reset(): void;
+}
+export declare function createExpertGuards(options: ExpertGuardOptions): ExpertGuards;

package/dist/runtime/escalation/expert-mailbox.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What the base model says to the expert while the expert is still working.
+ *
+ * The escalation already had a channel in one direction and at one moment: the
+ * base asks, the expert answers, and between those two points neither could say
+ * anything to the other. That was tolerable while `escalate` blocked -- the base
+ * was not running, so it had nothing to say -- and it is not tolerable now. The
+ * base is live, it is being told what the expert is doing, and the two things it
+ * is there for both require a channel: answering a question the expert asked,
+ * and telling an expert that is going round in circles to stop.
+ *
+ * This is the same shape as the team mailbox next door in `multi-agent.ts`,
+ * built separately rather than reused because that one is keyed by agent id
+ * across a roster of teammates and carries a notification telling the recipient
+ * to go and read its messages with a tool. There is exactly one expert, it has
+ * no mailbox tool, and the message has to arrive in the turn rather than as an
+ * invitation to fetch it.
+ *
+ * THE LABEL IS THE POINT. The expert reads this in the middle of its own work,
+ * where an unlabelled paragraph is indistinguishable from the user speaking --
+ * and a correction from the person who owns the task is worth more than one the
+ * supervising model inferred from a note. Both are worth acting on and they are
+ * not worth the same, so they are never merged. When the base is passing on
+ * something the user said, it says so in its own words, inside its own message.
+ */
+export interface ExpertMailbox {
+    /** Queue something for the expert's next turn. */
+    send(text: string): void;
+    /** Everything waiting, labelled and cleared. Nothing when empty. */
+    take(): string | undefined;
+    /** The escalation is over; nothing waiting is worth delivering. */
+    clear(): void;
+}
+export declare function createExpertMailbox(): ExpertMailbox;