Channels: sender_id + tool context; workflows: ${vars}, foreach, dispatch-message

[lezama]

Summary

Adds two layers of substrate primitives that consumers (WhatsApp adapters, multi-step workflows, message-broadcast use-cases) were repeatedly reaching past:

Channels + tool context

• WP_Agent_Channel::extract_sender_id() extension hook so adapters can expose the user's external id (WhatsApp number, Slack user, etc.) to the runtime.
• client_context.sender_id plumbed into the agents/chat schema so abilities can be authored against the canonical client context shape.
• Tool execution merges runtime context into the args before validating required parameters. This lets a channel-supplied value (e.g. user_phone from sender_id) satisfy an ability's required arg without forcing every channel to duplicate that logic per turn.

Workflow primitives

• \${vars.*} bindings alongside the existing \${steps.*.output.*} syntax, for hoisting workflow-level constants.
• foreach step type so a workflow can fan a single step over an array (e.g. "for each pending prediction, score it").
• Bug fix in the spec validator that was double-prefixing the `steps.` path component, masking real errors.

New ability + auto-sync

• `agents/dispatch-message` ability with handler filter — lets a workflow send a message to a recipient without knowing the transport.
• Workflow ↔ cron bridge auto-syncs cron triggers when a workflow CPT post is saved, so admins don't have to remember to schedule by hand.

Smoke tests for all of the above under `tests/`.

Test plan

• Existing test suite passes.
• Channel that overrides `extract_sender_id()` lands the value in `client_context.sender_id`.
• Ability with required `user_phone` succeeds when only `sender_id` is supplied.
• Workflow with `${vars.foo}` interpolates correctly.
• `foreach` step iterates an array output from a prior step.
• Saving a workflow post with a cron trigger registers the cron without manual intervention.
• Calling `agents/dispatch-message` with a registered handler delivers; unregistered handler returns a clear error.

[chubes4]

Directionally this is aligned with what I would want Agents API to own, using Data Machine as the production adoption case.

Data Machine already has the big, messy version of this problem: durable flows, scheduled jobs, fan-out, tool execution, channel-ish chat surfaces, approval gates, and long-running automation. From that lens, these primitives are the right kind of substrate:

• sender_id belongs in the canonical channel/client context contract. DM should not need per-adapter conventions for external human identity.
• foreach + scoped ${vars.*} is the workflow primitive DM-style pipelines eventually need from the generic layer.
• agents/dispatch-message is the right separation from agents/chat: chat is inbound agent execution, dispatch is outbound delivery through a transport.
• Optional Action Scheduler integration is the right dependency posture. Agents API should use AS when present without making the whole substrate require it.

The part I would want tightened before adopting this for production Data Machine scheduling is the workflow lifecycle contract around cron auto-sync.

Right now the new sync hooks wp_agent_workflow_registered, which covers code/in-memory registration. That is useful, but DM’s production case is durable: flows/workflows are saved, updated, disabled, deleted, migrated, and sometimes repaired outside a normal plugin boot path. For that world, scheduler sync needs to follow durable lifecycle events, not only registration.

What I’d want from Agents API before DM could lean on this directly:

• A generic durable workflow lifecycle surface: saved/updated/deleted/disabled or equivalent events around WP_Agent_Workflow_Store implementations.
• Scheduler bridge behavior that can subscribe to those lifecycle events and keep AS in sync for create/update/delete, including unscheduling stale hooks.
• Clear separation between “code registered this workflow for this request” and “this workflow is durably active and should have scheduled work.”
• A way for stores/products to opt into the bridge without pretending their persisted workflows are code-registered at boot.

So I like the AS bridge pattern, and it does not conflict with Data Machine. I just wouldn’t want the auto-sync story to stop at wp_register_workflow(), because the production beast is persisted workflows with real lifecycle management.

One adjacent architectural note: the tool-context change is solving a real need, but I’d prefer required tool args to be satisfied by explicit context mappings/defaults rather than broad ambient context key matching. That keeps sensitive parameters auditable when a runtime like DM starts delegating more tool execution to Agents API.

[lezama]

Thanks for the close read. Pushed two follow-ups:

f32d2c8 introduces WP_Agent_Workflow_Lifecycle (saved / deleted / disabled / enabled) as the durable event surface, separate from wp_agent_workflow_registered. WP_Agent_Workflow_Store now documents the contract — stores call into the helper after each op. The AS bridge gained a sync() that unschedules every existing action for the workflow id before re-registering, so updates that drop a cron trigger don't leak stale schedules. Bridge-sync subscribes to all four lifecycle hooks; _registered stays the in-memory-only signal.

5dc4195 drops the broad ambient context-key matching for required tool args. Tools now opt in via client_context_bindings (associative param => context_key for rename, flat list for same-name). Undeclared context keys cannot satisfy a required parameter, so sensitive abilities stay auditable end-to-end.

Both covered by smoke tests (workflow-lifecycle-smoke.php + extended tool-runtime-smoke.php).

[chubes4]

Architecture concerns from the Data Machine adoption lens are resolved for me. The durable lifecycle hooks + sync() bridge are the right shape for persisted workflow stores, and client_context_bindings fixes the ambient-context issue cleanly.

Only thing from my side: fix the current lint failure, then let 'er rip.