macro-agent 0.0.10 → 0.0.12

package/openspec/changes/archive/2025-12-21-add-mvp-foundation/specs/agent-manager/spec.md

@@ -1,150 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Agent Spawning
-
-The system SHALL spawn new agents with unique IDs, session management, and event emission.
-
-#### Scenario: Spawn a child agent
-- **GIVEN** an initialized AgentManager and a running parent agent 'parent_1'
-- **WHEN** spawn({ task: 'implement auth', parent: 'parent_1' }) is called
-- **THEN** a unique agent_id is generated
-- **AND** a task is created for the agent (if task_id not provided)
-- **AND** an ACP session is started for the agent
-- **AND** a spawn event is emitted to the event store
-- **AND** default subscriptions are set up (agent, task, lineage)
-- **AND** the parent is subscribed to the child's subtree (unless subscribe_parent: false)
-- **AND** the function returns the new agent record
-
-#### Scenario: Spawn with custom configuration
-- **GIVEN** an initialized AgentManager
-- **WHEN** spawn({ task: 'review code', parent: 'parent_1', config: { model: 'claude-opus-4-20250514', timeout: 3600000 } }) is called
-- **THEN** the agent is created with the specified model and timeout
-- **AND** these config values are included in the spawn event payload
-
-#### Scenario: Spawn with explicit task_id
-- **GIVEN** an existing task 'task_123'
-- **WHEN** spawn({ task: 'implement feature', parent: 'parent_1', task_id: 'task_123' }) is called
-- **THEN** the agent is assigned to task 'task_123'
-- **AND** no new task is created
-
----
-
-### Requirement: Agent Termination
-
-The system SHALL terminate agents and update their state appropriately.
-
-#### Scenario: Terminate a running agent
-- **GIVEN** a running agent 'agent_1' with session 'sess_123'
-- **WHEN** terminate('agent_1', 'completed') is called
-- **THEN** the ACP session is terminated
-- **AND** a terminate event is emitted with reason 'completed'
-- **AND** the agent's state in the view changes to 'stopped'
-- **AND** the agent's associated task status is updated to 'completed'
-
-#### Scenario: Terminate with failure
-- **GIVEN** a running agent 'agent_1'
-- **WHEN** terminate('agent_1', 'failed') is called
-- **THEN** a terminate event is emitted with reason 'failed'
-- **AND** the agent's associated task status is updated to 'failed'
-
-#### Scenario: Terminate non-existent agent
-- **GIVEN** no agent with id 'nonexistent'
-- **WHEN** terminate('nonexistent', 'stopped') is called
-- **THEN** an error is returned indicating agent not found
-
----
-
-### Requirement: Agent Queries
-
-The system SHALL support querying agents by various criteria.
-
-#### Scenario: Get agent by ID
-- **GIVEN** an agent 'agent_1' exists
-- **WHEN** get('agent_1') is called
-- **THEN** the full agent record is returned including id, session_id, parent, state, task, config, timestamps
-
-#### Scenario: Get non-existent agent
-- **GIVEN** no agent with id 'nonexistent'
-- **WHEN** get('nonexistent') is called
-- **THEN** null is returned
-
-#### Scenario: List agents with filter
-- **GIVEN** agents in various states (running, stopped)
-- **WHEN** list({ state: 'running' }) is called
-- **THEN** only agents in 'running' state are returned
-
-#### Scenario: List agents by parent
-- **GIVEN** parent agent 'parent_1' with children 'child_1' and 'child_2'
-- **WHEN** list({ parent: 'parent_1' }) is called
-- **THEN** both 'child_1' and 'child_2' are returned
-
----
-
-### Requirement: Agent Hierarchy
-
-The system SHALL track and query the agent hierarchy.
-
-#### Scenario: Get children of an agent
-- **GIVEN** agent 'manager_1' has spawned 'worker_1' and 'worker_2'
-- **WHEN** getChildren('manager_1') is called
-- **THEN** both 'worker_1' and 'worker_2' are returned
-
-#### Scenario: Get hierarchy tree
-- **GIVEN** a hierarchy: head_manager → manager_1 → [worker_1, worker_2]
-- **WHEN** getHierarchy('head_manager') is called
-- **THEN** a tree structure is returned with head_manager at root
-- **AND** manager_1 as a child with worker_1 and worker_2 as its children
-- **AND** each node includes agent_id, task, and state
-
-#### Scenario: Get hierarchy with depth limit
-- **GIVEN** a deep hierarchy (4+ levels)
-- **WHEN** getHierarchy('root', { depth: 2 }) is called
-- **THEN** only 2 levels of the hierarchy are returned
-
----
-
-### Requirement: Head Manager Bootstrap
-
-The system SHALL create or retrieve the head manager agent on demand.
-
-#### Scenario: Create head manager on first interaction
-- **GIVEN** no agents exist in the system
-- **WHEN** getOrCreateHeadManager() is called
-- **THEN** a new head manager agent is spawned with parent: null
-- **AND** the agent's task is set to the system head_manager_task from config
-- **AND** the agent is returned
-
-#### Scenario: Return existing head manager
-- **GIVEN** a running head manager agent exists
-- **WHEN** getOrCreateHeadManager() is called
-- **THEN** the existing head manager is returned
-- **AND** no new agent is spawned
-
-#### Scenario: Create new head manager after previous stopped
-- **GIVEN** a stopped head manager agent exists (no running head manager)
-- **WHEN** getOrCreateHeadManager() is called
-- **THEN** a new head manager agent is spawned
-- **AND** the new agent is returned
-
----
-
-### Requirement: System Prompt Generation
-
-The system SHALL generate appropriate system prompts for spawned agents.
-
-#### Scenario: Generate prompt for child agent
-- **GIVEN** spawning a child agent with parent 'manager_1' and task 'implement auth'
-- **WHEN** the system prompt is generated
-- **THEN** the prompt includes the agent_id and session_id
-- **AND** the prompt includes the task description
-- **AND** the prompt includes the parent agent_id
-- **AND** the prompt includes the lineage chain
-- **AND** the prompt includes available MCP tools
-- **AND** the prompt includes guidance for status reporting and messaging
-
-#### Scenario: Generate prompt for head manager
-- **GIVEN** spawning the head manager (parent: null)
-- **WHEN** the system prompt is generated
-- **THEN** the prompt includes head manager specific responsibilities
-- **AND** the prompt indicates this agent interacts directly with users
-- **AND** the prompt includes guidance for task decomposition and child spawning

package/openspec/changes/archive/2025-12-21-add-mvp-foundation/specs/cli-api/spec.md

@@ -1,258 +0,0 @@
-## ADDED Requirements
-
-### Requirement: API Server Initialization
-
-The system SHALL provide an HTTP/WebSocket server for CLI and client communication.
-
-#### Scenario: Start API server
-- **GIVEN** the multi-agent system is configured
-- **WHEN** the API server is started
-- **THEN** REST endpoints are available at the configured port (default 3000)
-- **AND** WebSocket connections are accepted for real-time updates
-
-#### Scenario: Server configuration
-- **GIVEN** config specifies port 4000 and host 'localhost'
-- **WHEN** the API server is started
-- **THEN** the server listens on localhost:4000
-
----
-
-### Requirement: System Endpoints
-
-The system SHALL provide endpoints for system management.
-
-#### Scenario: Initialize system
-- **GIVEN** a fresh system start
-- **WHEN** POST /api/init is called
-- **THEN** the event store is initialized
-- **AND** configuration is loaded
-- **AND** the system is ready to accept commands
-
-#### Scenario: Get system status
-- **GIVEN** a running system with agents
-- **WHEN** GET /api/status is called
-- **THEN** the response includes system state (running/stopped)
-- **AND** head manager info (id, state)
-- **AND** aggregate counts (agents running, tasks in progress)
-
----
-
-### Requirement: Conversation Endpoints
-
-The system SHALL provide endpoints for user conversation with the head manager.
-
-#### Scenario: Send message to head manager
-- **GIVEN** the system is running
-- **WHEN** POST /api/conversation/message with { content: 'Hello' } is called
-- **THEN** the head manager is created if not exists
-- **AND** the message is sent to the head manager via ACP
-- **AND** the response includes { status: 'sent', agent_id }
-
-#### Scenario: Get conversation history
-- **GIVEN** previous messages with the head manager
-- **WHEN** GET /api/conversation/history is called
-- **THEN** the conversation history is returned
-- **AND** messages include role (user/assistant), content, timestamp
-
----
-
-### Requirement: Agent Endpoints
-
-The system SHALL provide read-only endpoints for agent information.
-
-#### Scenario: List agents
-- **GIVEN** multiple agents in the system
-- **WHEN** GET /api/agents is called
-- **THEN** all agents are returned with id, state, task summary, parent
-
-#### Scenario: List agents with filter
-- **GIVEN** agents in various states
-- **WHEN** GET /api/agents?state=running is called
-- **THEN** only running agents are returned
-
-#### Scenario: Get agent details
-- **GIVEN** agent 'agent_1' exists
-- **WHEN** GET /api/agents/agent_1 is called
-- **THEN** full agent details are returned including config, timestamps, children
-
-#### Scenario: Get agent hierarchy
-- **GIVEN** agent 'agent_1' with children
-- **WHEN** GET /api/agents/agent_1/hierarchy is called
-- **THEN** the subtree under agent_1 is returned as a tree structure
-
----
-
-### Requirement: Task Endpoints
-
-The system SHALL provide read-only endpoints for task information.
-
-#### Scenario: List tasks
-- **GIVEN** multiple tasks in the system
-- **WHEN** GET /api/tasks is called
-- **THEN** all tasks are returned with id, description, status, assigned_agent
-
-#### Scenario: List tasks with filter
-- **GIVEN** tasks in various statuses
-- **WHEN** GET /api/tasks?status=in_progress is called
-- **THEN** only in-progress tasks are returned
-
-#### Scenario: Get task details
-- **GIVEN** task 'task_1' exists
-- **WHEN** GET /api/tasks/task_1 is called
-- **THEN** full task details are returned including inputs, outputs, artifacts, agent_history
-
----
-
-### Requirement: Event Endpoints
-
-The system SHALL provide endpoints for event queries (debugging).
-
-#### Scenario: Query events
-- **GIVEN** events in the event store
-- **WHEN** GET /api/events?type=status is called
-- **THEN** status events are returned in chronological order
-
-#### Scenario: Query events with time range
-- **GIVEN** events spanning multiple timestamps
-- **WHEN** GET /api/events?after=timestamp1&before=timestamp2 is called
-- **THEN** only events within the time range are returned
-
----
-
-### Requirement: WebSocket Real-time Updates
-
-The system SHALL provide WebSocket channels for real-time updates.
-
-#### Scenario: Subscribe to agent updates
-- **GIVEN** a WebSocket connection
-- **WHEN** client sends { type: 'subscribe', channel: 'agents' }
-- **THEN** the client receives agent:update events when agents change state
-
-#### Scenario: Subscribe to task updates
-- **GIVEN** a WebSocket connection
-- **WHEN** client sends { type: 'subscribe', channel: 'tasks' }
-- **THEN** the client receives task:update events when tasks change
-
-#### Scenario: Subscribe to conversation
-- **GIVEN** a WebSocket connection
-- **WHEN** client sends { type: 'subscribe', channel: 'conversation' }
-- **THEN** the client receives conversation:message events for head manager responses
-
-#### Scenario: TinyBase to WebSocket bridge
-- **GIVEN** a client subscribed to 'agents' channel
-- **WHEN** a spawn event is emitted and the agents view updates
-- **THEN** the WebSocket client receives the agent:update event in real-time
-
----
-
-### Requirement: CLI Start Command
-
-The system SHALL provide a command to start the multi-agent system.
-
-#### Scenario: Start system
-- **GIVEN** the CLI is installed
-- **WHEN** `multiagent start` is executed
-- **THEN** the API server starts
-- **AND** the event store is initialized
-- **AND** the MCP server starts
-- **AND** a success message is displayed
-
-#### Scenario: Start with custom port
-- **GIVEN** the CLI is installed
-- **WHEN** `multiagent start --port 4000` is executed
-- **THEN** the API server starts on port 4000
-
----
-
-### Requirement: CLI Chat Command
-
-The system SHALL provide an interactive chat mode.
-
-#### Scenario: Enter chat mode
-- **GIVEN** the system is running
-- **WHEN** `multiagent chat` is executed
-- **THEN** a prompt appears for user input
-- **AND** a WebSocket connection is established for real-time updates
-
-#### Scenario: Send message in chat
-- **GIVEN** chat mode is active
-- **WHEN** user types a message and presses enter
-- **THEN** the message is sent to the head manager
-- **AND** the response streams back and is displayed
-
-#### Scenario: Real-time status in chat
-- **GIVEN** chat mode is active with verbose flag
-- **WHEN** an agent status changes
-- **THEN** a status line is displayed: [status] Agent X: running
-
----
-
-### Requirement: CLI Status Commands
-
-The system SHALL provide commands to view system state.
-
-#### Scenario: System status
-- **GIVEN** the system is running
-- **WHEN** `multiagent status` is executed
-- **THEN** system status is displayed (running/stopped)
-- **AND** head manager info is displayed
-- **AND** aggregate counts are displayed (agents, tasks)
-
-#### Scenario: List agents
-- **GIVEN** agents exist in the system
-- **WHEN** `multiagent agents` is executed
-- **THEN** a table of agents is displayed with id, state, task
-
-#### Scenario: Agent details
-- **GIVEN** agent 'agent_1' exists
-- **WHEN** `multiagent agents agent_1` is executed
-- **THEN** detailed agent info is displayed
-
-#### Scenario: List tasks
-- **GIVEN** tasks exist in the system
-- **WHEN** `multiagent tasks` is executed
-- **THEN** a table of tasks is displayed with id, status, assigned_agent
-
-#### Scenario: Task details
-- **GIVEN** task 'task_1' exists
-- **WHEN** `multiagent tasks task_1` is executed
-- **THEN** detailed task info is displayed
-
----
-
-### Requirement: CLI Hierarchy Command
-
-The system SHALL provide a command to visualize the agent tree.
-
-#### Scenario: Display hierarchy
-- **GIVEN** a multi-level agent hierarchy
-- **WHEN** `multiagent hierarchy` is executed
-- **THEN** a tree visualization is displayed:
-```
-agent_abc123 (head_manager) [running]
-├── agent_def456 (architect) [completed]
-├── agent_ghi789 (implementer) [running]
-│   ├── agent_jkl012 (auth_module) [completed]
-│   └── agent_mno345 (api_routes) [running]
-└── agent_pqr678 (reviewer) [stopped]
-```
-
----
-
-### Requirement: CLI Management Commands
-
-The system SHALL provide commands for system management.
-
-#### Scenario: Clear system
-- **GIVEN** the system has history
-- **WHEN** `multiagent clear` is executed
-- **THEN** the user is prompted for confirmation
-- **AND** if confirmed, the event store is cleared
-- **AND** a new head manager will be created on next interaction
-
-#### Scenario: Stop system
-- **GIVEN** the system is running
-- **WHEN** `multiagent stop` is executed
-- **THEN** all running agents are terminated gracefully
-- **AND** the API server stops
-- **AND** state is persisted

package/openspec/changes/archive/2025-12-21-add-mvp-foundation/specs/event-store/spec.md

@@ -1,160 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Event Store Initialization
-
-The system SHALL provide an EventStore that initializes TinyBase with persistent storage.
-
-#### Scenario: Store initialization with default config
-- **GIVEN** no existing store file
-- **WHEN** createEventStore() is called with default config
-- **THEN** a new TinyBase store is created at ~/.multiagent/store.db
-- **AND** the events table is created with the correct schema
-- **AND** materialized view tables are initialized (agents, tasks, messages, subscriptions)
-
-#### Scenario: Store initialization with existing data
-- **GIVEN** an existing store file with previous events
-- **WHEN** createEventStore() is called
-- **THEN** the existing store is loaded
-- **AND** materialized views are rebuilt from the event log
-
----
-
-### Requirement: Event Emission
-
-The system SHALL emit events to an append-only log with auto-generated IDs and timestamps.
-
-#### Scenario: Emit a spawn event
-- **GIVEN** an initialized EventStore
-- **WHEN** emit({ type: 'spawn', source: { agent_id: 'parent_1' }, payload: { agent_id: 'child_1', task: 'do work' } }) is called
-- **THEN** an event is created with a unique event_id
-- **AND** the event has a timestamp set to the current time
-- **AND** the event is appended to the events table
-- **AND** the function returns the complete event with id and timestamp
-
-#### Scenario: Event immutability
-- **GIVEN** an event has been emitted
-- **WHEN** any attempt is made to modify the event
-- **THEN** the modification fails or is rejected
-- **AND** the original event remains unchanged
-
----
-
-### Requirement: Event Querying
-
-The system SHALL support querying events with filters.
-
-#### Scenario: Query events by type
-- **GIVEN** an EventStore with spawn, status, and message events
-- **WHEN** query({ type: 'status' }) is called
-- **THEN** only status events are returned
-- **AND** events are returned in chronological order
-
-#### Scenario: Query events by source agent
-- **GIVEN** an EventStore with events from multiple agents
-- **WHEN** query({ source_agent_id: 'agent_1' }) is called
-- **THEN** only events where source.agent_id equals 'agent_1' are returned
-
-#### Scenario: Query events by time range
-- **GIVEN** an EventStore with events spanning multiple timestamps
-- **WHEN** query({ after: timestamp1, before: timestamp2 }) is called
-- **THEN** only events within the time range are returned
-
----
-
-### Requirement: Agent View Projection
-
-The system SHALL maintain a materialized view of agents derived from events.
-
-#### Scenario: Agent created on spawn event
-- **GIVEN** an empty agents view
-- **WHEN** a spawn event is emitted for agent_id 'agent_1'
-- **THEN** the agents view contains an entry for 'agent_1'
-- **AND** the entry has state 'spawning'
-- **AND** the entry includes session_id, parent, task, and created_at from the event
-
-#### Scenario: Agent state updated on status event
-- **GIVEN** an agent in 'spawning' state
-- **WHEN** a status event with status_type 'started' is emitted for that agent
-- **THEN** the agent's state changes to 'running'
-- **AND** started_at is set to the event timestamp
-
-#### Scenario: Agent state updated on terminate event
-- **GIVEN** an agent in 'running' state
-- **WHEN** a terminate event is emitted for that agent with reason 'completed'
-- **THEN** the agent's state changes to 'stopped'
-- **AND** stop_reason is set to 'completed'
-- **AND** stopped_at is set to the event timestamp
-
----
-
-### Requirement: Task View Projection
-
-The system SHALL maintain a materialized view of tasks derived from events.
-
-#### Scenario: Task created on task event
-- **GIVEN** an empty tasks view
-- **WHEN** a task event with action 'created' is emitted
-- **THEN** the tasks view contains an entry for the task_id
-- **AND** the entry has status 'pending'
-- **AND** the entry includes description and created_by from the event
-
-#### Scenario: Task assigned on task event
-- **GIVEN** a task in 'pending' status
-- **WHEN** a task event with action 'assigned' is emitted
-- **THEN** the task's status changes to 'assigned'
-- **AND** assigned_agent is set to the agent_id from the event
-
-#### Scenario: Task status change
-- **GIVEN** a task in 'assigned' status
-- **WHEN** a task event with action 'status_change' and status 'in_progress' is emitted
-- **THEN** the task's status changes to 'in_progress'
-
----
-
-### Requirement: Message Queue Projection
-
-The system SHALL maintain a materialized view of pending messages per agent.
-
-#### Scenario: Message added to recipient queue
-- **GIVEN** an agent 'agent_1' with an empty message queue
-- **WHEN** a message event is emitted with target.agent_id 'agent_1'
-- **THEN** the message appears in agent_1's pending messages
-- **AND** the message includes id, from, content, timestamp
-
-#### Scenario: Message delivered to multiple recipients
-- **GIVEN** agents 'agent_1' and 'agent_2' subscribed to topic 'updates'
-- **WHEN** a message event is emitted with target.topic 'updates'
-- **THEN** the message appears in both agent_1's and agent_2's pending queues
-
----
-
-### Requirement: Subscription Projection
-
-The system SHALL maintain a materialized view of agent subscriptions.
-
-#### Scenario: Subscription added
-- **GIVEN** an agent 'agent_1' with no subscriptions
-- **WHEN** a subscription is registered for { type: 'topic', target: 'errors' }
-- **THEN** the subscriptions view shows agent_1 subscribed to topic 'errors'
-
-#### Scenario: Query subscribers by topic
-- **GIVEN** multiple agents subscribed to topic 'discoveries'
-- **WHEN** getSubscribers({ type: 'topic', target: 'discoveries' }) is called
-- **THEN** all agent_ids subscribed to that topic are returned
-
----
-
-### Requirement: Real-time View Updates
-
-The system SHALL provide reactive updates when views change.
-
-#### Scenario: Subscribe to agent view changes
-- **GIVEN** a subscription to agent view changes
-- **WHEN** a spawn event is emitted
-- **THEN** the subscriber callback is invoked with the updated agent entry
-
-#### Scenario: Subscribe to specific agent changes
-- **GIVEN** a subscription to changes for agent 'agent_1'
-- **WHEN** a status event is emitted for 'agent_1'
-- **THEN** the subscriber callback is invoked
-- **AND** changes to other agents do not trigger the callback