docs: sync all README.md files with current codebase
- Root README: add all 9 packages to table, update architecture diagram,
refresh CLI reference from uwf --help
- New READMEs for 8 packages (cli-workflow, workflow-protocol,
workflow-moderator, workflow-agent-kit, workflow-agent-hermes,
workflow-agent-builtin, workflow-agent-claude-code, workflow-dashboard)
- Updated workflow-util README to match current exports
- All API sections verified against src/index.ts exports
小橘 🍊（NEKO Team）
This commit is contained in:
@@ -0,0 +1,128 @@
|
||||
# @uncaged/cli-workflow
|
||||
|
||||
`uwf` CLI — thread lifecycle, workflow registry, CAS inspection, and setup.
|
||||
|
||||
## Overview
|
||||
|
||||
Layer 4 entry point for the workflow engine. The `uwf` binary orchestrates one step per invocation: load thread head from `threads.yaml`, run the moderator, spawn the configured agent CLI, run extract, append a CAS step node, and update the head pointer (or archive when `$END`).
|
||||
|
||||
This package has no library `src/index.ts` — it is consumed as a CLI binary only.
|
||||
|
||||
**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`, `@uncaged/workflow-agent-kit`, `@uncaged/workflow-moderator`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`, `commander`, `dotenv`, `yaml`
|
||||
|
||||
## Installation
|
||||
|
||||
Included as the `uwf` binary when you install `@uncaged/cli-workflow`:
|
||||
|
||||
```bash
|
||||
bun add -g @uncaged/cli-workflow
|
||||
# or from the monorepo:
|
||||
bun link packages/cli-workflow
|
||||
```
|
||||
|
||||
## CLI Usage
|
||||
|
||||
### Global options
|
||||
|
||||
```
|
||||
-V, --version Show version
|
||||
--format <json|yaml> Output format (default: json)
|
||||
-h, --help Show help
|
||||
```
|
||||
|
||||
### Thread
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `uwf thread start <workflow> -p <prompt>` | Create a thread without executing |
|
||||
| `uwf thread step <thread-id> [--agent <cmd>] [-c <count>]` | Execute one or more moderator→agent→extract cycles |
|
||||
| `uwf thread show <thread-id>` | Show thread head pointer |
|
||||
| `uwf thread list [--all]` | List active threads (`--all` includes archived) |
|
||||
| `uwf thread steps <thread-id>` | List all steps chronologically |
|
||||
| `uwf thread read <thread-id> [--quota N] [--before <hash>] [--start]` | Render thread as readable markdown |
|
||||
| `uwf thread fork <step-hash>` | Fork from a specific step |
|
||||
| `uwf thread step-details <step-hash>` | Dump full detail node as YAML |
|
||||
| `uwf thread kill <thread-id>` | Terminate and archive |
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
uwf thread start solve-issue -p "Fix the login redirect bug"
|
||||
uwf thread step 01ARZ3NDEKTSV4RRFFQ69G5FAV
|
||||
uwf thread step 01ARZ3NDEKTSV4RRFFQ69G5FAV -c 3 --agent uwf-builtin
|
||||
uwf thread read 01ARZ3NDEKTSV4RRFFQ69G5FAV --quota 8000
|
||||
```
|
||||
|
||||
### Workflow
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `uwf workflow put <file.yaml>` | Register a workflow from YAML |
|
||||
| `uwf workflow show <name-or-hash>` | Show workflow definition |
|
||||
| `uwf workflow list` | List registered workflows |
|
||||
|
||||
### CAS
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `uwf cas get <hash> [--timestamp]` | Read a CAS node |
|
||||
| `uwf cas put <type-hash> <data>` | Store a node, print hash |
|
||||
| `uwf cas put-text <text>` | Store plain text, print hash |
|
||||
| `uwf cas has <hash>` | Check existence |
|
||||
| `uwf cas refs <hash>` | List direct references |
|
||||
| `uwf cas walk <hash>` | Recursive traversal |
|
||||
| `uwf cas reindex` | Rebuild type index |
|
||||
| `uwf cas schema list` | List registered schemas |
|
||||
| `uwf cas schema get <hash>` | Show a schema |
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
uwf setup
|
||||
uwf setup --provider openai --base-url https://api.openai.com/v1 \
|
||||
--api-key sk-... --model gpt-4o --agent hermes
|
||||
```
|
||||
|
||||
Config: `~/.uncaged/workflow/config.yaml`. API keys: `~/.uncaged/workflow/.env`.
|
||||
|
||||
### Skill
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `uwf skill cli` | Print markdown reference of all uwf commands (for agent skills) |
|
||||
|
||||
### Log
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `uwf log list` | List log files with sizes |
|
||||
| `uwf log show [--thread <id>] [--process <pid>] [--date YYYY-MM-DD]` | Show filtered log entries |
|
||||
| `uwf log clean [--before YYYY-MM-DD]` | Delete old log files |
|
||||
|
||||
## Internal Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── cli.ts Commander entrypoint, command registration
|
||||
├── format.ts JSON/YAML output formatting
|
||||
├── store.ts CAS store + registry initialization
|
||||
├── validate.ts Workflow YAML validation
|
||||
├── schemas.ts CLI-local schema registration
|
||||
└── commands/
|
||||
├── thread.ts Thread lifecycle and step execution
|
||||
├── workflow.ts Workflow registry (put/show/list)
|
||||
├── cas.ts CAS inspection and schema ops
|
||||
├── setup.ts Interactive/non-interactive setup
|
||||
├── skill.ts Built-in skill references
|
||||
└── log.ts Process debug log management
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `~/.uncaged/workflow/config.yaml` | Providers, models, default agent |
|
||||
| `~/.uncaged/workflow/.env` | API keys (referenced by `apiKeyEnv` in config) |
|
||||
| `~/.uncaged/workflow/registry.yaml` | Workflow name → CAS hash |
|
||||
| `~/.uncaged/workflow/threads.yaml` | Active thread head pointers |
|
||||
| `~/.uncaged/workflow/cas/` | Content-addressed node storage |
|
||||
@@ -0,0 +1,141 @@
|
||||
# @uncaged/workflow-agent-builtin
|
||||
|
||||
`uwf-builtin` agent — built-in LLM agent with file read/write and shell tools.
|
||||
|
||||
## Overview
|
||||
|
||||
Layer 3 agent implementation. Runs an OpenAI-compatible chat completion loop with built-in tools (`read_file`, `write_file`, `run_command`). Uses the configured provider/model from `config.yaml`. Produces frontmatter markdown output and stores turn-by-turn session detail in CAS.
|
||||
|
||||
Useful when you want a self-contained agent without an external CLI like Hermes or Claude Code.
|
||||
|
||||
**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-agent-kit`, `@uncaged/workflow-util`
|
||||
|
||||
## Installation
|
||||
|
||||
Included as the `uwf-builtin` binary when you install `@uncaged/workflow-agent-builtin`:
|
||||
|
||||
```bash
|
||||
bun add -g @uncaged/workflow-agent-builtin
|
||||
```
|
||||
|
||||
## CLI Usage
|
||||
|
||||
Invoked by `uwf thread step`:
|
||||
|
||||
```bash
|
||||
uwf-builtin <thread-id> <role>
|
||||
```
|
||||
|
||||
Configure as default agent:
|
||||
|
||||
```bash
|
||||
uwf setup --agent builtin
|
||||
```
|
||||
|
||||
Override per step:
|
||||
|
||||
```bash
|
||||
uwf thread step <thread-id> --agent uwf-builtin
|
||||
```
|
||||
|
||||
Environment variables set by the engine:
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `UWF_EDGE_PROMPT` | Moderator edge instruction for this step |
|
||||
|
||||
## API
|
||||
|
||||
All exports come from `src/index.ts`.
|
||||
|
||||
### Agent factory
|
||||
|
||||
```typescript
|
||||
function createBuiltinAgent(): () => Promise<void>
|
||||
function buildBuiltinMessages(ctx: AgentContext): ChatMessage[]
|
||||
```
|
||||
|
||||
### LLM loop
|
||||
|
||||
```typescript
|
||||
const BUILTIN_MAX_TURNS = 30;
|
||||
const BUILTIN_CONTINUE_MAX_TURNS = 5;
|
||||
|
||||
function runBuiltinLoop(/* options: RunBuiltinLoopOptions */): Promise<RunBuiltinLoopResult>
|
||||
function chatCompletionWithTools(
|
||||
provider: ResolvedLlmProvider,
|
||||
messages: ChatMessage[],
|
||||
tools: OpenAiToolDefinition[],
|
||||
): Promise<LlmAssistantResponse>
|
||||
```
|
||||
|
||||
`RunBuiltinLoopOptions` and `RunBuiltinLoopResult` are internal to `loop.ts` and not re-exported from `index.ts`.
|
||||
|
||||
### Tools
|
||||
|
||||
```typescript
|
||||
function getBuiltinTools(): readonly BuiltinTool[]
|
||||
function executeBuiltinTool(
|
||||
name: string,
|
||||
args: Record<string, unknown>,
|
||||
ctx: ToolContext,
|
||||
): Promise<string>
|
||||
```
|
||||
|
||||
### Session and detail
|
||||
|
||||
```typescript
|
||||
function initSessionDir(storageRoot: string): Promise<void>
|
||||
function appendSessionTurn(storageRoot: string, sessionId: string, turn: BuiltinTurnPayload): Promise<void>
|
||||
function readSessionTurns(storageRoot: string, sessionId: string): Promise<BuiltinTurnPayload[]>
|
||||
function removeSession(storageRoot: string, sessionId: string): Promise<void>
|
||||
function registerBuiltinSchemas(store: Store): Promise<BuiltinSchemaHashes>
|
||||
function storeBuiltinDetail(store: Store, payload: BuiltinDetailPayload): Promise<string>
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
```typescript
|
||||
type ChatMessage = /* system | user | assistant | tool */;
|
||||
type LlmAssistantResponse = { content: string | null; toolCalls: LlmToolCall[] | null };
|
||||
type LlmToolCall = { id: string; name: string; arguments: string };
|
||||
type BuiltinTool = { name: string; description: string; parameters: Record<string, unknown> };
|
||||
type ToolContext = { cwd: string; storageRoot: string };
|
||||
type BuiltinDetailPayload = { /* session turns, model, timestamps */ };
|
||||
type BuiltinLoopTurn = { /* single loop iteration record */ };
|
||||
type BuiltinToolCallRecord = { /* tool call audit */ };
|
||||
type BuiltinToolResultRecord = { /* tool result audit */ };
|
||||
type BuiltinTurnPayload = { /* persisted turn */ };
|
||||
```
|
||||
|
||||
## Internal Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts
|
||||
├── cli.ts Binary entrypoint
|
||||
├── agent.ts createBuiltinAgent
|
||||
├── loop.ts Multi-turn LLM + tool loop
|
||||
├── prompt.ts buildBuiltinMessages
|
||||
├── session.ts Session directory persistence
|
||||
├── detail.ts CAS detail node storage
|
||||
├── schemas.ts Builtin CAS schemas
|
||||
├── types.ts Detail and turn payload types
|
||||
├── llm/
|
||||
│ ├── index.ts
|
||||
│ ├── llm.ts chatCompletionWithTools
|
||||
│ └── types.ts ChatMessage, LlmToolCall, etc.
|
||||
└── tools/
|
||||
├── index.ts getBuiltinTools, executeBuiltinTool
|
||||
├── read-file.ts
|
||||
├── write-file.ts
|
||||
├── run-command.ts
|
||||
├── path.ts
|
||||
└── types.ts
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Requires a configured OpenAI-compatible provider and model in `~/.uncaged/workflow/config.yaml` (via `uwf setup`). API keys are loaded from `~/.uncaged/workflow/.env`.
|
||||
|
||||
Tools run with the current working directory as `ToolContext.cwd` (typically the directory where `uwf thread step` was invoked).
|
||||
@@ -0,0 +1,91 @@
|
||||
# @uncaged/workflow-agent-claude-code
|
||||
|
||||
`uwf-claude-code` agent — spawns the Claude Code CLI and captures session detail.
|
||||
|
||||
## Overview
|
||||
|
||||
Layer 3 agent implementation. Spawns the `claude` CLI with a composed system prompt (role definition, task, prior steps, edge prompt). Parses stream or JSON stdout, caches session IDs for multi-turn continuation, and stores raw output plus structured detail in CAS.
|
||||
|
||||
**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-agent-kit`
|
||||
|
||||
## Installation
|
||||
|
||||
Included as the `uwf-claude-code` binary when you install `@uncaged/workflow-agent-claude-code`:
|
||||
|
||||
```bash
|
||||
bun add -g @uncaged/workflow-agent-claude-code
|
||||
```
|
||||
|
||||
Requires the `claude` CLI on `PATH`.
|
||||
|
||||
## CLI Usage
|
||||
|
||||
Invoked by `uwf thread step`:
|
||||
|
||||
```bash
|
||||
uwf-claude-code <thread-id> <role>
|
||||
```
|
||||
|
||||
Configure or override the agent:
|
||||
|
||||
```bash
|
||||
uwf setup --agent claude-code
|
||||
uwf thread step <thread-id> --agent uwf-claude-code
|
||||
```
|
||||
|
||||
Environment variables set by the engine:
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `UWF_EDGE_PROMPT` | Moderator edge instruction for this step |
|
||||
|
||||
## API
|
||||
|
||||
All exports come from `src/index.ts`.
|
||||
|
||||
### Agent factory
|
||||
|
||||
```typescript
|
||||
function createClaudeCodeAgent(): () => Promise<void>
|
||||
function buildClaudeCodePrompt(ctx: AgentContext): string
|
||||
```
|
||||
|
||||
### Session detail
|
||||
|
||||
```typescript
|
||||
function parseClaudeCodeStreamOutput(stdout: string): ClaudeCodeParsedResult | null
|
||||
function parseClaudeCodeJsonOutput(stdout: string): ClaudeCodeParsedResult | null
|
||||
function storeClaudeCodeDetail(
|
||||
store: Store,
|
||||
parsed: ClaudeCodeParsedResult,
|
||||
sessionId: string,
|
||||
): Promise<string>
|
||||
function storeClaudeCodeRawOutput(store: Store, rawOutput: string): Promise<string>
|
||||
```
|
||||
|
||||
## Usage (library)
|
||||
|
||||
```typescript
|
||||
import { createClaudeCodeAgent, buildClaudeCodePrompt } from "@uncaged/workflow-agent-claude-code";
|
||||
|
||||
const main = createClaudeCodeAgent();
|
||||
void main();
|
||||
```
|
||||
|
||||
## Internal Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts
|
||||
├── cli.ts Binary entrypoint
|
||||
├── claude-code.ts createClaudeCodeAgent, buildClaudeCodePrompt, spawn logic
|
||||
├── session-detail.ts Parse stdout, store CAS detail nodes
|
||||
├── schemas.ts Claude Code detail CAS schemas
|
||||
└── types.ts ClaudeCodeParsedResult, message shapes
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Uses session caching from `@uncaged/workflow-agent-kit` (`getCachedSessionId` / `setCachedSessionId`). No separate config file — relies on the Claude Code CLI's own authentication.
|
||||
|
||||
Maximum turns per invocation: 90 (constant in `claude-code.ts`).
|
||||
@@ -0,0 +1,90 @@
|
||||
# @uncaged/workflow-agent-hermes
|
||||
|
||||
`uwf-hermes` agent — spawns Hermes chat via ACP and captures session detail.
|
||||
|
||||
## Overview
|
||||
|
||||
Layer 3 agent implementation. Wraps the Hermes CLI using the Agent Client Protocol (ACP). On first visit to a role it sends a composed prompt (role definition, task, history, edge prompt); on continuation it resumes the cached session. Session transcripts and raw output are stored as CAS detail nodes.
|
||||
|
||||
**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-agent-kit`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`
|
||||
|
||||
## Installation
|
||||
|
||||
Included as the `uwf-hermes` binary when you install `@uncaged/workflow-agent-hermes`:
|
||||
|
||||
```bash
|
||||
bun add -g @uncaged/workflow-agent-hermes
|
||||
```
|
||||
|
||||
Requires the `hermes` CLI on `PATH`.
|
||||
|
||||
## CLI Usage
|
||||
|
||||
Invoked by `uwf thread step` (not typically run directly):
|
||||
|
||||
```bash
|
||||
uwf-hermes <thread-id> <role>
|
||||
```
|
||||
|
||||
Environment variables set by the engine:
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `UWF_EDGE_PROMPT` | Moderator edge instruction for this step |
|
||||
|
||||
Configure as the default agent via `uwf setup --agent hermes`.
|
||||
|
||||
Override per step:
|
||||
|
||||
```bash
|
||||
uwf thread step <thread-id> --agent uwf-hermes
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
All exports come from `src/index.ts`.
|
||||
|
||||
### Agent factory
|
||||
|
||||
```typescript
|
||||
function createHermesAgent(): () => Promise<void>
|
||||
function buildHermesPrompt(ctx: AgentContext): string
|
||||
```
|
||||
|
||||
### ACP client
|
||||
|
||||
```typescript
|
||||
class HermesAcpClient {
|
||||
// Spawns hermes, handles JSON-RPC over stdio
|
||||
}
|
||||
```
|
||||
|
||||
## Usage (library)
|
||||
|
||||
```typescript
|
||||
import { createHermesAgent, buildHermesPrompt } from "@uncaged/workflow-agent-hermes";
|
||||
|
||||
// CLI entry (src/cli.ts):
|
||||
const main = createHermesAgent();
|
||||
void main();
|
||||
```
|
||||
|
||||
## Internal Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts
|
||||
├── cli.ts Binary entrypoint
|
||||
├── hermes.ts createHermesAgent, buildHermesPrompt
|
||||
├── acp-client.ts HermesAcpClient — ACP JSON-RPC over stdio
|
||||
├── session-cache.ts Session ID cache (re-exports kit helpers + isResumeDisabled)
|
||||
├── session-detail.ts Parse Hermes session JSON, store CAS detail nodes
|
||||
├── schemas.ts Hermes detail CAS schemas
|
||||
└── types.ts HermesSessionJson, HermesSessionMessage
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Uses workflow config from `~/.uncaged/workflow/config.yaml` (via agent-kit). Hermes session files are stored under the workflow storage root (see `session-detail.ts`).
|
||||
|
||||
Set `UWF_HERMES_NO_RESUME=1` to disable session resume (see `isResumeDisabled` in `session-cache.ts`).
|
||||
@@ -0,0 +1,182 @@
|
||||
# @uncaged/workflow-agent-kit
|
||||
|
||||
Agent framework — `createAgent` factory, context builder, frontmatter fast-path, and LLM extract pipeline.
|
||||
|
||||
## Overview
|
||||
|
||||
Layer 2 agent framework. Provides the standard entrypoint for all agent CLIs: parse `<thread-id> <role>` from argv, load thread/workflow context from CAS, invoke the agent's `run`/`continue` functions, validate output via frontmatter fast-path or LLM extract, and write a `StepNodePayload` to CAS.
|
||||
|
||||
Also exports prompt builders, config/storage helpers, and session ID caching for multi-turn agents.
|
||||
|
||||
**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`, `dotenv`, `yaml`
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
bun add @uncaged/workflow-agent-kit
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
All exports come from `src/index.ts`.
|
||||
|
||||
### Agent factory
|
||||
|
||||
```typescript
|
||||
function createAgent(options: AgentOptions): () => Promise<void>
|
||||
|
||||
type AgentOptions = {
|
||||
name: string;
|
||||
run: AgentRunFn;
|
||||
continue: AgentContinueFn;
|
||||
};
|
||||
|
||||
type AgentRunFn = (ctx: AgentContext) => Promise<AgentRunResult>;
|
||||
type AgentContinueFn = (
|
||||
sessionId: string,
|
||||
message: string,
|
||||
store: AgentContext["store"],
|
||||
) => Promise<AgentRunResult>;
|
||||
|
||||
type AgentRunResult = {
|
||||
output: string;
|
||||
detailHash: string;
|
||||
sessionId: string;
|
||||
};
|
||||
```
|
||||
|
||||
Agent CLIs call `createAgent(...)` and invoke the returned function as `main()`.
|
||||
|
||||
### Context
|
||||
|
||||
```typescript
|
||||
function buildContext(threadId: ThreadId, role: string): Promise<AgentContext>
|
||||
function buildContextWithMeta(
|
||||
threadId: ThreadId,
|
||||
role: string,
|
||||
): Promise<AgentContext & { meta: BuildContextMeta }>
|
||||
|
||||
type AgentContext = ModeratorContext & {
|
||||
threadId: ThreadId;
|
||||
role: string;
|
||||
store: Store;
|
||||
workflow: WorkflowPayload;
|
||||
outputFormatInstruction: string;
|
||||
edgePrompt: string;
|
||||
isFirstVisit: boolean;
|
||||
};
|
||||
|
||||
type BuildContextMeta = {
|
||||
storageRoot: string;
|
||||
store: Store;
|
||||
schemas: AgentStore["schemas"];
|
||||
headHash: CasRef;
|
||||
chain: ChainState;
|
||||
};
|
||||
```
|
||||
|
||||
Requires `UWF_EDGE_PROMPT` in the environment (set by `uwf thread step`).
|
||||
|
||||
### Prompt builders
|
||||
|
||||
```typescript
|
||||
function buildRolePrompt(role: RoleDefinition): string
|
||||
function buildOutputFormatInstruction(schema: JSONSchema): string
|
||||
function buildContinuationPrompt(
|
||||
ctx: AgentContext,
|
||||
priorOutput: string,
|
||||
instruction: string,
|
||||
): string
|
||||
```
|
||||
|
||||
### Extract pipeline
|
||||
|
||||
```typescript
|
||||
function resolveExtractModelAlias(config: WorkflowConfig): ModelAlias
|
||||
function resolveModel(config: WorkflowConfig, alias: ModelAlias): ResolvedLlmProvider
|
||||
function extract(
|
||||
rawOutput: string,
|
||||
outputSchema: CasRef,
|
||||
config: WorkflowConfig,
|
||||
): Promise<ExtractResult>
|
||||
|
||||
type ResolvedLlmProvider = { baseUrl: string; apiKey: string; model: string };
|
||||
type ExtractResult = { value: unknown; hash: CasRef };
|
||||
```
|
||||
|
||||
### Frontmatter fast-path
|
||||
|
||||
```typescript
|
||||
function tryFrontmatterFastPath(
|
||||
rawOutput: string,
|
||||
outputSchema: CasRef,
|
||||
store: Store,
|
||||
): Promise<FrontmatterFastPathResult | null>
|
||||
|
||||
type FrontmatterFastPathResult = { body: string; outputHash: CasRef };
|
||||
```
|
||||
|
||||
### Session cache
|
||||
|
||||
```typescript
|
||||
function getCachedSessionId(threadId: ThreadId, role: string): Promise<string | null>
|
||||
function setCachedSessionId(
|
||||
threadId: ThreadId,
|
||||
role: string,
|
||||
sessionId: string,
|
||||
): Promise<void>
|
||||
```
|
||||
|
||||
### Config and storage
|
||||
|
||||
```typescript
|
||||
function getConfigPath(storageRoot: string): string
|
||||
function getEnvPath(storageRoot: string): string
|
||||
function resolveStorageRoot(): string
|
||||
function loadWorkflowConfig(storageRoot: string): Promise<WorkflowConfig>
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```typescript
|
||||
import { createAgent, buildRolePrompt } from "@uncaged/workflow-agent-kit";
|
||||
import type { AgentContext, AgentRunResult } from "@uncaged/workflow-agent-kit";
|
||||
|
||||
async function run(ctx: AgentContext): Promise<AgentRunResult> {
|
||||
const prompt = buildRolePrompt(ctx.workflow.roles[ctx.role]!);
|
||||
// ... spawn external process, capture output ...
|
||||
return { output: markdown, detailHash: "...", sessionId: "..." };
|
||||
}
|
||||
|
||||
async function continueSession(
|
||||
sessionId: string,
|
||||
message: string,
|
||||
): Promise<AgentRunResult> {
|
||||
// ... continue multi-turn session ...
|
||||
return { output: markdown, detailHash: "...", sessionId };
|
||||
}
|
||||
|
||||
export const main = createAgent({ name: "my-agent", run, continue: continueSession });
|
||||
```
|
||||
|
||||
## Internal Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts
|
||||
├── run.ts createAgent entrypoint
|
||||
├── context.ts Thread chain walk, AgentContext builder
|
||||
├── extract.ts LLM structured extract fallback
|
||||
├── frontmatter.ts Frontmatter fast-path validation
|
||||
├── build-role-prompt.ts Role definition → prompt text
|
||||
├── build-output-format-instruction.ts
|
||||
├── build-continuation-prompt.ts
|
||||
├── session-cache.ts Per-thread/session ID persistence
|
||||
├── storage.ts CAS store, config, threads index
|
||||
├── schemas.ts Agent CAS schema registration
|
||||
└── types.ts AgentContext, AgentOptions, etc.
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Reads `config.yaml` and `.env` from the workflow storage root (`~/.uncaged/workflow` by default). See `@uncaged/workflow-protocol` for `WorkflowConfig` shape. Set via `uwf setup`.
|
||||
@@ -0,0 +1,84 @@
|
||||
# @uncaged/workflow-dashboard
|
||||
|
||||
Web graph editor for visualizing and editing workflow YAML definitions.
|
||||
|
||||
## Overview
|
||||
|
||||
A private alpha web app (not part of the runtime engine stack). Provides a React + `@xyflow/react` canvas for editing workflow roles, conditions, and graph transitions. Uses `@uncaged/workflow-protocol` types for validation and YAML round-tripping.
|
||||
|
||||
Planned integration: local `uwf connect` over WebSocket to sync YAML between CLI and the browser editor. The REST API and Elysia backend are currently stubs for development.
|
||||
|
||||
**Dependencies:** `@uncaged/workflow-protocol`, `@xyflow/react`, React 19, react-router v7, Vite 8, Tailwind CSS v4, Elysia
|
||||
|
||||
## Installation
|
||||
|
||||
Monorepo-only ( `"private": true` ). Not published to npm.
|
||||
|
||||
```bash
|
||||
cd packages/workflow-dashboard
|
||||
bun install --no-cache
|
||||
```
|
||||
|
||||
## CLI Usage
|
||||
|
||||
Start the Vite dev server (port 3000):
|
||||
|
||||
```bash
|
||||
cd packages/workflow-dashboard
|
||||
bun run dev
|
||||
```
|
||||
|
||||
Build for production:
|
||||
|
||||
```bash
|
||||
bun run build
|
||||
```
|
||||
|
||||
Open `http://localhost:3000` in a browser.
|
||||
|
||||
## Internal Structure
|
||||
|
||||
```
|
||||
workflow-dashboard/
|
||||
├── server.ts Vite dev server entry (port 3000)
|
||||
├── vite.config.ts Vite + React + Tailwind + Elysia plugin
|
||||
├── vite-dev.ts Custom Vite plugin
|
||||
├── index.html
|
||||
├── components.json shadcn configuration
|
||||
├── server/
|
||||
│ ├── api.ts Elysia REST API (health + workflow CRUD stub)
|
||||
│ └── workflow.ts Workflow file read/write + format conversion
|
||||
└── src/
|
||||
├── main.tsx React DOM entry
|
||||
├── app.tsx Root layout
|
||||
├── router.tsx Hash-mode routes
|
||||
├── index.css
|
||||
├── lib/utils.ts Tailwind cn() helper
|
||||
├── components/ui/ shadcn components (button, card, dialog, input, …)
|
||||
├── pages/
|
||||
│ ├── home.tsx Workflow list
|
||||
│ ├── detail.tsx Workflow detail view
|
||||
│ └── editor.tsx Full editor page
|
||||
└── editor/ Core graph editor
|
||||
├── flow.tsx FlowEditor component
|
||||
├── context.tsx State (useSyncExternalStore + Immer)
|
||||
├── injection.ts DI container
|
||||
├── type.ts Internal editor types
|
||||
├── model/ Node/edge state model
|
||||
├── nodes/ Start, role, end node components
|
||||
├── edges/ Conditional edge rendering
|
||||
├── panel/ Toolbar, add/edit panels
|
||||
├── trans/ YAML ↔ graph conversion (trans-in, trans-out, validate)
|
||||
├── layout/ Auto-layout
|
||||
└── utils/ Event helpers, click-outside hook
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
| Setting | Default | Notes |
|
||||
|---------|---------|-------|
|
||||
| Dev server port | `3000` | Set in `server.ts` |
|
||||
| Workflow storage (dev) | `tmp/workflow/` | YAML files during development |
|
||||
| Path alias | `@/` → `src/` | Configured in `vite.config.ts` |
|
||||
|
||||
No library API — this package is an application, not importable as a module.
|
||||
@@ -0,0 +1,60 @@
|
||||
# @uncaged/workflow-moderator
|
||||
|
||||
JSONata-based graph evaluator — determines the next role or `$END` with zero LLM cost.
|
||||
|
||||
## Overview
|
||||
|
||||
The moderator (Layer 1) walks the workflow graph from the current role. For each outgoing transition it evaluates an optional JSONata condition against `ModeratorContext` (start prompt + prior step outputs). The first truthy transition wins; its target role and edge prompt are returned. When no transition matches, the workflow ends (`$END`).
|
||||
|
||||
**Dependencies:** `@uncaged/workflow-protocol`, `jsonata`
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
bun add @uncaged/workflow-moderator
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### Functions
|
||||
|
||||
```typescript
|
||||
function evaluate(
|
||||
workflow: WorkflowPayload,
|
||||
context: ModeratorContext,
|
||||
): Promise<Result<EvaluateResult, Error>>
|
||||
```
|
||||
|
||||
Returns `{ ok: true, value: { role, prompt } }` where `role` is the next role name or `"$END"`, and `prompt` is the edge instruction for the agent.
|
||||
|
||||
### Types
|
||||
|
||||
```typescript
|
||||
type EvaluateResult = {
|
||||
role: string;
|
||||
prompt: string;
|
||||
};
|
||||
```
|
||||
|
||||
The `Result<T, E>` type is local to this package (`{ ok: true; value: T } | { ok: false; error: E }`), not re-exported from `index.ts`.
|
||||
|
||||
## Usage
|
||||
|
||||
```typescript
|
||||
import { evaluate } from "@uncaged/workflow-moderator";
|
||||
import type { ModeratorContext, WorkflowPayload } from "@uncaged/workflow-protocol";
|
||||
|
||||
const result = await evaluate(workflow, context);
|
||||
if (result.ok && result.value.role !== "$END") {
|
||||
console.log(`Next role: ${result.value.role}, prompt: ${result.value.prompt}`);
|
||||
}
|
||||
```
|
||||
|
||||
## Internal Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts Public exports
|
||||
├── evaluate.ts Graph walk + JSONata condition evaluation
|
||||
└── types.ts EvaluateResult, Result
|
||||
```
|
||||
@@ -0,0 +1,193 @@
|
||||
# @uncaged/workflow-protocol
|
||||
|
||||
Shared TypeScript types and JSON Schema constants for the workflow engine.
|
||||
|
||||
## Overview
|
||||
|
||||
This is the contract layer (Layer 0). It defines `WorkflowPayload`, thread node payloads, moderator context, CLI output shapes, and configuration types used across every other package. It has no runtime logic beyond exporting schema objects from `@uncaged/json-cas`.
|
||||
|
||||
**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
bun add @uncaged/workflow-protocol
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
All exports come from `src/index.ts`.
|
||||
|
||||
### JSON Schema constants
|
||||
|
||||
```typescript
|
||||
START_NODE_SCHEMA: JSONSchema
|
||||
STEP_NODE_SCHEMA: JSONSchema
|
||||
WORKFLOW_SCHEMA: JSONSchema
|
||||
```
|
||||
|
||||
### Core identifiers
|
||||
|
||||
```typescript
|
||||
type CasRef = string // XXH64 hash, 13-char Crockford Base32
|
||||
type ThreadId = string // ULID, 26-char Crockford Base32
|
||||
type WorkflowName = string
|
||||
type RoleName = string
|
||||
```
|
||||
|
||||
### Workflow definition
|
||||
|
||||
```typescript
|
||||
type RoleDefinition = {
|
||||
description: string;
|
||||
goal: string;
|
||||
capabilities: string[];
|
||||
procedure: string;
|
||||
output: string;
|
||||
frontmatter: CasRef;
|
||||
};
|
||||
|
||||
type Transition = {
|
||||
role: string;
|
||||
condition: string | null;
|
||||
prompt: string;
|
||||
};
|
||||
|
||||
type ConditionDefinition = {
|
||||
description: string;
|
||||
expression: string;
|
||||
};
|
||||
|
||||
type WorkflowPayload = {
|
||||
name: string;
|
||||
description: string;
|
||||
roles: Record<string, RoleDefinition>;
|
||||
conditions: Record<string, ConditionDefinition>;
|
||||
graph: Record<string, Transition[]>;
|
||||
};
|
||||
```
|
||||
|
||||
### Thread nodes
|
||||
|
||||
```typescript
|
||||
type StepRecord = {
|
||||
role: string;
|
||||
output: CasRef;
|
||||
detail: CasRef;
|
||||
agent: string;
|
||||
edgePrompt: string;
|
||||
};
|
||||
|
||||
type StartNodePayload = {
|
||||
workflow: CasRef;
|
||||
prompt: string;
|
||||
};
|
||||
|
||||
type StepNodePayload = StepRecord & {
|
||||
start: CasRef;
|
||||
prev: CasRef | null;
|
||||
};
|
||||
```
|
||||
|
||||
### Moderator context
|
||||
|
||||
```typescript
|
||||
type StepContext = Omit<StepRecord, "output"> & { output: unknown };
|
||||
|
||||
type ModeratorContext = {
|
||||
start: StartNodePayload;
|
||||
steps: StepContext[];
|
||||
};
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
```typescript
|
||||
type ProviderAlias = string;
|
||||
type ModelAlias = string;
|
||||
type AgentAlias = string;
|
||||
|
||||
type ProviderConfig = { baseUrl: string; apiKeyEnv: string };
|
||||
type ModelConfig = {
|
||||
provider: ProviderAlias;
|
||||
name: string;
|
||||
};
|
||||
|
||||
type AgentConfig = {
|
||||
command: string;
|
||||
args: string[];
|
||||
};
|
||||
|
||||
type WorkflowConfig = {
|
||||
providers: Record<ProviderAlias, ProviderConfig>;
|
||||
models: Record<ModelAlias, ModelConfig>;
|
||||
agents: Record<AgentAlias, AgentConfig>;
|
||||
defaultAgent: AgentAlias;
|
||||
agentOverrides: Record<WorkflowName, Record<RoleName, AgentAlias>> | null;
|
||||
defaultModel: ModelAlias;
|
||||
modelOverrides: Record<Scenario, ModelAlias> | null;
|
||||
};
|
||||
```
|
||||
|
||||
### CLI output types
|
||||
|
||||
```typescript
|
||||
type StartOutput = { workflow: CasRef; thread: ThreadId };
|
||||
|
||||
type StepOutput = {
|
||||
workflow: CasRef;
|
||||
thread: ThreadId;
|
||||
head: CasRef;
|
||||
done: boolean;
|
||||
};
|
||||
|
||||
type StepEntry = {
|
||||
hash: CasRef;
|
||||
role: string;
|
||||
output: unknown;
|
||||
detail: CasRef;
|
||||
agent: string;
|
||||
timestamp: number;
|
||||
};
|
||||
|
||||
type StartEntry = {
|
||||
hash: CasRef;
|
||||
workflow: CasRef;
|
||||
prompt: string;
|
||||
timestamp: number;
|
||||
};
|
||||
|
||||
type ThreadStepsOutput = {
|
||||
thread: ThreadId;
|
||||
workflow: CasRef;
|
||||
steps: [StartEntry, ...StepEntry[]];
|
||||
};
|
||||
|
||||
type ThreadForkOutput = {
|
||||
thread: ThreadId;
|
||||
forkedFrom: { step: CasRef };
|
||||
};
|
||||
|
||||
type ThreadListItem = {
|
||||
thread: ThreadId;
|
||||
workflow: CasRef;
|
||||
head: CasRef;
|
||||
};
|
||||
|
||||
type ThreadsIndex = Record<ThreadId, CasRef>;
|
||||
|
||||
type Scenario = string;
|
||||
```
|
||||
|
||||
## Internal Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts Public re-exports
|
||||
├── types.ts All type definitions
|
||||
└── schemas.ts START_NODE_SCHEMA, STEP_NODE_SCHEMA, WORKFLOW_SCHEMA
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
This package defines `WorkflowConfig` types only. Runtime config loading lives in `@uncaged/workflow-agent-kit` (`loadWorkflowConfig`).
|
||||
@@ -1,32 +1,145 @@
|
||||
# @uncaged/workflow-util
|
||||
|
||||
Shared utilities: encoding, IDs, logging, storage paths, and ref-field normalization.
|
||||
Shared utilities: encoding, IDs, logging, frontmatter parsing, storage paths, and CLI reference generation.
|
||||
|
||||
## What This Package Does
|
||||
## Overview
|
||||
|
||||
It provides filesystem-safe Base32 and ULID generation, the structured logger used across packages, helpers for the default workflow data directory and global CAS path, and utilities to merge/normalize `refs` on steps. It re-exports `ok`/`err` from protocol for convenience.
|
||||
Layer 1 shared infrastructure used across CLI, agent-kit, and agent packages. Provides Crockford Base32 encoding, ULID generation, structured logging with fixed 8-char tags, frontmatter markdown parsing/validation, process-level debug logging, and helpers for the default workflow data directory.
|
||||
|
||||
## Key Exports
|
||||
**Dependencies:** none (standalone)
|
||||
|
||||
From `src/index.ts`:
|
||||
## Installation
|
||||
|
||||
- **Base32:** `CROCKFORD_BASE32_ALPHABET`, `decodeCrockfordBase32Bits`, `decodeCrockfordToUint64`, `encodeCrockfordBase32Bits`, `encodeUint64AsCrockford`
|
||||
- **Logger:** `createLogger`
|
||||
- **Refs:** `mergeRefsWithContentHash`, `normalizeRefsField`
|
||||
- **Result:** `ok`, `err` (from `@uncaged/workflow-protocol`)
|
||||
- **Paths:** `getDefaultWorkflowStorageRoot`, `getGlobalCasDir`
|
||||
- **ULID:** `generateUlid`
|
||||
- **Types:** `CreateLoggerOptions`, `LogFn`, `LoggerSink`, `Result`
|
||||
```bash
|
||||
bun add @uncaged/workflow-util
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
## API
|
||||
|
||||
- **Workspace:** `@uncaged/workflow-protocol` — `Result` and shared types used by helpers
|
||||
All exports come from `src/index.ts`.
|
||||
|
||||
### Encoding and IDs
|
||||
|
||||
```typescript
|
||||
function encodeUint64AsCrockford(value: bigint): string
|
||||
function generateUlid(nowMs: number): string
|
||||
```
|
||||
|
||||
### Logging
|
||||
|
||||
```typescript
|
||||
function createLogger(options?: { sink: { kind: "stderr" } }): LogFn
|
||||
|
||||
type LogFn = (tag: string, message: string) => void
|
||||
// CreateLoggerOptions and LoggerSink are internal types
|
||||
```
|
||||
|
||||
### Process logger
|
||||
|
||||
```typescript
|
||||
function createProcessLogger(options: CreateProcessLoggerOptions): ProcessLogger
|
||||
|
||||
type ProcessLogger = {
|
||||
pid: string;
|
||||
log: ProcessLogFn;
|
||||
};
|
||||
|
||||
type ProcessLoggerContext = {
|
||||
thread: string | null;
|
||||
workflow: string | null;
|
||||
};
|
||||
|
||||
type CreateProcessLoggerOptions = {
|
||||
storageRoot: string | null;
|
||||
context: ProcessLoggerContext;
|
||||
};
|
||||
|
||||
type ProcessLogFn = (
|
||||
tag: string,
|
||||
msg: string,
|
||||
context: Record<string, string> | null,
|
||||
) => void;
|
||||
```
|
||||
|
||||
### Frontmatter markdown
|
||||
|
||||
```typescript
|
||||
function parseFrontmatterMarkdown(raw: string): ParsedFrontmatterMarkdown
|
||||
function validateFrontmatter(
|
||||
parsed: ParsedFrontmatterMarkdown,
|
||||
schema: Record<string, unknown>,
|
||||
): FrontmatterValidationError[]
|
||||
|
||||
type ParsedFrontmatterMarkdown = {
|
||||
frontmatter: Record<string, unknown>;
|
||||
body: string;
|
||||
};
|
||||
|
||||
type AgentFrontmatter = { /* standard agent frontmatter fields */ };
|
||||
type FrontmatterScope = string;
|
||||
type FrontmatterStatus = string;
|
||||
type FrontmatterValidationError = { path: string; message: string };
|
||||
```
|
||||
|
||||
### Result helpers
|
||||
|
||||
```typescript
|
||||
function ok<T>(value: T): Result<T, never>
|
||||
function err<E>(error: E): Result<never, E>
|
||||
|
||||
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
|
||||
```
|
||||
|
||||
### Storage paths
|
||||
|
||||
```typescript
|
||||
function getDefaultWorkflowStorageRoot(): string
|
||||
function getGlobalCasDir(storageRoot: string | undefined): string
|
||||
```
|
||||
|
||||
### Refs and misc
|
||||
|
||||
```typescript
|
||||
function normalizeRefsField(value: unknown): string[]
|
||||
function generateCliReference(): string
|
||||
function env(name: string, fallback: string): string
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```typescript
|
||||
import { createLogger, getDefaultWorkflowStorageRoot, generateUlid } from "@uncaged/workflow-util";
|
||||
import {
|
||||
createLogger,
|
||||
generateUlid,
|
||||
getDefaultWorkflowStorageRoot,
|
||||
parseFrontmatterMarkdown,
|
||||
} from "@uncaged/workflow-util";
|
||||
|
||||
const log = createLogger();
|
||||
log("4KNMR2PX", "example");
|
||||
log("4KNMR2PX", "Loading workflow...");
|
||||
|
||||
const root = getDefaultWorkflowStorageRoot();
|
||||
const threadId = generateUlid(Date.now());
|
||||
```
|
||||
|
||||
## Internal Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts
|
||||
├── base32.ts Crockford Base32 encode/decode
|
||||
├── ulid.ts ULID generation
|
||||
├── logger.ts Structured logger
|
||||
├── process-logger/ Process-level debug log files
|
||||
├── frontmatter-markdown/ Parse and validate agent frontmatter
|
||||
├── refs-field.ts Normalize refs arrays on CAS nodes
|
||||
├── result.ts ok / err helpers
|
||||
├── storage-root.ts Default ~/.uncaged/workflow paths
|
||||
├── env.ts Environment variable helper
|
||||
├── cli-reference.ts Markdown CLI reference generator
|
||||
└── types.ts LogFn, Result, logger options
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
`getDefaultWorkflowStorageRoot()` resolves to `~/.uncaged/workflow` unless overridden by environment (see `storage-root.ts`).
|
||||
|
||||
Reference in New Issue
Block a user