Run status should report what the run is waiting for

Open
#550 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

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

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.

Description

enhancement

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.phpSTATUS_RUNTIME_TOOL_PENDING and STATUS_APPROVAL_REQUIRED are canonical statuses.
  • src/Channels/register-agents-chat-run-control-abilities.phpagents_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.
Dominant language
PHP
Stars
33
Forks
8
Avg merge
1h 39m
Merged PRs (30d)
30

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Automattic/agents-api

All issues in Automattic/agents-api

Similar issues

More PHP issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.