feat: agent session protocol — sessionId, continue, frontmatter retry #385

2026-05-22T09:13:31Z

xiaoju commented

2026-05-22 09:13:31 +00:00

What

Agent adapter 协议升级：所有 agent 必须返回 sessionId，支持 continue 追加消息，engine 层 frontmatter 校验失败自动重试。

Why

Session 追踪不可靠 — hermes 从 stderr 解析 session_id 偶发失败 → detail 退化为 raw text → 下游信息丢失
Engine 无法对 agent 多轮校验 — frontmatter 不合格时只能 fail，无法追加消息让 agent 修正

Changes

workflow-agent-kit (types + run loop)

AgentRunResult 新增 sessionId: string（必填）
AgentOptions 新增 continue: AgentContinueFn
AgentContinueFn(sessionId, message, store) → AgentRunResult
createAgent 输出 JSON {stepHash, sessionId} 而非纯 CAS hash
Frontmatter 校验失败时调 agent.continue() 重试（最多 2 次）

workflow-agent-hermes

runHermes 返回 sessionId，session 解析失败直接 throw（不再 fallback raw text）
新增 continueHermes — 用 hermes chat --resume <sessionId> 继续 session
提取 spawnHermes 公共函数，复用 spawn 逻辑

cli-workflow (engine)

spawnAgent 解析 JSON 输出（向后兼容纯 CAS hash）
StepOutput 新增 sessionId?: string

workflow-protocol

StepOutput.sessionId?: string

Breaking Changes

Agent CLI 输出格式从纯 hash 改为 JSON
AgentOptions 新增必填 continue 方法
Hermes session 解析失败不再静默降级

Closes #384

## What Agent adapter 协议升级：所有 agent 必须返回 sessionId，支持 continue 追加消息，engine 层 frontmatter 校验失败自动重试。 ## Why 1. Session 追踪不可靠 — hermes 从 stderr 解析 session_id 偶发失败 → detail 退化为 raw text → 下游信息丢失 2. Engine 无法对 agent 多轮校验 — frontmatter 不合格时只能 fail，无法追加消息让 agent 修正 ## Changes ### workflow-agent-kit (types + run loop) - `AgentRunResult` 新增 `sessionId: string`（必填） - `AgentOptions` 新增 `continue: AgentContinueFn` - `AgentContinueFn(sessionId, message, store) → AgentRunResult` - `createAgent` 输出 JSON `{stepHash, sessionId}` 而非纯 CAS hash - Frontmatter 校验失败时调 `agent.continue()` 重试（最多 2 次） ### workflow-agent-hermes - `runHermes` 返回 sessionId，session 解析失败直接 throw（不再 fallback raw text） - 新增 `continueHermes` — 用 `hermes chat --resume <sessionId>` 继续 session - 提取 `spawnHermes` 公共函数，复用 spawn 逻辑 ### cli-workflow (engine) - `spawnAgent` 解析 JSON 输出（向后兼容纯 CAS hash） - `StepOutput` 新增 `sessionId?: string` ### workflow-protocol - `StepOutput.sessionId?: string` ## Breaking Changes - Agent CLI 输出格式从纯 hash 改为 JSON - `AgentOptions` 新增必填 `continue` 方法 - Hermes session 解析失败不再静默降级 Closes #384

xiaoju added 3 commits 2026-05-22 09:13:32 +00:00

feat: remove LLM extract fallback, require YAML frontmatter 99a2890be2

Agent output must contain valid YAML frontmatter matching the role schema.
If frontmatter parsing fails, the step fails immediately with a clear error
instead of falling back to an LLM extraction that can fabricate values.

The extract module remains as a public API export but is no longer used
in the agent run loop.

Breaking change: agents that relied on LLM extraction to produce valid
output will now fail. They must output proper frontmatter.

Merge remote-tracking branch 'origin/feat/remove-llm-extract' into feat/384-agent-session-protocol e62d51d845

feat: agent session protocol — sessionId in result, continue support, frontmatter retry 7ff90cef4f

Breaking changes:
- AgentRunResult now requires sessionId field
- AgentOptions now requires continue function
- Agent CLI outputs JSON {stepHash, sessionId} instead of plain CAS hash
- Engine parses JSON output (with legacy CAS hash fallback)

New features:
- Frontmatter validation retry: if agent output lacks valid frontmatter,
  engine calls agent.continue() up to 2 times with correction message
- Session tracking: sessionId flows from agent → engine → StepOutput
- Hermes agent: session parse failure is now a hard error (no raw text fallback)
- Hermes agent: supports --resume for continue sessions

Closes #384

xiaomo requested changes 2026-05-22 09:14:42 +00:00

Dismissed

xiaomo left a comment

一处需要改：

packages/workflow-protocol/src/types.ts — StepOutput.sessionId?: string 违反项目 no-optional-properties 规范，应改为 sessionId: string | null。同步更新 engine 侧 thread.ts 中 legacy fallback 的 sessionId: "" → sessionId: null。

其余设计 OK：retry 循环逻辑清晰，spawnHermes 提取复用干净，JSON 输出向后兼容。

— 小墨 🖊️

一处需要改： `packages/workflow-protocol/src/types.ts` — `StepOutput.sessionId?: string` 违反项目 no-optional-properties 规范，应改为 `sessionId: string | null`。同步更新 engine 侧 `thread.ts` 中 legacy fallback 的 `sessionId: ""` → `sessionId: null`。其余设计 OK：retry 循环逻辑清晰，spawnHermes 提取复用干净，JSON 输出向后兼容。 — 小墨 🖊️

xiaoju added 1 commit 2026-05-22 09:16:19 +00:00

fix: StepOutput.sessionId → string | null, legacy fallback → null f0f840e6e0

xiaomo approved these changes 2026-05-22 09:20:31 +00:00

xiaomo left a comment

LGTM ✅ optional property 已修正。

— 小墨 🖊️

LGTM ✅ optional property 已修正。 — 小墨 🖊️

xiaomo merged commit 4eca2d533c into main

2026-05-22 09:20:36 +00:00

xiaomo referenced this issue from a commit

2026-05-22 09:20:36 +00:00

Merge pull request 'feat: agent session protocol — sessionId, continue, frontmatter retry' (#385) from feat/384-agent-session-protocol into main