@contractspec/lib.ai-agent 7.0.7 → 8.0.0

package/dist/node/index.js

@@ -2131,103 +2131,3837 @@ var init_i18n = __esm(() => {
   init_messages();
 });
 
-// src/spec/spec.ts
-function defineAgent(spec) {
-  const i18n = createAgentI18n(spec.locale);
-  if (!spec.meta?.key) {
-    throw new Error(i18n.t("error.agentKeyRequired"));
+// src/approval/workflow.ts
+import { randomUUID } from "node:crypto";
+
+class InMemoryApprovalStore {
+  items = new Map;
+  maxItems;
+  constructor(options = {}) {
+    this.maxItems = options.maxItems ?? 1000;
+  }
+  async create(request) {
+    this.evictIfNeeded();
+    this.items.set(request.id, request);
+  }
+  async get(id) {
+    return this.items.get(id) ?? null;
+  }
+  async getByToolCallId(toolCallId) {
+    for (const request of this.items.values()) {
+      if (request.toolCallId === toolCallId) {
+        return request;
+      }
+    }
+    return null;
+  }
+  async update(id, updates) {
+    const existing = this.items.get(id);
+    if (existing) {
+      this.items.set(id, { ...existing, ...updates });
+    }
+  }
+  async list(options) {
+    let results = [...this.items.values()];
+    if (options?.status) {
+      results = results.filter((r) => r.status === options.status);
+    }
+    if (options?.agentId) {
+      results = results.filter((r) => r.agentId === options.agentId);
+    }
+    if (options?.tenantId) {
+      results = results.filter((r) => r.tenantId === options.tenantId);
+    }
+    return results.sort((a, b) => b.requestedAt.getTime() - a.requestedAt.getTime());
+  }
+  clear() {
+    this.items.clear();
+  }
+  evictIfNeeded() {
+    if (this.items.size < this.maxItems) {
+      return;
+    }
+    let oldestId = null;
+    let oldestTimestamp = Number.POSITIVE_INFINITY;
+    for (const [id, request] of this.items.entries()) {
+      const ts = request.requestedAt.getTime();
+      if (ts < oldestTimestamp) {
+        oldestTimestamp = ts;
+        oldestId = id;
+      }
+    }
+    if (oldestId) {
+      this.items.delete(oldestId);
+    }
+  }
+}
+
+class ApprovalWorkflow {
+  store;
+  constructor(store = new InMemoryApprovalStore) {
+    this.store = store;
+  }
+  async requestApproval(params) {
+    const request = {
+      id: randomUUID(),
+      sessionId: params.sessionId,
+      agentId: params.agentId,
+      tenantId: params.tenantId,
+      toolName: params.toolName,
+      toolCallId: params.toolCallId,
+      toolArgs: params.toolArgs,
+      reason: params.reason,
+      requestedAt: new Date,
+      status: "pending",
+      payload: params.payload
+    };
+    await this.store.create(request);
+    return request;
+  }
+  async requestApprovalFromToolCall(toolCall, context) {
+    return this.requestApproval({
+      sessionId: context.sessionId,
+      agentId: context.agentId,
+      tenantId: context.tenantId,
+      toolName: toolCall.toolName,
+      toolCallId: toolCall.toolCallId,
+      toolArgs: toolCall.args,
+      reason: context.reason ?? createAgentI18n(context.locale).t("approval.toolRequiresApproval", {
+        name: toolCall.toolName
+      })
+    });
+  }
+  async approve(id, reviewer, notes) {
+    await this.store.update(id, {
+      status: "approved",
+      reviewer,
+      resolvedAt: new Date,
+      notes
+    });
+  }
+  async reject(id, reviewer, notes) {
+    await this.store.update(id, {
+      status: "rejected",
+      reviewer,
+      resolvedAt: new Date,
+      notes
+    });
+  }
+  async getStatus(toolCallId) {
+    const request = await this.store.getByToolCallId(toolCallId);
+    return request?.status ?? null;
+  }
+  async isApproved(toolCallId) {
+    const status = await this.getStatus(toolCallId);
+    return status === "approved";
+  }
+  async listPending(options) {
+    return this.store.list({ ...options, status: "pending" });
+  }
+  async get(id) {
+    return this.store.get(id);
+  }
+}
+function createApprovalWorkflow(store) {
+  if (store && typeof store === "object" && "create" in store && typeof store.create === "function") {
+    return new ApprovalWorkflow(store);
+  }
+  const options = store;
+  return new ApprovalWorkflow(new InMemoryApprovalStore(options));
+}
+var init_workflow = __esm(() => {
+  init_i18n();
+});
+
+// src/knowledge/injector.ts
+async function injectStaticKnowledge(instructions, knowledgeRefs, retriever, locale) {
+  if (!retriever)
+    return instructions;
+  const requiredRefs = knowledgeRefs.filter((ref) => ref.required);
+  if (requiredRefs.length === 0)
+    return instructions;
+  const i18n = createAgentI18n(locale);
+  const blocks = [];
+  for (const ref of requiredRefs) {
+    if (!retriever.supportsSpace(ref.key)) {
+      console.warn(i18n.t("log.knowledge.spaceNotAvailable", { key: ref.key }));
+      continue;
+    }
+    try {
+      const content = await retriever.getStatic(ref.key);
+      if (content) {
+        const header = ref.instructions ? `## ${ref.key}
+${ref.instructions}` : `## ${ref.key}`;
+        blocks.push(`${header}
+
+${content}`);
+      }
+    } catch (error) {
+      console.warn(i18n.t("log.knowledge.loadFailed", { key: ref.key }), error);
+    }
+  }
+  if (blocks.length === 0)
+    return instructions;
+  return `${instructions}
+
+---
+
+# ${i18n.t("knowledge.header")}
+
+${i18n.t("knowledge.description")}
+
+${blocks.join(`
+
+---
+
+`)}`;
+}
+function createKnowledgeInjector(retriever, locale) {
+  return {
+    inject: (instructions, knowledgeRefs) => injectStaticKnowledge(instructions, knowledgeRefs, retriever, locale),
+    hasSpace: (spaceKey) => retriever?.supportsSpace(spaceKey) ?? false,
+    listSpaces: () => retriever?.listSpaces() ?? []
+  };
+}
+var init_injector = __esm(() => {
+  init_i18n();
+});
+
+// src/session/store.ts
+class InMemorySessionStore {
+  sessions = new Map;
+  maxSessions;
+  maxMessagesPerSession;
+  maxStepsPerSession;
+  constructor(options = {}) {
+    this.maxSessions = options.maxSessions ?? 500;
+    this.maxMessagesPerSession = options.maxMessagesPerSession ?? 200;
+    this.maxStepsPerSession = options.maxStepsPerSession ?? 200;
+  }
+  async get(sessionId) {
+    return this.sessions.get(sessionId) ?? null;
+  }
+  async create(session) {
+    this.evictIfNeeded();
+    const now = new Date;
+    const fullSession = {
+      ...session,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.sessions.set(session.sessionId, fullSession);
+    return fullSession;
+  }
+  async appendStep(sessionId, step) {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      session.steps.push(step);
+      this.trimArray(session.steps, this.maxStepsPerSession);
+      session.updatedAt = new Date;
+    }
+  }
+  async appendMessage(sessionId, message) {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      session.messages.push(message);
+      this.trimArray(session.messages, this.maxMessagesPerSession);
+      session.updatedAt = new Date;
+    }
+  }
+  async update(sessionId, updates) {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      Object.assign(session, updates, { updatedAt: new Date });
+    }
+  }
+  async delete(sessionId) {
+    return this.sessions.delete(sessionId);
+  }
+  async listByAgent(agentId, limit = 100) {
+    const results = [];
+    for (const session of this.sessions.values()) {
+      if (session.agentId === agentId) {
+        results.push(session);
+        if (results.length >= limit)
+          break;
+      }
+    }
+    return results.sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+  }
+  async listByTenant(tenantId, limit = 100) {
+    const results = [];
+    for (const session of this.sessions.values()) {
+      if (session.tenantId === tenantId) {
+        results.push(session);
+        if (results.length >= limit)
+          break;
+      }
+    }
+    return results.sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+  }
+  clear() {
+    this.sessions.clear();
+  }
+  evictIfNeeded() {
+    if (this.sessions.size < this.maxSessions) {
+      return;
+    }
+    let oldestSessionId = null;
+    let oldestUpdatedAt = Number.POSITIVE_INFINITY;
+    for (const [sessionId, session] of this.sessions.entries()) {
+      const updatedAt = session.updatedAt.getTime();
+      if (updatedAt < oldestUpdatedAt) {
+        oldestUpdatedAt = updatedAt;
+        oldestSessionId = sessionId;
+      }
+    }
+    if (oldestSessionId) {
+      this.sessions.delete(oldestSessionId);
+    }
+  }
+  trimArray(items, maxItems) {
+    if (items.length <= maxItems) {
+      return;
+    }
+    const overflow = items.length - maxItems;
+    items.splice(0, overflow);
+  }
+}
+function createInMemorySessionStore(options) {
+  return new InMemorySessionStore(options);
+}
+function createSecureSessionToken() {
+  const cryptoApi = globalThis.crypto;
+  if (typeof cryptoApi?.randomUUID === "function") {
+    return cryptoApi.randomUUID();
+  }
+  if (typeof cryptoApi?.getRandomValues === "function") {
+    const bytes = cryptoApi.getRandomValues(new Uint8Array(16));
+    const versionByte = bytes.at(6);
+    const variantByte = bytes.at(8);
+    if (versionByte === undefined || variantByte === undefined) {
+      throw new Error("Secure session token generation requires 16 random bytes.");
+    }
+    bytes[6] = versionByte & 15 | 64;
+    bytes[8] = variantByte & 63 | 128;
+    const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0"));
+    return [
+      hex.slice(0, 4).join(""),
+      hex.slice(4, 6).join(""),
+      hex.slice(6, 8).join(""),
+      hex.slice(8, 10).join(""),
+      hex.slice(10, 16).join("")
+    ].join("-");
+  }
+  throw new Error("Secure session IDs require Web Crypto support.");
+}
+function generateSessionId() {
+  return `sess_${createSecureSessionToken()}`;
+}
+
+// src/telemetry/adapter.ts
+function parseAgentId(agentId) {
+  const match = agentId.match(/^(.+)\.v(\d+)$/);
+  if (match) {
+    return { name: match[1], version: match[2] };
+  }
+  return { name: agentId, version: "1.0.0" };
+}
+function getRecord(value) {
+  return value && typeof value === "object" ? value : undefined;
+}
+function getStepResponse(step) {
+  const response = getRecord(step.response);
+  if (!response)
+    return;
+  return {
+    id: response["id"],
+    modelId: response["modelId"],
+    timestamp: response["timestamp"],
+    headers: response["headers"],
+    body: response["body"],
+    messages: response["messages"]
+  };
+}
+function getRequestBodyValue(request, key) {
+  const body = request?.["body"];
+  if (!body)
+    return;
+  if (typeof body === "string") {
+    try {
+      const parsed = JSON.parse(body);
+      return typeof parsed[key] === "string" ? parsed[key] : undefined;
+    } catch {
+      return;
+    }
+  }
+  const record = getRecord(body);
+  return typeof record?.[key] === "string" ? record[key] : undefined;
+}
+async function trackAgentStep(collector, agentId, step, durationMs, context) {
+  const { name, version } = parseAgentId(agentId);
+  const response = getStepResponse(step);
+  const providerMetadata = step.providerMetadata;
+  const warnings = step.warnings;
+  const rawFinishReason = step.rawFinishReason;
+  const request = getRecord(step.request);
+  const traceId = context?.traceId ?? getRequestBodyValue(request, "$ai_trace_id");
+  const sessionId = context?.sessionId ?? getRequestBodyValue(request, "$ai_session_id");
+  const parentSpanId = response?.id;
+  for (const toolCall of step.toolCalls ?? []) {
+    const toolResult = step.toolResults?.find((r) => r.toolCallId === toolCall.toolCallId);
+    const toolError = getRecord(toolResult?.output)?.["error"];
+    const toolSample = {
+      operation: { name: `${name}.${toolCall.toolName}`, version },
+      durationMs: durationMs ?? 0,
+      success: step.toolResults?.some((r) => r.toolCallId === toolCall.toolCallId && r.output !== undefined) ?? false,
+      timestamp: new Date,
+      metadata: {
+        telemetryEvent: "span",
+        traceId,
+        sessionId,
+        spanId: toolCall.toolCallId,
+        parentSpanId,
+        spanName: `tool.${toolCall.toolName}`,
+        agentId,
+        actorId: context?.actorId,
+        tenantId: context?.tenantId,
+        workflowId: context?.workflowId,
+        stepIndex: context?.stepIndex,
+        toolName: toolCall.toolName,
+        toolCallArgs: toolCall.input,
+        toolResultOutput: toolResult?.output,
+        errorMessage: typeof toolError === "string" ? toolError : typeof toolResult?.output === "string" ? toolResult.output : undefined,
+        finishReason: step.finishReason,
+        rawFinishReason
+      }
+    };
+    await collector.collect(toolSample);
+  }
+  const stepSample = {
+    operation: { name, version },
+    durationMs: durationMs ?? 0,
+    success: step.finishReason !== "error",
+    timestamp: new Date,
+    metadata: {
+      telemetryEvent: "generation",
+      traceId,
+      sessionId,
+      spanId: response?.id,
+      spanName: `agent.${name}.step`,
+      agentId,
+      actorId: context?.actorId,
+      tenantId: context?.tenantId,
+      workflowId: context?.workflowId,
+      stepIndex: context?.stepIndex,
+      stepStartedAt: context?.stepStartedAt,
+      finishReason: step.finishReason,
+      rawFinishReason,
+      tokenUsage: step.usage,
+      totalUsage: step.totalUsage,
+      providerMetadata,
+      warnings,
+      stepText: step.text,
+      stepReasoningText: step.reasoningText,
+      responseId: response?.id,
+      responseModelId: response?.modelId,
+      responseTimestamp: response?.timestamp,
+      responseHeaders: response?.headers,
+      responseBody: response?.body,
+      responseMessages: response?.messages,
+      requestBody: request?.["body"],
+      requestHeaders: request?.["headers"],
+      toolCallCount: step.toolCalls?.length ?? 0,
+      toolCalls: step.toolCalls,
+      toolResults: step.toolResults,
+      errorMessage: step.finishReason === "error" ? step.text : undefined
+    }
+  };
+  await collector.collect(stepSample);
+}
+
+class InMemoryTelemetryCollector {
+  samples = [];
+  async collect(sample) {
+    this.samples.push(sample);
+  }
+  getSamples() {
+    return [...this.samples];
+  }
+  getSamplesForOperation(operationName) {
+    return this.samples.filter((s) => s.operation.name === operationName);
+  }
+  clear() {
+    this.samples.length = 0;
+  }
+}
+function createInMemoryTelemetryCollector() {
+  return new InMemoryTelemetryCollector;
+}
+var noopTelemetryCollector;
+var init_adapter = __esm(() => {
+  noopTelemetryCollector = {
+    collect: async () => {}
+  };
+});
+
+// src/tools/knowledge-tool.ts
+import { tool } from "ai";
+import * as z from "zod";
+function createKnowledgeQueryTool(retriever, knowledgeRefs, locale) {
+  const i18n = createAgentI18n(locale);
+  const optionalSpaces = knowledgeRefs.filter((k) => !k.required).map((k) => k.key).filter((key) => retriever.supportsSpace(key));
+  if (optionalSpaces.length === 0) {
+    return null;
+  }
+  const spaceDescriptions = knowledgeRefs.filter((k) => !k.required && retriever.supportsSpace(k.key)).map((k) => `- ${k.key}: ${k.instructions ?? i18n.t("tool.knowledge.spaceDefault")}`).join(`
+`);
+  return tool({
+    description: `${i18n.t("tool.knowledge.description")}
+
+${i18n.t("tool.knowledge.availableSpaces")}
+${spaceDescriptions}`,
+    inputSchema: z.object({
+      query: z.string().describe(i18n.t("tool.knowledge.param.query")),
+      spaceKey: z.enum(optionalSpaces).optional().describe(i18n.t("tool.knowledge.param.spaceKey")),
+      topK: z.number().optional().default(5).describe(i18n.t("tool.knowledge.param.topK"))
+    }),
+    execute: async ({ query, spaceKey, topK }) => {
+      const spacesToSearch = spaceKey ? [spaceKey] : optionalSpaces;
+      const allResults = [];
+      for (const space of spacesToSearch) {
+        try {
+          const results = await retriever.retrieve(query, {
+            spaceKey: space,
+            topK: topK ?? 5
+          });
+          for (const result of results) {
+            allResults.push({
+              space,
+              content: result.content,
+              score: result.score
+            });
+          }
+        } catch (error) {
+          console.warn(i18n.t("log.knowledge.queryFailed", { space }), error);
+        }
+      }
+      if (allResults.length === 0) {
+        return i18n.t("tool.knowledge.noResults");
+      }
+      allResults.sort((a, b) => b.score - a.score);
+      const topResults = allResults.slice(0, topK ?? 5);
+      return topResults.map((r, i) => `${i18n.t("tool.knowledge.sourceLabel", { index: i + 1, space: r.space, score: (r.score * 100).toFixed(0) })}
+${r.content}`).join(`
+
+---
+
+`);
+    }
+  });
+}
+var init_knowledge_tool = __esm(() => {
+  init_i18n();
+});
+
+// src/tools/mcp-client-helpers.ts
+import {
+  Experimental_StdioMCPTransport as StdioClientTransport
+} from "@ai-sdk/mcp/mcp-stdio";
+function buildMcpTransport(config) {
+  const transport = resolveTransportType(config);
+  if (transport === "stdio") {
+    const stdioConfig = resolveStdioConfig(config);
+    return new StdioClientTransport(stdioConfig);
+  }
+  const remoteConfig = config;
+  const headers = resolveRemoteHeaders(remoteConfig);
+  const remoteTransport = {
+    type: transport,
+    url: requireNonEmptyString(remoteConfig.url, "url", config.name)
+  };
+  if (headers) {
+    remoteTransport.headers = headers;
+  }
+  if (remoteConfig.authProvider) {
+    remoteTransport.authProvider = remoteConfig.authProvider;
+  }
+  return remoteTransport;
+}
+function prefixToolNames(config, tools) {
+  const prefix = config.toolPrefix?.trim();
+  if (!prefix) {
+    return tools;
+  }
+  const prefixedTools = {};
+  for (const [toolName, tool2] of Object.entries(tools)) {
+    prefixedTools[`${prefix}_${toolName}`] = tool2;
+  }
+  return prefixedTools;
+}
+function getErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function resolveTransportType(config) {
+  return config.transport ?? "stdio";
+}
+function resolveStdioConfig(config) {
+  const stdioConfig = config;
+  return {
+    command: requireNonEmptyString(stdioConfig.command, "command", config.name),
+    args: stdioConfig.args,
+    env: stdioConfig.env,
+    cwd: stdioConfig.cwd
+  };
+}
+function resolveRemoteHeaders(config) {
+  const headers = {
+    ...config.headers ?? {}
+  };
+  const accessToken = config.accessToken ?? resolveEnvToken(config.accessTokenEnvVar);
+  if (accessToken && headers.Authorization === undefined) {
+    headers.Authorization = `Bearer ${accessToken}`;
+  }
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+function resolveEnvToken(envVarName) {
+  if (!envVarName) {
+    return;
+  }
+  const value = process.env[envVarName];
+  if (!value) {
+    return;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+function requireNonEmptyString(value, field, serverName) {
+  if (!value) {
+    throw new Error(`MCP server "${serverName}" is missing required "${field}".`);
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`MCP server "${serverName}" has an empty "${field}".`);
+  }
+  return trimmed;
+}
+var init_mcp_client_helpers = () => {};
+
+// src/tools/mcp-client.ts
+import {
+  experimental_createMCPClient
+} from "@ai-sdk/mcp";
+async function mcpServerToTools(config) {
+  let client = null;
+  try {
+    const transport = buildMcpTransport(config);
+    client = await experimental_createMCPClient({
+      transport,
+      name: config.clientName,
+      version: config.clientVersion
+    });
+    const tools = await client.tools();
+    const prefixedTools = prefixToolNames(config, tools);
+    const connectedClient = client;
+    return {
+      tools: prefixedTools,
+      cleanup: () => connectedClient.close(),
+      serverToolNames: {
+        [config.name]: Object.keys(prefixedTools)
+      }
+    };
+  } catch (error) {
+    if (client) {
+      await client.close().catch(() => {
+        return;
+      });
+    }
+    throw new Error(`[MCP:${config.name}] Failed to connect tools: ${getErrorMessage(error)}`);
+  }
+}
+async function createMcpToolsets(configs, options = {}) {
+  const connected = [];
+  try {
+    for (const config of configs) {
+      const result = await mcpServerToTools(config);
+      connected.push(result);
+    }
+  } catch (error) {
+    await Promise.allSettled(connected.map((result) => result.cleanup()));
+    throw error;
+  }
+  const combinedTools = {};
+  const serverToolNames = {};
+  const collisionStrategy = options.onNameCollision ?? "overwrite";
+  try {
+    for (const result of connected) {
+      for (const [serverName, toolNames] of Object.entries(result.serverToolNames)) {
+        serverToolNames[serverName] = toolNames;
+      }
+      for (const [toolName, tool2] of Object.entries(result.tools)) {
+        const hasCollision = combinedTools[toolName] !== undefined;
+        if (hasCollision && collisionStrategy === "error") {
+          throw new Error(`Duplicate MCP tool name "${toolName}" detected. Use "toolPrefix" or set onNameCollision to "overwrite".`);
+        }
+        combinedTools[toolName] = tool2;
+      }
+    }
+  } catch (error) {
+    await Promise.allSettled(connected.map((result) => result.cleanup()));
+    throw error;
+  }
+  return {
+    tools: combinedTools,
+    serverToolNames,
+    cleanup: async () => {
+      const cleanupResults = await Promise.allSettled(connected.map((result) => result.cleanup()));
+      const failures = cleanupResults.filter((result) => result.status === "rejected");
+      if (failures.length > 0) {
+        throw new Error(`Failed to cleanup ${failures.length} MCP client connection(s).`);
+      }
+    }
+  };
+}
+var init_mcp_client = __esm(() => {
+  init_mcp_client_helpers();
+});
+
+// src/tools/memory-tools.ts
+import { anthropic } from "@ai-sdk/anthropic";
+function createAnthropicMemoryTool(store) {
+  const memory = anthropic.tools.memory_20250818({
+    execute: async (action) => {
+      switch (action.command) {
+        case "view":
+          return store.view(action.path ?? "/memories", action.view_range);
+        case "create":
+          return store.create(action.path ?? "/memories/untitled", action.file_text ?? "");
+        case "str_replace":
+          return store.strReplace(action.path ?? "/memories", action.old_str ?? "", action.new_str ?? "");
+        case "insert":
+          return store.insert(action.path ?? "/memories", action.insert_line ?? 0, action.insert_text ?? "");
+        case "delete":
+          return store.delete(action.path ?? "/memories");
+        case "rename":
+          return store.rename(action.old_path ?? "/memories", action.new_path ?? "/memories");
+        default:
+          return `Unknown command: ${action.command}`;
+      }
+    }
+  });
+  return memory;
+}
+var init_memory_tools = () => {};
+
+// src/schema/json-schema-to-zod.ts
+import { z as z2 } from "zod";
+function jsonSchemaToZod(schema) {
+  const s = schema;
+  const makeNullable = (zodSchema) => {
+    return s.nullable ? z2.union([zodSchema, z2.null()]) : zodSchema;
+  };
+  if (s.const !== undefined) {
+    return z2.literal(s.const);
+  }
+  if (s.enum) {
+    const values = s.enum;
+    return makeNullable(z2.enum(values.map(String)));
+  }
+  if (s.anyOf && s.anyOf.length > 0) {
+    const schemas = s.anyOf.map((sub) => jsonSchemaToZod(sub));
+    if (schemas.length === 1)
+      return schemas[0] ?? z2.unknown();
+    return z2.union([
+      schemas[0] ?? z2.unknown(),
+      schemas[1] ?? z2.unknown(),
+      ...schemas.slice(2)
+    ]);
+  }
+  if (s.oneOf && s.oneOf.length > 0) {
+    const schemas = s.oneOf.map((sub) => jsonSchemaToZod(sub));
+    if (schemas.length === 1)
+      return schemas[0] ?? z2.unknown();
+    return z2.union([
+      schemas[0] ?? z2.unknown(),
+      schemas[1] ?? z2.unknown(),
+      ...schemas.slice(2)
+    ]);
+  }
+  if (s.allOf && s.allOf.length > 0) {
+    const schemas = s.allOf.map((sub) => jsonSchemaToZod(sub));
+    return schemas.reduce((acc, curr) => z2.intersection(acc, curr));
+  }
+  switch (s.type) {
+    case "string":
+      return makeNullable(buildStringSchema(s));
+    case "number":
+    case "integer":
+      return makeNullable(buildNumberSchema(s));
+    case "boolean":
+      return makeNullable(z2.boolean());
+    case "null":
+      return z2.null();
+    case "array":
+      return makeNullable(buildArraySchema(s));
+    case "object":
+      return makeNullable(buildObjectSchema(s));
+    default:
+      return z2.unknown();
+  }
+}
+function buildStringSchema(schema) {
+  let zodSchema = z2.string();
+  if (schema.description) {
+    zodSchema = zodSchema.describe(schema.description);
+  }
+  switch (schema.format) {
+    case "email":
+      zodSchema = zodSchema.email();
+      break;
+    case "uri":
+    case "url":
+      zodSchema = zodSchema.url();
+      break;
+    case "uuid":
+      zodSchema = zodSchema.uuid();
+      break;
+    case "date-time":
+      zodSchema = zodSchema.datetime();
+      break;
+    case "date":
+      zodSchema = zodSchema.date();
+      break;
+  }
+  if (schema.minLength !== undefined) {
+    zodSchema = zodSchema.min(schema.minLength);
+  }
+  if (schema.maxLength !== undefined) {
+    zodSchema = zodSchema.max(schema.maxLength);
+  }
+  if (schema.pattern) {
+    zodSchema = zodSchema.regex(new RegExp(schema.pattern));
+  }
+  return zodSchema;
+}
+function buildNumberSchema(schema) {
+  let zodSchema = schema.type === "integer" ? z2.number().int() : z2.number();
+  if (schema.description) {
+    zodSchema = zodSchema.describe(schema.description);
+  }
+  if (schema.minimum !== undefined) {
+    zodSchema = zodSchema.min(schema.minimum);
+  }
+  if (schema.maximum !== undefined) {
+    zodSchema = zodSchema.max(schema.maximum);
+  }
+  return zodSchema;
+}
+function buildArraySchema(schema) {
+  const itemsSchema = schema.items ? jsonSchemaToZod(schema.items) : z2.unknown();
+  let zodSchema = z2.array(itemsSchema);
+  if (schema.description) {
+    zodSchema = zodSchema.describe(schema.description);
+  }
+  return zodSchema;
+}
+function buildObjectSchema(schema) {
+  const properties = schema.properties ?? {};
+  const required = new Set(schema.required ?? []);
+  const shape = {};
+  for (const [key, propSchema] of Object.entries(properties)) {
+    const zodProp = jsonSchemaToZod(propSchema);
+    shape[key] = required.has(key) ? zodProp : zodProp.optional();
+  }
+  let zodSchema = z2.object(shape);
+  if (schema.description) {
+    zodSchema = zodSchema.describe(schema.description);
+  }
+  return zodSchema;
+}
+function jsonSchemaToZodSafe(schema) {
+  if (!schema || Object.keys(schema).length === 0) {
+    return z2.object({});
+  }
+  return jsonSchemaToZod(schema);
+}
+var init_json_schema_to_zod = () => {};
+
+// src/tools/operation-tool-handler.ts
+function toolCtxToHandlerCtx(ctx) {
+  return {
+    traceId: ctx.metadata?.traceId,
+    organizationId: ctx.tenantId ?? null,
+    userId: ctx.actorId ?? null,
+    actor: ctx.actorId ? "user" : "anonymous",
+    channel: "agent",
+    roles: []
+  };
+}
+function createOperationToolHandler(registry, operationRef) {
+  return async (input, context) => {
+    const handlerCtx = toolCtxToHandlerCtx(context);
+    const result = await registry.execute(operationRef.key, operationRef.version, input ?? {}, handlerCtx);
+    return result;
+  };
+}
+
+// src/tools/subagent-tool.ts
+import { readUIMessageStream, tool as tool2 } from "ai";
+import { z as z3 } from "zod";
+function toReadableStream(iterable) {
+  if (iterable instanceof ReadableStream) {
+    return iterable;
+  }
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const chunk of iterable) {
+          controller.enqueue(chunk);
+        }
+      } finally {
+        controller.close();
+      }
+    }
+  });
+}
+function createSubagentTool(options) {
+  const {
+    subagent,
+    description = "Research a topic or question in depth.",
+    taskParam = "task",
+    toModelSummary = true,
+    passConversationHistory = false
+  } = options;
+  const inputSchema = z3.object({
+    [taskParam]: z3.string().describe("The research task to complete")
+  });
+  const execute = async function* (input, options2) {
+    const task = String(input[taskParam] ?? input.task ?? "");
+    const { abortSignal, messages } = options2 ?? {};
+    if (passConversationHistory && messages && messages.length > 0 && typeof subagent.generate === "function") {
+      const result2 = await subagent.generate({
+        messages: [...messages, { role: "user", content: task }],
+        abortSignal
+      });
+      yield { parts: [{ type: "text", text: result2.text }] };
+      return;
+    }
+    const result = await subagent.stream({
+      prompt: task,
+      abortSignal
+    });
+    const uiStream = result.toUIMessageStream();
+    const stream = toReadableStream(uiStream);
+    for await (const message of readUIMessageStream({
+      stream
+    })) {
+      yield message;
+    }
+  };
+  const toolOptions = {
+    description,
+    inputSchema,
+    execute,
+    ...toModelSummary && {
+      toModelOutput: ({
+        output
+      }) => {
+        const parts = output?.parts;
+        if (!Array.isArray(parts)) {
+          return { type: "text", value: "Task completed." };
+        }
+        const lastTextPart = [...parts].reverse().find((p) => p?.type === "text");
+        return {
+          type: "text",
+          value: lastTextPart?.text ?? "Task completed."
+        };
+      }
+    }
+  };
+  return tool2(toolOptions);
+}
+var init_subagent_tool = () => {};
+
+// src/tools/tool-adapter.ts
+import { tool as tool3 } from "ai";
+function isAsyncGenerator(value) {
+  return typeof value === "object" && value !== null && typeof value.next === "function" && typeof value[Symbol.asyncIterator] === "function";
+}
+function specToolToAISDKTool(specTool, handler, context = {}, effectiveInputSchema, operationSpec) {
+  let lastInvocationAt;
+  const inputSchema = effectiveInputSchema ?? jsonSchemaToZodSafe(specTool.schema);
+  const buildContext = (signal) => ({
+    agentId: context.agentId ?? "unknown",
+    sessionId: context.sessionId ?? "unknown",
+    tenantId: context.tenantId,
+    actorId: context.actorId,
+    locale: context.locale,
+    metadata: context.metadata,
+    signal
+  });
+  return tool3({
+    description: specTool.description ?? specTool.name,
+    inputSchema,
+    needsApproval: specTool.requiresApproval ?? !specTool.automationSafe,
+    execute: async function* (input, options) {
+      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 = options?.abortSignal ?? context.signal;
+      const { signal: timeoutSignal, dispose } = createTimeoutSignal(signal, timeoutMs);
+      try {
+        const execution = handler(input, buildContext(timeoutSignal));
+        if (isAsyncGenerator(execution)) {
+          for await (const raw of execution) {
+            const wrapped = wrapToolOutputForRendering(specTool, raw, operationSpec);
+            yield typeof wrapped === "string" ? wrapped : wrapped;
+          }
+        } else {
+          const raw = timeoutMs ? await withTimeout(Promise.resolve(execution), timeoutMs, specTool.name) : await Promise.resolve(execution);
+          const wrapped = wrapToolOutputForRendering(specTool, raw, operationSpec);
+          yield typeof wrapped === "string" ? wrapped : wrapped;
+        }
+      } finally {
+        dispose();
+        lastInvocationAt = Date.now();
+      }
+    }
+  });
+}
+function specToolsToAISDKTools(specTools, handlers, context = {}, options) {
+  const tools = {};
+  for (const specTool of specTools) {
+    if (specTool.subagentRef && options?.subagentRegistry) {
+      const subagent = options.subagentRegistry.get(specTool.subagentRef.agentId);
+      if (!subagent) {
+        throw new Error(`Subagent not found: ${specTool.subagentRef.agentId}. Register it in subagentRegistry.`);
+      }
+      if (specTool.requiresApproval === true || specTool.automationSafe === false) {
+        console.warn(`[ContractSpec] Subagent tool "${specTool.name}" cannot use needsApproval. ` + `requiresApproval and automationSafe are ignored for subagent tools (AI SDK limitation). ` + `See https://ai-sdk.dev/docs/agents/subagents#no-tool-approvals-in-subagents`);
+      }
+      tools[specTool.name] = createSubagentTool({
+        subagent,
+        description: specTool.description ?? specTool.name,
+        toModelSummary: specTool.subagentRef.toModelSummary ?? true,
+        passConversationHistory: specTool.subagentRef.passConversationHistory
+      });
+      continue;
+    }
+    let handler;
+    let effectiveInputSchema;
+    let op;
+    if (specTool.operationRef && options?.operationRegistry) {
+      op = options.operationRegistry.get(specTool.operationRef.key, specTool.operationRef.version);
+      if (!op) {
+        throw new Error(`Operation not found: ${specTool.operationRef.key}${specTool.operationRef.version ? `.v${specTool.operationRef.version}` : ""}`);
+      }
+      handler = createOperationToolHandler(options.operationRegistry, specTool.operationRef);
+      effectiveInputSchema = op.io.input?.getZod?.();
+    } else {
+      const manualHandler = handlers.get(specTool.name);
+      if (!manualHandler) {
+        if (specTool.subagentRef) {
+          throw new Error(`Subagent tool "${specTool.name}" requires subagentRegistry. Pass subagentRegistry in ContractSpecAgentConfig.`);
+        }
+        throw new Error(createAgentI18n(context.locale).t("error.missingToolHandler", {
+          name: specTool.name
+        }));
+      }
+      handler = manualHandler;
+    }
+    tools[specTool.name] = specToolToAISDKTool(specTool, handler, context, effectiveInputSchema, op);
+  }
+  return tools;
+}
+function createToolHandler(handler) {
+  return (input, context) => {
+    return handler(input, context);
+  };
+}
+function buildToolHandlers(handlersObj) {
+  return new Map(Object.entries(handlersObj));
+}
+function wrapToolOutputForRendering(specTool, result, operationSpec) {
+  const presentation = specTool.outputPresentation ?? operationSpec?.outputPresentation;
+  const form = specTool.outputForm ?? operationSpec?.outputForm;
+  const dataView = specTool.outputDataView ?? operationSpec?.outputDataView;
+  if (presentation) {
+    return {
+      presentationKey: presentation.key,
+      data: result
+    };
+  }
+  if (form) {
+    return {
+      formKey: form.key,
+      defaultValues: typeof result === "object" && result !== null ? result : {}
+    };
+  }
+  if (dataView) {
+    return {
+      dataViewKey: dataView.key,
+      items: Array.isArray(result) ? result : result != null ? [result] : []
+    };
+  }
+  return result;
+}
+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_i18n();
+  init_json_schema_to_zod();
+  init_subagent_tool();
+});
+
+// src/telemetry/posthog.ts
+var exports_posthog = {};
+__export(exports_posthog, {
+  createPostHogTracedModel: () => createPostHogTracedModel,
+  createPostHogTelemetryCollector: () => createPostHogTelemetryCollector,
+  createCompositeTelemetryCollector: () => createCompositeTelemetryCollector,
+  PostHogTelemetryCollector: () => PostHogTelemetryCollector,
+  CompositeTelemetryCollector: () => CompositeTelemetryCollector
+});
+async function createPostHogTracedModel(model, config, overrides) {
+  const { withTracing } = await importPostHogAI();
+  const phClient = await resolvePostHogClient(config);
+  const tracingOptions = {
+    ...config.defaults,
+    ...overrides
+  };
+  return withTracing(model, phClient, tracingOptions);
+}
+
+class PostHogTelemetryCollector {
+  phClient;
+  config;
+  initPromise;
+  constructor(config) {
+    this.config = config;
+    this.phClient = config.client;
+  }
+  async collect(sample) {
+    const client = await this.getClient();
+    const metadata = asRecord(sample.metadata);
+    const distinctId = this.config.defaults?.posthogDistinctId ?? asString(metadata["actorId"]) ?? "system";
+    const traceId = asString(metadata["traceId"]) ?? this.config.defaults?.posthogTraceId;
+    const sessionId = asString(metadata["sessionId"]);
+    const telemetryEvent = asString(metadata["telemetryEvent"]);
+    const event = telemetryEvent === "span" ? "$ai_span" : "$ai_generation";
+    const tokenUsage = metadata["tokenUsage"];
+    const totalUsage = metadata["totalUsage"];
+    const errorMessage = asString(metadata["errorMessage"]);
+    client.capture({
+      distinctId,
+      event,
+      properties: {
+        $ai_model: asString(metadata["responseModelId"]) ?? sample.operation.name,
+        $ai_provider: asString(metadata["provider"]) ?? "contractspec",
+        $ai_latency: sample.durationMs / 1000,
+        $ai_is_error: !sample.success,
+        $ai_error: !sample.success ? errorMessage : undefined,
+        $ai_trace_id: traceId,
+        $ai_session_id: sessionId,
+        $ai_span_id: asString(metadata["spanId"]),
+        $ai_parent_id: asString(metadata["parentSpanId"]),
+        $ai_span_name: asString(metadata["spanName"]) ?? sample.operation.name,
+        ...tokenUsage ? mapTokenUsage(tokenUsage) : {},
+        ...totalUsage ? mapTotalUsage(totalUsage) : {},
+        $ai_http_status: asNumber(metadata["httpStatus"]),
+        $ai_request_url: asString(metadata["requestUrl"]),
+        $ai_base_url: asString(metadata["baseUrl"]),
+        ...this.config.defaults?.posthogProperties,
+        contractspec_operation: sample.operation.name,
+        contractspec_version: sample.operation.version,
+        contractspec_agent_id: asString(metadata["agentId"]),
+        contractspec_tenant_id: asString(metadata["tenantId"]),
+        contractspec_actor_id: asString(metadata["actorId"]),
+        contractspec_step_index: asNumber(metadata["stepIndex"]),
+        contractspec_step_started_at: asDateIso(metadata["stepStartedAt"]),
+        contractspec_finish_reason: asString(metadata["finishReason"]),
+        contractspec_finish_reason_raw: asString(metadata["rawFinishReason"]),
+        contractspec_tool_count: asNumber(metadata["toolCallCount"]),
+        contractspec_tool_name: asString(metadata["toolName"]),
+        contractspec_tool_call_args: metadata["toolCallArgs"],
+        contractspec_tool_result_output: metadata["toolResultOutput"],
+        contractspec_provider_metadata: metadata["providerMetadata"],
+        contractspec_step_warnings: metadata["warnings"],
+        contractspec_response_id: asString(metadata["responseId"]),
+        contractspec_response_model_id: asString(metadata["responseModelId"]),
+        contractspec_response_timestamp: asDateIso(metadata["responseTimestamp"]),
+        contractspec_response_headers: metadata["responseHeaders"],
+        contractspec_response_body: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["responseBody"],
+        contractspec_response_messages: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["responseMessages"],
+        contractspec_request_headers: metadata["requestHeaders"],
+        contractspec_request_body: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["requestBody"],
+        contractspec_step_text: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["stepText"],
+        contractspec_step_reasoning_text: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["stepReasoningText"]
+      },
+      groups: this.config.defaults?.posthogGroups
+    });
+  }
+  async shutdown() {
+    if (this.phClient?.shutdown) {
+      await this.phClient.shutdown();
+    }
+  }
+  async getClient() {
+    if (this.phClient)
+      return this.phClient;
+    if (!this.initPromise) {
+      this.initPromise = resolvePostHogClient(this.config).then((client) => {
+        this.phClient = client;
+        return client;
+      });
+    }
+    return this.initPromise;
+  }
+}
+function createPostHogTelemetryCollector(config) {
+  return new PostHogTelemetryCollector(config);
+}
+
+class CompositeTelemetryCollector {
+  collectors;
+  constructor(collectors) {
+    this.collectors = collectors;
+  }
+  async collect(sample) {
+    await Promise.all(this.collectors.map((c) => c.collect(sample)));
+  }
+}
+function createCompositeTelemetryCollector(collectors) {
+  return new CompositeTelemetryCollector(collectors);
+}
+async function importPostHogAI() {
+  try {
+    return await runtimeImport("@posthog/ai");
+  } catch {
+    throw new Error(createAgentI18n().t("error.telemetry.posthogAiRequired"));
+  }
+}
+async function resolvePostHogClient(config) {
+  if (config.client)
+    return config.client;
+  if (!config.apiKey) {
+    throw new Error(createAgentI18n().t("error.telemetry.posthogClientOrKeyRequired"));
+  }
+  try {
+    const { PostHog } = await runtimeImport("posthog-node");
+    return new PostHog(config.apiKey, {
+      host: config.host ?? "https://us.i.posthog.com"
+    });
+  } catch {
+    throw new Error(createAgentI18n().t("error.telemetry.posthogNodeRequired"));
+  }
+}
+function mapTokenUsage(usage) {
+  const usageRecord = asRecord(usage);
+  const inputTokenDetails = asRecord(usageRecord["inputTokenDetails"]);
+  const outputTokenDetails = asRecord(usageRecord["outputTokenDetails"]);
+  return {
+    $ai_input_tokens: asNumber(usageRecord["inputTokens"]) ?? asNumber(usageRecord["promptTokens"]),
+    $ai_output_tokens: asNumber(usageRecord["outputTokens"]) ?? asNumber(usageRecord["completionTokens"]),
+    $ai_reasoning_tokens: asNumber(outputTokenDetails["reasoningTokens"]) ?? asNumber(usageRecord["reasoningTokens"]),
+    $ai_cache_read_input_tokens: asNumber(inputTokenDetails["cacheReadTokens"]) ?? asNumber(usageRecord["cachedInputTokens"]),
+    $ai_cache_creation_input_tokens: asNumber(inputTokenDetails["cacheWriteTokens"]),
+    $ai_usage: maybeRecord(usageRecord["raw"]) ?? usageRecord
+  };
+}
+function mapTotalUsage(usage) {
+  const usageRecord = asRecord(usage);
+  return {
+    contractspec_total_input_tokens: asNumber(usageRecord["inputTokens"]),
+    contractspec_total_output_tokens: asNumber(usageRecord["outputTokens"]),
+    contractspec_total_tokens: asNumber(usageRecord["totalTokens"]),
+    contractspec_total_usage_raw: maybeRecord(usageRecord["raw"]) ?? usageRecord
+  };
+}
+function asRecord(value) {
+  return value && typeof value === "object" ? value : {};
+}
+function maybeRecord(value) {
+  return value && typeof value === "object" ? value : undefined;
+}
+function asString(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function asNumber(value) {
+  return typeof value === "number" ? value : undefined;
+}
+function asDateIso(value) {
+  if (value instanceof Date)
+    return value.toISOString();
+  return;
+}
+var runtimeImport;
+var init_posthog = __esm(() => {
+  init_i18n();
+  runtimeImport = new Function("specifier", "return import(specifier)");
+});
+
+// src/agent/contract-spec-agent.ts
+var exports_contract_spec_agent = {};
+__export(exports_contract_spec_agent, {
+  ContractSpecAgent: () => ContractSpecAgent
+});
+import { randomUUID as randomUUID2 } from "node:crypto";
+import {
+  agentKey
+} from "@contractspec/lib.contracts-spec/agent";
+import {
+  stepCountIs,
+  Experimental_Agent as ToolLoopAgent
+} from "ai";
+import * as z4 from "zod";
+
+class ContractSpecAgent {
+  version = "agent-v1";
+  id;
+  spec;
+  tools;
+  config;
+  instructions;
+  mcpCleanup;
+  activeStepContexts = new Map;
+  constructor(config, instructions, tools, mcpCleanup) {
+    this.config = config;
+    this.spec = config.spec;
+    this.id = agentKey(config.spec.meta);
+    this.tools = tools;
+    this.instructions = instructions;
+    this.mcpCleanup = mcpCleanup;
+  }
+  static async create(config) {
+    const effectiveConfig = {
+      ...config,
+      approvalWorkflow: config.approvalWorkflow ?? (config.spec.policy?.escalation?.approvalWorkflow ? createApprovalWorkflow() : undefined)
+    };
+    let mcpToolset = null;
+    if ((effectiveConfig.mcpServers?.length ?? 0) > 0) {
+      mcpToolset = await createMcpToolsets(effectiveConfig.mcpServers ?? [], {
+        onNameCollision: "error"
+      });
+    }
+    try {
+      const instructions = await injectStaticKnowledge(effectiveConfig.spec.instructions, effectiveConfig.spec.knowledge ?? [], effectiveConfig.knowledgeRetriever);
+      const specTools = specToolsToAISDKTools(effectiveConfig.spec.tools, effectiveConfig.toolHandlers, { agentId: agentKey(effectiveConfig.spec.meta) }, {
+        operationRegistry: effectiveConfig.operationRegistry,
+        subagentRegistry: effectiveConfig.subagentRegistry
+      });
+      const knowledgeTool = effectiveConfig.knowledgeRetriever ? createKnowledgeQueryTool(effectiveConfig.knowledgeRetriever, effectiveConfig.spec.knowledge ?? []) : null;
+      const memoryTool = effectiveConfig.spec.memoryTools?.provider === "anthropic" && effectiveConfig.agentMemoryStore ? createAnthropicMemoryTool(effectiveConfig.agentMemoryStore) : null;
+      const reservedToolNames = new Set(Object.keys(specTools));
+      if (knowledgeTool) {
+        reservedToolNames.add("query_knowledge");
+      }
+      if (memoryTool) {
+        reservedToolNames.add("memory");
+      }
+      const conflictingMcpTools = Object.keys(mcpToolset?.tools ?? {}).filter((toolName) => reservedToolNames.has(toolName));
+      if (conflictingMcpTools.length > 0) {
+        throw new Error(`MCP tools conflict with agent tools: ${conflictingMcpTools.join(", ")}. Configure MCP toolPrefix values to avoid collisions.`);
+      }
+      const tools = {
+        ...specTools,
+        ...knowledgeTool ? { query_knowledge: knowledgeTool } : {},
+        ...memoryTool ? { memory: memoryTool } : {},
+        ...mcpToolset?.tools ?? {},
+        ...effectiveConfig.additionalTools ?? {}
+      };
+      return new ContractSpecAgent(effectiveConfig, instructions, tools, mcpToolset?.cleanup);
+    } catch (error) {
+      if (mcpToolset) {
+        await mcpToolset.cleanup().catch(() => {
+          return;
+        });
+      }
+      throw error;
+    }
+  }
+  async cleanup() {
+    if (!this.mcpCleanup) {
+      return;
+    }
+    const cleanup = this.mcpCleanup;
+    this.mcpCleanup = undefined;
+    await cleanup();
+  }
+  async generate(params) {
+    const sessionId = params.options?.sessionId ?? generateSessionId();
+    const traceId = params.options?.metadata?.["traceId"] ?? this.config.posthogConfig?.tracingOptions?.posthogTraceId ?? randomUUID2();
+    const workflowId = params.options?.workflowId ?? params.options?.metadata?.["workflowId"];
+    const threadId = params.options?.threadId ?? params.options?.metadata?.["threadId"];
+    const runtimeAdapter = this.resolveRuntimeAdapter();
+    this.activeStepContexts.set(sessionId, {
+      traceId,
+      tenantId: params.options?.tenantId,
+      actorId: params.options?.actorId,
+      workflowId,
+      threadId,
+      stepIndex: 0,
+      stepStartedAt: new Date
+    });
+    if (!params.messages?.length) {
+      await this.ensureSession({
+        sessionId,
+        prompt: params.prompt ?? "",
+        options: params.options,
+        traceId
+      });
+      await this.runSessionMiddleware(sessionId, runtimeAdapter?.middleware?.beforeModel);
+    }
+    const model = await this.resolveModelForCall({
+      sessionId,
+      traceId,
+      options: params.options
+    });
+    const effectiveMaxSteps = resolveMaxSteps(params.maxSteps, this.spec.maxSteps);
+    const inner = this.createInnerAgent(model, effectiveMaxSteps);
+    const generateOptions = {
+      abortSignal: params.signal,
+      options: {
+        tenantId: params.options?.tenantId,
+        actorId: params.options?.actorId,
+        sessionId,
+        workflowId,
+        threadId,
+        metadata: params.options?.metadata
+      }
+    };
+    let result;
+    try {
+      if (params.messages && params.messages.length > 0) {
+        result = await inner.generate({
+          messages: params.messages,
+          ...generateOptions
+        });
+      } else {
+        const prompt = params.systemOverride && params.prompt ? `${this.instructions}
+
+${params.systemOverride}
+
+${params.prompt}` : params.prompt ?? "";
+        result = await inner.generate({
+          prompt,
+          ...generateOptions
+        });
+      }
+    } catch (error) {
+      const executionError = toAgentExecutionError(error);
+      if (this.config.sessionStore) {
+        await this.config.sessionStore.update(sessionId, {
+          status: "failed",
+          traceId,
+          workflowId,
+          threadId,
+          lastError: executionError
+        });
+        await this.syncSessionCheckpoint(sessionId);
+      }
+      await this.emitAgentEvent("agent.failed", {
+        sessionId,
+        tenantId: params.options?.tenantId,
+        workflowId,
+        traceId,
+        metadata: {
+          error: executionError.message,
+          code: executionError.code ?? executionError.kind
+        }
+      });
+      this.activeStepContexts.delete(sessionId);
+      throw error;
+    }
+    if (!params.messages?.length) {
+      await this.runSessionMiddleware(sessionId, runtimeAdapter?.middleware?.afterModel);
+    }
+    let pendingApproval = this.activeStepContexts.get(sessionId)?.pendingApproval;
+    const escalationError = pendingApproval ? undefined : resolveEscalationError(this.spec, result.finishReason);
+    if (this.config.sessionStore && result.text.trim().length > 0) {
+      const currentSession = await this.config.sessionStore.get(sessionId);
+      const lastMessage = currentSession?.messages.at(-1);
+      const lastContent = lastMessage && "content" in lastMessage ? lastMessage.content : undefined;
+      if (lastMessage?.role !== "assistant" || lastContent !== result.text) {
+        await this.config.sessionStore.appendMessage(sessionId, {
+          role: "assistant",
+          content: result.text
+        });
+      }
+    }
+    if (!pendingApproval && escalationError) {
+      pendingApproval = await this.requestApproval(sessionId, {
+        toolName: this.spec.policy?.escalation?.approvalWorkflow ?? "approval_required",
+        toolCallId: `approval_${sessionId}`,
+        args: {
+          finishReason: result.finishReason,
+          threshold: this.spec.policy?.escalation?.confidenceThreshold ?? this.spec.policy?.confidence?.min
+        },
+        reason: escalationError.message,
+        error: escalationError
+      });
+    }
+    const finalStatus = pendingApproval ? "escalated" : "completed";
+    if (this.config.sessionStore) {
+      await this.config.sessionStore.update(sessionId, {
+        status: finalStatus,
+        traceId,
+        workflowId,
+        threadId,
+        pendingApprovalRequestId: pendingApproval?.id,
+        lastError: pendingApproval ? escalationError : undefined
+      });
+      await this.syncSessionCheckpoint(sessionId);
+    }
+    if (pendingApproval) {
+      await this.emitAgentEvent("agent.escalated", {
+        sessionId,
+        tenantId: params.options?.tenantId,
+        workflowId,
+        traceId,
+        metadata: {
+          approvalRequestId: pendingApproval.id,
+          reason: pendingApproval.reason
+        }
+      });
+    } else {
+      await this.emitAgentEvent("agent.completed", {
+        sessionId,
+        tenantId: params.options?.tenantId,
+        workflowId,
+        traceId,
+        metadata: {
+          finishReason: result.finishReason
+        }
+      });
+    }
+    const session = this.config.sessionStore ? await this.config.sessionStore.get(sessionId) : null;
+    this.activeStepContexts.delete(sessionId);
+    return {
+      text: result.text,
+      steps: result.steps,
+      toolCalls: result.toolCalls.map((tc) => ({
+        type: "tool-call",
+        toolCallId: tc.toolCallId,
+        toolName: tc.toolName,
+        args: "args" in tc ? tc.args : ("input" in tc) ? tc.input : undefined
+      })),
+      toolResults: result.toolResults.map((tr) => ({
+        type: "tool-result",
+        toolCallId: tr.toolCallId,
+        toolName: tr.toolName,
+        output: tr.output
+      })),
+      finishReason: result.finishReason,
+      usage: result.usage,
+      session: session ?? undefined,
+      pendingApproval: pendingApproval ? {
+        toolName: pendingApproval.toolName,
+        toolCallId: pendingApproval.toolCallId,
+        args: pendingApproval.toolArgs
+      } : undefined
+    };
+  }
+  async stream(params) {
+    const sessionId = params.options?.sessionId ?? generateSessionId();
+    const traceId = params.options?.metadata?.["traceId"] ?? this.config.posthogConfig?.tracingOptions?.posthogTraceId ?? randomUUID2();
+    const workflowId = params.options?.workflowId ?? params.options?.metadata?.["workflowId"];
+    const threadId = params.options?.threadId ?? params.options?.metadata?.["threadId"];
+    const runtimeAdapter = this.resolveRuntimeAdapter();
+    this.activeStepContexts.set(sessionId, {
+      traceId,
+      tenantId: params.options?.tenantId,
+      actorId: params.options?.actorId,
+      workflowId,
+      threadId,
+      stepIndex: 0,
+      stepStartedAt: new Date
+    });
+    const prompt = params.systemOverride && params.prompt ? `${this.instructions}
+
+${params.systemOverride}
+
+${params.prompt}` : params.prompt ?? "";
+    await this.ensureSession({
+      sessionId,
+      prompt,
+      options: params.options,
+      traceId
+    });
+    await this.runSessionMiddleware(sessionId, runtimeAdapter?.middleware?.beforeModel);
+    const model = await this.resolveModelForCall({
+      sessionId,
+      traceId,
+      options: params.options
+    });
+    const effectiveMaxSteps = resolveMaxSteps(params.maxSteps, this.spec.maxSteps);
+    const inner = this.createInnerAgent(model, effectiveMaxSteps);
+    return inner.stream({
+      prompt,
+      abortSignal: params.signal,
+      options: {
+        tenantId: params.options?.tenantId,
+        actorId: params.options?.actorId,
+        sessionId,
+        workflowId,
+        threadId,
+        metadata: params.options?.metadata
+      }
+    });
+  }
+  async handleStepFinish(step) {
+    const sessionId = step.options?.sessionId;
+    const context = sessionId ? this.activeStepContexts.get(sessionId) : undefined;
+    if (sessionId && this.config.sessionStore) {
+      await this.config.sessionStore.appendStep(sessionId, step);
+      if (step.text.trim().length > 0) {
+        await this.config.sessionStore.appendMessage(sessionId, {
+          role: "assistant",
+          content: step.text
+        });
+      }
+      for (const toolCall of step.toolCalls ?? []) {
+        await this.emitAgentEvent("agent.tool.called", {
+          sessionId,
+          tenantId: context?.tenantId,
+          workflowId: context?.workflowId,
+          traceId: context?.traceId,
+          stepIndex: context?.stepIndex,
+          toolName: toolCall.toolName,
+          metadata: {
+            toolCallId: toolCall.toolCallId
+          }
+        });
+      }
+      for (const toolResult of step.toolResults ?? []) {
+        const toolCall = step.toolCalls?.find((candidate) => candidate.toolCallId === toolResult.toolCallId);
+        const toolError = extractToolExecutionError(toolResult.output);
+        await this.config.sessionStore.appendMessage(sessionId, {
+          role: "tool",
+          content: stringifyToolResult(toolResult.toolName, toolResult.output)
+        });
+        if (toolError) {
+          await this.emitAgentEvent("agent.tool.failed", {
+            sessionId,
+            tenantId: context?.tenantId,
+            workflowId: context?.workflowId,
+            traceId: context?.traceId,
+            stepIndex: context?.stepIndex,
+            toolName: toolResult.toolName,
+            metadata: {
+              toolCallId: toolResult.toolCallId,
+              error: toolError.message,
+              code: toolError.code
+            }
+          });
+          const shouldEscalate = toolError.kind === "timeout" && this.spec.policy?.escalation?.onTimeout || toolError.kind !== "timeout" && this.spec.policy?.escalation?.onToolFailure;
+          if (shouldEscalate && toolCall && !context?.pendingApproval) {
+            await this.requestApproval(sessionId, {
+              toolName: toolCall.toolName,
+              toolCallId: toolCall.toolCallId,
+              args: toolCall.input,
+              reason: toolError.message,
+              error: toolError
+            });
+          }
+        } else {
+          await this.emitAgentEvent("agent.tool.completed", {
+            sessionId,
+            tenantId: context?.tenantId,
+            workflowId: context?.workflowId,
+            traceId: context?.traceId,
+            stepIndex: context?.stepIndex,
+            toolName: toolResult.toolName,
+            metadata: {
+              toolCallId: toolResult.toolCallId
+            }
+          });
+        }
+      }
+      await this.config.sessionStore.update(sessionId, {
+        status: context?.pendingApproval ? "escalated" : step.finishReason === "tool-calls" ? "waiting" : "running",
+        workflowId: context?.workflowId,
+        threadId: context?.threadId,
+        traceId: context?.traceId,
+        pendingApprovalRequestId: context?.pendingApproval?.id
+      });
+      await this.syncSessionCheckpoint(sessionId);
+    }
+    if (this.config.telemetryCollector) {
+      const now = new Date;
+      const stepStartedAt = context?.stepStartedAt ?? now;
+      const durationMs = Math.max(now.getTime() - stepStartedAt.getTime(), 0);
+      if (context) {
+        context.stepIndex += 1;
+        context.stepStartedAt = now;
+      }
+      await trackAgentStep(this.config.telemetryCollector, this.id, step, durationMs, {
+        sessionId,
+        tenantId: context?.tenantId,
+        actorId: context?.actorId,
+        workflowId: context?.workflowId,
+        traceId: context?.traceId,
+        stepIndex: context?.stepIndex,
+        stepStartedAt
+      });
+      if (sessionId && step.finishReason !== "tool-calls") {
+        this.activeStepContexts.delete(sessionId);
+      }
+    }
+  }
+  async ensureSession(params) {
+    if (!this.config.sessionStore) {
+      return;
+    }
+    const runtimeAdapter = this.resolveRuntimeAdapter();
+    let session = await this.config.sessionStore.get(params.sessionId);
+    const previousStatus = session?.status;
+    if (!session && runtimeAdapter?.checkpoint) {
+      const checkpoint = await runtimeAdapter.checkpoint.load(params.sessionId);
+      if (checkpoint) {
+        session = await this.config.sessionStore.create({
+          ...omitSessionTimestamps(checkpoint.state),
+          workflowId: params.options?.workflowId ?? checkpoint.state.workflowId,
+          threadId: params.options?.threadId ?? checkpoint.state.threadId,
+          traceId: params.traceId,
+          checkpointId: checkpoint.checkpointId,
+          status: "running",
+          pendingApprovalRequestId: undefined,
+          lastError: undefined,
+          metadata: params.options?.metadata ?? checkpoint.state.metadata
+        });
+      }
+    }
+    if (!session) {
+      session = await this.config.sessionStore.create({
+        sessionId: params.sessionId,
+        agentId: this.id,
+        tenantId: params.options?.tenantId,
+        actorId: params.options?.actorId,
+        workflowId: params.options?.workflowId,
+        threadId: params.options?.threadId,
+        traceId: params.traceId,
+        status: "running",
+        messages: [],
+        steps: [],
+        metadata: params.options?.metadata
+      });
+      await this.emitAgentEvent("agent.session.created", {
+        sessionId: params.sessionId,
+        tenantId: params.options?.tenantId,
+        workflowId: params.options?.workflowId,
+        traceId: params.traceId
+      });
+    } else {
+      await this.config.sessionStore.update(params.sessionId, {
+        status: "running",
+        workflowId: params.options?.workflowId ?? session.workflowId,
+        threadId: params.options?.threadId ?? session.threadId,
+        traceId: params.traceId,
+        metadata: params.options?.metadata ?? session.metadata,
+        pendingApprovalRequestId: undefined,
+        lastError: undefined
+      });
+      await this.emitAgentEvent("agent.session.updated", {
+        sessionId: params.sessionId,
+        tenantId: params.options?.tenantId ?? session.tenantId,
+        workflowId: params.options?.workflowId ?? session.workflowId,
+        traceId: params.traceId,
+        metadata: {
+          previousStatus: previousStatus ?? "idle",
+          nextStatus: "running"
+        }
+      });
+    }
+    await this.config.sessionStore.appendMessage(params.sessionId, {
+      role: "user",
+      content: params.prompt
+    });
+    if (runtimeAdapter?.suspendResume && (previousStatus === "waiting" || previousStatus === "escalated")) {
+      await runtimeAdapter.suspendResume.resume({
+        sessionId: params.sessionId,
+        input: params.prompt,
+        metadata: compactStringRecord({
+          traceId: params.traceId,
+          workflowId: params.options?.workflowId,
+          threadId: params.options?.threadId
+        })
+      });
+    }
+    await this.syncSessionCheckpoint(params.sessionId);
+  }
+  resolveRuntimeAdapter() {
+    return resolveRuntimeAdapterBundle(this.spec, this.config.runtimeAdapters);
+  }
+  async syncSessionCheckpoint(sessionId) {
+    if (!this.config.sessionStore) {
+      return null;
+    }
+    const runtimeAdapter = this.resolveRuntimeAdapter();
+    const session = await this.config.sessionStore.get(sessionId);
+    if (!runtimeAdapter?.checkpoint || !session) {
+      return session;
+    }
+    const checkpointId = `${sessionId}:${Date.now()}`;
+    await runtimeAdapter.checkpoint.save({
+      sessionId,
+      threadId: session.threadId,
+      state: session,
+      checkpointId,
+      createdAt: new Date
+    });
+    await this.config.sessionStore.update(sessionId, {
+      checkpointId
+    });
+    return this.config.sessionStore.get(sessionId);
+  }
+  async runSessionMiddleware(sessionId, hook) {
+    if (!hook || !this.config.sessionStore) {
+      return;
+    }
+    const session = await this.config.sessionStore.get(sessionId);
+    if (!session) {
+      return;
+    }
+    const next = await hook(session);
+    if (!next) {
+      return;
+    }
+    await this.config.sessionStore.update(sessionId, {
+      status: next.status,
+      metadata: next.metadata,
+      workflowId: next.workflowId,
+      threadId: next.threadId,
+      traceId: next.traceId,
+      checkpointId: next.checkpointId,
+      pendingApprovalRequestId: next.pendingApprovalRequestId,
+      lastError: next.lastError
+    });
+    await this.syncSessionCheckpoint(sessionId);
+  }
+  async requestApproval(sessionId, params) {
+    const approvalWorkflow = this.config.approvalWorkflow;
+    const context = this.activeStepContexts.get(sessionId);
+    if (!approvalWorkflow || !context || context.pendingApproval) {
+      return context?.pendingApproval;
+    }
+    const request = await approvalWorkflow.requestApproval({
+      sessionId,
+      agentId: this.id,
+      tenantId: context.tenantId,
+      toolName: params.toolName,
+      toolCallId: params.toolCallId,
+      toolArgs: params.args,
+      reason: params.reason,
+      payload: {
+        traceId: context.traceId,
+        workflowId: context.workflowId,
+        threadId: context.threadId,
+        code: params.error?.code
+      }
+    });
+    context.pendingApproval = request;
+    if (this.config.sessionStore) {
+      await this.config.sessionStore.update(sessionId, {
+        status: "escalated",
+        pendingApprovalRequestId: request.id,
+        lastError: params.error
+      });
+      await this.syncSessionCheckpoint(sessionId);
+    }
+    await this.emitAgentEvent("agent.tool.approval_requested", {
+      sessionId,
+      tenantId: context.tenantId,
+      workflowId: context.workflowId,
+      traceId: context.traceId,
+      stepIndex: context.stepIndex,
+      toolName: params.toolName,
+      metadata: {
+        approvalRequestId: request.id,
+        toolCallId: params.toolCallId,
+        reason: params.reason
+      }
+    });
+    await this.emitAgentEvent("agent.escalated", {
+      sessionId,
+      tenantId: context.tenantId,
+      workflowId: context.workflowId,
+      traceId: context.traceId,
+      stepIndex: context.stepIndex,
+      toolName: params.toolName,
+      metadata: {
+        approvalRequestId: request.id,
+        reason: params.reason
+      }
+    });
+    const runtimeAdapter = this.resolveRuntimeAdapter();
+    if (runtimeAdapter?.suspendResume) {
+      await runtimeAdapter.suspendResume.suspend({
+        sessionId,
+        reason: params.reason,
+        metadata: compactStringRecord({
+          traceId: context.traceId,
+          workflowId: context.workflowId,
+          threadId: context.threadId,
+          approvalRequestId: request.id
+        })
+      });
+    }
+    return request;
+  }
+  async emitAgentEvent(event, payload) {
+    if (!this.config.eventEmitter) {
+      return;
+    }
+    await this.config.eventEmitter(event, {
+      agentId: this.id,
+      ...payload
+    });
+  }
+  createInnerAgent(model, maxSteps) {
+    return new ToolLoopAgent({
+      model,
+      instructions: this.instructions,
+      tools: this.tools,
+      stopWhen: stepCountIs(maxSteps),
+      callOptionsSchema: ContractSpecCallOptionsSchema,
+      onStepFinish: async (step) => {
+        await this.handleStepFinish(step);
+      }
+    });
+  }
+  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;
+    }
+    const mergedProperties = {
+      ...posthogConfig.defaults?.posthogProperties,
+      ...posthogConfig.tracingOptions?.posthogProperties,
+      $ai_session_id: params.sessionId,
+      contractspec_session_id: params.sessionId,
+      contractspec_trace_id: params.traceId,
+      contractspec_agent_id: this.id,
+      contractspec_tenant_id: params.options?.tenantId,
+      contractspec_actor_id: params.options?.actorId,
+      contractspec_workflow_id: params.options?.workflowId,
+      contractspec_thread_id: params.options?.threadId
+    };
+    const tracingOptions = {
+      ...posthogConfig.tracingOptions,
+      posthogDistinctId: posthogConfig.tracingOptions?.posthogDistinctId ?? params.options?.actorId,
+      posthogTraceId: params.traceId,
+      posthogProperties: mergedProperties
+    };
+    const { createPostHogTracedModel: createPostHogTracedModel2 } = await Promise.resolve().then(() => (init_posthog(), exports_posthog));
+    return createPostHogTracedModel2(this.config.model, posthogConfig, tracingOptions);
+  }
+}
+function omitSessionTimestamps(session) {
+  const { createdAt: _createdAt, updatedAt: _updatedAt, ...rest } = session;
+  return rest;
+}
+function resolveRuntimeAdapterBundle(spec, runtimeAdapters) {
+  if (!runtimeAdapters) {
+    return;
+  }
+  const preferredKeys = [
+    "langgraph",
+    "langchain",
+    "workflow-devkit"
+  ];
+  for (const key of preferredKeys) {
+    if (spec.runtime?.capabilities?.adapters?.[key] && runtimeAdapters[key]) {
+      return runtimeAdapters[key];
+    }
+  }
+  for (const key of preferredKeys) {
+    if (runtimeAdapters[key]) {
+      return runtimeAdapters[key];
+    }
+  }
+  return;
+}
+function compactStringRecord(input) {
+  return Object.fromEntries(Object.entries(input).filter((entry) => typeof entry[1] === "string" && entry[1].length > 0));
+}
+function toAgentExecutionError(error) {
+  if (error && typeof error === "object" && "kind" in error && typeof error.kind === "string" && "message" in error && typeof error.message === "string") {
+    return {
+      kind: error.kind,
+      message: error.message,
+      code: "code" in error && typeof error.code === "string" ? error.code : undefined,
+      retryAfterMs: "retryAfterMs" in error && typeof error.retryAfterMs === "number" ? error.retryAfterMs : undefined
+    };
+  }
+  if (error instanceof Error) {
+    return {
+      kind: error.message.toLowerCase().includes("timeout") || error.code === "TOOL_EXECUTION_TIMEOUT" ? "timeout" : "fatal",
+      message: error.message,
+      code: error.code
+    };
+  }
+  return {
+    kind: "fatal",
+    message: String(error)
+  };
+}
+function extractToolExecutionError(output) {
+  if (!output) {
+    return;
+  }
+  if (typeof output === "string") {
+    if (output.toLowerCase().includes("error")) {
+      return {
+        kind: output.toLowerCase().includes("timeout") ? "timeout" : "retryable",
+        message: output
+      };
+    }
+    return;
+  }
+  if (typeof output !== "object") {
+    return;
+  }
+  const record2 = output;
+  const nestedError = record2["error"];
+  if (nestedError instanceof Error) {
+    return toAgentExecutionError(nestedError);
+  }
+  if (nestedError && typeof nestedError === "object") {
+    return toAgentExecutionError(nestedError);
+  }
+  if (typeof record2["message"] === "string" && typeof record2["kind"] === "string") {
+    return {
+      kind: record2["kind"],
+      message: record2["message"],
+      code: typeof record2["code"] === "string" ? record2["code"] : undefined,
+      retryAfterMs: typeof record2["retryAfterMs"] === "number" ? record2["retryAfterMs"] : undefined
+    };
+  }
+  if (typeof record2["errorMessage"] === "string") {
+    return {
+      kind: typeof record2["errorCode"] === "string" && record2["errorCode"].includes("TIMEOUT") ? "timeout" : "retryable",
+      message: record2["errorMessage"],
+      code: typeof record2["errorCode"] === "string" ? record2["errorCode"] : undefined
+    };
+  }
+  return;
+}
+function stringifyToolResult(toolName, output) {
+  if (typeof output === "string") {
+    return `[${toolName}] ${output}`;
+  }
+  try {
+    return `[${toolName}] ${JSON.stringify(output)}`;
+  } catch {
+    return `[${toolName}] [unserializable result]`;
+  }
+}
+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_workflow();
+  init_injector();
+  init_adapter();
+  init_knowledge_tool();
+  init_mcp_client();
+  init_memory_tools();
+  init_tool_adapter();
+  ContractSpecCallOptionsSchema = z4.object({
+    tenantId: z4.string().optional(),
+    actorId: z4.string().optional(),
+    sessionId: z4.string().optional(),
+    workflowId: z4.string().optional(),
+    threadId: z4.string().optional(),
+    metadata: z4.record(z4.string(), z4.unknown()).optional()
+  });
+});
+
+// src/providers/types.ts
+var ExternalProviderError, ProviderNotAvailableError, ProviderExecutionError, ContextCreationError;
+var init_types = __esm(() => {
+  init_i18n();
+  ExternalProviderError = class ExternalProviderError extends Error {
+    provider;
+    code;
+    cause;
+    constructor(message, provider, code, cause) {
+      super(message);
+      this.provider = provider;
+      this.code = code;
+      this.cause = cause;
+      this.name = "ExternalProviderError";
+    }
+  };
+  ProviderNotAvailableError = class ProviderNotAvailableError extends ExternalProviderError {
+    constructor(provider, reason, locale) {
+      const i18n = createAgentI18n(locale);
+      super(i18n.t("error.provider.notAvailable", {
+        provider,
+        reason: reason ? `: ${reason}` : ""
+      }), provider, "PROVIDER_NOT_AVAILABLE");
+      this.name = "ProviderNotAvailableError";
+    }
+  };
+  ProviderExecutionError = class ProviderExecutionError extends ExternalProviderError {
+    constructor(provider, message, cause) {
+      super(message, provider, "EXECUTION_FAILED", cause);
+      this.name = "ProviderExecutionError";
+    }
+  };
+  ContextCreationError = class ContextCreationError extends ExternalProviderError {
+    constructor(provider, message, cause) {
+      super(message, provider, "CONTEXT_CREATION_FAILED", cause);
+      this.name = "ContextCreationError";
+    }
+  };
+});
+
+// src/providers/claude-agent-sdk/session-bridge.ts
+function toClaudeAgentSession(state) {
+  const messages = [];
+  for (const msg of state.messages) {
+    if (msg.role === "user" || msg.role === "assistant") {
+      const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
+      messages.push({
+        role: msg.role,
+        content
+      });
+    }
+  }
+  return {
+    sessionId: state.sessionId,
+    messages,
+    metadata: {
+      agentId: state.agentId,
+      tenantId: state.tenantId,
+      actorId: state.actorId
+    }
+  };
+}
+function createClaudeAgentSession(options) {
+  return {
+    sessionId: options?.sessionId,
+    messages: [],
+    metadata: {
+      tenantId: options?.tenantId,
+      actorId: options?.actorId,
+      ...options?.metadata
+    }
+  };
+}
+function createEmptyClaudeSession() {
+  return createClaudeAgentSession();
+}
+function buildClaudeAgentContext(options) {
+  return {
+    tenantId: options?.tenantId,
+    actorId: options?.actorId,
+    sessionId: options?.sessionId,
+    ...options?.metadata
+  };
+}
+function appendUserMessage(session, content) {
+  return {
+    ...session,
+    messages: [...session.messages, { role: "user", content }]
+  };
+}
+function appendAssistantMessage(session, content) {
+  return {
+    ...session,
+    messages: [...session.messages, { role: "assistant", content }]
+  };
+}
+function clearSession(session) {
+  return {
+    ...session,
+    messages: []
+  };
+}
+function getRecentMessages(session, count) {
+  return session.messages.slice(-count);
+}
+function extractToolUseBlocks(content) {
+  if (typeof content === "string") {
+    return [];
+  }
+  return content.filter((block) => block.type === "tool_use");
+}
+function createToolResultBlock(toolUseId, result, isError = false) {
+  return {
+    type: "tool_result",
+    tool_use_id: toolUseId,
+    content: typeof result === "string" ? result : JSON.stringify(result),
+    is_error: isError
+  };
+}
+function updateSessionMetadata(session, metadata) {
+  return {
+    ...session,
+    metadata: {
+      ...session.metadata,
+      ...metadata
+    }
+  };
+}
+function getMessageCount(session) {
+  return session.messages.length;
+}
+function estimateTokens(session) {
+  let chars = 0;
+  for (const msg of session.messages) {
+    if (typeof msg.content === "string") {
+      chars += msg.content.length;
+    } else {
+      chars += JSON.stringify(msg.content).length;
+    }
+  }
+  return Math.ceil(chars / 4);
+}
+function summarizeSession(session) {
+  let userMessages = 0;
+  let assistantMessages = 0;
+  for (const msg of session.messages) {
+    if (msg.role === "user") {
+      userMessages++;
+    } else {
+      assistantMessages++;
+    }
+  }
+  return {
+    messageCount: session.messages.length,
+    userMessages,
+    assistantMessages,
+    estimatedTokens: estimateTokens(session)
+  };
+}
+
+// src/providers/claude-agent-sdk/tool-bridge.ts
+function specToolToClaudeAgentTool(tool4, handler, context) {
+  return {
+    name: tool4.name,
+    description: tool4.description ?? createAgentI18n().t("tool.fallbackDescription", { name: tool4.name }),
+    input_schema: normalizeSchema(tool4.schema),
+    requires_confirmation: tool4.requiresApproval ?? !tool4.automationSafe,
+    execute: async (input) => {
+      const fullContext = {
+        agentId: context.agentId ?? "unknown",
+        sessionId: context.sessionId ?? "unknown",
+        tenantId: context.tenantId,
+        actorId: context.actorId,
+        metadata: context.metadata,
+        signal: context.signal
+      };
+      return handler(input, fullContext);
+    }
+  };
+}
+function specToolsToClaudeAgentTools(tools, handlers, context) {
+  return tools.filter((tool4) => handlers.has(tool4.name)).map((tool4) => {
+    const handler = handlers.get(tool4.name);
+    if (!handler) {
+      throw new Error(createAgentI18n().t("error.handlerNotFoundForTool", {
+        name: tool4.name
+      }));
+    }
+    return specToolToClaudeAgentTool(tool4, handler, context);
+  });
+}
+function claudeAgentToolToSpecTool(claudeTool, execute) {
+  const config = {
+    name: claudeTool.name,
+    description: claudeTool.description,
+    schema: claudeTool.input_schema,
+    requiresApproval: claudeTool.requires_confirmation,
+    automationSafe: !claudeTool.requires_confirmation
+  };
+  const handler = execute ? async (input, _ctx) => String(await execute(input)) : undefined;
+  return { config, handler };
+}
+function claudeAgentToolsToSpecTools(claudeTools) {
+  const configs = [];
+  const handlers = new Map;
+  for (const claudeTool of claudeTools) {
+    const { config, handler } = claudeAgentToolToSpecTool(claudeTool, claudeTool.execute);
+    configs.push(config);
+    if (handler) {
+      handlers.set(config.name, handler);
+    }
+  }
+  return { configs, handlers };
+}
+function specToolToExternalTool(tool4, handler, context) {
+  return {
+    name: tool4.name,
+    description: tool4.description ?? createAgentI18n().t("tool.fallbackDescription", { name: tool4.name }),
+    inputSchema: tool4.schema ?? { type: "object" },
+    requiresApproval: tool4.requiresApproval ?? !tool4.automationSafe,
+    execute: handler ? async (input) => {
+      const fullContext = {
+        agentId: context?.agentId ?? "unknown",
+        sessionId: context?.sessionId ?? "unknown",
+        tenantId: context?.tenantId,
+        actorId: context?.actorId,
+        metadata: context?.metadata,
+        signal: context?.signal
+      };
+      return handler(input, fullContext);
+    } : undefined
+  };
+}
+function normalizeSchema(schema) {
+  if (!schema) {
+    return { type: "object" };
   }
-  if (typeof spec.meta.version !== "string") {
-    throw new Error(i18n.t("error.agentMissingVersion", { key: spec.meta.key }));
+  if (schema.type === "object") {
+    return schema;
   }
-  if (!spec.instructions?.trim()) {
-    throw new Error(i18n.t("error.agentRequiresInstructions", { key: spec.meta.key }));
+  return {
+    type: "object",
+    properties: {
+      value: schema
+    },
+    required: ["value"]
+  };
+}
+function extractToolCalls(response) {
+  if (!response.content) {
+    return [];
   }
-  if (!spec.tools?.length) {
-    throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
+  return response.content.filter((block) => block.type === "tool_use").map((block) => ({
+    toolCallId: block.id ?? "",
+    toolName: block.name ?? "",
+    args: block.input
+  }));
+}
+var init_tool_bridge = __esm(() => {
+  init_i18n();
+});
+
+// src/providers/claude-agent-sdk/adapter.ts
+import { randomUUID as randomUUID3 } from "node:crypto";
+import {
+  agentKey as agentKey2
+} from "@contractspec/lib.contracts-spec/agent";
+
+class ClaudeAgentSDKProvider {
+  name = "claude-agent-sdk";
+  version = "1.0.0";
+  config;
+  sdkAvailable = null;
+  constructor(config = {}) {
+    this.config = {
+      model: "claude-sonnet-4-20250514",
+      extendedThinking: false,
+      computerUse: false,
+      maxTokens: 4096,
+      temperature: 0.7,
+      ...config
+    };
   }
-  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`);
+  isAvailable() {
+    if (this.sdkAvailable !== null) {
+      return this.sdkAvailable;
+    }
+    try {
+      __require.resolve("@anthropic-ai/claude-agent-sdk");
+      const apiKey = this.config.apiKey ?? process.env.ANTHROPIC_API_KEY;
+      this.sdkAvailable = Boolean(apiKey);
+    } catch {
+      this.sdkAvailable = false;
     }
+    return this.sdkAvailable;
   }
-  const toolNames = new Set;
-  for (const tool of spec.tools) {
-    if (toolNames.has(tool.name)) {
-      throw new Error(i18n.t("error.agentDuplicateTool", {
-        key: spec.meta.key,
-        name: tool.name
-      }));
+  async createContext(spec) {
+    if (!this.isAvailable()) {
+      throw new ProviderNotAvailableError(this.name, createAgentI18n(this.config.locale).t("error.provider.sdkNotConfigured"));
+    }
+    let mcpToolset = null;
+    try {
+      const toolSet = {};
+      for (const tool4 of spec.tools) {
+        toolSet[tool4.name] = specToolToExternalTool(tool4);
+      }
+      if ((this.config.mcpServers?.length ?? 0) > 0) {
+        mcpToolset = await createMcpToolsets(this.config.mcpServers ?? [], {
+          onNameCollision: "error"
+        });
+        for (const [toolName, mcpTool] of Object.entries(mcpToolset.tools)) {
+          if (toolSet[toolName]) {
+            throw new Error(`MCP tool "${toolName}" collides with a ContractSpec tool. Configure MCP toolPrefix values to avoid collisions.`);
+          }
+          toolSet[toolName] = this.mcpToolToExternalTool(toolName, mcpTool);
+        }
+      }
+      const instructions = await injectStaticKnowledge(spec.instructions, spec.knowledge ?? [], undefined);
+      const contextId = `claude-${agentKey2(spec.meta)}-${Date.now()}`;
+      const metadata = {
+        computerUseEnabled: this.config.computerUse ?? false,
+        extendedThinkingEnabled: this.config.extendedThinking ?? false,
+        mcpServerIds: this.config.mcpServers?.map((s) => s.name) ?? []
+      };
+      const cleanupMcp = mcpToolset?.cleanup;
+      return {
+        id: contextId,
+        spec: {
+          ...spec,
+          instructions
+        },
+        tools: toolSet,
+        metadata,
+        cleanup: async () => {
+          if (cleanupMcp) {
+            await cleanupMcp();
+          }
+        }
+      };
+    } catch (error) {
+      if (mcpToolset) {
+        await mcpToolset.cleanup().catch(() => {
+          return;
+        });
+      }
+      throw new ContextCreationError(this.name, createAgentI18n(this.config.locale).t("error.provider.contextCreation", {
+        error: error instanceof Error ? error.message : String(error)
+      }), error instanceof Error ? error : undefined);
+    }
+  }
+  async execute(context, params) {
+    try {
+      const sdk = await this.loadSDK();
+      const systemPrompt = params.systemOverride ? `${context.spec.instructions}
+
+${params.systemOverride}` : context.spec.instructions;
+      const claudeContext = buildClaudeAgentContext(params.options);
+      let session = createEmptyClaudeSession();
+      session = appendUserMessage(session, params.prompt);
+      const claudeTools = this.prepareToolsForSDK(context);
+      const rawResponse = await sdk.execute({
+        model: this.config.model,
+        system: systemPrompt,
+        messages: session.messages,
+        tools: claudeTools,
+        max_tokens: this.config.maxTokens,
+        temperature: this.config.temperature,
+        metadata: claudeContext,
+        extended_thinking: this.config.extendedThinking,
+        computer_use: this.config.computerUse
+      });
+      const response = rawResponse;
+      const toolCalls = extractToolCalls(response);
+      const toolResults = await this.executeTools(toolCalls, context, params);
+      if (response.content) {
+        const content = response.content;
+        session = appendAssistantMessage(session, content);
+      }
+      return {
+        text: this.extractTextContent(response),
+        toolCalls: toolCalls.map((tc) => ({
+          type: "tool-call",
+          toolCallId: tc.toolCallId,
+          toolName: tc.toolName,
+          args: tc.args
+        })),
+        toolResults: toolResults.map((tr) => ({
+          type: "tool-result",
+          toolCallId: tr.toolCallId,
+          toolName: tr.toolName,
+          output: tr.output
+        })),
+        usage: {
+          inputTokens: response.usage?.input_tokens ?? 0,
+          outputTokens: response.usage?.output_tokens ?? 0
+        },
+        finishReason: this.mapStopReason(response.stop_reason),
+        metadata: {
+          sessionId: context.metadata?.sessionId,
+          model: response.model
+        }
+      };
+    } catch (error) {
+      throw new ProviderExecutionError(this.name, createAgentI18n(this.config.locale).t("error.provider.executionFailed", {
+        error: error instanceof Error ? error.message : String(error)
+      }), error instanceof Error ? error : undefined);
+    }
+  }
+  async* stream(context, params) {
+    try {
+      const sdk = await this.loadSDK();
+      const systemPrompt = params.systemOverride ? `${context.spec.instructions}
+
+${params.systemOverride}` : context.spec.instructions;
+      const claudeContext = buildClaudeAgentContext(params.options);
+      const claudeTools = this.prepareToolsForSDK(context);
+      const stream = await sdk.stream({
+        model: this.config.model,
+        system: systemPrompt,
+        messages: [{ role: "user", content: params.prompt }],
+        tools: claudeTools,
+        max_tokens: this.config.maxTokens,
+        temperature: this.config.temperature,
+        metadata: claudeContext,
+        extended_thinking: this.config.extendedThinking,
+        computer_use: this.config.computerUse
+      });
+      let fullText = "";
+      const allToolCalls = [];
+      const allToolResults = [];
+      let stepIndex = 0;
+      for await (const event of stream) {
+        if (event.type === "content_block_delta" && event.delta?.type === "text_delta") {
+          const text = event.delta.text ?? "";
+          fullText += text;
+          yield { type: "text", text };
+        }
+        if (event.type === "content_block_start" && event.content_block?.type === "tool_use") {
+          const toolCall = {
+            toolCallId: event.content_block.id ?? "",
+            toolName: event.content_block.name ?? "",
+            args: event.content_block.input
+          };
+          allToolCalls.push(toolCall);
+          yield {
+            type: "tool-call",
+            toolCall: {
+              type: "tool-call",
+              ...toolCall
+            }
+          };
+        }
+        if (event.type === "message_stop") {
+          stepIndex++;
+          yield { type: "step-complete", stepIndex };
+        }
+      }
+      for (const toolCall of allToolCalls) {
+        const result = await this.executeTool(toolCall, context, params);
+        allToolResults.push(result);
+        yield {
+          type: "tool-result",
+          toolResult: {
+            type: "tool-result",
+            ...result
+          }
+        };
+      }
+      yield {
+        type: "done",
+        result: {
+          text: fullText,
+          toolCalls: allToolCalls.map((tc) => ({
+            type: "tool-call",
+            ...tc
+          })),
+          toolResults: allToolResults.map((tr) => ({
+            type: "tool-result",
+            ...tr
+          })),
+          usage: { inputTokens: 0, outputTokens: 0 },
+          finishReason: "stop"
+        }
+      };
+    } catch (error) {
+      throw new ProviderExecutionError(this.name, createAgentI18n(this.config.locale).t("error.provider.streamFailed", {
+        error: error instanceof Error ? error.message : String(error)
+      }), error instanceof Error ? error : undefined);
+    }
+  }
+  async loadSDK() {
+    try {
+      const module = __require("@anthropic-ai/claude-agent-sdk");
+      return module.default ?? module;
+    } catch {
+      throw new ProviderNotAvailableError(this.name, createAgentI18n(this.config.locale).t("error.provider.claudeSdkMissing"));
+    }
+  }
+  prepareToolsForSDK(context) {
+    const i18n = createAgentI18n(this.config.locale);
+    const toolsForSdk = [];
+    for (const [toolName, externalTool] of Object.entries(context.tools)) {
+      if (!externalTool.execute) {
+        continue;
+      }
+      toolsForSdk.push({
+        name: toolName,
+        description: externalTool.description ?? i18n.t("tool.fallbackDescription", { name: toolName }),
+        input_schema: this.normalizeToolSchemaForClaude(externalTool.inputSchema),
+        requires_confirmation: externalTool.requiresApproval,
+        execute: async (input) => {
+          const result = await externalTool.execute?.(input);
+          return typeof result === "string" ? result : JSON.stringify(result);
+        }
+      });
+    }
+    return toolsForSdk;
+  }
+  mcpToolToExternalTool(toolName, tool4) {
+    return {
+      name: toolName,
+      description: tool4.description ?? createAgentI18n(this.config.locale).t("tool.fallbackDescription", {
+        name: toolName
+      }),
+      inputSchema: this.normalizeExternalInputSchema(tool4.inputSchema),
+      execute: async (input) => {
+        if (!tool4.execute) {
+          throw new Error(createAgentI18n(this.config.locale).t("error.toolNoExecuteHandler", {
+            name: toolName
+          }));
+        }
+        return tool4.execute(input, {
+          toolCallId: `mcp-${randomUUID3()}`,
+          messages: []
+        });
+      }
+    };
+  }
+  normalizeExternalInputSchema(schema) {
+    if (this.isRecord(schema)) {
+      const type = schema["type"];
+      if (type === "object" || schema["properties"]) {
+        return schema;
+      }
+    }
+    return {
+      type: "object",
+      properties: {}
+    };
+  }
+  normalizeToolSchemaForClaude(schema) {
+    if (schema.type === "object") {
+      return {
+        type: "object",
+        properties: schema.properties,
+        required: schema.required,
+        additionalProperties: schema.additionalProperties
+      };
+    }
+    return {
+      type: "object",
+      properties: {
+        value: schema
+      },
+      required: ["value"]
+    };
+  }
+  isRecord(value) {
+    return typeof value === "object" && value !== null;
+  }
+  async executeTool(toolCall, context, _params) {
+    const tool4 = context.tools[toolCall.toolName];
+    if (!tool4?.execute) {
+      return {
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        output: createAgentI18n(this.config.locale).t("error.toolNotFoundOrNoHandler", {
+          name: toolCall.toolName
+        })
+      };
+    }
+    try {
+      const output = await tool4.execute(toolCall.args);
+      return {
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        output
+      };
+    } catch (error) {
+      return {
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        output: `Error: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
+  }
+  async executeTools(toolCalls, context, params) {
+    return Promise.all(toolCalls.map((tc) => this.executeTool(tc, context, params)));
+  }
+  extractTextContent(response) {
+    if (!response.content) {
+      return "";
+    }
+    return response.content.filter((block) => typeof block === "object" && block !== null && block.type === "text").map((block) => block.text).join("");
+  }
+  mapStopReason(stopReason) {
+    switch (stopReason) {
+      case "end_turn":
+      case "stop_sequence":
+        return "stop";
+      case "tool_use":
+        return "tool-calls";
+      case "max_tokens":
+        return "length";
+      default:
+        return "stop";
+    }
+  }
+}
+var init_adapter2 = __esm(() => {
+  init_i18n();
+  init_injector();
+  init_mcp_client();
+  init_types();
+  init_tool_bridge();
+});
+
+// src/providers/claude-agent-sdk/index.ts
+var exports_claude_agent_sdk = {};
+__export(exports_claude_agent_sdk, {
+  updateSessionMetadata: () => updateSessionMetadata,
+  toClaudeAgentSession: () => toClaudeAgentSession,
+  summarizeSession: () => summarizeSession,
+  specToolsToClaudeAgentTools: () => specToolsToClaudeAgentTools,
+  specToolToExternalTool: () => specToolToExternalTool,
+  specToolToClaudeAgentTool: () => specToolToClaudeAgentTool,
+  getRecentMessages: () => getRecentMessages,
+  getMessageCount: () => getMessageCount,
+  extractToolUseBlocks: () => extractToolUseBlocks,
+  extractToolCalls: () => extractToolCalls,
+  estimateTokens: () => estimateTokens,
+  createToolResultBlock: () => createToolResultBlock,
+  createEmptyClaudeSession: () => createEmptyClaudeSession,
+  createClaudeAgentSession: () => createClaudeAgentSession,
+  clearSession: () => clearSession,
+  claudeAgentToolsToSpecTools: () => claudeAgentToolsToSpecTools,
+  claudeAgentToolToSpecTool: () => claudeAgentToolToSpecTool,
+  buildClaudeAgentContext: () => buildClaudeAgentContext,
+  appendUserMessage: () => appendUserMessage,
+  appendAssistantMessage: () => appendAssistantMessage,
+  ClaudeAgentSDKProvider: () => ClaudeAgentSDKProvider
+});
+var init_claude_agent_sdk = __esm(() => {
+  init_adapter2();
+  init_tool_bridge();
+});
+
+// src/providers/opencode-sdk/tool-bridge.ts
+function specToolToOpenCodeTool(tool4) {
+  return {
+    name: tool4.name,
+    description: tool4.description ?? createAgentI18n().t("tool.fallbackDescription", { name: tool4.name }),
+    parameters: normalizeToOpenCodeParameters(tool4.schema),
+    permission: getPermissionLevel(tool4)
+  };
+}
+function specToolsToOpenCodeTools(tools) {
+  return tools.map(specToolToOpenCodeTool);
+}
+function getPermissionLevel(tool4) {
+  if (tool4.requiresApproval) {
+    return "ask";
+  }
+  if (tool4.automationSafe === false) {
+    return "ask";
+  }
+  return "allow";
+}
+function openCodeToolToSpecTool(openCodeTool) {
+  return {
+    name: openCodeTool.name,
+    description: openCodeTool.description,
+    schema: openCodeTool.parameters,
+    requiresApproval: openCodeTool.permission === "ask",
+    automationSafe: openCodeTool.permission === "allow"
+  };
+}
+function openCodeToolsToSpecTools(openCodeTools) {
+  return openCodeTools.map(openCodeToolToSpecTool);
+}
+function specToolToExternalToolForOpenCode(tool4, handler, context) {
+  return {
+    name: tool4.name,
+    description: tool4.description ?? createAgentI18n().t("tool.fallbackDescription", { name: tool4.name }),
+    inputSchema: tool4.schema ?? { type: "object" },
+    requiresApproval: tool4.requiresApproval ?? !tool4.automationSafe,
+    execute: handler ? async (input) => {
+      const fullContext = {
+        agentId: context?.agentId ?? "unknown",
+        sessionId: context?.sessionId ?? "unknown",
+        tenantId: context?.tenantId,
+        actorId: context?.actorId,
+        metadata: context?.metadata,
+        signal: context?.signal
+      };
+      return handler(input, fullContext);
+    } : undefined
+  };
+}
+function normalizeToOpenCodeParameters(schema) {
+  if (!schema) {
+    return { type: "object" };
+  }
+  if (schema.type === "object") {
+    return {
+      type: "object",
+      properties: schema.properties,
+      required: schema.required
+    };
+  }
+  return {
+    type: "object",
+    properties: {
+      value: convertToOpenCodeParameter(schema)
+    },
+    required: ["value"]
+  };
+}
+function convertToOpenCodeParameter(schema) {
+  const param = {
+    type: schema.type ?? "string"
+  };
+  if (schema.description) {
+    param.description = schema.description;
+  }
+  if (schema.enum) {
+    param.enum = schema.enum;
+  }
+  if (schema.default !== undefined) {
+    param.default = schema.default;
+  }
+  return param;
+}
+function createToolHandlerMap(tools) {
+  const handlers = new Map;
+  for (const [name, tool4] of Object.entries(tools)) {
+    if (tool4.execute) {
+      handlers.set(name, tool4.execute);
+    }
+  }
+  return handlers;
+}
+async function executeToolCall(toolCall, handlers) {
+  const handler = handlers.get(toolCall.name);
+  if (!handler) {
+    return {
+      tool_call_id: toolCall.id,
+      output: createAgentI18n().t("error.toolNotFoundOrNoHandler", {
+        name: toolCall.name
+      }),
+      is_error: true
+    };
+  }
+  try {
+    const result = await handler(toolCall.arguments);
+    return {
+      tool_call_id: toolCall.id,
+      output: typeof result === "string" ? result : JSON.stringify(result)
+    };
+  } catch (error) {
+    return {
+      tool_call_id: toolCall.id,
+      output: `Error: ${error instanceof Error ? error.message : String(error)}`,
+      is_error: true
+    };
+  }
+}
+var init_tool_bridge2 = __esm(() => {
+  init_i18n();
+});
+
+// src/providers/opencode-sdk/agent-bridge.ts
+function inferAgentType(spec) {
+  const hasCodeTools = spec.tools.some((tool4) => [
+    "write_file",
+    "edit_file",
+    "create_file",
+    "delete_file",
+    "bash",
+    "execute",
+    "run_command",
+    "terminal"
+  ].includes(tool4.name.toLowerCase()));
+  const instructionsLower = spec.instructions.toLowerCase();
+  const hasPlanningKeywords = /\b(plan|design|architect|strategy|analyze|review|assess|evaluate)\b/.test(instructionsLower);
+  const hasExplorationKeywords = /\b(search|find|explore|discover|locate|grep|pattern)\b/.test(instructionsLower);
+  const hasResearchKeywords = /\b(research|investigate|understand|learn|gather|collect)\b/.test(instructionsLower);
+  if (hasCodeTools) {
+    return "build";
+  }
+  if (hasPlanningKeywords && !hasCodeTools) {
+    return "plan";
+  }
+  if (hasExplorationKeywords && !hasResearchKeywords) {
+    return "explore";
+  }
+  return "general";
+}
+function specToOpenCodeConfig(spec, options) {
+  const agentType = options?.agentType ?? inferAgentType(spec);
+  return {
+    name: spec.meta.key,
+    version: spec.meta.version,
+    description: spec.description ?? spec.meta.description,
+    instructions: spec.instructions,
+    agent_type: agentType,
+    tools: specToolsToOpenCodeTools(spec.tools),
+    config: {
+      max_steps: options?.maxSteps ?? spec.maxSteps ?? 10,
+      temperature: options?.temperature ?? 0.7,
+      model: options?.model,
+      permissions: buildPermissions(spec)
+    }
+  };
+}
+function buildPermissions(spec) {
+  const permissions = {};
+  for (const tool4 of spec.tools) {
+    if (tool4.requiresApproval) {
+      permissions[tool4.name] = "ask";
+    } else if (tool4.automationSafe === false) {
+      permissions[tool4.name] = "ask";
+    } else {
+      permissions[tool4.name] = "allow";
+    }
+  }
+  return permissions;
+}
+function specToOpenCodeMarkdown(spec, options) {
+  const agentType = options?.agentType ?? inferAgentType(spec);
+  return {
+    frontmatter: {
+      name: spec.meta.key,
+      type: agentType,
+      version: spec.meta.version,
+      model: options?.model,
+      temperature: options?.temperature ?? 0.7,
+      max_steps: options?.maxSteps ?? spec.maxSteps ?? 10,
+      tools: spec.tools.map((t) => t.name)
+    },
+    body: buildMarkdownBody(spec)
+  };
+}
+function buildMarkdownBody(spec) {
+  const i18n = createAgentI18n(spec.locale);
+  const lines = [];
+  lines.push(`# ${spec.meta.key}`);
+  lines.push("");
+  if (spec.description ?? spec.meta.description) {
+    lines.push(spec.description ?? spec.meta.description ?? "");
+    lines.push("");
+  }
+  lines.push(i18n.t("export.instructions"));
+  lines.push("");
+  lines.push(spec.instructions);
+  lines.push("");
+  if (spec.tools.length > 0) {
+    lines.push(i18n.t("export.tools"));
+    lines.push("");
+    for (const tool4 of spec.tools) {
+      const permission = tool4.requiresApproval ? i18n.t("export.bridge.requiresApproval") : tool4.automationSafe === false ? i18n.t("export.bridge.askMode") : "";
+      lines.push(`- **${tool4.name}**: ${tool4.description ?? i18n.t("export.noDescription")} ${permission}`.trim());
     }
-    toolNames.add(tool.name);
-    if (tool.subagentRef && tool.operationRef) {
-      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" cannot have both subagentRef and operationRef. Use one.`);
+    lines.push("");
+  }
+  if (spec.knowledge && spec.knowledge.length > 0) {
+    lines.push(i18n.t("export.knowledgeSources"));
+    lines.push("");
+    for (const k of spec.knowledge) {
+      const required = k.required ? i18n.t("export.required") : i18n.t("export.optional");
+      lines.push(`- ${k.key} ${required}`);
     }
-    const outputRefCount = [
-      tool.outputPresentation,
-      tool.outputForm,
-      tool.outputDataView
-    ].filter(Boolean).length;
-    if (outputRefCount > 1) {
-      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" has multiple output refs (outputPresentation, outputForm, outputDataView). Use at most one.`);
+    lines.push("");
+  }
+  return lines.join(`
+`);
+}
+function serializeOpenCodeMarkdown(markdown) {
+  const lines = [];
+  lines.push("---");
+  lines.push(`name: ${markdown.frontmatter.name}`);
+  lines.push(`type: ${markdown.frontmatter.type}`);
+  if (markdown.frontmatter.version) {
+    lines.push(`version: ${markdown.frontmatter.version}`);
+  }
+  if (markdown.frontmatter.model) {
+    lines.push(`model: ${markdown.frontmatter.model}`);
+  }
+  if (markdown.frontmatter.temperature !== undefined) {
+    lines.push(`temperature: ${markdown.frontmatter.temperature}`);
+  }
+  if (markdown.frontmatter.max_steps !== undefined) {
+    lines.push(`max_steps: ${markdown.frontmatter.max_steps}`);
+  }
+  if (markdown.frontmatter.tools && markdown.frontmatter.tools.length > 0) {
+    lines.push(`tools:`);
+    for (const tool4 of markdown.frontmatter.tools) {
+      lines.push(`  - ${tool4}`);
     }
   }
-  return Object.freeze(spec);
+  lines.push("---");
+  lines.push("");
+  lines.push(markdown.body);
+  return lines.join(`
+`);
+}
+function openCodeConfigToSpec(config) {
+  return {
+    meta: {
+      key: config.name,
+      version: config.version ?? "1.0.0",
+      description: config.description ?? "",
+      stability: "experimental",
+      owners: [],
+      tags: []
+    },
+    description: config.description,
+    instructions: config.instructions ?? "",
+    tools: config.tools?.map((tool4) => ({
+      name: tool4.name,
+      description: tool4.description,
+      schema: tool4.parameters,
+      requiresApproval: tool4.permission === "ask",
+      automationSafe: tool4.permission === "allow"
+    })) ?? [],
+    maxSteps: config.config?.max_steps ?? 10
+  };
 }
-function agentKey(meta) {
-  return `${meta.key}.v${meta.version}`;
+var init_agent_bridge = __esm(() => {
+  init_i18n();
+  init_tool_bridge2();
+});
+
+// src/providers/opencode-sdk/adapter.ts
+import {
+  agentKey as agentKey3
+} from "@contractspec/lib.contracts-spec/agent";
+
+class OpenCodeSDKProvider {
+  name = "opencode-sdk";
+  version = "1.0.0";
+  config;
+  sdkAvailable = null;
+  constructor(config = {}) {
+    this.config = {
+      serverUrl: "http://127.0.0.1:4096",
+      port: 4096,
+      agentType: "general",
+      temperature: 0.7,
+      timeout: 30000,
+      ...config
+    };
+    if (!config.serverUrl && config.port) {
+      this.config.serverUrl = `http://127.0.0.1:${config.port}`;
+    }
+  }
+  isAvailable() {
+    if (this.sdkAvailable !== null) {
+      return this.sdkAvailable;
+    }
+    try {
+      __require.resolve("@opencode-ai/sdk");
+      this.sdkAvailable = true;
+    } catch {
+      this.sdkAvailable = false;
+    }
+    return this.sdkAvailable;
+  }
+  async createContext(spec) {
+    if (!this.isAvailable()) {
+      throw new ProviderNotAvailableError(this.name, createAgentI18n(this.config.locale).t("error.provider.sdkNotInstalled"));
+    }
+    try {
+      const sdk = await this.loadSDK();
+      const { client } = await sdk.createOpencode({
+        hostname: this.getHostname(),
+        port: this.config.port ?? 4096,
+        timeout: this.config.timeout
+      });
+      const session = await client.session.create({
+        agent: this.config.agentType ?? inferAgentType(spec),
+        model: this.config.model
+      });
+      const toolSet = {};
+      for (const tool4 of spec.tools) {
+        toolSet[tool4.name] = specToolToExternalToolForOpenCode(tool4);
+      }
+      const instructions = await injectStaticKnowledge(spec.instructions, spec.knowledge ?? [], undefined);
+      const contextId = `opencode-${agentKey3(spec.meta)}-${Date.now()}`;
+      const metadata = {
+        sessionId: session.id,
+        agentType: this.config.agentType ?? inferAgentType(spec),
+        serverUrl: this.config.serverUrl ?? `http://127.0.0.1:${this.config.port ?? 4096}`
+      };
+      return {
+        id: contextId,
+        spec: {
+          ...spec,
+          instructions
+        },
+        tools: toolSet,
+        metadata,
+        cleanup: async () => {
+          try {
+            await client.session.delete({ id: session.id });
+          } catch {}
+        }
+      };
+    } catch (error) {
+      throw new ContextCreationError(this.name, createAgentI18n(this.config.locale).t("error.provider.contextCreation", {
+        error: error instanceof Error ? error.message : String(error)
+      }), error instanceof Error ? error : undefined);
+    }
+  }
+  async execute(context, params) {
+    try {
+      const sdk = await this.loadSDK();
+      const metadata = context.metadata;
+      const { client } = await sdk.createOpencodeClient({
+        baseUrl: metadata.serverUrl
+      });
+      const systemPrompt = params.systemOverride ? `${context.spec.instructions}
+
+${params.systemOverride}` : context.spec.instructions;
+      const response = await client.session.prompt({
+        id: metadata.sessionId,
+        body: {
+          content: params.prompt,
+          system: systemPrompt
+        }
+      });
+      const toolCalls = this.extractToolCalls(response);
+      const toolHandlers = createToolHandlerMap(context.tools);
+      const toolResults = await Promise.all(toolCalls.map((tc) => executeToolCall(tc, toolHandlers)));
+      return {
+        text: this.extractTextContent(response),
+        toolCalls: toolCalls.map((tc) => ({
+          type: "tool-call",
+          toolCallId: tc.id,
+          toolName: tc.name,
+          args: tc.arguments
+        })),
+        toolResults: toolResults.map((tr) => ({
+          type: "tool-result",
+          toolCallId: tr.tool_call_id,
+          toolName: toolCalls.find((tc) => tc.id === tr.tool_call_id)?.name ?? "",
+          output: tr.output
+        })),
+        usage: {
+          inputTokens: response.usage?.input_tokens ?? 0,
+          outputTokens: response.usage?.output_tokens ?? 0
+        },
+        finishReason: this.mapFinishReason(response.finish_reason),
+        metadata: {
+          sessionId: metadata.sessionId,
+          agentType: metadata.agentType
+        }
+      };
+    } catch (error) {
+      throw new ProviderExecutionError(this.name, createAgentI18n(this.config.locale).t("error.provider.executionFailed", {
+        error: error instanceof Error ? error.message : String(error)
+      }), error instanceof Error ? error : undefined);
+    }
+  }
+  async* stream(context, params) {
+    try {
+      const sdk = await this.loadSDK();
+      const metadata = context.metadata;
+      const { client } = await sdk.createOpencodeClient({
+        baseUrl: metadata.serverUrl
+      });
+      const systemPrompt = params.systemOverride ? `${context.spec.instructions}
+
+${params.systemOverride}` : context.spec.instructions;
+      const events = client.session.subscribe({
+        id: metadata.sessionId
+      });
+      await client.session.prompt({
+        id: metadata.sessionId,
+        body: {
+          content: params.prompt,
+          system: systemPrompt
+        }
+      });
+      let fullText = "";
+      const allToolCalls = [];
+      const toolHandlers = createToolHandlerMap(context.tools);
+      let stepIndex = 0;
+      for await (const event of events) {
+        if (event.type === "message.delta") {
+          const text = event.delta?.content ?? "";
+          fullText += text;
+          yield { type: "text", text };
+        }
+        if (event.type === "tool.call") {
+          const toolCall = {
+            id: event.tool_call_id ?? `tc-${Date.now()}`,
+            name: event.tool_name ?? "",
+            arguments: event.arguments ?? {}
+          };
+          allToolCalls.push(toolCall);
+          yield {
+            type: "tool-call",
+            toolCall: {
+              type: "tool-call",
+              toolCallId: toolCall.id,
+              toolName: toolCall.name,
+              args: toolCall.arguments
+            }
+          };
+        }
+        if (event.type === "step.complete") {
+          stepIndex++;
+          yield { type: "step-complete", stepIndex };
+        }
+        if (event.type === "message.complete") {
+          break;
+        }
+      }
+      for (const toolCall of allToolCalls) {
+        const result = await executeToolCall(toolCall, toolHandlers);
+        yield {
+          type: "tool-result",
+          toolResult: {
+            type: "tool-result",
+            toolCallId: result.tool_call_id,
+            toolName: toolCall.name,
+            output: result.output
+          }
+        };
+      }
+      yield {
+        type: "done",
+        result: {
+          text: fullText,
+          toolCalls: allToolCalls.map((tc) => ({
+            type: "tool-call",
+            toolCallId: tc.id,
+            toolName: tc.name,
+            args: tc.arguments
+          })),
+          toolResults: [],
+          usage: { inputTokens: 0, outputTokens: 0 },
+          finishReason: "stop"
+        }
+      };
+    } catch (error) {
+      throw new ProviderExecutionError(this.name, createAgentI18n(this.config.locale).t("error.provider.streamFailed", {
+        error: error instanceof Error ? error.message : String(error)
+      }), error instanceof Error ? error : undefined);
+    }
+  }
+  async loadSDK() {
+    try {
+      const module = __require("@opencode-ai/sdk");
+      return module;
+    } catch {
+      throw new ProviderNotAvailableError(this.name, createAgentI18n(this.config.locale).t("error.provider.opencodeSdkMissing"));
+    }
+  }
+  getHostname() {
+    if (!this.config.serverUrl) {
+      return "127.0.0.1";
+    }
+    try {
+      const url = new URL(this.config.serverUrl);
+      return url.hostname;
+    } catch {
+      return "127.0.0.1";
+    }
+  }
+  extractToolCalls(response) {
+    if (!response.tool_calls) {
+      return [];
+    }
+    return response.tool_calls.map((tc) => ({
+      id: tc.id,
+      name: tc.name,
+      arguments: tc.arguments ?? {}
+    }));
+  }
+  extractTextContent(response) {
+    return response.content ?? response.message?.content ?? "";
+  }
+  mapFinishReason(finishReason) {
+    switch (finishReason) {
+      case "stop":
+      case "end":
+        return "stop";
+      case "tool_use":
+      case "tool_calls":
+        return "tool-calls";
+      case "length":
+      case "max_tokens":
+        return "length";
+      default:
+        return "stop";
+    }
+  }
 }
-var init_spec = __esm(() => {
+var init_adapter3 = __esm(() => {
   init_i18n();
+  init_injector();
+  init_types();
+  init_agent_bridge();
+  init_tool_bridge2();
+});
+
+// src/providers/opencode-sdk/index.ts
+var exports_opencode_sdk = {};
+__export(exports_opencode_sdk, {
+  specToolsToOpenCodeTools: () => specToolsToOpenCodeTools,
+  specToolToOpenCodeTool: () => specToolToOpenCodeTool,
+  specToolToExternalToolForOpenCode: () => specToolToExternalToolForOpenCode,
+  specToOpenCodeMarkdown: () => specToOpenCodeMarkdown,
+  specToOpenCodeConfig: () => specToOpenCodeConfig,
+  serializeOpenCodeMarkdown: () => serializeOpenCodeMarkdown,
+  openCodeToolsToSpecTools: () => openCodeToolsToSpecTools,
+  openCodeToolToSpecTool: () => openCodeToolToSpecTool,
+  openCodeConfigToSpec: () => openCodeConfigToSpec,
+  inferAgentType: () => inferAgentType,
+  executeToolCall: () => executeToolCall,
+  createToolHandlerMap: () => createToolHandlerMap,
+  OpenCodeSDKProvider: () => OpenCodeSDKProvider
+});
+var init_opencode_sdk = __esm(() => {
+  init_adapter3();
+  init_agent_bridge();
+  init_tool_bridge2();
 });
 
-// src/spec/registry.ts
+// src/agent/json-runner.ts
 init_i18n();
-import { SpecContractRegistry } from "@contractspec/lib.contracts-spec/registry";
-import { compareVersions } from "compare-versions";
+init_contract_spec_agent();
+import { createProvider } from "@contractspec/lib.ai-providers/factory";
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+function getJsonOnlyRules(locale) {
+  const i18n = createAgentI18n(locale);
+  return [
+    i18n.t("agent.json.rules.validJsonOnly"),
+    i18n.t("agent.json.rules.noMarkdownFences"),
+    i18n.t("agent.json.rules.noCommentary"),
+    i18n.t("agent.json.rules.doubleQuotes"),
+    i18n.t("agent.json.rules.noTrailingCommas")
+  ].join(`
+`);
+}
+function getDefaultSpec(locale) {
+  const i18n = createAgentI18n(locale);
+  return {
+    meta: {
+      key: "agent.json-runner",
+      version: "1.0.0",
+      description: i18n.t("agent.json.defaultDescription"),
+      stability: StabilityEnum.Experimental,
+      owners: ["platform.core"],
+      tags: ["json", "agent"]
+    },
+    instructions: i18n.t("agent.json.systemPrompt"),
+    tools: []
+  };
+}
+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) {
+    return createProvider(options.provider).getModel();
+  }
+  throw new Error(createAgentI18n(options.locale).t("error.jsonRunner.requiresModel"));
+}
+function applyModelSettings(model, settings) {
+  const { temperature } = settings;
+  if (temperature === undefined)
+    return model;
+  const withSettings = model;
+  if (typeof withSettings.withSettings === "function") {
+    return withSettings.withSettings({ temperature });
+  }
+  return model;
+}
+function buildInstructions(base, locale, system) {
+  return [base, getJsonOnlyRules(locale), system].filter(Boolean).join(`
 
-class AgentRegistry extends SpecContractRegistry {
-  constructor(items) {
-    super("agent", items);
-  }
-  listNames() {
-    const names = new Set;
-    for (const spec of this.items.values()) {
-      names.add(spec.meta.key);
-    }
-    return [...names];
-  }
-  require(name, version, locale) {
-    const spec = this.get(name, version);
-    if (!spec) {
-      throw new Error(createAgentI18n(locale).t("error.agentSpecNotFound", {
-        name: `${name}${version != null ? `.v${version}` : ""}`
+`);
+}
+function ensureToolHandlers(spec, handlers, locale) {
+  for (const tool4 of spec.tools) {
+    if (!handlers.has(tool4.name)) {
+      throw new Error(createAgentI18n(locale).t("error.missingToolHandler", {
+        name: tool4.name
       }));
     }
-    return spec;
   }
-  has(name, version) {
-    return this.get(name, version) !== undefined;
+}
+async function createAgentJsonRunner(options) {
+  const resolved = await resolveModel(options);
+  const model = applyModelSettings(resolved, {
+    temperature: options.temperature ?? 0
+  });
+  const baseSpec = options.spec ?? getDefaultSpec(options.locale);
+  const spec = {
+    ...baseSpec,
+    locale: options.spec?.locale ?? options.locale,
+    instructions: buildInstructions(baseSpec.instructions, options.locale, options.system),
+    maxSteps: options.maxSteps ?? baseSpec.maxSteps
+  };
+  const toolHandlers = options.toolHandlers ?? new Map;
+  ensureToolHandlers(spec, toolHandlers, options.locale);
+  const agent = await ContractSpecAgent.create({
+    spec,
+    model,
+    toolHandlers
+  });
+  return {
+    async generateJson(prompt) {
+      const result = await agent.generate({ prompt });
+      return result.text;
+    }
+  };
+}
+
+// src/agent/unified-agent.ts
+init_i18n();
+
+class UnifiedAgent {
+  spec;
+  config;
+  tools;
+  provider;
+  context;
+  state;
+  constructor(spec, config) {
+    this.spec = spec;
+    this.config = config;
+    this.tools = config.tools ?? new Map;
+    this.state = {
+      backend: config.backend,
+      isReady: false,
+      messageCount: 0
+    };
+  }
+  i18n(runtimeLocale) {
+    return createAgentI18n(this.spec.locale, runtimeLocale ?? this.config.locale);
+  }
+  async initialize() {
+    const backend = this.config.backend;
+    try {
+      switch (backend) {
+        case "ai-sdk":
+          this.state.isReady = true;
+          break;
+        case "claude-agent-sdk":
+          await this.initializeClaudeAgentSDK();
+          break;
+        case "opencode-sdk":
+          await this.initializeOpenCodeSDK();
+          break;
+        default:
+          throw new Error(this.i18n().t("error.unknownBackend", {
+            backend: String(backend)
+          }));
+      }
+    } catch (error) {
+      this.state.lastError = error instanceof Error ? error : new Error(String(error));
+      if (this.config.fallbackBackend && this.config.fallbackBackend !== backend) {
+        await this.cleanupProviderContext();
+        console.warn(this.i18n().t("log.unifiedAgent.fallback", {
+          backend: String(backend),
+          fallback: String(this.config.fallbackBackend)
+        }));
+        this.state.backend = this.config.fallbackBackend;
+        await this.initialize();
+      } else {
+        throw error;
+      }
+    }
+  }
+  async initializeClaudeAgentSDK() {
+    try {
+      const { ClaudeAgentSDKProvider: ClaudeAgentSDKProvider2 } = await Promise.resolve().then(() => (init_claude_agent_sdk(), exports_claude_agent_sdk));
+      const config = this.config.config;
+      this.provider = new ClaudeAgentSDKProvider2(config ?? {});
+      if (!this.provider.isAvailable()) {
+        throw new Error(this.i18n().t("error.claudeSdk.notAvailable"));
+      }
+      this.context = await this.provider.createContext(this.spec);
+      this.state.isReady = true;
+    } catch (error) {
+      if (error.code === "MODULE_NOT_FOUND") {
+        throw new Error(this.i18n().t("error.claudeSdk.notInstalled"));
+      }
+      throw error;
+    }
+  }
+  async initializeOpenCodeSDK() {
+    try {
+      const { OpenCodeSDKProvider: OpenCodeSDKProvider2 } = await Promise.resolve().then(() => (init_opencode_sdk(), exports_opencode_sdk));
+      const config = this.config.config;
+      this.provider = new OpenCodeSDKProvider2(config ?? {});
+      if (!this.provider.isAvailable()) {
+        throw new Error(this.i18n().t("error.opencodeSdk.notAvailable"));
+      }
+      this.context = await this.provider.createContext(this.spec);
+      this.state.isReady = true;
+    } catch (error) {
+      if (error.code === "MODULE_NOT_FOUND") {
+        throw new Error(this.i18n().t("error.opencodeSdk.notInstalled"));
+      }
+      throw error;
+    }
   }
-  getVersions(name) {
-    const versions = [];
-    for (const spec of this.items.values()) {
-      if (spec.meta.key === name) {
-        versions.push(spec);
+  async run(message, options) {
+    if (!this.state.isReady) {
+      await this.initialize();
+    }
+    const backend = options?.backend ?? this.state.backend;
+    this.state.messageCount++;
+    try {
+      switch (backend) {
+        case "ai-sdk":
+          return await this.runWithAISDK(message, options);
+        case "claude-agent-sdk":
+        case "opencode-sdk":
+          return await this.runWithExternalProvider(message, options);
+        default:
+          throw new Error(this.i18n().t("error.unknownBackend", {
+            backend: String(backend)
+          }));
       }
+    } catch (error) {
+      this.state.lastError = error instanceof Error ? error : new Error(String(error));
+      throw error;
+    }
+  }
+  async runWithAISDK(message, options) {
+    const { ContractSpecAgent: ContractSpecAgent2 } = await Promise.resolve().then(() => (init_contract_spec_agent(), exports_contract_spec_agent));
+    const backendConfig = this.getAISDKConfig();
+    const model = await this.resolveAISDKModel();
+    const agent = await ContractSpecAgent2.create({
+      spec: this.spec,
+      model,
+      toolHandlers: this.tools,
+      mcpServers: backendConfig?.mcpServers
+    });
+    try {
+      return await agent.generate({
+        prompt: message,
+        options
+      });
+    } finally {
+      await agent.cleanup().catch(() => {
+        return;
+      });
+    }
+  }
+  async runWithExternalProvider(message, options) {
+    if (!this.provider || !this.context) {
+      throw new Error(this.i18n().t("error.providerNotInitialized"));
+    }
+    const result = await this.provider.execute(this.context, {
+      prompt: message,
+      options
+    });
+    return this.convertExternalResult(result);
+  }
+  convertExternalResult(result) {
+    return {
+      text: result.text,
+      steps: [],
+      toolCalls: result.toolCalls.map((tc) => ({
+        type: "tool-call",
+        toolCallId: tc.toolCallId,
+        toolName: tc.toolName,
+        args: tc.args
+      })),
+      toolResults: result.toolResults.map((tr) => ({
+        type: "tool-result",
+        toolCallId: tr.toolCallId,
+        toolName: tr.toolName,
+        output: tr.output
+      })),
+      finishReason: result.finishReason,
+      usage: result.usage ? {
+        promptTokens: result.usage.inputTokens,
+        completionTokens: result.usage.outputTokens,
+        totalTokens: result.usage.totalTokens ?? result.usage.inputTokens + result.usage.outputTokens
+      } : undefined
+    };
+  }
+  getAISDKConfig() {
+    if (this.config.backend !== "ai-sdk")
+      return;
+    return this.config.config;
+  }
+  async resolveAISDKModel() {
+    const backendConfig = this.getAISDKConfig();
+    let model;
+    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");
+      model = createProvider2(backendConfig.provider).getModel();
+    } else {
+      const { anthropic: anthropic2 } = await import("@ai-sdk/anthropic");
+      model = anthropic2(backendConfig?.model ?? "claude-3-5-sonnet-20240620");
+    }
+    return this.applyModelSettings(model, {
+      temperature: backendConfig?.temperature,
+      maxTokens: backendConfig?.maxTokens
+    });
+  }
+  applyModelSettings(model, settings) {
+    if (settings.temperature === undefined && settings.maxTokens === undefined) {
+      return model;
+    }
+    const withSettings = model;
+    if (typeof withSettings.withSettings === "function") {
+      return withSettings.withSettings({
+        temperature: settings.temperature,
+        maxTokens: settings.maxTokens
+      });
+    }
+    return model;
+  }
+  getState() {
+    return { ...this.state };
+  }
+  getSpec() {
+    return this.spec;
+  }
+  getBackend() {
+    return this.state.backend;
+  }
+  async isBackendAvailable(backend) {
+    switch (backend) {
+      case "ai-sdk":
+        return true;
+      case "claude-agent-sdk":
+        try {
+          const { ClaudeAgentSDKProvider: ClaudeAgentSDKProvider2 } = await Promise.resolve().then(() => (init_claude_agent_sdk(), exports_claude_agent_sdk));
+          const provider = new ClaudeAgentSDKProvider2({});
+          return provider.isAvailable();
+        } catch {
+          return false;
+        }
+      case "opencode-sdk":
+        try {
+          const { OpenCodeSDKProvider: OpenCodeSDKProvider2 } = await Promise.resolve().then(() => (init_opencode_sdk(), exports_opencode_sdk));
+          const provider = new OpenCodeSDKProvider2({});
+          return provider.isAvailable();
+        } catch {
+          return false;
+        }
+      default:
+        return false;
+    }
+  }
+  async switchBackend(backend) {
+    if (backend === this.state.backend) {
+      return;
+    }
+    await this.cleanupProviderContext();
+    this.state.backend = backend;
+    this.state.isReady = false;
+    this.provider = undefined;
+    this.context = undefined;
+    await this.initialize();
+  }
+  reset() {
+    this.state.messageCount = 0;
+    this.state.sessionId = undefined;
+    this.state.lastError = undefined;
+    this.cleanupProviderContext().catch(() => {
+      return;
+    });
+    this.context = undefined;
+  }
+  async cleanupProviderContext() {
+    const context = this.context;
+    this.context = undefined;
+    if (context) {
+      await context.cleanup().catch(() => {
+        return;
+      });
     }
-    return versions.sort((a, b) => compareVersions(a.meta.version, b.meta.version));
   }
+  addTool(name, handler) {
+    this.tools.set(name, handler);
+  }
+  removeTool(name) {
+    return this.tools.delete(name);
+  }
+}
+function createUnifiedAgent(spec, config) {
+  return new UnifiedAgent(spec, config);
+}
+function createAISDKAgent(spec, options) {
+  return new UnifiedAgent(spec, {
+    backend: "ai-sdk",
+    tools: options?.tools,
+    config: {
+      model: options?.model,
+      modelInstance: options?.modelInstance,
+      provider: options?.provider,
+      temperature: options?.temperature,
+      maxTokens: options?.maxTokens,
+      mcpServers: options?.mcpServers
+    }
+  });
+}
+function createClaudeAgentSDKAgent(spec, config) {
+  const { tools, ...sdkConfig } = config ?? {};
+  return new UnifiedAgent(spec, {
+    backend: "claude-agent-sdk",
+    tools,
+    config: sdkConfig
+  });
+}
+function createOpenCodeSDKAgent(spec, config) {
+  const { tools, ...sdkConfig } = config ?? {};
+  return new UnifiedAgent(spec, {
+    backend: "opencode-sdk",
+    tools,
+    config: sdkConfig
+  });
 }
-function createAgentRegistry() {
-  return new AgentRegistry;
+async function getAvailableBackends() {
+  const backends = ["ai-sdk"];
+  try {
+    const { ClaudeAgentSDKProvider: ClaudeAgentSDKProvider2 } = await Promise.resolve().then(() => (init_claude_agent_sdk(), exports_claude_agent_sdk));
+    const provider = new ClaudeAgentSDKProvider2({});
+    if (provider.isAvailable()) {
+      backends.push("claude-agent-sdk");
+    }
+  } catch {}
+  try {
+    const { OpenCodeSDKProvider: OpenCodeSDKProvider2 } = await Promise.resolve().then(() => (init_opencode_sdk(), exports_opencode_sdk));
+    const provider = new OpenCodeSDKProvider2({});
+    if (provider.isAvailable()) {
+      backends.push("opencode-sdk");
+    }
+  } catch {}
+  return backends;
 }
 
-// src/spec/index.ts
-init_spec();
+// src/agent/index.ts
+init_contract_spec_agent();
+
+// src/approval/index.ts
+init_workflow();
 export {
-  defineAgent,
-  createAgentRegistry,
-  agentKey,
-  AgentRegistry
+  getAvailableBackends,
+  createUnifiedAgent,
+  createOpenCodeSDKAgent,
+  createClaudeAgentSDKAgent,
+  createApprovalWorkflow,
+  createAgentJsonRunner,
+  createAISDKAgent,
+  UnifiedAgent,
+  InMemoryApprovalStore,
+  ContractSpecAgent,
+  ApprovalWorkflow
 };