AgentEnvironment class

One inheritance LAYER of a named inference environment (ADR-0002 D1). A pure VALUE (config = VALUES in the tree — ADR-0000 A8); it carries no behavior and reaches no service. Nullable scalars mean "this layer does not declare it — INHERIT"; resolve folds a chain of layers into one flattened environment.

Constructors

AgentEnvironment({EnvBase base = const EnvBaseUndeclared(), String? command, List<String>? args, List<String> argsAppend = const [], PromptMode? promptMode, String? promptFlag, Map<String, String> env = const {}, String? model, InferenceTarget? target, String? pathCheck, String? resumeFlag, ResumeStyle? resumeStyle, List<String>? usageJsonArgs, String? sessionAdapter, List<String>? drivenArgs, String? roleAsset, List<String>? roleArgs, List<String>? memoryDirArgs, SeatPrimeMode? primeMode}): Creates a layer. Every field is optional: an undeclared field INHERITS (scalars/args) or contributes nothing (argsAppend/env).
const

Properties

args → List<String>?: Default argv (gc args). REPLACE: a non-null args replaces the inherited list wholesale (null inherits). Deliberately asymmetric with argsAppend — gc keeps this asymmetry.
final
argsAppend → List<String>: Extra argv (gc args_append). ACCUMULATE: every layer's argsAppend is concatenated root->leaf after the resolved args.
final
base → EnvBase: The inheritance pointer (gc base) — tri-state, LOAD-BEARING. Default EnvBaseUndeclared (absent).
final
command → String?: The executable to run (gc command). null INHERITS; a value REPLACES.
final
drivenArgs → List<String>?: Argv only a DRIVEN session rides — the station's headless one-turn spawn posture (claude's permission skip, opencode's run subcommand). spawnFor renders it in the args slot; an OPERATOR SEAT launch omits it, so the subtraction the seat needs is DECLARED per harness instead of computed from a flag literal in the launcher. This UN-DEFERS gc's print_args, whose deferral audit above named exactly this moment ("one-shot vs interactive must toggle per environment separately from args"). REPLACE across layers (last non-null wins), like args.
final
env → Map<String, String>: Process env layered for this environment (gc env). Key-wise merge: the leaf wins per key.
final
flattened → AgentEnvironment: This layer folded ALONE - its NORMAL FORM: resolve over a one-layer chain, so every field is kept and base collapses to EnvBaseStandalone.
no setter
hashCode → int: The hash code for this object.
no setteroverride
memoryDirArgs → List<String>?: How this harness is pointed at the seat's DISC as its native memory, as a template carrying kMemoryDirHole, which renders an ABSOLUTE path. null means the harness has no native memory home: the disc is still the seat's memory and the role definition tells the occupant to read its index. NOTHING is injected per session for any harness (the_grid#agent-disc-file-shape-and-home section 5).
final
model → String?: The model id (the role -> tier -> model axis — ADR-0000 A20; a the_grid ADDITION, gc carries the model via options_schema). null inherits.
final
needsSiteEndpoint → bool: Whether target requires a site endpoint (ADR-0002 D3). A null target is the default InferenceTarget.providerManaged => false.
no setter
pathCheck → String?: The real binary to PATH-check when command is a shell wrapper (gc path_check — the FT-2 sh -c case). null checks command itself.
final
primeMode → SeatPrimeMode?: How the newest handoff reaches the occupant. null inherits; the default when no layer declares one is SeatPrimeMode.prompt — the transport every harness already has.
final
promptFlag → String?: The flag used when promptMode is PromptMode.flag (gc prompt_flag).
final
promptMode → PromptMode?: How the brief is delivered (gc prompt_mode). null inherits; the default when none is declared anywhere is PromptMode.arg (gc's default).
final
resumeFlag → String?: The CLI token that resumes a session by id (gc resume_flag, e.g. --resume / resume). null means the tool has no resume.
final
resumeStyle → ResumeStyle?: How resumeFlag is applied (gc resume_style). null inherits; the default when resumeFlag is set is ResumeStyle.flag.
final
roleArgs → List<String>?: How this harness takes that role definition ON ARGV, as a template carrying kSeatHole. null means the harness has NO native role flag: the definition reaches it through the overlay flavor's own projection, already materialized at install, and the launcher passes nothing.
final
roleAsset → String?: WHERE this harness reads an operator seat's authored ROLE DEFINITION, as a GRID-HOME-RELATIVE path template carrying kSeatHole. The seat launcher REFUSES when the rendered path is absent — a seat is authored before it is occupied. This UN-DEFERS gc's instructions_file ("a harness whose instructions filename varies by tool"). null means this harness has no authored-persona home and cannot be occupied.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
sessionAdapter → String?: Adapter registry id for channel transport; null keeps one-turn transport.
final
target → InferenceTarget?: WHERE inference runs — the KIND only (ADR-0002 D3; a the_grid ADDITION from ADR-0008 ModelTarget). null inherits; the default is InferenceTarget.providerManaged.
final
usageJsonArgs → List<String>?: The argv that turns ON this tool's JSON usage surface (FT-2 — a the_grid addition beside gc's shell-wrapper pathCheck): claude ['--output-format', 'json'], codex ['--json']. null ⇒ NO usage surface, so a usageOut is IGNORED (the single spawnFor renders the plain invocation). REPLACE across layers (last non-null wins), like args.
final

Methods

noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toString() → String: A string representation of this object.
override
validate() → String?: A NAMED-invariant guard (guards LOUD or GONE — ADR-0000 A8): a PromptMode.flag transport with no promptFlag is unspawnable, and a resumeStyle set with no resumeFlag is meaningless. Returns the human error or null when legal — the two-moment posture of AgentHarnessRegistry.validate (return, don't throw; the caller fails the boot or the work).

Operators

operator ==(Object other) → bool: The equality operator.
override

Static Methods

resolve(List<AgentEnvironment> chain) → AgentEnvironment: Folds an inheritance chain — ROOT at index 0, LEAF last — into one flattened environment: