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

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,16 @@ 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.
 - `@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"
@@ -82,227 +79,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-context-broker/README.md

@@ -0,0 +1,38 @@
+# 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, 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.
+
+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 `/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.
+
+## 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.
+- The current implementation remains in-memory. Restarting Pi loses broker state until the current branch is backfilled again.
+- Prompt integration injects only a bounded broker brief and lookup guidance. It does not yet rewrite existing raw tool-result messages out of Pi's transcript context; that deeper prompt-load reduction remains a follow-up.
+- Rollback is immediate: unset `PI_CONTEXT_BROKER_ENABLED` and `/reload` or restart Pi.

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

@@ -0,0 +1,28 @@
+{
+  "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"
+  },
+  "dependencies": {
+    "@fiale-plus/pi-core": "^0.1.0"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ]
+}

package/node_modules/@fiale-plus/pi-rogue-context-broker/src/extension.test.ts

@@ -0,0 +1,221 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { registerContextBrokerBeta, shouldEnableContextBrokerBeta } from "./extension.js";
+
+function createPiMock() {
+  const handlers = new Map<string, any[]>();
+  const commands = new Map<string, any>();
+  const pi: any = {
+    on(name: string, handler: any) {
+      handlers.set(name, [...(handlers.get(name) ?? []), handler]);
+    },
+    registerCommand(name: string, options: any) {
+      commands.set(name, options);
+    },
+  };
+  return { pi, handlers, commands };
+}
+
+function createCtx(entries: any[] = []) {
+  const notifications: Array<{ message: string; type?: string }> = [];
+  return {
+    ctx: {
+      cwd: "/repo",
+      ui: {
+        notify(message: string, type?: string) {
+          notifications.push({ message, type });
+        },
+        setStatus() {},
+      },
+      sessionManager: {
+        getSessionFile() {
+          return "/sessions/current.jsonl";
+        },
+        getBranch() {
+          return entries;
+        },
+      },
+    } as any,
+    notifications,
+  };
+}
+
+async function runHandlers(handlers: Map<string, any[]>, name: string, event: any, ctx: any) {
+  for (const handler of handlers.get(name) ?? []) {
+    await handler(event, ctx);
+  }
+}
+
+describe("context broker beta enablement", () => {
+  const oldEnv = process.env.PI_CONTEXT_BROKER_ENABLED;
+
+  afterEach(() => {
+    if (oldEnv === undefined) delete process.env.PI_CONTEXT_BROKER_ENABLED;
+    else process.env.PI_CONTEXT_BROKER_ENABLED = oldEnv;
+  });
+
+  it("is disabled by default unless explicitly opted in", () => {
+    delete process.env.PI_CONTEXT_BROKER_ENABLED;
+    expect(shouldEnableContextBrokerBeta()).toBe(false);
+
+    process.env.PI_CONTEXT_BROKER_ENABLED = "true";
+    expect(shouldEnableContextBrokerBeta()).toBe(true);
+  });
+
+  it("registers /context with command completions", () => {
+    const { pi, commands } = createPiMock();
+    registerContextBrokerBeta(pi);
+
+    const command = commands.get("context");
+    expect(command).toBeTruthy();
+    expect(command.getArgumentCompletions("")?.map((item: any) => item.value.trim())).toEqual([
+      "status",
+      "brief",
+      "lookup",
+      "pin",
+      "prune",
+    ]);
+  });
+
+  it("backfills current branch toolResult and bashExecution entries idempotently", async () => {
+    const { pi, handlers, commands } = createPiMock();
+    registerContextBrokerBeta(pi);
+    const entries = [
+      {
+        type: "message",
+        id: "assistant-1",
+        timestamp: "2026-06-05T00:00:00.000Z",
+        message: { role: "assistant", content: [{ type: "toolCall", id: "tc-read", name: "read", arguments: { path: "README.md" } }] },
+      },
+      {
+        type: "message",
+        id: "tool-1",
+        timestamp: "2026-06-05T00:00:00.000Z",
+        message: { role: "toolResult", toolCallId: "tc-read", toolName: "read", content: [{ type: "text", text: "readme" }], isError: false },
+      },
+      {
+        type: "message",
+        id: "bash-1",
+        timestamp: "2026-06-05T00:00:01.000Z",
+        message: { role: "bashExecution", command: "npm test", output: "passed", exitCode: 0, cancelled: false, truncated: false },
+      },
+    ];
+    const { ctx, notifications } = createCtx(entries);
+
+    await runHandlers(handlers, "session_start", { type: "session_start" }, ctx);
+    await runHandlers(handlers, "session_start", { type: "session_start" }, ctx);
+    await commands.get("context").handler("status", ctx);
+    await commands.get("context").handler("lookup README.md", ctx);
+
+    expect(notifications[0].message).toContain("Backfilled 2/2");
+    expect(notifications[1].message).toContain("Backfilled 0/2");
+    expect(notifications.at(-2)?.message).toContain("records=2");
+    expect(notifications.at(-1)?.message).toContain("README.md");
+  });
+
+  it("is safe on malformed session branches", async () => {
+    const { pi, handlers } = createPiMock();
+    registerContextBrokerBeta(pi);
+    const { ctx, notifications } = createCtx([null, { type: "message", id: "broken", message: null }]);
+
+    await runHandlers(handlers, "session_start", { type: "session_start" }, ctx);
+
+    expect(notifications[0].message).toContain("Backfilled 0/0");
+  });
+
+  it("does not backfill bash entries explicitly excluded from context", async () => {
+    const { pi, handlers, commands } = createPiMock();
+    registerContextBrokerBeta(pi);
+    const { ctx, notifications } = createCtx([
+      {
+        type: "message",
+        id: "secret-bash",
+        timestamp: "2026-06-05T00:00:00.000Z",
+        message: {
+          role: "bashExecution",
+          command: "echo SECRET_TOKEN=abc123",
+          output: "SECRET_TOKEN=abc123",
+          exitCode: 0,
+          cancelled: false,
+          truncated: false,
+          excludeFromContext: true,
+        },
+      },
+    ]);
+
+    await runHandlers(handlers, "session_start", { type: "session_start" }, ctx);
+    await commands.get("context").handler("brief", ctx);
+
+    expect(notifications[0].message).toContain("Backfilled 0/0");
+    expect(notifications.at(-1)?.message).not.toContain("SECRET_TOKEN");
+  });
+
+  it("exact lookup returns byte-clipped payloads and marks truncation explicitly", async () => {
+    const { pi, handlers, commands } = createPiMock();
+    registerContextBrokerBeta(pi, { lookupBytes: 80, searchBytes: 50 });
+    const { ctx, notifications } = createCtx();
+
+    await runHandlers(handlers, "session_start", { type: "session_start" }, ctx);
+    await runHandlers(handlers, "tool_result", {
+      type: "tool_result",
+      toolCallId: "call-1",
+      toolName: "bash",
+      input: { command: "printf long" },
+      content: [{ type: "text", text: "測試".repeat(100) }],
+      isError: false,
+    }, ctx);
+
+    const lookupCompletion = commands.get("context").getArgumentCompletions("lookup ")?.[0];
+    expect(lookupCompletion.value).toMatch(/^lookup ctx:\/\//);
+
+    await commands.get("context").handler(lookupCompletion.value, ctx);
+    const payload = notifications.at(-1)?.message.split("payload:\n").at(-1) ?? "";
+    expect(notifications.at(-1)?.message).toContain("payload:");
+    expect(payload).toContain("[truncated: omitted");
+    expect(Buffer.byteLength(payload, "utf8")).toBeLessThanOrEqual(80);
+  });
+
+  it("text search lookup returns a smaller byte-clipped excerpt", async () => {
+    const { pi, handlers, commands } = createPiMock();
+    registerContextBrokerBeta(pi, { lookupBytes: 80, searchBytes: 50 });
+    const { ctx, notifications } = createCtx();
+
+    await runHandlers(handlers, "session_start", { type: "session_start" }, ctx);
+    await runHandlers(handlers, "tool_result", {
+      type: "tool_result",
+      toolCallId: "call-2",
+      toolName: "bash",
+      input: { command: "echo needle" },
+      content: [{ type: "text", text: "needle " + "✅".repeat(100) }],
+      isError: false,
+    }, ctx);
+
+    await commands.get("context").handler("lookup needle", ctx);
+    const payload = notifications.at(-1)?.message.split("payload:\n").at(-1) ?? "";
+    expect(notifications.at(-1)?.message).toContain("payload:");
+    expect(payload).toContain("[truncated: omitted");
+    expect(Buffer.byteLength(payload, "utf8")).toBeLessThanOrEqual(50);
+  });
+
+  it("injects a bounded broker brief without raw payload text", async () => {
+    const { pi, handlers } = createPiMock();
+    registerContextBrokerBeta(pi, { briefBytes: 220 });
+    const { ctx } = createCtx();
+
+    await runHandlers(handlers, "session_start", { type: "session_start" }, ctx);
+    await runHandlers(handlers, "tool_result", {
+      type: "tool_result",
+      toolCallId: "call-3",
+      toolName: "bash",
+      input: { command: "echo secret" },
+      content: [{ type: "text", text: "SECRET_TOKEN=" + "z".repeat(200) }],
+      isError: false,
+    }, ctx);
+
+    const result = await handlers.get("before_agent_start")?.[0]({ systemPrompt: "base" }, ctx);
+
+    expect(Buffer.byteLength(result.systemPrompt, "utf8")).toBeLessThanOrEqual(Buffer.byteLength("base\n\n", "utf8") + 220 + 180);
+    expect(result.systemPrompt).toContain("Context Broker");
+    expect(result.systemPrompt).toContain("ctx://");
+    expect(result.systemPrompt).not.toContain("SECRET_TOKEN");
+  });
+});

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

@@ -0,0 +1,359 @@
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionContext, ToolResultEvent } from "@earendil-works/pi-coding-agent";
+import { createInMemoryContextBroker } from "./index.js";
+
+export interface ContextBrokerBetaOptions {
+  enabled?: boolean;
+  maxRecords?: number;
+  maxBytes?: number;
+  briefBytes?: number;
+  lookupBytes?: number;
+  searchBytes?: number;
+}
+
+type UiLike = { notify(message: string, type?: "info" | "warning" | "error"): void; setStatus?(key: string, text: string | undefined): void };
+type SessionContextLike = Pick<ExtensionContext, "cwd" | "sessionManager"> & { ui: UiLike };
+
+const DEFAULT_BRIEF_BYTES = 1_800;
+const DEFAULT_LOOKUP_BYTES = 12_000;
+const DEFAULT_SEARCH_BYTES = 2_000;
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const ENABLED_VALUES = new Set(["1", "true", "yes", "on"]);
+
+function isEnvEnabled(): boolean {
+  return ENABLED_VALUES.has(String(process.env.PI_CONTEXT_BROKER_ENABLED ?? "").trim().toLowerCase());
+}
+
+function toText(value: unknown): string {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value ?? "");
+  }
+}
+
+function truncateUtf8(text: string, maxBytes: number): string {
+  const limit = Math.max(0, Math.floor(maxBytes));
+  const totalBytes = Buffer.byteLength(text, "utf8");
+  if (totalBytes <= limit) return text;
+  if (limit === 0) return "";
+
+  let omittedBytes = totalBytes;
+  let result = "";
+  let marker = "…";
+
+  for (let pass = 0; pass < 4; pass += 1) {
+    const verboseMarker = `\n[truncated: omitted ${omittedBytes} bytes]`;
+    marker = Buffer.byteLength(verboseMarker, "utf8") < limit ? verboseMarker : "…";
+    const contentLimit = Math.max(0, limit - Buffer.byteLength(marker, "utf8"));
+    let used = 0;
+    let prefix = "";
+
+    for (const char of text) {
+      const bytes = Buffer.byteLength(char, "utf8");
+      if (used + bytes > contentLimit) break;
+      prefix += char;
+      used += bytes;
+    }
+
+    result = prefix;
+    const nextOmittedBytes = totalBytes - used;
+    if (nextOmittedBytes === omittedBytes) break;
+    omittedBytes = nextOmittedBytes;
+  }
+
+  return `${result}${marker}`;
+}
+
+function compact(value: string, max = 120): string {
+  return truncateUtf8(value.replace(/\s+/g, " ").trim(), max);
+}
+
+function sessionIdFor(ctx: Partial<SessionContextLike>): string {
+  const file = ctx.sessionManager?.getSessionFile?.();
+  return file || ctx.cwd || process.cwd();
+}
+
+function messageTimestamp(entry: any): number | undefined {
+  const value = entry?.message?.timestamp ?? entry?.timestamp;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  const parsed = Date.parse(String(value ?? ""));
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function toolPayload(event: { toolName: string; input?: unknown; content?: unknown; details?: unknown; isError?: boolean }): string {
+  return [
+    `tool=${event.toolName}`,
+    `isError=${Boolean(event.isError)}`,
+    "input:",
+    toText(event.input),
+    "content:",
+    toText(event.content),
+    "details:",
+    toText(event.details),
+  ].join("\n");
+}
+
+function summarizeTool(event: { toolName: string; input?: any; isError?: boolean }, bytes: number): string {
+  const command = event.toolName === "bash" ? event.input?.command : undefined;
+  const path = event.input?.path;
+  const target = command ? ` command=${compact(String(command), 120)}` : path ? ` path=${path}` : "";
+  return `${event.isError ? "failed" : "completed"} ${event.toolName}${target}; payload=${bytes} bytes`;
+}
+
+export function registerContextBrokerBeta(pi: ExtensionAPI, options: ContextBrokerBetaOptions = {}): void {
+  const p = pi as any;
+  if (p.__piRogueContextBrokerBetaRegistered) return;
+  p.__piRogueContextBrokerBetaRegistered = true;
+
+  const briefBytes = options.briefBytes ?? DEFAULT_BRIEF_BYTES;
+  const lookupBytes = options.lookupBytes ?? DEFAULT_LOOKUP_BYTES;
+  const searchBytes = options.searchBytes ?? DEFAULT_SEARCH_BYTES;
+  const broker = createInMemoryContextBroker({
+    maxRecords: options.maxRecords ?? 64,
+    maxBytes: options.maxBytes ?? 8 * 1024 * 1024,
+    briefBytes,
+  });
+  const seenSourceIds = new Set<string>();
+  let activeSessionId = process.cwd();
+
+  function currentBrief(): string {
+    return broker.renderBrief({ sessionId: activeSessionId, budgetBytes: briefBytes });
+  }
+
+  function publishToolArtifact(event: {
+    toolName: string;
+    input?: any;
+    content?: unknown;
+    details?: unknown;
+    isError?: boolean;
+    sourceId?: string;
+    createdAt?: number;
+  }): boolean {
+    if (event.sourceId) {
+      if (seenSourceIds.has(event.sourceId)) return false;
+      seenSourceIds.add(event.sourceId);
+    }
+
+    const payload = toolPayload(event);
+    const bytes = Buffer.byteLength(payload, "utf8");
+    broker.publish({
+      sessionId: activeSessionId,
+      kind: "tool_output",
+      payload,
+      summary: summarizeTool(event, bytes),
+      tags: [event.toolName, event.isError ? "error" : "ok", event.sourceId ? "session-backfill" : "live"],
+      command: event.toolName === "bash" && typeof event.input?.command === "string" ? event.input.command : undefined,
+      paths: typeof event.input?.path === "string" ? [event.input.path] : [],
+      ttlMs: DEFAULT_TTL_MS,
+      parentIds: event.sourceId ? [event.sourceId] : [],
+      createdAt: event.createdAt,
+    });
+    return true;
+  }
+
+  function backfillSessionArtifacts(ctx: Partial<SessionContextLike>): { added: number; scanned: number; errors: number } {
+    activeSessionId = sessionIdFor(ctx);
+    let entries: any[] = [];
+    try {
+      entries = ctx.sessionManager?.getBranch?.() ?? [];
+    } catch {
+      return { added: 0, scanned: 0, errors: 1 };
+    }
+
+    const toolInputs = new Map<string, { toolName?: string; input?: unknown }>();
+    for (const entry of entries) {
+      const message = entry?.type === "message" ? entry.message : undefined;
+      if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
+      for (const block of message.content) {
+        if (block?.type === "toolCall" && typeof block.id === "string") {
+          toolInputs.set(block.id, { toolName: typeof block.name === "string" ? block.name : undefined, input: block.arguments });
+        }
+      }
+    }
+
+    let added = 0;
+    let scanned = 0;
+    let errors = 0;
+
+    for (const entry of entries) {
+      try {
+        const entryId = typeof entry?.id === "string" ? entry.id : undefined;
+        const createdAt = messageTimestamp(entry);
+
+        if (entry?.type === "message" && entry.message?.role === "toolResult") {
+          scanned += 1;
+          const sourceId = typeof entry.message.toolCallId === "string" ? entry.message.toolCallId : entryId;
+          const toolInput = sourceId ? toolInputs.get(sourceId) : undefined;
+          if (publishToolArtifact({
+            toolName: String(entry.message.toolName ?? toolInput?.toolName ?? "tool"),
+            input: entry.message.input ?? toolInput?.input,
+            content: entry.message.content,
+            details: entry.message.details,
+            isError: Boolean(entry.message.isError),
+            sourceId,
+            createdAt,
+          })) added += 1;
+        }
+
+        if (entry?.type === "message" && entry.message?.role === "bashExecution") {
+          if (entry.message.excludeFromContext === true) continue;
+          scanned += 1;
+          const sourceId = entryId;
+          if (publishToolArtifact({
+            toolName: "bash",
+            input: { command: entry.message.command },
+            content: entry.message.output,
+            details: {
+              exitCode: entry.message.exitCode,
+              cancelled: entry.message.cancelled,
+              truncated: entry.message.truncated,
+              fullOutputPath: entry.message.fullOutputPath,
+            },
+            isError: typeof entry.message.exitCode === "number" ? entry.message.exitCode !== 0 : Boolean(entry.message.cancelled),
+            sourceId,
+            createdAt,
+          })) added += 1;
+        }
+      } catch {
+        errors += 1;
+      }
+    }
+
+    return { added, scanned, errors };
+  }
+
+  const contextActions: AutocompleteItem[] = [
+    { value: "status", label: "status", description: "Show broker record, byte, and pinned counts" },
+    { value: "brief", label: "brief", description: "Show the bounded broker brief" },
+    { value: "lookup ", label: "lookup", description: "Lookup by ctx:// handle or current-session text" },
+    { value: "pin ", label: "pin", description: "Pin an artifact by ctx:// handle or id" },
+    { value: "prune", label: "prune", description: "Run TTL/cap pruning now" },
+  ];
+
+  function artifactCompletions(action: "lookup" | "pin", query: string): AutocompleteItem[] {
+    const needle = query.trim().toLowerCase();
+    return broker.lookup({ sessionId: activeSessionId, limit: 10 })
+      .filter((artifact) => {
+        if (!needle) return true;
+        return artifact.handle.toLowerCase().includes(needle)
+          || artifact.summary.toLowerCase().includes(needle)
+          || artifact.kind.toLowerCase().includes(needle)
+          || artifact.tags.join(" ").toLowerCase().includes(needle)
+          || artifact.paths.join(" ").toLowerCase().includes(needle);
+      })
+      .map((artifact) => ({
+        value: `${action} ${artifact.handle}`,
+        label: `${action} ${artifact.kind}`,
+        description: `${artifact.pinned ? "pinned; " : ""}${artifact.summary}`,
+      }));
+  }
+
+  function contextArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
+    const prefix = argumentPrefix.trimStart();
+    const [action = "", ...restParts] = prefix.split(/\s+/);
+    const hasActionSeparator = /\s/.test(prefix);
+
+    if (!action || !hasActionSeparator) {
+      const items = contextActions.filter((item) => item.value.trim().startsWith(action));
+      return items.length ? items : contextActions;
+    }
+
+    if (action === "lookup" || action === "pin") {
+      const items = artifactCompletions(action, restParts.join(" "));
+      return items.length ? items : null;
+    }
+
+    return null;
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    const { added, scanned, errors } = backfillSessionArtifacts(ctx);
+    ctx.ui.setStatus?.("context-broker", "ctx:on beta");
+    ctx.ui.notify(
+      `Context broker beta enabled. Backfilled ${added}/${scanned} current-branch tool artifacts${errors ? ` (${errors} malformed skipped)` : ""}. Use /context status or /context brief.`,
+      errors ? "warning" : "info",
+    );
+  });
+
+  pi.on("tool_result", async (event: ToolResultEvent, ctx) => {
+    activeSessionId = sessionIdFor(ctx);
+    publishToolArtifact({ ...event, sourceId: event.toolCallId });
+  });
+
+  pi.on("before_agent_start", async (event) => {
+    const brief = currentBrief();
+    if (!brief.includes("ctx://")) return;
+    return {
+      systemPrompt: [
+        event.systemPrompt,
+        brief,
+        "Context broker beta rule: use /context lookup <handle> for exact evidence when a broker handle is relevant. Broker briefs are bounded summaries and never raw payload dumps.",
+      ].join("\n\n"),
+    };
+  });
+
+  pi.registerCommand("context", {
+    description: "Inspect the beta context broker: status | brief | lookup <handle-or-text> | pin <handle> | prune",
+    getArgumentCompletions: contextArgumentCompletions,
+    handler: async (args, ctx) => {
+      activeSessionId = sessionIdFor(ctx);
+      const [action = "status", ...rest] = String(args || "").trim().split(/\s+/).filter(Boolean);
+      const query = rest.join(" ");
+
+      if (action === "status") {
+        const status = broker.status();
+        ctx.ui.notify(
+          `Context broker beta: enabled, session=${activeSessionId}, records=${status.records}, bytes=${status.bytes}/${status.maxBytes}, pinned=${status.pinnedRecords}/${status.pinnedBytes} bytes`,
+          "info",
+        );
+        return;
+      }
+
+      if (action === "brief") {
+        ctx.ui.notify(currentBrief(), "info");
+        return;
+      }
+
+      if (action === "lookup") {
+        if (!query) {
+          ctx.ui.notify("Usage: /context lookup <ctx://handle-or-text>", "warning");
+          return;
+        }
+        const exact = query.startsWith("ctx://");
+        const results = broker.lookup(exact ? { handle: query } : { sessionId: activeSessionId, text: query, limit: 5 });
+        ctx.ui.notify(results.length ? results.map((item) => [
+          item.handle,
+          `kind=${item.kind} bytes=${item.bytes}`,
+          `summary=${item.summary}`,
+          "payload:",
+          truncateUtf8(item.payload, exact ? lookupBytes : searchBytes),
+        ].join("\n")).join("\n\n---\n\n") : "No context artifacts matched.", "info");
+        return;
+      }
+
+      if (action === "pin") {
+        if (!query) {
+          ctx.ui.notify("Usage: /context pin <ctx://handle-or-id>", "warning");
+          return;
+        }
+        const pinned = broker.pin(query, true);
+        ctx.ui.notify(pinned ? `Pinned ${pinned.handle}` : "No artifact matched that handle/id.", pinned ? "info" : "warning");
+        return;
+      }
+
+      if (action === "prune") {
+        const status = broker.prune();
+        ctx.ui.notify(`Pruned. ${status.records} records, ${status.bytes} bytes remain.`, "info");
+        return;
+      }
+
+      ctx.ui.notify("Usage: /context status | brief | lookup <handle-or-text> | pin <handle> | prune", "warning");
+    },
+  });
+}
+
+export function shouldEnableContextBrokerBeta(options: ContextBrokerBetaOptions = {}): boolean {
+  return Boolean(options.enabled ?? isEnvEnabled());
+}

package/node_modules/@fiale-plus/{pi-core/src/context-broker.test.ts → pi-rogue-context-broker/src/index.test.ts}

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { describe, expect, it } from "vitest";
-import { createInMemoryContextBroker } from "./context-broker.js";
+import { createInMemoryContextBroker } from "./index.js";
 
 describe("createInMemoryContextBroker", () => {
   it("publishes stable, unique handles and looks up artifacts by handle", () => {

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

@@ -0,0 +1,245 @@
+import { createHash } from "node:crypto";
+import { safeName } from "@fiale-plus/pi-core";
+import type {
+  BoundedContextBroker,
+  ContextArtifact,
+  ContextArtifactInput,
+  ContextArtifactKind,
+  ContextBrokerOptions,
+  ContextBrokerStatus,
+  ContextLookupQuery,
+} from "@fiale-plus/pi-core";
+
+export type {
+  BoundedContextBroker,
+  ContextArtifact,
+  ContextArtifactInput,
+  ContextArtifactKind,
+  ContextBrokerOptions,
+  ContextBrokerStatus,
+  ContextLookupQuery,
+} from "@fiale-plus/pi-core";
+
+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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fiale-plus/pi-rogue-bundle",
-  "version": "0.1.15",
-  "description": "Public Pi-Rogue bundle for advisor, orchestration, and shared context-broker core. Single consolidated artefact (leaf releases paused; private packages are bundled here).",
+  "version": "0.1.16",
+  "description": "Public Pi-Rogue bundle for advisor, orchestration, and beta context broker. Single consolidated artefact (leaf releases paused; private packages are bundled here).",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -11,9 +11,13 @@
   "keywords": [
     "pi-package"
   ],
+  "scripts": {
+    "test": "cd ../.. && vitest run packages/bundle/src/*.test.ts"
+  },
   "main": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./context-broker": "./src/context-broker.ts"
   },
   "pi": {
     "extensions": [
@@ -30,11 +34,13 @@
   "dependencies": {
     "@fiale-plus/pi-core": "^0.1.0",
     "@fiale-plus/pi-rogue-advisor": "^0.1.0",
+    "@fiale-plus/pi-rogue-context-broker": "^0.1.0",
     "@fiale-plus/pi-rogue-orchestration": "^0.1.0"
   },
   "bundledDependencies": [
     "@fiale-plus/pi-core",
     "@fiale-plus/pi-rogue-advisor",
+    "@fiale-plus/pi-rogue-context-broker",
     "@fiale-plus/pi-rogue-orchestration"
   ],
   "publishConfig": {

package/src/context-broker.ts

@@ -0,0 +1 @@
+export * from "@fiale-plus/pi-rogue-context-broker";

package/src/extension.test.ts

@@ -0,0 +1,63 @@
+import { createInMemoryContextBroker } from "./context-broker.js";
+import { afterEach, describe, expect, it } from "vitest";
+import { registerBundle } from "./extension.js";
+
+function createPiMock() {
+  const handlers = new Map<string, any[]>();
+  const commands = new Map<string, any>();
+  const pi: any = new Proxy({
+    on(name: string, handler: any) {
+      handlers.set(name, [...(handlers.get(name) ?? []), handler]);
+    },
+    registerCommand(name: string, options: any) {
+      commands.set(name, options);
+    },
+    getFlag() {
+      return undefined;
+    },
+  }, {
+    get(target, prop) {
+      if (prop in target) return (target as any)[prop];
+      if (typeof prop === "string" && prop.startsWith("__")) return undefined;
+      return () => undefined;
+    },
+  });
+  return { pi, handlers, commands };
+}
+
+describe("bundle extension defaults", () => {
+  const oldEnv = process.env.PI_CONTEXT_BROKER_ENABLED;
+
+  afterEach(() => {
+    if (oldEnv === undefined) delete process.env.PI_CONTEXT_BROKER_ENABLED;
+    else process.env.PI_CONTEXT_BROKER_ENABLED = oldEnv;
+  });
+
+  it("does not register the beta context broker by default", async () => {
+    delete process.env.PI_CONTEXT_BROKER_ENABLED;
+    const { pi, commands } = createPiMock();
+
+    await registerBundle(pi);
+
+    expect(commands.has("context")).toBe(false);
+  });
+
+  it("registers the beta context broker only when explicitly enabled", async () => {
+    process.env.PI_CONTEXT_BROKER_ENABLED = "true";
+    const { pi, commands } = createPiMock();
+
+    await registerBundle(pi);
+
+    expect(commands.has("context")).toBe(true);
+  });
+});
+
+describe("bundle context-broker export", () => {
+  it("exposes the beta context broker runtime for explicit opt-in", () => {
+    const broker = createInMemoryContextBroker({ defaultTtlMs: 0 });
+    const artifact = broker.publish({ sessionId: "bundle-test", kind: "memory_note", payload: "hello" });
+
+    expect(artifact.handle).toContain("ctx://session/bundle-test/memory_note/");
+    expect(broker.lookup({ handle: artifact.handle })).toEqual([artifact]);
+  });
+});

package/src/extension.ts

@@ -2,15 +2,26 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerAdvisor } from "@fiale-plus/pi-rogue-advisor";
 import { registerOrchestration } from "@fiale-plus/pi-rogue-orchestration";
 
-export function registerBundle(pi: ExtensionAPI): void {
+const ENABLED_VALUES = new Set(["1", "true", "yes", "on"]);
+
+function contextBrokerBetaEnabled(): boolean {
+  return ENABLED_VALUES.has(String(process.env.PI_CONTEXT_BROKER_ENABLED ?? "").trim().toLowerCase());
+}
+
+export async function registerBundle(pi: ExtensionAPI): Promise<void> {
   const p = pi as any;
   if (p.__piRogueBundleRegistered) return;
   p.__piRogueBundleRegistered = true;
 
   registerAdvisor(pi);
   registerOrchestration(pi);
+
+  if (contextBrokerBetaEnabled()) {
+    const { registerContextBrokerBeta } = await import("@fiale-plus/pi-rogue-context-broker/extension");
+    registerContextBrokerBeta(pi);
+  }
 }
 
-export default function bundleExtension(pi: ExtensionAPI): void {
-  registerBundle(pi);
+export default function bundleExtension(pi: ExtensionAPI): Promise<void> {
+  return registerBundle(pi);
 }