import { AgentContract } from "../contracts/agent/agent.contract.mjs";
import { ModelCallOptions, ModelContract } from "../contracts/model.contract.mjs";
import { Placeholders } from "../contracts/placeholders.type.mjs";
import { SystemPromptContract } from "../contracts/system-prompt.contract.mjs";
import { SupervisorIntentValue } from "../contracts/supervisor/intent-entry.type.mjs";
import { Next } from "../contracts/supervisor/next.type.mjs";
import { AgentEventHandlers } from "../agent/agent-config.type.mjs";

//#region ../ai/src/supervisor/router-factory.d.ts
/**
 * Output shape every router agent produced by {@link router} emits —
 * the canonical `{ next, reasoning }` contract the supervisor's
 * dispatch loop reads. Exposed so callers can type a router result
 * they handle directly.
 */
type RouterOutput = {
  /** Chosen intent name, a fan-out array, or the `END` sentinel. */next: Next; /** One-sentence justification for the routing choice. */
  reasoning: string;
};
/**
 * Description source for one intent the router can pick from. Accepts
 * the same value-shapes the supervisor's `intents` map does (bare
 * agent / workflow / callback / object entry) so a caller can pass the
 * very same `intents` object to both `router()` and `ai.supervisor()`.
 *
 * The router only needs each intent's NAME (the map key) and a
 * human-readable DESCRIPTION — it never dispatches anything itself, so
 * the underlying unit is read for its `description` only.
 */
type RouterIntents = Record<string, SupervisorIntentValue>;
/**
 * Config for {@link router}. Mirrors the relevant slice of `AgentConfig`
 * — the router IS an agent — plus the `intents` map it routes over.
 *
 * Everything except `model` and `intents` is optional; the helper
 * generates the output schema and the routing system prompt for you.
 */
type RouterConfig = {
  /**
   * Stable identifier for the router agent. Defaults to
   * `"<supervisor-ish>-router"` is NOT assumed — when omitted the helper
   * uses `"router"` so the agent carries a meaningful (non-anonymous)
   * name, which `ai.supervisor({ router })` is happy to accept.
   */
  name?: string; /** The routing LLM. Required — a router with no model can't decide. */
  model: ModelContract;
  /**
   * The intents the router chooses among. Same object you pass to
   * `ai.supervisor({ intents })`. Their descriptions are rendered into
   * the generated routing system prompt so the LLM knows what each
   * option does.
   */
  intents: RouterIntents;
  /**
   * Extra guidance prepended to the framework-generated routing system
   * prompt. Use it for domain framing ("You coordinate a support
   * team."); the mechanical "here are your options, emit `next`"
   * scaffolding is appended automatically.
   */
  systemPrompt?: SystemPromptContract | string; /** Placeholder values merged into the router's system prompt template. */
  placeholders?: Placeholders; /** Base model call options forwarded to the underlying agent. */
  modelOptions?: ModelCallOptions;
  /**
   * Hard cap on LLM trips for the router agent. A router is a
   * single-shot decision maker, so this defaults to `1` — override
   * only if the router itself calls tools mid-decision.
   */
  maxTrips?: number; /** Factory-level event handlers forwarded to the underlying agent. */
  on?: AgentEventHandlers;
};
/**
 * Build a routing agent for `ai.supervisor({ router })` without
 * hand-writing the output schema or the "pick one of these intents"
 * system prompt.
 *
 * **What it does for you.**
 * - Generates the canonical `{ next, reasoning }` output schema
 *   (baked onto the agent so it's a valid router standalone, and
 *   identical to what the supervisor injects per-turn) — the model is
 *   steered to emit a single intent name or the `END` sentinel.
 * - Auto-builds a system prompt that lists every intent + its
 *   description + the reserved `END` value + terse routing rules, with
 *   any caller-supplied `systemPrompt` framing kept on top.
 *
 * The result is a plain {@link AgentContract}; pass it straight to
 * `ai.supervisor({ router: ... })`. Because the supervisor also injects
 * the same schema per-turn and prepends its own per-turn context
 * message, the baked schema/prompt are belt-and-suspenders — they make
 * the agent a correct router even when invoked directly.
 *
 * @example
 * const intents = { triage, orderLookup, billingLookup, resolver };
 *
 * const supportRouter = ai.router({
 *   model,
 *   intents,
 *   systemPrompt: "You coordinate a customer-support team.",
 * });
 *
 * const support = ai.supervisor({
 *   name: "customer-support",
 *   router: supportRouter,
 *   intents,
 *   maxIterations: 6,
 * });
 */
declare function router(config: RouterConfig): AgentContract<RouterOutput>;
//#endregion
export { RouterConfig, RouterIntents, RouterOutput, router };
//# sourceMappingURL=router-factory.d.mts.map