xiaoju
5bbac3e4f7
Audit public API surfaces using reachability analysis from application entry points (Worker, CLI, Dashboard). Symbols not reachable from any application's customization tree are removed from package index.ts files. Source files and internal usage are untouched — only the public export surface is narrowed. Changes by package: - workflow-util: -7 exports (base32 internals, logger config types) - workflow-cas: -12 exports (merkle internals, serialization details) - workflow-execute: -24 exports (engine internals, LLM extract details) - workflow-reactor: -4 exports (reactor config/invocation internals) - workflow-register: -8 exports (redundant protocol re-exports, internal YAML fns) - workflow-runtime: curated re-export subset (stop full protocol re-export) - workflow-util-agent: -5 exports (internal agent helpers) - workflow-agent-cursor: -1 export (validateCursorAgentConfig) - workflow-agent-hermes: -1 export (validateHermesAgentConfig) Note: workflow-protocol index.ts unchanged — downstream packages still import removed symbols via internal paths. Protocol cleanup requires updating workflow-runtime/src/types.ts first (separate PR). Refs #273, #274, #275, #276, #277, #278, #279, #280, #281, #282
@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.