@fiale-plus/pi-rogue-bundle 0.1.15 → 0.1.17

package/README.md

@@ -4,7 +4,9 @@
 
 It stitches together (and bundles for a true single-package install):
 
+- `@fiale-plus/pi-core` (shared contracts/helpers)
 - `@fiale-plus/pi-rogue-advisor` (logic; direct releases paused)
+- `@fiale-plus/pi-rogue-context-broker` (beta context-broker runtime; disabled by default)
 - `@fiale-plus/pi-rogue-orchestration` (logic; direct releases paused)
 
 Direct installs of the advisor/orchestration packages are paused (marked private). All users and future releases go through the bundle. See `docs/release.md` and root `AGENTS.md` / `README.md` for the release policy.
@@ -26,12 +28,17 @@ npm install
 ## Scope boundaries
 
 - **Lab / internal helpers are excluded from this bundle.**
+- The beta context-broker runtime is bundled for opt-in experiments but is not registered/enabled by default.
+- Opt-in consumers can import the runtime through the bundle subpath: `@fiale-plus/pi-rogue-bundle/context-broker`.
+- Set `PI_CONTEXT_BROKER_ENABLED=true` before starting Pi to register the beta `/context` command surface and prompt-load rewriting.
+- Optional durable broker storage can be enabled with `PI_CONTEXT_BROKER_DURABLE=true` or `PI_CONTEXT_BROKER_STORE_DIR=/path/to/store`; it defaults to SQLite/FTS and supports `PI_CONTEXT_BROKER_BACKEND=jsonl` for the legacy JSONL/blob backend.
 - `@fiale-plus/pi-rogue-bundle` is the only published surface for the logic.
 - Internal helper packages (`@fiale-plus/pi-rogue-guardrails`, `@fiale-plus/pi-rogue-brain`, `@fiale-plus/pi-rogue-repo-arch`) are maintained separately in the lab section and not published.
 
 ## Command surface
 
-- `/advisor`, `/goal`, `/loop`, `/autoresearch`, `/autoresearch-lab` plus status/config/command paths (all provided via the bundle).
+- Default: `/advisor`, `/goal`, `/loop`, `/autoresearch`, `/autoresearch-lab` plus status/config/command paths (all provided via the bundle).
+- Opt-in beta: `PI_CONTEXT_BROKER_ENABLED=true` adds `/context status`, `/context brief`, `/context lookup <handle|text>`, `/context pin <handle>`, and `/context prune` with autocomplete.
 
 ## Status
 

package/node_modules/@fiale-plus/pi-core/README.md

@@ -2,11 +2,12 @@
 
 Shared helpers for the Pi-Rogue workspace.
 
-Includes the first bounded context broker contract and in-memory implementation:
+Includes shared bounded context broker contracts:
 
-- `createInMemoryContextBroker()` stores artifacts behind stable `ctx://...` handles.
-- Lookups support handle, session, kind, tag, path, command prefix, branch, and text filters.
-- Omitted summaries become metadata-only placeholders, keeping raw payloads out of prompt briefs by default.
-- Pruning enforces per-session record/byte caps, TTL expiry on reads, and pinned-artifact retention.
+- `BoundedContextBroker`
+- `ContextArtifact` / `ContextArtifactInput`
+- lookup, retention, and status type definitions
+
+The executable in-memory implementation lives in `@fiale-plus/pi-rogue-context-broker`.
 
 Install locally from this repo root: `npm install`

package/node_modules/@fiale-plus/pi-core/src/context-broker.ts

@@ -1,6 +1,3 @@
-import { createHash } from "node:crypto";
-import { safeName } from "./text.js";
-
 export type ContextArtifactKind =
   | "tool_output"
   | "diff"
@@ -9,6 +6,8 @@ export type ContextArtifactKind =
   | "advisor_brief"
   | "memory_note";
 
+export type ContextArtifactTier = "hot" | "warm" | "cold";
+
 export interface ContextArtifactInput {
   sessionId: string;
   kind: ContextArtifactKind;
@@ -18,6 +17,7 @@ export interface ContextArtifactInput {
   paths?: string[];
   command?: string;
   branch?: string;
+  tier?: ContextArtifactTier;
   ttlMs?: number;
   pinned?: boolean;
   parentIds?: string[];
@@ -39,6 +39,7 @@ export interface ContextArtifact {
   paths: string[];
   command?: string;
   branch?: string;
+  tier: ContextArtifactTier;
   expiresAt?: number;
   pinned: boolean;
   parentIds: string[];
@@ -53,6 +54,7 @@ export interface ContextLookupQuery {
   path?: string;
   commandPrefix?: string;
   branch?: string;
+  tier?: ContextArtifactTier;
   text?: string;
   limit?: number;
 }
@@ -62,6 +64,12 @@ export interface ContextBrokerStatus {
   bytes: number;
   pinnedRecords: number;
   pinnedBytes: number;
+  hotRecords: number;
+  hotBytes: number;
+  warmRecords: number;
+  warmBytes: number;
+  coldRecords: number;
+  coldBytes: number;
   maxRecords: number;
   maxBytes: number;
 }
@@ -70,6 +78,15 @@ export interface ContextBrokerOptions {
   maxRecords?: number;
   maxBytes?: number;
   defaultTtlMs?: number;
+  hotTtlMs?: number;
+  warmTtlMs?: number;
+  coldTtlMs?: number;
+  hotMaxRecords?: number;
+  warmMaxRecords?: number;
+  coldMaxRecords?: number;
+  hotMaxBytes?: number;
+  warmMaxBytes?: number;
+  coldMaxBytes?: number;
   summaryBytes?: number;
   briefBytes?: number;
 }
@@ -82,227 +99,3 @@ export interface BoundedContextBroker {
   status(): ContextBrokerStatus;
   renderBrief(query?: ContextLookupQuery & { budgetBytes?: number }): string;
 }
-
-const DEFAULT_MAX_RECORDS = 256;
-const DEFAULT_MAX_BYTES = 128 * 1024 * 1024;
-const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
-const DEFAULT_SUMMARY_BYTES = 320;
-const DEFAULT_BRIEF_BYTES = 2_000;
-
-function normalizeList(values: string[] | undefined): string[] {
-  return [...new Set((values ?? []).map((value) => String(value || "").trim()).filter(Boolean))];
-}
-
-function payloadText(payload: string | Buffer): string {
-  return Buffer.isBuffer(payload) ? payload.toString("utf8") : String(payload ?? "");
-}
-
-function payloadBytes(payload: string | Buffer): number {
-  return Buffer.isBuffer(payload) ? payload.length : Buffer.byteLength(String(payload ?? ""), "utf8");
-}
-
-function hashPayload(payload: string | Buffer): string {
-  return createHash("sha256").update(Buffer.isBuffer(payload) ? payload : String(payload)).digest("hex");
-}
-
-function normalizeNeedle(value: string | undefined): string {
-  return String(value ?? "").trim().toLowerCase();
-}
-
-function truncateUtf8(text: string, maxBytes: number): string {
-  const limit = Math.max(0, Math.floor(maxBytes));
-  if (Buffer.byteLength(text, "utf8") <= limit) return text;
-  if (limit === 0) return "";
-
-  const ellipsis = "…";
-  const ellipsisBytes = Buffer.byteLength(ellipsis, "utf8");
-  const contentLimit = Math.max(0, limit - ellipsisBytes);
-  let used = 0;
-  let result = "";
-
-  for (const char of text) {
-    const bytes = Buffer.byteLength(char, "utf8");
-    if (used + bytes > contentLimit) break;
-    result += char;
-    used += bytes;
-  }
-
-  if (Buffer.byteLength(result + ellipsis, "utf8") <= limit) return result + ellipsis;
-  return result;
-}
-
-function summarizeArtifact(summary: string | undefined, kind: ContextArtifactKind, bytes: number, sha256: string, maxBytes: number): string {
-  const cleaned = String(summary ?? "").replace(/\s+/g, " ").trim();
-  if (cleaned) return truncateUtf8(cleaned, maxBytes);
-  return truncateUtf8(`[${kind} payload stored externally; ${bytes} bytes; sha256=${sha256.slice(0, 16)}]`, maxBytes);
-}
-
-function artifactMatches(artifact: ContextArtifact, query: ContextLookupQuery): boolean {
-  if (query.id && artifact.id !== query.id) return false;
-  if (query.handle && artifact.handle !== query.handle) return false;
-  if (query.sessionId && artifact.sessionId !== query.sessionId) return false;
-  if (query.kind && artifact.kind !== query.kind) return false;
-  if (query.branch && artifact.branch !== query.branch) return false;
-  if (query.tag && !artifact.tags.includes(query.tag)) return false;
-  if (query.path) {
-    const queryPath = query.path.replace(/\/$/, "");
-    if (!artifact.paths.some((path) => path === query.path || path.startsWith(`${queryPath}/`))) return false;
-  }
-  if (query.commandPrefix && !artifact.command?.startsWith(query.commandPrefix)) return false;
-
-  const text = normalizeNeedle(query.text);
-  if (text) {
-    const haystack = [artifact.summary, artifact.payload, artifact.command, artifact.tags.join(" "), artifact.paths.join(" ")]
-      .join("\n")
-      .toLowerCase();
-    if (!haystack.includes(text)) return false;
-  }
-
-  return true;
-}
-
-export function createInMemoryContextBroker(options: ContextBrokerOptions = {}): BoundedContextBroker {
-  const maxRecords = Math.max(1, Math.floor(options.maxRecords ?? DEFAULT_MAX_RECORDS));
-  const maxBytes = Math.max(1, Math.floor(options.maxBytes ?? DEFAULT_MAX_BYTES));
-  const defaultTtlMs = Math.max(0, Math.floor(options.defaultTtlMs ?? DEFAULT_TTL_MS));
-  const summaryBytes = Math.max(16, Math.floor(options.summaryBytes ?? DEFAULT_SUMMARY_BYTES));
-  const defaultBriefBytes = Math.max(64, Math.floor(options.briefBytes ?? DEFAULT_BRIEF_BYTES));
-  let artifacts: Array<ContextArtifact & { sequence: number }> = [];
-  let sequence = 0;
-
-  function currentStatus(): ContextBrokerStatus {
-    const bytes = artifacts.reduce((sum, artifact) => sum + artifact.bytes, 0);
-    const pinned = artifacts.filter((artifact) => artifact.pinned);
-    return {
-      records: artifacts.length,
-      bytes,
-      pinnedRecords: pinned.length,
-      pinnedBytes: pinned.reduce((sum, artifact) => sum + artifact.bytes, 0),
-      maxRecords,
-      maxBytes,
-    };
-  }
-
-  function dropExpired(now = Date.now(), protectedIds = new Set<string>()): void {
-    artifacts = artifacts.filter(
-      (artifact) => artifact.pinned || protectedIds.has(artifact.id) || !artifact.expiresAt || artifact.expiresAt > now,
-    );
-  }
-
-  function oldestRemovable(sessionId: string, protectedIds: Set<string>): { artifact: ContextArtifact & { sequence: number }; index: number } | undefined {
-    return artifacts
-      .map((artifact, index) => ({ artifact, index }))
-      .filter(({ artifact }) => artifact.sessionId === sessionId && !artifact.pinned && !protectedIds.has(artifact.id))
-      .sort((a, b) => {
-        if (a.artifact.createdAt !== b.artifact.createdAt) return a.artifact.createdAt - b.artifact.createdAt;
-        return a.artifact.sequence - b.artifact.sequence;
-      })[0];
-  }
-
-  function sessionWithinCaps(sessionId: string): boolean {
-    const sessionArtifacts = artifacts.filter((artifact) => artifact.sessionId === sessionId);
-    return sessionArtifacts.length <= maxRecords && sessionArtifacts.reduce((sum, artifact) => sum + artifact.bytes, 0) <= maxBytes;
-  }
-
-  function prune(now = Date.now(), protectedIds = new Set<string>()): ContextBrokerStatus {
-    dropExpired(now, protectedIds);
-
-    for (const sessionId of new Set(artifacts.map((artifact) => artifact.sessionId))) {
-      while (!sessionWithinCaps(sessionId)) {
-        const candidate = oldestRemovable(sessionId, protectedIds);
-        if (!candidate) break;
-        artifacts.splice(candidate.index, 1);
-      }
-    }
-
-    return currentStatus();
-  }
-
-  function status(): ContextBrokerStatus {
-    dropExpired();
-    return currentStatus();
-  }
-
-  function publish(input: ContextArtifactInput): ContextArtifact {
-    const now = input.createdAt ?? Date.now();
-    const payload = payloadText(input.payload);
-    const sha256 = hashPayload(input.payload);
-    const bytes = payloadBytes(input.payload);
-    const artifactSequence = ++sequence;
-    const id = `ctx-${now.toString(36)}-${String(artifactSequence).padStart(4, "0")}-${sha256.slice(0, 12)}`;
-    const session = safeName(input.sessionId || "session");
-    const kind = input.kind;
-    const handle = `ctx://session/${session}/${kind}/${sha256.slice(0, 16)}/${id}`;
-    const ttlMs = input.ttlMs ?? defaultTtlMs;
-
-    const artifact: ContextArtifact & { sequence: number } = {
-      id,
-      handle,
-      sessionId: input.sessionId,
-      kind,
-      createdAt: now,
-      updatedAt: now,
-      bytes,
-      sha256,
-      payload,
-      summary: summarizeArtifact(input.summary, kind, bytes, sha256, summaryBytes),
-      tags: normalizeList(input.tags),
-      paths: normalizeList(input.paths),
-      command: input.command?.trim() || undefined,
-      branch: input.branch?.trim() || undefined,
-      expiresAt: ttlMs > 0 ? now + ttlMs : undefined,
-      pinned: Boolean(input.pinned),
-      parentIds: normalizeList(input.parentIds),
-      sequence: artifactSequence,
-    };
-
-    artifacts = [artifact, ...artifacts];
-    prune(now, new Set([artifact.id]));
-    return artifact;
-  }
-
-  function lookup(query: ContextLookupQuery = {}): ContextArtifact[] {
-    dropExpired();
-    const limit = Math.max(1, Math.floor(query.limit ?? (artifacts.length || 1)));
-    return artifacts
-      .filter((artifact) => artifactMatches(artifact, query))
-      .sort((a, b) => Number(b.pinned) - Number(a.pinned) || b.createdAt - a.createdAt || b.sequence - a.sequence)
-      .slice(0, limit);
-  }
-
-  function pin(idOrHandle: string, pinned = true): ContextArtifact | null {
-    dropExpired();
-    const artifact = artifacts.find((candidate) => candidate.id === idOrHandle || candidate.handle === idOrHandle) ?? null;
-    if (!artifact) return null;
-    artifact.pinned = pinned;
-    artifact.updatedAt = Date.now();
-    prune();
-    return artifacts.find((candidate) => candidate.id === artifact.id) ?? null;
-  }
-
-  function renderBrief(query: ContextLookupQuery & { budgetBytes?: number } = {}): string {
-    const budget = Math.max(64, Math.floor(query.budgetBytes ?? defaultBriefBytes));
-    const lines = [
-      "## Context Broker",
-      `Budget: ${budget} bytes`,
-      ...lookup({ ...query, limit: query.limit ?? 8 }).map((artifact) => {
-        const pin = artifact.pinned ? " pinned" : "";
-        const path = artifact.paths.length ? ` paths=${artifact.paths.slice(0, 3).join(",")}` : "";
-        const tags = artifact.tags.length ? ` tags=${artifact.tags.slice(0, 3).join(",")}` : "";
-        return `- ${artifact.handle} kind=${artifact.kind}${pin}${path}${tags} summary="${artifact.summary}"`;
-      }),
-      "Lookup: use broker lookup by handle/path/tag/kind/session before replaying raw payloads.",
-    ];
-
-    return truncateUtf8(lines.join("\n"), budget);
-  }
-
-  return {
-    publish,
-    lookup,
-    pin,
-    prune,
-    status,
-    renderBrief,
-  };
-}

package/node_modules/@fiale-plus/pi-rogue-advisor/src/extension.ts

@@ -283,6 +283,15 @@ function brief(s: SessionState): string {
   return lines.join("\n").slice(0, 1200);
 }
 
+function contextBrokerBrief(pi: ExtensionAPI): string {
+  try {
+    const text = (pi as any).__piRogueContextBroker?.renderBrief?.();
+    return typeof text === "string" && text.includes("ctx://") ? sanitizeAdvisorText(text).slice(0, 2400) : "";
+  } catch {
+    return "";
+  }
+}
+
 const CLIPBOARD_IMAGE_PATH_RE = /(?:\/(?:private\/)?var\/folders\/[^\s"'`<>]+\/T|\/(?:tmp|var\/tmp))\/clipboard-\d{4}-\d{2}-\d{2}-[A-Za-z0-9-]+\.(?:png|jpe?g|gif|webp)\b/g;
 
 export function sanitizeAdvisorText(text: unknown): string {
@@ -881,12 +890,18 @@ async function askAdvisor(pi: ExtensionAPI, ctx: any, question: string, scope: s
   const state = loadState();
   if (!question.trim()) return { text: "Ask a question.", error: "empty" };
 
-  const ck = hash("adv", config.model ?? "auto", squish(question, 300), includeWork ? brief(state) : "");
+  const brokerBrief = includeWork ? contextBrokerBrief(pi) : "";
+  const ck = hash("adv", config.model ?? "auto", squish(question, 300), includeWork ? brief(state) : "", brokerBrief);
   const cache = loadCache();
   if (cache[ck]) { state.cacheHits++; saveState(state); return { text: cache[ck], cached: true }; }
 
   const msgs = [
-    { role: "user", content: [ `Question: ${question}`, scope ? `Scope: ${scope}` : "", includeWork && brief(state) ? `Session:\n${brief(state)}` : "" ].filter(Boolean).join("\n"), timestamp: new Date().toISOString() },
+    { role: "user", content: [
+      `Question: ${question}`,
+      scope ? `Scope: ${scope}` : "",
+      includeWork && brief(state) ? `Session:\n${brief(state)}` : "",
+      brokerBrief ? `Context broker brief:\n${brokerBrief}` : "",
+    ].filter(Boolean).join("\n"), timestamp: new Date().toISOString() },
   ] as any[];
 
   const completed = await completeWithModelFallback(ctx, config, ADVISOR_SYSTEM, msgs, { maxTokens: 600, reasoning: "medium" as ThinkingLevel });
@@ -984,7 +999,8 @@ async function doReview(pi: ExtensionAPI, ctx: any, trigger: string, delta: stri
     }
 
     const b = brief(state);
-    if (!b) {
+    const brokerBrief = contextBrokerBrief(pi);
+    if (!b && !brokerBrief) {
       finalDecision = "defer";
       finalReason = "missing brief context";
       markReviewApplied(state, signature, trigger, finalDecision, finalReason, true);
@@ -993,7 +1009,7 @@ async function doReview(pi: ExtensionAPI, ctx: any, trigger: string, delta: stri
       return;
     }
 
-    const rk = hash("rev", trigger, b, delta, String(meta.fileChanged), String(meta.failed), String(meta.isAgentEnd), String(reviewRoute.label), signature);
+    const rk = hash("rev", trigger, b, brokerBrief, delta, String(meta.fileChanged), String(meta.failed), String(meta.isAgentEnd), String(reviewRoute.label), signature);
     const cache = loadCache();
     if (cache[rk]) {
       finalDecision = "defer";
@@ -1011,7 +1027,8 @@ async function doReview(pi: ExtensionAPI, ctx: any, trigger: string, delta: stri
         `Delta: ${delta || "(none)"}`,
         `Files: ${meta.fileChanged} Errors: ${meta.failed}`,
         `Route: ${summarizeRoute(reviewRoute)}`,
-        `Brief:\n${b}`,
+        b ? `Brief:\n${b}` : "",
+        brokerBrief ? `Context broker brief:\n${brokerBrief}` : "",
       ].join("\n"), timestamp: new Date().toISOString() },
     ] as any[];
     const completed = await completeWithModelFallback(ctx, config, REVIEW_SYSTEM, msgs, { maxTokens: 400, reasoning: "low" as ThinkingLevel });
@@ -1140,13 +1157,14 @@ export function registerAdvisor(pi: ExtensionAPI): void {
     const prompt = typeof event.prompt === "string" && event.prompt.trim() ? squish(event.prompt, 1000) : "";
     if (prompt) state.lastTask = prompt;
     const briefText = brief(state);
+    const brokerBrief = contextBrokerBrief(pi);
     const intent = prompt ? classifyIntent(prompt) : "";
     const mode = prompt ? classifyMode(prompt) : "";
     const intentTag = intent ? `Intent: ${intent}` : "";
     const modeTag = mode ? `Mode: ${mode}` : "";
     // Enrich preflight text with session context so the binary gate has more signal
-    const enrichedText = [prompt, event.systemPrompt || "", briefText ? `Brief: ${briefText}` : "", intentTag, modeTag].filter(Boolean).join(" ");
-    const routeInput: AdvisorRouteInput = { phase: "preflight", text: enrichedText || prompt || event.systemPrompt || briefText || intentTag || modeTag || "", brief: briefText };
+    const enrichedText = [prompt, event.systemPrompt || "", briefText ? `Brief: ${briefText}` : "", brokerBrief ? `Context broker: ${brokerBrief}` : "", intentTag, modeTag].filter(Boolean).join(" ");
+    const routeInput: AdvisorRouteInput = { phase: "preflight", text: enrichedText || prompt || event.systemPrompt || briefText || brokerBrief || intentTag || modeTag || "", brief: [briefText, brokerBrief].filter(Boolean).join("\n\n") };
 
     // Binary gate model — fast local classifier for continue/escalate decisions
     const gatePrediction = binaryGatePredict(routeInput.text);
@@ -1191,6 +1209,7 @@ export function registerAdvisor(pi: ExtensionAPI): void {
         note,
         controlTag,
         briefText ? `Brief (cache-aware):\n${briefText}` : "",
+        brokerBrief ? `Context broker brief (lookup-first):\n${brokerBrief}` : "",
       ].filter(Boolean).join("\n\n"),
     };
   });

package/node_modules/@fiale-plus/pi-rogue-advisor/src/loop-convergence.test.ts

@@ -93,6 +93,7 @@ describe("advisor two-agent convergence", () => {
   let messageRenderers: MessageRendererMap;
   let sendMessageMock: ReturnType<typeof vi.fn>;
   let completeSimpleMock: ReturnType<typeof vi.fn>;
+  let piMock: any;
   let priorState: string | null = null;
   let priorConfig: string | null = null;
   let priorCache: string | null = null;
@@ -107,6 +108,7 @@ describe("advisor two-agent convergence", () => {
     commands = setup.commands;
     messageRenderers = setup.messageRenderers;
     sendMessageMock = setup.sendMessage;
+    piMock = setup.pi;
 
     mkdirSync(dirname(ADVISOR_STATE_PATH), { recursive: true });
     writeFileSync(ADVISOR_CONFIG_PATH, JSON.stringify({ mode: "auto", review: "light", checkins: "off", checkinIntervalMinutes: 30 }, null, 2), "utf8");
@@ -377,6 +379,21 @@ describe("advisor two-agent convergence", () => {
     );
   });
 
+  it("includes broker briefs in manual advisor context when available", async () => {
+    expect(commands.advisor).toBeTruthy();
+    piMock.__piRogueContextBroker = {
+      renderBrief: () => "## Context Broker\nHot:\n- ctx://session/s/tool_output/abc/ctx-1 summary=\"npm test passed\"",
+    };
+    completeSimpleMock.mockResolvedValue({ content: [{ type: "text", text: "Use the broker handle as evidence." }] });
+
+    await commands.advisor.handler("should we use broker context", ctx);
+
+    const messages = completeSimpleMock.mock.calls.at(-1)?.[1]?.messages;
+    const promptText = JSON.stringify(messages ?? completeSimpleMock.mock.calls.at(-1));
+    expect(promptText).toContain("Context broker brief");
+    expect(promptText).toContain("ctx://session/s/tool_output/abc/ctx-1");
+  });
+
   it("does not re-run advisory review on repeated agent-end material snapshots", async () => {
     const preflight = handlers.before_agent_start;
     const agentEnd = handlers.agent_end;

package/node_modules/@fiale-plus/pi-rogue-context-broker/README.md

@@ -0,0 +1,44 @@
+# Pi-Rogue Context Broker
+
+Beta context broker runtime for Pi-Rogue.
+
+This package contains the executable in-memory bounded broker implementation:
+
+- `createInMemoryContextBroker()` stores artifacts behind stable `ctx://...` handles.
+- Lookups support handle, session, kind, tag, path, command prefix, branch, tier, and text filters.
+- Omitted summaries become metadata-only placeholders, keeping raw payloads out of prompt briefs by default.
+- Artifacts are classified as hot/warm/cold on publish; prompt briefs render hot first, warm second, and exclude cold unless explicitly queried.
+- Pruning enforces per-session record/byte caps, tier-specific record/byte caps, TTL expiry on reads, and pinned-artifact retention.
+
+It is intentionally disabled by default in the bundle.
+
+## Opt-in beta extension
+
+Set `PI_CONTEXT_BROKER_ENABLED=true` before starting Pi with the bundle installed to enable the beta extension:
+
+```bash
+PI_CONTEXT_BROKER_ENABLED=true pi
+```
+
+When enabled, the bundle registers a `context_lookup` LLM tool plus `/context` commands:
+
+- `/context status` — enabled state, record/byte counts, pinned counts.
+- `/context brief` — bounded prompt-safe broker brief with handles and summaries.
+- `/context lookup <handle|text>` — exact handle rehydration or current-session text search.
+- `/context pin <handle>` — protect an artifact from normal TTL/cap pruning.
+- `/context prune` — run TTL/cap pruning immediately.
+
+The command includes autocomplete for subcommands and known artifact handles. Exact handle lookup returns clipped payload text; text search returns a smaller clipped excerpt, and truncation is marked explicitly.
+
+Optional durability is available with `PI_CONTEXT_BROKER_DURABLE=true` or `PI_CONTEXT_BROKER_STORE_DIR=/path/to/store`. Durable mode now defaults to SQLite (`artifacts.sqlite`) with an FTS index for text lookup, so exact handles, tier, and pin state survive restarts without replay reconstruction. Set `PI_CONTEXT_BROKER_BACKEND=jsonl` to use the legacy JSONL/blob backend.
+
+## Session behavior and limits
+
+- On session start/reload, the beta backfills the current Pi session branch from `toolResult` and prompt-visible `bashExecution` entries.
+- Backfill is idempotent by session entry id, skips malformed entries instead of failing the session, and honors Pi's `excludeFromContext` bash entries.
+- Without durable mode, restarting Pi loses broker state until the current branch is backfilled again.
+- Prompt integration injects a bounded, tier-aware broker brief and lookup guidance; the LLM also gets a `context_lookup` tool for exact handle dereferencing.
+- The `context` hook rewrites large `toolResult` and prompt-visible `bashExecution` payloads in the LLM-bound message copy to broker handles and summaries, reducing prompt load while preserving exact `/context lookup` rehydration.
+- Pi `excludeFromContext` bash entries are not backfilled or rewritten into broker prompts.
+- Basic secret redaction runs before broker storage and display for common token/password/API-key patterns.
+- Rollback is immediate: unset `PI_CONTEXT_BROKER_ENABLED` and `/reload` or restart Pi. Disable durable writes by unsetting `PI_CONTEXT_BROKER_DURABLE` and `PI_CONTEXT_BROKER_STORE_DIR`.

package/node_modules/@fiale-plus/pi-rogue-context-broker/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@fiale-plus/pi-rogue-context-broker",
+  "version": "0.1.0",
+  "description": "Beta context broker runtime for Pi-Rogue. In-memory bounded broker implementation behind explicit opt-in.",
+  "private": true,
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package"
+  ],
+  "scripts": {
+    "check": "tsc -p ../../tsconfig.json --noEmit",
+    "test": "cd ../.. && vitest run packages/context-broker/src/*.test.ts"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./extension": "./src/extension.ts",
+    "./file": "./src/file.ts",
+    "./sqlite": "./src/sqlite.ts"
+  },
+  "dependencies": {
+    "@fiale-plus/pi-core": "^0.1.0",
+    "typebox": "^1.1.24"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ]
+}