fix(runtime): add stoppedByCancellation status for proper cancellation handling

When shouldContinueRun returns false, the coordinator now sets the checkpoint
status to stoppedByCancellation. This allows the run loop to properly handle
the cancellation case and update the job status accordingly.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: FL4TLiN3

.changeset/calm-birds-teach.md

@@ -0,0 +1,8 @@
+---
+"@perstack/core": patch
+"@perstack/runtime": patch
+---
+
+Add stoppedByCancellation status for proper job cancellation handling
+
+When `shouldContinueRun` returns `false`, the coordinator now sets the checkpoint status to `stoppedByCancellation` instead of leaving it as `init` or `proceeding`. This allows the run loop to properly handle the cancellation case and update the job status accordingly.

apps/runtime/src/run.test.ts

@@ -73,6 +73,15 @@ describe("@perstack/runtime: run", () => {
       expect(result.status).toBe("stoppedByError")
     })
 
+    it("returns checkpoint on stoppedByCancellation status", async () => {
+      const stoppedCheckpoint = createCheckpoint({ status: "stoppedByCancellation" })
+      setupMockExecutor([{ checkpoint: stoppedCheckpoint }])
+
+      const result = await run({ setting, checkpoint })
+
+      expect(result.status).toBe("stoppedByCancellation")
+    })
+
     it("throws error on unknown status", async () => {
       // Manually create checkpoint with invalid status to bypass schema validation
       const unknownCheckpoint = {
@@ -195,6 +204,19 @@ describe("@perstack/runtime: run", () => {
       const lastCall = storeJob.mock.calls[storeJob.mock.calls.length - 1][0] as Job
       expect(lastCall.status).toBe("stoppedByError")
     })
+
+    it("updates job status to stoppedByCancellation on cancellation", async () => {
+      const stoppedCheckpoint = createCheckpoint({ status: "stoppedByCancellation" })
+      setupMockExecutor([{ checkpoint: stoppedCheckpoint }])
+
+      const storeJob = vi.fn()
+
+      await run({ setting, checkpoint }, { storeJob })
+
+      const lastCall = storeJob.mock.calls[storeJob.mock.calls.length - 1][0] as Job
+      expect(lastCall.status).toBe("stoppedByCancellation")
+      expect(lastCall.finishedAt).toBeDefined()
+    })
   })
 
   describe("returnOnDelegationComplete option", () => {

apps/runtime/src/run.ts

@@ -163,6 +163,11 @@ export async function run(runInput: RunParamsInput, options?: RunOptions): Promi
         return resultCheckpoint
       }
 
+      case "stoppedByCancellation": {
+        storeJob({ ...job, status: "stoppedByCancellation", finishedAt: Date.now() })
+        return resultCheckpoint
+      }
+
       default:
         throw new Error("Run stopped by unknown reason")
     }

apps/runtime/src/state-machine/coordinator.test.ts

@@ -380,7 +380,7 @@ describe("@perstack/runtime: StateMachineCoordinator", () => {
       expect(params.storeCheckpoint).toHaveBeenCalledWith(eventCheckpoint)
     })
 
-    it("respects shouldContinueRun callback", async () => {
+    it("respects shouldContinueRun callback and sets stoppedByCancellation status", async () => {
       const shouldContinueRun = vi.fn().mockResolvedValue(false)
       const params = createMockParams({ shouldContinueRun })
       const mockCloseManagers = vi.fn().mockResolvedValue(undefined)
@@ -420,12 +420,13 @@ describe("@perstack/runtime: StateMachineCoordinator", () => {
         logics: mockLogics,
       })
 
-      await coordinator.execute()
+      const result = await coordinator.execute()
 
       expect(shouldContinueRun).toHaveBeenCalledTimes(1)
       expect(mockActor.stop).toHaveBeenCalledTimes(1)
       expect(mockCloseManagers).toHaveBeenCalledTimes(1)
       expect(mockActor.send).not.toHaveBeenCalled()
+      expect(result.status).toBe("stoppedByCancellation")
     })
   })
 

apps/runtime/src/state-machine/coordinator.ts

@@ -127,7 +127,11 @@ export class StateMachineCoordinator {
       if (!shouldContinue) {
         this.actor?.stop()
         await this.closeManagers(runState.context.skillManagers)
-        this.resolvePromise?.(runState.context.checkpoint)
+        const cancelledCheckpoint = {
+          ...runState.context.checkpoint,
+          status: "stoppedByCancellation" as const,
+        }
+        this.resolvePromise?.(cancelledCheckpoint)
         return
       }
     }

apps/runtime/src/state-machine/states/init.test.ts

@@ -226,4 +226,40 @@ describe("@perstack/runtime: StateMachineLogic['Init']", () => {
       }),
     ).rejects.toThrow("Input message is undefined")
   })
+
+  it("resumes from stoppedByCancellation correctly", async () => {
+    const setting = createRunSetting({
+      input: { text: "resume-text" },
+    })
+    const checkpoint = createCheckpoint({
+      status: "stoppedByCancellation",
+    })
+    const step = createStep()
+    await expect(
+      StateMachineLogics.Init({
+        setting,
+        checkpoint,
+        step,
+        eventListener: async () => {},
+        skillManagers: {},
+        llmExecutor: mockLLMExecutor,
+      }),
+    ).resolves.toStrictEqual({
+      type: "startRun",
+      id: expect.any(String),
+      expertKey: setting.expertKey,
+      timestamp: expect.any(Number),
+      jobId: setting.jobId,
+      runId: setting.runId,
+      stepNumber: checkpoint.stepNumber,
+      initialCheckpoint: checkpoint,
+      inputMessages: [
+        {
+          type: "userMessage",
+          id: expect.any(String),
+          contents: [{ type: "textPart", id: expect.any(String), text: "resume-text" }],
+        },
+      ],
+    })
+  })
 })

packages/core/src/schemas/checkpoint.ts

@@ -19,6 +19,7 @@ export type CheckpointStatus =
   | "stoppedByDelegate"
   | "stoppedByExceededMaxSteps"
   | "stoppedByError"
+  | "stoppedByCancellation"
 
 export const checkpointStatusSchema = z.enum([
   "init",
@@ -28,6 +29,7 @@ export const checkpointStatusSchema = z.enum([
   "stoppedByDelegate",
   "stoppedByExceededMaxSteps",
   "stoppedByError",
+  "stoppedByCancellation",
 ])
 
 /** Information about a delegation target */

packages/core/src/schemas/job.ts

@@ -10,13 +10,15 @@ export type JobStatus =
   | "stoppedByMaxSteps"
   | "stoppedByInteractiveTool"
   | "stoppedByError"
+  | "stoppedByCancellation"
 
 export const jobStatusSchema = z.enum([
   "running",
   "completed",
   "stoppedByMaxSteps",
   "stoppedByInteractiveTool",
   "stoppedByError",
+  "stoppedByCancellation",
 ])
 
 export interface Job {