workflow-message-history: The Living Trace: Debugging Durable Logic

The Code is the Dashboard

The "Black Box" problem of AI agents is usually met with messy logs or expensive observability SaaS. When an agent runs for three days, orchestrating multiple LLM calls and tool executions, traditional debugging tools fall short. You need to see exactly where the agent is, what it's thinking, and what context it's carrying.

vercel-labs/workflow-message-history proposes a radical alternative: Workflow-as-Code as a self-documenting UI. By treating a durable execution as a sequence of "message envelopes" and reflecting that state directly back onto the source code in real-time, it turns the IDE into a live flight recorder.

Solving the 72-Hour Bug

AI agents need to survive crashes. If a function runs for 72 hours and the server restarts on hour 71, you can't afford to start over. This is the domain of Durable Execution.

This project tackles the observability side of durable execution. It tracks the "survival" of a workflow through a persistent message history. If a step fails, the workflow doesn't just crash; it pauses, waiting to be resumed with its history intact.

The Envelope and the Stream

The core technical breakthrough is the "Envelope" pattern. Instead of passing raw strings or unstructured JSON between steps, the workflow uses a TicketEnvelope. This envelope acts as a state machine container, holding the payload, the current status, and a growing history array.

export type TicketEnvelope = {
  id: string;
  status: 'new' | 'normalized' | 'classified' | 'routed' | 'dispatched';
  payload: any;
  history: HistoryEvent[];
};

To get this history to the UI without blocking the workflow, the project uses a clever "Side-Channel" streaming approach. Steps emit progress events to a writable stream, which an API route then converts into Server-Sent Events (SSE) for the browser.

From Heavy Metal to Serverless

Historically, durable orchestration requires setting up heavy-duty infrastructure like Temporal or Inngest. Vercel Labs is pushing for a "Zero-Config" approach, deeply integrated with the Next.js App Router and the Vercel AI SDK.

By bringing the execution trace directly into the developer's view of the source code, workflow-message-history offers a compelling glimpse into the future of debugging non-deterministic AI flows.