hive-agent 0.1.0__tar.gz

hive_agent-0.1.0/.context/execution-plan.md

@@ -0,0 +1,210 @@
+# Hive Execution Plan
+
+## What's Done
+
+- [x] README.md (project pitch, quick start, features)
+- [x] CLAUDE.md (dev conventions, architecture)
+- [x] pyproject.toml (dependencies, scripts, packaging)
+- [x] CLI stub (all commands defined, imports stubbed)
+- [x] Agent profiles (5 presets with personalities)
+- [x] Core protocols (ModelProvider, ToolExecutor, AgentProfile, AgentState)
+- [x] Project structure (all modules created)
+- [x] LICENSE (MIT)
+- [x] Launcher scripts (start.sh, stop.sh)
+
+---
+
+## Phase 1: Single Agent Working (Priority: HIGH)
+
+Goal: `hive spawn coder --task "write hello world"` actually works end-to-end.
+
+### 1.1 Memory Store
+**File:** `src/hive/memory/store.py`
+- SQLite database initialization (create tables on first run)
+- Tables: agents, tasks, messages, tool_results
+- CRUD operations for each table
+- Async via aiosqlite
+
+### 1.2 Event Log
+**File:** `src/hive/memory/events.py`
+- JSONL append-only writer
+- Event types: agent_spawned, task_started, step_executed, task_completed, error
+- Stream reader (for `hive logs`)
+- Replay function (for `hive replay`)
+
+### 1.3 Claude Model Provider
+**File:** `src/hive/models/claude.py`
+- Implement ModelProvider protocol
+- `complete()`: call Anthropic API with messages + tools
+- `plan()`: given objective + tools, return list of PlanSteps
+- Handle streaming, token counting, error handling
+- Auto-detect API key from env
+
+### 1.4 Built-in Tools (core set)
+**Files:** `src/hive/execution/tools/filesystem.py`, `shell.py`, `git.py`, `memory_tools.py`
+- `file_read(path)` - read file contents
+- `file_write(path, content)` - write file
+- `file_list(directory)` - list directory
+- `shell_exec(command)` - run shell command (with allowlist)
+- `git_status()`, `git_commit(message)`, `git_branch(name)`
+- `memory_set(key, value)`, `memory_get(key)`
+
+### 1.5 Tool Registry
+**File:** `src/hive/execution/registry.py`
+- Auto-discover tools from `execution/tools/` package
+- Register by name, store ToolDefinition
+- `execute(tool_name, agent_id, **params) -> ToolResult`
+- `list_tools() -> list[ToolDefinition]`
+
+### 1.6 Agent Loop
+**File:** `src/hive/agents/loop.py`
+- Core function: `async run_task(profile, task, store, model, tools) -> TaskResult`
+- Steps:
+  1. Build system prompt from profile
+  2. Call model.plan(task, available_tools)
+  3. For each step: execute tool, collect result
+  4. Substitute {result} into next step params
+  5. On failure: replan from failed step (max 2 retries)
+  6. Validate output (did something actually get produced?)
+  7. Log everything to event store
+
+### 1.7 Daemon Setup
+**File:** `src/hive/daemon/setup.py`
+- `initialize_hive()`: create .hive/ directory, config.yaml, state.db
+- Detect available models (check API keys, binaries, endpoints)
+- Copy default profiles
+
+### 1.8 Daemon Lifecycle
+**File:** `src/hive/daemon/lifecycle.py`
+- `spawn_agent(name, task, model_override)` - load profile, create state, start loop
+- `kill_agent(name)` - mark dead, stop execution
+- `get_all_agents()` - list current states
+
+### 1.9 Wire CLI to Real Implementations
+- Connect CLI commands to lifecycle/store/events
+- `hive init` -> setup.initialize_hive()
+- `hive spawn` -> lifecycle.spawn_agent()
+- `hive status` -> lifecycle.get_all_agents()
+- `hive logs` -> events.stream_agent_events()
+
+---
+
+## Phase 2: Multi-Model + Detection
+
+### 2.1 LM Studio Provider
+**File:** `src/hive/models/local.py`
+- OpenAI-compatible API (localhost:1234)
+- Detect if LM Studio is running
+- List available models from endpoint
+
+### 2.2 Codex CLI Provider
+**File:** `src/hive/models/codex.py`
+- Wrap `codex` CLI via subprocess
+- Detect if codex binary exists
+- Parse output
+
+### 2.3 Model Router
+**File:** `src/hive/models/router.py`
+- `detect_models()` - scan for all available providers
+- `get_model(preference, task_complexity)` - return best available
+- Fallback logic: local -> sonnet -> opus
+- Cost estimation per provider
+
+### 2.4 Config System
+**File:** `src/hive/daemon/config.py`
+- Load `.hive/config.yaml`
+- Merge with defaults
+- Validate schema (pydantic)
+- Support env var substitution (${ANTHROPIC_API_KEY})
+
+---
+
+## Phase 3: Multi-Agent + Rooms
+
+### 3.1 Agent Messaging
+**File:** `src/hive/rooms/messaging.py`
+- `send_message(from_agent, to_agent, content)`
+- `get_inbox(agent_id) -> list[Message]`
+- Messages stored in SQLite
+
+### 3.2 Rooms
+**File:** `src/hive/rooms/room.py`
+- Create room with named agents
+- Post messages to room (visible to all members)
+- Agent picks up messages that match its role
+- Turn-based or event-driven collaboration
+
+### 3.3 Oracle Review
+**File:** `src/hive/agents/oracle.py`
+- `request_review(agent_id, proposal, context) -> Approval|Rejection`
+- Oracle uses Opus model
+- Injected into agent loop when autonomy=medium and action is high-risk
+
+### 3.4 Concurrent Agent Execution
+- Thread pool or asyncio tasks for parallel agents
+- Shared state via SQLite (serialized access)
+- Event bus for real-time notifications
+
+---
+
+## Phase 4: Skills + Tool Synthesis
+
+### 4.1 Skill Loader
+**File:** `src/hive/skills/loader.py`
+- Load SKILL.md files from `.hive/skills/` and `profiles/skills/`
+- Parse YAML frontmatter for triggers
+- Inject skill content into agent system prompt when relevant
+
+### 4.2 Tool Synthesis
+**File:** `src/hive/execution/synthesis.py`
+- Agent calls `create_tool(name, description, code)`
+- Write Python to `.hive/tools/{name}.py`
+- Validate (parse AST, basic test)
+- Hot-load into registry
+
+### 4.3 MCP Server
+**File:** `src/hive/mcp/server.py`
+- Expose Hive as MCP tools for Claude Code
+- Tools: spawn_agent, kill_agent, chat_agent, get_status, list_agents
+- Users can manage Hive agents from within Claude Code sessions
+
+---
+
+## Phase 5: Polish + Launch
+
+### 5.1 Demo GIF
+- Record terminal session showing agents collaborating
+- Keep under 15 seconds
+- Show: spawn, task assignment, agent working, result
+
+### 5.2 CONTRIBUTING.md
+- How to add tools, models, agent presets
+- Dev setup instructions
+
+### 5.3 GitHub Actions
+- CI: lint + type check + tests on push
+- Release: publish to PyPI on tag
+
+### 5.4 Launch
+- Hacker News / Reddit post
+- Tweet thread showing the demo
+- Cross-post to AI/agent communities
+
+---
+
+## Estimated LOC per Phase
+
+| Phase | Files | LOC | Time |
+|-------|-------|-----|------|
+| Phase 1 | 9 files | ~1500 | 2-3 days |
+| Phase 2 | 4 files | ~600 | 1-2 days |
+| Phase 3 | 4 files | ~800 | 2-3 days |
+| Phase 4 | 3 files | ~500 | 1-2 days |
+| Phase 5 | misc | ~200 | 1 day |
+| **Total** | **~20 files** | **~3600** | **~10 days** |
+
+---
+
+## Key Principle
+
+Every phase must leave the project in a working state. Phase 1 alone should be demoable. Don't build Phase 2 features into Phase 1 code "for later" - keep each phase minimal and functional.

hive_agent-0.1.0/.context/incomplete-areas-audit.md

@@ -0,0 +1,178 @@
+# Hive Repo — Incomplete Areas Audit
+
+## Repository Snapshot
+
+- **Branch**: `dev` (ahead of `origin/dev` by 1 commit)
+- **Untracked artifacts**: `logs/`, `scenarios/detective/results/run-*.json`
+- **Tests**: `uv run pytest` — 122 passed
+- **Lint**: `uv run ruff check src tests scenarios` — 7 errors (all in `scenarios/`)
+- **Types**: `uv run mypy src` — 82 errors in 24 files (65 checked)
+
+---
+
+## Findings
+
+### 1. Packaging: YAML data files excluded from wheel
+
+**Severity**: High
+**Files**: `pyproject.toml`, `profiles/*.yaml`, `models.yaml`, `dist/hive_agent-0.1.0-py3-none-any.whl`
+
+`pyproject.toml` has no `[tool.setuptools.package-data]` or equivalent config. The existing wheel at `dist/` contains zero `.yaml` files. This means `pip install hive-agent` from the wheel works only when run from the project root (where `profiles/` and `models.yaml` are in CWD).
+
+Code has fallback logic (`profile.py:10-19` checks CWD then `importlib.resources`, `registry.py:11-13` checks CWD then relative path), but neither fallback works from an arbitrary install location.
+
+**Affected files**:
+- `profiles/coder.yaml`, `oracle.yaml`, `researcher.yaml`, `reviewer.yaml`, `tester.yaml`
+- `models.yaml` (model registry with pricing/routing)
+
+**Fix**: Add package-data config to `pyproject.toml` to bundle YAML files, or copy them into `src/hive/` and adjust paths.
+
+**Verify**: `uv build && unzip -l dist/*.whl | grep yaml`
+
+---
+
+### 2. README architecture section references deleted module
+
+**Severity**: Low
+**File**: `README.md:57`
+
+Line 57 shows `├── execution/        # Tool system` in the architecture diagram, but `src/hive/execution/` was deleted in this branch. The `runtime/` module that replaced it is not shown. Line 47 says `├── agents/  # Agent runtime` which is vague.
+
+**Fix**: Update the architecture tree to replace `execution/` with `runtime/` and add a line for `context.py`.
+
+**Verify**: `ls src/hive/ | sort` and compare with README.
+
+---
+
+### 3. Launcher scripts
+
+**Severity**: None (not a real issue)
+
+`scripts/start.sh` and `scripts/stop.sh` exist and reference `hive.daemon.server`, which still exists. No broken imports or deleted module references. This was a false positive from the other agent's checklist.
+
+---
+
+### 4. Mypy strict typing failures — 82 errors
+
+**Severity**: Medium
+**File**: `pyproject.toml` (mypy config at `[tool.mypy]` with `strict = true`)
+
+Breakdown by error code:
+| Code | Count | Description |
+|------|-------|-------------|
+| `type-arg` | 35 | Missing generic type args (`dict` → `dict[str, Any]`) |
+| `no-untyped-call` | 17 | Calling untyped functions in typed context |
+| `no-any-return` | 7 | Returning `Any` from typed function |
+| `arg-type` | 6 | Wrong argument type (includes `WorldState \| None` issues) |
+| `import-untyped` | 4 | Missing stubs (yaml) |
+| `attr-defined` | 4 | Attribute not found on type |
+| `union-attr` | 3 | Accessing attr on union without narrowing |
+| `abstract` | 2 | Instantiating abstract class |
+| `no-untyped-def` | 2 | Missing function annotation |
+| `return-value` | 1 | Wrong return type |
+| `assignment` | 1 | Incompatible assignment |
+
+Most impactful clusters:
+- **`daemon/loop.py`** (6 errors): `WorldState | None` passed where non-optional `WorldState` expected — real type-safety gap from the economy-toggle refactor
+- **`interactions/runner.py`** (7 errors): Type mismatches with `GenerateResult` vs old `ScenarioResult`
+- **`mcp/server.py`** (4 errors): Bare `dict` without type params
+
+**Fix**: Address in priority order — `arg-type` and `union-attr` errors are real safety gaps; `type-arg` errors are annotation noise.
+
+**Verify**: `uv run mypy src`
+
+---
+
+### 5. Persistent memory wrapper — SemanticMemory integration
+
+**Severity**: Was Critical — now fixed
+**Files**: `src/hive/runtime/memory.py`, `src/hive/memory/semantic.py`
+
+Three bugs were fixed earlier in this session:
+- Constructor arg order was reversed (`agent_name, hive_dir` → `hive_dir, agent_name`)
+- Called non-existent `add_observation()` instead of `store()`
+- Called non-existent `query()` instead of `search()`
+- `clear()` didn't delete persisted data
+- `store()` returned meaningless ID in semantic path
+
+All fixed. No remaining issues.
+
+**Verify**: `uv run pytest tests/runtime/test_agent.py -x`
+
+---
+
+### 6. Model availability detection — key-only check
+
+**Severity**: Low
+**Files**: `src/hive/runtime/providers.py:52-54`, `src/hive/runtime/providers.py:210-212`
+
+Both `AnthropicRuntimeProvider.available` and `OpenAIRuntimeProvider.available` return `bool(api_key)` — they don't test connectivity. Invalid/revoked keys or network issues aren't detected until generation time.
+
+This is standard practice for SDK wrappers (the old deleted providers did the same thing). Not a regression, and adding connectivity checks would introduce latency on startup. Acceptable as-is.
+
+**Fix**: None needed. Could optionally add a `ping()`/`verify()` method for explicit health checks.
+
+---
+
+### 7. Runtime Agent doesn't use structured LogWriter
+
+**Severity**: Medium
+**Files**: `src/hive/runtime/agent.py`, `src/hive/logging/writer.py`, `src/hive/logging/models.py`
+
+`Agent.run()` uses only Python `logging` (debug/error/warning). The structured logging infrastructure (`LogWriter` with `DecisionLog`, `ToolLog`, `CycleLog`, `GoalLog`) exists and is used by `ExistenceLoop` and the daemon, but the runtime `Agent` doesn't emit any structured logs.
+
+This means tool calls, model generation metadata (tokens, cost, duration), and step-by-step traces from `Agent.run()` are invisible to the log analysis pipeline.
+
+**Fix**: Accept an optional `LogWriter` in Agent constructor. Log `DecisionLog` after each `generate()` call and `ToolLog` after each tool execution.
+
+**Verify**: Run a scenario and check `logs/` for agent-level structured entries.
+
+---
+
+### 8. Two parallel interaction APIs coexist
+
+**Severity**: Low
+**Files**: `src/hive/interactions/base.py`, `src/hive/interactions/runner.py`, `src/hive/interactions/exchange.py`
+
+Two systems live in `interactions/`:
+- **Old**: `Scenario`, `ScenarioRunner`, `InteractionPattern`, `MemoryStrategy`, `AgentSlot` — used by `scenarios/detective/run.py`
+- **New**: `Participant`, `ExchangeRunner`, `ExchangeConfig`, `InteractionMessage` — used by tests and presets
+
+Both are exported from `interactions/__init__.py`. The old system still works (provider calls were updated to `create_runtime_provider`). Neither is dead code — `ScenarioRunner` powers the detective scenario, `ExchangeRunner` is the new primary API.
+
+**Fix**: Not urgent. When the old scenario system is no longer needed, remove it. Until then, coexistence is fine — they don't conflict.
+
+---
+
+### 9. Scenario lint issues — 7 ruff errors
+
+**Severity**: Low
+**File**: `scenarios/detective/run.py`, `scenarios/runtime_test.py`
+
+All 7 errors are in `scenarios/` (zero in `src/`):
+- 4x `E402` in `detective/run.py`: imports after `sys.path.insert` — necessary for standalone scripts
+- 1x `F841` in `detective/run.py:288`: unused `correct_answer` variable
+- 1x `F541` in `runtime_test.py:78`: f-string with no placeholders
+- 1x `F841` in `runtime_test.py:88`: unused `expected` variable
+
+The `E402` errors are inherent to the `sys.path` pattern and can be suppressed with `# noqa: E402`. The `F841` and `F541` are trivial cleanups.
+
+**Fix**: Add `# noqa: E402` to the post-sys.path imports, remove unused variables, drop the stray `f` prefix.
+
+**Verify**: `uv run ruff check scenarios/`
+
+---
+
+## Priority Summary
+
+| # | Finding | Severity | Action |
+|---|---------|----------|--------|
+| 1 | YAML files excluded from wheel | High | Fix pyproject.toml packaging |
+| 4 | 82 mypy errors (6 real type-safety gaps) | Medium | Fix arg-type/union-attr errors in daemon/loop.py and interactions/runner.py |
+| 7 | Runtime Agent missing structured logging | Medium | Wire LogWriter into Agent |
+| 2 | README stale architecture diagram | Low | Update tree |
+| 8 | Dual interaction APIs | Low | Document; deprecate old when ready |
+| 9 | 7 ruff errors in scenarios/ | Low | Quick cleanup |
+| 3 | Launcher scripts | None | No issue found |
+| 5 | PersistentMemory semantic bugs | None | Already fixed |
+| 6 | Model availability key-only check | None | By design |

hive_agent-0.1.0/.context/plans/phase1-remaining.md

@@ -0,0 +1,90 @@
+# Phase 1 — Remaining Work
+
+## Status Audit (2026-05-11)
+
+Most of Phase 1 is done. Tests pass (122/122), lint is clean, YAML packaging is fixed,
+`replay`, `inspect`, `nudge`, `runs`, `status` all work. Runtime Agent has structured
+logging wired in.
+
+### What's left
+
+| # | Task | Severity | Est. |
+|---|------|----------|------|
+| 1 | Fix `hive watch` async bugs | Critical | 30 min |
+| 2 | Fix mypy type errors | Medium | 45 min |
+| 3 | Update README architecture diagram | Low | 5 min |
+| 4 | Integration test for daemon loop | Medium | 30 min |
+
+---
+
+## Task 1: Fix `hive watch` — Async Bugs
+
+**File:** `src/hive/cli/main.py` lines 241-374
+
+**Problem:** `_build_dashboard()` (sync) calls `asyncio.run()` for store queries (lines 261,
+276), but it's called from inside `_run()` (async, line 367), which runs inside another
+`asyncio.run()` (line 372). Nested `asyncio.run()` crashes with
+`RuntimeError: asyncio.run() cannot be called from a running event loop`.
+
+Same issue in `_poll_events()` (line 328) — it's async but calls `asyncio.run()`.
+
+**Fix approach:**
+- Make `_build_dashboard()` async — use `await store.list_agents()` and
+  `await store.get_active_goal()` directly
+- In `_poll_events()`, replace `asyncio.run(store.list_agents())` with
+  `await store.list_agents()`
+- The outer `_run()` orchestrates both `_poll_events()` and dashboard refresh as
+  concurrent async tasks
+- Keep the `Live` context manager — it works fine with periodic `live.update()` calls
+  from an async loop
+
+**Verify:** `hive init && hive start -b 5 -p coder` in one terminal, `hive watch` in
+another. Dashboard should update without crashing.
+
+---
+
+## Task 2: Fix Mypy Errors
+
+**Current:** 79 errors across 24 files. Most are annotation noise, but some are real.
+
+**Priority fixes (real type-safety gaps):**
+- `daemon/loop.py`: `WorldState | None` passed where non-optional `WorldState` expected
+- `interactions/runner.py`: type mismatches with `GenerateResult` vs old return types
+- Missing `types-PyYAML` stub — add to dev dependencies
+
+**Lower priority (annotation noise):**
+- Bare `dict` / `list` without type params throughout
+- `Any` return types in world/stats.py, runtime/workflow.py, etc.
+
+**Verify:** `uv run mypy src` — target zero `arg-type` and `union-attr` errors. The
+`type-arg` noise can stay for now.
+
+---
+
+## Task 3: Update README Architecture Diagram
+
+**File:** `README.md` line ~57
+
+**Problem:** Shows `execution/` which was deleted. Should show `runtime/` instead.
+Also missing entries for `context.py`, `checkpoint.py`, `world/`.
+
+**Verify:** `ls src/hive/ | sort` matches the diagram.
+
+---
+
+## Task 4: Integration Test — End-to-End Daemon Loop
+
+**Goal:** Prove the daemon loop actually works: spawn agent → existence loop generates
+goal → suffering updates → events logged → state persisted.
+
+**Approach:**
+- Use `researcher` profile with a mocked model provider (don't call real LLMs)
+- Short heartbeat (0.5s), run 3 cycles, then stop
+- Assert: goal was generated, suffering state updated, events written to JSONL,
+  agent state in SQLite
+- Use temp directories for `.hive/` and `logs/`
+- Existing test patterns in `tests/` — match the style
+
+**File:** `tests/test_daemon_integration.py`
+
+**Verify:** `uv run pytest tests/test_daemon_integration.py -v`