opencodekit 0.9.2 → 0.11.0

package/dist/template/.opencode/plugin/README.md

@@ -2,27 +2,51 @@
 
 TypeScript plugins for extending OpenCode functionality following official best practices.
 
+## Directory Structure
+
+```
+plugin/
+├── lib/
+│   └── notify.ts        # Shared notification utilities
+├── injector.ts          # AGENTS.md hierarchy walker
+├── compactor.ts         # Context usage warnings
+├── enforcer.ts          # TODO completion enforcement
+├── notification.ts      # Session completion alerts
+├── sessions.ts          # Session management tools
+├── truncator.ts         # Output size monitoring
+└── README.md
+```
+
 ## Installed Plugins
 
-### sessions.ts 🆕
+### injector.ts
 
-**Session management and context transfer** - enables short, focused sessions by providing session discovery and context reads.
+**AGENTS.md hierarchy walker** - solves OpenCode's limitation where findUp only finds the first AGENTS.md match.
 
-Based on [AmpCode's 200k tokens article](https://ampcode.com/200k-tokens-is-plenty): long context makes agents "drunk" (hallucinate, argue, fail) while costing exponentially more.
+- Hooks into `tool.execute.after` for `read` tool
+- Walks up from file directory to project root
+- Collects ALL AGENTS.md files in the path
+- Injects in order: root → specific (T-shaped context loading)
+- Caches per session to avoid duplicate injections
 
-**Tools:**
+**Example:** When reading `src/components/Button.tsx`:
 
-- `list_sessions(project?, since?, limit?)` - Discover available sessions with metadata
-  - `project`: "current" (default), "all", or absolute path
-  - `since`: "today", "yesterday", "this week", or ISO date
-  - `limit`: Max sessions to return (default: 20)
+```
+Injects:
+1. /project/AGENTS.md (root context)
+2. /project/src/AGENTS.md (src context)
+3. /project/src/components/AGENTS.md (component context)
+```
 
-- `read_session(session_reference, project?, focus?)` - Load context from previous sessions
-  - `session_reference`: "last", "previous", "2 ago", date, or session ID
-  - `project`: Filter when using relative/date references
-  - `focus`: Optional filter (e.g., "test failures", "bug findings")
+### sessions.ts
+
+**Session management and context transfer** - enables short, focused sessions.
+
+**Tools:**
 
-**Returns:** Session metadata, user tasks, tool usage stats, file changes
+- `list_sessions(project?, since?, limit?)` - Discover available sessions
+- `read_session(session_reference, project?, focus?)` - Load context from previous sessions
+- `summarize_session(session_id)` - Generate AI summary of a session
 
 **Workflow pattern:**
 
@@ -30,133 +54,121 @@ Based on [AmpCode's 200k tokens article](https://ampcode.com/200k-tokens-is-plen
 Session 1: Implementation (80k) → close
 Session 2: read_session("last") → Refactor (60k) → close
 Session 3: read_session("previous") → Tests (90k) → close
-Session 4: read_session refs → Review (100k)
 ```
 
-Result: 4 fresh contexts vs 1 bloated 330k thread with degraded performance.
+### compactor.ts
 
-**When to start new session:**
+**Context usage warnings** - notifies at token thresholds before hitting limits.
 
-- Task complete
-- Token usage > 150k
-- Switching phases (implementation → review → testing)
-- After handoff
+- Warns at 70% (info), 85% (warn), 95% (critical)
+- Sends native notifications at 85%+
+- Tracks per-session to avoid duplicate warnings
 
-### notification.ts
+### enforcer.ts
 
-Native notification plugin that alerts when sessions complete:
+**TODO completion enforcement** - forces continuation when session idles with incomplete work.
 
-- Sends notifications when AI finishes (via `session.idle` event)
-- Extracts session summary from messages
-- Cross-platform support (macOS via `osascript`, Linux via `notify-send`)
-- Simplified implementation following official docs pattern
+- Tracks TODOs per session via `todo.updated` events
+- On `session.idle`, checks for incomplete high-priority or in-progress TODOs
+- **ENFORCES** continuation by calling `client.session.promptAsync()` (not just notification)
+- Injects prompt: "Continue working on incomplete TODOs: [list]"
+- 5-minute cooldown to prevent spam
+- Falls back to OS notification if prompt injection fails
 
-**Official Docs:** [OpenCode Plugins - Send notifications](https://opencode.ai/docs/plugins/#send-notifications)
+**Behavior:**
 
-### superpowers.ts
+- High-priority or in-progress TODOs → Inject continuation prompt
+- Low-priority pending TODOs → OS notification only (no forced continuation)
 
-Custom tools for loading and discovering skills:
+### notification.ts
 
-- `use_skill` - Load a specific skill to guide your work
-- `find_skills` - List all available skills (project, personal, superpowers)
-- Skills loaded on-demand, not auto-injected
-- Supports skill resolution priority: project > personal > superpowers
+**Session completion alerts** - sends native notifications when AI finishes.
 
-**Official Docs:** [OpenCode Plugins - Custom tools](https://opencode.ai/docs/plugins/#custom-tools)
+- Extracts session summary from messages
+- Cross-platform (macOS, Linux, WSL, Windows)
+- Uses shared `lib/notify.ts` utilities
 
-## Best Practices Applied
+### truncator.ts
 
-### ✅ Correct Import Syntax
+**Output size monitoring** - logs warnings for large outputs under context pressure.
 
-```typescript
-import { type Plugin, tool } from "@opencode-ai/plugin";
-```
+- Monitors `tool.execute.after` events
+- Warns when outputs exceed thresholds based on context usage
+- Note: Actual truncation requires OpenCode core changes; this is observation-only
 
-### ✅ Proper Plugin Structure
+## Shared Library
 
-```typescript
-export const MyPlugin: Plugin = async ({ project, client, $, directory }) => {
-  return {
-    event: async ({ event }) => {
-      /* ... */
-    },
-    tool: {
-      mytool: tool({
-        /* ... */
-      }),
-    },
-  };
-};
-```
+### lib/notify.ts
 
-### ✅ TypeScript Configuration
+Shared utilities used by multiple plugins:
 
-- Minimal `tsconfig.json` for plugin development
-- No compilation needed (OpenCode loads `.ts` directly)
-- Type safety with `@opencode-ai/plugin` types
+```typescript
+import { notify, THRESHOLDS, getContextPercentage } from "./lib/notify";
 
-### ✅ Registered in opencode.json
+// Send cross-platform notification using $ shell API
+await notify($, "Title", "Message");
 
-```json
-{
-  "plugin": ["./plugin/superpowers.ts", "./plugin/notification.ts"]
-}
+// Context thresholds
+THRESHOLDS.MODERATE; // 70%
+THRESHOLDS.URGENT; // 85%
+THRESHOLDS.CRITICAL; // 95%
 ```
 
-## Development
+## Best Practices Applied
 
-All plugins are written in TypeScript with proper type safety:
+### Use `$` Shell API (not `exec`)
 
-- Import types from `@opencode-ai/plugin`
-- Use structured logging with `client.app.log()`
-- Handle errors gracefully with `.catch(() => {})`
-- Follow OpenCode plugin conventions from official docs
+```typescript
+// ✅ Correct - uses Bun shell from plugin context
+export const MyPlugin: Plugin = async ({ $ }) => {
+  await $`osascript -e 'display notification "Done!"'`;
+};
 
-## Available Hooks
+// ❌ Wrong - manual exec with escaping
+import { exec } from "child_process";
+exec(`osascript -e '...'`, () => {});
+```
 
-From [official documentation](https://opencode.ai/docs/plugins/#events):
+### Share Common Code
 
-- `event` - Listen to OpenCode events (session.idle, file.edited, etc.)
-- `tool.execute.before` - Hook before tool execution
-- `tool.execute.after` - Hook after tool execution
-- `tool` - Add custom tools to OpenCode
+```typescript
+// ✅ Correct - import from shared lib
+import { notify } from "./lib/notify";
 
-## Plugin Examples
+// ❌ Wrong - copy-paste same code in every plugin
+function notify() {
+  /* duplicated */
+}
+```
 
-### Send Notifications (notification.ts)
+### Proper Plugin Structure
 
 ```typescript
-export const NotificationPlugin: Plugin = async ({ $, client }) => {
+import type { Plugin } from "@opencode-ai/plugin";
+
+export const MyPlugin: Plugin = async ({ client, $ }) => {
   return {
     event: async ({ event }) => {
-      if (event.type === "session.idle") {
-        await $`osascript -e 'display notification "Done!" with title "OpenCode"'`;
-      }
+      /* ... */
+    },
+    "tool.execute.after": async (input, output) => {
+      /* ... */
     },
   };
 };
 ```
 
-### Custom Tools (superpowers.ts)
+## Available Hooks
 
-```typescript
-export const SuperpowersPlugin: Plugin = async ({ directory }) => {
-  return {
-    tool: {
-      use_skill: tool({
-        description: "Load a skill to guide your work",
-        args: { skill_name: tool.schema.string() },
-        async execute(args, ctx) {
-          // Load and return skill content
-        },
-      }),
-    },
-  };
-};
-```
+| Hook                  | Purpose                                                         |
+| --------------------- | --------------------------------------------------------------- |
+| `event`               | Listen to OpenCode events (session.idle, session.updated, etc.) |
+| `tool.execute.before` | Hook before tool execution                                      |
+| `tool.execute.after`  | Hook after tool execution (observation only)                    |
+| `tool`                | Add custom tools                                                |
 
 ## Resources
 
 - [OpenCode Plugin Documentation](https://opencode.ai/docs/plugins/)
-- [OpenCode Ecosystem Plugins](https://opencode.ai/docs/ecosystem#plugins)
+- [OpenCode Custom Tools](https://opencode.ai/docs/custom-tools/)
 - [Community Examples](https://github.com/sst/opencode/discussions)

package/dist/template/.opencode/plugin/compactor.ts

@@ -1,183 +1,107 @@
 /**
  * OpenCode Compactor Plugin
- * Warns at token thresholds before hitting limits - graceful context management
- *
- * Inspired by oh-my-opencode's context-window-monitor and anthropic-auto-compact
+ * Warns at token thresholds before hitting limits
  */
 
 import type { Plugin } from "@opencode-ai/plugin";
-import { exec } from "child_process";
-import { readFileSync } from "fs";
-
-// Notification helpers
-function isWSL(): boolean {
-  try {
-    const release = readFileSync("/proc/version", "utf8").toLowerCase();
-    return release.includes("microsoft") || release.includes("wsl");
-  } catch {
-    return false;
-  }
-}
+import {
+	THRESHOLDS,
+	type TokenStats,
+	getContextPercentage,
+	notify,
+} from "./lib/notify";
 
-function escapeShell(str: string): string {
-  return str.replace(/"/g, '\\"').replace(/\$/g, "\\$").replace(/`/g, "\\`");
-}
+type LogLevel = "debug" | "info" | "warn" | "error";
 
-function notify(title: string, message: string): void {
-  const platform = process.platform;
-  const safeTitle = title ? String(title) : "Notification";
-  const safeMessage = message ? String(message) : "";
-  const escapedTitle = escapeShell(safeTitle);
-  const escapedMessage = escapeShell(safeMessage);
-
-  let command: string;
-
-  if (platform === "darwin") {
-    command = `osascript -e 'display notification "${escapedMessage}" with title "${escapedTitle}"'`;
-  } else if (platform === "linux") {
-    command = `notify-send "${escapedTitle}" "${escapedMessage}"`;
-    if (isWSL()) {
-      command = `(${command}) 2>&1 || echo "WSL notification failed"`;
-    }
-  } else if (platform === "win32") {
-    command = `powershell -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.MessageBox]::Show('${escapedMessage}', '${escapedTitle}')"`;
-  } else {
-    return;
-  }
-
-  exec(command, () => {});
+interface WarningLevel {
+	level: LogLevel;
+	emoji: string;
+	action: string;
 }
 
-interface TokenStats {
-  used: number;
-  limit: number;
-  percentage?: number;
+function getWarningLevel(percentage: number): WarningLevel | null {
+	if (percentage >= THRESHOLDS.CRITICAL) {
+		return {
+			level: "error",
+			emoji: "🚨",
+			action: "CRITICAL: Prune immediately or start new session.",
+		};
+	}
+	if (percentage >= THRESHOLDS.URGENT) {
+		return {
+			level: "warn",
+			emoji: "⚠️",
+			action: "Consider pruning completed tool outputs.",
+		};
+	}
+	if (percentage >= THRESHOLDS.MODERATE) {
+		return {
+			level: "info",
+			emoji: "📈",
+			action: "Context at 70%. Consider consolidating.",
+		};
+	}
+	return null;
 }
 
-const THRESHOLDS = {
-  MODERATE: 70,
-  URGENT: 85,
-  CRITICAL: 95,
-} as const;
-
-type LogLevel = "debug" | "info" | "warn" | "error";
-
-export const CompactorPlugin: Plugin = async ({ client }) => {
-  const warnedSessions = new Map<string, number>();
-
-  client.app
-    .log({
-      body: {
-        service: "compactor-plugin",
-        level: "info",
-        message:
-          "📊 Compactor Plugin loaded - context window monitoring active",
-      },
-    })
-    .catch(() => {});
-
-  function getWarningLevel(
-    percentage: number,
-  ): { level: LogLevel; emoji: string; action: string } | null {
-    if (percentage >= THRESHOLDS.CRITICAL) {
-      return {
-        level: "error",
-        emoji: "🚨",
-        action:
-          "CRITICAL: Prune immediately or start new session. Context nearly exhausted.",
-      };
-    }
-    if (percentage >= THRESHOLDS.URGENT) {
-      return {
-        level: "warn",
-        emoji: "⚠️",
-        action:
-          "Consider pruning completed tool outputs or summarizing findings.",
-      };
-    }
-    if (percentage >= THRESHOLDS.MODERATE) {
-      return {
-        level: "info",
-        emoji: "📈",
-        action:
-          "Context at 70%. Still plenty of room - no rush, but consider consolidating.",
-      };
-    }
-    return null;
-  }
-
-  return {
-    event: async ({ event }) => {
-      const props = event.properties as Record<string, unknown>;
-
-      if (event.type === "session.updated") {
-        const info = props?.info as Record<string, unknown> | undefined;
-        const tokenStats = (info?.tokens || props?.tokens) as
-          | TokenStats
-          | undefined;
-        const sessionId = (info?.id || props?.sessionID) as string | undefined;
-
-        if (!sessionId || !tokenStats?.used || !tokenStats?.limit) return;
-
-        const pct =
-          tokenStats.percentage ||
-          Math.round((tokenStats.used / tokenStats.limit) * 100);
-        const lastWarned = warnedSessions.get(sessionId) || 0;
-
-        const warning = getWarningLevel(pct);
-        if (!warning) return;
-
-        let currentThreshold = 0;
-        if (pct >= THRESHOLDS.CRITICAL) currentThreshold = THRESHOLDS.CRITICAL;
-        else if (pct >= THRESHOLDS.URGENT) currentThreshold = THRESHOLDS.URGENT;
-        else if (pct >= THRESHOLDS.MODERATE)
-          currentThreshold = THRESHOLDS.MODERATE;
-
-        if (lastWarned >= currentThreshold) return;
-
-        warnedSessions.set(sessionId, currentThreshold);
-
-        const message = `${warning.emoji} Context: ${pct}% (${tokenStats.used.toLocaleString()}/${tokenStats.limit.toLocaleString()} tokens). ${warning.action}`;
-
-        client.app
-          .log({
-            body: {
-              service: "compactor-plugin",
-              level: warning.level,
-              message,
-            },
-          })
-          .catch(() => {});
-
-        if (pct >= THRESHOLDS.URGENT) {
-          notify(`Context ${pct}%`, warning.action);
-        }
-      }
-
-      if (event.type === "session.compacted") {
-        const sessionId = props?.sessionID as string | undefined;
-
-        if (sessionId) {
-          client.app
-            .log({
-              body: {
-                service: "compactor-plugin",
-                level: "info",
-                message: "♻️ Session compacted - context freed",
-              },
-            })
-            .catch(() => {});
-
-          warnedSessions.set(sessionId, 0);
-        }
-      }
-
-      if (event.type === "session.deleted") {
-        const sessionId = props?.sessionID as string | undefined;
-        if (sessionId) {
-          warnedSessions.delete(sessionId);
-        }
-      }
-    },
-  };
+export const CompactorPlugin: Plugin = async ({ client, $ }) => {
+	const warnedSessions = new Map<string, number>();
+
+	return {
+		event: async ({ event }) => {
+			const props = event.properties as Record<string, unknown>;
+
+			if (event.type === "session.updated") {
+				const info = props?.info as Record<string, unknown> | undefined;
+				const tokenStats = (info?.tokens || props?.tokens) as
+					| TokenStats
+					| undefined;
+				const sessionId = (info?.id || props?.sessionID) as string | undefined;
+
+				if (!sessionId || !tokenStats?.used || !tokenStats?.limit) return;
+
+				const pct = getContextPercentage(tokenStats);
+				const lastWarned = warnedSessions.get(sessionId) || 0;
+
+				const warning = getWarningLevel(pct);
+				if (!warning) return;
+
+				let currentThreshold = 0;
+				if (pct >= THRESHOLDS.CRITICAL) currentThreshold = THRESHOLDS.CRITICAL;
+				else if (pct >= THRESHOLDS.URGENT) currentThreshold = THRESHOLDS.URGENT;
+				else if (pct >= THRESHOLDS.MODERATE)
+					currentThreshold = THRESHOLDS.MODERATE;
+
+				if (lastWarned >= currentThreshold) return;
+
+				warnedSessions.set(sessionId, currentThreshold);
+
+				const message = `${warning.emoji} Context: ${pct}% (${tokenStats.used.toLocaleString()}/${tokenStats.limit.toLocaleString()} tokens). ${warning.action}`;
+
+				client.app
+					.log({
+						body: { service: "compactor", level: warning.level, message },
+					})
+					.catch(() => {});
+
+				if (pct >= THRESHOLDS.URGENT) {
+					await notify($, `Context ${pct}%`, warning.action);
+				}
+			}
+
+			if (event.type === "session.compacted") {
+				const sessionId = props?.sessionID as string | undefined;
+				if (sessionId) {
+					warnedSessions.set(sessionId, 0);
+				}
+			}
+
+			if (event.type === "session.deleted") {
+				const sessionId = props?.sessionID as string | undefined;
+				if (sessionId) {
+					warnedSessions.delete(sessionId);
+				}
+			}
+		},
+	};
 };