@kortyx/agent 0.14.1 → 0.15.0

package/dist/index.js

@@ -21,11 +21,15 @@ var index_exports = {};
 __export(index_exports, {
   createAgent: () => createAgent,
   createChatRouteHandler: () => createChatRouteHandler,
+  createCheckpointRouteHandler: () => createCheckpointRouteHandler,
   extractLatestUserMessage: () => extractLatestUserMessage,
   handleChatRequestBody: () => handleChatRequestBody,
+  handleCheckpointRequestBody: () => handleCheckpointRequestBody,
   orchestrateGraphStream: () => orchestrateGraphStream,
   parseChatRequestBody: () => parseChatRequestBody,
+  parseCheckpointRequestBody: () => parseCheckpointRequestBody,
   parseResumeMeta: () => parseResumeMeta,
+  projectWorkflowTopology: () => projectWorkflowTopology,
   streamChat: () => streamChat,
   streamChatFromRoute: () => streamChatFromRoute,
   transformGraphStreamForUI: () => transformGraphStreamForUI,
@@ -50,6 +54,25 @@ var chatRequestBodySchema = import_zod.z.looseObject({
   context: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
   messages: import_zod.z.array(chatMessageSchema)
 });
+var checkpointRequestBodySchema = import_zod.z.discriminatedUnion("action", [
+  import_zod.z.object({
+    action: import_zod.z.literal("list"),
+    sessionId: import_zod.z.string().min(1)
+  }).strict(),
+  import_zod.z.object({
+    action: import_zod.z.literal("get"),
+    checkpointId: import_zod.z.string().min(1)
+  }).strict(),
+  import_zod.z.object({
+    action: import_zod.z.literal("rollback"),
+    checkpointId: import_zod.z.string().min(1)
+  }).strict(),
+  import_zod.z.object({
+    action: import_zod.z.literal("fork"),
+    checkpointId: import_zod.z.string().min(1),
+    newSessionId: import_zod.z.string().min(1).optional()
+  }).strict()
+]);
 var toErrorMessage = (error) => error instanceof Error ? error.message : String(error);
 function parseChatRequestBody(value) {
   const parsed = chatRequestBodySchema.safeParse(value);
@@ -67,6 +90,12 @@ function parseChatRequestBody(value) {
     messages: parsed.data.messages
   };
 }
+function parseCheckpointRequestBody(value) {
+  const parsed = checkpointRequestBodySchema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  const [firstIssue] = parsed.error.issues;
+  throw new Error(firstIssue.message);
+}
 async function handleChatRequestBody(args) {
   const { agent, body } = args;
   const stream = await agent.streamChat(body.messages, {
@@ -105,6 +134,38 @@ function createChatRouteHandler(args) {
     }
   };
 }
+async function handleCheckpointRequestBody(args) {
+  const { agent, body } = args;
+  const result = body.action === "list" ? await agent.listCheckpoints(body.sessionId) : body.action === "get" ? await agent.getCheckpoint(body.checkpointId) : body.action === "rollback" ? await agent.rollbackTo(body.checkpointId) : await agent.fork(body.checkpointId, {
+    ...body.newSessionId ? { newSessionId: body.newSessionId } : {}
+  });
+  return new Response(JSON.stringify(result), {
+    headers: {
+      "content-type": "application/json"
+    }
+  });
+}
+function createCheckpointRouteHandler(args) {
+  const { agent, errorStatus = 400 } = args;
+  return async function POST(request) {
+    try {
+      const body = parseCheckpointRequestBody(await request.json());
+      return await handleCheckpointRequestBody({ agent, body });
+    } catch (error) {
+      return new Response(
+        JSON.stringify({
+          error: toErrorMessage(error)
+        }),
+        {
+          status: errorStatus,
+          headers: {
+            "content-type": "application/json"
+          }
+        }
+      );
+    }
+  };
+}
 
 // src/adapters/http-client.ts
 var import_browser = require("@kortyx/stream/browser");
@@ -127,6 +188,266 @@ var import_providers = require("@kortyx/providers");
 var import_runtime4 = require("@kortyx/runtime");
 var import_zod2 = require("zod");
 
+// src/telemetry/events.ts
+var import_node_crypto = require("crypto");
+var isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var createId = () => {
+  try {
+    return (0, import_node_crypto.randomUUID)();
+  } catch {
+    return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  }
+};
+var shouldCaptureTelemetryContent = (value, side) => {
+  if (value === true) return true;
+  return Boolean(
+    value && typeof value === "object" && !Array.isArray(value) && value[side] === true
+  );
+};
+var emitTelemetryEvent = (args) => {
+  const telemetry = isRecord(args.config.telemetry) ? args.config.telemetry : void 0;
+  const base = telemetry?.correlation;
+  const runId = args.correlation?.runId ?? base?.runId;
+  const workflowId = args.correlation?.workflowId ?? base?.workflowId;
+  if (!telemetry?.reporter || !telemetry.environment || !telemetry.service || !runId || !workflowId) {
+    return;
+  }
+  const context = isRecord(args.config.context) ? args.config.context : {};
+  const event = {
+    schemaVersion: 1,
+    eventId: createId(),
+    occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+    environment: telemetry.environment,
+    service: telemetry.service,
+    correlation: {
+      runId,
+      workflowId,
+      ...base?.sessionId ? { sessionId: base.sessionId } : {},
+      ...base?.workflowRevisionId ? { workflowRevisionId: base.workflowRevisionId } : {},
+      ...base?.topologyHash ? { topologyHash: base.topologyHash } : {},
+      ...base?.nodeId ? { nodeId: base.nodeId } : {},
+      ...args.correlation ?? {}
+    },
+    ...telemetry.metadata || telemetry.tags || context.userId || context.tenantId ? {
+      context: {
+        ...typeof context.userId === "string" ? { userId: context.userId } : {},
+        ...typeof context.tenantId === "string" ? { tenantId: context.tenantId } : {},
+        ...telemetry.tags ? { tags: telemetry.tags } : {},
+        ...telemetry.metadata ? { metadata: telemetry.metadata } : {}
+      }
+    } : {},
+    type: args.type,
+    payload: args.payload
+  };
+  try {
+    void Promise.resolve(telemetry.reporter.emit([event])).then(async () => {
+      if (!args.flush) return;
+      const flush = telemetry.flush;
+      if (typeof flush === "function") await flush.call(telemetry);
+    }).catch(() => {
+    });
+  } catch {
+  }
+};
+
+// src/telemetry/topology.ts
+var import_node_crypto2 = require("crypto");
+var isRecord2 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var stableValue = (value) => {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!isRecord2(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value).filter(([, nested]) => typeof nested !== "function").sort(([a], [b]) => a.localeCompare(b)).map(([key, nested]) => [key, stableValue(nested)])
+  );
+};
+var asString = (value) => typeof value === "string" && value.length > 0 ? value : void 0;
+var metadata = (value) => isRecord2(value) ? stableValue(value) : void 0;
+var tagsFrom = (workflow) => {
+  const raw = isRecord2(workflow.metadata) ? workflow.metadata.tags : void 0;
+  if (!Array.isArray(raw)) return void 0;
+  const tags = raw.filter((tag) => typeof tag === "string").sort();
+  return tags.length > 0 ? tags : void 0;
+};
+var wordsFrom = (value) => value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").split(/[^a-zA-Z0-9]+/).map((word) => word.toLowerCase()).filter(Boolean);
+var camelFromWorkflowId = (workflowId) => {
+  const [first = "", ...rest] = wordsFrom(workflowId);
+  return [
+    first,
+    ...rest.map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`)
+  ].join("");
+};
+var resolveMemberTransitionTarget = (memberName, knownWorkflowIds) => {
+  const exact = knownWorkflowIds.find(
+    (workflowId) => camelFromWorkflowId(workflowId) === memberName
+  );
+  if (exact) return exact;
+  const memberWords = new Set(wordsFrom(memberName));
+  const candidates = knownWorkflowIds.map((workflowId) => {
+    const workflowWords = wordsFrom(workflowId);
+    const matched = workflowWords.filter((word) => memberWords.has(word));
+    return {
+      workflowId,
+      matched: matched.length,
+      total: workflowWords.length
+    };
+  }).filter(
+    (candidate) => candidate.total > 0 && candidate.matched === candidate.total
+  ).sort(
+    (a, b) => b.matched - a.matched || a.workflowId.localeCompare(b.workflowId)
+  );
+  if (candidates.length !== 1) return void 0;
+  return candidates[0]?.workflowId;
+};
+var transitionTargetsFromRun = (run, knownWorkflowIds) => {
+  if (typeof run !== "function") return [];
+  const source = Function.prototype.toString.call(run);
+  const targets = /* @__PURE__ */ new Set();
+  for (const match of source.matchAll(
+    /\btransitionTo\s*:\s*(['"`])([^'"`$]+)\1/g
+  )) {
+    const target = match[2]?.trim();
+    if (target) targets.add(target);
+  }
+  for (const match of source.matchAll(
+    /\btransitionTo\s*:\s*(?:[A-Za-z_$][\w$]*\.)+([A-Za-z_$][\w$]*)/g
+  )) {
+    const memberName = match[1];
+    const target = resolveMemberTransitionTarget(memberName, knownWorkflowIds);
+    if (target) targets.add(target);
+  }
+  for (const match of source.matchAll(
+    /\btransitionTo\s*:\s*(?:[A-Za-z_$][\w$]*\.)*[A-Za-z_$][\w$]*\[['"`]([A-Za-z_$][\w$]*)['"`]\]/g
+  )) {
+    const memberName = match[1];
+    const target = resolveMemberTransitionTarget(memberName, knownWorkflowIds);
+    if (target) targets.add(target);
+  }
+  return [...targets].sort();
+};
+var transitionsFromNodes = (workflow, knownWorkflowIds) => {
+  const transitions = /* @__PURE__ */ new Map();
+  for (const [sourceNodeId, node] of Object.entries(
+    workflow.nodes
+  )) {
+    for (const targetWorkflowId of transitionTargetsFromRun(
+      node.run,
+      knownWorkflowIds
+    )) {
+      if (targetWorkflowId === workflow.id) continue;
+      const key = `${sourceNodeId}:${targetWorkflowId}`;
+      transitions.set(key, { sourceNodeId, targetWorkflowId });
+    }
+  }
+  return [...transitions.values()].sort(
+    (a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))
+  );
+};
+var projectWorkflowTopology = (args) => {
+  const nodes = Object.entries(
+    args.workflow.nodes
+  ).map(([id, node]) => {
+    const nodeMetadata = metadata(node.metadata);
+    const params = metadata(node.params);
+    const model = isRecord2(node.params) ? isRecord2(node.params.model) ? node.params.model : void 0 : void 0;
+    const provider = isRecord2(model) ? asString(model.provider) ?? asString(model.providerId) : void 0;
+    const modelName = isRecord2(model) ? asString(model.name) ?? asString(model.modelId) : void 0;
+    return {
+      id,
+      ...asString(nodeMetadata?.label) ? { label: asString(nodeMetadata?.label) } : {},
+      ...asString(nodeMetadata?.type) ? { type: asString(nodeMetadata?.type) } : {},
+      ...provider ? { provider } : {},
+      ...modelName ? { model: modelName } : {},
+      ...nodeMetadata ? { metadata: nodeMetadata } : {},
+      // These fields feed the hash but are intentionally not sent as Studio
+      // display metadata. They are stripped below after hashing.
+      _execution: {
+        ...typeof node.run === "string" ? { run: node.run } : {},
+        ...params ? { params } : {},
+        ...node.behavior ? { behavior: stableValue(node.behavior) } : {}
+      }
+    };
+  }).sort((a, b) => a.id.localeCompare(b.id));
+  const edges = args.workflow.edges.map((edge) => {
+    const condition = isRecord2(edge[2]) ? asString(edge[2].when) : void 0;
+    return {
+      sourceNodeId: edge[0],
+      targetNodeId: edge[1],
+      ...condition ? { condition } : {}
+    };
+  }).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+  const transitions = transitionsFromNodes(
+    args.workflow,
+    args.knownWorkflowIds ?? []
+  );
+  const tags = tagsFrom(args.workflow);
+  const hashInput = stableValue({
+    workflowId: args.workflow.id,
+    nodes: nodes.map((node) => ({ id: node.id, ...node._execution })),
+    edges,
+    transitions
+  });
+  const topologyHash = (0, import_node_crypto2.createHash)("sha256").update(JSON.stringify(hashInput)).digest("hex");
+  return {
+    schemaVersion: 1,
+    environment: args.environment,
+    service: args.service,
+    workflow: {
+      id: args.workflow.id,
+      declaredVersion: args.workflow.version,
+      ...args.workflow.description ? { description: args.workflow.description } : {},
+      ...tags ? { tags } : {},
+      topologyHash,
+      nodes: nodes.map(({ _execution: _ignored, ...node }) => node),
+      edges,
+      ...transitions.length > 0 ? { transitions } : {}
+    }
+  };
+};
+var prepareWorkflowTelemetry = (args) => {
+  const telemetry = isRecord2(args.config.telemetry) ? args.config.telemetry : void 0;
+  if (!telemetry?.reporter || !telemetry.environment || !telemetry.service) {
+    return args.config;
+  }
+  let snapshot;
+  try {
+    snapshot = projectWorkflowTopology({
+      workflow: args.workflow,
+      environment: telemetry.environment,
+      service: telemetry.service,
+      knownWorkflowIds: args.knownWorkflowIds
+    });
+  } catch {
+    return args.config;
+  }
+  let workflowRevisionId;
+  try {
+    workflowRevisionId = telemetry.reporter.getWorkflowRevisionId?.({
+      environment: snapshot.environment,
+      workflowId: snapshot.workflow.id,
+      topologyHash: snapshot.workflow.topologyHash
+    });
+    void Promise.resolve(
+      telemetry.reporter.ensureWorkflowTopology(snapshot)
+    ).catch(() => {
+    });
+  } catch {
+  }
+  return {
+    ...args.config,
+    telemetry: {
+      ...telemetry,
+      correlation: {
+        ...telemetry.correlation ?? {},
+        runId: args.runId,
+        ...args.sessionId ? { sessionId: args.sessionId } : {},
+        workflowId: snapshot.workflow.id,
+        topologyHash: snapshot.workflow.topologyHash,
+        ...workflowRevisionId ? { workflowRevisionId } : {}
+      }
+    }
+  };
+};
+
 // src/chat/process-chat.ts
 var import_runtime3 = require("@kortyx/runtime");
 
@@ -139,10 +460,12 @@ var import_runtime = require("@kortyx/runtime");
 var import_langgraph = require("@langchain/langgraph");
 
 // src/stream/transform-graph-stream-for-ui.ts
+var isGraphStateOutput = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && "currentWorkflow" in value;
 async function* transformGraphStreamForUI(stream, options = {}) {
   const { debug = false, emitStatus = debug } = options;
   const startedNodes = /* @__PURE__ */ new Set();
   const endedNodes = /* @__PURE__ */ new Set();
+  let latestGraphState = null;
   for await (const event of stream) {
     const { event: type, name, data } = event ?? {};
     if (debug) console.log(`[debug:event]`, JSON.stringify(event, null, 2));
@@ -167,6 +490,7 @@ async function* transformGraphStreamForUI(stream, options = {}) {
             JSON.stringify(output, null, 2)
           );
         if (!output || nodeName?.startsWith("ChannelWrite")) break;
+        if (isGraphStateOutput(output)) latestGraphState = output;
         if (nodeName !== "__start__" && nodeName !== "__end__") {
           if (!endedNodes.has(nodeName)) {
             if (emitStatus) {
@@ -183,7 +507,11 @@ async function* transformGraphStreamForUI(stream, options = {}) {
       case "on_graph_end": {
         if (debug)
           console.log(`[debug:on_graph_end]`, JSON.stringify(data, null, 2));
-        yield { type: "done", data: data?.output ?? null };
+        const output = data?.output;
+        yield {
+          type: "done",
+          data: isGraphStateOutput(output) ? output : latestGraphState
+        };
         break;
       }
       default:
@@ -196,42 +524,71 @@ async function* transformGraphStreamForUI(stream, options = {}) {
 }
 
 // src/orchestrator.ts
-var isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var isRecord3 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var isGraphState = (value) => isRecord3(value) && typeof value.currentWorkflow === "string";
+var getGraphCheckpointId = (snapshot) => {
+  if (!isRecord3(snapshot)) return void 0;
+  const config = isRecord3(snapshot.config) ? snapshot.config : void 0;
+  const configurable = config && isRecord3(config.configurable) ? config.configurable : void 0;
+  const checkpointId = configurable?.checkpoint_id;
+  return typeof checkpointId === "string" && checkpointId.length > 0 ? checkpointId : void 0;
+};
 var getTraceAdapter = (config) => {
-  const telemetry = isRecord(config.telemetry) ? config.telemetry : void 0;
+  const telemetry = isRecord3(config.telemetry) ? config.telemetry : void 0;
   const traceAdapter = telemetry?.trace ?? config.reasonTrace;
-  return isRecord(traceAdapter) ? traceAdapter : void 0;
+  return isRecord3(traceAdapter) ? traceAdapter : void 0;
 };
 async function orchestrateGraphStream({
   sessionId,
   runId,
   graph,
   state,
-  config,
+  config: initialConfig,
   selectWorkflow,
+  knownWorkflowIds,
   frameworkAdapter
 }) {
   const out = new import_node_stream.PassThrough({ objectMode: true });
+  let config = initialConfig;
   let currentGraph = graph;
   let currentState = state;
   let finished = false;
   let structuredSeq = 0;
   const debugEnabled = Boolean(config?.features?.tracing);
   const traceAdapter = getTraceAdapter(config);
-  const contextMeta = isRecord(config.context) ? config.context : {};
-  const telemetryConfig = isRecord(config.telemetry) ? config.telemetry : {};
+  const contextMeta = isRecord3(config.context) ? config.context : {};
+  const telemetryConfig = isRecord3(config.telemetry) ? config.telemetry : {};
+  const emitResumeFailure = (resumeError) => {
+    const interruptId = typeof config.telemetryInterruptId === "string" ? config.telemetryInterruptId : void 0;
+    if (!interruptId) return;
+    emitTelemetryEvent({
+      config,
+      type: "interrupt.resolved",
+      correlation: typeof config.telemetryInterruptNodeId === "string" ? { nodeId: config.telemetryInterruptNodeId } : void 0,
+      payload: {
+        interruptId,
+        resolvedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        resumeOutcome: "failed",
+        resumeError: resumeError instanceof Error ? resumeError.message : String(resumeError)
+      },
+      flush: true
+    });
+  };
+  const telemetryCorrelation = isRecord3(telemetryConfig.correlation) ? telemetryConfig.correlation : {};
   const runSpanArgs = {
     name: "kortyx.run",
     attributes: {
       ...sessionId ? { sessionId } : {},
       runId,
       workflowId: state.currentWorkflow,
+      ...typeof telemetryCorrelation.topologyHash === "string" ? { topologyHash: telemetryCorrelation.topologyHash } : {},
+      ...typeof telemetryCorrelation.workflowRevisionId === "string" ? { workflowRevisionId: telemetryCorrelation.workflowRevisionId } : {},
       ...typeof contextMeta.userId === "string" ? { userId: contextMeta.userId } : {},
       ...typeof contextMeta.tenantId === "string" ? { tenantId: contextMeta.tenantId } : {}
     },
     telemetry: {
       metadata: {
-        ...isRecord(telemetryConfig.metadata) ? telemetryConfig.metadata : {},
+        ...isRecord3(telemetryConfig.metadata) ? telemetryConfig.metadata : {},
         ...contextMeta
       },
       tags: Array.isArray(telemetryConfig.tags) ? telemetryConfig.tags : void 0,
@@ -240,6 +597,10 @@ async function orchestrateGraphStream({
     }
   };
   const namespacesUsed = /* @__PURE__ */ new Set();
+  const touchedNodes = /* @__PURE__ */ new Set();
+  const structuredStreamIds = /* @__PURE__ */ new Set();
+  const activePendingRequests = /* @__PURE__ */ new Map();
+  const pendingRequestWrites = [];
   try {
     const sid = config?.session?.id;
     if (sid && typeof sid === "string") {
@@ -249,7 +610,9 @@ async function orchestrateGraphStream({
   }
   const pending = {
     to: null,
-    payload: {}
+    payload: {},
+    sourceNodeId: void 0,
+    sourceWorkflowId: void 0
   };
   let lastStatusMsg = "";
   let lastStatusAt = 0;
@@ -315,10 +678,12 @@ async function orchestrateGraphStream({
       createdAt: Date.now(),
       ttlMs: pendingTtlMs
     };
+    activePendingRequests.set(record.token, record);
     if (pendingStore) {
-      pendingStore.save(record).catch((error) => {
+      const savePromise = pendingStore.save(record).catch((error) => {
         console.error("[orchestrator] failed to save pending request", error);
       });
+      pendingRequestWrites.push(savePromise);
     }
     const clientMeta = record.schema.meta && typeof record.schema.meta === "object" && !Array.isArray(record.schema.meta) ? Object.fromEntries(
       Object.entries(record.schema.meta).filter(
@@ -349,6 +714,34 @@ async function orchestrateGraphStream({
         }))
       }
     });
+    emitTelemetryEvent({
+      config,
+      type: "interrupt.created",
+      correlation: { nodeId: record.node },
+      payload: {
+        interruptId: record.requestId,
+        requestId: record.requestId,
+        kind: record.schema.kind,
+        interactionMode: record.schema.kind === "text" ? "freeform" : record.options.length > 0 ? "static-options" : record.schema.schemaId ? "dynamic-picker" : "unknown",
+        ...record.schema.schemaId ? { schemaId: record.schema.schemaId } : {},
+        ...record.schema.schemaVersion ? { schemaVersion: record.schema.schemaVersion } : {},
+        ...typeof record.schema.question === "string" && shouldCaptureTelemetryContent(telemetryConfig.captureContent, "output") ? { question: record.schema.question } : {},
+        ...shouldCaptureTelemetryContent(
+          telemetryConfig.captureContent,
+          "output"
+        ) ? {
+          options: record.options.map((option) => ({
+            id: option.id,
+            label: option.label,
+            ...option.description ? { description: option.description } : {}
+          }))
+        } : {},
+        optionCount: record.options.length,
+        nodeId: record.node,
+        expiresAt: new Date(record.createdAt + record.ttlMs).toISOString()
+      },
+      flush: true
+    });
     wroteHumanInput = true;
   };
   const forwardEmit = (event, payload) => {
@@ -376,6 +769,7 @@ async function orchestrateGraphStream({
     if (event === "text-start") {
       const node = payload?.node;
       if (!node) return;
+      touchedNodes.add(node);
       out.write({
         type: "text-start",
         node,
@@ -389,6 +783,7 @@ async function orchestrateGraphStream({
       const node = payload?.node;
       const delta = String(payload?.delta ?? "");
       if (!node || !delta) return;
+      touchedNodes.add(node);
       appendAccumulatedOutput(payload, node, delta);
       out.write({
         type: "text-delta",
@@ -403,6 +798,7 @@ async function orchestrateGraphStream({
     if (event === "text-end") {
       const node = payload?.node;
       if (!node) return;
+      touchedNodes.add(node);
       out.write({
         type: "text-end",
         node,
@@ -426,6 +822,7 @@ async function orchestrateGraphStream({
         ...payloadObj.opId ? { opId: payloadObj.opId } : {},
         ...payloadObj.input !== void 0 ? { input: payloadObj.input } : {}
       });
+      if (payloadObj.node) touchedNodes.add(payloadObj.node);
       return;
     }
     if (event === "tool-call-result") {
@@ -444,6 +841,7 @@ async function orchestrateGraphStream({
         ...payloadObj.structuredContent !== void 0 ? { structuredContent: payloadObj.structuredContent } : {},
         ...typeof payloadObj.isError === "boolean" ? { isError: payloadObj.isError } : {}
       });
+      if (payloadObj.node) touchedNodes.add(payloadObj.node);
       return;
     }
     if (event === "tool-call-error") {
@@ -460,21 +858,26 @@ async function orchestrateGraphStream({
         ...payloadObj.opId ? { opId: payloadObj.opId } : {},
         message: String(payloadObj.message ?? "")
       });
+      if (payloadObj.node) touchedNodes.add(payloadObj.node);
       return;
     }
     if (event === "message") {
       const node = payload?.node;
       const text = String(payload?.content ?? "");
+      if (node) touchedNodes.add(node);
       out.write({ type: "message", node, content: text });
       return;
     }
     if (event === "structured_data") {
       const payloadObj = payload;
       const kind = payloadObj.kind === "set" || payloadObj.kind === "append" || payloadObj.kind === "text-delta" || payloadObj.kind === "final" ? payloadObj.kind : "final";
+      const streamId = typeof payloadObj.streamId === "string" && payloadObj.streamId ? payloadObj.streamId : nextStructuredStreamId();
+      structuredStreamIds.add(streamId);
+      if (payloadObj.node) touchedNodes.add(payloadObj.node);
       out.write({
         type: "structured-data",
         node: payloadObj.node,
-        streamId: typeof payloadObj.streamId === "string" && payloadObj.streamId ? payloadObj.streamId : nextStructuredStreamId(),
+        streamId,
         dataType: typeof payloadObj.dataType === "string" && payloadObj.dataType ? payloadObj.dataType : "generic",
         kind,
         ...typeof payloadObj.schemaId === "string" ? { schemaId: payloadObj.schemaId } : {},
@@ -504,10 +907,14 @@ async function orchestrateGraphStream({
       });
       pending.to = payload?.transitionTo ?? null;
       pending.payload = payload?.payload ?? {};
+      const transition = payload;
+      pending.sourceNodeId = typeof transition.node === "string" ? transition.node : void 0;
+      pending.sourceWorkflowId = typeof transition.workflow === "string" ? transition.workflow : void 0;
       return;
     }
     if (event === "interrupt") {
       const p = payload;
+      if (typeof p?.node === "string") touchedNodes.add(p.node);
       const local = {
         node: p?.node,
         workflow: p?.workflow,
@@ -522,11 +929,39 @@ async function orchestrateGraphStream({
   const runLoop = async (runTraceSpan) => {
     while (true) {
       let workflowFinalState = null;
+      let workflowFinalGraphCheckpointId;
+      let sawWorkflowDone = false;
+      let workflowDoneData;
       currentGraph.config = currentGraph.config || {};
       currentGraph.config.emit = forwardEmit;
       const threadId = currentGraph.config?.session?.id || sessionId || "anonymous-session";
-      const checkpointNs = String(currentState.currentWorkflow || "default");
+      const checkpointNs = "";
       namespacesUsed.add(checkpointNs);
+      const readLatestGraphCheckpointId = async () => {
+        const checkpointer = currentGraph.config?.checkpointer;
+        return checkpointer?.getLatestCheckpointId?.(runId, checkpointNs);
+      };
+      const readLatestGraphSnapshot = async () => {
+        if (typeof currentGraph.getState !== "function") {
+          const checkpointId2 = await readLatestGraphCheckpointId();
+          return checkpointId2 ? { state: currentState, checkpointId: checkpointId2 } : null;
+        }
+        const snapshot = await currentGraph.getState({
+          configurable: {
+            thread_id: runId,
+            checkpoint_ns: checkpointNs
+          }
+        });
+        const values = isRecord3(snapshot) && "values" in snapshot ? snapshot.values : snapshot;
+        const checkpointId = getGraphCheckpointId(snapshot) ?? await readLatestGraphCheckpointId();
+        if (!isGraphState(values)) {
+          return checkpointId ? { state: currentState, checkpointId } : null;
+        }
+        return {
+          state: values,
+          ...checkpointId ? { checkpointId } : {}
+        };
+      };
       if (debugEnabled) {
         out.write({
           type: "status",
@@ -536,13 +971,14 @@ async function orchestrateGraphStream({
       const isResume = Boolean(currentGraph.config?.resume);
       const resumeUpdate = currentGraph.config?.resumeUpdate;
       const resumeValue = currentGraph.config?.resumeValue;
+      const resumeCheckpointId = currentGraph.config?.resumeCheckpointId;
       const invokeState = isResume ? resumeValue !== void 0 && resumeUpdate ? new import_langgraph.Command({ resume: resumeValue, update: resumeUpdate }) : resumeValue !== void 0 ? new import_langgraph.Command({ resume: resumeValue }) : resumeUpdate ? new import_langgraph.Command({ update: resumeUpdate }) : null : currentState;
       const runtimeStream = currentGraph.streamEvents(invokeState, {
         version: "v2",
         configurable: {
           thread_id: runId,
-          // Use a stable namespace so checkpoints survive across recompiles of same workflow
-          checkpoint_ns: checkpointNs
+          checkpoint_ns: checkpointNs,
+          ...isResume && resumeCheckpointId ? { checkpoint_id: resumeCheckpointId } : {}
         }
       });
       if (debugEnabled) {
@@ -557,20 +993,58 @@ async function orchestrateGraphStream({
       });
       for await (const chunk of uiStream) {
         if (finished) break;
-        out.write(chunk);
+        if ("node" in chunk && typeof chunk.node === "string") {
+          touchedNodes.add(chunk.node);
+        }
         if (chunk.type === "done") {
-          workflowFinalState = chunk.data ?? null;
-          break;
+          sawWorkflowDone = true;
+          workflowDoneData = chunk.data;
+          continue;
         }
+        out.write(chunk);
       }
       if (finished) return;
+      if (sawWorkflowDone) {
+        const graphSnapshot = await readLatestGraphSnapshot();
+        workflowFinalGraphCheckpointId = graphSnapshot?.checkpointId;
+        workflowFinalState = isGraphState(workflowDoneData) ? workflowDoneData : graphSnapshot?.state ?? currentState;
+      }
       const transitionTo = pending.to;
       const transitionPayload = pending.payload;
+      const sourceNodeId = pending.sourceNodeId;
+      const sourceWorkflowId = pending.sourceWorkflowId;
       pending.to = null;
       pending.payload = {};
+      pending.sourceNodeId = void 0;
+      pending.sourceWorkflowId = void 0;
       if (transitionTo) {
         try {
           const nextWorkflow = await selectWorkflow(transitionTo);
+          const sourceTelemetry = isRecord3(config.telemetry) ? config.telemetry : {};
+          config = prepareWorkflowTelemetry({
+            config,
+            workflow: nextWorkflow,
+            runId,
+            sessionId,
+            knownWorkflowIds
+          });
+          const targetTelemetry = isRecord3(config.telemetry) ? config.telemetry : {};
+          emitTelemetryEvent({
+            config,
+            type: "workflow.transitioned",
+            ...sourceNodeId ? { correlation: { nodeId: sourceNodeId } } : {},
+            payload: {
+              sourceNodeId: sourceNodeId ?? "",
+              sourceWorkflowId: sourceWorkflowId ?? String(currentState.currentWorkflow),
+              ...typeof sourceTelemetry.correlation === "object" && sourceTelemetry.correlation && typeof sourceTelemetry.correlation.workflowRevisionId === "string" ? {
+                sourceWorkflowRevisionId: sourceTelemetry.correlation.workflowRevisionId
+              } : {},
+              targetWorkflowId: transitionTo,
+              ...typeof targetTelemetry.correlation === "object" && targetTelemetry.correlation && typeof targetTelemetry.correlation.workflowRevisionId === "string" ? {
+                targetWorkflowRevisionId: targetTelemetry.correlation.workflowRevisionId
+              } : {}
+            }
+          });
           const nextGraph = await (0, import_runtime.createExecutionGraph)(nextWorkflow, {
             ...config,
             emit: forwardEmit
@@ -585,6 +1059,7 @@ async function orchestrateGraphStream({
           currentState = {
             ...currentState,
             currentWorkflow: transitionTo,
+            config,
             input: newInput,
             data: mergedData,
             ui: {}
@@ -607,12 +1082,27 @@ async function orchestrateGraphStream({
       }
       if (workflowFinalState) {
         if (workflowFinalState && pendingRecordToken) {
+          if (pendingRequestWrites.length > 0) {
+            await Promise.all(pendingRequestWrites);
+          }
           if (pendingStore) {
             await pendingStore.update(pendingRecordToken, {
-              state: workflowFinalState
+              state: workflowFinalState,
+              ...workflowFinalGraphCheckpointId ? { graphCheckpointId: workflowFinalGraphCheckpointId } : {}
+            });
+          }
+          const pendingRequest = activePendingRequests.get(pendingRecordToken);
+          if (pendingRequest) {
+            activePendingRequests.set(pendingRecordToken, {
+              ...pendingRequest,
+              state: workflowFinalState,
+              ...workflowFinalGraphCheckpointId ? { graphCheckpointId: workflowFinalGraphCheckpointId } : {}
             });
           }
         }
+        if (!pendingRecordToken && pendingRequestWrites.length > 0) {
+          await Promise.all(pendingRequestWrites);
+        }
         const shouldKeepFrameworkState = Boolean(pendingRecordToken) || Boolean(workflowFinalState?.awaitingHumanInput);
         if (!shouldKeepFrameworkState) {
           try {
@@ -637,15 +1127,106 @@ async function orchestrateGraphStream({
           "kortyx.run.final_workflow": String(currentState.currentWorkflow)
         });
         runTraceSpan.end?.(runTraceEndArgs());
+        const resolvedSessionId2 = config?.session?.id || sessionId || "";
+        if (resolvedSessionId2 && frameworkAdapter?.sessionCheckpoints) {
+          try {
+            const checkpoint = await frameworkAdapter.sessionCheckpoints.append(
+              {
+                sessionId: resolvedSessionId2,
+                runId,
+                ...workflowFinalGraphCheckpointId ? { graphCheckpointId: workflowFinalGraphCheckpointId } : {},
+                workflow: String(workflowFinalState.currentWorkflow),
+                state: workflowFinalState,
+                nodes: Array.from(touchedNodes),
+                structuredStreamIds: Array.from(structuredStreamIds),
+                pendingRequests: Array.from(activePendingRequests.values())
+              }
+            );
+            out.write({
+              type: "checkpoint",
+              id: checkpoint.id,
+              sessionId: checkpoint.sessionId,
+              turnIndex: checkpoint.turnIndex,
+              ...checkpoint.label ? { label: checkpoint.label } : {}
+            });
+            emitTelemetryEvent({
+              config,
+              type: "session.checkpointed",
+              payload: {
+                checkpointId: checkpoint.id,
+                turnIndex: checkpoint.turnIndex,
+                ...checkpoint.parentCheckpointId ? { parentCheckpointId: checkpoint.parentCheckpointId } : {},
+                nodes: checkpoint.nodes
+              }
+            });
+          } catch (error) {
+            console.error("[orchestrator] session checkpoint failed", error);
+          }
+        }
         out.write({ type: "done", data: workflowFinalState });
         out.end();
         return;
       }
+      const naturalGraphSnapshot = await readLatestGraphSnapshot();
+      const naturalFinalState = naturalGraphSnapshot?.state ?? currentState;
+      if (pendingRequestWrites.length > 0) {
+        await Promise.all(pendingRequestWrites);
+      }
+      if (pendingRecordToken && naturalGraphSnapshot?.checkpointId) {
+        if (pendingStore) {
+          await pendingStore.update(pendingRecordToken, {
+            state: naturalFinalState,
+            graphCheckpointId: naturalGraphSnapshot.checkpointId
+          });
+        }
+        const pendingRequest = activePendingRequests.get(pendingRecordToken);
+        if (pendingRequest) {
+          activePendingRequests.set(pendingRecordToken, {
+            ...pendingRequest,
+            state: naturalFinalState,
+            graphCheckpointId: naturalGraphSnapshot.checkpointId
+          });
+        }
+      }
+      const resolvedSessionId = config?.session?.id || sessionId || "";
+      if (resolvedSessionId && frameworkAdapter?.sessionCheckpoints) {
+        try {
+          const checkpoint = await frameworkAdapter.sessionCheckpoints.append({
+            sessionId: resolvedSessionId,
+            runId,
+            ...naturalGraphSnapshot?.checkpointId ? { graphCheckpointId: naturalGraphSnapshot.checkpointId } : {},
+            workflow: String(naturalFinalState.currentWorkflow),
+            state: naturalFinalState,
+            nodes: Array.from(touchedNodes),
+            structuredStreamIds: Array.from(structuredStreamIds),
+            pendingRequests: Array.from(activePendingRequests.values())
+          });
+          out.write({
+            type: "checkpoint",
+            id: checkpoint.id,
+            sessionId: checkpoint.sessionId,
+            turnIndex: checkpoint.turnIndex,
+            ...checkpoint.label ? { label: checkpoint.label } : {}
+          });
+          emitTelemetryEvent({
+            config,
+            type: "session.checkpointed",
+            payload: {
+              checkpointId: checkpoint.id,
+              turnIndex: checkpoint.turnIndex,
+              ...checkpoint.parentCheckpointId ? { parentCheckpointId: checkpoint.parentCheckpointId } : {},
+              nodes: checkpoint.nodes
+            }
+          });
+        } catch (error) {
+          console.error("[orchestrator] session checkpoint failed", error);
+        }
+      }
       runTraceSpan.setAttributes?.({
-        "kortyx.run.final_workflow": String(currentState.currentWorkflow)
+        "kortyx.run.final_workflow": String(naturalFinalState.currentWorkflow)
       });
       runTraceSpan.end?.(runTraceEndArgs());
-      out.write({ type: "done" });
+      out.write({ type: "done", data: naturalFinalState });
       out.end();
       return;
     }
@@ -671,6 +1252,7 @@ async function orchestrateGraphStream({
   }) : runLoop(fallbackRunSpan ?? {});
   runPromise.catch((err) => {
     fallbackRunSpan?.fail?.(err);
+    emitResumeFailure(err);
     console.error("[error:orchestrateGraphStream]", err);
     out.write({
       type: "error",
@@ -683,11 +1265,16 @@ async function orchestrateGraphStream({
 }
 
 // src/interrupt/resume-handler.ts
-var isRecord2 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var isRecord4 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var responseFromSelection = (selected) => {
+  if (selected.length === 0) return void 0;
+  if (selected.length === 1) return selected[0];
+  return JSON.stringify(selected);
+};
 function parseResumeMeta(msg) {
   if (!msg || !msg.metadata) return null;
   const raw = msg.metadata.resume;
-  if (!isRecord2(raw)) return null;
+  if (!isRecord4(raw)) return null;
   const token = typeof raw.token === "string" ? raw.token : "";
   const requestId = typeof raw.requestId === "string" ? raw.requestId : "";
   const cancel = raw.cancel === true;
@@ -695,10 +1282,10 @@ function parseResumeMeta(msg) {
   const rawSelected = raw.selected;
   if (typeof rawSelected === "string") selected = [rawSelected];
   else if (Array.isArray(rawSelected)) selected = rawSelected.map(String);
-  else if (isRecord2(raw.choice) && typeof raw.choice.id === "string")
+  else if (isRecord4(raw.choice) && typeof raw.choice.id === "string")
     selected = [raw.choice.id];
   else if (Array.isArray(raw.choices))
-    selected = raw.choices.map((c) => isRecord2(c) ? c.id : void 0).filter((id) => typeof id === "string");
+    selected = raw.choices.map((c) => isRecord4(c) ? c.id : void 0).filter((id) => typeof id === "string");
   if (!token || !requestId) return null;
   return { token, requestId, selected, cancel };
 }
@@ -707,6 +1294,7 @@ async function tryPrepareResumeStream({
   sessionId,
   config,
   selectWorkflow,
+  knownWorkflowIds,
   defaultWorkflowId,
   applyResumeSelection,
   frameworkAdapter
@@ -724,6 +1312,21 @@ async function tryPrepareResumeStream({
   }
   if (meta.cancel) {
     await store.delete(pending.token);
+    emitTelemetryEvent({
+      config,
+      type: "interrupt.cancelled",
+      correlation: {
+        runId: pending.runId,
+        sessionId,
+        workflowId: pending.workflow,
+        nodeId: pending.node
+      },
+      payload: {
+        interruptId: pending.requestId,
+        reason: "cancelled_by_client"
+      },
+      flush: true
+    });
     return null;
   }
   console.log(
@@ -732,10 +1335,10 @@ async function tryPrepareResumeStream({
     )} sessionId=${sessionId}`
   );
   const resumeData = applyResumeSelection ? applyResumeSelection({ pending, selected: meta.selected }) : meta.selected?.length ? { coordinates: String(meta.selected[0]) } : {};
-  const resumeDataPatch = isRecord2(resumeData) ? resumeData : {};
-  const pendingMeta = isRecord2(pending.schema?.meta) ? pending.schema.meta : {};
-  const resumeStatePatch = isRecord2(pendingMeta.__kortyxResumeStatePatch) ? pendingMeta.__kortyxResumeStatePatch : void 0;
-  const pendingData = isRecord2(pending.state?.data) ? pending.state?.data : {};
+  const resumeDataPatch = isRecord4(resumeData) ? resumeData : {};
+  const pendingMeta = isRecord4(pending.schema?.meta) ? pending.schema.meta : {};
+  const resumeStatePatch = isRecord4(pendingMeta.__kortyxResumeStatePatch) ? pendingMeta.__kortyxResumeStatePatch : void 0;
+  const pendingData = isRecord4(pending.state?.data) ? pending.state?.data : {};
   const workflowId = typeof pending.workflow === "string" && pending.workflow.trim() ? pending.workflow : typeof defaultWorkflowId === "string" && defaultWorkflowId.trim() ? defaultWorkflowId : "job-search";
   const resumedState = {
     // For static breakpoints, resume with null input (set in orchestrator),
@@ -753,6 +1356,14 @@ async function tryPrepareResumeStream({
     }
   };
   const wf = await selectWorkflow(resumedState.currentWorkflow);
+  const telemetryConfig = prepareWorkflowTelemetry({
+    config,
+    workflow: wf,
+    runId: pending.runId,
+    sessionId,
+    knownWorkflowIds
+  });
+  resumedState.config = telemetryConfig;
   const resumeUpdate = {};
   if (Object.keys(resumeDataPatch).length > 0) {
     resumeUpdate.data = {
@@ -765,25 +1376,54 @@ async function tryPrepareResumeStream({
   }
   const hasResumeUpdate = Object.keys(resumeUpdate).length > 0;
   const resumeValue = meta.selected?.length && pending.schema.kind === "multi-choice" ? meta.selected.map((x) => String(x)) : meta.selected?.length ? String(meta.selected[0]) : void 0;
+  const resumeCheckpointId = typeof pending.graphCheckpointId === "string" && pending.graphCheckpointId.length > 0 ? pending.graphCheckpointId : void 0;
   const resumedGraph = await (0, import_runtime2.createExecutionGraph)(wf, {
-    ...config,
+    ...telemetryConfig,
     resume: true,
     ...resumeValue !== void 0 ? { resumeValue } : {},
+    ...resumeCheckpointId ? { resumeCheckpointId } : {},
     ...hasResumeUpdate ? { resumeUpdate } : {}
   });
   await store.delete(pending.token);
+  const response = responseFromSelection(meta.selected);
+  const telemetry = isRecord4(telemetryConfig.telemetry) ? telemetryConfig.telemetry : {};
+  const responseCaptured = Boolean(
+    response && shouldCaptureTelemetryContent(telemetry.captureContent, "input")
+  );
+  emitTelemetryEvent({
+    config: telemetryConfig,
+    type: "interrupt.resolved",
+    correlation: {
+      runId: pending.runId,
+      sessionId,
+      workflowId,
+      nodeId: pending.node
+    },
+    payload: {
+      interruptId: pending.requestId,
+      resolvedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      resumeOutcome: "resumed",
+      responseCaptured,
+      ...responseCaptured && response ? { response } : {}
+    },
+    flush: true
+  });
   const args = {
     sessionId,
     runId: pending.runId,
     graph: resumedGraph,
     state: resumedState,
     config: {
-      ...config,
+      ...telemetryConfig,
       resume: true,
+      telemetryInterruptId: pending.requestId,
+      telemetryInterruptNodeId: pending.node,
       ...resumeValue !== void 0 ? { resumeValue } : {},
+      ...resumeCheckpointId ? { resumeCheckpointId } : {},
       ...hasResumeUpdate ? { resumeUpdate } : {}
     },
     selectWorkflow,
+    knownWorkflowIds,
     frameworkAdapter
   };
   const stream = await orchestrateGraphStream(args);
@@ -811,12 +1451,13 @@ async function streamChat({
   loadRuntimeConfig,
   selectWorkflow,
   workflowRegistry,
+  knownWorkflowIds,
   frameworkAdapter,
   getProvider,
   applyResumeSelection
 }) {
   const config = await loadRuntimeConfig(options);
-  const runtimeConfig = {
+  let runtimeConfig = {
     ...config,
     getProvider,
     ...frameworkAdapter ? { checkpointer: frameworkAdapter.checkpointer } : {}
@@ -859,22 +1500,60 @@ async function streamChat({
     sessionId: resolvedSessionId,
     config: runtimeConfig,
     selectWorkflow: workflowSelector,
+    knownWorkflowIds,
     ...frameworkAdapter ? { frameworkAdapter } : {},
     ...defaultWorkflowId ? { defaultWorkflowId } : {},
     ...applyResumeSelection ? { applyResumeSelection } : {}
   });
   if (resumeStream) return resumeStream;
   const runId = (0, import_runtime3.makeRequestId)("run");
-  const currentWorkflow = baseState.currentWorkflow;
+  let headCheckpoint = !isResumeRequest && frameworkAdapter?.sessionCheckpoints ? await frameworkAdapter.sessionCheckpoints.getHead(resolvedSessionId) : null;
+  if (!isResumeRequest && !headCheckpoint && frameworkAdapter?.sessionCheckpoints) {
+    headCheckpoint = await frameworkAdapter.sessionCheckpoints.append({
+      sessionId: resolvedSessionId,
+      runId,
+      workflow: String(baseState.currentWorkflow),
+      state: {
+        ...baseState,
+        input: "",
+        awaitingHumanInput: false
+      },
+      nodes: [],
+      structuredStreamIds: [],
+      pendingRequests: [],
+      label: "session start"
+    });
+  }
+  const currentWorkflow = requestedWorkflowId ? baseState.currentWorkflow : headCheckpoint?.state.currentWorkflow ?? baseState.currentWorkflow;
   const selectedWorkflow = await workflowSelector(currentWorkflow);
+  runtimeConfig = prepareWorkflowTelemetry({
+    config: runtimeConfig,
+    workflow: selectedWorkflow,
+    runId,
+    sessionId: resolvedSessionId,
+    knownWorkflowIds
+  });
   const graph = await (0, import_runtime3.createExecutionGraph)(selectedWorkflow, runtimeConfig);
+  const initialState = headCheckpoint ? {
+    ...headCheckpoint.state,
+    input,
+    config: runtimeConfig,
+    currentWorkflow,
+    awaitingHumanInput: false,
+    runtime: {
+      ...headCheckpoint.state.runtime ?? {},
+      ...runtime.requestedWorkflow ? { requestedWorkflow: runtime.requestedWorkflow } : {},
+      ...runtime.priorMessages ? { priorMessages: runtime.priorMessages } : {}
+    }
+  } : { ...baseState, config: runtimeConfig, currentWorkflow };
   const orchestratedStream = await orchestrateGraphStream({
     sessionId: resolvedSessionId,
     runId,
     graph,
-    state: { ...baseState, currentWorkflow },
+    state: initialState,
     config: runtimeConfig,
     selectWorkflow: workflowSelector,
+    knownWorkflowIds,
     ...frameworkAdapter ? { frameworkAdapter } : {}
   });
   return orchestratedStream;
@@ -928,6 +1607,32 @@ var parseAgentProcessOptions = (value) => {
   if (value === void 0) return void 0;
   return parseSchema(agentProcessOptionsSchema, value);
 };
+var hydratePendingGraphCheckpoint = async (frameworkAdapter, request) => {
+  if (request.graphCheckpointId) return request;
+  const checkpointer = frameworkAdapter.checkpointer;
+  const graphCheckpointId = await checkpointer?.getLatestCheckpointId?.(
+    request.runId,
+    request.workflow
+  ) ?? await checkpointer?.getLatestCheckpointId?.(request.runId, "");
+  return graphCheckpointId ? { ...request, graphCheckpointId } : request;
+};
+var clearPendingGraphWrites = async (frameworkAdapter, request) => {
+  if (!request.graphCheckpointId) return;
+  const checkpointer = frameworkAdapter.checkpointer;
+  if (!checkpointer?.deleteCheckpointWrites) return;
+  await Promise.all([
+    checkpointer.deleteCheckpointWrites(
+      request.runId,
+      request.workflow,
+      request.graphCheckpointId
+    ),
+    checkpointer.deleteCheckpointWrites(
+      request.runId,
+      "",
+      request.graphCheckpointId
+    )
+  ]);
+};
 function createAgent(args) {
   const parsedArgs = parseCreateAgentArgs(args);
   const {
@@ -962,6 +1667,22 @@ function createAgent(args) {
       fallbackId: resolvedDefaultWorkflowId ?? "general-chat"
     });
   })();
+  const registeredWorkflowsPromise = registryPromise.then(
+    (registry) => registry?.list?.()
+  );
+  const projectTopology = async (options) => {
+    const registeredWorkflows = await registeredWorkflowsPromise;
+    if (!registeredWorkflows?.length) return [];
+    const knownWorkflowIds = registeredWorkflows.map((workflow) => workflow.id);
+    return registeredWorkflows.map(
+      (workflow) => projectWorkflowTopology({
+        workflow,
+        environment: options.environment,
+        service: options.service,
+        knownWorkflowIds
+      })
+    );
+  };
   const streamChat2 = async (messages, options) => {
     const parsedOptions = parseAgentProcessOptions(options);
     const registry = await registryPromise;
@@ -970,11 +1691,18 @@ function createAgent(args) {
         "createAgent requires workflows, workflowsDir, or workflowRegistry."
       );
     }
+    const registeredWorkflows = await registeredWorkflowsPromise.catch(
+      () => void 0
+    );
+    const knownWorkflowIds = registeredWorkflows?.map(
+      (workflow) => workflow.id
+    );
     return streamChat({
       ...resolvedDefaultWorkflowId ? { defaultWorkflowId: resolvedDefaultWorkflowId } : {},
       messages,
       options: parsedOptions,
       workflowRegistry: registry,
+      ...knownWorkflowIds ? { knownWorkflowIds } : {},
       frameworkAdapter: resolvedFrameworkAdapter,
       getProvider: resolvedGetProvider,
       loadRuntimeConfig: (runtimeOptions) => ({
@@ -988,17 +1716,107 @@ function createAgent(args) {
       })
     });
   };
-  return { streamChat: streamChat2 };
+  const listCheckpoints = (sessionId) => resolvedFrameworkAdapter.sessionCheckpoints.list(sessionId);
+  const getCheckpoint = (id) => resolvedFrameworkAdapter.sessionCheckpoints.get(id);
+  const rollbackTo = async (id) => {
+    const target = await resolvedFrameworkAdapter.sessionCheckpoints.get(id);
+    const result = await resolvedFrameworkAdapter.sessionCheckpoints.rollbackTo(id);
+    const activePendingRequests = await Promise.all(
+      result.activePendingRequests.map(
+        (request) => hydratePendingGraphCheckpoint(resolvedFrameworkAdapter, request)
+      )
+    );
+    await Promise.all(
+      activePendingRequests.map(
+        (request) => clearPendingGraphWrites(resolvedFrameworkAdapter, request)
+      )
+    );
+    await Promise.all([
+      ...result.invalidatedInterruptTokens.map(
+        (token) => resolvedFrameworkAdapter.pendingRequests.delete(token)
+      ),
+      ...activePendingRequests.map(
+        (request) => resolvedFrameworkAdapter.pendingRequests.save(request)
+      )
+    ]);
+    if (target) {
+      emitTelemetryEvent({
+        config: { ...telemetry ? { telemetry } : {} },
+        type: "session.rolled_back",
+        correlation: {
+          runId: target.runId,
+          sessionId: target.sessionId,
+          workflowId: target.workflow
+        },
+        payload: {
+          checkpointId: target.id,
+          invalidatedInterruptIds: result.invalidatedInterruptTokens
+        }
+      });
+    }
+    return { ...result, activePendingRequests };
+  };
+  const fork = async (id, options) => {
+    const result = await resolvedFrameworkAdapter.sessionCheckpoints.fork(
+      id,
+      options
+    );
+    const activePendingRequests = await Promise.all(
+      result.checkpoint.activePendingRequests.map(
+        (request) => hydratePendingGraphCheckpoint(resolvedFrameworkAdapter, request)
+      )
+    );
+    await Promise.all(
+      activePendingRequests.map(
+        (request) => clearPendingGraphWrites(resolvedFrameworkAdapter, request)
+      )
+    );
+    await Promise.all(
+      activePendingRequests.map(
+        (request) => resolvedFrameworkAdapter.pendingRequests.save(request)
+      )
+    );
+    emitTelemetryEvent({
+      config: { ...telemetry ? { telemetry } : {} },
+      type: "session.forked",
+      correlation: {
+        runId: result.checkpoint.runId,
+        sessionId: result.checkpoint.sessionId,
+        workflowId: result.checkpoint.workflow
+      },
+      payload: {
+        newSessionId: result.sessionId,
+        parentSessionId: result.parentSessionId,
+        forkedFromCheckpointId: result.forkedFrom
+      }
+    });
+    return {
+      ...result,
+      checkpoint: { ...result.checkpoint, activePendingRequests }
+    };
+  };
+  return {
+    projectTopology,
+    streamChat: streamChat2,
+    listCheckpoints,
+    getCheckpoint,
+    rollbackTo,
+    fork
+  };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createAgent,
   createChatRouteHandler,
+  createCheckpointRouteHandler,
   extractLatestUserMessage,
   handleChatRequestBody,
+  handleCheckpointRequestBody,
   orchestrateGraphStream,
   parseChatRequestBody,
+  parseCheckpointRequestBody,
   parseResumeMeta,
+  projectWorkflowTopology,
   streamChat,
   streamChatFromRoute,
   transformGraphStreamForUI,