Completed¶

Phase 8.5 delivered: Collapsed SOUL.md/USER.md/IDENTITY.md/TOOLS.md into single AGENTS.md (SOUL+USER as sections, TOOLS replaced by dynamic builtin listing, IDENTITY always from inline fallback). Deleted dead workspace/memory/MEMORY.md artifact. Added workspace tree to system prompt (depth-2, cached per session, invalidated on file write). Added tool output offloading — exec/web_fetch results > 4k chars saved to tmp/ with read_file reference. Write policy simplified: only AGENTS.md protected. Project-local TODO.md guidance added. L1-L5+ER evals all 100%; L6-pipeline flaky (pre-existing: sub-agent PathGuard blocks absolute eval tmp paths).

Phase 8 delivered: MCP client with FastMCP (stdio + streamable HTTP, Claude Desktop-compatible config, tool allowlisting, description hashing), entry-point plugin discovery (picobot.tools), tool group registry with dynamic tool search, eval framework (26 tasks across 6 levels, 7 grader types, 100% pass rate), AgentResult with full token/cost metrics, sub-agent token tracking, sub-agent supervision model (stop hook, message queue, overdue nudges, enriched status checks, cancel, restrict tools, efficiency preamble), expected_duration/timeout on spawn. OTel and ToolRegistry composition deferred to Phase 9.

Upcoming¶

Phase 9: Capabilities¶

Features that build on Phase 8 infrastructure. Each is independent and can be done in any order.

• Personal RPA skill — Thin orchestration layer on existing Playwright + cron + agent loop. "Explore-replay-heal" pattern: AI discovers workflow once, compiles to deterministic Playwright steps, re-invokes AI only when selectors break. Hybrid YAML workflow format with both selectors and natural language descriptions. Credentials via Python keyring (OS-native). Position as "last resort when no API exists" — not a general automation platform. ~500-800 LOC. See research/personal-rpa.

• Channel integrations — BaseChannel ABC with Telegram and Slack implementations. In-process via process_direct() (not NDJSON subprocess). Telegram: python-telegram-bot with long polling, streaming via sendMessageDraft (API 9.3). Slack: slack-bolt Socket Mode, streaming via chat.startStream/appendStream/stopStream. Session keys: channel:chat_id. ~1,100-1,500 LOC total (350-450 per adapter + gateway + markdown conversion). See research/channel-integrations.

• MCP server mode (~300-500 LOC) — Expose picobot's unique tools (KB, sub-agents, cron) as MCP server via FastMCP. Stdio transport for Claude Desktop/VS Code integration, Streamable HTTP for remote access. picobot serve-mcp CLI command. Fills a gap in the MCP ecosystem — no existing server offers progressive KB or sub-agent orchestration. See research/mcp-support.

Phase 10: Scale¶

Features with higher complexity or dependency cost. Build only when there's demonstrated need.

• Semantic search — Three-retriever hybrid search: frontmatter tags (existing) + SQLite FTS5 BM25 in-memory + numpy vector search, fused via Reciprocal Rank Fusion. Nomic embeddings (nomic-embed-text-v1.5, 768d, local+remote unified). HyPE (Hypothetical Question Embedding) at index time for intent-based agent queries (+42pp context precision). Embeddings cached in gitignored .npz sidecar. nomic[local] is a required dependency. Graduate to faiss-cpu at 5K docs, ChromaDB at 10K+. See research/kb-retrieval.

• Federated KB — Separate repos with virtual overlay (not git submodules). Priority resolution at application layer: local > project > org > community. Each remote is independent git repo cloned to cache dir with per-remote sync policy. Encryption: age with topic-level recipient lists, agebox-style explicit encrypt/decrypt on sync. Unified search spanning all remotes. See research/federated-kb.

• SwiftUI menubar app (optional, macOS) — MenuBarExtra (.window style) with status popover. Thin client (~500-1000 lines Swift) consuming existing FastAPI server via SSE (real-time events) + REST (queries/commands). Native notifications via UNUserNotificationCenter with actionable buttons for sub-agent completion. Distribution: DMG + Sparkle auto-update + Homebrew cask. Skip App Sandbox (not needed outside App Store). See research/swiftui-menubar.

Decisions¶

Research conducted 2026-02-22. Full reports in docs/research/.

Framework adoption: Don't adopt, cherry-pick¶

Evaluated PydanticAI (v1.62.0), LangGraph, smolagents, OpenAI Agents SDK, CrewAI, Agno, Google ADK. No framework offers both PydanticAI-quality features AND the loop-level control picobot needs. PydanticAI's toolset composition (FilteredToolset, PreparedToolset, ApprovalRequired) is tightly coupled to RunContext — can't use without adopting the full agent loop. Picobot exists to study agent loop reliability; adopting a framework defeats the purpose.

Approach: Use FastMCP directly (independent package). Implement OTel natively (same GenAI Semantic Conventions). Port toolset design patterns onto ToolRegistry. Optionally evaluate PydanticAI Agent for sub-agents only later. Total custom code: ~750-1,150 LOC vs ~600-900 LOC savings from framework adoption — not worth the coupling. See research/framework-adoption.

Plugin system: Entry points + MCP, not a framework¶

MCP for external/third-party tools. Python entry points for picobot-native tool packages. No custom manifest (pyproject.toml is the manifest), no marketplace (PyPI is the registry), no plugin CLI (uv pip install suffices), no hook system (until demonstrated need). Phase B: local directory plugins + Tool Search for context management when > 20 tools. Phase C: hooks + settings overlay if community materializes. See research/plugin-system.

Semantic search: numpy brute-force, not ChromaDB¶

numpy brute-force + SQLite FTS5 in-memory is simpler and adequate at picobot's 100-1000 doc scale: <0.1ms vector query, ~26 MB memory, ~15 LOC for RRF fusion. Nomic at 768d (MTEB 62.28) as required dependency — the only viable model with unified local+remote API. ChromaDB is lighter than initially researched (~150 MB with ONNX, not 2.2 GB with PyTorch) but still unnecessary at this scale. Always-on embeddings — no optional/fallback pattern. Graduate to faiss-cpu at 5K docs, ChromaDB at 10K+. See research/kb-retrieval.

RPA: Build on existing stack, not external libraries¶

Skyvern (AGPL-3.0), Browser-Use, and similar tools add licensing constraints and dependency churn. Picobot already has Playwright + cron + agent loop — the RPA skill formalizes their combination. "Explore-replay-heal" pattern amortizes AI cost. Position as last-resort for sites without APIs (traditional RPA has 30-50% failure rate). See research/personal-rpa.