@cerebriline/core 4.100.240

package/dist/runtime/atomic/transaction-controller.d.ts

@@ -0,0 +1,364 @@
+import { type RevisionLog } from "./file-revisions";
+import { type Oracle, type OracleVerdict } from "./oracle";
+import { type TransactionOutcome, type TransactionVerdictSource } from "./protocol";
+import { type RestoreReport, type Snapshot, type SnapshotLimits } from "./snapshot";
+/** What the model said about its own change, where nothing else could say it. */
+export type SelfReport = "success" | "failure" | "unsure";
+export interface TransactionReport {
+    /** The plan as the model declared it, carried forward if this one fails. */
+    plan?: string;
+    /** What the model said when it tried to end the turn. */
+    account?: string;
+    /**
+     * The model's own verdict, where there is no oracle. `undefined` means it
+     * never gave one — which is not the same as saying it could not tell.
+     */
+    selfReport?: SelfReport;
+    /**
+     * The run is ending because the no-tool-call nudges ran out, not because the
+     * model chose to stop. It changes what silence means: a model cut off
+     * mid-work has not declined to report, it never got to.
+     */
+    forced?: boolean;
+}
+export type TransactionSettlement = {
+    kept: true;
+    message: string;
+    verdict?: OracleVerdict;
+} | {
+    kept: false;
+    message: string;
+    verdict?: OracleVerdict;
+    restore: RestoreReport;
+    /**
+     * Whether the work stayed on disk instead of being rolled back.
+     *
+     * See `carriedOn` on the controller. `restore` is empty when this is
+     * set -- nothing was put back, so there is nothing to report.
+     */
+    carried?: boolean;
+    /** The next transaction's rules and record, or nothing when out of them. */
+    nextPrompt?: string;
+};
+export type TransactionEvent = {
+    type: "opened";
+    transaction: number;
+    oracle?: Oracle;
+}
+/** A check was proposed, approved and taken on for the rest of the run. */
+ | {
+    type: "adopted";
+    transaction: number;
+    oracle: Oracle;
+} | {
+    type: "judging";
+    transaction: number;
+    oracle?: Oracle;
+}
+/**
+ * A transaction the model tried to end without changing anything.
+ *
+ * Not a settlement: nothing was judged and nothing was put back, so it
+ * carries no verdict. `continued` says which of the two things happened —
+ * the transaction was handed back to the model, or the run was let go.
+ */
+ | {
+    type: "empty";
+    transaction: number;
+    message: string;
+    continued: boolean;
+}
+/**
+ * The plan for this transaction, the first time one is seen.
+ *
+ * `from` says where it was found. A plan stated in the reply is already in
+ * front of the user; one found in the reasoning is not, and is the reason
+ * this event exists — the protocol asks for the plan in the reply and a 9B
+ * put it in its reasoning four times out of four, so nothing downstream
+ * ever saw it.
+ */
+ | {
+    type: "plan";
+    transaction: number;
+    plan: string;
+    from: "reply" | "reasoning";
+} | {
+    type: "settled";
+    transaction: number;
+    kept: boolean;
+    /** Not kept, and not rolled back either: the check's answer moved. */
+    carried?: boolean;
+    /**
+     * Who judged it. A consumer counting successes has to be able to
+     * separate "the check passed" from "nothing checked and nobody
+     * said" -- both arrive here as `kept: true`.
+     */
+    source: TransactionVerdictSource;
+    message: string;
+    /**
+     * Wall-clock from `open()` to this settlement.
+     *
+     * The settlement line said what happened to the transaction and
+     * never how long it took, so a run that looped for forty minutes
+     * and one that landed first try read identically in the transcript
+     * -- and the completion message above it carries no time either, so
+     * there was nowhere else to look.
+     */
+    elapsedMs?: number;
+    verdict?: OracleVerdict;
+    restore?: RestoreReport;
+};
+export interface TransactionControllerOptions {
+    workspaceRoot: string;
+    /** Hard limit on changes declared per transaction. */
+    maxChanges: number;
+    /** Transactions this task gets before it stops. */
+    maxTransactions: number;
+    /** The check that decides, or nothing when the workspace has none. */
+    oracle?: Oracle;
+    /**
+     * Whether the model may name its own check while there is none.
+     *
+     * Set by the host that has somewhere to ask the user. It stops mattering
+     * the moment a check exists, since one is frozen once taken on.
+     */
+    allowCheckProposal?: boolean;
+    /**
+     * Discarded attempts before a check that has never passed may be replaced.
+     *
+     * Zero, or absent, is the freeze as it was. See `checkIsUnderReconsideration`
+     * for the condition and why it is scoped the way it is.
+     */
+    checkReconsideredAfter?: number;
+    oracleTimeoutMs?: number;
+    snapshotLimits?: SnapshotLimits;
+    /**
+     * The session's file-history log, when the host keeps one.
+     *
+     * Given rather than made, so the transaction and the session share a single
+     * history: the numbering the model has been told about stays continuous
+     * across engaging and disengaging the protocol, and the compaction ledger
+     * keeps answering from the same store. Absent, this makes its own, which is
+     * what every caller did before the log became session-scoped.
+     */
+    revisions?: RevisionLog;
+    /**
+     * Something for the last transaction's opening prompt, asked for once.
+     *
+     * The host's, and opaque here: this is where the escalation offer is said,
+     * and the protocol does not know what an expert is.
+     */
+    describeLastTransaction?: () => string | undefined;
+    onEvent?: (event: TransactionEvent) => void;
+}
+/**
+ * The protocol as a state machine the host drives: snapshot, change, judge,
+ * keep or put back — bounded.
+ *
+ * Written this way round because the boundary belongs to the host. The model
+ * gets no tool to close a transaction with: one it forgot to call would leave
+ * every change in that transaction unjudged, so a forgotten call would become
+ * silently discarded work. A boundary the host owns cannot be forgotten — the
+ * agent runtime asks this object at the moment the model tries to end its
+ * turn, and the answer either lets it end or puts the files back and hands it
+ * the next transaction.
+ *
+ * The rollback is the part that has to be right. Cline's checkpoints cannot
+ * serve it — they require a git work tree and throw without one — so this uses
+ * the copy-and-checksum snapshot next door instead.
+ */
+export declare class TransactionController {
+    private readonly options;
+    private readonly history;
+    private readonly uncoveredPaths;
+    /**
+     * Every version of every file a tool has written in the open transaction.
+     *
+     * Lives here because its lifetime is the base snapshot's: #1 of each file is
+     * what the base holds, so a log that outlived its base would offer the model
+     * a revision the rollback cannot honour.
+     */
+    private readonly revisionLog;
+    /** What a rollback goes back to. Outlives a transaction that was carried. */
+    private snapshot?;
+    /**
+     * The tree as the open transaction found it.
+     *
+     * The same object as `snapshot` in the ordinary case, and older than it
+     * after a carry -- "has this transaction changed anything" and "what does a
+     * rollback undo" stop being the same question once work outlives the
+     * transaction that made it.
+     */
+    private openedWith?;
+    private current;
+    /** When the open transaction started, for the settlement line. */
+    private openedAt;
+    private adopted?;
+    /** Whether the adopted check has ever passed, on any files, since adoption. */
+    private adoptedEverPassed;
+    /** Attempts that changed something and were thrown away, since adoption. */
+    private discardedSinceAdoption;
+    /** Open while the model may replace a check that has never passed. Once. */
+    private reconsidering;
+    /**
+     * Every distinct thing this run's check has said, and whether it has ever
+     * said the same thing twice.
+     *
+     * The repeat is what makes the novelty mean anything. A check that prints a
+     * duration, a timestamp or a seed says something new every single time it
+     * runs, and treating that as evidence the edits are landing would tell a
+     * model its work was progressing while nothing moved -- the same trap
+     * `describeStuckHostCheck` documents from the other direction. A check that
+     * has repeated itself once is demonstrably deterministic on the path it
+     * takes, and only then is "it has never said this before" a fact about the
+     * files rather than about the clock.
+     */
+    private readonly checkOutputs;
+    private checkHasRepeated;
+    /** Set by a carried settlement, so the next `open` keeps the older base. */
+    private carrying;
+    private reconsiderationsUsed;
+    constructor(options: TransactionControllerOptions);
+    /** One-based number of the open transaction, or 0 before the first opens. */
+    get transaction(): number;
+    /** The check that judges this run, however it came by one. */
+    get oracle(): Oracle | undefined;
+    /**
+     * Whether a check can still be taken on — which is only ever while there is
+     * none. See `adoptOracle`.
+     */
+    get canAdoptOracle(): boolean;
+    /**
+     * Whether the check the model named is currently up for replacement.
+     *
+     * Scoped to a check the model proposed and nothing else: `adopted` is set
+     * only by `adoptOracle`, and `options.oracle` being absent is what says
+     * discovery found nothing to run. A check the user wrote, or one detected
+     * in the tree, is the specification and is never reconsidered — it is not
+     * the model's to disagree with.
+     *
+     * The condition is "it has never passed once, across attempts that really
+     * changed something". That is the only observable separating a check that
+     * cannot pass from a task that is hard, and measured over ten runs the two
+     * that died looked like this from the first transaction onward.
+     */
+    get checkIsUnderReconsideration(): boolean;
+    /**
+     * Take a check for the rest of the run, once.
+     *
+     * For a check the model proposed and the user approved, in a workspace
+     * where discovery found nothing. It can only ever be set while there is no
+     * check at all, and that is the freeze: a model allowed to re-propose after
+     * a transaction fails will weaken the check until one passes, which is an
+     * elaborate way of arriving back at `self-declared`. Replacing it costs a
+     * new session, not a tool call.
+     */
+    adoptOracle(oracle: Oracle): void;
+    /**
+     * Run a candidate check against the files as this transaction found them.
+     *
+     * The question a proposed check has to answer before it is trusted: does it
+     * fail on the unmodified files? A check that already passes there is not a
+     * check of anything — `echo ok`, `node --version`, a test that never
+     * touches the bug — and approving one produces `self-declared` with a
+     * ceremony around it. Failing first and passing after is the definition of
+     * a regression test, and it is the property this enforces.
+     *
+     * Where nothing has been edited yet, the working tree *is* the base and it
+     * is simply run. Where something has, the base is put back for the length
+     * of the run and the edits are put back after it — the same restore the
+     * protocol performs on a discarded transaction, in both directions, with
+     * the return leg in a `finally` so a check that throws cannot cost the
+     * model its work.
+     */
+    judgeAgainstBase(oracle: Oracle): Promise<OracleVerdict>;
+    /**
+     * Record what the check just said, and answer whether it is new.
+     *
+     * One funnel for every run of the oracle in this controller, so the record
+     * covers the checks the model asked for as well as the ones that judged a
+     * transaction.
+     */
+    private noteCheckOutput;
+    /**
+     * Run the check against the working tree, and settle nothing.
+     *
+     * The check the transaction is judged by was reachable from exactly one
+     * place -- `settle`, at the completion attempt -- so a model working under
+     * it got no verdict until the transaction was over, and a failing one threw
+     * the whole transaction away. Measured on a live run: 341 messages and 65
+     * edits with no check result, then one `SyntaxError` and a full rollback,
+     * after which the model restored the original file and started again.
+     *
+     * The arm that works never had this problem, because there the check is a
+     * shell line named in the prompt and the model simply reruns it -- 88 times
+     * in one successful run. This is that, for a check the model cannot type.
+     */
+    runCheck(): Promise<OracleVerdict>;
+    /** Every transaction so far, in order, kept or not. */
+    get outcomes(): readonly TransactionOutcome[];
+    /** Files no snapshot could hold, so nobody assumes they were protected. */
+    get uncovered(): string[];
+    /**
+     * The base the open transaction would roll back to, or nothing when none is
+     * open. What a host hands the user when a run is cut short mid-transaction.
+     */
+    get pending(): Snapshot | undefined;
+    /** The open transaction's per-file history. Empty before the first write. */
+    get revisions(): RevisionLog;
+    /** Whether the open transaction has changed anything on disk. */
+    isUntouched(): Promise<boolean>;
+    /**
+     * Take the base this transaction rolls back to, and return the rules to put
+     * to the model.
+     *
+     * Taken at the open of every transaction rather than once per task: a kept
+     * transaction becomes the base the next one rolls back to, which is what
+     * makes a sequence of them additive rather than a single undo point.
+     */
+    /**
+     * Whether this transaction should offer the model its check back.
+     *
+     * Every clause earns its place. The check must be the model's own; it must
+     * never have passed; enough attempts must have really been thrown away to
+     * rule out an unlucky one; it can happen once; and there has to be a
+     * transaction left after this one, or a replacement judges nothing.
+     *
+     * The threshold is bounded by `maxTransactions` because that is a setting:
+     * a fixed two would fire on the last attempt of a three-attempt task and be
+     * useless there.
+     */
+    private shouldReconsiderCheck;
+    open(): Promise<string>;
+    /**
+     * Judge the open transaction, and keep it or put every file back.
+     *
+     * Called at the boundary — the model calling a completion tool, or ending a
+     * turn with nothing left to call. Both are the same event to this: the model
+     * believes it is done, which is exactly when its belief is worth checking.
+     */
+    settle(report?: TransactionReport): Promise<TransactionSettlement>;
+    /**
+     * Put back what the open transaction changed, without judging it.
+     *
+     * For a run the user cut short. Offered rather than done: rolling back on a
+     * cancel would destroy work the user interrupted for their own reasons, so
+     * the host decides and this carries it out.
+     */
+    discard(): Promise<RestoreReport | undefined>;
+    private emit;
+}
+/**
+ * Whether a model's own account of its change is enough to keep it.
+ *
+ * The three answers are not symmetric. "It worked" keeps; "it did not" and "I
+ * cannot tell" both discard, because a model reporting its own doubt is real
+ * evidence about the change.
+ *
+ * Saying nothing at all is a fourth thing and is treated as none of them. It is
+ * a reporting failure, not a statement about the change, and discarding real
+ * work over a line the model forgot to write is precisely the failure a
+ * host-owned boundary exists to avoid. So silence keeps the change and labels
+ * it unverified, where the user can see the diff and decide.
+ */
+export declare function judgeSelfReport(report: SelfReport | undefined): boolean;

package/dist/runtime/atomic/unparseable-change.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Why a failed check sometimes says nothing about the change that failed it.
+ *
+ * Measured on the 39-minute run analysed today: the check ran eighteen times,
+ * eleven of them byte-identical, over a file that at several points did not
+ * parse at all. A check run against a file the engine refuses measures the
+ * refusal, not the fix -- but the verdict it produced read like any other
+ * failure, so the model reconsidered a plan that had never been tried.
+ *
+ * This names that case, at the one moment it is cheap to name: the transaction
+ * has failed and the files it changed are still on disk, one call before the
+ * rollback puts them back.
+ *
+ * Deliberately past-tense, and deliberately without the scan's prescribed
+ * `editor` call. By the time the model reads this the rollback has happened
+ * and the column the scan named is a column of a file that no longer exists;
+ * handing a 9B a precise instruction against a stale file is how a report
+ * meant to save a transaction spends the next one.
+ */
+/** Whether the check's output names a parse failure. */
+export declare function looksLikeSyntaxError(output: string): boolean;
+/** A file as it stood when the transaction failed. */
+export interface ChangedFile {
+    /** Absolute path. */
+    readonly path: string;
+    readonly text: string;
+}
+/**
+ * Say that the check measured a file that does not parse, or nothing.
+ *
+ * Nothing is the common case and the right default: a check fails for real
+ * reasons far more often than for a bracket, and a verdict that guessed would
+ * be worse than one that stayed quiet.
+ */
+export declare function describeUnparseableChange(changed: readonly ChangedFile[], root: string): string | null;

package/dist/runtime/capabilities/index.d.ts

@@ -0,0 +1,2 @@
+export { normalizeRuntimeCapabilities } from "./normalize-runtime-capabilities";
+export type { RuntimeCapabilities } from "./runtime-capabilities";

package/dist/runtime/capabilities/normalize-runtime-capabilities.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeCapabilities } from "./runtime-capabilities";
+export declare function normalizeRuntimeCapabilities(...sources: Array<RuntimeCapabilities | undefined>): RuntimeCapabilities | undefined;

package/dist/runtime/capabilities/runtime-capabilities.d.ts

@@ -0,0 +1,18 @@
+import type { ToolApprovalRequest, ToolApprovalResult } from "@cerebriline/shared";
+import type { ReadReceipts, ToolExecutors } from "../../extensions/tools";
+export interface RuntimeCapabilities {
+    toolExecutors?: Partial<ToolExecutors>;
+    /**
+     * The host's record of what has been read.
+     *
+     * A host that replaces `readFile` or `editor` replaces the half of the
+     * read-before-write guard that WRITES the record, while `grep`, `sed` and
+     * `awk` keep the one core built -- which nothing then writes to. The result
+     * is a guard that refuses every `sed` in-place run for a file the model has
+     * just read, and says the file "has not been read in this session" while
+     * `read_files` calls on it sit in the same transcript. Hand the registry
+     * over with the executors and all of them share one.
+     */
+    readReceipts?: ReadReceipts;
+    requestToolApproval?: (request: ToolApprovalRequest) => Promise<ToolApprovalResult> | ToolApprovalResult;
+}

package/dist/runtime/config/agent-message-codec.d.ts

@@ -0,0 +1,6 @@
+import type { AgentMessage, Message, MessageWithMetadata } from "@cerebriline/shared";
+export declare function messageToAgentMessages(message: MessageWithMetadata): AgentMessage[];
+export declare function messagesToAgentMessages(messages: readonly MessageWithMetadata[]): AgentMessage[];
+export declare function agentMessageToMessageWithMetadata(message: AgentMessage): MessageWithMetadata;
+export declare function agentMessagesToMessagesWithMetadata(messages: readonly AgentMessage[]): MessageWithMetadata[];
+export declare function agentMessagesToMessages(messages: readonly AgentMessage[]): Message[];

package/dist/runtime/config/agent-runtime-config-builder.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Build an `AgentRuntimeConfig` from an `AgentConfig` plus session-owned
+ * supporting objects (model handler, tools, hooks, plugins, telemetry).
+ *
+ * The function is intentionally **pure**: it does not create handlers or tools
+ * itself; it receives them already resolved from the caller (`SessionRuntime`)
+ * and wires them into an `AgentRuntimeConfig`.
+ *
+ * Fields that do **not** round-trip into `AgentRuntimeConfig`
+ * (e.g. `execution.maxConsecutiveMistakes`, `execution.loopDetection`) are
+ * consumed by `SessionRuntime` / `MistakeTracker` /
+ * `LoopDetectionTracker` — not passed through here.
+ * `execution.reasoningLoopDetection` is the exception: it is enforced inside
+ * the model stream, so it does round-trip.
+ */
+import type { AgentConfig, AgentMessage, AgentModel, AgentRuntimeConfig, AgentRuntimeHooks, AgentRuntimePlugin, AgentRuntimePrepareTurnContext, AgentRuntimePrepareTurnResult, AgentTool, BasicLogger, ITelemetryService } from "@cerebriline/shared";
+/**
+ * Inputs required to assemble an `AgentRuntimeConfig`. Distinct from
+ * `AgentConfig` because some of these (the model adapter, the hook
+ * bridge's runtime-hooks bag, a resolved plugin list) can only be
+ * produced inside `SessionRuntime`.
+ */
+export interface CreateAgentRuntimeConfigInput {
+    readonly agentConfig: AgentConfig;
+    /**
+     * Core/hub runtime session identifier used for host lifecycle operations,
+     * event routing, persistence, and approval delivery.
+     */
+    readonly sessionId?: string;
+    readonly agentId: string;
+    /**
+     * Agent conversation/transcript identifier used by tools, hooks, telemetry,
+     * and model history correlation.
+     */
+    readonly conversationId?: string;
+    readonly parentAgentId?: string;
+    /** The role label for teammates (`AgentConfig.role` in sub-agent configs). */
+    readonly agentRole?: string;
+    /** Pre-built model adapter (produced by `apiHandlerToAgentModel`). */
+    readonly model: AgentModel;
+    readonly logger?: BasicLogger;
+    readonly telemetry?: ITelemetryService;
+    /** Pre-built tool array (builtins + plugin-contributed + session extras). */
+    readonly tools?: readonly AgentTool<unknown, unknown>[];
+    readonly toolContextMetadata?: Record<string, unknown>;
+    /** Pre-resolved plugin list from the plugin loader. */
+    readonly plugins?: readonly AgentRuntimePlugin[];
+    /** Runtime hooks supplied by the session/runtime builder. */
+    readonly hooks?: Partial<AgentRuntimeHooks>;
+    /** Host-owned context pipeline invoked before runtime model hooks. */
+    readonly prepareTurn?: (context: AgentRuntimePrepareTurnContext) => Promise<AgentRuntimePrepareTurnResult | undefined> | AgentRuntimePrepareTurnResult | undefined;
+    /** Seed messages (usually `session.conversation.getMessages()`). */
+    readonly initialMessages?: readonly AgentMessage[];
+    /**
+     * Optional completion-policy override. Pass `null` for model modes that
+     * cannot call tools (for example image generation).
+     */
+    readonly completionPolicy?: AgentRuntimeConfig["completionPolicy"] | null;
+    /**
+     * Override for `AgentRuntimeConfig.systemPrompt` — useful when
+     * the caller has composed additional guidance (e.g. via
+     * `LocalRuntimeHost.composeSystemPrompt`). Defaults to
+     * `agentConfig.systemPrompt`.
+     */
+    readonly systemPrompt?: string;
+}
+/**
+ * Produce an `AgentRuntimeConfig` from session-owned runtime inputs.
+ */
+export declare function createAgentRuntimeConfig(input: CreateAgentRuntimeConfigInput): AgentRuntimeConfig;
+/**
+ * Collect the provider-/reasoning-related fields from `AgentConfig`
+ * into `AgentRuntimeConfig.modelOptions`. Kept undefined when every
+ * field is undefined so the runtime does not receive an empty object.
+ */
+export declare function buildModelOptions(config: AgentConfig): Record<string, unknown> | undefined;
+/**
+ * Compose `messageModelInfo` from the provider-related fields per
+ * §3.2.1: `{ id: modelId, provider: providerId, family:
+ * providerConfig?.family }`.
+ */
+export declare function buildMessageModelInfo(config: AgentConfig): AgentMessage["modelInfo"];
+/**
+ * `"parallel"` when `maxParallelToolCalls ≥ 2`, `"sequential"` when
+ * `1`, `undefined` when the caller did not specify.
+ *
+ * `undefined` stays `undefined` on purpose: it means *this host has no
+ * opinion*, and the default that answers it lives in one place, the runtime's
+ * `resolveParallelToolCallBound`. Returning `"sequential"` here would put a
+ * second default in a second file, which is how this setting came to have a
+ * documented default of 8 that nothing ever applied.
+ */
+export declare function resolveToolExecution(maxParallelToolCalls: number | undefined): "sequential" | "parallel" | undefined;

package/dist/runtime/config/connection-update.d.ts

@@ -0,0 +1,40 @@
+import type { CoreSessionConfig } from "../../types/config";
+export interface ConnectionUpdate {
+    providerId?: string;
+    modelId?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    providerConfig?: CoreSessionConfig["providerConfig"];
+    reasoningEffort?: CoreSessionConfig["reasoningEffort"] | null;
+    thinking?: CoreSessionConfig["thinking"] | null;
+    thinkingBudgetTokens?: CoreSessionConfig["thinkingBudgetTokens"] | null;
+}
+export interface ConnectionUpdateInput {
+    providerId?: string;
+    modelId?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    providerConfig?: CoreSessionConfig["providerConfig"];
+    thinking?: boolean;
+    reasoningEffort?: CoreSessionConfig["reasoningEffort"];
+    thinkingBudgetTokens?: number;
+}
+/**
+ * Builds a ConnectionUpdate for switching a live session's provider/model
+ * connection. Shared by clients (CLI, desktop sidecar, …) so the
+ * thinking/reasoning transition rules stay consistent:
+ * - `thinking: false` disables reasoning and clears effort/budget.
+ * - `thinking: true` (or a provided effort/budget) enables reasoning; an
+ *   explicit `thinking: true` resets the reasoning state, so a stale effort or
+ *   token budget from the previous connection is cleared unless a replacement
+ *   accompanies it. A bare effort/budget without a `thinking` flag updates
+ *   only the provided field.
+ * - `thinking: undefined` leaves the session's reasoning state untouched.
+ * Connection fields are included only when defined; an empty string is passed
+ * through (it means "clear"), so callers that want to skip blanks must drop
+ * them before calling.
+ */
+export declare function buildConnectionUpdate(input: ConnectionUpdateInput): ConnectionUpdate;
+export declare function normalizeConnectionUpdate(updates: ConnectionUpdate): ConnectionUpdate;

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

@@ -0,0 +1,109 @@
+/**
+ * The A2A vocabulary, and only the vocabulary.
+ *
+ * Agent2Agent is a wire protocol for agents that do not share a process: three
+ * transports, an AgentCard served over HTTPS for discovery, push-notification
+ * webhooks, security schemes. Our base model and our expert are two
+ * `SessionRuntime` instances in one process editing one workspace, so none of
+ * that is ours to run and the official SDK would ship a client, a server and
+ * three transports we would never call.
+ *
+ * What is worth having is the nouns. They are the part of the spec that had to
+ * be argued about, and adopting them costs nothing and settles questions we
+ * would otherwise settle badly one at a time:
+ *
+ *   TaskState    escalation had no state machine at all -- everything was
+ *                prose. `input-required` is the expert asking the base a
+ *                question; `canceled` is the base telling a circling expert to
+ *                stop; `rejected` is the expert refusing the brief. Each of
+ *                those is a thing we now have to have an answer for, which is
+ *                the point of borrowing the enum rather than inventing three
+ *                booleans later.
+ *   Message      one shape for both directions, carrying structure and prose
+ *                side by side rather than forcing notes through a string.
+ *   Part         the reason a note can be read by a 9B model and by the panel
+ *                at the same time: the text part is for the model, the data
+ *                part is for everything else.
+ *   Artifact     the expert's delivery as a thing with an identity, instead of
+ *                a paragraph the base has to parse by reading.
+ *
+ * Deliberately absent: AgentCard (discovery between hosts that cannot see each
+ * other -- here "you can message each other" is two sentences of prompt),
+ * every transport, push-notification config, and the SDK.
+ *
+ * Field names follow the spec exactly, including the camelCase and including
+ * `messageId` rather than `id`, so that a reader who knows A2A recognises
+ * these and a reader who does not can look them up.
+ *
+ * Spec: https://a2a-protocol.org/latest/specification/
+ */
+/**
+ * Where a task is, in the spec's own words.
+ *
+ * The three interrupted/terminal distinctions are the load-bearing part:
+ * `working` and `input-required` both mean the expert is alive, but only one
+ * of them means the base owes it an answer.
+ */
+export type TaskState = "submitted" | "working" | "input-required" | "completed" | "failed" | "canceled" | "rejected";
+export declare const TERMINAL_TASK_STATES: ReadonlySet<TaskState>;
+export declare function isTerminal(state: TaskState): boolean;
+/** Who sent a message. The spec has no third role, and neither do we. */
+export type Role = "user" | "agent";
+/** Text meant to be read by a model. */
+export interface TextPart {
+    kind: "text";
+    text: string;
+}
+/**
+ * Structure meant to be read by code.
+ *
+ * This is what keeps the informational notes honest. The panel needs the tool
+ * name and the revision number; the base model needs a sentence. Putting both
+ * in one part would mean one of them is parsed out of the other, and the
+ * parser would be the thing that breaks.
+ */
+export interface DataPart {
+    kind: "data";
+    data: Record<string, unknown>;
+}
+export type Part = TextPart | DataPart;
+/** One thing said, in either direction. */
+export interface Message {
+    messageId: string;
+    role: Role;
+    parts: Part[];
+    taskId?: string;
+    contextId?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Something the task produced.
+ *
+ * For us that is the expert's delivery: what it changed and what it ran, with
+ * the files it touched named in a data part rather than described in the prose.
+ */
+export interface Artifact {
+    artifactId: string;
+    parts: Part[];
+    name?: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TaskStatus {
+    state: TaskState;
+    message?: Message;
+    /** Milliseconds since the epoch. The spec says timestamp; this is ours. */
+    timestamp?: number;
+}
+export interface Task {
+    id: string;
+    status: TaskStatus;
+    contextId?: string;
+    artifacts?: Artifact[];
+    history?: Message[];
+    metadata?: Record<string, unknown>;
+}
+export declare function textPart(text: string): TextPart;
+export declare function dataPart(data: Record<string, unknown>): DataPart;
+/** Every text part, joined. Data parts are not prose and are not included. */
+export declare function textOf(parts: readonly Part[]): string;