@tt-a1i/mco 0.1.2

package/README.md

@@ -0,0 +1,190 @@
+# MCO Docs Index
+
+## Read First
+1. [multi-cli-orchestrator-proposal.md](./multi-cli-orchestrator-proposal.md)
+2. [capability-research.md](./capability-research.md)
+3. [notes.md](./notes.md)
+
+## Gate Artifacts
+1. [capability-probe-spec.md](./capability-probe-spec.md)
+2. [adapter-contract-tests.md](./adapter-contract-tests.md)
+3. [dry-run-plan.md](./dry-run-plan.md)
+4. [implementation-gate-checklist.md](./implementation-gate-checklist.md)
+
+## Implementation Freeze
+1. [docs/implementation/step0-interface-freeze.md](./docs/implementation/step0-interface-freeze.md)
+2. [docs/contracts/cli-json-v0.1.x.md](./docs/contracts/cli-json-v0.1.x.md)
+3. [docs/contracts/provider-permissions-v0.1.x.md](./docs/contracts/provider-permissions-v0.1.x.md)
+
+## Planning and Tracking
+1. [task_plan.md](./task_plan.md)
+
+## Release Notes
+1. [docs/releases/v0.1.2.md](./docs/releases/v0.1.2.md)
+2. [docs/releases/v0.1.2.zh-CN.md](./docs/releases/v0.1.2.zh-CN.md)
+3. [docs/releases/v0.1.1.md](./docs/releases/v0.1.1.md)
+4. [docs/releases/v0.1.1.zh-CN.md](./docs/releases/v0.1.1.zh-CN.md)
+5. [docs/releases/v0.1.0.md](./docs/releases/v0.1.0.md)
+6. [docs/releases/v0.1.0.zh-CN.md](./docs/releases/v0.1.0.zh-CN.md)
+
+## Unified CLI (Step 2)
+`mco review` is the unified entrypoint for running a review task.
+
+`mco run` is the generalized execution entrypoint for agent-style task orchestration (no forced findings schema).
+
+## Installation
+
+Python package (recommended):
+
+```bash
+pipx install mco
+mco --help
+```
+
+Install from source (editable):
+
+```bash
+git clone https://github.com/tt-a1i/mco.git
+cd mco
+python3 -m pip install -e .
+mco --help
+```
+
+NPM wrapper (Python 3 required on PATH):
+
+```bash
+npm i -g @tt-a1i/mco
+mco --help
+```
+
+Quick start:
+```bash
+./mco review \
+  --repo . \
+  --prompt "Review this repository for high-risk bugs and security issues." \
+  --providers claude,codex
+```
+
+Machine-readable output:
+```bash
+./mco review --repo . --prompt "Review for bugs." --providers claude,codex --json
+```
+
+Stdout-only result mode (for caller rendering, no `summary.md/decision.md/findings.json/run.json` write):
+```bash
+./mco review --repo . --prompt "Review for bugs." --providers claude,codex --result-mode stdout --json
+```
+
+General run mode:
+```bash
+./mco run --repo . --prompt "Summarize the current repo architecture." --providers claude,codex --json
+```
+
+Config file (JSON):
+```json
+{
+  "providers": ["claude", "codex"],
+  "artifact_base": "reports/review",
+  "state_file": ".mco/state.json",
+  "policy": {
+    "timeout_seconds": 180,
+    "stall_timeout_seconds": 900,
+    "poll_interval_seconds": 1.0,
+    "review_hard_timeout_seconds": 1800,
+    "enforce_findings_contract": false,
+    "max_retries": 1,
+    "high_escalation_threshold": 1,
+    "require_non_empty_findings": true,
+    "max_provider_parallelism": 0,
+    "allow_paths": [".", "runtime", "scripts"],
+    "enforcement_mode": "strict",
+    "provider_permissions": {
+      "claude": {
+        "permission_mode": "plan"
+      },
+      "codex": {
+        "sandbox": "workspace-write"
+      }
+    },
+    "provider_timeouts": {
+      "claude": 300,
+      "codex": 240,
+      "qwen": 240
+    }
+  }
+}
+```
+
+Run with config:
+```bash
+./mco review --config ./mco.example.json --repo . --prompt "Review for bugs and security issues."
+```
+
+Override fan-out and per-provider timeout from CLI:
+```bash
+./mco review \
+  --repo . \
+  --prompt "Review for bugs and security issues." \
+  --providers claude,codex,gemini,opencode,qwen \
+  --strict-contract \
+  --max-provider-parallelism 2 \
+  --stall-timeout 900 \
+  --review-hard-timeout 1800 \
+  --provider-timeouts qwen=900,codex=900
+```
+
+Run mode with hard path constraints:
+```bash
+./mco run \
+  --repo . \
+  --prompt "Compare adapter behaviors and return a short markdown summary." \
+  --providers claude,codex \
+  --allow-paths runtime,scripts \
+  --target-paths runtime/adapters,runtime/review_engine.py \
+  --enforcement-mode strict \
+  --provider-permissions-json '{"codex":{"sandbox":"workspace-write"},"claude":{"permission_mode":"plan"}}' \
+  --json
+```
+
+Artifacts are written to:
+- `<artifact_base>/<task_id>/summary.md`
+- `<artifact_base>/<task_id>/decision.md`
+- `<artifact_base>/<task_id>/findings.json`
+- `<artifact_base>/<task_id>/run.json`
+- `<artifact_base>/<task_id>/providers/*.json`
+- `<artifact_base>/<task_id>/raw/*.log`
+
+`run.json` includes audit fields for reproducibility:
+- `effective_cwd`
+- `allow_paths_hash`
+- `permissions_hash`
+
+Notes:
+- YAML config requires `pyyaml` installed; otherwise use JSON config.
+- Review prompt is wrapped with a JSON finding contract, but strict parse enforcement is optional.
+- Enable strict gate behavior with `--strict-contract` (or `policy.enforce_findings_contract=true` in config).
+- `run` mode does not force findings schema; it focuses on execution aggregation and provider success.
+- `result_mode=artifact` (default): write user-facing artifacts and print compact result.
+- `result_mode=stdout`: print provider-level result payload to stdout, skip user-facing artifact files.
+- `result_mode=both`: write artifacts and print provider-level payload.
+- Execution model is `wait-all`: one provider timeout/failure does not stop others.
+- Timeout behavior is progress-driven:
+  - `stall_timeout_seconds`: cancel only when output progress is idle beyond threshold.
+  - `review_hard_timeout_seconds`: hard deadline applied only in `review` mode.
+- `max_provider_parallelism=0` (or omitted) means full parallelism across selected providers.
+- `provider_timeouts` are provider-specific stall-timeout overrides.
+- `allow_paths` and `target_paths` are validated against `repo_root`; path escape is rejected.
+- `enforcement_mode=strict` (default) fails closed when provider permission requirements cannot be honored.
+
+## Step5 Benchmark Script
+Use this script to generate serial vs full-parallel evidence and write reports under `reports/adapter-contract/<date>/`:
+
+```bash
+./scripts/run_step5_parallel_benchmark.sh
+```
+
+The generated summary JSON includes separated parse-vs-findings metrics:
+- `providers_total`
+- `parse_success_rate`
+- `effective_findings_count`
+- `zero_finding_provider_count`

package/bin/mco.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("node:child_process");
+const { resolve } = require("node:path");
+
+const scriptPath = resolve(__dirname, "..", "mco");
+const args = process.argv.slice(2);
+
+const result = spawnSync("python3", [scriptPath, ...args], {
+  stdio: "inherit",
+});
+
+if (result.error) {
+  console.error(`Failed to run python3: ${result.error.message}`);
+  process.exit(1);
+}
+
+process.exit(result.status === null ? 1 : result.status);
+

package/mco

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT_DIR = Path(__file__).resolve().parent
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from runtime.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@tt-a1i/mco",
+  "version": "0.1.2",
+  "description": "Node wrapper for the mco CLI (Python runtime required).",
+  "license": "UNLICENSED",
+  "bin": {
+    "mco": "bin/mco.js"
+  },
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node -e \"console.log('No JS tests. Use Python test suite.')\""
+  },
+  "files": [
+    "bin/mco.js",
+    "mco",
+    "runtime"
+  ]
+}

package/runtime/__init__.py

@@ -0,0 +1,8 @@
+"""Runtime package for orchestrator gate implementation."""
+
+from .artifacts import ARTIFACT_LAYOUT_VERSION
+from .types import RUN_RESULT_SCHEMA_VERSION
+
+__version__ = "0.1.2"
+
+__all__ = ["ARTIFACT_LAYOUT_VERSION", "RUN_RESULT_SCHEMA_VERSION", "__version__"]

package/runtime/adapters/__init__.py

@@ -0,0 +1,7 @@
+from .claude import ClaudeAdapter
+from .codex import CodexAdapter
+from .gemini import GeminiAdapter
+from .opencode import OpenCodeAdapter
+from .qwen import QwenAdapter
+
+__all__ = ["ClaudeAdapter", "CodexAdapter", "GeminiAdapter", "OpenCodeAdapter", "QwenAdapter"]

package/runtime/adapters/claude.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import Any, List
+
+from ..contracts import CapabilitySet, NormalizeContext, NormalizedFinding, TaskInput
+from .parsing import normalize_findings_from_text
+from .shim import ShimAdapterBase
+
+
+class ClaudeAdapter(ShimAdapterBase):
+    def __init__(self) -> None:
+        super().__init__(
+            provider_id="claude",
+            binary_name="claude",
+            capability_set=CapabilitySet(
+                tiers=["C0", "C1", "C2", "C3", "C4", "C5", "C6"],
+                supports_native_async=False,
+                supports_poll_endpoint=False,
+                supports_resume_after_restart=True,
+                supports_schema_enforcement=True,
+                min_supported_version="2.1.59",
+                tested_os=["macos"],
+            ),
+        )
+
+    def _auth_check_command(self, binary: str) -> List[str]:
+        return [binary, "auth", "status"]
+
+    def supported_permission_keys(self) -> List[str]:
+        return ["permission_mode"]
+
+    def _build_command(self, input_task: TaskInput) -> List[str]:
+        permission_mode = "plan"
+        raw_permissions = input_task.metadata.get("provider_permissions")
+        if isinstance(raw_permissions, dict):
+            value = raw_permissions.get("permission_mode")
+            if isinstance(value, str) and value.strip():
+                permission_mode = value.strip()
+        return [
+            "claude",
+            "-p",
+            "--permission-mode",
+            permission_mode,
+            "--output-format",
+            "text",
+            input_task.prompt,
+        ]
+
+    def _build_command_for_record(self) -> List[str]:
+        return ["claude", "-p", "--permission-mode", "plan", "--output-format", "text", "<prompt>"]
+
+    def _is_success(self, return_code: int, stdout_text: str, stderr_text: str) -> bool:
+        if return_code != 0:
+            return False
+        text = f"{stdout_text}\n{stderr_text}".lower()
+        return "api error" not in text
+
+    def normalize(self, raw: Any, ctx: NormalizeContext) -> List[NormalizedFinding]:
+        text = raw if isinstance(raw, str) else ""
+        return normalize_findings_from_text(text, ctx, "claude")

package/runtime/adapters/codex.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import Any, List
+
+from ..contracts import CapabilitySet, NormalizeContext, NormalizedFinding, TaskInput
+from .parsing import normalize_findings_from_text
+from .shim import ShimAdapterBase
+
+
+class CodexAdapter(ShimAdapterBase):
+    def __init__(self) -> None:
+        super().__init__(
+            provider_id="codex",
+            binary_name="codex",
+            capability_set=CapabilitySet(
+                tiers=["C0", "C1", "C2", "C3", "C4", "C5"],
+                supports_native_async=False,
+                supports_poll_endpoint=False,
+                supports_resume_after_restart=True,
+                supports_schema_enforcement=True,
+                min_supported_version="0.46.0",
+                tested_os=["macos"],
+            ),
+        )
+
+    def _auth_check_command(self, binary: str) -> List[str]:
+        return [binary, "login", "status"]
+
+    def supported_permission_keys(self) -> List[str]:
+        return ["sandbox"]
+
+    def _build_command(self, input_task: TaskInput) -> List[str]:
+        sandbox = "workspace-write"
+        raw_permissions = input_task.metadata.get("provider_permissions")
+        if isinstance(raw_permissions, dict):
+            value = raw_permissions.get("sandbox")
+            if isinstance(value, str) and value.strip():
+                sandbox = value.strip()
+        cmd = [
+            "codex",
+            "exec",
+            "--skip-git-repo-check",
+            "-C",
+            input_task.repo_root,
+            "--sandbox",
+            sandbox,
+            "--json",
+        ]
+        output_schema_path = input_task.metadata.get("output_schema_path")
+        if isinstance(output_schema_path, str) and output_schema_path.strip():
+            cmd.extend(["--output-schema", output_schema_path.strip()])
+        cmd.append(input_task.prompt)
+        return cmd
+
+    def _build_command_for_record(self) -> List[str]:
+        return [
+            "codex",
+            "exec",
+            "--skip-git-repo-check",
+            "-C",
+            "<repo_root>",
+            "--sandbox",
+            "workspace-write",
+            "--json",
+            "--output-schema",
+            "<schema-path>",
+            "<prompt>",
+        ]
+
+    def _is_success(self, return_code: int, stdout_text: str, stderr_text: str) -> bool:
+        if return_code == 0:
+            return True
+        # Codex may emit MCP startup errors and still return useful JSON events.
+        if stdout_text.strip() and "\"type\":\"turn.completed\"" in stdout_text:
+            return True
+        if stdout_text.strip() and "\"ok\":true" in stdout_text:
+            return True
+        if "mcp client" in stderr_text.lower() and stdout_text.strip():
+            return True
+        return False
+
+    def normalize(self, raw: Any, ctx: NormalizeContext) -> List[NormalizedFinding]:
+        text = raw if isinstance(raw, str) else ""
+        return normalize_findings_from_text(text, ctx, "codex")

package/runtime/adapters/gemini.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Any, List
+
+from ..contracts import CapabilitySet, NormalizeContext, NormalizedFinding, TaskInput
+from .parsing import normalize_findings_from_text
+from .shim import ShimAdapterBase
+
+
+class GeminiAdapter(ShimAdapterBase):
+    def __init__(self) -> None:
+        super().__init__(
+            provider_id="gemini",
+            binary_name="gemini",
+            capability_set=CapabilitySet(
+                tiers=["C0", "C1", "C2", "C3"],
+                supports_native_async=False,
+                supports_poll_endpoint=False,
+                supports_resume_after_restart=False,
+                supports_schema_enforcement=False,
+                min_supported_version="0.1.7",
+                tested_os=["macos"],
+            ),
+        )
+
+    def _auth_check_command(self, binary: str) -> List[str]:
+        return [binary, "-p", "Reply with exactly OK"]
+
+    def _build_command(self, input_task: TaskInput) -> List[str]:
+        return ["gemini", "-p", input_task.prompt]
+
+    def _build_command_for_record(self) -> List[str]:
+        return ["gemini", "-p", "<prompt>"]
+
+    def _is_success(self, return_code: int, stdout_text: str, stderr_text: str) -> bool:
+        if return_code != 0:
+            return False
+        text = f"{stdout_text}\n{stderr_text}".lower()
+        if "unknown arguments" in text:
+            return False
+        if "api error" in text:
+            return False
+        return True
+
+    def normalize(self, raw: Any, ctx: NormalizeContext) -> List[NormalizedFinding]:
+        text = raw if isinstance(raw, str) else ""
+        return normalize_findings_from_text(text, ctx, "gemini")
+

package/runtime/adapters/opencode.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any, List
+
+from ..contracts import CapabilitySet, NormalizeContext, NormalizedFinding, TaskInput
+from .parsing import normalize_findings_from_text
+from .shim import ShimAdapterBase
+
+
+class OpenCodeAdapter(ShimAdapterBase):
+    def __init__(self) -> None:
+        super().__init__(
+            provider_id="opencode",
+            binary_name="opencode",
+            capability_set=CapabilitySet(
+                tiers=["C0", "C1", "C2", "C3", "C4"],
+                supports_native_async=True,
+                supports_poll_endpoint=True,
+                supports_resume_after_restart=True,
+                supports_schema_enforcement=False,
+                min_supported_version="1.2.11",
+                tested_os=["macos"],
+            ),
+        )
+
+    def _auth_check_command(self, binary: str) -> List[str]:
+        return [binary, "auth", "list"]
+
+    def _build_command(self, input_task: TaskInput) -> List[str]:
+        return ["opencode", "run", input_task.prompt, "--format", "json"]
+
+    def _build_command_for_record(self) -> List[str]:
+        return ["opencode", "run", "<prompt>", "--format", "json"]
+
+    def normalize(self, raw: Any, ctx: NormalizeContext) -> List[NormalizedFinding]:
+        text = raw if isinstance(raw, str) else ""
+        return normalize_findings_from_text(text, ctx, "opencode")
+