168 lines
6.1 KiB
Markdown
168 lines
6.1 KiB
Markdown
# AgentHarness lifecycle
|
|
|
|
`AgentHarness` is the orchestration layer above the low-level `Agent`. It owns session persistence, runtime configuration, resource resolution, operation locking, and extension-facing mutation semantics.
|
|
|
|
This document describes the current direction and implemented behavior. Some extension/session-facade details are planned and called out explicitly.
|
|
|
|
## State model
|
|
|
|
The harness separates state into four categories.
|
|
|
|
### Harness config
|
|
|
|
Harness config is the latest runtime configuration set by the application or extensions:
|
|
|
|
- model
|
|
- thinking level
|
|
- tools
|
|
- active tool names
|
|
- resources or resource provider
|
|
- system prompt or system prompt provider
|
|
|
|
Getters return harness config. They do not return the snapshot used by an in-flight provider request.
|
|
|
|
Setters update harness config immediately, including while a turn is in flight. Changes affect the next turn snapshot, not the currently running provider request.
|
|
|
|
### Turn snapshot
|
|
|
|
A turn snapshot is the concrete state used for one LLM turn. It is created by `createTurnState()` and contains:
|
|
|
|
- persisted session messages
|
|
- resolved resources
|
|
- resolved system prompt
|
|
- model
|
|
- thinking level
|
|
- all tools
|
|
- active tools
|
|
|
|
Static option values are used directly. Provider callbacks are invoked once per `createTurnState()` call. All logic for that turn uses the same snapshot.
|
|
|
|
### Session
|
|
|
|
The session contains persisted entries only. Session reads return persisted state and do not include queued writes.
|
|
|
|
### Pending session writes
|
|
|
|
Session writes requested while an operation is active are queued as pending session writes. Pending writes are based on session-entry shapes without generated fields (`id`, `parentId`, `timestamp`).
|
|
|
|
Pending session writes are always persisted. They are flushed at save points, at operation settlement, and in failure cleanup.
|
|
|
|
A public pending-writes/session-facade API is planned but not implemented yet.
|
|
|
|
## Operation phases
|
|
|
|
The harness has an explicit phase:
|
|
|
|
```ts
|
|
type AgentHarnessPhase = "idle" | "turn" | "compaction" | "branch_summary" | "retry";
|
|
```
|
|
|
|
Structural operations require `phase === "idle"` and synchronously set the phase before the first `await`:
|
|
|
|
- `prompt`
|
|
- `skill`
|
|
- `promptFromTemplate`
|
|
- `compact`
|
|
- `navigateTree`
|
|
|
|
Starting another structural operation while the harness is not idle throws.
|
|
|
|
The following operations are allowed during a turn where appropriate:
|
|
|
|
- `steer`
|
|
- `followUp`
|
|
- `nextTurn`
|
|
- `abort`
|
|
- runtime config setters
|
|
|
|
Phase/settlement semantics are still provisional and need a full lifecycle pass.
|
|
|
|
## Turn execution
|
|
|
|
`prompt`, `skill`, and `promptFromTemplate` follow the same flow:
|
|
|
|
1. Assert idle and set phase to `"turn"`.
|
|
2. Create a turn snapshot with `createTurnState()`.
|
|
3. Derive invocation text from that snapshot.
|
|
4. Execute the turn with `executeTurn()`.
|
|
|
|
`skill` and `promptFromTemplate` resolve their resource from the same snapshot that is passed to the turn. They do not resolve resources separately.
|
|
|
|
`steer`, `followUp`, and `nextTurn` accept text plus optional images and create user messages internally. `nextTurn` messages are inserted before the new user message on the next user-initiated turn.
|
|
|
|
Queue modes are live, not turn-snapshotted:
|
|
|
|
- `steeringMode`
|
|
- `followUpMode`
|
|
|
|
Changing a queue mode during a run affects the next queue drain. Queue drains happen at safe points.
|
|
|
|
## Save points
|
|
|
|
A save point occurs after an assistant turn and its tool-result messages have completed.
|
|
|
|
At a save point the harness:
|
|
|
|
1. flushes pending session writes after the agent-emitted messages for that turn
|
|
2. creates a fresh turn snapshot if the low-level loop may continue
|
|
3. applies the fresh context/model/thinking-level state before the next provider request
|
|
|
|
This lets model, thinking level, tool, resource, and system prompt changes made during a turn affect the next turn in the same run, while never mutating an in-flight provider request. The loop callbacks are not recreated at save points.
|
|
|
|
The low-level loop converts harness `ThinkingLevel` to provider `reasoning` at the provider boundary:
|
|
|
|
- `"off"` -> `undefined`
|
|
- all other thinking levels pass through
|
|
|
|
No state refresh is needed on `agent_end` except flushing leftover pending session writes and clearing the operation phase. The exact `settled` event timing is still under review.
|
|
|
|
## Hooks and events
|
|
|
|
Current hooks receive only the event payload. There is no extension context object yet.
|
|
|
|
Event payloads describe what is happening. Harness getters describe latest config for future snapshots.
|
|
|
|
The split between harness-specific events (`AgentHarnessOwnEvent`) and the union of low-level plus harness events (`AgentHarnessEvent`) is provisional but useful for distinguishing hookable harness events from public subscription events.
|
|
|
|
A future extension context may expose the harness and a queued-write session facade.
|
|
|
|
## Planned session facade
|
|
|
|
Extensions should eventually interact with a harness-scoped session facade rather than the raw session.
|
|
|
|
Planned read semantics:
|
|
|
|
- reads delegate to persisted session state
|
|
- reads do not include queued pending writes
|
|
|
|
Planned write semantics:
|
|
|
|
- idle: persist immediately
|
|
- busy: enqueue as pending session writes
|
|
|
|
A planned diagnostics API may expose pending writes explicitly:
|
|
|
|
```ts
|
|
getPendingWrites(): readonly PendingSessionWrite[]
|
|
```
|
|
|
|
Agent-emitted messages are persisted on `message_end` to preserve transcript ordering. Pending extension/session writes flush after those messages at save points.
|
|
|
|
## Abort
|
|
|
|
Abort is allowed during a turn. It aborts the low-level run and clears low-level steering/follow-up queues.
|
|
|
|
Abort does not discard pending session writes. Pending writes flush at the next save point if reached, at `agent_end`, or in operation failure cleanup.
|
|
|
|
Abort barrier semantics still need an audit.
|
|
|
|
## Compaction and tree navigation
|
|
|
|
Compaction and tree navigation are structural session mutations.
|
|
|
|
They are allowed only while idle and are not queued. They operate on persisted session state. The next prompt creates a fresh turn snapshot.
|
|
|
|
Branch summary generation is part of the tree navigation operation.
|
|
|
|
Auto-compaction and retry decision points are not implemented in `AgentHarness` yet.
|