@nklisch/pi-enhanced 0.3.1 → 0.4.1

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

@@ -0,0 +1,225 @@
+import { createReadStream, existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+
+import { ASTRA_MODEL_ID, ASTRA_PROVIDER } from "./activation.js";
+
+/** Past-session access. Pi stores sessions as JSONL trees at
+ * `<agentDir>/sessions/<cwd-slug>/<timestamp>_<uuid>.jsonl`, with sub-agent
+ * task sessions nested under a `tasks/` subdir (excluded here — they are
+ * worker noise, and their parent session carries the durable signal). */
+
+export interface SessionFileInfo {
+  path: string;
+  id: string;
+  cwd: string;
+  mtimeMs: number;
+  /** True when any assistant message in the file was produced by astra, or a
+   * model_change switched to it. Assistant messages carry provider/model
+   * directly, so sessions that were astra from the start are still caught. */
+  astra: boolean;
+}
+
+export interface SessionSearchHit {
+  sessionId: string;
+  project: string;
+  timestamp: string;
+  kind: "user" | "assistant" | "toolCall" | "toolResult";
+  excerpt: string;
+}
+
+const HITS_PER_FILE_CAP = 50;
+const SUMMARIZED_EXCERPT = 200;
+const FULL_EXCERPT = 2000;
+
+async function* iterLines(path: string): AsyncGenerator<string> {
+  const rl = createInterface({ input: createReadStream(path, "utf8"), crlfDelay: Infinity });
+  for await (const line of rl) yield line;
+}
+
+/** Enumerate top-level session files across all project dirs, newest first. */
+export function listSessionFiles(sessionsDir: string, maxAgeDays?: number): { path: string; mtimeMs: number }[] {
+  if (!existsSync(sessionsDir)) return [];
+  const cutoff = maxAgeDays === undefined ? null : Date.now() - maxAgeDays * 86_400_000;
+  const files: { path: string; mtimeMs: number }[] = [];
+  for (const dir of readdirSync(sessionsDir)) {
+    const dirPath = join(sessionsDir, dir);
+    try {
+      if (!statSync(dirPath).isDirectory()) continue;
+      for (const file of readdirSync(dirPath)) {
+        if (!file.endsWith(".jsonl")) continue;
+        const path = join(dirPath, file);
+        const mtimeMs = statSync(path).mtimeMs;
+        if (cutoff !== null && mtimeMs < cutoff) continue;
+        files.push({ path, mtimeMs });
+      }
+    } catch {
+      continue; // unreadable dir: skip, never fail recall over it
+    }
+  }
+  return files.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+
+function isAstraMarker(entry: Record<string, unknown>): boolean {
+  if (entry.type === "model_change" && entry.provider === ASTRA_PROVIDER && entry.modelId === ASTRA_MODEL_ID) return true;
+  if (entry.type === "message") {
+    const msg = entry.message as Record<string, unknown> | undefined;
+    if (msg?.role === "assistant" && msg.provider === ASTRA_PROVIDER && msg.model === ASTRA_MODEL_ID) return true;
+  }
+  return false;
+}
+
+/** Identify a session file: header id/cwd plus astra usage, streaming so large
+ * files stop early once both identity and astra-ness are known. */
+export async function identifySession(path: string, mtimeMs: number): Promise<SessionFileInfo> {
+  let id = "";
+  let cwd = "";
+  let astra = false;
+  for await (const line of iterLines(path)) {
+    if (id && cwd && astra) break;
+    let entry: Record<string, unknown>;
+    try {
+      entry = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    if (entry.type === "session") {
+      id = String(entry.id ?? "");
+      cwd = String(entry.cwd ?? "");
+    } else if (isAstraMarker(entry)) {
+      astra = true;
+    }
+  }
+  return { path, id, cwd, mtimeMs, astra };
+}
+
+function textOf(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((b): b is Record<string, unknown> => typeof b === "object" && b !== null)
+    .map((b) => (typeof b.text === "string" ? b.text : ""))
+    .filter(Boolean)
+    .join(" ");
+}
+
+function truncate(text: string, cap: number): string {
+  const clean = text.replace(/\s+/g, " ").trim();
+  return clean.length <= cap ? clean : `${clean.slice(0, cap)}…`;
+}
+
+/** Search astra sessions for a query. Summarized by default: tool hits return
+ * name + truncated args/results, message hits return short excerpts. `full`
+ * raises the excerpt cap. Only astra sessions are searched — other models'
+ * sessions are noise for this tool and may carry unrelated secrets. */
+export async function searchAstraSessions(
+  sessionsDir: string,
+  query: string,
+  options: { full?: boolean; limit?: number; maxAgeDays?: number } = {},
+): Promise<SessionSearchHit[]> {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (terms.length === 0) return [];
+  const limit = options.limit ?? 10;
+  const cap = options.full ? FULL_EXCERPT : SUMMARIZED_EXCERPT;
+  const hits: SessionSearchHit[] = [];
+
+  for (const { path, mtimeMs } of listSessionFiles(sessionsDir, options.maxAgeDays)) {
+    if (hits.length >= limit) break;
+    const info = await identifySession(path, mtimeMs);
+    if (!info.astra) continue;
+
+    const fileHits: SessionSearchHit[] = [];
+    for await (const line of iterLines(path)) {
+      if (fileHits.length >= HITS_PER_FILE_CAP) break;
+      if (!terms.every((t) => line.toLowerCase().includes(t))) continue;
+      let entry: Record<string, unknown>;
+      try {
+        entry = JSON.parse(line) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      if (entry.type !== "message") continue;
+      const msg = entry.message as Record<string, unknown>;
+      const role = msg.role as string;
+      const timestamp = String(entry.timestamp ?? "");
+      const base = { sessionId: info.id, project: info.cwd, timestamp };
+      if (role === "user" || role === "assistant") {
+        const content = msg.content;
+        if (Array.isArray(content)) {
+          for (const block of content as Record<string, unknown>[]) {
+            if (block.type === "toolCall") {
+              const args = truncate(JSON.stringify(block.arguments ?? {}), cap);
+              if (terms.every((t) => `${String(block.name)} ${args}`.toLowerCase().includes(t))) {
+                fileHits.push({ ...base, kind: "toolCall", excerpt: `${String(block.name)}(${args})` });
+              }
+            } else if (block.type === "text" && typeof block.text === "string") {
+              const text = block.text as string;
+              if (terms.every((t) => text.toLowerCase().includes(t))) {
+                fileHits.push({ ...base, kind: role as "user" | "assistant", excerpt: truncate(text, cap) });
+              }
+            }
+          }
+        } else {
+          const text = textOf(content);
+          if (terms.every((t) => text.toLowerCase().includes(t))) {
+            fileHits.push({ ...base, kind: role as "user" | "assistant", excerpt: truncate(text, cap) });
+          }
+        }
+      } else if (role === "toolResult") {
+        const text = textOf(msg.content);
+        if (terms.every((t) => `${String(msg.toolName ?? "")} ${text}`.toLowerCase().includes(t))) {
+          fileHits.push({
+            ...base,
+            kind: "toolResult",
+            excerpt: `${String(msg.toolName ?? "tool")} → ${truncate(text, cap)}`,
+          });
+        }
+      }
+    }
+    hits.push(...fileHits);
+  }
+  return hits.slice(0, limit);
+}
+
+/** Compact transcript of one session for the distiller: user/assistant text
+ * plus tool-call names with truncated args, tool results reduced to a short
+ * marker. Full results are deliberately excluded — they are the largest and
+ * least durable content, and the biggest secret-resurfacing vector. */
+export async function readSessionDigest(path: string, capBytes = 60_000): Promise<string> {
+  const parts: string[] = [];
+  let size = 0;
+  for await (const line of iterLines(path)) {
+    if (size >= capBytes) {
+      parts.push("… [transcript truncated]");
+      break;
+    }
+    let entry: Record<string, unknown>;
+    try {
+      entry = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    if (entry.type !== "message") continue;
+    const msg = entry.message as Record<string, unknown>;
+    let chunk = "";
+    if (msg.role === "user") chunk = `USER: ${truncate(textOf(msg.content), 1500)}`;
+    else if (msg.role === "assistant") {
+      const content = Array.isArray(msg.content) ? (msg.content as Record<string, unknown>[]) : [];
+      const texts = content
+        .map((b) => {
+          if (b.type === "text") return truncate(String(b.text ?? ""), 1500);
+          if (b.type === "toolCall") return `[tool: ${String(b.name)} ${truncate(JSON.stringify(b.arguments ?? {}), 200)}]`;
+          return "";
+        })
+        .filter(Boolean)
+        .join(" ");
+      chunk = texts ? `ASSISTANT: ${texts}` : "";
+    } else if (msg.role === "toolResult") {
+      chunk = `[result: ${String(msg.toolName ?? "tool")}${msg.isError ? " (error)" : ""}] ${truncate(textOf(msg.content), 200)}`;
+    }
+    if (!chunk) continue;
+    size += chunk.length;
+    parts.push(chunk);
+  }
+  return parts.join("\n");
+}

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

@@ -0,0 +1,227 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Store layout under the pocket root:
+ *   config.json          — toggles + distiller settings (config.ts)
+ *   SUMMARY.md           — injected into astra's system prompt; mechanical render
+ *   POCKET.md            — searchable registry, one line per note
+ *   notes/<ts>-<slug>.md — append-only note files
+ *   distilled.json       — distiller bookkeeping (which sessions are processed)
+ */
+
+const PINNED_START = "<!-- pocket:pinned:start -->";
+const PINNED_END = "<!-- pocket:pinned:end -->";
+const DIGEST_START = "<!-- pocket:digest:start -->";
+const DIGEST_END = "<!-- pocket:digest:end -->";
+
+const RECENT_NOTES_CAP = 20;
+const REGISTRY_LINE_CAP = 500;
+const BODY_SCAN_CAP = 200;
+
+export function defaultAgentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
+
+export function pocketRoot(agentDir: string = defaultAgentDir()): string {
+  return join(agentDir, "astral-pocket");
+}
+
+export function notesDir(root: string): string {
+  return join(root, "notes");
+}
+
+export function ensureLayout(root: string): void {
+  mkdirSync(notesDir(root), { recursive: true });
+  const registry = join(root, "POCKET.md");
+  if (!existsSync(registry)) {
+    writeFileSync(registry, "# Astral Pocket Registry\n\nOne line per note. Search this first.\n\n", "utf8");
+  }
+  if (!existsSync(join(root, "SUMMARY.md"))) {
+    writeFileSync(join(root, "SUMMARY.md"), renderSummary(root, []), "utf8");
+  }
+}
+
+export interface NoteInput {
+  title: string;
+  body: string;
+  keywords?: string[];
+  /** cwd of the session taking the note; recorded for project-aware ranking. */
+  project?: string;
+  source?: "agent" | "distilled";
+}
+
+function slugify(text: string): string {
+  const slug = text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+  return slug || "note";
+}
+
+function stamp(date: Date): string {
+  return date.toISOString().replace(/[:.]/g, "-").replace("Z", "Z");
+}
+
+function extractSection(markdown: string, start: string, end: string): string | null {
+  const i = markdown.indexOf(start);
+  const j = markdown.indexOf(end);
+  if (i === -1 || j === -1 || j < i) return null;
+  return markdown.slice(i + start.length, j).trim();
+}
+
+/** Write one note file and update the registry + summary. Returns the note's
+ * file name. Callers that need cross-file mutation safety should wrap this in
+ * `withFileMutationQueue(join(root, "POCKET.md"), ...)`. */
+export function writeNote(root: string, input: NoteInput, now: Date = new Date()): string {
+  ensureLayout(root);
+  const fileName = `${stamp(now)}-${slugify(input.title)}.md`;
+  const frontmatter = [
+    "---",
+    `created: ${now.toISOString()}`,
+    `project: ${input.project ?? "unknown"}`,
+    `keywords: [${(input.keywords ?? []).join(", ")}]`,
+    `source: ${input.source ?? "agent"}`,
+    "---",
+  ].join("\n");
+  writeFileSync(join(notesDir(root), fileName), `${frontmatter}\n\n# ${input.title}\n\n${input.body.trim()}\n`, "utf8");
+
+  const projectTag = input.project ? (input.project.split("/").filter(Boolean).pop() ?? input.project) : "unknown";
+  const keywordTag = (input.keywords ?? []).join(", ");
+  const line = `- [${input.title}](notes/${fileName})${keywordTag ? ` — ${keywordTag}` : ""} — ${projectTag} — ${now.toISOString().slice(0, 10)}`;
+  appendRegistryLine(root, line);
+  rerenderSummary(root);
+  return fileName;
+}
+
+function appendRegistryLine(root: string, line: string): void {
+  const registry = join(root, "POCKET.md");
+  const existing = existsSync(registry) ? readFileSync(registry, "utf8") : "";
+  writeFileSync(registry, `${existing.trimEnd()}\n${line}\n`, "utf8");
+}
+
+export function readRegistryLines(root: string): string[] {
+  const registry = join(root, "POCKET.md");
+  if (!existsSync(registry)) return [];
+  return readFileSync(registry, "utf8")
+    .split("\n")
+    .filter((l) => l.startsWith("- ["));
+}
+
+/** Re-render SUMMARY.md mechanically: the pinned block and the
+ * distiller-maintained digest block carry over verbatim from the existing
+ * file; only the recent-notes index is regenerated. This is the mechanical
+ * floor — it runs on every note write with zero LLM involvement. */
+export function rerenderSummary(root: string): void {
+  writeFileSync(join(root, "SUMMARY.md"), renderSummary(root, readRegistryLines(root)), "utf8");
+}
+
+function renderSummary(root: string, registryLines: string[]): string {
+  const summaryPath = join(root, "SUMMARY.md");
+  const existing = existsSync(summaryPath) ? readFileSync(summaryPath, "utf8") : "";
+  const pinned = extractSection(existing, PINNED_START, PINNED_END) ?? "";
+  const digest =
+    extractSection(existing, DIGEST_START, DIGEST_END) ??
+    "_No digest yet. It is filled in by the distiller pass; until then, rely on Recent notes and search POCKET.md._";
+  const recent = registryLines.slice(-RECENT_NOTES_CAP);
+  return [
+    "# Astral Pocket Summary",
+    "",
+    PINNED_START,
+    pinned,
+    PINNED_END,
+    "",
+    "## Durable digest",
+    "",
+    DIGEST_START,
+    digest,
+    DIGEST_END,
+    "",
+    "## Recent notes",
+    "",
+    ...(recent.length > 0 ? recent : ["_No notes yet._"]),
+    "",
+  ].join("\n");
+}
+
+/** Replace the distiller-maintained digest block, preserving everything else.
+ * Returns false when SUMMARY.md is missing the markers (never rendered). */
+export function updateDigest(root: string, digest: string): boolean {
+  const summaryPath = join(root, "SUMMARY.md");
+  if (!existsSync(summaryPath)) return false;
+  const existing = readFileSync(summaryPath, "utf8");
+  const i = existing.indexOf(DIGEST_START);
+  const j = existing.indexOf(DIGEST_END);
+  if (i === -1 || j === -1 || j < i) return false;
+  writeFileSync(summaryPath, `${existing.slice(0, i + DIGEST_START.length)}\n${digest.trim()}\n${existing.slice(j)}`, "utf8");
+  return true;
+}
+
+/** The text injected into astra's system prompt, capped to keep the per-turn
+ * cost bounded regardless of how large the summary grows. */
+export function readSummaryCapped(root: string, capBytes = 12_000): string {
+  const summaryPath = join(root, "SUMMARY.md");
+  if (!existsSync(summaryPath)) return "";
+  const text = readFileSync(summaryPath, "utf8");
+  return text.length <= capBytes ? text : `${text.slice(0, capBytes)}\n\n_(summary truncated; search POCKET.md for older material)_`;
+}
+
+export interface PocketSearchHit {
+  noteFile: string;
+  title: string;
+  excerpt: string;
+  project: string;
+}
+
+/** Case-insensitive keyword search over the registry, then the note bodies.
+ * Registry hits rank first; current-project notes rank above others. */
+export function searchPocket(root: string, query: string, currentProject: string | undefined, limit: number): PocketSearchHit[] {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (terms.length === 0) return [];
+  const matches = (haystack: string) => terms.every((t) => haystack.toLowerCase().includes(t));
+
+  const hits: PocketSearchHit[] = [];
+  for (const line of readRegistryLines(root).slice(-REGISTRY_LINE_CAP)) {
+    if (!matches(line)) continue;
+    const fileMatch = line.match(/\]\((notes\/[^)]+)\)/);
+    const titleMatch = line.match(/- \[([^\]]+)\]/);
+    if (!fileMatch) continue;
+    hits.push({
+      noteFile: fileMatch[1].replace(/^notes\//, ""),
+      title: titleMatch?.[1] ?? fileMatch[1],
+      excerpt: line,
+      project: "",
+    });
+  }
+
+  const bodyHits: PocketSearchHit[] = [];
+  // Timestamp-prefixed names sort chronologically; cap the body scan at the
+  // newest files so recall stays fast as the store grows.
+  const files = readdirSync(notesDir(root))
+    .filter((f) => f.endsWith(".md"))
+    .sort()
+    .slice(-BODY_SCAN_CAP);
+  for (const file of files) {
+    if (hits.some((h) => h.noteFile === file)) continue;
+    const text = readFileSync(join(notesDir(root), file), "utf8");
+    if (!matches(text)) continue;
+    const project = text.match(/^project: (.+)$/m)?.[1] ?? "";
+    const title = text.match(/^# (.+)$/m)?.[1] ?? file;
+    const idx = text.toLowerCase().indexOf(terms[0]);
+    bodyHits.push({
+      noteFile: file,
+      title,
+      excerpt: text.slice(Math.max(0, idx - 120), idx + 280).trim(),
+      project,
+    });
+  }
+
+  const currentTag = currentProject?.split("/").filter(Boolean).pop();
+  const ranked = [...hits, ...bodyHits].sort((a, b) => {
+    const aCur = currentTag && a.project.endsWith(currentTag) ? 1 : 0;
+    const bCur = currentTag && b.project.endsWith(currentTag) ? 1 : 0;
+    return bCur - aCur;
+  });
+  return ranked.slice(0, limit);
+}

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

@@ -0,0 +1,112 @@
+import { Type } from "typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+
+import type { ActivationState } from "./activation.js";
+import { searchAstraSessions } from "./sessions.js";
+import { readSummaryCapped, searchPocket, writeNote } from "./store.js";
+
+const INACTIVE_MESSAGE =
+  "Pocket tools are only active in gpt-6-astra sessions with the pocket enabled (/pocket on).";
+
+export interface ToolDeps {
+  state: ActivationState;
+  /** Pocket root directory (~/.pi/agent/astral-pocket). */
+  root: string;
+  /** Sessions directory (~/.pi/agent/sessions). */
+  sessionsDir: string;
+  maxSessionAgeDays: () => number;
+}
+
+function textResult(text: string) {
+  return { content: [{ type: "text" as const, text }], details: {} };
+}
+
+export function registerPocketTools(pi: ExtensionAPI, deps: ToolDeps): void {
+  pi.registerTool({
+    name: "pocket_note",
+    label: "Pocket Note",
+    description:
+      "Write a durable note to your persistent pocket. Notes survive across sessions. Use for decisions, conventions, pitfalls, and preferences worth remembering — never for secrets or ephemeral task state.",
+    promptSnippet: "Save a durable cross-session note to the astral pocket",
+    promptGuidelines: [
+      "Use pocket_note when you learn something durable (a decision and why, a project convention, a pitfall, a user preference) — not for ephemeral task state.",
+      "Never put secrets, credentials, tokens, or personal data in pocket notes.",
+    ],
+    parameters: Type.Object({
+      title: Type.String({ description: "Short note title" }),
+      body: Type.String({ description: "Note content — a few sentences is enough" }),
+      keywords: Type.Optional(Type.Array(Type.String(), { description: "2-5 recall keywords" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      if (!deps.state.active) throw new Error(INACTIVE_MESSAGE);
+      const fileName = await withFileMutationQueue(join(deps.root, "POCKET.md"), async () =>
+        writeNote(deps.root, {
+          title: params.title,
+          body: params.body,
+          keywords: params.keywords,
+          project: ctx.cwd,
+          source: "agent",
+        }),
+      );
+      return textResult(`Note saved to the pocket: notes/${fileName}`);
+    },
+  });
+
+  pi.registerTool({
+    name: "pocket_recall",
+    label: "Pocket Recall",
+    description:
+      "Search your persistent pocket notes and your past gpt-6-astra sessions. Summarized by default (tool names + truncated args/results); pass full: true for larger excerpts. Past-session output can contain sensitive data from earlier work — prefer summarized results.",
+    promptSnippet: "Search pocket notes and past astra sessions",
+    promptGuidelines: [
+      "Use pocket_recall for the quick pocket pass: search with keywords from the pocket summary before deep repo exploration.",
+      "Keep recall cheap: at most 4-6 lookup steps, summarized results first, full: true only when you need exact commands or error text.",
+    ],
+    parameters: Type.Object({
+      query: Type.String({ description: "Keywords to search for (all must match)" }),
+      source: Type.Optional(
+        Type.Union([Type.Literal("pocket"), Type.Literal("sessions"), Type.Literal("both")], {
+          description: "Where to search (default: both)",
+        }),
+      ),
+      full: Type.Optional(Type.Boolean({ description: "Return larger excerpts (default: false)" })),
+      limit: Type.Optional(Type.Number({ description: "Max hits (default: 10)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      if (!deps.state.active) throw new Error(INACTIVE_MESSAGE);
+      const source = params.source ?? "both";
+      const limit = params.limit ?? 10;
+      const sections: string[] = [];
+
+      if (source === "pocket" || source === "both") {
+        const hits = searchPocket(deps.root, params.query, ctx.cwd, limit);
+        sections.push(
+          hits.length === 0
+            ? "Pocket notes: no matches."
+            : `Pocket notes (${hits.length}):\n${hits
+                .map((h) => `- ${h.title} [notes/${h.noteFile}]${h.project ? ` (${h.project})` : ""}\n  ${h.excerpt}`)
+                .join("\n")}`,
+        );
+      }
+
+      if (source === "sessions" || source === "both") {
+        const hits = await searchAstraSessions(deps.sessionsDir, params.query, {
+          full: params.full,
+          limit,
+          maxAgeDays: deps.maxSessionAgeDays(),
+        });
+        sections.push(
+          hits.length === 0
+            ? "Past astra sessions: no matches."
+            : `Past astra sessions (${hits.length}):\n${hits
+                .map((h) => `- [${h.kind}] ${h.timestamp} (${h.project})\n  ${h.excerpt}`)
+                .join("\n")}`,
+        );
+      }
+
+      return textResult(sections.join("\n\n"));
+    },
+  });
+}

package/node_modules/@nklisch/pi-conveniences/extensions/agents-context.ts

@@ -38,16 +38,15 @@ export const RELATIVE_PATH = ".agents/AGENTS.md";
 /** The exact opening tag emitted — also the idempotency sentinel. */
 export const OPEN_TAG = `<project_instructions path="${RELATIVE_PATH}">`;
 
-type SystemPromptOptions = { cwd?: string };
 type BeforeAgentStartEvent = {
   systemPrompt?: string;
-  systemPromptOptions?: SystemPromptOptions;
 };
 type PiApi = {
   on?: (
     event: "before_agent_start",
     handler: (
       event: BeforeAgentStartEvent,
+      ctx?: { cwd?: string },
     ) => { systemPrompt: string } | undefined | void,
   ) => void;
 };
@@ -80,10 +79,9 @@ function readAgentsContext(cwd: string): string | null {
 }
 
 export default function agentsContextExtension(pi: PiApi): void {
-  pi.on?.("before_agent_start", (event) => {
-    const content = readAgentsContext(
-      event?.systemPromptOptions?.cwd ?? process.cwd(),
-    );
+  pi.on?.("before_agent_start", (event, ctx) => {
+    // Pi supplies the active workspace on the event context, not the event.
+    const content = readAgentsContext(ctx?.cwd ?? process.cwd());
     if (!content) return;
     const base = event?.systemPrompt ?? "";
     // Idempotency / double-registration guard. The prompt is rebuilt from base