86 lines
3.4 KiB
Markdown
86 lines
3.4 KiB
Markdown
# 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
|