agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/model_proxy/detect.py

@@ -44,6 +44,16 @@ class ModelCapabilities:
     preferred_protocol: str = "chat"  # "responses" | "chat":路由该走哪条
     checked_at: float = 0.0
     verdict: Verdict = "unknown"  # 最近一次探测结论
+    # --- 以下为 opt-in 贵探测,默认 None(未探),由 probe_extended_capability 按需填充 ---
+    # store/previous_response_id 服务端会话链是否真生效(2026-09 实测 deepseek 系
+    # 返回 200 但静默丢历史=假支持)。False 时客户端必须每次带全量历史。
+    store_supported: bool | None = None
+    # 该模型 reasoning_effort 的合法值集合(2026-09 实测 glm-5.3-flash 只认
+    # low/high/max,medium/none/xhigh 全 400;且不能按 family 前缀推断,逐模型实测)。
+    reasoning_effort_values: frozenset[str] | None = None
+    # 非流式响应里 reasoning item 是否稳定出现(2026-09 实测 glm-5.3-flash
+    # 同 effort 下约半数响应只有 message 没有 reasoning item;流式不受影响)。
+    reasoning_item_reliable: bool | None = None
 
 
 def _classify_responses_error(status: int, body: str) -> Verdict:
@@ -336,3 +346,247 @@ def _finalize(caps: ModelCapabilities) -> ModelCapabilities:
         # 因为转换层对 chat 模型是确定可用的,而直连 responses 在 unknown 下有风险
         caps.preferred_protocol = "chat"
     return caps
+
+
+# ---------------------------------------------------------------------------
+# Opt-in 贵探测:store 会话链 / reasoning_effort 值域 / reasoning item 可靠性
+# 这三个探测各需多次真实请求,默认不并入 probe_responses_capability,由调用方按需触发。
+# 全部遵循同一铁律:只在确凿证据下置 True/False,故障/超时/不确定一律留 None(未探)。
+# ---------------------------------------------------------------------------
+
+# reasoning_effort 候选值,覆盖 OpenAI/Codex 主流档 + glm 的 max。
+_EFFORT_CANDIDATES = ("none", "minimal", "low", "medium", "high", "xhigh", "max")
+
+
+def probe_extended_capability(
+    client: httpx.Client | httpx.AsyncClient,
+    base: str,
+    key: str,
+    model: str,
+    timeout: float = 60.0,
+):
+    """按需探测 store/reasoning 三项能力,返回填充了对应字段的 ModelCapabilities。
+
+    - ``store_supported``: store=true 拿 response_id,再用 previous_response_id
+      追问一个只有上一轮才知道的事实;答出=真支持,答不出=假支持(静默丢历史)。
+    - ``reasoning_effort_values``: 逐个候选值发最小请求,200=接受,400=拒绝;
+      其余(超时/5xx)不计入(故障≠值域缺失)。
+    - ``reasoning_item_reliable``: 非流式带 reasoning 请求,检查 output 是否含
+      reasoning item。单次缺席不足以判 False(可能模型本来没想),需 N 次全缺席才判。
+
+    按 client 类型分发:sync 返回 ModelCapabilities,async 返回 coroutine。
+    """
+    if isinstance(client, httpx.AsyncClient):
+        return _probe_extended_async(client, base, key, model, timeout)
+    if isinstance(client, httpx.Client):
+        return _probe_extended_sync(client, base, key, model, timeout)
+    raise TypeError(f"client 必须是 httpx.Client/AsyncClient,不是 {type(client).__name__}")
+
+
+def _reasoning_item_present(data: Any) -> bool:
+    if not isinstance(data, dict):
+        return False
+    return any(
+        isinstance(item, dict) and item.get("type") == "reasoning"
+        for item in data.get("output", [])
+    )
+
+
+def _post_json(client, url, payload, headers, timeout):
+    """统一 sync post + json 解析;返回 (status, data) 或 None(故障)。"""
+    try:
+        r = client.post(url, json=payload, headers=headers, timeout=timeout)
+    except (httpx.TimeoutException, httpx.ConnectError, httpx.HTTPError):
+        return None
+    try:
+        return r.status_code, r.json()
+    except ValueError:
+        return r.status_code, None
+
+
+async def _post_json_async(client, url, payload, headers, timeout):
+    try:
+        r = await client.post(url, json=payload, headers=headers, timeout=timeout)
+    except (httpx.TimeoutException, httpx.ConnectError, httpx.HTTPError):
+        return None
+    try:
+        return r.status_code, r.json()
+    except ValueError:
+        return r.status_code, None
+
+
+def _store_first_payload(model: str, marker: str) -> dict:
+    return {
+        "model": model,
+        "input": f"记住代号 {marker},只回 OK",
+        "max_output_tokens": 200,
+        "store": True,
+    }
+
+
+def _probe_store_sync(client, url, headers, model, timeout):
+    marker = "cobalt-9173"
+    first = _post_json(client, url, _store_first_payload(model, marker), headers, timeout)
+    if not first or first[0] != 200 or not isinstance(first[1], dict):
+        return None
+    rid = first[1].get("id")
+    if not rid:
+        return None
+    second = _post_json(
+        client,
+        url,
+        {"model": model, "input": "我刚才让你记的代号是什么?只回答代号",
+         "max_output_tokens": 200, "previous_response_id": rid},
+        headers,
+        timeout,
+    )
+    if not second or second[0] != 200 or not isinstance(second[1], dict):
+        return None
+    text = "".join(
+        c.get("text", "")
+        for item in second[1].get("output", [])
+        if isinstance(item, dict) and item.get("type") == "message"
+        for c in item.get("content", [])
+        if isinstance(c, dict)
+    )
+    return marker in text
+
+
+async def _probe_store_async(client, url, headers, model, timeout):
+    marker = "cobalt-9173"
+    first = await _post_json_async(
+        client, url, _store_first_payload(model, marker), headers, timeout
+    )
+    if not first or first[0] != 200 or not isinstance(first[1], dict):
+        return None
+    rid = first[1].get("id")
+    if not rid:
+        return None
+    second = await _post_json_async(
+        client,
+        url,
+        {"model": model, "input": "我刚才让你记的代号是什么?只回答代号",
+         "max_output_tokens": 200, "previous_response_id": rid},
+        headers,
+        timeout,
+    )
+    if not second or second[0] != 200 or not isinstance(second[1], dict):
+        return None
+    text = "".join(
+        c.get("text", "")
+        for item in second[1].get("output", [])
+        if isinstance(item, dict) and item.get("type") == "message"
+        for c in item.get("content", [])
+        if isinstance(c, dict)
+    )
+    return marker in text
+
+
+def _probe_effort_values_sync(client, url, headers, model, timeout):
+    accepted = set()
+    saw_any = False
+    for eff in _EFFORT_CANDIDATES:
+        res = _post_json(
+            client,
+            url,
+            {"model": model, "input": "hi", "max_output_tokens": 30,
+             "reasoning": {"effort": eff}},
+            headers,
+            timeout,
+        )
+        if res is None:
+            continue  # 故障,不计入
+        status, _ = res
+        saw_any = True
+        if status == 200:
+            accepted.add(eff)
+        # 400 = 明确拒绝该值,不计入 accepted
+    return frozenset(accepted) if saw_any else None
+
+
+async def _probe_effort_values_async(client, url, headers, model, timeout):
+    accepted = set()
+    saw_any = False
+    for eff in _EFFORT_CANDIDATES:
+        res = await _post_json_async(
+            client,
+            url,
+            {"model": model, "input": "hi", "max_output_tokens": 30,
+             "reasoning": {"effort": eff}},
+            headers,
+            timeout,
+        )
+        if res is None:
+            continue
+        status, _ = res
+        saw_any = True
+        if status == 200:
+            accepted.add(eff)
+    return frozenset(accepted) if saw_any else None
+
+
+def _probe_reasoning_reliable_sync(client, url, headers, model, timeout, trials=3):
+    """N 次非流式全缺席 reasoning item 才判 False;任一故障或出现就留 None/True。"""
+    absences = 0
+    for _ in range(trials):
+        res = _post_json(
+            client,
+            url,
+            {"model": model, "input": "9.11 和 9.9 哪个大?", "max_output_tokens": 600,
+             "reasoning": {"effort": "low"}},
+            headers,
+            timeout,
+        )
+        if res is None or res[0] != 200:
+            return None  # 故障,无法判定
+        if _reasoning_item_present(res[1]):
+            return True
+        absences += 1
+    return False if absences == trials else None
+
+
+async def _probe_reasoning_reliable_async(client, url, headers, model, timeout, trials=3):
+    absences = 0
+    for _ in range(trials):
+        res = await _post_json_async(
+            client,
+            url,
+            {"model": model, "input": "9.11 和 9.9 哪个大?", "max_output_tokens": 600,
+             "reasoning": {"effort": "low"}},
+            headers,
+            timeout,
+        )
+        if res is None or res[0] != 200:
+            return None
+        if _reasoning_item_present(res[1]):
+            return True
+        absences += 1
+    return False if absences == trials else None
+
+
+def _probe_extended_sync(client, base, key, model, timeout) -> ModelCapabilities:
+    caps = ModelCapabilities(checked_at=time.time(), verdict="unknown")
+    url = f"{base.rstrip('/')}/responses"
+    headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
+    caps.store_supported = _probe_store_sync(client, url, headers, model, timeout)
+    caps.reasoning_effort_values = _probe_effort_values_sync(
+        client, url, headers, model, timeout
+    )
+    caps.reasoning_item_reliable = _probe_reasoning_reliable_sync(
+        client, url, headers, model, timeout
+    )
+    return caps
+
+
+async def _probe_extended_async(client, base, key, model, timeout) -> ModelCapabilities:
+    caps = ModelCapabilities(checked_at=time.time(), verdict="unknown")
+    url = f"{base.rstrip('/')}/responses"
+    headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
+    caps.store_supported = await _probe_store_async(client, url, headers, model, timeout)
+    caps.reasoning_effort_values = await _probe_effort_values_async(
+        client, url, headers, model, timeout
+    )
+    caps.reasoning_item_reliable = await _probe_reasoning_reliable_async(
+        client, url, headers, model, timeout
+    )
+    return caps

ksadk/model_proxy/server.py

@@ -77,16 +77,19 @@ def _emit_completed(
     config.emit("proxy.completed", payload)
 
 
+def _upstream_error_detail(status_code: int) -> dict[str, object]:
+    return {
+        "type": "rate_limit_error" if status_code == 429 else "upstream_error",
+        "code": "rate_limit_exceeded" if status_code == 429 else "upstream_error",
+        "message": f"The model upstream rejected the request (HTTP {status_code}).",
+    }
+
+
 def _upstream_error(status_code: int) -> JSONResponse:
     """Return a stable public error without relaying an upstream traceback."""
     return JSONResponse(
         status_code=status_code,
-        content={
-            "error": {
-                "type": "upstream_error",
-                "message": "The model upstream rejected the request.",
-            }
-        },
+        content={"error": _upstream_error_detail(status_code)},
     )
 
 
@@ -248,9 +251,10 @@ def create_app(config: ProxyConfig) -> FastAPI:
 async def _chat_passthrough_stream(config: ProxyConfig, base: str, headers: dict, body: dict):
     """chat SSE 字节级透传(不转换),让前缀缓存/流式格式与直连一致。"""
     try:
+        stream_headers = {**headers, "Accept": "text/event-stream"}
         async with httpx.AsyncClient(timeout=config.timeout) as c:
             async with c.stream(
-                "POST", f"{base}/chat/completions", json=body, headers=headers
+                "POST", f"{base}/chat/completions", json=body, headers=stream_headers
             ) as r:
                 async for line in r.aiter_lines():
                     yield line + "\n"
@@ -275,10 +279,11 @@ async def _stream_gen(
     for e in s.start():
         yield e
     try:
+        stream_headers = {**headers, "Accept": "text/event-stream"}
         # 超时必须有界(config.timeout):无限超时的活动 SSE 会让 stop() 后线程仍存活
         async with httpx.AsyncClient(timeout=config.timeout) as c:
             async with c.stream(
-                "POST", f"{base}/chat/completions", json=chat_req, headers=headers
+                "POST", f"{base}/chat/completions", json=chat_req, headers=stream_headers
             ) as r:
                 config.emit(
                     "proxy.upstream",
@@ -308,7 +313,7 @@ async def _stream_gen(
                             "type": "response.failed",
                             "response": {
                                 **s._resp("failed"),
-                                "error": {"message": "The model upstream rejected the request."},
+                                "error": _upstream_error_detail(r.status_code),
                             },
                         },
                     )

ksadk/model_proxy/transform.py

@@ -7,6 +7,7 @@ codex_responses_sse.rs,用 Python 重写。本模块只做纯函数/纯状态机
 
 import json
 import time
+from dataclasses import dataclass
 
 
 class UnsupportedToolsError(ValueError):
@@ -234,18 +235,83 @@ _EFFORT_CAP_PREFIXES = (
     ("qwen3.5", "high"),
 )
 
+# 各上游模型的 reasoning_effort 合法值集合(2026-09 实测,见 tests/model_proxy)。
+# 与 _EFFORT_CAP_PREFIXES 的区别:cap 是"单调钳顶"(qwen 超 cap 钳到 cap);
+# 这里是"值域裁剪"——glm-5.3-flash 是始终思考模型,合法值只有 low/high/max,
+# none/minimal/medium/xhigh 全部 400,无法用单调钳顶表达。
+_EFFORT_ALLOWED_SETS = {
+    "glm-5.3-flash": ("low", "high", "max"),
+}
+# 值域裁剪用的档位表:max 视为与 xhigh 同级(5),仅在值域裁剪内部使用,
+# 不改 _EFFORT_RANK(影响 cap 路径)。
+_ALLOWED_RANK = {**_EFFORT_RANK, "max": 5}
+
+
+@dataclass(frozen=True)
+class ReasoningEffortPolicy:
+    """Immutable inputs to the versioned effort projection algorithm."""
+
+    version: str
+    ranks: tuple[tuple[str, int], ...]
+    allowed_ranks: tuple[tuple[str, int], ...]
+    allowed_sets: tuple[tuple[str, tuple[str, ...]], ...]
+    caps: tuple[tuple[str, str], ...]
+
+
+def reasoning_effort_policy() -> ReasoningEffortPolicy:
+    return ReasoningEffortPolicy(
+        version="model-effort-map/v1",
+        ranks=tuple(_EFFORT_RANK.items()),
+        allowed_ranks=tuple(_ALLOWED_RANK.items()),
+        allowed_sets=tuple(
+            (prefix, tuple(values)) for prefix, values in _EFFORT_ALLOWED_SETS.items()
+        ),
+        caps=tuple(_EFFORT_CAP_PREFIXES),
+    )
+
+
+def remap_reasoning_effort(model, effort, *, policy: ReasoningEffortPolicy | None = None):
+    """把 reasoning_effort 向上取整到该模型的合法值集合(值域裁剪)。
+
+    规则:档位 >= 入参的最近合法档;无更高档则取集合最高档;未知档位取集合最低档。
+    未列出的模型/非字符串原样返回(不做发明式映射)。
+
+    实测:glm-5.3-flash 始终思考,medium/xhigh/none/minimal 全 400,
+    medium→high、xhigh→max、none/minimal→low。
+    """
+    if not isinstance(model, str) or not isinstance(effort, str):
+        return effort
+    policy = policy or reasoning_effort_policy()
+    allowed_ranks = dict(policy.allowed_ranks)
+    allowed = None
+    for prefix, vals in policy.allowed_sets:
+        if model.startswith(prefix):
+            allowed = vals
+            break
+    if not allowed or effort in allowed:
+        return effort
+    r = allowed_ranks.get(effort)
+    if r is None:
+        return allowed[0]
+    higher = [v for v in allowed if allowed_ranks[v] >= r]
+    return higher[0] if higher else allowed[-1]
+
 
-def clamp_reasoning_effort(model, effort):
-    """把超出上游模型族支持上限的 reasoning_effort 钳到最高合法档。
+def clamp_reasoning_effort(model, effort, *, policy: ReasoningEffortPolicy | None = None):
+    """把 reasoning_effort 适配到上游模型:先做值域裁剪,再做上限钳制。
 
-    codex 对自家模型默认发 xhigh;qwen3.7 系上游 400,需钳到 high。
+    值域裁剪(remap_reasoning_effort)处理非单调值域(如 glm-5.3-flash 只认
+    low/high/max);上限钳制处理单调超 cap(如 qwen3.7 xhigh→high)。
     未知档位/未知模型族原样返回(不做发明式映射)。
     """
-    if not isinstance(effort, str) or effort not in _EFFORT_RANK:
+    policy = policy or reasoning_effort_policy()
+    effort = remap_reasoning_effort(model, effort, policy=policy)
+    ranks = dict(policy.ranks)
+    if not isinstance(effort, str) or effort not in ranks:
         return effort
-    for prefix, cap in _EFFORT_CAP_PREFIXES:
+    for prefix, cap in policy.caps:
         if isinstance(model, str) and model.startswith(prefix):
-            if _EFFORT_RANK[effort] > _EFFORT_RANK[cap]:
+            if ranks[effort] > ranks[cap]:
                 return cap
             return effort
     return effort

ksadk/plugins/__init__.py

@@ -1,4 +1,4 @@
-"""Versioned contracts for the Phase 2 plugin composition boundary.
+"""Versioned contracts for the Release plugin composition boundary.
 
 This package models discovery, deterministic locking, and the controlled
 PluginHost lifecycle.  It does not create a second runtime/event store;

ksadk/plugins/bridges/dsh.py

@@ -32,6 +32,11 @@ except ImportError:  # pragma: no cover - DSH production hosts are Unix
 import yaml
 from pydantic import BaseModel, ConfigDict
 
+from ksadk.plugins.bridges.dsh_profile_manifest import (
+    bundle_patch,
+    profile_bundles,
+    profile_dependencies,
+)
 from ksadk.plugins.dsh_installation_digest import (
     DshInstallationDigestError,
     installation_digest,
@@ -217,6 +222,16 @@ def dsh_subprocess_environment(*, dsh_home: Path | None = None) -> dict[str, str
     }
     if "PATH" not in environment:
         environment["PATH"] = os.defpath
+    # DSH invokes pnpm by name for Profile mutations. A verified explicit
+    # binary must govern those children as well as the bootstrap/pack step;
+    # otherwise an unrelated package manager on PATH silently takes over.
+    configured_pnpm = Path(os.environ.get("AGENTENGINE_PNPM_BIN", ""))
+    if (
+        configured_pnpm.is_absolute()
+        and configured_pnpm.name in {"pnpm", "pnpm.cmd", "pnpm.exe"}
+        and configured_pnpm.is_file()
+    ):
+        environment["PATH"] = str(configured_pnpm.parent) + os.pathsep + environment["PATH"]
     if dsh_home is not None:
         environment["DSH_HOME"] = str(dsh_home)
     return environment
@@ -828,32 +843,15 @@ class DshProfilePluginBridge:
 
     @staticmethod
     def _dependencies(manifest: Mapping[str, object]) -> dict[str, str]:
-        raw = manifest.get("dependencies")
-        if raw is None:
-            return {}
-        if not isinstance(raw, dict) or any(
-            not isinstance(name, str) or not isinstance(value, str) for name, value in raw.items()
-        ):
-            raise DshBridgeError("DSH profile dependencies are invalid")
-        return dict(raw)
+        return profile_dependencies(manifest, error_type=DshBridgeError)
 
     @staticmethod
     def _bundles(manifest: Mapping[str, object]) -> list[str]:
-        dsh = manifest.get("dsh")
-        profile = dsh.get("profile") if isinstance(dsh, dict) else None
-        bundles = profile.get("bundles") if isinstance(profile, dict) else None
-        if bundles is None:
-            return []
-        if not isinstance(bundles, list) or any(not isinstance(item, str) for item in bundles):
-            raise DshBridgeError("DSH profile bundle order is invalid")
-        return list(bundles)
+        return profile_bundles(manifest, error_type=DshBridgeError)
 
     @staticmethod
     def _bundle_patch(package: Mapping[str, object]) -> str | None:
-        dsh = package.get("dsh")
-        bundle = dsh.get("bundle") if isinstance(dsh, dict) else None
-        patch = bundle.get("patch") if isinstance(bundle, dict) else None
-        return patch.strip() if isinstance(patch, str) and patch.strip() else None
+        return bundle_patch(package)
 
     def _require_bundle(self, name: str) -> None:
         package = self._read_package(name)
@@ -998,6 +996,17 @@ class DshProfilePluginBridge:
     def _prepare_source(self, source: str) -> _PreparedSource:
         value = source.strip()
         candidate = Path(value).expanduser()
+        if not candidate.is_absolute():
+            # dsh CLI 以 Profile 目录为 cwd 解析 add 的源参数；相对当前工作目录
+            # 存在的本地源必须先绝对化，否则会被写成指向不存在位置的 link: 依赖。
+            workspace_relative = self._cwd / candidate
+            if workspace_relative.exists():
+                candidate = workspace_relative
+            elif value.endswith(".tgz"):
+                raise DshPluginMutationError(
+                    f"local DSH plugin source does not exist: {value} "
+                    f"(resolved against {self._cwd})"
+                )
         if not candidate.is_absolute() or not candidate.exists():
             return _PreparedSource(value, "", "tgz", "")
         local = candidate.resolve()

ksadk/plugins/bridges/dsh_profile_manifest.py

@@ -0,0 +1,36 @@
+"""Pure validation and projection of DSH profile and bundle manifests."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+
+def profile_dependencies(
+    manifest: Mapping[str, object], *, error_type: type[Exception],
+) -> dict[str, str]:
+    raw = manifest.get("dependencies")
+    if raw is None:
+        return {}
+    if not isinstance(raw, dict) or any(
+        not isinstance(name, str) or not isinstance(value, str) for name, value in raw.items()
+    ):
+        raise error_type("DSH profile dependencies are invalid")
+    return dict(raw)
+
+
+def profile_bundles(manifest: Mapping[str, object], *, error_type: type[Exception]) -> list[str]:
+    dsh = manifest.get("dsh")
+    profile = dsh.get("profile") if isinstance(dsh, dict) else None
+    bundles = profile.get("bundles") if isinstance(profile, dict) else None
+    if bundles is None:
+        return []
+    if not isinstance(bundles, list) or any(not isinstance(item, str) for item in bundles):
+        raise error_type("DSH profile bundle order is invalid")
+    return list(bundles)
+
+
+def bundle_patch(package: Mapping[str, object]) -> str | None:
+    dsh = package.get("dsh")
+    bundle = dsh.get("bundle") if isinstance(dsh, dict) else None
+    patch = bundle.get("patch") if isinstance(bundle, dict) else None
+    return patch.strip() if isinstance(patch, str) and patch.strip() else None