@cerebriline/core 4.100.240

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

@@ -0,0 +1,115 @@
+/**
+ * What the base model is told about the expert while the expert is working.
+ *
+ * The base model is live for the whole escalation now, standing down from
+ * edits and watching. Watching costs it a turn every time it is woken, and on
+ * a 9B base against an expert that makes a hundred tool calls that is the
+ * whole task budget spent on narration. So notes are collected continuously
+ * and handed over in batches.
+ *
+ * THE CLOCK RUNS FROM THE HAND-OVER, NOT FROM THE NOTE. The base is woken at
+ * most once per interval, and the interval starts when it last took a batch --
+ * so a base that spends four minutes reviewing does not come back to eight
+ * batches queued behind it. It comes back to one, holding everything that
+ * happened while it was away (user, 2026-09-14: "if it's not done with the
+ * previous review gets the next batch when it ends or more than one together
+ * or the remaining plus the notification the expert is done").
+ *
+ * THREE THINGS JUMP THE CLOCK, because waiting on them is worse than the turn
+ * they cost: the expert speaking (it may be asking a question), a guard
+ * tripping (the expert may be going in circles), and the task reaching a state
+ * that is not `working` -- `input-required` owes an answer, and a terminal
+ * state means there is nothing left to wait for.
+ *
+ * THINKING IS NOT A NOTE, and there is deliberately no method that takes it.
+ * The expert's reasoning runs to tens of thousands of characters per turn and
+ * the base model is the smaller of the two; handing it that is how the
+ * supervision budget gets spent on text the base cannot use. Tool calls and
+ * messages are what it needs to follow the work.
+ *
+ * EVERY CHANGED FILE CARRIES THE REVISION IT CAN BE READ AT. A batch describes
+ * what happened up to a moment that has already passed -- by the time the base
+ * reads "the expert edited manic_miner.html" the expert has edited it twice
+ * more, and a base that opens the file on disk is checking a claim against
+ * evidence that has moved. The revision number is the fixed point: it names
+ * the exact bytes the note is about, and `read_files` with `revision` serves
+ * them. That is what makes "I fixed function A and the linter is quiet" a
+ * testable statement rather than a claim about a file that no longer exists.
+ */
+import type { AgentToolDefinition } from "@cerebriline/shared";
+import { type Part, type TaskState } from "./a2a";
+/** A file the expert wrote, and the revision holding what it wrote. */
+export interface ExpertFileTouch {
+    path: string;
+    /** Its index in the expert's revision log, for `read_files`. */
+    revision: number;
+}
+export interface ExpertNote {
+    kind: "tool" | "message" | "guard";
+    /** The tool's name, for `kind: "tool"`. */
+    tool?: string;
+    /** What was said, for `kind: "message"` and `kind: "guard"`. */
+    text?: string;
+    /** How many identical calls this line stands for. Always at least 1. */
+    count: number;
+    files: ExpertFileTouch[];
+    /** The tool's own failure, where it had one. */
+    error?: string;
+}
+export interface ExpertNoteBatch {
+    state: TaskState;
+    /** The task has ended: this is the last batch there will be. */
+    final: boolean;
+    notes: ExpertNote[];
+    /** The batch as the base model and the panel each need it. */
+    parts: Part[];
+}
+export interface ExpertNotesOptions {
+    /** How long the base is left alone between batches. */
+    intervalMs?: number;
+    now?: () => number;
+}
+export interface ExpertNotes {
+    noteTool(input: {
+        tool: string;
+        files?: readonly ExpertFileTouch[];
+        error?: string;
+    }): void;
+    noteMessage(text: string): void;
+    noteGuard(text: string): void;
+    setState(state: TaskState): void;
+    readonly state: TaskState;
+    /** Notes waiting to be handed over. */
+    readonly pending: number;
+    /** Whether the base should be woken now. */
+    due(): boolean;
+    /** Everything waiting, cleared. Nothing when the base should be left alone. */
+    take(): ExpertNoteBatch | undefined;
+}
+export declare const DEFAULT_NOTE_INTERVAL_MS = 30000;
+export declare function createExpertNotes(options?: ExpertNotesOptions): ExpertNotes;
+export interface ExpertNoteTakerOptions {
+    notes: ExpertNotes;
+    /**
+     * The highest revision held for each file, read either side of a call.
+     *
+     * A diff rather than a reading of the tool's input, so this needs to know
+     * nothing about what any particular tool's arguments mean -- and so a tool
+     * that writes by a route this code has never heard of still shows up. What
+     * moved is what was written.
+     */
+    heads: () => ReadonlyMap<string, number>;
+    /** Workspace-relative paths for the note, where the host can give them. */
+    relative?: (absolutePath: string) => string;
+}
+/**
+ * Wrap the expert's tools so every call it makes becomes a note.
+ *
+ * Outside the revision capture, so the heads it reads afterwards already hold
+ * what the call wrote. What it cannot see is a tool that reports its own
+ * failure in its result rather than by throwing -- an editor that refuses, a
+ * command that exits non-zero -- and that is fine: the base model is being
+ * given the shape of the work, not a transcript, and a refused call that
+ * changed nothing is exactly the kind of detail the batching exists to drop.
+ */
+export declare function withExpertNotes<T extends AgentToolDefinition>(tools: readonly T[], options: ExpertNoteTakerOptions): T[];

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

@@ -0,0 +1,29 @@
+/**
+ * Who the expert is, for as long as the conversation lives.
+ *
+ * Separate from the brief on purpose. The brief is one escalation — a goal, a
+ * transaction, a record — and a held conversation gets a new one each time. This
+ * is the part that does not change: that the caller is a model rather than a
+ * user, that the expert is expected to edit rather than advise, and that what it
+ * hands back is going to be checked.
+ *
+ * The first of those is the one that earns its place. A model given a technical
+ * question by what it takes to be a user answers it: a paragraph of guidance, a
+ * suggested patch in a fenced block, and no edit. That is a correct response to
+ * the wrong situation, and it is exactly what a second opinion produced before
+ * this feature existed — the base model then had to transcribe the suggestion,
+ * which is the step it was stuck at in the first place. So this says, in the
+ * first line, that nobody is reading this but another model with the same tools.
+ */
+export interface ExpertPromptInput {
+    workspaceRoot?: string;
+    /**
+     * The rules the session itself is working under, where the host has them.
+     *
+     * A project's own instructions apply to whoever is editing. An expert that
+     * does not have them writes changes the base model has to undo, and it is
+     * the base model that gets blamed for the result.
+     */
+    sessionInstructions?: string;
+}
+export declare function buildExpertPrompt(input: ExpertPromptInput): string;

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

@@ -0,0 +1,62 @@
+/**
+ * Every version of every file the expert writes, for as long as the escalation
+ * lasts.
+ *
+ * WHY THE BASE MODEL NEEDS THIS. It is live while the expert works and it is
+ * told what the expert did in batches, which means every note describes a
+ * moment that has already passed. By the time the base reads "the expert edited
+ * manic_miner.html" the expert has edited it twice more, so a base that opens
+ * the file on disk is checking a claim against evidence that has moved under
+ * it. The revision number is the fixed point: it names the exact bytes the note
+ * was about, and `read_files` with `revision` serves them. That is what turns
+ * "I fixed function A and the linter is quiet" from an assertion into something
+ * testable (user, 2026-09-14: "this is a testable statement if run on the right
+ * snapshot").
+ *
+ * WHY IT IS NOT THE CHANGE PROTOCOL'S LOG. The protocol's revisions belong to
+ * the base model's open transaction -- its budget, its plan, its rollback --
+ * and the expert is not in that arrangement at all; as of this build it is not
+ * even given the protocol's tools. Sharing one log would mean the expert's
+ * writes renumbering the base model's history, and `restore_file` offering to
+ * put back a version the base never made.
+ *
+ * WHY IT IS PURGED AT THE END. A revision is worth holding while there is still
+ * a claim to check. When the escalation closes, the delivery has been made, the
+ * base has accepted or pushed back, and what is left is copies of files held in
+ * memory for a conversation that is over (user, 2026-09-14: "once the expert
+ * escalation is done, we purge the snapshots").
+ *
+ * The log, the de-duplication, the memory cap and the read decoration are all
+ * `runtime/atomic`'s, unchanged. This is the escalation's own instance of them.
+ */
+import { type FileRevision } from "../atomic/file-revisions";
+import type { RevisionCaptureSource } from "../atomic/revision-capture";
+import type { Snapshot } from "../atomic/snapshot";
+export interface ExpertRevisions {
+    /**
+     * What `withRevisionCapture` needs to decorate the expert's tools.
+     *
+     * Read through rather than copied: the base snapshot arrives when the
+     * escalation opens, which is after the expert's tools have been built.
+     */
+    readonly source: RevisionCaptureSource;
+    /** Begin an escalation's history at the workspace as it stands now. */
+    open(base: Snapshot, index: number): void;
+    /** Every version of one file, oldest first. #1 is as the escalation opened. */
+    revisions(absolutePath: string): readonly FileRevision[];
+    /** Files anything has been recorded for. */
+    tracked(): readonly string[];
+    /**
+     * The highest revision held for each file.
+     *
+     * What the note-taker diffs across a tool call to work out what that call
+     * wrote, without having to know what any particular tool's input means. A
+     * tool that writes two files in one call shows up as two entries moving,
+     * and a tool that writes nothing shows up as nothing moving -- which is
+     * also the right answer for a read.
+     */
+    heads(): ReadonlyMap<string, number>;
+    /** The escalation is over. Drop the history and the claim on the workspace. */
+    purge(): void;
+}
+export declare function createExpertRevisions(): ExpertRevisions;

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

@@ -0,0 +1,164 @@
+/**
+ * The expert's side of an escalation: one conversation, held or closed.
+ *
+ * An escalation is not a single question. The session's model states a goal and
+ * a scope, the expert answers, the model checks the answer against the task and
+ * pushes back if it does not hold — so what the expert needs is a conversation
+ * that survives between calls, and what the *host* needs is a decision about
+ * whether to keep it.
+ *
+ * Both answers are right on different hardware, which is why the decision is a
+ * setting rather than a default:
+ *
+ *   held    a hosted provider's prompt cache stays warm and the expert still
+ *           has the exchange in its context, so a follow-up sends one message
+ *           rather than the whole conversation again. On a metered account that
+ *           difference is the bill.
+ *   closed  a local server gets its slot back, which is what lets another model
+ *           load at all. `OLLAMA_MAX_LOADED_MODELS` is usually 1 or 2, and an
+ *           expert held open is a model the session's own cannot replace.
+ *
+ * The accounting is here rather than left to the host because the expert is the
+ * one model whose cost has to be separable. A total that folds the expert's
+ * tokens into the session's answers no question anybody has about a paid
+ * account, and the generation rate is the provider's own reported figure for
+ * the same reason the task header uses it: wall-clock over tokens would fold in
+ * queueing and tool time and move when the model did not.
+ */
+import type { AgentEvent, AgentResult } from "@cerebriline/shared";
+import type { AgentSlotGate } from "../../extensions/tools/team/agent-slot-gate";
+/**
+ * What an escalation spent.
+ *
+ * Two clocks, deliberately. `generateMs` is what the provider says it spent
+ * generating, and is the only honest input to a tok/s figure. `wallMs` is what
+ * the escalation actually took, queueing and prompt processing included, and is
+ * what a metered account is billed for.
+ */
+export interface ExpertUsage {
+    inputTokens: number;
+    outputTokens: number;
+    /** Tokens generated across the requests whose provider timed itself. */
+    generateTokens: number;
+    /** Milliseconds those requests spent generating, by the provider's clock. */
+    generateMs: number;
+    /** Wall-clock the expert was running, by ours. */
+    wallMs: number;
+    /**
+     * Requests the expert's provider was actually sent.
+     *
+     * This used to be the number of *turns asked of the expert*, which put two
+     * different denominators on one line: `inputTokens` sums the prompt of
+     * every request the expert's own agent loop makes, and an expert that
+     * works for an hour makes dozens. Run 0303 reported
+     * `expert_in=9,490,524 expert_requests=1` -- a prompt larger than any
+     * context window, over one request, which is impossible and was read as a
+     * broken counter rather than as two units. Now `inputTokens / requests` is
+     * the average prompt, which is what anyone dividing them expects.
+     *
+     * The turn count is not lost: it is `asks` below, and the harness already
+     * reports it separately as `expert_replies`.
+     */
+    requests: number;
+    /** Turns asked of the expert, the first brief included. */
+    asks: number;
+}
+/**
+ * What the expert has done so far in the turn that is still running.
+ *
+ * A hand-over is one tool call from the base model's point of view, so the
+ * chat has nothing to say between the brief and the delivery -- and an expert
+ * that reads a file twelve times over twenty minutes looks exactly like a hung
+ * request. This is what makes the difference visible while it is still true.
+ */
+export interface ExpertProgress {
+    /** Tool calls the expert has completed in this turn. */
+    toolCalls: number;
+    /** The last one's name, when the event carried it. */
+    lastTool?: string;
+    /** What the turn has spent so far, wall-clock included. */
+    usage: ExpertUsage;
+}
+/**
+ * A block the expert finished: a stretch of thinking, or something it said.
+ *
+ * Reported per completed block rather than streamed. The block arrives whole on
+ * `content_end`, so a consumer that wants the whole of it -- and the thinking
+ * is the part worth having whole; 50,000 characters of it is normal -- gets it
+ * in one message instead of rebuilding it from deltas. Nothing accumulates on
+ * either side, which is what keeps a long escalation from re-sending the same
+ * text on every update.
+ */
+export interface ExpertUtterance {
+    kind: "thinking" | "message";
+    text: string;
+}
+export interface ExpertReply {
+    text: string;
+    iterations: number;
+    finishReason?: string;
+    /** What this turn alone spent. */
+    usage: ExpertUsage;
+}
+/**
+ * The part of a session runtime an escalation uses.
+ *
+ * Narrow on purpose: `SessionRuntime` satisfies it structurally, and a test can
+ * satisfy it without a provider, a model or a network.
+ */
+export interface ExpertRuntime {
+    run(prompt: string): Promise<AgentResult>;
+    shutdown?(reason?: string): Promise<void>;
+    abort?(reason?: unknown): void;
+}
+export interface ExpertSessionOptions {
+    /**
+     * Builds the expert's runtime, once, on the first ask.
+     *
+     * Deferred rather than taken as a value so that configuring an expert costs
+     * nothing until one is actually called — on a local server, constructing it
+     * is what loads the model.
+     */
+    open: (context: {
+        onEvent: (event: AgentEvent) => void;
+    }) => Promise<ExpertRuntime>;
+    /** Follow-ups allowed after the first delivery. */
+    maxFollowUps: number;
+    /**
+     * The endpoint's slot gate, when the host resolved one.
+     *
+     * A local server queues a request that finds no free slot rather than
+     * refusing it, and says nothing while it does, so an ungated expert call
+     * reads as a slow run rather than a blocked one.
+     */
+    gate?: Pick<AgentSlotGate, "run" | "active">;
+    /**
+     * Called as the expert works, not only when it answers.
+     *
+     * Fires on every completed tool call and on every usage event the provider
+     * sends, which is as often as the expert gives anyone anything to report.
+     */
+    onProgress?: (progress: ExpertProgress) => void;
+    /**
+     * Called as the expert thinks and speaks, block by block.
+     *
+     * Separate from `onProgress` because these are the expert's words rather
+     * than a measurement of it, and because they must never carry usage: the
+     * turn's spend is reported once, and a second copy riding on the transcript
+     * would be added to it.
+     */
+    onUtterance?: (utterance: ExpertUtterance) => void;
+}
+export interface ExpertSession {
+    /** Answers the expert has actually produced. A failed run is not one. */
+    readonly deliveries: number;
+    /** Deliveries after the first. The brief itself is not a follow-up. */
+    readonly followUps: number;
+    readonly closed: boolean;
+    /** Everything this conversation has spent so far. */
+    readonly usage: ExpertUsage;
+    ask(message: string): Promise<ExpertReply>;
+    /** Ends the conversation and releases the endpoint's slot. Idempotent. */
+    close(reason?: string): Promise<void>;
+}
+export declare function createExpertSession(options: ExpertSessionOptions): ExpertSession;

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

@@ -0,0 +1,32 @@
+/**
+ * The expert's transcript, saved like any delegated agent's.
+ *
+ * The expert runs outside the spawn tools, so nothing reported its start or end
+ * to the session store, and its conversation lived only in memory. A report
+ * from a finished task then held every agent's transcript but the one the task
+ * had escalated to.
+ */
+import type { AgentResult } from "@cerebriline/shared";
+import type { SubAgentEndContext, SubAgentStartContext } from "../../extensions/tools/team/spawn-agent-tool";
+import type { ExpertRuntime } from "./expert-session";
+/** The parent the expert's sub-session is filed under. */
+export declare const EXPERT_PARENT_AGENT_ID = "lead";
+/** What `withExpertTranscript` needs of the expert's runtime. */
+export interface ExpertRuntimeWithTranscript extends ExpertRuntime {
+    getAgentId(): string;
+    getConversationId(): string;
+    getMessages(): AgentResult["messages"];
+}
+export interface ExpertTranscriptSink {
+    start(context: SubAgentStartContext): Promise<unknown> | unknown;
+    end(context: SubAgentEndContext): Promise<unknown> | unknown;
+}
+/**
+ * The expert's runtime, saving its messages after every ask.
+ *
+ * The first ask files the sub-session, with the brief as its task. Each ask
+ * then writes the whole conversation so far, whether it answered, finished on
+ * `error`, or threw. A sink that fails is ignored: saving is best-effort and
+ * must never cost the escalation.
+ */
+export declare function withExpertTranscript(expert: ExpertRuntimeWithTranscript, sink: ExpertTranscriptSink): ExpertRuntime;

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

@@ -0,0 +1,58 @@
+/**
+ * Spending a terminal guard on an escalation instead of on a stop.
+ *
+ * The evidence is the strongest in the study behind this feature. Of the 88
+ * runs that did not end FIXED, 40 were ended by the repeated-call loop guard --
+ * 45% of all failures -- and that same guard ended 3 of 243 successful runs.
+ * The consecutive-mistake limit accounts for 2 more failures and no successes,
+ * and the reasoning-loop streak for a handful. Precision here is structural
+ * rather than statistical: these runs were over. Handing the task to the expert
+ * at that exact moment cannot cost anything that was not already lost.
+ *
+ * What it must not become is a way around the guard. Two properties hold:
+ *
+ * - **Once per task.** The second time a terminal guard fires, it fires.
+ * - **Deferred, never removed.** Taking the offer means calling `escalate` on
+ *   the very next turn. A model that is given the turn and spends it on
+ *   something else is stopped at the end of it, with the guard's own words.
+ *
+ * The second property is the one that needs machinery. The mistake limit's
+ * `continue` resets its counter, so without this the run would get a fresh six
+ * mistakes out of a guard that was about to end it.
+ */
+import type { AgentEvent, TerminalGuardDecision } from "@cerebriline/shared";
+export interface ForcedEscalationOptions {
+    /** Escalations still available. Zero means the guard stands as it is. */
+    remaining: () => number;
+    /** End the run, the way the guard was about to. */
+    stop: (message: string) => void;
+    logger?: {
+        log?: (message: string) => void;
+    };
+}
+export interface ForcedEscalation {
+    /**
+     * Answer a terminal guard, or leave it standing.
+     *
+     * `undefined` means this has nothing to offer — spent, or no budget — and
+     * the guard does exactly what it did before.
+     */
+    decide(input: {
+        /** The guard, in the model's own terms. */
+        guard: string;
+        diagnosis?: string;
+    }): TerminalGuardDecision | undefined;
+    /** Fold in one agent event, so the deferral can see whether it was taken. */
+    observe(event: AgentEvent): void;
+    /** Whether the offer has been made. */
+    readonly spent: boolean;
+}
+/** What the model is told when a guard stands down for it. */
+export declare function describeForcedEscalation(input: {
+    guard: string;
+    diagnosis?: string;
+    remaining: number;
+}): string;
+/** What the run is stopped with when the turn was spent on something else. */
+export declare function describeMissedEscalation(guard: string): string;
+export declare function createForcedEscalation(options: ForcedEscalationOptions): ForcedEscalation;

package/dist/runtime/escalation/stand-down.d.ts

@@ -0,0 +1,66 @@
+/**
+ * What the base model may do while the expert is editing its workspace.
+ *
+ * The escalation used to be a blocking call: the base model went into
+ * `escalate`, the tool did not return until the expert had delivered, and the
+ * question of what the base was allowed to do meanwhile did not arise because
+ * it could do nothing at all. That cost the two things the user asked for
+ * (2026-09-14): a base model that watches the expert and can call it off when
+ * it starts going in circles, and a user steer that reaches the base while the
+ * expert is still working rather than an hour later.
+ *
+ * Making the base live raises the problem the blocking call did not have. Two
+ * models now hold write access to one workspace, and nothing arbitrates
+ * between them: the base reads a file, the expert rewrites it, the base edits
+ * the lines it read and destroys the expert's work -- or, worse, both of them
+ * do, and neither delivery is what is on disk. That is not a rule the models
+ * can be trusted to keep between themselves, because each of them is correct
+ * about its own edit.
+ *
+ * So the base stands down. Not from the task and not from the turn: from
+ * CHANGES. It reads, it greps, it runs the check, it reads the versions the
+ * expert wrote and it messages the expert. What it cannot do is write, and
+ * that is enforced here rather than asked for in a prompt, because a prompt is
+ * a request and this is an invariant (user: "the base model should be
+ * instructed to stand down from changes; all editing operations prohibited
+ * until the expert is done").
+ *
+ * `run_commands` is the deliberate exception. The user allowed running --
+ * checking the expert's work is most of what the base is there for, and a base
+ * that cannot run anything is a base that can only take the expert's word --
+ * and a command can write anything, so it is warned rather than refused.
+ */
+import type { AgentToolDefinition } from "@cerebriline/shared";
+/**
+ * What the base model is told when it hands over.
+ *
+ * The spot-check instruction is the load-bearing sentence. The notes name
+ * every tool call the expert made, and a model told to verify them all will
+ * spend the whole escalation reading -- which is the turn economy the batching
+ * exists to protect (user: "instruct the base model to NOT do a systematic
+ * check of all tools request but overview the flow and run spot checks").
+ */
+export declare const STAND_DOWN_NOTICE = "== YOU ARE STANDING DOWN WHILE THE EXPERT WORKS ==\n\nThe expert is editing this workspace now. You are not. Until it delivers, every tool that writes a file is refused \u2014 you cannot edit, patch, restore or submit, and there is no way to override that. This is not a judgement about your work; it is that two models writing to one workspace destroy each other's changes, and the expert has the pen.\n\nWhat you do instead is watch. You will be given notes as the expert works: what it called, what it changed, what it said. Do not audit them. Read the flow, form a view of whether the work is going somewhere, and run spot checks on the parts that matter \u2014 the file the expert says it fixed, the check it says now passes, the claim you doubt. `read_files` with a `revision` from a note shows you the exact bytes that note was about, which is the only way to check a claim against what was actually written rather than against a file that has moved on since.\n\nYou may run commands, including the check. Do not run one that changes a file. A formatter, a build step that rewrites sources, a `sed -i` \u2014 any of those lands on top of what the expert is doing, and neither of you will be able to say what happened.\n\nYou may message the expert, and you should keep it rare: a message costs it a turn and pulls it off what it is doing. Send one when you have something it needs \u2014 an answer to a question, a correction the user gave you, or the judgement only you can make: that it is going in circles and should stop. You are authorised to call it off.\n\nWhen the expert delivers, you have the pen back and the task is yours again.";
+/** The stand-down, as the session drives it. */
+export interface StandDown {
+    /** Whether the base model is standing down right now. */
+    readonly engaged: boolean;
+    /** The expert has the workspace. */
+    engage(): void;
+    /** The expert is done. The base model has the pen back. */
+    release(): void;
+}
+export declare function createStandDown(): StandDown;
+/**
+ * Return the tool list with the writers gated on the stand-down.
+ *
+ * A decoration rather than a filter, and deliberately: a tool that vanishes
+ * mid-task teaches the model that the tool does not exist, and it stops
+ * planning with it for the rest of the run. A tool that answers "not now, and
+ * here is why" leaves the capability where the model can find it again.
+ */
+export declare function withStandDown<T extends AgentToolDefinition>(tools: readonly T[], standDown: StandDown): T[];
+/** Names the stand-down refuses, for the prompt and for tests. */
+export declare const STAND_DOWN_REFUSED_TOOLS: readonly string[];
+/** Names that stay open, stated so a reader does not have to infer them. */
+export declare const STAND_DOWN_ALLOWED_TOOLS: readonly string[];

package/dist/runtime/escalation/struggle-offer.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Turning "this run is not going anywhere" into an offer of help.
+ *
+ * The detector next door measures; this words the consequence, and the split
+ * is deliberate. What the measurement earns depends on things the detector
+ * cannot see -- whether an expert is configured at all, how much of the
+ * escalation budget is left, whether the user asked to approve each one.
+ *
+ * Delivered on a tool result rather than appended to the conversation. The
+ * conversation store is snapshotted into `initialMessages` when a run starts
+ * and overwritten from `runResult.messages` when it ends, so a message
+ * appended to it mid-run reaches nothing: measured on a live session where a
+ * guard counted six refusals and not one of the twenty-six requests on the
+ * wire carried a word of the warning.
+ */
+import type { AgentToolDefinition } from "@cerebriline/shared";
+/**
+ * What the model is told when the detector has fired.
+ *
+ * Both halves matter, and the second one is the half that is easy to leave
+ * out: the expert is there to be used. A model that refuses to escalate after
+ * four failed attempts in ten turns wastes more than one that escalates early,
+ * and a paragraph that only warned about cost would produce exactly that.
+ *
+ * It never says the model must. The forcing path is a different mechanism at a
+ * different place, and a suggestion that reads like an order makes the run's
+ * one real stop indistinguishable from a nudge.
+ */
+export declare function describeEscalationOffer(input: {
+    diagnosis: string;
+    remaining: number;
+}): string;
+/**
+ * The quieter message, one failure short of the offer above.
+ *
+ * Two things separate it from `describeEscalationOffer`. It states what was
+ * measured and stops -- no paragraph about cost, no "the expert exists to be
+ * used" -- because at this count the honest reading is usually "this is a
+ * normal bad patch", and a full proposal every time one would arrive would
+ * train the model to skip the one that matters. And it names the expert only
+ * when the code it is working in is genuinely hard to read, which is the one
+ * case where the extra help is worth raising before the trigger.
+ *
+ * The complexity lines arrive already worded, each carrying its own bound.
+ * Nothing here restates the number as a prediction: it says the code is hard
+ * to read, which is all it measures.
+ */
+export declare function describeEscalationNudge(input: {
+    diagnosis: string;
+    complexity: readonly string[];
+    /**
+     * Whether the hardest function in any file in play lands in the top band.
+     *
+     * `extreme`, which is 60 and above -- 6.3% of files measured across
+     * TypeScript, C and C++. Rare enough that raising it means something.
+     */
+    high: boolean;
+    /** Whether a file in play no longer parses end to end. */
+    broken?: boolean;
+    /**
+     * Which measurement asked for this.
+     *
+     * `edit-streak` names the expert on its own, where the plain nudge names it
+     * only in dense code. Three refused edits in a row is not a bad patch --
+     * the model has tried the same thing three times and been told no three
+     * times -- and that is the point at which raising the expert is the useful
+     * thing to say rather than the premature one.
+     */
+    reason?: "failures" | "edit-streak" | "transactions";
+    /**
+     * Whether this session can hand a piece of the work to a subagent.
+     *
+     * The expert is named late because it costs money or a shared GPU. A
+     * subagent is this model on this endpoint, so naming it is nearly free --
+     * which is why it rides the nudge that was already being sent rather than
+     * earning a threshold of its own. The gate is the host's: `spawn_agent` off,
+     * or an endpoint that serves one request at a time, and there is nothing to
+     * suggest.
+     */
+    canDelegate?: boolean;
+    remaining: number;
+}): string;
+/** A held suggestion, taken by whichever tool result comes next. */
+export interface PendingSuggestion {
+    hold(message: string): void;
+    /** What is owed, without consuming it. */
+    peek(): string | undefined;
+    take(): string | undefined;
+}
+export declare function createPendingSuggestion(): PendingSuggestion;
+/**
+ * Wrap every tool so the next result carries a held suggestion.
+ *
+ * Every tool, not a chosen few: the suggestion is about the run rather than
+ * about any one call, and the model's next call is wherever it happens to go.
+ * `escalate` and `spawn_agent` are excluded — a model that has just taken the
+ * advice does not need to be given it again inside the answer. Neither call
+ * consumes the suggestion, so it is still owed to whatever runs next.
+ */
+export declare function withStruggleSuggestion<T extends AgentToolDefinition>(tools: readonly T[], pending: PendingSuggestion): T[];