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

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

@@ -0,0 +1,216 @@
+import { createHash } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { createInMemoryContextBroker } from "./index.js";
+
+describe("createInMemoryContextBroker", () => {
+  it("publishes stable, unique handles and looks up artifacts by handle", () => {
+    const broker = createInMemoryContextBroker();
+    const first = broker.publish({
+      sessionId: "session-a",
+      kind: "tool_output",
+      payload: "same payload",
+      summary: "tests passed",
+      tags: ["test"],
+      paths: ["packages/core"],
+    });
+    const second = broker.publish({
+      sessionId: "session-a",
+      kind: "tool_output",
+      payload: "same payload",
+      summary: "same payload repeat",
+      tags: ["test"],
+      paths: ["packages/core"],
+    });
+
+    expect(first.handle).not.toEqual(second.handle);
+    expect(first.handle).toMatch(/^ctx:\/\/session\/session-a\/tool_output\//);
+    expect(broker.lookup({ handle: first.handle })).toEqual([first]);
+    expect(broker.lookup({ handle: second.handle })).toEqual([second]);
+  });
+
+  it("filters by session, kind, tag, path, and text", () => {
+    const broker = createInMemoryContextBroker();
+    const core = broker.publish({
+      sessionId: "s1",
+      kind: "tool_output",
+      payload: "vitest packages/core passed",
+      tags: ["test", "core"],
+      paths: ["packages/core/src/context-broker.ts"],
+    });
+    broker.publish({
+      sessionId: "s2",
+      kind: "advisor_brief",
+      payload: "different payload",
+      tags: ["advisor"],
+      paths: ["packages/advisor/src/router.ts"],
+    });
+
+    expect(broker.lookup({ sessionId: "s1", kind: "tool_output", tag: "core" })).toEqual([core]);
+    expect(broker.lookup({ path: "packages/core" })).toEqual([core]);
+    expect(broker.lookup({ text: "vitest" })).toEqual([core]);
+    expect(broker.lookup({ sessionId: "s2", kind: "tool_output" })).toEqual([]);
+  });
+
+  it("uses a metadata-only summary when callers omit summaries", () => {
+    const broker = createInMemoryContextBroker({ briefBytes: 500 });
+    const artifact = broker.publish({
+      sessionId: "s",
+      kind: "tool_output",
+      payload: "SECRET_TOKEN=abc123\n".repeat(20),
+      paths: ["logs/secret-output.txt"],
+    });
+
+    const brief = broker.renderBrief({ sessionId: "s" });
+
+    expect(artifact.summary).toContain("payload stored externally");
+    expect(artifact.summary).not.toContain("SECRET_TOKEN");
+    expect(brief).not.toContain("SECRET_TOKEN");
+    expect(brief).toContain(artifact.handle);
+  });
+
+  it("enforces record caps by pruning oldest unpinned artifacts", () => {
+    const broker = createInMemoryContextBroker({ maxRecords: 2, defaultTtlMs: 0 });
+    const first = broker.publish({ sessionId: "s", kind: "memory_note", payload: "one", createdAt: 1 });
+    const second = broker.publish({ sessionId: "s", kind: "memory_note", payload: "two", createdAt: 2 });
+    const third = broker.publish({ sessionId: "s", kind: "memory_note", payload: "three", createdAt: 3 });
+
+    expect(broker.lookup({ id: first.id })).toEqual([]);
+    expect(broker.lookup({ id: second.id })).toEqual([second]);
+    expect(broker.lookup({ id: third.id })).toEqual([third]);
+    expect(broker.status().records).toBe(2);
+  });
+
+  it("applies caps independently per session", () => {
+    const broker = createInMemoryContextBroker({ maxRecords: 1, defaultTtlMs: 0 });
+    const sessionOne = broker.publish({ sessionId: "s1", kind: "tool_output", payload: "one", createdAt: 1 });
+    const sessionTwo = broker.publish({ sessionId: "s2", kind: "tool_output", payload: "two", createdAt: 2 });
+
+    expect(broker.lookup({ sessionId: "s1" })).toEqual([sessionOne]);
+    expect(broker.lookup({ sessionId: "s2" })).toEqual([sessionTwo]);
+    expect(broker.status().records).toBe(2);
+  });
+
+  it("uses sequence tie-breakers when createdAt timestamps tie", () => {
+    const broker = createInMemoryContextBroker({ maxRecords: 2, defaultTtlMs: 0 });
+    const first = broker.publish({ sessionId: "s", kind: "tool_output", payload: "alpha", createdAt: 1000 });
+    const second = broker.publish({ sessionId: "s", kind: "tool_output", payload: "bravo", createdAt: 1000 });
+    const third = broker.publish({ sessionId: "s", kind: "tool_output", payload: "charlie", createdAt: 1000 });
+
+    expect(broker.lookup({ id: first.id })).toEqual([]);
+    expect(broker.lookup({ id: second.id })).toEqual([second]);
+    expect(broker.lookup({ id: third.id })).toEqual([third]);
+  });
+
+  it("enforces byte caps by pruning oldest unpinned artifacts", () => {
+    const broker = createInMemoryContextBroker({ maxBytes: 6, defaultTtlMs: 0 });
+    const first = broker.publish({ sessionId: "s", kind: "tool_output", payload: "12345", createdAt: 1 });
+    const second = broker.publish({ sessionId: "s", kind: "tool_output", payload: "abcde", createdAt: 2 });
+
+    expect(broker.lookup({ id: first.id })).toEqual([]);
+    expect(broker.lookup({ id: second.id })).toEqual([second]);
+    expect(broker.status().bytes).toBe(5);
+  });
+
+  it("preserves the returned handle when a new artifact exceeds maxBytes", () => {
+    const broker = createInMemoryContextBroker({ maxBytes: 4, defaultTtlMs: 0 });
+    const artifact = broker.publish({ sessionId: "s", kind: "tool_output", payload: "oversized", createdAt: 1 });
+
+    expect(broker.lookup({ id: artifact.id })).toEqual([artifact]);
+    expect(broker.lookup({ handle: artifact.handle })).toEqual([artifact]);
+    expect(broker.status().bytes).toBe(Buffer.byteLength("oversized", "utf8"));
+  });
+
+  it("computes bytes and SHA-256 on raw Buffer payload bytes", () => {
+    const broker = createInMemoryContextBroker({ maxBytes: 1024, defaultTtlMs: 0 });
+    const payload = Buffer.from([0x66, 0xff, 0x61, 0x62, 0x80, 0x00]);
+    const artifact = broker.publish({ sessionId: "s", kind: "tool_output", payload, createdAt: 1 });
+    const expectedSha = createHash("sha256").update(payload).digest("hex");
+
+    expect(artifact.bytes).toBe(payload.length);
+    expect(artifact.sha256).toBe(expectedSha);
+    expect(Buffer.byteLength(artifact.payload, "utf8")).toBeGreaterThan(artifact.bytes);
+  });
+
+  it("keeps pinned artifacts visible while pruning unpinned records", () => {
+    const broker = createInMemoryContextBroker({ maxRecords: 2, defaultTtlMs: 0 });
+    const pinned = broker.publish({ sessionId: "s", kind: "diff", payload: "important", pinned: true, createdAt: 1 });
+    const older = broker.publish({ sessionId: "s", kind: "diff", payload: "temporary", createdAt: 2 });
+    const newer = broker.publish({ sessionId: "s", kind: "diff", payload: "latest", createdAt: 3 });
+
+    expect(broker.lookup({ id: pinned.id })).toEqual([pinned]);
+    expect(broker.lookup({ id: older.id })).toEqual([]);
+    expect(broker.lookup({ id: newer.id })).toEqual([newer]);
+    expect(broker.status().pinnedRecords).toBe(1);
+  });
+
+  it("expires unpinned artifacts by ttl", () => {
+    const broker = createInMemoryContextBroker({ defaultTtlMs: 10 });
+    const artifact = broker.publish({ sessionId: "s", kind: "tool_output", payload: "old", createdAt: 100 });
+
+    broker.prune(111);
+
+    expect(broker.lookup({ id: artifact.id })).toEqual([]);
+  });
+
+  it("prunes expired artifacts before lookup without an explicit prune call", () => {
+    const broker = createInMemoryContextBroker({ defaultTtlMs: 1 });
+    const artifact = broker.publish({ sessionId: "s", kind: "tool_output", payload: "expired", createdAt: 1 });
+
+    expect(broker.lookup({ id: artifact.id })).toEqual([]);
+    expect(broker.status().records).toBe(0);
+  });
+
+  it("omits expired artifacts from rendered prompt briefs", () => {
+    const broker = createInMemoryContextBroker({ defaultTtlMs: 1, briefBytes: 500 });
+    const artifact = broker.publish({ sessionId: "s", kind: "tool_output", payload: "expired secret", summary: "expired summary", createdAt: 1 });
+
+    const brief = broker.renderBrief({ sessionId: "s" });
+
+    expect(brief).not.toContain(artifact.handle);
+    expect(brief).not.toContain("expired summary");
+  });
+
+  it("keeps pinned expired artifacts visible until unpinned", () => {
+    const broker = createInMemoryContextBroker({ defaultTtlMs: 1 });
+    const artifact = broker.publish({ sessionId: "s", kind: "tool_output", payload: "pinned", pinned: true, createdAt: 1 });
+
+    expect(broker.lookup({ id: artifact.id })).toEqual([artifact]);
+    expect(broker.pin(artifact.id, false)).toBeNull();
+    expect(broker.lookup({ id: artifact.id })).toEqual([]);
+  });
+
+  it("renders a bounded prompt brief with lookup instructions", () => {
+    const broker = createInMemoryContextBroker({ briefBytes: 180 });
+    broker.publish({
+      sessionId: "s",
+      kind: "tool_output",
+      payload: "x".repeat(500),
+      summary: "large command output passed with no failures",
+      tags: ["test"],
+      paths: ["packages/core"],
+    });
+
+    const brief = broker.renderBrief();
+
+    expect(Buffer.byteLength(brief, "utf8")).toBeLessThanOrEqual(180);
+    expect(brief).toContain("Context Broker");
+    expect(brief).toContain("ctx://session/s/tool_output/");
+  });
+
+  it("enforces prompt brief budgets by UTF-8 byte length", () => {
+    const broker = createInMemoryContextBroker({ briefBytes: 170 });
+    broker.publish({
+      sessionId: "emoji-session",
+      kind: "tool_output",
+      payload: "✅".repeat(200),
+      summary: "✅ 測試 passed ".repeat(20),
+      tags: ["測試", "✅"],
+      paths: ["packages/核心/✅.ts"],
+    });
+
+    const brief = broker.renderBrief({ budgetBytes: 170 });
+
+    expect(Buffer.byteLength(brief, "utf8")).toBeLessThanOrEqual(170);
+    expect(brief).toContain("Context Broker");
+  });
+});

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.14",
-  "description": "Public Pi-Rogue bundle for advisor and orchestration. Single consolidated artefact (advisor and orchestration releases paused; their packages are private and 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": [
@@ -28,11 +32,15 @@
     "@earendil-works/pi-coding-agent": "^0.74.0"
   },
   "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);
 }