/**
 * agent_bridge — agent loop core (WAB.4, 0.5.97).
 *
 * Authoritative spec: `docs/tasks/T-warm-agent-chat-bridge.md` WAB.4.
 * Architecture: `docs/tasks/WAB.1-architecture.md` decisions (c) + (g).
 *
 * Responsibility:
 *   Drive a single agent turn against the Anthropic Messages API:
 *     1. Take the persisted `state.history`, append the inbound user
 *        message to a working copy (do NOT mutate `state`).
 *     2. Apply cache_control markers to the system prompt + the last
 *        two USER messages in the working history (Anthropic's
 *        prompt-cache breakpoint policy — see comment below).
 *     3. Loop `messages.create` → assistant block → if `stop_reason`
 *        is `'tool_use'`, dispatch tools, append `tool_result` blocks
 *        back to working history, repeat. Otherwise return.
 *     4. Cap at `MAX_TOOL_ITERATIONS=8` round-trips; throw on overflow.
 *     5. Return the NEW history entries (user input + every assistant
 *        block + tool_result blocks) plus the final reply text. Caller
 *        feeds these into `SessionManager.appendTurn` which atomically
 *        persists + mutates state.
 *
 * Decision (c) lock (WAB.1):
 *   The Anthropic SDK client is passed in via `opts.client` — there is
 *   exactly ONE daemon-wide client. We do NOT construct or hold one
 *   here. This keeps connection pooling sane (one HTTP agent across all
 *   sessions) and matches Hermes's `_get_or_create_agent` pattern.
 *
 * Decision (g) lock (WAB.1):
 *   `opts.model` is a fully-resolved string (e.g.
 *   `claude-haiku-4-5-20251001`) — alias resolution happens upstream in
 *   WAB.6's `pack_binding.ts`. This module is model-neutral; it never
 *   inspects the string. v1 supports `api` mode only because the
 *   subscription/local/MCP modes don't expose a tool-use round-trip.
 *
 * Cache-control marker policy (Anthropic prompt caching):
 *   - System prompt: ALWAYS marked (1 breakpoint). Most stable thing
 *     across turns — the agent's identity + tool surface description.
 *   - Last 2 user messages: marked on the FINAL content block of each
 *     (2 breakpoints). This keeps the previous-turn context warm
 *     through the current turn so a follow-up message hits the cache.
 *   - Total: 3 of Anthropic's 4-breakpoint limit. We reserve the 4th
 *     for a future tools-section marker.
 *   - 5-minute TTL: Anthropic's default. We do not refresh — sessions
 *     idle longer than 5 min lose the cache (WAB.1 risk callout
 *     accepted this).
 *
 * SDK type compatibility:
 *   `@anthropic-ai/sdk` v0.30.1's STABLE `messages.d.ts` does NOT
 *   include `cache_control` on content-block params (only the `beta`
 *   namespace does). The API itself accepts `cache_control` on the
 *   stable endpoint — prompt caching went GA mid-2024 and the SDK
 *   types haven't caught up on v0.30. To avoid forcing the upgrade or
 *   binding ourselves to the beta path, we use a STRUCTURAL contract
 *   (`AnthropicMessageClient`) below — opensquid owns the types, the
 *   real SDK client satisfies the contract structurally. No `any`, no
 *   `as never` casts at the API boundary.
 *
 * Imports from: ./types.js.
 * Imported by: dispatcher.ts (WAB.5 — glue), daemon.ts (WAB.7),
 *   agent_loop.test.ts.
 */
import type { ChatHistoryEntry, SessionState, ToolDispatcher, ToolSpec } from './types.js';
/** Hard cap on tool-use round-trips per turn. Throws on overflow. */
export declare const MAX_TOOL_ITERATIONS = 8;
/** Default `max_tokens` for the assistant's reply. Overridable per call. */
export declare const DEFAULT_MAX_TOKENS = 1024;
/** Number of trailing user messages to mark with cache_control. */
export declare const CACHE_BREAKPOINT_USER_MSGS = 2;
export interface AnthropicCacheControl {
    type: 'ephemeral';
}
export interface AnthropicTextBlockParam {
    type: 'text';
    text: string;
    cache_control?: AnthropicCacheControl;
}
export interface AnthropicToolUseBlockParam {
    type: 'tool_use';
    id: string;
    name: string;
    input: unknown;
    cache_control?: AnthropicCacheControl;
}
export interface AnthropicToolResultBlockParam {
    type: 'tool_result';
    tool_use_id: string;
    content: string;
    cache_control?: AnthropicCacheControl;
}
export type AnthropicContentBlockParam = AnthropicTextBlockParam | AnthropicToolUseBlockParam | AnthropicToolResultBlockParam;
export interface AnthropicMessageParam {
    role: 'user' | 'assistant';
    content: AnthropicContentBlockParam[];
}
export interface AnthropicSystemBlock {
    type: 'text';
    text: string;
    cache_control?: AnthropicCacheControl;
}
export interface AnthropicResponseTextBlock {
    type: 'text';
    text: string;
}
export interface AnthropicResponseToolUseBlock {
    type: 'tool_use';
    id: string;
    name: string;
    input: unknown;
}
export type AnthropicResponseBlock = AnthropicResponseTextBlock | AnthropicResponseToolUseBlock;
export interface AnthropicMessageResponse {
    content: AnthropicResponseBlock[];
    stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | null;
}
export interface AnthropicMessageCreateParams {
    model: string;
    max_tokens: number;
    system: AnthropicSystemBlock[];
    tools: ToolSpec[];
    messages: AnthropicMessageParam[];
}
export interface AnthropicMessageClient {
    create(params: AnthropicMessageCreateParams): Promise<AnthropicMessageResponse>;
}
export interface RunAgentTurnOptions {
    /** Daemon-wide Anthropic `client.messages` (one instance per daemon). */
    client: AnthropicMessageClient;
    /** Resolved model id (alias resolution upstream in WAB.6). */
    model: string;
    /** Assistant system prompt (loaded from pack `chat_agent.yaml` in WAB.6). */
    systemPrompt: string;
    /** Tool surface — typically `dispatcher.list()`. */
    tools: ToolSpec[];
    /** Resolves `tool_use` blocks from the model. */
    dispatcher: ToolDispatcher;
    /** Override `DEFAULT_MAX_TOKENS`. */
    maxTokens?: number;
    /** Override `MAX_TOOL_ITERATIONS`. */
    maxToolIterations?: number;
    /** Injected clock (tests). Defaults to `() => new Date().toISOString()`. */
    nowIso?: () => string;
}
export interface RunAgentTurnResult {
    /** New entries appended during this turn (user input + assistant + tool_results). */
    assistantEntries: ChatHistoryEntry[];
    /** Final text reply (concatenated text blocks from the terminal assistant message). */
    replyText: string;
}
export declare function runAgentTurn(state: SessionState, inboundText: string, opts: RunAgentTurnOptions): Promise<RunAgentTurnResult>;
//# sourceMappingURL=agent_loop.d.ts.map