@fiale-plus/pi-rogue 0.2.0

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

@@ -0,0 +1,818 @@
+import { createHash } from "node:crypto";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+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";
+
+export interface ContextBrokerBetaOptions {
+  enabled?: boolean;
+  maxRecords?: number;
+  maxBytes?: number;
+  globalMaxRecords?: number;
+  globalMaxBytes?: 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 = 8 * 1024;
+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 envNonNegativeInt(name: string): number | undefined {
+  const raw = process.env[name];
+  if (!raw) return undefined;
+  const value = Number.parseInt(raw, 10);
+  if (!Number.isFinite(value) || value < 0) return undefined;
+  return value;
+}
+
+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 sanitizeForPrompt(text: string): string {
+  return String(text).replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, (char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, "0")}`);
+}
+
+function isHostilePayload(payload: string): boolean {
+  return hasHostileText(payload);
+}
+
+function hasHostileText(text: string): boolean {
+  let suspicious = 0;
+  let scanned = 0;
+  for (const char of text.slice(0, 4096)) {
+    const code = char.codePointAt(0) ?? 0;
+    scanned += 1;
+    if (
+      code === 0x00
+      || (code >= 0x01 && code <= 0x08)
+      || (code >= 0x0E && code <= 0x1F)
+      || (code >= 0x7F && code <= 0x9F)
+    ) {
+      suspicious += 1;
+    }
+  }
+  if (scanned < 12) return suspicious > 0;
+  return suspicious / scanned >= 0.05;
+}
+
+function hasHostileValue(value: unknown): boolean {
+  if (typeof value === "string") return hasHostileText(value);
+  if (Array.isArray(value)) return value.some(hasHostileValue);
+  if (value && typeof value === "object") {
+    return Object.values(value as Record<string, unknown>).some((entry) => hasHostileValue(entry));
+  }
+  return false;
+}
+
+function renderLookupOutput(item: ContextArtifact, payloadLimit: number): string {
+  const isBinary = item.tags.includes("hostile") || item.tags.includes("binary");
+  const payloadLines = isBinary
+    ? [
+      "payload:",
+      "[payload intentionally omitted from prompt for safety; use /context export",
+      sanitizeForPrompt(item.handle),
+      "for full content]",
+    ]
+    : [
+      "payload:",
+      truncateUtf8(sanitizeForPrompt(item.payload), payloadLimit),
+    ];
+
+  return [
+    sanitizeForPrompt(item.handle),
+    `tier=${item.tier} kind=${item.kind} bytes=${item.bytes}`,
+    `summary=${sanitizeForPrompt(item.summary)}`,
+    ...payloadLines,
+  ].join("\n");
+}
+
+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 contextLookupHistoryPlaceholder(): string {
+  return [
+    "Context lookup result omitted from prompt.",
+    "Prior context_lookup evidence is terminal and is not re-brokered.",
+    "Run context_lookup again with a focused handle/filter only if exact evidence is still needed.",
+  ].join("\n");
+}
+
+function prunedPayloadPlaceholder(hostile = false): string {
+  return [
+    "Context broker artifact pruned before prompt assembly.",
+    hostile ? "Raw hostile/binary payload omitted from prompt for safety." : "Raw payload omitted from prompt to avoid restoring pruned broker evidence.",
+    "Re-run the originating command or use a retained ctx:// handle if exact evidence is still needed.",
+  ].join("\n");
+}
+
+function summarizeTool(event: { toolName: string; input?: any; isError?: boolean }, bytes: number, hostile = false): 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}` : "";
+  const marker = hostile ? "; payload marked hostile; use /context export for full content" : "";
+  return `${event.isError ? "failed" : "completed"} ${event.toolName}${target}; payload=${bytes} bytes${marker}`;
+}
+
+const NON_BROKERED_TOOL_NAMES = new Set(["context_lookup"]);
+
+function shouldBrokerToolName(toolName: string): boolean {
+  return !NON_BROKERED_TOOL_NAMES.has(toolName);
+}
+
+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);
+}
+
+
+function isNeverBrokeredToolName(toolName: unknown): boolean {
+  return toolName === "advisor";
+}
+
+function isNeverBrokeredToolMessage(message: unknown): boolean {
+  if (message == null || typeof message !== "object") return false;
+  const maybe = message as { toolName?: unknown };
+  return isNeverBrokeredToolName(maybe.toolName);
+}
+
+export async function registerContextBrokerBeta(pi: ExtensionAPI, options: ContextBrokerBetaOptions = {}): Promise<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
+    ?? envNonNegativeInt("PI_CONTEXT_BROKER_REWRITE_THRESHOLD_BYTES")
+    ?? DEFAULT_REWRITE_THRESHOLD_BYTES;
+  const brokerOptions = {
+    maxRecords: options.maxRecords ?? 64,
+    maxBytes: options.maxBytes ?? 8 * 1024 * 1024,
+    globalMaxRecords: options.globalMaxRecords ?? envNonNegativeInt("PI_CONTEXT_BROKER_GLOBAL_MAX_RECORDS"),
+    globalMaxBytes: options.globalMaxBytes ?? envNonNegativeInt("PI_CONTEXT_BROKER_GLOBAL_MAX_BYTES"),
+    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 })
+      : (await import("./sqlite.js")).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();
+  const routingTelemetry = {
+    contextHookCalls: 0,
+    contextHookToolResults: 0,
+    contextHookToolResultRewrites: 0,
+    contextHookToolResultHostile: 0,
+    contextHookBash: 0,
+    contextHookBashRewrites: 0,
+    contextHookBashHostile: 0,
+    toolResultEvents: 0,
+    toolResultArtifacts: 0,
+    backfillScans: 0,
+    backfillAdded: 0,
+    backfillErrors: 0,
+    toolLookupCalls: 0,
+    toolLookupExactCalls: 0,
+    toolLookupTextCalls: 0,
+    toolLookupHits: 0,
+    toolLookupMisses: 0,
+    commandLookupCalls: 0,
+    commandLookupExactCalls: 0,
+    commandLookupTextCalls: 0,
+    commandLookupHits: 0,
+    commandLookupMisses: 0,
+    exportCalls: 0,
+    pinCalls: 0,
+    statusCalls: 0,
+    pruneCalls: 0,
+  };
+
+  function formatRoutingTelemetry(): string {
+    const line = [
+      `contextHook calls=${routingTelemetry.contextHookCalls}`,
+      `toolResults seen=${routingTelemetry.contextHookToolResults} rewritten=${routingTelemetry.contextHookToolResultRewrites} hostile=${routingTelemetry.contextHookToolResultHostile}`,
+      `bash seen=${routingTelemetry.contextHookBash} rewritten=${routingTelemetry.contextHookBashRewrites} hostile=${routingTelemetry.contextHookBashHostile}`,
+      `lookups tool(calls=${routingTelemetry.toolLookupCalls}, hits=${routingTelemetry.toolLookupHits}, misses=${routingTelemetry.toolLookupMisses})`,
+      `lookups slash(calls=${routingTelemetry.commandLookupCalls}, hits=${routingTelemetry.commandLookupHits}, misses=${routingTelemetry.commandLookupMisses})`,
+      `exports=${routingTelemetry.exportCalls}`,
+      `pins=${routingTelemetry.pinCalls}`,
+      `pruneCalls=${routingTelemetry.pruneCalls}`,
+      `backfill scans=${routingTelemetry.backfillScans} added=${routingTelemetry.backfillAdded} errors=${routingTelemetry.backfillErrors}`,
+    ];
+    return `Context broker routing telemetry: ${line.join(", ")}`;
+  }
+
+  function publishToolArtifact(event: {
+    toolName: string;
+    input?: any;
+    content?: unknown;
+    details?: unknown;
+    isError?: boolean;
+    sourceId?: string;
+    createdAt?: number;
+    ttlMs?: number;
+  }): ContextArtifact | null {
+    if (!shouldBrokerToolName(event.toolName)) return 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 hostilePayload = isHostilePayload(payload) || hasHostileValue(sanitizedEvent);
+    const artifact = broker.publish({
+      sessionId: activeSessionId,
+      kind: "tool_output",
+      payload,
+      summary: summarizeTool(sanitizedEvent, bytes, hostilePayload),
+      tags: [
+        event.toolName,
+        event.isError ? "error" : "ok",
+        event.sourceId ? "session-backfill" : "live",
+        ...(hostilePayload ? ["hostile", "binary"] : []),
+      ],
+      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 (artifact) routingTelemetry.toolResultArtifacts += 1;
+    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;
+          routingTelemetry.backfillScans += 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,
+            ttlMs: ttlFromNowFor(createdAt),
+          }) && !alreadySeen) {
+            added += 1;
+            routingTelemetry.backfillAdded += 1;
+          }
+        }
+
+        if (entry?.type === "message" && entry.message?.role === "bashExecution") {
+          if (entry.message.excludeFromContext === true) continue;
+          scanned += 1;
+          routingTelemetry.backfillScans += 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,
+            ttlMs: ttlFromNowFor(createdAt),
+          }) && !alreadySeen) {
+            added += 1;
+            routingTelemetry.backfillAdded += 1;
+          }
+        }
+      } catch {
+        errors += 1;
+        routingTelemetry.backfillErrors += 1;
+      }
+    }
+
+    return { added, scanned, errors };
+  }
+
+  function currentBrief(): string {
+    return broker.renderBrief({ sessionId: activeSessionId, budgetBytes: briefBytes });
+  }
+
+  p.__piRogueContextBroker = {
+    renderBrief: currentBrief,
+    lookup: broker.lookup,
+    status: broker.status,
+  };
+
+  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: "export ", label: "export", description: "Export full payload for a ctx:// handle or id" },
+    { value: "prune", label: "prune", description: "Run TTL/cap pruning now" },
+  ];
+
+  function artifactCompletions(action: "lookup" | "pin" | "export", 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" || action === "export") {
+      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");
+    ctx.ui.notify(
+      `Context broker enabled. Backfilled ${added}/${scanned} current-branch tool artifacts${errors ? ` (${errors} malformed skipped)` : ""}. Use /context status or /context brief.`,
+      errors ? "warning" : "info",
+    );
+  });
+
+  pi.on("session_compact", async (_event, ctx) => {
+    activeSessionId = sessionIdFor(ctx);
+    const before = broker.status();
+    const after = broker.purge({ sessionId: activeSessionId, keepPinned: true });
+    seenSourceIds.clear();
+    sourceHandles.clear();
+    const removed = before.records - after.records;
+    if (removed > 0) ctx.ui.notify(`Context broker compact cleanup purged ${removed} unpinned artifact${removed === 1 ? "" : "s"}; pinned artifacts retained.`, "info");
+  });
+
+  pi.on("tool_result", async (event: ToolResultEvent, ctx) => {
+    activeSessionId = sessionIdFor(ctx);
+    routingTelemetry.toolResultEvents += 1;
+    publishToolArtifact({ ...event, sourceId: event.toolCallId });
+  });
+
+  pi.on("context", async (event, ctx) => {
+    activeSessionId = sessionIdFor(ctx);
+    routingTelemetry.contextHookCalls += 1;
+    const toolInputs = collectToolInputs(event.messages);
+    const drafts = event.messages.map((message: any): { original: any; replacement?: any; artifact?: ContextArtifact; rewrite?: (artifact: ContextArtifact) => any; safeFallback?: any } => {
+      if (message?.role === "toolResult") {
+        routingTelemetry.contextHookToolResults += 1;
+        const raw = contentText(message.content);
+        const toolInput = typeof message.toolCallId === "string" ? toolInputs.get(message.toolCallId) : undefined;
+        const toolName = String(message.toolName ?? toolInput?.toolName ?? "tool");
+        const hostile = hasHostileText(raw) || hasHostileValue(message.content);
+        if (hostile) routingTelemetry.contextHookToolResultHostile += 1;
+        const shouldRewrite = Buffer.byteLength(raw, "utf8") > rewriteThresholdBytes || hostile;
+        if (!shouldRewrite) return { original: message };
+        if (!shouldBrokerToolName(toolName)) {
+          return { original: message, replacement: { ...message, content: [{ type: "text", text: contextLookupHistoryPlaceholder() }] } };
+        }
+        const artifact = publishToolArtifact({
+          toolName,
+          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 };
+        routingTelemetry.contextHookToolResultRewrites += 1;
+        return {
+          original: message,
+          artifact,
+          rewrite: (live) => ({ ...message, content: [{ type: "text", text: brokerPlaceholder(live) }] }),
+          safeFallback: { ...message, content: [{ type: "text", text: prunedPayloadPlaceholder(hostile) }] },
+        };
+      }
+
+      if (message?.role === "bashExecution" && message.excludeFromContext !== true) {
+        routingTelemetry.contextHookBash += 1;
+        const raw = String(message.output ?? "");
+        const hostile = hasHostileText(raw) || hasHostileValue(message.output);
+        if (hostile) routingTelemetry.contextHookBashHostile += 1;
+        const shouldRewrite = Buffer.byteLength(raw, "utf8") > rewriteThresholdBytes || hostile;
+        if (!shouldRewrite) 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 };
+        routingTelemetry.contextHookBashRewrites += 1;
+        return {
+          original: message,
+          artifact,
+          rewrite: (live) => ({ ...message, output: brokerPlaceholder(live), truncated: true }),
+          safeFallback: { ...message, output: prunedPayloadPlaceholder(hostile), truncated: true },
+        };
+      }
+
+      return { original: message };
+    });
+
+    let changed = false;
+    const messages = drafts.map((draft) => {
+      if (draft.replacement) {
+        changed = true;
+        return draft.replacement;
+      }
+      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);
+        if (draft.safeFallback) {
+          changed = true;
+          return draft.safeFallback;
+        }
+        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 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);
+      routingTelemetry.toolLookupCalls += 1;
+      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://");
+      routingTelemetry.toolLookupExactCalls += exact ? 1 : 0;
+      routingTelemetry.toolLookupTextCalls += exact ? 0 : 1;
+      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) {
+        routingTelemetry.toolLookupMisses += 1;
+        return textResult("No context artifacts matched. Missing or expired handles should be reported explicitly.");
+      }
+      routingTelemetry.toolLookupHits += 1;
+      return textResult(results.map((item) => renderLookupOutput(item, exact ? lookupBytes : searchBytes)).join("\n\n---\n\n"));
+    },
+  });
+
+  pi.registerCommand("context", {
+    description: "Inspect the context broker: status | brief | lookup <handle-or-text> | pin <handle-or-id> | export <handle-or-id> | 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") {
+        routingTelemetry.statusCalls += 1;
+        const status = broker.status();
+        ctx.ui.notify(
+          `Context broker: 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",
+        );
+        ctx.ui.notify(formatRoutingTelemetry(), "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;
+        }
+        routingTelemetry.commandLookupCalls += 1;
+        const exact = query.startsWith("ctx://");
+        routingTelemetry.commandLookupExactCalls += exact ? 1 : 0;
+        routingTelemetry.commandLookupTextCalls += exact ? 0 : 1;
+        const results = broker.lookup(exact ? { handle: query } : { sessionId: activeSessionId, text: query, limit: 5 });
+        if (results.length) {
+          routingTelemetry.commandLookupHits += 1;
+        } else {
+          routingTelemetry.commandLookupMisses += 1;
+        }
+        ctx.ui.notify(results.length ? results.map((item) => renderLookupOutput(item, exact ? lookupBytes : searchBytes)).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);
+        routingTelemetry.pinCalls += 1;
+        ctx.ui.notify(pinned ? `Pinned ${pinned.handle}` : "No artifact matched that handle/id.", pinned ? "info" : "warning");
+        return;
+      }
+
+      if (action === "export") {
+        if (!query) {
+          ctx.ui.notify("Usage: /context export <ctx://handle-or-id>", "warning");
+          return;
+        }
+
+        const exact = query.startsWith("ctx://");
+        const artifact = exact ? broker.lookup({ handle: query })[0] : broker.lookup({ id: query })[0];
+        if (!artifact) {
+          ctx.ui.notify("No artifact matched that handle-or-id.", "warning");
+          return;
+        }
+
+        const exportDir = mkdtempSync(join(tmpdir(), "pi-context-broker-export-"));
+        const exportPath = join(exportDir, `${artifact.id}.txt`);
+        writeFileSync(exportPath, artifact.payload, "utf8");
+        routingTelemetry.exportCalls += 1;
+        ctx.ui.notify(`Exported full payload for ${sanitizeForPrompt(artifact.handle)} (${artifact.bytes} bytes) to ${exportPath}`, "info");
+        return;
+      }
+
+      if (action === "prune") {
+        routingTelemetry.pruneCalls += 1;
+        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-or-id> | export <handle-or-id> | prune", "warning");
+    },
+  });
+}
+
+export function shouldEnableContextBrokerBeta(options: ContextBrokerBetaOptions = {}): boolean {
+  return Boolean(options.enabled ?? isEnvEnabled());
+}