Workflows: unopinionated substrate (Spec, Runner, abilities, AS bridge)

[lezama]

Summary

Adds an unopinionated workflow plumbing layer in the spirit of Channels and Memory — substrate ships contracts, value objects, validators, an in-memory registry, an optional Action Scheduler bridge, and three canonical Abilities API entry points; every consumer brings its own storage and run-recorder implementations.

The two existing references — James LePage's six-month-old design spike (design-only, no implementation) and the HAL team's wpcom workflow engine (production since Aug 2025, closed-source inside wpcom) — converge on the same shape: deterministic orchestration over registered abilities and agents, with the runtime owned by whichever consumer wants to drive it. Data Machine already runs its own pipelines/flows/jobs against custom tables; openclaWP wants a smaller CPT-backed runtime; future consumers may want neither. agents-api is the right place for the contract those runtimes share.

Per Chris Huber on 2026-05-08: "we will handle it similar to memory, where we provide unopinionated plumbing."

What ships

Component	Purpose
WP_Agent_Workflow_Spec + Spec_Validator	Immutable value object + structural validator returning [ path, code, message ] triples for editor / REST surfaces
WP_Agent_Workflow_Bindings	Pure helper that expands ${inputs.x} and ${steps.<id>.output.<path>} templates. Whole-string templates preserve native types; mixed-content templates stringify; missing paths return null (atomic) / empty string (mixed)
WP_Agent_Workflow_Run_Result	Immutable execution outcome with pending / running / succeeded / failed / skipped statuses
WP_Agent_Workflow_Store	Interface only — no default impl. Consumers wire their preferred persistence
WP_Agent_Workflow_Run_Recorder	Interface only — same model
WP_Agent_Workflow_Runner	Abstract execution engine. Sequential steps, step-type handler map (ability and agent ship; branch / parallel / workflow extensible via filter), per-step recording, short-circuit on failure unless continue_on_error is set. Default agent handler routes through the canonical agents/chat dispatcher (per #100)
WP_Agent_Workflow_Registry	In-memory wp_register_workflow() / wp_get_workflow() — pair with a Store for durable persistence
WP_Agent_Workflow_Action_Scheduler_Bridge	Optional bridge — no-ops cleanly when AS isn't loaded. Fires wp_agent_workflow_schedule_requested regardless so custom schedulers can take over
register-agents-workflow-abilities.php	Three abilities under the existing agents-api category: agents/run-workflow (dispatcher mirroring agents/chat), agents/validate-workflow (pure substrate, no runtime), agents/describe-workflow

Sample spec

return array(
    'id'      => 'triage-inbound-customer-request',
    'version' => '1.0.0',
    'inputs'  => array( 'request' => array( 'type' => 'string', 'required' => true ) ),
    'steps'   => array(
        array(
            'id'      => 'classify',
            'type'    => 'agent',
            'agent'   => 'ops-triage',
            'message' => 'Classify and decide next action: ${inputs.request}',
        ),
        array(
            'id'      => 'create-ticket',
            'type'    => 'ability',
            'ability' => 'linear/create-issue',
            'args'    => array(
                'title' => '${steps.classify.output.title}',
                'body'  => '${steps.classify.output.summary}',
            ),
        ),
    ),
    'triggers' => array(
        array( 'type' => 'on_demand' ),
        array( 'type' => 'wp_action', 'hook' => 'comment_post' ),
    ),
);

Out of scope (deferred to consumers / v1)

• Branching / conditionals / parallel steps — extensible today via wp_agent_workflow_step_handlers filter, no built-ins ship
• Nested workflows (type: workflow) — same extension hook
• YAML DSL — companion plugin; PHP array stays canonical
• Pause / resume / approval gates
• Workflow editor UI
• Durable storage / run history — every consumer ships its own (Data Machine keeps its tables; openclaWP will add CPTs in a follow-up PR)

Tests

composer test

Adds four smoke files under tests/:

• workflow-bindings-smoke.php — 13 assertions, template substitution edge cases
• workflow-spec-validator-smoke.php — 20 assertions, structural validation + Spec value object
• workflow-runner-smoke.php — 17 assertions, full execute path with stub abilities + recorder
• agents-workflow-ability-smoke.php — 18 assertions, dispatcher pattern (mirrors agents-chat-ability-smoke)

All 950+ existing assertions continue to pass; bootstrap-smoke's expected_source_directories allowlist gains Workflows/.

Sequencing

A consumer PR to lezama/openclawp follows this one — CPT-backed Store + Run_Recorder, wp-admin UI, and a demo workflow shipped behind the existing example-agent opt-in filter pattern. Coordinated separately with Chris on Data Machine adoption — non-blocking for either consumer.

Test plan

• composer install && composer test — every smoke green
• In a real WP, wp eval 'wp_register_workflow([ ... ]); print_r( wp_get_workflow( "demo/x" )->to_array() );' to confirm in-memory registry round-trip
• In a real WP, wp eval 'wp_get_ability( "agents/validate-workflow" )->execute([ "spec" => [ ... ] ])' to confirm the validate ability lands