Automattic / Automattic/agents-api

Run status should report what the run is waiting for

Open
#550 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
PHP
Stars
33
Forks
8
Avg merge
1h 36m
Merged PRs (30d)
31

Description

## Problem

Two run statuses mean the run is blocked and waiting on someone: `runtime_tool_pending` and `approval_required`. The run payload says the run is blocked. It does not say what to act on.

A client that polls `agents/get-chat-run` and sees `approval_required` has to already know which subsystem blocked the run, then go find the row itself. For approvals there is no canonical way to do it: the pending-action list takes implementation-defined filters, so scoping by run is up to each store. The caller that is supposed to unblock the run cannot get from the run to the thing that unblocks it.

## Evidence

- `src/Runtime/class-wp-agent-chat-run-control.php` — `STATUS_RUNTIME_TOOL_PENDING` and `STATUS_APPROVAL_REQUIRED` are canonical statuses.
- `src/Channels/register-agents-chat-run-control-abilities.php` — `agents_chat_run_output_schema()` returns `run_id`, `session_id`, `status`, timestamps, and opaque `metadata`. Nothing about what the run is waiting for.
- `agents/resolve-pending-action` requires an `action_id`, and `agents/submit-runtime-tool-result` requires a `request_id`. Neither id is reachable from the run payload.
- `agents_pending_action_filters_input_schema()` documents its filters as implementation-defined, so run scoping is not part of the contract. `agents/list-runtime-tool-requests` does accept `run_id`, which is the shape to follow.

## Required contract

- Add an optional `required_actions` array to the canonical run payload, normalized in `WP_Agent_Run_Control::normalize_run()` so every run family gets it.
- Each entry names the kind of action and the id to act on. Cover `runtime_tool_result` and `pending_action` first, and leave the kind open for other blocking sources.
- Populate it whenever the status is a blocked status, and leave it empty otherwise. A store that cannot supply it returns nothing rather than an invented entry.
- Add a canonical run filter to the pending-action list so the entry can be verified against a query.

## Tests

- A run blocked on a runtime tool exposes an entry whose id is accepted by `agents/submit-runtime-tool-result`.
- A run blocked on an approval exposes an entry whose id is accepted by `agents/resolve-pending-action`.
- Running and completed runs expose an empty list.
- Two runs blocked in the same session never see each other's entries.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with src/Runtime/class-wp-agent-chat-run-control.php and src/Channels/register-agents-chat-run-control-abilities.php; read normalize_run(), agents_chat_run_output_schema(), and the runtime-tool and pending-action entry points. Done means blocked runs expose verifiable required_actions IDs scoped to their run, non-blocked runs expose an empty list, and pending-action filtering supports run_id; verify the four required scenarios in the issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
php, wordpress
Domain
api, backend-api-design
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.