@nklisch/pi-enhanced 0.3.1 → 0.4.1

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,82 @@
+# @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.
+
+## Commands
+
+- `/pocket on` / `/pocket off` — enable/disable the pocket (persisted).
+- `/pocket status` — show enablement, activation, note count, distiller config.
+
+## Storage
+
+Everything lives in `~/.pi/agent/astral-pocket/` (or
+`$PI_CODING_AGENT_DIR/astral-pocket/`):
+
+```
+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
+
+`config.json` (all optional, defaults shown):
+
+```json
+{
+  "enabled": true,
+  "distiller": {
+    "enabled": true,
+    "model": null,
+    "minIdleHours": 6,
+    "maxSessionsPerPass": 16,
+    "maxSessionAgeDays": 30
+  }
+}
+```
+
+`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.
+
+## Privacy note
+
+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.
+
+## Install
+
+```sh
+pi install npm:@nklisch/pi-astral-pocket
+```

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

@@ -0,0 +1,52 @@
+{
+  "name": "@nklisch/pi-astral-pocket",
+  "version": "0.1.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-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@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,78 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface DistillerConfig {
+  /** Master switch for the startup-pass distiller. */
+  enabled: boolean;
+  /** "provider/modelId" override; null walks the cheap-model preference list. */
+  model: string | null;
+  /** Sessions younger than this are still in progress; leave them alone. */
+  minIdleHours: number;
+  /** Bound on LLM extraction calls per activation pass (Codex parity: 16). */
+  maxSessionsPerPass: number;
+  /** Sessions older than this are not worth distilling (Codex parity: 30). */
+  maxSessionAgeDays: number;
+}
+
+export interface PocketConfig {
+  /** Master switch for the whole pocket, toggled by /pocket on|off. */
+  enabled: boolean;
+  distiller: DistillerConfig;
+}
+
+export const DEFAULT_CONFIG: PocketConfig = {
+  enabled: true,
+  distiller: {
+    enabled: true,
+    model: null,
+    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");
+}
+
+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));
+}
+
+/** 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 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 = (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,
+      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),
+    },
+  };
+}
+
+export function saveConfig(root: string, config: PocketConfig): void {
+  mkdirSync(root, { recursive: true });
+  writeFileSync(configPath(root), `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}

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

@@ -0,0 +1,162 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+
+import type { DistillerConfig } from "./config.js";
+import { identifySession, listSessionFiles, readSessionDigest, type SessionFileInfo } from "./sessions.js";
+import { ensureLayout, updateDigest, writeNote } from "./store.js";
+
+/** Bounded startup-pass distiller, modeled on Codex's memories pipeline: when
+ * astra activates, find astra sessions that have been idle long enough, run
+ * one cheap-model extraction per session into distilled pocket notes, then one
+ * consolidation call that refreshes the durable digest. There is no daemon —
+ * the pass runs at activation time only, and every failure degrades to the
+ * mechanical floor (registry + recent-notes index stay correct without it). */
+
+export interface DistillerDeps {
+  /** One cheap-model completion. Injected so tests never touch the network;
+   * null when no distiller model resolves (distiller skips with a notice). */
+  callModel: ((prompt: string) => Promise<string>) | null;
+  log: (message: string) => void;
+  now?: () => number;
+}
+
+export interface DistillerResult {
+  processed: number;
+  skippedReason?: string;
+  errors: string[];
+}
+
+interface DistilledState {
+  sessions: Record<string, string>; // sessionId -> ISO date distilled
+}
+
+function statePath(root: string): string {
+  return join(root, "distilled.json");
+}
+
+function loadState(root: string): DistilledState {
+  try {
+    return JSON.parse(readFileSync(statePath(root), "utf8")) as DistilledState;
+  } catch {
+    return { sessions: {} };
+  }
+}
+
+function saveState(root: string, state: DistilledState): void {
+  writeFileSync(statePath(root), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+/** Sessions eligible for distillation: astra sessions idle past the threshold,
+ * within the age cap, not already distilled, oldest first, bounded. */
+export async function selectDistillationCandidates(
+  sessionsDir: string,
+  config: DistillerConfig,
+  state: DistilledState,
+  nowMs: number,
+): Promise<SessionFileInfo[]> {
+  const idleCutoff = nowMs - config.minIdleHours * 3_600_000;
+  const candidates: SessionFileInfo[] = [];
+  for (const { path, mtimeMs } of listSessionFiles(sessionsDir, config.maxSessionAgeDays)) {
+    if (mtimeMs > idleCutoff) continue;
+    const info = await identifySession(path, mtimeMs);
+    if (!info.astra || !info.id || state.sessions[info.id]) continue;
+    candidates.push(info);
+  }
+  return candidates.sort((a, b) => a.mtimeMs - b.mtimeMs).slice(0, config.maxSessionsPerPass);
+}
+
+const EXTRACTION_PROMPT = `You are distilling a past coding-agent session into durable pocket notes for future sessions.
+
+From the transcript below, extract ONLY durable knowledge worth carrying forward:
+- decisions and their rationale
+- project conventions and constraints
+- recurring pitfalls and their fixes
+- user preferences and working style
+- non-obvious facts that cost effort to discover
+
+Do NOT include: ephemeral task status, things already recorded in the repo, anything re-derivable in seconds, or secrets/credentials/personal data (redact anything that looks like one).
+
+If nothing in the session is durable, reply with exactly: NONE
+Otherwise reply with at most 5 short markdown bullets, each starting with a bolded title.
+
+TRANSCRIPT:
+`;
+
+const CONSOLIDATION_PROMPT = `You maintain the "durable digest" of an agent's cross-session pocket notes. Merge the new distilled notes below into the existing digest: dedupe, drop contradicted or stale entries, keep it under 40 short bullets. Reply with the refreshed digest markdown only, no commentary.
+
+EXISTING DIGEST:
+`;
+
+export async function runDistillerPass(
+  root: string,
+  sessionsDir: string,
+  config: DistillerConfig,
+  deps: DistillerDeps,
+): Promise<DistillerResult> {
+  const nowMs = (deps.now ?? Date.now)();
+  if (!config.enabled) return { processed: 0, skippedReason: "distiller disabled", errors: [] };
+  if (!deps.callModel) {
+    deps.log("astral-pocket: no distiller model resolved; mechanical floor only");
+    return { processed: 0, skippedReason: "no distiller model", errors: [] };
+  }
+
+  ensureLayout(root);
+  const state = loadState(root);
+  const candidates = await selectDistillationCandidates(sessionsDir, config, state, nowMs);
+  const errors: string[] = [];
+  const extracted: string[] = [];
+
+  for (const session of candidates) {
+    try {
+      const transcript = await readSessionDigest(session.path);
+      if (transcript.length < 200) {
+        state.sessions[session.id] = new Date(nowMs).toISOString(); // too short to hold durable signal
+        continue;
+      }
+      const output = await deps.callModel(`${EXTRACTION_PROMPT}\n${transcript}`);
+      if (output.trim() && output.trim() !== "NONE") {
+        const project = session.cwd.split("/").filter(Boolean).pop() ?? "unknown";
+        // Queue on POCKET.md like pocket_note does: the distiller runs
+        // concurrently with live note writes, and registry+summary updates
+        // are read-modify-write cycles that would otherwise race.
+        await withFileMutationQueue(join(root, "POCKET.md"), async () =>
+          writeNote(root, {
+            title: `Distilled session — ${project} — ${new Date(session.mtimeMs).toISOString().slice(0, 10)}`,
+            body: output.trim(),
+            keywords: ["distilled", project],
+            project: session.cwd,
+            source: "distilled",
+          }),
+        );
+        extracted.push(output.trim());
+      }
+      state.sessions[session.id] = new Date(nowMs).toISOString();
+    } catch (error) {
+      errors.push(`${session.id}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  if (extracted.length > 0) {
+    try {
+      const summaryPath = join(root, "SUMMARY.md");
+      const existing = existsSync(summaryPath) ? readFileSync(summaryPath, "utf8") : "";
+      const digestMatch = existing.match(/<!-- pocket:digest:start -->([\s\S]*?)<!-- pocket:digest:end -->/);
+      const existingDigest = digestMatch?.[1]?.trim() ?? "";
+      const refreshed = await deps.callModel(
+        `${CONSOLIDATION_PROMPT}\n${existingDigest}\n\nNEW NOTES:\n${extracted.join("\n")}`,
+      );
+      if (refreshed.trim()) updateDigest(root, refreshed.trim());
+    } catch (error) {
+      errors.push(`consolidation: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  try {
+    saveState(root, state);
+  } catch (error) {
+    errors.push(`state: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return { processed: extracted.length, errors };
+}

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

@@ -0,0 +1,59 @@
+/** Guidance injected into astra's system prompt while the pocket is active.
+ * Adapted from OpenAI Codex's shipped memories template
+ * (codex-rs/ext/memories/templates/memories/read_path.md): same decision
+ * boundary, same budgeted quick pass, same drift policy. Differences from
+ * Codex are deliberate: notes are written autonomously with judgment (this is
+ * a personal pocket, not a shared memory product), and there is no citation
+ * block (pi has no UI surface that would render it). */
+export function buildPocketGuidance(summary: string): string {
+  return `## Astral Pocket
+
+You have a persistent note pocket that survives across sessions. It carries
+decisions, conventions, pitfalls, and preferences you judged worth keeping.
+The pocket summary is appended below; the full store is searchable with the
+pocket_recall tool.
+
+Decision boundary — when to consult the pocket:
+
+- Skip the pocket ONLY when the request is clearly self-contained and needs no
+  project history, conventions, or prior decisions (current time, one-line
+  shell commands, trivial rewrites).
+- Consult it by default when the task mentions a project, repo, or topic that
+  appears in the summary below, when the user asks about prior context or
+  previous decisions, or when the task is ambiguous in a way earlier choices
+  could resolve.
+- If unsure, do a quick pocket pass.
+
+Quick pocket pass (keep it cheap — at most 4-6 lookup steps before main work):
+
+1. Skim the summary below for task-relevant keywords.
+2. Search with pocket_recall using those keywords.
+3. Open at most 1-2 of the most relevant hits (full: true only when you need
+   exact commands, error text, or precise evidence).
+4. If nothing relevant surfaces, stop and continue normally.
+
+During execution: if you hit repeated errors or confusing behavior that prior
+context might explain, redo the quick pass.
+
+Trust and drift:
+
+- Pocket notes are point-in-time. If a noted fact is likely to have drifted
+  and is cheap to verify, verify before relying on it. When you answer from an
+  unverified note, say it is pocket-derived and may be stale.
+- Do not present unverified pocket facts as confirmed-current.
+
+Taking notes with pocket_note:
+
+- Write a note when you learn something durable: a decision and its rationale,
+  a project convention, a recurring pitfall, a user preference, a non-obvious
+  fact that cost effort to discover.
+- Do not note ephemeral task state, things already recorded in the repo
+  (AGENTS.md, docs, code), or anything you could re-derive in seconds.
+- Never note secrets, credentials, tokens, or personal data.
+- One topic per note; a few sentences is enough. Give it 2-5 keywords so
+  future recall can find it.
+
+========= POCKET SUMMARY BEGINS =========
+${summary.trim() || "(empty — no notes yet)"}
+========= POCKET SUMMARY ENDS =========`;
+}

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

@@ -0,0 +1,127 @@
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { recomputeActivation, type ActivationState } from "./activation.js";
+import { DISTILLER_MODEL_PREFERENCE, loadConfig, saveConfig, type PocketConfig } from "./config.js";
+import { runDistillerPass } from "./distiller.js";
+import { buildPocketGuidance } from "./guidance.js";
+import { readRegistryLines, readSummaryCapped, ensureLayout, pocketRoot, defaultAgentDir } from "./store.js";
+import { registerPocketTools } from "./tools.js";
+
+/** Extract text from a completed AssistantMessage, failing on error stops. */
+function messageText(message: { stopReason?: string; errorMessage?: string; content: unknown }): string {
+  if (message.stopReason === "error") throw new Error(message.errorMessage ?? "model error");
+  if (!Array.isArray(message.content)) return "";
+  return (message.content as { type?: string; text?: string }[])
+    .filter((b) => b.type === "text" && typeof b.text === "string")
+    .map((b) => b.text)
+    .join("");
+}
+
+/** Resolve the distiller's cheap model: config override first, then the
+ * preference list, first entry the registry can resolve. Returns null when
+ * nothing resolves — the distiller then degrades to the mechanical floor. */
+function makeCallModel(ctx: ExtensionContext, config: PocketConfig): ((prompt: string) => Promise<string>) | null {
+  const candidates = config.distiller.model
+    ? [config.distiller.model]
+    : DISTILLER_MODEL_PREFERENCE;
+  for (const ref of candidates) {
+    const slash = ref.indexOf("/");
+    const providerId = ref.slice(0, slash);
+    const modelId = ref.slice(slash + 1);
+    const model = ctx.modelRegistry.find(providerId, modelId);
+    if (!model) continue;
+    const provider = ctx.modelRegistry.getProvider(providerId) as {
+      streamSimple?: (m: unknown, c: unknown, o?: unknown) => { result(): Promise<unknown> };
+    } | null;
+    if (!provider?.streamSimple) continue;
+    return async (prompt: string) => {
+      const stream = provider.streamSimple!(model, {
+        messages: [{ role: "user", content: prompt, timestamp: Date.now() }],
+      });
+      return messageText((await stream.result()) as { stopReason?: string; errorMessage?: string; content: unknown });
+    };
+  }
+  return null;
+}
+
+export default function extension(pi: ExtensionAPI): void {
+  const agentDir = defaultAgentDir();
+  const root = pocketRoot(agentDir);
+  const sessionsDir = join(agentDir, "sessions");
+  const state: ActivationState = { active: false };
+  let config = loadConfig(root);
+
+  registerPocketTools(pi, {
+    state,
+    root,
+    sessionsDir,
+    maxSessionAgeDays: () => config.distiller.maxSessionAgeDays,
+  });
+
+  /** Sync activation with the current model; on activation, ensure the store
+   * exists and kick the bounded distiller pass (fire-and-forget — it must
+   * never delay or fail the user's session start). */
+  function activate(ctx: ExtensionContext): void {
+    const becameActive = recomputeActivation(pi, ctx, state, config);
+    if (!state.active) return;
+    ensureLayout(root);
+    if (!becameActive) return;
+    const callModel = makeCallModel(ctx, config);
+    runDistillerPass(root, sessionsDir, config.distiller, {
+      callModel,
+      log: (msg) => ctx.ui.notify(msg, "info"),
+    })
+      .then((result) => {
+        if (result.errors.length > 0) {
+          ctx.ui.notify(`astral-pocket distiller: ${result.errors.length} session(s) failed`, "warning");
+        }
+      })
+      .catch(() => ctx.ui.notify("astral-pocket distiller pass failed; mechanical floor intact", "warning"));
+  }
+
+  pi.on("session_start", (_event, ctx) => {
+    activate(ctx);
+  });
+  pi.on("model_select", (_event, ctx) => {
+    activate(ctx);
+  });
+
+  pi.on("before_agent_start", (event, _ctx) => {
+    if (!state.active) return undefined;
+    return { systemPrompt: `${event.systemPrompt}\n\n${buildPocketGuidance(readSummaryCapped(root))}` };
+  });
+
+  pi.registerCommand("pocket", {
+    description: "Toggle the astral pocket: /pocket on|off|status",
+    getArgumentCompletions: (prefix) => {
+      const items = ["on", "off", "status"].map((v) => ({ value: v, label: v }));
+      const filtered = items.filter((i) => i.value.startsWith(prefix));
+      return filtered.length > 0 ? filtered : null;
+    },
+    handler: async (args, ctx) => {
+      const verb = args.trim().toLowerCase();
+      if (verb === "on" || verb === "off") {
+        config = { ...config, enabled: verb === "on" };
+        saveConfig(root, config);
+        activate(ctx);
+        ctx.ui.notify(
+          config.enabled
+            ? "Astral pocket enabled (active for gpt-6-astra sessions)."
+            : "Astral pocket disabled.",
+          "info",
+        );
+        return;
+      }
+      const notes = readRegistryLines(root).length;
+      ctx.ui.notify(
+        [
+          `Pocket: ${config.enabled ? "enabled" : "disabled"}; ${state.active ? "active this session" : "inactive (not an astra session)"}`,
+          `Notes: ${notes}. Distiller: ${config.distiller.enabled ? `on (model: ${config.distiller.model ?? DISTILLER_MODEL_PREFERENCE[0]})` : "off"}`,
+          `Store: ${root}`,
+        ].join("\n"),
+        "info",
+      );
+    },
+  });
+}