@normful/picadillo 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [4.0.0] - 2026-02-17
+
+### 🚀 Features
+
+- *(extension)* Add overstory extension boilerplate and logic
+
+### 📚 Documentation
+
+- Add overstory extension to README
+
+### ⚙️ Miscellaneous Tasks
+
+- Shorten package.json description, fix overstory repo URL
 ## [3.0.0] - 2026-02-17
 
 ### 🚀 Features
@@ -12,6 +25,10 @@
 ### 📚 Documentation
 
 - Update README with reorganized skills and extensions sections
+
+### ⚙️ Miscellaneous Tasks
+
+- Release 3.0.0
 ## [2.0.3] - 2026-02-16
 
 ### 📚 Documentation

package/README.md

@@ -67,6 +67,12 @@ Hooks to automatically run `gt prime` and `gt mail` from [gastown](https://githu
 Hooks to automatically run [mulch](https://github.com/jayminwest/mulch) for
 recording and retrieving structured project learnings.
 
+### overstory
+
+Hooks to automatically run `overstory prime` and `overstory mail check` from
+[overstory](https://github.com/jayminwest/overstory/), along with logging tool
+start/end, session end events, and integration with mulch for learning.
+
 ## Parrot Extension Demo
 
 [![asciicast](https://asciinema.org/a/788693.svg)](https://asciinema.org/a/788693)

package/extensions/overstory.ts

@@ -0,0 +1,207 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExecResult } from "@mariozechner/pi-coding-agent";
+
+export type { ExecResult };
+export const OVERSTORY_MESSAGE_TYPE = "overstory";
+
+export async function overstoryPrime(
+  execFn: ExtensionAPI["exec"],
+  forCompact = false,
+): Promise<string> {
+  let primeText = "";
+  try {
+    const { stdout } = await execFn("overstory", [
+      "prime",
+      "--agent",
+      "orchestrator",
+      ...(forCompact ? ["--compact"] : []),
+    ]);
+    primeText = stdout;
+  } catch (e) {
+    console.error("overstory prime failed:", e);
+  }
+  return primeText;
+}
+
+export async function overstoryMailCheck(
+  execFn: ExtensionAPI["exec"],
+): Promise<string> {
+  let mailText = "";
+  try {
+    const { stdout } = await execFn("overstory", [
+      "mail",
+      "check",
+      "--inject",
+      "--agent",
+      "orchestrator",
+    ]);
+    mailText = stdout;
+  } catch (e) {
+    console.error("overstory mail check failed:", e);
+  }
+  return mailText;
+}
+
+export async function logToolStart(
+  execFn: ExtensionAPI["exec"],
+  toolName: string,
+): Promise<void> {
+  try {
+    await execFn("overstory", [
+      "log",
+      "tool-start",
+      "--agent",
+      "orchestrator",
+      "--tool-name",
+      toolName,
+    ]);
+  } catch (e) {
+    console.error("overstory log tool-start failed:", e);
+  }
+}
+
+export async function logToolEnd(
+  execFn: ExtensionAPI["exec"],
+  toolName: string,
+): Promise<void> {
+  try {
+    await execFn("overstory", [
+      "log",
+      "tool-end",
+      "--agent",
+      "orchestrator",
+      "--tool-name",
+      toolName,
+    ]);
+  } catch (e) {
+    console.error("overstory log tool-end failed:", e);
+  }
+}
+
+export async function logSessionEnd(
+  execFn: ExtensionAPI["exec"],
+): Promise<void> {
+  try {
+    await execFn("overstory", [
+      "log",
+      "session-end",
+      "--agent",
+      "orchestrator",
+    ]);
+  } catch (e) {
+    console.error("overstory log session-end failed:", e);
+  }
+}
+
+export async function mulchLearn(
+  execFn: ExtensionAPI["exec"],
+): Promise<string> {
+  let primeText = "";
+  try {
+    const { stdout } = await execFn("mulch", ["learn"]);
+    primeText = stdout;
+  } catch (e) {
+    console.error("mulch learn failed:", e);
+  }
+  return primeText;
+}
+
+export async function handleSessionStart(
+  execFn: ExtensionAPI["exec"],
+  sendMessage: ExtensionAPI["sendMessage"],
+): Promise<void> {
+  const primeText = await overstoryPrime(execFn);
+  if (!primeText) return;
+
+  const mailText = await overstoryMailCheck(execFn);
+  sendMessage(
+    {
+      customType: OVERSTORY_MESSAGE_TYPE,
+      content: primeText + "\n\n" + mailText,
+      display: true,
+    },
+    {
+      deliverAs: "followUp",
+      triggerTurn: true,
+    },
+  );
+}
+
+export function handleBeforeAgentStart(mailText: string) {
+  return {
+    message: {
+      customType: OVERSTORY_MESSAGE_TYPE,
+      content: mailText,
+      display: true,
+    },
+  };
+}
+
+export async function handleToolExecutionEnd(
+  execFn: ExtensionAPI["exec"],
+  event: { toolName: string },
+): Promise<void> {
+  logToolEnd(execFn, event.toolName);
+}
+
+export async function handleToolExecutionStart(
+  execFn: ExtensionAPI["exec"],
+  event: { toolName: string },
+): Promise<void> {
+  logToolStart(execFn, event.toolName);
+}
+
+export async function handleSessionCompact(
+  execFn: ExtensionAPI["exec"],
+  sendMessage: ExtensionAPI["sendMessage"],
+): Promise<void> {
+  const primeText = await overstoryPrime(execFn, true);
+  if (!primeText) return;
+
+  sendMessage(
+    {
+      customType: OVERSTORY_MESSAGE_TYPE,
+      content: primeText,
+      display: true,
+    },
+    {
+      deliverAs: "followUp",
+      triggerTurn: true,
+    },
+  );
+}
+
+export async function handleSessionShutdown(
+  execFn: ExtensionAPI["exec"],
+): Promise<void> {
+  await Promise.all([logSessionEnd(execFn), mulchLearn(execFn)]);
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, _ctx) => {
+    await handleSessionStart(pi.exec, pi.sendMessage);
+  });
+
+  pi.on("before_agent_start", async (_event, _ctx) => {
+    const mailText = await overstoryMailCheck(pi.exec);
+    return handleBeforeAgentStart(mailText);
+  });
+
+  pi.on("tool_execution_end", async (event, _ctx) => {
+    // Fire-and-forget: don't await, let it run in background
+    void handleToolExecutionEnd(pi.exec, event);
+  });
+
+  pi.on("tool_execution_start", async (event, _ctx) => {
+    // Fire-and-forget: don't await, let it run in background
+    void handleToolExecutionStart(pi.exec, event);
+  });
+
+  pi.on("session_compact", async (_event, _ctx) => {
+    await handleSessionCompact(pi.exec, pi.sendMessage);
+  });
+
+  pi.on("session_shutdown", async (_event, _ctx) => {
+    await handleSessionShutdown(pi.exec);
+  });
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@normful/picadillo",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "private": false,
-  "description": "pi agent skills/extensions: run-in-tmux, parrot (send AI message with edited version of AI message)",
+  "description": "pi agent skills & extensions: run-in-tmux, parrot, mulch, overstory",
   "keywords": [
     "pi",
     "pi-coding-agent",