@nklisch/pi-enhanced 0.3.1 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v0.4.1 — 2026-09-04
+
+### Added
+
+- Include `@nklisch/pi-astral-pocket` 0.1.0, the Astra-only persistent note and recall extension.
+
+### Fixed
+
+- Rebundle `@nklisch/pi-plugins` 0.8.2 and `@nklisch/pi-conveniences` 0.1.3 with accurate plugin versions, a framed manager, safer updates, and workspace-correct project instructions.
+
 ## v0.3.1
 
 ### Fixed

package/README.md

@@ -25,6 +25,7 @@ install commands, or versions to coordinate.
 | pi-background-tasks | Background jobs with polling, status, cancellation, and wakeups. |
 | pi-model-modes | System-prompt adaptation per model and mode. |
 | pi-conveniences | `/exit`, `.agents/AGENTS.md` context loading, context-window footer, subagent model listing. |
+| pi-astral-pocket | Persistent note pocket and past-session recall, active only for gpt-6-astra. |
 | pi-fff-compat | FFF-indexed file search through Pi-native find/grep semantics (no fuzzy fallback). |
 
 (`@nklisch/pi-zai-research` remains published separately if you prefer its

package/node_modules/@nklisch/pi-astral-pocket/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) Nathan Klisch

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

@@ -0,0 +1,138 @@
+# @nklisch/pi-astral-pocket
+
+Astral Pocket keeps durable Markdown notes across Pi sessions. It activates only
+when the current model is `openai-codex/gpt-6-astra`.
+
+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.
+
+## Notes and digest
+
+The extension adds two tools while Astra is active:
+
+- `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
+```
+
+`/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.
+
+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": "openai-codex/gpt-6-astra",
+    "reasoning": "minimal",
+    "minIdleHours": 6,
+    "maxSessionsPerPass": 16,
+    "maxSessionAgeDays": 30
+  }
+}
+```
+
+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
+
+Files are stored under `~/.pi/agent/astral-pocket/`, or under
+`$PI_CODING_AGENT_DIR/astral-pocket/` when that variable is set:
+
+```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-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

@@ -0,0 +1,54 @@
+{
+  "name": "@nklisch/pi-astral-pocket",
+  "version": "0.2.0",
+  "private": false,
+  "description": "Model-gated note pocket and session recall for gpt-6-astra",
+  "type": "module",
+  "author": {
+    "name": "Nathan Klisch"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nklisch/pi-extensions.git",
+    "directory": "packages/pi-astral-pocket"
+  },
+  "bugs": {
+    "url": "https://github.com/nklisch/pi-extensions/issues"
+  },
+  "homepage": "https://github.com/nklisch/pi-extensions/tree/main/packages/pi-astral-pocket#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "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",
+    "vitest": "^4.0.0"
+  }
+}

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

@@ -0,0 +1,44 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { PocketConfig } from "./config.js";
+
+export const ASTRA_PROVIDER = "openai-codex";
+export const ASTRA_MODEL_ID = "gpt-6-astra";
+export const POCKET_TOOLS = ["pocket_note", "pocket_recall"] as const;
+
+/** Mutable activation flag shared by tools, the /pocket command, and the
+ * before_agent_start injector. Module-level because the extension factory has
+ * no ctx — the first reliable model read is in session_start. */
+export interface ActivationState {
+  active: boolean;
+}
+
+export function isAstraModel(model: { id?: string; provider?: string } | undefined | null): boolean {
+  return model?.provider === ASTRA_PROVIDER && model?.id === ASTRA_MODEL_ID;
+}
+
+export function isActive(state: ActivationState, ctx: ExtensionContext, config: PocketConfig): boolean {
+  return config.enabled && isAstraModel(ctx.model);
+}
+
+/** Recompute activation from the current model + config and sync pi's active
+ * tool set. Call from session_start and model_select handlers — never from
+ * the factory body (pi forbids active-set mutation during load). */
+export function recomputeActivation(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  state: ActivationState,
+  config: PocketConfig,
+): boolean {
+  const active = isActive(state, ctx, config);
+  const current = pi.getActiveTools();
+  const hasPocket = POCKET_TOOLS.every((t) => current.includes(t));
+  if (active && !hasPocket) {
+    pi.setActiveTools([...new Set([...current, ...POCKET_TOOLS])]);
+  } else if (!active && hasPocket) {
+    pi.setActiveTools(current.filter((t) => !(POCKET_TOOLS as readonly string[]).includes(t)));
+  }
+  const becameActive = active && !state.active;
+  state.active = active;
+  return becameActive;
+}

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

@@ -0,0 +1,95 @@
+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 activation-time and explicit distillation. */
+  enabled: boolean;
+  /** 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 extraction calls per pass. */
+  maxSessionsPerPass: number;
+  /** Sessions older than this are not automatically distilled. */
+  maxSessionAgeDays: number;
+}
+
+export interface PocketConfig {
+  enabled: boolean;
+  distiller: DistillerConfig;
+}
+
+export const DEFAULT_CONFIG: PocketConfig = {
+  enabled: true,
+  distiller: {
+    enabled: true,
+    model: DEFAULT_DISTILLER_MODEL,
+    reasoning: DEFAULT_DISTILLER_REASONING,
+    minIdleHours: 6,
+    maxSessionsPerPass: 16,
+    maxSessionAgeDays: 30,
+  },
+};
+
+export function configPath(root: string): string {
+  return join(root, "config.json");
+}
+
+function clampNumber(value: unknown, fallback: number, min: number, max: number): number {
+  const n = typeof value === "number" && Number.isFinite(value) ? value : fallback;
+  return Math.min(max, Math.max(min, n));
+}
+
+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 {
+    raw = JSON.parse(readFileSync(configPath(root), "utf8")) as Record<string, unknown>;
+  } catch {
+    return structuredClone(DEFAULT_CONFIG);
+  }
+  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,
+      // 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),
+    },
+  };
+}
+
+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 });
+  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.
+    }
+  }
+}