yams-blackboard 0.1.1

package/DESIGN.md

@@ -0,0 +1,344 @@
+# YAMS Blackboard Plugin - Schema Design
+
+## Overview
+
+This plugin implements a **blackboard architecture** for agent-to-agent communication using YAMS as the shared memory store. Agents post findings, claim tasks, and discover each other's work through structured queries.
+
+## Core Entities
+
+### 1. Agent Card
+
+Agents self-register their identity and capabilities. This enables:
+- Capability-based task routing
+- Agent discovery for collaboration
+- Audit trail of who contributed what
+
+```typescript
+interface AgentCard {
+  id: string                    // Unique identifier, e.g., "security-scanner"
+  name: string                  // Human-readable name
+  capabilities: string[]        // What this agent can do
+  version?: string              // Agent version
+  registered_at: string         // ISO timestamp
+  status: "active" | "idle" | "offline"
+}
+```
+
+**Storage**: `agents/{agent_id}.json`
+**Tags**: `agent, capability:{cap1}, capability:{cap2}`
+
+---
+
+### 2. Finding
+
+The core unit of agent communication. Findings are discoveries, observations, or outputs that other agents may want to know about.
+
+```typescript
+interface Finding {
+  // Identity
+  id: string                    // Auto-generated: f-{timestamp}-{random}
+  agent_id: string              // Who produced this
+
+  // Classification
+  topic: string                 // Category: security, performance, bug, architecture, refactor, test, doc
+  title: string                 // Brief summary (< 100 chars)
+
+  // Content
+  content: string               // Full details (markdown)
+
+  // Confidence & Priority
+  confidence: number            // 0.0 - 1.0, how certain the agent is
+  severity?: "info" | "low" | "medium" | "high" | "critical"
+
+  // Context & Relationships
+  context_id?: string           // Groups related findings (e.g., a task ID)
+  references?: Reference[]      // Links to code, docs, other findings
+  parent_id?: string            // For threaded/reply findings
+
+  // Lifecycle
+  status: "draft" | "published" | "acknowledged" | "resolved" | "rejected"
+  created_at: string            // ISO timestamp
+  updated_at?: string
+  resolved_by?: string          // Agent that resolved this
+  resolution?: string           // How it was resolved
+
+  // Persistence
+  scope: "session" | "persistent"  // Default: persistent
+  ttl?: number                  // Optional TTL in seconds (for session-scoped)
+
+  // Arbitrary metadata
+  metadata?: Record<string, string>
+}
+
+interface Reference {
+  type: "file" | "url" | "finding" | "task" | "symbol"
+  target: string                // Path, URL, ID, or symbol name
+  label?: string                // Human-readable label
+  line_start?: number           // For file references
+  line_end?: number
+}
+```
+
+**Storage**: `findings/{topic}/{id}.md` (with YAML frontmatter)
+**Tags**: `finding, agent:{id}, topic:{topic}, severity:{sev}, scope:{scope}, status:{status}`
+
+---
+
+### 3. Task
+
+For coordinated workflows where agents need to claim work, track progress, and hand off results.
+
+```typescript
+interface Task {
+  // Identity
+  id: string                    // Auto-generated: t-{timestamp}-{random}
+
+  // Description
+  title: string                 // What needs to be done
+  description?: string          // Detailed requirements
+
+  // Classification
+  type: "analysis" | "fix" | "review" | "test" | "research" | "synthesis"
+  priority: 0 | 1 | 2 | 3 | 4   // 0 = critical, 4 = backlog
+
+  // Lifecycle
+  status: "pending" | "claimed" | "working" | "blocked" | "review" | "completed" | "failed" | "cancelled"
+
+  // Assignment
+  created_by: string            // Agent that created the task
+  assigned_to?: string          // Agent currently working on it
+  claimed_at?: string
+
+  // Dependencies
+  depends_on?: string[]         // Task IDs that must complete first
+  blocks?: string[]             // Task IDs waiting on this
+
+  // Results
+  findings?: string[]           // Finding IDs produced by this task
+  artifacts?: Artifact[]        // Output files/data
+
+  // Context
+  context_id?: string           // Groups related tasks
+  parent_task?: string          // For subtasks
+
+  // Timestamps
+  created_at: string
+  updated_at?: string
+  completed_at?: string
+
+  // Failure handling
+  error?: string                // Error message if failed
+  retry_count?: number
+  max_retries?: number
+}
+
+interface Artifact {
+  name: string
+  type: "file" | "data" | "report"
+  path?: string                 // YAMS path or local path
+  hash?: string                 // YAMS content hash
+  mime_type?: string
+}
+```
+
+**Storage**: `tasks/{id}.json`
+**Tags**: `task, type:{type}, status:{status}, priority:{p}, creator:{id}, assignee:{id}`
+
+**State Machine**:
+```
+                    ┌──────────────────────────────────────┐
+                    │                                      │
+                    ▼                                      │
+┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐  │
+│ pending │───▶│ claimed │───▶│ working │───▶│ review  │──┤
+└─────────┘    └─────────┘    └─────────┘    └─────────┘  │
+     │              │              │              │        │
+     │              │              ▼              │        │
+     │              │         ┌─────────┐        │        │
+     │              └────────▶│ blocked │────────┘        │
+     │                        └─────────┘                 │
+     │                                                    │
+     │         ┌───────────┐    ┌─────────┐              │
+     └────────▶│ cancelled │    │completed│◀─────────────┘
+               └───────────┘    └─────────┘
+                                     ▲
+                                     │
+                               ┌─────────┐
+                               │ failed  │
+                               └─────────┘
+```
+
+---
+
+### 4. Context
+
+Groups related findings and tasks into a coherent unit of work.
+
+```typescript
+interface Context {
+  id: string                    // Auto-generated or user-provided
+  name: string                  // Human-readable name
+  description?: string
+
+  // Aggregates
+  findings: string[]            // Finding IDs in this context
+  tasks: string[]               // Task IDs in this context
+  agents: string[]              // Agents that contributed
+
+  // Lifecycle
+  status: "active" | "completed" | "archived"
+  created_at: string
+  updated_at?: string
+
+  // Summary (for compaction)
+  summary?: string              // AI-generated summary
+  key_findings?: string[]       // Most important finding IDs
+}
+```
+
+**Storage**: `contexts/{id}.json`
+**Tags**: `context, status:{status}`
+
+---
+
+## Naming Conventions
+
+### Tags
+
+All entities use hierarchical tags for efficient filtering:
+
+| Prefix | Purpose | Examples |
+|--------|---------|----------|
+| `agent:` | Source agent | `agent:security-scanner` |
+| `topic:` | Finding category | `topic:security`, `topic:performance` |
+| `severity:` | Finding severity | `severity:high`, `severity:critical` |
+| `status:` | Lifecycle state | `status:published`, `status:completed` |
+| `scope:` | Persistence | `scope:session`, `scope:persistent` |
+| `type:` | Task type | `type:fix`, `type:review` |
+| `priority:` | Task priority | `priority:0`, `priority:2` |
+| `ctx:` | Context grouping | `ctx:audit-2025-01` |
+| `capability:` | Agent capability | `capability:code-review` |
+
+### Paths
+
+```
+agents/{agent_id}.json
+findings/{topic}/{finding_id}.md
+tasks/{task_id}.json
+contexts/{context_id}.json
+```
+
+---
+
+## Compaction Behavior
+
+When OpenCode compacts a session, the plugin:
+
+1. **Queries active context** - Gets all findings/tasks in current context
+2. **Generates summary** - Uses structured template:
+
+```markdown
+## Blackboard Summary
+
+### Agents Active
+- security-scanner: code-review, vuln-detection
+- performance-analyzer: profiling, optimization
+
+### Key Findings ({count} total)
+- [HIGH] SQL injection in auth module (security-scanner, 0.95 confidence)
+- [MEDIUM] N+1 query in user list (performance-analyzer, 0.87 confidence)
+- ...
+
+### Tasks
+- [COMPLETED] Audit authentication flow (2 findings)
+- [WORKING] Fix SQL injection vulnerability (assigned: code-fixer)
+- [PENDING] Review performance optimizations (blocked by: t-xxx)
+
+### Unresolved Issues
+- Finding f-xxx still unacknowledged
+- Task t-yyy blocked for >1 hour
+```
+
+3. **Injects into context** - Adds summary to `output.context`
+
+---
+
+## Session vs Persistent Scope
+
+| Aspect | Session-Scoped | Persistent |
+|--------|----------------|------------|
+| **Default** | No | Yes |
+| **Survives restart** | No | Yes |
+| **Use case** | Temporary scratch work | Long-term knowledge |
+| **Cleanup** | Auto on session end | Manual or TTL |
+| **Example** | Draft findings, WIP | Confirmed bugs, decisions |
+
+To make a finding session-scoped:
+```typescript
+bb_post_finding({
+  // ...
+  scope: "session",
+  ttl: 3600  // Optional: auto-delete after 1 hour
+})
+```
+
+---
+
+## Tool Summary
+
+| Tool | Purpose |
+|------|---------|
+| `bb_register_agent` | Register agent identity and capabilities |
+| `bb_post_finding` | Publish a finding to the blackboard |
+| `bb_query_findings` | Filter findings by topic, agent, severity, etc. |
+| `bb_search_findings` | Semantic search across findings |
+| `bb_acknowledge_finding` | Mark a finding as seen/acknowledged |
+| `bb_resolve_finding` | Mark a finding as resolved |
+| `bb_create_task` | Create a new task |
+| `bb_claim_task` | Claim a pending task |
+| `bb_update_task` | Update task status/progress |
+| `bb_complete_task` | Mark task completed with results |
+| `bb_fail_task` | Mark task as failed |
+| `bb_get_ready_tasks` | Get tasks ready to work (no blockers) |
+| `bb_list_agents` | List registered agents |
+| `bb_create_context` | Create a new context grouping |
+| `bb_get_context_summary` | Get summary of a context |
+| `bb_recent_activity` | Get recent findings and task updates |
+
+---
+
+## Example Workflow
+
+```
+1. Agents register on session start
+   bb_register_agent({ id: "scanner", capabilities: ["security", "lint"] })
+   bb_register_agent({ id: "fixer", capabilities: ["code-fix", "refactor"] })
+
+2. Scanner posts findings
+   bb_post_finding({
+     agent_id: "scanner",
+     topic: "security",
+     title: "XSS in user profile",
+     severity: "high",
+     confidence: 0.91
+   })
+
+3. Coordinator creates task
+   bb_create_task({
+     title: "Fix XSS vulnerability",
+     type: "fix",
+     priority: 1,
+     context_id: "security-audit"
+   })
+
+4. Fixer claims and works
+   bb_claim_task({ task_id: "t-xxx", agent_id: "fixer" })
+   bb_update_task({ task_id: "t-xxx", status: "working" })
+
+5. Fixer completes with finding
+   bb_post_finding({ ..., context_id: "security-audit", parent_id: "f-original" })
+   bb_complete_task({ task_id: "t-xxx", findings: ["f-fix"] })
+
+6. Original finding resolved
+   bb_resolve_finding({ finding_id: "f-original", resolved_by: "fixer", resolution: "Fixed in PR #123" })
+```

package/README.md

@@ -0,0 +1,268 @@
+# YAMS Blackboard Plugin for OpenCode
+
+A **blackboard architecture** plugin enabling agent-to-agent communication through [YAMS](https://github.com/yams-project/yams) as shared memory.
+
+## Overview
+
+This plugin implements the classic [blackboard pattern](https://en.wikipedia.org/wiki/Blackboard_system) for multi-agent AI systems. Agents post findings, claim tasks, and discover each other's work through a shared knowledge store.
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   YAMS BLACKBOARD                   │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
+│  │  Findings   │  │   Tasks     │  │   Context   │ │
+│  │  (tagged)   │  │  (status)   │  │   (graph)   │ │
+│  └─────────────┘  └─────────────┘  └─────────────┘ │
+└─────────────────────────────────────────────────────┘
+        ▲ write            ▲ write           │ read
+        │                  │                 ▼
+   ┌────┴────┐        ┌────┴────┐       ┌────────┐
+   │ Agent A │        │ Agent B │       │ Agent C │
+   │ (scan)  │        │ (review)│       │(synthesize)│
+   └─────────┘        └─────────┘       └────────┘
+```
+
+## Prerequisites
+
+- **YAMS daemon** must be installed and running
+- **bun** (for local development/building)
+- **OpenCode** v1.1.0+ (for plugin support)
+
+## Installation
+
+### Option 1: npm (Recommended)
+
+Add to your `opencode.json`:
+
+```json
+{
+  "plugins": ["yams-blackboard"]
+}
+```
+
+OpenCode automatically installs npm plugins at startup.
+
+### Option 2: Local Plugin
+
+Copy to your project's `.opencode/plugin/` directory:
+
+```bash
+mkdir -p .opencode/plugin/yams-blackboard
+cp -r * .opencode/plugin/yams-blackboard/
+```
+
+### Verify YAMS is Running
+
+The plugin communicates with YAMS via CLI. Ensure the daemon is running:
+
+```bash
+yams daemon start
+yams status
+```
+
+## Tools
+
+### Agent Management
+
+| Tool | Description |
+|------|-------------|
+| `bb_register_agent` | Register agent identity and capabilities |
+| `bb_list_agents` | List all registered agents |
+
+### Findings
+
+| Tool | Description |
+|------|-------------|
+| `bb_post_finding` | Post a finding to the blackboard |
+| `bb_query_findings` | Query findings by topic, agent, severity |
+| `bb_search_findings` | Semantic search across findings |
+| `bb_get_finding` | Get full details of a finding |
+| `bb_acknowledge_finding` | Mark a finding as acknowledged |
+| `bb_resolve_finding` | Mark a finding as resolved |
+
+### Tasks
+
+| Tool | Description |
+|------|-------------|
+| `bb_create_task` | Create a new task |
+| `bb_get_ready_tasks` | Get tasks ready to work (no blockers) |
+| `bb_claim_task` | Claim a pending task |
+| `bb_update_task` | Update task status |
+| `bb_complete_task` | Mark task completed |
+| `bb_fail_task` | Mark task as failed |
+| `bb_query_tasks` | Query tasks by type, status, assignee |
+
+### Context & Utility
+
+| Tool | Description |
+|------|-------------|
+| `bb_create_context` | Create a context to group findings/tasks |
+| `bb_get_context_summary` | Get summary of a context |
+| `bb_set_context` | Set current working context |
+| `bb_recent_activity` | Get recent findings and tasks |
+| `bb_stats` | Get blackboard statistics |
+| `bb_connections` | Explore graph connections |
+
+## Example Workflow
+
+```typescript
+// Agent 1: Security scanner registers and posts finding
+bb_register_agent({
+  id: "scanner",
+  name: "Security Scanner",
+  capabilities: ["security", "code-review"]
+})
+
+bb_post_finding({
+  agent_id: "scanner",
+  topic: "security",
+  title: "SQL Injection in auth.ts:42",
+  severity: "high",
+  confidence: 0.92,
+  content: "Found unsanitized user input passed directly to SQL query...",
+  references: [{ type: "file", target: "src/auth.ts", line_start: 42 }]
+})
+
+// Agent 2: Fixer discovers the finding
+bb_search_findings({ query: "SQL injection" })
+
+// Coordinator creates a task
+bb_create_task({
+  title: "Fix SQL injection vulnerability",
+  type: "fix",
+  created_by: "coordinator",
+  priority: 1
+})
+
+// Fixer claims and works
+bb_claim_task({ task_id: "t-xxx", agent_id: "fixer" })
+bb_update_task({ task_id: "t-xxx", status: "working" })
+
+// Fixer completes and resolves
+bb_complete_task({ task_id: "t-xxx", findings: ["f-fix-001"] })
+bb_resolve_finding({
+  finding_id: "f-original",
+  agent_id: "fixer",
+  resolution: "Parameterized queries added in PR #123"
+})
+```
+
+## Schemas
+
+### Finding
+
+```typescript
+interface Finding {
+  id: string
+  agent_id: string
+  topic: "security" | "performance" | "bug" | "architecture" | ...
+  title: string
+  content: string
+  confidence: number        // 0.0 - 1.0
+  severity?: "info" | "low" | "medium" | "high" | "critical"
+  status: "draft" | "published" | "acknowledged" | "resolved" | "rejected"
+  scope: "session" | "persistent"  // Default: persistent
+  context_id?: string
+  references?: Reference[]
+}
+```
+
+### Task
+
+```typescript
+interface Task {
+  id: string
+  title: string
+  type: "analysis" | "fix" | "review" | "test" | "research" | "synthesis"
+  priority: 0 | 1 | 2 | 3 | 4  // 0=critical, 4=backlog
+  status: "pending" | "claimed" | "working" | "blocked" | "review" | "completed" | "failed"
+  created_by: string
+  assigned_to?: string
+  depends_on?: string[]
+  findings?: string[]
+}
+```
+
+See [DESIGN.md](./DESIGN.md) for complete schema documentation.
+
+## Lifecycle Hooks
+
+The plugin integrates with OpenCode's lifecycle:
+
+- **`session.created`**: Starts a YAMS session for the conversation
+- **`session.compacted`**: Injects blackboard summary into compaction context
+
+## Persistence
+
+By default, findings are **persistent** (survive across sessions). Use `scope: "session"` for temporary scratch work:
+
+```typescript
+bb_post_finding({
+  // ...
+  scope: "session",
+  ttl: 3600  // Optional: auto-delete after 1 hour
+})
+```
+
+## Architecture
+
+Based on research into multi-agent communication patterns:
+
+- **Blackboard Pattern**: Shared memory over direct messaging for loose coupling
+- **A2A Protocol Concepts**: Structured findings with lifecycle states
+- **Task Coordination**: Claim-based work distribution with dependencies
+
+## Development
+
+### Building
+
+Build with external dependencies (do not bundle zod or plugin SDK):
+
+```bash
+bun install
+bun run build
+```
+
+This compiles `index.ts` to `index.js` for distribution.
+
+### Type Checking
+
+```bash
+bun run typecheck
+```
+
+### Local Testing
+
+1. Build the plugin: `bun run build`
+2. Copy to your project: `cp index.js ~/.opencode/plugin/yams-blackboard.js`
+3. Restart OpenCode
+4. Test with: `bb_list_agents`
+
+## Troubleshooting
+
+### "YAMS daemon not running"
+
+Ensure the YAMS daemon is started:
+
+```bash
+yams daemon start
+yams status  # Should show "running"
+```
+
+### "Command 'yams' not found"
+
+YAMS must be installed and in your PATH. Check your installation.
+
+### Plugin not loading
+
+1. Verify `opencode.json` has `"plugins": ["yams-blackboard"]`
+2. Check OpenCode logs for plugin load errors
+3. Try clearing npm cache: `npm cache clean --force`
+
+### Tools not appearing
+
+The plugin registers tools on `session.created`. Start a new session if tools don't appear.
+
+## License
+
+MIT