oct.mcp.executor module

oct.mcp.executor module#

Purpose#

Tool Executor (Layer 4, inner logic) for the oct-mcp six-layer pipeline. Maps validated tool arguments to oct CLI argv lists and delegates execution to oct.mcp.sandbox.SandboxExecutor.

Responsibilities#

  • Provide one _build_argv_<tool>() function per Phase 5A tool that converts a validated Pydantic model to an ["oct", subcommand, ...] argv list.

  • Provide ToolExecutor which wires together the Pydantic model dict and the sandbox.

  • Never import oct internals directly — always call the oct CLI as a subprocess (blueprint §5.5 isolation principle, design decision D3).

Diagnostics#

Domain: MCP Levels:

L2 — lifecycle: tool execution L3 — argv details L4 — deep trace

Contracts#

  • This module does not import click or the MCP SDK.

  • _build_argv_*() functions accept a dict (from model.model_dump()) and return a list[str]. They never raise for valid validated input.

  • ToolExecutor.execute() never raises — it returns SandboxResult directly from the sandbox.

class oct.mcp.executor.ToolExecutor(sandbox: SandboxExecutor | None = None, timeout_default: int = 60, timeout_test: int = 300, max_output_bytes: int = 1048576)[source]#

Bases: object

Maps MCP tool names and validated args to sandboxed oct calls.

Parameters:

  • sandbox – SandboxExecutor instance (injected so tests can substitute a mock).

  • timeout_default – Default subprocess timeout in seconds.

  • timeout_test – Override timeout for oct_test (pytest may need more time).

  • max_output_bytes – Hard cap on combined stdout+stderr passed to the sandbox.

execute(tool_name: str, validated_args: dict, project_root: Path) → SandboxResult[source]#

Execute tool_name with validated_args inside the sandbox.

Parameters:

  • tool_name – One of the 9 Phase 5A tool names.

  • validated_args – A model_dump() dict from the corresponding Pydantic model.

  • project_root – Absolute project root path (used as subprocess cwd and forwarded to the argv builder).

Return type:

SandboxResult — never raises.

execute_write(tool_name: str, validated_args: dict, project_root: Path, dry_run_override: bool = False) → SandboxResult[source]#

Execute a write tool, injecting the safety-gate dry-run decision.

Parameters:

  • tool_name – One of the 11 Phase 5B write tool names.

  • validated_args – A model_dump() dict from the corresponding Pydantic model.

  • project_root – Absolute project root path.

  • dry_run_override – When True (as determined by SafetyGate), injects _dry_run_override=True into the args dict so that _build_argv_format always passes --dry-run regardless of the apply field value.