@nklisch/pi-enhanced 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## v0.4.3 — Prepared
+
+### Fixed
+
+- Bundle `@nklisch/pi-plugins` 0.8.3 and select `@nklisch/pi-mcp-adapter` 2.21.0-nklisch.3 so installed MCP calls retain structured facts in model-visible results.
+- Keep all other bundled workspace versions unchanged from 0.4.2.
+
 ## v0.4.1 — 2026-09-04
 
 ### Added

package/node_modules/@nklisch/pi-astral-pocket/README.md

@@ -1,62 +1,79 @@
 # @nklisch/pi-astral-pocket
 
-A persistent note pocket that activates only for `openai-codex/gpt-6-astra`
-sessions. Astra gets a dedicated, cross-session note store with recall —
-modeled on OpenAI Codex's memories system, minus the always-on cost.
-
-## What it does
-
-When the active model is astra (including mid-session `/model` switches), the
-extension:
-
-- **Injects pocket guidance** into the system prompt: when to consult the
-  pocket, a budgeted "quick pass" lookup protocol, drift/verification policy,
-  and note-taking judgment (durable facts only, never secrets).
-- **Activates two tools**:
-  - `pocket_note` — write a durable note (title, body, keywords). The store's
-    registry and summary are updated mechanically on every write.
-  - `pocket_recall` — keyword-search pocket notes and past **astra** sessions.
-    Summarized by default (tool names + truncated args/results); `full: true`
-    for larger excerpts.
-- **Runs a bounded distiller pass** on activation: astra sessions idle past a
-  threshold (default 6h, max 16 per pass, 30-day window) are distilled into
-  pocket notes by a cheap configurable model, then consolidated into the
-  injected summary's durable digest. There is no daemon; the pass only runs
-  when astra activates. If the distiller is disabled or its model is
-  unavailable, the mechanical floor (registry + recent-notes index) keeps
-  working.
-
-For any other model, the extension is inert: no tools, no injection, no
-distiller.
+Astral Pocket keeps durable Markdown notes across Pi sessions. It activates only
+when the current model is `openai-codex/gpt-6-astra`.
 
-## Commands
+Notes normally belong to the current Git repository. Subdirectories and linked
+worktrees share the same local repository identity. Explicit global notes can
+carry a general preference or a conditional lesson between repositories.
+Foreign repository memories are not injected into the current session.
 
-- `/pocket on` / `/pocket off` — enable/disable the pocket (persisted).
-- `/pocket status` — show enablement, activation, note count, distiller config.
+## Notes and digest
 
-## Storage
+The extension adds two tools while Astra is active:
 
-Everything lives in `~/.pi/agent/astral-pocket/` (or
-`$PI_CODING_AGENT_DIR/astral-pocket/`):
+- `pocket_note` saves a durable note. Its default scope is `project`. The caller
+  may set `scope: "global"` only for an intentionally portable preference or
+  observation.
+- `pocket_recall` searches current-project and global notes, plus past Astra
+  sessions from the current repository. `full: true` returns larger excerpts.
+  `scope: "all"` deliberately includes other repositories and labels their
+  results as cross-repository precedent. Recall returns at most 20 matches from
+  each selected source.
 
+Distillation means extracting durable decisions, constraints, preferences, and
+pitfalls from an idle session into a source-linked note. Automatic extraction
+always stays project-scoped. A digest is then rebuilt from the actual notes for
+the current repository. Explicit global notes have a separate, smaller digest.
+The extension never builds a new digest by recursively summarizing an old one.
+
+Memory is historical evidence, not an instruction source. The current user
+request and current repository guidance take priority. Verify remembered facts
+when their relevance or freshness is uncertain.
+
+## Commands
+
+```text
+/pocket status
+/pocket on
+/pocket off
+/pocket distiller on
+/pocket distiller off
+/pocket model openai-codex/gpt-6-astra
+/pocket model reset
+/pocket reasoning minimal
+/pocket reasoning off|minimal|low|medium|high|xhigh|max
+/pocket reasoning reset
+/pocket distill
+/pocket rebuild
 ```
-config.json     # enabled flag + distiller settings
-SUMMARY.md      # injected into astra's prompt; pinned block + durable digest + recent notes
-POCKET.md       # searchable registry, one line per note
-notes/          # append-only note files (<timestamp>-<slug>.md)
-distilled.json  # distiller bookkeeping
-```
 
-### Configuration
+`/pocket status` shows the requested and resolved model, requested and effective
+reasoning, whether distillation is enabled, and the last pass outcome. Pi may
+map a requested reasoning level to a model-supported effort; status reports that
+mapping.
+
+`/pocket distill` retries changed or previously failed session work and stale
+digests. `/pocket rebuild` also forces the current project and global digest
+caches to be regenerated. Both commands require an active Astra session and an
+enabled distiller.
 
-`config.json` (all optional, defaults shown):
+Changing the model or reasoning setting cancels the current pass before starting
+a replacement. Switching away from Astra, disabling the pocket, reloading, or
+shutting down cancels the session-owned pass.
+
+## Configuration
+
+Configuration lives in `config.json`. All fields are optional. These are the
+defaults:
 
 ```json
 {
   "enabled": true,
   "distiller": {
     "enabled": true,
-    "model": null,
+    "model": "openai-codex/gpt-6-astra",
+    "reasoning": "minimal",
     "minIdleHours": 6,
     "maxSessionsPerPass": 16,
     "maxSessionAgeDays": 30
@@ -64,19 +81,58 @@ distilled.json  # distiller bookkeeping
 }
 ```
 
-`distiller.model` is a `"provider/modelId"` override; when null the first
-resolvable entry of a cheap-model preference list is used. If no model
-resolves, the distiller skips with a notice.
+The model must use the exact `provider/modelId` form. Astral Pocket asks Pi's
+model registry for current authentication and headers on every request. It does
+not silently select another provider when that model is unavailable. A malformed
+configuration falls back to defaults without blocking note access.
+
+## Storage and recovery
 
-## Privacy note
+Files are stored under `~/.pi/agent/astral-pocket/`, or under
+`$PI_CODING_AGENT_DIR/astral-pocket/` when that variable is set:
 
-Pi session files record tool calls and results verbatim. `pocket_recall`
-searches only astra sessions and summarizes by default, but full excerpts can
-re-surface anything that appeared in past output. Keep the default summarized
-mode unless you need exact commands or error text.
+```text
+config.json       settings
+notes/            canonical Markdown notes
+digests/          rebuildable per-project and global digest caches
+POCKET.md         rebuildable note registry
+SUMMARY.md        legacy-compatible derived summary surface
+distilled.json    processed source revisions and digest fingerprints
+```
+
+Canonical note files remain readable if a model call fails or a derived registry
+or digest lags. Changed sessions replace their one stable generated note. If a
+fresh extraction returns `NONE`, that generated note is removed rather than
+leaving superseded knowledge behind. Legacy notes are not rewritten: notes with
+project metadata remain project-scoped, while notes with unknown scope appear
+only in an explicit all-project recall.
+
+There is no daemon or global worker. Work runs only on Astra activation or an
+explicit command. Pi's file mutation queue serializes writes inside one process,
+and files are atomically replaced to avoid torn output. Two simultaneous Pi
+processes can still duplicate model calls or publish competing derived snapshots;
+the extension does not claim cross-process locking. A later rebuild recovers the
+registry and digest from canonical notes.
+
+## Privacy
+
+Session files can contain prompts, tool arguments, and tool results. Distillation
+uses a bounded transcript that omits most tool output and instructs the model to
+exclude credentials, personal data, quoted instructions, rejected proposals,
+and facts already documented in the repository. A prompt cannot guarantee that
+every sensitive value is removed.
+
+Choosing a distiller model sends the bounded source material to that model's
+configured provider. Astral Pocket never falls back to a different provider.
+Use `pocket_recall` without `full` first; larger session excerpts can re-surface
+sensitive text from past work. Use all-project recall only when you intentionally
+want foreign repository precedent.
 
 ## Install
 
 ```sh
-pi install npm:@nklisch/pi-astral-pocket
+pi install npm:@nklisch/pi-enhanced
 ```
+
+Astral Pocket is currently distributed as part of Pi Enhanced rather than as a
+standalone npm package.

package/node_modules/@nklisch/pi-astral-pocket/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nklisch/pi-astral-pocket",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "Model-gated note pocket and session recall for gpt-6-astra",
   "type": "module",
@@ -40,10 +40,12 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
   "devDependencies": {
+    "@earendil-works/pi-ai": "0.82.0",
     "@earendil-works/pi-coding-agent": "*",
     "@types/node": "^24.0.0",
     "typescript": ">=7.0.0 <8",

package/node_modules/@nklisch/pi-astral-pocket/src/config.ts

@@ -1,21 +1,28 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
+
+export const DEFAULT_DISTILLER_MODEL = "openai-codex/gpt-6-astra";
+export const DEFAULT_DISTILLER_REASONING: ModelThinkingLevel = "minimal";
+export const REASONING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
 export interface DistillerConfig {
-  /** Master switch for the startup-pass distiller. */
+  /** Master switch for activation-time and explicit distillation. */
   enabled: boolean;
-  /** "provider/modelId" override; null walks the cheap-model preference list. */
-  model: string | null;
+  /** Exact provider/modelId selection. No provider fallback is performed. */
+  model: string;
+  /** Requested Pi reasoning level; the model may map it to another effective effort. */
+  reasoning: ModelThinkingLevel;
   /** Sessions younger than this are still in progress; leave them alone. */
   minIdleHours: number;
-  /** Bound on LLM extraction calls per activation pass (Codex parity: 16). */
+  /** Bound on extraction calls per pass. */
   maxSessionsPerPass: number;
-  /** Sessions older than this are not worth distilling (Codex parity: 30). */
+  /** Sessions older than this are not automatically distilled. */
   maxSessionAgeDays: number;
 }
 
 export interface PocketConfig {
-  /** Master switch for the whole pocket, toggled by /pocket on|off. */
   enabled: boolean;
   distiller: DistillerConfig;
 }
@@ -24,22 +31,14 @@ export const DEFAULT_CONFIG: PocketConfig = {
   enabled: true,
   distiller: {
     enabled: true,
-    model: null,
+    model: DEFAULT_DISTILLER_MODEL,
+    reasoning: DEFAULT_DISTILLER_REASONING,
     minIdleHours: 6,
     maxSessionsPerPass: 16,
     maxSessionAgeDays: 30,
   },
 };
 
-/** Cheap-model preference order when config.distiller.model is null. The first
- * entry resolvable in the user's model registry wins; if none resolve, the
- * distiller degrades to "mechanical floor only" rather than failing. */
-export const DISTILLER_MODEL_PREFERENCE: readonly string[] = [
-  "zai/glm-5.3-flash",
-  "openrouter/deepseek-v4-flash-latest",
-  "ollama-cloud/glm-5.3-flash",
-];
-
 export function configPath(root: string): string {
   return join(root, "config.json");
 }
@@ -49,9 +48,17 @@ function clampNumber(value: unknown, fallback: number, min: number, max: number)
   return Math.min(max, Math.max(min, n));
 }
 
-/** Load config, tolerating a missing or corrupt file by falling back to
- * defaults. The pocket is a convenience feature: a broken config must never
- * block extension load, so every read failure degrades to defaults. */
+export function isReasoningLevel(value: unknown): value is ModelThinkingLevel {
+  return typeof value === "string" && (REASONING_LEVELS as readonly string[]).includes(value);
+}
+
+export function isModelSpec(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const slash = value.indexOf("/");
+  return slash > 0 && slash < value.length - 1;
+}
+
+/** A malformed configuration degrades to defaults so note access remains usable. */
 export function loadConfig(root: string): PocketConfig {
   let raw: Record<string, unknown> = {};
   try {
@@ -59,12 +66,16 @@ export function loadConfig(root: string): PocketConfig {
   } catch {
     return structuredClone(DEFAULT_CONFIG);
   }
-  const d = (raw.distiller ?? {}) as Record<string, unknown>;
+  const d = typeof raw.distiller === "object" && raw.distiller !== null
+    ? raw.distiller as Record<string, unknown>
+    : {};
   return {
     enabled: typeof raw.enabled === "boolean" ? raw.enabled : DEFAULT_CONFIG.enabled,
     distiller: {
       enabled: typeof d.enabled === "boolean" ? d.enabled : DEFAULT_CONFIG.distiller.enabled,
-      model: typeof d.model === "string" && d.model.includes("/") ? d.model : null,
+      // Legacy null meant "choose a cheap fallback". It now resets to the explicit Astra default.
+      model: isModelSpec(d.model) ? d.model : DEFAULT_DISTILLER_MODEL,
+      reasoning: isReasoningLevel(d.reasoning) ? d.reasoning : DEFAULT_DISTILLER_REASONING,
       minIdleHours: clampNumber(d.minIdleHours, DEFAULT_CONFIG.distiller.minIdleHours, 1, 48),
       maxSessionsPerPass: clampNumber(d.maxSessionsPerPass, DEFAULT_CONFIG.distiller.maxSessionsPerPass, 1, 128),
       maxSessionAgeDays: clampNumber(d.maxSessionAgeDays, DEFAULT_CONFIG.distiller.maxSessionAgeDays, 0, 90),
@@ -72,7 +83,13 @@ export function loadConfig(root: string): PocketConfig {
   };
 }
 
+function atomicWrite(path: string, contents: string): void {
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temporary, contents, "utf8");
+  renameSync(temporary, path);
+}
+
 export function saveConfig(root: string, config: PocketConfig): void {
   mkdirSync(root, { recursive: true });
-  writeFileSync(configPath(root), `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  atomicWrite(configPath(root), `${JSON.stringify(config, null, 2)}\n`);
 }

package/node_modules/@nklisch/pi-astral-pocket/src/controller.ts

@@ -0,0 +1,78 @@
+import type { DistillerResult } from "./distiller.js";
+
+export type PassOutcome =
+  | { state: "idle" }
+  | { state: "running"; startedAt: string }
+  | { state: "completed"; finishedAt: string; result: DistillerResult }
+  | { state: "failed"; finishedAt: string; error: string }
+  | { state: "cancelled"; finishedAt: string };
+
+export type PassReporter = (message: string, level: "info" | "warning" | "error") => void;
+
+/** Own one serialized, revocable background pass for this extension instance. */
+export class DistillerController {
+  private generation = 0;
+  private controller: AbortController | undefined;
+  private queue: Promise<void> = Promise.resolve();
+  private reporter: PassReporter | undefined;
+  private outcome: PassOutcome = { state: "idle" };
+
+  status(): PassOutcome {
+    return this.outcome;
+  }
+
+  stop(): void {
+    this.generation += 1;
+    this.reporter = undefined;
+    this.controller?.abort();
+    this.controller = undefined;
+    if (this.outcome.state === "running") {
+      this.outcome = { state: "cancelled", finishedAt: new Date().toISOString() };
+    }
+  }
+
+  start(
+    task: (signal: AbortSignal) => Promise<DistillerResult>,
+    reporter?: PassReporter,
+  ): Promise<void> {
+    this.stop();
+    const generation = this.generation;
+    const controller = new AbortController();
+    this.controller = controller;
+    this.reporter = reporter;
+    const run = async () => {
+      if (controller.signal.aborted || generation !== this.generation) return;
+      this.outcome = { state: "running", startedAt: new Date().toISOString() };
+      try {
+        const result = await task(controller.signal);
+        if (controller.signal.aborted || generation !== this.generation) return;
+        this.outcome = { state: "completed", finishedAt: new Date().toISOString(), result };
+        if (result.errors.length > 0) {
+          this.report(generation, `Astral Pocket distillation finished with ${result.errors.length} error(s); source notes remain available.`, "warning");
+        }
+      } catch (error) {
+        if (controller.signal.aborted || generation !== this.generation) return;
+        const message = error instanceof Error ? error.message : String(error);
+        this.outcome = { state: "failed", finishedAt: new Date().toISOString(), error: message };
+        this.report(generation, `Astral Pocket distillation failed: ${message}. Source notes remain available.`, "warning");
+      } finally {
+        if (generation === this.generation) {
+          this.controller = undefined;
+          this.reporter = undefined;
+        }
+      }
+    };
+    this.queue = this.queue.catch(() => undefined).then(run);
+    return this.queue;
+  }
+
+  private report(generation: number, message: string, level: "info" | "warning" | "error"): void {
+    if (generation !== this.generation || !this.reporter) return;
+    try {
+      this.reporter(message, level);
+    } catch {
+      // Session replacement can revoke a UI sink between the generation check
+      // and notification. Reporting failure must never escape this boundary.
+    }
+  }
+}