kollabor-agent 0.5.7

Agent execution toolkit - tool execution, MCP integration, file operations, and shell commands

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

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:

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