feat: add handoff workflow checkpoint recovery

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

sidecar/src/Aryx.AgentHost/Contracts/ProtocolModels.cs

@@ -188,6 +188,7 @@ public sealed class RunTurnCommandDto : SidecarCommandEnvelope
     public PatternDefinitionDto Pattern { get; init; } = new();
     public IReadOnlyList<ChatMessageDto> Messages { get; init; } = [];
     public RunTurnToolingConfigDto? Tooling { get; init; }
+    public WorkflowCheckpointResumeDto? ResumeFromCheckpoint { get; init; }
 }
 
 public sealed class CancelTurnCommandDto : SidecarCommandEnvelope
@@ -488,6 +489,15 @@ public sealed class PendingMessagesModifiedEventDto : SidecarEventDto
     public string? AgentName { get; init; }
 }
 
+public sealed class WorkflowCheckpointSavedEventDto : SidecarEventDto
+{
+    public string SessionId { get; init; } = string.Empty;
+    public string WorkflowSessionId { get; init; } = string.Empty;
+    public string CheckpointId { get; init; } = string.Empty;
+    public string StorePath { get; init; } = string.Empty;
+    public int StepNumber { get; init; }
+}
+
 public sealed class WorkflowDiagnosticEventDto : SidecarEventDto
 {
     public string SessionId { get; init; } = string.Empty;
@@ -604,6 +614,13 @@ public sealed class ExitPlanModeRequestedEventDto : SidecarEventDto
     public string? RecommendedAction { get; init; }
 }
 
+public sealed class WorkflowCheckpointResumeDto
+{
+    public string WorkflowSessionId { get; init; } = string.Empty;
+    public string CheckpointId { get; init; } = string.Empty;
+    public string StorePath { get; init; } = string.Empty;
+}
+
 public sealed class CommandErrorEventDto : SidecarEventDto
 {
     public string Message { get; init; } = string.Empty;

sidecar/src/Aryx.AgentHost/Services/CopilotWorkflowRunner.cs

@@ -1,7 +1,9 @@
+using System.IO;
 using System.Linq;
 using Aryx.AgentHost.Contracts;
 using GitHub.Copilot.SDK;
 using Microsoft.Agents.AI.Workflows;
+using Microsoft.Agents.AI.Workflows.Checkpointing;
 using Microsoft.Extensions.AI;
 
 namespace Aryx.AgentHost.Services;
@@ -81,7 +83,16 @@ public sealed class CopilotWorkflowRunner : ITurnWorkflowRunner
             List<ChatMessage> inputMessages = command.Messages.Select(WorkflowTranscriptProjector.ToChatMessage).ToList();
             WorkflowTranscriptProjector.AttachMessageMode(inputMessages, command.MessageMode);
 
-            await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, inputMessages).ConfigureAwait(false);
+            using FileSystemJsonCheckpointStore? checkpointStore = CreateCheckpointStore(command);
+            CheckpointManager? checkpointManager = checkpointStore is not null
+                ? CheckpointManager.CreateJson(checkpointStore)
+                : null;
+
+            await using StreamingRun run = await OpenWorkflowRunAsync(
+                command,
+                workflow,
+                inputMessages,
+                checkpointManager).ConfigureAwait(false);
             await run.TrySendMessageAsync(new TurnToken(emitEvents: true)).ConfigureAwait(false);
 
             await foreach (WorkflowEvent evt in run.WatchStreamAsync(runCancellation.Token).ConfigureAwait(false))
@@ -120,6 +131,62 @@ public sealed class CopilotWorkflowRunner : ITurnWorkflowRunner
         }
     }
 
+    internal static FileSystemJsonCheckpointStore? CreateCheckpointStore(RunTurnCommandDto command)
+    {
+        if (!ShouldEnableWorkflowCheckpointing(command))
+        {
+            return null;
+        }
+
+        DirectoryInfo checkpointDirectory = new(GetCheckpointStorePath(command));
+        return new FileSystemJsonCheckpointStore(checkpointDirectory);
+    }
+
+    internal static bool ShouldEnableWorkflowCheckpointing(RunTurnCommandDto command)
+    {
+        ArgumentNullException.ThrowIfNull(command);
+        return string.Equals(command.Pattern.Mode, "handoff", StringComparison.OrdinalIgnoreCase);
+    }
+
+    internal static string GetCheckpointStorePath(RunTurnCommandDto command)
+    {
+        ArgumentNullException.ThrowIfNull(command);
+
+        if (!string.IsNullOrWhiteSpace(command.ResumeFromCheckpoint?.StorePath))
+        {
+            return command.ResumeFromCheckpoint.StorePath;
+        }
+
+        string localAppData = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
+        return Path.Combine(localAppData, "Aryx", "workflow-checkpoints", command.SessionId, command.RequestId);
+    }
+
+    private static ValueTask<StreamingRun> OpenWorkflowRunAsync(
+        RunTurnCommandDto command,
+        Workflow workflow,
+        IReadOnlyList<ChatMessage> inputMessages,
+        CheckpointManager? checkpointManager)
+    {
+        if (checkpointManager is not null && command.ResumeFromCheckpoint is { } resumeFromCheckpoint)
+        {
+            return InProcessExecution.ResumeStreamingAsync(
+                workflow,
+                new CheckpointInfo(resumeFromCheckpoint.WorkflowSessionId, resumeFromCheckpoint.CheckpointId),
+                checkpointManager);
+        }
+
+        if (checkpointManager is not null)
+        {
+            return InProcessExecution.RunStreamingAsync(
+                workflow,
+                inputMessages.ToList(),
+                checkpointManager,
+                sessionId: command.RequestId);
+        }
+
+        return InProcessExecution.RunStreamingAsync(workflow, inputMessages.ToList());
+    }
+
     internal static void ConfigureHookLifecycleEventSuppression(
         CopilotTurnExecutionState state,
         CopilotAgentBundle bundle)
@@ -211,6 +278,12 @@ public sealed class CopilotWorkflowRunner : ITurnWorkflowRunner
             return false;
         }
 
+        if (TryCreateWorkflowCheckpointSavedEvent(command, evt, out WorkflowCheckpointSavedEventDto? checkpointSaved))
+        {
+            await onEvent(checkpointSaved).ConfigureAwait(false);
+            return false;
+        }
+
         if (TryCreateWorkflowDiagnosticEvent(command, evt, state, out WorkflowDiagnosticEventDto? diagnostic))
         {
             await onEvent(diagnostic).ConfigureAwait(false);
@@ -347,6 +420,33 @@ public sealed class CopilotWorkflowRunner : ITurnWorkflowRunner
         }
     }
 
+    internal static bool TryCreateWorkflowCheckpointSavedEvent(
+        RunTurnCommandDto command,
+        WorkflowEvent evt,
+        out WorkflowCheckpointSavedEventDto checkpointSaved)
+    {
+        checkpointSaved = default!;
+
+        if (!ShouldEnableWorkflowCheckpointing(command)
+            || evt is not SuperStepCompletedEvent superStepCompleted
+            || superStepCompleted.CompletionInfo?.Checkpoint is not CheckpointInfo checkpoint)
+        {
+            return false;
+        }
+
+        checkpointSaved = new WorkflowCheckpointSavedEventDto
+        {
+            Type = "workflow-checkpoint-saved",
+            RequestId = command.RequestId,
+            SessionId = command.SessionId,
+            WorkflowSessionId = checkpoint.SessionId,
+            CheckpointId = checkpoint.CheckpointId,
+            StorePath = GetCheckpointStorePath(command),
+            StepNumber = superStepCompleted.StepNumber,
+        };
+        return true;
+    }
+
     private static bool TryCreateWorkflowDiagnosticEvent(
         RunTurnCommandDto command,
         WorkflowEvent evt,

sidecar/tests/Aryx.AgentHost.Tests/CopilotWorkflowRunnerTests.cs

@@ -1,3 +1,4 @@
+using System.IO;
 using System.Reflection;
 using System.Runtime.CompilerServices;
 using Aryx.AgentHost.Contracts;
@@ -798,6 +799,50 @@ public sealed class CopilotWorkflowRunnerTests
             });
     }
 
+    [Fact]
+    public async Task HandleWorkflowEventAsync_EmitsWorkflowCheckpointSavedEvent()
+    {
+        RunTurnCommandDto command = CreateHandoffCommand();
+        CopilotTurnExecutionState state = new(command);
+        List<WorkflowCheckpointSavedEventDto> checkpoints = [];
+
+        MethodInfo handleWorkflowEvent = typeof(CopilotWorkflowRunner).GetMethod(
+            "HandleWorkflowEventAsync",
+            BindingFlags.NonPublic | BindingFlags.Static)!;
+        Task<bool> handleTask = (Task<bool>)handleWorkflowEvent.Invoke(
+            null,
+            [
+                command,
+                new SuperStepCompletedEvent(
+                    3,
+                    new SuperStepCompletionInfo([])
+                    {
+                        Checkpoint = new CheckpointInfo(command.RequestId, "checkpoint-1"),
+                    }),
+                Array.Empty<ChatMessage>(),
+                state,
+                (Func<TurnDeltaEventDto, Task>)(_ => Task.CompletedTask),
+                (Func<SidecarEventDto, Task>)(sidecarEvent =>
+                {
+                    checkpoints.Add(Assert.IsType<WorkflowCheckpointSavedEventDto>(sidecarEvent));
+                    return Task.CompletedTask;
+                }),
+            ])!;
+
+        bool shouldEndTurn = await handleTask;
+
+        Assert.False(shouldEndTurn);
+        WorkflowCheckpointSavedEventDto checkpoint = Assert.Single(checkpoints);
+        Assert.Equal("workflow-checkpoint-saved", checkpoint.Type);
+        Assert.Equal(command.SessionId, checkpoint.SessionId);
+        Assert.Equal(command.RequestId, checkpoint.WorkflowSessionId);
+        Assert.Equal("checkpoint-1", checkpoint.CheckpointId);
+        Assert.Equal(3, checkpoint.StepNumber);
+        Assert.EndsWith(
+            Path.Combine("Aryx", "workflow-checkpoints", command.SessionId, command.RequestId),
+            checkpoint.StorePath);
+    }
+
     [Fact]
     public async Task HandleWorkflowEventAsync_EmitsExecutorFailedDiagnostic()
     {