opencodekit 0.16.15 → 0.16.18

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

@@ -1,184 +1,58 @@
 # OpenCode Plugins
 
-TypeScript plugins for extending OpenCode functionality following official best practices.
+Plugins in this directory extend OpenCode with project-specific behavior and tools.
 
-## Directory Structure
+## Current Plugin Files
 
-```
+```text
 plugin/
+├── memory.ts           # Memory DB maintenance + observation toasts
+├── sessions.ts         # Session tools (list/read/search/summarize)
+├── compaction.ts       # Compaction-time context recovery injection
+├── swarm-enforcer.ts   # Beads workflow enforcement and reminders
+├── skill-mcp.ts        # Skill-scoped MCP bridge (skill_mcp tools)
+├── copilot-auth.ts     # GitHub Copilot provider/auth integration
 ├── 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
-
-### injector.ts
-
-**AGENTS.md hierarchy walker** - solves OpenCode's limitation where findUp only finds the first AGENTS.md match.
-
-- 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
-
-**Example:** When reading `src/components/Button.tsx`:
-
-```
-Injects:
-1. /project/AGENTS.md (root context)
-2. /project/src/AGENTS.md (src context)
-3. /project/src/components/AGENTS.md (component context)
-```
-
-### sessions.ts
-
-**Session management and context transfer** - enables short, focused sessions.
-
-**Tools:**
-
-- `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:**
-
-```
-Session 1: Implementation (80k) → close
-Session 2: read_session("last") → Refactor (60k) → close
-Session 3: read_session("previous") → Tests (90k) → close
+│   ├── memory-db.ts    # SQLite + FTS5 memory backend
+│   └── notify.ts       # Shared notification helpers
+└── sdk/                # Copilot SDK adaptation code
 ```
 
-### compactor.ts
-
-**Context usage warnings** - notifies at token thresholds before hitting limits.
-
-- Warns at 70% (info), 85% (warn), 95% (critical)
-- Sends native notifications at 85%+
-- Tracks per-session to avoid duplicate warnings
-
-### enforcer.ts
-
-**TODO completion enforcement** - forces continuation when session idles with incomplete work.
-
-- 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
-
-**Behavior:**
-
-- High-priority or in-progress TODOs → Inject continuation prompt
-- Low-priority pending TODOs → OS notification only (no forced continuation)
+## Plugin Responsibilities
 
-### swarm-enforcer.ts
+- `memory.ts`
+  - Optimizes FTS5 index on idle sessions
+  - Checkpoints WAL when needed
+  - Shows toast feedback for observation saves and session errors
 
-**Swarm protocol guardrails (Beads-as-board)** - nudges agents to follow the Beads-first workflow.
+- `sessions.ts`
+  - Provides custom tools: `list_sessions`, `read_session`, `search_session`, `summarize_session`
 
-- Treats `.beads/` as the single source of truth for the swarm task board
-- If user expresses implementation intent and no task is `in_progress`, injects a nudge to use `br ready/show/update`
-- If there are `in_progress` tasks but `.beads/artifacts/<id>/spec.md` is missing, nudges to create it before implementation
-- On `file.edited`, warns if code is being changed without a claimed task or with missing `spec.md`
-- On `session.idle`, reminds to `br close` + `br sync` when work is done
+- `compaction.ts`
+  - Injects session continuity context during compaction
+  - Pulls memory/project/handoff context and recovery instructions
 
-### notification.ts
+- `swarm-enforcer.ts`
+  - Injects bead state and stage labels into system context
+  - Warns when implementation starts without a properly started bead
+  - Reminds to close/sync in-progress work on session idle
 
-**Session completion alerts** - sends native notifications when AI finishes.
+- `skill-mcp.ts`
+  - Loads MCP configs from skills
+  - Exposes `skill_mcp`, `skill_mcp_status`, `skill_mcp_disconnect`
+  - Supports tool filtering with `includeTools`
 
-- Extracts session summary from messages
-- Cross-platform (macOS, Linux, WSL, Windows)
-- Uses shared `lib/notify.ts` utilities
-
-### truncator.ts
-
-**Output size monitoring** - logs warnings for large outputs under context pressure.
-
-- 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
-
-## Shared Library
-
-### lib/notify.ts
-
-Shared utilities used by multiple plugins:
-
-```typescript
-import { notify, THRESHOLDS, getContextPercentage } from "./lib/notify";
-
-// Send cross-platform notification using $ shell API
-await notify($, "Title", "Message");
-
-// Context thresholds
-THRESHOLDS.MODERATE; // 70%
-THRESHOLDS.URGENT; // 85%
-THRESHOLDS.CRITICAL; // 95%
-```
-
-## Best Practices Applied
-
-### Use `$` Shell API (not `exec`)
-
-```typescript
-// ✅ Correct - uses Bun shell from plugin context
-export const MyPlugin: Plugin = async ({ $ }) => {
-  await $`osascript -e 'display notification "Done!"'`;
-};
-
-// ❌ Wrong - manual exec with escaping
-import { exec } from "child_process";
-exec(`osascript -e '...'`, () => {});
-```
-
-### Share Common Code
-
-```typescript
-// ✅ Correct - import from shared lib
-import { notify } from "./lib/notify";
-
-// ❌ Wrong - copy-paste same code in every plugin
-function notify() {
-  /* duplicated */
-}
-```
-
-### Proper Plugin Structure
-
-```typescript
-import type { Plugin } from "@opencode-ai/plugin";
-
-export const MyPlugin: Plugin = async ({ client, $ }) => {
-  return {
-    event: async ({ event }) => {
-      /* ... */
-    },
-    "tool.execute.after": async (input, output) => {
-      /* ... */
-    },
-  };
-};
-```
+- `copilot-auth.ts`
+  - Handles GitHub Copilot OAuth/device flow
+  - Adds model/provider request shaping for compatible reasoning behavior
 
-## Available Hooks
+## Notes
 
-| 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                                                |
+- `notification.ts.bak` is a backup file and not part of the active plugin set.
+- Keep plugin documentation aligned with actual files in this directory.
+- Prefer shared helpers in `lib/` over duplicated utilities across plugins.
 
-## Resources
+## References
 
-- [OpenCode Plugin Documentation](https://opencode.ai/docs/plugins/)
-- [OpenCode Custom Tools](https://opencode.ai/docs/custom-tools/)
-- [Community Examples](https://github.com/sst/opencode/discussions)
+- OpenCode plugin docs: https://opencode.ai/docs/plugins/
+- OpenCode custom tools docs: https://opencode.ai/docs/custom-tools/

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

@@ -1,152 +1,183 @@
 /**
- * Session Continuity Plugin (Compaction-Time Context Injection)
+ * Session Continuity Plugin (compaction-time context injection)
  *
- * Complements DCP plugin (which handles context management rules via
- * experimental.chat.system.transform). This plugin fires ONLY during
- * compaction events (experimental.session.compacting) and handles:
+ * Purpose:
+ * - Provide compact, bounded state needed to resume work after compaction.
+ * - Keep injected prompt guidance minimal and deterministic.
  *
- * 1. Load session-context.md (CONTINUITY.md pattern) — highest priority
- * 2. Load project memory files (user prefs, tech stack, gotchas)
- * 3. Inject beads in-progress state (active task IDs)
- * 4. Load most recent handoff file for session resumption
- * 5. Append post-compaction recovery protocol
- *
- * Division of responsibility:
- * - DCP plugin: context budget zones, distill/compress/prune rules,
- *   prunable-tools list, nudge system (always-on via system.transform)
- * - This plugin: session state preservation, post-compaction recovery,
- *   memory persistence reminders (compaction-time only)
+ * Non-goals:
+ * - Replace DCP policy/rules management.
+ * - Inject large free-form manuals into the prompt.
  */
 
+import { execFile } from "node:child_process";
+import { readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
 import type { Plugin } from "@opencode-ai/plugin";
 
-export const CompactionPlugin: Plugin = async ({ $, directory }) => {
-	const MEMORY_DIR = `${directory}/.opencode/memory`;
-	const HANDOFF_DIR = `${MEMORY_DIR}/handoffs`;
-
-	return {
-		"experimental.session.compacting": async (input, output) => {
-			// 1. Load session context (CONTINUITY.md pattern) - HIGHEST PRIORITY
-			let sessionContext = "";
-			try {
-				const sessionFile = `${MEMORY_DIR}/session-context.md`;
-				const content = await $`cat ${sessionFile} 2>/dev/null`.text();
-				if (content.trim()) {
-					sessionContext = `\n## Session Continuity (Compaction-Safe)\n${content}`;
-				}
-			} catch {
-				// No session context yet
-			}
-
-			// 2. Load project memory files
-			let memoryContext = "";
-			try {
-				const memoryFiles =
-					await $`find ${MEMORY_DIR}/project -name '*.md' -type f 2>/dev/null | head -10`.quiet();
-				if (memoryFiles.stdout) {
-					const files = memoryFiles.stdout.toString().trim().split("\n");
-					for (const file of files) {
-						const content = await $`cat ${file}`.text();
-						if (content.trim() && !content.includes("<!-- ")) {
-							const name = file.split("/").pop()?.replace(".md", "");
-							memoryContext += `\n## Project ${name}\n${content}`;
-						}
-					}
-				}
-			} catch {
-				// Memory dir doesn't exist or other error
-			}
-
-			// 3. Inject beads in-progress state
-			let beadsContext = "";
-			try {
-				const result =
-					await $`cd ${directory} && br list --status in_progress --json 2>/dev/null`.quiet();
-				if (result.stdout) {
-					const inProgress = JSON.parse(result.stdout.toString());
-					if (inProgress.length > 0) {
-						beadsContext = `\n## Active Beads (In Progress)\n${inProgress.map((b: { id: string; title: string }) => `- ${b.id}: ${b.title}`).join("\n")}`;
-					}
-				}
-			} catch {
-				// Beads not available, skip
-			}
-
-			// 4. Load most recent handoff file (session continuity)
-			let handoffContext = "";
+const execFileAsync = promisify(execFile);
+
+const MAX_SESSION_CONTEXT_CHARS = 3000;
+const MAX_PROJECT_FILES = 3;
+const MAX_PROJECT_FILE_CHARS = 900;
+const MAX_HANDOFF_CHARS = 2500;
+const MAX_BEADS = 8;
+const MAX_COMBINED_CONTEXT_CHARS = 9000;
+
+function truncate(text: string, maxChars: number): string {
+	if (text.length <= maxChars) return text;
+	return `${text.slice(0, maxChars)}\n...[truncated]`;
+}
+
+async function safeReadFile(filePath: string): Promise<string> {
+	try {
+		return await readFile(filePath, "utf-8");
+	} catch {
+		return "";
+	}
+}
+
+function renderSection(title: string, body: string): string {
+	if (!body.trim()) return "";
+	return `## ${title}\n${body.trim()}`;
+}
+
+async function readProjectMemoryContext(memoryDir: string): Promise<string> {
+	const projectDir = path.join(memoryDir, "project");
+	let names: string[] = [];
+	try {
+		names = (await readdir(projectDir))
+			.filter((name) => name.endsWith(".md"))
+			.sort()
+			.slice(0, MAX_PROJECT_FILES);
+	} catch {
+		return "";
+	}
+
+	const chunks: string[] = [];
+	for (const name of names) {
+		const fullPath = path.join(projectDir, name);
+		const content = (await safeReadFile(fullPath)).trim();
+		if (!content) continue;
+		chunks.push(
+			`### ${name.replace(/\.md$/, "")}\n${truncate(content, MAX_PROJECT_FILE_CHARS)}`,
+		);
+	}
+
+	return chunks.join("\n\n");
+}
+
+async function readLatestHandoff(handoffDir: string): Promise<string> {
+	let names: string[] = [];
+	try {
+		names = (await readdir(handoffDir)).filter((name) => name.endsWith(".md"));
+	} catch {
+		return "";
+	}
+
+	if (names.length === 0) return "";
+
+	const withMtime = await Promise.all(
+		names.map(async (name) => {
+			const fullPath = path.join(handoffDir, name);
 			try {
-				const result =
-					await $`ls -t ${HANDOFF_DIR}/*.md 2>/dev/null | head -1`.quiet();
-				if (result.stdout) {
-					const handoffPath = result.stdout.toString().trim();
-					if (handoffPath) {
-						const handoffContent = await $`cat ${handoffPath}`.text();
-						handoffContext = `\n## Previous Session Handoff\n\n${handoffContent}\n\n**IMPORTANT**: Resume work from where previous session left off.`;
-					}
-				}
+				const info = await stat(fullPath);
+				return { name, fullPath, mtimeMs: info.mtimeMs };
 			} catch {
-				// No handoff files, skip
+				return { name, fullPath, mtimeMs: 0 };
 			}
+		}),
+	);
+
+	withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
+	const latest = withMtime[0];
+	const content = (await safeReadFile(latest.fullPath)).trim();
+	if (!content) return "";
+
+	return `Source: ${latest.name}\n${truncate(content, MAX_HANDOFF_CHARS)}`;
+}
+
+async function readInProgressBeads(directory: string): Promise<string> {
+	try {
+		const { stdout } = await execFileAsync(
+			"br",
+			["list", "--status", "in_progress", "--json"],
+			{
+				cwd: directory,
+				timeout: 10000,
+			},
+		);
+
+		const parsed = JSON.parse(stdout as string) as Array<{
+			id: string;
+			title: string;
+		}>;
+
+		if (!Array.isArray(parsed) || parsed.length === 0) return "";
+
+		return parsed
+			.slice(0, MAX_BEADS)
+			.map((item) => `- ${item.id}: ${item.title}`)
+			.join("\n");
+	} catch {
+		return "";
+	}
+}
+
+export const CompactionPlugin: Plugin = async ({ directory }) => {
+	const memoryDir = path.join(directory, ".opencode", "memory");
+	const handoffDir = path.join(memoryDir, "handoffs");
 
-			// Inject all context - session context FIRST (most important)
-			const allContext = [
-				sessionContext,
-				beadsContext,
-				handoffContext,
-				memoryContext,
+	return {
+		"experimental.session.compacting": async (_input, output) => {
+			const sessionContext = truncate(
+				(await safeReadFile(path.join(memoryDir, "session-context.md"))).trim(),
+				MAX_SESSION_CONTEXT_CHARS,
+			);
+
+			const [projectContext, beadsContext, handoffContext] = await Promise.all([
+				readProjectMemoryContext(memoryDir),
+				readInProgressBeads(directory),
+				readLatestHandoff(handoffDir),
+			]);
+
+			const combined = [
+				renderSection("Session Continuity", sessionContext),
+				renderSection("Active Beads", beadsContext),
+				renderSection("Previous Handoff", handoffContext),
+				renderSection("Project Memory", projectContext),
 			]
 				.filter(Boolean)
-				.join("\n");
+				.join("\n\n");
 
-			if (allContext) {
-				output.context.push(`## Session Context\n${allContext}\n`);
+			if (combined) {
+				output.context.push(
+					`## Session Context\n${truncate(combined, MAX_COMBINED_CONTEXT_CHARS)}\n`,
+				);
 			}
 
-			// Append post-compaction recovery protocol
-			// NOTE: Context management rules (distill/compress/prune, tool guidance)
-			// are handled by DCP plugin via experimental.chat.system.transform (always present).
-			// This plugin ONLY handles session continuity and post-compaction recovery.
 			output.prompt = `${output.prompt}
 
-## Post-Compaction Recovery Protocol
-
-### IMMEDIATE: Restore Session State (Do This First)
-1. Read session-context.md via \`memory-read({ file: "session-context" })\`
-2. If missing or stale, reconstruct from the compaction summary above
-3. Resume work from the "Now" item — do NOT restart from scratch
-4. Ask 1-3 targeted questions ONLY if critical gaps remain (don't interrogate)
-
-### Session Continuity Document
-Maintain session-context.md via memory-update tool. This is your lifeline after compaction.
-
-\`\`\`
-Goal: [What + measurable success criteria]
-Constraints: [Hard limits. Mark UNCONFIRMED if inferred, never assume]
-Decisions: [Key choices made this session + WHY]
-State:
-  Done: [Completed items with verification status]
-  Now: [Current focus - ONE thing only]
-  Next: [Queued items in priority order]
-Open Questions: [Uncertainties - mark UNCONFIRMED, note what would resolve each]
-Working Set: [Exact file paths, bead IDs, branch name, worktree path if applicable]
-\`\`\`
-
-Update session-context.md when: goal changes, key decision made, state shifts, or uncertainty discovered.
-
-### Preservation Priorities (Compaction-Specific)
-These items MUST survive compaction — if they appeared in conversation, include in summary:
-- **Bead state**: IDs (br-xxx), status, in-progress tasks, dependencies
-- **Todo items**: Exact IDs, statuses, priorities, content
-- **File paths**: Exact paths with line numbers where relevant
-- **User constraints**: Verbatim. Never paraphrase.
-- **Decisions + rationale**: Both WHAT and WHY
-- **UNCONFIRMED items**: Keep uncertainty markers intact
-
-### Memory Persistence (Before Compaction Loses It)
-Save discoveries to persistent memory so they survive:
-- Gotchas/edge cases → observation({ type: "warning", ... })
-- Architecture insights → observation({ type: "pattern", ... })
-- Key decisions → observation({ type: "decision", ... })
+<compaction_task>
+Summarize conversation state for reliable continuation after compaction.
+</compaction_task>
+
+<compaction_rules>
+- Preserve exact IDs, file paths, and unresolved constraints.
+- Distinguish completed work from current in-progress work.
+- Keep summary concise and execution-focused.
+- If critical context is missing, state uncertainty explicitly.
+</compaction_rules>
+
+<compaction_output>
+Include:
+- What was done
+- What is being worked on now
+- Files currently in play
+- Next actions
+- Persistent user constraints/preferences
+</compaction_output>
 `;
 		},
 	};

package/dist/template/.opencode/plugin/lib/memory-db.ts

@@ -85,6 +85,31 @@ export interface MemoryFileRow {
 	updated_at_epoch: number | null;
 }
 
+export type ActionQueueSource = "approval" | "bead" | "worker";
+export type ActionQueueStatus = "pending" | "ready" | "idle";
+
+export interface ActionQueueItemRow {
+	id: string;
+	source: ActionQueueSource;
+	status: ActionQueueStatus;
+	title: string;
+	owner: string | null;
+	payload: string | null;
+	created_at: string;
+	created_at_epoch: number;
+	updated_at: string | null;
+	updated_at_epoch: number | null;
+}
+
+export interface ActionQueueItemInput {
+	id: string;
+	source: ActionQueueSource;
+	status: ActionQueueStatus;
+	title: string;
+	owner?: string;
+	payload?: Record<string, unknown>;
+}
+
 // ============================================================================
 // Schema
 // ============================================================================
@@ -153,6 +178,23 @@ CREATE TABLE IF NOT EXISTS memory_files (
 );
 
 CREATE INDEX IF NOT EXISTS idx_memory_files_path ON memory_files(file_path);
+
+-- Action queue table for orchestration status snapshots
+CREATE TABLE IF NOT EXISTS action_queue_items (
+  id TEXT PRIMARY KEY,
+  source TEXT NOT NULL CHECK(source IN ('approval','bead','worker')),
+  status TEXT NOT NULL CHECK(status IN ('pending','ready','idle')),
+  title TEXT NOT NULL,
+  owner TEXT,
+  payload TEXT,
+  created_at TEXT NOT NULL,
+  created_at_epoch INTEGER NOT NULL,
+  updated_at TEXT,
+  updated_at_epoch INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_action_queue_status ON action_queue_items(status);
+CREATE INDEX IF NOT EXISTS idx_action_queue_source ON action_queue_items(source);
 `;
 
 // FTS5 sync triggers (separate because they can't use IF NOT EXISTS)
@@ -574,6 +616,76 @@ export function getMemoryFile(filePath: string): MemoryFileRow | null {
 		.get(filePath) as MemoryFileRow | null;
 }
 
+/**
+ * Replace action queue snapshot with a new set of items.
+ */
+export function replaceActionQueueItems(items: ActionQueueItemInput[]): void {
+	const db = getMemoryDB();
+	const now = new Date();
+
+	const insertStmt = db.query(
+		`
+			INSERT INTO action_queue_items
+			(id, source, status, title, owner, payload, created_at, created_at_epoch)
+			VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+			ON CONFLICT(id) DO UPDATE SET
+				source = excluded.source,
+				status = excluded.status,
+				title = excluded.title,
+				owner = excluded.owner,
+				payload = excluded.payload,
+				updated_at = excluded.created_at,
+				updated_at_epoch = excluded.created_at_epoch
+		`,
+	);
+
+	db.transaction(() => {
+		db.run("DELETE FROM action_queue_items");
+		for (const item of items) {
+			insertStmt.run(
+				item.id,
+				item.source,
+				item.status,
+				item.title,
+				item.owner ?? null,
+				item.payload ? JSON.stringify(item.payload) : null,
+				now.toISOString(),
+				now.getTime(),
+			);
+		}
+	})();
+}
+
+/**
+ * Return action queue items, optionally filtered by status.
+ */
+export function listActionQueueItems(
+	status?: ActionQueueStatus,
+): ActionQueueItemRow[] {
+	const db = getMemoryDB();
+	if (!status) {
+		return db
+			.query(
+				"SELECT * FROM action_queue_items ORDER BY created_at_epoch DESC, id ASC",
+			)
+			.all() as ActionQueueItemRow[];
+	}
+
+	return db
+		.query(
+			"SELECT * FROM action_queue_items WHERE status = ? ORDER BY created_at_epoch DESC, id ASC",
+		)
+		.all(status) as ActionQueueItemRow[];
+}
+
+/**
+ * Clear all action queue items.
+ */
+export function clearActionQueueItems(): void {
+	const db = getMemoryDB();
+	db.run("DELETE FROM action_queue_items");
+}
+
 // ============================================================================
 // FTS5 Maintenance
 // ============================================================================