feat(host-agent): make execution history authoritative

2026-07-15 11:46:27 +08:00
parent ccde30e378
commit 77d4813bb2
46 changed files with 890 additions and 3132 deletions
@@ -1,30 +1,74 @@
-## ADDED Requirements
+## MODIFIED 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.
+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, the 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
+- **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
+- **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.
+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
+- **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
+- **THEN** its metadata, Timeline records, and screenshot artifacts remain
+  available for query
+
+## ADDED Requirements
+
+### 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
+
+## REMOVED Requirements

 ### 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