@vellumai/assistant 0.6.5 → 0.6.6

package/src/daemon/conversation-runtime-assembly.ts

@@ -18,15 +18,22 @@ import {
   countMemoryPrefixBlocks,
   extractMemoryPrefixBlocks,
 } from "../memory/graph/conversation-graph-memory.js";
-import { searchPkbFiles } from "../memory/pkb/pkb-search.js";
 import type { QdrantSparseVector } from "../memory/qdrant-client.js";
 import { readSlackMetadata } from "../messaging/providers/slack/message-metadata.js";
 import {
   extractTagLineTexts,
+  isReactionTagLine,
   type RenderableSlackMessage,
   renderSlackTranscript,
 } from "../messaging/providers/slack/render-transcript.js";
 import { isPermissionControlsV2Enabled } from "../permissions/v2-consent-policy.js";
+import { getInjectors } from "../plugins/registry.js";
+import type {
+  InjectionBlock,
+  InjectionPlacement,
+  TurnContext,
+  TurnInjectionInputs,
+} from "../plugins/types.js";
 import type { ContentBlock, Message } from "../providers/types.js";
 import {
   type ActorTrustContext,
@@ -36,17 +43,10 @@ import {
 import { channelStatusToMemberStatus } from "../runtime/routes/inbound-stages/acl-enforcement.js";
 import type { SubagentState } from "../subagent/types.js";
 import { TERMINAL_STATUSES } from "../subagent/types.js";
-import { getLogger } from "../util/logger.js";
 import { getWorkspaceDir, getWorkspacePromptPath } from "../util/platform.js";
 import { stripCommentLines } from "../util/strip-comment-lines.js";
 import { filterMessagesForUntrustedActor } from "./conversation-lifecycle.js";
-import {
-  getInContextPkbPaths,
-  type PkbContextConversation,
-} from "./pkb-context-tracker.js";
-import { buildPkbReminder } from "./pkb-reminder-builder.js";
-
-const pkbReminderLog = getLogger("pkb-reminder");
+import { type PkbContextConversation } from "./pkb-context-tracker.js";
 
 /**
  * Describes the capabilities of the channel through which the user is
@@ -522,16 +522,11 @@ export function buildSubagentStatusBlock(
   return lines.join("\n");
 }
 
-/** Append a subagent status block to the last user message. */
-export function injectSubagentStatus(
-  message: Message,
-  statusBlock: string,
-): Message {
-  return {
-    ...message,
-    content: [...message.content, { type: "text" as const, text: statusBlock }],
-  };
-}
+// The `<active_subagents>` block is emitted by the `subagent-status` default
+// injector (`plugins/defaults/injectors.ts`) as an `append-user-tail`
+// placement. Use {@link applyRuntimeInjections} with
+// `options.subagentStatusBlock` set, or drive the injector chain directly
+// via `collectInjectorBlocks`.
 
 /**
  * Append voice call-control protocol instructions to the last user
@@ -575,42 +570,10 @@ export function readNowScratchpad(): string | null {
 }
 
 /**
- * Insert NOW.md scratchpad content into the user message, after any
- * injected context blocks (e.g. memory_context) but before the user's
- * original content.  This keeps the user's actual message as the last
- * thing the model reads.
+ * The `<NOW.md>` block is emitted by the `now-md` default injector
+ * (`plugins/defaults/injectors.ts`) as an `after-memory-prefix` placement.
+ * Use {@link applyRuntimeInjections} with `options.nowScratchpad` set.
  */
-export function injectNowScratchpad(
-  message: Message,
-  content: string,
-): Message {
-  const scratchpadBlock = {
-    type: "text" as const,
-    text: `<NOW.md Always keep this up to date; keep under 10 lines>\n${content}\n</NOW.md>`,
-  };
-
-  // Find insertion point: skip any leading injected-context text blocks
-  // (e.g. memory_context) so the scratchpad lands between injected context
-  // and the user's original content.
-  let insertIdx = 0;
-  for (let i = 0; i < message.content.length; i++) {
-    const block = message.content[i];
-    if (block.type === "text" && block.text.startsWith("<memory_context")) {
-      insertIdx = i + 1;
-    } else {
-      break;
-    }
-  }
-
-  return {
-    ...message,
-    content: [
-      ...message.content.slice(0, insertIdx),
-      scratchpadBlock,
-      ...message.content.slice(insertIdx),
-    ],
-  };
-}
 
 /** Strip `<NOW.md>` blocks injected by `injectNowScratchpad`. */
 export function stripNowScratchpad(messages: Message[]): Message[] {
@@ -638,16 +601,6 @@ const AUTOINJECT_FILENAME = "_autoinject.md";
 /** Max buffer.md lines injected into prompts — keeps context bounded even when filing is off. */
 const MAX_BUFFER_LINES = 50;
 
-/** Minimum hybrid-search score for a PKB path to surface as an injection hint. */
-const PKB_HINT_THRESHOLD = 0.5;
-
-/**
- * Stricter hint threshold for PKB entries under `archive/`. Archive files are
- * date-indexed dumps of older notes — they match loosely and are rarely the
- * most relevant read, so require a higher bar before recommending them.
- */
-const PKB_HINT_ARCHIVE_THRESHOLD = 0.7;
-
 /**
  * Read `_autoinject.md` from the PKB directory and return the list of
  * filenames to inject.
@@ -728,49 +681,10 @@ export function readPkbContext(): string | null {
   return parts.length > 0 ? parts.join("\n\n") : null;
 }
 
-/**
- * Insert PKB context into the user message, after any injected memory
- * blocks but before NOW.md and the user's original content.
- */
-export function injectPkbContext(message: Message, content: string): Message {
-  // Escape closing tags that could break out of the XML wrapper
-  const escaped = content.replace(
-    /<\/knowledge_base\s*>/gi,
-    "&lt;/knowledge_base&gt;",
-  );
-  const pkbBlock = {
-    type: "text" as const,
-    text: `<knowledge_base>\n${escaped}\n</knowledge_base>`,
-  };
-
-  // Find insertion point: skip any leading memory/image blocks
-  let insertIdx = 0;
-  for (let i = 0; i < message.content.length; i++) {
-    const block = message.content[i];
-    if (
-      block.type === "text" &&
-      (block.text.startsWith("<memory") ||
-        block.text.startsWith("</memory_image>") ||
-        block.text.startsWith("<memory_context"))
-    ) {
-      insertIdx = i + 1;
-    } else if (block.type === "image") {
-      // Memory images precede the memory text block
-      insertIdx = i + 1;
-    } else {
-      break;
-    }
-  }
-
-  return {
-    ...message,
-    content: [
-      ...message.content.slice(0, insertIdx),
-      pkbBlock,
-      ...message.content.slice(insertIdx),
-    ],
-  };
-}
+// The `<knowledge_base>` block is emitted by the `pkb-context` default
+// injector (`plugins/defaults/injectors.ts`) as an `after-memory-prefix`
+// placement, splicing immediately after any leading memory-prefix blocks.
+// Use {@link applyRuntimeInjections} with `options.pkbContext` set.
 
 /** Strip `<knowledge_base>` blocks injected by `injectPkbContext`. */
 export function stripPkbContext(messages: Message[]): Message[] {
@@ -1146,18 +1060,10 @@ export function stripChannelCapabilityContext(messages: Message[]): Message[] {
   return stripUserTextBlocksByPrefix(messages, ["<channel_capabilities>"]);
 }
 
-/**
- * Prepend workspace top-level directory context to a user message.
- */
-export function injectWorkspaceTopLevelContext(
-  message: Message,
-  contextText: string,
-): Message {
-  return {
-    ...message,
-    content: [{ type: "text", text: contextText }, ...message.content],
-  };
-}
+// The workspace top-level context block is emitted by the
+// `workspace-context` default injector (`plugins/defaults/injectors.ts`)
+// as a `prepend-user-tail` placement. Use {@link applyRuntimeInjections}
+// with `options.workspaceTopLevelContext` set.
 
 /**
  * Strip `<active_workspace>` (and legacy `<active_dynamic_page>`) blocks
@@ -1549,21 +1455,33 @@ function buildActiveThreadBlockFromRenderable(
   if (members.length === 0) return null;
 
   // The active-thread block is flattened to plain text below, which discards
-  // `Message.role`. Force a role-derived sender label on any member whose
-  // `rowToRenderable` emitted `null` (assistant rows, user rows without a
-  // real Slack displayName) so speaker attribution survives the flattening.
-  const labeledMembers = members.map((m) =>
-    m.senderLabel
-      ? m
-      : {
-          ...m,
-          senderLabel: m.role === "assistant" ? "@assistant" : "@user",
-        },
-  );
+  // `Message.role`. Assistant rows are relabeled in the post-render step:
+  // `renderSlackTranscript` emits assistant content with no tag-line wrapper
+  // (to prevent the model mimicking `[MM/DD/YY HH:MM]:` prefixes in outbound
+  // replies), so we prepend an explicit `@assistant:` label to the flattened
+  // line. Unnamed user rows (no real Slack displayName) get a `@user`
+  // senderLabel here so their tag line carries attribution through the
+  // renderer. Labeled user rows and assistant rows pass through unchanged.
+  const labeledMembers = members.map((m) => {
+    if (m.role === "assistant") return m;
+    if (m.senderLabel !== null) return m;
+    return { ...m, senderLabel: "@user" };
+  });
 
   const rendered = renderSlackTranscript(labeledMembers);
   if (rendered.length === 0) return null;
-  const lines = extractTagLineTexts(rendered).join("\n");
+  // Reaction / overflow-trailer lines already embed `@assistant` inline, so
+  // `isReactionTagLine` is used to skip those and avoid double-attribution
+  // (`@assistant: [... @assistant reacted ...]`). Regular content and the
+  // `[deleted]` sentinel get the prefix so attribution survives flattening.
+  const lines = rendered
+    .map((msg) => {
+      const text = extractTagLineTexts([msg])[0] ?? "";
+      return msg.role === "assistant" && !isReactionTagLine(text)
+        ? `@assistant: ${text}`
+        : text;
+    })
+    .join("\n");
   return `<active_thread>\n${lines}\n</active_thread>`;
 }
 
@@ -1715,13 +1633,32 @@ export function findLastInjectedNowContent(messages: Message[]): string | null {
 export type InjectionMode = "full" | "minimal";
 
 /**
- * Per-turn injection bytes captured for later persistence to message
- * metadata. Empty in this PR — later PRs capture `<turn_context>` and
- * `<system_reminder>` bodies so they survive daemon restarts.
+ * Per-turn injection bytes captured so `loadFromDb` can rehydrate historical
+ * user messages byte-for-byte after a daemon restart or conversation
+ * eviction. Persisting the exact injected text onto message metadata keeps
+ * Anthropic's prefix cache anchored to msg[0] instead of invalidating every
+ * turn on reload. Any field left `undefined` means that block was not
+ * injected on this turn.
  */
 export interface RuntimeInjectionBlocks {
   unifiedTurnContext?: string;
   pkbSystemReminder?: string;
+  workspaceBlock?: string;
+  nowScratchpadBlock?: string;
+  pkbContextBlock?: string;
+  /**
+   * Composed output of every plugin-registered {@link Injector}, concatenated
+   * in ascending `order`. Empty string when every injector opted out (returned
+   * `null`). Today the default injectors (`default-injectors` plugin)
+   * placeholder-return `null`, so this is only non-empty when a third-party
+   * plugin registers an injector that emits content.
+   *
+   * Populated by {@link composeInjectorChain} during
+   * {@link applyRuntimeInjections}. Distinct from the other `blocks` fields
+   * because those track specific hardcoded injections today; this field is
+   * the extensibility seam for {@link Injector} plugins.
+   */
+  injectorChainBlock?: string;
 }
 
 export interface RuntimeInjectionResult {
@@ -1730,118 +1667,449 @@ export interface RuntimeInjectionResult {
 }
 
 /**
- * Apply a chain of user-message injections to `runMessages`.
+ * Run every registered {@link Injector}'s `produce()` in ascending `order`
+ * and return every non-null block the chain produced.
+ *
+ * Injectors returning `null` are omitted from the result. The returned array
+ * preserves ascending-`order` sort so downstream callers (notably
+ * {@link applyRuntimeInjections}) can group blocks by `placement` and apply
+ * them declaratively without losing per-injector ordering within each slot.
+ */
+export async function collectInjectorBlocks(
+  ctx: TurnContext,
+): Promise<InjectionBlock[]> {
+  const injectors = getInjectors();
+  if (injectors.length === 0) return [];
+  const out: InjectionBlock[] = [];
+  for (const injector of injectors) {
+    const block = await injector.produce(ctx);
+    if (block) out.push(block);
+  }
+  return out;
+}
+
+/**
+ * Run every registered {@link Injector}'s `produce()` in ascending
+ * `order`, concatenate the non-null results into a single block of text,
+ * and return it.
+ *
+ * Separator: blank line between blocks. Injectors returning `null` are
+ * skipped entirely (no leading/trailing blank lines). When no injector
+ * contributes, the function returns an empty string.
  *
- * Each injection is optional — pass `null`/`undefined` to skip it.
- * Returns the final message array ready for the provider, along with a
- * `blocks` object reserved for captured injection bytes (currently empty).
+ * Used by tests that assert the concatenation contract and by callers that
+ * want a single informational string view of the chain. The canonical
+ * integration point is {@link applyRuntimeInjections}, which uses
+ * {@link collectInjectorBlocks} + placement-aware application to splice
+ * each block into the per-turn message array.
+ */
+export async function composeInjectorChain(ctx: TurnContext): Promise<string> {
+  const blocks = await collectInjectorBlocks(ctx);
+  const pieces: string[] = [];
+  for (const block of blocks) {
+    if (block.text.length > 0) pieces.push(block.text);
+  }
+  return pieces.join("\n\n");
+}
+
+/**
+ * Default block placement. Kept in sync with {@link InjectionBlock} so
+ * blocks produced without an explicit `placement` (e.g. third-party
+ * injectors written against the pre-G2.1 API) behave predictably.
+ */
+const DEFAULT_PLACEMENT: InjectionPlacement = "append-user-tail";
+
+/**
+ * Count leading memory-prefix blocks on a user message's `content`.
+ *
+ * Delegates to {@link countMemoryPrefixBlocks} from
+ * `memory/graph/conversation-graph-memory.js` — the same state-machine the
+ * pre-migration PKB-reminder branch used to find its splice point. The
+ * pre-migration `injectPkbContext` and `injectNowScratchpad` helpers used
+ * slightly simpler rules inline; reusing the canonical counter here
+ * collapses the three near-identical splice rules into one source of truth
+ * so the ordering of PKB-context / PKB-reminder / NOW blocks relative to
+ * any memory prefix is stable and testable. For the common case (just
+ * `<memory __injected>` text, no images), the output is byte-identical to
+ * the pre-migration helpers.
+ */
+function countMemoryPrefixBlocksOnContent(content: ContentBlock[]): number {
+  return countMemoryPrefixBlocks(content);
+}
+
+/**
+ * Apply one injector block to a `runMessages` array according to its
+ * declared {@link InjectionPlacement}.
+ *
+ * Preserves the byte-for-byte positional semantics of the pre-migration
+ * `inject*` helpers:
+ *  - `"prepend-user-tail"` — prepend to the tail user message's content.
+ *  - `"append-user-tail"`  — append to the tail user message's content.
+ *  - `"after-memory-prefix"` — splice immediately after any leading memory
+ *    prefix blocks (mirrors `injectPkbContext` / `injectNowScratchpad`).
+ *  - `"replace-run-messages"` — replace `runMessages` wholesale with
+ *    `block.messagesOverride`.
+ *
+ * Blocks with empty `text` on non-replace placements are no-ops (the
+ * pre-migration branches also short-circuited on empty strings).
+ */
+function applyInjectionBlock(
+  runMessages: Message[],
+  block: InjectionBlock,
+): Message[] {
+  const placement = block.placement ?? DEFAULT_PLACEMENT;
+
+  if (placement === "replace-run-messages") {
+    if (!block.messagesOverride) return runMessages;
+    return block.messagesOverride;
+  }
+
+  if (block.text.length === 0) return runMessages;
+
+  const userTail = runMessages[runMessages.length - 1];
+  if (!userTail || userTail.role !== "user") return runMessages;
+
+  const textBlock = { type: "text" as const, text: block.text };
+
+  switch (placement) {
+    case "prepend-user-tail":
+      return [
+        ...runMessages.slice(0, -1),
+        { ...userTail, content: [textBlock, ...userTail.content] },
+      ];
+    case "append-user-tail":
+      return [
+        ...runMessages.slice(0, -1),
+        { ...userTail, content: [...userTail.content, textBlock] },
+      ];
+    case "after-memory-prefix": {
+      const memoryPrefixCount = countMemoryPrefixBlocksOnContent(
+        userTail.content,
+      );
+      return [
+        ...runMessages.slice(0, -1),
+        {
+          ...userTail,
+          content: [
+            ...userTail.content.slice(0, memoryPrefixCount),
+            textBlock,
+            ...userTail.content.slice(memoryPrefixCount),
+          ],
+        },
+      ];
+    }
+  }
+}
+
+/**
+ * Per-turn options accepted by {@link applyRuntimeInjections}.
+ *
+ * Most fields flow through to the per-injector {@link TurnInjectionInputs}
+ * bag attached to the {@link TurnContext} the caller provides (or to an
+ * ephemeral {@link TurnContext} synthesized for test call sites). A small
+ * number of fields drive hardcoded branches that live outside the injector
+ * chain — `activeSurface`, `channelCapabilities`, `channelCommandContext`,
+ * `voiceCallControlPrompt`, `transportHints`, and `isNonInteractive` —
+ * because they are orchestrator-owned content that never made sense as
+ * plugin-overridable default injectors.
+ */
+export interface RuntimeInjectionOptions {
+  /**
+   * Active dashboard-surface context (read from `<active_workspace>`). Kept
+   * on the options bag rather than an injector because it is a
+   * channel-capability concern that has never been gated as a default
+   * injector.
+   */
+  activeSurface?: ActiveSurfaceContext | null;
+  workspaceTopLevelContext?: string | null;
+  channelCapabilities?: ChannelCapabilities | null;
+  channelCommandContext?: ChannelCommandContext | null;
+  unifiedTurnContext?: string | null;
+  voiceCallControlPrompt?: string | null;
+  pkbContext?: string | null;
+  pkbActive?: boolean;
+  /**
+   * Dense query vector surfaced from the graph memory retriever.
+   * When present together with `pkbActive`, used to run `searchPkbFiles`
+   * to surface relevance hints in the PKB system reminder. When missing,
+   * the reminder falls back to the flat static text.
+   */
+  pkbQueryVector?: number[];
+  /** Optional sparse vector accompanying `pkbQueryVector`. */
+  pkbSparseVector?: QdrantSparseVector;
+  /** Memory scope id used to filter PKB search results. */
+  pkbScopeId?: string;
+  /**
+   * The live conversation (or a minimal shape containing `messages`) used
+   * to compute which PKB paths are already "in context" and therefore
+   * suppressed from hint suggestions.
+   */
+  pkbConversation?: PkbContextConversation;
+  /** Auto-injected PKB filenames (resolved relative to `pkbRoot`). */
+  pkbAutoInjectList?: string[];
+  /** Absolute path to the PKB directory (e.g. `<workspace>/pkb`). */
+  pkbRoot?: string;
+  /**
+   * Working directory against which relative `file_read` tool paths
+   * resolve, used to detect workspace-relative reads like
+   * `pkb/threads.md`. Falls back to `pkbRoot` when omitted.
+   */
+  pkbWorkingDir?: string;
+  nowScratchpad?: string | null;
+  subagentStatusBlock?: string | null;
+  isNonInteractive?: boolean;
+  transportHints?: string[] | null;
+  /**
+   * Pre-rendered Slack chronological transcript that replaces the
+   * default `runMessages` history for any Slack conversation (channels
+   * and DMs alike).
+   *
+   * When `channelCapabilities` describes a Slack conversation and this
+   * array is non-empty, the `slack-messages` default injector emits a
+   * `replace-run-messages` block that swaps `runMessages` with this
+   * transcript. Channel renders include sibling-thread tags; DM renders
+   * are flat (DMs have no threads). The `transportHints` pipeline is
+   * skipped for any Slack conversation so the persisted view isn't
+   * duplicated by gateway-side hints.
+   *
+   * Callers build this via `loadSlackChronologicalMessages` (or the
+   * underlying `assembleSlackChronologicalMessages`) before invoking
+   * this function so the assembly path stays free of direct DB calls
+   * and remains easy to test.
+   */
+  slackChronologicalMessages?: Message[] | null;
+  /**
+   * Pre-rendered `<active_thread>` focus block listing the messages of
+   * the thread the current inbound user message belongs to.
+   *
+   * Appended to the FINAL user message ONLY when `channelCapabilities`
+   * describes a Slack non-DM channel. The block is non-persisted: history
+   * rebuilds re-derive it from storage on each turn, and
+   * `RUNTIME_INJECTION_PREFIXES` strips any `<active_thread>` blocks from
+   * prior turns so they do not accumulate.
+   *
+   * Callers build this via `loadSlackActiveThreadFocusBlock` (or the
+   * underlying `assembleSlackActiveThreadFocusBlock`). Pass `null` /
+   * `undefined` when the inbound is a top-level (non-thread) post.
+   */
+  slackActiveThreadFocusBlock?: string | null;
+  mode?: InjectionMode;
+  /**
+   * Per-turn {@link TurnContext} forwarded to plugin-registered
+   * {@link Injector}s via {@link collectInjectorBlocks}. When omitted,
+   * `applyRuntimeInjections` synthesizes an ephemeral context (with a
+   * fallback `trust` classification) so the default-injector chain still
+   * runs — call sites that build the options bag without holding a full
+   * `TurnContext` get the same chain output.
+   *
+   * When provided, the caller's `trust`, `conversationId`, `turnIndex`,
+   * etc. are preserved; the function layers its per-turn
+   * {@link TurnInjectionInputs} onto a shallow clone so the caller's
+   * `TurnContext` is not mutated.
+   */
+  turnContext?: TurnContext;
+}
+
+/**
+ * Build the {@link TurnInjectionInputs} bag from the options bag.
+ *
+ * Exposed so callers that already hold a {@link TurnContext} can layer the
+ * same per-turn inputs onto it before handing control to
+ * {@link collectInjectorBlocks} directly — useful for tests and for the
+ * overflow-reducer reinject path.
+ */
+export function buildTurnInjectionInputs(
+  options: RuntimeInjectionOptions,
+): TurnInjectionInputs {
+  return {
+    mode: options.mode,
+    workspaceTopLevelContext: options.workspaceTopLevelContext,
+    unifiedTurnContext: options.unifiedTurnContext,
+    pkbContext: options.pkbContext,
+    pkbActive: options.pkbActive,
+    pkbQueryVector: options.pkbQueryVector,
+    pkbSparseVector: options.pkbSparseVector,
+    pkbScopeId: options.pkbScopeId,
+    pkbConversation: options.pkbConversation,
+    pkbAutoInjectList: options.pkbAutoInjectList,
+    pkbRoot: options.pkbRoot,
+    pkbWorkingDir: options.pkbWorkingDir,
+    nowScratchpad: options.nowScratchpad,
+    subagentStatusBlock: options.subagentStatusBlock,
+    channelCapabilities: options.channelCapabilities,
+    slackChronologicalMessages: options.slackChronologicalMessages,
+    slackActiveThreadFocusBlock: options.slackActiveThreadFocusBlock,
+    activeSurface: options.activeSurface,
+    channelCommandContext: options.channelCommandContext,
+    voiceCallControlPrompt: options.voiceCallControlPrompt,
+    transportHints: options.transportHints,
+    isNonInteractive: options.isNonInteractive,
+  };
+}
+
+/** Minimal synthetic TurnContext used when the caller omits one. */
+function synthesizeFallbackTurnContext(
+  inputs: TurnInjectionInputs,
+): TurnContext {
+  return {
+    requestId: "runtime-assembly-fallback",
+    conversationId: "runtime-assembly-fallback",
+    turnIndex: 0,
+    trust: {
+      sourceChannel: inputs.channelCapabilities?.channel
+        ? (inputs.channelCapabilities.channel as TrustContext["sourceChannel"])
+        : "vellum",
+      trustClass: "unknown",
+    },
+    injectionInputs: inputs,
+  };
+}
+
+/**
+ * Apply the runtime-injection chain to `runMessages`.
+ *
+ * The canonical per-turn assembly pipeline for every provider call:
+ *
+ *  1. Build the per-turn {@link TurnInjectionInputs} bag from `options`.
+ *  2. Layer it onto a {@link TurnContext} — either the one the caller
+ *     supplies via `options.turnContext` (preserving its `requestId`,
+ *     trust, and other fields) or an ephemeral fallback synthesized here.
+ *  3. Drive the default + third-party {@link Injector} chain via
+ *     {@link collectInjectorBlocks}.
+ *  4. Apply the chain's `"replace-run-messages"` block (Slack chronological
+ *     transcript) first so subsequent branches operate on the replaced
+ *     tail. When replacement fires, re-prepend any memory-prefix blocks
+ *     that `graphMemory.prepareMemory` had attached to the original tail —
+ *     the Slack transcript is rendered fresh from persisted rows and
+ *     carries no memory prefix of its own.
+ *  5. Apply the chain's `"after-memory-prefix"` blocks in ascending
+ *     `order`. This runs BEFORE step 6's hardcoded prepends so the
+ *     memory-prefix counter sees only the memory blocks on the tail —
+ *     any `<channel_capabilities>` / `<channel_command_context>` /
+ *     `<transport_hints>` prepended first would push the count to zero
+ *     and force PKB / NOW to splice at the top of the tail. Within the
+ *     after-memory block, each successive splice lands at the memory
+ *     boundary, pushing earlier splices further from memory — so
+ *     higher-`order` blocks end up closer to the memory prefix.
+ *  6. Run the remaining hardcoded branches (`isNonInteractive`,
+ *     `voiceCallControlPrompt`, `activeSurface`, `channelCapabilities`,
+ *     `channelCommandContext`, `transportHints`) in their historical order.
+ *  7. Finally, apply the chain's remaining blocks by placement:
+ *     `"append-user-tail"` in ascending `order`, then `"prepend-user-tail"`
+ *     in descending `order` so the lowest-`order` prepend lands topmost in
+ *     the user tail content.
+ *
+ * Returns the final message array plus a `blocks` object holding the exact
+ * injected text for each captured block — callers persist those bytes to
+ * message metadata for later byte-exact rehydration.
  */
 export async function applyRuntimeInjections(
   runMessages: Message[],
-  options: {
-    activeSurface?: ActiveSurfaceContext | null;
-    workspaceTopLevelContext?: string | null;
-    channelCapabilities?: ChannelCapabilities | null;
-    channelCommandContext?: ChannelCommandContext | null;
-    unifiedTurnContext?: string | null;
-    voiceCallControlPrompt?: string | null;
-    pkbContext?: string | null;
-    pkbActive?: boolean;
-    /**
-     * Dense query vector surfaced from the graph memory retriever (PR 3).
-     * When present together with `pkbActive`, used to run `searchPkbFiles`
-     * to surface relevance hints in the PKB system reminder. When missing,
-     * the reminder falls back to the flat static text.
-     */
-    pkbQueryVector?: number[];
-    /** Optional sparse vector accompanying `pkbQueryVector`. */
-    pkbSparseVector?: QdrantSparseVector;
-    /** Memory scope id used to filter PKB search results. */
-    pkbScopeId?: string;
-    /**
-     * The live conversation (or a minimal shape containing `messages`) used
-     * to compute which PKB paths are already "in context" and therefore
-     * suppressed from hint suggestions.
-     */
-    pkbConversation?: PkbContextConversation;
-    /** Auto-injected PKB filenames (resolved relative to `pkbRoot`). */
-    pkbAutoInjectList?: string[];
-    /** Absolute path to the PKB directory (e.g. `<workspace>/pkb`). */
-    pkbRoot?: string;
-    /**
-     * Working directory against which relative `file_read` tool paths
-     * resolve, used to detect workspace-relative reads like
-     * `pkb/threads.md`. Falls back to `pkbRoot` when omitted.
-     */
-    pkbWorkingDir?: string;
-    nowScratchpad?: string | null;
-    subagentStatusBlock?: string | null;
-    isNonInteractive?: boolean;
-    transportHints?: string[] | null;
-    /**
-     * Pre-rendered Slack chronological transcript that replaces the
-     * default `runMessages` history for any Slack conversation (channels
-     * and DMs alike).
-     *
-     * When `channelCapabilities` describes a Slack conversation and this
-     * array is non-empty, it overrides `runMessages` so the model sees one
-     * chronologically-ordered transcript built from the stored Slack
-     * metadata. Channel renders include sibling-thread tags; DM renders
-     * are flat (DMs have no threads). The `transportHints` pipeline is
-     * skipped for any Slack conversation so the persisted view isn't
-     * duplicated by gateway-side hints.
-     *
-     * Callers build this via `loadSlackChronologicalMessages` (or the
-     * underlying `assembleSlackChronologicalMessages`) before invoking
-     * this function so the assembly path stays free of direct DB calls
-     * and remains easy to test.
-     */
-    slackChronologicalMessages?: Message[] | null;
-    /**
-     * Pre-rendered `<active_thread>` focus block listing the messages of
-     * the thread the current inbound user message belongs to.
-     *
-     * Appended (tail-block) to the FINAL user message ONLY when
-     * `channelCapabilities` describes a Slack non-DM channel. The block is
-     * non-persisted: history rebuilds re-derive it from storage on each
-     * turn, and `RUNTIME_INJECTION_PREFIXES` strips any `<active_thread>`
-     * blocks from prior turns so they do not accumulate.
-     *
-     * Callers build this via `loadSlackActiveThreadFocusBlock` (or the
-     * underlying `assembleSlackActiveThreadFocusBlock`). Pass `null` /
-     * `undefined` when the inbound is a top-level (non-thread) post.
-     */
-    slackActiveThreadFocusBlock?: string | null;
-    mode?: InjectionMode;
-  },
+  options: RuntimeInjectionOptions,
 ): Promise<RuntimeInjectionResult> {
   const mode = options.mode ?? "full";
-  let pkbSystemReminderCaptured: string | undefined;
-  const slackChannel = isSlackChannelConversation(options.channelCapabilities);
-  // Slack DMs and channels both assemble context from persisted message
-  // rows, so suppress hint injection for any Slack conversation. Other
-  // channels (telegram, email, etc.) keep the generic hint pipeline.
   const slackConversation = options.channelCapabilities?.channel === "slack";
+
+  // Build the per-injector inputs and attach them to the caller's
+  // TurnContext (without mutating it). When the caller didn't supply one,
+  // synthesize a minimal fallback so the chain still runs — test call sites
+  // that drive injection via `options` without constructing a full context
+  // continue to work.
+  const injectionInputs = buildTurnInjectionInputs(options);
+  const turnCtx: TurnContext = options.turnContext
+    ? { ...options.turnContext, injectionInputs }
+    : synthesizeFallbackTurnContext(injectionInputs);
+
+  const chainBlocks = await collectInjectorBlocks(turnCtx);
+
+  // Split the chain output by placement so the downstream assembly can
+  // process each slot with the correct ordering rule.
+  const prepends: InjectionBlock[] = [];
+  const appends: InjectionBlock[] = [];
+  const afterMemory: InjectionBlock[] = [];
+  let replaceBlock: InjectionBlock | null = null;
+  for (const block of chainBlocks) {
+    switch (block.placement ?? "append-user-tail") {
+      case "replace-run-messages":
+        // Later replace-run-messages blocks would overwrite earlier ones;
+        // the default chain only registers one (the Slack transcript).
+        replaceBlock = block;
+        break;
+      case "after-memory-prefix":
+        afterMemory.push(block);
+        break;
+      case "prepend-user-tail":
+        prepends.push(block);
+        break;
+      case "append-user-tail":
+        appends.push(block);
+        break;
+    }
+  }
+
+  // Track captured text for metadata persistence. Each field corresponds
+  // to a specific default-injector block id so the loop below can pick up
+  // the right capture without re-rendering.
+  //
+  // The capture is gated on the tail actually being a user message — if it
+  // isn't, `applyInjectionBlock` no-ops the block and no content is actually
+  // injected, so the persisted metadata must be undefined (matches
+  // pre-migration behaviour where the `inject*` helpers short-circuited the
+  // same way).
   let turnContextCaptured: string | undefined;
+  let workspaceCaptured: string | undefined;
+  let nowScratchpadCaptured: string | undefined;
+  let pkbContextCaptured: string | undefined;
+  let pkbSystemReminderCaptured: string | undefined;
+  const initialTail = runMessages[runMessages.length - 1];
+  const initialTailIsUser = !!initialTail && initialTail.role === "user";
+  if (initialTailIsUser) {
+    for (const block of chainBlocks) {
+      switch (block.id) {
+        case "unified-turn-context":
+          turnContextCaptured = block.text;
+          break;
+        case "workspace-context":
+          workspaceCaptured = block.text;
+          break;
+        case "now-md":
+          nowScratchpadCaptured = block.text;
+          break;
+        case "pkb-context":
+          pkbContextCaptured = block.text;
+          break;
+        case "pkb-reminder":
+          pkbSystemReminderCaptured = block.text;
+          break;
+      }
+    }
+  }
+
+  // Compose the block text into a single informational string for
+  // `injectorChainBlock`. Matches the pre-migration behaviour where the
+  // field captured the composed view of every third-party injector on
+  // the turn. We include default injectors here too so downstream
+  // observers see the full set.
+  const injectorChainPieces: string[] = [];
+  for (const block of chainBlocks) {
+    if (block.text.length > 0) injectorChainPieces.push(block.text);
+  }
+  const injectorChainBlock =
+    injectorChainPieces.length > 0
+      ? injectorChainPieces.join("\n\n")
+      : undefined;
+
   let result = runMessages;
-  // Slack channels AND DMs both override `runMessages` with a pre-rendered
-  // chronological transcript built from persisted message rows. The shared
-  // assembler (`assembleSlackChronologicalMessages`) renders thread tags
-  // for channels and a flat sequence for DMs, so the same branch handles
-  // both. The active-thread focus block below stays gated on `slackChannel`
-  // since DMs do not have threads.
-  if (
-    slackConversation &&
-    options.slackChronologicalMessages &&
-    options.slackChronologicalMessages.length > 0
-  ) {
+
+  // ── Step 1: Slack chronological replacement (chain "replace" block) ──
+  if (replaceBlock && replaceBlock.messagesOverride) {
     // `graphMemory.prepareMemory` prepends a `<memory __injected>` block
     // (and any memory-image groups) to the last user message before
     // runtime assembly runs. The Slack transcript is freshly rendered
     // from persisted rows and has no such prefix, so swap it in and then
     // re-prepend the captured prefix onto the new tail user message.
     const carriedMemoryBlocks = extractMemoryPrefixBlocks(runMessages);
-    result = options.slackChronologicalMessages;
+    result = replaceBlock.messagesOverride;
     if (carriedMemoryBlocks.length > 0) {
       const slackTail = result[result.length - 1];
       if (slackTail && slackTail.role === "user") {
@@ -1856,6 +2124,25 @@ export async function applyRuntimeInjections(
     }
   }
 
+  // ── Step 2: after-memory-prefix chain blocks ──
+  // These splice relative to the memory-prefix count on the tail content,
+  // so they must run BEFORE the hardcoded prepends in step 3. Otherwise
+  // any prepended `<channel_capabilities>` / `<channel_command_context>` /
+  // `<transport_hints>` (none of which are memory-prefix blocks) would
+  // drop the count to 0 and PKB / NOW would splice at the very top of
+  // the tail instead of immediately after memory.
+  //
+  // Ascending `order`: each splice lands at the memory-prefix boundary,
+  // pushing any previously-spliced block one slot further from memory.
+  // So higher-`order` blocks end up closer to the memory prefix.
+  for (const block of afterMemory) {
+    result = applyInjectionBlock(result, block);
+  }
+
+  // ── Step 3: hardcoded branches that stayed outside the injector chain ──
+  // These run in the same historical order as before G2.1 so their
+  // interleaving with any prior tail content stays stable.
+
   // For non-interactive conversations (scheduled jobs, work items), instruct the
   // model to never ask for clarification — there is no human present to answer.
   if (options.isNonInteractive) {
@@ -1887,117 +2174,6 @@ export async function applyRuntimeInjections(
     }
   }
 
-  if (mode === "full" && options.pkbContext) {
-    const userTail = result[result.length - 1];
-    if (userTail && userTail.role === "user") {
-      result = [
-        ...result.slice(0, -1),
-        injectPkbContext(userTail, options.pkbContext),
-      ];
-    }
-  }
-
-  // PKB behavioral nudge — injected on every turn when PKB is active so
-  // the model keeps reading topic files and calling `remember`. When a
-  // query vector is available from the graph memory retriever, run a
-  // hybrid PKB search to surface up to three relevance hints; fall back
-  // to the flat static reminder on empty results or any error.
-  if (mode === "full" && options.pkbActive) {
-    const userTail = result[result.length - 1];
-    if (userTail && userTail.role === "user") {
-      let hints: string[] = [];
-      const queryVector = options.pkbQueryVector;
-      if (
-        queryVector &&
-        queryVector.length > 0 &&
-        options.pkbScopeId &&
-        options.pkbConversation &&
-        options.pkbRoot
-      ) {
-        try {
-          const results = await searchPkbFiles(
-            queryVector,
-            options.pkbSparseVector,
-            8,
-            [options.pkbScopeId],
-          );
-          const workingDir = options.pkbWorkingDir ?? options.pkbRoot;
-          const inContext = getInContextPkbPaths(
-            options.pkbConversation,
-            options.pkbAutoInjectList ?? [],
-            options.pkbRoot,
-            workingDir,
-          );
-          const pkbRoot = options.pkbRoot;
-          // Gate on `denseScore` (cosine, [0, 1]) so the quality bar is stable
-          // regardless of whether sparse was provided. Rank by `hybridScore`
-          // (RRF) when available — that captures the sparse signal for
-          // re-ordering eligible hits. hybridScore and denseScore live on
-          // different scales, so items with hybridScore are ordered together
-          // and placed ahead of items that only have denseScore.
-          hints = results
-            .filter((r) => {
-              const abs = resolve(pkbRoot, r.path);
-              if (inContext.has(abs)) return false;
-              const threshold = r.path
-                .replace(/\\/g, "/")
-                .startsWith("archive/")
-                ? PKB_HINT_ARCHIVE_THRESHOLD
-                : PKB_HINT_THRESHOLD;
-              return r.denseScore >= threshold;
-            })
-            .sort((a, b) => {
-              const aHasHybrid = a.hybridScore !== undefined;
-              const bHasHybrid = b.hybridScore !== undefined;
-              if (aHasHybrid && !bHasHybrid) return -1;
-              if (!aHasHybrid && bHasHybrid) return 1;
-              if (aHasHybrid && bHasHybrid) {
-                return b.hybridScore! - a.hybridScore!;
-              }
-              return b.denseScore - a.denseScore;
-            })
-            .slice(0, 3)
-            .map((r) => r.path);
-        } catch (err) {
-          pkbReminderLog.warn(
-            { err: err instanceof Error ? err.message : String(err) },
-            "PKB hint search failed — falling back to flat reminder",
-          );
-          hints = [];
-        }
-      }
-
-      const reminder = buildPkbReminder(hints);
-      pkbSystemReminderCaptured = reminder;
-      // Splice the reminder in right after the memory prefix blocks so it
-      // lands above the user's typed text, producing the tail shape
-      // `[<turn_context>, <memory __injected>, <system_reminder>, ...your_text, ...later_appends]`
-      // after `unifiedTurnContext` later prepends `<turn_context>` at index 0.
-      const memoryPrefixCount = countMemoryPrefixBlocks(userTail.content);
-      result = [
-        ...result.slice(0, -1),
-        {
-          ...userTail,
-          content: [
-            ...userTail.content.slice(0, memoryPrefixCount),
-            { type: "text" as const, text: reminder },
-            ...userTail.content.slice(memoryPrefixCount),
-          ],
-        },
-      ];
-    }
-  }
-
-  if (mode === "full" && options.nowScratchpad) {
-    const userTail = result[result.length - 1];
-    if (userTail && userTail.role === "user") {
-      result = [
-        ...result.slice(0, -1),
-        injectNowScratchpad(userTail, options.nowScratchpad),
-      ];
-    }
-  }
-
   if (mode === "full" && options.activeSurface) {
     const userTail = result[result.length - 1];
     if (userTail && userTail.role === "user") {
@@ -2028,33 +2204,6 @@ export async function applyRuntimeInjections(
     }
   }
 
-  if (mode === "full" && options.subagentStatusBlock) {
-    const userTail = result[result.length - 1];
-    if (userTail && userTail.role === "user") {
-      result = [
-        ...result.slice(0, -1),
-        injectSubagentStatus(userTail, options.subagentStatusBlock),
-      ];
-    }
-  }
-
-  if (options.unifiedTurnContext) {
-    const userTail = result[result.length - 1];
-    if (userTail && userTail.role === "user") {
-      turnContextCaptured = options.unifiedTurnContext;
-      result = [
-        ...result.slice(0, -1),
-        {
-          ...userTail,
-          content: [
-            { type: "text" as const, text: options.unifiedTurnContext },
-            ...userTail.content,
-          ],
-        },
-      ];
-    }
-  }
-
   // Slack conversations (both channels and DMs) build their own
   // chronological transcript from persisted messages and intentionally do
   // not receive the per-turn `<transport_hints>` block — the rendered
@@ -2076,50 +2225,18 @@ export async function applyRuntimeInjections(
     }
   }
 
-  // Slack active-thread focus block: when the inbound user message lives
-  // inside a thread, append a non-persisted `<active_thread>` tail block
-  // listing that thread's parent + replies so the model can orient even
-  // when the channel-wide chronological transcript is long and
-  // interleaved. Stripped on subsequent rebuilds via the
-  // `RUNTIME_INJECTION_PREFIXES` list so focus blocks never accumulate.
-  if (
-    mode === "full" &&
-    slackChannel &&
-    typeof options.slackActiveThreadFocusBlock === "string" &&
-    options.slackActiveThreadFocusBlock.length > 0
-  ) {
-    const userTail = result[result.length - 1];
-    if (userTail && userTail.role === "user") {
-      result = [
-        ...result.slice(0, -1),
-        {
-          ...userTail,
-          content: [
-            ...userTail.content,
-            {
-              type: "text" as const,
-              text: options.slackActiveThreadFocusBlock,
-            },
-          ],
-        },
-      ];
-    }
+  // ── Step 4: apply remaining chain blocks by placement ──
+  // append-user-tail: ascending `order` so lower-order blocks come first
+  // in the append sequence.
+  for (const block of appends) {
+    result = applyInjectionBlock(result, block);
   }
 
-  // Workspace top-level context is injected last so it appears first
-  // (prepended) in the user message content, keeping cache breakpoints
-  // anchored to the trailing blocks.
-  if (mode === "full" && options.workspaceTopLevelContext) {
-    const userTail = result[result.length - 1];
-    if (userTail && userTail.role === "user") {
-      result = [
-        ...result.slice(0, -1),
-        injectWorkspaceTopLevelContext(
-          userTail,
-          options.workspaceTopLevelContext,
-        ),
-      ];
-    }
+  // prepend-user-tail: descending `order` so the lowest-order block lands
+  // topmost in the tail content (each successive prepend pushes the
+  // previous one further down).
+  for (let i = prepends.length - 1; i >= 0; i--) {
+    result = applyInjectionBlock(result, prepends[i]);
   }
 
   return {
@@ -2127,6 +2244,10 @@ export async function applyRuntimeInjections(
     blocks: {
       unifiedTurnContext: turnContextCaptured,
       pkbSystemReminder: pkbSystemReminderCaptured,
+      workspaceBlock: workspaceCaptured,
+      nowScratchpadBlock: nowScratchpadCaptured,
+      pkbContextBlock: pkbContextCaptured,
+      injectorChainBlock,
     },
   };
 }