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

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

@@ -0,0 +1,573 @@
+import { createHash } from "node:crypto";
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import type { ExtensionAPI, ExtensionContext, ToolResultEvent } from "@earendil-works/pi-coding-agent";
+import type { ContextArtifact } from "@fiale-plus/pi-core";
+import { createFileContextBroker } from "./file.js";
+import { createInMemoryContextBroker } from "./index.js";
+import { createSqliteContextBroker } from "./sqlite.js";
+
+export interface ContextBrokerBetaOptions {
+  enabled?: boolean;
+  maxRecords?: number;
+  maxBytes?: number;
+  briefBytes?: number;
+  lookupBytes?: number;
+  searchBytes?: number;
+  rewriteThresholdBytes?: number;
+  durable?: boolean;
+  storeDir?: string;
+}
+
+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_REWRITE_THRESHOLD_BYTES = 2_000;
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const ENABLED_VALUES = new Set(["1", "true", "yes", "on"]);
+
+function envFlag(name: string): boolean {
+  return ENABLED_VALUES.has(String(process.env[name] ?? "").trim().toLowerCase());
+}
+
+function isEnvEnabled(): boolean {
+  return envFlag("PI_CONTEXT_BROKER_ENABLED");
+}
+
+function isSensitiveKey(key: string): boolean {
+  return /(?:api[_-]?key|token|secret|password|credential)/i.test(key);
+}
+
+function redactSecrets(text: string): string {
+  return text
+    .replace(/\b(sk-[A-Za-z0-9_-]{12,})\b/g, "[REDACTED_API_KEY]")
+    .replace(/\b(gh[pousr]_[A-Za-z0-9_]{12,})\b/g, "[REDACTED_GITHUB_TOKEN]")
+    .replace(/([\"']?(?:api[_-]?key|token|secret|password|credential)[\w.-]*[\"']?\s*[:=]\s*[\"']?)([^\s'\",;}]+)/gi, "$1[REDACTED]");
+}
+
+function sanitizeValue(value: unknown, depth = 0): unknown {
+  if (typeof value === "string") return redactSecrets(value);
+  if (value == null || typeof value !== "object") return value;
+  if (depth > 6) return "[MAX_DEPTH]";
+  if (Array.isArray(value)) return value.map((item) => sanitizeValue(item, depth + 1));
+  return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([key, item]) => [
+    key,
+    isSensitiveKey(key) ? "[REDACTED]" : sanitizeValue(item, depth + 1),
+  ]));
+}
+
+function toText(value: unknown): string {
+  if (typeof value === "string") return redactSecrets(value);
+  try {
+    return redactSecrets(JSON.stringify(value, null, 2));
+  } catch {
+    return redactSecrets(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 stableHash(value: string): string {
+  return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+
+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 contentText(content: unknown): string {
+  if (Array.isArray(content)) {
+    return content.map((block) => block?.type === "text" ? block.text : toText(block)).join("\n");
+  }
+  return toText(content);
+}
+
+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 textResult(text: string): AgentToolResult<unknown> {
+  return { content: [{ type: "text", text }], details: {} };
+}
+
+function brokerPlaceholder(artifact: ContextArtifact): string {
+  return [
+    `Context broker artifact: ${artifact.handle}`,
+    `Summary: ${artifact.summary}`,
+    `Payload bytes: ${artifact.bytes}`,
+    "Raw payload omitted from prompt. Use /context lookup <handle> if exact evidence is needed.",
+  ].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`;
+}
+
+function ttlFromNowFor(createdAt: number | undefined): number | undefined {
+  if (typeof createdAt !== "number" || !Number.isFinite(createdAt)) return undefined;
+  return Math.max(DEFAULT_TTL_MS, Date.now() - createdAt + DEFAULT_TTL_MS);
+}
+
+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 rewriteThresholdBytes = options.rewriteThresholdBytes ?? DEFAULT_REWRITE_THRESHOLD_BYTES;
+  const brokerOptions = {
+    maxRecords: options.maxRecords ?? 64,
+    maxBytes: options.maxBytes ?? 8 * 1024 * 1024,
+    briefBytes,
+  };
+  const durable = options.durable ?? (envFlag("PI_CONTEXT_BROKER_DURABLE") || Boolean(options.storeDir ?? process.env.PI_CONTEXT_BROKER_STORE_DIR));
+  const durableBackend = String(process.env.PI_CONTEXT_BROKER_BACKEND ?? "sqlite").trim().toLowerCase();
+  const broker = durable
+    ? durableBackend === "jsonl"
+      ? createFileContextBroker({ ...brokerOptions, dir: options.storeDir ?? process.env.PI_CONTEXT_BROKER_STORE_DIR })
+      : createSqliteContextBroker({ ...brokerOptions, dir: options.storeDir ?? process.env.PI_CONTEXT_BROKER_STORE_DIR })
+    : createInMemoryContextBroker(brokerOptions);
+  const seenSourceIds = new Set<string>();
+  const sourceHandles = new Map<string, string>();
+  let activeSessionId = process.cwd();
+
+  function currentBrief(): string {
+    return broker.renderBrief({ sessionId: activeSessionId, budgetBytes: briefBytes });
+  }
+
+  p.__piRogueContextBroker = {
+    renderBrief: currentBrief,
+    lookup: broker.lookup,
+    status: broker.status,
+  };
+
+  function publishToolArtifact(event: {
+    toolName: string;
+    input?: any;
+    content?: unknown;
+    details?: unknown;
+    isError?: boolean;
+    sourceId?: string;
+    createdAt?: number;
+    ttlMs?: number;
+  }): ContextArtifact | null {
+    if (event.sourceId) {
+      const existingHandle = sourceHandles.get(event.sourceId);
+      if (existingHandle) {
+        const existing = broker.lookup({ handle: existingHandle })[0];
+        if (existing) return existing;
+        sourceHandles.delete(event.sourceId);
+        seenSourceIds.delete(event.sourceId);
+      }
+      if (seenSourceIds.has(event.sourceId)) seenSourceIds.delete(event.sourceId);
+      seenSourceIds.add(event.sourceId);
+    }
+
+    const sanitizedEvent = {
+      ...event,
+      input: sanitizeValue(event.input) as any,
+      content: sanitizeValue(event.content),
+      details: sanitizeValue(event.details),
+    };
+    const payload = toolPayload(sanitizedEvent);
+    const bytes = Buffer.byteLength(payload, "utf8");
+    const artifact = broker.publish({
+      sessionId: activeSessionId,
+      kind: "tool_output",
+      payload,
+      summary: summarizeTool(sanitizedEvent, bytes),
+      tags: [event.toolName, event.isError ? "error" : "ok", event.sourceId ? "session-backfill" : "live"],
+      command: event.toolName === "bash" && typeof sanitizedEvent.input?.command === "string" ? sanitizedEvent.input.command : undefined,
+      paths: typeof sanitizedEvent.input?.path === "string" ? [sanitizedEvent.input.path] : [],
+      ttlMs: event.ttlMs ?? DEFAULT_TTL_MS,
+      parentIds: event.sourceId ? [event.sourceId] : [],
+      createdAt: event.createdAt,
+    });
+    if (event.sourceId) sourceHandles.set(event.sourceId, artifact.handle);
+    return artifact;
+  }
+
+  function collectToolInputs(entries: any[]): Map<string, { toolName?: string; input?: unknown }> {
+    const toolInputs = new Map<string, { toolName?: string; input?: unknown }>();
+    for (const entry of entries) {
+      const message = entry?.type === "message" ? entry.message : entry;
+      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 });
+        }
+      }
+    }
+    return toolInputs;
+  }
+
+  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 = collectToolInputs(entries);
+
+    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;
+          const alreadySeen = sourceId ? seenSourceIds.has(sourceId) || sourceHandles.has(sourceId) : false;
+          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,
+          }) && !alreadySeen) added += 1;
+        }
+
+        if (entry?.type === "message" && entry.message?.role === "bashExecution") {
+          if (entry.message.excludeFromContext === true) continue;
+          scanned += 1;
+          const sourceId = entryId;
+          const alreadySeen = sourceId ? seenSourceIds.has(sourceId) || sourceHandles.has(sourceId) : false;
+          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,
+          }) && !alreadySeen) 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("context", async (event, ctx) => {
+    activeSessionId = sessionIdFor(ctx);
+    const toolInputs = collectToolInputs(event.messages);
+    const drafts = event.messages.map((message: any): { original: any; artifact?: ContextArtifact; rewrite?: (artifact: ContextArtifact) => any } => {
+      if (message?.role === "toolResult") {
+        const raw = contentText(message.content);
+        if (Buffer.byteLength(raw, "utf8") <= rewriteThresholdBytes) return { original: message };
+        const toolInput = typeof message.toolCallId === "string" ? toolInputs.get(message.toolCallId) : undefined;
+        const artifact = publishToolArtifact({
+          toolName: String(message.toolName ?? toolInput?.toolName ?? "tool"),
+          input: message.input ?? toolInput?.input,
+          content: message.content,
+          details: message.details,
+          isError: Boolean(message.isError),
+          sourceId: typeof message.toolCallId === "string" ? message.toolCallId : undefined,
+          createdAt: typeof message.timestamp === "number" ? message.timestamp : undefined,
+          ttlMs: ttlFromNowFor(typeof message.timestamp === "number" ? message.timestamp : undefined),
+        });
+        if (!artifact) return { original: message };
+        return { original: message, artifact, rewrite: (live) => ({ ...message, content: [{ type: "text", text: brokerPlaceholder(live) }] }) };
+      }
+
+      if (message?.role === "bashExecution" && message.excludeFromContext !== true) {
+        const raw = String(message.output ?? "");
+        if (Buffer.byteLength(raw, "utf8") <= rewriteThresholdBytes) return { original: message };
+        const sourceId = typeof message.timestamp === "number"
+          ? `bash:${message.timestamp}:${stableHash([message.command ?? "", raw, message.exitCode ?? "", message.cancelled ?? ""].join("\n"))}`
+          : `bash:${stableHash([message.command ?? "", raw, message.exitCode ?? "", message.cancelled ?? ""].join("\n"))}`;
+        const artifact = publishToolArtifact({
+          toolName: "bash",
+          input: { command: message.command },
+          content: message.output,
+          details: {
+            exitCode: message.exitCode,
+            cancelled: message.cancelled,
+            truncated: message.truncated,
+            fullOutputPath: message.fullOutputPath,
+          },
+          isError: typeof message.exitCode === "number" ? message.exitCode !== 0 : Boolean(message.cancelled),
+          sourceId,
+          createdAt: typeof message.timestamp === "number" ? message.timestamp : undefined,
+          ttlMs: ttlFromNowFor(typeof message.timestamp === "number" ? message.timestamp : undefined),
+        });
+        if (!artifact) return { original: message };
+        return { original: message, artifact, rewrite: (live) => ({ ...message, output: brokerPlaceholder(live), truncated: true }) };
+      }
+
+      return { original: message };
+    });
+
+    let changed = false;
+    const messages = drafts.map((draft) => {
+      if (!draft.artifact || !draft.rewrite) return draft.original;
+      const live = broker.lookup({ handle: draft.artifact.handle })[0];
+      if (!live) {
+        for (const parentId of draft.artifact.parentIds) sourceHandles.delete(parentId);
+        return draft.original;
+      }
+      changed = true;
+      return draft.rewrite(live);
+    });
+
+    return changed ? { messages } : undefined;
+  });
+
+  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.registerTool({
+    name: "context_lookup",
+    label: "Context Lookup",
+    description: "Lookup exact or searchable context broker artifacts by handle, current-session text, path, tag, kind, or tier.",
+    promptSnippet: "context_lookup: retrieve context broker artifacts by ctx:// handle or focused filters before asking the user to repeat prior tool output.",
+    promptGuidelines: [
+      "Use context_lookup when a ctx:// handle is relevant and exact evidence is needed.",
+      "Do not paste large raw broker payloads unless the user explicitly asks; summarize and cite handles instead.",
+    ],
+    parameters: Type.Object({
+      handle: Type.Optional(Type.String({ description: "Exact ctx:// handle to retrieve" })),
+      text: Type.Optional(Type.String({ description: "Current-session text search over broker summaries and indexed payload text" })),
+      path: Type.Optional(Type.String({ description: "File or directory path filter" })),
+      tag: Type.Optional(Type.String({ description: "Artifact tag filter" })),
+      kind: Type.Optional(Type.String({ enum: ["tool_output", "diff", "file_snapshot", "subagent_result", "advisor_brief", "memory_note"] })),
+      tier: Type.Optional(Type.String({ enum: ["hot", "warm", "cold"] })),
+      limit: Type.Optional(Type.Number({ minimum: 1, maximum: 10, description: "Maximum artifacts to return" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      activeSessionId = sessionIdFor(ctx);
+      const p = params as { handle?: string; text?: string; path?: string; tag?: string; kind?: any; tier?: any; limit?: number };
+      const exact = typeof p.handle === "string" && p.handle.startsWith("ctx://");
+      const focused = exact || Boolean(p.text?.trim() || p.path?.trim() || p.tag?.trim() || p.kind || p.tier);
+      if (!focused) {
+        return textResult("context_lookup requires a focused filter: handle, text, path, tag, kind, or tier. Empty lookups are refused to avoid dumping brokered payloads into the prompt.");
+      }
+      const results = broker.lookup({
+        handle: exact ? p.handle : undefined,
+        sessionId: exact ? undefined : activeSessionId,
+        text: exact ? undefined : p.text,
+        path: p.path,
+        tag: p.tag,
+        kind: p.kind,
+        tier: p.tier,
+        limit: Math.min(10, Math.max(1, Math.floor(p.limit ?? (exact ? 1 : 5)))),
+      });
+      if (!results.length) return textResult("No context artifacts matched. Missing or expired handles should be reported explicitly.");
+      return textResult(results.map((item) => [
+        item.handle,
+        `tier=${item.tier} kind=${item.kind} bytes=${item.bytes}`,
+        `summary=${item.summary}`,
+        "payload:",
+        truncateUtf8(item.payload, exact ? lookupBytes : searchBytes),
+      ].join("\n")).join("\n\n---\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}, tiers=hot:${status.hotRecords}/${status.hotBytes} warm:${status.warmRecords}/${status.warmBytes} cold:${status.coldRecords}/${status.coldBytes}, 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());
+}