Module agent_context

Expand description

AgentContextView — Contract C: the task-level context that must reach the LLM/Agent boundary, materialized once and consumed by every axis.

§The gap this closes (GH #20)

Task-level context lives in Ctx.meta.runtime (project_root / work_dir / task_metadata / run_id / project_name_alias, …) and has to reach the executing Agent through two independent renderers:

Spawner axis — the WS thin-path (crates/mlua-swarm-server/src/operator_ws/session.rs) splices individual Ctx.meta.runtime keys into the Spawn.directive text a MainAI reads.
Worker axis — Engine::fetch_worker_payload{,_trusted} (crate::core::engine) builds a crate::types::WorkerPayload a SubAgent pulls over GET /v1/worker/prompt; it never carried task-level meta at all (only task_id / attempt / agent / system / prompt).

Before this module, each axis field-by-field-pulled the keys it needed straight out of ctx.meta.runtime, so a new field (e.g. task_metadata) had to be wired into every consumer by hand — and task_metadata never made it into the directive text at all (the F2 gap tracked in the operator-execution-model guide).

§The fix: materialize once, consume everywhere

AgentContextView formalizes Contract C as one view struct. A new innermost SpawnerLayer (crate::middleware::agent_context) builds it from Ctx exactly once per spawn — after the outer TaskInputMiddleware / ProjectNameAliasMiddleware / WorkerBindingMiddleware layers have inserted their runtime keys, and before the base spawner stack (WS session / in-process AgentBlock) runs — and fans the materialized view out on two independent rails:

 TaskInput/Alias/Binding middlewares (outer, existing)  — insert runtime keys
        │ ctx (keys present)
        ▼
 AgentContextMiddleware (innermost layer)
   view = AgentContextView::from_ctx(ctx).apply_policy(&policy)
   (a) EngineState.agent_ctx[(task_id, attempt)].view = view     ← Worker axis source
   (b) ctx.meta.runtime[AGENT_CONTEXT_KEY] = json(view)          ← Spawner axis source
        │ inner.spawn(new_ctx)
        ▼
 base stack (OperatorDelegate → WS session.rs | in-proc AgentBlock runtime.rs)

(a) is read back by Engine::fetch_worker_payload{,_trusted} (keyed by (task_id, attempt), mirroring EngineState.prompts / .systems — Ctx itself is not stored, so the view has to be snapshotted at dispatch time to still be servable when the Worker axis fetches it later). (b) is read back via AgentContextView::materialized_or_from_ctx by both the Spawner axis (WS session.rs) and the in-process AgentBlock axis (crate::worker::agent_block::runtime) — falling back to AgentContextView::from_ctx when the middleware was never layered (backward compat).

A field added to AgentContextView (either a named field, or an extra entry) reaches both axes automatically — no per-consumer wiring required. ContextPolicy filters the materialized view before it is snapshotted / stashed; GH #21 Phase 1 wires it to Blueprint schema fields (Blueprint.default_agent_ctx / default_context_policy, AgentMeta.ctx / context_policy, resolved by crate::service::task_launch::derive_agent_ctx / derive_context_policies and consumed by crate::middleware::agent_context::AgentContextMiddleware).

Structs§

AgentContextView: Contract C’s view struct — the task-level context that must reach the LLM/Agent boundary, materialized once per spawn (see the module doc).
ContextPolicy: Filter over AgentContextView fields (GH #20/#21). Relocated to the schema crate in GH #21 Phase 1 so a Blueprint author can declare one via Blueprint.default_context_policy / AgentMeta.context_policy — this re-export keeps mlua_swarm::core::agent_context::ContextPolicy resolving unchanged for every existing caller (path-compat; see the context_policy_path_compat_reexport test below). The filter application logic lives on the view side, at AgentContextView::apply_policy. Receptacle for a Blueprint-driven filter over the materialized AgentContextView (GH #20/#21). Declared BP-side via Blueprint::default_context_policy (BP-global) or AgentMeta::context_policy (per-agent, outranks the BP-global tier) — resolved and applied by AgentContextMiddleware in the mlua-swarm core crate (this crate stays execution-free; see the crate doc). Default (include: None, exclude: vec![]) is pass-all — Self::allows returns true for every field name.
StepPointer: A pointer to one preceding step’s OUTPUT, embedded into AgentContextView::steps by crates/mlua-swarm-server/src/worker.rs’s GET /v1/worker/prompt handler (the projection-adapter ST5 Worker axis) — never the OUTPUT content itself (pointer-only invariant: no preview, no content bytes, matching the “worker payload never inline-embeds a projected value” contract crate::core::projection’s module doc establishes for the directive header).

Constants§

AGENT_CONTEXT_KEY: ctx.meta.runtime key under which the materialized AgentContextView (JSON-serialized) is stashed by crate::middleware::agent_context::AgentContextMiddleware — the Spawner axis’s read-back source (see the module doc).
PROJECTION_PLACEMENT_KEY: ctx.meta.runtime key under which the Blueprint-wide crate::core::projection_placement::ProjectionPlacement resolver (JSON-serialized, GH #27 follow-up to #23) is stashed by crate::middleware::agent_context::AgentContextMiddleware — the read-back source for the spawn-time in-flight projection pointer (crates/mlua-swarm-server/src/operator_ws/session.rs’s append_projection_pointer), which has no direct Engine handle to call Engine::projection_placement_for with. Absent (or undeserializable) falls back to ProjectionPlacement::default() (byte-compat).
PROJECT_NAME_ALIAS_KEY: ctx.meta.runtime key that carries Blueprint.metadata.project_name_alias. Canonical home as of GH #20; re-exported from crate::middleware::project_name_alias for API compatibility (same string value the existing ctx.meta.runtime.get("project_name_alias") consumers keyed off).
RUN_ID_KEY: ctx.meta.runtime key that carries the issue #13 run-id propagation value. Canonical home as of GH #20 (previously a bare literal at Engine::dispatch_attempt_with).
STEP_CTX_KEY: ctx.meta.runtime key that carries the GH #21 Phase 2 Step tier’s resolved context bundle (TaskSpec.step_ctx, threaded through by Engine::dispatch_attempt_with on every attempt — same insertion site as RUN_ID_KEY). Consumed by crate::middleware::agent_context::AgentContextMiddleware, which unpacks the bundle’s keys and applies them with the same only-if-absent mechanics as the Agent / BP-global tiers, ordered FIRST (Step outranks Agent and BP-global — see that middleware’s module doc for the full precedence narrative). The bundle itself (this key’s raw value) stays in the runtime bag verbatim — only its individual keys are folded into AgentContextView::extra.
TASK_METADATA_KEY: ctx.meta.runtime key that carries the Task-level free-form metadata object. Canonical home as of GH #20; re-exported from crate::middleware::task_input for API compatibility.
TASK_PROJECT_ROOT_KEY: ctx.meta.runtime key that carries the Task-level project root path. Canonical home as of GH #20; re-exported from crate::middleware::task_input for API compatibility.
TASK_WORK_DIR_KEY: ctx.meta.runtime key that carries the Task-level work dir path. Canonical home as of GH #20; re-exported from crate::middleware::task_input for API compatibility.