import type { CachePolicy, ChatFallback, ChatInputDuringExecutionMode, ChatMessage, ChatToolChoice, ChatToolDefinition, ChatToolHandlers } from '@genesislcap/foundation-ai';
export type { CachePolicy, ChatFallback, ChatInputDuringExecutionMode, ChatToolChoice };
/**
 * Context passed to `onActivate` / `onDeactivate` lifecycle hooks on an agent.
 *
 * @beta
 */
export interface AgentLifecycleContext {
    /** The agent the hook is firing for. */
    agentName: string;
    /** The assistant session key — stable across reloads, unique per assistant instance. */
    sessionKey: string;
    /** The agent that was active immediately before this one, if any. Only set on `onActivate`. */
    previousAgentName?: string;
    /** Aborted if the session disconnects mid-activation. */
    signal: AbortSignal;
    /**
     * A previously-serialized state image for this agent (from the agent's
     * `serialize`), passed only on `onActivate` when resuming a persisted
     * session. A stateful
     * agent's `init` rebuilds from it — e.g. via `restoreMachine` — or starts
     * fresh when it is `undefined`.
     */
    restored?: unknown;
}
/**
 * Context passed to an agent's `resumable` predicate (GENC-1351 §5.9), evaluated
 * at session-save time on the active agent (which, for a locked guided flow, is
 * the flow-owner).
 *
 * @beta
 */
export interface AgentPersistenceContext {
    /** The agent being consulted. */
    agentName: string;
    /** The assistant session key — stable across reloads. */
    sessionKey: string;
    /**
     * This agent's just-serialized state image — the value its `serialize()`
     * returned for this save (or the carried-forward image). Inspect the machine
     * step here. Derive the decision from this (not live closure state): the
     * predicate must be a pure function of the state so a resumable snapshot stays
     * resumable when re-evaluated on restore.
     */
    state: unknown;
    /** Full conversation transcript at save time. */
    messages: ReadonlyArray<ChatMessage>;
    /** True when this agent currently owns the guided flow (`name === flowOwnerAgentName`). */
    isFlowOwner: boolean;
}
/**
 * Context passed to the function form of `systemPrompt` / `toolDefinitions`.
 * Resolved each tool-loop iteration so the agent can vary what the LLM sees per turn.
 *
 * @beta
 */
export interface SystemPromptContext {
    /** The active agent's name. */
    agentName: string;
    /** Full conversation history up to (but not including) the message being processed. */
    history: ReadonlyArray<ChatMessage>;
    /** 0 = first LLM call this turn; > 0 = retry or subsequent tool-loop iteration. */
    turnIndex: number;
    /** Aborted if the turn is cancelled. */
    signal: AbortSignal;
}
/**
 * System prompt for an agent. Either a static string (resolved once) or a function
 * resolved each tool-loop iteration. The function form lets the agent compute the
 * prompt from external state — e.g. a state machine's current step.
 *
 * @beta
 */
export type SystemPromptInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
/**
 * Tool definitions for an agent. Either a static array (the conventional shape) or
 * a function resolved each tool-loop iteration. The function form lets the agent
 * narrow the tool surface per turn — e.g. expose only the tools valid in the
 * current state of a state machine.
 *
 * @beta
 */
export type ToolDefinitionsInput = ChatToolDefinition[] | ((ctx: SystemPromptContext) => ChatToolDefinition[] | Promise<ChatToolDefinition[]>);
/**
 * Tool handlers for an agent. Either a static map (the conventional shape) or a
 * function resolved each tool-loop iteration. The function form lets the agent
 * narrow the dispatchable handler set per turn — pair it with the function form
 * of `toolDefinitions` so the LLM-visible tools and the dispatchable handlers
 * stay in lockstep, and handlers don't have to defend themselves against being
 * dispatched in states where their tool isn't advertised.
 *
 * @beta
 */
export type ToolHandlersInput = ChatToolHandlers | ((ctx: SystemPromptContext) => ChatToolHandlers | Promise<ChatToolHandlers>);
/**
 * Names which registered `AIProviderRegistry` entry an agent uses. Either
 * a static string (resolved once at agent registration) or a function resolved
 * each tool-loop iteration — pick the function form to vary the provider by
 * current state (e.g. a stateful agent that switches providers between
 * machine states).
 *
 * Unknown provider names hard-error: static names at agent registration time,
 * function-resolved names on first resolution.
 *
 * @beta
 */
export type ProviderInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
/**
 * Sampling temperature for an agent, normalized to `0`–`1` (`0` = deterministic,
 * `1` = the most random the active provider allows). Either a static number
 * (resolved once) or a function resolved each tool-loop iteration — pick the
 * function form to vary it by current state (e.g. a lower temperature for a
 * precise extraction step, higher for brainstorming). Each transport translates
 * the normalized value into its own native range. Omit to use the
 * provider/model default. See `ChatRequestOptions.temperature`.
 *
 * @beta
 */
export type TemperatureInput = number | ((ctx: SystemPromptContext) => number | Promise<number>);
/**
 * Tool-call mode for an agent. Either a static `ChatToolChoice` (resolved
 * once) or a function resolved each tool-loop iteration — pick the function form
 * to vary it by current state (e.g. force a classifier tool in an intake step,
 * then `'auto'` everywhere multi-step work happens). Omit to use the default
 * (`'auto'`, except sub-agent turns which force `'required'`).
 *
 * @beta
 */
export type ToolChoiceInput = ChatToolChoice | ((ctx: SystemPromptContext) => ChatToolChoice | Promise<ChatToolChoice>);
/**
 * Prompt-cache policy for an agent. Either a static `CachePolicy` (resolved once) or a
 * function resolved each tool-loop iteration — pick the function form to vary it by current state
 * (e.g. cache `'history'` in a long generating phase, `'default'` in short low-touch ones). Omit
 * to request no caching. Resolved and applied the same way as {@link TemperatureInput}.
 *
 * @beta
 */
export type CachePolicyInput = CachePolicy | ((ctx: SystemPromptContext) => CachePolicy | Promise<CachePolicy>);
/**
 * Per-turn tail context for an agent — volatile content (current file/spec, diagnostics, live
 * state) injected at the tail of every model-call so the model sees it without invalidating the
 * cached prefix. Either a static string or a function resolved each tool-loop iteration. **Provide
 * raw content** — the framework frames it (wraps it in a `<system-reminder>` marker) so the model
 * reads it as ambient context, not user input. Omit, or return an empty string, for none.
 *
 * @beta
 */
export type TailContextInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
/**
 * Structured-output schema for an agent. When set, the model's final (non-tool) answer is
 * constrained to this JSON Schema instead of free text. Either a static schema or a function
 * resolved each tool-loop iteration — return the schema on the turn(s) it should apply and
 * `undefined` otherwise, so "whole-loop" vs "finalize-turn" enforcement is just what the
 * resolver returns (e.g. `({ state }) => state.machine.matches('finalizing') ? schema : undefined`).
 *
 * Orthogonal to {@link ToolChoiceInput}: an agent can carry both `tools` and a `responseSchema`.
 * Each provider applies it natively where possible (Anthropic `output_config.format`, Gemini
 * JSON mode) and degrades gracefully otherwise. The schema is a plain JSON Schema object; keep to
 * the portable subset providers share (`additionalProperties: false`, explicit `required`, enums,
 * `anyOf` for nullables — no numeric/string constraints or recursion).
 *
 * @beta
 */
export type ResponseSchemaInput = object | ((ctx: SystemPromptContext) => object | undefined | Promise<object | undefined>);
/**
 * Context passed to an agent's `onUnresolvedTool` hook when the model calls a
 * tool the driver cannot dispatch.
 *
 * @beta
 */
export interface UnresolvedToolContext {
    /** The tool name the model attempted to call. */
    toolName: string;
    /**
     * Why the call could not be dispatched:
     * - `'stale'` — the tool was advertised earlier this activation but is not
     *   part of the current step (e.g. a stateful agent has moved on).
     * - `'unknown'` — the tool was never advertised this activation (a
     *   hallucinated name).
     */
    kind: 'stale' | 'unknown';
    /**
     * The tool names dispatchable right now, so the hook can steer the model
     * back to a valid call.
     */
    availableTools: string[];
}
/**
 * Optional per-agent hook consulted only on the already-failing unresolved-tool
 * path — when the model calls a tool the driver cannot dispatch. Lets the agent
 * replace the framework's default message with a context-aware redirect.
 *
 * Return a non-empty string to override the default tool-result message; return
 * `undefined` (or an empty/whitespace string, or throw) to fall back to the
 * framework default. The happy path is never affected. See
 * {@link UnresolvedToolContext}.
 *
 * @beta
 */
export type UnresolvedToolInput = (ctx: UnresolvedToolContext) => string | undefined | Promise<string | undefined>;
/**
 * Opts an agent in to manual selection from the assistant's agent picker.
 *
 * Only applies to top-level agents — sub-agents are never user-selectable.
 * Has no effect unless the assistant's `agentPicker` is also enabled.
 *
 * @beta
 */
export interface ManualSelectionConfig {
    /**
     * Whether this agent appears in the picker.
     */
    enabled: boolean;
    /**
     * Optional short description shown as a tooltip on the picker entry, and as
     * a secondary line in the dropdown variant.
     */
    hint?: string;
}
interface BaseAgentConfig {
    /**
     * Stable identity for this agent. Used for classifier routing, manual
     * pinning, and history filtering — must not vary per turn. For a per-turn
     * display label (e.g. "Guided Booking (Counterparties)"), supply
     * {@link BaseAgentConfig.displayName}.
     */
    name: string;
    /**
     * Optional per-turn display label. Resolved each tool-loop iteration and
     * stamped onto outgoing messages (`agentLabel`) and the debug-log timeline.
     * Renderers fall back to `name` when this is unset. Use the function form
     * to vary the label by current state (e.g. a state machine's step).
     *
     * Identity stays on `name` — this is for UX only.
     */
    displayName?: SystemPromptInput;
    /**
     * System prompt injected into every conversation turn for this agent.
     *
     * Either a string (resolved once) or a function resolved each tool-loop
     * iteration — pick the function form when the prompt depends on per-turn state
     * (e.g. a state machine's current step). See {@link SystemPromptInput}.
     */
    systemPrompt?: SystemPromptInput;
    /**
     * Tool definitions (JSON Schema) passed to the AI provider for this agent.
     *
     * Either a static array or a function resolved each tool-loop iteration —
     * pick the function form to narrow the tool surface per turn (e.g. expose
     * only the tools valid in the current state of a state machine).
     * See {@link ToolDefinitionsInput}.
     */
    toolDefinitions?: ToolDefinitionsInput;
    /**
     * Tool handler implementations for this agent.
     *
     * Either a static map or a function resolved each tool-loop iteration —
     * pick the function form to narrow the dispatchable handler set per turn,
     * matching the function form of `toolDefinitions`.
     * See {@link ToolHandlersInput}.
     */
    toolHandlers?: ToolHandlersInput;
    /**
     * Which registered AI provider this agent uses, by name. Either a static
     * string (resolved once at agent registration) or a function resolved each
     * tool-loop iteration — pick the function form to vary the provider by
     * current state (e.g. a stateful agent that switches providers between
     * machine states).
     *
     * Omit to use the registry's default provider. Unknown names hard-error:
     * static names at registration time, function-resolved names on first
     * resolution.
     *
     * Known limitation: switching provider mid-conversation can blow the
     * smaller provider's context window if history accumulated under a
     * larger one. No automatic trimming is performed.
     *
     * @beta
     */
    provider?: ProviderInput;
    /**
     * Sampling temperature for this agent, normalized to `0`–`1`. Either a static
     * number or a function resolved each tool-loop iteration — pick the function
     * form to vary it by current state. Omit to use the provider/model default.
     * Resolved and applied the same way as {@link BaseAgentConfig.provider}.
     * See {@link TemperatureInput}.
     *
     * @beta
     */
    temperature?: TemperatureInput;
    /**
     * Tool-call mode for this agent — whether the model may, must, or must not
     * call a tool this turn (and optionally which one). Either a static value or
     * a function resolved each tool-loop iteration — pick the function form to
     * vary it by current state (e.g. force a single tool at a known juncture).
     * Omit to use the default (`'auto'`, except sub-agent turns which force
     * `'required'`). See {@link ToolChoiceInput}.
     *
     * @beta
     */
    toolChoice?: ToolChoiceInput;
    /**
     * Prompt-cache policy for this agent — whether to emit cache breakpoints and how far up the
     * prefix. Either a static value or a function resolved each tool-loop iteration (vary by state).
     * Resolved and applied the same way as {@link BaseAgentConfig.temperature}. Omit to request no
     * caching. Provider-neutral — see {@link CachePolicyInput} / `CachePolicy` for the
     * Anthropic-vs-Gemini behaviour. See {@link CachePolicyInput}.
     *
     * @beta
     */
    cachePolicy?: CachePolicyInput;
    /**
     * Volatile per-turn context injected at the tail of every model-call (after the history and any
     * cache breakpoint), so it is seen each turn without busting the cached prefix — the place to put
     * the changing parts (current file/spec, diagnostics, live state) that would otherwise
     * destabilize a cached system prompt. Provide *raw* content; the framework frames it (wraps it in
     * a `<system-reminder>` marker). Resolved per turn like {@link BaseAgentConfig.temperature}. See
     * {@link TailContextInput}.
     *
     * @beta
     */
    tailContext?: TailContextInput;
    /**
     * Structured-output schema for this agent. When resolved to a schema on a turn, the model's
     * final (non-tool) answer is constrained to it instead of free text. Composes with `tools`;
     * resolved per turn like {@link BaseAgentConfig.cachePolicy}, so returning `undefined` on
     * working turns and the schema on the finalize turn gives finalize-turn enforcement for free.
     * See {@link ResponseSchemaInput}.
     *
     * @beta
     */
    responseSchema?: ResponseSchemaInput;
    /**
     * Refusal-fallback chain for this agent (provider-neutral). If the model declines a turn
     * (`stop_reason: 'refusal'` — e.g. Fable 5 safety classifiers), the provider re-runs it on the
     * next listed model. Typical use: a Fable 5 agent with `[{ model: 'claude-opus-4-8' }]`. Static
     * (not per-turn); providers that support it apply it server-side, others ignore it.
     *
     * @beta
     */
    fallbacks?: ChatFallback[];
    /**
     * Optional hook consulted when the model calls a tool the driver cannot
     * dispatch — either a *stale* tool (advertised earlier this activation but
     * not part of the current step) or an *unknown* one (never advertised this
     * activation). Return a context-aware redirect string to replace the
     * framework's default message, or `undefined` to keep it. Consulted only on
     * the already-failing unresolved-tool path; the happy path is unaffected.
     * See {@link UnresolvedToolInput}.
     *
     * @beta
     */
    onUnresolvedTool?: UnresolvedToolInput;
    /**
     * Optional primer history prepended to every call (not visible to the user).
     * Used to establish agent identity and behavioural rules.
     */
    primerHistory?: ChatMessage[];
    /**
     * Sub-agents available to this agent's tool handlers via `requestSubAgent`.
     */
    subAgents?: AgentConfig[];
    /**
     * How the main chat input area behaves while this agent is executing.
     * Defaults to `'disabled'`. See {@link ChatInputDuringExecutionMode}.
     */
    chatInputDuringExecution?: ChatInputDuringExecutionMode;
    /**
     * Opts this agent in to manual selection from the assistant's agent picker.
     * Has no effect on sub-agents or when the assistant's `agentPicker` is
     * disabled. See {@link ManualSelectionConfig}.
     */
    manualSelection?: ManualSelectionConfig;
    /**
     * Fires when this agent becomes the active specialist (including being pinned).
     * Use to instantiate per-agent state that should outlive a single turn — e.g.
     * a state machine the agent owns across the conversation. Awaited before the
     * agent's first turn runs.
     *
     * Capture dependencies (services, redux store refs, etc.) via closure on the
     * host element rather than expecting them on the context.
     *
     * @beta
     */
    onActivate?: (ctx: AgentLifecycleContext) => void | Promise<void>;
    /**
     * Fires when this agent is being deactivated (the user switches to another
     * agent, the session is torn down, or the agent is unpinned and replaced).
     * Use to dispose per-agent state created in `onActivate`. Awaited before the
     * incoming agent's `onActivate` runs.
     *
     * @beta
     */
    onDeactivate?: (ctx: AgentLifecycleContext) => void | Promise<void>;
    /**
     * Returns an agent-supplied debug payload for the export log. Called once per
     * LLM call by the driver (alongside the resolved prompt and tool list) and
     * once at log-export time for the latest snapshot. Stateful agents should
     * return their machine state and captured context so the exported timeline
     * captures what drove each turn.
     *
     * Return value must be JSON-serializable. {@link defineStatefulAgent} wires a
     * sensible default that snapshots any machine-shaped state automatically.
     *
     * @beta
     */
    getDebugSnapshot?: () => unknown;
    /**
     * Returns a lossless, JSON-serializable image of the agent's state for session
     * persistence — distinct from `getDebugSnapshot`, which may abbreviate for
     * readability. Pass the value back to the agent on restore (as
     * `ctx.restored` in its `init`) to resume. {@link defineStatefulAgent} wires a
     * default that snapshots any machine-shaped state via `getPersistedSnapshot()`
     * and returns plain state as-is.
     *
     * @beta
     */
    serialize?: () => unknown;
    /**
     * Whether the agent's current state is resumable — i.e. worth persisting so the
     * session can be restored mid-flow (GENC-1351 §5.9). Consulted at save time on
     * the active agent (the flow-owner during a locked flow). Return `true`
     * (or leave the field absent) to persist and resume normally; return `false`
     * for a point that shouldn't be resumed — the session is not persisted, and on
     * return the assistant shows {@link AgentConfig.notResumableMessage} (or a
     * default) and pre-fills the composer with the prompt that started the flow so
     * the user can re-run it.
     *
     * Only consulted when the user has persistence enabled. Must be a **pure
     * function of `ctx.state`** — it may be re-evaluated on a restored snapshot, so
     * a resumable state must stay resumable. A thrown error is treated as `true`
     * (fail-safe: never drop a resumable chat on a predicate bug).
     *
     * @beta
     */
    resumable?: (ctx: AgentPersistenceContext) => boolean | Promise<boolean>;
    /**
     * Message shown on return when {@link AgentConfig.resumable} returned `false`
     * and the user comes back to a non-resumable session (GENC-1351 §5.9). Falls
     * back to a built-in default when omitted.
     *
     * @beta
     */
    notResumableMessage?: string;
}
/**
 * Configuration for a specialist agent.
 *
 * Specialist agents are offered to the classifier for intent routing. The
 * `description` is used to auto-generate the classifier prompt — no manual
 * routing prompt authoring required.
 *
 * @beta
 */
export interface SpecialistAgentConfig extends BaseAgentConfig {
    /**
     * Plain-language description of what this agent handles.
     * Used by the classifier to auto-generate its routing prompt.
     */
    description: string;
    fallback?: never;
    /**
     * When `true`, the classifier never auto-routes to this agent. The user can
     * still select it manually via the picker, provided both prerequisites are
     * met: this agent has `manualSelection.enabled` set to `true`, *and* the
     * assistant has the picker enabled via `chatConfig.picker.mode`.
     *
     * Use this for agents that overlap heavily with a sibling (e.g. a guided
     * wizard sitting next to a free-form agent in the same domain) and should
     * only be reached intentionally rather than via classifier routing.
     *
     * @beta
     */
    excludeFromClassifier?: boolean;
}
/**
 * Configuration for a fallback agent.
 *
 * Invoked when the classifier returns no match. Excluded from the classifier
 * prompt. Only one fallback is permitted per agents array.
 *
 * @beta
 */
export interface FallbackAgentConfig extends BaseAgentConfig {
    /**
     * Marks this agent as the fallback for unrecognised requests.
     */
    fallback: true;
    description?: never;
}
/**
 * Configuration for an agent passed to `FoundationAiAssistant`.
 *
 * Either a specialist (requires `description`) or a fallback (requires
 * `fallback: true`). Passing both or neither is a compile error.
 *
 * @beta
 */
export type AgentConfig = SpecialistAgentConfig | FallbackAgentConfig;
/**
 * Identity helper that infers the narrowest possible type for an agent config,
 * preserving string literal types (including `name`) without requiring `as const`.
 *
 * Use this when you need `typeof myAgent` to carry the literal `name` type —
 * for example, when wiring `ChatToolHandlers<typeof myAgent>`.
 *
 * ```ts
 * const myAgent = defineAgent({ name: 'my_agent', ... });
 * type Handlers = ChatToolHandlers<typeof myAgent>;
 * // requestSubAgent name param is now typed as 'my_agent'
 * ```
 *
 * @beta
 */
export declare function defineAgent<const T extends AgentConfig>(config: T): T;
//# sourceMappingURL=config.d.ts.map