# 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