docs: replace RFC-001 with up-to-date architecture doc
RFC-001 was severely outdated (pre-refactor types). New architecture.md covers the current three-phase engine, pure data roles, AgentBinding, ExtractFn, and all design decisions. 小橘 <xiaoju@shazhou.work>
This commit is contained in:
@@ -0,0 +1,259 @@
|
||||
# @uncaged/workflow — Architecture
|
||||
|
||||
**Last updated:** 2026-05-06 by 小橘 🍊（NEKO Team）
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
A workflow engine that executes single-file ESM bundles. Each workflow is a self-contained `.esm.js` file identified by its XXH64 hash (Crockford Base32). No daemon — processes start on demand and exit when done.
|
||||
|
||||
## Package Structure
|
||||
|
||||
| Package | npm Name | Purpose |
|
||||
|---------|----------|---------|
|
||||
| `workflow` | `@uncaged/workflow` | Core: types, engine, ExtractFn, hash/ULID/registry |
|
||||
| `cli-workflow` | `@uncaged/cli-workflow` | CLI: `uncaged-workflow` command |
|
||||
| `workflow-agent-cursor` | `@uncaged/workflow-agent-cursor` | Cursor CLI agent (extracts workspace from ctx) |
|
||||
| `workflow-agent-hermes` | `@uncaged/workflow-agent-hermes` | Hermes CLI agent |
|
||||
| `workflow-agent-llm` | `@uncaged/workflow-agent-llm` | OpenAI-compatible LLM agent |
|
||||
| `workflow-role-planner` | `@uncaged/workflow-role-planner` | Pure data: phased planning prompt + schema |
|
||||
| `workflow-role-coder` | `@uncaged/workflow-role-coder` | Pure data: coding prompt + schema |
|
||||
| `workflow-role-reviewer` | `@uncaged/workflow-role-reviewer` | Pure data: code review prompt + schema |
|
||||
| `workflow-role-committer` | `@uncaged/workflow-role-committer` | Pure data: git commit prompt + schema |
|
||||
| `workflow-template-solve-issue` | `@uncaged/workflow-template-solve-issue` | Composes roles + moderator into a complete workflow |
|
||||
| `workflow-util-agent` | `@uncaged/workflow-util-agent` | `buildAgentPrompt` + `spawnCli` utilities |
|
||||
|
||||
Monorepo with **bun workspace**, `workspace:*` protocol.
|
||||
|
||||
## Core Types
|
||||
|
||||
```typescript
|
||||
// --- Sentinel values ---
|
||||
const START = "__start__";
|
||||
const END = "__end__";
|
||||
|
||||
// --- RoleMeta: maps role names → their meta types ---
|
||||
type RoleMeta = Record<string, Record<string, unknown>>;
|
||||
|
||||
// --- Role Definition: pure data, no execution logic ---
|
||||
type RoleDefinition<Meta> = {
|
||||
description: string; // human-readable
|
||||
systemPrompt: string; // given to agent
|
||||
extractPrompt: string; // given to extractor
|
||||
schema: z.ZodType<Meta>; // meta shape (Zod v4)
|
||||
};
|
||||
|
||||
// --- Workflow Definition: pure data, no agent binding ---
|
||||
type WorkflowDefinition<M extends RoleMeta> = {
|
||||
description: string;
|
||||
roles: { [K in keyof M & string]: RoleDefinition<M[K]> };
|
||||
moderator: Moderator<M>;
|
||||
};
|
||||
|
||||
// --- Agent: raw string output, reads role info from context ---
|
||||
type AgentFn = (ctx: AgentContext) => Promise<string>;
|
||||
|
||||
// --- Agent Binding: runtime assignment ---
|
||||
type AgentBinding = {
|
||||
agent: AgentFn;
|
||||
overrides?: Partial<Record<string, AgentFn>>;
|
||||
};
|
||||
|
||||
// --- Extract: structured data from context ---
|
||||
type ExtractFn = <T>(schema: z.ZodType<T>, prompt: string, ctx: ExtractContext) => Promise<T>;
|
||||
|
||||
// --- Moderator: pure routing function ---
|
||||
type Moderator<M extends RoleMeta> = (ctx: ModeratorContext<M>) => (keyof M & string) | typeof END;
|
||||
|
||||
// --- Composition ---
|
||||
// createWorkflow(def, binding, extract) => WorkflowFn
|
||||
```
|
||||
|
||||
## Three-Phase Engine Loop
|
||||
|
||||
Each role execution has three distinct phases with progressive context:
|
||||
|
||||
```
|
||||
┌─→ Phase 1: MODERATOR
|
||||
│ Context: ModeratorContext { threadId, start, steps }
|
||||
│ Action: moderator(ctx) → role name | END
|
||||
│
|
||||
│ Phase 2: AGENT
|
||||
│ Context: AgentContext = ModeratorCtx + { currentRole: { name, systemPrompt } }
|
||||
│ Action: agent(ctx) → raw string
|
||||
│
|
||||
│ Phase 3: EXTRACTOR
|
||||
│ Context: ExtractContext = AgentCtx + { agentContent }
|
||||
│ Action: extract(schema, extractPrompt, ctx) → typed meta
|
||||
│
|
||||
│ Merge: RoleStep { role, content, meta, timestamp }
|
||||
│ Append to steps
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Context Types (progressive)
|
||||
|
||||
```typescript
|
||||
// Phase 1: Moderator sees accumulated state only
|
||||
type ModeratorContext<M> = {
|
||||
threadId: string;
|
||||
start: StartStep;
|
||||
steps: RoleStep<M>[];
|
||||
};
|
||||
|
||||
// Phase 2: Agent knows its identity
|
||||
type AgentContext<M> = ModeratorContext<M> & {
|
||||
currentRole: { name: string; systemPrompt: string };
|
||||
};
|
||||
|
||||
// Phase 3: Extractor has agent output
|
||||
type ExtractContext<M> = AgentContext<M> & {
|
||||
agentContent: string;
|
||||
};
|
||||
|
||||
// ThreadContext is an alias for AgentContext (backward compat)
|
||||
type ThreadContext<M> = AgentContext<M>;
|
||||
```
|
||||
|
||||
### Key Properties
|
||||
|
||||
- **Moderator is synchronous and pure** — no I/O, no state mutation
|
||||
- **Agent gets context, not instructions** — reads `ctx.currentRole.systemPrompt`
|
||||
- **Extractor is a general tool** — not limited to post-agent extraction; agents can use it too (e.g. Cursor agent extracts workspace path before execution)
|
||||
- **extractPrompt is a call parameter**, not context state — different callers use different prompts
|
||||
|
||||
## Agent Information Sources
|
||||
|
||||
An agent has exactly three information sources:
|
||||
|
||||
1. **Prior knowledge** — LLM training, agent memory, agent skills
|
||||
2. **Thread context** — `AgentContext` (start, steps, currentRole)
|
||||
3. **Derived information** — from 1 & 2 (e.g. tool calls, shell commands)
|
||||
|
||||
No hidden environment parameters. If an agent needs something (like a workspace path), it extracts it from context using `ExtractFn`.
|
||||
|
||||
## Bundle Contract
|
||||
|
||||
A workflow bundle is a single `.esm.js` file with two named exports:
|
||||
|
||||
```typescript
|
||||
// Named exports (no default export)
|
||||
export const descriptor: WorkflowDescriptor;
|
||||
export const run: WorkflowFn;
|
||||
|
||||
type WorkflowFn = (
|
||||
input: { prompt: string; steps: RoleOutput[] },
|
||||
options: { threadId: string; maxRounds: number },
|
||||
) => AsyncGenerator<RoleOutput, WorkflowResult>;
|
||||
```
|
||||
|
||||
### Constraints
|
||||
|
||||
- Single `.esm.js` file
|
||||
- No dynamic `import()`
|
||||
- All static imports must be Node built-in modules only
|
||||
- XXH64 hash (Crockford Base32) = globally unique version ID
|
||||
|
||||
### Why AsyncGenerator?
|
||||
|
||||
- Each `yield` → engine writes to `.data.jsonl`, checks abort/pause
|
||||
- `return` → engine marks thread complete
|
||||
- Fork = pass historical steps as `input.steps` to a new generator
|
||||
- Zero injection — bundle doesn't import from the engine
|
||||
|
||||
## Storage Layout
|
||||
|
||||
```
|
||||
~/.uncaged/workflow/
|
||||
├── bundles/
|
||||
│ ├── C9NMV6V2TQT81.esm.js # Crockford Base32 of XXH64
|
||||
│ └── C9NMV6V2TQT81.yaml # Role descriptor
|
||||
├── logs/ # One folder per bundle hash
|
||||
│ └── C9NMV6V2TQT81/
|
||||
│ ├── 01KQXKW…YG.data.jsonl # Thread state
|
||||
│ └── 01KQXKW…YG.info.jsonl # Debug log
|
||||
└── workflow.yaml # Registry
|
||||
```
|
||||
|
||||
### ID Encoding: Crockford Base32
|
||||
|
||||
- Case-insensitive, filesystem-safe, no ambiguous chars (0/O, 1/I/L)
|
||||
- Bundle hash: XXH64 → 13-char
|
||||
- Thread ID: ULID → 26-char (10 timestamp + 16 random)
|
||||
|
||||
### Registry (`workflow.yaml`)
|
||||
|
||||
```yaml
|
||||
workflows:
|
||||
solve-issue:
|
||||
hash: "C9NMV6V2TQT81"
|
||||
timestamp: 1714963200000
|
||||
history:
|
||||
- hash: "A7BKR3M1NPQ40"
|
||||
timestamp: 1714876800000
|
||||
```
|
||||
|
||||
### Thread JSONL
|
||||
|
||||
**`.data.jsonl`** — Line 1: start record, Line 2+: role outputs
|
||||
|
||||
```jsonc
|
||||
// Start record
|
||||
{ "name": "solve-issue", "hash": "C9NMV6V2TQT81", "threadId": "01KQXKW…",
|
||||
"parameters": { "prompt": "Fix bug #3", "options": { "maxRounds": 5 } },
|
||||
"timestamp": 1714963200000 }
|
||||
// Role output
|
||||
{ "role": "planner", "content": "...", "meta": { "phases": [...] }, "timestamp": ... }
|
||||
```
|
||||
|
||||
**`.info.jsonl`** — Structured debug log
|
||||
|
||||
```jsonc
|
||||
{ "tag": "4KNMR2PX", "content": "Loading bundle...", "timestamp": ... }
|
||||
```
|
||||
|
||||
Tags are 8-char Crockford Base32 (40-bit random), one per call site. `grep "4KNMR2PX"` → instant code location.
|
||||
|
||||
## Execution Model
|
||||
|
||||
- **No daemon.** `uncaged-workflow run <name>` starts a worker process
|
||||
- Same bundle's threads share one process (memory efficiency)
|
||||
- Process exits when all threads complete
|
||||
- Thread termination via IPC within the process
|
||||
|
||||
## CLI Commands
|
||||
|
||||
| Priority | Command | Description |
|
||||
|----------|---------|-------------|
|
||||
| P1 | `add <name> <file.esm.js>` | Register a bundle |
|
||||
| P1 | `list` | List registered workflows |
|
||||
| P1 | `show <name>` | Show workflow details |
|
||||
| P1 | `remove <name>` | Remove a workflow |
|
||||
| P1 | `run <name> [--prompt] [--max-rounds]` | Start a thread |
|
||||
| P1 | `threads [name]` | List threads |
|
||||
| P1 | `thread <id>` | Show thread state |
|
||||
| P1 | `thread rm <id>` | Delete a thread |
|
||||
| P1 | `ps` | List running threads |
|
||||
| P1 | `kill <thread-id>` | Terminate a running thread |
|
||||
| P2 | `history <name>` | Show version history |
|
||||
| P2 | `rollback <name> [hash]` | Switch to a previous version |
|
||||
| P2 | `pause <thread-id>` | Pause a running thread |
|
||||
| P2 | `resume <thread-id>` | Resume a paused thread |
|
||||
| P3 | `fork <thread-id> [--from-role <role>]` | Fork from historical state |
|
||||
|
||||
All commands implemented and tested. ✅
|
||||
|
||||
## Design Decisions
|
||||
|
||||
| Decision | Rationale |
|
||||
|----------|-----------|
|
||||
| **Role = pure data** | Decouples definition from execution; same role with different agents |
|
||||
| **Agent bound at runtime** | WorkflowDefinition is reusable; agent choice is deployment concern |
|
||||
| **Three-phase context** | Each phase sees only what it needs; clean separation |
|
||||
| **ExtractFn as general tool** | Agents use it for pre-execution extraction; engine uses it for meta |
|
||||
| **Single-file ESM** | Hash = version, no dependency hell, self-contained |
|
||||
| **No daemon** | OS handles process lifecycle; unnecessary complexity |
|
||||
| **Crockford Base32** | Filesystem-safe, readable, compact |
|
||||
| **No concurrency in registry** | Different workflows have different constraints; belongs at workflow/role level |
|
||||
| **No dryRun** | Tests use mock agents + mock fetch; simpler architecture |
|
||||
@@ -1,437 +0,0 @@
|
||||
# RFC-001: Workflow Engine Design
|
||||
|
||||
**Author:** 小橘 🍊（NEKO Team）
|
||||
**Date:** 2026-05-06
|
||||
**Status:** Draft
|
||||
|
||||
---
|
||||
|
||||
## 1. Package Structure
|
||||
|
||||
| Package | npm Name | Binary |
|
||||
|---------|----------|--------|
|
||||
| Core lib | `@uncaged/workflow` | — |
|
||||
| CLI | `@uncaged/cli-workflow` | `uncaged-workflow` |
|
||||
|
||||
Future: `@uncaged/cli` umbrella, invoke via `uncaged workflow <subcommand>`.
|
||||
|
||||
Monorepo uses **bun workspace**.
|
||||
|
||||
## 2. Workflow Physical Implementation
|
||||
|
||||
A **Workflow** is a single-file ESM module that **named-exports** an **AsyncGenerator** function as `run` and workflow metadata as `descriptor`:
|
||||
|
||||
```typescript
|
||||
/** What each yield produces — one role's output. */
|
||||
type RoleOutput = {
|
||||
role: string;
|
||||
content: string;
|
||||
meta: Record<string, unknown>;
|
||||
};
|
||||
|
||||
/** What the generator returns when done. */
|
||||
type WorkflowResult = {
|
||||
returnCode: number;
|
||||
summary: string;
|
||||
};
|
||||
|
||||
/** Input to a workflow — prompt + optional historical steps for fork/resume. */
|
||||
type ThreadInput = {
|
||||
prompt: string;
|
||||
steps: RoleOutput[]; // [] for new thread, pre-filled for fork/resume
|
||||
};
|
||||
|
||||
/** The bundle contract — an AsyncGenerator, not a Promise. */
|
||||
type WorkflowFn = (
|
||||
input: ThreadInput,
|
||||
options: { threadId: string; maxRounds: number }
|
||||
) => AsyncGenerator<RoleOutput, WorkflowResult>;
|
||||
```
|
||||
|
||||
### Why AsyncGenerator?
|
||||
|
||||
The workflow **yields** each role output instead of writing to an injected writer or
|
||||
exporting a framework-specific shape:
|
||||
|
||||
```typescript
|
||||
// Example bundle — zero framework dependency (named exports only)
|
||||
export const descriptor = {
|
||||
description: "Fix auth bug",
|
||||
roles: {
|
||||
planner: {
|
||||
description: "Plans the fix",
|
||||
schema: { type: "object", properties: { files: { type: "array", items: { type: "string" } } } },
|
||||
},
|
||||
coder: {
|
||||
description: "Implements the plan",
|
||||
schema: { type: "object", properties: { diff: { type: "string" } } },
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
export const run = async function* (input, options) {
|
||||
const plan = await callLLM("plan: " + input.prompt);
|
||||
yield { role: "planner", content: plan, meta: { files: ["src/auth.ts"] } };
|
||||
|
||||
const code = await callLLM("implement: " + plan);
|
||||
yield { role: "coder", content: code, meta: { diff: "..." } };
|
||||
|
||||
return { returnCode: 0, summary: "Fixed auth bug" };
|
||||
};
|
||||
```
|
||||
|
||||
**Engine controls the loop**, not the bundle:
|
||||
- Each `yield` → engine writes to `.data.jsonl`, checks `AbortSignal`, handles pause/resume
|
||||
- `return` → engine writes the final result, marks thread complete
|
||||
- **Fork** = read historical steps from `.data.jsonl`, pass as `input.steps` to a new generator
|
||||
- **Zero injection** — the bundle doesn't import or receive anything from the engine
|
||||
|
||||
### Fork/Resume via ThreadInput
|
||||
|
||||
When using the `createRoleModerator` helper, fork is **naturally handled**:
|
||||
|
||||
```typescript
|
||||
// The moderator receives ThreadContext with historical steps
|
||||
// It sees planner already ran → routes to coder automatically
|
||||
const gen = workflow(
|
||||
{ prompt: "fix bug #3", steps: [{ role: "planner", content: "...", meta: {} }] },
|
||||
{ threadId: "01KQXKW18CT8G75T53R8F4G7YG", maxRounds: 10 }
|
||||
);
|
||||
// First yield will be coder's output, not planner's
|
||||
```
|
||||
|
||||
No special replay logic needed — the moderator/role pattern inherently supports
|
||||
resuming from any snapshot, because moderator routing is a pure function of the
|
||||
accumulated steps.
|
||||
|
||||
This follows the **Dependency Inversion Principle**: the engine depends on the
|
||||
generator protocol (a language primitive), not on a framework-specific `WorkflowDefinition`.
|
||||
Bundles remain pure functions with no coupling to `@uncaged/workflow`.
|
||||
|
||||
### Relationship to Role/Moderator Pattern
|
||||
|
||||
The Role + Moderator pattern from Section 8 is one **implementation strategy** inside a
|
||||
bundle, not the bundle contract itself. A helper like `createRoleModerator(roles, moderator)`
|
||||
can produce the AsyncGenerator internally, but simple workflows can yield directly without
|
||||
any framework types.
|
||||
|
||||
### Constraints
|
||||
|
||||
- Single `.esm.js` file
|
||||
- Named exports `run` (callable AsyncGenerator workflow) and `descriptor` (metadata object)
|
||||
- No default export
|
||||
- No dynamic `import()`
|
||||
- All static imports must be Node built-in modules only
|
||||
|
||||
This guarantees the file is self-contained, and its **XXH64 hash** (encoded as Crockford Base32) serves as a globally unique version identifier.
|
||||
|
||||
### Role Descriptor (`export const descriptor`)
|
||||
|
||||
The bundle **must** export a `descriptor` object describing roles for tooling/agent consumption.
|
||||
|
||||
Shape: `{ description: string, roles: Record<string, { description: string, schema: JSONSchema }> }`
|
||||
|
||||
When you register a bundle via `uncaged-workflow add`, the engine imports the module, validates `descriptor`, and writes `{hash}.yaml` next to `{hash}.esm.js` under `bundles/` (same serialized shape as below):
|
||||
|
||||
```yaml
|
||||
description: "Workflow brief introduction"
|
||||
roles:
|
||||
planner:
|
||||
description: "Analyzes the issue and creates a plan"
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
plan:
|
||||
type: string
|
||||
files:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
coder:
|
||||
description: "Implements the plan"
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
diff:
|
||||
type: string
|
||||
```
|
||||
|
||||
Execution uses `run` only; YAML is for tooling and introspection.
|
||||
|
||||
## 3. Storage Layout
|
||||
|
||||
All data lives under `~/.uncaged/workflow/`:
|
||||
|
||||
```
|
||||
~/.uncaged/workflow/
|
||||
├── bundles/ # ESM bundles
|
||||
│ ├── C9NMV6V2TQT81.esm.js # Crockford Base32 of XXH64 hash
|
||||
│ └── C9NMV6V2TQT81.yaml # Role descriptor (from bundle export, at register time)
|
||||
├── logs/ # Thread data, one folder per bundle hash
|
||||
│ └── C9NMV6V2TQT81/
|
||||
│ ├── 01KQXKW18CT8G75T53R8F4G7YG.data.jsonl
|
||||
│ └── 01KQXKW18CT8G75T53R8F4G7YG.info.jsonl
|
||||
└── workflow.yaml # Registry
|
||||
```
|
||||
|
||||
**Not** a git repo. **Not** an npm package. Bundles are self-contained single files.
|
||||
|
||||
### ID Encoding
|
||||
|
||||
All IDs use **Crockford Base32**:
|
||||
- Better readability than Base64
|
||||
- Higher density than hex (shorter filenames)
|
||||
- ULID: 10 chars timestamp (high 2 bits zero-padded for future use) + 16 chars random
|
||||
|
||||
## 4. Registry (`workflow.yaml`)
|
||||
|
||||
```yaml
|
||||
workflows:
|
||||
solve-issue:
|
||||
hash: "C9NMV6V2TQT81"
|
||||
timestamp: 1714963200000
|
||||
history:
|
||||
- hash: "A7BKR3M1NPQ40"
|
||||
timestamp: 1714876800000
|
||||
- hash: "X2FGH8J4KLM56"
|
||||
timestamp: 1714790400000
|
||||
```
|
||||
|
||||
Type:
|
||||
|
||||
```typescript
|
||||
{
|
||||
workflows: Record<string, {
|
||||
hash: string; // Crockford Base32 of current XXH64
|
||||
timestamp: number;
|
||||
history: { hash: string; timestamp: number }[];
|
||||
}>
|
||||
}
|
||||
```
|
||||
|
||||
No concurrency control or timeout settings in the registry — those belong to each workflow/role/adapter.
|
||||
|
||||
## 5. Thread JSONL Format
|
||||
|
||||
### `.data.jsonl` — Thread State
|
||||
|
||||
**Line 1: Start record**
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"name": "solve-issue",
|
||||
"hash": "C9NMV6V2TQT81",
|
||||
"threadId": "01KQXKW18CT8G75T53R8F4G7YG",
|
||||
"parameters": {
|
||||
"prompt": "Fix the login redirect bug in #3",
|
||||
"options": {
|
||||
"maxRounds": 5
|
||||
}
|
||||
},
|
||||
"timestamp": 1714963200000
|
||||
}
|
||||
```
|
||||
|
||||
**Line 2+: Role outputs**
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"role": "planner",
|
||||
"content": "Plan: modify auth middleware...",
|
||||
"meta": { "plan": "...", "files": ["src/auth.ts"] },
|
||||
"timestamp": 1714963201000
|
||||
}
|
||||
```
|
||||
|
||||
### `.info.jsonl` — Debug Log
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"tag": "4KNMR2PX", // 40-bit random, Crockford Base32 (8 chars)
|
||||
"content": "Loading workflow bundle...",
|
||||
"timestamp": 1714963200500
|
||||
}
|
||||
```
|
||||
|
||||
## 6. Execution Model
|
||||
|
||||
- **No daemon.** `uncaged-workflow run <name>` starts a worker process.
|
||||
- Same bundle's threads share one process (memory efficiency).
|
||||
- Process exits automatically when all threads complete.
|
||||
- Thread termination requires **IPC** within the process (not just kill PID).
|
||||
|
||||
## 7. CLI Requirements
|
||||
|
||||
### P1 (Must Have)
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `uncaged-workflow add <name> <file.esm.js> [--types <path>]` | Register a compiled `.esm.js` bundle (descriptor extracted from `export const descriptor`) |
|
||||
| `uncaged-workflow list` | List registered workflows |
|
||||
| `uncaged-workflow show <name>` | Show workflow details |
|
||||
| `uncaged-workflow remove <name>` | Remove a workflow |
|
||||
| `uncaged-workflow run <name> [--prompt] [--max-rounds]` | Start a thread |
|
||||
| `uncaged-workflow threads [name]` | List threads (optionally filter by workflow) |
|
||||
| `uncaged-workflow thread <id>` | Show thread state |
|
||||
| `uncaged-workflow thread rm <id>` | Delete a thread |
|
||||
| `uncaged-workflow ps` | List running threads |
|
||||
| `uncaged-workflow kill <thread-id>` | Terminate a running thread (via IPC) |
|
||||
|
||||
### P2 (Should Have)
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `uncaged-workflow history <name>` | Show version history |
|
||||
| `uncaged-workflow rollback <name> [hash]` | Switch to a previous version |
|
||||
| `uncaged-workflow pause <thread-id>` | Pause a running thread |
|
||||
| `uncaged-workflow resume <thread-id>` | Resume a paused thread |
|
||||
|
||||
### P3 (Nice to Have)
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `uncaged-workflow fork <thread-id> [--from-role <role>]` | Fork from a historical thread state |
|
||||
|
||||
## 8. Role/Moderator Pattern (Helper, Not Contract)
|
||||
|
||||
The bundle contract is the AsyncGenerator from Section 2. The Role + Moderator pattern
|
||||
below is a **convenience helper** for the common case of multi-role workflows with a
|
||||
routing function. It lives in `@uncaged/workflow` as an optional utility.
|
||||
|
||||
### Helper Function
|
||||
|
||||
```typescript
|
||||
function createRoleModerator<M extends RoleMeta>(
|
||||
def: { roles: { [K in keyof M & string]: Role<M[K]> }; moderator: Moderator<M> }
|
||||
): WorkflowFn; // returns (input: ThreadInput, options) => AsyncGenerator
|
||||
```
|
||||
|
||||
Usage in a bundle:
|
||||
|
||||
```typescript
|
||||
import { createRoleModerator, END } from "@uncaged/workflow";
|
||||
|
||||
export const descriptor = {
|
||||
description: "Example multi-role workflow",
|
||||
roles: {
|
||||
planner: { description: "Plans work", schema: {} },
|
||||
coder: { description: "Writes code", schema: {} },
|
||||
},
|
||||
};
|
||||
|
||||
export const run = createRoleModerator({
|
||||
roles: { planner, coder },
|
||||
moderator(ctx) { return ctx.steps.length === 0 ? "planner" : END; },
|
||||
});
|
||||
// Accepts ThreadInput — fork with pre-filled steps works automatically
|
||||
```
|
||||
|
||||
### Supporting Types
|
||||
|
||||
```typescript
|
||||
/** Sentinel values for automaton control flow. */
|
||||
const START = "__start__" as const;
|
||||
const END = "__end__" as const;
|
||||
|
||||
/** Maps role names → their meta types. Single generic drives all inference. */
|
||||
type RoleMeta = Record<string, Record<string, unknown>>;
|
||||
|
||||
/** Typed output of a Role execution. */
|
||||
type RoleResult<Meta> = { content: string; meta: Meta };
|
||||
|
||||
/** Engine start frame: initial prompt + thread identity. */
|
||||
type StartStep = {
|
||||
role: START;
|
||||
content: string; // the user prompt
|
||||
meta: { maxRounds: number; threadId: string };
|
||||
timestamp: number;
|
||||
};
|
||||
|
||||
/** A completed role step in the thread. */
|
||||
type RoleStep<M extends RoleMeta> = {
|
||||
[K in keyof M & string]: { role: K; meta: M[K]; content: string; timestamp: number };
|
||||
}[keyof M & string];
|
||||
|
||||
/** Thread-scoped context passed to roles and moderator. */
|
||||
type ThreadContext<M extends RoleMeta = RoleMeta> = {
|
||||
threadId: string;
|
||||
start: StartStep;
|
||||
steps: RoleStep<M>[];
|
||||
};
|
||||
|
||||
/**
|
||||
* A Role — receives full thread context, returns typed content + meta.
|
||||
* Implementation can be an agent, LLM call, script, HTTP request, etc.
|
||||
*/
|
||||
type Role<Meta> = (ctx: ThreadContext) => Promise<RoleResult<Meta>>;
|
||||
|
||||
/**
|
||||
* An Agent — raw string output interface for LLM/CLI adapters.
|
||||
* Structured meta is extracted by the role's extract layer.
|
||||
*/
|
||||
type AgentFn = (ctx: ThreadContext, systemPrompt: string) => Promise<string>;
|
||||
|
||||
/**
|
||||
* The Moderator — a pure routing function.
|
||||
* Receives the full thread context (start + all prior steps).
|
||||
* On initial call, `steps` is empty.
|
||||
* Returns the next role name or END to terminate.
|
||||
*/
|
||||
type Moderator<M extends RoleMeta> = (ctx: ThreadContext<M>) => (keyof M & string) | END;
|
||||
|
||||
/** Complete workflow definition as authored by users. */
|
||||
type WorkflowDefinition<M extends RoleMeta> = {
|
||||
name: string;
|
||||
roles: { [K in keyof M & string]: Role<M[K]> };
|
||||
moderator: Moderator<M>;
|
||||
};
|
||||
```
|
||||
|
||||
### Execution Flow (when using createRoleModerator)
|
||||
|
||||
```
|
||||
START (prompt) → Moderator → Role A → Moderator → Role B → ... → Moderator → END
|
||||
```
|
||||
|
||||
1. Engine creates a `StartStep` with the user prompt and maxRounds
|
||||
2. Moderator is called with `steps = []`, returns the first role name
|
||||
3. Role executes, appends a `RoleStep` to the thread
|
||||
4. Moderator is called again with updated steps, returns next role or END
|
||||
5. Repeat until END or maxRounds reached
|
||||
|
||||
### Responsibilities
|
||||
|
||||
| Component | Responsibility | Purity |
|
||||
|-----------|---------------|--------|
|
||||
| **Moderator** | Route to next role based on thread state | Pure function, no side effects |
|
||||
| **Role** | Execute a step (call LLM, run script, etc.) | Async, may have side effects |
|
||||
| **AgentFn** | Low-level LLM/CLI invocation adapter | Async, side effects |
|
||||
|
||||
### Key Constraints
|
||||
|
||||
- Moderator is **synchronous and pure** — no I/O, no state mutation
|
||||
- Roles receive the **full thread context** (not just the last message)
|
||||
- Round count = `steps.length`; max rounds in `start.meta.maxRounds`
|
||||
- The `meta` field on each step is **typed per role** via the `RoleMeta` generic
|
||||
|
||||
## 9. Design Decisions & Rationale
|
||||
|
||||
### Why single-file ESM?
|
||||
- Hash = version. No ambiguity.
|
||||
- No dependency hell. Self-contained.
|
||||
- Simple to distribute, store, and verify.
|
||||
|
||||
### Why no daemon?
|
||||
- Unnecessary complexity for process-per-bundle model.
|
||||
- OS process management (systemd, etc.) handles restarts.
|
||||
- IPC within process handles thread lifecycle.
|
||||
|
||||
### Why Crockford Base32?
|
||||
- Case-insensitive, filesystem-safe.
|
||||
- No ambiguous characters (0/O, 1/I/L).
|
||||
- More compact than hex (13 chars for 64-bit vs 16).
|
||||
|
||||
### Why not control concurrency in registry?
|
||||
- Different workflows have different constraints.
|
||||
- Same workflow may allow cross-project concurrency but not intra-project.
|
||||
- Concurrency belongs at workflow/role/adapter level.
|
||||
Reference in New Issue
Block a user