@rol1n/pi-kit 0.0.0-stage → 0.1.0

package/extensions/image-generate/index.ts

@@ -0,0 +1,200 @@
+/**
+ * image-generate — Image generation tool and model selector.
+ *
+ * Provides:
+ * 1. Tool `image_generate`: Tool call for generating images with local disk persistence.
+ *    Delegates generation to adapters in custom-providers/image (DashScope and OpenRouter).
+ * 2. Command `/image-generate model`: Interactive model picker matching Pi's native model selector UI.
+ */
+
+import { type ExtensionAPI, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Text, type AutocompleteItem } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+import {
+  fetchAllAvailableImageModels,
+  generateImage,
+  resolveImageModel,
+  type ImageModelDefinition,
+} from "../custom-providers/image/index.ts";
+import { saveImageAtomically } from "./files.ts";
+import { DEFAULT_MODEL, registryImageModels, resolveProviderId } from "./models.ts";
+import { SearchableImageModelSelectorComponent } from "./model-selector.ts";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+let currentModel = DEFAULT_MODEL;
+
+// ============================ Extension Entrypoint ============================
+
+export default function imageGenerate(pi: ExtensionAPI): void {
+  // 1. Slash command: /image-generate model [name]
+  pi.registerCommand("image-generate", {
+    description: "Switch default image generation model (/image-generate model [name])",
+    getArgumentCompletions: (prefix: string): AutocompleteItem[] | null => {
+      const trimmed = prefix.trimStart();
+      if (!trimmed || "model".startsWith(trimmed)) {
+        return [{ value: "model", label: "model", description: "Select image generation model in TUI" }];
+      }
+      return null;
+    },
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const parts = args.trim().split(/\s+/).filter(Boolean);
+      const sub = (parts[0] || "").toLowerCase();
+
+      const models = await fetchAllAvailableImageModels(registryImageModels(ctx), ctx.signal);
+
+      // Case: direct model slug provided
+      if (sub === "model" && parts[1]) {
+        const resolved = resolveImageModel(parts.slice(1).join(" "), models);
+        currentModel = resolved;
+        ctx.ui.notify(`Default image model set to: ${resolved}`, "info");
+        return;
+      }
+
+      // Case: bare command or /image-generate model -> open interactive selector
+      if (sub === "model" || parts.length === 0) {
+        // Detect login status for each provider
+        const loginStatusMap = new Map<string, boolean>();
+        for (const m of models) {
+          if (!loginStatusMap.has(m.provider)) {
+            const key = await ctx.modelRegistry.getApiKeyForProvider(m.provider);
+            loginStatusMap.set(
+              m.provider,
+              Boolean(key) || Boolean(process.env[`${m.provider.toUpperCase()}_API_KEY`]),
+            );
+          }
+        }
+
+        const chosenModel = await ctx.ui.custom<ImageModelDefinition | undefined>((tui, theme, _kb, done) => {
+          return new SearchableImageModelSelectorComponent(
+            tui,
+            theme,
+            "Select Image Generation Model",
+            models,
+            currentModel,
+            (model) => done(model),
+            () => done(undefined),
+            (provider) => loginStatusMap.get(provider) ?? false,
+          );
+        });
+
+        if (!chosenModel) return;
+
+        currentModel = chosenModel.id;
+        const isLogged = loginStatusMap.get(chosenModel.provider);
+        const extra = isLogged ? "" : ` (No key detected: please run /login ${chosenModel.provider})`;
+        ctx.ui.notify(`Default image model set to: ${chosenModel.name} (${chosenModel.id})${extra}`, "info");
+        return;
+      }
+
+      // Unknown arguments: report usage instead of silently doing nothing
+      ctx.ui.notify(
+        `Unknown argument: ${parts.join(" ")}. Usage: /image-generate [model] [name]`,
+        "warning",
+      );
+    },
+  });
+
+  // 2. Tool: image_generate (English Schema)
+  pi.registerTool({
+    name: "image_generate",
+    description:
+      "Generate an image from a text prompt using OpenRouter or DashScope. Saves the generated image to local disk and returns the file path.",
+    parameters: Type.Object({
+      prompt: Type.String({
+        description: "The text prompt describing the image to generate.",
+      }),
+      model: Type.Optional(
+        Type.String({
+          description:
+            "Optional model slug (e.g. 'google/gemini-3.1-flash-image', 'qwen-image-3.0-pro', 'black-forest-labs/flux.2-pro'). Defaults to current default model.",
+        }),
+      ),
+      aspectRatio: Type.Optional(
+        Type.String({
+          description: "Optional aspect ratio for the image (e.g., '1:1', '16:9', '9:16', '4:3', '3:4').",
+        }),
+      ),
+      image: Type.Optional(
+        Type.String({
+          description: "Optional local file path or remote image URL for image-to-image reference.",
+        }),
+      ),
+    }),
+    execute: async (_toolCallId, params, signal, ctx) => {
+      const targetModel = params.model
+        ? resolveImageModel(params.model, registryImageModels(ctx))
+        : currentModel;
+      const timeoutSig = AbortSignal.any([AbortSignal.timeout(DEFAULT_TIMEOUT_MS), ...(signal ? [signal] : [])]);
+
+      const providerId = resolveProviderId(ctx, targetModel);
+      const apiKey =
+        (await ctx.modelRegistry.getApiKeyForProvider(providerId)) ||
+        process.env[`${providerId.toUpperCase()}_API_KEY`];
+
+      if (!apiKey) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: No ${providerId} API key found. Please run '/login ${providerId}' or set ${providerId.toUpperCase()}_API_KEY environment variable.`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      try {
+        const res = await generateImage(
+          {
+            prompt: params.prompt,
+            model: targetModel,
+            aspectRatio: params.aspectRatio,
+            image: params.image,
+            cwd: ctx.cwd,
+          },
+          { apiKey, provider: providerId, signal: timeoutSig, cwd: ctx.cwd },
+        );
+
+        const savedPath = await saveImageAtomically(ctx.cwd, res.buffer, res.mimeType);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Image successfully generated using '${res.model}'.\nSaved to: ${savedPath}`,
+            },
+          ],
+          details: {
+            model: res.model,
+            provider: res.provider,
+            savedPath,
+            prompt: params.prompt,
+            revisedPrompt: res.revisedPrompt,
+          },
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Image generation failed: ${err?.message ?? String(err)}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+    renderCall(args, theme) {
+      const { prompt, model } = args as { prompt?: string; model?: string };
+      const displayModel = model || currentModel;
+      const preview = prompt ? (prompt.length > 50 ? prompt.slice(0, 47) + "..." : prompt) : "";
+      return new Text(
+        theme.fg("toolTitle", theme.bold("generate_image ")) +
+          theme.fg("dim", `[${displayModel}] `) +
+          theme.fg("accent", `"${preview}"`),
+      );
+    },
+  });
+}

package/extensions/image-generate/model-selector.ts

@@ -0,0 +1,150 @@
+import { Container, Input, Spacer, Text, fuzzyFilter, getKeybindings } from "@earendil-works/pi-tui";
+import type { ImageModelDefinition } from "../custom-providers/image/index.ts";
+
+export class SearchableImageModelSelectorComponent extends Container {
+  private searchInput: Input;
+  private listContainer: Container;
+  private selectedIndex = 0;
+  private filteredModels: ImageModelDefinition[] = [];
+  private _focused = true;
+
+  get focused() {
+    return this._focused;
+  }
+  set focused(value: boolean) {
+    this._focused = value;
+    this.searchInput.focused = value;
+  }
+
+  constructor(
+    private tui: any,
+    private theme: any,
+    private title: string,
+    private models: ImageModelDefinition[],
+    private currentModelId: string,
+    private onSelect: (model: ImageModelDefinition) => void,
+    private onCancel: () => void,
+    private getLoginStatus?: (provider: string) => boolean,
+  ) {
+    super();
+    this.filteredModels = [...models];
+    const curIdx = models.findIndex((m) => m.id === currentModelId);
+    this.selectedIndex = curIdx >= 0 ? curIdx : 0;
+
+    this.searchInput = new Input();
+    this.searchInput.focused = true;
+    this.listContainer = new Container();
+
+    this.updateList();
+  }
+
+  filterModels(query: string) {
+    const q = query.trim().toLowerCase();
+    if (q) {
+      this.filteredModels = fuzzyFilter(
+        this.models,
+        q,
+        (m) => `${m.id} ${m.name} ${m.provider} ${m.description}`,
+      );
+    } else {
+      this.filteredModels = [...this.models];
+    }
+    this.selectedIndex = q ? 0 : Math.min(this.selectedIndex, Math.max(0, this.filteredModels.length - 1));
+    this.updateList();
+    this.tui.requestRender?.();
+  }
+
+  updateList() {
+    this.listContainer.clear();
+    const maxVisible = 6;
+    const total = this.filteredModels.length;
+
+    if (total === 0) {
+      this.listContainer.addChild(new Text(this.theme.fg("muted", "  No matching models"), 0, 0));
+      return;
+    }
+
+    const startIndex = Math.max(0, Math.min(this.selectedIndex - Math.floor(maxVisible / 2), total - maxVisible));
+    const endIndex = Math.min(startIndex + maxVisible, total);
+
+    for (let i = startIndex; i < endIndex; i++) {
+      const item = this.filteredModels[i];
+      const isSelected = i === this.selectedIndex;
+      const isCurrent = item.id === this.currentModelId;
+
+      const cursor = isSelected ? this.theme.fg("accent", "→ ") : "  ";
+      const check = isCurrent ? this.theme.fg("accent", "✓ ") : "  ";
+      const modelText = isSelected
+        ? this.theme.fg("accent", this.theme.bold ? this.theme.bold(item.id) : item.id)
+        : this.theme.fg("text", item.id);
+      const providerBadge = this.theme.fg("muted", `[${item.provider}]`);
+
+      let authBadge = "";
+      if (this.getLoginStatus) {
+        const loggedIn = this.getLoginStatus(item.provider);
+        authBadge = loggedIn
+          ? this.theme.fg("dim", " · logged in")
+          : this.theme.fg("warning", ` · not logged in: /login ${item.provider}`);
+      }
+
+      const line = `${cursor}${check}${modelText} ${providerBadge}${authBadge}`;
+      this.listContainer.addChild(new Text(line, 0, 0));
+    }
+
+    if (startIndex > 0 || endIndex < total) {
+      const scrollInfo = this.theme.fg("muted", `  (${this.selectedIndex + 1}/${total})`);
+      this.listContainer.addChild(new Text(scrollInfo, 0, 0));
+    }
+
+    const selected = this.filteredModels[this.selectedIndex];
+    if (selected) {
+      this.listContainer.addChild(new Spacer(1));
+      this.listContainer.addChild(
+        new Text(this.theme.fg("muted", `  Model: ${selected.name} — ${selected.description}`), 0, 0),
+      );
+    }
+  }
+
+  render(width: number): string[] {
+    this.clear();
+    const border = this.theme.fg("accent", "─".repeat(Math.max(10, width)));
+
+    this.addChild(new Text(border, 0, 0));
+    this.addChild(new Spacer(1));
+    this.addChild(new Text(this.theme.fg("accent", this.theme.bold ? this.theme.bold(`  ${this.title}`) : `  ${this.title}`), 0, 0));
+    this.addChild(new Spacer(1));
+    this.addChild(this.searchInput);
+    this.addChild(new Spacer(1));
+    this.addChild(this.listContainer);
+    this.addChild(new Spacer(1));
+    this.addChild(new Text(this.theme.fg("dim", "  Enter to select · Escape to cancel"), 0, 0));
+    this.addChild(new Text(border, 0, 0));
+
+    return super.render(width);
+  }
+
+  handleInput(keyData: string) {
+    const kb = getKeybindings();
+    if (kb.matches(keyData, "tui.select.up") || keyData === "k") {
+      if (this.filteredModels.length === 0) return;
+      this.selectedIndex = this.selectedIndex === 0 ? this.filteredModels.length - 1 : this.selectedIndex - 1;
+      this.updateList();
+      this.tui.requestRender?.();
+    } else if (kb.matches(keyData, "tui.select.down") || keyData === "j") {
+      if (this.filteredModels.length === 0) return;
+      this.selectedIndex = this.selectedIndex === this.filteredModels.length - 1 ? 0 : this.selectedIndex + 1;
+      this.updateList();
+      this.tui.requestRender?.();
+    } else if (kb.matches(keyData, "tui.select.confirm") || keyData === "\n" || keyData === "\r") {
+      const selected = this.filteredModels[this.selectedIndex];
+      if (selected) {
+        this.onSelect(selected);
+      }
+    } else if (kb.matches(keyData, "tui.select.cancel") || keyData === "\x1b" || keyData === "\x03") {
+      this.onCancel();
+    } else {
+      this.searchInput.handleInput(keyData);
+      this.filterModels(this.searchInput.getValue());
+    }
+  }
+}

package/extensions/image-generate/models.ts

@@ -0,0 +1,19 @@
+/** 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";
+}

package/extensions/memory-log/README.md

@@ -0,0 +1,54 @@
+# memory-log
+
+Observational memory for long Pi sessions: background observers distill conversation chunks, a ledger records observations, and a consolidator writes durable project memory. Compaction rebuilds context from the recorded memory and recent conversation.
+
+## Install
+
+```sh
+pi install npm:@rol1n/memory-log
+```
+
+Also included in `@rol1n/pi-kit`. The extension loads with new-session memory disabled by default.
+
+## Commands
+
+| Command | Action |
+|---|---|
+| `/mem-log on` / `/mem-log off` | Set the current session's memory gate |
+| `/mem-log status` or `/mem-log:status` | Inspect observation progress, workers, memory, and costs |
+| `/mem-log compact` or `/mem-log:compact` | Request compaction |
+| `/mem-log consolidate` or `/mem-log:consolidate` | Consolidate the observation pool |
+
+## Settings
+
+Add `memoryLog` to personal or project Pi settings. Project values override personal values:
+
+```json
+{
+  "memoryLog": {
+    "defaultEnabled": false,
+    "chunkTokens": 10000,
+    "poolTargetTokens": 10000,
+    "consolidateAtPoolTokens": 15000,
+    "compactAtContextTokens": 150000,
+    "tailTokens": 20000,
+    "journeyTargetTokens": 1000,
+    "observerConcurrency": 4,
+    "resumeAfterMidRunCompaction": true,
+    "passive": false,
+    "debugLog": false,
+    "models": {
+      "observer": { "thinking": "low" },
+      "consolidator": { "thinking": "medium" }
+    }
+  }
+}
+```
+
+Observer and consolidator model objects accept `provider`, `id`, and `thinking`. An explicitly configured model takes priority over the session model, followed by Pi's configured default model. `chunkOverlapTokens` defaults to zero.
+
+Environment overrides are `PI_OM_PASSIVE`, `PI_OM_OBSERVER_PROVIDER`, `PI_OM_OBSERVER_MODEL`, `PI_OM_OBSERVER_THINKING`, and the corresponding `PI_OM_CONSOLIDATOR_*` values. Passive mode disables automatic triggers separately from the session gate.
+
+## Storage and requirements
+
+Durable files live under `.memory/<session-id>/` in the working project, including topic files and `JOURNEY.md`. Gate changes and observation history are recorded in the Pi session ledger. Observer and consolidator workers require the `pi` executable and model credentials; they make additional model requests. Disabling memory aborts active background workers.

package/extensions/memory-log/agent/consolidator/prompt.ts

@@ -0,0 +1,47 @@
+export const CONSOLIDATOR_SYSTEM = `You are the consolidation agent for a coding assistant's long-term memory.
+
+Your job: take a batch of older observations (timestamped facts distilled from earlier conversation) and fold them into durable topic files under .memory/. These topic files are the assistant's permanent, cross-session memory of this project. The observations you are given are about to be deleted from the short-term buffer, so anything worth keeping that you fail to record here is forgotten forever.
+
+You operate entirely on .memory/. You have scoped tools: read, write, edit, ls, grep — all confined to the .memory/ directory. You CANNOT touch anything outside .memory/. Do NOT create or edit INDEX.md; it is generated automatically from your topic files' front-matter — your job is the <topic>.md files plus JOURNEY.md (described below).
+
+How you work:
+1. Run ls to see existing topic files, and read the ones relevant to the incoming observations.
+2. For each incoming observation, decide where it belongs: an existing topic file, or a new one.
+3. Write/edit topic files so each holds clean, current-state prose about its topic.
+4. Update JOURNEY.md (see below) with a short segment covering this batch.
+5. When every incoming observation has been folded in (or deliberately discarded as low-value/noise), emit a one-sentence confirmation and stop.
+
+Topic routing (start conservative — prefer fewer, larger topics; split only when a file clearly covers two unrelated subjects):
+- Create a topic when the observations introduce a genuinely new subject with no existing home.
+- Merge into an existing topic when the observations extend or update it.
+- Split a topic only when it has grown to cover clearly distinct subjects.
+
+Writing topic files:
+- Write current-state prose, not a changelog. If an observation supersedes an existing fact, REWRITE the file to reflect the new truth and delete the obsolete statement. Do not leave "was X, now Y" cruft or tombstones.
+- Preserve distinguishing detail: file paths, identifiers, package/function names, error codes, exact numbers, the user's own terminology (quote unusual terms verbatim).
+- Keep prose tight and skimmable. Headings and short paragraphs or bullet lists are fine. This is reference material the assistant will read later.
+- Preserve the authoritative/assertion vs question distinction the observations carry. User assertions are authoritative.
+
+JOURNEY.md — the running project history (orientation, not a topic file):
+- Purpose: ONE brief, free-form narrative of how this project/work reached its current state, so a future reader can orient to the rough arc of how we got here. Its current contents are provided in your prompt; you rewrite the whole file with the write tool. It has NO front-matter and is not a topic file.
+- STRICTLY DESCRIPTIVE. Write only what happened, in the past tense. Do NOT include recommendations, next steps, TODOs, plans, advice, warnings, predictions, open questions framed as tasks, or evaluative judgement. No "should", "needs to", "the goal is", "next we". If you catch yourself steering future behaviour, delete that sentence. It exists purely to orient, never to instruct.
+- Keep it ROUGH and high-level: the shape of the journey, not a detailed log. Topic files already hold the details.
+- APPEND-MOSTLY: add one short dated segment (2-5 sentences) describing the arc that THIS batch of observations represents, using a '## <date>' heading and the current time from your prompt. Leave existing recent segments intact — do not rewrite them.
+- THIS BATCH IS NOT THE END OF THE SESSION. The session was still running when you were invoked — these observations are an early or mid-session slice; newer conversation exists beyond this batch that has not been consolidated yet. Never write as if this batch edge is the current moment. Forbidden phrases: "by session end", "at the end of the session", "the session concluded", "work remaining", or anything framed as the present state. Use past-arc language instead: "during this period", "by this point", "at this stage of the session".
+- COMPRESS THE OLD TAIL ONLY WHEN OVER SIZE: if the file would exceed the token budget given in your prompt, condense the OLDEST segments into a tighter summary at the top, preserving the most recent segments in more detail. Recent history stays detailed; the distant past gets condensed. Never grow the file unbounded.
+- Order chronologically, oldest first (a compressed early-history summary may lead).
+
+Front-matter (REQUIRED at the top of every topic file you write):
+---
+id: <stable-slug>            # matches the filename without .md, e.g. "auth" for auth.md
+title: <short human title>
+summary: <one line, <= 140 chars; what this file covers — this is what the assistant sees in the index>
+updated: <the current date/time provided in your prompt>
+---
+Maintain these fields whenever you write a file. The summary is load-bearing: it is the ONLY thing the assistant sees about this file until it opens it, so make it specific.
+
+Filenames: lowercase kebab-case slugs ending in .md (e.g. auth.md, deploy-pipeline.md, user-preferences.md). The id must equal the filename without .md.
+
+Completion:
+- When done, emit a one-sentence plain-text confirmation and stop. The run ends on its own.
+- The whole incoming batch leaves the short-term buffer once you finish, whether you filed it or judged it not worth keeping — you do not report back. So make sure everything worth keeping has been written to a file before you stop. Discarding clear noise is fine and expected; dropping a genuine fact you meant to keep is the failure to avoid.`;

package/extensions/memory-log/agent/consolidator/tools.ts

@@ -0,0 +1,160 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { Static } from "typebox";
+import { atomicWrite } from "../../memory/paths.ts";
+
+type ToolText = { content: { type: "text"; text: string }[]; details: unknown };
+
+function ok(text: string, details: unknown = {}): ToolText {
+  return { content: [{ type: "text" as const, text }], details };
+}
+
+function fail(text: string): ToolText {
+  return { content: [{ type: "text" as const, text: `Error: ${text}` }], details: { error: true } };
+}
+
+function scoped(root: string, requested: string): string | undefined {
+  const abs = resolve(root, requested);
+  const rel = relative(root, abs);
+  if (rel === "") return abs;
+  if (rel.startsWith("..")) return undefined;
+  return abs;
+}
+
+const ReadSchema = Type.Object({
+  path: Type.String({ description: "Path inside .memory/, e.g. 'auth.md' or '.memory/auth.md'." }),
+});
+const WriteSchema = Type.Object({
+  path: Type.String({ description: "Path inside .memory/ to (over)write, e.g. 'auth.md'." }),
+  content: Type.String({ description: "Full file content, including YAML front-matter." }),
+});
+const EditSchema = Type.Object({
+  path: Type.String({ description: "Path inside .memory/ to edit." }),
+  oldText: Type.String({ description: "Exact text to replace (must occur exactly once)." }),
+  newText: Type.String({ description: "Replacement text." }),
+});
+const LsSchema = Type.Object({
+  path: Type.Optional(Type.String({ description: "Subdirectory inside .memory/. Defaults to .memory/ root." })),
+});
+const GrepSchema = Type.Object({
+  pattern: Type.String({ description: "JavaScript regular expression to search for." }),
+  path: Type.Optional(Type.String({ description: "Restrict to this file/subdir inside .memory/." })),
+});
+
+type ReadInput = Static<typeof ReadSchema>;
+type WriteInput = Static<typeof WriteSchema>;
+type EditInput = Static<typeof EditSchema>;
+type LsInput = Static<typeof LsSchema>;
+type GrepInput = Static<typeof GrepSchema>;
+
+function listFilesRecursive(dir: string): string[] {
+  const out: string[] = [];
+  for (const name of readdirSync(dir)) {
+    if (name.startsWith(".")) continue;
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) out.push(...listFilesRecursive(full));
+    else out.push(full);
+  }
+  return out;
+}
+
+export function registerConsolidatorTools(pi: ExtensionAPI, memoryRoot: string): void {
+  const root = resolve(memoryRoot);
+
+  pi.registerTool({
+    name: "read",
+    label: "Read memory file",
+    description: "Read a topic file under .memory/.",
+    parameters: ReadSchema,
+    async execute(_id: string, params: ReadInput): Promise<ToolText> {
+      const abs = scoped(root, params.path);
+      if (!abs) return fail("path escapes .memory/");
+      if (!existsSync(abs)) return fail(`no such file: ${params.path}`);
+      return ok(readFileSync(abs, "utf-8"));
+    },
+  });
+
+  pi.registerTool({
+    name: "write",
+    label: "Write memory file",
+    description: "Create or overwrite a topic file under .memory/ (atomic). Do not write INDEX.md.",
+    parameters: WriteSchema,
+    async execute(_id: string, params: WriteInput): Promise<ToolText> {
+      const abs = scoped(root, params.path);
+      if (!abs) return fail("path escapes .memory/");
+      if (/(^|\/)INDEX\.md$/i.test(params.path)) return fail("INDEX.md is generated automatically; do not write it");
+      atomicWrite(abs, params.content);
+      return ok(`Wrote ${params.path} (${params.content.length} bytes).`);
+    },
+  });
+
+  pi.registerTool({
+    name: "edit",
+    label: "Edit memory file",
+    description: "Replace an exact substring in a topic file under .memory/ (atomic).",
+    parameters: EditSchema,
+    async execute(_id: string, params: EditInput): Promise<ToolText> {
+      const abs = scoped(root, params.path);
+      if (!abs) return fail("path escapes .memory/");
+      if (/(^|\/)INDEX\.md$/i.test(params.path)) return fail("INDEX.md is generated automatically; do not edit it");
+      if (!existsSync(abs)) return fail(`no such file: ${params.path}`);
+      const current = readFileSync(abs, "utf-8");
+      const occurrences = current.split(params.oldText).length - 1;
+      if (occurrences === 0) return fail("oldText not found");
+      if (occurrences > 1) return fail(`oldText is ambiguous (${occurrences} matches); add more context`);
+      atomicWrite(abs, current.replace(params.oldText, params.newText));
+      return ok(`Edited ${params.path}.`);
+    },
+  });
+
+  pi.registerTool({
+    name: "ls",
+    label: "List memory files",
+    description: "List files under .memory/.",
+    parameters: LsSchema,
+    async execute(_id: string, params: LsInput): Promise<ToolText> {
+      const targetDir = params.path ? scoped(root, params.path) : root;
+      if (!targetDir) return fail("path escapes .memory/");
+      if (!existsSync(targetDir)) return fail(`no such directory: ${params.path ?? "."}`);
+      const files = listFilesRecursive(targetDir).map((p) => relative(root, p));
+      return ok(files.length > 0 ? files.join("\n") : "(empty directory)");
+    },
+  });
+
+  pi.registerTool({
+    name: "grep",
+    label: "Search memory files",
+    description: "Search topic files under .memory/ using a regular expression.",
+    parameters: GrepSchema,
+    async execute(_id: string, params: GrepInput): Promise<ToolText> {
+      let re: RegExp;
+      try {
+        re = new RegExp(params.pattern);
+      } catch (error) {
+        return fail(`invalid regex: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      const target = params.path ? scoped(root, params.path) : root;
+      if (!target) return fail("path escapes .memory/");
+      if (!existsSync(target)) return fail(`no such file/directory: ${params.path ?? "."}`);
+
+      const files = statSync(target).isDirectory() ? listFilesRecursive(target) : [target];
+      const matches: string[] = [];
+      for (const file of files) {
+        const rel = relative(root, file);
+        let content: string;
+        try {
+          content = readFileSync(file, "utf-8");
+        } catch {
+          continue;
+        }
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+          if (re.test(lines[i])) matches.push(`${rel}:${i + 1}: ${lines[i]}`);
+        }
+      }
+      return ok(matches.length > 0 ? matches.join("\n") : "(no matches)");
+    },
+  });
+}

package/extensions/memory-log/agent/cost.ts

@@ -0,0 +1,32 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { writeWorkerCost } from "../spawn/runs.ts";
+
+type CostUsage = { cost?: { total?: unknown } };
+type MaybeAssistantMessage = { role?: string; usage?: CostUsage };
+
+/**
+ * Register shared cost accumulation for subprocess workers.
+ */
+export function trackWorkerCost(pi: ExtensionAPI): void {
+  const costPath = process.env.OM_COST_PATH;
+  if (!costPath) return;
+
+  let costUsd = 0;
+
+  pi.on("message_end", async (event: { message?: MaybeAssistantMessage }) => {
+    const message = event?.message;
+    if (message?.role !== "assistant") return;
+    const total = message.usage?.cost?.total;
+    if (typeof total === "number" && Number.isFinite(total) && total > 0) {
+      costUsd += total;
+    }
+  });
+
+  pi.on("agent_end", async () => {
+    try {
+      writeWorkerCost(costPath, { costUsd });
+    } catch {
+      // ignore — cost is non-critical telemetry
+    }
+  });
+}