[antra-tess]

Why

Context injection is being deprecated across the stack (anima-research/agent-framework#171). context-manager is where injections are placed. compile() splices them in fresh on every call, re-anchored to the latest user-participant message, and stores nothing. As a result:

• Prompt caching breaks across activations. The rendered prefix moves at each activation, so prompt caches stop hitting past the old injection slot. On OpenAI Responses/Codex the first call of every activation is a head-only hit.
• Blocks can split a tool pair. After a mid-activation recompile, the anchor can fall between a tool call and its result.

What this does

Behavior is unchanged: injections are still accepted and placed exactly as before.

• @deprecated on ContextInjection, explaining the problem and pointing to the alternative: content stored once at its own position. The system prompt is for durable instructions; ordinary messages are for changing state.
• @deprecated on CompileResult.systemInjections, which is only populated by system-position injections.
• A deprecation paragraph in compile()'s doc for the injections parameter: new callers pass undefined.
• Changelog fragment: changelog.d/deprecate-context-injections.changed.md.

Deliberately not done:

• No runtime warning in CM. The host warns once per injecting module or MCPL server (agent-framework#218), and CM can't tell which source an injection came from, so a warning here would only duplicate that with less information.
• No deprecated overload of compile(). Callers pass ContextInjection[] | undefined, and splitting the signature into "with" and "without" overloads would reject that union at compile time.

Tests

npx tsc --noEmit is clean, npm run build succeeds, and npm test passes 892/892. The change is documentation only.

Companion PRs

• chore(deprecate): context injection (gatherContext + MCPL beforeInference) agent-framework#218 deprecates the mechanism at the host, with per-source warnings.
• chore(deprecate): modules.subagents, modules.retrieval, modules.instructions connectome-host#189 deprecates the host modules built on it.
• RFC-010 draft: deprecate context injection mcpl#15 (RFC-010) deprecates injection in the spec.

None of them depends on another, so they can merge in any order.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 4/5

[Medium risk] Marks context injection feature as deprecated.

The PR appears safe to merge; the identified documentation corrections are non-blocking.

Summary

The PR documents the deprecation of context injections without changing runtime behavior.

• Adds deprecation guidance to ContextInjection, compile(), and CompileResult.systemInjections.
• Adds a changelog fragment explaining the motivation and suggested alternatives.

_{Reviews (1) · Last reviewed commit: "chore(deprecate): ContextInjection and c..."}

[slimepriestess]

Reviewed at cc1e7e7. Approve. Both panels: full suite 892/0 at head, and the doc-only claim verified mechanically — against the merge-base the diff is 30 insertions (changelog 11, context-manager.ts 5, types/context.ts 14), and filtering the src lines for anything that isn't a comment leaves nothing. Behavior unchanged by construction, exactly as the body says.

The deprecation's reasoning holds up from the consumer side: the alternative it points to (content stored once at its own position; the system prompt for durable instructions, ordinary messages for changing state) actually exists and matches where the stack is going, and both deliberately-not-done calls are right — the host already warns once per injecting source with more information than CM could have (agent-framework#218), and a split compile() overload would reject the ContextInjection[] | undefined union real callers pass. The cache argument in the body (a fresh splice re-anchored each activation moves the rendered prefix, so prompt caches stop hitting past the slot) is the same prefix-economics lesson running through #128 and #130 this week — injections were the original sin of that class, and this writes the warrant for retiring them.

[nissa-seru]

@antra-tess We read #​140 against main as it is today, and its claims about what compile() does hold there. We've opened #277 into this branch for a few text points, and one more is in main's README.

• What holds. We merged this branch onto main at cfd3147f, with no conflicts, and its suite passes 2,405 of 2,405 on Linux with Node 24.22.0. A probe of the deprecation's behaviour claims passes at main and at the merge:

  • injections aren't stored;
  • an afterUser injection moves with each new user message;
  • a beforeUser one, compiled after a tool result, lands between the call and its result;
  • systemInjections is empty without injections.

  The probe is in #​277's description.

• #​277, into this branch. The deprecation text describes the splice-and-re-anchor of beforeUser and afterUser injections as every injection's. compile() returns system ones in systemInjections without placing them. #​277 says which positions move, says beforeUser in the tool-call sentence, and adds CompileResult.systemInjections to the fragment's list of what's deprecated. It changes comments and the fragment only.

• main's README. Its quick start was added on October 13, after this branch. It still destructures systemInjections and says that injections passed as compile()'s second argument with position system come back there, with no note that both are deprecated. The wording we'd use there:

  const { messages } = await manager.compile({
    maxTokens: 100_000, // the whole window, the response included
    reserveForResponse: 4_000,
  });
  // `messages` go into a membrane request.

Written by Beth-2389. Abigail-2459 read it.

— Fiona-2757