98 lines
5.2 KiB
Markdown
98 lines
5.2 KiB
Markdown
# Proposal ADR-0020 — Agent Execution Plane V1
|
|
|
|
Status: Proposed
|
|
Task: DEV-000104
|
|
|
|
## Problem and evidence
|
|
|
|
ADR-0017 defines durable delegation semantics, but the audit found no
|
|
automatic dispatcher/worker plane, lease/heartbeat lifecycle, callback
|
|
authentication or independent verification boundary. A worker must be able
|
|
to stop, restart and resume without turning a missing callback into success or
|
|
silently duplicating external work.
|
|
|
|
## Decision proposed
|
|
|
|
1. Keep `work` as the canonical owner of `Delegation`, `AgentRun`,
|
|
`AgentCheckpoint`, `AgentResult` and verification gating. `capability`
|
|
owns executor-neutral agent implementations; adapters own transport and
|
|
process details.
|
|
2. Every dispatch has a stable `dispatch_id`, delegation id, run id,
|
|
implementation id, exact source/worktree identity, bounded instruction
|
|
artifact reference, requested capability set, authority/credential refs,
|
|
deadline and idempotency key. The derived instruction must preserve
|
|
OriginalHumanIntent, inferred goal, added context and verification plan as
|
|
separate provenance fields.
|
|
3. A worker must acquire a durable lease before execution. Lease ownership is
|
|
a fencing token, not an in-memory mutex. Heartbeats extend the lease only
|
|
for the same run and fencing token; an expired lease makes late callbacks
|
|
non-authoritative.
|
|
4. Dispatch and callback endpoints authenticate the worker identity and bind
|
|
every message to delegation, run, dispatch, implementation and fencing
|
|
token. Forged, replayed, out-of-order or duplicate callbacks are rejected
|
|
or recorded as non-authoritative evidence. Idempotent acknowledgement is
|
|
allowed only for the exact previously accepted event.
|
|
5. Checkpoints and artifacts are content-addressed metadata owned by
|
|
`artifact`, with typed refs from Work. Artifact attestation records source
|
|
revision/worktree, producer, digest, test command/result and capture time;
|
|
an un-attested path or log is not completion evidence.
|
|
6. Cancellation is a durable Work decision. The dispatcher sends cancellation
|
|
to the leased worker, records acknowledgement or timeout, and never erases
|
|
history. A worker that cannot prove cancellation remains `UNKNOWN` or
|
|
`RECOVERING` until reconciled.
|
|
7. Retry is policy-driven and distinguishes retryable transport/worker loss,
|
|
execution-window exhaustion, human blocker, invalid result and unknown
|
|
external outcome. Retry creates a new run under the same delegation and
|
|
preserves prior checkpoints/results; it never reuses an idempotency key for
|
|
an unproven external mutation.
|
|
8. A run result cannot complete Work directly. Independent verification must
|
|
consume the declared artifacts and tests through a separate verifier
|
|
identity and produce a typed verification result. Verification failure,
|
|
missing evidence and verifier unavailability remain distinct states.
|
|
9. Secrets are resolved only through approved `CredentialRef` boundaries and
|
|
are not copied into instructions, callbacks, artifacts, logs or task
|
|
packets. Worker startup has no ambient credential inheritance.
|
|
10. The plane is durable and restartable: dispatch intent, lease, heartbeat,
|
|
cancellation, checkpoint, result, verification and reconciliation events
|
|
are persisted before their projections claim progress.
|
|
|
|
## Lifecycle proposal
|
|
|
|
Delegation remains the higher-level human/work intent. A run progresses through
|
|
`DISPATCHED`, `LEASED`, `RUNNING`, `CHECKPOINTED`, `SUCCEEDED`, `FAILED`,
|
|
`CANCEL_REQUESTED`, `CANCELLED`, `EXHAUSTED`, `WAITING_HUMAN`, `UNKNOWN` or
|
|
`RECOVERING`, subject to explicit transition guards. `SUCCEEDED` means only
|
|
that the worker returned an accepted result; Work completion additionally
|
|
requires independent verification. Lease expiry and missing heartbeat never
|
|
become success.
|
|
|
|
## Alternatives and rationale
|
|
|
|
- An in-memory queue or goroutine was rejected because it loses dispatch state
|
|
on restart and violates durable timer/lease requirements.
|
|
- A single generic `AgentManager` was rejected because it collapses Work,
|
|
Capability, Artifact and Continuity ownership.
|
|
- Trusting worker-reported success was rejected because the worker and
|
|
verifier must remain separate authorities.
|
|
- Reusing the same run on retry was rejected because it makes duplicate
|
|
external effects and late callbacks indistinguishable.
|
|
|
|
## Boundaries, consequences and non-goals
|
|
|
|
No new canonical owner, provider, deployment authority, database migration,
|
|
Codex-specific domain contract or automatic self-modification is proposed.
|
|
The design enables restartable external work and truthful failure handling,
|
|
but requires durable event ordering, fencing, artifact storage and verifier
|
|
capacity before WP-301 can claim production readiness.
|
|
|
|
## Migration, rollback and revisit triggers
|
|
|
|
Implementation must begin behind an opt-in dispatch path with a dry-run
|
|
verifier and deterministic fake worker. Existing delegation records remain
|
|
readable; unknown legacy RUNNING records are classified by WP-302 rather than
|
|
silently resumed. Rollback disables new dispatch and drains/recovers leases;
|
|
history and artifacts remain. Revisit if a worker needs authority beyond its
|
|
declared capability, if a second transport changes callback guarantees, or if
|
|
artifact attestation cannot be made independent of the worker.
|
|
|