@cuylabs/agent-runtime-dapr 4.8.1 → 4.10.0

package/README.md

@@ -118,6 +118,20 @@ tool still executes through `agent.getHost()`.
 
 For the full explanation, see [Tool Hosts In Durable Workflows](docs/tool-hosts.md).
 
+## Durable Context Compaction
+
+Durable turns compact at the same model-step boundary as direct `Agent.chat()`,
+but they do it through workflow state instead of the in-process chat loop.
+Before a `model-step` activity runs, the workflow can call a
+`context-compaction` activity. That activity applies the agent's normal
+compaction policy to the serialized workflow messages, persists the compaction
+entry to session storage, returns the compacted message snapshots, and the
+workflow checkpoints `context-compaction-finish` before continuing.
+
+This keeps the durable path crash-safe without importing direct-loop internals:
+direct execution uses `ChatModelStepSnapshot`; Dapr durable execution uses
+`AgentWorkflowTurnState.messages` and `AgentWorkflowModelStepPlan`.
+
 ## Quick Start
 
 ### Step 1: Define your agent

package/dist/{chunk-2TBZCBXE.js → chunk-7VYLWJTB.js}

@@ -191,12 +191,38 @@ var DaprWorkflowClient = class {
   }
 };
 
+// src/workflow/activity-names.ts
+var DEFAULT_AGENT_TURN_WORKFLOW_NAME = "agent-turn";
+function createAgentTurnActivityNames(workflowName, overrides = {}, options = {}) {
+  return {
+    ...options.includeSteerDrain || overrides.steerDrain ? {
+      steerDrain: overrides.steerDrain ?? `${workflowName}:steer-drain`
+    } : {},
+    ...options.includeContextCompaction || overrides.contextCompaction ? {
+      contextCompaction: overrides.contextCompaction ?? `${workflowName}:context-compaction`
+    } : {},
+    modelStep: overrides.modelStep ?? `${workflowName}:model-step`,
+    ...options.includeHumanInputCheck || overrides.humanInputCheck ? {
+      humanInputCheck: overrides.humanInputCheck ?? `${workflowName}:human-input-check`
+    } : {},
+    ...options.includeApprovalCheck || overrides.approvalCheck ? {
+      approvalCheck: overrides.approvalCheck ?? `${workflowName}:approval-check`
+    } : {},
+    toolCall: overrides.toolCall ?? `${workflowName}:tool-call`,
+    stepCommit: overrides.stepCommit ?? `${workflowName}:step-commit`,
+    outputCommit: overrides.outputCommit ?? `${workflowName}:output-commit`
+  };
+}
+
 // src/workflow/runtime-activities.ts
 import {
   advanceAgentTurnState,
+  assembleModelContext,
   convertAgentMessagesToModelMessages,
   createAgentTurnEngine,
   createAgentTurnStepCommitBatch,
+  ContextWindowManager,
+  DEFAULT_CONTEXT_LIMITS,
   executeAgentToolCall,
   normalizeToolReplayPolicy,
   prepareModelStep,
@@ -224,14 +250,29 @@ function resolveOption(value) {
 async function* emptyCommitApplier() {
   yield* [];
 }
+function createRuntimeContextWindow(runtime) {
+  if (!runtime.contextWindow) return void 0;
+  return new ContextWindowManager({
+    limits: {
+      contextWindow: runtime.contextWindow,
+      reserveTokens: runtime.reserveTokens ?? DEFAULT_CONTEXT_LIMITS.reserveTokens
+    }
+  });
+}
 function createDaprAgentTurnSteerDrainActivity(options) {
   return {
     name: "steer-drain",
     handler: async (_context, input) => options.drain(input)
   };
 }
-async function withObserverContext(bridge, sessionId, fn) {
-  const parentCtx = bridge?.getOtelContext(sessionId);
+function createDaprAgentTurnContextCompactionActivity(options) {
+  return {
+    name: "context-compaction",
+    handler: async (_context, input) => await options.compact(input)
+  };
+}
+async function withObserverContext(bridge, sessionId, turnId, fn) {
+  const parentCtx = bridge?.getOtelContext(sessionId, turnId);
   if (!parentCtx) return fn();
   try {
     const otelApi = await import("@opentelemetry/api");
@@ -257,7 +298,8 @@ function createDaprAgentTurnModelStepActivity(options) {
         if (middleware?.hasMiddleware) {
           await middleware.runChatStart(
             plan.sessionId,
-            `[workflow model-step ${plan.step}]`
+            `[workflow model-step ${plan.step}]`,
+            { sessionId: plan.sessionId, turnId: plan.turnId }
           );
         }
         let stepResult;
@@ -268,6 +310,22 @@ function createDaprAgentTurnModelStepActivity(options) {
             plan.systemPrompts
           ) : plan.systemPrompts;
           const restoredMessages = restoreAgentWorkflowMessages(plan.messages);
+          const resolvedMcpTools = typeof options.mcpTools === "function" ? await options.mcpTools() : options.mcpTools;
+          const abort = options.createAbortSignal?.() ?? new AbortController().signal;
+          const contextWindow = createRuntimeContextWindow(runtime);
+          const assembledContext = await assembleModelContext({
+            sessionId: plan.sessionId,
+            turnId: plan.turnId,
+            step: plan.step,
+            cwd: runtime.cwd,
+            messages: restoredMessages,
+            toolNames: Object.keys(tools),
+            mcpToolNames: Object.keys(resolvedMcpTools ?? {}),
+            abort,
+            ...middleware ? { contextFragmentCollector: middleware } : {},
+            ...contextWindow ? { window: contextWindow } : {},
+            ...plan.contextCompaction ? { compaction: plan.contextCompaction } : {}
+          });
           const turnEngine = createAgentTurnEngine({
             sessionId: plan.sessionId,
             startedAt: now(),
@@ -275,13 +333,15 @@ function createDaprAgentTurnModelStepActivity(options) {
           });
           const preparedStep = prepareModelStep({
             sessionId: plan.sessionId,
+            turnId: plan.turnId,
             step: plan.step,
             systemPrompts,
-            messages: restoredMessages,
+            messages: assembledContext.messages,
+            contextReport: assembledContext.report,
             toModelMessages: options.toModelMessages ?? convertAgentMessagesToModelMessages,
-            abort: options.createAbortSignal?.() ?? new AbortController().signal,
+            abort,
             tools,
-            mcpTools: typeof options.mcpTools === "function" ? await options.mcpTools() : options.mcpTools,
+            mcpTools: resolvedMcpTools,
             config: runtime,
             ...host ? { host } : {},
             ...options.turnTracker ? { turnTracker: options.turnTracker } : {},
@@ -302,6 +362,7 @@ function createDaprAgentTurnModelStepActivity(options) {
                 text: item.value.text,
                 ...item.value.usage ? { usage: item.value.usage } : {},
                 ...item.value.finishReason ? { finishReason: item.value.finishReason } : {},
+                contextReport: assembledContext.report,
                 turnState: turnEngine.getState(),
                 ...stepCommit ? { stepCommit } : {}
               };
@@ -315,11 +376,15 @@ function createDaprAgentTurnModelStepActivity(options) {
           stepError = normalizeError(err);
         }
         if (middleware?.hasMiddleware) {
-          await middleware.runChatEnd(plan.sessionId, {
-            usage: stepResult?.usage,
-            error: stepError,
-            output: stepResult?.text
-          });
+          await middleware.runChatEnd(
+            plan.sessionId,
+            {
+              usage: stepResult?.usage,
+              error: stepError,
+              output: stepResult?.text
+            },
+            { sessionId: plan.sessionId, turnId: plan.turnId }
+          );
         }
         if (stepError) throw stepError;
         return stepResult;
@@ -327,6 +392,7 @@ function createDaprAgentTurnModelStepActivity(options) {
       return withObserverContext(
         options.observerBridge,
         plan.sessionId,
+        plan.turnId,
         runActivity
       );
     }
@@ -442,6 +508,7 @@ function createDaprAgentTurnToolCallActivity(options) {
       return withObserverContext(
         options.observerBridge,
         plan.sessionId,
+        void 0,
         runActivity
       );
     }
@@ -503,37 +570,18 @@ function createDaprAgentTurnOutputCommitActivity(options) {
 
 // src/workflow/runtime.ts
 import {
-  advanceAgentTurnState as advanceAgentTurnState2,
   applyWorkflowInterventions,
   applyAgentWorkflowCommitResult,
+  applyAgentWorkflowContextCompactionResult,
   applyAgentWorkflowModelStepResult,
   applyAgentWorkflowToolCallResult,
-  createApprovalCorrection,
   failAgentWorkflowTurnState,
-  formatApprovalDeniedReason,
-  planNextAgentWorkflowOperation,
-  recordAgentWorkflowReplayDecision
+  formatApprovalDeniedReason as formatApprovalDeniedReason2,
+  planNextAgentWorkflowOperation
 } from "@cuylabs/agent-core";
-var MAX_CONTROL_EVENTS_PER_BOUNDARY = 32;
-var DEFAULT_WORKFLOW_NAME = "agent-turn";
-function defaultActivityNames(workflowName, overrides = {}, options = {}) {
-  return {
-    ...options.includeSteerDrain || overrides.steerDrain ? {
-      steerDrain: overrides.steerDrain ?? `${workflowName}:steer-drain`
-    } : {},
-    modelStep: overrides.modelStep ?? `${workflowName}:model-step`,
-    ...options.includeHumanInputCheck || overrides.humanInputCheck ? {
-      humanInputCheck: overrides.humanInputCheck ?? `${workflowName}:human-input-check`
-    } : {},
-    ...options.includeApprovalCheck || overrides.approvalCheck ? {
-      approvalCheck: overrides.approvalCheck ?? `${workflowName}:approval-check`
-    } : {},
-    toolCall: overrides.toolCall ?? `${workflowName}:tool-call`,
-    stepCommit: overrides.stepCommit ?? `${workflowName}:step-commit`,
-    outputCommit: overrides.outputCommit ?? `${workflowName}:output-commit`
-  };
-}
-function normalizeError2(error) {
+
+// src/workflow/runtime-helpers.ts
+function normalizeWorkflowError(error) {
   if (error instanceof Error) return error;
   if (typeof error === "string") return new Error(error);
   if (error && typeof error === "object") {
@@ -556,12 +604,45 @@ function renameActivity(activity, name) {
 function summarizeWorkflowState(state) {
   return JSON.stringify({
     sessionId: state.sessionId,
+    turnId: state.turnId,
     phase: state.phase,
     step: state.step,
     finalResponse: state.finalResponse,
     error: state.error
   });
 }
+
+// src/workflow/steering.ts
+var MAX_CONTROL_EVENTS_PER_BOUNDARY = 32;
+function normalizeSteerSnapshots(payload) {
+  if (!Array.isArray(payload)) {
+    return [];
+  }
+  return payload.flatMap((candidate) => {
+    if (!candidate || typeof candidate !== "object") {
+      return [];
+    }
+    const steer = candidate;
+    if (typeof steer.id !== "string" || !steer.id.trim() || typeof steer.message !== "string" || !steer.message.trim() || typeof steer.createdAt !== "string" || !steer.createdAt.trim()) {
+      return [];
+    }
+    return [
+      {
+        id: steer.id.trim(),
+        message: steer.message.trim(),
+        createdAt: steer.createdAt.trim()
+      }
+    ];
+  });
+}
+
+// src/workflow/tool-gates.ts
+import {
+  advanceAgentTurnState as advanceAgentTurnState2,
+  createApprovalCorrection,
+  formatApprovalDeniedReason,
+  recordAgentWorkflowReplayDecision
+} from "@cuylabs/agent-core";
 function ensureReplayDecision(state, plan, now) {
   if (plan.replayDecision) {
     return { state, decision: plan.replayDecision };
@@ -689,27 +770,6 @@ function createHumanInputToolCallResult(plan, response, updatedAt) {
     )
   };
 }
-function normalizeSteerSnapshots(payload) {
-  if (!Array.isArray(payload)) {
-    return [];
-  }
-  return payload.flatMap((candidate) => {
-    if (!candidate || typeof candidate !== "object") {
-      return [];
-    }
-    const steer = candidate;
-    if (typeof steer.id !== "string" || !steer.id.trim() || typeof steer.message !== "string" || !steer.message.trim() || typeof steer.createdAt !== "string" || !steer.createdAt.trim()) {
-      return [];
-    }
-    return [
-      {
-        id: steer.id.trim(),
-        message: steer.message.trim(),
-        createdAt: steer.createdAt.trim()
-      }
-    ];
-  });
-}
 var EXTERNAL_EVENT_TIMEOUT = /* @__PURE__ */ Symbol("EXTERNAL_EVENT_TIMEOUT");
 function* waitForExternalEventWithTimeout(context, eventName, timeoutMs) {
   if (!context.waitForExternalEvent) {
@@ -730,13 +790,16 @@ function* waitForExternalEventWithTimeout(context, eventName, timeoutMs) {
   }
   return yield eventTask;
 }
+
+// src/workflow/runtime.ts
 function createDaprAgentTurnWorkflowDefinition(options) {
-  const workflowName = options.workflowName ?? DEFAULT_WORKFLOW_NAME;
-  const activityNames = defaultActivityNames(
+  const workflowName = options.workflowName ?? DEFAULT_AGENT_TURN_WORKFLOW_NAME;
+  const activityNames = createAgentTurnActivityNames(
     workflowName,
     options.activityNames,
     {
       includeSteerDrain: Boolean(options.steerDrain),
+      includeContextCompaction: Boolean(options.contextCompaction),
       includeHumanInputCheck: Boolean(options.humanInputCheck),
       includeApprovalCheck: Boolean(options.approvalCheck)
     }
@@ -779,6 +842,44 @@ function createDaprAgentTurnWorkflowDefinition(options) {
             }
           }
         }
+        if (state.phase === "model-step" && activityNames.contextCompaction && options.contextCompaction) {
+          const compaction = yield context.callActivity(
+            activityNames.contextCompaction,
+            {
+              workflowInstanceId: context.getWorkflowInstanceId?.() ?? "",
+              sessionId: state.sessionId,
+              step: state.step,
+              messages: state.messages.map(
+                (message) => structuredClone(message)
+              )
+            }
+          );
+          state = applyAgentWorkflowContextCompactionResult(
+            state,
+            compaction,
+            now()
+          );
+          if (compaction.compacted && !context.isReplaying?.()) {
+            await options.onEvent?.(state.sessionId, {
+              type: "context-compaction",
+              phase: "pre-step",
+              inputTokens: compaction.inputTokens,
+              limit: compaction.limit,
+              decision: compaction.decision,
+              effectiveness: compaction.effectiveness,
+              removedCount: compaction.removedCount,
+              tokensRemoved: compaction.tokensRemoved,
+              summarized: compaction.summarized,
+              ...compaction.cutReason ? { cutReason: compaction.cutReason } : {}
+            });
+            await options.onEvent?.(state.sessionId, {
+              type: "context-overflow",
+              inputTokens: compaction.inputTokens,
+              limit: compaction.limit
+            });
+            await bridge?.notifyCheckpoint("context-compaction-finish", state);
+          }
+        }
         const plan = planNextAgentWorkflowOperation(state);
         if (!plan) {
           if (!context.isReplaying?.()) {
@@ -947,7 +1048,7 @@ function createDaprAgentTurnWorkflowDefinition(options) {
                     state,
                     createDeniedToolCallResult(
                       plan,
-                      formatApprovalDeniedReason(
+                      formatApprovalDeniedReason2(
                         plan.toolCall.toolName,
                         decision.feedback
                       ),
@@ -1133,7 +1234,7 @@ function createDaprAgentTurnWorkflowDefinition(options) {
                         state,
                         createDeniedToolCallResult(
                           singlePlan,
-                          formatApprovalDeniedReason(
+                          formatApprovalDeniedReason2(
                             singlePlan.toolCall.toolName,
                             decision.feedback
                           ),
@@ -1234,7 +1335,7 @@ function createDaprAgentTurnWorkflowDefinition(options) {
         }
       }
     } catch (error) {
-      const normalized = normalizeError2(error);
+      const normalized = normalizeWorkflowError(error);
       state = failAgentWorkflowTurnState(state, normalized, now());
       context.setCustomStatus?.(summarizeWorkflowState(state));
       if (!context.isReplaying?.()) {
@@ -1252,6 +1353,9 @@ function createDaprAgentTurnWorkflowDefinition(options) {
 function createDaprAgentTurnWorkflowKit(options) {
   const getBridge = () => options.observerBridge;
   const steerDrainActivity = options.steerDrainActivity ? createDaprAgentTurnSteerDrainActivity(options.steerDrainActivity) : void 0;
+  const contextCompactionActivity = options.contextCompactionActivity ? createDaprAgentTurnContextCompactionActivity(
+    options.contextCompactionActivity
+  ) : void 0;
   const humanInputCheckActivity = options.humanInputCheckActivity ? createDaprAgentTurnHumanInputCheckActivity(
     options.humanInputCheckActivity
   ) : void 0;
@@ -1286,6 +1390,9 @@ function createDaprAgentTurnWorkflowKit(options) {
     ...steerDrainActivity ? {
       steerDrain: (input) => steerDrainActivity.handler(void 0, input)
     } : {},
+    ...contextCompactionActivity ? {
+      contextCompaction: (input) => contextCompactionActivity.handler(void 0, input)
+    } : {},
     modelStep: (input) => modelStepActivity.handler(void 0, input),
     ...humanInputCheckActivity ? {
       humanInputCheck: (input) => humanInputCheckActivity.handler(void 0, input)
@@ -1307,6 +1414,12 @@ function createDaprAgentTurnWorkflowKit(options) {
           registration.activityNames.steerDrain
         )
       } : {},
+      ...contextCompactionActivity && registration.activityNames.contextCompaction ? {
+        contextCompaction: renameActivity(
+          contextCompactionActivity,
+          registration.activityNames.contextCompaction
+        )
+      } : {},
       modelStep: renameActivity(
         modelStepActivity,
         registration.activityNames.modelStep
@@ -1343,6 +1456,8 @@ export {
   isTerminalDaprWorkflowStatus,
   hasStartedDaprWorkflow,
   DaprWorkflowClient,
+  DEFAULT_AGENT_TURN_WORKFLOW_NAME,
+  createAgentTurnActivityNames,
   createDaprAgentTurnSteerDrainActivity,
   createDaprAgentTurnModelStepActivity,
   createDaprAgentTurnToolCallActivity,