164 lines
4.3 KiB
Markdown
164 lines
4.3 KiB
Markdown
# Flows
|
|
|
|
Flows are packaged automation units. They are discovered from `.codex/flows/*`
|
|
first and then `flows/*`, with the installed `.codex` copy taking precedence.
|
|
|
|
Each flow has:
|
|
|
|
```text
|
|
flow.toml
|
|
schemas/*.schema.json
|
|
exec/*
|
|
```
|
|
|
|
`flow.toml` is the manifest. Use `flow` naming consistently:
|
|
|
|
```toml
|
|
name = "example-flow"
|
|
version = 1
|
|
description = "Short operational purpose."
|
|
|
|
[config]
|
|
commit = true
|
|
|
|
[[steps]]
|
|
name = "do-work"
|
|
runner = "bun"
|
|
script = "exec/do-work.ts"
|
|
timeout_ms = 300000
|
|
|
|
[steps.trigger]
|
|
type = "upstream.release"
|
|
schema = "schemas/upstream-release.schema.json"
|
|
```
|
|
|
|
The runtime passes a generic event to every step:
|
|
|
|
```ts
|
|
type FlowEvent<T = unknown> = {
|
|
id: string;
|
|
type: string;
|
|
source?: string;
|
|
occurredAt?: string;
|
|
receivedAt: string;
|
|
payload: T;
|
|
};
|
|
```
|
|
|
|
Domain payload types live in each flow package as JSON Schema files and are
|
|
referenced by `steps.trigger.schema`.
|
|
|
|
## Runners
|
|
|
|
`runner = "bun"` executes the script directly with Bun. The step receives JSON
|
|
on stdin:
|
|
|
|
```json
|
|
{
|
|
"flow": {
|
|
"name": "example-flow",
|
|
"version": 1,
|
|
"root": "/repo/flows/example-flow",
|
|
"step": "do-work",
|
|
"config": {},
|
|
"event": {}
|
|
}
|
|
}
|
|
```
|
|
|
|
The script must print a final line beginning with `FLOW_RESULT ` followed by
|
|
JSON.
|
|
|
|
`runner = "code-mode"` starts a Codex app-server and calls the fork-only
|
|
`thread/codeMode/execute` method through a raw JSON-RPC request. Code Mode code
|
|
is present on `main`, but execution is disabled unless:
|
|
|
|
```bash
|
|
CODEX_FLOWS_ENABLE_CODE_MODE=1
|
|
```
|
|
|
|
Set `CODEX_APP_SERVER_CODEX_COMMAND` when Code Mode should run against the
|
|
Peezy fork instead of the default `codex` binary.
|
|
|
|
## Commands
|
|
|
|
List flows:
|
|
|
|
```bash
|
|
bun run flow list
|
|
```
|
|
|
|
Fire all matching steps for an event:
|
|
|
|
```bash
|
|
bun run flow fire --event event.json
|
|
```
|
|
|
|
Run one step:
|
|
|
|
```bash
|
|
bun run flow run openai-codex-bindings regenerate-bindings --event event.json
|
|
```
|
|
|
|
## Systemd-Local Backend
|
|
|
|
`codex-flow-systemd-local` is the first execution backend. Patchbay posts
|
|
generic `FlowEvent` JSON to this service; the service persists events and runs
|
|
to SQLite, discovers matching flow steps, and starts each step locally.
|
|
|
|
Run it directly:
|
|
|
|
```bash
|
|
bun run flow:backend serve --cwd /home/peezy/codex-flows-public
|
|
```
|
|
|
|
Useful environment:
|
|
|
|
```bash
|
|
CODEX_FLOW_BACKEND_HOST=127.0.0.1
|
|
CODEX_FLOW_BACKEND_PORT=7345
|
|
CODEX_FLOW_BACKEND_DATA_DIR=/var/lib/codex-flow-systemd-local
|
|
CODEX_FLOW_BACKEND_SECRET=shared-hmac-secret
|
|
CODEX_FLOW_BACKEND_EXECUTOR=direct
|
|
```
|
|
|
|
`CODEX_FLOW_BACKEND_EXECUTOR=systemd-run` wraps each step in a transient
|
|
`systemd-run --user --wait --collect` unit. The default `direct` executor is
|
|
still suitable when the backend service itself is managed by systemd.
|
|
|
|
Endpoints:
|
|
|
|
- `POST /events` or `POST /flow-events`: accept one `FlowEvent`
|
|
- `GET /runs?eventId=<id>`: inspect recorded runs for an event
|
|
- `GET /healthz`: health check
|
|
|
|
## Convex Backend Direction
|
|
|
|
Convex should be a durable orchestration backend, not the place where long
|
|
running Codex or shell work executes. A future Convex backend should:
|
|
|
|
- accept the same generic `FlowEvent` shape
|
|
- persist event, run, step, retry, and result records durably
|
|
- choose matching flow steps from a stored or installed flow manifest
|
|
- lease work to an external worker or remote app-server
|
|
- receive heartbeats and final `FLOW_RESULT` records from that worker
|
|
- expose programmatic fire/retry/cancel APIs
|
|
|
|
This keeps Patchbay dispatch-only, keeps Convex durable, and keeps process-heavy
|
|
work on infrastructure that can run Codex, Bun, Git, Cargo, and system tools.
|
|
|
|
## Codex Release Flows
|
|
|
|
The upstream `openai/codex` release event fans out to two flow packages:
|
|
|
|
- `openai-codex-bindings`: Bun runner. Uses canonical `@openai/codex@version`,
|
|
regenerates `@peezy.tech/codex-flows` app-server bindings, runs checks,
|
|
commits when changed, and can push/trigger trusted publishing when configured.
|
|
- `peezy-codex-fork`: Code Mode runner. Rebases the Peezy fork patch stack onto
|
|
the upstream release tag, optionally squashes the patch stack, verifies the
|
|
fork, and can push/tag to trigger the fork release workflow when configured.
|
|
|
|
Publishing is controlled by flow config and environment. The packaged defaults
|
|
commit local changes when appropriate but do not push or publish until
|
|
`push = true`, `publish = true`, or matching `CODEX_FLOW_PUSH=1` /
|
|
`CODEX_FLOW_PUBLISH=1` deployment configuration is set.
|