@project-ava-supernova/core 0.2.71

package/dist/agent/agent.d.ts

@@ -0,0 +1,623 @@
+import type { Provider } from '../providers/types.js';
+import type { Message, AssistantMessage, ToolCall, ModelDefinition, TokenUsage } from '../core/types.js';
+import type { ToolRegistry } from '../tools/tool-registry.js';
+import type { AvaSurface } from '../dataset/events.js';
+/**
+ * Desktop-automation + browser-control tools. Two separate jobs ride on this
+ * one list, which is why it's exported rather than local:
+ *
+ * 1. MODE GATING (any surface) — they're only valid in desktop mode, so the
+ *    no-prefix default path filters them out. Otherwise the model hallucinates
+ *    desktop_click_by_name mid-coding-session and the safety gate eats the noise.
+ *
+ * 2. MARKETPLACE COMPLIANCE (extension only) — Microsoft blocked this extension
+ *    over exactly these tools and required their removal to reinstate it
+ *    (v0.48.1, 2026-04-21). The extension host passes this list to
+ *    registerBuiltins({ exclude }) so they are NEVER CONSTRUCTED there.
+ *
+ * Until 2026-07-17 only job 1 existed, and job 2 was believed done but wasn't:
+ * the tools were registered on every surface and the only thing standing
+ * between a marketplace user and a desktop_* schema was mode detection, which
+ * keys off a literal '[Desktop Automation Mode]' prefix in the user's own
+ * message text and had no idea which surface it was running on. They couldn't
+ * actually drive anything (the extension supplies no uiaProvider/inputProvider),
+ * but "inert" is not the promise we made to MS.
+ *
+ * Keep this list as the ONE definition. If a desktop_* or browser_* tool is
+ * added to the registry and not added here, it ships to the marketplace.
+ */
+export declare const DESKTOP_TOOL_NAMES: readonly ["desktop_plan_approve", "desktop_launch_app", "desktop_list_elements", "desktop_click_by_name", "desktop_focus_window", "desktop_type", "desktop_key_press", "browser_navigate", "browser_snapshot", "browser_click", "browser_type", "browser_close"];
+/**
+ * The mode this turn is in, read from the tag the surfaces prepend.
+ *
+ * Exported because the AutoCoordinator had grown a second copy of this that
+ * sniffed the SYSTEM prompt for the string `'Plan mode'`. The marker is
+ * `[Plan Mode]`, on the user message, with a capital M — so the copy matched
+ * nothing and answered `'work'` for all seven modes, every turn, since it was
+ * written. One fact, two detectors, and the quiet one was wrong: the same
+ * shape as the dead tool names in the mode allowlists.
+ */
+export declare function detectModeFromMessages(messages: Message[]): string | null;
+/**
+ * Can this mode change files?
+ *
+ * Read from `MODE_ALLOWED_TOOLS` rather than a list of its own. A mode that is
+ * not handed `write` or `edit` is read-only by design, and nothing downstream
+ * should be able to grant it more than the mode itself has.
+ *
+ * Exists because the AutoCoordinator's Builder hand-off had no idea what mode
+ * it was in. Seen live 2026-08-19: a Plan-mode turn produced a plan card, wrote
+ * eleven todos, announced "Builder dispatched — executing 11 tasks", and started
+ * editing an Unreal project. Plan mode is read-only — it cannot open a file to
+ * write it — and the orchestrator went around that by spawning agents that
+ * could. The operator's words were "why are you coding when did i say to do
+ * anything but plan".
+ *
+ * An unknown mode returns true: work mode carries no prefix, so callers that
+ * default to it must not be silently blocked.
+ */
+/**
+ * The hard ceiling on what a persona may be handed in a READ-ONLY mode.
+ *
+ * The conductor scopes each persona by its own `allowedTools`, taken from the
+ * full registry — the mode allowlist is not consulted at all. So a mode's
+ * read-only guarantee held only for as long as nobody put a write-capable
+ * persona on its team, which is a promise about a roster rather than about the
+ * mode. Audited 2026-08-19: Plan's team happened to be clean, and the
+ * guarantee was one persona away from being false.
+ *
+ * Returns null for a mode that can edit files, deliberately. Work's allowlist
+ * is known to be stale and has never applied (it has no prefix, so the filter
+ * never runs) — clamping the Builder to it here would enforce a list nobody
+ * has checked, and would land as a breakage dressed as a tightening.
+ */
+export declare function readOnlyModeToolCeiling(mode: string | null | undefined): ReadonlySet<string> | null;
+export declare function modeCanEditFiles(mode: string | null | undefined): boolean;
+export interface ContextUsage {
+    used: number;
+    limit: number;
+    percent: number;
+}
+export type AgentEvent = {
+    type: 'stream_start';
+} | {
+    type: 'thinking_delta';
+    content: string;
+} | {
+    type: 'stream_delta';
+    content: string;
+} | {
+    type: 'stream_end';
+    message: AssistantMessage;
+} | {
+    type: 'progress';
+    labelKey: string;
+    model?: string;
+} | {
+    type: 'tool_call_start';
+    toolCall: ToolCall;
+} | {
+    type: 'tool_call_partial';
+    toolCallId: string;
+    data: string;
+} | {
+    type: 'tool_call_end';
+    toolCall: ToolCall;
+    result: string;
+    success: boolean;
+    metadata?: Record<string, unknown>;
+} | {
+    type: 'usage';
+    usage: TokenUsage;
+    cost?: number;
+} | {
+    type: 'error';
+    error: Error;
+} | {
+    type: 'context_usage';
+    context: ContextUsage;
+} | {
+    type: 'context_compression_start';
+} | {
+    type: 'context_compression_end';
+    originalTokens: number;
+    compressedTokens: number;
+} | {
+    type: 'context_truncated';
+    droppedCount: number;
+} | {
+    type: 'interjection';
+    content: string;
+} | {
+    type: 'done';
+    finalMessage: AssistantMessage;
+} | {
+    type: 'auto_routing';
+    category: string;
+    model: string;
+    reason: string;
+} | {
+    type: 'auto_agent_start';
+    model: string;
+    category: string;
+} | {
+    type: 'auto_agent_end';
+    model: string;
+    summary?: string;
+} | {
+    type: 'execution_start';
+    total: number;
+} | {
+    type: 'task_start';
+    taskId: string;
+    title: string;
+    index: number;
+    total: number;
+} | {
+    type: 'task_complete';
+    taskId: string;
+    title: string;
+    summary?: string;
+} | {
+    type: 'task_blocked';
+    taskId: string;
+    title: string;
+    reason: string;
+} | {
+    type: 'task_failed';
+    taskId: string;
+    title: string;
+    error: string;
+} | {
+    type: 'execution_complete';
+    completed: number;
+    blocked: number;
+    total: number;
+} | {
+    type: 'verification_start';
+    files: string[];
+} | {
+    type: 'verification_end';
+    passed: boolean;
+    report: string;
+    stats: {
+        total: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+    };
+} | {
+    type: 'verification_retry_start';
+    reason: string;
+} | {
+    type: 'verify_started';
+    files: string[];
+} | {
+    type: 'verify_passed';
+    files: string[];
+} | {
+    type: 'verify_failed';
+    files: string[];
+    output: string;
+} | {
+    type: 'fresh_eyes_started';
+    signature: string;
+} | {
+    type: 'fresh_eyes_complete';
+} | {
+    type: 'loop_refund_eligible';
+    signature: string;
+    tokensInRecovery: number;
+    reason: string;
+};
+export type AgentEventHandler = (event: AgentEvent) => void;
+export declare class Agent {
+    private readonly provider;
+    private readonly model;
+    private readonly visionProvider?;
+    private readonly visionModel?;
+    private readonly visionDescriptionCache;
+    private readonly toolRegistry;
+    private readonly toolContext;
+    private readonly pendingInterjections;
+    private pauseRequested;
+    private runToolEvidence;
+    /**
+     * The id of the turn currently running — one per run(), shared by every
+     * model call the turn makes, sent to our platform as X-Ava-Turn-Id.
+     *
+     * A tool-using turn calls the model repeatedly, and each call was landing in
+     * usage_logs as its own row with nothing connecting them. So a turn where
+     * the third call failed and the fourth succeeded was indistinguishable from
+     * four separate turns: retries invisible, and no way to tell a price change
+     * from a behaviour change. This is what makes cost-per-outcome answerable
+     * rather than just cost-per-call.
+     */
+    private runTurnId;
+    private runClaimFlagged;
+    private lastAudit;
+    private honestyVerifyAttempted;
+    /** Build the verify-or-restate re-prompt for the honesty gate. Maps the
+     *  claim to the tool that would actually check it, and offers the honest
+     *  alternative (restate without asserting). Internal — never shown as text. */
+    private buildHonestyVerifyNudge;
+    private _inThinkTag;
+    private currentTaskComplexity;
+    private readCountBeforeFirstWrite;
+    private hasWrittenInThisRun;
+    private explorationNudgeFired;
+    private designReinjectionTurn;
+    private designReinjectionLastTurn;
+    private designReinjectionLastMtimes;
+    /** Which surface this Agent is running in (cli/extension/ide/companion). */
+    private readonly surface;
+    /** Stable session UUID — one per Agent instance unless caller overrides. */
+    private readonly sessionId;
+    /**
+     * Loop-prevention master switch. When false, the pre-closure verify
+     * guard skips the verify_change call and falls straight through to the
+     * existing closure logic — the agent behaves exactly like it did before
+     * post-edit-verify shipped. Used as an emergency off switch and a way
+     * for power users who hate any extra LLM round-trips to opt out. The
+     * `recordEditFromTool` post-tool hook still runs (it's free) so the
+     * trajectory has the data if the flag flips on mid-session.
+     *
+     * Default true — the guard catches real bugs (build-broken closures,
+     * stuck-loop credit burn) and the cost is bounded (one verify pass +
+     * at most one fresh-eyes call per turn).
+     */
+    private readonly loopPreventionEnabled;
+    /**
+     * Recovery hook that returns the new messages accumulated during the
+     * currently-running Agent.run() call. Set at the top of run(),
+     * cleared (left as a stale closure) when run() exits — the next run
+     * overwrites it. Lets the caller reach into a cancelled run and
+     * persist Ava's partial work (completed tool calls, streamed
+     * assistant text) before the AbortError throws her out, instead of
+     * losing all of it because run() never reached its return statement.
+     *
+     * Without this, pressing Stop mid-task discarded every tool call and
+     * file edit Ava had completed — the next user message saw a
+     * conversation history with a gap where her work used to be, and
+     * Ava had no memory of what she'd done. See cancelRun() in the host.
+     */
+    private currentRunRecoveryHook;
+    /**
+     * Consecutive identical failures, per tool+arguments, within one run.
+     *
+     * A tool that fails the SAME WAY on the same arguments is not a retry
+     * situation — nothing has changed, so the next attempt cannot go differently.
+     * Observed in the wild: health_plan_create failed seven times running while
+     * the model cheerfully called it again each time, spending credits per turn,
+     * until the operator hit Stop. Nothing counted the repeats and nothing told
+     * anyone.
+     *
+     * Keyed on tool + arguments so a genuine retry with DIFFERENT arguments is
+     * untouched — changing the call is exactly the productive response to a
+     * failure, and this must not punish it.
+     */
+    private repeatedToolFailures;
+    /**
+     * Trajectory metadata from the previous Agent.run() in this session.
+     * Used to attach `correction_received` events to the trajectory the
+     * user is correcting, and to record whether that prior trajectory
+     * had verified before answering. Reset across agent instances.
+     */
+    private lastTrajectoryMetadata;
+    /**
+     * The mode of the previous Agent.run() in this session. Used to fire
+     * `mode_switch` dataset events when the user changes modes between
+     * turns (e.g. switches from Work to Plan via the [Plan Mode] prefix).
+     */
+    private lastDetectedMode;
+    constructor(opts: {
+        provider: Provider;
+        model: ModelDefinition;
+        /** Vision bridge — provider + model used to describe images for a text-only
+         *  coordinator (e.g. Qwen Omni Plus). When omitted, images get the legacy
+         *  "switch to a vision model" note instead of being described. */
+        visionProvider?: Provider;
+        visionModel?: ModelDefinition;
+        toolRegistry: ToolRegistry;
+        cwd: string;
+        sharedState?: Record<string, unknown>;
+        /**
+         * Surface this Agent runs in. Optional for backwards compatibility
+         * with existing callers, defaults to 'cli'. Each surface package
+         * (extension, ide, companion) should pass its own value so dataset
+         * events get the correct attribution.
+         */
+        surface?: AvaSurface;
+        /** Optional session UUID. Defaults to a fresh UUID per Agent. */
+        sessionId?: string;
+        /** Optional secret-grant callback for the secret_request tool. */
+        secretGranter?: (label: string, reason?: string) => Promise<{
+            id: string;
+            label: string;
+        } | null>;
+        /**
+         * Loop-prevention master switch. Defaults to true. Surfaces should
+         * read their settings (e.g. `ava-supernova.loopPrevention.enabled`)
+         * and pass through. Set false to disable the pre-closure verify
+         * guard + fresh-eyes escalation entirely.
+         */
+        loopPreventionEnabled?: boolean;
+    });
+    /**
+     * Return the new messages accumulated by the currently-running (or
+     * just-aborted) Agent.run() call. Used by the host's cancellation
+     * path to persist Ava's partial work — completed tool calls, streamed
+     * assistant text — before the conversation history is updated with
+     * the stop marker. Returns an empty array if no run has happened.
+     *
+     * Safe to call after run() has exited normally — the hook still
+     * returns a snapshot of the run that just finished.
+     */
+    getCurrentRunPartialMessages(): Message[];
+    /**
+     * Update the working directory used by all tool executions.
+     * Called when the user opens a different project folder mid-session.
+     */
+    setCwd(cwd: string): void;
+    /**
+     * Run a one-shot completion — single prompt, no tools, no streaming,
+     * timeout-bounded. Returns the assistant's trimmed text content, or
+     * null on error / timeout / empty response.
+     *
+     * Intended for utility callers that need a quick model round-trip
+     * without spinning up the full agent loop — e.g. the extension host's
+     * auto-journal reflection that writes a 2–4 sentence session summary
+     * after a completed turn. Cheap: one LLM call, no tool schemas, small
+     * max_tokens.
+     *
+     * Errors (network, provider, parse, timeout) all collapse to null so
+     * the caller can fall back gracefully without try/catch plumbing.
+     */
+    completeOneShot(prompt: string, opts?: {
+        maxTokens?: number;
+        timeoutMs?: number;
+    }): Promise<string | null>;
+    /**
+     * Inject a user message mid-run. The message will be appended to the
+     * conversation between the current and next agent iteration, allowing
+     * the user to steer, add context, or redirect without cancelling.
+     */
+    inject(message: string): void;
+    /**
+     * Request a graceful pause. Unlike the abort signal (a hard, immediate
+     * stop), this lets the current step finish and then exits the loop cleanly
+     * at the next boundary — so a typed "wait"/"pause" never rips Ava out
+     * mid-write. The conversation keeps everything completed; the user's next
+     * message continues from there.
+     */
+    requestPause(): void;
+    /**
+     * Drop every queued interjection without processing it.
+     *
+     * Called from the extension's cancel/stop handler so user injections
+     * queued during the aborted task don't silently replay as the first
+     * message of the next run. Without this, "stop" + "new task" would
+     * carry the last typed-but-not-yet-processed interjection into the
+     * fresh turn and feel like the old task was still alive.
+     */
+    clearPendingInterjections(): void;
+    /**
+     * True when at least one interjection is queued waiting to be consumed.
+     * Used by Conductor orchestration (passed via the orchestrate options'
+     * `hasPendingInjection` callback) to break out of the blocking persona
+     * loop early when the user sends a message — without this poll, the
+     * Conductor can hold the main Agent loop for 10–60 seconds on a full
+     * team and silently drop the injection when control returns.
+     */
+    hasPendingInterjections(): boolean;
+    /**
+     * Run one agent turn against the given conversation history.
+     *
+     * Contract: `messages` is the CALLER'S current conversation history
+     * — system prompt + user turns + assistant turns + tool calls/results,
+     * ending with the user's latest message to act on. The agent uses this
+     * as read-only input to build its own working context (which may be
+     * compressed, truncated, or trimmed internally for token economy);
+     * none of those transforms leak back to the caller.
+     *
+     * Returns ONLY the new messages produced by this turn — assistant
+     * replies, tool results, mid-turn user interjections. The caller is
+     * responsible for appending them to its conversation
+     * (`conversation.appendMessages(result)`).
+     *
+     * Before the Option 2 refactor (commit trail leading up to this) the
+     * return value was the full history plus the new turn's messages, and
+     * callers did `conversation.setMessages(result)` — which meant
+     * compression's destructive transforms could leak across the
+     * conversation boundary and silently clear user scrollback. Returning
+     * only new messages makes that class of bug impossible by construction.
+     */
+    /**
+     * Mode detection with the surface rule applied.
+     *
+     * `detectModeFromMessages` keys off a literal prefix in the USER's own
+     * message text ('[Desktop Automation Mode]'), and knows nothing about which
+     * surface it's running on. On the VS Code extension, desktop mode does not
+     * exist: Microsoft blocked us over the desktop/browser tools and required
+     * their removal to reinstate (v0.48.1). Without this, a marketplace user
+     * could type the prefix by hand and pull desktop_* into the turn — schemas,
+     * personas, mode-switch events, the lot.
+     *
+     * This is the second of two locks. The first is the extension host excluding
+     * DESKTOP_TOOL_NAMES at registerBuiltins, so the tools are never constructed
+     * there at all. Two locks, because we already broke this promise once by
+     * assuming one implicit one was enough.
+     */
+    private detectModeForSurface;
+    run(messages: Message[], onEvent: AgentEventHandler, signal?: AbortSignal): Promise<Message[]>;
+    private runInner;
+    /**
+     * Extract and save memories from a completed run.
+     * Fire-and-forget — never blocks the response.
+     * Errors are logged at debug level so they don't spam the UI but are visible for debugging.
+     */
+    private extractMemoriesFromRun;
+    private streamResponse;
+    /**
+     * Run a tool through the registry while emitting `tool_choice` /
+     * `tool_result` dataset events around the call. Returns the same
+     * shape `toolRegistry.execute` does — never throws (registry
+     * exceptions are converted to a failure result, mirroring the
+     * existing executeToolCall behaviour). Both the sequential and
+     * parallel tool paths in `runInner` go through this helper so the
+     * dataset trajectory captures every tool invocation in order.
+     */
+    private executeToolWithCapture;
+    private executeToolCall;
+    /**
+     * Scan a batch of tool calls for a UI file write/edit and return the first
+     * matching file path. Returns undefined if no UI file was touched.
+     * Used by the design context re-injection hook to decide whether to refresh
+     * the Decisions/design/* content into the next LLM turn.
+     */
+    private findUIFilePathInBatch;
+    /**
+     * Walk the message array backwards to find the most recent user-role
+     * message that represents a real user request (not a meta injection like
+     * a memory brief or compression summary). Returns the text content, or
+     * null if nothing qualifies.
+     */
+    private findLatestNonMetaUserMessage;
+    /**
+     * Append text to the first system-role message's content, or prepend a
+     * new system message if none exists. Used to merge the directness hint
+     * into the session prompt without creating a separate system message
+     * (which would break Qwen's "system must be at beginning" rule).
+     */
+    private appendToSystemMessage;
+    /**
+     * Classify a tool call as a read-only exploration call (file_read, glob,
+     * grep, list_directory, find_symbol, project_index) vs a write/action
+     * call (file_write, file_edit, bash, git_*, etc). Used by the exploration
+     * budget tracker to count "reads before first write" for each run.
+     */
+    private isReadOnlyToolCall;
+    private isWriteCapableToolCall;
+    /**
+     * After each batch of tool calls, update the exploration budget state
+     * and return a nudge message if the budget has been exceeded. The nudge
+     * is a soft signal — it's injected into the next LLM call's context
+     * telling the agent "you're stalling, commit to a direction." It never
+     * hard-stops the run; graceful escalation is the design intent.
+     *
+     * Returns null if no nudge is needed, or the nudge message body if the
+     * caller should inject it before the next turn.
+     */
+    private maybeExplorationBudgetNudge;
+    /** Get current context usage for a set of messages. */
+    getContextUsage(messages: Message[]): ContextUsage;
+    /** Manually compress context — triggered by user clicking the context bar. */
+    manualCompress(messages: Message[], onEvent: AgentEventHandler, signal?: AbortSignal): Promise<Message[]>;
+    /**
+     * Compress conversation context by summarizing older messages.
+     * Keeps the system prompt and last 8 messages (4 user-assistant exchanges)
+     * verbatim, summarizes everything in between using the model.
+     * Falls back silently if the compression API call fails.
+     */
+    compressContext(messages: Message[], onEvent: AgentEventHandler, signal?: AbortSignal): Promise<Message[]>;
+    private static estimateTextTokens;
+    private estimateMessageTokens;
+    /** Estimate total token count across an array of messages. */
+    estimateTokenCount(messages: Message[]): number;
+    /**
+     * Collapse old tool results to save tokens. Tool outputs older than
+     * KEEP_RECENT messages get trimmed to 200 chars + a note.
+     * This prevents token bleed from accumulated file reads, grep results, etc.
+     */
+    /**
+     * Trim older messages for token-cost control, preserving everything that
+     * matters for continuity:
+     *   - The system prompt is never touched.
+     *   - The pinned original user task is preserved verbatim (it's the root
+     *     intent of the whole session and must survive every trim pass).
+     *   - The last 8 messages are kept verbatim for recent context.
+     *   - `tool`-role messages older than the recent window are trimmed to
+     *     MAX_OLD_TOOL_CHARS (very aggressive — 200 chars — because tool
+     *     outputs rarely matter in full once the next turn has consumed them).
+     *   - `user` and `assistant` message bodies older than the recent window
+     *     get trimmed if they exceed OLD_MESSAGE_BODY_MAX_CHARS. The structural
+     *     "who said what" stays intact but verbose inlined content gets cut.
+     *   - `reasoning_content` on old plain-text assistant messages is stripped
+     *     entirely. Reasoning is working memory for the turn that produced it
+     *     and has zero value once the next turn has landed — but it can be
+     *     10x larger than the actual response and was previously kept forever.
+     *     Tool-calling assistant turns are an exception: DeepSeek V4 thinking
+     *     mode requires reasoning_content to be re-sent on every subsequent
+     *     request that follows a tool call, so it stays put on those.
+     *
+     * This is the primary lever for keeping per-turn token cost in check on
+     * long sessions. Combined with the earlier compression trigger (40%
+     * instead of 70%), it dramatically reduces the cost of running an agent
+     * for 60+ minutes on a single conversation.
+     */
+    private trimOldToolResults;
+    private truncateMessages;
+    /**
+     * Detect the "first turn after Stop" pattern and strip prior conversation.
+     *
+     * When cancelRun() fires in the extension, a marker is pushed into the
+     * conversation: `[User pressed Stop — previous task terminated...]`.
+     * After the user's next real message, the conversation looks like:
+     *
+     *   [... prior task, maybe 150K tokens ...]
+     *   [User pressed Stop — ...]   (meta user message)
+     *   Actual new user message
+     *
+     * The prior 150K tokens are dead weight. Sending them back means the
+     * model re-draws on the task the user told us to abandon. The fix is
+     * to detect this pattern and return a restricted message array:
+     *
+     *   [system prompt + stop directive]
+     *   [new user message]
+     *
+     * Detection: find the most recent stop marker. If it exists AND there
+     * is exactly one non-meta user message after it (and the assistant
+     * hasn't yet responded to that message), we're in the first post-stop
+     * turn — restrict.
+     *
+     * If more messages exist after that point (assistant replies, tool
+     * results), we've already handled the first post-stop turn normally;
+     * further turns see full context and operate as normal.
+     */
+    private maybeRestrictPostStopContext;
+    /**
+     * Age out old images and old tool results to cut per-turn token cost.
+     *
+     * Keeps the N most recent image-bearing user messages and the M most
+     * recent tool results in full fidelity. Older ones become text-only
+     * placeholders. The assistant's prior reasoning about the content
+     * remains intact in the assistant messages — we're just dropping raw
+     * payloads that the model no longer needs pixel-for-pixel.
+     *
+     * Why this exists: a single 25K-token screenshot re-sent across 10
+     * turns burns 250K tokens for no informational gain after turn 2 or 3.
+     * Same applies to verbose bash/file_read output: after the assistant
+     * has reasoned about it, we don't need the full dump in context
+     * anymore. This is the single biggest lever on token consumption in
+     * the agent loop. Conservative keep counts (2 images, 5 tool results)
+     * preserve enough active context for normal multi-step work while
+     * eliminating the long tail of stale payloads.
+     */
+    private ageHistoryContent;
+    /**
+     * Public wrapper around fixToolPairing for post-error recovery flows.
+     * When a provider returns 400, the message history may have landed in
+     * an invalid shape (orphan tool_calls, unmatched tool results). The
+     * extension's Retry handler calls this on the live conversation before
+     * issuing another request so the user isn't stuck in a loop of the
+     * same broken payload bouncing off the provider.
+     */
+    repairMessages(messages: Message[]): Message[];
+    /**
+     * Ensure every `tool` message has a preceding `assistant` with a matching
+     * `tool_calls` entry, and every `assistant` with `tool_calls` has all its
+     * `tool` results following it. Drops orphans from the front.
+     */
+    private fixToolPairing;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent/agent.ts"],"names":[],"mappings":"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"}