@delta-infra/cli 1.0.95 → 1.0.97

package/skills/delta-science/references/workflows.md

@@ -1,61 +1,98 @@
-# 跨服务工作流
-
-整个流程由单一 `delta-science` Skill 编排。线上调用最终执行
-`delta-cli science invoke`，禁止直接 HTTP。可使用 subagent 协助整理输入、核对 reference
-或展示结果，但主流程负责工具选择和所有线上调用。CLI 成功后每一步只消费对应 reference
-定义的 `data` 响应字段。已知 reference 中没有目标 operation 时，不猜测相近 endpoint；reference
-缺失、过期或与 CLI 返回不一致时，按 `SKILL.md` 的只读实时 catalog 流程确认。
-
-## 单个已命名分子
-
-1. 用 PubChem `compound-summary` 解析名称并取得身份字段。
-2. 按文档规定的回退顺序提取 SMILES。
-3. 只有用户要求 RDKit 描述符或明确的结构校验时，才调用 RDKit `batch-parse-describe`。
+# 跨服务工作流
+
+整个流程由单一 `delta-science` Skill 编排。线上调用最终执行
+`delta-cli science invoke`，禁止直接 HTTP。可使用 subagent 协助整理输入、核对 reference
+或展示结果，但主流程负责工具选择和所有线上调用。CLI 成功后每一步只消费对应 reference
+定义的 `data` 响应字段。已知 reference 中没有目标 operation 时，不猜测相近 endpoint；reference
+缺失、过期或与 CLI 返回不一致时，按 `SKILL.md` 的只读实时 catalog 流程确认。
+
+## 单个已命名分子
+
+1. 用 PubChem `compound-summary` 解析名称并取得身份字段。
+2. 按文档规定的回退顺序提取 SMILES。
+3. 只有用户要求 RDKit 描述符或明确的结构校验时，才调用 RDKit `batch-parse-describe`。
 4. 只有用户明确要求图片时，才调用 RDKit `render`，并解码、验证图片字节。
 5. 比较分子式、分子量、InChIKey 和供体/受体数量时，要明确区分 LogP、TPSA 等依赖模型的数值。
 
-## 多分子比较
-
-1. 用 PubChem 批量解析全部名称，请求体只包含 `identifiers` 和 `namespace:"name"`。省略 `properties`。
-2. 从业务响应的 `results[*]` 读取记录，并从每条记录的嵌套 `properties` 读取字段。
-3. 未解析成功的记录要排除，并明确说明原因。
-4. 使用 RDKit `similarity-matrix` 校验和排序两两相似度。它的 `sanitize` 已经校验输入，不要额外调用 parse。
-5. 用 PubChem 记录的原始 `input` 作为 molecule id，并按文档顺序从嵌套属性中提取 SMILES。
-6. 保持输入顺序，报告每个分数时明确对应的分子对。
-7. 除非用户明确要求，不要渲染、保存用户文件、检查健康状态或探测额外描述符。
-8. `ranked_pairs` 使用命名字段 `a`、`b`、`similarity`。找指定目标的最近邻时，
-   在包含该目标的记录中取最大 `similarity`，另一侧字段就是最近邻；不要使用
-   `i`、`j`、`score` 或猜测矩阵下标。
-
-## 材料工作流
-
-1. 使用 pymatgen 校验化学式/结构并转换 CIF；无机式量只能取当前业务响应 `weight`。
-2. GSAS-II 只能接收真实 CIF 文本后再做衍射计算。
+如果用户明确要求一次返回 PubChem 记录以及 RDKit 规范化/描述符/指纹，使用
+`chemistry/molecule.enrich`；只要 PubChem 身份信息或只要 RDKit 计算时，仍使用对应的
+单服务 operation。
+
+## 多分子比较
+
+1. 用 PubChem 批量解析全部名称，请求体只包含 `identifiers` 和 `namespace:"name"`。省略 `properties`。
+2. 从业务响应的 `results[*]` 读取记录，并从每条记录的嵌套 `properties` 读取字段。
+3. 未解析成功的记录要排除，并明确说明原因。
+4. 使用 RDKit `similarity-matrix` 校验和排序两两相似度。它的 `sanitize` 已经校验输入，不要额外调用 parse。
+5. 用 PubChem 记录的原始 `input` 作为 molecule id，并按文档顺序从嵌套属性中提取 SMILES。
+6. 保持输入顺序，报告每个分数时明确对应的分子对。
+7. 除非用户明确要求，不要渲染、保存用户文件、检查健康状态或探测额外描述符。
+8. `ranked_pairs` 使用命名字段 `a`、`b`、`similarity`。找指定目标的最近邻时，
+   在包含该目标的记录中取最大 `similarity`，另一侧字段就是最近邻；不要使用
+   `i`、`j`、`score` 或猜测矩阵下标。
+
+## 材料工作流
+
+1. 使用 pymatgen 校验化学式/结构并转换 CIF；无机式量只能取当前业务响应 `weight`。
+2. GSAS-II 只能接收真实 CIF 文本后再做衍射计算。
 3. LAMMPS 只能在已有明确的力场、data 和脚本设置后运行；部署检查可以使用内置有界示例。
 4. 从 LAMMPS 返回 pymatgen 或 GSAS-II 前，需要从弛豫结果重新构造 CIF/POSCAR。不要直接传递 LAMMPS data/dump 文件。
 
-## 优化工作流
+## Materials Design 工作流
 
-- 通用数值或分类实验变量：Delta-BO
-- 固定 SMILES 候选池或 PDF2Dock/Vina+NN 轨迹：LDM-BO
-- 固定 KRAS G12D 的生成式小分子闭环：STRBO
-- 指定抗原的 11-aa CDRH3 闭环：AntBO
-- 偶联反应、反应条件和带真实历史得率的下一批实验推荐：SynBO
+1. 先明确 identifier、可控设计变量、目标列及方向、泄漏/元数据列、分组或时间切分和
+   可行候选空间；不能优化 identifier、测量后变量或泄漏字段。
+2. 优先使用用户提供的候选表；只有服务契约允许且假设已标明时，才从可控变量的观测域
+   生成离散候选。组成闭合、硬约束、步长和是否允许外推必须显式记录。
+3. 读取作业的 `status` 后再读取 `result_status`；`completed` 不等于推荐可靠。
+   `complete`、`exploratory`、`readiness_only` 和 `failed` 必须分别报告，并保留 warnings。
+4. 只有用户要求或工作流需要时才下载 report/CSV/JSON artifact；依据服务返回的 size 和
+   SHA-256 校验，不能声称结果已经写入本地项目目录。
 
-用户以 “LDM/大发现模型” 描述任务时，必须先按 `SKILL.md` 读取 `ldm.md`，再读取唯一
-选定后端的 reference。LDM 是工作流意图，不是 tool；禁止旧
-`large-discovery-model`、`run_ldm_loop.py`、gateway backend 和直接 HTTP。
+Materials Design 的 `jobs` 上传是 multipart。当前 `delta-cli science invoke` 只能传 JSON
+body/query；除非实时目录提供明确的文件上传 adapter，否则不猜测 endpoint、不要把文件
+路径或 base64 塞进 `--data`，也不要改走直连 Gateway。
 
-禁止为了让优化器运行而编造观测数据。用户没有提供测量结果时，只能使用初始化或随机建议模式，并明确说明它是待实验验证的建议，不是已经验证的最优条件。
-SynBO/Delta-BO 没有返回 recommendations 时，不得用本地回归、GP、UCB 或人工排序替代。
+## QE DFT 工作流
 
-SynBO 只接受离散条件列表。用户给连续范围时，在一次调用前完成以下处理：
+1. 读取 health 和实时 workflow catalog，选择当前为 `supported` 的 workflow；收集完整
+   campaign element union，并按服务返回值解析/锁定 PP。
+2. 结构必须先成为服务返回的 checksum-addressed artifact；job 只引用 artifact ID、已批准
+   parameter set、PP lock、k-points、workflow_inputs 和资源请求。
+3. 提交必须使用稳定幂等语义；HTTP 202/accepted 只表示接收，不表示 QE 已收敛。轮询时
+   独立读取 `execution`、`solver`、`scientific` 三个状态，并按原始 stable error code 分类。
+4. CPU 是默认资源策略。只有用户明确要求或项目已有 GPU 授权且 live catalog 标记为
+   `gpu_support_status: verified` 时才请求 GPU；`gpu` 不得静默回退到 CPU，`auto` 也不等于
+   已实际使用 GPU。
+5. 日志和结果 artifact 下载后按服务返回的 SHA-256 校验；不要把 scheduler 完成、solver
+   收敛或可解析输出直接写成 scientific acceptance。
 
-1. 条件网格包含用户上下界、全部历史观测值和少量合理中间点。
-2. 同一条件列在 `condition_dict` 与 `previous_results` 中统一为字符串。
-3. 得率等 objective metric 保持数值。
-4. 小数据 CPU 默认 `tiny + RF + UCB`，并在最终答案中报告实际离散网格。
-5. CLI 返回失败或业务响应为空 recommendations 时结束；不得连续尝试多种 payload 或模型。
+QE 原始 artifact 上传需要二进制 body，job 提交还需要自定义 `Idempotency-Key`。当前 CLI
+没有这两类参数；只能调用 Science Server 已明确暴露的等价 adapter，否则报告“当前 CLI
+未暴露该 operation；未发送远端请求”。
 
-用户未要求文件时只返回 recommendations 文本，不创建输入 CSV。必须交接时，仅把本次
-成功业务响应写入当前 `WORKSPACE_ROOT/synbo_result.json`。
+## 优化工作流
+
+- 通用数值或分类实验变量：Delta-BO
+- 固定 SMILES 候选池或 PDF2Dock/Vina+NN 轨迹：LDM-BO
+- 固定 KRAS G12D 的生成式小分子闭环：STRBO
+- 指定抗原的 11-aa CDRH3 闭环：AntBO
+- 偶联反应、反应条件和带真实历史得率的下一批实验推荐：SynBO
+
+用户以 “LDM/大发现模型” 描述任务时，必须先按 `SKILL.md` 读取 `ldm.md`，再读取唯一
+选定后端的 reference。LDM 是工作流意图，不是 tool；禁止旧
+`large-discovery-model`、`run_ldm_loop.py`、gateway backend 和直接 HTTP。
+
+禁止为了让优化器运行而编造观测数据。用户没有提供测量结果时，只能使用初始化或随机建议模式，并明确说明它是待实验验证的建议，不是已经验证的最优条件。
+SynBO/Delta-BO 没有返回 recommendations 时，不得用本地回归、GP、UCB 或人工排序替代。
+
+SynBO 只接受离散条件列表。用户给连续范围时，在一次调用前完成以下处理：
+
+1. 条件网格包含用户上下界、全部历史观测值和少量合理中间点。
+2. 同一条件列在 `condition_dict` 与 `previous_results` 中统一为字符串。
+3. 得率等 objective metric 保持数值。
+4. 小数据 CPU 默认 `tiny + RF + UCB`，并在最终答案中报告实际离散网格。
+5. CLI 返回失败或业务响应为空 recommendations 时结束；不得连续尝试多种 payload 或模型。
+
+用户未要求文件时只返回 recommendations 文本，不创建输入 CSV。必须交接时，仅把本次
+成功业务响应写入当前 `WORKSPACE_ROOT/synbo_result.json`。

package/skills/delta-science/scripts/catalog.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Read the authoritative Delta Science catalog through delta-cli."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+
+from invoke import _parse_cli_error, _resolve_cli, _runtime_config
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    action = parser.add_mutually_exclusive_group(required=True)
+    action.add_argument("--tools", action="store_true")
+    action.add_argument("--endpoints", metavar="TOOL")
+    parser.add_argument("--cli")
+    parser.add_argument("--science-base-url")
+    parser.add_argument("--timeout", type=float, default=30.0)
+    return parser
+
+
+def main() -> int:
+    args = _parser().parse_args()
+    started = time.perf_counter()
+    kind = "tools" if args.tools else "endpoints"
+    try:
+        runtime = _runtime_config()
+        cli = _resolve_cli(args.cli, runtime)
+        env = os.environ.copy()
+        base_url = args.science_base_url or runtime.get("science_base_url")
+        if base_url:
+            env["DELTA_INFRA_SCIENCE_BASE_URL"] = str(base_url)
+
+        command = [cli, "science", "list"]
+        if args.endpoints:
+            command = [cli, "science", "endpoints", "list", args.endpoints]
+        completed = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            env=env,
+            timeout=args.timeout,
+            check=False,
+        )
+        if completed.returncode != 0:
+            error_type, detail = _parse_cli_error(completed)
+            raise RuntimeError(f"{error_type}: {detail}")
+        root = json.loads(completed.stdout)
+        if not isinstance(root, dict) or root.get("ok") is not True:
+            raise RuntimeError(json.dumps(root, ensure_ascii=False))
+        if "data" not in root:
+            raise RuntimeError("CLI success envelope is missing data")
+        print(json.dumps({
+            "ok": True,
+            "transport": "delta-cli",
+            "catalog": kind,
+            "tool": args.endpoints,
+            "elapsed_seconds": round(time.perf_counter() - started, 3),
+            "native": root["data"],
+        }, ensure_ascii=False))
+        return 0
+    except subprocess.TimeoutExpired:
+        error_type = "timeout"
+        error = f"timeout after {args.timeout}s"
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        error_type = "catalog"
+        error = str(exc)
+    except RuntimeError as exc:
+        error_type = "cli"
+        error = str(exc)
+
+    print(json.dumps({
+        "ok": False,
+        "transport": "delta-cli",
+        "catalog": kind,
+        "tool": args.endpoints,
+        "error_type": error_type,
+        "elapsed_seconds": round(time.perf_counter() - started, 3),
+        "error": error[:2000],
+    }, ensure_ascii=False))
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/delta-science/scripts/generated_catalog.py

@@ -0,0 +1,69 @@
+"""Generated Science catalog aliases. Do not edit by hand."""
+
+LEGACY_TOOL_ALIASES = {
+    "synbo": "synbo-service",
+    "antbo": "antbo-service",
+}
+
+LEGACY_ENDPOINTS = {
+    "pubchem": {
+        "health": "chem_pubchem_health",
+        "compound-resolve-cids": "chem_pubchem_compound_resolve-cids",
+        "compound-properties": "chem_pubchem_compound_properties",
+        "compound-synonyms": "chem_pubchem_compound_synonyms",
+        "compound-summary": "chem_pubchem_compound_summary",
+        "compound-batch-summary": "chem_pubchem_compound_batch-summary",
+    },
+    "rdkit": {
+        "health": "chem_rdkit_health",
+        "parse": "chem_rdkit_parse",
+        "descriptors": "chem_rdkit_descriptors",
+        "batch-descriptors": "chem_rdkit_batch-descriptors",
+        "batch-parse-describe": "chem_rdkit_batch-parse-describe",
+        "render": "chem_rdkit_render",
+        "fingerprint": "chem_rdkit_fingerprint",
+        "similarity": "chem_rdkit_similarity",
+        "similarity-matrix": "chem_rdkit_similarity-matrix",
+        "substructure": "chem_rdkit_substructure",
+    },
+    "pymatgen": {
+        "health": "chem_pymatgen_health",
+        "composition-parse": "chem_pymatgen_composition_parse",
+        "structure-parse": "chem_pymatgen_structure_parse",
+        "structure-summary": "chem_pymatgen_structure_summary",
+        "structure-convert": "chem_pymatgen_structure_convert",
+        "structure-symmetry": "chem_pymatgen_structure_symmetry",
+    },
+    "gsasii": {
+        "health": "chem_gsasii_health",
+        "powder-simulate": "chem_gsasii_powder_simulate",
+        "powder-refine": "chem_gsasii_powder_refine",
+    },
+    "lammps": {
+        "health": "chem_lammps_health",
+        "lj-melt-example": "chem_lammps_examples_lj-melt",
+        "run": "chem_lammps_run",
+    },
+    "delta-bo": {
+        "commands": "chem_delta-bo_commands",
+        "generate": "chem_delta-bo_generate",
+    },
+    "ldm-bo": {
+        "health": "chem_ldm-bo_health",
+        "recommend": "chem_ldm-bo_recommend",
+        "trajectory": "chem_ldm-bo_trajectory",
+    },
+    "synbo": {
+        "health": "chem_synbo_health",
+        "initialize": "chem_synbo_initialize",
+        "optimize": "chem_synbo_optimize",
+    },
+    "antbo": {
+        "health": "biology_antbo_health",
+        "run-default-job": "biology_antbo_run_default_job",
+        "run": "biology_antbo_run",
+        "log": "biology_antbo_log",
+        "jobs": "biology_antbo_jobs",
+        "stop": "biology_antbo_stop",
+    },
+}

package/skills/delta-science/scripts/invoke.py

@@ -0,0 +1,346 @@
+#!/usr/bin/env python3
+"""Invoke one Delta Science operation strictly through delta-cli."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import time
+from typing import Any
+
+SKILL_DIR = Path(__file__).resolve().parents[1]
+_CLI_ERROR_TYPES = {
+    2: "validation",
+    3: "auth",
+    4: "permission",
+    5: "not_found",
+    6: "network",
+    7: "api",
+    10: "internal",
+}
+
+
+def _json_object(raw: str | None, flag: str) -> dict[str, Any] | None:
+    if raw is None:
+        return None
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{flag} is not valid JSON: {exc}") from exc
+    if not isinstance(value, dict):
+        raise ValueError(f"{flag} must decode to a JSON object")
+    return value
+
+
+def _normalize_synbo_payload(
+    tool: str,
+    endpoint: str,
+    data: dict[str, Any] | None,
+) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+    """Normalize SynBO's discrete condition contract before any remote request."""
+    canonical_tool = tool.removesuffix("-service")
+    if canonical_tool != "synbo" or endpoint not in {"initialize", "optimize"}:
+        return data, None
+    if data is None:
+        raise ValueError(f"synbo/{endpoint} requires --data-json")
+
+    condition_dict = data.get("condition_dict")
+    if not isinstance(condition_dict, dict) or not condition_dict:
+        raise ValueError("SynBO condition_dict must be a non-empty object")
+
+    normalized_conditions: dict[str, list[str]] = {}
+    for name, raw_values in condition_dict.items():
+        if not isinstance(raw_values, list) or not raw_values:
+            raise ValueError(
+                f"SynBO condition_dict.{name} must be a non-empty explicit list; "
+                "range objects are not supported"
+            )
+        values = [str(value) for value in raw_values]
+        if any(value == "" for value in values):
+            raise ValueError(f"SynBO condition_dict.{name} contains an empty value")
+        if len(set(values)) != len(values):
+            raise ValueError(
+                f"SynBO condition_dict.{name} contains duplicate values after "
+                "string normalization"
+            )
+        normalized_conditions[str(name)] = values
+
+    normalized = dict(data)
+    normalized["condition_dict"] = normalized_conditions
+    normalization = {
+        "condition_values": "strings",
+        "condition_space_size": _condition_space_size(normalized_conditions),
+    }
+
+    if endpoint == "initialize":
+        return normalized, normalization
+
+    metrics = normalized.get("opt_metrics")
+    if not isinstance(metrics, list) or not metrics:
+        raise ValueError("SynBO optimize requires a non-empty opt_metrics list")
+    metric_names = [str(metric) for metric in metrics]
+    normalized["opt_metrics"] = metric_names
+
+    previous_results = normalized.get("previous_results")
+    if not isinstance(previous_results, list) or not previous_results:
+        raise ValueError("SynBO optimize requires non-empty previous_results")
+
+    normalized_rows: list[dict[str, Any]] = []
+    for index, raw_row in enumerate(previous_results):
+        if not isinstance(raw_row, dict):
+            raise ValueError(f"SynBO previous_results[{index}] must be an object")
+        row = dict(raw_row)
+        for condition_name, allowed_values in normalized_conditions.items():
+            if condition_name not in row:
+                raise ValueError(
+                    f"SynBO previous_results[{index}] is missing condition "
+                    f"{condition_name!r}"
+                )
+            value = str(row[condition_name])
+            if value not in allowed_values:
+                raise ValueError(
+                    f"SynBO previous_results[{index}].{condition_name}={value!r} "
+                    "is not present in condition_dict"
+                )
+            row[condition_name] = value
+        for metric_name in metric_names:
+            metric_value = row.get(metric_name)
+            if (
+                metric_name not in row
+                or isinstance(metric_value, bool)
+                or not isinstance(metric_value, (int, float))
+            ):
+                raise ValueError(
+                    f"SynBO previous_results[{index}].{metric_name} must be numeric"
+                )
+        normalized_rows.append(row)
+
+    normalized["previous_results"] = normalized_rows
+    normalized.setdefault("accuracy", "tiny")
+    normalized.setdefault("device", "cpu")
+    normalized.setdefault("surrogate_model", "RF")
+    normalized.setdefault("acq_func", "UCB")
+    normalization["defaults"] = {
+        key: normalized[key]
+        for key in ("accuracy", "device", "surrogate_model", "acq_func")
+    }
+    return normalized, normalization
+
+
+def _condition_space_size(condition_dict: dict[str, list[str]]) -> int:
+    size = 1
+    for values in condition_dict.values():
+        size *= len(values)
+    return size
+
+
+def _runtime_config() -> dict[str, Any]:
+    path = SKILL_DIR / "runtime.local.json"
+    if not path.is_file():
+        return {}
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def _resolve_cli(explicit: str | None, runtime: dict[str, Any]) -> str:
+    candidates: list[str | None] = [
+        explicit,
+        os.environ.get("DELTA_CLI_PATH"),
+        runtime.get("cli_path"),
+        shutil.which("delta-cli"),
+        shutil.which("delta-cli.exe"),
+    ]
+    package_root = SKILL_DIR.parents[1]
+    exe_name = "delta-cli.exe" if os.name == "nt" else "delta-cli"
+    candidates.append(str(package_root / "bin" / exe_name))
+    for candidate in candidates:
+        if candidate and Path(candidate).is_file():
+            return str(Path(candidate).resolve())
+    raise FileNotFoundError(
+        "delta-cli not found; install @delta-infra/cli, set DELTA_CLI_PATH, "
+        "or add cli_path to delta-science/runtime.local.json"
+    )
+
+
+def _unwrap(stdout: str) -> tuple[Any, int]:
+    try:
+        root = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"CLI stdout is not JSON: {exc}") from exc
+    if not isinstance(root, dict):
+        raise RuntimeError("CLI stdout root is not an object")
+    if root.get("ok") is not True:
+        raise RuntimeError(json.dumps(root.get("error", root), ensure_ascii=False))
+    if "data" not in root:
+        raise RuntimeError("CLI success envelope is missing data")
+
+    value: Any = root["data"]
+    depth = 0
+    while isinstance(value, dict):
+        if "status_code" in value and "data" in value:
+            status_code = value.get("status_code")
+            if not isinstance(status_code, int) or not 200 <= status_code < 300:
+                raise RuntimeError(json.dumps(value, ensure_ascii=False))
+            value = value["data"]
+        elif (
+            "code" in value
+            and "data" in value
+            and set(value).intersection({"message", "msg"})
+        ):
+            code = value.get("code")
+            if code not in (0, "0", None):
+                raise RuntimeError(json.dumps(value, ensure_ascii=False))
+            value = value["data"]
+        else:
+            break
+        depth += 1
+        if depth > 4:
+            raise RuntimeError("too many nested service envelopes")
+    if isinstance(value, dict) and value.get("valid") is False:
+        raise RuntimeError(json.dumps({
+            "valid": False,
+            "error": value.get("error"),
+            "warnings": value.get("warnings"),
+        }, ensure_ascii=False))
+    return value, depth
+
+
+def _validate_native(tool: str, endpoint: str, native: Any) -> None:
+    canonical_tool = tool.removesuffix("-service")
+    if canonical_tool == "synbo" and endpoint == "optimize":
+        if not isinstance(native, dict):
+            raise RuntimeError("SynBO optimize returned a non-object result")
+        recommendations = native.get("recommendations")
+        if not isinstance(recommendations, list) or not recommendations:
+            raise RuntimeError("SynBO optimize returned no recommendations")
+
+
+def _parse_cli_error(completed: subprocess.CompletedProcess[str]) -> tuple[str, str]:
+    detail = completed.stderr.strip() or completed.stdout.strip()
+    error_type = _CLI_ERROR_TYPES.get(completed.returncode, "cli")
+    try:
+        envelope = json.loads(detail)
+        error = envelope.get("error", {}) if isinstance(envelope, dict) else {}
+        if isinstance(error, dict):
+            error_type = str(error.get("type") or error_type)
+            message = error.get("message")
+            if message:
+                detail = str(message)
+    except (AttributeError, json.JSONDecodeError):
+        pass
+    return error_type, detail
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--tool", required=True)
+    parser.add_argument("--endpoint", required=True)
+    body = parser.add_mutually_exclusive_group()
+    body.add_argument("--data-json")
+    body.add_argument("--params-json")
+    parser.add_argument("--cli")
+    parser.add_argument("--science-base-url")
+    parser.add_argument("--timeout", type=float, default=120.0)
+    return parser
+
+
+def main() -> int:
+    args = _parser().parse_args()
+    started = time.perf_counter()
+    stage = "arguments"
+    cli_exit_code: int | None = None
+    error_type = "unknown"
+    normalization: dict[str, Any] | None = None
+    try:
+        data = _json_object(args.data_json, "--data-json")
+        params = _json_object(args.params_json, "--params-json")
+        data, normalization = _normalize_synbo_payload(
+            args.tool, args.endpoint, data
+        )
+        runtime = _runtime_config()
+        stage = "cli-resolution"
+        cli = _resolve_cli(args.cli, runtime)
+
+        env = os.environ.copy()
+        base_url = args.science_base_url or runtime.get("science_base_url")
+        if base_url:
+            env["DELTA_INFRA_SCIENCE_BASE_URL"] = str(base_url)
+
+        command = [
+            cli, "science", "invoke",
+            "--tool", args.tool,
+            "--endpoint", args.endpoint,
+        ]
+        if data is not None:
+            command.extend(["--data", json.dumps(data, ensure_ascii=False, separators=(",", ":"))])
+        if params is not None:
+            command.extend(["--params", json.dumps(params, ensure_ascii=False, separators=(",", ":"))])
+
+        stage = "delta-cli"
+        completed = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            env=env,
+            timeout=args.timeout,
+            check=False,
+        )
+        if completed.returncode != 0:
+            cli_exit_code = completed.returncode
+            error_type, detail = _parse_cli_error(completed)
+            raise RuntimeError(f"exit_code={completed.returncode}: {detail}")
+        stage = "response-validation"
+        native, depth = _unwrap(completed.stdout)
+        _validate_native(args.tool, args.endpoint, native)
+        result = {
+            "ok": True,
+            "transport": "delta-cli",
+            "tool": args.tool,
+            "endpoint": args.endpoint,
+            "elapsed_seconds": round(time.perf_counter() - started, 3),
+            "envelope_depth": depth,
+            "native": native,
+        }
+        if normalization is not None:
+            result["request_normalization"] = normalization
+        print(json.dumps(result, ensure_ascii=False))
+        return 0
+    except subprocess.TimeoutExpired:
+        error_type = "timeout"
+        error = f"timeout after {args.timeout}s"
+    except ValueError as exc:
+        error_type = "validation"
+        error = str(exc)
+    except OSError as exc:
+        error_type = "cli_resolution"
+        error = str(exc)
+    except RuntimeError as exc:
+        if error_type == "unknown":
+            error_type = "response_validation"
+        error = str(exc)
+    print(json.dumps({
+        "ok": False,
+        "transport": "delta-cli",
+        "tool": args.tool,
+        "endpoint": args.endpoint,
+        "stage": stage,
+        "error_type": error_type,
+        "cli_exit_code": cli_exit_code,
+        "elapsed_seconds": round(time.perf_counter() - started, 3),
+        "error": error[:2000],
+    }, ensure_ascii=False))
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())