Surface area, in full.
Every public entry point in @athree/runner plus the CLI and package topology.
Schemas use zod; payloads on the wire use airtight.
defineWorkflow(spec)
Declares a workflow. The returned object is exported as the module's default and discovered by the runner.
| Field | Type | Notes |
|---|---|---|
| title | string | Required. Human-readable label. |
| description | string | Required. Surfaced in the manager UI. |
| rootDir | string | Required. Project source root, e.g. 'src'. |
| sitesDir | string | Required. Directory whose immediate children are per-site stage folders. |
| inputsSchema | ZodType | Validated before run() is called. |
| outputsSchema | ZodType | Validated before a success: true stage commits. |
| agents | AgentDefinition[] | Agent definitions registered with the workflow scope. |
| projectLocations | ProjectLocation[] | Folders the agent may read or write — objectives, schemas, skills. |
| setup(ctx) | () ⇒ Promise<void> | Optional. Useful for seeding ctx.inputs in dev runs. |
| teardown(ctx) | () ⇒ Promise<void> | Optional. Cleanup hook. |
defineStage(spec)
Declares a stage. The runner discovers any module exporting a stage as default within sitesDir/<site>/.
| Field | Type | Notes |
|---|---|---|
| title | string | Required. |
| description | string | Optional. |
| match(ctx) | () ⇒ Promise<boolean> | Pure check. Required on every stage except the initial one. |
| run(ctx) | () ⇒ Promise<void> | Required. Performs interactions; sets ctx.outputs. |
| verify(ctx) | () ⇒ Promise<boolean> | Optional. Validates run side effects after execution. |
| overlay | boolean | If true, this stage is matched ahead of normal stages. |
| repeatable | boolean | If true, the stage may be matched more than once. |
| success | boolean | Marks the stage as a terminal-success outcome. |
defineAgent(spec)
Declares an LLM-powered agent. Register it on a workflow's agents array; resolve at runtime via ctx.resolve().
defineAgent({ id: 'string', // stable identifier title: 'string', description: 'string', icon: 'fas fa-...', // Font Awesome class systemPrompt: () => ({ content: '…' }), tools: [EvaluateTool, AskUserQuestionTool, FailTool], });
Built-in tools
Importable from @athree/runner and droppable into any agent's tools array.
| Tool | Purpose |
|---|---|
| EvaluateTool | Evaluate JavaScript in the workflow context — used by skills to run setup snippets verbatim. |
| AskUserQuestionTool | Pause the agent, append a question to the thread, resume on user reply. |
| FailTool | Terminate the agent with a structured failure reason. |
defineTool(spec)
Declares a typed function the agent may call.
defineTool({ description: 'string', inputSchema: ZodType, outputSchema: ZodType, execute: async (input, ctx) => output, });
WorkflowContext
The single argument passed to every match(), run() and verify().
| Property | Type | Notes |
|---|---|---|
| page | Page | Playwright (Patchright) page bound to the run. |
| inputs | T (inferred) | Validated against inputsSchema. |
| outputs | T (inferred) | Mutable. Built up across stages. |
| site | string | Filters the candidate stage pool. Set in your default/main.stage. |
| networkResources | NetworkResource[] | Captured requests/responses from the page; great for API-first extraction. |
| logger | Logger | Structured logger scoped to the run. |
| resolve(Class) | T | IoC resolver. Use to fetch agents and shared services. |
new App()
The top-level container. Wires services with mesh-ioc, owns browser pool and HTTP/WS servers when configured.
const app = new App(); await app.run(); // initialise services, browsers, listeners // … use app.workflowRunner … await app.shutdown(); // drains, closes pages, stops servers
app.workflowRunner
The orchestration entry point.
| Method | Returns | Notes |
|---|---|---|
| runWorkflow(id, opts?) | Promise<RunResult> | Resolves with { result, outputs, finalStage }. Throws on routing errors. |
| learn(spec) | Promise<LearnResult> | Runs the multi-agent learning session against the workflow. |
CLI — a3 run
Provided by @athree/cli. Spawns a runner subprocess with the loader hooks pre-registered.
a3 run <workflowFile> [options] -d, --dir <dir> project root (default: cwd) --inputs <json> inline JSON inputs --inputs-file <path> JSON file with inputs -V, --version print CLI version
| Exit code | Meaning |
|---|---|
| 0 | Workflow ended in final: 'success'. |
| 1 | Routing error (no match, ambiguous match, exec error). |
| 2 | Workflow ended in final: 'failure'. |
Package topology
Imports must respect this layering. The lint config rejects violations.
Protos
@athree/runner-proto@athree/manager-proto
Shared
@athree/helpers@athree/module-loader
Runtime
@athree/runner@athree/manager@athree/runner-extensions
Surface
@athree/cli@athree/frontend
| Package | Responsibility |
|---|---|
| @athree/runner-proto | Runner-side RPC contracts and schema definitions. |
| @athree/manager-proto | Manager-side RPC contracts. |
| @athree/helpers | Runtime-agnostic helpers (markdown, json, throttle, time). |
| @athree/module-loader | Node loader hooks: .md imports, cache-busting. |
| @athree/runner | Workflow runtime engine: stages, agents, tools, browser, LLMs. |
| @athree/manager | Local orchestration of isolated runner sessions; manager API. |
| @athree/runner-extensions | Optional integrations layered on the runner runtime. |
| @athree/cli | CLI entrypoint. |
| @athree/frontend | Vue UI consuming typed RPC clients. |
Stable across v4. The
defineWorkflow / defineStage /
defineAgent / defineTool shape is the public contract.
Internal services (e.g. StageMatcher, StageExecutor) may move between minor versions.