@memberjunction/ai 6.1.0-edge.6 → 6.1.0-edge.7

package/dist/generic/chat.types.d.ts

@@ -1,11 +1,18 @@
 import { BaseParams, BaseResult, ModelUsage } from "./baseModel.js";
 /**
  * The possible roles for a chat message.
+ *
+ * `tool` carries the RESULT of a native tool call back to the model and is only ever produced
+ * alongside a preceding `assistant` turn whose {@link ChatMessage.toolCalls} it answers. Its
+ * content is one or more `tool_result` {@link ChatMessageContentBlock}s. Drivers that do not
+ * implement tools (`BaseLLM.SupportsTools === false`) map it to `user` like any other non-assistant
+ * role, so an unsupported driver degrades to prose rather than erroring.
  */
 export declare const ChatMessageRole: {
     readonly system: "system";
     readonly user: "user";
     readonly assistant: "assistant";
+    readonly tool: "tool";
 };
 export type ChatMessageRole = typeof ChatMessageRole[keyof typeof ChatMessageRole];
 /**
@@ -15,15 +22,32 @@ export type ChatMessageRole = typeof ChatMessageRole[keyof typeof ChatMessageRol
 export type ChatMessageContentBlock = {
     /**
      * The type of content block.
-     * Can be 'text', 'image_url', 'video_url', 'audio_url', or 'file_url'.
+     * Can be 'text', 'image_url', 'video_url', 'audio_url', 'file_url', or 'tool_result'.
      */
-    type: 'text' | 'image_url' | 'video_url' | 'audio_url' | 'file_url';
+    type: 'text' | 'image_url' | 'video_url' | 'audio_url' | 'file_url' | 'tool_result';
     /**
      * The content of the block.
      * This can be a string. In the case of 'image_url', 'video_url', 'audio_url', or 'file_url', it should be a URL to the resource, OR it can be a base64 encoded string.
      * representing the content of the item. For base64 images, use the data URL format: data:image/png;base64,<data>
+     * For 'tool_result', this is the result payload the model should see — stringify non-text results.
      */
     content: string;
+    /**
+     * For 'tool_result' blocks: the {@link ChatToolCall.id} this block answers. Required on
+     * 'tool_result'; providers use it to pair a result with the call that requested it.
+     */
+    toolCallId?: string;
+    /**
+     * For 'tool_result' blocks: the name of the tool that was called. Optional — carried for
+     * providers (and logs) that key results by name rather than id.
+     */
+    toolName?: string;
+    /**
+     * For 'tool_result' blocks: whether the result represents a FAILED tool execution. Providers
+     * that model this natively (Anthropic's `is_error`) get it mapped through; others receive the
+     * error text as an ordinary result.
+     */
+    isError?: boolean;
     /**
      * Optional MIME type for media content (e.g., 'image/png', 'image/jpeg', 'audio/mp3').
      * When content is a data URL, this can be extracted from the URL. When content is raw base64, this field is required.
@@ -50,6 +74,91 @@ export type ChatMessageContentBlock = {
  * Union type for the content of a chat message.
  */
 export type ChatMessageContent = string | ChatMessageContentBlock[];
+/**
+ * A single tool made available to the model for this request.
+ *
+ * Provider-neutral by design: every major vendor declares tool parameters as JSON Schema with
+ * per-property `description` strings, so that is the interchange format here — `input_schema`
+ * (Anthropic), `parameters` (OpenAI), `parameters` / `parametersJsonSchema` (Gemini).
+ */
+export interface ChatTool {
+    /**
+     * The tool's name, as the model will call it. Providers constrain this to `[a-zA-Z0-9_-]`,
+     * 64 characters or fewer; callers building tools from names that can contain other characters
+     * (MJ Action names, say) must sanitize deterministically and keep a reverse map.
+     */
+    name: string;
+    /**
+     * What the tool does and — more importantly for call accuracy — WHEN the model should call it.
+     * Prescriptive phrasing ("Call this when…") measurably outperforms a bare description.
+     */
+    description?: string;
+    /**
+     * JSON Schema for the tool's input. Stick to the cross-provider common subset — `type`,
+     * `description`, `enum`, `items`, `properties`, `required` — because Gemini's classic
+     * function-declaration schema is an OpenAPI subset that rejects keywords like
+     * `additionalProperties`. Drivers adapt anything beyond that subset.
+     */
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * Controls how the model may use the tools declared for this request.
+ *
+ * - `'auto'` — the model decides whether to call a tool. The default whenever tools are present.
+ * - `'none'` — tools stay declared (and cached) but the model must not call one this turn. The
+ *   way to force a prose/JSON answer without changing the cached tool block.
+ * - `'required'` — the model must call some tool.
+ * - `{ name }` — the model must call the named tool.
+ *
+ * Forcing a call typically SUPPRESSES text output, and Anthropic additionally disables extended
+ * thinking under a forced tool choice — never assume text accompanies a forced call.
+ */
+export type ChatToolChoice = 'auto' | 'none' | 'required' | {
+    name: string;
+};
+/**
+ * One tool call the model asked for, normalized across providers.
+ */
+export interface ChatToolCall {
+    /**
+     * The provider's call id, echoed back on the matching `tool_result` block so the provider can
+     * pair result to call. Drivers synthesize a stable id for providers that do not supply one
+     * (Gemini names calls rather than identifying them).
+     */
+    id: string;
+    /** The tool name the model called — matches a {@link ChatTool.name} that was declared. */
+    name: string;
+    /**
+     * The call arguments, already PARSED. Providers that transmit arguments as a JSON string
+     * (OpenAI) parse them in the driver, so consumers never see a string here.
+     */
+    arguments: Record<string, unknown>;
+    /**
+     * Opaque provider data that must travel with the call when it is replayed into history.
+     * Gemini 3 attaches a `thoughtSignature` to each function-call part and rejects a replayed call
+     * that lacks it (HTTP 400); the driver stores it here on the way in and
+     * sends it back on the way out. Other providers leave this undefined. Never read by the loop.
+     */
+    providerMetadata?: Record<string, unknown>;
+}
+/**
+ * The normalized `finish_reason` a driver reports when the model ended its turn by calling one or
+ * more tools. Consumers branch on this rather than on any provider-specific stop reason.
+ *
+ * This is currently the ONLY normalized value: every other `finish_reason` is whatever the driver's
+ * SDK returned (`'stop'`, `"completed"`, `"STOP"`, …). Normalizing the rest is tracked in
+ * MemberJunction/MJ#4335, which must preserve unrecognized values rather than map onto a closed
+ * union — a shipped action overloads the field as a channel selector.
+ */
+export declare const CHAT_FINISH_REASON_TOOL_CALLS = "tool_calls";
+/**
+ * The normalized `finish_reason` a driver reports when the model tried to call a tool but the call
+ * could not be read — Gemini's `MALFORMED_FUNCTION_CALL`, typically an oversized or syntactically
+ * broken argument object. The turn then carries whatever text preceded the broken call and NO
+ * `toolCalls`, so without this marker a consumer reads leftover narration as the model's answer.
+ * The agent loop turns it into a corrective retry.
+ */
+export declare const CHAT_FINISH_REASON_MALFORMED_TOOL_CALL = "malformed_tool_call";
 /**
  * Defines the shape of an individual chat message.
  *
@@ -71,6 +180,15 @@ export type ChatMessage<M = any> = {
      * the core ChatMessage type.
      */
     metadata?: M;
+    /**
+     * For `assistant` turns that called tools: the calls the model made, so a prior tool-calling
+     * turn round-trips back to the provider on the next request. Every provider requires the
+     * assistant's own call turn to be present in history before the matching results.
+     *
+     * Set this from {@link ChatCompletionMessage.toolCalls} when appending the model's reply to
+     * the conversation; the `tool` turn that answers it follows immediately.
+     */
+    toolCalls?: ChatToolCall[];
 };
 /**
  * Defines the shape of an individual message from the model in response to a chat completion request.
@@ -89,6 +207,17 @@ export type ChatCompletionMessage = {
      * Not all providers/models support this field.
      */
     thinking?: string | null;
+    /**
+     * Tool calls the model made on this turn, normalized across providers. Absent or empty when
+     * the model did not call a tool.
+     *
+     * A turn can carry BOTH `content` and `toolCalls` — the tool-capable providers structurally
+     * allow it (Anthropic `text` + `tool_use` blocks, OpenAI nullable `content` alongside
+     * `tool_calls`, Gemini `text` + `functionCall` parts) — so this is never an either/or with
+     * `content`. Equally, nothing downstream may assume `content` is non-empty on a tool-call
+     * turn: a forced {@link ChatToolChoice} usually suppresses text entirely.
+     */
+    toolCalls?: ChatToolCall[];
 };
 /**
  * Interface for streaming chat completion callbacks
@@ -235,6 +364,26 @@ export declare class ChatParams extends BaseParams {
      * Typically ranges from 2-20, depending on the provider.
      */
     topLogProbs?: number;
+    /**
+     * Tool declarations for this request. When present and the driver reports
+     * `SupportsTools === true`, these are passed to the provider's native tool-calling API.
+     *
+     * A driver with `SupportsTools === false` IGNORES this and notes the fact in
+     * `modelSpecificResponseDetails` — the prompt runner's capability gate should mean that never
+     * happens, but Layer 2 stays safe on its own.
+     */
+    tools?: ChatTool[];
+    /**
+     * How the model may use {@link ChatParams.tools}. Ignored when no tools are declared.
+     * Defaults to the provider's own default (`'auto'`) when omitted.
+     */
+    toolChoice?: ChatToolChoice;
+    /**
+     * Whether the model may emit several tool calls in a single turn. Omit to accept the
+     * provider's default (parallel calls allowed). Maps to OpenAI `parallel_tool_calls` and
+     * Anthropic `tool_choice.disable_parallel_tool_use`.
+     */
+    parallelToolCalls?: boolean;
 }
 /**
  * Returns the first user message from the chat params
@@ -391,6 +540,57 @@ export declare function hasImageContent(content: ChatMessageContent): boolean;
  * @returns A plain text string with all text blocks joined
  */
 export declare function getTextFromContent(content: ChatMessageContent): string;
+/**
+ * Validates that every tool result in a conversation answers a tool call the model actually made.
+ *
+ * The contract providers enforce: a `tool_result` is only meaningful next to the assistant turn
+ * whose `tool_use` / `tool_calls` it answers. The easy way to break it is to append the model's
+ * reply to the conversation WITHOUT copying {@link ChatCompletionMessage.toolCalls} onto the
+ * assistant {@link ChatMessage}, then append the results — the calls vanish and the results are
+ * orphaned. Anthropic rejects that outright, and the provider's own error names an opaque id rather
+ * than the mistake, so this catches it at the MJ boundary with a message that says what to fix.
+ *
+ * Only runs where it can find a problem: conversations with no tool turns are untouched.
+ *
+ * @param messages The conversation to check
+ * @throws Error naming the unmatched tool-call ids and how to fix the history
+ */
+export declare function validateToolConversation(messages: ChatMessage[]): void;
+/**
+ * Collapses an MJ role onto the three roles every chat API understands.
+ *
+ * `tool` becomes `user`, which is how a tool result reads to a provider with no tool support — the
+ * user handing the model some text. Drivers that DO implement tools must not use this for `tool`
+ * turns; they map those onto their SDK's own tool-result shape.
+ *
+ * @param role The MJ message role
+ * @returns The equivalent classic role
+ */
+export declare function toClassicChatMessageRole(role: ChatMessageRole): 'system' | 'user' | 'assistant';
+/**
+ * Extracts the `tool_result` blocks from a message's content, ignoring everything else.
+ * Returns an empty array for plain-string content.
+ *
+ * @param content The message content to inspect
+ * @returns The tool-result blocks, in order
+ */
+export declare function getToolResultBlocks(content: ChatMessageContent): ChatMessageContentBlock[];
+/**
+ * Builds the `tool` turn that answers one or more tool calls.
+ *
+ * Providers require the results for a given assistant turn's calls to arrive TOGETHER, in the
+ * single turn that immediately follows it — so pass every result for that turn in one call rather
+ * than appending a message per result.
+ *
+ * @param results One entry per tool call being answered
+ * @returns A `tool`-role message whose content is the corresponding `tool_result` blocks
+ */
+export declare function createToolResultMessage(results: Array<{
+    toolCallId: string;
+    toolName?: string;
+    content: string;
+    isError?: boolean;
+}>): ChatMessage;
 /**
  * Parses a base64 data URL into its components.
  *

package/dist/generic/chat.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat.types.d.ts","sourceRoot":"","sources":["../../src/generic/chat.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chat.types.d.ts","sourceRoot":"","sources":["../../src/generic/chat.types.ts"],"names":[],"mappings":"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"}

package/dist/generic/chat.types.js

@@ -1,12 +1,37 @@
 import { BaseParams, BaseResult } from "./baseModel.js";
 /**
  * The possible roles for a chat message.
+ *
+ * `tool` carries the RESULT of a native tool call back to the model and is only ever produced
+ * alongside a preceding `assistant` turn whose {@link ChatMessage.toolCalls} it answers. Its
+ * content is one or more `tool_result` {@link ChatMessageContentBlock}s. Drivers that do not
+ * implement tools (`BaseLLM.SupportsTools === false`) map it to `user` like any other non-assistant
+ * role, so an unsupported driver degrades to prose rather than erroring.
  */
 export const ChatMessageRole = {
     system: 'system',
     user: 'user',
-    assistant: 'assistant'
+    assistant: 'assistant',
+    tool: 'tool'
 };
+/**
+ * The normalized `finish_reason` a driver reports when the model ended its turn by calling one or
+ * more tools. Consumers branch on this rather than on any provider-specific stop reason.
+ *
+ * This is currently the ONLY normalized value: every other `finish_reason` is whatever the driver's
+ * SDK returned (`'stop'`, `"completed"`, `"STOP"`, …). Normalizing the rest is tracked in
+ * MemberJunction/MJ#4335, which must preserve unrecognized values rather than map onto a closed
+ * union — a shipped action overloads the field as a channel selector.
+ */
+export const CHAT_FINISH_REASON_TOOL_CALLS = 'tool_calls';
+/**
+ * The normalized `finish_reason` a driver reports when the model tried to call a tool but the call
+ * could not be read — Gemini's `MALFORMED_FUNCTION_CALL`, typically an oversized or syntactically
+ * broken argument object. The turn then carries whatever text preceded the broken call and NO
+ * `toolCalls`, so without this marker a consumer reads leftover narration as the model's answer.
+ * The agent loop turns it into a corrective retry.
+ */
+export const CHAT_FINISH_REASON_MALFORMED_TOOL_CALL = 'malformed_tool_call';
 export class ChatParams extends BaseParams {
     constructor() {
         super(...arguments);
@@ -130,6 +155,94 @@ export function getTextFromContent(content) {
         .map(block => block.content)
         .join('\n');
 }
+/**
+ * Validates that every tool result in a conversation answers a tool call the model actually made.
+ *
+ * The contract providers enforce: a `tool_result` is only meaningful next to the assistant turn
+ * whose `tool_use` / `tool_calls` it answers. The easy way to break it is to append the model's
+ * reply to the conversation WITHOUT copying {@link ChatCompletionMessage.toolCalls} onto the
+ * assistant {@link ChatMessage}, then append the results — the calls vanish and the results are
+ * orphaned. Anthropic rejects that outright, and the provider's own error names an opaque id rather
+ * than the mistake, so this catches it at the MJ boundary with a message that says what to fix.
+ *
+ * Only runs where it can find a problem: conversations with no tool turns are untouched.
+ *
+ * @param messages The conversation to check
+ * @throws Error naming the unmatched tool-call ids and how to fix the history
+ */
+export function validateToolConversation(messages) {
+    const declaredCallIds = new Set();
+    const orphaned = [];
+    for (const message of messages) {
+        // Assistant turns declare ids; results may only reference ids declared BEFORE them, so the
+        // two are collected in a single forward pass.
+        if (message.role === ChatMessageRole.assistant) {
+            for (const call of message.toolCalls ?? []) {
+                declaredCallIds.add(call.id);
+            }
+            continue;
+        }
+        for (const block of getToolResultBlocks(message.content)) {
+            if (!block.toolCallId || !declaredCallIds.has(block.toolCallId)) {
+                orphaned.push(block.toolCallId ?? '(missing toolCallId)');
+            }
+        }
+    }
+    if (orphaned.length > 0) {
+        throw new Error(`Tool result(s) with no matching tool call in the conversation: ${orphaned.join(', ')}. ` +
+            `Every tool_result must answer a call declared by an EARLIER assistant message — set ` +
+            `ChatMessage.toolCalls from the model's ChatCompletionMessage.toolCalls when you append ` +
+            `its reply, before appending the results.`);
+    }
+}
+/**
+ * Collapses an MJ role onto the three roles every chat API understands.
+ *
+ * `tool` becomes `user`, which is how a tool result reads to a provider with no tool support — the
+ * user handing the model some text. Drivers that DO implement tools must not use this for `tool`
+ * turns; they map those onto their SDK's own tool-result shape.
+ *
+ * @param role The MJ message role
+ * @returns The equivalent classic role
+ */
+export function toClassicChatMessageRole(role) {
+    return role === ChatMessageRole.tool ? ChatMessageRole.user : role;
+}
+/**
+ * Extracts the `tool_result` blocks from a message's content, ignoring everything else.
+ * Returns an empty array for plain-string content.
+ *
+ * @param content The message content to inspect
+ * @returns The tool-result blocks, in order
+ */
+export function getToolResultBlocks(content) {
+    if (typeof content === 'string') {
+        return [];
+    }
+    return content.filter(block => block.type === 'tool_result');
+}
+/**
+ * Builds the `tool` turn that answers one or more tool calls.
+ *
+ * Providers require the results for a given assistant turn's calls to arrive TOGETHER, in the
+ * single turn that immediately follows it — so pass every result for that turn in one call rather
+ * than appending a message per result.
+ *
+ * @param results One entry per tool call being answered
+ * @returns A `tool`-role message whose content is the corresponding `tool_result` blocks
+ */
+export function createToolResultMessage(results) {
+    return {
+        role: ChatMessageRole.tool,
+        content: results.map(r => ({
+            type: 'tool_result',
+            content: r.content,
+            toolCallId: r.toolCallId,
+            toolName: r.toolName,
+            isError: r.isError
+        }))
+    };
+}
 /**
  * Parses a base64 data URL into its components.
  *

package/dist/generic/chat.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"chat.types.js","sourceRoot":"","sources":["../../src/generic/chat.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chat.types.js","sourceRoot":"","sources":["../../src/generic/chat.types.ts"],"names":[],"mappings":"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"}

package/dist/generic/modelConfiguration.d.ts

@@ -1,9 +1,8 @@
 /**
- * The canonical `ModelConfiguration` shape + the pure cascade resolver.
+ * The canonical AI configuration shapes + the pure cascade resolvers.
  *
- * `ModelConfiguration` is a JSONType `nvarchar(max)` column that exists at THREE levels of the
- * model catalog, forming an inherit-with-override cascade (the structured generalization of the
- * scalar `SupportsPrefill` / `PrefillFallbackText` cascade those same three entities already carry):
+ * The AI stack carries `nvarchar(max)` JSONType configuration bags at five levels, in two cascades.
+ * The MODEL CATALOG cascade describes the model:
  *
  * ```
  * MJ: AI Model Types . ModelConfiguration     (type-wide default — e.g. every Realtime model)
@@ -11,18 +10,29 @@
  *     < MJ: AI Model Vendors . ModelConfiguration   (per model-on-this-provider — the winner)
  * ```
  *
- * **Lockstep contract**: this interface is the package-side mirror of
- * `metadata/entities/JSONType-interfaces/IAIModelConfiguration.ts`, which is pushed into
- * `EntityField.JSONTypeDefinition` and drives the CodeGen-generated `ModelConfigurationObject`
- * accessors on the three entities. Keep the two in step when adding a section or property —
- * the same pact `IAgentSettings` follows with `@memberjunction/ai-core-plus`.
+ * The PROMPT cascade describes what a given prompt asks for, and layers on top of the catalog:
+ *
+ * ```
+ * MJ: AI Prompts . PromptConfiguration        (per-prompt)
+ *   < MJ: AI Prompt Models . PromptConfiguration  (per prompt-on-this-model — the winner)
+ * ```
+ *
+ * Both compose the SAME per-modality section types ({@link LLMConfigurationSettings},
+ * {@link RealtimeConfigurationSettings}, …) — one definition of what "the LLM configuration" means,
+ * reused at every layer. Only the outer per-table type differs.
+ *
+ * **Lockstep contract**: these interfaces mirror
+ * `metadata/entities/JSONType-interfaces/IAIConfiguration.ts`, which is pushed into
+ * `EntityField.JSONTypeDefinition` and drives the CodeGen-generated `ModelConfigurationObject` /
+ * `PromptConfigurationObject` accessors on the five entities. Keep the two in step when adding a section
+ * or property — the same pact `IAgentSettings` follows with `@memberjunction/ai-core-plus`.
  *
  * **Boundary rule** (also documented on the metadata interface): anything the engine filters,
  * sorts, or joins on stays a COLUMN (`PowerRank`, `IsActive`, `Priority`, `Status` — SQL cannot
- * cheaply predicate into this bag); anything a driver consumes at session/call time belongs HERE.
- * New capability knobs go in this bag — do not add a new capability column per knob.
+ * cheaply predicate into this bag); anything a driver or runner consumes at call time belongs HERE.
+ * New capability knobs go in the bag — do not add a capability column per knob. A knob graduates to
+ * a real column when it needs a foreign key or becomes a first-class platform concept.
  */
-import { JSONObject } from './baseRealtime.js';
 /**
  * MJ-normalized turn-detection mode vocabulary — provider-neutral by design so a shared model
  * catalog is safe on every provider:
@@ -53,40 +63,145 @@ export interface RealtimeTurnDetectionSettings {
     /** Server-VAD trailing-silence duration in ms; ignored by profiles without a mapping. */
     SilenceDurationMs?: number;
 }
-/** The `Realtime` section of {@link AIModelConfiguration} — knobs the realtime drivers consume. */
-export interface RealtimeModelConfigurationSection {
+/**
+ * Which plane handles reasoning during a realtime session:
+ * - `'local'` — the application/agent loop handles reasoning, Actions, and tool results (MJ default).
+ * - `'remote'` — the model delegates reasoning to a remote model or hosted agent backend.
+ */
+export type RealtimeReasoningPlane = 'local' | 'remote';
+/**
+ * Configuration for remote reasoning delegation.
+ */
+export interface RealtimeRemoteReasoning {
+    /** What the remote reference denotes. `model` = Live/Inworld; `hostedAgent` = ElevenLabs. */
+    Kind?: 'model' | 'hostedAgent';
+    /** 'gpt-5.6-terra' | 'anthropic/claude-sonnet-4-6' | 'MJ Realtime Co-Agent'. */
+    Ref?: string;
+    /** Reasoning effort level for supported models. */
+    Effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+    /** Maximum output tokens for the remote reasoning pass. */
+    MaxOutputTokens?: number;
+}
+/**
+ * Realtime reasoning settings controlling dual delegation.
+ */
+export interface RealtimeReasoningSettings {
+    /** Absent = 'local'. Session-creation-time only — NOT runtime-switchable. */
+    Plane?: RealtimeReasoningPlane;
+    /** Remote reasoning target when Plane is 'remote'. */
+    Remote?: RealtimeRemoteReasoning;
+}
+/** The `Realtime` section — knobs the realtime drivers consume. */
+export interface RealtimeConfigurationSettings {
     /**
      * Catalog-level turn-detection default for this model. Folded into the session Config bag as
      * the `turnDetection` key BELOW the agent/app config cascade (`realtime.session.turnDetection`)
      * and the runtime override — the catalog supplies the default, agents/apps/callers refine it.
      */
-    TurnDetection?: RealtimeTurnDetectionSettings;
+    TurnDetection?: RealtimeTurnDetectionSettings | null;
+    /**
+     * Reasoning plane settings — dual delegation configuration.
+     * Absent defaults to 'local'.
+     */
+    Reasoning?: RealtimeReasoningSettings;
 }
 /**
- * The `LLM` section of {@link AIModelConfiguration}. Reserved — no consumers yet. Candidate
- * contents: per-model effort-level defaults, response-format quirks, tool-calling behavior flags.
- * Existing capability COLUMNS (`SupportsEffortLevel`, `SupportsStreaming`, …) are NOT migrating
- * here — new knobs only (see the boundary rule in the module docstring).
+ * The `LLM` section — knobs the LLM drivers and the prompt runner consume at call time.
+ *
+ * Every flag here is TRI-STATE (`boolean | null | absent`), and the three differ. The cascade
+ * REPLACES on any explicit value (including `null`) and only skips a layer that OMITS the property.
+ * So absent means "inherit", while an explicit value at a higher layer overrides a lower one even
+ * when that value is `false`.
+ *
+ * Properties are marked with the layers that HONOR them. Setting one at a layer that does not honor
+ * it is inert rather than an error — deliberate tolerance, so a knob can move between layers
+ * without a schema change.
+ *
+ * Deliberately NO index signature: this interface must stay structurally identical to the JSONType
+ * source, because CodeGen emits per-entity copies of that source and runtime code assigns those
+ * generated types straight into this one. An index signature here (and not there) makes the two
+ * incompatible. Unknown keys in stored JSON still round-trip fine at runtime — the parse is
+ * tolerant; what is lost is only a compile-time affordance nothing needs.
  */
-export interface LLMModelConfigurationSection {
-    /** Open extension point until the first typed knob lands. */
+export interface LLMConfigurationSettings {
+    /**
+     * **Catalog layers only.** Whether this model — or this vendor's serving of it — supports native
+     * tool/function calling. CAPABILITY flag, and a hard gate: no policy or preference at any layer
+     * can force tools onto a (model, vendor) whose resolved value is not true.
+     *
+     * Set `false` only for a model or serving path verified NOT to support tools; leave absent when
+     * support is unknown, because absent is the honest value and it inherits.
+     */
+    SupportsNativeToolCalling?: boolean | null;
+    /**
+     * **Catalog layers only.** Whether prompts run against this model default to native tool calling
+     * when they express no preference of their own. POLICY flag — subordinate to
+     * {@link LLMConfigurationSettings.SupportsNativeToolCalling}.
+     */
+    DefaultToNativeToolCalling?: boolean | null;
+    /**
+     * **Prompt layers only.** Whether THIS prompt asks for native tool calling. PREFERENCE — it
+     * outranks the catalog's `DefaultToNativeToolCalling` and is still subordinate to the capability
+     * gate. Absent means "no preference; fall through to the model's default".
+     */
+    UseNativeToolCalling?: boolean | null;
+    /**
+     * **Catalog layers only.** How control flow is expressed when a request resolves to native tool
+     * calling. `'envelope'` (the default when absent) is the hybrid: Actions are tools, everything
+     * else — completion, chat, delegation, payload changes — is the JSON envelope. `'implicit'` is the
+     * implicit protocol: sub-agents, `payload_change_request` and `ask_user` are tools too, a tool call
+     * continues the loop, and plain text with no call ends the turn as task completion. Consulted only
+     * when the gate resolves native; subordinate to {@link LLMConfigurationSettings.SupportsNativeToolCalling}.
+     */
+    NativeControlFlow?: 'envelope' | 'implicit' | null;
+    /**
+     * **Catalog layers only.** Whether action results are returned to the model as native tool-result
+     * turns instead of a markdown "Action results" user message. Absent means `false`. Consulted
+     * only when the gate resolves native.
+     */
+    NativeToolResults?: boolean | null;
+}
+/** Vision knobs. Reserved — no consumers yet. */
+export interface VisionConfigurationSettings {
+    [key: string]: unknown;
+}
+/** Audio (TTS/STT) knobs. Reserved — no consumers yet. */
+export interface AudioConfigurationSettings {
     [key: string]: unknown;
 }
 /**
- * The per-modality model-configuration bag stored (as JSON) in the `ModelConfiguration` column of
- * `MJ: AI Model Types`, `MJ: AI Models`, and `MJ: AI Model Vendors`. Sections are optional and
- * per-modality so one catalog row can configure everything its model does.
+ * The per-modality bag common to every AI configuration column. Sections are optional and
+ * per-modality so one row can configure everything the thing it describes does.
  */
-export interface AIModelConfiguration {
-    /** Text-generation knobs. Reserved. */
-    LLM?: LLMModelConfigurationSection;
-    /** Realtime (speech-to-speech) knobs — the first live section. */
-    Realtime?: RealtimeModelConfigurationSection;
+export interface AIConfigurationSections {
+    /** Text-generation knobs. */
+    LLM?: LLMConfigurationSettings | null;
+    /** Realtime (speech-to-speech) knobs. */
+    Realtime?: RealtimeConfigurationSettings | null;
     /** Vision knobs. Reserved. */
-    Vision?: JSONObject;
+    Vision?: VisionConfigurationSettings | null;
     /** Audio (TTS/STT) knobs. Reserved. */
-    Audio?: JSONObject;
+    Audio?: AudioConfigurationSettings | null;
 }
+/**
+ * The `ModelConfiguration` column on `MJ: AI Model Types`, `MJ: AI Models` and
+ * `MJ: AI Model Vendors` — the model-catalog cascade.
+ */
+export type AIModelConfiguration = AIConfigurationSections;
+/**
+ * The `PromptConfiguration` column on `MJ: AI Prompts` — per-prompt call-time knobs, layered on top of
+ * the resolved model-catalog configuration by the prompt runner.
+ */
+export type AIPromptConfiguration = AIConfigurationSections;
+/**
+ * The `PromptConfiguration` column on `MJ: AI Prompt Models` — the most specific layer, overriding both
+ * the prompt's own bag and the model catalog for this one (prompt, model) pairing.
+ */
+export type AIPromptModelConfiguration = AIConfigurationSections;
+/** @deprecated Renamed to {@link RealtimeConfigurationSettings}; the sections are shared now. */
+export type RealtimeModelConfigurationSection = RealtimeConfigurationSettings;
+/** @deprecated Renamed to {@link LLMConfigurationSettings}; the sections are shared now. */
+export type LLMModelConfigurationSection = LLMConfigurationSettings;
 /**
  * TOLERANTLY parses one `ModelConfiguration` column value. Returns `null` — never throws — for
  * absent, blank, malformed, or non-object payloads, so a bad catalog row contributes nothing to