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

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

@@ -0,0 +1,165 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { safeName } from "@fiale-plus/pi-core";
+import type { BoundedContextBroker, ContextArtifact, ContextArtifactInput, ContextArtifactTier, ContextBrokerOptions, ContextBrokerStatus, ContextLookupQuery } from "@fiale-plus/pi-core";
+import { createInMemoryContextBroker } from "./index.js";
+
+export interface FileContextBrokerOptions extends ContextBrokerOptions {
+  dir?: string;
+}
+
+const STORE_VERSION = 1;
+
+interface StoredRecord {
+  version: number;
+  handle: string;
+  baseTier?: ContextArtifactTier;
+  input: Omit<ContextArtifactInput, "payload"> & { payloadSha256: string };
+}
+
+function defaultStoreDir(): string {
+  return join(homedir(), ".pi", "agent", "fiale-plus", "context-broker");
+}
+
+function ensureDir(path: string): void {
+  mkdirSync(path, { recursive: true });
+}
+
+function metadataFile(dir: string): string {
+  return join(dir, "metadata.jsonl");
+}
+
+function blobFile(dir: string, sha256: string): string {
+  return join(dir, "blobs", `${sha256}.txt`);
+}
+
+function stableSource(input: ContextArtifactInput): string | undefined {
+  return input.parentIds?.find(Boolean);
+}
+
+function readStoredRecords(dir: string): StoredRecord[] {
+  const file = metadataFile(dir);
+  if (!existsSync(file)) return [];
+  const recordsByHandle = new Map<string, StoredRecord>();
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed) as StoredRecord;
+      if (parsed?.version === STORE_VERSION && parsed.handle && parsed.input?.payloadSha256) {
+        recordsByHandle.set(parsed.handle, parsed);
+      }
+    } catch {
+      // Ignore corrupt JSONL rows; durable storage is append-only recovery, not a startup blocker.
+    }
+  }
+  return [...recordsByHandle.values()];
+}
+
+function loadPayload(dir: string, sha256: string): string | undefined {
+  const file = blobFile(dir, sha256);
+  if (!existsSync(file)) return undefined;
+  return readFileSync(file, "utf8");
+}
+
+function artifactBaseTier(artifact: ContextArtifact, fallback?: ContextArtifactTier): ContextArtifactTier {
+  return (artifact as ContextArtifact & { baseTier?: ContextArtifactTier }).baseTier ?? fallback ?? artifact.tier;
+}
+
+function persistRecord(dir: string, artifact: ContextArtifact, input: ContextArtifactInput): void {
+  ensureDir(join(dir, "blobs"));
+  const blob = blobFile(dir, artifact.sha256);
+  if (!existsSync(blob)) writeFileSync(blob, artifact.payload, "utf8");
+  const record: StoredRecord = {
+    version: STORE_VERSION,
+    handle: artifact.handle,
+    baseTier: artifactBaseTier(artifact, input.tier),
+    input: {
+      sessionId: input.sessionId,
+      kind: input.kind,
+      summary: input.summary,
+      tags: input.tags,
+      paths: input.paths,
+      command: input.command,
+      branch: input.branch,
+      tier: artifactBaseTier(artifact, input.tier),
+      ttlMs: input.ttlMs,
+      pinned: artifact.pinned,
+      parentIds: input.parentIds,
+      createdAt: input.createdAt ?? artifact.createdAt,
+      payloadSha256: artifact.sha256,
+    },
+  };
+  ensureDir(dirname(metadataFile(dir)));
+  appendFileSync(metadataFile(dir), `${JSON.stringify(record)}\n`, "utf8");
+}
+
+function persistArtifactSnapshot(dir: string, artifact: ContextArtifact): void {
+  persistRecord(dir, artifact, {
+    sessionId: artifact.sessionId,
+    kind: artifact.kind,
+    payload: artifact.payload,
+    summary: artifact.summary,
+    tags: artifact.tags,
+    paths: artifact.paths,
+    command: artifact.command,
+    branch: artifact.branch,
+    tier: artifactBaseTier(artifact),
+    ttlMs: artifact.expiresAt ? Math.max(0, artifact.expiresAt - artifact.createdAt) : 0,
+    pinned: artifact.pinned,
+    parentIds: artifact.parentIds,
+    createdAt: artifact.createdAt,
+  });
+}
+
+export function createFileContextBroker(options: FileContextBrokerOptions = {}): BoundedContextBroker {
+  const dir = options.dir ?? process.env.PI_CONTEXT_BROKER_STORE_DIR ?? defaultStoreDir();
+  ensureDir(join(dir, "blobs"));
+  const broker = createInMemoryContextBroker(options);
+  const persistedSources = new Map<string, string>();
+  const handleAliases = new Map<string, string>();
+
+  for (const record of readStoredRecords(dir)) {
+    const payload = loadPayload(dir, record.input.payloadSha256);
+    if (payload === undefined) continue;
+    const artifact = broker.publish({ ...record.input, tier: record.baseTier ?? record.input.tier, payload });
+    handleAliases.set(record.handle, artifact.handle);
+    const source = stableSource(record.input as unknown as ContextArtifactInput);
+    if (source) persistedSources.set(source, artifact.handle);
+  }
+
+  function publish(input: ContextArtifactInput): ContextArtifact {
+    const source = stableSource(input);
+    const existingHandle = source ? persistedSources.get(source) : undefined;
+    if (existingHandle) {
+      const existing = broker.lookup({ handle: existingHandle })[0];
+      if (existing) return existing;
+    }
+
+    const artifact = broker.publish(input);
+    if (source) persistedSources.set(source, artifact.handle);
+    persistRecord(dir, artifact, input);
+    return artifact;
+  }
+
+  return {
+    publish,
+    lookup(query?: ContextLookupQuery): ContextArtifact[] {
+      const mappedHandle = query?.handle ? handleAliases.get(query.handle) : undefined;
+      return broker.lookup(mappedHandle ? { ...query, handle: mappedHandle } : query);
+    },
+    pin(idOrHandle: string, pinned?: boolean): ContextArtifact | null {
+      const artifact = broker.pin(handleAliases.get(idOrHandle) ?? idOrHandle, pinned);
+      if (artifact) persistArtifactSnapshot(dir, artifact);
+      return artifact;
+    },
+    prune(now?: number): ContextBrokerStatus { return broker.prune(now); },
+    status(): ContextBrokerStatus { return broker.status(); },
+    renderBrief(query?: ContextLookupQuery & { budgetBytes?: number }): string { return broker.renderBrief(query); },
+  };
+}
+
+export function contextBrokerStoreDirForSession(baseDir: string, sessionId: string): string {
+  return join(baseDir, safeName(sessionId));
+}

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", () => {
@@ -179,6 +179,66 @@ describe("createInMemoryContextBroker", () => {
     expect(broker.lookup({ id: artifact.id })).toEqual([]);
   });
 
+  it("classifies artifacts into hot, warm, and cold tiers on publish", () => {
+    const broker = createInMemoryContextBroker({ defaultTtlMs: 0 });
+    const failure = broker.publish({ sessionId: "s", kind: "tool_output", payload: "failed", tags: ["error"], createdAt: 1 });
+    const command = broker.publish({ sessionId: "s", kind: "tool_output", payload: "passed", tags: ["ok"], createdAt: 2 });
+    const archive = broker.publish({ sessionId: "s", kind: "subagent_result", payload: "old", tags: ["completed"], createdAt: 3 });
+    const explicit = broker.publish({ sessionId: "s", kind: "diff", payload: "manual", tier: "cold", createdAt: 4 });
+
+    expect(failure.tier).toBe("hot");
+    expect(command.tier).toBe("warm");
+    expect(archive.tier).toBe("cold");
+    expect(explicit.tier).toBe("cold");
+    expect(broker.lookup({ sessionId: "s", tier: "cold" }).map((artifact) => artifact.id)).toEqual([explicit.id, archive.id]);
+  });
+
+  it("renders prompt briefs hot-first, warm-second, and excludes cold unless explicit", () => {
+    const broker = createInMemoryContextBroker({ briefBytes: 900, defaultTtlMs: 0 });
+    const cold = broker.publish({ sessionId: "s", kind: "tool_output", payload: "cold", summary: "cold archive", tier: "cold", createdAt: 1 });
+    const warm = broker.publish({ sessionId: "s", kind: "tool_output", payload: "warm", summary: "warm command", tier: "warm", createdAt: 2 });
+    const hot = broker.publish({ sessionId: "s", kind: "tool_output", payload: "hot", summary: "hot failure", tier: "hot", createdAt: 3 });
+
+    const brief = broker.renderBrief({ sessionId: "s" });
+    expect(brief).toContain("Hot:");
+    expect(brief).toContain(hot.handle);
+    expect(brief).toContain("Warm:");
+    expect(brief).toContain(warm.handle);
+    expect(brief).not.toContain(cold.handle);
+    expect(brief.indexOf(hot.handle)).toBeLessThan(brief.indexOf(warm.handle));
+
+    const coldBrief = broker.renderBrief({ sessionId: "s", tier: "cold", budgetBytes: 500 });
+    expect(coldBrief).toContain("Cold:");
+    expect(coldBrief).toContain(cold.handle);
+
+    expect(broker.pin(cold.handle, true)?.tier).toBe("hot");
+    expect(broker.renderBrief({ sessionId: "s" })).toContain(cold.handle);
+    expect(broker.pin(cold.handle, false)?.tier).toBe("cold");
+    expect(broker.renderBrief({ sessionId: "s" })).not.toContain(cold.handle);
+  });
+
+  it("applies tier-specific record, byte, and ttl retention", () => {
+    const broker = createInMemoryContextBroker({
+      defaultTtlMs: 0,
+      hotMaxRecords: 1,
+      warmMaxBytes: 6,
+      coldTtlMs: 10,
+    });
+    const oldHot = broker.publish({ sessionId: "s", kind: "tool_output", payload: "old-hot", tier: "hot", createdAt: 1 });
+    const newHot = broker.publish({ sessionId: "s", kind: "tool_output", payload: "new-hot", tier: "hot", createdAt: 2 });
+    const oldWarm = broker.publish({ sessionId: "s", kind: "tool_output", payload: "12345", tier: "warm", createdAt: 3 });
+    const newWarm = broker.publish({ sessionId: "s", kind: "tool_output", payload: "abcde", tier: "warm", createdAt: 4 });
+    const cold = broker.publish({ sessionId: "s", kind: "tool_output", payload: "cold", tier: "cold", createdAt: 5 });
+
+    expect(broker.lookup({ id: oldHot.id })).toEqual([]);
+    expect(broker.lookup({ id: newHot.id })).toEqual([newHot]);
+    expect(broker.lookup({ id: oldWarm.id })).toEqual([]);
+    expect(broker.lookup({ id: newWarm.id })).toEqual([newWarm]);
+
+    broker.prune(16);
+    expect(broker.lookup({ id: cold.id })).toEqual([]);
+  });
+
   it("renders a bounded prompt brief with lookup instructions", () => {
     const broker = createInMemoryContextBroker({ briefBytes: 180 });
     broker.publish({

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

@@ -0,0 +1,324 @@
+import { createHash } from "node:crypto";
+import { safeName } from "@fiale-plus/pi-core";
+import type {
+  BoundedContextBroker,
+  ContextArtifact,
+  ContextArtifactInput,
+  ContextArtifactKind,
+  ContextArtifactTier,
+  ContextBrokerOptions,
+  ContextBrokerStatus,
+  ContextLookupQuery,
+} from "@fiale-plus/pi-core";
+
+export type {
+  BoundedContextBroker,
+  ContextArtifact,
+  ContextArtifactInput,
+  ContextArtifactKind,
+  ContextArtifactTier,
+  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;
+const TIER_ORDER: Record<ContextArtifactTier, number> = { hot: 0, warm: 1, cold: 2 };
+const TIER_REMOVAL_ORDER: Record<ContextArtifactTier, number> = { cold: 0, warm: 1, hot: 2 };
+
+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 classifyBaseTier(input: ContextArtifactInput, tags: string[]): ContextArtifactTier {
+  if (input.tier) return input.tier;
+  const normalizedTags = tags.map((tag) => tag.toLowerCase());
+  if (normalizedTags.includes("hot")) return "hot";
+  if (normalizedTags.includes("warm")) return "warm";
+  if (normalizedTags.includes("cold")) return "cold";
+  if (normalizedTags.some((tag) => tag === "error" || tag === "failed" || tag === "failure")) return "hot";
+  if (normalizedTags.some((tag) => tag === "archive" || tag === "historical" || tag === "completed")) return "cold";
+  if (input.kind === "advisor_brief" || input.kind === "memory_note") return "hot";
+  return "warm";
+}
+
+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.tier && artifact.tier !== query.tier) 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;
+}
+
+function tierLine(artifact: ContextArtifact): string {
+  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} tier=${artifact.tier} kind=${artifact.kind}${pin}${path}${tags} summary="${artifact.summary}"`;
+}
+
+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 tierTtlMs: Record<ContextArtifactTier, number> = {
+    hot: Math.max(0, Math.floor(options.hotTtlMs ?? defaultTtlMs)),
+    warm: Math.max(0, Math.floor(options.warmTtlMs ?? defaultTtlMs)),
+    cold: Math.max(0, Math.floor(options.coldTtlMs ?? defaultTtlMs)),
+  };
+  const tierMaxRecords: Record<ContextArtifactTier, number> = {
+    hot: Math.max(1, Math.floor(options.hotMaxRecords ?? maxRecords)),
+    warm: Math.max(1, Math.floor(options.warmMaxRecords ?? maxRecords)),
+    cold: Math.max(1, Math.floor(options.coldMaxRecords ?? maxRecords)),
+  };
+  const tierMaxBytes: Record<ContextArtifactTier, number> = {
+    hot: Math.max(1, Math.floor(options.hotMaxBytes ?? maxBytes)),
+    warm: Math.max(1, Math.floor(options.warmMaxBytes ?? maxBytes)),
+    cold: Math.max(1, Math.floor(options.coldMaxBytes ?? maxBytes)),
+  };
+  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; baseTier: ContextArtifactTier }> = [];
+  let sequence = 0;
+
+  function currentStatus(): ContextBrokerStatus {
+    const bytes = artifacts.reduce((sum, artifact) => sum + artifact.bytes, 0);
+    const pinned = artifacts.filter((artifact) => artifact.pinned);
+    const byTier = (tier: ContextArtifactTier) => artifacts.filter((artifact) => artifact.tier === tier);
+    const hot = byTier("hot");
+    const warm = byTier("warm");
+    const cold = byTier("cold");
+    return {
+      records: artifacts.length,
+      bytes,
+      pinnedRecords: pinned.length,
+      pinnedBytes: pinned.reduce((sum, artifact) => sum + artifact.bytes, 0),
+      hotRecords: hot.length,
+      hotBytes: hot.reduce((sum, artifact) => sum + artifact.bytes, 0),
+      warmRecords: warm.length,
+      warmBytes: warm.reduce((sum, artifact) => sum + artifact.bytes, 0),
+      coldRecords: cold.length,
+      coldBytes: cold.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 removalCandidates(sessionId: string, protectedIds: Set<string>, tier?: ContextArtifactTier): Array<{ artifact: ContextArtifact & { sequence: number; baseTier: ContextArtifactTier }; index: number }> {
+    return artifacts
+      .map((artifact, index) => ({ artifact, index }))
+      .filter(({ artifact }) => artifact.sessionId === sessionId && !artifact.pinned && !protectedIds.has(artifact.id) && (!tier || artifact.tier === tier))
+      .sort((a, b) => {
+        if (!tier && TIER_REMOVAL_ORDER[a.artifact.tier] !== TIER_REMOVAL_ORDER[b.artifact.tier]) {
+          return TIER_REMOVAL_ORDER[a.artifact.tier] - TIER_REMOVAL_ORDER[b.artifact.tier];
+        }
+        if (a.artifact.createdAt !== b.artifact.createdAt) return a.artifact.createdAt - b.artifact.createdAt;
+        return a.artifact.sequence - b.artifact.sequence;
+      });
+  }
+
+  function withinCaps(sessionId: string, tier?: ContextArtifactTier): boolean {
+    const sessionArtifacts = artifacts.filter((artifact) => artifact.sessionId === sessionId && (!tier || artifact.tier === tier));
+    const recordsCap = tier ? tierMaxRecords[tier] : maxRecords;
+    const bytesCap = tier ? tierMaxBytes[tier] : maxBytes;
+    return sessionArtifacts.length <= recordsCap && sessionArtifacts.reduce((sum, artifact) => sum + artifact.bytes, 0) <= bytesCap;
+  }
+
+  function prune(now = Date.now(), protectedIds = new Set<string>()): ContextBrokerStatus {
+    dropExpired(now, protectedIds);
+
+    for (const sessionId of new Set(artifacts.map((artifact) => artifact.sessionId))) {
+      for (const tier of ["cold", "warm", "hot"] as ContextArtifactTier[]) {
+        while (!withinCaps(sessionId, tier)) {
+          const candidate = removalCandidates(sessionId, protectedIds, tier)[0];
+          if (!candidate) break;
+          artifacts.splice(candidate.index, 1);
+        }
+      }
+
+      while (!withinCaps(sessionId)) {
+        const candidate = removalCandidates(sessionId, protectedIds)[0];
+        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 tags = normalizeList(input.tags);
+    const baseTier = classifyBaseTier(input, tags);
+    const tier: ContextArtifactTier = input.pinned ? "hot" : baseTier;
+    const handle = `ctx://session/${session}/${kind}/${sha256.slice(0, 16)}/${id}`;
+    const ttlMs = input.ttlMs ?? tierTtlMs[tier];
+
+    const artifact: ContextArtifact & { sequence: number; baseTier: ContextArtifactTier } = {
+      id,
+      handle,
+      sessionId: input.sessionId,
+      kind,
+      createdAt: now,
+      updatedAt: now,
+      bytes,
+      sha256,
+      payload,
+      summary: summarizeArtifact(input.summary, kind, bytes, sha256, summaryBytes),
+      tags,
+      paths: normalizeList(input.paths),
+      command: input.command?.trim() || undefined,
+      branch: input.branch?.trim() || undefined,
+      tier,
+      expiresAt: ttlMs > 0 ? now + ttlMs : undefined,
+      pinned: Boolean(input.pinned),
+      parentIds: normalizeList(input.parentIds),
+      sequence: artifactSequence,
+      baseTier,
+    };
+
+    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)
+        || TIER_ORDER[a.tier] - TIER_ORDER[b.tier]
+        || 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.tier = pinned ? "hot" : artifact.baseTier;
+    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 explicitCold = query.tier === "cold" || Boolean(query.handle || query.id);
+    const baseQuery = { ...query };
+    delete (baseQuery as { budgetBytes?: number }).budgetBytes;
+    const candidates = lookup({ ...baseQuery, limit: query.limit ?? 32 })
+      .filter((artifact) => explicitCold || artifact.tier !== "cold");
+    const hot = candidates.filter((artifact) => artifact.tier === "hot");
+    const warm = candidates.filter((artifact) => artifact.tier === "warm");
+    const cold = candidates.filter((artifact) => artifact.tier === "cold");
+    const lines = [
+      "## Context Broker",
+      `Budget: ${budget} bytes`,
+      hot.length ? "Hot:" : "",
+      ...hot.map(tierLine),
+      warm.length ? "Warm:" : "",
+      ...warm.map(tierLine),
+      cold.length ? "Cold:" : "",
+      ...cold.map(tierLine),
+      "Lookup: use broker lookup by handle/path/tag/kind/session before replaying raw payloads.",
+    ].filter(Boolean);
+
+    return truncateUtf8(lines.join("\n"), budget);
+  }
+
+  return {
+    publish,
+    lookup,
+    pin,
+    prune,
+    status,
+    renderBrief,
+  };
+}

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

@@ -0,0 +1,78 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { createSqliteContextBroker } from "./sqlite.js";
+
+describe("createSqliteContextBroker", () => {
+  it("persists handles, payloads, tiers, and pin state without replay reconstruction", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ctx-sqlite-test-"));
+    try {
+      const path = join(dir, "artifacts.sqlite");
+      let broker = createSqliteContextBroker({ path, defaultTtlMs: 0, briefBytes: 800 });
+      const warm = broker.publish({ sessionId: "s", kind: "tool_output", payload: "needle payload", summary: "warm summary", createdAt: Date.now() });
+      const cold = broker.publish({ sessionId: "s", kind: "subagent_result", payload: "archived payload", summary: "cold archive", tier: "cold", createdAt: Date.now() + 1 });
+      expect(broker.pin(cold.handle, true)?.tier).toBe("hot");
+
+      broker = createSqliteContextBroker({ path, defaultTtlMs: 0, briefBytes: 800 });
+
+      expect(broker.lookup({ handle: warm.handle })[0]?.payload).toBe("needle payload");
+      const reloadedCold = broker.lookup({ handle: cold.handle })[0];
+      expect(reloadedCold?.pinned).toBe(true);
+      expect(reloadedCold?.tier).toBe("hot");
+      expect(broker.renderBrief({ sessionId: "s" })).toContain(cold.handle);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("uses SQLite FTS for text lookup and enforces tier caps", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ctx-sqlite-test-"));
+    try {
+      const broker = createSqliteContextBroker({ path: join(dir, "artifacts.sqlite"), defaultTtlMs: 0, coldMaxRecords: 1 });
+      const firstCold = broker.publish({ sessionId: "s", kind: "tool_output", payload: "alpha archive", tier: "cold", createdAt: Date.now() });
+      const secondCold = broker.publish({ sessionId: "s", kind: "tool_output", payload: "needle beta archive", tier: "cold", createdAt: Date.now() + 1 });
+
+      expect(broker.lookup({ id: firstCold.id })).toEqual([]);
+      expect(broker.lookup({ text: "needle" })[0]?.handle).toBe(secondCold.handle);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("dedupes replayed source artifacts so durable handles survive caps", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ctx-sqlite-test-"));
+    try {
+      const path = join(dir, "artifacts.sqlite");
+      let broker = createSqliteContextBroker({ path, defaultTtlMs: 0, maxRecords: 1 });
+      const original = broker.publish({ sessionId: "s", kind: "tool_output", payload: "same replayed payload", parentIds: ["tool-call-1"], createdAt: Date.now() });
+
+      broker = createSqliteContextBroker({ path, defaultTtlMs: 0, maxRecords: 1 });
+      const replayed = broker.publish({ sessionId: "s", kind: "tool_output", payload: "same replayed payload", parentIds: ["tool-call-1"], createdAt: Date.now() + 1 });
+
+      expect(replayed.handle).toBe(original.handle);
+      expect(broker.lookup({ handle: original.handle })[0]?.payload).toBe("same replayed payload");
+      expect(broker.status().records).toBe(1);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("republishes expired replayed sources instead of returning dead handles", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ctx-sqlite-test-"));
+    try {
+      const path = join(dir, "artifacts.sqlite");
+      let broker = createSqliteContextBroker({ path, defaultTtlMs: 1 });
+      const expired = broker.publish({ sessionId: "s", kind: "tool_output", payload: "expired payload", parentIds: ["tool-call-1"], createdAt: 1 });
+      expect(broker.lookup({ handle: expired.handle })).toEqual([]);
+
+      broker = createSqliteContextBroker({ path, defaultTtlMs: 1 });
+      const replayed = broker.publish({ sessionId: "s", kind: "tool_output", payload: "fresh replayed payload", parentIds: ["tool-call-1"], createdAt: 1, ttlMs: Date.now() + 60_000 });
+
+      expect(replayed.handle).not.toBe(expired.handle);
+      expect(broker.lookup({ handle: replayed.handle })[0]?.payload).toBe("fresh replayed payload");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});