@contractspec/lib.ai-agent 2.9.1 → 3.1.1

package/dist/agent/contract-spec-agent.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {
@@ -2297,21 +2302,39 @@ var init_json_schema_to_zod = () => {};
 // src/tools/tool-adapter.ts
 import { tool } from "ai";
 function specToolToAISDKTool(specTool, handler, context = {}) {
+  let lastInvocationAt;
   return tool({
     description: specTool.description ?? specTool.name,
     inputSchema: jsonSchemaToZodSafe(specTool.schema),
     needsApproval: specTool.requiresApproval ?? !specTool.automationSafe,
     execute: async (input) => {
-      const result = await handler(input, {
-        agentId: context.agentId ?? "unknown",
-        sessionId: context.sessionId ?? "unknown",
-        tenantId: context.tenantId,
-        actorId: context.actorId,
-        locale: context.locale,
-        metadata: context.metadata,
-        signal: context.signal
-      });
-      return typeof result === "string" ? result : JSON.stringify(result);
+      const now = Date.now();
+      const cooldownMs = normalizeDuration(specTool.cooldownMs);
+      if (cooldownMs && lastInvocationAt !== undefined) {
+        const elapsed = now - lastInvocationAt;
+        if (elapsed < cooldownMs) {
+          const retryAfterMs = cooldownMs - elapsed;
+          throw createToolExecutionError(`Tool "${specTool.name}" is cooling down. Retry in ${retryAfterMs}ms.`, "TOOL_COOLDOWN_ACTIVE", retryAfterMs);
+        }
+      }
+      const timeoutMs = normalizeDuration(specTool.timeoutMs);
+      const { signal, dispose } = createTimeoutSignal(context.signal, timeoutMs);
+      try {
+        const execution = handler(input, {
+          agentId: context.agentId ?? "unknown",
+          sessionId: context.sessionId ?? "unknown",
+          tenantId: context.tenantId,
+          actorId: context.actorId,
+          locale: context.locale,
+          metadata: context.metadata,
+          signal
+        });
+        const result = timeoutMs ? await withTimeout(execution, timeoutMs, specTool.name) : await execution;
+        return typeof result === "string" ? result : JSON.stringify(result);
+      } finally {
+        dispose();
+        lastInvocationAt = Date.now();
+      }
     }
   });
 }
@@ -2336,6 +2359,64 @@ function createToolHandler(handler) {
 function buildToolHandlers(handlersObj) {
   return new Map(Object.entries(handlersObj));
 }
+function normalizeDuration(value) {
+  if (value === undefined) {
+    return;
+  }
+  if (!Number.isFinite(value)) {
+    return;
+  }
+  if (value <= 0) {
+    return;
+  }
+  return Math.round(value);
+}
+function withTimeout(execution, timeoutMs, toolName) {
+  return new Promise((resolve, reject) => {
+    const timeoutHandle = setTimeout(() => {
+      reject(createToolExecutionError(`Tool "${toolName}" timed out after ${timeoutMs}ms.`, "TOOL_EXECUTION_TIMEOUT"));
+    }, timeoutMs);
+    execution.then((result) => {
+      clearTimeout(timeoutHandle);
+      resolve(result);
+    }).catch((error) => {
+      clearTimeout(timeoutHandle);
+      reject(error);
+    });
+  });
+}
+function createTimeoutSignal(signal, timeoutMs) {
+  const controller = new AbortController;
+  const abortFromSource = () => controller.abort();
+  if (signal) {
+    if (signal.aborted) {
+      controller.abort();
+    } else {
+      signal.addEventListener("abort", abortFromSource);
+    }
+  }
+  const timeoutHandle = timeoutMs !== undefined ? setTimeout(() => {
+    controller.abort();
+  }, timeoutMs) : undefined;
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      if (timeoutHandle !== undefined) {
+        clearTimeout(timeoutHandle);
+      }
+      if (signal) {
+        signal.removeEventListener("abort", abortFromSource);
+      }
+    }
+  };
+}
+function createToolExecutionError(message, code, retryAfterMs) {
+  return Object.assign(new Error(message), {
+    code,
+    kind: "retryable",
+    retryAfterMs
+  });
+}
 var init_tool_adapter = __esm(() => {
   init_json_schema_to_zod();
   init_i18n();
@@ -3151,7 +3232,13 @@ class ContractSpecAgent {
           steps: [],
           metadata: params.options?.metadata
         });
+      } else if (existing.status !== "running") {
+        await this.config.sessionStore.update(sessionId, { status: "running" });
       }
+      await this.config.sessionStore.appendMessage(sessionId, {
+        role: "user",
+        content: params.prompt
+      });
     }
     const prompt = params.systemOverride ? `${this.instructions}
 
@@ -3163,24 +3250,41 @@ ${params.prompt}` : params.prompt;
       traceId,
       options: params.options
     });
-    const inner = this.createInnerAgent(model);
-    const result = await inner.generate({
-      prompt,
-      abortSignal: params.signal,
-      options: {
-        tenantId: params.options?.tenantId,
-        actorId: params.options?.actorId,
-        sessionId,
-        metadata: params.options?.metadata
+    const effectiveMaxSteps = resolveMaxSteps(params.maxSteps, this.spec.maxSteps);
+    const inner = this.createInnerAgent(model, effectiveMaxSteps);
+    let result;
+    try {
+      result = await inner.generate({
+        prompt,
+        abortSignal: params.signal,
+        options: {
+          tenantId: params.options?.tenantId,
+          actorId: params.options?.actorId,
+          sessionId,
+          metadata: params.options?.metadata
+        }
+      });
+    } catch (error) {
+      if (this.config.sessionStore) {
+        await this.config.sessionStore.update(sessionId, {
+          status: "failed"
+        });
       }
-    }).finally(() => {
       this.activeStepContexts.delete(sessionId);
-    });
+      throw error;
+    }
+    this.activeStepContexts.delete(sessionId);
+    const escalationError = resolveEscalationError(this.spec, result.finishReason);
     if (this.config.sessionStore) {
+      await this.config.sessionStore.appendMessage(sessionId, {
+        role: "assistant",
+        content: result.text
+      });
       await this.config.sessionStore.update(sessionId, {
-        status: "completed"
+        status: escalationError ? "escalated" : "completed"
       });
     }
+    const session = this.config.sessionStore ? await this.config.sessionStore.get(sessionId) : null;
     return {
       text: result.text,
       steps: result.steps,
@@ -3197,7 +3301,16 @@ ${params.prompt}` : params.prompt;
         output: tr.output
       })),
       finishReason: result.finishReason,
-      usage: result.usage
+      usage: result.usage,
+      session: session ?? undefined,
+      pendingApproval: escalationError ? {
+        toolName: this.spec.policy?.escalation?.approvalWorkflow ?? "approval_required",
+        toolCallId: `approval_${sessionId}`,
+        args: {
+          reason: escalationError.message,
+          code: escalationError.code
+        }
+      } : undefined
     };
   }
   async stream(params) {
@@ -3220,7 +3333,28 @@ ${params.prompt}` : params.prompt;
       traceId,
       options: params.options
     });
-    const inner = this.createInnerAgent(model);
+    const effectiveMaxSteps = resolveMaxSteps(params.maxSteps, this.spec.maxSteps);
+    const inner = this.createInnerAgent(model, effectiveMaxSteps);
+    if (this.config.sessionStore) {
+      const existing = await this.config.sessionStore.get(sessionId);
+      if (!existing) {
+        await this.config.sessionStore.create({
+          sessionId,
+          agentId: this.id,
+          tenantId: params.options?.tenantId,
+          actorId: params.options?.actorId,
+          status: "running",
+          messages: [],
+          steps: [],
+          metadata: params.options?.metadata
+        });
+      }
+      await this.config.sessionStore.appendMessage(sessionId, {
+        role: "user",
+        content: params.prompt
+      });
+      await this.config.sessionStore.update(sessionId, { status: "running" });
+    }
     return inner.stream({
       prompt,
       abortSignal: params.signal,
@@ -3236,6 +3370,9 @@ ${params.prompt}` : params.prompt;
     const sessionId = step.options?.sessionId;
     if (sessionId && this.config.sessionStore) {
       await this.config.sessionStore.appendStep(sessionId, step);
+      await this.config.sessionStore.update(sessionId, {
+        status: step.finishReason === "tool-calls" ? "waiting" : "running"
+      });
     }
     if (this.config.telemetryCollector) {
       const now = new Date;
@@ -3259,12 +3396,12 @@ ${params.prompt}` : params.prompt;
       }
     }
   }
-  createInnerAgent(model) {
+  createInnerAgent(model, maxSteps) {
     return new ToolLoopAgent({
       model,
       instructions: this.instructions,
       tools: this.tools,
-      stopWhen: stepCountIs(this.spec.maxSteps ?? 10),
+      stopWhen: stepCountIs(maxSteps),
       callOptionsSchema: ContractSpecCallOptionsSchema,
       onStepFinish: async (step) => {
         await this.handleStepFinish(step);
@@ -3272,6 +3409,10 @@ ${params.prompt}` : params.prompt;
     });
   }
   async resolveModelForCall(params) {
+    if (this.config.modelSelector && params.options?.selectionContext) {
+      const { model } = await this.config.modelSelector.selectAndCreate(params.options.selectionContext);
+      return model;
+    }
     const posthogConfig = this.config.posthogConfig;
     if (!posthogConfig) {
       return this.config.model;
@@ -3296,6 +3437,46 @@ ${params.prompt}` : params.prompt;
     return createPostHogTracedModel2(this.config.model, posthogConfig, tracingOptions);
   }
 }
+function resolveMaxSteps(overrideMaxSteps, specMaxSteps) {
+  const candidate = overrideMaxSteps ?? specMaxSteps ?? 10;
+  if (!Number.isFinite(candidate)) {
+    return 10;
+  }
+  if (candidate < 1) {
+    return 1;
+  }
+  return Math.round(candidate);
+}
+function resolveEscalationError(spec, finishReason) {
+  const escalation = spec.policy?.escalation;
+  if (!escalation) {
+    return;
+  }
+  if (escalation.onTimeout && finishReason === "length") {
+    return {
+      kind: "timeout",
+      code: "AGENT_TIMEOUT_ESCALATION",
+      message: "Agent reached max step budget and requires escalation."
+    };
+  }
+  if (escalation.onToolFailure && finishReason === "error") {
+    return {
+      kind: "retryable",
+      code: "AGENT_TOOL_FAILURE_ESCALATION",
+      message: "Agent encountered a tool failure and requires escalation."
+    };
+  }
+  const confidenceThreshold = escalation.confidenceThreshold;
+  const defaultConfidence = spec.policy?.confidence?.default;
+  if (confidenceThreshold !== undefined && defaultConfidence !== undefined && defaultConfidence < confidenceThreshold) {
+    return {
+      kind: "policy_blocked",
+      code: "AGENT_CONFIDENCE_ESCALATION",
+      message: `Agent default confidence (${defaultConfidence}) is below escalation threshold (${confidenceThreshold}).`
+    };
+  }
+  return;
+}
 var ContractSpecCallOptionsSchema;
 var init_contract_spec_agent = __esm(() => {
   init_spec();

package/dist/agent/index.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {
@@ -2297,21 +2302,39 @@ var init_json_schema_to_zod = () => {};
 // src/tools/tool-adapter.ts
 import { tool } from "ai";
 function specToolToAISDKTool(specTool, handler, context = {}) {
+  let lastInvocationAt;
   return tool({
     description: specTool.description ?? specTool.name,
     inputSchema: jsonSchemaToZodSafe(specTool.schema),
     needsApproval: specTool.requiresApproval ?? !specTool.automationSafe,
     execute: async (input) => {
-      const result = await handler(input, {
-        agentId: context.agentId ?? "unknown",
-        sessionId: context.sessionId ?? "unknown",
-        tenantId: context.tenantId,
-        actorId: context.actorId,
-        locale: context.locale,
-        metadata: context.metadata,
-        signal: context.signal
-      });
-      return typeof result === "string" ? result : JSON.stringify(result);
+      const now = Date.now();
+      const cooldownMs = normalizeDuration(specTool.cooldownMs);
+      if (cooldownMs && lastInvocationAt !== undefined) {
+        const elapsed = now - lastInvocationAt;
+        if (elapsed < cooldownMs) {
+          const retryAfterMs = cooldownMs - elapsed;
+          throw createToolExecutionError(`Tool "${specTool.name}" is cooling down. Retry in ${retryAfterMs}ms.`, "TOOL_COOLDOWN_ACTIVE", retryAfterMs);
+        }
+      }
+      const timeoutMs = normalizeDuration(specTool.timeoutMs);
+      const { signal, dispose } = createTimeoutSignal(context.signal, timeoutMs);
+      try {
+        const execution = handler(input, {
+          agentId: context.agentId ?? "unknown",
+          sessionId: context.sessionId ?? "unknown",
+          tenantId: context.tenantId,
+          actorId: context.actorId,
+          locale: context.locale,
+          metadata: context.metadata,
+          signal
+        });
+        const result = timeoutMs ? await withTimeout(execution, timeoutMs, specTool.name) : await execution;
+        return typeof result === "string" ? result : JSON.stringify(result);
+      } finally {
+        dispose();
+        lastInvocationAt = Date.now();
+      }
     }
   });
 }
@@ -2336,6 +2359,64 @@ function createToolHandler(handler) {
 function buildToolHandlers(handlersObj) {
   return new Map(Object.entries(handlersObj));
 }
+function normalizeDuration(value) {
+  if (value === undefined) {
+    return;
+  }
+  if (!Number.isFinite(value)) {
+    return;
+  }
+  if (value <= 0) {
+    return;
+  }
+  return Math.round(value);
+}
+function withTimeout(execution, timeoutMs, toolName) {
+  return new Promise((resolve, reject) => {
+    const timeoutHandle = setTimeout(() => {
+      reject(createToolExecutionError(`Tool "${toolName}" timed out after ${timeoutMs}ms.`, "TOOL_EXECUTION_TIMEOUT"));
+    }, timeoutMs);
+    execution.then((result) => {
+      clearTimeout(timeoutHandle);
+      resolve(result);
+    }).catch((error) => {
+      clearTimeout(timeoutHandle);
+      reject(error);
+    });
+  });
+}
+function createTimeoutSignal(signal, timeoutMs) {
+  const controller = new AbortController;
+  const abortFromSource = () => controller.abort();
+  if (signal) {
+    if (signal.aborted) {
+      controller.abort();
+    } else {
+      signal.addEventListener("abort", abortFromSource);
+    }
+  }
+  const timeoutHandle = timeoutMs !== undefined ? setTimeout(() => {
+    controller.abort();
+  }, timeoutMs) : undefined;
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      if (timeoutHandle !== undefined) {
+        clearTimeout(timeoutHandle);
+      }
+      if (signal) {
+        signal.removeEventListener("abort", abortFromSource);
+      }
+    }
+  };
+}
+function createToolExecutionError(message, code, retryAfterMs) {
+  return Object.assign(new Error(message), {
+    code,
+    kind: "retryable",
+    retryAfterMs
+  });
+}
 var init_tool_adapter = __esm(() => {
   init_json_schema_to_zod();
   init_i18n();
@@ -3151,7 +3232,13 @@ class ContractSpecAgent {
           steps: [],
           metadata: params.options?.metadata
         });
+      } else if (existing.status !== "running") {
+        await this.config.sessionStore.update(sessionId, { status: "running" });
       }
+      await this.config.sessionStore.appendMessage(sessionId, {
+        role: "user",
+        content: params.prompt
+      });
     }
     const prompt = params.systemOverride ? `${this.instructions}
 
@@ -3163,24 +3250,41 @@ ${params.prompt}` : params.prompt;
       traceId,
       options: params.options
     });
-    const inner = this.createInnerAgent(model);
-    const result = await inner.generate({
-      prompt,
-      abortSignal: params.signal,
-      options: {
-        tenantId: params.options?.tenantId,
-        actorId: params.options?.actorId,
-        sessionId,
-        metadata: params.options?.metadata
+    const effectiveMaxSteps = resolveMaxSteps(params.maxSteps, this.spec.maxSteps);
+    const inner = this.createInnerAgent(model, effectiveMaxSteps);
+    let result;
+    try {
+      result = await inner.generate({
+        prompt,
+        abortSignal: params.signal,
+        options: {
+          tenantId: params.options?.tenantId,
+          actorId: params.options?.actorId,
+          sessionId,
+          metadata: params.options?.metadata
+        }
+      });
+    } catch (error) {
+      if (this.config.sessionStore) {
+        await this.config.sessionStore.update(sessionId, {
+          status: "failed"
+        });
       }
-    }).finally(() => {
       this.activeStepContexts.delete(sessionId);
-    });
+      throw error;
+    }
+    this.activeStepContexts.delete(sessionId);
+    const escalationError = resolveEscalationError(this.spec, result.finishReason);
     if (this.config.sessionStore) {
+      await this.config.sessionStore.appendMessage(sessionId, {
+        role: "assistant",
+        content: result.text
+      });
       await this.config.sessionStore.update(sessionId, {
-        status: "completed"
+        status: escalationError ? "escalated" : "completed"
       });
     }
+    const session = this.config.sessionStore ? await this.config.sessionStore.get(sessionId) : null;
     return {
       text: result.text,
       steps: result.steps,
@@ -3197,7 +3301,16 @@ ${params.prompt}` : params.prompt;
         output: tr.output
       })),
       finishReason: result.finishReason,
-      usage: result.usage
+      usage: result.usage,
+      session: session ?? undefined,
+      pendingApproval: escalationError ? {
+        toolName: this.spec.policy?.escalation?.approvalWorkflow ?? "approval_required",
+        toolCallId: `approval_${sessionId}`,
+        args: {
+          reason: escalationError.message,
+          code: escalationError.code
+        }
+      } : undefined
     };
   }
   async stream(params) {
@@ -3220,7 +3333,28 @@ ${params.prompt}` : params.prompt;
       traceId,
       options: params.options
     });
-    const inner = this.createInnerAgent(model);
+    const effectiveMaxSteps = resolveMaxSteps(params.maxSteps, this.spec.maxSteps);
+    const inner = this.createInnerAgent(model, effectiveMaxSteps);
+    if (this.config.sessionStore) {
+      const existing = await this.config.sessionStore.get(sessionId);
+      if (!existing) {
+        await this.config.sessionStore.create({
+          sessionId,
+          agentId: this.id,
+          tenantId: params.options?.tenantId,
+          actorId: params.options?.actorId,
+          status: "running",
+          messages: [],
+          steps: [],
+          metadata: params.options?.metadata
+        });
+      }
+      await this.config.sessionStore.appendMessage(sessionId, {
+        role: "user",
+        content: params.prompt
+      });
+      await this.config.sessionStore.update(sessionId, { status: "running" });
+    }
     return inner.stream({
       prompt,
       abortSignal: params.signal,
@@ -3236,6 +3370,9 @@ ${params.prompt}` : params.prompt;
     const sessionId = step.options?.sessionId;
     if (sessionId && this.config.sessionStore) {
       await this.config.sessionStore.appendStep(sessionId, step);
+      await this.config.sessionStore.update(sessionId, {
+        status: step.finishReason === "tool-calls" ? "waiting" : "running"
+      });
     }
     if (this.config.telemetryCollector) {
       const now = new Date;
@@ -3259,12 +3396,12 @@ ${params.prompt}` : params.prompt;
       }
     }
   }
-  createInnerAgent(model) {
+  createInnerAgent(model, maxSteps) {
     return new ToolLoopAgent({
       model,
       instructions: this.instructions,
       tools: this.tools,
-      stopWhen: stepCountIs(this.spec.maxSteps ?? 10),
+      stopWhen: stepCountIs(maxSteps),
       callOptionsSchema: ContractSpecCallOptionsSchema,
       onStepFinish: async (step) => {
         await this.handleStepFinish(step);
@@ -3272,6 +3409,10 @@ ${params.prompt}` : params.prompt;
     });
   }
   async resolveModelForCall(params) {
+    if (this.config.modelSelector && params.options?.selectionContext) {
+      const { model } = await this.config.modelSelector.selectAndCreate(params.options.selectionContext);
+      return model;
+    }
     const posthogConfig = this.config.posthogConfig;
     if (!posthogConfig) {
       return this.config.model;
@@ -3296,6 +3437,46 @@ ${params.prompt}` : params.prompt;
     return createPostHogTracedModel2(this.config.model, posthogConfig, tracingOptions);
   }
 }
+function resolveMaxSteps(overrideMaxSteps, specMaxSteps) {
+  const candidate = overrideMaxSteps ?? specMaxSteps ?? 10;
+  if (!Number.isFinite(candidate)) {
+    return 10;
+  }
+  if (candidate < 1) {
+    return 1;
+  }
+  return Math.round(candidate);
+}
+function resolveEscalationError(spec, finishReason) {
+  const escalation = spec.policy?.escalation;
+  if (!escalation) {
+    return;
+  }
+  if (escalation.onTimeout && finishReason === "length") {
+    return {
+      kind: "timeout",
+      code: "AGENT_TIMEOUT_ESCALATION",
+      message: "Agent reached max step budget and requires escalation."
+    };
+  }
+  if (escalation.onToolFailure && finishReason === "error") {
+    return {
+      kind: "retryable",
+      code: "AGENT_TOOL_FAILURE_ESCALATION",
+      message: "Agent encountered a tool failure and requires escalation."
+    };
+  }
+  const confidenceThreshold = escalation.confidenceThreshold;
+  const defaultConfidence = spec.policy?.confidence?.default;
+  if (confidenceThreshold !== undefined && defaultConfidence !== undefined && defaultConfidence < confidenceThreshold) {
+    return {
+      kind: "policy_blocked",
+      code: "AGENT_CONFIDENCE_ESCALATION",
+      message: `Agent default confidence (${defaultConfidence}) is below escalation threshold (${confidenceThreshold}).`
+    };
+  }
+  return;
+}
 var ContractSpecCallOptionsSchema;
 var init_contract_spec_agent = __esm(() => {
   init_spec();
@@ -4579,7 +4760,11 @@ function getDefaultSpec(locale) {
     tools: []
   };
 }
-function resolveModel(options) {
+async function resolveModel(options) {
+  if (options.modelSelector && options.selectionContext) {
+    const { model } = await options.modelSelector.selectAndCreate(options.selectionContext);
+    return model;
+  }
   if (options.model)
     return options.model;
   if (options.provider) {
@@ -4612,7 +4797,8 @@ function ensureToolHandlers(spec, handlers, locale) {
   }
 }
 async function createAgentJsonRunner(options) {
-  const model = applyModelSettings(resolveModel(options), {
+  const resolved = await resolveModel(options);
+  const model = applyModelSettings(resolved, {
     temperature: options.temperature ?? 0
   });
   const baseSpec = options.spec ?? getDefaultSpec(options.locale);
@@ -4813,7 +4999,10 @@ class UnifiedAgent {
   async resolveAISDKModel() {
     const backendConfig = this.getAISDKConfig();
     let model;
-    if (backendConfig?.modelInstance) {
+    if (backendConfig?.modelSelector && backendConfig.selectionContext) {
+      const result = await backendConfig.modelSelector.selectAndCreate(backendConfig.selectionContext);
+      model = result.model;
+    } else if (backendConfig?.modelInstance) {
       model = backendConfig.modelInstance;
     } else if (backendConfig?.provider) {
       const { createProvider: createProvider2 } = await import("@contractspec/lib.ai-providers/factory");

package/dist/agent/json-runner.d.ts

@@ -1,5 +1,6 @@
 import type { LanguageModel } from 'ai';
 import type { ProviderConfig } from '@contractspec/lib.ai-providers/types';
+import type { ModelSelector, ModelSelectionContext } from '@contractspec/lib.ai-providers/selector-types';
 import type { AgentSpec } from '../spec/spec';
 import type { ToolHandler } from '../types';
 export interface AgentJsonRunnerOptions {
@@ -11,6 +12,8 @@ export interface AgentJsonRunnerOptions {
     maxSteps?: number;
     temperature?: number;
     locale?: string;
+    modelSelector?: ModelSelector;
+    selectionContext?: ModelSelectionContext;
 }
 export interface AgentJsonRunner {
     generateJson: (prompt: string) => Promise<string>;