xingyue
3ed38c65ec
Adds `uncaged-workflow serve` command that exposes workflow data via a local HTTP API for the upcoming Web UI (RFC #118 Phase 1). Routes: - GET /healthz — health check - GET /api/workflows — list registered workflows - GET /api/workflows/:name — show workflow details - GET /api/workflows/:name/history — version history - GET /api/threads — list threads (optional ?workflow= filter) - GET /api/threads/running — list running threads - GET /api/threads/:id — show thread records (parsed JSONL) - GET /api/cas — list CAS hashes - GET /api/cas/:hash — get CAS content - POST /api/cas — store content, returns hash - DELETE /api/cas/:hash — remove CAS entry - POST /api/cas/gc — garbage collect Default: 127.0.0.1:7860, configurable via --port/-p and --host. Refs: #118
@uncaged/workflow
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).
Core Concepts
| Concept | Description |
|---|---|
| Workflow | A single-file ESM module exporting run (workflow function) and descriptor (metadata). Identified by its XXH64 hash. |
| Bundle | The physical .esm.js file stored in ~/.uncaged/workflow/bundles/. |
| Thread | A single execution of a workflow, identified by a ULID. Persisted as .data.jsonl + .info.jsonl. |
| Role | A named actor within a workflow. Each role produces output with typed meta. Roles live inside template packages (src/roles/). |
| Registry | workflow.yaml — maps workflow names to current/historical bundle hashes. |
| CAS | Content-Addressed Storage — bundles are immutable and addressed by hash. |
Monorepo Packages
packages/
workflow/ # @uncaged/workflow — core lib (types, engine, hash, ULID, registry)
cli-workflow/ # @uncaged/cli-workflow — CLI (`uncaged-workflow` command)
workflow-template-develop/ # @uncaged/workflow-template-develop — develop workflow template (includes roles)
workflow-template-solve-issue/ # @uncaged/workflow-template-solve-issue — solve-issue workflow template (includes roles)
workflow-agent-hermes/ # @uncaged/workflow-agent-hermes — Hermes agent adapter
workflow-agent-cursor/ # @uncaged/workflow-agent-cursor — Cursor agent adapter
workflow-agent-llm/ # @uncaged/workflow-agent-llm — LLM agent adapter
workflow-util-agent/ # @uncaged/workflow-util-agent — agent utilities (buildAgentPrompt, spawnCli)
Managed with bun workspace using the workspace:* protocol.
Quick Start
# Install dependencies
bun install
# Build all packages
bun run build
# Register a workflow bundle
uncaged-workflow workflow add solve-issue dist/packages/workflow-template-solve-issue/solve-issue.esm.js
# Run a workflow
uncaged-workflow run solve-issue --prompt "Fix bug #42"
CLI Usage
uncaged-workflow # Print full command usage (exits with status 1)
uncaged-workflow workflow list # List registered workflows
uncaged-workflow run <name> # Start a workflow thread
uncaged-workflow thread list # List all threads
uncaged-workflow thread show <id> # Inspect a thread
uncaged-workflow skill # Agent-consumable reference docs
Run uncaged-workflow with no arguments to print usage, or uncaged-workflow skill cli for the full CLI skill reference.
Development
bun run check # Biome lint + format check
bun run format # Auto-format with Biome
bun test # Run tests
Architecture
See docs/architecture.md for the full design — three-phase engine loop, bundle contract, storage layout, and design decisions.