/**
 * Command/event surface of `EmbeddedAgentRuntime` — the contract clients
 * drive and observe. See shortcutXL/docs/migration/spec.md.
 */
import type { AgentLoopEvent, ThinkingLevel } from '../core/core-types.js';
import { type AgentSessionContext } from './agent-session-store.js';
import { type AgentSnapshot } from './agent-snapshot.js';
import { type AgentFileUpload } from './agent-uploads.js';
import type { HostToolRequest, HostToolResult, ToolRegistry } from './host-tool-api.js';
import type { RunStatsEntry, RunStatsTokenUsageByModel } from './run-stats.js';
import { type FocusedRange, type RangeRestriction } from './user-turn-enrichments.js';
export type { FocusedRange, RangeRestriction } from './user-turn-enrichments.js';
export declare const AgentCommandKind: {
    readonly Abort: "abort";
    readonly Configure: "configure";
    readonly Dispose: "dispose";
    readonly SubmitPrompt: "submitPrompt";
};
export type AgentCommandKind = (typeof AgentCommandKind)[keyof typeof AgentCommandKind];
export interface AgentConfiguration {
    systemPrompt: string;
    toolNames: string[];
    /**
     * The agent mode this configuration represents — `action`, `ask`, `plan`,
     * `shorty`, `review`, etc.
     *
     * The host computes `systemPrompt` + `toolNames` from this value before
     * sending Configure. The runtime uses it for two things only:
     *
     * 1. `switch_mode`'s dynamic description (so the LLM sees its current mode).
     * 2. Drift detection — if a host sends a prompt+tools that disagree with
     *    `agentMode`, the runtime can flag it instead of silently misbehaving.
     *
     * Optional today for incremental rollout. New callers must set it; old
     * callers degrade to the static fallback description.
     */
    agentMode?: string;
}
export interface ConfigureAgentCommand {
    kind: typeof AgentCommandKind.Configure;
    configuration: AgentConfiguration;
}
/**
 * Per-turn speed mode. Only `'fast'` is meaningful and only on supported
 * Shortcut models. The proxy gates this server-side: `speed='fast'` for unsupported
 * models is silently dropped. Mirrors the `speed` field in
 * `backend/agent/config.py:Configuration`.
 */
export type AgentSubmitSpeed = 'fast' | 'standard';
/**
 * Per-turn knobs the host attaches to a single submit. Only fields that
 * actually affect a turn's LLM call or compaction decision belong here —
 * persistent settings live on `EmbeddedAgentSettingsStore`. See
 * shortcutXL/docs/migration/archive/section_7_per_turn/spec.md §7-A and
 * behavior-matrix.md §7-A-1..6 for the full contract.
 *
 * Precedence at submit time:
 *   1. AgentSubmitOptions.model (and the other per-turn fields) override
 *      the persistent baseline for the duration of this submit only.
 *   2. Persistent settings on `EmbeddedAgentSettingsStore` / agent state
 *      are restored after the run so subsequent submits see the baseline.
 *
 * The runtime CreditGate is a submit-boundary halt, not a model override.
 *
 * No leak across turns: PT-3 in behavior-matrix.md asserts a per-turn
 * override never survives into the next submit.
 *
 * Note on extended context (Anthropic 1M-context beta): NOT exposed here
 * because our `/api/llm/stream` proxy doesn't forward a `context_size`
 * flag today. Opus 4.7 has 1M natively; other Claude models on the proxy
 * would require a backend change before a per-turn knob would do anything.
 * Until that lands, callers who need to reshape the compaction decision
 * use `baseTokenLimit` (LLM call itself is unaffected).
 */
export interface AgentSubmitOptions {
    /** Compaction-decision context window override. LLM call unaffected. */
    baseTokenLimit?: number;
    /**
     * Model id for THIS submit only. The runtime resolves via
     * `modelRegistry.find(provider, modelId)` against the user's currently
     * selected provider. Falls back to persistent agent.state.model when
     * undefined or unresolvable.
     */
    model?: string;
    /**
     * Thinking level for THIS submit only. Maps to `effort_level` and
     * `thinking_type` on the proxy wire (`stream.ts` does the translation).
     * Falls back to persistent agent.state.thinkingLevel when undefined.
     */
    thinkingLevel?: ThinkingLevel;
    /**
     * Speed mode for THIS submit only. Currently only meaningful as
     * `'fast'` on supported Shortcut models. The proxy drops the flag for other models.
     * Maps to the `speed` field in the proxy request body.
     */
    speed?: AgentSubmitSpeed;
    /** §18 branch editing: snapshot id of the user message to truncate-before then resubmit. */
    editFromMessageId?: string;
    /** Host-provided user message id. ShortcutXL web uses this as the workbook checkpoint key. */
    userMessageId?: string;
    /** UI-only interaction mode for the submitted turn, exposed on snapshots. */
    interactionMode?: string;
    /** §17 per-submit file uploads; client-owned, rendered as a content block on the user message. */
    fileUploads?: AgentFileUpload[];
    /**
     * §25 per-submit workbook summary. Rendered as the `# Brief summary of the current
     * active workbook and sheets *(NOT an attachment)*` content block. Empty string ⇒ no block.
     */
    workbookSummary?: string;
    /**
     * §25 per-submit user-focus context. Rendered as the `# User Focus` content block.
     * Suppressed when `rangeRestrictions` is non-empty (precedence rule, backend parity).
     */
    focusedRange?: FocusedRange;
    /**
     * §25 per-submit range restrictions. Rendered as `# Critical Restriction` (mode=`restricted`)
     * or `# Enhanced Context` (mode=`enhanced`). Empty array ⇒ no block. The first element's
     * `mode` decides the block kind for the entire list.
     */
    rangeRestrictions?: RangeRestriction[];
    /**
     * §25 reset boundary. When `true`, the user message for THIS submit is tagged
     * `contextResetBoundary: true`; `convertAgentMessagesToLlm` will slice the LLM-projected
     * messages from this boundary forward. UI snapshot still shows the full thread.
     *
     * Replaces the pre-§25 `submitShortcutXLMessage` rejection of context-reset on SXL threads.
     */
    contextReset?: boolean;
    /** Host-requested tool names to hide for this submit. */
    skipTools?: string[];
}
export interface SubmitPromptCommand {
    kind: typeof AgentCommandKind.SubmitPrompt;
    prompt: string;
    /** Optional per-turn knobs. Absent on legacy callers. */
    submitOptions?: AgentSubmitOptions;
}
export interface AbortAgentCommand {
    kind: typeof AgentCommandKind.Abort;
}
export interface DisposeAgentCommand {
    kind: typeof AgentCommandKind.Dispose;
}
export type AgentCommand = SubmitPromptCommand | ConfigureAgentCommand | AbortAgentCommand | DisposeAgentCommand;
export declare const AgentEventKind: {
    readonly ChildAgentEvent: "childAgentEvent";
    readonly HostToolRequest: "hostToolRequest";
    readonly HostToolResultApplied: "hostToolResultApplied";
    readonly ConfigurationUpdated: "configurationUpdated";
    readonly FatalError: "fatalError";
    /** Fired when the post-turn suggestions runner starts. */
    readonly FollowupSuggestionsStarted: "followupSuggestionsStarted";
    readonly FollowupSuggestionsReady: "followupSuggestionsReady";
    /** §14 — fired when the post-turn suggestions runner errors. */
    readonly FollowupSuggestionsFailed: "followupSuggestionsFailed";
    readonly MainMessageStream: "mainMessageStream";
    readonly RunStatsUpdated: "runStatsUpdated";
    readonly SessionContextUpdated: "sessionContextUpdated";
    readonly SnapshotUpdated: "snapshotUpdated";
    readonly Telemetry: "telemetry";
};
export type AgentEventKind = (typeof AgentEventKind)[keyof typeof AgentEventKind];
export declare const AgentProtocolErrorKind: {
    readonly HostToolRequestProtocol: "hostToolRequestProtocol";
    readonly ControllerProtocol: "controllerProtocol";
    readonly WorkerPortProtocol: "workerPortProtocol";
};
export type AgentProtocolErrorKind = (typeof AgentProtocolErrorKind)[keyof typeof AgentProtocolErrorKind];
export interface RuntimeErrorInfo {
    kind: AgentProtocolErrorKind;
    message: string;
    requestId?: string;
}
export interface AgentHostToolRequestEvent {
    kind: typeof AgentEventKind.HostToolRequest;
    request: HostToolRequest;
}
export interface AgentHostToolResultAppliedEvent {
    kind: typeof AgentEventKind.HostToolResultApplied;
    result: HostToolResult;
}
export interface AgentConfigurationUpdatedEvent {
    configuration: AgentConfiguration;
    kind: typeof AgentEventKind.ConfigurationUpdated;
}
export interface AgentFatalErrorEvent {
    kind: typeof AgentEventKind.FatalError;
    error: RuntimeErrorInfo;
}
export interface AgentSnapshotUpdatedEvent {
    kind: typeof AgentEventKind.SnapshotUpdated;
    snapshot: AgentSnapshot;
}
export declare const AgentMainMessageStreamEventType: {
    readonly End: "end";
    readonly Start: "start";
    readonly TextDelta: "text_delta";
    readonly ThinkingDelta: "thinking_delta";
    readonly ToolCallEnd: "toolcall_end";
};
export type AgentMainMessageStreamEventType = (typeof AgentMainMessageStreamEventType)[keyof typeof AgentMainMessageStreamEventType];
export type AgentMainMessageStreamPayload = {
    type: typeof AgentMainMessageStreamEventType.Start;
    /** Stable UI message id that snapshots will use for the committed assistant message. */
    messageId: string;
    runId?: string;
    streamId: string;
} | {
    contentIndex: number;
    delta: string;
    runId?: string;
    streamId: string;
    type: typeof AgentMainMessageStreamEventType.TextDelta | typeof AgentMainMessageStreamEventType.ThinkingDelta;
} | {
    args: Record<string, unknown>;
    contentIndex: number;
    runId?: string;
    streamId: string;
    toolCallId: string;
    toolName: string;
    type: typeof AgentMainMessageStreamEventType.ToolCallEnd;
} | {
    runId?: string;
    streamId: string;
    type: typeof AgentMainMessageStreamEventType.End;
};
export interface AgentMainMessageStreamEvent {
    kind: typeof AgentEventKind.MainMessageStream;
    stream: AgentMainMessageStreamPayload;
}
export declare const AGENT_TOOL_IN_FLIGHT_DISPLAY_DELAY_MS = 30000;
export interface AgentSessionContextUpdatedEvent {
    context: AgentSessionContext;
    kind: typeof AgentEventKind.SessionContextUpdated;
}
export declare const AgentTelemetryEventType: {
    readonly OperationFinished: "operation_finished";
    readonly OperationStarted: "operation_started";
    readonly RecoveryFailed: "recovery_failed";
    readonly RecoveryFallback: "recovery_fallback";
    readonly RecoveryStarted: "recovery_started";
    readonly RecoverySucceeded: "recovery_succeeded";
    readonly RunStarted: "run_started";
};
export type AgentTelemetryEventType = (typeof AgentTelemetryEventType)[keyof typeof AgentTelemetryEventType];
export declare const AgentTelemetryTerminalPhase: {
    readonly Cancelled: "cancelled";
    readonly Completed: "completed";
    readonly Failed: "failed";
};
export type AgentTelemetryTerminalPhase = (typeof AgentTelemetryTerminalPhase)[keyof typeof AgentTelemetryTerminalPhase];
export type AgentTelemetryOperationKind = 'compaction' | 'host_tool' | 'llm' | 'subagent' | 'tool';
export type AgentTelemetryRecoveryCategory = 'rate_limit' | 'overloaded' | 'server_error' | 'context_overflow' | 'max_output_tokens' | 'auth_error' | 'tool_error' | 'unknown';
export type AgentTelemetryPayload = {
    type: typeof AgentTelemetryEventType.RunStarted;
    runId?: string;
} | {
    type: typeof AgentTelemetryEventType.OperationStarted;
    opId: string;
    opKind: AgentTelemetryOperationKind;
    startedAt: number;
    runId?: string;
    toolCallId?: string;
    toolName?: string;
} | {
    type: typeof AgentTelemetryEventType.OperationFinished;
    opId: string;
    opKind: AgentTelemetryOperationKind;
    phase: AgentTelemetryTerminalPhase;
    startedAt: number;
    endedAt: number;
    runId?: string;
    toolCallId?: string;
    toolName?: string;
    metadata?: Record<string, unknown>;
    errorMessage?: string;
} | {
    type: typeof AgentTelemetryEventType.RecoveryStarted;
    category: AgentTelemetryRecoveryCategory;
    attempt: number;
    maxAttempts: number;
    delayMs: number;
    errorMessage: string;
    runId?: string;
} | {
    type: typeof AgentTelemetryEventType.RecoverySucceeded;
    category: AgentTelemetryRecoveryCategory;
    attempt: number;
    runId?: string;
} | {
    type: typeof AgentTelemetryEventType.RecoveryFailed;
    category: AgentTelemetryRecoveryCategory;
    attempt: number;
    finalError?: string;
    runId?: string;
} | {
    type: typeof AgentTelemetryEventType.RecoveryFallback;
    category: AgentTelemetryRecoveryCategory;
    fallbackModel: string;
    runId?: string;
};
export interface AgentTelemetryEvent {
    kind: typeof AgentEventKind.Telemetry;
    telemetry: AgentTelemetryPayload;
}
/** Per-run usage snapshot ferried from worker to host for the `RunMetricsDropdown` UI. */
export interface AgentRunStatsUpdatedEvent {
    kind: typeof AgentEventKind.RunStatsUpdated;
    threadTokenUsage: RunStatsTokenUsageByModel;
    runEntry: RunStatsEntry;
}
/** Fired once when the background follow-up suggestions job starts. */
export interface AgentFollowupSuggestionsStartedEvent {
    kind: typeof AgentEventKind.FollowupSuggestionsStarted;
}
export interface AgentSkillProposal {
    name: string;
    description: string;
    prompt: string;
}
/**
 * Fire-and-forget follow-up suggestions for the just-finished turn. Emitted
 * once per successful (`Completed`) turn from the embedded runtime; failures
 * are swallowed silently so suggestions never block the agent loop.
 *
 * The host attaches these to the just-finished thread under the last
 * assistant message so the user can click to submit them as the next turn.
 *
 * Parity note: backend-side suggestions are produced by a separate
 * LangGraph subgraph and ferried over SSE. The embedded runtime collapses
 * that to one in-process LLM call — same Haiku model, same forced
 * `tool_choice` on `set_followup_suggestions`, same payload shape.
 */
export interface AgentFollowupSuggestionsReadyEvent {
    kind: typeof AgentEventKind.FollowupSuggestionsReady;
    /** 1-3 follow-up prompts the user might want to send next. */
    suggestions: string[];
    /** Optional skill proposal for turning the workflow into a reusable skill. */
    skillProposal?: AgentSkillProposal | null;
}
/** §14 — emitted when the post-turn suggestions runner errors. */
export interface AgentFollowupSuggestionsFailedEvent {
    kind: typeof AgentEventKind.FollowupSuggestionsFailed;
    /** Short error message; never includes API keys or internal URLs. */
    message: string;
}
/**
 * Cross-process validator. The event ferries through `postMessage`, so the
 * receiver MUST verify the per-model usage shape before handing it to
 * `useRunStatsStore.updateFromBackend` — a malformed payload from a
 * compromised or stale worker would otherwise corrupt the store.
 */
export declare function isAgentRunStatsUpdatedEvent(value: unknown): value is AgentRunStatsUpdatedEvent;
/** Forwarded subagent event tagged with parent task identifiers for UI routing. */
export interface AgentChildLoopEvent {
    kind: typeof AgentEventKind.ChildAgentEvent;
    /** Parent tool_call_id from the `task` call that spawned this child. */
    toolCallId: string;
    /** Catalog key (e.g. `general`, `workbook_reader`). */
    subagentType: string;
    /** LLM-chosen tab label. */
    subagentName: string;
    /** Effective child model id selected by the task tool, when known. */
    subagentModel?: string;
    /** Effective child thinking level selected by the task tool, when known. */
    subagentThinkingLevel?: string;
    /** Raw child `AgentLoopEvent` from the embedded runtime's owned AI loop. */
    event: AgentLoopEvent;
}
/** Single source of truth for the (toolCallId, subagentType, subagentName, event) emitter. */
export interface ChildAgentEventMetadata {
    readonly model?: string;
    readonly thinkingLevel?: string;
}
export type ChildAgentEventEmitter = (toolCallId: string, subagentType: string, subagentName: string, event: AgentLoopEvent, metadata?: ChildAgentEventMetadata) => void;
export type AgentEvent = AgentChildLoopEvent | AgentHostToolRequestEvent | AgentHostToolResultAppliedEvent | AgentConfigurationUpdatedEvent | AgentFatalErrorEvent | AgentFollowupSuggestionsStartedEvent | AgentFollowupSuggestionsReadyEvent | AgentFollowupSuggestionsFailedEvent | AgentMainMessageStreamEvent | AgentRunStatsUpdatedEvent | AgentSessionContextUpdatedEvent | AgentSnapshotUpdatedEvent | AgentTelemetryEvent;
export type AgentEventListener = (event: AgentEvent) => void;
export interface EmbeddedAgentRuntime {
    abort(): Promise<void>;
    configure(configuration: AgentConfiguration): Promise<void>;
    dispose(): void;
    getSnapshot(): AgentSnapshot;
    resumeWithHostToolResult(result: HostToolResult): Promise<void>;
    submit(prompt: string, options?: AgentSubmitOptions): Promise<void>;
    subscribe(listener: AgentEventListener): () => void;
}
/** Project an AgentEvent into a structured-clone-safe form using the provided tool registry. */
export declare function toStructuredCloneSafeAgentEvent(event: AgentEvent, registry: ToolRegistry): AgentEvent;
/** Type guard for the wire-level `AgentConfiguration` shape. */
export declare function isAgentConfiguration(value: unknown): value is AgentConfiguration;
/** Type guard validating any AgentCommand variant received from the host. */
export declare function isAgentCommand(value: unknown): value is AgentCommand;
/** Type guard for a RuntimeErrorInfo payload carried on fatal-error events. */
export declare function isRuntimeErrorInfo(value: unknown): value is RuntimeErrorInfo;
/** Type guard validating any AgentEvent variant arriving cross-process. */
export declare function isAgentEvent(value: unknown, registry: ToolRegistry): value is AgentEvent;
//# sourceMappingURL=agent-api.d.ts.map