@jaybeeuu/agent-cortex 1.20.0

package/extensions/lib/tiny-model.ts

@@ -0,0 +1,212 @@
+/**
+ * Shared helpers for making cheap LLM calls from extensions.
+ *
+ * Reads a `tinyModel` config key from settings.json (global + project merged)
+ * and provides functions for session naming and response summarization using
+ * the configured model — typically the tiniest free model available.
+ *
+ * Config (in ~/.pi/agent/settings.json or .pi/settings.json):
+ * ```json
+ * {
+ *   "tinyModel": {
+ *     "model": "opencode/mimo-v2.5-free",
+ *     "maxNameLength": 50,
+ *     "maxSummaryLength": 100
+ *   }
+ * }
+ * ```
+ */
+
+import { complete } from "@earendil-works/pi-ai";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync, existsSync } from "node:fs";
+import type { Model, Api } from "@earendil-works/pi-ai";
+
+/* ── Types ── */
+
+export interface TinyModelConfig {
+  /** Provider/id string, e.g. "opencode/mimo-v2.5-free" */
+  model: string;
+  /** Global on/off toggle */
+  enabled: boolean;
+  /** Max characters for auto-generated session names */
+  maxNameLength: number;
+  /** Max characters for response summaries in notifications */
+  maxSummaryLength: number;
+}
+
+const DEFAULT_CONFIG: TinyModelConfig = {
+  model: "opencode/mimo-v2.5-free",
+  enabled: true,
+  maxNameLength: 40,
+  maxSummaryLength: 100,
+};
+
+/* ── Config loading ── */
+
+/**
+ * Load tiny-model config from merged global + project settings.
+ *
+ * Project .pi/settings.json overrides global ~/.pi/agent/settings.json.
+ */
+export function loadTinyModelConfig(cwd?: string): TinyModelConfig {
+  const paths = [join(homedir(), ".pi", "agent", "settings.json")];
+  if (cwd) paths.push(join(cwd, ".pi", "settings.json"));
+
+  const merged: Record<string, any> = {};
+
+  for (const filePath of paths) {
+    try {
+      if (existsSync(filePath)) {
+        const raw = readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.tinyModel && typeof parsed.tinyModel === "object") {
+          Object.assign(merged, parsed.tinyModel);
+        }
+      }
+    } catch {
+      // skip unreadable or invalid settings files
+    }
+  }
+
+  return { ...DEFAULT_CONFIG, ...merged } as TinyModelConfig;
+}
+
+/**
+ * Parse a "provider/id" string into its parts.
+ */
+export function parseModelString(modelStr: string): {
+  provider: string;
+  id: string;
+} {
+  const slash = modelStr.indexOf("/");
+  if (slash === -1) return { provider: "opencode", id: modelStr };
+  return {
+    provider: modelStr.slice(0, slash),
+    id: modelStr.slice(slash + 1),
+  };
+}
+
+/* ── LLM helpers ── */
+
+type ModelAny = Model<Api>;
+type CompleteOptions = Record<string, any>;
+
+/**
+ * Generate a concise session title from the user's first prompt.
+ *
+ * Calls the configured tiny model with a system prompt tuned for naming.
+ * Returns null on failure (caller should fall back to truncation).
+ */
+export async function generateNameFromPrompt(
+  model: ModelAny,
+  apiKey: string | undefined,
+  headers: Record<string, string> | undefined,
+  prompt: string,
+  maxLength: number,
+): Promise<string | null> {
+  const systemPrompt = [
+    "You are a session naming assistant. Generate a concise title for a coding session.",
+    "",
+    "Rules:",
+    "- Output ONLY the title, no quotes, no prefix, no explanation",
+    `- Maximum ${maxLength} characters`,
+    "- Summarize intent, do not copy verbatim",
+    "- Keep it short (3\u20135 words), capture the general theme",
+    "- If the message mentions files or modules, keep the key names brief",
+  ].join("\n");
+
+  const truncated = prompt.length > 2000 ? prompt.slice(0, 2000) + "..." : prompt;
+
+  try {
+    const options: CompleteOptions = { maxTokens: 64 };
+    if (apiKey) options.apiKey = apiKey;
+    if (headers) options.headers = headers;
+
+    const result = await complete(model, {
+      systemPrompt,
+      messages: [{ role: "user", content: truncated, timestamp: Date.now() }],
+    }, options);
+
+    const text = result.content
+      ?.filter((b: any): b is { type: "text"; text: string } => b.type === "text")
+      ?.map((b) => b.text)
+      ?.join("")
+      ?.trim() ?? "";
+
+    return cleanTitle(text, maxLength);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Summarize an assistant response into a one-line summary.
+ *
+ * Calls the configured tiny model. Returns null on failure.
+ */
+export async function summarizeResponseText(
+  model: ModelAny,
+  apiKey: string | undefined,
+  headers: Record<string, string> | undefined,
+  responseText: string,
+  maxLength: number,
+): Promise<string | null> {
+  const systemPrompt = [
+    "Summarize what the AI assistant did in this coding session response.",
+    "Be concise — one short sentence or phrase.",
+    `Maximum ${maxLength} characters.`,
+    "Focus on what changed or was accomplished.",
+    "Output ONLY the summary, no quotes, no prefix, no explanation.",
+  ].join("\n");
+
+  const truncated =
+    responseText.length > 2000 ? responseText.slice(0, 2000) + "..." : responseText;
+
+  try {
+    const options: CompleteOptions = { maxTokens: 64 };
+    if (apiKey) options.apiKey = apiKey;
+    if (headers) options.headers = headers;
+
+    const result = await complete(model, {
+      systemPrompt,
+      messages: [{ role: "user", content: truncated, timestamp: Date.now() }],
+    }, options);
+
+    const text = result.content
+      ?.filter((b: any): b is { type: "text"; text: string } => b.type === "text")
+      ?.map((b) => b.text)
+      ?.join("")
+      ?.trim() ?? "";
+
+    return text || null;
+  } catch {
+    return null;
+  }
+}
+
+/* ── Internal helpers ── */
+
+function cleanTitle(raw: string, maxLength: number): string | null {
+  let name = raw.trim();
+  if (!name) return null;
+
+  // Strip surrounding quotes if present
+  if (
+    (name.startsWith('"') && name.endsWith('"')) ||
+    (name.startsWith("'") && name.endsWith("'"))
+  ) {
+    name = name.slice(1, -1);
+  }
+
+  // Collapse newlines
+  name = name.replace(/\n/g, " ").trim();
+
+  // Truncate
+  if (name.length > maxLength) {
+    name = name.slice(0, maxLength - 3) + "...";
+  }
+
+  return name || null;
+}

package/extensions/notify/index.ts

@@ -0,0 +1,293 @@
+/**
+ * Desktop notification + terminal bell on task completion.
+ *
+ * Fires after multi-turn or long-running tasks (>1 turn or >30s) with a
+ * multiline notification showing:
+ *   Line 1: working directory path
+ *   Line 2: session name (if set)
+ *   Line 3: LLM-generated summary of what the agent did
+ *
+ * The notification title is the tmux session:window.pane identifier (when
+ * available) or "pi".
+ *
+ * Response summarization uses the tiny model configured in settings.json
+ * under the `tinyModel` key.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { execSync } from "node:child_process";
+import { homedir } from "node:os";
+
+import {
+  loadTinyModelConfig,
+  parseModelString,
+  summarizeResponseText,
+} from "../lib/tiny-model.js";
+import type { TinyModelConfig } from "../lib/tiny-model.js";
+
+/* ── Context helpers ── */
+
+/**
+ * Get the tmux session:window.pane identifier, or undefined if not in tmux.
+ */
+function getTmuxLabel(): string | undefined {
+  if (!process.env.TMUX) return undefined;
+  try {
+    return execSync(
+      'tmux display-message -p "#{session_name}:#{window_index}.#{pane_index}"',
+      { encoding: "utf-8", timeout: 2000 },
+    ).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Format a working directory path for display.
+ *
+ * Replaces $HOME with ~ and truncates from the left to ~40 chars when the
+ * path is too long, keeping the trailing directory name visible.
+ */
+function formatTruncatedPath(cwd: string): string {
+  const home = homedir();
+  let display = cwd;
+  if (display.startsWith(home)) {
+    display = "~" + display.slice(home.length);
+  }
+
+  const maxLen = 40;
+  if (display.length <= maxLen) return display;
+
+  const head = "~\u2026/";
+  const tailLen = maxLen - head.length;
+  if (tailLen <= 0) return display.slice(-maxLen);
+
+  return head + display.slice(-tailLen);
+}
+
+/**
+ * Extract plain text from the last assistant response for summarization.
+ *
+ * Returns the concatenated text content of the last assistant message,
+ * or empty string if none found.
+ */
+function extractAssistantText(messages: AgentMessage[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.role !== "assistant") continue;
+
+    const texts = msg.content
+      .filter(
+        (b): b is { type: "text"; text: string } => b.type === "text",
+      )
+      .map((b) => b.text)
+      .filter(Boolean);
+
+    if (texts.length === 0) continue;
+
+    return texts.join(" ").trim();
+  }
+  return "";
+}
+
+/* ── Desktop notification helpers (OSC 777 / 99 / 9) ── */
+
+function wrapForTmux(sequence: string): string {
+  if (!process.env.TMUX) return sequence;
+  const escaped = sequence.split("\x1b").join("\x1b\x1b");
+  return `\x1bPtmux;${escaped}\x1b\\`;
+}
+
+function notifyOSC777(title: string, body: string): void {
+  process.stdout.write(wrapForTmux(`\x1b]777;notify;${title};${body}\x07`));
+}
+
+function notifyOSC9(message: string): void {
+  process.stdout.write(wrapForTmux(`\x1b]9;${message}\x07`));
+}
+
+function notifyOSC99(title: string, body: string): void {
+  // d=1 = persistent notification (stays until dismissed)
+  process.stdout.write(wrapForTmux(`\x1b]99;i=1:d=1;${title}\x1b\\`));
+  process.stdout.write(wrapForTmux(`\x1b]99;i=1:p=body;${body}\x1b\\`));
+}
+
+function sendDesktopNotification(title: string, sections: string[]): void {
+  const isIterm2 =
+    process.env.TERM_PROGRAM === "iTerm.app" ||
+    Boolean(process.env.ITERM_SESSION_ID);
+
+  // Flatten sections into a single notification body for non-Windows paths
+  const body = sections.join(" \u00b7 ");
+
+  if (process.env.KITTY_WINDOW_ID) {
+    notifyOSC99(title, body);
+  } else if (isIterm2) {
+    notifyOSC9(`${title}: ${body}`);
+  } else if (process.env.WT_SESSION || process.platform === 'win32') {
+    // Windows Terminal / Windows — PowerShell toast via execFileSync
+    const { execFileSync } = require("node:child_process");
+    const script = buildWindowsToastScript(title, sections);
+    try {
+      execFileSync("powershell.exe", ["-NoProfile", "-Command", script], { timeout: 5000 });
+    } catch (e) {
+      console.warn("[notify] toast failed:", e.message);
+    }
+  } else {
+    notifyOSC777(title, body);
+  }
+}
+
+function buildWindowsToastScript(title: string, sections: string[]): string {
+  // Escape single quotes for PowerShell single-quoted strings: double them up
+  const esc = (s: string) => s.replace(/'/g, "''").replace(/\r/g, '');
+  const psTitle = esc(title);
+
+  // Use ToastText04 for up to 4 text elements (title + 3 body sections)
+  const template = [
+    `[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null`,
+    `$t = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText04)`,
+    `$null = $t.SelectSingleNode('/toast').SetAttribute('scenario', 'persistent')`,
+    // Title goes to text[0], body sections to text[1-3]
+    `$null = $t.SelectSingleNode('//text[@id=1]').AppendChild($t.CreateTextNode('${psTitle}'))`,
+  ];
+
+  for (let i = 0; i < Math.min(sections.length, 3); i++) {
+    const escaped = esc(sections[i]);
+    template.push(`$null = $t.SelectSingleNode('//text[@id=${i + 2}]').AppendChild($t.CreateTextNode('${escaped}'))`);
+  }
+
+  template.push(`$toast = [Windows.UI.Notifications.ToastNotification]::new($t)`);
+  template.push(`[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('pi').Show($toast) > $null`);
+
+  return template.join("; ");
+}
+
+/* ── Bell ── */
+
+function ringBell(): void {
+  try {
+    const { openSync, writeSync, closeSync } = require("node:fs");
+    const fd = openSync("/dev/tty", "w");
+    writeSync(fd, "\x07");
+    closeSync(fd);
+  } catch {
+    process.stdout.write("\x07");
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  let agentStartTime = 0;
+  let turnCount = 0;
+  let config: TinyModelConfig;
+
+  pi.on("session_start", async (_event, ctx) => {
+    config = loadTinyModelConfig(ctx.cwd);
+  });
+
+  pi.on("agent_start", async () => {
+    agentStartTime = Date.now();
+    turnCount = 0;
+  });
+
+  pi.on("turn_end", async () => {
+    turnCount++;
+  });
+
+  pi.on("agent_end", async (event, ctx) => {
+    const elapsed = Date.now() - agentStartTime;
+
+    // Only notify on multi-turn or long tasks — not on quick chat replies
+    if (turnCount === 1 && elapsed < 30_000) return;
+
+    // ── Title: path · tmux identifier (prominent notification header) ──
+    const tmuxLabel = getTmuxLabel();
+    const truncatedPath = formatTruncatedPath(ctx.cwd);
+    const title = tmuxLabel
+      ? `${truncatedPath}  \u00b7  ${tmuxLabel}`
+      : truncatedPath;
+
+    // ── Body: sections separated by a blank line ──
+    const sections: string[] = [];
+
+    // Section 1: session name (if set)
+    const sessionName = pi.getSessionName();
+    if (sessionName) sections.push(sessionName);
+
+    // Section 2: LLM-generated summary of the assistant's response
+    const responseText = extractAssistantText(event.messages);
+    if (responseText) {
+      try {
+        const summary = await summarizeResponseWithFallback(
+          ctx,
+          responseText,
+          config,
+        );
+        sections.push(summary);
+      } catch {
+        // If summary fails (e.g. config not loaded), just show raw text
+        sections.push(responseText.slice(0, config?.maxSummaryLength ?? 100).replace(/\s+/g, ' ').trim());
+      }
+    }
+
+    // Desktop notification
+    sendDesktopNotification(title, sections);
+
+    // Terminal bell (tmux catches this via monitor-bell + visual-bell)
+    ringBell();
+  });
+}
+
+/**
+ * Summarize response text using the configured tiny model, falling back
+ * to simple truncation if the LLM call fails or is disabled.
+ */
+async function summarizeResponseWithFallback(
+  ctx: any,
+  responseText: string,
+  config: TinyModelConfig,
+): Promise<string> {
+  if (!config.enabled) {
+    return truncateToOneLine(responseText, config.maxSummaryLength);
+  }
+
+  try {
+    const { provider, id } = parseModelString(config.model);
+    const model = ctx.modelRegistry.find(provider, id);
+    if (!model) {
+      return truncateToOneLine(responseText, config.maxSummaryLength);
+    }
+
+    const { apiKey, headers } =
+      await ctx.modelRegistry.getApiKeyAndHeaders(model);
+
+    const summary = await summarizeResponseText(
+      model,
+      apiKey,
+      headers,
+      responseText,
+      config.maxSummaryLength,
+    );
+
+    if (summary) return summary;
+  } catch (err) {
+    console.warn("[notify] LLM summary failed, falling back:", err);
+  }
+
+  return truncateToOneLine(responseText, config.maxSummaryLength);
+}
+
+/**
+ * Truncate text to roughly `maxLen` characters on a single line,
+ * breaking at a word boundary.
+ */
+function truncateToOneLine(text: string, maxLen: number): string {
+  const singleLine = text.replace(/\s+/g, " ").trim();
+  if (singleLine.length <= maxLen) return singleLine;
+
+  const breakPoint = singleLine.lastIndexOf(" ", maxLen - 1);
+  const truncated =
+    breakPoint > 0 ? singleLine.slice(0, breakPoint) : singleLine.slice(0, maxLen);
+  return truncated + " \u2026";
+}

package/extensions/session-start.ts

@@ -0,0 +1,44 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadSessionContext } from "./context-loader.js";
+
+/**
+ * Session-start extension.
+ *
+ * Injects baseline context at the start of every PI session:
+ * 1. Skill availability hints (so the agent knows they exist)
+ * 2. Project context files (AGENTS.md, user-preferences.md)
+ *
+ * Context files are read dynamically from the project root (cwd).
+ */
+export default function (pi: ExtensionAPI) {
+  pi.on("before_agent_start", async (_event, ctx) => {
+    const skillHints = [
+      "Available skills — invoke when relevant (not pre-loaded to save context):",
+      "",
+      "• /skill:using-agent-skills — meta-skill that routes to the right skill",
+      "  and enforces core agent behaviors. Check this first if unsure.",
+      "",
+      "• /skill:bd-tool — project context & task tracking with beads.",
+      "  Run `bd ready` to see available work.",
+      "",
+      "• /skill:git-workflow — git discipline: feature branches,",
+      "  worktrees for solo AFK work, PR workflow, and when to ask.",
+      "",
+      "Read the SKILL.md for full instructions when needed.",
+    ].join("\n");
+
+    const contextFiles = loadSessionContext(ctx.cwd);
+
+    const content = contextFiles
+      ? `${skillHints}\n\n---\n\n${contextFiles}`
+      : skillHints;
+
+    return {
+      message: {
+        customType: "session-start",
+        content,
+        display: false,
+      },
+    };
+  });
+}

package/extensions/skill-stats/README.md

@@ -0,0 +1,74 @@
+# skill-stats
+
+A PI extension that tracks skill usage across all sessions.
+
+## What it tracks
+
+| Signal | Source | What it tells you |
+|---|---|---|
+| **Loaded** | `before_agent_start` → `systemPromptOptions.skills` | Skill was injected into the system prompt (available to the LLM) |
+| **Invoked** | `input` matching `/skill:name` | User explicitly invoked the skill |
+| **Read** | `read` tool call to a SKILL.md | LLM actively loaded the skill's full instructions |
+
+### Misuse detection
+
+A skill that is *loaded* frequently but *never read* may be burning context budget without being consulted — a candidate for removal or tightening.
+
+## Data
+
+Usage data is stored in `~/.pi/agent-cortex/skill-usage.json` — a single file across all projects, with per-project breakdowns so you can slice by project.
+
+## Installation
+
+This extension is bundled with the `agent-cortex` PI package. Install the package for
+auto-discovery:
+
+```bash
+pi install git:https://github.com/jaybeeuu/agent-cortex
+pi config enable extension:skill-stats
+```
+
+After install, `/reload` inside PI (or restart PI). The extension auto-registers.
+
+### Development symlink (alternative)
+
+```bash
+ln -sf $(pwd)/extensions/skill-stats ~/.pi/agent/extensions/skill-stats
+/reload
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/skill-stats` | Show usage dashboard with per-project slicing |
+| `/skill-stats --project ./relative/path` | Filter to a specific project |
+| `/skill-usage-reset` | Wipe all recorded data |
+
+## Raw data
+
+The JSON file at `~/.pi/agent-cortex/skill-usage.json` contains the full record:
+
+```json
+{
+  "version": 1,
+  "skills": {
+    "bd-tool": {
+      "loadedCount": 42,
+      "invokedCount": 5,
+      "readCount": 18,
+      "lastUsed": "2026-06-07T...",
+      "byProject": {
+        "/home/jaybeeuu/src/agent-cortex": {
+          "loadedCount": 40,
+          "invokedCount": 3,
+          "readCount": 16,
+          "lastUsed": "2026-06-07T..."
+        }
+      }
+    }
+  },
+  "totalTurns": 350,
+  "lastUpdated": "2026-06-07T..."
+}
+```