@mgiles/perk 3.1.0 → 3.3.0

package/extension/pi/v1/contextInjection.ts

@@ -0,0 +1,207 @@
+// The one marker-dedup'd context-injection mechanism (contracts §8.31 semantics) behind the
+// six injected authoring/adapter contexts: gist, plan, objective-authoring, refinement and the
+// plannotator/tombell plan adapters all register the same `before_agent_start` + `context` hook
+// pair around one injected, marker-dedup'd context. The MECHANICS live here — the live-evidence
+// dedup, the selection-driven retention filter, the guarded reads, the runner fence. Callers keep
+// flavor selection + content construction (the customType/marker vocabulary) in their
+// `InjectedContextSpec` closures; `isPlanGuidanceStage` is the one shared stage predicate (the
+// plan context and the two plan-adapter plan flavors).
+//
+// ONE decision drives both hooks: `spec.select` (the flavor to deliver this turn, or null). It
+// reads the FULL branch (`branchOf` — eligibility/state survive compaction), while the dedup
+// reads Pi's OWN live projection (`contextEvidence.ts`: `buildContextEntries()` → native
+// messages) and asks the typed predicate whether the selected flavor's marker is still delivered
+// — as user content (a cold prompt) or as the owned customType's content (a prior hidden copy).
+// A copy Pi has compacted out of context re-injects on the next turn even though the historical
+// entry still sits on the branch; a summary quoting the marker never counts. The submitting
+// `event.prompt` is checked BEFORE the projection read: at `before_agent_start` a cold launch's
+// prompt is not yet persisted, so only that check sees a cold seed on the launch turn.
+//
+// RETENTION follows SELECTION on the `context` event, and touches ONLY the owned customType: a
+// null selection (ineligible, or eligibility could not be established — a failed branch read or
+// a throwing selector) removes every owned custom message; a selected flavor retains only the
+// owned copies carrying that flavor's marker and removes obsolete sibling flavors (a
+// plan→objective transition under plannotator cannot retain the old plan-adapter instructions).
+// User/task messages are NEVER removed for carrying an owned marker — a cold seed, a quoted
+// marker, an `<untrusted_draft>` body are the human's/the door's input and stay byte-for-byte;
+// assistant/tool messages and other features' custom messages are never inspected. This filters
+// the OUTGOING model context only: persisted transcripts and compaction summaries are never
+// rewritten.
+//
+// Failure semantics: a failed branch read short-circuits INJECTION (no `select` call — an
+// empty-branch fallback would wrongly inject for a selector whose reads pass on `undefined`); a
+// failed projection read also returns without constructing or injecting content (a guessed copy
+// could double-deliver); on the `context` event the same failure fails CLOSED to "nothing
+// selected" — stale owned guidance must never survive an unreadable branch. Retention never
+// reads the projection.
+//
+// Deliberate NON-callers keep their own scan/strip semantics: `substrate/bindingDelivery.ts`
+// (strips only its own customType — never user turns; projection errors escape its hook),
+// `substrate/agentScratch.ts` (requires the exact current custom block, not a marker scan),
+// `substrate/toolGating.ts` (full-branch scan — the strict once-per-selected-branch read-only
+// marker; its `perk:mode-context` retention is independent of every authoring context here),
+// and `hunkFeedback/receiver.ts`.
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { GIST_AUTHOR_STAGE } from "../../authoring/gist/draft.ts";
+import { OBJECTIVE_AUTHOR_STAGE, OBJECTIVE_SAVE_STAGE } from "../../authoring/objective/prose.ts";
+import { REFINE_STAGE } from "../../authoring/refinement/context.ts";
+import { type BranchEntry, branchOf } from "../../substrate/workflowState.ts";
+import {
+  activeContextMessages,
+  type ContextMessage,
+  contextCarriesMarker,
+} from "./contextEvidence.ts";
+
+/**
+ * The stages plan guidance is withheld from, for one of two reasons: another authoring context
+ * OWNS the stage (the objective/gist/refinement installers inject their own contexts;
+ * `objective-save` rides `plan_review`'s objective-arm routing), or the stage is read-only but
+ * authors nothing (`audit`, the dev-only `perk-dev audit judge` door — a literal: it has no
+ * authoring module). The registry guard test pins the set against the read-only stages.
+ */
+const PLAN_GUIDANCE_EXCLUDED_STAGES: ReadonlySet<string> = new Set([
+  OBJECTIVE_AUTHOR_STAGE,
+  OBJECTIVE_SAVE_STAGE,
+  GIST_AUTHOR_STAGE,
+  REFINE_STAGE,
+  "audit",
+]);
+
+/**
+ * Plan guidance rides the read-only gate in every stage not excluded above: the stage-less warm
+ * `/plan` (`undefined`), the cold `plan`/`objective-plan` claims, and any other (unknown or
+ * read-write) stage id — fail-open like the stage tool filter.
+ */
+export function isPlanGuidanceStage(stage: string | undefined): boolean {
+  return stage === undefined || !PLAN_GUIDANCE_EXCLUDED_STAGES.has(stage);
+}
+
+/**
+ * One marker-dedup'd injected context: the owned customType + the flavor table. Each flavor is
+ * declared ONCE — the marker literal keys its content thunk — so the retention key, the dedup
+ * key (the selected key), and the injected content cannot drift apart: `select` returns a KEY of
+ * the table, never a free-floating marker/content pair.
+ */
+export interface InjectedContextSpec<K extends string = string> {
+  customType: string;
+  /**
+   * The flavor table: marker literal → content thunk (plannotator: all three flavor markers).
+   * A thunk is invoked ONLY after the dedup scan passes, preserving the scan-before-construct
+   * ordering (config reads/renders never run on dedup-suppressed turns). Caller contract: the
+   * rendered content carries its own key (the marker rides inside the template bytes — pinned by
+   * each caller's content tests); a marker-less content would defeat the dedup (re-inject every
+   * turn) AND the retention (an owned copy without its flavor's marker is removed as obsolete).
+   */
+  flavors: Readonly<Record<K, (ctx: ExtensionContext) => string>>;
+  /**
+   * Feature policy — the ONE eligibility/retention decision: the flavor to deliver this turn (a
+   * `flavors` key), or null (ineligible/defer). Drives injection on `before_agent_start` AND the
+   * owned-message retention on `context` (null removes every owned copy; a key retains only that
+   * flavor's copies).
+   */
+  select(ctx: ExtensionContext, branch: readonly BranchEntry[]): K | null;
+}
+
+/** The structural message slice the retention filter inspects. */
+interface OwnedMessage {
+  customType?: string;
+  content?: unknown;
+}
+
+/**
+ * The owned-message retention filter (module-private — tests drive it through the registered
+ * hook): messages of the owned customType survive only when a flavor is selected AND their
+ * content carries that flavor's marker (a string-content or text-part scan of the OWNED copy
+ * only); every other message — any role, any other customType — passes through untouched, marker
+ * or not.
+ */
+function retainSelectedFlavor<T>(messages: T[], customType: string, marker: string | null): T[] {
+  return messages.filter((m) => {
+    const msg = m as OwnedMessage;
+    if (msg.customType !== customType) return true;
+    return marker !== null && carriesMarker(msg.content, marker);
+  });
+}
+
+function carriesMarker(content: unknown, marker: string): boolean {
+  if (typeof content === "string") return content.includes(marker);
+  if (Array.isArray(content)) {
+    return content.some(
+      (c) =>
+        (c as { type?: string; text?: string }).type === "text" &&
+        ((c as { text?: string }).text ?? "").includes(marker),
+    );
+  }
+  return false;
+}
+
+/**
+ * Register the inject/retain hook pair for one marker-dedup'd context (contracts §8.31
+ * semantics). Call at the exact registration position the replaced hook pair held — hook
+ * ordering is frozen by each installer's internal sequence.
+ *
+ * - `before_agent_start`: guarded branch read (a failed read short-circuits — no `select` call,
+ *   no injection) → the runner fence (a runner child selects nothing — no `select` call) →
+ *   `spec.select` (null → no injection) → the submitting prompt carrying the SELECTED marker
+ *   suppresses (cold delivery before persistence; another flavor's marker does not) → guarded
+ *   projection read (a failed read returns — nothing constructed, nothing injected) → a live
+ *   owned copy of the selected marker suppresses (the content thunk is never invoked) → inject
+ *   `{ customType, content, display: false }`.
+ * - `context`: guarded branch read + the same fence + `spec.select` (a failed read or a throwing
+ *   selector fails closed to null) → retain the owned customType's copies carrying the selected
+ *   flavor's marker only; remove every other owned copy (all of them on null). No other message
+ *   is inspected.
+ *
+ * `runnerChild` is the composition root's per-`session_start` runner bit (§8.3): suppression
+ * only, never a grant — and ahead of `spec.select`, so a runner child performs no selector reads.
+ */
+export function installInjectedContext<K extends string>(
+  pi: ExtensionAPI,
+  spec: InjectedContextSpec<K>,
+  runnerChild: () => boolean,
+): void {
+  // Defensive over a widened K (string): an off-table key names no flavor — never inject or
+  // retain on it.
+  const flavorOf = (key: K | null): string | null =>
+    key !== null && spec.flavors[key] !== undefined ? key : null;
+  const selectedMarker = (ctx: ExtensionContext, branch: readonly BranchEntry[]): string | null =>
+    runnerChild() ? null : flavorOf(spec.select(ctx, branch));
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    let branch: readonly BranchEntry[];
+    try {
+      branch = branchOf(ctx);
+    } catch {
+      return;
+    }
+    const marker = selectedMarker(ctx, branch);
+    if (marker === null) return;
+    const content = spec.flavors[marker as K];
+    if (event.prompt.includes(marker)) return;
+    let live: readonly ContextMessage[];
+    try {
+      live = activeContextMessages(ctx);
+    } catch {
+      return;
+    }
+    if (contextCarriesMarker(live, { customType: spec.customType, marker })) return;
+    return {
+      message: {
+        customType: spec.customType,
+        content: content(ctx),
+        display: false,
+      },
+    };
+  });
+
+  pi.on("context", async (event, ctx) => {
+    let selected: string | null;
+    try {
+      selected = selectedMarker(ctx, branchOf(ctx));
+    } catch {
+      selected = null;
+    }
+    return { messages: retainSelectedFlavor(event.messages, spec.customType, selected) };
+  });
+}