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 so that every step transition (status, index, the actual prompt submitted to the LLM for that step, the model's resulting decision, result, and screenshot when captured) is persisted as it happens, rather than discarded when the assignment completes. The persisted prompt SHALL be the prompt actually sent to the LLM for that specific step, not the task's overall goal.

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 any captured screenshot are persisted to the Host Agent's local task metadata store and timeline before the next step begins

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 local task storage is isolated from an unrelated local Runtime

The Host Agent SHALL use a configurable, Host-Agent-specific database and artifact path for its task metadata store and timeline, distinct from any local Runtime API's own task storage path, so that the two processes cannot silently collide or share state when run on the same machine.

Scenario: Host Agent and local Runtime run on the same machine

WHEN both a Host Agent process and a local Runtime API process run on the same machine with their default configurations
THEN each process reads and writes its own task metadata store and timeline without observing or modifying the other's data

2.8 KiB Raw Blame History