ymai-codeflow 0.0.0-stage → 0.3.30

package/bin/cli.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+'use strict';
+// Launcher: delegates to the bundled Python executor runtime (stdlib-only, Python 3.11+).
+const { spawn } = require('child_process');
+const path = require('path');
+
+const packageRoot = path.join(__dirname, '..');
+const runtimeDir = path.join(packageRoot, 'runtime');
+const args = process.argv.slice(2);
+const known = new Set(['connect', '--once-smoke', '--check-config', '--help']);
+if (args.length === 0 || !known.has(args[0])) {
+  console.error('Usage: ymai-codeflow connect --ws-url <url> --token <token> --executor-id <id> [--provider claude] [--memory-mode platform] [--max-tasks N]');
+  console.error('       ymai-codeflow --check-config | --once-smoke | --help');
+  console.error('Requires Python 3.11+ on the target machine.');
+  process.exit(args.length === 0 ? 2 : 1);
+}
+
+const pythonCandidates = process.env.AINATIVE_PYTHON
+  ? [process.env.AINATIVE_PYTHON]
+  : ['python3', 'python3.11', 'python'];
+
+let child;
+(function tryNext(i) {
+  if (i >= pythonCandidates.length) {
+    console.error('Python 3.11+ not found. Install Python 3.11+ or set AINATIVE_PYTHON=/path/to/python3.');
+    process.exit(1);
+  }
+  const py = pythonCandidates[i];
+  child = spawn(py, ['-m', 'runtime.daemon', ...args], {
+    cwd: packageRoot,
+    stdio: 'inherit',
+    env: process.env,
+  });
+  child.on('error', (err) => {
+    if (err.code === 'ENOENT') { tryNext(i + 1); return; }
+    console.error(err.message);
+    process.exit(1);
+  });
+  child.on('exit', (code2) => process.exit(code2 ?? 0));
+})(0);

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "ymai-codeflow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.30",
+  "description": "CodeFlow executor runtime launcher — connects AI worker daemons to the CodeFlow platform (Python 3.11+ required).",
+  "bin": {
+    "ymai-codeflow": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "runtime/"
+  ],
+  "keywords": ["codeflow", "executor", "agent", "ai", "delivery"],
+  "license": "Apache-2.0",
+  "engines": { "node": ">=16" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qsumm/CodeFlow.git"
+  }
+}

package/runtime/chain.py

@@ -0,0 +1,162 @@
+"""跨角色接棒:经平台 REST API(架构许可通道,见 SdlcDriver javadoc / docs/10 v2)。
+
+配置(runtime.env):
+  RUNTIME_HANDOFF_AGENT_ID   下一角色 agentId(必填才启用接棒)
+  AINATIVE_API_BASE_URL    默认 http://localhost:7001
+  AINATIVE_WORKSPACE_ID    工作空间 ID
+  AINATIVE_REFRESH_TOKEN   平台 refresh token(401 时自动换取新 access token)
+  AINATIVE_ACCESS_TOKEN    当前 access token(可选,建议给 refresh token 即可)
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+
+_state = {"access": None, "refresh": None, "base": None, "ws": None}
+
+
+def _put(path: str, body: dict, token: str | None = None) -> dict:
+    req = urllib.request.Request(_state["base"] + path, method="PUT",
+                                 data=json.dumps(body).encode())
+    req.add_header("Content-Type", "application/json")
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+    with urllib.request.urlopen(req, timeout=15) as r:
+        return json.loads(r.read())
+
+
+def _post(path: str, body: dict, token: str | None = None) -> dict:
+    req = urllib.request.Request(_state["base"] + path, method="POST",
+                                 data=json.dumps(body).encode())
+    req.add_header("Content-Type", "application/json")
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+    with urllib.request.urlopen(req, timeout=15) as r:
+        return json.loads(r.read())
+
+
+def _ensure_token(cfg) -> str:
+    if _state["access"] is None:
+        _state["access"] = cfg.extra_env.get("AINATIVE_ACCESS_TOKEN") or None
+        _state["refresh"] = cfg.extra_env.get("AINATIVE_REFRESH_TOKEN")
+        _state["base"] = cfg.extra_env.get("AINATIVE_API_BASE_URL", "http://localhost:7001")
+    if _state["access"] is None and _state["refresh"]:
+        d = _post("/api/auth/refresh", {"refreshToken": _state["refresh"],
+                                        "workspaceId": int(cfg.extra_env.get("AINATIVE_WORKSPACE_ID", 0))})["data"]
+        _state["access"] = d["accessToken"]
+    if _state["access"] is None:
+        raise RuntimeError("no API token: set AINATIVE_ACCESS_TOKEN/REFRESH_TOKEN")
+    return _state["access"]
+
+
+def _switch_workspace_token(cfg) -> str | None:
+    """把平台级令牌换成工作区级令牌(DEF-028)。
+
+    平台登录返回的 access token 是"平台级"的,直接调 /api/workitems/{id} 会被拒
+    (HTTP 403,code 11001「非该工作空间成员」)。工作区级令牌需先调用
+    POST /api/workspaces/{id}/switch 换取。
+    """
+    ws = cfg.extra_env.get("AINATIVE_WORKSPACE_ID")
+    if not ws:
+        return None
+    base = _state["base"]
+    current = _state["access"] or _state["refresh"]
+    req = urllib.request.Request(f"{base}/api/workspaces/{int(ws)}/switch", method="POST",
+                                 data=b"{}")
+    req.add_header("Content-Type", "application/json")
+    if current:
+        req.add_header("Authorization", f"Bearer {current}")
+    with urllib.request.urlopen(req, timeout=15) as r:
+        data = json.loads(r.read()).get("data") or {}
+    token = data.get("accessToken")
+    if token:
+        _state["access"] = token
+    return token
+
+
+def _with_refresh_retry(cfg, fn):
+    try:
+        return fn(_ensure_token(cfg))
+    except urllib.error.HTTPError as e:
+        if e.code == 403 and _state["ws"] is None:
+            # 平台级令牌 → 先换工作区级令牌再试一次(DEF-028)
+            ws = cfg.extra_env.get("AINATIVE_WORKSPACE_ID")
+            if ws:
+                _state["ws"] = ws
+                try:
+                    _switch_workspace_token(cfg)
+                    return fn(_ensure_token(cfg))
+                except Exception:
+                    pass
+            raise
+        if e.code != 401 or not _state["refresh"]:
+            raise
+        _state["access"] = None
+        return fn(_ensure_token(cfg))
+
+
+def _get(path: str, token: str) -> dict:
+    req = urllib.request.Request(_state["base"] + path, method="GET")
+    req.add_header("Authorization", f"Bearer {token}")
+    with urllib.request.urlopen(req, timeout=15) as r:
+        return json.loads(r.read())
+
+
+def finalize_to_done(cfg, workitem_id: int) -> None:
+    """把工单流转到其状态模板的 DONE 节点(链路终点收敛,等价于页面上的完工流转)。"""
+    def call(tok):
+        w = _get(f"/api/workitems/{workitem_id}", tok)["data"]
+        nodes = _get(f"/api/status-templates/{w['templateId']}/nodes", tok)["data"]
+        done = next((n for n in nodes if str(n.get("category", "")).upper() == "DONE"), None)
+        if done is None:
+            raise RuntimeError("no DONE node in status template")
+        if done["id"] == w.get("statusNodeId"):
+            return {"success": True, "message": "already at DONE"}
+        body = {"toNodeId": done["id"], "fromNodeId": w.get("statusNodeId"),
+                "expectedVersion": w.get("version")}
+        return _post(f"/api/workitems/{workitem_id}/transition", body, tok)
+    resp = _with_refresh_retry(cfg, call)
+    if not resp.get("success"):
+        raise RuntimeError(f"finalize failed: {resp.get('message')}")
+
+
+def handoff_to_human(cfg, workitem_id: int, user_id: int | None = None) -> None:
+    """把工单交还真人(平台合法操作:assigneeType=HUMAN + 真人 userId)。"""
+    uid = user_id if user_id is not None else cfg.extra_env.get("AINATIVE_HUMAN_USER_ID")
+    if uid is None:
+        raise RuntimeError("no human user id for handoff (roster/ AINATIVE_HUMAN_USER_ID)")
+    def call(tok):
+        return _put(f"/api/workitems/{workitem_id}/assignee",
+                    {"assigneeType": "HUMAN", "assigneeRef": int(uid)}, tok)
+    resp = _with_refresh_retry(cfg, call)
+    if not resp.get("success"):
+        raise RuntimeError(f"handoff_to_human failed: {resp.get('message')}")
+
+
+def reassign_to_agent(cfg, workitem_id: int, agent_id: int) -> None:
+    """把工单重新指派给下一角色的数字员工(平台合法操作,等价于项目经理在页面点指派)。"""
+    cfg.extra_env.setdefault("AINATIVE_API_BASE_URL", "http://localhost:7001")
+    _state["base"] = cfg.extra_env["AINATIVE_API_BASE_URL"]
+    body = {"assigneeType": "AGENT", "assigneeRef": agent_id}
+    def call(tok):
+        return _put(f"/api/workitems/{workitem_id}/assignee", body, tok)
+    resp = _with_refresh_retry(cfg, call)
+    if not resp.get("success"):
+        raise RuntimeError(f"reassign failed: {resp.get('message')}")
+
+
+def agent_comment(cfg, dispatch_id: int, content_md: str) -> dict:
+    """数字员工备注:走平台 daemon 备注通道(executor token 认证,免 Bearer)。
+
+    平台侧为该备注触发 WorkitemCommentCreatedEvent → outbox COMMENT_CREATE →
+    外部工单平台(禅道等)备注回写。这是"交付结论回到源头平台"的正式通道。
+    """
+    base = cfg.extra_env.get("AINATIVE_API_BASE_URL", "http://localhost:7001")
+    _state["base"] = base
+    path = f"/api/daemon/dispatches/{int(dispatch_id)}/comments?token={cfg.executor_token}"
+    req = urllib.request.Request(base + path, method="POST",
+                                 data=json.dumps({"contentMd": content_md}).encode())
+    req.add_header("Content-Type", "application/json")
+    with urllib.request.urlopen(req, timeout=15) as r:
+        return json.loads(r.read())

package/runtime/config.py

@@ -0,0 +1,94 @@
+"""CodeFlow runtime - configuration (env only, stdlib)."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from dataclasses import dataclass, field
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass
+class Config:
+    server_ws_url: str
+    executor_id: int
+    executor_token: str
+    provider: str = "mock"
+    agent_cmd: str = "claude"
+    agent_timeout_sec: int = 1800
+    agent_max_turns: int = 40
+    agent_allowed_tools: str = ""
+    handoff_agent_id: int | None = None
+    chain_finalize: bool = False
+    handoff_human_on_fail: bool = False
+    data_dir: str = "./runtime-data"
+    heartbeat_sec: int = 30
+    max_concurrent: int = 1
+    log_level: str = "info"
+    powercontext_base_url: str = ""
+    powercontext_timeout_sec: float = 8.0
+    powercontext_remember: bool = True
+    extra_env: dict = field(default_factory=dict)
+
+    @property
+    def ws_path(self) -> str:
+        # ws://host:port/ws/executor -> path with query appended later
+        parts = self.server_ws_url.split("://", 1)
+        if len(parts) != 2 or parts[0] not in ("ws", "wss"):
+            raise ConfigError(f"AINATIVE_SERVER_WS_URL must start with ws:// or wss://: {self.server_ws_url}")
+        hostpath = parts[1]
+        path = "/" + hostpath.split("/", 1)[1] if "/" in hostpath else "/ws/executor"
+        if path.rstrip("/") != "/ws/executor":
+            raise ConfigError(f"WS path must be /ws/executor, got: {path}")
+        return path
+
+    @property
+    def ws_hostport(self) -> str:
+        return self.server_ws_url.split("://", 1)[1].split("/", 1)[0]
+
+    @property
+    def use_tls(self) -> bool:
+        return self.server_ws_url.startswith("wss://")
+
+
+def load_config(env: dict | None = None) -> Config:
+    env = dict(os.environ if env is None else env)
+    missing = [k for k in ("AINATIVE_SERVER_WS_URL", "AINATIVE_EXECUTOR_ID", "AINATIVE_EXECUTOR_TOKEN") if not env.get(k)]
+    if missing:
+        raise ConfigError("missing required env: " + ", ".join(missing))
+    provider = env.get("AINATIVE_PROVIDER", "mock")
+    if provider not in ("mock", "claude", "gemini", "codex", "cursor"):
+        raise ConfigError(f"AINATIVE_PROVIDER must be mock|claude|gemini|codex|cursor, got: {provider}")
+    # 各 provider 的默认 CLI 命令;可用 AINATIVE_AGENT_CMD 覆盖(绝对路径/自定义名)。
+    cfg = Config(
+        server_ws_url=env["AINATIVE_SERVER_WS_URL"],
+        executor_id=int(env["AINATIVE_EXECUTOR_ID"]),
+        executor_token=env["AINATIVE_EXECUTOR_TOKEN"],
+        provider=provider,
+        agent_cmd=env.get("AINATIVE_AGENT_CMD",
+                          {"claude": "claude", "gemini": "gemini", "codex": "codex",
+                           "cursor": "cursor-agent"}.get(provider, "claude")),
+        agent_timeout_sec=int(env.get("AINATIVE_AGENT_TIMEOUT_SEC", "1800")),
+        agent_max_turns=int(env.get("AINATIVE_AGENT_MAX_TURNS", "40")),
+        agent_allowed_tools=env.get("AINATIVE_AGENT_ALLOWED_TOOLS", ""),
+        handoff_agent_id=int(env["RUNTIME_HANDOFF_AGENT_ID"]) if env.get("RUNTIME_HANDOFF_AGENT_ID") else None,
+        chain_finalize=env.get("RUNTIME_CHAIN_FINALIZE", "0") in ("1", "true", "yes"),
+        handoff_human_on_fail=env.get("RUNTIME_HANDOFF_HUMAN_ON_FAIL", "0") in ("1", "true", "yes"),
+        # 绝对化:工作目录会作为 claude CLI 的 cwd,相对路径会让 --settings 解析失败(DEF-026)
+        data_dir=str(Path(env.get("RUNTIME_DATA_DIR", "./runtime-data")).expanduser().resolve()),
+        heartbeat_sec=int(env.get("RUNTIME_HEARTBEAT_SEC", "30")),
+        max_concurrent=int(env.get("RUNTIME_MAX_CONCURRENT", "1")),
+        log_level=env.get("RUNTIME_LOG_LEVEL", "info"),
+        # PowerContext 记忆外挂(可选):不配 POWERCONTEXT_BASE_URL 即关闭
+        powercontext_base_url=(env.get("POWERCONTEXT_BASE_URL") or "").strip().rstrip("/"),
+        powercontext_timeout_sec=float(env.get("POWERCONTEXT_TIMEOUT_SEC") or "8.0"),
+        powercontext_remember=env.get("POWERCONTEXT_REMEMBER", "1") in ("1", "true", "yes"),
+        extra_env={k: v for k, v in env.items()
+                  if k.startswith(("ANTHROPIC_", "AINATIVE_AGENT_"))
+                  or k in ("AINATIVE_ACCESS_TOKEN", "AINATIVE_REFRESH_TOKEN",
+                           "AINATIVE_API_BASE_URL", "AINATIVE_WORKSPACE_ID")},
+    )
+    cfg.ws_path  # validate URL shape eagerly
+    return cfg

package/runtime/conversation.py

@@ -0,0 +1,220 @@
+"""Clarification-conversation turn execution (CONVERSATION_TURN frames).
+
+协议(平台侧 WsConversationTransport/InboundFrameRouter):
+  平台 → runtime: CONVERSATION_TURN{conversationId,turnId,agentId,dispatchAttempt?,
+             content,requestId,cliSessionRef?,systemPrompt?,capabilityDownloadUrl,
+             capabilitySha256,capabilityHash,mcpToken}
+  runtime → 平台: CONVERSATION_TURN_ACK{conversationId,turnId,dispatchAttempt?,
+             status:SUCCESS|FAILED,error?,replyMarkdown?,sessionId?,usage?}
+
+心跳声明 CONVERSATION_DELIVERY_ACK_V1 后,ACK 必须回显 dispatchAttempt,
+平台据此做陈旧投递判定与投递确认。
+
+claude 执行形态:每会话一个工作区;每回合下载 capability 包(sha256 校验)解包,
+--resume 上一回合 sessionId 保持上下文;MCP(ainative) 以 Bearer mcpToken 注入,
+数字员工由此读取工单与平台数据。
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+import time
+import urllib.request
+import zipfile
+from pathlib import Path
+
+from .logging_util import log
+from .providers.claude_code import write_settings_file
+
+CAPABILITY_TIMEOUT_SEC = 120
+TURN_TIMEOUT_SEC = 30 * 60  # 平台 ~11min 会重投;dispatchAttempt 去重保证幂等
+
+
+def download_capability(url: str, expected_sha256: str, dest_dir: Path) -> Path:
+    """下载 capability 包并做 sha256 完整性校验(与平台 TaskPackager 计算口径一致)。"""
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    zip_path = dest_dir / "capability.zip"
+    tmp = zip_path.with_suffix(".part")
+    req = urllib.request.Request(url)
+    with urllib.request.urlopen(req, timeout=CAPABILITY_TIMEOUT_SEC) as resp, open(tmp, "wb") as f:
+        while True:
+            chunk = resp.read(256 * 1024)
+            if not chunk:
+                break
+            f.write(chunk)
+    digest = hashlib.sha256(tmp.read_bytes()).hexdigest()
+    if expected_sha256 and digest.lower() != expected_sha256.lower():
+        tmp.unlink(missing_ok=True)
+        raise ValueError(f"capability sha256 mismatch: got {digest}, want {expected_sha256}")
+    tmp.replace(zip_path)
+    return zip_path
+
+
+def extract_capability(zip_path: Path, dest_dir: Path) -> None:
+    """解包 capability 包(覆盖式;包内为 skills.json/mcp 配置/仓库上下文等)。"""
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(zip_path) as zf:
+        zf.extractall(dest_dir)
+
+
+def ainative_mcp_server(capsule_dir: Path, mcp_token: str) -> dict | None:
+    """从 capability 的 skills.json 取内置 ainative MCP 描述,注入 Bearer mcpToken。
+
+    平台 authType=ainative-dispatch 的鉴权即 MCP 端点的 Authorization 头。
+    """
+    skills_path = capsule_dir / "skills.json"
+    if not skills_path.exists():
+        return None
+    try:
+        doc = json.loads(skills_path.read_text(encoding="utf-8"))
+    except (ValueError, OSError) as e:
+        log.warn("conversation.skills_unreadable", error=str(e))
+        return None
+    for server in doc.get("mcpServers") or []:
+        name = str(server.get("name", "")).lower()
+        if name != "ainative":
+            continue
+        url = server.get("url")
+        if not url:
+            return None
+        return {"type": "http" if server.get("transport", "http") == "http" else "sse",
+                "url": url, "headers": {"Authorization": f"Bearer {mcp_token}"}}
+    return None
+
+
+def write_mcp_config(workdir: Path, server: dict | None) -> None:
+    if not server:
+        return
+    (workdir / ".mcp.json").write_text(
+        json.dumps({"mcpServers": {"ainative": server}}, ensure_ascii=False), encoding="utf-8")
+
+
+def write_conversation_settings(workdir: Path, env: dict, mcp_token: str | None) -> str | None:
+    """claude --settings:钉模型端点环境变量 + 预授权 ainative MCP 工具。
+
+    -p 模式无权限弹窗,部分 CLI 版本对 --allowedTools 的服务器级简写不生效,
+    settings 的 permissions.allow(服务器名 + 工具通配两种形式)是权威路径。
+    """
+    picked = {k: v for k, v in env.items()
+              if k.startswith("ANTHROPIC_") or k == "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC"}
+    settings = {"env": picked}
+    if mcp_token:
+        settings["permissions"] = {"allow": ["mcp__ainative", "mcp__ainative__*"]}
+    path = workdir / "claude-settings.json"
+    path.write_text(json.dumps(settings, ensure_ascii=False), encoding="utf-8")
+    return str(path)
+
+
+def build_command(cli_binary: str, content: str, *, session_ref: str | None,
+                  system_prompt: str | None, settings_file: str | None,
+                  max_turns: int, allowed_tools: str | None = None) -> list[str]:
+    argv = [cli_binary, "-p", content, "--output-format", "json"]
+    if session_ref:
+        argv += ["--resume", session_ref]
+    if max_turns:
+        argv += ["--max-turns", str(max_turns)]
+    if settings_file:
+        argv += ["--settings", settings_file]
+    if system_prompt:
+        argv += ["--append-system-prompt", system_prompt]
+    if allowed_tools:
+        argv += ["--allowedTools", allowed_tools]
+    return argv
+
+
+def parse_result(raw: str) -> dict:
+    """解析 claude --output-format json 单行结果 → {text, session_id, is_error, usage}。"""
+    out = {"text": "", "session_id": None, "is_error": True, "error": "empty output",
+           "usage": None, "model": None}
+    for line in (raw or "").splitlines():
+        line = line.strip()
+        if not line or not line.startswith("{"):
+            continue
+        try:
+            data = json.loads(line)
+        except ValueError:
+            continue
+        if data.get("type") != "result":
+            continue
+        out["text"] = data.get("result") or ""
+        out["session_id"] = data.get("session_id")
+        out["is_error"] = bool(data.get("is_error"))
+        out["error"] = None if not out["is_error"] else (out["text"] or "claude reported error")
+        usage = data.get("usage") or {}
+        out["usage"] = {
+            "inputTokens": int(usage.get("input_tokens") or 0),
+            "outputTokens": int(usage.get("output_tokens") or 0),
+            "cacheReadTokens": int(usage.get("cache_read_input_tokens") or 0),
+            "cacheWriteTokens": int(usage.get("cache_creation_input_tokens") or 0),
+        }
+        model_usage = data.get("modelUsage") or {}
+        if isinstance(model_usage, dict) and model_usage:
+            out["model"] = next(iter(model_usage))
+        break
+    return out
+
+
+def run_claude_turn(cli_binary: str, workdir: Path, content: str, *, session_ref: str | None,
+                    system_prompt: str | None, settings_path: str | None, max_turns: int,
+                    env: dict, timeout_sec: int = TURN_TIMEOUT_SEC,
+                    allowed_tools: str | None = None) -> dict:
+    """同步执行一回合对话;返回 parse_result 形态,附 exit_code/stderr 供失败诊断。"""
+    argv = build_command(cli_binary, content, session_ref=session_ref,
+                         system_prompt=system_prompt, settings_file=settings_path,
+                         max_turns=max_turns, allowed_tools=allowed_tools)
+    started = time.monotonic()
+    try:
+        proc = subprocess.run(argv, cwd=str(workdir), env=env, capture_output=True,
+                              text=True, timeout=timeout_sec)
+        result = parse_result(proc.stdout or "")
+        result["exit_code"] = proc.returncode
+        if proc.returncode != 0 and not result["text"]:
+            result["is_error"] = True
+            result["error"] = (proc.stderr or "")[-800:] or f"claude exited {proc.returncode}"
+    except subprocess.TimeoutExpired:
+        result = {"text": "", "session_id": None, "is_error": True,
+                  "error": f"conversation turn timeout after {timeout_sec}s",
+                  "usage": None, "model": None, "exit_code": None}
+    result["duration_ms"] = int((time.monotonic() - started) * 1000)
+    return result
+
+
+def turn_ack(conversation_id: int, turn_id: int, dispatch_attempt: int | None,
+             status: str, *, reply_markdown: str = "", error: str = "",
+             session_id: str | None = None, usage: dict | None = None,
+             model: str | None = None) -> dict:
+    frame = {"type": "CONVERSATION_TURN_ACK", "conversationId": int(conversation_id),
+             "turnId": int(turn_id), "status": status,
+             "replyMarkdown": reply_markdown or "", "error": error or ""}
+    if dispatch_attempt:
+        frame["dispatchAttempt"] = int(dispatch_attempt)
+    if session_id:
+        frame["sessionId"] = session_id
+    if usage:
+        frame["usage"] = {"provider": "claude", "model": model or "", **usage}
+    return frame
+
+
+def register_mcp_server(cli_binary: str, workdir: Path, env: dict, url: str, mcp_token: str) -> bool:
+    """以 local scope 注册 ainative MCP(用户添加即受信,headless 免批准)。
+
+    token 每回合轮换(turn-bound),-f 覆盖旧注册。失败仅告警:工具不可用时数字员工
+    仍可凭 capability 包内上下文作答。
+    """
+    # 该 CLI 版本无 force 旗标:先 remove(不存在则报错,忽略)再 add 实现每回合轮换覆盖
+    subprocess.run([cli_binary, "mcp", "remove", "--scope", "local", "ainative"],
+                   cwd=str(workdir), env=env, capture_output=True, text=True, timeout=60)
+    argv = [cli_binary, "mcp", "add", "--transport", "http", "--scope", "local",
+            "ainative", url, "--header", f"Authorization: Bearer {mcp_token}"]
+    try:
+        proc = subprocess.run(argv, cwd=str(workdir), env=env, capture_output=True,
+                              text=True, timeout=60)
+        if proc.returncode != 0:
+            log.warn("conversation.mcp_add_failed", code=proc.returncode,
+                     stderr=(proc.stderr or "")[-200:])
+            return False
+        return True
+    except (OSError, subprocess.TimeoutExpired) as e:
+        log.warn("conversation.mcp_add_error", error=str(e))
+        return False