deepline 0.1.140 → 0.1.142

package/dist/bundling-sources/apps/play-runner-workers/src/coordinator-entry.ts

@@ -65,6 +65,11 @@ import {
 } from './workflow-retry-state';
 import { createOrAttachWorkflowInstance } from './workflow-instance-create';
 import { sanitizeLiveLogLines } from './runtime/live-progress';
+import {
+  DURABLE_OBJECT_DEPLOY_HANDOFF_RETRY_DELAYS_MS,
+  durableObjectDeployHandoffMessage,
+  sleepForDurableObjectDeployHandoffRetry,
+} from './durable-object-deploy-handoff';
 
 export { DynamicWorkflowBinding };
 
@@ -784,24 +789,58 @@ async function callRunScopedControl<T>(
   path: string,
   init?: RequestInit,
 ): Promise<T> {
-  const response = await runScopedDurableObject(env, runId).fetch(
-    `https://deepline.run-state.internal${path}`,
-    {
-      ...(init ?? {}),
-      headers: {
-        'content-type': 'application/json',
-        ...(init?.headers ?? {}),
-      },
-    },
-  );
-  if (!response.ok) {
+  const maxAttempts = DURABLE_OBJECT_DEPLOY_HANDOFF_RETRY_DELAYS_MS.length + 1;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    let response: Response;
+    try {
+      response = await runScopedDurableObject(env, runId).fetch(
+        `https://deepline.run-state.internal${path}`,
+        {
+          ...(init ?? {}),
+          headers: {
+            'content-type': 'application/json',
+            ...(init?.headers ?? {}),
+          },
+        },
+      );
+    } catch (error) {
+      const handoffMessage = durableObjectDeployHandoffMessage(error);
+      if (handoffMessage && attempt < maxAttempts) {
+        console.warn('[coordinator] run state DO deploy handoff retry', {
+          runId,
+          path,
+          attempt,
+          error: handoffMessage,
+        });
+        await sleepForDurableObjectDeployHandoffRetry(attempt - 1);
+        continue;
+      }
+      throw error;
+    }
+
+    if (response.ok) {
+      return (await response.json()) as T;
+    }
+
+    const responseText = (await response.text().catch(() => '')).slice(0, 400);
+    const handoffMessage = durableObjectDeployHandoffMessage(responseText);
+    if (handoffMessage && attempt < maxAttempts) {
+      console.warn('[coordinator] run state DO deploy handoff retry', {
+        runId,
+        path,
+        attempt,
+        status: response.status,
+        error: handoffMessage,
+      });
+      await sleepForDurableObjectDeployHandoffRetry(attempt - 1);
+      continue;
+    }
+
     throw new Error(
-      `run state ${path} failed ${response.status}: ${(
-        await response.text().catch(() => '')
-      ).slice(0, 400)}`,
+      `run state ${path} failed ${response.status}: ${responseText}`,
     );
   }
-  return (await response.json()) as T;
+  throw new Error(`run state ${path} failed after deploy handoff retries`);
 }
 
 async function recordWorkflowInstanceId(input: {

package/dist/bundling-sources/apps/play-runner-workers/src/durable-object-deploy-handoff.ts

@@ -0,0 +1,24 @@
+export const DURABLE_OBJECT_DEPLOY_HANDOFF_STORAGE_ERROR =
+  "The Durable Object's code has been updated, this version can no longer access storage";
+
+export const DURABLE_OBJECT_DEPLOY_HANDOFF_RETRY_DELAYS_MS = [50, 150, 350];
+
+export function durableObjectDeployHandoffMessage(
+  value: unknown,
+): string | null {
+  const message = value instanceof Error ? value.message : String(value ?? '');
+  return message.includes(DURABLE_OBJECT_DEPLOY_HANDOFF_STORAGE_ERROR)
+    ? message
+    : null;
+}
+
+export async function sleepForDurableObjectDeployHandoffRetry(
+  attemptIndex: number,
+): Promise<void> {
+  const delayMs =
+    DURABLE_OBJECT_DEPLOY_HANDOFF_RETRY_DELAYS_MS[attemptIndex] ??
+    DURABLE_OBJECT_DEPLOY_HANDOFF_RETRY_DELAYS_MS[
+      DURABLE_OBJECT_DEPLOY_HANDOFF_RETRY_DELAYS_MS.length - 1
+    ];
+  await new Promise((resolve) => setTimeout(resolve, delayMs));
+}

package/dist/bundling-sources/apps/play-runner-workers/src/entry.ts

@@ -76,6 +76,12 @@ import {
   type ToolExecuteResult,
   type ToolResultMetadataInput,
 } from '../../../shared_libs/play-runtime/tool-result';
+import {
+  TOOL_EXECUTE_RATE_LIMIT_MAX_ATTEMPTS,
+  TOOL_EXECUTE_TRANSPORT_MAX_ATTEMPTS,
+  TOOL_EXECUTE_TRANSPORT_RETRY_DELAY_MS,
+  decideToolExecuteHttpRetry,
+} from '../../../shared_libs/play-runtime/tool-execute-retry-policy';
 import type { PlayCallGovernanceSnapshot } from '../../../shared_libs/play-runtime/scheduler-backend';
 import type { PreloadedRuntimeDbSession } from '../../../shared_libs/play-runtime/db-session';
 import type { PlayRuntimeManifestMap } from '../../../shared_libs/plays/compiler-manifest';
@@ -1223,12 +1229,11 @@ async function callToolDirect(
 ): Promise<ToolExecuteResult> {
   const { id, toolId, input } = args;
   const path = `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`;
-  const maxAttempts = 3;
   let lastError: Error | null = null;
 
   for (
     let attempt = 1;
-    attempt <= WORKER_TOOL_RATE_LIMIT_MAX_ATTEMPTS;
+    attempt <= TOOL_EXECUTE_RATE_LIMIT_MAX_ATTEMPTS;
     attempt += 1
   ) {
     let res: Response;
@@ -1247,18 +1252,18 @@ async function callToolDirect(
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       lastError = new Error(
-        `Tool ${toolId} transport failed calling ${path} for run ${req.runId} on attempt ${attempt}/${WORKER_TOOL_TRANSPORT_MAX_ATTEMPTS}: ${message}`,
+        `Tool ${toolId} transport failed calling ${path} for run ${req.runId} on attempt ${attempt}/${TOOL_EXECUTE_TRANSPORT_MAX_ATTEMPTS}: ${message}`,
       );
       if (
-        attempt >= WORKER_TOOL_TRANSPORT_MAX_ATTEMPTS ||
+        attempt >= TOOL_EXECUTE_TRANSPORT_MAX_ATTEMPTS ||
         !isRetryableRuntimeApiError(error)
       ) {
         throw lastError;
       }
       onRetryAttempt?.();
-      const delayMs = WORKER_TOOL_TRANSPORT_RETRY_DELAY_MS * attempt;
+      const delayMs = TOOL_EXECUTE_TRANSPORT_RETRY_DELAY_MS * attempt;
       console.warn(
-        `[deepline-run:${req.runId}] tool transport retry tool=${toolId} path=${path} attempt=${attempt}/${WORKER_TOOL_TRANSPORT_MAX_ATTEMPTS} retryAfterMs=${delayMs} error=${redactSecretsFromLogString(message)}`,
+        `[deepline-run:${req.runId}] tool transport retry tool=${toolId} path=${path} attempt=${attempt}/${TOOL_EXECUTE_TRANSPORT_MAX_ATTEMPTS} retryAfterMs=${delayMs} error=${redactSecretsFromLogString(message)}`,
       );
       await sleepWorkerMs(delayMs);
       continue;
@@ -1276,18 +1281,25 @@ async function callToolDirect(
 
     const text = await res.text().catch(() => '');
     const isRateLimited = res.status === 429;
-    // Rate-limit pushback gets the larger 429-specific retry budget; every
-    // other failure keeps the generic 3-attempt budget.
-    const attemptCap = isRateLimited
-      ? WORKER_TOOL_RATE_LIMIT_MAX_ATTEMPTS
-      : maxAttempts;
+    const initialRetryDecision = decideToolExecuteHttpRetry({
+      toolId,
+      status: res.status,
+    });
     lastError = normalizeToolHttpErrorMessage({
       toolId,
       status: res.status,
       attempt,
-      maxAttempts: attemptCap,
+      maxAttempts: initialRetryDecision.attemptCap,
       bodyText: text,
     });
+    // Rate-limit pushback gets the larger 429-specific retry budget, unless the
+    // current response body is a hard Deepline billing denial.
+    const retryDecision = decideToolExecuteHttpRetry({
+      toolId,
+      status: res.status,
+      hardBillingFailure: isHardBillingToolHttpError(lastError),
+    });
+    const attemptCap = retryDecision.attemptCap;
     const retryAfterSeconds = Number(res.headers.get('retry-after'));
     const retryAfterMs =
       Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
@@ -1298,10 +1310,7 @@ async function callToolDirect(
       // final attempt so the (org, provider) bucket backs off across isolates.
       onProviderBackpressure?.(retryAfterMs > 0 ? retryAfterMs : 1_000);
     }
-    const retryable =
-      (isRateLimited && !isHardBillingToolHttpError(lastError)) ||
-      (res.status >= 500 && WORKER_RETRY_SAFE_5XX_TOOLS.has(toolId));
-    if (!retryable || attempt >= attemptCap) {
+    if (!retryDecision.retryable || attempt >= attemptCap) {
       throw lastError;
     }
     // Charge the retry budget per attempt, matching the cjs runner's
@@ -1490,7 +1499,6 @@ const MAP_ROW_FAILURE_SAMPLE_LIMIT = 3;
 // their previous batching behavior; declared providers tighten via the
 // Governor's suggestedParallelism.
 const WORKER_TOOL_BATCH_DEFAULT_PARALLELISM = 4;
-const WORKER_RETRY_SAFE_5XX_TOOLS = new Set(['test_transient_500']);
 /**
  * In-process retry budget for HTTP 429 tool responses. Rate-limit pushback is
  * throughput pacing (provider or Deepline limiter), not a tool defect, so it
@@ -1499,9 +1507,6 @@ const WORKER_RETRY_SAFE_5XX_TOOLS = new Set(['test_transient_500']);
  * throttling before the call fails. Every retry still charges the Governor's
  * retry budget, so a runaway storm stays bounded and loud.
  */
-const WORKER_TOOL_RATE_LIMIT_MAX_ATTEMPTS = 8;
-const WORKER_TOOL_TRANSPORT_MAX_ATTEMPTS = 3;
-const WORKER_TOOL_TRANSPORT_RETRY_DELAY_MS = 1_000;
 
 function sleepWorkerMs(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -2473,7 +2478,7 @@ async function postRuntimeEgressFetch(
   let lastError: Error | null = null;
   for (
     let attempt = 1;
-    attempt <= WORKER_TOOL_RATE_LIMIT_MAX_ATTEMPTS;
+    attempt <= TOOL_EXECUTE_RATE_LIMIT_MAX_ATTEMPTS;
     attempt += 1
   ) {
     const response = await fetchRuntimeApi(
@@ -2519,7 +2524,7 @@ async function postRuntimeEgressFetch(
         ? Math.ceil(retryAfterSeconds * 1000)
         : 1_000;
     onProviderBackpressure?.(retryAfterMs);
-    if (attempt >= WORKER_TOOL_RATE_LIMIT_MAX_ATTEMPTS) {
+    if (attempt >= TOOL_EXECUTE_RATE_LIMIT_MAX_ATTEMPTS) {
       throw lastError;
     }
     onRetryAttempt?.();
@@ -3943,6 +3948,13 @@ function createMinimalWorkerCtx(
           {
             completed: completedRowsForProgress(),
             total: progressTotalRows,
+            startedRows: startedExecutedRows,
+            activeRows: activeExecutedRows,
+            waitingRows: Math.max(
+              0,
+              rowsToExecute.length - startedExecutedRows,
+            ),
+            completedRows: completedExecutedRows,
             startedAt: mapStartedAt,
             message: formatMapExecutionHeartbeatMessage({
               rowsToExecute: rowsToExecute.length,
@@ -6147,6 +6159,18 @@ async function executeRunRequest(
           ...(typeof progress.failed === 'number'
             ? { failed: progress.failed }
             : {}),
+          ...(typeof progress.startedRows === 'number'
+            ? { startedRows: progress.startedRows }
+            : {}),
+          ...(typeof progress.activeRows === 'number'
+            ? { activeRows: progress.activeRows }
+            : {}),
+          ...(typeof progress.waitingRows === 'number'
+            ? { waitingRows: progress.waitingRows }
+            : {}),
+          ...(typeof progress.completedRows === 'number'
+            ? { completedRows: progress.completedRows }
+            : {}),
           ...(typeof progress.message === 'string' && progress.message
             ? { message: progress.message }
             : {}),

package/dist/bundling-sources/apps/play-runner-workers/src/runtime/live-progress.ts

@@ -2,6 +2,10 @@ export type LiveNodeProgressSnapshot = {
   completed?: number;
   total?: number;
   failed?: number;
+  startedRows?: number;
+  activeRows?: number;
+  waitingRows?: number;
+  completedRows?: number;
   message?: string;
   updatedAt?: number;
   startedAt?: number;

package/dist/bundling-sources/apps/play-runner-workers/src/runtime/tool-http-errors.ts

@@ -1,262 +1,7 @@
-export class ToolHttpError extends Error {
-  readonly billing: Record<string, unknown> | null;
-  /** HTTP status of the failed tool-execute response (e.g. 429, 502). */
-  readonly status: number;
-
-  constructor(
-    message: string,
-    billing: Record<string, unknown> | null,
-    status: number,
-  ) {
-    super(message);
-    this.name = 'ToolHttpError';
-    this.billing = billing;
-    this.status = status;
-  }
-}
-
-function formatCreditAmount(value: unknown): string {
-  if (typeof value !== 'number' || !Number.isFinite(value)) {
-    return String(value ?? '-');
-  }
-  return Number(value.toFixed(8)).toString();
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
-function getStringField(value: unknown, key: string): string | null {
-  if (!isRecord(value)) return null;
-  const field = value[key];
-  return typeof field === 'string' && field.trim() ? field : null;
-}
-
-function getObjectField(
-  value: unknown,
-  key: string,
-): Record<string, unknown> | null {
-  if (!isRecord(value)) return null;
-  const field = value[key];
-  return isRecord(field) ? field : null;
-}
-
-function isInsufficientCreditsBilling(
-  billing: Record<string, unknown> | null,
-): billing is Record<string, unknown> {
-  return billing?.kind === 'insufficient_credits';
-}
-
-function isHardBillingFailurePayload(
-  payload: Record<string, unknown> | null,
-): payload is Record<string, unknown> {
-  if (!payload) return false;
-  const category = String(
-    payload.error_category ?? payload.errorCategory ?? '',
-  ).toLowerCase();
-  const code = String(payload.code ?? payload.error_code ?? '').toUpperCase();
-  const message = String(
-    payload.error ?? payload.message ?? payload.failure_description ?? '',
-  ).toLowerCase();
-  if (category === 'billing') return true;
-  if (
-    code === 'INSUFFICIENT_CREDITS' ||
-    code === 'BILLING_CAP_EXCEEDED' ||
-    code === 'MONTHLY_BILLING_LIMIT_EXCEEDED'
-  ) {
-    return true;
-  }
-  return (
-    (message.includes('billing cap') ||
-      message.includes('monthly billing limit') ||
-      message.includes('rolling 30-day organization billing cap') ||
-      message.includes('insufficient credits')) &&
-    !message.includes('rate limit')
-  );
-}
-
-function normalizeHardBillingPayload(
-  payload: Record<string, unknown>,
-): Record<string, unknown> {
-  return {
-    kind: 'billing_cap_exceeded',
-    code:
-      typeof payload.code === 'string' && payload.code.trim()
-        ? payload.code
-        : 'MONTHLY_BILLING_LIMIT_EXCEEDED',
-    error_category: 'billing',
-    failure_origin:
-      typeof payload.failure_origin === 'string' &&
-      payload.failure_origin.trim()
-        ? payload.failure_origin
-        : 'deepline_billing',
-    message:
-      typeof payload.error === 'string' && payload.error.trim()
-        ? payload.error
-        : typeof payload.message === 'string' && payload.message.trim()
-          ? payload.message
-          : 'Deepline billing cap exceeded.',
-    ...payload,
-  };
-}
-
-function formatHardBillingFailureMessage(input: {
-  billing: Record<string, unknown>;
-  toolId: string;
-  status: number;
-  attempt: number;
-  maxAttempts: number;
-}): string {
-  const code = getStringField(input.billing, 'code');
-  const message =
-    getStringField(input.billing, 'message') ??
-    getStringField(input.billing, 'error') ??
-    'Deepline billing cap exceeded.';
-  return [
-    `tool ${input.toolId} ${input.status} attempt ${input.attempt}/${input.maxAttempts}:`,
-    'Deepline billing cap exceeded.',
-    'Run halted before marking remaining rows processed.',
-    code ? `code=${code}.` : '',
-    message,
-  ]
-    .filter(Boolean)
-    .join(' ');
-}
-
-function formatInsufficientCreditsMessage(input: {
-  billing: Record<string, unknown>;
-  toolId: string;
-}): string {
-  const operation =
-    getStringField(input.billing, 'operation_id') ??
-    getStringField(input.billing, 'operation') ??
-    input.toolId;
-  const balance = formatCreditAmount(input.billing.balance_credits);
-  const required = formatCreditAmount(input.billing.required_credits);
-  const recommended = formatCreditAmount(
-    input.billing.recommended_add_credits ?? input.billing.needed_credits,
-  );
-  const billingUrl = getStringField(input.billing, 'billing_url');
-  const addSuffix =
-    billingUrl && recommended !== '-'
-      ? ` Add >=${recommended} at ${billingUrl}.`
-      : billingUrl
-        ? ` Add credits at ${billingUrl}.`
-        : '';
-  return `Workspace balance ${balance} < required ${required} for ${operation}.${addSuffix}`;
-}
-
-function formatPublicToolErrorPayload(input: {
-  parsed: Record<string, unknown> | null;
-  bodyText: string;
-}): string {
-  if (!input.parsed) {
-    return input.bodyText.slice(0, 500);
-  }
-
-  const selected: Record<string, unknown> = {};
-  for (const key of [
-    'error',
-    'message',
-    'code',
-    'failure_origin',
-    'error_category',
-    'failure_description',
-    'operator_hint',
-    'failure_hint',
-    'details',
-    'provider',
-    'operation',
-    'request_id',
-    'requestId',
-    'credential_source',
-    'credential_owner',
-  ]) {
-    const value = input.parsed[key];
-    if (typeof value === 'string' && value.trim()) {
-      selected[key] = value;
-    }
-  }
-
-  return JSON.stringify(
-    Object.keys(selected).length > 0 ? selected : input.parsed,
-  ).slice(0, 1_500);
-}
-
-export function normalizeToolHttpErrorMessage(input: {
-  toolId: string;
-  status: number;
-  attempt: number;
-  maxAttempts: number;
-  bodyText: string;
-}): ToolHttpError {
-  let parsed: Record<string, unknown> | null = null;
-  try {
-    const candidate = JSON.parse(input.bodyText);
-    parsed = isRecord(candidate) ? candidate : null;
-  } catch {
-    parsed = null;
-  }
-  const billing = getObjectField(parsed, 'billing');
-  if (isInsufficientCreditsBilling(billing)) {
-    return new ToolHttpError(
-      `tool ${input.toolId} ${input.status} attempt ${input.attempt}/${input.maxAttempts}: ${formatInsufficientCreditsMessage(
-        {
-          billing,
-          toolId: input.toolId,
-        },
-      )}`,
-      billing,
-      input.status,
-    );
-  }
-  const hardBillingPayload = isHardBillingFailurePayload(billing)
-    ? normalizeHardBillingPayload(billing)
-    : isHardBillingFailurePayload(parsed)
-      ? normalizeHardBillingPayload(parsed)
-      : null;
-  if (hardBillingPayload) {
-    return new ToolHttpError(
-      formatHardBillingFailureMessage({
-        billing: hardBillingPayload,
-        toolId: input.toolId,
-        status: input.status,
-        attempt: input.attempt,
-        maxAttempts: input.maxAttempts,
-      }),
-      hardBillingPayload,
-      input.status,
-    );
-  }
-  return new ToolHttpError(
-    `tool ${input.toolId} ${input.status} attempt ${input.attempt}/${input.maxAttempts}: ${formatPublicToolErrorPayload(
-      {
-        parsed,
-        bodyText: input.bodyText,
-      },
-    )}`,
-    billing,
-    input.status,
-  );
-}
-
-export function extractErrorBilling(
-  error: unknown,
-): Record<string, unknown> | null {
-  return error instanceof ToolHttpError ? error.billing : null;
-}
-
-export function isHardBillingToolHttpError(error: unknown): boolean {
-  return (
-    error instanceof ToolHttpError && isHardBillingFailurePayload(error.billing)
-  );
-}
-
-/**
- * A tool call that ultimately failed with HTTP 429 — provider or
- * Deepline-internal rate-limit pushback that survived the in-process retry
- * budget. This is run-level throughput pressure, never a row-specific defect.
- */
-export function isRateLimitToolHttpError(error: unknown): boolean {
-  return error instanceof ToolHttpError && error.status === 429;
-}
+export {
+  ToolHttpError,
+  extractErrorBilling,
+  isHardBillingToolHttpError,
+  isRateLimitToolHttpError,
+  normalizeToolHttpErrorMessage,
+} from '../../../../shared_libs/play-runtime/tool-http-errors';

package/dist/bundling-sources/sdk/src/client.ts

@@ -75,6 +75,7 @@ import type {
   ToolSearchResult,
   ToolMetadata,
   CustomerDbQueryResult,
+  DeeplineAgentModelDescription,
 } from './types.js';
 import type { PlayStagedFileRef } from './plays/local-file-discovery.js';
 import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest.js';
@@ -1113,6 +1114,29 @@ export class DeeplineClient {
     );
   }
 
+  /**
+   * Describe a Deepline Agent model and its provider-specific option surface.
+   *
+   * Combines live AI Gateway model metadata with Deepline's generated AI SDK
+   * provider option registry so agents can construct `providerOptions`
+   * payloads before executing `deeplineagent`.
+   *
+   * The returned option schemas describe accepted provider option shapes, not
+   * guaranteed support for every model. Runtime AI SDK/Gateway errors remain
+   * authoritative for model-gated values.
+   *
+   * @param model - Gateway model id such as `"openai/gpt-5.5"`
+   * @returns Model metadata, provider option shapes, and runnable examples
+   */
+  async describeModel(model: string): Promise<DeeplineAgentModelDescription> {
+    return this.http.request<DeeplineAgentModelDescription>(
+      `/api/v2/models/describe?model=${encodeURIComponent(model)}`,
+      {
+        method: 'GET',
+      },
+    );
+  }
+
   /**
    * Execute a tool and return the standard execution envelope.
    *

package/dist/bundling-sources/sdk/src/release.ts

@@ -101,10 +101,10 @@ export const SDK_RELEASE = {
   // 0.1.108 ships explicit dataset column/tool recompute policy and removes
   // the SDK enrich generator's one-second stale policy.
   // 0.1.110 ships authored V2 prebuilts and required top-level play descriptions.
-  version: '0.1.140',
+  version: '0.1.142',
   apiContract: '2026-06-dataset-column-cell-stale-hard-cutover',
   supportPolicy: {
-    latest: '0.1.140',
+    latest: '0.1.142',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
     commandMinimumSupported: [

package/dist/bundling-sources/sdk/src/types.ts

@@ -247,6 +247,38 @@ export interface ToolDefinition {
   }>;
 }
 
+export interface ModelProviderOptionField {
+  name: string;
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  enumValues?: string[];
+  description: string;
+  caveat?: string;
+}
+
+export interface ModelProviderOptionNamespace {
+  provider: string;
+  sourcePackage: string;
+  sourceSymbol: string;
+  fields: ModelProviderOptionField[];
+}
+
+export interface DeeplineAgentModelDescription {
+  schemaVersion: 1;
+  model: string;
+  provider: string;
+  modelMetadata: Record<string, unknown> | null;
+  providerOptions: {
+    gateway: ModelProviderOptionNamespace;
+    selectedProvider?: ModelProviderOptionNamespace;
+  };
+  exampleInput: {
+    model: string;
+    providerOptions: Record<string, unknown>;
+  };
+  caveats: string[];
+  sources: string[];
+}
+
 /**
  * Query options for ranked tool/provider discovery.
  */