@wildo-ai/external-connectors-models 1.0.1 → 1.1.0

package/dist/esm/protocols/llm.external-connectors-models.schemas.d.ts

@@ -1,29 +1,37 @@
 import { z } from "zod";
-import { ExternalProvider_ExchangeProtocol_Configuration_Base, ExternalProvider_ExchangeProtocol_Kind, ExternalProvider_ExchangeProtocol_Profile_Base } from "../core/commons.external-connectors-models.schemas.js";
-import { ExternalProvider_OperationDefinition_Base } from "../core/operations.external-connectors-models.schemas.js";
-import { CLIRuntime_OutputParserMode, CLIRuntime_RunnerHost } from "./cli-runtime.external-connectors-models.schemas.js";
+import { ExternalProvider_ExchangeProtocol_Configuration_Base, ExternalProvider_ExchangeProtocol_Kind, ExternalProvider_ExchangeProtocol_Profile_Base } from "../core/commons.external-connectors-models.schemas";
+import { ExternalProvider_OperationDefinition_Base } from "../core/operations.external-connectors-models.schemas";
 export declare enum LLM_Model {
     OPEN_AI_O1 = "o1",
     OPEN_AI_O1_MINI = "o1-mini",
     OPEN_AI_O3_MINI = "o3-mini",
     OPEN_AI_O4_MINI = "o4-mini",
+    /** GPT-5.6 frontier flagship tier. */
+    OPEN_AI_GPT_5_6_SOL = "gpt-5.6-sol",
+    /** GPT-5.6 balanced tier for everyday work. */
+    OPEN_AI_GPT_5_6_TERRA = "gpt-5.6-terra",
+    /** GPT-5.6 fast/affordable tier. */
+    OPEN_AI_GPT_5_6_LUNA = "gpt-5.6-luna",
+    /** Dec-2025 flagship (accepts `temperature`, unlike the 5.6 family). */
+    OPEN_AI_GPT_5_2 = "gpt-5.2",
+    /** Extended-reasoning 5.2 variant. */
+    OPEN_AI_GPT_5_2_PRO = "gpt-5.2-pro",
+    OPEN_AI_GPT_5_1 = "gpt-5.1",
     OPEN_AI_GPT_5 = "gpt-5",
-    OPEN_AI_GPT_5_1_INSTANT = "gpt-5.1-instant",
-    OPEN_AI_GPT_5_1_THINKING = "gpt-5.1-thinking",
+    OPEN_AI_GPT_5_MINI = "gpt-5-mini",
     OPEN_AI_GPT_4O = "gpt-4o",
     OPEN_AI_GPT_4O_MINI = "gpt-4o-mini",
     OPEN_AI_GPT_4_TURBO = "gpt-4-turbo",
     OPEN_AI_GPT_4 = "gpt-4",
     OPEN_AI_GPT_3_5_TURBO = "gpt-3.5-turbo",
-    CLAUDE_4_OPUS = "claude-4-opus",
+    /** Anthropic's most intelligent generally-available model (Claude 5 family, Mythos-class tier). */
+    CLAUDE_FABLE_5 = "claude-fable-5",
+    /** Claude 5 family workhorse. */
+    CLAUDE_SONNET_5 = "claude-sonnet-5",
+    /** Latest Opus-tier model (4.x line). */
+    CLAUDE_OPUS_4_8 = "claude-opus-4-8",
     CLAUDE_SONNET_4_5 = "claude-sonnet-4-5",
     CLAUDE_HAIKU_4_5 = "claude-haiku-4-5",
-    CLAUDE_3_7_SONNET = "claude-3-7-sonnet",
-    CLAUDE_3_5_SONNET = "claude-3-5-sonnet-20241022",
-    CLAUDE_3_5_HAIKU = "claude-3-5-haiku-20241022",
-    CLAUDE_3_OPUS = "claude-3-opus-20240229",
-    CLAUDE_3_SONNET = "claude-3-sonnet-20240229",
-    CLAUDE_3_HAIKU = "claude-3-haiku-20240307",
     GOOGLE_GEMINI_3_DEEP_THINK = "gemini-3-deep-think",
     GOOGLE_GEMINI_3_PRO = "gemini-3-pro",
     GOOGLE_GEMINI_2_5_PRO = "gemini-2.5-pro",
@@ -59,9 +67,30 @@ export declare enum LLM_Model_IO_Capability {
     LONG_CONTEXT = "long_context",
     CODE_GENERATION = "code_generation"
 }
+/**
+ * Whether a model can think, and whether that thinking can be turned OFF.
+ *
+ * This is the MODEL-PROPERTY axis of reasoning. It answers "what is this model
+ * capable of", never "how hard should this call think" — the latter is
+ * {@link LLMProvider_ReasoningEffort}, a per-call parameter. Keeping the two
+ * apart is deliberate: a capability is a fact about the model, an effort is a
+ * choice by the author. (The six `*_THINKING` operation keys that once encoded
+ * this as a third axis were retired on 2026-07-17.)
+ *
+ * Consumed by {@link LLM_MODEL_THINKING_CAPABILITY} +
+ * {@link validateReasoningEffortForModel} to reject impossible
+ * model × effort pairs at authoring time instead of as a provider 400.
+ */
 export declare enum LLM_Model_Thinking_Capability {
-    NONE = "none",// Model does not support thinking/reasoning mode
-    OPTIONAL = "optional",// Model supports optional thinking mode (can enable/disable)
+    /** Not a reasoning model — it cannot think, so NO `reasoningEffort` is valid. */
+    NONE = "none",
+    /** Thinking can be enabled AND disabled — every effort level is valid, incl. `NONE`. */
+    OPTIONAL = "optional",
+    /**
+     * The model ALWAYS reasons and thinking CANNOT be disabled (o-series,
+     * Claude 5). Every effort is valid EXCEPT `NONE` — asking such a model not to
+     * think is a provider error, not a preference.
+     */
     ALWAYS = "always"
 }
 export declare enum LLM_Model_Availability {
@@ -71,20 +100,126 @@ export declare enum LLM_Model_Availability {
     DEPRECATED = "deprecated",// Still available but deprecated
     DISCONTINUED = "discontinued"
 }
+/**
+ * WHAT A MODEL IS CHOSEN FOR — the durable axis of model selection.
+ *
+ * Concrete model ids churn monthly; the kinds of work a model is selected for
+ * do not. This enum is therefore the surface an AUTHOR names
+ * (`config.modelApplicability`), while the concrete id is resolved by the
+ * framework from {@link LLM_MODEL_CATALOG} +
+ * {@link LLM_MODEL_APPLICABILITY_PREFERENCE}. A model launch becomes one
+ * catalog row and one preference edit, with no agent definition touched.
+ *
+ * Members name the WORK, never the model's SIZE or a vendor tier. A tier
+ * ("mini", "pro", "Sol/Terra/Luna", "Opus/Sonnet/Haiku") is a property of one
+ * vendor's line-up — it renames (GPT-5.6 already did), it differs per provider,
+ * and it still never says what to choose it FOR.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ */
+export declare enum LLM_Model_Applicability {
+    /**
+     * High-stakes semantic judgment where being wrong is expensive and the answer
+     * is read by a human or gates a durable decision — critique, deliberation,
+     * persona derivation, acceptance judgment.
+     *
+     * Choose it when: cost and latency are worth trading for quality, the input is
+     * ambiguous, and there is no mechanical check downstream that would catch a
+     * poor answer.
+     * Do NOT choose it for: volume work, or anything a schema already constrains.
+     */
+    DEEP_JUDGMENT = "deep_judgment",
+    /**
+     * Everyday generation of application artifacts against a declared schema —
+     * structured output, copy, plans, summaries.
+     *
+     * Choose it when: the shape is constrained by a schema or a template, quality
+     * matters but the task is bounded, and the call happens tens of times rather
+     * than thousands. This is the correct default when no other member obviously
+     * fits.
+     */
+    STRUCTURED_AUTHORING = "structured_authoring",
+    /**
+     * High-volume, low-judgment transformation — labelling, translation,
+     * extraction, reformatting, classification against a fixed vocabulary.
+     *
+     * Choose it when: the same call runs hundreds or thousands of times, the
+     * answer is checkable, and unit cost dominates quality. The trade is
+     * deliberate: paying a judgment-tier price per label is the failure this
+     * member exists to prevent.
+     */
+    HIGH_VOLUME_MECHANICAL = "high_volume_mechanical",
+    /**
+     * Work whose binding constraint is how much material must be in ONE call —
+     * whole-corpus analysis, cross-document reconciliation, large-codebase
+     * reading.
+     *
+     * Choose it when: chunking would destroy the semantics (the answer depends on
+     * relating parts that must be seen together). If the work chunks cleanly,
+     * choose by judgment level instead and let the caller chunk.
+     */
+    LONG_CONTEXT_ANALYSIS = "long_context_analysis",
+    /**
+     * Judgment that requires SEEING an artifact — logo/brand assessment, rendered
+     * layout review, screenshot triage.
+     *
+     * Choose it when: the input is an image and the output is an assessment of it.
+     * Resolution refuses any model whose catalog row does not evidence
+     * {@link LLM_Model_IO_Capability.MULTIMODAL_VISION}, so an unverified model is
+     * never silently selected for vision work.
+     */
+    VISUAL_JUDGMENT = "visual_judgment",
+    /**
+     * Autonomous, workspace-mutating code authoring driven through a coding-agent
+     * CLI rather than a chat API.
+     *
+     * Choose it when: the agent edits files in a trusted workspace and needs long
+     * tool-using turns. This member is transport-bound — it is only serviceable
+     * on a provider that declares an `AGENT_CLIENT_PROTOCOL` transport, so resolving it never
+     * silently downgrades workspace work to a chat call that can only describe an
+     * edit.
+     */
+    WORKSPACE_CODING_AGENT = "workspace_coding_agent"
+}
+/** @wildo_source:part:start saas.external-providers.llm.operation-key facet:kind:api facet:audience:app-developer
+ *
+ * The LLM operation vocabulary — WHAT a call does, never HOW HARD it thinks.
+ *
+ * This is the key you put on an agent's `config.operationKey`. It selects the
+ * executor, and with it BOTH the invocation `input` shape you must supply and
+ * the `output` shape you get back:
+ *
+ * | Operation key         | `invocation.input`            | `invocation.output` |
+ * |-----------------------|-------------------------------|---------------------|
+ * | `GENERATE_TEXT`       | `{ prompt }`                  | `{ text }`          |
+ * | `GENERATE_STRUCTURED` | `{ prompt, schema }` (Zod)    | `{ object }`        |
+ * | `CHAT_COMPLETION`     | `{ messages }` or `{ prompt }`| `{ message }`       |
+ * | `CHAT_MULTIMODAL`     | `{ prompt, images }`          | `{ message }`       |
+ *
+ * `GENERATE_STRUCTURED` REQUIRES `input.schema`; omitting it is a validation
+ * error, not a silent fallback to text. The `STREAM_*` keys exist for the
+ * conversational runtime — a one-shot caller uses the buffered keys above.
+ *
+ * Import path: `@wildo-ai/external-connectors-models`.
+ *
+ * Reasoning depth is a PARAMETER ({@link LLMProvider_ReasoningEffort} on the
+ * model configuration), not an operation. The six `*_THINKING` op keys that
+ * used to live here were RETIRED (2026-07-17): they were inert at execution
+ * (each routed to the exact same executor as its non-thinking sibling) and,
+ * once `reasoningEffort` landed, they became a SECOND authority axis for the
+ * same concept — two ways to say "think harder", neither carrying its own
+ * semantic weight. A model's ability to reason is a property of the model +
+ * the effort parameter, not a parallel operation surface.
+ */
 export declare enum LLMProvider_OperationKey {
     GENERATE_TEXT = "llm.generateText",
     CHAT_COMPLETION = "llm.chatCompletion",
     STREAM_TEXT = "llm.streamText",
     GENERATE_STRUCTURED = "llm.generateStructured",
     CHAT_MULTIMODAL = "llm.chatMultimodal",
-    STREAM_STRUCTURED = "llm.streamStructured",
-    GENERATE_TEXT_THINKING = "llm.generateText.thinking",
-    CHAT_COMPLETION_THINKING = "llm.chatCompletion.thinking",
-    STREAM_TEXT_THINKING = "llm.streamText.thinking",
-    GENERATE_STRUCTURED_THINKING = "llm.generateStructured.thinking",
-    CHAT_MULTIMODAL_THINKING = "llm.chatMultimodal.thinking",
-    STREAM_STRUCTURED_THINKING = "llm.streamStructured.thinking"
+    STREAM_STRUCTURED = "llm.streamStructured"
 }
+/** @wildo_source:part:end saas.external-providers.llm.operation-key */
 /**
  * Prompt format preference for provider-specific rendering
  * Used by PromptCompilerBackendService to select optimal format
@@ -115,6 +250,249 @@ export declare const LLMProvider_ToolChoice_Schema: z.ZodUnion<readonly [z.ZodLi
     name: z.ZodString;
 }, z.core.$strip>]>;
 export type LLMProvider_ToolChoice = z.infer<typeof LLMProvider_ToolChoice_Schema>;
+/** @wildo_source:part:start saas.external-providers.llm.model-configuration facet:kind:api facet:audience:app-developer
+ *
+ * Reasoning-effort control for reasoning-capable models (GPT-5.6 Sol/Terra/Luna,
+ * OpenAI o-series, Claude 5 thinking, Gemini reasoning, …). The values mirror
+ * the AI SDK 7 top-level `reasoning` option EXACTLY, which the SDK translates to
+ * each provider's native reasoning setting (OpenAI `reasoning_effort`, Anthropic
+ * thinking budget, …). Omit for non-reasoning models or to accept the provider
+ * default.
+ *
+ * Effort ladder (cost/latency ↑ with depth):
+ * - `NONE` — reasoning off; mechanical tasks (extraction, formatting, labelling).
+ * - `MINIMAL` / `LOW` — brief reasoning; simple structured output.
+ * - `MEDIUM` — balanced; most authored generation (market/email copy).
+ * - `HIGH` / `XHIGH` — deep reasoning; judgment work (persona derivation,
+ *   deliberation, logo/quality judges).
+ * - `PROVIDER_DEFAULT` — explicitly defer to the model's own default effort.
+ *
+ * NOT EVERY MODEL SUPPORTS EVERY LEVEL — the SDK forwards the value and the
+ * provider validates it. Support matrix VERIFIED LIVE (2026-07-16/17); pick a
+ * level the target model actually supports:
+ *
+ * | Model family        | Supported                          | Rejected                       |
+ * |---------------------|------------------------------------|--------------------------------|
+ * | OpenAI GPT-5.6      | none, low, medium, high, xhigh     | `minimal`, `max`               |
+ * | Anthropic Claude 5  | low, medium, high, xhigh           | **`none`** — thinking CANNOT   |
+ * | (fable-5, …)        |                                    | be disabled ("thinking.type.   |
+ * |                     |                                    | disabled is not supported…";   |
+ * |                     |                                    | defaults to adaptive)          |
+ *
+ * ⚠️ `NONE` is therefore NOT portable: it turns reasoning off on GPT-5.6 but
+ * ERRORS on Claude 5. `PROVIDER_DEFAULT` as an explicit value is also rejected
+ * by GPT-5.6 — omit the field entirely for the model's default instead.
+ */
+export declare enum LLMProvider_ReasoningEffort {
+    PROVIDER_DEFAULT = "provider-default",
+    NONE = "none",
+    MINIMAL = "minimal",
+    LOW = "low",
+    MEDIUM = "medium",
+    HIGH = "high",
+    XHIGH = "xhigh"
+}
+/** @wildo_source:part:end saas.external-providers.llm.model-configuration */
+/**
+ * One row per model: everything the framework knows about a concrete id.
+ *
+ * The entry deliberately separates TWO kinds of knowledge, because they carry
+ * different burdens of proof and different consequences when wrong:
+ *
+ * **Probed facts** — `availability`, `thinkingCapability`,
+ * `unsupportedReasoningEfforts`, `rejectsExplicitTemperature`. These are
+ * assertions about the provider's API and are populated ONLY from a live probe
+ * (`live-model-smoke.test.ts`, `WILDO_LIVE_MODEL_SMOKE=1`). Absence means
+ * "not yet verified", never "false" — a wrong value here BLOCKS a legal
+ * configuration, so guessing is worse than omitting. Never infer them from
+ * published docs: the docs have already been wrong once (they claimed GPT-5.6
+ * supports `minimal`; the API rejects it).
+ *
+ * **Framework opinion** — `applicabilities`, `ioCapabilities`. These express
+ * what Wildo is willing to SELECT this model for. Being wrong here degrades
+ * quality or cost, it does not make a call illegal, and the remedy is an edit
+ * to one row rather than to every agent definition.
+ */
+export type LLM_ModelCatalogEntry = {
+    /** The `ref` of the provider module that serves this id. */
+    providerRef: string;
+    /**
+     * PROBED. Omitted when this repository has never verified the id against the
+     * provider's live model list. An unverified model is never auto-resolved
+     * ({@link resolveModelForApplicability}); it stays nameable as an explicit
+     * pin, which is the escape hatch for custom and fine-tuned deployments.
+     */
+    availability?: LLM_Model_Availability;
+    /** ISO date of the live verification behind the probed fields. */
+    probedOn?: string;
+    /**
+     * FRAMEWORK OPINION. Which kinds of work this model may be selected for.
+     * Empty means "never auto-selected" — a legal, deliberate state for an id we
+     * keep nameable (legacy, pinned, or recorded in an old trace) but do not want
+     * chosen on an author's behalf.
+     */
+    applicabilities: readonly LLM_Model_Applicability[];
+    /** FRAMEWORK OPINION, except where a probe confirmed it. */
+    ioCapabilities?: readonly LLM_Model_IO_Capability[];
+    /** PROBED. See {@link LLM_Model_Thinking_Capability}. */
+    thinkingCapability?: LLM_Model_Thinking_Capability;
+    /** PROBED. Effort levels this model rejects despite its thinking capability. */
+    unsupportedReasoningEfforts?: readonly LLMProvider_ReasoningEffort[];
+    /** PROBED. `true` when sending any explicit `temperature` is a provider error. */
+    rejectsExplicitTemperature?: boolean;
+};
+/**
+ * THE model catalog — the single per-model fact table.
+ *
+ * It is an EXHAUSTIVE `Record`, not a `Partial`: adding a member to
+ * {@link LLM_Model} without a row here is a compile error. That exhaustiveness
+ * is the entire guarantee. Before this record existed, model knowledge lived in
+ * four parallel partial maps keyed by the same string — a thinking-capability
+ * map, an unsupported-effort map, a pricing table and a capacity registry —
+ * plus two enums ({@link LLM_Model_Availability},
+ * {@link LLM_Model_IO_Capability}) that had no per-model facts and no consumer
+ * at all. Partial maps are how a vocabulary silently stops describing the
+ * running system.
+ *
+ * Per-field burden of proof: see {@link LLM_ModelCatalogEntry}.
+ */
+export declare const LLM_MODEL_CATALOG: Record<LLM_Model, LLM_ModelCatalogEntry>;
+/**
+ * Availability states a model may be auto-RESOLVED in. `DEPRECATED` and
+ * `DISCONTINUED` are deliberately absent: a retired id stays nameable as an
+ * explicit pin and readable in a stored trace, but the framework will not
+ * choose it on an author's behalf.
+ */
+export declare const LLM_MODEL_RESOLVABLE_AVAILABILITIES: readonly LLM_Model_Availability[];
+/**
+ * The framework's DEFAULT answer to "which model serves this kind of work",
+ * ordered by preference, highest first.
+ *
+ * This is the one place a monthly model launch lands: add its catalog row, then
+ * put it at the head of the applicabilities it should now serve. No agent
+ * definition changes. An application may override this per applicability (see
+ * the resolution options on {@link resolveModelForApplicability}) when it wants
+ * a different cost/quality trade without forking the engine.
+ *
+ * A preference entry is only a CANDIDATE — resolution still requires the row to
+ * name the requesting provider, to be in a resolvable availability, and to
+ * declare the applicability. So an entry can never resurrect a retired model or
+ * quietly widen what a model is used for.
+ */
+export declare const LLM_MODEL_APPLICABILITY_PREFERENCE: Record<LLM_Model_Applicability, readonly LLM_Model[]>;
+/** Why {@link resolveModelForApplicability} could not answer — carried into a named CONFIGURATION error. */
+export declare enum LLM_ModelResolutionFailure {
+    /** The applicability has no candidate at all for this provider. */
+    NO_CANDIDATE_FOR_PROVIDER = "no_candidate_for_provider",
+    /** Candidates exist for this provider but none is in a resolvable availability. */
+    NO_RESOLVABLE_AVAILABILITY = "no_resolvable_availability",
+    /** Candidates exist and are available, but none evidences the required IO capability. */
+    REQUIRED_IO_CAPABILITY_UNEVIDENCED = "required_io_capability_unevidenced"
+}
+export type LLM_ModelResolutionInput = {
+    applicability: LLM_Model_Applicability;
+    /** Resolve within ONE provider — the provider the agent is configured against. */
+    providerRef: string;
+    /**
+     * Application-level override of the default preference order, per
+     * applicability. Only the ORDER and MEMBERSHIP of candidates is overridable;
+     * every catalog gate still applies, so an override cannot select a retired
+     * model, a model of another provider, or a model that does not declare the
+     * applicability.
+     */
+    preferenceOverride?: Partial<Record<LLM_Model_Applicability, readonly LLM_Model[]>>;
+};
+export type LLM_ModelResolution = {
+    resolved: true;
+    model: LLM_Model;
+    entry: LLM_ModelCatalogEntry;
+    fromOverride: boolean;
+} | {
+    resolved: false;
+    failure: LLM_ModelResolutionFailure;
+    consideredModels: readonly LLM_Model[];
+};
+/**
+ * Resolve an applicability to ONE concrete model id for a given provider.
+ *
+ * Fails CLOSED and explains itself: an unresolvable applicability must surface
+ * as a named startup/configuration error naming what was considered, never as a
+ * silent fallback to some other model. A fallback here would be the exact defect
+ * this layer exists to remove — the author asked for a KIND of model, and
+ * quietly handing them a different kind is worse than refusing.
+ *
+ * Note this function answers the semantic question only. Whether the resolved
+ * model is reachable over the agent's TRANSPORT (a profile that
+ * declares it) is a separate gate owned by the backend, because the transport
+ * declaration lives on the provider registry rather than in this catalog.
+ *
+ * `catalog` is a parameter rather than a closed-over constant so each gate can
+ * be exercised INDEPENDENTLY: with the real catalog, several gates are
+ * unreachable simply because no shipped row has the shape that trips them (no
+ * model is currently both applicability-declaring and unverified), and a gate
+ * that cannot be reached is a gate nobody has tested. Production callers pass
+ * nothing.
+ */
+export declare const resolveModelForApplicability: (input: LLM_ModelResolutionInput, catalog?: Record<LLM_Model, LLM_ModelCatalogEntry>) => LLM_ModelResolution;
+/**
+ * Model → thinking capability, DERIVED from {@link LLM_MODEL_CATALOG}.
+ *
+ * Still partial and still evidence-only: a model appears here only when its
+ * catalog row carries a probed `thinkingCapability`. Absence means "not yet
+ * verified", NOT "no thinking". Validation FAILS OPEN on absent/unknown models
+ * — `LLMProvider_OperationModelConfiguration.model` is a free `z.string()`
+ * (fine-tuned + custom deployment ids are legitimate), so we can neither
+ * enumerate every id nor guess safely. Guessing is worse than omitting: a wrong
+ * `ALWAYS` blocks a legal config, whereas an omission leaves runtime behavior
+ * untouched.
+ */
+export declare const LLM_MODEL_THINKING_CAPABILITY: Partial<Record<LLM_Model, LLM_Model_Thinking_Capability>>;
+/**
+ * Effort levels a specific model REJECTS despite its thinking capability,
+ * DERIVED from {@link LLM_MODEL_CATALOG} — per-provider vocabulary quirks,
+ * distinct from the capability axis above. Evidence-only, same rule.
+ *
+ * `PROVIDER_DEFAULT` is rejected by GPT-5.6 as an explicit value: to get the
+ * model's own default, OMIT `reasoningEffort` entirely rather than naming it.
+ */
+export declare const LLM_MODEL_UNSUPPORTED_REASONING_EFFORTS: Partial<Record<LLM_Model, readonly LLMProvider_ReasoningEffort[]>>;
+/**
+ * Resolve a model's verified thinking capability, or `undefined` when the model
+ * id is unknown/unverified (free-form ids are legitimate — see
+ * {@link LLM_MODEL_THINKING_CAPABILITY}).
+ */
+export declare const getModelThinkingCapability: (model: string) => LLM_Model_Thinking_Capability | undefined;
+/** @wildo_source:part:start saas.external-providers.llm.model-configuration facet:kind:api facet:audience:app-developer
+ *
+ * Validate a `model × reasoningEffort` pair against verified capability.
+ *
+ * Returns a human-readable violation, or `null` when the pair is valid OR
+ * cannot be judged. **Fails OPEN by design** (unknown model, or omitted effort
+ * → `null`): the alternative would reject legitimate custom deployments.
+ *
+ * Call this at authoring/registration time so an impossible pair surfaces as a
+ * named startup error instead of a provider 400 in the middle of a long agent
+ * pipeline — the trap this exists to catch is `NONE`, which turns reasoning off
+ * on GPT-5.6 but hard-errors on Claude 5.
+ *
+ * @param model The configured model id (free-form; unknown ids pass).
+ * @param effort The configured effort; omit/undefined always passes.
+ * @returns A violation message, or `null` if valid/unjudgeable.
+ */
+export declare const validateReasoningEffortForModel: (model: string, effort: LLMProvider_ReasoningEffort | undefined) => string | null;
+/** @wildo_source:part:start saas.external-providers.llm.model-configuration facet:kind:api facet:audience:app-developer
+ *
+ * The provider/model/sampling surface every LLM agent config inherits — this is
+ * the shape behind an agent's `config` (an agent adds `operationKey` on top).
+ *
+ * `providerRef` names a provider you enabled for the `AI_LLM` capability in
+ * `defineSaaSProviders`; `model` is a free-form string so fine-tuned and custom
+ * deployment ids stay legal. Every sampling field is OPTIONAL and every one of
+ * them is forwarded to the provider verbatim — so an unsupported value is a
+ * provider 400, not a framework-side clamp. Omit a field to accept the model's
+ * own default; that is the portable choice (notably: the Claude 5 family
+ * REJECTS an explicit `temperature`).
+ */
 export declare const LLMProvider_OperationModelConfiguration_Schema: z.ZodObject<{
     model: z.ZodString;
     providerRef: z.ZodString;
@@ -124,7 +502,7 @@ export declare const LLMProvider_OperationModelConfiguration_Schema: z.ZodObject
     frequencyPenalty: z.ZodOptional<z.ZodNumber>;
     presencePenalty: z.ZodOptional<z.ZodNumber>;
     stopStringSequences: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    thinkingEnabled: z.ZodOptional<z.ZodBoolean>;
+    reasoningEffort: z.ZodOptional<z.ZodEnum<typeof LLMProvider_ReasoningEffort>>;
     toolingFunctionEnabled: z.ZodOptional<z.ZodBoolean>;
     mcpCompatible: z.ZodOptional<z.ZodBoolean>;
     toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodLiteral<"none">, z.ZodLiteral<"required">, z.ZodObject<{
@@ -133,6 +511,7 @@ export declare const LLMProvider_OperationModelConfiguration_Schema: z.ZodObject
     }, z.core.$strip>]>>;
 }, z.core.$strip>;
 export type LLMProvider_OperationModelConfiguration = z.infer<typeof LLMProvider_OperationModelConfiguration_Schema>;
+/** @wildo_source:part:end saas.external-providers.llm.model-configuration */
 export declare enum LLMProvider_FinishReason {
     STOP = "stop",
     LENGTH = "length",
@@ -145,6 +524,12 @@ export declare const LLMProvider_UsageSchema: z.ZodObject<{
     promptTokens: z.ZodOptional<z.ZodNumber>;
     completionTokens: z.ZodOptional<z.ZodNumber>;
     totalTokens: z.ZodOptional<z.ZodNumber>;
+    tokenUsageComplete: z.ZodOptional<z.ZodBoolean>;
+    inputTokenDetails: z.ZodOptional<z.ZodObject<{
+        noCacheTokens: z.ZodOptional<z.ZodNumber>;
+        cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+        cacheWriteTokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type LLMProvider_Usage = z.infer<typeof LLMProvider_UsageSchema>;
 export declare const LLMProvider_TrackingSchema: z.ZodObject<{
@@ -186,9 +571,19 @@ export declare const LLMProvider_TrackingSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type LLMProvider_Tracking = z.infer<typeof LLMProvider_TrackingSchema>;
+/**
+ * How an LLM operation was physically executed.
+ *
+ * One member, deliberately. A `CLI` member existed while a coding agent was
+ * mis-modelled as a text completion and reached the model through a subprocess;
+ * with coding agents moved to their own operation family and their own
+ * execution-transport metadata, an LLM call is served over HTTP and nothing
+ * else. Kept as an enum rather than collapsed away because the field is
+ * recorded on durable execution contexts, where a bare literal would carry no
+ * explanation and a second transport may yet be real.
+ */
 export declare enum LLMProvider_ExecutionTransportKind {
-    API = "api",
-    CLI = "cli"
+    API = "api"
 }
 export declare const LLMProvider_ExecutionArtifactKindSchema: z.ZodEnum<{
     stdout: "stdout";
@@ -204,32 +599,134 @@ export declare const LLMProvider_ExecutionArtifactMetadataSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type LLMProvider_ExecutionArtifactMetadata = z.infer<typeof LLMProvider_ExecutionArtifactMetadataSchema>;
 export declare const LLMProvider_ExecutionTransportMetadataSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    kind: z.ZodLiteral<LLMProvider_ExecutionTransportKind.API>;
+    kind: z.ZodLiteral<LLMProvider_ExecutionTransportKind>;
     protocolKind: z.ZodLiteral<ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER>;
     providerRef: z.ZodString;
     model: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    kind: z.ZodLiteral<LLMProvider_ExecutionTransportKind.CLI>;
-    protocolKind: z.ZodLiteral<ExternalProvider_ExchangeProtocol_Kind.CLI_RUNTIME>;
-    providerRef: z.ZodString;
-    model: z.ZodOptional<z.ZodString>;
-    resolvedModel: z.ZodOptional<z.ZodString>;
-    executionProfileRef: z.ZodString;
-    runnerHost: z.ZodEnum<typeof CLIRuntime_RunnerHost>;
-    outputParserMode: z.ZodEnum<typeof CLIRuntime_OutputParserMode>;
-    command: z.ZodString;
-    workingDirectory: z.ZodString;
-    exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    signal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    artifacts: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        kind: z.ZodEnum<{
-            stdout: "stdout";
-            stderr: "stderr";
-        }>;
-        byteLength: z.ZodNumber;
-    }, z.core.$strip>>>;
 }, z.core.$strip>], "kind">;
 export type LLMProvider_ExecutionTransportMetadata = z.infer<typeof LLMProvider_ExecutionTransportMetadataSchema>;
+/**
+ * Why a `GENERATE_STRUCTURED` call returned `{ object: undefined }` even though a
+ * physical provider call completed.
+ *
+ * The two members are the two distinct code paths that can produce a missing object,
+ * and they are NOT interchangeable — they differ in whether the call is billable and
+ * in whether the provider told us anything about the shape of the failure:
+ *
+ * - `INVALID_OBJECT_AFTER_COMPLETED_CALL` — the provider answered, its usage is real
+ *   and metered, and the SDK rejected what came back: schema validation failed, the
+ *   JSON was unparseable, or the completion was truncated. This is the member that
+ *   carries `validationIssues` (the exact schema paths the model omitted) and
+ *   `finishReason`.
+ * - `NO_OBJECT_GENERATED` — the SDK raised `AI_NoObjectGeneratedError` without a
+ *   usage-bearing payload, so no shape metadata was recovered. Distinguished from the
+ *   above precisely because a caller must NOT read the absence of `validationIssues`
+ *   here as "the schema was satisfied".
+ * - `RESOLVED_WITHOUT_OBJECT` — the SDK call RESOLVED, raising nothing at all, and the
+ *   object was still absent. Off-contract for the AI SDK, whose `generateObject` declares
+ *   a non-optional `object` and signals absence by throwing; it is a member because the
+ *   engine does not validate that contract, so without it this vocabulary would have a
+ *   hole exactly where the invariant below is least defensible. A caller seeing this is
+ *   looking at an SDK or provider-adapter defect, not at a model that answered badly.
+ *
+ * Deliberately NOT a member: a provider transport failure. Those still THROW a typed
+ * backend error rather than returning `{ object: undefined }`, and folding them in
+ * here would let a caller treat a network fault as a model-output problem.
+ *
+ * The invariant these three members exist to uphold: **every path that hands a caller
+ * `{ object: undefined }` attaches one of them.** That is what lets the field's absence
+ * mean "not a structured-output failure" rather than "no reason was recorded" — and it is
+ * why the third member was added rather than the third path left unattached.
+ */
+export declare enum LLMProvider_StructuredGenerationFailureKind {
+    INVALID_OBJECT_AFTER_COMPLETED_CALL = "invalid-object-after-completed-call",
+    NO_OBJECT_GENERATED = "no-object-generated",
+    RESOLVED_WITHOUT_OBJECT = "resolved-without-object"
+}
+/**
+ * One structural validation issue recovered from the SDK/Zod cause chain.
+ *
+ * `code` + `path` ONLY, never the issue's `message`: a provider validation error
+ * retains the rejected value in its message, so carrying it would copy private model
+ * output into any log, trace or persisted failure record that receives this reason.
+ * The path is what a caller actually needs — it names the field the model omitted.
+ */
+export declare const LLMProvider_StructuredValidationIssueSchema: z.ZodObject<{
+    code: z.ZodString;
+    path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+}, z.core.$strip>;
+export type LLMProvider_StructuredValidationIssue = z.infer<typeof LLMProvider_StructuredValidationIssueSchema>;
+/**
+ * The reason a structured generation produced no object, carried back to the CALLER.
+ *
+ * ## Why this exists
+ *
+ * `GENERATE_STRUCTURED` logs a rich failure line (error name, message, validation
+ * cause, the exact schema paths that failed, finish reason, generated-text length)
+ * and then used to return `{ object: undefined }` with nothing attached. Every caller
+ * therefore knew only "no object" and had to invent a generic message, so the only way
+ * to learn WHY a unit failed was to grep the process's own log file for the preceding
+ * line — which is not available to the operator reading a CLI summary, a persisted
+ * failure record, or a retry classifier.
+ *
+ * ## Where it is delivered
+ *
+ * On {@link LLMProvider_OperationContext_BaseSchema}, i.e. the invocation's
+ * `executionContext` — the same envelope that already carries `usage`, `finishReason`
+ * and `transport`. It is OPTIONAL and present only on a failed structured generation,
+ * so no existing caller is affected; a caller that wants the reason reads
+ * `executionContext.structuredGenerationFailure` exactly as it already reads
+ * `executionContext.usage`.
+ *
+ * Because the whole envelope is what the agent-call trace sink receives as its
+ * `context`, the reason reaches traceability for free.
+ *
+ * ## Privacy
+ *
+ * Contains NO generated text. `generatedTextLength` is a length, not a sample; it
+ * distinguishes a truncation from an empty completion without disclosing content.
+ */
+export declare const LLMProvider_StructuredGenerationFailureSchema: z.ZodObject<{
+    kind: z.ZodEnum<typeof LLMProvider_StructuredGenerationFailureKind>;
+    message: z.ZodString;
+    errorName: z.ZodOptional<z.ZodString>;
+    validationCauseName: z.ZodOptional<z.ZodString>;
+    validationIssues: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    }, z.core.$strip>>>;
+    finishReason: z.ZodOptional<z.ZodString>;
+    generatedTextLength: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    rootKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type LLMProvider_StructuredGenerationFailure = z.infer<typeof LLMProvider_StructuredGenerationFailureSchema>;
+/**
+ * Read the structured-generation failure reason off an invocation's `executionContext`.
+ *
+ * THE supported way to reach it. Provided as a function rather than left to each caller
+ * because the alternative is the cast every `usage` reader already hand-rolls
+ * (`response.executionContext as { usage?: … }`) — N copies of one shape, each free to
+ * drift from the schema, none of them validated. Here the schema IS the reader.
+ *
+ * Returns `undefined` both when the generation succeeded and when the context predates
+ * this field, so a caller never has to distinguish "no failure" from "no reason
+ * recorded" — in either case there is nothing more specific to report than the absence
+ * of an object.
+ */
+/**
+ * Render a structured-generation failure as one operator-readable line.
+ *
+ * Lives here, beside the schema, rather than in each caller: the two labelling
+ * orchestrators alone would otherwise have hand-rolled the same rendering twice, and the
+ * value of `validationIssues` is entirely in how it is presented — a caller that quietly
+ * drops it reports "no object" with extra words. Keeping one renderer means a site that
+ * reports the reason at all reports the whole reason.
+ *
+ * Carries no generated text, only its length — see
+ * {@link LLMProvider_StructuredGenerationFailureSchema}.
+ */
+export declare function describeStructuredGenerationFailure(failure: LLMProvider_StructuredGenerationFailure): string;
+export declare function readStructuredGenerationFailure(executionContext: unknown): LLMProvider_StructuredGenerationFailure | undefined;
 export declare const LLMProvider_OperationContext_BaseSchema: z.ZodObject<{
     callTimestamp: z.ZodISODateTime;
     callDuration: z.ZodOptional<z.ZodNumber>;
@@ -239,6 +736,12 @@ export declare const LLMProvider_OperationContext_BaseSchema: z.ZodObject<{
         promptTokens: z.ZodOptional<z.ZodNumber>;
         completionTokens: z.ZodOptional<z.ZodNumber>;
         totalTokens: z.ZodOptional<z.ZodNumber>;
+        tokenUsageComplete: z.ZodOptional<z.ZodBoolean>;
+        inputTokenDetails: z.ZodOptional<z.ZodObject<{
+            noCacheTokens: z.ZodOptional<z.ZodNumber>;
+            cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+            cacheWriteTokens: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     outputTracking: z.ZodOptional<z.ZodObject<{
         toolsUsed: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -281,31 +784,24 @@ export declare const LLMProvider_OperationContext_BaseSchema: z.ZodObject<{
     executionTime: z.ZodOptional<z.ZodNumber>;
     finishedAt: z.ZodOptional<z.ZodString>;
     transport: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        kind: z.ZodLiteral<LLMProvider_ExecutionTransportKind.API>;
+        kind: z.ZodLiteral<LLMProvider_ExecutionTransportKind>;
         protocolKind: z.ZodLiteral<ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER>;
         providerRef: z.ZodString;
         model: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        kind: z.ZodLiteral<LLMProvider_ExecutionTransportKind.CLI>;
-        protocolKind: z.ZodLiteral<ExternalProvider_ExchangeProtocol_Kind.CLI_RUNTIME>;
-        providerRef: z.ZodString;
-        model: z.ZodOptional<z.ZodString>;
-        resolvedModel: z.ZodOptional<z.ZodString>;
-        executionProfileRef: z.ZodString;
-        runnerHost: z.ZodEnum<typeof CLIRuntime_RunnerHost>;
-        outputParserMode: z.ZodEnum<typeof CLIRuntime_OutputParserMode>;
-        command: z.ZodString;
-        workingDirectory: z.ZodString;
-        exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-        signal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        artifacts: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            kind: z.ZodEnum<{
-                stdout: "stdout";
-                stderr: "stderr";
-            }>;
-            byteLength: z.ZodNumber;
-        }, z.core.$strip>>>;
     }, z.core.$strip>], "kind">>;
+    structuredGenerationFailure: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<typeof LLMProvider_StructuredGenerationFailureKind>;
+        message: z.ZodString;
+        errorName: z.ZodOptional<z.ZodString>;
+        validationCauseName: z.ZodOptional<z.ZodString>;
+        validationIssues: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strip>>>;
+        finishReason: z.ZodOptional<z.ZodString>;
+        generatedTextLength: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        rootKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type LLMProvider_OperationContext_Base = z.infer<typeof LLMProvider_OperationContext_BaseSchema>;
 export type LLMProvider_OperationDefinitionBase = ExternalProvider_OperationDefinition_Base & {
@@ -432,6 +928,10 @@ export type LLMProvider_StreamTextOutput = z.infer<typeof LLMProvider_StreamText
 export declare const LLMProvider_GenerateStructuredInputSchema: z.ZodObject<{
     prompt: z.ZodString;
     schema: z.ZodCustom<z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>, z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>>;
+    images: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"image">;
+        image: z.ZodUnion<readonly [z.ZodURL, z.ZodString]>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export declare const LLMProvider_GenerateStructuredOutputSchema: z.ZodObject<{
     object: z.ZodUnknown;
@@ -490,7 +990,7 @@ export declare const LLMProvider_StreamStructuredOutputSchema: z.ZodObject<{
 export type LLMProvider_StreamStructuredInput = z.infer<typeof LLMProvider_StreamStructuredInputSchema>;
 export type LLMProvider_StreamStructuredOutput = z.infer<typeof LLMProvider_StreamStructuredOutputSchema>;
 export declare const LLMProvider_StatusSchema: z.ZodObject<{
-    status: z.ZodEnum<typeof import("../index.js").ExternalProvider_Status>;
+    status: z.ZodEnum<typeof import("..").ExternalProvider_Status>;
     lastCheckedAt: z.ZodString;
     errorReason: z.ZodOptional<z.ZodString>;
     protocolKind: z.ZodLiteral<ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER>;