@rol1n/pi-kit 0.1.0 → 0.1.2

package/continue-signal/README.md

@@ -0,0 +1,20 @@
+# continue-signal
+
+Resume an idle Pi agent with a visible continuation signal.
+
+## Install
+
+```sh
+pi install npm:@rol1n/continue-signal
+```
+
+Also included in `@rol1n/pi-kit`.
+
+## Commands and shortcuts
+
+| Action | Trigger |
+|---|---|
+| Resume unfinished work | `/continue` or `Alt+C` |
+| Resume with custom instruction | `/continue Review the remaining test failures` |
+
+An explicit command argument takes priority; otherwise the current editor draft is consumed, falling back to a default resume prompt.

package/{extensions/continue-signal → continue-signal}/index.ts

@@ -3,13 +3,31 @@
  * Uses the editor draft when no prompt is supplied.
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Key } from "@earendil-works/pi-tui";
-import { renderContinueSignal } from "./renderer.ts";
+import type { ExtensionAPI, ExtensionContext, MessageRenderer } from "@earendil-works/pi-coding-agent";
+import { Box, Key, Text } from "@earendil-works/pi-tui";
 
 const DEFAULT_PROMPT = "Review the conversation context and resume any unfinished work from where it stopped.";
 const CUSTOM_TYPE = "continue-signal";
 
+const renderContinueSignal: MessageRenderer<{ timestamp?: number }> = (
+  message,
+  { expanded, outputPad },
+  theme,
+) => {
+  const time = new Date(message.details?.timestamp ?? Date.now()).toLocaleTimeString();
+  const title = `${theme.bold(theme.fg("accent", "⚡ LOOP RESUME SIGNAL"))} ${theme.fg("muted", `[${time}]` )}`;
+
+  const box = new Box(outputPad, 1, (text) => theme.bg("customMessageBg", text));
+  box.addChild(new Text(title, 0, 0));
+  box.addChild(new Text(theme.fg("text", "Re-linking conversation context & resuming agent loop..."), 0, 0));
+
+  if (expanded && message.content) {
+    box.addChild(new Text(theme.fg("dim", `Prompt: ${message.content}`), 0, 0));
+  }
+
+  return box;
+};
+
 export default function (pi: ExtensionAPI) {
   pi.registerMessageRenderer(CUSTOM_TYPE, renderContinueSignal);
 

package/custom-providers/README.md

@@ -0,0 +1,20 @@
+# custom-providers
+
+Registers additional model providers through Pi's native model registry and `/login` interface.
+
+## Install
+
+```sh
+pi install npm:@rol1n/custom-providers
+```
+
+Also included in `@rol1n/pi-kit`.
+
+## Providers
+
+| Provider | Configuration |
+|---|---|
+| Magpie | `MAGPIE_BASE_URL` (default `http://127.0.0.1:3425/v1`); authenticate via `MAGPIE_GATEWAY_KEY` or `/login magpie` |
+| SHUAI API | Authenticate via `/login shuaiapi` |
+| BigModel | Authenticate via `/login bigmodel` |
+| DashScope | Authenticate via `/login dashscope`; `DASHSCOPE_IMAGE_URL` overrides the image API base URL |

package/{extensions/custom-providers → custom-providers}/index.ts

@@ -10,9 +10,19 @@ import { imageProviders } from "./image/index.ts";
 import { classifierProviders } from "./classifier/index.ts";
 import { asrProviders } from "./asr/index.ts";
 
-export { asrProviders, ALL_ASR_MODELS } from "./asr/index.ts";
+export { asrProviders, ALL_ASR_MODELS, createAsrProvider, type AsrModelDefinition, type StreamingAsrProvider } from "./asr/index.ts";
+export { imageProviders, fetchAllAvailableImageModels, generateImage, resolveImageModel, type ImageModelDefinition } from "./image/index.ts";
+
+const BATCH_LOCK_KEY = "__piCustomProvidersBatchLock";
+
+export function ensureCustomProviders(pi: ExtensionAPI): void {
+  const g = globalThis as Record<string, unknown>;
+  if (g[BATCH_LOCK_KEY]) return;
+  g[BATCH_LOCK_KEY] = true;
+  setTimeout(() => {
+    g[BATCH_LOCK_KEY] = false;
+  }, 0).unref?.();
 
-export default function customProviders(pi: ExtensionAPI): void {
   const providerIds = new Set<string>([
     ...Object.keys(chatProviders),
     ...Object.keys(imageProviders),
@@ -48,3 +58,7 @@ export default function customProviders(pi: ExtensionAPI): void {
     pi.registerProvider(id, config);
   }
 }
+
+export default function customProviders(pi: ExtensionAPI): void {
+  ensureCustomProviders(pi);
+}

package/image-generate/README.md

@@ -0,0 +1,25 @@
+# image-generate
+
+Generate images through OpenRouter or DashScope and save them to `.pi/generated-images/` in the current project. Registers the `image_generate` tool and `/image-generate` model selector.
+
+## Install
+
+```sh
+pi install npm:@rol1n/image-generate
+```
+
+Also included in `@rol1n/pi-kit`. Installing this package automatically installs `@rol1n/custom-providers`.
+
+## Use
+
+Run `/image-generate model` to open the interactive model picker, or `/image-generate model qwen-image-3.0-pro` to switch directly.
+
+```json
+{
+  "prompt": "A clean technical diagram of a terminal workflow",
+  "aspectRatio": "16:9",
+  "model": "google/gemini-3.1-flash-image"
+}
+```
+
+Authenticate via `/login openrouter` or `/login dashscope` (or `OPENROUTER_API_KEY` / `DASHSCOPE_API_KEY`).

package/{extensions/image-generate → image-generate}/index.ts

@@ -12,13 +12,32 @@ import { Text, type AutocompleteItem } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 import {
+  ensureCustomProviders,
   fetchAllAvailableImageModels,
   generateImage,
   resolveImageModel,
   type ImageModelDefinition,
-} from "../custom-providers/image/index.ts";
+} from "../custom-providers/index.ts";
 import { saveImageAtomically } from "./files.ts";
-import { DEFAULT_MODEL, registryImageModels, resolveProviderId } from "./models.ts";
+/** Image catalog lookup and provider selection. */
+
+export const DEFAULT_MODEL = "google/gemini-3.1-flash-image";
+
+/** Image models known to Pi: OpenRouter's built-in catalog plus our DashScope registration. */
+export function registryImageModels(ctx: { modelRegistry: { getModelsOfType(type: string): readonly any[] } }) {
+  return ctx.modelRegistry.getModelsOfType("image") as readonly { id: string; name?: string; provider: string }[];
+}
+
+/** Resolve which provider owns a model id, preferring the Pi registry over heuristics. */
+export function resolveProviderId(
+  ctx: { modelRegistry: { getModelsOfType(type: string): readonly any[] } },
+  modelId: string,
+): string {
+  const lower = modelId.toLowerCase();
+  const known = registryImageModels(ctx).find((m) => m.id.toLowerCase() === lower);
+  if (known) return known.provider;
+  return lower.startsWith("qwen-image") ? "dashscope" : "openrouter";
+}
 import { SearchableImageModelSelectorComponent } from "./model-selector.ts";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -28,6 +47,7 @@ let currentModel = DEFAULT_MODEL;
 // ============================ Extension Entrypoint ============================
 
 export default function imageGenerate(pi: ExtensionAPI): void {
+  ensureCustomProviders(pi);
   // 1. Slash command: /image-generate model [name]
   pi.registerCommand("image-generate", {
     description: "Switch default image generation model (/image-generate model [name])",

package/{extensions/image-generate → image-generate}/model-selector.ts

@@ -1,5 +1,5 @@
 import { Container, Input, Spacer, Text, fuzzyFilter, getKeybindings } from "@earendil-works/pi-tui";
-import type { ImageModelDefinition } from "../custom-providers/image/index.ts";
+import type { ImageModelDefinition } from "../custom-providers/index.ts";
 
 export class SearchableImageModelSelectorComponent extends Container {
   private searchInput: Input;

package/memory-log/README.md

@@ -0,0 +1,121 @@
+# memory-log
+
+> Tiered asynchronous observational memory for long-running Pi sessions.
+
+`memory-log` keeps multi-day coding sessions coherent across compactions without blocking your workflow. Based on the observational memory paradigm from [elpapi42/pi-observational-memory](https://github.com/elpapi42/pi-observational-memory), it moves memory distillation into background subprocesses while you work, making compaction a model-free rendering step when sufficient observations are available. If a safe cutoff or usable memory summary is unavailable, Pi's native summarizer takes over instead.
+
+## Install
+
+```sh
+pi install npm:@rol1n/memory-log
+```
+
+Also included in `@rol1n/pi-kit`. The extension loads with new-session memory disabled by default (`/mem-log on` to enable for the current session, or `"defaultEnabled": true` in settings).
+
+---
+
+## Why it exists
+
+Long AI coding sessions typically hit two walls:
+
+1. **The Compression Wall (Summary of a Summary)**: Traditional compaction summarizes the conversation when the context window fills up. Over multiple cycles, the agent carries a compressed summary of a previous summary, gradually losing concrete architectural rationale, rejected approaches, and subtle constraints.
+2. **Compaction Stalls**: Waiting for a model to rewrite a massive transcript right when the context window overflows interrupts flow.
+
+`memory-log` solves both by doing the heavy lifting **asynchronously in the background** as the session progresses:
+
+- **Background Observers**: Whenever raw conversation history accumulates a full chunk (`chunkTokens`), a background Pi worker distills that chunk into timestamped, priority-tagged (`🔴` / `🟡` / `🟢`) atomic observations stored in the session branch ledger.
+- **Consolidator & Durable Topic Files**: When the active observation pool reaches `consolidateAtPoolTokens`, a background consolidator archives older observations into durable Markdown topic files under `.memory/<sessionId>/` (`INDEX.md`, `<topic>.md`) and appends project milestones to `.memory/<sessionId>/JOURNEY.md`, draining the active pool back toward `poolTargetTokens`.
+- **Safe Deterministic Compaction**: After `agent_settled` (all retries and queued continuations have finished), context pressure can trigger compaction. The cutoff snaps to a completed observation boundary near `tailTokens`, never crossing an unobserved gap in newly recorded chunks or splitting a tool call from its results. The entire unobserved tail stays verbatim, even if larger than the target. The summary is rendered from `JOURNEY.md` + the **Memory Map** + active observations, without an LLM call. Missing boundaries or empty memory delegate to Pi's native summarizer, which may make an LLM call.
+- **Source Recall**: `memory_recall` retrieves the original conversation chunk behind an observation by timestamp, including history hidden by compaction and observations archived to topic files.
+- **TUI Observability**: Displays live footer gauges (`Next` chunk progress, `Pool` capacity, `Ctx` window usage), active worker spinners, and session memory cost.
+
+---
+
+## Commands
+
+| Command | Action |
+|---|---|
+| `/mem-log` | Enable memory log (if off) or display status & timeline (if on) |
+| `/mem-log on` / `/mem-log off` | Enable or disable observational memory for the current session |
+| `/mem-log status` or `/mem-log:status` | View gauges, worker states, cost summary, and observation timeline |
+| `/mem-log compact` or `/mem-log:compact` | Request immediate compaction (native summarization if no safe memory cutoff exists) |
+| `/mem-log consolidate` or `/mem-log:consolidate` | Consolidate the active observation pool into durable topic files immediately |
+
+---
+
+## Source recall
+
+The agent can call `memory_recall` with an observation's full timestamp-id (including a `.NN` suffix, if present), or an unambiguous prefix:
+
+```json
+{ "timestamp": "2026-10-23T14:30:00" }
+```
+
+- New observations persist exact `sourceEntryIds`; provenance covers the **whole chunk**, not a per-fact citation.
+- Older records remain readable: ranges are inferred from coverage anchors in source order, not worker completion order. Inferred ranges are explicitly labeled and may include extra conversation; old records cannot prove gaps caused by failed workers. Legacy compaction coverage retains its existing watermark interpretation.
+- Recall searches only the **current branch**. Missing sources are reported as unavailable or partial, never borrowed from another branch. Archived observations remain traceable in the ledger.
+- Output is paged at 12,000 source characters. Use the returned `nextOffset` as `offset` to continue; `limit` can request a smaller page. Images/non-text blocks use placeholders.
+- Recall is read-only and remains available when background memory processing is disabled.
+
+Automatic compaction requires a Pi version that exposes `agent_settled`. Aborted runs do not trigger it; there is no retry-error guessing or idle polling. Pi's own compaction mechanism remains independent.
+
+---
+
+## Configuration
+
+Add a `memoryLog` section to `~/.pi/agent/settings.json` (global) or `.pi/settings.json` (project-level override):
+
+```json
+{
+  "memoryLog": {
+    "defaultEnabled": false,
+    "chunkTokens": 10000,
+    "poolTargetTokens": 10000,
+    "consolidateAtPoolTokens": 15000,
+    "compactAtContextTokens": 150000,
+    "tailTokens": 20000,
+    "journeyTargetTokens": 1000,
+    "observerConcurrency": 4,
+    "passive": false,
+    "debugLog": false,
+    "models": {
+      "observer": { "thinking": "low" },
+      "consolidator": { "thinking": "medium" }
+    }
+  }
+}
+```
+
+`resumeAfterMidRunCompaction` is retained for configuration compatibility but has no effect: this extension's automatic trigger now runs only after settlement and never starts a synthetic continuation.
+
+### Model resolution
+
+`models.observer` and `models.consolidator` accept `{ "provider": "...", "id": "...", "thinking": "off|minimal|low|medium|high|xhigh" }`.
+Resolution priority: **explicit `memoryLog.models` -> current session model -> Pi default model (`defaultProvider` / `defaultModel`)**.
+
+### Environment overrides
+
+| Variable | Purpose |
+|---|---|
+| `PI_OM_PASSIVE=1` | Disable automatic observer/consolidator/compaction triggers while keeping manual commands |
+| `PI_OM_OBSERVER_PROVIDER` / `PI_OM_OBSERVER_MODEL` / `PI_OM_OBSERVER_THINKING` | Override observer worker model |
+| `PI_OM_CONSOLIDATOR_PROVIDER` / `PI_OM_CONSOLIDATOR_MODEL` / `PI_OM_CONSOLIDATOR_THINKING` | Override consolidator worker model |
+
+---
+
+## Storage layout
+
+```text
+<project-root>/.memory/<session-id>/
+├── INDEX.md          # Orchestrator-rendered index of durable topics (injected as the Memory Map)
+├── JOURNEY.md        # Chronological project history maintained by the consolidator
+└── <topic-slug>.md   # Durable topic notes read on demand by the agent
+```
+
+Short-term observations and enable/disable gates are stored directly in the Pi session JSONL ledger so they branch and fork naturally with your session tree.
+
+---
+
+## Credits
+
+Adapted from and inspired by [elpapi42/pi-observational-memory](https://github.com/elpapi42/pi-observational-memory) (MIT License), extended with file-backed durable topic consolidation (`.memory/<sessionId>/`), `JOURNEY.md` tracking, and TUI progress gauges.

package/{extensions/memory-log → memory-log}/config.ts

@@ -42,7 +42,7 @@ export interface Config {
    * used as the last-resort fallback when no session model is available.
    */
   settingsDefaultModel?: { provider?: string; id?: string };
-  /** Resume the agent automatically after a mid-run compaction. */
+  /** @deprecated Compatibility only; automatic compaction now runs after agent_settled. */
   resumeAfterMidRunCompaction: boolean;
   /** Power-user setting: disable all triggers (distinct from the on/off gate). */
   passive: boolean;

package/{extensions/memory-log → memory-log}/hooks/compaction-hook.ts

@@ -14,16 +14,50 @@ import {
   type Entry,
 } from "../ledger/index.ts";
 
-/** Distinct, branch-resolved coversUpToId indices of committed observation chunks, ascending. */
+/**
+ * Completed boundaries behind the contiguous observation frontier. A later worker
+ * finishing first must not authorize discarding an earlier failed/in-flight chunk.
+ * Legacy records only have a cumulative watermark; retain that older contract.
+ */
 function chunkBoundaryIndices(branch: Entry[]): number[] {
   const indexes = entryIndexById(branch);
-  const set = new Set<number>();
-  for (const entry of branch) {
+  const boundaries = new Set<number>();
+  const coveredAt = new Map<string, number>();
+  let legacyFrontier = -1;
+  for (let i = 0; i < branch.length; i++) {
+    const entry = branch[i];
     if (!isObservationsRecordedEntry(entry)) continue;
     const idx = indexes.get(entry.data.coversUpToId);
-    if (idx !== undefined) set.add(idx);
+    if (idx === undefined || idx >= i || !isSourceEntry(branch[idx])) continue;
+    if (entry.data.sourceEntryIds === undefined) {
+      legacyFrontier = Math.max(legacyFrontier, idx);
+    } else {
+      const ids = entry.data.sourceEntryIds;
+      // Reject unresolved, out-of-order, or non-source anchors.
+      let previous = -1;
+      const valid = ids.length > 0 && ids.at(-1) === entry.data.coversUpToId && ids.every((id) => {
+        const index = indexes.get(id);
+        if (index === undefined || index <= previous || index > idx || !isSourceEntry(branch[index])) return false;
+        previous = index;
+        return true;
+      });
+      if (!valid) continue;
+      for (const id of ids) coveredAt.set(id, Math.min(coveredAt.get(id) ?? Infinity, idx));
+    }
+    boundaries.add(idx);
+  }
+  const safeBoundaries: number[] = [];
+  let requiredCoverageEnd = -1;
+  for (let i = 0; i < branch.length; i++) {
+    if (isSourceEntry(branch[i])) {
+      const coveredEnd = i <= legacyFrontier ? i : (coveredAt.get(branch[i].id) ?? Infinity);
+      requiredCoverageEnd = Math.max(requiredCoverageEnd, coveredEnd);
+    }
+    // The projection must include the records that authorize this cut, not just
+    // records for overlapping chunks whose watermarks lie beyond it.
+    if (boundaries.has(i) && requiredCoverageEnd <= i) safeBoundaries.push(i);
   }
-  return Array.from(set).sort((a, b) => a - b);
+  return safeBoundaries;
 }
 
 /** First source entry after `boundaryIndex` that is a valid cut point, or undefined. */
@@ -37,9 +71,9 @@ function firstKeptAfterBoundary(branch: Entry[], boundaryIndex: number): Entry |
 
 export function snapCutoff(
   branch: Entry[],
-  proposedFirstKeptId: string,
+  _proposedFirstKeptId: string,
   tailTokens: number,
-): { firstKeptId: string; tail: number | undefined } {
+): { firstKeptId: string | undefined; tail: number | undefined } {
   const indexes = entryIndexById(branch);
   const lastCompactionIdx = findLastCompactionIndex(branch);
   const boundaries = chunkBoundaryIndices(branch);
@@ -80,26 +114,21 @@ export function snapCutoff(
     }
   }
 
-  if (!finalFirstKeptId) {
-    finalFirstKeptId = proposedFirstKeptId;
-    finalTail = undefined;
-  }
-
   return { firstKeptId: finalFirstKeptId, tail: finalTail };
 }
 
-export function snapFirstKeptEntryId(branch: Entry[], proposedFirstKeptId: string, tailTokens: number): string {
+export function snapFirstKeptEntryId(branch: Entry[], proposedFirstKeptId: string, tailTokens: number): string | undefined {
   return snapCutoff(branch, proposedFirstKeptId, tailTokens).firstKeptId;
 }
 
 export function canSkipObserverWait(
   branch: Entry[],
-  snappedFirstKeptId: string,
+  snappedFirstKeptId: string | undefined,
   snappedTail: number | undefined,
   tailTokens: number,
   observersInFlight: Iterable<{ coversUpToId: string }>,
 ): boolean {
-  if (snappedTail === undefined || snappedTail > tailTokens) return false;
+  if (!snappedFirstKeptId || snappedTail === undefined || snappedTail > tailTokens) return false;
 
   const indexes = entryIndexById(branch);
   const cutoffIndex = indexes.get(snappedFirstKeptId);
@@ -115,6 +144,7 @@ export function canSkipObserverWait(
 export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void {
   pi.on("session_before_compact", async (event: any, ctx: any) => {
     if (!runtime.enabled || runtime.config.passive) return undefined;
+    if (event.signal?.aborted) return { cancel: true };
 
     const hasUI = ctx.hasUI;
     if (runtime.compactHookInFlight) {
@@ -140,11 +170,24 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
         snap = snapCutoff(branch, firstKeptEntryId, tailTokens);
       }
 
+      if (event.signal?.aborted) return { cancel: true };
+      if (!runtime.enabled) return undefined;
+
+      // No proven observed cut: let Pi summarize the raw history, never stamp an
+      // empty deterministic summary over unobserved messages (including old tails).
       const snapped = snap.firstKeptId;
+      if (!snapped || snap.tail === undefined) {
+        if (hasUI) ctx.ui.notify("memory-log: no safe observed cutoff — using Pi's native summarizer", "info");
+        return undefined;
+      }
       const projection = buildCompactionProjection(branch, snapped);
       const journey = readJourney(runtime.memoryRoot);
       const map = renderMemoryMap(listTopics(runtime.memoryRoot));
       const summary = renderSummary(journey, map, projection.observations);
+      if (!summary.trim()) {
+        if (hasUI) ctx.ui.notify("memory-log: memory summary is empty — using Pi's native summarizer", "info");
+        return undefined;
+      }
 
       return {
         compaction: {

package/memory-log/hooks/compaction-trigger.ts

@@ -0,0 +1,87 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  findLastCompactionIndex,
+  rawTokensAfterIndex,
+  rawTokensSinceLastCompaction,
+  type Entry,
+} from "../ledger/index.ts";
+import type { Runtime } from "../runtime.ts";
+
+export function contextPressureTokens(
+  ctx: { getContextUsage?: () => { tokens: number | null } | undefined; sessionManager: { getBranch: () => Entry[] } },
+  threshold: number,
+): { tokens: number; due: boolean } {
+  const branch = ctx.sessionManager.getBranch();
+  if (branch.length === 0) return { tokens: 0, due: false };
+
+  // If the last entry on the branch is already a compaction, context was just compacted on this branch.
+  const lastEntry = branch[branch.length - 1];
+  if (lastEntry.type === "compaction") {
+    return { tokens: 0, due: false };
+  }
+
+  const lastCompactionIdx = findLastCompactionIndex(branch);
+  if (lastCompactionIdx !== -1) {
+    // If no new source entries exist after compaction, context has not grown since compaction.
+    const tokensSinceCompaction = rawTokensAfterIndex(branch, lastCompactionIdx);
+    if (tokensSinceCompaction === 0) {
+      return { tokens: 0, due: false };
+    }
+
+    // Check if any assistant message has responded after the compaction.
+    // In Pi, getContextUsage() returns tokens: null until an assistant message responds post-compaction.
+    let hasAssistantAfterCompaction = false;
+    for (let i = branch.length - 1; i > lastCompactionIdx; i--) {
+      const entry = branch[i];
+      if (entry.type === "message" && (entry.message as any)?.role === "assistant") {
+        hasAssistantAfterCompaction = true;
+        break;
+      }
+    }
+    if (!hasAssistantAfterCompaction) {
+      return { tokens: 0, due: false };
+    }
+  }
+
+  const live = ctx.getContextUsage?.()?.tokens;
+  if (live != null) {
+    return { tokens: live, due: live >= threshold };
+  }
+
+  const raw = rawTokensSinceLastCompaction(branch);
+  return { tokens: raw, due: raw >= threshold };
+}
+
+/**
+ * agent_end is not idle: Pi may still retry or drain queued work. agent_settled
+ * is the final boundary, so no retry guessing, timers, or idle polling is needed.
+ */
+export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): void {
+  pi.on("agent_settled", (event, ctx) => {
+    if (event.aborted || !runtime.enabled || runtime.config.passive) return;
+    if (runtime.compactInFlight || runtime.compactHookInFlight) return;
+    // Another handler may already have started work at this notification boundary.
+    if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
+    if (!contextPressureTokens(ctx, runtime.config.compactAtContextTokens).due) return;
+
+    runtime.compactInFlight = true;
+    try {
+      if (ctx.hasUI) ctx.ui.notify("memory-log: context threshold reached — compacting (waiting for pending observers if needed)...", "info");
+      // compact() is callback-based. Do not await session idle from this handler.
+      ctx.compact({
+        onComplete: () => {
+          runtime.compactInFlight = false;
+          if (ctx.hasUI) ctx.ui.notify("memory-log: compaction completed", "info");
+        },
+        onError: (error) => {
+          runtime.compactInFlight = false;
+          if (error.message !== "Compaction cancelled" && ctx.hasUI) ctx.ui.notify(`memory-log: ${error.message}`, "error");
+        },
+      });
+    } catch (error) {
+      runtime.compactInFlight = false;
+      const message = error instanceof Error ? error.message : String(error);
+      if (ctx.hasUI) ctx.ui.notify(`memory-log: compaction trigger failed — ${message}`, "error");
+    }
+  });
+}

package/{extensions/memory-log → memory-log}/hooks/observer-trigger.ts

@@ -102,6 +102,7 @@ async function dispatchObserver(
   runtime.observersInFlight.set(runId, { controller, coversUpToId });
 
   const { text: chunkText } = serializeSourceAddressedBranchEntries(slice.entries);
+  const sourceEntryIds = slice.entries.map((entry) => entry.id);
   const lastEntry = slice.entries.at(-1);
 
   runtime.status.workerStart("observer", runId);
@@ -148,7 +149,7 @@ async function dispatchObserver(
     });
 
     if (observations.length > 0) {
-      pi.appendEntry(OM_OBSERVATIONS_RECORDED, { observations, coversUpToId });
+      pi.appendEntry(OM_OBSERVATIONS_RECORDED, { observations, coversUpToId, sourceEntryIds });
     }
     runtime.status.workerDone(runId, observations.length);
     runtime.refreshFooterGauges(ctx.sessionManager.getBranch(), ctx.getContextUsage?.()?.tokens ?? null);

package/{extensions/memory-log → memory-log}/index.ts

@@ -20,6 +20,7 @@ import { registerObserverTrigger } from "./hooks/observer-trigger.ts";
 import { OM_ENABLED, type Entry } from "./ledger/index.ts";
 import { ensureSessionMemory } from "./memory/session.ts";
 import { Runtime } from "./runtime.ts";
+import { registerRecallTool } from "./tools/recall.ts";
 
 function readGateFromLedger(branch: Entry[], defaultEnabled: boolean): boolean {
   for (let i = branch.length - 1; i >= 0; i--) {
@@ -136,6 +137,9 @@ export default function observationalMemory(pi: ExtensionAPI): void {
     handler: commandHandler,
   });
 
+  // Read-only recall remains available when background memory processing is off.
+  registerRecallTool(pi);
+
   // Triggers + hooks
   registerObserverTrigger(pi, runtime);
   registerConsolidatorTrigger(pi, runtime);

package/{extensions/memory-log → memory-log}/ledger/index.ts

@@ -5,3 +5,4 @@ export * from "./projection.ts";
 export * from "./pool.ts";
 export * from "./render.ts";
 export * from "./serialize.ts";
+export * from "./recall.ts";