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

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

@@ -1,7 +1,6 @@
 import { z } from "zod";
 import { ExternalProvider_ExchangeProtocol_Kind, ExternalProvider_ExchangeProtocol_Status_BaseSchema } from "../core/commons.external-connectors-models.schemas.js";
 import { ExternalProvider_OperationContextSchema } from "../core/operations.external-connectors-models.schemas.js";
-import { CLIRuntime_OutputParserMode, CLIRuntime_RunnerHost } from "./cli-runtime.external-connectors-models.schemas.js";
 //===============================================================
 // LLM Provider
 // --------
@@ -17,24 +16,51 @@ export var LLM_Model;
     LLM_Model["OPEN_AI_O3_MINI"] = "o3-mini";
     LLM_Model["OPEN_AI_O4_MINI"] = "o4-mini";
     // OpenAI Models - GPT Series
+    // Ids verified LIVE against `GET /v1/models` (2026-07-16). The previous
+    // "gpt-5.1-instant" / "gpt-5.1-thinking" entries were ChatGPT PRODUCT
+    // names, not API model ids — they never existed on the API (removed).
+    //
+    // GPT-5.6 (launched 2026-07-09) renames tiers: the NUMBER is the
+    // generation, Sol/Terra/Luna are durable capability tiers — Sol = frontier
+    // flagship, Terra = balanced everyday work, Luna = fast/affordable
+    // (roughly the Fable/Opus/Sonnet-tier equivalents). ALL THREE reject
+    // non-default `temperature` (only 1; verified live) — agents on them must
+    // send NO sampling params.
+    /** GPT-5.6 frontier flagship tier. */
+    LLM_Model["OPEN_AI_GPT_5_6_SOL"] = "gpt-5.6-sol";
+    /** GPT-5.6 balanced tier for everyday work. */
+    LLM_Model["OPEN_AI_GPT_5_6_TERRA"] = "gpt-5.6-terra";
+    /** GPT-5.6 fast/affordable tier. */
+    LLM_Model["OPEN_AI_GPT_5_6_LUNA"] = "gpt-5.6-luna";
+    /** Dec-2025 flagship (accepts `temperature`, unlike the 5.6 family). */
+    LLM_Model["OPEN_AI_GPT_5_2"] = "gpt-5.2";
+    /** Extended-reasoning 5.2 variant. */
+    LLM_Model["OPEN_AI_GPT_5_2_PRO"] = "gpt-5.2-pro";
+    LLM_Model["OPEN_AI_GPT_5_1"] = "gpt-5.1";
     LLM_Model["OPEN_AI_GPT_5"] = "gpt-5";
-    LLM_Model["OPEN_AI_GPT_5_1_INSTANT"] = "gpt-5.1-instant";
-    LLM_Model["OPEN_AI_GPT_5_1_THINKING"] = "gpt-5.1-thinking";
+    LLM_Model["OPEN_AI_GPT_5_MINI"] = "gpt-5-mini";
     LLM_Model["OPEN_AI_GPT_4O"] = "gpt-4o";
     LLM_Model["OPEN_AI_GPT_4O_MINI"] = "gpt-4o-mini";
     LLM_Model["OPEN_AI_GPT_4_TURBO"] = "gpt-4-turbo";
     LLM_Model["OPEN_AI_GPT_4"] = "gpt-4";
     LLM_Model["OPEN_AI_GPT_3_5_TURBO"] = "gpt-3.5-turbo";
     // Anthropic Models
-    LLM_Model["CLAUDE_4_OPUS"] = "claude-4-opus";
+    // Ids verified LIVE against `GET /v1/models` (2026-07-16). The previous
+    // "claude-4-opus" entry was never a real API id, and the claude-3* family
+    // is RETIRED (absent from the provider's model list) — all removed.
+    //
+    // The WHOLE Claude 5 family (fable-5 AND sonnet-5) REJECTS explicit
+    // `temperature` ("deprecated for this model", verified live 2026-07-16) —
+    // agents on them must send NO sampling params. Claude 4.5+ additionally
+    // rejects temperature+topP together.
+    /** Anthropic's most intelligent generally-available model (Claude 5 family, Mythos-class tier). */
+    LLM_Model["CLAUDE_FABLE_5"] = "claude-fable-5";
+    /** Claude 5 family workhorse. */
+    LLM_Model["CLAUDE_SONNET_5"] = "claude-sonnet-5";
+    /** Latest Opus-tier model (4.x line). */
+    LLM_Model["CLAUDE_OPUS_4_8"] = "claude-opus-4-8";
     LLM_Model["CLAUDE_SONNET_4_5"] = "claude-sonnet-4-5";
     LLM_Model["CLAUDE_HAIKU_4_5"] = "claude-haiku-4-5";
-    LLM_Model["CLAUDE_3_7_SONNET"] = "claude-3-7-sonnet";
-    LLM_Model["CLAUDE_3_5_SONNET"] = "claude-3-5-sonnet-20241022";
-    LLM_Model["CLAUDE_3_5_HAIKU"] = "claude-3-5-haiku-20241022";
-    LLM_Model["CLAUDE_3_OPUS"] = "claude-3-opus-20240229";
-    LLM_Model["CLAUDE_3_SONNET"] = "claude-3-sonnet-20240229";
-    LLM_Model["CLAUDE_3_HAIKU"] = "claude-3-haiku-20240307";
     // Google Models
     LLM_Model["GOOGLE_GEMINI_3_DEEP_THINK"] = "gemini-3-deep-think";
     LLM_Model["GOOGLE_GEMINI_3_PRO"] = "gemini-3-pro";
@@ -75,10 +101,31 @@ export var LLM_Model_IO_Capability;
     LLM_Model_IO_Capability["LONG_CONTEXT"] = "long_context";
     LLM_Model_IO_Capability["CODE_GENERATION"] = "code_generation";
 })(LLM_Model_IO_Capability || (LLM_Model_IO_Capability = {}));
+/**
+ * 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 var LLM_Model_Thinking_Capability;
 (function (LLM_Model_Thinking_Capability) {
+    /** Not a reasoning model — it cannot think, so NO `reasoningEffort` is valid. */
     LLM_Model_Thinking_Capability["NONE"] = "none";
+    /** Thinking can be enabled AND disabled — every effort level is valid, incl. `NONE`. */
     LLM_Model_Thinking_Capability["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.
+     */
     LLM_Model_Thinking_Capability["ALWAYS"] = "always";
 })(LLM_Model_Thinking_Capability || (LLM_Model_Thinking_Capability = {}));
 export var LLM_Model_Availability;
@@ -89,23 +136,128 @@ export var LLM_Model_Availability;
     LLM_Model_Availability["DEPRECATED"] = "deprecated";
     LLM_Model_Availability["DISCONTINUED"] = "discontinued";
 })(LLM_Model_Availability || (LLM_Model_Availability = {}));
+/**
+ * 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 var LLM_Model_Applicability;
+(function (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.
+     */
+    LLM_Model_Applicability["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.
+     */
+    LLM_Model_Applicability["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.
+     */
+    LLM_Model_Applicability["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.
+     */
+    LLM_Model_Applicability["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.
+     */
+    LLM_Model_Applicability["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.
+     */
+    LLM_Model_Applicability["WORKSPACE_CODING_AGENT"] = "workspace_coding_agent";
+})(LLM_Model_Applicability || (LLM_Model_Applicability = {}));
+/** @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 var LLMProvider_OperationKey;
 (function (LLMProvider_OperationKey) {
-    // Base operations (thinking controlled via parameter for OPTIONAL models)
     LLMProvider_OperationKey["GENERATE_TEXT"] = "llm.generateText";
     LLMProvider_OperationKey["CHAT_COMPLETION"] = "llm.chatCompletion";
     LLMProvider_OperationKey["STREAM_TEXT"] = "llm.streamText";
     LLMProvider_OperationKey["GENERATE_STRUCTURED"] = "llm.generateStructured";
     LLMProvider_OperationKey["CHAT_MULTIMODAL"] = "llm.chatMultimodal";
     LLMProvider_OperationKey["STREAM_STRUCTURED"] = "llm.streamStructured";
-    // Thinking-enabled operations (for models with OPTIONAL or ALWAYS thinking)
-    LLMProvider_OperationKey["GENERATE_TEXT_THINKING"] = "llm.generateText.thinking";
-    LLMProvider_OperationKey["CHAT_COMPLETION_THINKING"] = "llm.chatCompletion.thinking";
-    LLMProvider_OperationKey["STREAM_TEXT_THINKING"] = "llm.streamText.thinking";
-    LLMProvider_OperationKey["GENERATE_STRUCTURED_THINKING"] = "llm.generateStructured.thinking";
-    LLMProvider_OperationKey["CHAT_MULTIMODAL_THINKING"] = "llm.chatMultimodal.thinking";
-    LLMProvider_OperationKey["STREAM_STRUCTURED_THINKING"] = "llm.streamStructured.thinking";
 })(LLMProvider_OperationKey || (LLMProvider_OperationKey = {}));
+/** @wildo_source:part:end saas.external-providers.llm.operation-key */
 /**
  * Prompt format preference for provider-specific rendering
  * Used by PromptCompilerBackendService to select optimal format
@@ -131,6 +283,431 @@ export const LLMProvider_ToolChoice_Schema = z.union([
         name: z.string(),
     }),
 ]);
+/** @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 var LLMProvider_ReasoningEffort;
+(function (LLMProvider_ReasoningEffort) {
+    LLMProvider_ReasoningEffort["PROVIDER_DEFAULT"] = "provider-default";
+    LLMProvider_ReasoningEffort["NONE"] = "none";
+    LLMProvider_ReasoningEffort["MINIMAL"] = "minimal";
+    LLMProvider_ReasoningEffort["LOW"] = "low";
+    LLMProvider_ReasoningEffort["MEDIUM"] = "medium";
+    LLMProvider_ReasoningEffort["HIGH"] = "high";
+    LLMProvider_ReasoningEffort["XHIGH"] = "xhigh";
+})(LLMProvider_ReasoningEffort || (LLMProvider_ReasoningEffort = {}));
+/**
+ * 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 const LLM_MODEL_CATALOG = {
+    // ---------------------------------------------------------------
+    // OpenAI — ids verified LIVE against `GET /v1/models` (2026-07-16).
+    // ---------------------------------------------------------------
+    [LLM_Model.OPEN_AI_GPT_5_6_SOL]: {
+        providerRef: "openai",
+        availability: LLM_Model_Availability.PRODUCTION,
+        probedOn: "2026-07-16",
+        applicabilities: [LLM_Model_Applicability.DEEP_JUDGMENT, LLM_Model_Applicability.LONG_CONTEXT_ANALYSIS],
+        ioCapabilities: [
+            LLM_Model_IO_Capability.MULTIMODAL_VISION,
+            LLM_Model_IO_Capability.STRUCTURED_OUTPUTS,
+            LLM_Model_IO_Capability.TOOL_USE,
+            LLM_Model_IO_Capability.LONG_CONTEXT,
+        ],
+        thinkingCapability: LLM_Model_Thinking_Capability.OPTIONAL,
+        // Live: `minimal` → 400 (the published docs claim it exists — they are wrong).
+        unsupportedReasoningEfforts: [LLMProvider_ReasoningEffort.MINIMAL, LLMProvider_ReasoningEffort.PROVIDER_DEFAULT],
+        rejectsExplicitTemperature: true,
+    },
+    [LLM_Model.OPEN_AI_GPT_5_6_TERRA]: {
+        providerRef: "openai",
+        availability: LLM_Model_Availability.PRODUCTION,
+        probedOn: "2026-07-16",
+        applicabilities: [LLM_Model_Applicability.STRUCTURED_AUTHORING, LLM_Model_Applicability.VISUAL_JUDGMENT],
+        ioCapabilities: [
+            LLM_Model_IO_Capability.MULTIMODAL_VISION,
+            LLM_Model_IO_Capability.STRUCTURED_OUTPUTS,
+            LLM_Model_IO_Capability.TOOL_USE,
+        ],
+        thinkingCapability: LLM_Model_Thinking_Capability.OPTIONAL,
+        unsupportedReasoningEfforts: [LLMProvider_ReasoningEffort.MINIMAL, LLMProvider_ReasoningEffort.PROVIDER_DEFAULT],
+        rejectsExplicitTemperature: true,
+    },
+    [LLM_Model.OPEN_AI_GPT_5_6_LUNA]: {
+        providerRef: "openai",
+        availability: LLM_Model_Availability.PRODUCTION,
+        probedOn: "2026-07-16",
+        applicabilities: [LLM_Model_Applicability.HIGH_VOLUME_MECHANICAL],
+        ioCapabilities: [LLM_Model_IO_Capability.STRUCTURED_OUTPUTS, LLM_Model_IO_Capability.TOOL_USE],
+        thinkingCapability: LLM_Model_Thinking_Capability.OPTIONAL,
+        unsupportedReasoningEfforts: [LLMProvider_ReasoningEffort.MINIMAL, LLMProvider_ReasoningEffort.PROVIDER_DEFAULT],
+        rejectsExplicitTemperature: true,
+    },
+    [LLM_Model.OPEN_AI_GPT_5_2_PRO]: {
+        providerRef: "openai",
+        availability: LLM_Model_Availability.PRODUCTION,
+        probedOn: "2026-07-16",
+        applicabilities: [LLM_Model_Applicability.DEEP_JUDGMENT],
+    },
+    [LLM_Model.OPEN_AI_GPT_5_2]: {
+        providerRef: "openai",
+        availability: LLM_Model_Availability.PRODUCTION,
+        probedOn: "2026-07-16",
+        applicabilities: [],
+    },
+    [LLM_Model.OPEN_AI_GPT_5_1]: { providerRef: "openai", availability: LLM_Model_Availability.PRODUCTION, probedOn: "2026-07-16", applicabilities: [] },
+    [LLM_Model.OPEN_AI_GPT_5]: { providerRef: "openai", availability: LLM_Model_Availability.PRODUCTION, probedOn: "2026-07-16", applicabilities: [] },
+    [LLM_Model.OPEN_AI_GPT_5_MINI]: { providerRef: "openai", availability: LLM_Model_Availability.PRODUCTION, probedOn: "2026-07-16", applicabilities: [] },
+    [LLM_Model.OPEN_AI_GPT_4O]: { providerRef: "openai", availability: LLM_Model_Availability.PRODUCTION, probedOn: "2026-07-16", applicabilities: [] },
+    [LLM_Model.OPEN_AI_GPT_4O_MINI]: { providerRef: "openai", availability: LLM_Model_Availability.PRODUCTION, probedOn: "2026-07-16", applicabilities: [] },
+    [LLM_Model.OPEN_AI_GPT_4_TURBO]: { providerRef: "openai", availability: LLM_Model_Availability.PRODUCTION, probedOn: "2026-07-16", applicabilities: [] },
+    [LLM_Model.OPEN_AI_GPT_4]: { providerRef: "openai", availability: LLM_Model_Availability.PRODUCTION, probedOn: "2026-07-16", applicabilities: [] },
+    [LLM_Model.OPEN_AI_GPT_3_5_TURBO]: { providerRef: "openai", availability: LLM_Model_Availability.PRODUCTION, probedOn: "2026-07-16", applicabilities: [] },
+    [LLM_Model.OPEN_AI_O1]: { providerRef: "openai", availability: LLM_Model_Availability.PRODUCTION, probedOn: "2026-07-16", applicabilities: [] },
+    [LLM_Model.OPEN_AI_O1_MINI]: { providerRef: "openai", availability: LLM_Model_Availability.PRODUCTION, probedOn: "2026-07-16", applicabilities: [] },
+    [LLM_Model.OPEN_AI_O3_MINI]: { providerRef: "openai", availability: LLM_Model_Availability.PRODUCTION, probedOn: "2026-07-16", applicabilities: [] },
+    [LLM_Model.OPEN_AI_O4_MINI]: { providerRef: "openai", availability: LLM_Model_Availability.PRODUCTION, probedOn: "2026-07-16", applicabilities: [] },
+    // ---------------------------------------------------------------
+    // Anthropic — ids verified LIVE against `GET /v1/models` (2026-07-16).
+    // The Claude 5 family reasons ADAPTIVELY and cannot be told not to:
+    // live, `reasoning: 'none'` → 400 "thinking.type.disabled is not supported
+    // for this model; thinking defaults to adaptive".
+    // ---------------------------------------------------------------
+    [LLM_Model.CLAUDE_FABLE_5]: {
+        providerRef: "anthropic",
+        availability: LLM_Model_Availability.PRODUCTION,
+        probedOn: "2026-07-16",
+        applicabilities: [
+            LLM_Model_Applicability.DEEP_JUDGMENT,
+            LLM_Model_Applicability.LONG_CONTEXT_ANALYSIS,
+            LLM_Model_Applicability.VISUAL_JUDGMENT,
+        ],
+        ioCapabilities: [
+            LLM_Model_IO_Capability.MULTIMODAL_VISION,
+            LLM_Model_IO_Capability.STRUCTURED_OUTPUTS,
+            LLM_Model_IO_Capability.TOOL_USE,
+            LLM_Model_IO_Capability.LONG_CONTEXT,
+        ],
+        thinkingCapability: LLM_Model_Thinking_Capability.ALWAYS,
+        rejectsExplicitTemperature: true,
+    },
+    [LLM_Model.CLAUDE_SONNET_5]: {
+        providerRef: "anthropic",
+        availability: LLM_Model_Availability.PRODUCTION,
+        probedOn: "2026-07-16",
+        applicabilities: [
+            LLM_Model_Applicability.STRUCTURED_AUTHORING,
+            LLM_Model_Applicability.WORKSPACE_CODING_AGENT,
+        ],
+        ioCapabilities: [
+            LLM_Model_IO_Capability.MULTIMODAL_VISION,
+            LLM_Model_IO_Capability.STRUCTURED_OUTPUTS,
+            LLM_Model_IO_Capability.TOOL_USE,
+            LLM_Model_IO_Capability.CODE_GENERATION,
+        ],
+        thinkingCapability: LLM_Model_Thinking_Capability.ALWAYS,
+        rejectsExplicitTemperature: true,
+    },
+    [LLM_Model.CLAUDE_OPUS_4_8]: {
+        providerRef: "anthropic",
+        availability: LLM_Model_Availability.PRODUCTION,
+        probedOn: "2026-07-16",
+        applicabilities: [LLM_Model_Applicability.WORKSPACE_CODING_AGENT],
+        ioCapabilities: [LLM_Model_IO_Capability.TOOL_USE, LLM_Model_IO_Capability.CODE_GENERATION],
+    },
+    [LLM_Model.CLAUDE_SONNET_4_5]: {
+        providerRef: "anthropic",
+        availability: LLM_Model_Availability.PRODUCTION,
+        probedOn: "2026-07-16",
+        applicabilities: [LLM_Model_Applicability.WORKSPACE_CODING_AGENT],
+        ioCapabilities: [LLM_Model_IO_Capability.TOOL_USE, LLM_Model_IO_Capability.CODE_GENERATION],
+    },
+    [LLM_Model.CLAUDE_HAIKU_4_5]: {
+        providerRef: "anthropic",
+        availability: LLM_Model_Availability.PRODUCTION,
+        probedOn: "2026-07-16",
+        applicabilities: [LLM_Model_Applicability.HIGH_VOLUME_MECHANICAL],
+        ioCapabilities: [LLM_Model_IO_Capability.STRUCTURED_OUTPUTS],
+    },
+    // ---------------------------------------------------------------
+    // Google / Mistral / Perplexity / xAI — NEVER live-verified by this
+    // repository. `availability` is therefore omitted and no row is
+    // auto-selectable. Probe an id and fill its row before preferring it.
+    // ---------------------------------------------------------------
+    [LLM_Model.GOOGLE_GEMINI_3_DEEP_THINK]: { providerRef: "google", applicabilities: [] },
+    [LLM_Model.GOOGLE_GEMINI_3_PRO]: { providerRef: "google", applicabilities: [] },
+    [LLM_Model.GOOGLE_GEMINI_2_5_PRO]: { providerRef: "google", applicabilities: [] },
+    [LLM_Model.GOOGLE_GEMINI_2_5_FLASH]: { providerRef: "google", applicabilities: [] },
+    [LLM_Model.GOOGLE_GEMINI_2_0_FLASH]: { providerRef: "google", applicabilities: [] },
+    [LLM_Model.GOOGLE_GEMINI_1_5_PRO]: { providerRef: "google", applicabilities: [] },
+    [LLM_Model.GOOGLE_GEMINI_1_5_FLASH]: { providerRef: "google", applicabilities: [] },
+    [LLM_Model.GOOGLE_GEMINI_PRO]: { providerRef: "google", applicabilities: [] },
+    [LLM_Model.GOOGLE_GEMINI_PRO_VISION]: { providerRef: "google", applicabilities: [] },
+    [LLM_Model.MISTRAL_LARGE]: { providerRef: "mistral", applicabilities: [] },
+    [LLM_Model.MISTRAL_MEDIUM]: { providerRef: "mistral", applicabilities: [] },
+    [LLM_Model.MISTRAL_SMALL]: { providerRef: "mistral", applicabilities: [] },
+    [LLM_Model.PERPLEXITY_SONAR_LARGE_ONLINE]: { providerRef: "perplexity", applicabilities: [] },
+    [LLM_Model.PERPLEXITY_SONAR_MEDIUM_ONLINE]: { providerRef: "perplexity", applicabilities: [] },
+    [LLM_Model.PERPLEXITY_SONAR_SMALL_ONLINE]: { providerRef: "perplexity", applicabilities: [] },
+    [LLM_Model.PERPLEXITY_SONAR_LARGE_CHAT]: { providerRef: "perplexity", applicabilities: [] },
+    [LLM_Model.PERPLEXITY_SONAR_MEDIUM_CHAT]: { providerRef: "perplexity", applicabilities: [] },
+    [LLM_Model.PERPLEXITY_SONAR_SMALL_CHAT]: { providerRef: "perplexity", applicabilities: [] },
+    [LLM_Model.GROK_4]: { providerRef: "grok", applicabilities: [] },
+    [LLM_Model.GROK_3]: { providerRef: "grok", applicabilities: [] },
+    [LLM_Model.GROK_2_VISION]: { providerRef: "grok", applicabilities: [] },
+    [LLM_Model.GROK_2]: { providerRef: "grok", applicabilities: [] },
+};
+/**
+ * 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 const LLM_MODEL_RESOLVABLE_AVAILABILITIES = [
+    LLM_Model_Availability.PRODUCTION,
+    LLM_Model_Availability.BETA,
+    LLM_Model_Availability.PREVIEW,
+];
+/**
+ * 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 const LLM_MODEL_APPLICABILITY_PREFERENCE = {
+    [LLM_Model_Applicability.DEEP_JUDGMENT]: [
+        LLM_Model.CLAUDE_FABLE_5,
+        LLM_Model.OPEN_AI_GPT_5_6_SOL,
+        LLM_Model.OPEN_AI_GPT_5_2_PRO,
+    ],
+    [LLM_Model_Applicability.STRUCTURED_AUTHORING]: [
+        LLM_Model.OPEN_AI_GPT_5_6_TERRA,
+        LLM_Model.CLAUDE_SONNET_5,
+    ],
+    [LLM_Model_Applicability.HIGH_VOLUME_MECHANICAL]: [
+        LLM_Model.OPEN_AI_GPT_5_6_LUNA,
+        LLM_Model.CLAUDE_HAIKU_4_5,
+    ],
+    [LLM_Model_Applicability.LONG_CONTEXT_ANALYSIS]: [
+        LLM_Model.CLAUDE_FABLE_5,
+        LLM_Model.OPEN_AI_GPT_5_6_SOL,
+    ],
+    [LLM_Model_Applicability.VISUAL_JUDGMENT]: [
+        LLM_Model.OPEN_AI_GPT_5_6_TERRA,
+        LLM_Model.CLAUDE_FABLE_5,
+    ],
+    [LLM_Model_Applicability.WORKSPACE_CODING_AGENT]: [
+        LLM_Model.CLAUDE_SONNET_5,
+        LLM_Model.CLAUDE_SONNET_4_5,
+        LLM_Model.CLAUDE_OPUS_4_8,
+    ],
+};
+/**
+ * IO capabilities an applicability REQUIRES of any model resolved for it.
+ *
+ * Only vision is gated today, and deliberately: selecting a model that cannot
+ * see for work whose entire input is an image is a silent, expensive failure
+ * (the model answers confidently about nothing). Because `ioCapabilities` is
+ * evidence-led, an unpopulated row is simply not selected for vision work —
+ * fail-closed on the axis where a wrong answer is unrecoverable.
+ */
+const LLM_MODEL_APPLICABILITY_REQUIRED_IO = {
+    [LLM_Model_Applicability.VISUAL_JUDGMENT]: [LLM_Model_IO_Capability.MULTIMODAL_VISION],
+};
+/** Why {@link resolveModelForApplicability} could not answer — carried into a named CONFIGURATION error. */
+export var LLM_ModelResolutionFailure;
+(function (LLM_ModelResolutionFailure) {
+    /** The applicability has no candidate at all for this provider. */
+    LLM_ModelResolutionFailure["NO_CANDIDATE_FOR_PROVIDER"] = "no_candidate_for_provider";
+    /** Candidates exist for this provider but none is in a resolvable availability. */
+    LLM_ModelResolutionFailure["NO_RESOLVABLE_AVAILABILITY"] = "no_resolvable_availability";
+    /** Candidates exist and are available, but none evidences the required IO capability. */
+    LLM_ModelResolutionFailure["REQUIRED_IO_CAPABILITY_UNEVIDENCED"] = "required_io_capability_unevidenced";
+})(LLM_ModelResolutionFailure || (LLM_ModelResolutionFailure = {}));
+/**
+ * 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 const resolveModelForApplicability = (input, catalog = LLM_MODEL_CATALOG) => {
+    const override = input.preferenceOverride?.[input.applicability];
+    const candidates = override ?? LLM_MODEL_APPLICABILITY_PREFERENCE[input.applicability];
+    const requiredIo = LLM_MODEL_APPLICABILITY_REQUIRED_IO[input.applicability] ?? [];
+    const forProvider = candidates.filter((model) => {
+        const entry = catalog[model];
+        return entry.providerRef === input.providerRef && entry.applicabilities.includes(input.applicability);
+    });
+    if (forProvider.length === 0) {
+        return { resolved: false, failure: LLM_ModelResolutionFailure.NO_CANDIDATE_FOR_PROVIDER, consideredModels: candidates };
+    }
+    const available = forProvider.filter((model) => {
+        const availability = catalog[model].availability;
+        return availability !== undefined && LLM_MODEL_RESOLVABLE_AVAILABILITIES.includes(availability);
+    });
+    if (available.length === 0) {
+        return { resolved: false, failure: LLM_ModelResolutionFailure.NO_RESOLVABLE_AVAILABILITY, consideredModels: forProvider };
+    }
+    const capable = available.filter((model) => {
+        const evidenced = catalog[model].ioCapabilities ?? [];
+        return requiredIo.every((capability) => evidenced.includes(capability));
+    });
+    if (capable.length === 0) {
+        return { resolved: false, failure: LLM_ModelResolutionFailure.REQUIRED_IO_CAPABILITY_UNEVIDENCED, consideredModels: available };
+    }
+    const model = capable[0];
+    return { resolved: true, model, entry: catalog[model], fromOverride: override !== undefined };
+};
+/**
+ * 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 const LLM_MODEL_THINKING_CAPABILITY = Object.fromEntries(Object.entries(LLM_MODEL_CATALOG)
+    .filter(([, entry]) => entry.thinkingCapability !== undefined)
+    .map(([model, entry]) => [model, entry.thinkingCapability]));
+/**
+ * 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 const LLM_MODEL_UNSUPPORTED_REASONING_EFFORTS = Object.fromEntries(Object.entries(LLM_MODEL_CATALOG)
+    .filter(([, entry]) => entry.unsupportedReasoningEfforts !== undefined)
+    .map(([model, entry]) => [model, entry.unsupportedReasoningEfforts]));
+/**
+ * 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 const getModelThinkingCapability = (model) => LLM_MODEL_THINKING_CAPABILITY[model];
+/** @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 const validateReasoningEffortForModel = (model, effort) => {
+    /** @wildo_source:part:end saas.external-providers.llm.model-configuration */
+    if (effort === undefined)
+        return null;
+    const capability = getModelThinkingCapability(model);
+    if (capability === undefined)
+        return null;
+    if (capability === LLM_Model_Thinking_Capability.NONE) {
+        return `Model "${model}" is not a reasoning model, so it accepts no reasoningEffort (got "${effort}"). Remove reasoningEffort, or pick a reasoning-capable model.`;
+    }
+    if (capability === LLM_Model_Thinking_Capability.ALWAYS && effort === LLMProvider_ReasoningEffort.NONE) {
+        return `Model "${model}" always reasons — its thinking cannot be disabled, so reasoningEffort "none" is rejected by the provider. Use "low" for the cheapest reasoning, or omit reasoningEffort for the model default.`;
+    }
+    const unsupported = LLM_MODEL_UNSUPPORTED_REASONING_EFFORTS[model];
+    if (unsupported?.includes(effort)) {
+        const hint = effort === LLMProvider_ReasoningEffort.PROVIDER_DEFAULT
+            ? 'Omit reasoningEffort entirely to get the model default.'
+            : `Supported levels for this model exclude "${effort}".`;
+        return `Model "${model}" rejects reasoningEffort "${effort}". ${hint}`;
+    }
+    return 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 const LLMProvider_OperationModelConfiguration_Schema = z.object({
     model: z.string(),
     providerRef: z.string(),
@@ -140,11 +717,26 @@ export const LLMProvider_OperationModelConfiguration_Schema = z.object({
     frequencyPenalty: z.number().optional(),
     presencePenalty: z.number().optional(),
     stopStringSequences: z.array(z.string()).optional(),
-    thinkingEnabled: z.boolean().optional(),
+    /**
+     * Reasoning-effort for reasoning-capable models — forwarded as the AI SDK
+     * top-level `reasoning` option (see {@link LLMProvider_ReasoningEffort}).
+     * Optional + additive: an agent that omits it keeps the model's default
+     * effort (the pre-Phase-3 behavior).
+     */
+    reasoningEffort: z.enum(LLMProvider_ReasoningEffort).optional(),
+    // NOTE: a `thinkingEnabled: boolean` field used to sit here. RETIRED
+    // (2026-07-17) — it was a THIRD authority axis on reasoning (alongside
+    // `reasoningEffort` and the `*_THINKING` op keys), it was strictly subsumed
+    // by `reasoningEffort` (which expresses on/off AND depth), and it was never
+    // read by any executor: the `THINKING_MODE` model preset and the
+    // `ThinkingModeFacet` set it, and nothing acted on it. Authors composing that
+    // facet believed they were enabling deep reasoning and got nothing. Use
+    // `reasoningEffort` — it is the single authority.
     toolingFunctionEnabled: z.boolean().optional(),
     mcpCompatible: z.boolean().optional(),
     toolChoice: LLMProvider_ToolChoice_Schema.optional(),
 });
+/** @wildo_source:part:end saas.external-providers.llm.model-configuration */
 // ===============================================================
 // LLM  Operations Context
 // ===============================================================
@@ -161,6 +753,20 @@ export const LLMProvider_UsageSchema = z.object({
     promptTokens: z.number().optional(),
     completionTokens: z.number().optional(),
     totalTokens: z.number().optional(),
+    /**
+     * False when a physical provider result omitted a token dimension THE OPERATION REQUIRES.
+     * Operation-aware by contract (RAG plan H4): a GENERATION requires prompt AND completion
+     * tokens; an EMBEDDING trace (`AgentCallTraceKind.EMBEDDING`) has no completion-token
+     * dimension, so its producer judges completeness on input tokens alone — an embedding must
+     * never be flagged incomplete for lacking tokens it structurally cannot have.
+     */
+    tokenUsageComplete: z.boolean().optional(),
+    /** Exact AI-SDK input categories retained for provider acquisition-cost accounting. */
+    inputTokenDetails: z.object({
+        noCacheTokens: z.number().optional(),
+        cacheReadTokens: z.number().optional(),
+        cacheWriteTokens: z.number().optional(),
+    }).optional(),
 });
 export const LLMProvider_TrackingSchema = z.object({
     // Tool execution tracking
@@ -200,10 +806,20 @@ export const LLMProvider_TrackingSchema = z.object({
         tokensUsed: z.number().optional(),
     })).optional(),
 });
+/**
+ * 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 var LLMProvider_ExecutionTransportKind;
 (function (LLMProvider_ExecutionTransportKind) {
     LLMProvider_ExecutionTransportKind["API"] = "api";
-    LLMProvider_ExecutionTransportKind["CLI"] = "cli";
 })(LLMProvider_ExecutionTransportKind || (LLMProvider_ExecutionTransportKind = {}));
 export const LLMProvider_ExecutionArtifactKindSchema = z.enum([
     "stdout",
@@ -220,22 +836,168 @@ export const LLMProvider_ExecutionTransportMetadataSchema = z.discriminatedUnion
         providerRef: z.string(),
         model: z.string().optional(),
     }),
-    z.object({
-        kind: z.literal(LLMProvider_ExecutionTransportKind.CLI),
-        protocolKind: z.literal(ExternalProvider_ExchangeProtocol_Kind.CLI_RUNTIME),
-        providerRef: z.string(),
-        model: z.string().optional(),
-        resolvedModel: z.string().optional(),
-        executionProfileRef: z.string(),
-        runnerHost: z.enum(CLIRuntime_RunnerHost),
-        outputParserMode: z.enum(CLIRuntime_OutputParserMode),
-        command: z.string(),
-        workingDirectory: z.string(),
-        exitCode: z.number().nullable().optional(),
-        signal: z.string().nullable().optional(),
-        artifacts: z.array(LLMProvider_ExecutionArtifactMetadataSchema).optional(),
-    }),
 ]);
+/**
+ * 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 var LLMProvider_StructuredGenerationFailureKind;
+(function (LLMProvider_StructuredGenerationFailureKind) {
+    LLMProvider_StructuredGenerationFailureKind["INVALID_OBJECT_AFTER_COMPLETED_CALL"] = "invalid-object-after-completed-call";
+    LLMProvider_StructuredGenerationFailureKind["NO_OBJECT_GENERATED"] = "no-object-generated";
+    LLMProvider_StructuredGenerationFailureKind["RESOLVED_WITHOUT_OBJECT"] = "resolved-without-object";
+})(LLMProvider_StructuredGenerationFailureKind || (LLMProvider_StructuredGenerationFailureKind = {}));
+/**
+ * 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 const LLMProvider_StructuredValidationIssueSchema = z.object({
+    code: z.string(),
+    path: z.array(z.union([z.string(), z.number()])),
+});
+/**
+ * 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 const LLMProvider_StructuredGenerationFailureSchema = z.object({
+    kind: z.enum(LLMProvider_StructuredGenerationFailureKind),
+    /** Human-readable one-liner, resolved through the engine's caught-error description. */
+    message: z.string(),
+    /** The thrown value's `name` when it had one, else its `typeof`. */
+    errorName: z.string().optional(),
+    /** `name` of the nested validation cause (e.g. `AI_TypeValidationError`, `ZodError`). */
+    validationCauseName: z.string().optional(),
+    /** Structural issues only — see {@link LLMProvider_StructuredValidationIssueSchema}. */
+    validationIssues: z.array(LLMProvider_StructuredValidationIssueSchema).optional(),
+    /**
+     * The provider/SDK finish reason AS REPORTED, deliberately a raw string rather than
+     * {@link LLMProvider_FinishReason}. The SDK's spelling (`content-filter`,
+     * `tool-calls`) does not match this enum's (`content_filter`, `tool_calls`), so
+     * narrowing would either drop the value or fabricate `OTHER` — and this field exists
+     * because `length` is the single most diagnostic value a truncated call reports.
+     */
+    finishReason: z.string().optional(),
+    /** Length of the text the provider did generate; `null` when it reported none. */
+    generatedTextLength: z.number().int().nonnegative().nullable().optional(),
+    /**
+     * TOP-LEVEL key names of the generated object, present ONLY for an `unrecognized_keys` failure.
+     *
+     * Still contains no generated content: these are the root keys of a schema-driven generation, which are
+     * schema shape and are read against a schema the consumer already holds. They exist because Zod reports
+     * that failure without naming the offending key on the code path this lane takes, leaving "an unknown key
+     * exists at the root" as the entire diagnosis while a single stray key discards the whole result.
+     */
+    rootKeys: z.array(z.string()).optional(),
+});
+/**
+ * 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 function describeStructuredGenerationFailure(failure) {
+    const parts = [`${failure.kind}: ${failure.message}`];
+    if (failure.finishReason !== undefined) {
+        parts.push(`finishReason=${failure.finishReason}`);
+    }
+    if (failure.validationIssues !== undefined && failure.validationIssues.length > 0) {
+        const issues = failure.validationIssues
+            .map((issue) => `${issue.path.length > 0 ? issue.path.join(".") : "<root>"} (${issue.code})`)
+            .join(", ");
+        parts.push(`schema paths: ${issues}`);
+    }
+    if (failure.generatedTextLength !== undefined && failure.generatedTextLength !== null) {
+        parts.push(`generatedTextLength=${failure.generatedTextLength}`);
+    }
+    return parts.join(" \u00b7 ");
+}
+export function readStructuredGenerationFailure(executionContext) {
+    if (typeof executionContext !== "object" || executionContext === null)
+        return undefined;
+    const candidate = executionContext.structuredGenerationFailure;
+    if (candidate === undefined)
+        return undefined;
+    const parsed = LLMProvider_StructuredGenerationFailureSchema.safeParse(candidate);
+    return parsed.success ? parsed.data : undefined;
+}
 export const LLMProvider_OperationContext_BaseSchema = ExternalProvider_OperationContextSchema.extend({
     finishReason: z.enum(LLMProvider_FinishReason).optional(),
     usage: LLMProvider_UsageSchema.optional(),
@@ -243,6 +1005,12 @@ export const LLMProvider_OperationContext_BaseSchema = ExternalProvider_Operatio
     executionTime: z.number().optional(),
     finishedAt: z.string().optional(),
     transport: LLMProvider_ExecutionTransportMetadataSchema.optional(),
+    /**
+     * Present ONLY when a `GENERATE_STRUCTURED` call returned `{ object: undefined }`.
+     * Its absence therefore means "not a structured-output failure", never "no reason
+     * available". See {@link LLMProvider_StructuredGenerationFailureSchema}.
+     */
+    structuredGenerationFailure: LLMProvider_StructuredGenerationFailureSchema.optional(),
 });
 // ===============================================================
 // LLM I/O Schemas
@@ -321,6 +1089,17 @@ export const LLMProvider_StreamTextOutputSchema = z.object({
 export const LLMProvider_GenerateStructuredInputSchema = z.object({
     prompt: z.string(),
     schema: z.custom(),
+    /**
+     * OPTIONAL image parts for VISION-grounded structured generation. When present
+     * (and the target model has `MULTIMODAL_VISION` capability, e.g. `gpt-4o`), the
+     * provider is driven with a multimodal user message (`prompt` text + these
+     * image parts) instead of a bare text prompt, so the schema-constrained object
+     * is produced FROM the pixels rather than from a text description of them. When
+     * absent the call is a plain text-input structured generation (unchanged). Each
+     * part follows {@link LLMProvider_ImageContentSchema} — a `data:image/...;base64,…`
+     * data URI or an image URL. Generic across providers/models; no domain logic.
+     */
+    images: z.array(LLMProvider_ImageContentSchema).optional(),
 });
 export const LLMProvider_GenerateStructuredOutputSchema = z.object({
     object: z.unknown(),
@@ -348,4 +1127,4 @@ export const LLMProvider_StreamStructuredOutputSchema = z.object({
 export const LLMProvider_StatusSchema = ExternalProvider_ExchangeProtocol_Status_BaseSchema.extend({
     protocolKind: z.literal(ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER),
 });
-//# sourceMappingURL=llm.external-connectors-models.schemas.js.map
+//# sourceMappingURL=llm.external-connectors-models.schemas.js.map