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

RFC: Agent detail as merkle CAS tree + per-agent detail schema #337

New Issue
Closed
opened 2026-05-18 15:26:15 +00:00 by xiaoju · 1 comment
xiaoju commented 2026-05-18 15:26:15 +00:00
Owner
Copy Link
Copy Source

Summary

Refactor agent detail storage: each agent defines its own detail schema and stores a merkle CAS tree. Agent-kit interface changes to let agents own their detail.

Phase 1: agent-kit interface change

Change AgentRunFn return type:

// Before
run(ctx: AgentContext): Promise<string>;  // raw text

// After  
run(ctx: AgentContext): Promise<{
  output: string;       // text for extractor
  detailHash: Hash;     // agent-managed detail merkle root
}>;

agent-kit no longer stores detail — agents do it themselves.

Phase 2: uwf-hermes merkle detail

Hermes session JSON (~/.hermes/sessions/session_*.json) contains the full react loop.

Schemas

hermes-turn (leaf):

{
  "index": 0,
  "role": "assistant" | "tool",
  "content": "...",
  "toolCalls": [{"name": "...", "args": "..."}],
  "reasoning": "..." 
}

hermes-detail (root):

{
  "sessionId": "20260518_223724_45ab80",
  "model": "qwen-plus",
  "duration": 12345,
  "turnCount": 25,
  "turns": ["<turn-hash-0>", "<turn-hash-1>", ...]
}

turns field uses cas_ref so uwf cas walk traverses the full tree.

Flow

  1. uwf-hermes runs hermes chat --quiet, captures session_id from stdout
  2. Reads ~/.hermes/sessions/session_{id}.json
  3. Stores each message as a hermes-turn CAS node
  4. Stores hermes-detail root referencing all turns
  5. Returns { output, detailHash: rootHash }

Benefits

  • uwf cas get <detail> → summary (model, duration, turn count)
  • uwf cas get <turns[N]> → specific turn
  • uwf cas walk <detail> → full merkle tree
  • No need to load entire session for quick inspection
  • Different agents (cursor-agent, etc.) define completely different detail schemas

Tasks

  • Phase 1: Change agent-kit AgentRunFn return type
  • Phase 1: Update run.ts to use agent-provided detailHash
  • Phase 2: Register hermes-turn and hermes-detail schemas in uwf-hermes
  • Phase 2: Parse Hermes session JSON into merkle CAS tree
  • Phase 2: Extract session_id from Hermes stdout

Dependencies

  • json-cas 0.3.0 (no null typeHash) — ✅ published
  • Closes #336 (detail uses null type)
## Summary Refactor agent detail storage: each agent defines its own detail schema and stores a merkle CAS tree. Agent-kit interface changes to let agents own their detail. ## Phase 1: agent-kit interface change Change `AgentRunFn` return type: ```typescript // Before run(ctx: AgentContext): Promise<string>; // raw text // After run(ctx: AgentContext): Promise<{ output: string; // text for extractor detailHash: Hash; // agent-managed detail merkle root }>; ``` agent-kit no longer stores detail — agents do it themselves. ## Phase 2: uwf-hermes merkle detail Hermes session JSON (`~/.hermes/sessions/session_*.json`) contains the full react loop. ### Schemas **hermes-turn** (leaf): ```json { "index": 0, "role": "assistant" | "tool", "content": "...", "toolCalls": [{"name": "...", "args": "..."}], "reasoning": "..." } ``` **hermes-detail** (root): ```json { "sessionId": "20260518_223724_45ab80", "model": "qwen-plus", "duration": 12345, "turnCount": 25, "turns": ["<turn-hash-0>", "<turn-hash-1>", ...] } ``` `turns` field uses `cas_ref` so `uwf cas walk` traverses the full tree. ### Flow 1. uwf-hermes runs `hermes chat --quiet`, captures `session_id` from stdout 2. Reads `~/.hermes/sessions/session_{id}.json` 3. Stores each message as a `hermes-turn` CAS node 4. Stores `hermes-detail` root referencing all turns 5. Returns `{ output, detailHash: rootHash }` ### Benefits - `uwf cas get <detail>` → summary (model, duration, turn count) - `uwf cas get <turns[N]>` → specific turn - `uwf cas walk <detail>` → full merkle tree - No need to load entire session for quick inspection - Different agents (cursor-agent, etc.) define completely different detail schemas ## Tasks - [ ] Phase 1: Change agent-kit `AgentRunFn` return type - [ ] Phase 1: Update `run.ts` to use agent-provided `detailHash` - [ ] Phase 2: Register `hermes-turn` and `hermes-detail` schemas in uwf-hermes - [ ] Phase 2: Parse Hermes session JSON into merkle CAS tree - [ ] Phase 2: Extract `session_id` from Hermes stdout ## Dependencies - json-cas 0.3.0 (no null typeHash) — ✅ published - Closes #336 (detail uses null type)
xiaoju commented 2026-05-18 16:20:33 +00:00
Author
Owner
Copy Link
Copy Source

Closing: Completed: Phase 1 (PR #338) + Phase 2 (PR #339) — merkle detail tree

— 小橘 🍊（NEKO Team）

Closing: Completed: Phase 1 (PR #338) + Phase 2 (PR #339) — merkle detail tree — 小橘 🍊（NEKO Team）
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#337
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?