fix(agent): continue truncated model turns (#185)

## Summary

- Treat provider `length` finish reasons as nonterminal model turns.
- Checkpoint the partial response and continue durably with an internal
instruction to split interrupted operations into smaller complete tool
calls.
- Validate the SDK finish-reason contract at the agent boundary and
accept only `stop` as tool-free semantic completion.
- Fail blocked, provider-error, and invalid terminal reasons explicitly
instead of publishing incomplete work as successful.

## Root cause

The production Pomodoro retry recovered its Daytona runtime correctly,
but Claude reached its per-response output limit while forming the next
operation. The Workflow used only the absence of parsed tool calls as
its completion condition, so it finalized that truncated turn and
exposed the sandbox readiness page.

## Architecture

The Mastra adapter validates the six AI SDK finish reasons. Cloudflare
Workflow owns the policy: tool calls execute durably; `length` appends a
non-visible continuation message and starts another checkpointed model
turn; only `stop` completes a tool-free run. This keeps semantic
completion in charge without adding a step, token, duration, or cost
ceiling.

## Decisions

| Decision | Choice | Reason |
|---|---|---|
| Handle truncation in Workflow | Durable continuation | It preserves
replay safety and applies to every provider and run type. |
| Preserve partial response history | Append an internal user
continuation message | The next turn sees the exact work already
attempted and avoids repeating completed actions. |
| Keep provider output settings unchanged | No fixed output-token
override | A larger fixed cap only postpones truncation and does not
establish correct completion semantics. |
| Reject non-stop terminal reasons | Explicit upstream failure | Content
filtering and provider errors are not successful outcomes. |

## Production evidence

- Run `019fe1b3-af54-7a69-bd1d-0cd940842e41` completed after model turn
5 returned `finishReason: "length"` with no tool call.
- The replacement Daytona sandbox was healthy and mounted the correct
durable volume, isolating this from the sandbox recovery issue fixed in
#183 and #184.

## Verification

- `pnpm lint`
- `pnpm typecheck`
- `pnpm turbo build --force`
- `pnpm deadcode`
- `pnpm architecture:check`
- `pnpm turbo skills:build`
- production flow will be repeated after merge and exact-SHA Cloudflare
deployment

## How to review

1. Review the finish-reason schema in
`packages/agent-core/src/mastra/durable-agent-step.ts`.
2. Review the durable loop policy in
`apps/agent-worker/src/durable-objects/agent-run-workflow.ts`.
3. Confirm the shared schema is enforced by
`agent-run-workflow-runtime.ts` and the README contract matches the
implementation.

Author: iamjr15

apps/agent-worker/README.md

@@ -87,6 +87,10 @@ the Daytona adapter normalizes the provider's structured `503` response to an in
 then the lifecycle verifies the active-run lease and canonical volume mount before replacing the
 stopped container on the same isolated workspace-volume subpath. This preserves user files while
 avoiding an indefinite dependency on one unhealthy runner.
+Provider output-length termination is nonterminal: the Workflow checkpoints the partial model turn,
+adds an internal continuation message, and resumes from that durable state. A tool-free turn completes
+the run only when the model reports an actual stop; content filtering, provider errors, and invalid
+terminal reasons fail explicitly instead of publishing incomplete work as success.
 There is no application step, token, duration, or cost ceiling; semantic completion ends the loop,
 while per-operation timeouts and the platform Workflow limit remain operational safeguards.
 The Worker pins Cloudflare's paid-plan maximum subrequest allowance because external provider,

apps/agent-worker/src/durable-objects/agent-run-workflow-runtime.ts

@@ -1,5 +1,6 @@
 import {
   executeGeneralAgentTool,
+  GeneralAgentFinishReasonSchema,
   type GeneralAgentToolCall,
   generateGeneralAgentStep,
 } from "@cheatcode/agent-core";
@@ -87,7 +88,7 @@ export const WorkflowModelStepResultSchema = z.strictObject({
   input: StartRunInputSchema,
   logicalModelId: LogicalModelIdSchema,
   step: z.strictObject({
-    finishReason: z.string(),
+    finishReason: GeneralAgentFinishReasonSchema,
     responseMessages: z.array(WorkflowJsonValueSchema),
     text: z.string(),
     toolCalls: z.array(WorkflowToolCallSchema),

apps/agent-worker/src/durable-objects/agent-run-workflow.ts

@@ -1,6 +1,7 @@
 import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
 import { NonRetryableError } from "cloudflare:workflows";
 import {
+  APIError,
   createLogger,
   emitErrorEvent,
   emitUserEvent,
@@ -57,6 +58,20 @@ const STATE_STEP = stepConfig("2 minutes", 5);
 const CLEANUP_STEP = stepConfig("5 minutes", 5);
 const FAILURE_STEP = stepConfig("2 minutes", AGENT_RUN_WORKFLOW_FAILURE_RETRY_LIMIT);
 const JsonValueSchema = z.json();
+const MODEL_LENGTH_CONTINUATION_MESSAGE: ModelMessage = {
+  role: "user",
+  content: [
+    {
+      type: "text",
+      text: [
+        "The provider ended your previous turn at its per-response output limit.",
+        "Continue the unfinished work from the current state without repeating completed work.",
+        "If a tool call was interrupted, split the remaining operation into smaller complete tool calls.",
+        "Do not claim completion until the requested outcome has been verified.",
+      ].join(" "),
+    },
+  ],
+};
 
 interface AgentRunWorkflowEnv extends AgentRunEnv, AgentRunWorkflowBindings {
   AGENT_RUN: DurableObjectNamespace<AgentRun>;
@@ -185,6 +200,11 @@ async function runAgentLoop(
       stepIndex,
     );
     if (model.step.toolCalls.length === 0) {
+      if (model.step.finishReason === "length") {
+        state = continueTruncatedModelTurn(state);
+        continue;
+      }
+      requireSemanticCompletion(model.step.finishReason);
       await publishClosingBackstopIfNeeded(env, workflowStep, workflowInstanceId, payload, state);
       return;
     }
@@ -219,6 +239,23 @@ async function runAgentLoop(
   }
 }
 
+function continueTruncatedModelTurn(state: WorkflowAgentState): WorkflowAgentState {
+  return WorkflowAgentStateSchema.parse({
+    ...state,
+    messages: [...state.messages, workflowJsonValue(MODEL_LENGTH_CONTINUATION_MESSAGE)],
+  });
+}
+
+function requireSemanticCompletion(
+  finishReason: WorkflowModelStepResult["step"]["finishReason"],
+): void {
+  if (finishReason === "stop") return;
+  throw new APIError(502, "upstream_llm_failed", "The model stopped before completing the run.", {
+    details: { finishReason },
+    retriable: finishReason !== "content-filter",
+  });
+}
+
 async function executeModelWorkflowStep(input: {
   env: AgentRunWorkflowEnv;
   payload: AgentRunWorkflowPayload;

packages/agent-core/README.md

@@ -7,6 +7,7 @@ Mastra agents, tool registry, and workflow entrypoints.
 - `createCodeRequestContext`
 - `generateGeneralAgentStep` and `executeGeneralAgentTool` for Cloudflare
   Workflow-owned, step-granular agent execution
+- `GeneralAgentFinishReasonSchema`, the validated model-turn completion contract
 - runtime credential and model contracts consumed by `agent-worker`
 
 The tool and agent registries are statically constrained by the lightweight

packages/agent-core/src/index.ts

@@ -11,6 +11,7 @@ export type {
 } from "./mastra/composio-context";
 export {
   executeGeneralAgentTool,
+  GeneralAgentFinishReasonSchema,
   type GeneralAgentToolCall,
   generateGeneralAgentStep,
 } from "./mastra/durable-agent-step";

packages/agent-core/src/mastra/durable-agent-step.ts

@@ -4,14 +4,25 @@ import { z } from "zod";
 import { mastra } from "./index";
 import { cheatcodeTools } from "./tool-defs/tool-set";
 
+export const GeneralAgentFinishReasonSchema = z.enum([
+  "stop",
+  "length",
+  "content-filter",
+  "tool-calls",
+  "error",
+  "other",
+]);
+
+type GeneralAgentFinishReason = z.infer<typeof GeneralAgentFinishReasonSchema>;
+
 export interface GeneralAgentToolCall {
   input: JSONValue;
   toolCallId: string;
   toolName: string;
 }
 
 interface GeneralAgentStepResult {
-  finishReason: string;
+  finishReason: GeneralAgentFinishReason;
   responseMessages: JSONValue[];
   text: string;
   toolCalls: GeneralAgentToolCall[];
@@ -51,7 +62,7 @@ export async function generateGeneralAgentStep(
     runId: options.runId,
   });
   return {
-    finishReason: result.finishReason ?? "unknown",
+    finishReason: GeneralAgentFinishReasonSchema.parse(result.finishReason),
     responseMessages: toJsonValues(result.response.messages ?? []),
     text: result.text,
     toolCalls: result.toolCalls.map((call) => ({