agentic-mobile-control/openspec/changes/task-execution-progress-visibility/proposal.md at ec261d57c2c00d8c3ceb3c629eb73e91f81e2ab1

Files

T

q792602257andClaude Opus 4.6 ec261d57c2 feat: surface task execution progress across Host Agent and Cloud

Host Agent now persists step-level execution detail locally (via a real
TaskMetadataStore/Timeline wired into TaskRunner) and reports a bounded
in-progress snapshot piggybacked on lease renewal. Cloud persists that
snapshot per active assignment and exposes it through the existing task
list/detail query path; Cloud Console renders it as a live badge. Host
Agent's local console gains authenticated, read-only task list and
detail/timeline pages (same-origin, server-rendered) with inlined
screenshots.

Also fixes a pre-existing gap in the shared Timeline: the actual
per-step LLM prompt is now recorded instead of the task goal, benefiting
both Runtime and Host Agent consoles. When a host uses the cloud planner
transport, each decide call's prompt and resulting tool decision are
durably logged in a new planner_decision_log table (with bounded
retention) and browsable from Cloud Console; direct-transport hosts
explicitly surface a "not reported" state.

Includes Alembic migrations 0008 (progress columns on scheduled_tasks)
and 0009 (planner_decision_log), bounded Host-Agent-local retention,
dual-backend repository parity, and Vitest + pytest coverage. Task 6.5
(manual end-to-end device verification) remains.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-07-14 12:47:49 +08:00

6.5 KiB

Raw Blame History

Why

Nobody can see a task while it is running. Host Agent's local console only shows a coarse "current assignment" snapshot (task id, device id, goal, started-at) because the TaskRunner it drives is wired with metadata_store=None, timeline=None — every step transition happens in memory and is discarded the instant the assignment finishes. Cloud Control Plane only learns about an assignment at claim, heartbeat, and terminal-result time, so Cloud Console has nothing better to show. The local Runtime (api/rest.py + console/) is a separate process with its own independent TaskMetadataStore/Timeline, so it never sees a task that a Host Agent executed at all. An operator debugging a stuck or misbehaving task currently has no live signal anywhere in the system until the task finishes or times out.

What Changes

Wire Host Agent's AssignmentExecutor / create_execution_factories() with a real metadata_store and timeline (or Host-Agent-local equivalents) so the in-process TaskRunner actually records step-by-step status instead of discarding it.
Expose that step-level detail through Host Agent's local console: extend AgentStatusTracker//api/status (or add a focused endpoint) with current step index, step status, and a short in-progress step log; render it in the dashboard's "Current assignment" section instead of the static started-at-only view.
Add a progress-reporting path from Host Agent to Cloud Control Plane so the control plane learns step-level state near-real-time rather than only at claim/heartbeat/terminal-result. Extend the existing cloud.internal_api.models Pydantic schema (the single source of truth Host Agent already imports directly) rather than introducing a parallel schema.
Persist and expose the latest per-assignment progress on the Cloud Control Plane side, and surface it in Cloud Console so an operator watching a remote task sees live step progress, not just "dispatched" / "succeeded" / "failed".
Give an operator a web console view of Host-Agent-executed task progress without making the runtime/-owned packages import host or cloud concerns (enforced by test_runtime_owned_packages_do_not_import_host_or_cloud_concerns). After evaluating the alternative of making the Runtime console/ SPA multi-backend (pointing its existing JS bundle at a Host Agent's console origin), this change instead extends Host Agent's own server-rendered local console with read-only task list/detail/timeline pages, reusing the same query shape api/console.py already exposes to the Runtime SPA. This avoids new cross-origin/session-cookie surface between the SPA and Host Agent, and keeps runtime/ untouched. See design.md for the full trade-off analysis.
All three surfaces continue to use polling (matching current behavior); this change does not introduce SSE/WebSocket infrastructure unless design.md finds a compelling reason to.
Fix the shared Timeline/TaskRunner/AIPlanner recording path so a persisted step's "prompt" is the actual prompt sent to the LLM for that step (not the task's overall goal) and the model's resulting decision is captured too — this pre-existing gap affects Runtime and Host Agent alike and undermines the step-level detail this change otherwise adds.
Persist a durable, per-step log of full LLM prompt/response content on the Cloud Control Plane, for centralized troubleshooting — reusing the already-existing cloud-planner-proxy decide endpoint as the capture point (no new protocol/endpoint) rather than the coarse lease-renewal piggyback used for live index/status. This durable log is populated only for hosts using the cloud planner transport; hosts on the direct transport still get only the coarse index/status via lease renewal. Cloud Console gains a view to browse a task's full LLM interaction history.

Capabilities

New Capabilities

host-agent-task-progress: Host Agent captures step-level execution progress for its in-flight assignment (via a wired metadata_store/timeline) and exposes it through its local console/API.
cloud-task-progress-visibility: Cloud Control Plane receives, persists, and exposes near-real-time step-level progress for assignments it has dispatched to a Host Agent, and Cloud Console renders it.
host-agent-console-task-pages: Host Agent's local server-rendered console gains read-only task list/detail/timeline pages (mirroring api/console.py's task query shape) so an operator can inspect a Host-Agent-executed task's progress and history without needing the separate Runtime console/ SPA or violating the runtime/-package host/cloud isolation boundary.

Modified Capabilities

host-agent-protocol: add a requirement that the Host Agent reports in-progress step-level status updates to the control plane (in addition to the existing heartbeat/claim/renewal/result operations), and that the control plane accepts and stores them per active assignment.
cloud-planner-proxy: the existing planner-decision endpoint additionally persists each resolved decision's prompt/response into a durable, bounded-retention per-step log, instead of discarding it after the response is returned.

Impact

apps/device-host-agent/host_agent/app.py, execution.py, assignment.py, status.py, web/app.py — wire a real metadata/timeline store into the in-process TaskRunner, extend status tracking and the local console UI/API.
runtime/task.py, runtime/ai_planner.py, runtime/tool_calling_client.py, storage/timeline.py — fix the shared step-recording path so the real per-step prompt and the model's response are captured, not just the task goal and parsed tool call (a correctness fix in already-existing, shared code, not new behavior scope).
packages/cloud-platform/cloud/internal_api/models.py, packages/cloud-platform/cloud/internal_api/api.py (decide_planner_call), repository.py/sql_repository.py, a new Alembic migration — new progress-reporting request/response models and a persistence + query path for latest per-assignment coarse progress, and a new durable per-step planner_decision_log table (with its own retention job) populated from the existing planner-decision endpoint.
cloud-console/ (Vue3 SPA) — new UI to render live per-assignment progress, and a new view to browse a task's full LLM interaction history.
apps/device-host-agent/host_agent/web/app.py — new read-only task list/detail/timeline pages backed by the Host-Agent-local TaskMetadataStore/Timeline; no changes anticipated to console/ (Vue3 SPA).
No changes anticipated to driver/, device/, core/ device-control internals.

6.5 KiB Raw Blame History

Why