codex-flows/packages/flow-runtime

@peezy.tech/flow-runtime

Generic runtime primitives for Codex flow packages.

This package loads flow.toml manifests, matches generic events to flow steps, validates JSON-schema payloads, and runs steps with the Bun or feature-flagged Code Mode runners.

import { discoverFlows, matchingSteps, runFlowStep } from "@peezy.tech/flow-runtime";

Flow Client

@peezy.tech/flow-runtime/client exposes a small flow-native client factory for product code that should not care whether flows run locally or through an HTTP backend:

import { createFlowClient } from "@peezy.tech/flow-runtime/client";

const flows = createFlowClient({
	mode: "local",
	cwd: process.cwd(),
});

await flows.dispatchEvent({
	id: "patch:upstream.release:openai/codex:rust-v1.2.3",
	type: "upstream.release",
	source: "patch",
	receivedAt: new Date().toISOString(),
	payload: { repo: "openai/codex", tag: "rust-v1.2.3" },
});

Use mode: "http" to wrap the existing backend HTTP client:

const flows = createFlowClient({
	mode: "http",
	baseUrl: "http://127.0.0.1:7345",
	hmacSecret: process.env.PATCH_FLOW_DISPATCH_SECRET,
});

@peezy.tech/flow-runtime/local-client runs matching steps synchronously in the selected workspace and keeps in-memory run/event state by default. Set state: { kind: "file" } to persist local run/event state under .codex/flow-client. It preserves the generic FlowEvent and FLOW_RESULT contracts; callers still provide deterministic event ids when idempotency matters.

Backend Client

@peezy.tech/flow-runtime/backend-client exposes backend-native inspection and control for generic flow state. It is intentionally separate from app-server thread commands: runs, events, attempts, replay, cancel, output, and FLOW_RESULT payloads belong to flow backends.

import { createFlowBackendHttpClient } from "@peezy.tech/flow-runtime/backend-client";

const backend = createFlowBackendHttpClient({
	baseUrl: "http://127.0.0.1:7345",
	bearerToken: process.env.CODEX_FLOW_BACKEND_TOKEN,
});

const { runs } = await backend.listRuns({ status: "completed", limit: 20 });

The client normalizes systemd-local, Convex-adapter, and codex-service-style run/event responses into stable view models with processStatus, resultStatus, effectiveStatus, needsAttention, attempts, latest output, and result payload data. Semantic statuses such as blocked and needs_intervention are read from FLOW_RESULT payloads when the backend stores them separately from process status.

Code Mode steps remain gated. Enable them with:

CODEX_FLOWS_MODE=code-mode