Metadata-Version: 2.4
Name: kollabor-agent
Version: 0.5.7
Summary: Agent execution toolkit - tool execution, MCP integration, file operations, and shell commands
License: MIT
Requires-Python: >=3.12
Requires-Dist: kollabor-ai>=0.5.7
Requires-Dist: kollabor-config>=0.5.7
Requires-Dist: kollabor-events>=0.5.7
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# kollabor-agent

`kollabor-agent` is the tool and agent execution runtime for Kollabor.

It owns tool dispatch, MCP server connections, file operations, shell execution,
agent/skill loading, background tasks, process management, and permission-aware
execution. The CLI and engine both build on this package when a model wants to
act on the local environment.

## Current Role

- Execute built-in tools such as terminal commands, file operations, and MCP
  tool calls.
- Load agent definitions and skills from project, user, and bundled locations.
- Manage MCP stdio servers and expose their tools to model providers.
- Provide permission risk assessment and approval flow primitives.
- Run background processes/tasks and provide process lifecycle helpers.
- Bridge native/XML tool definitions into the unified tool registry.

## Architecture

| Module | Responsibility |
|---|---|
| `tool_executor.py` | unified dispatch for terminal, file, MCP, and plugin tools |
| `file_operations_executor.py` | read/write/edit/move/copy/delete file operations |
| `mcp_integration.py` / `mcp_manager.py` | MCP config loading, connection, discovery, calls |
| `permissions/` | approval modes, risk assessment, response handling |
| `agent_manager.py` | agent, skill, and prompt asset loading |
| `runtime.py` / `process_manager.py` | agent lifecycle and managed processes |
| `background_task_manager.py` | background task tracking and cleanup |
| `shell_executor.py` / `shell_command_service.py` | async shell execution services |
| `native_tools_handler.py` | native tool-call routing |
| `tool_registry.py` / `tool_definitions/` | canonical tool metadata and schemas |
| `tool_generators/` | markdown, XML, and native JSON tool generation |
| `queue_processor.py` | tool queue and continuation flow used by the app |

## Usage

```python
from kollabor_agent import MCPIntegration, ToolExecutor
from kollabor_events import EventBus

bus = EventBus()
mcp = MCPIntegration(event_bus=bus)
executor = ToolExecutor(mcp_integration=mcp, event_bus=bus)

result = await executor.execute_tool({
    "id": "tool_1",
    "type": "terminal",
    "command": "pwd",
})

print(result.success, result.output)
```

## Known Gaps

- Tool execution depends on caller-provided context for workspace/cwd behavior;
  service callers must wire project boundaries explicitly until the runtime has
  a stronger workspace object.
- MCP session connect behavior is mostly implemented through internal helpers;
  a smaller public connection API would reduce route-level coupling.
- Permission scope, bundle scope, and tool registry behavior are powerful but
  spread across several modules; more contract tests would make changes safer.
- Some diagnostics and legacy compatibility paths still live inside the runtime
  and should be made quieter or moved behind debug flags.

## Roadmap

### Phase 1: Execution boundaries

- Add a first-class workspace/project execution context used by shell and file
  operations.
- Expose a public MCP connect/disconnect/list-tools API for service callers.
- Tighten cancellation behavior across shell, MCP, background, and plugin tools.

### Phase 2: Tool contract stabilization

- Keep the unified tool registry as the canonical source for schemas,
  permissions, bundle scope, and prompt rendering.
- Add regression tests for native JSON, XML, and markdown tool generation.
- Document exact tool result metadata expected by context-service and display
  layers.

### Phase 3: Agent runtime maturity

- Clarify which runtime pieces are reusable library APIs versus CLI orchestration
  internals.
- Harden process cleanup, circuit-breaker behavior, and background task
  reporting.
- Expand agent/skill loading tests across project, user, and bundled sources.

## Development

Targeted validation examples:

```bash
python -m py_compile packages/kollabor-agent/src/kollabor_agent/*.py
python -m pytest tests/unit/mcp tests/unit/test_auto_grant_mcp_tools.py -q
```

## Dependencies

- `kollabor-events`
- `kollabor-config`
- `kollabor-ai`
- `pyyaml`

## License

MIT
