xiaoju
a222db6f2d
- Add missing agent deps to template package.json so bun workspace
resolution works during `bun build` (workflow-agent-cursor for develop,
workflow-agent-hermes + workflow-execute for solve-issue)
- Create scripts/build-bundles.sh that builds both template bundles into
dist/*.esm.js with correct --external flags for runtime-symlinked packages
- Add build:bundles script to root package.json
- Extend ensureUncagedWorkflowSymlink to also symlink workflow-util,
workflow-execute, and workflow-register (needed by externalized bundles)
- Defer agent creation in develop bundle-entry.ts via lazy init so
requireEnv('WORKFLOW_LLM_API_KEY') only throws at first invocation,
not at import() time (fixes workflowAsAgent crash)
- Document that env vars must be set before the first worker spawn
(workers are persistent and don't inherit later env changes)
Fixes #206
Co-authored-by: Cursor <cursoragent@cursor.com>
@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. CAS-backed chain plus threads.json / history/*.jsonl; .info.jsonl for debug logs. |
| 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.