First-class WorkflowIntent in AgentContext and Checkpoint

[ahmed-sekka]

Motivation

Real-world feedback: persistence ≠ recovery. After a 3 a.m. crash, the agent restarts from the last checkpoint and resumes the next step — but the intent behind that step is gone. The state survives; the why doesn't.

Today the original goal is implicit in AgentContext.messages(), recoverable but not first-class. Downstream agents can also drift from the original goal at each hop ("téléphone arabe" effect).

Scope

Standardize how the original goal threads through the graph and survives checkpoints.

Acceptance criteria

• WorkflowIntent record: goal, originator, traceId, @Nullable WorkflowIntent parent
• StateKey<WorkflowIntent> WORKFLOW_INTENT exposed from the core
• Helper WorkflowIntent.subIntent(String subGoal) for parent ↔ child chaining when an agent derives a sub-task
• Checkpoint serializes/restores WorkflowIntent
• Documented convention: every node consults WORKFLOW_INTENT first, never solely the upstream output
• Sample demonstrating intent propagation across a multi-node graph

Non-goals

• An IntentRegistry component — this is a convention on a well-known StateKey, not a new module.
• Automatic intent extraction from messages.

Notes

Sub-intent chaining matters: when a node derives "to achieve X, first do Y," Y must record X as its parent so recovery preserves the full intent stack.