[delete-cloud]

Summary

• add metadata-only worker instance/process/capability/workspace-sync reporting for external-worker claim and heartbeat
• add durable runtime interaction list/inspect/resolve APIs and remote CLI commands
• document the advanced control-plane slice in ADR-0053 and task packet

Verification

• uv run pytest tests/ui/test_http_server.py -k "external_worker or interactions" -v
• uv run pytest tests/cli/test_remote_client.py -k "remote_interaction or remote_worker or external_worker" -v
• uv run pytest tests/ui/test_session_manager_runtime.py -k "approval or interaction" -v
• uv run pytest tests/coding_agent/test_pg_runtime_store.py -v
• uv run ruff check docs/adr/0053-advanced-external-worker-control-plane-foundations.md src/coding_agent/server/http_server.py src/coding_agent/server/session_manager.py src/coding_agent/server/schemas.py src/coding_agent/remote/client.py src/coding_agent/remote/worker.py src/coding_agent/cli/remote_commands.py tests/ui/test_http_server.py tests/ui/test_session_manager_runtime.py tests/ui/test_developer_console.py tests/cli/test_remote_client.py tests/coding_agent/test_pg_runtime_store.py tests/dogfood/test_local_dogfood_run.py tests/dogfood/test_workspace_provider_demo.py tests/integration/test_durable_runtime_smoke.py
• uv run ruff format --check src/coding_agent/server/http_server.py src/coding_agent/server/session_manager.py src/coding_agent/server/schemas.py src/coding_agent/remote/client.py src/coding_agent/remote/worker.py src/coding_agent/cli/remote_commands.py tests/ui/test_http_server.py tests/ui/test_session_manager_runtime.py tests/ui/test_developer_console.py tests/cli/test_remote_client.py tests/coding_agent/test_pg_runtime_store.py tests/dogfood/test_local_dogfood_run.py tests/dogfood/test_workspace_provider_demo.py tests/integration/test_durable_runtime_smoke.py
• git diff --check

Summary by CodeRabbit

Release Notes

• New Features

  • Added CLI commands to list, inspect, and resolve remote runtime interactions with optional filtering and approval/rejection options.
  • Added HTTP API endpoints for querying and managing runtime interactions across runs and sessions.
  • Extended worker metadata tracking to include instance identifiers, process information, capabilities, and workspace synchronization metadata.

• Documentation

  • Added architecture documentation defining advanced external worker control plane foundations.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR implements the "Advanced External Worker Control Plane Foundations" feature by extending the external-worker lifecycle with optional metadata reporting (worker instance ID, process ID, capabilities, workspace sync), adding durable HTTP APIs for browsing and resolving runtime approval interactions, and providing remote client and CLI tools for interaction management.

Changes

External Worker Control Plane

Layer / File(s)	Summary
Planning, Schemas, and Core Protocol .opencode/prompts/tasks/*, docs/adr/*, src/coding_agent/server/schemas.py, src/coding_agent/server/session_manager.py	Task packet and ADR-0053 define scope and acceptance criteria; WorkerClaimRequest, WorkerHeartbeatRequest, and WorkerStatusResponse extended with optional worker_instance_id, process_id, capabilities, and workspace_sync fields; RuntimeStoreProtocol and SessionManager add load_agent_interaction for interaction retrieval; new RuntimeInteractionResponse and ResolveInteractionRequest schemas introduced.
Worker Metadata Collection and Propagation src/coding_agent/remote/worker.py	Worker generates per-process worker_instance_id and computes capabilities and workspace_sync metadata; _claim_run and _heartbeat_until_complete include metadata in claim and heartbeat requests to control plane; helper functions create instance identity and compute metadata payloads.
Server Protocol Extensions and Worker Metadata Integration src/coding_agent/server/session_manager.py, src/coding_agent/server/http_server.py	SessionManager.claim_external_worker_run and heartbeat_external_worker_run accept and persist optional worker metadata; HTTP worker endpoints (/worker/runs/claim, /worker/runs/{run_id}/heartbeat) forward metadata to session manager; _worker_status_from_runs extracts and exposes metadata in worker status response.
Remote Client and CLI Interaction Commands src/coding_agent/remote/client.py, src/coding_agent/cli/remote_commands.py	New list_remote_interactions, get_remote_interaction, and resolve_remote_interaction client functions; remote interactions command lists with optional session/run/status filters; remote interaction fetches single interaction; remote resolve-interaction resolves with approve/reject and feedback.
HTTP Interaction Listing and Resolution Endpoints src/coding_agent/server/http_server.py	GET /runs/{run_id}/interactions and GET /interactions list interactions with optional filtering; GET /interactions/{interaction_id} fetches single interaction; POST /interactions/{interaction_id}/resolve validates approval state, submits resolution via session manager, and returns updated interaction; _runtime_interaction_response helper maps interaction records to response model.
Test Store Protocol Compliance tests/dogfood/test_local_dogfood_run.py, tests/dogfood/test_workspace_provider_demo.py, tests/integration/test_durable_runtime_smoke.py, tests/ui/test_developer_console.py, tests/ui/test_session_manager_runtime.py	All in-memory and test-double runtime stores implement load_agent_interaction method to support interaction querying across test harnesses.
Integration and Functional Test Coverage tests/ui/test_http_server.py, tests/cli/test_remote_client.py	New external-worker test verifies metadata (instance_id, process_id, capabilities, workspace_sync) is surfaced in /workers/{worker_id} status; runtime interaction tests validate listing and resolution via HTTP endpoints; FakeExternalWorkerRuntimeStore extended with interaction lifecycle methods; CLI test validates remote interactions and remote resolve-interaction commands.
Test Data Formatting Standardization tests/ui/test_developer_console.py	Test fixture data construction reformatted to multiline list/dict style for readability across UI test suite fixtures; no behavioral changes except addition of load_agent_interaction method noted in prior layer.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• delete-cloud/Coding-Agent-Loop#408: Adds /workers and /workers/{worker_id} HTTP endpoints to inspect worker status; this PR extends WorkerStatusResponse to include the worker_instance_id, process_id, capabilities, and workspace_sync metadata that those endpoints expose.
• delete-cloud/Coding-Agent-Loop#407: Introduced the external-worker claim/heartbeat/approval lifecycle APIs; this PR extends those same claim_external_worker_run and heartbeat_external_worker_run methods with additional optional metadata parameters and adds durable interaction browse/resolve endpoints on top of the foundation.

Poem

🐰 A worker claims with metadata bold,
Instance IDs and process tales to tell,
Heartbeats carry workspace sync and capabilities old,
Control plane listens—approvals resolve quite well!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.21% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'Add advanced external worker control-plane foundations' directly and accurately summarizes the main changes: introducing metadata reporting for external workers, durable runtime interaction APIs, and corresponding CLI commands.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch advanced-worker-control-plane

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}