host-agent-task-progress Specification

Purpose

Define durable, bounded task and per-step history owned by the Host Agent.

Requirements

Requirement: Host Agent records step-level execution detail for its in-process TaskRunner

The Host Agent SHALL construct its in-process TaskRunner with a durable metadata store and Timeline. TaskRunner.run() SHALL create the task's metadata row idempotently before its first status update, so every execution path persists its task status and evidence rather than discarding updates for a missing row. Every completed step SHALL retain its index, actual per-step LLM prompt and decision when available, tool call, result, distinct before/after screenshots when captured, raw OCR observations when available, and normalized UI-tree result when the invoked tool returned one.

Scenario: A goal assignment starts execution

WHEN the Host Agent's AssignmentExecutor invokes its TaskRunner
THEN the task metadata row exists before the runner records its running status

Scenario: A step completes during goal execution

WHEN the Host Agent's TaskRunner completes a step while executing an assigned goal
THEN the step's status, index, actual per-step LLM prompt and response, tool call, result, and available evidence are persisted before the next step begins

Scenario: A workflow creates a planned-goal task

WHEN a WorkflowRunner invokes a Host Agent-configured TaskRunner for a planned-goal step
THEN that task is persisted without requiring the workflow caller to create a metadata row separately

Scenario: An assignment finishes

WHEN an assignment reaches a terminal state (succeeded or failed)
THEN its full step history remains queryable from the Host Agent's local store after the in-memory Task object is discarded

Requirement: Host-Agent-local task history is retained within a bounded window

The Host Agent SHALL prune persisted task metadata, Timeline records, and associated screenshot artifacts once they exceed a configurable retention window or count, so that indefinite process uptime does not cause unbounded local disk growth.

Scenario: Retention window is exceeded

WHEN a persisted task's age or position exceeds the configured retention threshold
THEN the Host Agent removes that task's metadata row, Timeline records, and screenshot artifacts from local storage

Scenario: Retention has not been exceeded

WHEN a persisted task is within the configured retention threshold
THEN its metadata, Timeline records, and screenshot artifacts remain available for query

Requirement: Host Agent correlates local execution records with Cloud assignments

For a Cloud-dispatched goal assignment, the Host Agent SHALL persist the Cloud task ID and attempt alongside its generated local Runtime task ID before execution starts. The correlation fields SHALL remain optional and generic in the shared storage layer.

Scenario: A Cloud goal assignment begins

WHEN the Host Agent begins executing a Cloud goal assignment
THEN the local task row records that assignment's Cloud task ID and attempt

Scenario: A task is not Cloud-dispatched

WHEN a shared Runtime caller executes a task without Host/Cloud assignment context
THEN the task metadata row is created and the optional source correlation fields remain empty

3.4 KiB Raw Blame History