@contractspec/lib.ai-agent 7.0.10 → 8.0.0

package/dist/node/agent/agent-factory.js

@@ -2131,6 +2131,148 @@ var init_i18n = __esm(() => {
   init_messages();
 });
 
+// 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)
@@ -2317,56 +2459,6 @@ function generateSessionId() {
   return `sess_${createSecureSessionToken()}`;
 }
 
-// src/spec/spec.ts
-function defineAgent(spec) {
-  const i18n = createAgentI18n(spec.locale);
-  if (!spec.meta?.key) {
-    throw new Error(i18n.t("error.agentKeyRequired"));
-  }
-  if (typeof spec.meta.version !== "string") {
-    throw new Error(i18n.t("error.agentMissingVersion", { key: spec.meta.key }));
-  }
-  if (!spec.instructions?.trim()) {
-    throw new Error(i18n.t("error.agentRequiresInstructions", { key: spec.meta.key }));
-  }
-  if (!spec.tools?.length) {
-    throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
-  }
-  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
-    if (portRef !== undefined && portRef.trim().length === 0) {
-      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
-    }
-  }
-  const toolNames = new Set;
-  for (const tool of spec.tools) {
-    if (toolNames.has(tool.name)) {
-      throw new Error(i18n.t("error.agentDuplicateTool", {
-        key: spec.meta.key,
-        name: tool.name
-      }));
-    }
-    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.`);
-    }
-    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.`);
-    }
-  }
-  return Object.freeze(spec);
-}
-function agentKey(meta) {
-  return `${meta.key}.v${meta.version}`;
-}
-var init_spec = __esm(() => {
-  init_i18n();
-});
-
 // src/telemetry/adapter.ts
 function parseAgentId(agentId) {
   const match = agentId.match(/^(.+)\.v(\d+)$/);
@@ -2434,6 +2526,7 @@ async function trackAgentStep(collector, agentId, step, durationMs, context) {
         agentId,
         actorId: context?.actorId,
         tenantId: context?.tenantId,
+        workflowId: context?.workflowId,
         stepIndex: context?.stepIndex,
         toolName: toolCall.toolName,
         toolCallArgs: toolCall.input,
@@ -2459,6 +2552,7 @@ async function trackAgentStep(collector, agentId, step, durationMs, context) {
       agentId,
       actorId: context?.actorId,
       tenantId: context?.tenantId,
+      workflowId: context?.workflowId,
       stepIndex: context?.stepIndex,
       stepStartedAt: context?.stepStartedAt,
       finishReason: step.finishReason,
@@ -3377,7 +3471,10 @@ var exports_contract_spec_agent = {};
 __export(exports_contract_spec_agent, {
   ContractSpecAgent: () => ContractSpecAgent
 });
-import { randomUUID } from "node:crypto";
+import { randomUUID as randomUUID2 } from "node:crypto";
+import {
+  agentKey
+} from "@contractspec/lib.contracts-spec/agent";
 import {
   stepCountIs,
   Experimental_Agent as ToolLoopAgent
@@ -3402,7 +3499,10 @@ class ContractSpecAgent {
     this.mcpCleanup = mcpCleanup;
   }
   static async create(config) {
-    const effectiveConfig = 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 ?? [], {
@@ -3455,34 +3555,27 @@ class ContractSpecAgent {
   }
   async generate(params) {
     const sessionId = params.options?.sessionId ?? generateSessionId();
-    const traceId = params.options?.metadata?.["traceId"] ?? this.config.posthogConfig?.tracingOptions?.posthogTraceId ?? randomUUID();
+    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 (this.config.sessionStore && !params.messages?.length) {
-      const existing = await this.config.sessionStore.get(sessionId);
-      if (!existing) {
-        await this.config.sessionStore.create({
-          sessionId,
-          agentId: this.id,
-          tenantId: params.options?.tenantId,
-          actorId: params.options?.actorId,
-          status: "running",
-          messages: [],
-          steps: [],
-          metadata: params.options?.metadata
-        });
-      } else if (existing.status !== "running") {
-        await this.config.sessionStore.update(sessionId, { status: "running" });
-      }
-      await this.config.sessionStore.appendMessage(sessionId, {
-        role: "user",
-        content: params.prompt ?? ""
+    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,
@@ -3497,6 +3590,8 @@ class ContractSpecAgent {
         tenantId: params.options?.tenantId,
         actorId: params.options?.actorId,
         sessionId,
+        workflowId,
+        threadId,
         metadata: params.options?.metadata
       }
     };
@@ -3519,26 +3614,94 @@ ${params.prompt}` : params.prompt ?? "";
         });
       }
     } catch (error) {
+      const executionError = toAgentExecutionError(error);
       if (this.config.sessionStore) {
         await this.config.sessionStore.update(sessionId, {
-          status: "failed"
+          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;
     }
-    this.activeStepContexts.delete(sessionId);
-    const escalationError = resolveEscalationError(this.spec, result.finishReason);
-    if (this.config.sessionStore) {
-      await this.config.sessionStore.appendMessage(sessionId, {
-        role: "assistant",
-        content: result.text
+    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: escalationError ? "escalated" : "completed"
+        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,
@@ -3557,23 +3720,25 @@ ${params.prompt}` : params.prompt ?? "";
       finishReason: result.finishReason,
       usage: result.usage,
       session: session ?? undefined,
-      pendingApproval: escalationError ? {
-        toolName: this.spec.policy?.escalation?.approvalWorkflow ?? "approval_required",
-        toolCallId: `approval_${sessionId}`,
-        args: {
-          reason: escalationError.message,
-          code: escalationError.code
-        }
+      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 ?? randomUUID();
+    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
     });
@@ -3582,6 +3747,13 @@ ${params.prompt}` : params.prompt ?? "";
 ${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,
@@ -3589,26 +3761,6 @@ ${params.prompt}` : params.prompt ?? "";
     });
     const effectiveMaxSteps = resolveMaxSteps(params.maxSteps, this.spec.maxSteps);
     const inner = this.createInnerAgent(model, effectiveMaxSteps);
-    if (this.config.sessionStore) {
-      const existing = await this.config.sessionStore.get(sessionId);
-      if (!existing) {
-        await this.config.sessionStore.create({
-          sessionId,
-          agentId: this.id,
-          tenantId: params.options?.tenantId,
-          actorId: params.options?.actorId,
-          status: "running",
-          messages: [],
-          steps: [],
-          metadata: params.options?.metadata
-        });
-      }
-      await this.config.sessionStore.appendMessage(sessionId, {
-        role: "user",
-        content: prompt
-      });
-      await this.config.sessionStore.update(sessionId, { status: "running" });
-    }
     return inner.stream({
       prompt,
       abortSignal: params.signal,
@@ -3616,21 +3768,92 @@ ${params.prompt}` : params.prompt ?? "";
         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: step.finishReason === "tool-calls" ? "waiting" : "running"
+        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 context = sessionId ? this.activeStepContexts.get(sessionId) : undefined;
       const stepStartedAt = context?.stepStartedAt ?? now;
       const durationMs = Math.max(now.getTime() - stepStartedAt.getTime(), 0);
       if (context) {
@@ -3641,6 +3864,7 @@ ${params.prompt}` : params.prompt ?? "";
         sessionId,
         tenantId: context?.tenantId,
         actorId: context?.actorId,
+        workflowId: context?.workflowId,
         traceId: context?.traceId,
         stepIndex: context?.stepIndex,
         stepStartedAt
@@ -3650,6 +3874,215 @@ ${params.prompt}` : params.prompt ?? "";
       }
     }
   }
+  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,
@@ -3679,7 +4112,9 @@ ${params.prompt}` : params.prompt ?? "";
       contractspec_trace_id: params.traceId,
       contractspec_agent_id: this.id,
       contractspec_tenant_id: params.options?.tenantId,
-      contractspec_actor_id: params.options?.actorId
+      contractspec_actor_id: params.options?.actorId,
+      contractspec_workflow_id: params.options?.workflowId,
+      contractspec_thread_id: params.options?.threadId
     };
     const tracingOptions = {
       ...posthogConfig.tracingOptions,
@@ -3691,6 +4126,106 @@ ${params.prompt}` : params.prompt ?? "";
     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)) {
@@ -3733,8 +4268,8 @@ function resolveEscalationError(spec, finishReason) {
 }
 var ContractSpecCallOptionsSchema;
 var init_contract_spec_agent = __esm(() => {
+  init_workflow();
   init_injector();
-  init_spec();
   init_adapter();
   init_knowledge_tool();
   init_mcp_client();
@@ -3744,6 +4279,8 @@ var init_contract_spec_agent = __esm(() => {
     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()
   });
 });
@@ -3789,7 +4326,10 @@ class AgentFactory {
       posthogConfig: this.config.posthogConfig,
       additionalTools: mergedTools,
       mcpServers: mergedMcpServers.length > 0 ? mergedMcpServers : undefined,
-      modelSelector: this.config.modelSelector
+      modelSelector: this.config.modelSelector,
+      runtimeAdapters: options?.runtimeAdapters ?? this.config.runtimeAdapters,
+      approvalWorkflow: options?.approvalWorkflow ?? this.config.approvalWorkflow,
+      eventEmitter: this.config.eventEmitter
     });
   }
   async getOrCreate(name, version) {