@contractspec/lib.ai-agent 3.0.0 → 3.2.0

package/dist/exporters/claude-agent-exporter.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)) {

package/dist/exporters/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)) {

package/dist/exporters/opencode-exporter.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)) {

package/dist/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)) {

package/dist/interop/index.d.ts

@@ -43,5 +43,6 @@
  * ```
  */
 export * from './types';
+export * from './runtime-adapters';
 export { ContractSpecConsumer, createSpecConsumer, createSingleSpecConsumer, } from './spec-consumer';
 export { ContractSpecToolConsumer, createToolConsumer, createToolServer, exportToolsForExternalSDK, } from './tool-consumer';

package/dist/interop/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)) {

package/dist/interop/runtime-adapters.d.ts

@@ -0,0 +1,36 @@
+import type { AgentSessionState } from '../types';
+export type AgentRuntimeAdapterKey = 'langgraph' | 'langchain' | 'workflow-devkit';
+export interface AgentCheckpointEnvelope {
+    sessionId: string;
+    threadId?: string;
+    state: AgentSessionState;
+    checkpointId?: string;
+    createdAt: Date;
+}
+export interface AgentCheckpointPort {
+    save(envelope: AgentCheckpointEnvelope): Promise<void>;
+    load(sessionId: string): Promise<AgentCheckpointEnvelope | null>;
+    delete(sessionId: string): Promise<void>;
+}
+export interface AgentSuspendResumePort {
+    suspend(params: {
+        sessionId: string;
+        reason: string;
+        metadata?: Record<string, string>;
+    }): Promise<void>;
+    resume(params: {
+        sessionId: string;
+        input?: string;
+        metadata?: Record<string, string>;
+    }): Promise<void>;
+}
+export interface AgentRuntimeMiddlewareHooks<TState = unknown> {
+    beforeModel?: (state: TState) => Promise<TState | undefined> | TState | undefined;
+    afterModel?: (state: TState) => Promise<TState | undefined> | TState | undefined;
+}
+export interface AgentRuntimeAdapterBundle<TState = unknown> {
+    key: AgentRuntimeAdapterKey;
+    checkpoint?: AgentCheckpointPort;
+    suspendResume?: AgentSuspendResumePort;
+    middleware?: AgentRuntimeMiddlewareHooks<TState>;
+}

package/dist/interop/runtime-adapters.js

@@ -0,0 +1 @@
+// @bun

package/dist/interop/spec-consumer.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)) {

package/dist/node/agent/agent-factory.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();
@@ -3349,7 +3530,8 @@ class AgentFactory {
       telemetryCollector: this.config.telemetryCollector,
       posthogConfig: this.config.posthogConfig,
       additionalTools: mergedTools,
-      mcpServers: mergedMcpServers.length > 0 ? mergedMcpServers : undefined
+      mcpServers: mergedMcpServers.length > 0 ? mergedMcpServers : undefined,
+      modelSelector: this.config.modelSelector
     });
   }
   async getOrCreate(name, version) {