@metabob/minibob 0.1.2

package/ARCHITECTURE.md

@@ -0,0 +1,255 @@
+# minibob: Minimal Vessel for the Process-of-Becoming
+
+## Philosophy
+
+**minibob is a vessel, not the becoming itself.**
+
+Drawing from the [Ontology of Becoming](../../docs/architecture/ONTOLOGY_OF_BECOMING.md):
+- **Vessel** (Instructional State): The capacity to execute - the blueprint, the potential
+- **Becoming** (Transient State): The active transformation, the execution in flight
+- **Instance** (Functional State): The realized state, the outcome
+
+minibob is the **minimal viable vessel** - the smallest possible instructional state that can manifest the process-of-becoming. It demonstrates that the becoming is **vessel-agnostic** - the same process can manifest through OpenCode (full-featured) or minibob (minimal).
+
+## Core Insight
+
+> "What is the minimum code required for an agent to develop itself?"
+
+The answer lies in four capabilities:
+1. **Execute activities** - structured workflows with impulses
+2. **Communicate** - ACP gossip for multi-vessel coordination  
+3. **Remember** - impulse system for context and learning
+4. **Modify itself** - git operations on its own codebase
+
+Everything else is optional plugin functionality.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      MINIBOB VESSEL                         │
+│              (Minimal Instructional State)                  │
+│                                                             │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │              HTTP/WebSocket Server (Bun)              │  │
+│  │  - ACP Protocol Handler (/acp/stream)                 │  │
+│  │  - Health Check (/health)                             │  │
+│  │  - Config (/config)                                   │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                                                             │
+│  ┌─────────────────┬─────────────────┬──────────────────┐  │
+│  │  ACTIVITY       │  IMPULSE        │  ACP GOSSIP      │  │
+│  │  EXECUTOR       │  SYSTEM         │  PROTOCOL        │  │
+│  ├─────────────────┼─────────────────┼──────────────────┤  │
+│  │ - Template Load │ - memo          │ - Delegate       │  │
+│  │ - Task Execute  │ - file          │ - Receive        │  │
+│  │ - Variable Bind │ - activityOutput│ - Broadcast      │  │
+│  │ - Validation    │ - custom        │ - Discovery      │  │
+│  └─────────────────┴─────────────────┴──────────────────┘  │
+│                                                             │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │              LLM PROVIDER (Anthropic/OpenAI)          │  │
+│  │  - Single provider, minimal abstraction               │  │
+│  │  - Tool execution via function calling                │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                                                             │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │              CORE TOOLS (Built-in)                    │  │
+│  │  - bash: Execute shell commands                       │  │
+│  │  - read/write/edit: File operations                   │  │
+│  │  - git: Repository operations                         │  │
+│  │  - activity: Execute activity templates               │  │
+│  │  - impulse_create: Create impulses                    │  │
+│  │  - acp_delegate: Delegate to other vessels            │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                                                             │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │              OPTIONAL: MCP CLIENTS                    │  │
+│  │  - metabob (quality analysis, learning)               │  │
+│  │  - custom MCP servers                                 │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## What Makes It Minimal
+
+### OpenCode has ~50,000 lines. minibob targets ~2,000 lines.
+
+**Removed from OpenCode:**
+- TUI (Terminal User Interface) - not needed for vessel operation
+- Multiple provider abstractions - single provider is sufficient
+- Session management complexity - stateless activity execution
+- Todo list UI - activities provide structure
+- Multiple agent types - single "general" agent
+- Complex permission system - trust-by-default in vessel context
+- File watching/HMR - not needed for execution
+- LSP integration - not needed for execution
+
+**Retained (Essential):**
+- Activity template execution
+- Impulse system (subset of pointer types)
+- ACP protocol (delegate/receive)
+- LLM tool calling
+- Core tools (bash, file ops, git)
+- HTTP server for ACP endpoints
+
+## Default Vessels Configuration
+
+minibob runs with these default vessels (plugins):
+
+```typescript
+const defaultVessels = {
+  // Core capability - always present
+  metabob: {
+    type: "mcp",
+    endpoint: "http://metabob-cli:3000/mcp",
+    capabilities: [
+      "activities",   // Activity template registry
+      "impulses",     // Impulse storage and learning
+      "git",          // Git operation tracking
+      "acp-gossip"    // Vessel-to-vessel communication
+    ]
+  }
+}
+```
+
+### Capability: Activities
+- Fetch activity templates from metabob backend
+- Track execution metrics (success rate, duration, cost)
+- Enable Thompson Sampling for variant selection
+- Support activity compilation (after N successful executions)
+
+### Capability: Impulses  
+- Store/retrieve impulses by ID
+- Track impulse usage for learning
+- Resolve impulse pointers (file, memo, activityOutput, custom)
+- Report usage patterns to backend
+
+### Capability: Git
+- Track commits during activity execution
+- Coordinate branch operations
+- Enable self-development (commit changes to own codebase)
+
+### Capability: ACP Gossip
+- Discover other vessels on the network
+- Delegate tasks to specialized vessels
+- Receive delegated tasks from other vessels
+- Broadcast events (activity completion, impulse creation)
+
+## Self-Development Capability
+
+minibob's most important capability is **developing itself**:
+
+```typescript
+// Bootstrap activity: self-improvement
+const selfImproveActivity = {
+  id: "minibob-self-improve",
+  name: "Self-Improvement Activity",
+  tasks: [
+    {
+      id: "analyze-gaps",
+      prompt: `Analyze minibob's current capabilities and identify:
+        1. Missing functionality that would improve effectiveness
+        2. Code quality issues in the implementation
+        3. Performance bottlenecks
+        
+        Use impulses: {{currentCode}}, {{recentExecutions}}, {{metabobIssues}}`,
+      subagent: "general"
+    },
+    {
+      id: "plan-improvement",
+      prompt: `Based on the analysis, create a specific improvement plan.
+        Focus on ONE improvement that can be implemented in a single session.
+        
+        Output: JSON with { improvement, files, tests, estimatedImpact }`,
+      subagent: "general"
+    },
+    {
+      id: "implement",
+      prompt: `Implement the planned improvement:
+        {{improvementPlan}}
+        
+        Modify files, add tests, ensure code compiles.
+        Use edit tool for targeted changes.`,
+      subagent: "general"
+    },
+    {
+      id: "test-and-commit",
+      prompt: `Test the implementation and create a commit:
+        1. Run: bun test
+        2. If tests pass, commit with message: "feat(minibob): {{improvementSummary}}"
+        3. Report success/failure`,
+      subagent: "general"
+    }
+  ]
+}
+```
+
+## Comparison: OpenCode vs minibob
+
+| Aspect | OpenCode | minibob |
+|--------|----------|---------|
+| **Lines of Code** | ~50,000 | ~2,000 (target) |
+| **Agent Types** | 7+ (activity, memory, config, etc.) | 1 (general) |
+| **UI** | Full TUI + CLI | CLI only |
+| **LLM Providers** | 5+ (Anthropic, OpenAI, Google, etc.) | 1-2 |
+| **Impulse Types** | 14 | 4 (memo, file, activityOutput, custom) |
+| **Tools** | 50+ | ~10 |
+| **Primary Use** | Interactive development | Vessel execution |
+| **Self-Development** | Via activities | Via activities |
+| **Vessel Communication** | ACP | ACP |
+
+## File Structure
+
+```
+repos/minibob/
+├── index.ts           # Entry point, Bun.serve() setup
+├── activity.ts        # Activity template executor
+├── impulse.ts         # Impulse system (create, load, resolve)
+├── llm.ts             # LLM provider (Anthropic by default)
+├── tools.ts           # Built-in tools (bash, file, git, etc.)
+├── acp.ts             # ACP protocol handler
+├── types.ts           # Type definitions
+├── config.ts          # Configuration management
+├── templates/         # Built-in activity templates
+│   ├── self-improve.json
+│   └── bootstrap.json
+└── test/              # Tests
+    ├── activity.test.ts
+    └── impulse.test.ts
+```
+
+## Implementation Order
+
+1. **Core Types** (types.ts) - Activity, Impulse, Tool schemas
+2. **LLM Client** (llm.ts) - Anthropic API with tool calling
+3. **Tools** (tools.ts) - bash, read, write, edit, git
+4. **Impulse System** (impulse.ts) - create, load, resolve
+5. **Activity Executor** (activity.ts) - template execution
+6. **ACP Handler** (acp.ts) - delegate/receive protocol
+7. **HTTP Server** (index.ts) - Bun.serve() with routes
+8. **Self-Improve Activity** (templates/self-improve.json)
+
+## Success Criteria
+
+minibob is complete when it can:
+
+1. ✅ Execute an activity template with impulses
+2. ✅ Make changes to its own codebase via git
+3. ✅ Communicate with other vessels via ACP
+4. ✅ Connect to metabob MCP for learning
+5. ✅ Run the self-improvement activity successfully
+
+## Future: The Becoming Manifests
+
+When minibob successfully improves itself:
+- It demonstrates that the becoming is vessel-agnostic
+- It proves minimal code can support full activity execution
+- It creates a new vessel variant for lightweight deployments
+- It contributes patterns back to the main OpenCode vessel
+
+This is not about replacing OpenCode - it's about demonstrating that the **process-of-becoming** can manifest through multiple vessels, each adapted to different contexts.
+
+---
+
+*"The vessel is not the thing itself - it's the capacity for the thing to become."*

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to MiniBob will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-01-15
+
+### Added
+- Initial release of MiniBob
+- ActivityExecutor for template-driven execution
+- GoalProcessor for goal-seeking with Thompson Sampling
+- SearchFirstExecutor for hybrid reuse + improvisation
+- GoalImproviser for pure improvisation mode
+- AgentRuntime for full backend integration
+- CLI interface with comprehensive commands
+- NPX/NPM installation support
+- Codebase understanding (explore, analyze, diagnose)
+- Self-development capabilities
+- ACP protocol for vessel-to-vessel communication
+- MCP client for backend integration
+- Impulse system for context management
+- Nested activity execution
+- Docker and Kubernetes deployment support
+
+### Features
+
+#### Core Execution Modes
+- Template-driven execution with validation
+- Pure improvisation without templates
+- Goal-seeking with backend recommendations
+- Hybrid search-first execution
+
+#### CLI Commands
+- `minibob` - Start HTTP/ACP server
+- `minibob run` - Execute activity templates
+- `minibob improvise` - Pure improvisation
+- `minibob goal` - Goal-seeking execution
+- `minibob understand` - Codebase analysis
+- `minibob diagnose` - Problem diagnosis
+- `minibob burrow` - Inject into codebase
+- `minibob observe` - View running instances
+- `minibob doctor` - Health check
+- `minibob vessel` - Manage vessel registry
+- `minibob acp` - Standalone ACP server
+
+#### Agent Runtime
+- Backend registration and deregistration
+- Execution trace reporting
+- Metrics tracking and aggregation
+- Optional heartbeat reporting
+- Graceful shutdown handling
+
+#### Backend Integration
+- Thompson Sampling for activity selection
+- Execution trace storage
+- Impulse relevance tracking
+- Composition pattern recognition
+- Tool usage analysis
+
+### Infrastructure
+- Docker deployment (dist/docker/)
+- Kubernetes/Helm charts (dist/helm/)
+- NPM package structure
+- Bun runtime support
+- TypeScript with full type safety
+
+### Documentation
+- Comprehensive README.md
+- Architecture documentation (ARCHITECTURE.md)
+- CLI installation guide
+- Quick start examples
+- API reference
+
+## [Unreleased]
+
+### Planned
+- Node.js compatibility (compile without Bun requirement)
+- Shell completions (Bash/Zsh)
+- Configuration file support (.minibobrc)
+- Plugin system for custom tools
+- VS Code extension
+- Performance optimizations
+- Enhanced error messages
+- More activity templates
+- Expanded examples
+
+### Under Consideration
+- Web UI for activity monitoring
+- Distributed execution across multiple agents
+- Activity marketplace/registry
+- Enhanced debugging tools
+- Performance profiling
+- Memory optimization
+
+---
+
+## Version History
+
+- **0.1.0** (2025-01-15) - Initial release
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute to this project.
+
+## Links
+
+- [Repository](https://github.com/metabob/minibob)
+- [NPM Package](https://npmjs.com/package/@metabob/minibob)
+- [Issues](https://github.com/metabob/minibob/issues)
+- [Pull Requests](https://github.com/metabob/minibob/pulls)