# 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.