macro-agent 0.0.10 → 0.0.12

package/openspec/specs/mcp-tools/spec.md

@@ -1,228 +0,0 @@
-# mcp-tools Specification
-
-## Purpose
-TBD - created by archiving change add-mvp-foundation. Update Purpose after archive.
-## Requirements
-### Requirement: MCP Server Setup
-
-The system SHALL provide an MCP server that exposes multi-agent tools to agents.
-
-#### Scenario: Start MCP server
-- **GIVEN** the multi-agent system is initialized
-- **WHEN** the MCP server is started
-- **THEN** the server registers all available tools
-- **AND** agents can discover tools via the MCP protocol
-
-#### Scenario: Tool context injection
-- **GIVEN** an agent with id 'agent_1' and session 'sess_123'
-- **WHEN** the agent calls any MCP tool
-- **THEN** the tool handler receives context { agent_id: 'agent_1', session_id: 'sess_123' }
-- **AND** the tool can use this context for authorization and attribution
-
----
-
-### Requirement: spawn_agent Tool
-
-The system SHALL provide a tool for agents to spawn child agents.
-
-#### Scenario: Spawn child agent
-- **GIVEN** an agent 'manager_1' calls spawn_agent
-- **WHEN** spawn_agent({ task: 'Implement feature X' }) is invoked
-- **THEN** a new agent is spawned with parent 'manager_1'
-- **AND** the tool returns { agent_id, task_id }
-
-#### Scenario: Spawn with subscribe_parent false
-- **GIVEN** an agent calls spawn_agent with fire-and-forget intent
-- **WHEN** spawn_agent({ task: 'Background task', subscribe_parent: false }) is invoked
-- **THEN** the parent is NOT subscribed to the child's subtree
-- **AND** the child operates independently
-
-#### Scenario: Spawn with custom config
-- **GIVEN** an agent needs a specific model for a child
-- **WHEN** spawn_agent({ task: 'Complex analysis', config: { model: 'claude-opus-4-20250514' } }) is invoked
-- **THEN** the child agent uses the specified model
-
----
-
-### Requirement: emit_status Tool
-
-The system SHALL provide a tool for agents to report status milestones.
-
-#### Scenario: Emit started status
-- **GIVEN** agent 'worker_1' beginning work
-- **WHEN** emit_status({ status_type: 'started', summary: 'Beginning implementation' }) is invoked
-- **THEN** a status event is emitted with source agent_id 'worker_1'
-- **AND** the tool returns { event_id }
-
-#### Scenario: Emit checkpoint status
-- **GIVEN** agent 'worker_1' reaching a milestone
-- **WHEN** emit_status({ status_type: 'checkpoint', summary: '50% complete', details: { progress: '50%' } }) is invoked
-- **THEN** the status event includes the details
-- **AND** subscribers (e.g., parent) receive the update
-
-#### Scenario: Emit completed status
-- **GIVEN** agent 'worker_1' finishing work
-- **WHEN** emit_status({ status_type: 'completed', summary: 'Task finished', details: { artifacts: [...] } }) is invoked
-- **THEN** the completion is recorded
-- **AND** the agent's task status is updated
-
----
-
-### Requirement: send_message Tool
-
-The system SHALL provide a tool for agents to send messages.
-
-#### Scenario: Send direct message
-- **GIVEN** agent 'agent_1' wants to message 'agent_2'
-- **WHEN** send_message({ to: { agent_id: 'agent_2' }, content: 'Need your input' }) is invoked
-- **THEN** the message is routed to agent_2
-- **AND** the tool returns { message_id }
-
-#### Scenario: Send message to topic
-- **GIVEN** agent 'agent_1' wants to broadcast to a topic
-- **WHEN** send_message({ to: { topic: 'discoveries' }, content: 'Found issue X' }) is invoked
-- **THEN** all agents subscribed to 'discoveries' receive the message
-
-#### Scenario: Send reply with correlation
-- **GIVEN** agent received message 'msg_123'
-- **WHEN** send_message({ to: { agent_id: 'sender' }, content: 'Response', correlation_id: 'msg_123' }) is invoked
-- **THEN** the response is threaded with the original message
-
----
-
-### Requirement: check_messages Tool
-
-The system SHALL provide a tool for agents to check their message queue.
-
-#### Scenario: Check messages with default limit
-- **GIVEN** agent 'agent_1' has pending messages
-- **WHEN** check_messages({}) is invoked by agent_1
-- **THEN** up to 10 messages are returned (default limit)
-- **AND** messages include id, from, content, timestamp, truncated flag
-
-#### Scenario: Check messages with custom limit
-- **GIVEN** agent 'agent_1' has many pending messages
-- **WHEN** check_messages({ limit: 5 }) is invoked
-- **THEN** only 5 messages are returned
-
-#### Scenario: No pending messages
-- **GIVEN** agent 'agent_1' has no pending messages
-- **WHEN** check_messages({}) is invoked
-- **THEN** an empty messages array is returned
-
----
-
-### Requirement: query_index Tool
-
-The system SHALL provide a tool for agents to search for agents and tasks.
-
-#### Scenario: Query running agents
-- **GIVEN** multiple agents in various states
-- **WHEN** query_index({ type: 'agents', filter: { state: 'running' } }) is invoked
-- **THEN** only running agents are returned
-- **AND** the tool returns { entries, total, has_more }
-
-#### Scenario: Query tasks by status
-- **GIVEN** tasks in various statuses
-- **WHEN** query_index({ type: 'tasks', filter: { status: 'in_progress' } }) is invoked
-- **THEN** only in-progress tasks are returned
-
-#### Scenario: Search with text query
-- **GIVEN** agents and tasks with various descriptions
-- **WHEN** query_index({ type: 'all', search: 'authentication' }) is invoked
-- **THEN** entries matching 'authentication' are returned
-- **AND** results are sorted by relevance/recency
-
----
-
-### Requirement: get_hierarchy Tool
-
-The system SHALL provide a tool for agents to view the agent tree.
-
-#### Scenario: Get full hierarchy
-- **GIVEN** a multi-level agent hierarchy
-- **WHEN** get_hierarchy({}) is invoked
-- **THEN** the complete tree from head manager is returned
-- **AND** each node includes agent_id, task, state, children
-
-#### Scenario: Get hierarchy from specific root
-- **GIVEN** agent 'manager_1' with children
-- **WHEN** get_hierarchy({ root: 'manager_1' }) is invoked
-- **THEN** only the subtree under manager_1 is returned
-
-#### Scenario: Get hierarchy with depth limit
-- **GIVEN** a deep hierarchy
-- **WHEN** get_hierarchy({ depth: 2 }) is invoked
-- **THEN** only 2 levels of the hierarchy are returned
-
----
-
-### Requirement: get_agent_summary Tool
-
-The system SHALL provide a tool for quick agent lookup.
-
-#### Scenario: Get agent summary
-- **GIVEN** agent 'worker_1' exists with recent activity
-- **WHEN** get_agent_summary({ agent_id: 'worker_1' }) is invoked
-- **THEN** the summary includes id, session_id, task, state, parent, children_count, last_activity, recent_status
-
-#### Scenario: Get non-existent agent
-- **GIVEN** no agent with id 'nonexistent'
-- **WHEN** get_agent_summary({ agent_id: 'nonexistent' }) is invoked
-- **THEN** an error is returned indicating agent not found
-
----
-
-### Requirement: stop_agent Tool
-
-The system SHALL provide a tool for agents to terminate their children.
-
-#### Scenario: Stop own child
-- **GIVEN** agent 'manager_1' spawned 'worker_1'
-- **WHEN** manager_1 invokes stop_agent({ agent_id: 'worker_1' })
-- **THEN** worker_1 is terminated with reason 'stopped'
-- **AND** the tool returns { success: true }
-
-#### Scenario: Stop grandchild
-- **GIVEN** hierarchy: manager_1 → worker_1 → helper_1
-- **WHEN** manager_1 invokes stop_agent({ agent_id: 'helper_1' })
-- **THEN** helper_1 is terminated (manager_1 owns the subtree)
-
-#### Scenario: Cannot stop agent outside subtree
-- **GIVEN** agent 'agent_A' not in 'agent_B's subtree
-- **WHEN** agent_B invokes stop_agent({ agent_id: 'agent_A' })
-- **THEN** the operation fails with error 'Cannot stop agent outside your subtree'
-
----
-
-### Requirement: create_task Tool
-
-The system SHALL provide a tool for agents to create explicit tasks.
-
-#### Scenario: Create task
-- **GIVEN** agent 'manager_1' wants to create a task
-- **WHEN** create_task({ description: 'Review code changes' }) is invoked by manager_1
-- **THEN** a new task is created with created_by: 'manager_1'
-- **AND** the tool returns { task_id }
-
-#### Scenario: Create subtask
-- **GIVEN** parent task 'task_1' exists
-- **WHEN** create_task({ description: 'Subtask', parent_task: 'task_1' }) is invoked
-- **THEN** the task is created with parent_task reference
-
----
-
-### Requirement: get_task Tool
-
-The system SHALL provide a tool for agents to lookup task details.
-
-#### Scenario: Get task details
-- **GIVEN** task 'task_1' exists
-- **WHEN** get_task({ task_id: 'task_1' }) is invoked
-- **THEN** the full task record is returned including description, status, assigned_agent, inputs, outputs, artifacts
-
-#### Scenario: Get non-existent task
-- **GIVEN** no task with id 'nonexistent'
-- **WHEN** get_task({ task_id: 'nonexistent' }) is invoked
-- **THEN** an error is returned indicating task not found
-

package/openspec/specs/message-router/spec.md

@@ -1,157 +0,0 @@
-# message-router Specification
-
-## Purpose
-TBD - created by archiving change add-mvp-foundation. Update Purpose after archive.
-## Requirements
-### Requirement: Message Sending
-
-The system SHALL route messages to recipients based on target specification.
-
-#### Scenario: Send direct message to agent
-- **GIVEN** agents 'sender_1' and 'recipient_1' exist
-- **WHEN** send({ from: { agent_id: 'sender_1' }, to: { agent_id: 'recipient_1' }, content: 'Hello' }) is called
-- **THEN** a message event is emitted
-- **AND** the message appears in recipient_1's pending queue
-- **AND** the function returns the message with id and timestamp
-
-#### Scenario: Send message to task
-- **GIVEN** task 'task_1' assigned to agent 'worker_1'
-- **WHEN** send({ from: { agent_id: 'sender_1' }, to: { task_id: 'task_1' }, content: 'Status update needed' }) is called
-- **THEN** the message is routed to 'worker_1' (the assigned agent)
-- **AND** the message appears in worker_1's pending queue
-
-#### Scenario: Send message to topic
-- **GIVEN** agents 'agent_1' and 'agent_2' subscribed to topic 'errors'
-- **WHEN** send({ from: { agent_id: 'sender_1' }, to: { topic: 'errors' }, content: 'Error detected' }) is called
-- **THEN** the message appears in both agent_1's and agent_2's pending queues
-
-#### Scenario: Send message with correlation_id
-- **GIVEN** an original message with id 'msg_123'
-- **WHEN** send({ from: { agent_id: 'responder' }, to: { agent_id: 'requester' }, content: 'Response', correlation_id: 'msg_123' }) is called
-- **THEN** the message includes correlation_id 'msg_123' for threading
-
----
-
-### Requirement: Message Retrieval
-
-The system SHALL allow agents to retrieve their pending messages.
-
-#### Scenario: Get pending messages
-- **GIVEN** agent 'agent_1' has 3 pending messages
-- **WHEN** getMessages('agent_1') is called
-- **THEN** all 3 messages are returned in chronological order
-- **AND** each message includes id, from, content, timestamp
-
-#### Scenario: Get messages with limit
-- **GIVEN** agent 'agent_1' has 10 pending messages
-- **WHEN** getMessages('agent_1', { limit: 5 }) is called
-- **THEN** only the 5 oldest messages are returned
-
-#### Scenario: Get full message content
-- **GIVEN** a message 'msg_1' with truncated content in the queue
-- **WHEN** getFullMessage('msg_1') is called
-- **THEN** the complete message content is returned
-
-#### Scenario: Empty message queue
-- **GIVEN** agent 'agent_1' has no pending messages
-- **WHEN** getMessages('agent_1') is called
-- **THEN** an empty array is returned
-
----
-
-### Requirement: Subscription Management
-
-The system SHALL manage agent subscriptions to message channels.
-
-#### Scenario: Subscribe to topic
-- **GIVEN** agent 'agent_1' with no topic subscriptions
-- **WHEN** subscribe('agent_1', { type: 'topic', target: 'discoveries' }) is called
-- **THEN** agent_1 is subscribed to topic 'discoveries'
-- **AND** future messages to topic 'discoveries' are routed to agent_1
-
-#### Scenario: Subscribe to agent channel
-- **GIVEN** agent 'agent_1'
-- **WHEN** subscribe('agent_1', { type: 'agent', target: 'agent_1' }) is called
-- **THEN** agent_1 receives direct messages addressed to it
-
-#### Scenario: Subscribe to subtree
-- **GIVEN** manager 'manager_1' spawned child 'child_1'
-- **WHEN** subscribe('manager_1', { type: 'subtree', target: 'child_1' }) is called
-- **THEN** manager_1 receives all events from child_1 and its descendants
-
-#### Scenario: Unsubscribe from topic
-- **GIVEN** agent 'agent_1' subscribed to topic 'updates'
-- **WHEN** unsubscribe('agent_1', { type: 'topic', target: 'updates' }) is called
-- **THEN** agent_1 no longer receives messages to topic 'updates'
-
-#### Scenario: Get agent subscriptions
-- **GIVEN** agent 'agent_1' with multiple subscriptions
-- **WHEN** getSubscriptions('agent_1') is called
-- **THEN** all subscriptions are returned as an array of { type, target }
-
----
-
-### Requirement: Automatic Subscription Setup
-
-The system SHALL configure default subscriptions when agents spawn.
-
-#### Scenario: Default subscriptions on spawn
-- **GIVEN** spawning agent 'child_1' with parent 'parent_1'
-- **WHEN** default subscriptions are set up
-- **THEN** child_1 is subscribed to { type: 'agent', target: 'child_1' }
-- **AND** child_1 is subscribed to { type: 'lineage', target: 'child_1' }
-- **AND** if task_id provided, child_1 is subscribed to { type: 'task', target: task_id }
-
-#### Scenario: Parent subtree subscription
-- **GIVEN** spawning agent 'child_1' with parent 'parent_1' and subscribe_parent: true
-- **WHEN** default subscriptions are set up
-- **THEN** parent_1 is subscribed to { type: 'subtree', target: 'child_1' }
-
-#### Scenario: Skip parent subscription
-- **GIVEN** spawning agent 'child_1' with parent 'parent_1' and subscribe_parent: false
-- **WHEN** default subscriptions are set up
-- **THEN** parent_1 is NOT subscribed to child_1's subtree
-
----
-
-### Requirement: Status Event Routing
-
-The system SHALL route status events to appropriate subscribers.
-
-#### Scenario: Route status to parent
-- **GIVEN** agent 'child_1' with parent 'parent_1' subscribed to subtree
-- **WHEN** child_1 emits a status event (e.g., 'checkpoint')
-- **THEN** the status event appears in parent_1's message queue
-- **AND** the event includes agent_id, task_id, status_type, summary
-
-#### Scenario: Route completed status
-- **GIVEN** agent 'worker_1' with manager 'manager_1' subscribed to subtree
-- **WHEN** worker_1 emits status { status_type: 'completed', summary: 'Task done' }
-- **THEN** manager_1 receives the completion notification
-- **AND** can query worker_1 for detailed results
-
-#### Scenario: Route failed status
-- **GIVEN** agent 'worker_1' with manager 'manager_1' subscribed to subtree
-- **WHEN** worker_1 emits status { status_type: 'failed', summary: 'Error occurred' }
-- **THEN** manager_1 receives the failure notification
-- **AND** the event includes error details for manager to decide on recovery
-
----
-
-### Requirement: Message Truncation
-
-The system SHALL truncate large messages in the queue with reference to full content.
-
-#### Scenario: Truncate large message
-- **GIVEN** a message with content exceeding the configured limit (e.g., 1000 tokens)
-- **WHEN** the message is added to a recipient's queue
-- **THEN** the queued message content is truncated
-- **AND** the message is marked with truncated: true
-- **AND** the full content is retrievable via getFullMessage(message_id)
-
-#### Scenario: Small message not truncated
-- **GIVEN** a message with content under the configured limit
-- **WHEN** the message is added to a recipient's queue
-- **THEN** the full content is included
-- **AND** the message is marked with truncated: false
-

package/openspec/specs/task-manager/spec.md

@@ -1,140 +0,0 @@
-# task-manager Specification
-
-## Purpose
-TBD - created by archiving change add-mvp-foundation. Update Purpose after archive.
-## Requirements
-### Requirement: Task Creation
-
-The system SHALL create tasks with unique IDs and emit task events.
-
-#### Scenario: Create a new task
-- **GIVEN** an initialized TaskManager
-- **WHEN** create({ description: 'Implement user authentication', created_by: 'agent_1' }) is called
-- **THEN** a unique task_id is generated
-- **AND** a task event with action 'created' is emitted
-- **AND** the task appears in the tasks view with status 'pending'
-- **AND** the function returns the new task record
-
-#### Scenario: Create task with inputs
-- **GIVEN** an initialized TaskManager
-- **WHEN** create({ description: 'Review PR #123', created_by: 'manager_1', inputs: { pr_number: 123, repo: 'my-repo' } }) is called
-- **THEN** the task is created with the provided inputs
-- **AND** the inputs are stored in the task record
-
----
-
-### Requirement: Task Retrieval
-
-The system SHALL support retrieving tasks by ID and filtering.
-
-#### Scenario: Get task by ID
-- **GIVEN** a task 'task_1' exists
-- **WHEN** get('task_1') is called
-- **THEN** the full task record is returned including id, description, status, assigned_agent, timestamps
-
-#### Scenario: Get non-existent task
-- **GIVEN** no task with id 'nonexistent'
-- **WHEN** get('nonexistent') is called
-- **THEN** null is returned
-
-#### Scenario: List tasks with status filter
-- **GIVEN** tasks in various statuses (pending, in_progress, completed)
-- **WHEN** list({ status: 'in_progress' }) is called
-- **THEN** only tasks with status 'in_progress' are returned
-
-#### Scenario: List tasks by assigned agent
-- **GIVEN** agent 'worker_1' assigned to tasks 'task_1' and 'task_2'
-- **WHEN** list({ assigned_agent: 'worker_1' }) is called
-- **THEN** both 'task_1' and 'task_2' are returned
-
----
-
-### Requirement: Task Assignment
-
-The system SHALL support assigning and unassigning agents to tasks.
-
-#### Scenario: Assign agent to task
-- **GIVEN** a task 'task_1' in 'pending' status
-- **WHEN** assign('task_1', 'worker_1') is called
-- **THEN** a task event with action 'assigned' is emitted
-- **AND** the task's assigned_agent is set to 'worker_1'
-- **AND** the task's status changes to 'assigned'
-- **AND** an entry is added to the task's agent_history
-
-#### Scenario: Assign with role
-- **GIVEN** a task 'task_1' in 'pending' status
-- **WHEN** assign('task_1', 'reviewer_1', 'reviewer') is called
-- **THEN** the agent_history entry includes role 'reviewer'
-
-#### Scenario: Unassign agent from task
-- **GIVEN** a task 'task_1' assigned to 'worker_1'
-- **WHEN** unassign('task_1', 'worker_1') is called
-- **THEN** a task event with action 'unassigned' is emitted
-- **AND** the task's assigned_agent is cleared
-- **AND** the agent_history entry's ended_at is set
-
----
-
-### Requirement: Task Status Updates
-
-The system SHALL support updating task status with appropriate transitions.
-
-#### Scenario: Start task
-- **GIVEN** a task 'task_1' in 'assigned' status
-- **WHEN** updateStatus('task_1', 'in_progress') is called
-- **THEN** a task event with action 'status_change' is emitted
-- **AND** the task's status changes to 'in_progress'
-- **AND** started_at is set if not already set
-
-#### Scenario: Complete task
-- **GIVEN** a task 'task_1' in 'in_progress' status
-- **WHEN** updateStatus('task_1', 'completed') is called
-- **THEN** a task event with action 'completed' is emitted
-- **AND** the task's status changes to 'completed'
-- **AND** completed_at is set to current timestamp
-
-#### Scenario: Fail task
-- **GIVEN** a task 'task_1' in 'in_progress' status
-- **WHEN** updateStatus('task_1', 'failed') is called
-- **THEN** a task event with action 'failed' is emitted
-- **AND** the task's status changes to 'failed'
-
----
-
-### Requirement: Task Updates
-
-The system SHALL support updating task metadata.
-
-#### Scenario: Update task outputs
-- **GIVEN** a task 'task_1' in 'in_progress' status
-- **WHEN** update('task_1', { outputs: { result: 'success', files_changed: 5 } }) is called
-- **THEN** the task's outputs are updated
-- **AND** the change is reflected in the tasks view
-
-#### Scenario: Add artifact to task
-- **GIVEN** a task 'task_1'
-- **WHEN** update('task_1', { artifacts: [{ type: 'file', ref: 'src/auth.ts' }] }) is called
-- **THEN** the artifact is added to the task's artifacts array
-
----
-
-### Requirement: Subtask Management
-
-The system SHALL support hierarchical task decomposition.
-
-#### Scenario: Create subtask
-- **GIVEN** a parent task 'task_1'
-- **WHEN** createSubtask('task_1', { description: 'Implement JWT validation', created_by: 'manager_1' }) is called
-- **THEN** a new task is created with parent_task set to 'task_1'
-- **AND** the new task_id is added to task_1's subtasks array
-
-#### Scenario: Get subtasks
-- **GIVEN** task 'task_1' with subtasks 'task_2' and 'task_3'
-- **WHEN** getSubtasks('task_1') is called
-- **THEN** both 'task_2' and 'task_3' task records are returned
-
-#### Scenario: Subtask status rollup
-- **GIVEN** task 'task_1' with subtasks 'task_2' (completed) and 'task_3' (in_progress)
-- **WHEN** querying task 'task_1'
-- **THEN** the parent task can derive aggregate status from subtask statuses
-

package/references/acp-factory-ref/CHANGELOG.md

@@ -1,33 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [0.1.0] - 2024-XX-XX
-
-### Added
-
-- Initial release
-- `AgentFactory` for registering and spawning agents
-- `AgentHandle` for managing agent processes
-- `Session` for interacting with agent sessions
-- Pre-registered `claude-code` agent
-- Streaming responses via async iterators
-- Permission handling modes: `auto-approve`, `auto-deny`, `callback`, `interactive`
-- Interactive permission requests as session updates
-- `session.interruptWith()` for interrupting and redirecting agents
-- `session.fork()` for creating independent session copies (experimental)
-- `agentHandle.forkSession()` for forking by session ID (experimental)
-- `session.addContext()` stub for future mid-execution messaging
-- Custom file read/write handlers
-- Terminal operation handlers
-- MCP server support
-- Full TypeScript type exports
-
-### Dependencies
-
-- `@agentclientprotocol/sdk` ^0.10.0

package/references/acp-factory-ref/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Sudocode AI
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.