@normful/picadillo 3.0.0 → 4.1.0

package/.beads/sync-state.json

@@ -0,0 +1,7 @@
+{
+  "last_failure": "2026-02-18T01:49:04.979785+09:00",
+  "failure_count": 1,
+  "backoff_until": "2026-02-18T01:49:34.979785+09:00",
+  "needs_manual_sync": false,
+  "failure_reason": "git pull failed: exit status 128\nFrom github.com:normful/picadillo\n * branch            main       -\u003e FETCH_HEAD\nhint: You have divergent branches and need to specify how to reconcile them.\nhint: You can do so by running one of the following commands sometime before\nhint: your next pull:\nhint:\nhint:   git config pull.rebase false  # merge\nhint:   git config pull.rebase true   # rebase\nhint:   git config pull.ff only       # fast-forward only\nhint:\nhint: You can replace \"git config\" with \"git config --global\" to set a default\nhint: preference for all repositories. You can also pass --rebase, --no-rebase,\nhint: or --ff-only on the command line to override the configured default per\nhint: invocation.\nfatal: Need to specify how to reconcile divergent branches.\n"
+}

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [4.1.0] - 2026-02-17
+
+### 🚀 Features
+
+- *(overstory)* Ensure extension runs only in an Overstory git repository
+## [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
+- Release 4.0.0
 ## [3.0.0] - 2026-02-17
 
 ### 🚀 Features
@@ -12,6 +31,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,230 @@
+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 async function isOverstoryRepo(
+  execFn: ExtensionAPI["exec"],
+): Promise<boolean> {
+  try {
+    // Get the git repo root directory (fails if not in a git repo)
+    const gitRootResult = await execFn("git", ["rev-parse", "--show-toplevel"]);
+    const gitRoot = gitRootResult.stdout.trim();
+
+    // Check if .overstory directory exists in the git repo root
+    const overstoryDirResult = await execFn("ls", ["-d", `${gitRoot}/.overstory`]);
+    if (overstoryDirResult.code !== 0) {
+      return false; // No .overstory directory
+    }
+    return true;
+  } catch (e) {
+    return false; // Not in a git repo or other error
+  }
+}
+
+export default async function (pi: ExtensionAPI) {
+  if (!(await isOverstoryRepo(pi.exec))) {
+    return;
+  }
+
+  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.1.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",