@canonmsg/claude-code-plugin 0.28.0 → 0.29.0

package/dist/session-state.d.ts

@@ -1,10 +1,12 @@
 import type { PermissionMode, SDKMessageOrigin, SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
-import type { DeliveryIntent, ModelOption, TurnLifecycleState } from '@canonmsg/core';
+import type { DeliveryIntent, ModelOption, TurnLifecycleState, TurnOutputBlock } from '@canonmsg/core';
 import type { TurnArtifactSnapshot } from '@canonmsg/coding-agent-host';
 export type ClaudeInputKind = 'seed' | 'canon';
 export type ClaudeArtifactRoutingMode = 'workspace-generated' | 'disabled';
 export interface ClaudeInputEnvelope {
     kind: ClaudeInputKind;
+    /** Correlates this envelope with its turn result's `user_message_uuid`. */
+    messageUuid: string;
     msg: SDKUserMessage;
     intent: DeliveryIntent;
     sourceMessageId: string | null;
@@ -27,20 +29,52 @@ export interface ClaudePendingFinalDelivery {
     retryCount: number;
     /** Carried so a retried failure notice keeps suppressing agent auto-replies. */
     suppressAutoReply?: boolean;
+    /**
+     * Ids of the chunked parts already durable in Canon, in part order — the
+     * resume cursor. Without it a retry re-ran the whole sequence from part 1,
+     * which the server answers with a 409 on every part it already holds, so a
+     * long answer could never get its tail delivered.
+     */
+    deliveredMessageIds?: string[];
+    /**
+     * The metadata built for the FIRST attempt, replayed byte-for-byte by every
+     * retry. The server's idempotency fingerprint spans `metadata`, so a rebuilt
+     * object differing by one trail block turns a harmless replay into a 409.
+     * Caching removes the determinism assumption instead of relying on it.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * The self-context the FIRST attempt sent under, replayed by every retry for
+     * the same reason as the metadata: `selfContextId` is part of the server's
+     * idempotency fingerprint, and the session's live value moves with every
+     * inbound message — including ones that only queue behind this delivery. Left
+     * to drift, a resumed tail lands in a different self-context from its own
+     * head, and a replayed part diverges into a 409.
+     */
+    selfContextId?: string | null;
+    /**
+     * The failure that put this delivery in retry, already bounded for quoting.
+     * Read when retries run out with parts already delivered, so the stops-short
+     * notice can say what went wrong.
+     */
+    lastErrorMessage?: string;
 }
+export type ClaudeSessionRunState = 'idle' | 'running' | 'requires_action';
 export interface ClaudeCompletedTurnState {
     state: {
-        state?: 'idle' | 'running' | 'requires_action';
+        state?: ClaudeSessionRunState;
     };
     pendingFinalText: string | null;
     pendingFinalDelivery: ClaudePendingFinalDelivery | null;
     activeInput: ClaudeInputEnvelope | null;
+    dispatchingInput?: ClaudeInputEnvelope | null;
     toolInProgress: boolean;
     turnState: TurnLifecycleState;
     currentTurnId: string | null;
     currentTurnOpenedAt: number | null;
     currentTurnUpdatedAt: number | null;
     lastAcceptedIntent: DeliveryIntent | null;
+    turnActivity?: ClaudeTurnActivityState;
 }
 export declare function createClaudeInputEnvelope(input: {
     kind: ClaudeInputKind;
@@ -68,7 +102,344 @@ export declare function shouldDeliverClaudeFinal(input: {
     finalizedTurnKeys: ReadonlySet<string>;
     interruptedTurnKeys: ReadonlySet<string>;
 }): boolean;
+export declare function rememberDispatchedClaudeInput(dispatched: Map<string, ClaudeInputEnvelope>, input: ClaudeInputEnvelope): void;
+/**
+ * The envelope a turn result belongs to, matched by `user_message_uuid`.
+ *
+ * The SDK coalesces queued inputs — three rapid messages can produce two turns —
+ * and reports the LAST message of a coalesced batch, which is the correct owner
+ * of the reply. Entries up to and including the match are consumed, so messages
+ * folded into that batch do not linger. Returns null when the result carries no
+ * usable uuid, leaving the caller to fall back.
+ */
+export declare function takeClaudeResultOwner(dispatched: Map<string, ClaudeInputEnvelope>, userMessageUuid: unknown): ClaudeInputEnvelope | null;
+/**
+ * Whether an envelope owns the session's active-turn slot. Only Canon turns do;
+ * any future internal envelope must remain invisible to user-facing turn state.
+ */
+export declare function claudeInputOwnsTurnSlot(input: Pick<ClaudeInputEnvelope, 'kind'> | null | undefined): boolean;
+/** Why a non-empty final was gated instead of sent. Diagnostics only. */
+export declare function describeUndeliveredClaudeFinal(input: {
+    turn: ClaudeInputEnvelope | null;
+    finalizedTurnKeys: ReadonlySet<string>;
+    interruptedTurnKeys: ReadonlySet<string>;
+}): string;
 export declare function resetClaudeCompletedTurnState(session: ClaudeCompletedTurnState): void;
+export interface ClaudeTurnSlotState {
+    state: {
+        state?: ClaudeSessionRunState;
+    };
+}
+/**
+ * Whether the session already owns the turn slot.
+ *
+ * 'running' covers both a turn the SDK is working on and one still being
+ * dispatched — the distinction matters only to an interrupt (below), never to
+ * whether the session is free to start something else. Deliberately NOT a new
+ * published state: `session.state.state` is the host's internal busy flag (the
+ * published session snapshot has no such field), and the user-facing signal is
+ * the turn state, which `openTurn` already publishes as 'thinking' at dequeue.
+ *
+ * 'requires_action' counts too: an approval or a question waiting on a human is
+ * a turn that is very much alive, holding the turn id and the live node. Reading
+ * it as free let a message arriving during the prompt open a SECOND turn over
+ * the waiting one — the same collision the reservation exists to stop, and
+ * inconsistent with every interrupt path, which already treats it as active.
+ */
+export declare function isClaudeTurnSlotReserved(state: ClaudeSessionRunState | undefined): boolean;
+/**
+ * Whether the SDK's `session_state_changed` echo may overwrite the host's own
+ * busy flag.
+ *
+ * The echo and the reservation share one field, and the echo lags: the 'idle'
+ * that closes turn A is emitted after A's result has flushed, and the host
+ * drains its queue INSIDE that result handler — so by the time the echo is
+ * processed, turn B may already hold the slot. Applying it there releases a
+ * slot that is taken, re-opening the dispatch-window race and killing the
+ * typing signal B just started. An 'idle' echo is therefore ignored while the
+ * host knows it is busy; every other echo is authoritative, so the SDK can
+ * still take the session busy on its own (a resumed session, an internal
+ * envelope) and nothing can wedge the flag at 'running'.
+ */
+export declare function shouldApplyClaudeEchoedSessionState(input: {
+    echoed: ClaudeSessionRunState | undefined;
+    /** An input is mid-dispatch: reserved by the host, not yet with the SDK. */
+    dispatching: boolean;
+    /** A final is still being handed to Canon; the turn is not over. */
+    hasPendingFinalDelivery: boolean;
+}): boolean;
+/** Claim the slot for an input about to be dispatched. Must precede any await. */
+export declare function reserveClaudeTurnSlot(session: ClaudeTurnSlotState): void;
+/** Give the slot back — dispatch failed, or the turn is over. */
+export declare function releaseClaudeTurnSlot(session: ClaudeTurnSlotState): void;
+export type ClaudeControlSignalAction = 'act' | 'consume' | 'defer';
+/**
+ * What to do with a stop signal from the control channel.
+ *
+ * The dispatch window is the interesting case. The slot is reserved but the
+ * input has not reached Claude, so there is nothing for `query.interrupt()` to
+ * stop — yet consuming the signal as stale would make a Stop pressed in that
+ * window do NOTHING while the turn it was aimed at ran to completion, silently.
+ * Deferring hands it back to the poller, which revisits the same node a cycle
+ * later, by which time the input really is in flight.
+ *
+ * Outside that window a signal with nothing to act on is consumed, except that
+ * 'stop_and_drop' still has work to do while inputs are queued: dropping them.
+ */
+export declare function decideClaudeControlSignalAction(input: {
+    type: 'interrupt' | 'stop_and_drop';
+    /** An input is mid-dispatch: reserved by the host, not yet with the SDK. */
+    dispatching: boolean;
+    sessionState: ClaudeSessionRunState | undefined;
+    queueDepth: number;
+}): ClaudeControlSignalAction;
+export type ClaudeInboundDispatchDecision = 'start' | 'queue' | 'queue-front' | 'interrupt';
+/**
+ * What to do with an inbound Canon message.
+ *
+ * `hasInterruptibleInput` is the one piece that is not just "is the session
+ * busy": an interrupt can only stop an input the SDK has actually pulled. In
+ * the dispatch window there is nothing in flight to interrupt — calling
+ * `query.interrupt()` there would fire at an idle SDK and then let the input it
+ * was meant to pre-empt reach the SDK a moment later, unaffected, while the
+ * interrupting message sat in the queue behind it. Such a message goes to the
+ * FRONT of the queue instead, and starts as soon as the dispatched turn ends.
+ *
+ * A session waiting on an approval ('requires_action') is busy like any other
+ * live turn: an ordinary message queues behind the prompt, and an interrupt
+ * stops the waiting turn rather than racing a second one alongside it.
+ */
+export declare function decideClaudeInboundDispatch(input: {
+    intent: DeliveryIntent;
+    sessionState: ClaudeSessionRunState | undefined;
+    hasPendingFinalDelivery: boolean;
+    /** An input the SDK has pulled off the stream — the only thing interrupt() can stop. */
+    hasInterruptibleInput: boolean;
+}): ClaudeInboundDispatchDecision;
+/**
+ * Whether a turn that has just finished may hand the slot back.
+ *
+ * Finishing spans awaits — the final send, the context-usage read — and the
+ * session reads free to inbound messages from the SDK's idle echo onward, so a
+ * message arriving in that window can reserve the slot for ITSELF. Releasing
+ * unconditionally afterwards would hand the same slot to a second message and
+ * put two turns into the SDK at once, which is exactly what the reservation
+ * exists to stop.
+ */
+export declare function shouldReleaseClaudeTurnSlot(input: {
+    /** A newer turn is mid-dispatch. */
+    dispatching: boolean;
+    /** The turn the SDK is working on now, if any. */
+    activeTurnKey: string | null;
+    /** The turn asking to release the slot. */
+    completedTurnKey: string | null;
+}): boolean;
+/** Whether the next queued input may be dequeued now. */
+export declare function canDrainClaudeQueuedInput(input: {
+    closed: boolean;
+    controlInterruptPending: boolean;
+    sessionState: ClaudeSessionRunState | undefined;
+    queueDepth: number;
+}): boolean;
+export interface ClaudeDispatchSessionState extends ClaudeTurnSlotState {
+    dispatchingInput: ClaudeInputEnvelope | null;
+    closed: boolean;
+}
+/** Why an input never reached the SDK. */
+export type ClaudeDispatchAbandonReason = 'error' | 'closed';
+export interface ClaudeDispatchDeps {
+    /** Publish the turn: thinking header, typing signal, seeded live node. */
+    openTurn: (input: ClaudeInputEnvelope) => void;
+    /** Tell Canon the message was accepted — a network round-trip. */
+    markAccepted: (input: ClaudeInputEnvelope) => Promise<void>;
+    /** Capture the artifact baseline — a workspace walk. */
+    prepareArtifacts: (input: ClaudeInputEnvelope) => Promise<void>;
+    /** Hand the input to the SDK. */
+    send: (input: ClaudeInputEnvelope) => void;
+    /** Settle an input that will never be answered, and retire its turn. */
+    abandon: (input: ClaudeInputEnvelope, reason: ClaudeDispatchAbandonReason, error?: unknown) => void;
+}
+/**
+ * Dispatch one input: reserve the slot, publish the turn, then do the slow
+ * work, then hand it to the SDK.
+ *
+ * The ORDER is the point, which is why this lives here rather than inline in
+ * the host: the reservation and `openTurn` must both happen before the first
+ * await. Marking the message accepted is a network round-trip and the artifact
+ * baseline walks the workspace; leaving the session readable as free across
+ * that window let a second message bypass the queue and open a competing turn
+ * over this one (`seedTurnStreaming` wiping the first turn's live node, two
+ * inputs in the SDK under mismatched attribution).
+ *
+ * Never rejects. An input that cannot be handed over — a throw in the window,
+ * or a session torn down mid-dispatch — is ABANDONED rather than dropped: the
+ * host settles the message and retires the turn, instead of leaving the sender
+ * on 'accepted' forever with a 'thinking' row nothing will complete.
+ */
+export declare function dispatchClaudeInput(session: ClaudeDispatchSessionState, input: ClaudeInputEnvelope, deps: ClaudeDispatchDeps): Promise<void>;
+/** States in which a turn is live for the clients (mirrors the turn-state write). */
+export declare function isOpenClaudeTurnState(state: TurnLifecycleState): boolean;
+/**
+ * Whether the SDK's `running` confirmation should open the turn itself.
+ *
+ * When the host already opened this turn the confirmation is a no-op: re-seeding
+ * `/streaming` would clobber the blocks and text the turn has produced since.
+ */
+export declare function shouldOpenClaudeTurnOnRunning(state: TurnLifecycleState): boolean;
+export interface ClaudeOpenTurnState {
+    pendingFinalText: string | null;
+    toolInProgress: boolean;
+    turnState: TurnLifecycleState;
+    currentTurnId: string | null;
+    currentTurnOpenedAt: number | null;
+    currentTurnUpdatedAt: number | null;
+    turnActivity?: ClaudeTurnActivityState;
+}
+/**
+ * Move the session into a fresh open turn: 'thinking', with a turn id, before
+ * a single SDK message has arrived.
+ *
+ * The id is minted per OPEN, unconditionally. Keying the mint on "the turn
+ * state is not open" reads equivalent and is not: the state a finished turn
+ * actually sits in during the final-handoff window is 'streaming'
+ * (`markPendingFinalDelivery` puts it there and only the reset clears it), so a
+ * message arriving in that window — precisely the case this exists for — would
+ * inherit an id that already carries a `turn_complete` message, and the client
+ * drops a live turn whose id is already complete.
+ *
+ * Nothing needs the guard: a turn is only ever opened when none is running —
+ * at dequeue, or on the SDK's `running` echo for a turn the host did not open
+ * itself (`shouldOpenClaudeTurnOnRunning` has already proved the state is not
+ * an open one there).
+ */
+export declare function openClaudeTurn(session: ClaudeOpenTurnState, now?: number): void;
+export interface ClaudeTurnActivityState {
+    /** content_block index → trail block id, for `content_block_stop`. */
+    blockIdByIndex: Map<number, string>;
+    /** `tool_use` id → trail block id, for out-of-order `tool_result`s. */
+    blockIdByToolUseId: Map<string, string>;
+    /** This turn's plan block, once TodoWrite has produced one. */
+    planBlockId: string | null;
+}
+/**
+ * Whether an SDK message describes the agent's OWN work rather than a
+ * subagent's. Nested messages carry the id of the Task call that spawned them;
+ * that Task's row already stands for the whole subagent, and publishing its
+ * internals would flood the trail — and the 20-block budget the persisted turn
+ * trail is bounded to.
+ */
+export declare function isClaudeMainTurnMessage(parentToolUseId: unknown): boolean;
+export declare function createClaudeTurnActivityState(): ClaudeTurnActivityState;
+export declare function resetClaudeTurnActivityState(state: ClaudeTurnActivityState): void;
+export declare function claudeToolBlockId(toolUseId: string): string;
+export declare function claudePlanBlockId(turnId: string | null | undefined): string;
+/**
+ * This turn's plan block, claimed once and then reused.
+ *
+ * Reading the claimed id back — rather than re-deriving it from the turn id on
+ * every TodoWrite — is what keeps a plan card whole: a turn id that changed
+ * mid-turn would otherwise split the plan into a second card instead of
+ * updating the first.
+ */
+export declare function claimClaudePlanBlockId(state: ClaudeTurnActivityState, turnId: string | null | undefined): string;
+/**
+ * Claim the trail block for a tool call the model has started emitting, and
+ * remember how to find it again from either the `tool_use` id (tool_result) or
+ * the content-block index (content_block_stop).
+ */
+export declare function registerClaudeToolCallBlock(state: ClaudeTurnActivityState, input: {
+    toolUseId?: unknown;
+    index?: unknown;
+    turnId?: string | null;
+}): string;
+/** The block a `tool_result` belongs to. Null when this turn never claimed one. */
+export declare function resolveClaudeToolBlockId(state: ClaudeTurnActivityState, toolUseId: unknown): string | null;
+/**
+ * The block a `content_block_stop` closes, consumed on read — indexes restart
+ * at 0 with every assistant message, so a stale entry would mis-resolve.
+ */
+export declare function takeClaudeToolBlockIdByIndex(state: ClaudeTurnActivityState, index: unknown): string | null;
+/** TodoWrite is the plan card, not a tool receipt. */
+export declare const CLAUDE_PLAN_TOOL_NAME = "TodoWrite";
+/** The margin row's title for the plan card, which is the card's own heading. */
+export declare const CLAUDE_PLAN_BLOCK_TITLE = "Plan";
+/**
+ * The margin row's title for a tool call: what the agent actually did, not just
+ * which tool it reached for. Falls back to the tool name whenever the typed
+ * input is missing or shaped differently than expected — an unknown tool is
+ * still worth a row.
+ */
+export declare function summarizeClaudeToolCall(name: unknown, input: unknown): string;
+/** One-line reason for a failed tool call, for the receipt's summary slot. */
+export declare function summarizeClaudeToolFailure(content: unknown): string;
+/**
+ * Progress text for a call that is taking a while. Short calls get nothing:
+ * every summary change is an RTDB write, and "Running for 1s" says nothing the
+ * running row does not already say.
+ */
+export declare function formatClaudeToolElapsed(seconds: unknown): string | null;
+/**
+ * TodoWrite's typed input mapped onto the shared plan grammar (`renderPlanSteps`
+ * in @canonmsg/coding-agent-host), which both coding-agent hosts render through
+ * so a plan card reads the same whichever runtime produced it. What stays here
+ * is what is genuinely Claude's: the SDK's todo shape, its `activeForm` wording
+ * for the step being worked on ("Running the tests"), the per-step and
+ * per-plan bounds, and publishing NOTHING rather than a bare heading when a
+ * TodoWrite call carries no usable step.
+ *
+ * Unusable entries are dropped before rendering, so the numbering the reader
+ * sees stays contiguous.
+ */
+export declare function renderTodosAsPlan(todos: unknown): string | null;
+export type ClaudeTrailCommand = {
+    op: 'add';
+    id: string;
+    kind: 'tool' | 'plan';
+    /** Left off deliberately when an existing row's status must survive. */
+    status?: 'running';
+    title?: string;
+    text?: string;
+} | {
+    op: 'update';
+    id: string;
+    title?: string;
+    summary?: string;
+} | {
+    op: 'complete';
+    id: string;
+    summary?: string;
+} | {
+    op: 'fail';
+    id: string;
+    summary: string;
+};
+/**
+ * `content_block_start` for a `tool_use`: the call claims its row, titled with
+ * the tool's name until the typed input arrives on the assistant message.
+ */
+export declare function planClaudeToolCallStart(state: ClaudeTurnActivityState, input: {
+    toolUseId?: unknown;
+    index?: unknown;
+    name?: unknown;
+    turnId?: string | null;
+}): ClaudeTrailCommand[];
+/**
+ * The assistant message is the first place a call's typed INPUT is visible —
+ * `content_block_start` carries only the name. It is what turns "Bash" into
+ * "Running: npm test" and TodoWrite into the plan card.
+ */
+export declare function planClaudeAssistantTrail(state: ClaudeTurnActivityState, content: unknown, turnId: string | null): ClaudeTrailCommand[];
+/**
+ * `tool_result` on a `user` message: where a call's OUTCOME finally arrives.
+ * Rows settle here and nowhere else — `content_block_stop` only means the model
+ * finished writing the call.
+ */
+export declare function planClaudeToolResults(state: ClaudeTurnActivityState, content: unknown): ClaudeTrailCommand[];
+/** `tool_progress`: a long call says how long it has been going. */
+export declare function planClaudeToolProgress(state: ClaudeTurnActivityState, input: {
+    toolUseId: unknown;
+    elapsedSeconds: unknown;
+}): ClaudeTrailCommand[];
 export declare function claudeOriginForCanonSender(input: {
     senderType?: string | null;
     senderId: string;
@@ -107,6 +478,168 @@ export declare function composeClaudeFinalText(input: {
     streamedText?: string | null;
     failureNotice?: string | null;
 }): string | null;
+export type ClaudeFinalDeliveryFailure = 'retry' | 'permanent' | 'already-delivered';
+/**
+ * How the host should react to a failed final-reply send.
+ *
+ * Core's `isRetryableCanonDeliveryError` is already right about what a retry
+ * can fix (429, 5xx, transport errors); what the host lacked was the other
+ * half — everything else is PERMANENT and must be surfaced instead of retried.
+ * A 409 from the server's idempotency guard means a message already exists
+ * under this id, so the reply is durable: that is a success, not a failure.
+ *
+ * A CHUNKED final is the exception (#616's rule, kept). A chunked send is N
+ * sequential messages that abort on the first failure, so a 409 says only that
+ * ONE part id is taken, with nothing to say which — and since the part ids are
+ * a pure hash of agent + conversation + turnKey, an id can be taken by an
+ * ENTIRELY DIFFERENT answer to the same inbound message, written by a previous
+ * process. Reading that as "the final is delivered" would finalize the turn
+ * with the tail never sent, so it stays 'permanent': a stops-short notice beats
+ * silently dropping the end of an answer.
+ *
+ * Resume support does not soften this. Core absorbs the one conflict that IS
+ * provably ours — the first part of a resumed attempt, whose write may have
+ * landed before its response was lost — and reports every other one, so a
+ * conflict reaching this function is precisely the case that must not be read
+ * as success.
+ */
+export declare function classifyFinalDeliveryFailure(error: unknown, options?: {
+    chunked?: boolean;
+}): ClaudeFinalDeliveryFailure;
+/**
+ * The pending-delivery record for a final that has to be retried, carrying the
+ * progress the next attempt needs.
+ *
+ * Progress is monotonic: a later attempt can only ever add parts, so the longer
+ * of the two lists wins and a retry can never rewind the cursor. The metadata
+ * and the self-context are pinned to the FIRST attempt's values, because those
+ * are what the durable parts were fingerprinted against.
+ */
+export declare function buildClaudePendingFinalDelivery(input: {
+    previous: ClaudePendingFinalDelivery | null;
+    turnKey: string;
+    messageId: string;
+    text: string;
+    suppressAutoReply?: boolean;
+    metadata?: Record<string, unknown>;
+    selfContextId?: string | null;
+    deliveredMessageIds?: readonly string[];
+    lastErrorMessage?: string;
+}): ClaudePendingFinalDelivery;
+/**
+ * What a retry of this turn's final should reuse: the parts already durable,
+ * and the metadata and self-context they were written with. Empty for a first
+ * attempt, or when the pending record belongs to a different turn.
+ */
+export declare function readClaudeFinalDeliveryResume(pending: ClaudePendingFinalDelivery | null, turnKey: string): {
+    deliveredMessageIds: string[];
+    metadata?: Record<string, unknown>;
+    selfContextId?: string | null;
+};
+/**
+ * The chunking options a final send opts into, built from the resume cursor.
+ *
+ * A helper rather than an inline literal so the opt-in is one testable seam:
+ * dropping `resumable` restores restart-from-part-1, which no assertion on a
+ * hand-built call could catch.
+ */
+export declare function buildClaudeFinalChunkingOptions(resume: {
+    deliveredMessageIds: readonly string[];
+}): {
+    resumable: true;
+    deliveredMessageIds: readonly string[];
+};
+/** True when a final of this size will be split across several messages. */
+export declare function claudeFinalWillChunk(finalText: string, maxTextBytes?: number): boolean;
+/**
+ * The turn trail to attach to a final that is about to be sent.
+ *
+ * A chunked final's LAST message carries the answer's tail, while the trail's
+ * text blocks carry the compacted head. chat-domain's `buildTurnRenderParts`
+ * appends `message.text` after structured speech that is not a prefix of it, so
+ * an unfiltered trail would render the head again above the tail. Text blocks
+ * are therefore dropped from a chunked final; tool/plan/approval/status blocks
+ * are the margin's activity record and stay. Unchunked finals are untouched,
+ * which keeps the common case byte-identical to before.
+ */
+export declare function prepareTurnTrailForDelivery(trail: ReadonlyArray<TurnOutputBlock>, willChunk: boolean): TurnOutputBlock[];
+export declare const CLAUDE_FINAL_TRUNCATION_MARKER = "\n\n_[truncated \u2014 the full answer exceeded Canon's message size limit]_";
+/**
+ * Last-resort degradation for a final Canon refuses to accept: keep as much of
+ * the answer as fits in ONE message and say that the rest was dropped. Prefers
+ * to cut at a paragraph break near the end so the survivor reads as prose. The
+ * result — marker included — always fits the byte budget.
+ *
+ * Deliberate trade-off: this keeps the HEAD, so a trailing paragraph is lost —
+ * including the turn-failure notice `composeClaudeFinalText` appends last. That
+ * is acceptable only because the host calls this on a final that already fits
+ * (an oversized final is chunked, never truncated), so nothing is actually cut;
+ * it is the bound that keeps the degraded send legal, not a text editor. A
+ * caller that truncates for real must re-attach its own trailing notice.
+ */
+export declare function buildTruncatedFinalText(finalText: string, maxTextBytes?: number): string;
+/**
+ * Server-side `metadata` cap, taken from the shared contract rather than
+ * re-typed here. Note the UNIT: unlike message text, which the server measures
+ * in UTF-8 bytes, metadata is capped by `JSON.stringify(metadata).length` —
+ * UTF-16 code units — in both places it is checked (the request schema's
+ * misleadingly named `maxJsonBytes` and the handler's inline check). Mirroring
+ * it in bytes would be a different, stricter rule that drops the margin's
+ * activity record on payloads Canon would have accepted.
+ */
+export declare const CLAUDE_MESSAGE_METADATA_MAX_CHARS: 4096;
+/**
+ * Defensive pre-flight for message metadata. Hosts already bound the trail via
+ * core's `buildBoundedTurnTrail`, so this should never fire; if it ever does,
+ * losing the margin's activity record beats losing the answer.
+ */
+export declare function boundClaudeFinalMetadata(metadata: Record<string, unknown>, maxChars?: 4096): Record<string, unknown>;
+/**
+ * The standalone notice for a final Canon will not accept — the last thing the
+ * host can say when the answer itself cannot be delivered.
+ *
+ * `partiallyDelivered` marks a chunked final whose earlier parts are already in
+ * the conversation: the reader can see text, and needs to be told it stops
+ * short rather than being left to assume the answer ended there.
+ */
+export declare function buildUndeliverableFinalNotice(input: {
+    error: unknown;
+    partiallyDelivered?: boolean;
+}): string;
+/**
+ * What is left to say when the bounded retries for a final run out.
+ *
+ * With parts of a chunked answer already in the conversation, silence is the
+ * wrong ending: the reader takes the last delivered part for the end of the
+ * answer. That case gets the stops-short notice, which completes the turn.
+ *
+ * With NOTHING delivered there is deliberately no notice, so the host can clear
+ * `/streaming` and let functions' `onStreamingCleared` preserve the streamed
+ * text as a durable progress message — a notice would complete the turn and
+ * suppress exactly that fallback, leaving the reader with an apology and no
+ * answer at all.
+ */
+export declare function planExhaustedFinalDelivery(pending: ClaudePendingFinalDelivery): {
+    partiallyDelivered: boolean;
+    notice: string | null;
+};
+/**
+ * End a final whose retries ran out: say it stops short, THEN retire the turn.
+ *
+ * The order is the point, which is why the sequence lives here. The pending
+ * record is what makes the session read busy to inbound messages, and the
+ * notice is a network send with its own retries — clearing the record first
+ * left the session 'running' with no timer and no pending delivery, so an
+ * interrupt arriving in that window fired `query.interrupt()` at an SDK whose
+ * turn had already produced its result, flipped the turn row to 'interrupted'
+ * and cleared `/streaming` out from under the retirement.
+ */
+export declare function runClaudeExhaustedFinalDelivery(session: {
+    pendingFinalDelivery: ClaudePendingFinalDelivery | null;
+}, pending: ClaudePendingFinalDelivery, deps: {
+    sendNotice: (notice: string) => Promise<unknown>;
+    retireTurn: () => void;
+}): Promise<void>;
 export declare const MINIMUM_CLAUDE_CLI_VERSION: readonly number[];
 export declare function parseClaudeCliVersion(output: string): number[] | null;
 export declare function formatClaudeCliVersion(version: readonly number[]): string;