uncaged/workflow
10
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: builtin agent session resume via deterministic message reconstruction #426

New Issue
Closed
opened 2026-05-23 09:28:11 +00:00 by xingyue · 0 comments
xingyue commented 2026-05-23 09:28:11 +00:00
Owner
Copy Link
Copy Source

Background

Builtin agent currently starts a fresh LLM session on every step, even when the same role is re-entered in a workflow. This wastes LLM prompt cache and loses conversational context.

Design

The workflow thread context (CAS chain) is a pure function of the step history — session messages can be deterministically reconstructed without any extra persistence.

For a re-entering role, the message history should look like:

system: role prompt + output format

user₁: edge prompt₁ + context summary
assistant₁: frontmatter output₁ (final only, no tool call intermediates)

user₂: edge prompt₂ + summary of what happened since last visit
assistant₂: frontmatter output₂

user_N: current edge prompt + recent summary  ← current turn

This maximizes LLM prefix cache hits and models the moderator↔agent conversation correctly.

Changes Required

1. workflow-protocol: add edgePrompt to StepRecord

StepRecord needs an edgePrompt: string field so each step records what the moderator said. Old data compatibility: treat missing field as "".

2. workflow-agent-kit: persist edgePrompt in StepNode

  • writeStepNode / persistStep writes ctx.edgePrompt into CAS
  • StepNode CAS schema adds the field
  • buildHistory exposes edgePrompt in StepContext

3. builtin agent: reconstruct multi-turn messages from steps

Replace buildBuiltinPrompt(ctx) → { system, user } with buildBuiltinMessages(ctx) → ChatMessage[]:

  • system = role prompt + output format (stable prefix)
  • For each prior visit of this role: user (edgePrompt + inter-step summary) + assistant (frontmatter output text)
  • Final user = current edgePrompt + recent summary
  • ReAct loop intermediates (tool calls) are NOT included — only the final assistant conclusion per step

4. Tests

  • Unit test for message reconstruction with multi-step history
  • Verify cache-friendly prefix stability

Key Principles

  • Zero extra persistence — messages are a pure function of CAS chain
  • Stable message prefix → LLM prompt cache hits
  • Only final conclusions retained, not tool call intermediates
  • Backward compatible with existing steps (missing edgePrompt → "")
## Background Builtin agent currently starts a fresh LLM session on every step, even when the same role is re-entered in a workflow. This wastes LLM prompt cache and loses conversational context. ## Design The workflow thread context (CAS chain) is a pure function of the step history — session messages can be deterministically reconstructed without any extra persistence. For a re-entering role, the message history should look like: ``` system: role prompt + output format user₁: edge prompt₁ + context summary assistant₁: frontmatter output₁ (final only, no tool call intermediates) user₂: edge prompt₂ + summary of what happened since last visit assistant₂: frontmatter output₂ user_N: current edge prompt + recent summary ← current turn ``` This maximizes LLM prefix cache hits and models the moderator↔agent conversation correctly. ## Changes Required ### 1. workflow-protocol: add edgePrompt to StepRecord `StepRecord` needs an `edgePrompt: string` field so each step records what the moderator said. Old data compatibility: treat missing field as `""`. ### 2. workflow-agent-kit: persist edgePrompt in StepNode - `writeStepNode` / `persistStep` writes `ctx.edgePrompt` into CAS - StepNode CAS schema adds the field - `buildHistory` exposes edgePrompt in StepContext ### 3. builtin agent: reconstruct multi-turn messages from steps Replace `buildBuiltinPrompt(ctx) → { system, user }` with `buildBuiltinMessages(ctx) → ChatMessage[]`: - system = role prompt + output format (stable prefix) - For each prior visit of this role: user (edgePrompt + inter-step summary) + assistant (frontmatter output text) - Final user = current edgePrompt + recent summary - ReAct loop intermediates (tool calls) are NOT included — only the final assistant conclusion per step ### 4. Tests - Unit test for message reconstruction with multi-step history - Verify cache-friendly prefix stability ## Key Principles - Zero extra persistence — messages are a pure function of CAS chain - Stable message prefix → LLM prompt cache hits - Only final conclusions retained, not tool call intermediates - Backward compatible with existing steps (missing edgePrompt → "")
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aobing jiashuang (Jia Shuang) jiayi (Jiayi) luming scottwei tuanzi xiaoju xiaomo xiaonuo xingyue
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: uncaged/workflow#426
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?