oxygen-workflow-authoring

OXYGEN Workflow Authoring

A local file is only an authoring input; OXYGEN runs graphs durably.

Boundary

• Workflows own deterministic triggers/control flow; Agents own adaptive goals and tool choice; Sequences own outreach cadence; Tables own row dependencies.
• Use hosted runs, never local cron or shell loops.

Authoring loop

1. Search definitions/templates and inspect the schema.
2. Author explicit resource ids; lint and apply an immutable version.
3. Before go-live/sign-off, workflows call <ref> --preview — what leaves Oxygen, which accounts, credit floor; runs nothing, no --mode. Then dry-run, approve exact live scope, workflows tail.

Editable graph:

oxygen workflows events list --search "<outcome>" --kind builtin --json
oxygen workflows init --id my-workflow
oxygen workflows schema --subject graph --json
oxygen workflows lint --file my-workflow.workflow.json --phase draft --json
oxygen workflows apply --file my-workflow.workflow.json --draft --json
oxygen workflows lint --file my-workflow.workflow.json --phase publish --json

MCP: hydrate oxygen_workflows_* through oxygen_capabilities_schema. Resolve events with workflows events get <catalog-id>. Setup-required events remain draftable but block publish/enable; custom events need no provider setup.

Lint returns the same org-aware canSaveDraft / canPublish report everywhere. Draft phase permits safe incomplete work; publish phase (the default) checks readiness. Candidate approval/cap flags never grant authority.

Draft apply is inert: 0 credits, no node calls/run, no publish. After publish lint passes, apply without --draft; call and enable authorize execution separately. smoke_test/dry_run spend 0 credits and make no paid provider call or external write; internal reads use current data and oxygen.http_json_request may GET.

Test ONE step with workflows call --node <id> (test_node_id on MCP). Oxygen plans the slice server-side from the exact saved version — the target plus only the predecessors it needs — and records it on the run. Non-live, canonical graph workflows only.

JavaScript Code gets only declared inputs and needs a closed output schema. run_source/ctx is legacy. Use tools search --workflow-eligible then tools get for exact ids, schemas, and effects.

Composition rules

• Keep row work in Tables; use native actions, not hidden local data.
• Outbound uses oxygen.sequence_enroll on an active bounded Sequence, never a raw provider message.
• Branch on documented outputs and pin exact provider operations.
• Preview/cap paid or external writes; Workflow approval never bypasses safety.

Delete is permanent and preview-first: run workflows delete <ref> --json, then repeat with --yes. Run history stays read-only.

Rotate webhook secrets preview-first with workflows webhooks rotate <ref> --json, then --approved. The old secret stops immediately; copy the one-time replacement. Rotation never publishes, enables, or runs.

Replay only verified outcome=ran webhook deliveries with workflows webhooks replay <delivery-id> --request-key <stable-key> --json. It creates an inspectable, idempotent dry_run of the original revision and payload without changing ingress/history, spending credits, or writing externally.