AgentCapability class

The IMPLEMENT capability — spawn the coding agent in the bead's workspace, parameterized over the AMBIENT agent scope (ADR-0008 Decision 10): it reads the work Bead, the Workspace, the station's AgentConfig default, and the AgentHarnessRegistry with the effect verb, resolves the effective config through the ladder (resolveAgentConfig — step params > bead grid.agent envelope > ambient; fail-closed → a per-work Failed), and delegates the INVOCATION to the resolved harness.

It declares the FRONTIER tier (AgentTier.frontier, beads pow-2c9 / pow-n6n.4): absent a bead or station override, the coding agent rides kFrontierModelDefault (opus) — the committee's critics declare the cheaper MID tier off the same ambient config. WHICH environment it rides is its typed BuildAgentEnvironment seat (ADR-0006 D2), never a name.

The POLICY stays here: buildAgentBrief renders the full bead (a title-only brief starves the agent, A36) + the local-first working agreement: work in the worktree, COMMIT, do NOT push, do NOT open a PR. Landing is an explicit OPT-IN (--land; ADR-0006 D3) and OFF by default. (claude's auth seam is the macOS keychain — A38; no token rides argv.)

Also materializes the bead's declared grid.dart pub linkage into the worktree (_linkWorkspace — ADR-0000 A1): the DART domain's envelope is part of the work DEFINITION, read here alongside the rest of the bead, and applied via the DartLinkService the_grid's dart_grid_assets pack ships (grid_assets → dart_grid_assets, the pub-subordinate-to-Dart direction).

Constructors

AgentCapability({String? devRoot, DartLinkService linkService = const DartLinkService(), OverlayMaterializer materializer = const OverlayMaterializer(), GridAssetRegistry? assetRegistry, GridAssetRosterOverride? assetRosterOverride, String overlaySourceRef = kUnknownSourceRef, Map<String, String> overlayArgs = const {}, AgentSessionAdapterRegistry sessionAdapters = kBuiltinAgentSessionAdapters, AgentSteerSource steers = const NoAgentSteerSource(), GitRunner? gitRunner})
Creates the agent capability. devRoot is the station's registered root checkout path (RootCheckout.path — "the registered root checkout's path") relative grid.dart dev-path links absolutize against in the per-bead worktree; null in an offline/dry-run build (no root registered — a relative link then refuses, never silently applies a broken override). linkService is injectable for tests.
const

Properties

completionContract → CompletionContract
The coding agent's working agreement IS "commit your work in the worktree", so the engine may PROVE an inferred completion against the workspace before the circuit advances (the_grid#a38-…: a oneTurn session's completion is judged by COMMIT PRESENCE, not by turn count or exit signal).
no setter
hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

createAllocation(AllocationInputs inputs) → Allocation
The default Allocation for a spawned process (ADR-0009 D6) — a ProcessAllocation driving spawn/interpretEvent over the transport. A one-shot (StepKind.job) is respawn-or-skip; a StepKind.daemon is adopt-or-respawn + detach-capable. Override only for a bespoke process effect.
inherited
createSession({required RuntimeProvider runtime, required String name, required String attemptId, required String instanceFence, required TreeContext context, required StepArgs args}) → ProcessSession?
Creates a protocol session for this incarnation, or null for one-turn I/O.
interpretEvent(RuntimeEvent event) → StepSignal
Maps a runtime event to a StepSignal (a job's clean exit → complete; a daemon's up-signal → ready; a crash → failed; anything else → none). The host writes the resulting cursor state through the chokepoint.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
probeCompletionArtifact(TreeContext context, StepArgs args) → Future<GateOutcome>
Proves the artifact promised by CompletionContract.artifactDurability is durably readable. Returns GateOutcome.clear only when durable, GateOutcome.present when absent, and GateOutcome.probeError when the read cannot decide. Must be idempotent and side-effect-free beyond reading the declared artifact.
inherited
proveFreshness(AdoptFence fence, TreeContext context, StepArgs args) → Future<bool>
Proves a prior incarnation at fence is STILL the live effect this capability manages — the daemon adopt-freshness half (ADR-0009 D4: "pgid alive ∧ token echoed over its endpoint"). The engine supplies the pgid-alive half (the injected liveness seam); this supplies the domain-specific half (a daemon probes its endpoint and checks the token echoes). No-adopt-on-faith: the default is false, so a job — or a daemon that cannot prove it — is respawned fresh, never adopted blind. MUST be side-effect-free beyond the read.
inherited
result(TreeContext context, StepArgs args) → Future<Map<String, String>?>
The ROUND-COMMIT FENCE, then the CAPTURE-ONLY usage telemetry (FT-2).
spawn(TreeContext context, StepArgs args) → RuntimeConfig
Describes the process to spawn — PURE; the host owns the actual provider.start (and layers the per-incarnation env over the config). Called synchronously at kick (the branch is mounted): read ambient values from context here with the effect verb.
supervisionPolicy(StepArgs args) → SupervisionPolicy
Gives an EMPTY round one more ride before a visible gate.
teardown(StepArgs args) → Future<void>
Idempotent belt-and-braces cleanup on unmount (TEARDOWN-11/12) — e.g. pkill a detached side-process by token. Defaults to a no-op (the host's provider.stop kills the managed group). Runs on the dispose path, where the branch may already be unmounted — so it receives NO tree context (a lookup there would throw); it works from args + its own state.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited