@tt-a1i/mco 0.1.2 → 0.1.3

package/README.md

@@ -1,5 +1,7 @@
 # MCO Docs Index
 
+English | [简体中文](./README.zh-CN.md)
+
 ## Read First
 1. [multi-cli-orchestrator-proposal.md](./multi-cli-orchestrator-proposal.md)
 2. [capability-research.md](./capability-research.md)
@@ -34,10 +36,10 @@
 
 ## Installation
 
-Python package (recommended):
+NPM wrapper (available now, Python 3 required on PATH):
 
 ```bash
-pipx install mco
+npm i -g @tt-a1i/mco
 mco --help
 ```
 
@@ -50,12 +52,9 @@ python3 -m pip install -e .
 mco --help
 ```
 
-NPM wrapper (Python 3 required on PATH):
-
-```bash
-npm i -g @tt-a1i/mco
-mco --help
-```
+Python package via PyPI:
+- Not published yet.
+- Publish workflow is ready and will be enabled after PyPI Trusted Publisher setup.
 
 Quick start:
 ```bash

package/README.zh-CN.md

@@ -0,0 +1,196 @@
+# MCO 文档索引
+
+[English](./README.md) | 简体中文
+
+## 先读这些
+1. [multi-cli-orchestrator-proposal.md](./multi-cli-orchestrator-proposal.md)
+2. [capability-research.md](./capability-research.md)
+3. [notes.md](./notes.md)
+
+## 门禁产物
+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)
+
+## 接口冻结
+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)
+
+## 计划与跟踪
+1. [task_plan.md](./task_plan.md)
+
+## 发布说明
+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)
+
+## 统一 CLI（Step 2）
+`mco review`：统一的审查入口。  
+`mco run`：通用任务执行入口（不强制 findings schema）。
+
+## 安装
+
+npm 包装器（当前可用，系统需有 Python 3）：
+
+```bash
+npm i -g @tt-a1i/mco
+mco --help
+```
+
+源码可编辑安装：
+
+```bash
+git clone https://github.com/tt-a1i/mco.git
+cd mco
+python3 -m pip install -e .
+mco --help
+```
+
+Python 包（PyPI）：
+- 目前尚未发布。
+- 发布流程已就绪，待完成 PyPI Trusted Publisher 配置后开启。
+
+快速开始：
+
+```bash
+./mco review \
+  --repo . \
+  --prompt "Review this repository for high-risk bugs and security issues." \
+  --providers claude,codex
+```
+
+机器可读输出：
+
+```bash
+./mco review --repo . --prompt "Review for bugs." --providers claude,codex --json
+```
+
+仅 stdout 输出结果（不写 `summary.md/decision.md/findings.json/run.json`）：
+
+```bash
+./mco review --repo . --prompt "Review for bugs." --providers claude,codex --result-mode stdout --json
+```
+
+通用 run 模式：
+
+```bash
+./mco run --repo . --prompt "Summarize the current repo architecture." --providers claude,codex --json
+```
+
+配置文件（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
+    }
+  }
+}
+```
+
+按配置运行：
+
+```bash
+./mco review --config ./mco.example.json --repo . --prompt "Review for bugs and security issues."
+```
+
+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 模式：
+
+```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
+```
+
+产物目录：
+- `<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` 审计字段：
+- `effective_cwd`
+- `allow_paths_hash`
+- `permissions_hash`
+
+说明：
+- YAML 配置需要 `pyyaml`；否则使用 JSON 配置。
+- review 提示词会附加 JSON finding 合同；是否强制由策略控制。
+- 可用 `--strict-contract`（或配置 `policy.enforce_findings_contract=true`）开启严格合同。
+- `run` 模式不强制 findings schema，聚焦执行与聚合。
+- `result_mode=artifact`（默认）：写产物并输出简报。
+- `result_mode=stdout`：输出 provider 结果，不写用户侧产物。
+- `result_mode=both`：既写产物又输出 provider 结果。
+- 执行模型为 `wait-all`：单 provider 失败/超时不会中断其它 provider。
+- 超时是进度驱动：
+  - `stall_timeout_seconds`：仅在长时间无输出进展时取消。
+  - `review_hard_timeout_seconds`：仅 `review` 模式硬截止。
+- `max_provider_parallelism=0`（或省略）表示全并行。
+- `provider_timeouts` 为 provider 级 stall-timeout 覆盖项。
+- `allow_paths` 与 `target_paths` 会对 `repo_root` 做越界校验。
+- `enforcement_mode=strict`（默认）下，权限要求不满足会 fail-closed。
+
+## Step5 性能脚本
+用于产出串行 vs 全并行对比报告（写入 `reports/adapter-contract/<date>/`）：
+
+```bash
+./scripts/run_step5_parallel_benchmark.sh
+```
+
+生成的 summary JSON 包含：
+- `providers_total`
+- `parse_success_rate`
+- `effective_findings_count`
+- `zero_finding_provider_count`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tt-a1i/mco",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Node wrapper for the mco CLI (Python runtime required).",
   "license": "UNLICENSED",
   "bin": {

package/runtime/adapters/shim.py

@@ -40,6 +40,19 @@ class ShimRunHandle:
     stderr_file: TextIO
 
 
+_ENV_VARS_TO_STRIP = (
+    "CLAUDECODE",
+)
+
+
+def _sanitize_env() -> Dict[str, str]:
+    """Return a copy of os.environ with known conflicting variables removed."""
+    env = os.environ.copy()
+    for key in _ENV_VARS_TO_STRIP:
+        env.pop(key, None)
+    return env
+
+
 class ShimAdapterBase:
     id: ProviderId
 
@@ -104,6 +117,7 @@ class ShimAdapterBase:
             stderr=stderr_file,
             text=True,
             start_new_session=True,
+            env=_sanitize_env(),
         )
         self._runs[run_id] = ShimRunHandle(
             process=process,
@@ -123,6 +137,17 @@ class ShimAdapterBase:
             session_id=None,
         )
 
+    @staticmethod
+    def _close_io(handle: ShimRunHandle) -> None:
+        try:
+            handle.stdout_file.close()
+        except Exception:
+            pass
+        try:
+            handle.stderr_file.close()
+        except Exception:
+            pass
+
     def poll(self, ref: TaskRunRef) -> TaskStatus:
         handle = self._runs.get(ref.run_id)
         if handle is None:
@@ -154,11 +179,7 @@ class ShimAdapterBase:
                 message="running",
             )
 
-        try:
-            handle.stdout_file.close()
-            handle.stderr_file.close()
-        except Exception:
-            pass
+        self._close_io(handle)
 
         stdout_text = handle.stdout_path.read_text(encoding="utf-8") if handle.stdout_path.exists() else ""
         stderr_text = handle.stderr_path.read_text(encoding="utf-8") if handle.stderr_path.exists() else ""
@@ -182,6 +203,7 @@ class ShimAdapterBase:
             "stderr_path": str(handle.stderr_path),
         }
         handle.provider_result_path.write_text(json.dumps(payload, ensure_ascii=True, indent=2), encoding="utf-8")
+        self._runs.pop(ref.run_id, None)
 
         return TaskStatus(
             task_id=ref.task_id,
@@ -201,17 +223,27 @@ class ShimAdapterBase:
         if handle is None:
             return
         if handle.process.poll() is not None:
+            self._close_io(handle)
+            self._runs.pop(ref.run_id, None)
             return
         try:
             os.killpg(os.getpgid(handle.process.pid), signal.SIGTERM)
         except ProcessLookupError:
+            self._close_io(handle)
+            self._runs.pop(ref.run_id, None)
             return
         time.sleep(0.2)
         if handle.process.poll() is None:
             try:
                 os.killpg(os.getpgid(handle.process.pid), signal.SIGKILL)
             except ProcessLookupError:
+                self._close_io(handle)
+                self._runs.pop(ref.run_id, None)
                 return
+            time.sleep(0.1)
+        if handle.process.poll() is not None:
+            self._close_io(handle)
+            self._runs.pop(ref.run_id, None)
 
     def normalize(self, raw: object, ctx: NormalizeContext) -> List[NormalizedFinding]:
         raise NotImplementedError

package/runtime/cli.py

@@ -75,18 +75,20 @@ def _parse_provider_timeouts(raw: str) -> Dict[str, int]:
         return result
     for chunk in raw.split(","):
         pair = chunk.strip()
-        if not pair or "=" not in pair:
+        if not pair:
             continue
+        if "=" not in pair:
+            raise ValueError(f"invalid provider timeout entry: {pair}")
         provider, timeout_text = pair.split("=", 1)
         provider_name = provider.strip()
         if not provider_name:
-            continue
+            raise ValueError(f"invalid provider timeout entry: {pair}")
         try:
             timeout = int(timeout_text.strip())
         except Exception:
-            continue
+            raise ValueError(f"invalid timeout value for provider '{provider_name}': {timeout_text.strip()}") from None
         if timeout <= 0:
-            continue
+            raise ValueError(f"timeout must be > 0 for provider '{provider_name}'")
         result[provider_name] = timeout
     return result
 
@@ -102,23 +104,24 @@ def _parse_provider_permissions_json(raw: str) -> Dict[str, Dict[str, str]]:
     try:
         payload = json.loads(raw)
     except Exception:
-        return {}
+        raise ValueError("--provider-permissions-json must be valid JSON") from None
     if not isinstance(payload, dict):
-        return {}
+        raise ValueError("--provider-permissions-json root must be an object")
 
     result: Dict[str, Dict[str, str]] = {}
     for provider, permissions in payload.items():
         provider_name = str(provider).strip()
-        if not provider_name or not isinstance(permissions, dict):
-            continue
+        if not provider_name:
+            raise ValueError("--provider-permissions-json contains empty provider name")
+        if not isinstance(permissions, dict):
+            raise ValueError(f"permissions for provider '{provider_name}' must be an object")
         normalized: Dict[str, str] = {}
         for key, value in permissions.items():
             key_name = str(key).strip()
             if not key_name:
-                continue
+                raise ValueError(f"provider '{provider_name}' contains empty permission key")
             normalized[key_name] = str(value)
-        if normalized:
-            result[provider_name] = normalized
+        result[provider_name] = normalized
     return result
 
 
@@ -263,7 +266,11 @@ def main(argv: List[str] | None = None) -> int:
         parser.error("unsupported command")
         return 2
 
-    cfg = _resolve_config(args)
+    try:
+        cfg = _resolve_config(args)
+    except (FileNotFoundError, RuntimeError, ValueError) as exc:
+        print(f"Configuration error: {exc}", file=sys.stderr)
+        return 2
     repo_root = str(Path(args.repo).resolve())
     providers = [item for item in cfg.providers if item in ("claude", "codex", "gemini", "opencode", "qwen")]
     if not providers:
@@ -283,7 +290,11 @@ def main(argv: List[str] | None = None) -> int:
     )
     review_mode = args.command == "review"
     write_artifacts = args.result_mode in ("artifact", "both")
-    result = run_review(req, review_mode=review_mode, write_artifacts=write_artifacts)
+    try:
+        result = run_review(req, review_mode=review_mode, write_artifacts=write_artifacts)
+    except ValueError as exc:
+        print(f"Input error: {exc}", file=sys.stderr)
+        return 2
 
     payload = {
         "command": args.command,

package/runtime/orchestrator.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import threading
+import time
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Callable, Dict, List, Optional, Set, Tuple
@@ -50,8 +51,14 @@ class TaskStateMachine:
 
 
 class OrchestratorRuntime:
-    def __init__(self, retry_policy: Optional[RetryPolicy] = None, state_file: Optional[str] = None) -> None:
+    def __init__(
+        self,
+        retry_policy: Optional[RetryPolicy] = None,
+        state_file: Optional[str] = None,
+        sleep_fn: Optional[Callable[[float], None]] = None,
+    ) -> None:
         self.retry_policy = retry_policy or RetryPolicy()
+        self.sleep_fn = sleep_fn or time.sleep
         self.dispatch_cache: Dict[str, RunResult] = {}
         self.idempotency_index: Dict[str, str] = {}
         self.sent_notifications: Set[Tuple[str, str, str]] = set()
@@ -205,7 +212,9 @@ class OrchestratorRuntime:
                 return final
 
             retry_index = attempts
-            delays.append(self.retry_policy.compute_delay(retry_index))
+            delay_seconds = self.retry_policy.compute_delay(retry_index)
+            delays.append(delay_seconds)
+            self.sleep_fn(delay_seconds)
 
     def send_terminal_notification(self, task_id: str, state: TaskState, channel: str) -> bool:
         with self._lock:

package/runtime/schemas/review_findings.schema.json

@@ -53,8 +53,6 @@
             "additionalProperties": true,
             "required": [
               "file",
-              "line",
-              "symbol",
               "snippet"
             ],
             "properties": {