opencodekit 0.12.2 → 0.12.4

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

@@ -366,10 +366,12 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 		filePath: string,
 		reason?: string,
 		ttlSeconds = 600,
+		overrideAgent?: string,
 	): Promise<{ acquired: boolean; holder?: string }> {
 		const lockPath = lockDir(filePath);
 		const now = Date.now();
 		const expires = now + ttlSeconds * 1000;
+		const agentToUse = overrideAgent || state.agentId;
 
 		// Atomic: mkdir fails if dir exists
 		try {
@@ -384,10 +386,10 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 				if (lock.expires < now) {
 					// Expired - remove and retry
 					await $`rm -rf ${lockPath}`.cwd(directory).quiet();
-					return acquireLock(filePath, reason, ttlSeconds);
+					return acquireLock(filePath, reason, ttlSeconds, overrideAgent);
 				}
 
-				if (lock.agent === state.agentId) {
+				if (lock.agent === agentToUse) {
 					// We already hold this lock - refresh it
 					lock.expires = expires;
 					await $`echo ${JSON.stringify(lock)} > ${metaPath}`
@@ -400,14 +402,14 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 			} catch {
 				// Corrupted lock - remove and retry
 				await $`rm -rf ${lockPath}`.cwd(directory).quiet();
-				return acquireLock(filePath, reason, ttlSeconds);
+				return acquireLock(filePath, reason, ttlSeconds, overrideAgent);
 			}
 		}
 
 		// Lock acquired - write metadata
 		const lockData: LockData = {
 			path: filePath,
-			agent: state.agentId,
+			agent: agentToUse,
 			reason,
 			created: now,
 			expires,
@@ -597,7 +599,7 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 					role: tool.schema
 						.string()
 						.optional()
-						.describe("Role: fe|be|mobile|devops|qa"),
+						.describe("Role: build|rush|explore|planner|review|scout|vision"),
 				},
 				async execute(args) {
 					await $`bd init`
@@ -670,11 +672,17 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						.default("completed")
 						.describe("Completion message"),
 				},
-				async execute(args) {
+				async execute(args, context) {
 					const taskId = args.id || state.currentTask;
 					if (!taskId) return json({ error: "No task ID" });
 
-					const closeResult = await bdClose(taskId, args.msg);
+					// Audit trail
+					const auditAgent = context?.agent || state.agentId;
+
+					const closeResult = await bdClose(
+						taskId,
+						`${args.msg} [by ${auditAgent}]`,
+					);
 					if (closeResult.error) return json({ error: closeResult.error });
 
 					// Release all locks
@@ -708,7 +716,9 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 					tags: tool.schema
 						.array(tool.schema.string())
 						.optional()
-						.describe("Role tags: fe,be,mobile,devops,qa"),
+						.describe(
+							"Agent tags: build,rush,explore,planner,review,scout,vision",
+						),
 					parent: tool.schema.string().optional().describe("Parent issue ID"),
 					deps: tool.schema
 						.array(tool.schema.string())
@@ -754,7 +764,9 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 					"Assign task to role (leader only). Adds tag and notifies.",
 				args: {
 					id: tool.schema.string().describe("Issue ID"),
-					role: tool.schema.string().describe("Role: fe|be|mobile|devops|qa"),
+					role: tool.schema
+						.string()
+						.describe("Role: build|rush|explore|planner|review|scout|vision"),
 					notify: tool.schema
 						.boolean()
 						.default(true)
@@ -882,16 +894,24 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						.default(600)
 						.describe("Seconds until expiry"),
 				},
-				async execute(args) {
+				async execute(args, context) {
 					if (!args.paths?.length) return json({ error: "paths required" });
 
+					// Log who is reserving for audit
+					const reservingAgent = context?.agent || state.agentId;
+
 					await ensureReservationsDir();
 
 					const granted: string[] = [];
 					const conflicts: { path: string; holder?: string }[] = [];
 
 					for (const path of args.paths) {
-						const result = await acquireLock(path, args.reason, args.ttl);
+						const result = await acquireLock(
+							path,
+							args.reason,
+							args.ttl,
+							reservingAgent,
+						);
 						if (result.acquired) {
 							granted.push(path);
 						} else {
@@ -963,12 +983,15 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						.default(false)
 						.describe("Send to all workspaces"),
 				},
-				async execute(args) {
+				async execute(args, context) {
 					if (!args.subj) return json({ error: "subj required" });
 
+					// Use context agent if available for audit trail
+					const senderAgent = context?.agent || state.agentId;
+
 					const msg: Message = {
 						id: `msg-${Date.now().toString(36)}`,
-						from: state.agentId,
+						from: senderAgent,
 						to: args.to || "all",
 						subj: args.subj,
 						body: args.body,
@@ -1000,6 +1023,117 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 				},
 			}),
 
+			bd_ack: tool({
+				description: "Acknowledge message(s). Marks as read.",
+				args: {
+					ids: tool.schema
+						.array(tool.schema.string())
+						.describe("Message IDs to acknowledge"),
+				},
+				async execute(args) {
+					if (!args.ids?.length) return json({ error: "ids required" });
+
+					try {
+						const content =
+							await $`cat ${RESERVATIONS_DIR}/messages.jsonl 2>/dev/null`
+								.cwd(directory)
+								.text();
+
+						if (!content.trim()) return json({ acked: 0 });
+
+						const idsToAck = new Set(args.ids);
+						let acked = 0;
+
+						const msgs = content
+							.trim()
+							.split("\n")
+							.map((line) => {
+								try {
+									const msg = JSON.parse(line) as Message;
+									if (idsToAck.has(msg.id) && !msg.read) {
+										msg.read = true;
+										acked++;
+									}
+									return msg;
+								} catch {
+									return null;
+								}
+							})
+							.filter((m): m is Message => m !== null);
+
+						const newContent = msgs.map((m) => JSON.stringify(m)).join("\n");
+						await $`echo ${newContent} > ${RESERVATIONS_DIR}/messages.jsonl`
+							.cwd(directory)
+							.quiet();
+
+						return json({ ok: 1, acked });
+					} catch {
+						return json({ acked: 0 });
+					}
+				},
+			}),
+
+			bd_whois: tool({
+				description: "Agent directory lookup. See who's working on what.",
+				args: {
+					agent: tool.schema
+						.string()
+						.optional()
+						.describe("Agent ID to lookup (empty=all)"),
+				},
+				async execute(args) {
+					const locks = await getAllLocks();
+					const { tasks: inProgressTasks } = await bdList({
+						status: "in_progress",
+					});
+
+					// Build agent activity map
+					const agentMap: Record<
+						string,
+						{
+							files: string[];
+							task?: string;
+							role?: string;
+						}
+					> = {};
+
+					// Add locks info
+					for (const lock of locks) {
+						if (!agentMap[lock.agent]) {
+							agentMap[lock.agent] = { files: [] };
+						}
+						agentMap[lock.agent].files.push(lock.path);
+						if (lock.task) {
+							agentMap[lock.agent].task = lock.task;
+						}
+					}
+
+					// Add current agent info
+					if (!agentMap[state.agentId]) {
+						agentMap[state.agentId] = { files: [] };
+					}
+					agentMap[state.agentId].role = state.role || undefined;
+					if (state.currentTask) {
+						agentMap[state.agentId].task = state.currentTask;
+					}
+
+					// Filter if specific agent requested
+					if (args.agent) {
+						const agent = agentMap[args.agent];
+						if (!agent) return json({ error: "agent not found" });
+						return json({ agent: args.agent, ...agent });
+					}
+
+					return json({
+						agents: Object.entries(agentMap).map(([id, info]) => ({
+							id,
+							...info,
+						})),
+						in_progress_tasks: inProgressTasks.length,
+					});
+				},
+			}),
+
 			bd_status: tool({
 				description: "Workspace overview. Shows agents, tasks, locks.",
 				args: {
@@ -1038,10 +1172,22 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 
 			bd_sync: tool({
 				description: "Sync with git. Pull/push changes.",
-				args: {},
-				async execute() {
+				args: {
+					reason: tool.schema
+						.string()
+						.optional()
+						.describe("Audit trail reason for sync"),
+				},
+				async execute(args, context) {
 					const result = await bdSync();
-					return json({ ok: 1, output: result.output });
+					// Log sync with context for audit trail
+					const syncAgent = context?.agent || state.agentId;
+					return json({
+						ok: 1,
+						output: result.output,
+						by: syncAgent,
+						reason: args.reason,
+					});
 				},
 			}),
 
@@ -1249,6 +1395,25 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 			if (event.type === "session.idle" && state.currentTask) {
 				await bdSync();
 			}
+
+			// Cleanup expired locks on compaction
+			if (event.type === "session.compacted") {
+				await cleanupExpiredLocks();
+			}
+
+			// Log errors to audit trail
+			if (event.type === "session.error" && state.currentTask) {
+				await appendMessage({
+					id: `err-${Date.now().toString(36)}`,
+					from: state.agentId,
+					to: "all",
+					subj: `Session error on task ${state.currentTask}`,
+					body: `Error occurred during task execution`,
+					importance: "high",
+					at: Date.now(),
+					read: false,
+				});
+			}
 		},
 	};
 };

package/dist/template/.opencode/skill/beads/SKILL.md

@@ -340,6 +340,21 @@ bd_msg({
 bd_inbox({ unread: true, n: 10 });
 ```
 
+### Acknowledge Messages
+
+```typescript
+bd_ack({ ids: ["msg-abc", "msg-def"] }); // Mark as read
+```
+
+## Agent Coordination
+
+### Who's Working on What
+
+```typescript
+bd_whois(); // All agents with their files and tasks
+bd_whois({ agent: "build-abc" }); // Specific agent lookup
+```
+
 ## Status and Analysis
 
 ### Workspace Overview

package/dist/template/.opencode/skill/context-engineering/SKILL.md

@@ -0,0 +1,94 @@
+---
+description: Use when managing context window, deciding what to load/prune, or understanding AI adoption stages - covers constraint awareness and intent layer principles
+---
+
+# Context Engineering Skill
+
+## AI Adoption Stages
+
+OpenCode operates at **Stage 5-6**:
+
+- **Stage 5** (Agentic Verification): Agents run tests and iterate autonomously
+- **Stage 6** (Multi-Agent Orchestration): Parallel workstreams with coordination
+
+**Current constraint**: Planning and specification quality. Implementation capacity is not the bottleneck—how well you specify requirements is.
+
+## Autonomous Duration
+
+The key metric: **How long can an agent work before losing the plot?**
+
+Extend autonomous duration by:
+
+- Binding tighter to intent (clear specs, constraints, invariants)
+- Providing systematic context (AGENTS.md hierarchy, memory files)
+- Verification loops (test → iterate → verify)
+
+## Greenfield vs Legacy
+
+| Type           | Context                    | Agent Performance             |
+| -------------- | -------------------------- | ----------------------------- |
+| **Greenfield** | Simple, fast prototypes    | Works well immediately        |
+| **Legacy**     | Complex, hidden invariants | Needs careful context loading |
+
+Codebase complexity is a primary difficulty knob. Context is how you pay it down.
+
+## Three Context Constraints
+
+1. **Blind spots cause hallucinations** - If agent doesn't see specific context, it fills gaps with generic training priors. You only get the behavior you load.
+
+2. **Everything influences everything** - Noise-to-signal ratio matters. Irrelevant files degrade ALL output quality.
+
+3. **Window is finite** - Performance degrades BEFORE hitting hard token limits. Curate the smallest, highest-signal slice.
+
+## Practical Implications
+
+| Instead of              | Do This                                               |
+| ----------------------- | ----------------------------------------------------- |
+| Reading entire files    | Use `lsp_lsp_document_symbols` for outline            |
+| Loading whole documents | Read specific line ranges                             |
+| Flat file loading       | Navigate AGENTS.md hierarchy (progressive disclosure) |
+| Keeping completed work  | Prune context aggressively                            |
+
+## Intent Layer Principles
+
+### What Belongs in Each AGENTS.md
+
+- **Purpose & Scope** - What this area does. What it explicitly DOESN'T do.
+- **Entry Points & Contracts** - Main APIs, invariants, "all X goes through Y"
+- **Usage Patterns** - Canonical examples: "To add a rule, follow this pattern..."
+- **Anti-patterns** - Negative examples: "Never call X directly; go through Y"
+- **Dependencies & Downlinks** - What it connects to, pointers to child AGENTS.md
+- **Pitfalls** - Things that repeatedly confused agents/humans
+
+### Key Mechanics
+
+| Principle                       | Meaning                                                       |
+| ------------------------------- | ------------------------------------------------------------- |
+| **Hierarchical loading**        | When a node loads, all ancestors load too (T-shaped view)     |
+| **Compression, not bloat**      | Good nodes compress code; 10k tokens for 20k code adds weight |
+| **Least Common Ancestor (LCA)** | Place shared knowledge at shallowest node covering all paths  |
+| **Downlinks for discovery**     | Point to related context without loading everything upfront   |
+
+## Context Budget Guidelines
+
+| Phase             | Target Context | Action                                    |
+| ----------------- | -------------- | ----------------------------------------- |
+| Starting work     | <50k tokens    | Load only essential AGENTS.md + task spec |
+| Mid-task          | 50-100k tokens | Prune completed reads, keep active files  |
+| Approaching limit | >100k tokens   | Aggressive pruning, extract key findings  |
+| Near capacity     | >150k tokens   | Consider session restart with handoff     |
+
+## Anti-Patterns
+
+❌ Loading "everything that might be relevant"
+❌ Keeping old file reads after editing complete
+❌ Reading entire files when you only need a function
+❌ Ignoring AGENTS.md hierarchy (loading leaf without ancestors)
+
+## Best Practices
+
+✅ Start with minimum viable context
+✅ Use LSP tools for targeted information
+✅ Prune after each completed sub-task
+✅ Trust AGENTS.md hierarchy for discovery
+✅ Extract findings before pruning valuable reads

package/dist/template/.opencode/skill/memory-system/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: memory-system
+description: Use when persisting learnings, loading previous context, or searching past decisions - covers memory file structure, tools, and when to update each file
+---
+
+# Memory System
+
+Persistent context that survives across sessions.
+
+## Directory Structure
+
+```
+.opencode/memory/
+  _templates/     # Task templates (prd, observation, session-summary)
+  handoffs/       # Phase transitions
+  research/       # Research findings
+  observations/   # Structured observations
+  project/        # Persistent project knowledge
+    commands.md       # Build, test, lint, deploy commands
+    conventions.md    # Code patterns, commit style, PR process
+    gotchas.md        # Footguns, edge cases, "don't forget this"
+    architecture.md   # Key modules, directory structure
+  user.md         # Identity, preferences, communication style
+```
+
+## Standard Memory Blocks
+
+| File                      | Purpose                  | Update When                 |
+| ------------------------- | ------------------------ | --------------------------- |
+| `project/commands.md`     | Build/test/lint commands | Discovering new command     |
+| `project/conventions.md`  | Code patterns, style     | Learning team pattern       |
+| `project/gotchas.md`      | Footguns, warnings       | Hitting unexpected behavior |
+| `project/architecture.md` | Key modules, structure   | Mapping new area            |
+| `user.md`                 | Preferences, workflow    | Learning user preference    |
+
+## Explicit Memory Updates
+
+Don't rely on implicit learning. Explicitly persist:
+
+- Non-obvious project behavior → `project/gotchas.md`
+- User preferences discovered → `user.md`
+- New build/test commands → `project/commands.md`
+- Code patterns to follow → `project/conventions.md`
+
+## Memory Tools
+
+### memory-read
+
+Load previous context or templates:
+
+```typescript
+memory - read({ file: "project/commands" }); // Load commands
+memory - read({ file: "_templates/prd" }); // Load PRD template
+memory - read({ file: "handoffs/bd-abc123" }); // Load specific handoff
+```
+
+### memory-update
+
+Save learnings or handoffs:
+
+```typescript
+memory -
+  update({
+    file: "project/gotchas",
+    content: "### New Gotcha\n\nDescription...",
+    mode: "append", // or "replace"
+  });
+```
+
+### memory-search
+
+Find past decisions, research, or handoffs:
+
+```typescript
+memory - search({ query: "authentication" });
+memory - search({ query: "bugfix", type: "observations" });
+memory - search({ query: "session", type: "handoffs" });
+```
+
+## Observations
+
+Record important findings with structured metadata:
+
+```typescript
+observation({
+  type: "decision", // decision, bugfix, feature, pattern, discovery, learning, warning
+  title: "Use JWT auth",
+  content: "Decided to use JWT because...",
+  concepts: "auth, security",
+  files: "src/auth.ts",
+  bead_id: "bd-abc123",
+});
+```
+
+**When to create observations:**
+
+- Major architectural decisions
+- Bug root causes discovered
+- Patterns worth reusing
+- Gotchas and warnings for future
+
+## Best Practices
+
+1. **Read before work** - Check relevant memory files at session start
+2. **Update during work** - Don't wait until end; persist incrementally
+3. **Be specific** - Include file paths, function names, concrete examples
+4. **Keep it actionable** - Future agents should know what to do with the info

package/dist/template/.opencode/skill/session-management/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: session-management
+description: Use when context is growing large, switching tasks, or needing previous session context - covers thresholds, session tools, and workflow patterns
+---
+
+# Session Management
+
+**Philosophy**: Short sessions (<150k tokens) beat long bloated ones. Agents get worse with too much context. Cost is exponential.
+
+## Context Thresholds
+
+The environment monitors context usage and warns at these thresholds:
+
+| Threshold | Action                                                     |
+| --------- | ---------------------------------------------------------- |
+| **70%**   | Consolidate work; consider pruning irrelevant tool outputs |
+| **85%**   | Summarize findings and consider starting a new session     |
+| **95%**   | Critical: prune context immediately or restart session     |
+
+## Session Tools
+
+### list_sessions
+
+Discover available sessions before reading:
+
+```typescript
+list_sessions({ limit: 10, project: "current" }); // Current project
+list_sessions({ since: "today" }); // Today's sessions
+list_sessions({ project: "all", since: "yesterday" }); // Cross-project
+```
+
+### read_session
+
+Pull context from previous session:
+
+```typescript
+read_session("last"); // Most recent
+read_session("2 ago", { project: "current" }); // 2nd most recent
+read_session("today"); // Today's first session
+read_session("ses_abc123", { focus: "file changes" }); // Specific aspect
+```
+
+### search_session
+
+Full-text search across sessions:
+
+```typescript
+search_session({ query: "auth bug" }); // Search all sessions
+search_session({ query: "OAuth", session_id: "ses_abc" }); // Specific session
+search_session({ query: "error", limit: 10 }); // Limit results
+```
+
+Use to find past discussions, decisions, or work on a topic before starting new work.
+
+### summarize_session
+
+Generate AI summary of a session:
+
+```typescript
+summarize_session("ses_abc123"); // Trigger AI summarization
+```
+
+Use before `read_session` to get a quick overview of what happened in a past session without loading full context.
+
+## When to Start New Session
+
+- Completing distinct task from `bd ready`
+- Token usage approaching 150k
+- Switching phases (implementation → review → testing)
+- After handoff (`/handoff <bead-id>`)
+
+## Session Workflow Pattern
+
+```
+Session 1: Implement feature X (80k tokens)
+  ↓ close, update memory
+Session 2: list_sessions() → read_session("last") → Refactor (60k tokens)
+  ↓
+Session 3: read_session("previous") → Add tests (90k tokens)
+  ↓
+Session 4: read_session refs → Final review (100k tokens)
+```
+
+**Result**: 4 fresh contexts vs 1 degraded 330k context. Better performance, lower cost.
+
+## Context Transfer
+
+Use all available sources:
+
+1. `read_session("last")` - Previous session work
+2. Git state - `git diff`, `git log` - Code changes
+3. Memory files - `.opencode/memory/*` - Persistent context
+4. Beads - `bd show <id>` - Task specs
+
+**Don't**: Carry everything forward. Extract what's needed, discard the rest.
+
+## Pruning Strategy
+
+When context grows large:
+
+1. **Discard** completed task outputs (read files you won't edit again)
+2. **Extract** key findings before discarding research
+3. **Summarize** complex investigations into memory files
+4. **Restart** session if above 85% and work is at a natural break
+
+## Anti-Patterns
+
+- ❌ Running until context limit forces restart
+- ❌ Carrying all previous reads forward "just in case"
+- ❌ Not using memory files for cross-session persistence
+- ❌ Re-reading the same files every session instead of extracting key info