@celestea/core 2.7.1

package/dist/message.d.ts

@@ -0,0 +1,189 @@
+/**
+ * The model-visible message model — a 1:1 port of
+ * `celestea_harness/crates/core/src/message.rs`.
+ *
+ * Shapes ported here:
+ *   Role      enum { System, User, Assistant, Tool }      (serde lowercase)
+ *   ToolCall  { id, name, args: Value }
+ *   Content   enum { Text(String), ToolCall(ToolCall) }   (tag="type", content="content")
+ *   Message   { role, content: Vec<Content>, tool_call_id: Option<String> }
+ *   ToolSpec  { name, description, parameters }           (declared in ./types.ts)
+ *   Usage     { prompt_tokens, completion_tokens, total_tokens,
+ *               cache_read, reasoning_tokens }             (flat counters)
+ *
+ * Field names and content-tag names are contract, not style: the LLM request
+ * builder and every engine projection depend on them. Do not rename anything.
+ */
+/** `Role` — serde `rename_all = "lowercase"`. */
+export declare const ROLES: readonly ["system", "user", "assistant", "tool"];
+export type Role = (typeof ROLES)[number];
+/** `ToolCall` — the id is the provider call id, `args` is the raw JSON value. */
+export interface ToolCall {
+    id: string;
+    name: string;
+    args: unknown;
+}
+/** `Content::Text` — `{"type":"text","content":"…"}`. */
+export interface TextContent {
+    type: "text";
+    content: string;
+}
+/** `Content::ToolCall` — `{"type":"tool_call","content":{…}}`. */
+export interface ToolCallContent {
+    type: "tool_call";
+    content: ToolCall;
+}
+/** The four media types the attachment pipeline accepts (section 5.4 magic-byte whitelist). */
+export declare const IMAGE_MEDIA_TYPES: readonly ["image/png", "image/jpeg", "image/webp", "image/gif"];
+export type ImageMediaType = (typeof IMAGE_MEDIA_TYPES)[number];
+/** True for one of the four accepted normalized media types. */
+export declare function isImageMediaType(v: unknown): v is ImageMediaType;
+/**
+ * W804 (multimodal P0 4.1): a content-addressed REFERENCE to an attachment
+ * object, never the bytes. The object itself lives at
+ * <session-dir>/attachments/<attachment_id>.<ext> (section 5); the session log
+ * and every projected event carry only this shape — base64 in the log is a red line.
+ *
+ * original records the pre-normalization dimensions of an image that was
+ * re-encoded/downscaled (DSH originalDimensions semantics); P0 never writes it
+ * (no re-encode), but the type is frozen here so P1 is purely additive.
+ */
+export interface ImageRef {
+    /** Content-addressing id: sha256(original bytes) in lowercase hex. */
+    attachment_id: string;
+    /** Normalized media type (magic-byte sniffed, never trusted from a name). */
+    media_type: ImageMediaType;
+    /** Normalized pixel width. */
+    width: number;
+    /** Normalized pixel height. */
+    height: number;
+    /** Original upload/file name, for the UI and model-readable labels only. */
+    name?: string;
+    /** Set when the stored bytes are a downscaled/re-encoded variant. */
+    original?: {
+        width: number;
+        height: number;
+        bytes: number;
+        media_type: string;
+    };
+}
+/**
+ * W804: the log/event spelling of ImageRef (section 4.3). Structurally identical —
+ * the alias exists so the event codec and the content model can each use the
+ * vocabulary of their own layer without drifting apart.
+ */
+export type AttachmentRef = ImageRef;
+/** Content::Image — {"type":"image","content":{...ImageRef}} (section 4.1). */
+export interface ImageContent {
+    type: "image";
+    content: ImageRef;
+}
+export type Content = TextContent | ToolCallContent | ImageContent;
+/**
+ * `Message` — one entry of the model-visible history.
+ *
+ * `content` is always a list (an assistant turn that calls tools carries one
+ * `tool_call` item per call in a SINGLE message); `tool_call_id` is set only for
+ * `role = "tool"`, so a result can be matched to its call.
+ */
+export interface Message {
+    role: Role;
+    content: Content[];
+    tool_call_id: string | null;
+}
+/** `Message::user`. */
+export declare function userMessage(text: string): Message;
+/** `Message::system`. */
+export declare function systemMessage(text: string): Message;
+/** `Message::assistant_text`. */
+export declare function assistantText(text: string): Message;
+/** `Message::assistant_tool_call`. */
+export declare function assistantToolCall(call: ToolCall): Message;
+/** `Message::tool_result`. */
+export declare function toolResultMessage(id: string, text: string): Message;
+/**
+ * W804: a user message that carries text plus image references. The text block
+ * stays FIRST and the images follow (section 3.5 ordering rule); no-image callers
+ * keep using userMessage so the wire shape is byte-identical when there is
+ * nothing to attach.
+ */
+export declare function userMessageWithImages(text: string, images: readonly ImageRef[]): Message;
+/**
+ * W804: a tool result that carries the canonical JSON text plus image
+ * references (the read_image case, section 6.3). The TEXT remains the value's
+ * serde JSON — the model must still see path/dimensions — and the images are
+ * separate content blocks.
+ */
+export declare function toolResultWithImages(id: string, text: string, images: readonly ImageRef[]): Message;
+/** Static namespace facade: `Message::user(…)` → `Message.user(…)`. */
+export declare const Message: {
+    readonly user: typeof userMessage;
+    readonly system: typeof systemMessage;
+    readonly assistantText: typeof assistantText;
+    readonly assistantToolCall: typeof assistantToolCall;
+    readonly toolResult: typeof toolResultMessage;
+    readonly userWithImages: typeof userMessageWithImages;
+    readonly toolResultWithImages: typeof toolResultWithImages;
+};
+export declare function isTextContent(c: Content): c is TextContent;
+export declare function isToolCallContent(c: Content): c is ToolCallContent;
+export declare function isImageContent(c: Content): c is ImageContent;
+/** Wrap one already-content-addressed reference as a model-visible image block. */
+export declare function imageContent(ref: ImageRef): ImageContent;
+/** The image blocks of a message, in order (references only, never bytes). */
+export declare function messageImages(m: Message): ImageRef[];
+/** The tool calls carried by a message (empty for a text-only message). */
+export declare function messageToolCalls(m: Message): ToolCall[];
+/** The ids of the tool calls carried by a message. */
+export declare function toolCallIds(m: Message): string[];
+/**
+ * The text blocks of a message, in order. W804: image blocks are deliberately
+ * NOT text — they are never concatenated here (and never stringified into a
+ * prompt); a consumer that needs the images reads messageImages.
+ */
+export declare function messageTexts(m: Message): string[];
+/** The single text block of a text-only message, or null. */
+export declare function messageText(m: Message): string | null;
+/** True when the message carries at least one tool call. */
+export declare function hasToolCalls(m: Message): boolean;
+/**
+ * True when v has the ImageRef shape the event codec and projection accept.
+ * name and original are optional and their absence is the normal case.
+ *
+ * W834 F07 (R3 batch A): the checks below mirror the FROZEN AttachmentRef
+ * schema exactly — a 64-lowercase-hex `attachment_id`, and `width`/`height`
+ * that are integers >= 1. The old "string + finite number" test let a
+ * non-hex id or a zero/negative/fractional dimension through the codec, into
+ * the projection and the model-visible history, while the schema rejected it.
+ */
+export declare function isImageRef(v: unknown): v is ImageRef;
+/**
+ * Field-whitelist normalization of one decoded attachment reference: unknown
+ * fields are dropped and absent optionals stay omitted (serde style). Returns
+ * null when the value is not an ImageRef at all.
+ */
+export declare function normalizeImageRef(v: unknown): ImageRef | null;
+/**
+ * The image references carried by a tool_result value (its attachments field,
+ * section 6.3). Anything that is not a valid reference is ignored, so a
+ * malformed tool value can never smuggle a bogus image into the prompt.
+ */
+export declare function attachmentRefsOfValue(value: unknown): ImageRef[];
+/** Provider-reported token usage for one LLM response (`Usage`). */
+export interface Usage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    cache_read: number;
+    reasoning_tokens: number;
+}
+/** All-zero usage (`Usage::default`). */
+export declare function zeroUsage(): Usage;
+/** `Usage::is_empty` — true when every counter is zero. */
+export declare function usageIsEmpty(u: Usage): boolean;
+/** `Usage::add` — per-field sum, returning a new value. */
+export declare function usageAdd(a: Usage, b: Usage): Usage;
+/** Sum a list of usages (`Usage +=` in a loop). */
+export declare function usageSum(usages: readonly Usage[]): Usage;
+/** Cache-hit ratio as reported by the statusline (`cache_read / prompt_tokens`). */
+export declare function cacheHitRatio(u: Usage): number;

package/dist/message.js

@@ -0,0 +1,252 @@
+/**
+ * The model-visible message model — a 1:1 port of
+ * `celestea_harness/crates/core/src/message.rs`.
+ *
+ * Shapes ported here:
+ *   Role      enum { System, User, Assistant, Tool }      (serde lowercase)
+ *   ToolCall  { id, name, args: Value }
+ *   Content   enum { Text(String), ToolCall(ToolCall) }   (tag="type", content="content")
+ *   Message   { role, content: Vec<Content>, tool_call_id: Option<String> }
+ *   ToolSpec  { name, description, parameters }           (declared in ./types.ts)
+ *   Usage     { prompt_tokens, completion_tokens, total_tokens,
+ *               cache_read, reasoning_tokens }             (flat counters)
+ *
+ * Field names and content-tag names are contract, not style: the LLM request
+ * builder and every engine projection depend on them. Do not rename anything.
+ */
+// ---------------------------------------------------------------------------
+// Role / Content / ToolCall / Message
+// ---------------------------------------------------------------------------
+/** `Role` — serde `rename_all = "lowercase"`. */
+export const ROLES = ["system", "user", "assistant", "tool"];
+/** The four media types the attachment pipeline accepts (section 5.4 magic-byte whitelist). */
+export const IMAGE_MEDIA_TYPES = ["image/png", "image/jpeg", "image/webp", "image/gif"];
+/** True for one of the four accepted normalized media types. */
+export function isImageMediaType(v) {
+    return typeof v === "string" && IMAGE_MEDIA_TYPES.includes(v);
+}
+// Constructors mirror the engine's `impl Message` (same names, camelCase).
+/** `Message::user`. */
+export function userMessage(text) {
+    return { role: "user", content: [{ type: "text", content: text }], tool_call_id: null };
+}
+/** `Message::system`. */
+export function systemMessage(text) {
+    return { role: "system", content: [{ type: "text", content: text }], tool_call_id: null };
+}
+/** `Message::assistant_text`. */
+export function assistantText(text) {
+    return { role: "assistant", content: [{ type: "text", content: text }], tool_call_id: null };
+}
+/** `Message::assistant_tool_call`. */
+export function assistantToolCall(call) {
+    return { role: "assistant", content: [{ type: "tool_call", content: call }], tool_call_id: null };
+}
+/** `Message::tool_result`. */
+export function toolResultMessage(id, text) {
+    return { role: "tool", content: [{ type: "text", content: text }], tool_call_id: id };
+}
+/**
+ * W804: a user message that carries text plus image references. The text block
+ * stays FIRST and the images follow (section 3.5 ordering rule); no-image callers
+ * keep using userMessage so the wire shape is byte-identical when there is
+ * nothing to attach.
+ */
+export function userMessageWithImages(text, images) {
+    const content = [{ type: "text", content: text }];
+    for (const ref of images)
+        content.push(imageContent(ref));
+    return { role: "user", content, tool_call_id: null };
+}
+/**
+ * W804: a tool result that carries the canonical JSON text plus image
+ * references (the read_image case, section 6.3). The TEXT remains the value's
+ * serde JSON — the model must still see path/dimensions — and the images are
+ * separate content blocks.
+ */
+export function toolResultWithImages(id, text, images) {
+    const content = [{ type: "text", content: text }];
+    for (const ref of images)
+        content.push(imageContent(ref));
+    return { role: "tool", content, tool_call_id: id };
+}
+/** Static namespace facade: `Message::user(…)` → `Message.user(…)`. */
+export const Message = {
+    user: userMessage,
+    system: systemMessage,
+    assistantText,
+    assistantToolCall,
+    toolResult: toolResultMessage,
+    userWithImages: userMessageWithImages,
+    toolResultWithImages,
+};
+// ---------------------------------------------------------------------------
+// Content helpers (the engine pattern-matches; these are the TS equivalents)
+// ---------------------------------------------------------------------------
+export function isTextContent(c) {
+    return c.type === "text";
+}
+export function isToolCallContent(c) {
+    return c.type === "tool_call";
+}
+export function isImageContent(c) {
+    return c.type === "image";
+}
+/** Wrap one already-content-addressed reference as a model-visible image block. */
+export function imageContent(ref) {
+    return { type: "image", content: ref };
+}
+/** The image blocks of a message, in order (references only, never bytes). */
+export function messageImages(m) {
+    const out = [];
+    for (const c of m.content)
+        if (isImageContent(c))
+            out.push(c.content);
+    return out;
+}
+/** The tool calls carried by a message (empty for a text-only message). */
+export function messageToolCalls(m) {
+    const out = [];
+    for (const c of m.content)
+        if (isToolCallContent(c))
+            out.push(c.content);
+    return out;
+}
+/** The ids of the tool calls carried by a message. */
+export function toolCallIds(m) {
+    return messageToolCalls(m).map((tc) => tc.id);
+}
+/**
+ * The text blocks of a message, in order. W804: image blocks are deliberately
+ * NOT text — they are never concatenated here (and never stringified into a
+ * prompt); a consumer that needs the images reads messageImages.
+ */
+export function messageTexts(m) {
+    const out = [];
+    for (const c of m.content)
+        if (isTextContent(c))
+            out.push(c.content);
+    return out;
+}
+/** The single text block of a text-only message, or null. */
+export function messageText(m) {
+    const texts = messageTexts(m);
+    return texts.length === 1 ? (texts[0] ?? null) : null;
+}
+/** True when the message carries at least one tool call. */
+export function hasToolCalls(m) {
+    return m.content.some(isToolCallContent);
+}
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Attachment reference helpers (W804: the log/event side of ImageRef)
+// ---------------------------------------------------------------------------
+/**
+ * The content-addressing id shape frozen by the contract: sha256, lowercase hex.
+ * (contracts/session-event.schema.json $defs.AttachmentRef.attachment_id)
+ */
+const ATTACHMENT_ID_PATTERN = /^[0-9a-f]{64}$/;
+/**
+ * True when v has the ImageRef shape the event codec and projection accept.
+ * name and original are optional and their absence is the normal case.
+ *
+ * W834 F07 (R3 batch A): the checks below mirror the FROZEN AttachmentRef
+ * schema exactly — a 64-lowercase-hex `attachment_id`, and `width`/`height`
+ * that are integers >= 1. The old "string + finite number" test let a
+ * non-hex id or a zero/negative/fractional dimension through the codec, into
+ * the projection and the model-visible history, while the schema rejected it.
+ */
+export function isImageRef(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const r = v;
+    return (typeof r["attachment_id"] === "string" &&
+        ATTACHMENT_ID_PATTERN.test(r["attachment_id"]) &&
+        isImageMediaType(r["media_type"]) &&
+        typeof r["width"] === "number" &&
+        Number.isInteger(r["width"]) &&
+        r["width"] >= 1 &&
+        typeof r["height"] === "number" &&
+        Number.isInteger(r["height"]) &&
+        r["height"] >= 1 &&
+        (r["name"] === undefined || typeof r["name"] === "string"));
+}
+/**
+ * Field-whitelist normalization of one decoded attachment reference: unknown
+ * fields are dropped and absent optionals stay omitted (serde style). Returns
+ * null when the value is not an ImageRef at all.
+ */
+export function normalizeImageRef(v) {
+    if (!isImageRef(v))
+        return null;
+    const out = {
+        attachment_id: v.attachment_id,
+        media_type: v.media_type,
+        width: v.width,
+        height: v.height,
+    };
+    if (typeof v.name === "string")
+        out.name = v.name;
+    if (typeof v.original === "object" && v.original !== null) {
+        const o = v.original;
+        if (typeof o["width"] === "number" &&
+            typeof o["height"] === "number" &&
+            typeof o["bytes"] === "number" &&
+            typeof o["media_type"] === "string") {
+            out.original = { width: o["width"], height: o["height"], bytes: o["bytes"], media_type: o["media_type"] };
+        }
+    }
+    return out;
+}
+/**
+ * The image references carried by a tool_result value (its attachments field,
+ * section 6.3). Anything that is not a valid reference is ignored, so a
+ * malformed tool value can never smuggle a bogus image into the prompt.
+ */
+export function attachmentRefsOfValue(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return [];
+    const raw = value["attachments"];
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        const ref = normalizeImageRef(item);
+        if (ref !== null)
+            out.push(ref);
+    }
+    return out;
+}
+/** All-zero usage (`Usage::default`). */
+export function zeroUsage() {
+    return { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0, cache_read: 0, reasoning_tokens: 0 };
+}
+/** `Usage::is_empty` — true when every counter is zero. */
+export function usageIsEmpty(u) {
+    return (u.prompt_tokens === 0 &&
+        u.completion_tokens === 0 &&
+        u.total_tokens === 0 &&
+        u.cache_read === 0 &&
+        u.reasoning_tokens === 0);
+}
+/** `Usage::add` — per-field sum, returning a new value. */
+export function usageAdd(a, b) {
+    return {
+        prompt_tokens: a.prompt_tokens + b.prompt_tokens,
+        completion_tokens: a.completion_tokens + b.completion_tokens,
+        total_tokens: a.total_tokens + b.total_tokens,
+        cache_read: a.cache_read + b.cache_read,
+        reasoning_tokens: a.reasoning_tokens + b.reasoning_tokens,
+    };
+}
+/** Sum a list of usages (`Usage +=` in a loop). */
+export function usageSum(usages) {
+    let total = zeroUsage();
+    for (const u of usages)
+        total = usageAdd(total, u);
+    return total;
+}
+/** Cache-hit ratio as reported by the statusline (`cache_read / prompt_tokens`). */
+export function cacheHitRatio(u) {
+    return u.prompt_tokens === 0 ? 0 : u.cache_read / u.prompt_tokens;
+}

package/dist/plugin.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Plugin seam — port of `crates/core/src/plugin.rs`.
+ *
+ * Everything in the harness is a plugin: the model adapter, the session log,
+ * the tool registry, even the agent loop. A plugin mounts itself by providing
+ * services (and event listeners) into a [Context]; the composition root decides
+ * which plugins exist, `core` never hardcodes a concrete implementation.
+ */
+import type { Context } from "./context.js";
+export interface Plugin {
+    /** Stable plugin name (the legacy engine defaults to `type_name`; explicit here). */
+    name(): string;
+    /** Provide services / listen on the context. */
+    mount(ctx: Context): void;
+}
+/** Ergonomic constructor for a plugin whose name is a string literal. */
+export declare function definePlugin(name: string, mount: (ctx: Context) => void): Plugin;
+/** Mount every plugin in registration order (later plugins patch earlier ones). */
+export declare function mountPlugins(ctx: Context, plugins: readonly Plugin[]): Context;
+/** The names of the mounted plugins, in mount order. */
+export declare function pluginNames(plugins: readonly Plugin[]): string[];
+/**
+ * `NamedRegistry<T>` — named, ordered, replaceable rows: the "patch"
+ * primitive. A later row with the same name shadows an earlier one
+ * (`get` scans backwards), while `iter` still reports every row.
+ */
+export declare class NamedRegistry<T> {
+    private readonly rows;
+    insert(name: string, value: T): void;
+    /** Last registration wins. */
+    get(name: string): T | undefined;
+    /** Every row, in registration order (shadowed rows included). */
+    entries(): Array<{
+        name: string;
+        value: T;
+    }>;
+    get size(): number;
+}

package/dist/plugin.js

@@ -0,0 +1,49 @@
+/**
+ * Plugin seam — port of `crates/core/src/plugin.rs`.
+ *
+ * Everything in the harness is a plugin: the model adapter, the session log,
+ * the tool registry, even the agent loop. A plugin mounts itself by providing
+ * services (and event listeners) into a [Context]; the composition root decides
+ * which plugins exist, `core` never hardcodes a concrete implementation.
+ */
+/** Ergonomic constructor for a plugin whose name is a string literal. */
+export function definePlugin(name, mount) {
+    return { name: () => name, mount };
+}
+/** Mount every plugin in registration order (later plugins patch earlier ones). */
+export function mountPlugins(ctx, plugins) {
+    for (const p of plugins)
+        p.mount(ctx);
+    return ctx;
+}
+/** The names of the mounted plugins, in mount order. */
+export function pluginNames(plugins) {
+    return plugins.map((p) => p.name());
+}
+/**
+ * `NamedRegistry<T>` — named, ordered, replaceable rows: the "patch"
+ * primitive. A later row with the same name shadows an earlier one
+ * (`get` scans backwards), while `iter` still reports every row.
+ */
+export class NamedRegistry {
+    rows = [];
+    insert(name, value) {
+        this.rows.push({ name, value });
+    }
+    /** Last registration wins. */
+    get(name) {
+        for (let i = this.rows.length - 1; i >= 0; i--) {
+            const row = this.rows[i];
+            if (row !== undefined && row.name === name)
+                return row.value;
+        }
+        return undefined;
+    }
+    /** Every row, in registration order (shadowed rows included). */
+    entries() {
+        return this.rows.map((r) => ({ ...r }));
+    }
+    get size() {
+        return this.rows.length;
+    }
+}

package/dist/projection.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The engine's `derive_messages` projection — a 1:1 port of
+ * `crates/session/src/log.rs:73-204`.
+ *
+ * A2 (W746): this algorithm lives in CORE, not in the L1 implementation
+ * package. `SessionLog.deriveMessages()` is a seam method, so the projection
+ * has to be part of the seam: an implementation that returns `[]` (or that
+ * re-implements the rules slightly differently) is a silent history loss, not
+ * an "alternative implementation". `@celestea/session` re-exports these
+ * functions; backends built with [projectingSessionLog] get them for free.
+ *
+ * Rules (all of them are contract, each pinned by a unit test):
+ *   - `TurnStart` / `TurnEnd` are structural markers, never projected;
+ *   - `ThinkingDelta` is replay-only decoration (W252), never projected;
+ *   - `ToolCall` rows are ACCUMULATED, not projected: consecutive calls merge
+ *     into ONE assistant message carrying one `tool_call` content per call
+ *     (LLM protocols require all tool calls of a turn in a single message);
+ *   - the accumulator is flushed before any other event, and after the last
+ *     event;
+ *   - rows with `parent_id` (W255 run_code sub-calls) stay in the log for
+ *     audit/replay but never reach the model: both the call and its result are
+ *     skipped — the outer run_code round trip is all the model sees;
+ *   - `ToolResult` projects to a tool message whose text is `"Error: {err}"`
+ *     when the error is a non-empty string, otherwise the serde_json text of
+ *     the value (`"null"` when absent).
+ *
+ * `balance_tool_calls` (W267) then makes the projection protocol-valid: every
+ * assistant tool_calls message must be followed by one tool message per call.
+ */
+import type { Message, ToolCall } from "./message.js";
+import type { SessionEvent, ToolResultSurface } from "./types.js";
+/** W267 synthetic result text — byte-for-byte the engine's string (b046564). */
+export declare const CANCELLED_TOOL_CALL_TEXT = "Error: tool call was cancelled before execution (no result recorded)";
+/** The model-visible history of a session log (the engine's `derive_messages_from`). */
+export declare function deriveMessagesFrom(events: readonly SessionEvent[]): Message[];
+/**
+ * Flush accumulated tool calls as ONE assistant message (`flush_tool_calls`).
+ * It drains the accumulator, mirroring the engine's `std::mem::take`.
+ */
+export declare function flushToolCalls(messages: Message[], pending: ToolCall[]): void;
+/**
+ * Project one non-tool-call event (`project`). Returns null for the events the
+ * model never sees.
+ */
+export declare function projectEvent(event: SessionEvent): Message | null;
+/**
+ * The text of a projected ToolResult: error first, else the value with its
+ * `surface` applied (absent surface = the value as serde JSON, as before).
+ */
+export declare function toolResultText(error: string | null | undefined, value: unknown, surface?: ToolResultSurface): string;
+/**
+ * W267 protocol balance: every assistant `tool_calls` message is followed by
+ * one `tool` message per call id. A cancelled/interrupted turn can stop between
+ * ToolCall and ToolResult, leaving a dangling call that makes the whole history
+ * invalid for OpenAI-compatible upstreams ("insufficient tool messages
+ * following tool_calls message"). A synthetic cancelled result is inserted for
+ * each unanswered call; the log itself is untouched (audit keeps the truth).
+ *
+ * UPSTREAM PARITY NOTE: the cursor advance `i = j + inserted + 1` is ported
+ * unchanged from `crates/session/src/log.rs:149`, including its quirk — when a
+ * call message is fully answered, the message sitting right after its results
+ * is skipped by the cursor, so an unbalanced trailing call message in exactly
+ * that position is NOT balanced (see `packages/session/src/log/derive.test.ts`:
+ * `mirrors the upstream cursor quirk`). Parity with the engine is the contract
+ * here; the quirk is reported upstream rather than diverged from silently.
+ */
+export declare function balanceToolCalls(messages: Message[]): void;