agentengine-sdk-python 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

ksadk/model_proxy/namespace.py

@@ -23,6 +23,7 @@ chat completions 只认顶层 ``function`` 工具(chat 嵌套)和 ``function.nam
 from __future__ import annotations
 
 import hashlib
+import json
 from typing import Any
 
 CHAT_TOOL_NAME_MAX_LEN = 64
@@ -64,19 +65,37 @@ def build_restore_map(tools: list[Any] | None) -> dict[str, dict[str, str]]:
     if not tools:
         return restore
     for tool in tools:
-        if not isinstance(tool, dict) or tool.get("type") != "namespace":
+        if not isinstance(tool, dict):
+            continue
+        if tool.get("type") == "custom":
+            # custom 工具（如 apply_patch freeform）拍平为普通 function 转发，
+            # 响应侧据此把 function_call 还原成 custom_tool_call
+            custom_name = (tool.get("name") or "").strip()
+            if custom_name:
+                restore.setdefault(
+                    custom_name,
+                    {"custom": "true", "namespace": "", "name": custom_name},
+                )
+            continue
+        if tool.get("type") != "namespace":
             continue
         namespace = (tool.get("name") or "").strip()
         if not namespace:
             continue
         for child in _namespace_children(tool):
-            if not isinstance(child, dict) or child.get("type") != "function":
+            if not isinstance(child, dict) or child.get("type") not in {
+                "function",
+                "custom",
+            }:
                 continue
             name = (child.get("name") or "").strip()
             if not name:
                 continue
             flat = flatten_namespace_tool_name(namespace, name)
-            restore.setdefault(flat, {"namespace": namespace, "name": name})
+            entry = {"namespace": namespace, "name": name}
+            if child.get("type") == "custom":
+                entry["custom"] = "true"
+            restore.setdefault(flat, entry)
     return restore
 
 
@@ -91,7 +110,7 @@ def _rewrite_qualified_calls(value: Any, owners: dict[str, dict[str, str]]) -> b
         for item in value:
             changed |= _rewrite_qualified_calls(item, owners)
     elif isinstance(value, dict):
-        if value.get("type") == "function_call":
+        if value.get("type") in {"function_call", "custom_tool_call"}:
             namespace = (value.get("namespace") or "").strip()
             name = (value.get("name") or "").strip()
             if namespace and name:
@@ -129,24 +148,39 @@ def flatten_request_namespaces(body: dict) -> dict[str, dict[str, str]]:
         if tool.get("type") == "namespace":
             namespace = (tool.get("name") or "").strip()
             for child in _namespace_children(tool):
-                if not isinstance(child, dict) or child.get("type") != "function":
+                if not isinstance(child, dict) or child.get("type") not in {
+                    "function",
+                    "custom",
+                }:
                     continue
                 name = (child.get("name") or "").strip()
                 if not name or not namespace:
                     continue
                 flat = flatten_namespace_tool_name(namespace, name)
                 if flat in seen_flat:
-                    raise ValueError(
-                        f"namespace 拍平撞名:{flat} 来自不同 child,上游无法消歧"
-                    )
+                    raise ValueError(f"namespace 拍平撞名:{flat} 来自不同 child,上游无法消歧")
                 seen_flat.add(flat)
-                flat_tools.append({
-                    "type": "function",
-                    "name": flat,
-                    "description": child.get("description", ""),
-                    "parameters": child.get("parameters", {"type": "object", "properties": {}}),
-                    **({"strict": child["strict"]} if "strict" in child else {}),
-                })
+                if child.get("type") == "custom":
+                    flat_tools.append(
+                        {
+                            "type": "custom",
+                            "name": flat,
+                            "description": child.get("description", ""),
+                            **({"format": child["format"]} if "format" in child else {}),
+                        }
+                    )
+                else:
+                    flat_tools.append(
+                        {
+                            "type": "function",
+                            "name": flat,
+                            "description": child.get("description", ""),
+                            "parameters": child.get(
+                                "parameters", {"type": "object", "properties": {}}
+                            ),
+                            **({"strict": child["strict"]} if "strict" in child else {}),
+                        }
+                    )
         else:
             flat_tools.append(tool)
     body["tools"] = flat_tools
@@ -168,6 +202,24 @@ def restore_function_call(item: dict, restore_map: dict[str, dict[str, str]]) ->
     flat = item.get("name")
     entry = restore_map.get(flat) if isinstance(flat, str) else None
     if entry:
+        if entry.get("custom") == "true":
+            # function_call(JSON arguments) -> custom_tool_call(原始文本 input)
+            raw_args = item.pop("arguments", "") or ""
+            try:
+                payload = json.loads(raw_args)
+                text_input = (
+                    payload.get("input", raw_args) if isinstance(payload, dict) else raw_args
+                )
+            except Exception:
+                text_input = raw_args
+            item["type"] = "custom_tool_call"
+            item["name"] = entry["name"]
+            item["input"] = text_input
+            if entry.get("namespace"):
+                item["namespace"] = entry["namespace"]
+            else:
+                item.pop("namespace", None)
+            return item
         item["name"] = entry["name"]
         item["namespace"] = entry["namespace"]
     return item

ksadk/model_proxy/server.py

@@ -18,11 +18,65 @@ from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse, StreamingResponse
 
 from .config import _LOOPBACK_HOSTS, ProxyConfig
-from .transform import Streamer, UnsupportedToolsError, chat_to_response, responses_to_chat
+from .transform import (
+    Streamer,
+    UnsupportedToolsError,
+    chat_to_response,
+    clamp_reasoning_effort,
+    responses_to_chat,
+)
 
 logger = logging.getLogger(__name__)
 
 
+def _request_id(response: httpx.Response) -> str:
+    for name in (
+        "x-request-id",
+        "request-id",
+        "x-ks-request-id",
+        "x-amzn-requestid",
+    ):
+        value = response.headers.get(name)
+        if value:
+            return str(value)
+    return ""
+
+
+def _reported_usage(raw: object) -> dict[str, int] | None:
+    if not isinstance(raw, dict):
+        return None
+    prompt_details = raw.get("prompt_tokens_details") or {}
+    completion_details = raw.get("completion_tokens_details") or {}
+    return {
+        "inputTokens": int(raw.get("prompt_tokens") or 0),
+        "outputTokens": int(raw.get("completion_tokens") or 0),
+        "totalTokens": int(raw.get("total_tokens") or 0),
+        "cachedInputTokens": int(prompt_details.get("cached_tokens") or 0),
+        "reasoningOutputTokens": int(completion_details.get("reasoning_tokens") or 0),
+    }
+
+
+def _emit_completed(
+    config: ProxyConfig,
+    *,
+    response_id: str,
+    model: object,
+    status_code: int,
+    started: float,
+    usage: object = None,
+) -> None:
+    payload: dict[str, object] = {
+        "responseId": response_id,
+        "model": str(model or ""),
+        "statusCode": status_code,
+        "durationMs": max(0, int((time.monotonic() - started) * 1000)),
+    }
+    reported = _reported_usage(usage)
+    if reported is not None:
+        payload["usage"] = reported
+    config.emit("proxy.completed", payload)
+
+
 def _upstream_error(status_code: int) -> JSONResponse:
     """Return a stable public error without relaying an upstream traceback."""
     return JSONResponse(
@@ -98,8 +152,8 @@ def create_app(config: ProxyConfig) -> FastAPI:
         body = await req.json()
         try:
             chat_req, restore_map = responses_to_chat(body)
-        except UnsupportedToolsError as e:
-            logger.info("responses request uses unsupported tools: %s", e)
+        except UnsupportedToolsError:
+            logger.info("responses request uses unsupported tools", exc_info=True)
             return JSONResponse(
                 status_code=400,
                 content={
@@ -109,22 +163,84 @@ def create_app(config: ProxyConfig) -> FastAPI:
                     }
                 },
             )
+        # codex 会对内建能力发内部伪模型名(如 auto_review guardian 用 codex-auto-review),
+        # 单上游代理必须落回配置的真实模型,否则上游按未知模型 403。
+        # 真实模型名(codex 端已配置 model= 或 thread 级 model 覆盖)必须原样透传:
+        # RunAgent 的 Model 覆盖靠它生效,整体改写会把覆盖吞掉(终验 403 根因)。
+        requested_model = str(chat_req.get("model") or "")
+        if (
+            config.upstream_model
+            and requested_model.startswith("codex-")
+            and requested_model != config.upstream_model
+        ):
+            logger.debug(
+                "responses pseudo model rewrite: %s -> %s",
+                requested_model,
+                config.upstream_model,
+            )
+            chat_req["model"] = config.upstream_model
+        # 上游模型族的 reasoning_effort 上限不同(qwen3.7 对 xhigh 400),
+        # 按改写后的真实上游模型钳位(codex 对自家模型默认发 xhigh)。
+        if chat_req.get("reasoning_effort"):
+            chat_req["reasoning_effort"] = clamp_reasoning_effort(
+                chat_req["model"], chat_req["reasoning_effort"]
+            )
         rid = "resp_" + uuid.uuid4().hex[:24]
         model = body.get("model")
+        started = time.monotonic()
+        config.emit(
+            "proxy.requested",
+            {
+                "responseId": rid,
+                "model": str(model or ""),
+                "protocol": "responses-to-chat",
+                "stream": bool(body.get("stream")),
+            },
+        )
         if body.get("stream"):
             chat_req["stream"] = True
             chat_req["stream_options"] = {"include_usage": True}
             return StreamingResponse(
-                _stream_gen(config, base, headers, chat_req, rid, model, cancel, restore_map),
+                _stream_gen(
+                    config,
+                    base,
+                    headers,
+                    chat_req,
+                    rid,
+                    model,
+                    cancel,
+                    restore_map,
+                    started,
+                ),
                 media_type="text/event-stream",
                 headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
             )
         async with httpx.AsyncClient(timeout=config.timeout) as c:
             r = await c.post(f"{base}/chat/completions", json=chat_req, headers=headers)
+            config.emit(
+                "proxy.upstream",
+                {"requestId": _request_id(r), "statusCode": r.status_code},
+            )
             if r.status_code != 200:
+                _emit_completed(
+                    config,
+                    response_id=rid,
+                    model=model,
+                    status_code=r.status_code,
+                    started=started,
+                )
                 logger.warning("responses upstream rejected request: status=%s", r.status_code)
                 return _upstream_error(r.status_code)
-            return JSONResponse(chat_to_response(r.json(), rid, restore_map))
+            upstream_payload = r.json()
+            _emit_completed(
+                config,
+                response_id=rid,
+                model=model,
+                status_code=r.status_code,
+                started=started,
+                usage=upstream_payload.get("usage"),
+            )
+            return JSONResponse(chat_to_response(upstream_payload, rid, restore_map))
 
     return app
 
@@ -152,7 +268,9 @@ async def _stream_gen(
     model,
     cancel: threading.Event,
     restore_map: dict | None = None,
+    started: float | None = None,
 ):
+    started = time.monotonic() if started is None else started
     s = Streamer(rid, model, restore_map)
     for e in s.start():
         yield e
@@ -162,8 +280,28 @@ async def _stream_gen(
             async with c.stream(
                 "POST", f"{base}/chat/completions", json=chat_req, headers=headers
             ) as r:
+                config.emit(
+                    "proxy.upstream",
+                    {"requestId": _request_id(r), "statusCode": r.status_code},
+                )
                 if r.status_code != 200:
-                    logger.warning("responses upstream stream rejected: status=%s", r.status_code)
+                    _emit_completed(
+                        config,
+                        response_id=rid,
+                        model=model,
+                        status_code=r.status_code,
+                        started=started,
+                    )
+                    logger.warning(
+                        "responses upstream stream rejected: status=%s model=%s tools=%s "
+                        "msgs=%s bytes=%s has_text_format=%s",
+                        r.status_code,
+                        chat_req.get("model"),
+                        len(chat_req.get("tools") or []),
+                        len(chat_req.get("messages") or []),
+                        len(json.dumps(chat_req)),
+                        bool(chat_req.get("response_format")),
+                    )
                     yield Streamer.ev(
                         "response.failed",
                         {
@@ -177,6 +315,14 @@ async def _stream_gen(
                     return
                 async for line in r.aiter_lines():
                     if cancel.is_set():
+                        _emit_completed(
+                            config,
+                            response_id=rid,
+                            model=model,
+                            status_code=499,
+                            started=started,
+                            usage=s.usage,
+                        )
                         return  # stop() 置位:主动中断活动 SSE,让线程能及时回收
                     line = line.strip()
                     if not line.startswith("data:"):
@@ -191,6 +337,14 @@ async def _stream_gen(
                     for e in s.handle(chunk):
                         yield e
     except Exception as exc:  # noqa: BLE001
+        _emit_completed(
+            config,
+            response_id=rid,
+            model=model,
+            status_code=502,
+            started=started,
+            usage=s.usage,
+        )
         logger.warning("responses upstream stream failed", exc_info=exc)
         yield Streamer.ev(
             "response.failed",
@@ -205,6 +359,14 @@ async def _stream_gen(
         return
     for e in s.finalize():
         yield e
+    _emit_completed(
+        config,
+        response_id=rid,
+        model=model,
+        status_code=200,
+        started=started,
+        usage=s.usage,
+    )
 
 
 class ProxyServer:

ksadk/model_proxy/transform.py

@@ -122,6 +122,30 @@ def input_to_messages(inp):
                     },
                 }
             )
+        elif t == "custom_tool_call":
+            # 历史里的 custom_tool_call：还原为 function 调用（input 包进 JSON）
+            pending_tc.append(
+                {
+                    "id": item.get("call_id") or f"call_{len(pending_tc)}",
+                    "type": "function",
+                    "function": {
+                        "name": item.get("name"),
+                        "arguments": json.dumps(
+                            {"input": item.get("input") or ""}, ensure_ascii=False
+                        ),
+                    },
+                }
+            )
+        elif t == "custom_tool_call_output":
+            flush()
+            out = item.get("output")
+            messages.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": item.get("call_id") or "",
+                    "content": out if isinstance(out, str) else json.dumps(out, ensure_ascii=False),
+                }
+            )
         elif t == "function_call_output":
             flush()
             out = item.get("output")
@@ -155,9 +179,30 @@ def convert_tools(tools):
             if "strict" in t:
                 fn["strict"] = t["strict"]
             out.append({"type": "function", "function": fn})
+        elif isinstance(t, dict) and t.get("type") == "custom" and t.get("name"):
+            # custom 工具（apply_patch 等 freeform 输入）转为单 input 字符串参数的 function
+            out.append(
+                {
+                    "type": "function",
+                    "function": {
+                        "name": t.get("name"),
+                        "description": t.get("description", ""),
+                        "parameters": {
+                            "type": "object",
+                            "properties": {"input": {"type": "string"}},
+                            "required": ["input"],
+                        },
+                    },
+                }
+            )
         else:
             t = t or {}
-            unsupported.append(t.get("type") or t.get("name") or "unknown")
+            import json as _json
+
+            try:
+                unsupported.append(_json.dumps(t, ensure_ascii=False)[:300])
+            except Exception:
+                unsupported.append(str(t.get("type") or t.get("name") or "unknown"))
     if unsupported:
         raise UnsupportedToolsError(
             f"不支持转换的 codex 工具类型: {unsupported};"
@@ -180,6 +225,32 @@ def convert_tool_choice(tc):
     return tc
 
 
+# 各上游模型族的 reasoning_effort 上限(qwen3.7 系实测 xhigh 400;报错文案会列出
+# xhigh 但 DashScope 后端实际只认到 high,故不能用报错文案反推)。未列出的族原样透传。
+_EFFORT_RANK = {"none": 0, "minimal": 1, "low": 2, "medium": 3, "high": 4, "xhigh": 5}
+_EFFORT_CAP_PREFIXES = (
+    ("qwen3.7", "high"),
+    ("qwen3.6", "high"),
+    ("qwen3.5", "high"),
+)
+
+
+def clamp_reasoning_effort(model, effort):
+    """把超出上游模型族支持上限的 reasoning_effort 钳到最高合法档。
+
+    codex 对自家模型默认发 xhigh;qwen3.7 系上游 400,需钳到 high。
+    未知档位/未知模型族原样返回(不做发明式映射)。
+    """
+    if not isinstance(effort, str) or effort not in _EFFORT_RANK:
+        return effort
+    for prefix, cap in _EFFORT_CAP_PREFIXES:
+        if isinstance(model, str) and model.startswith(prefix):
+            if _EFFORT_RANK[effort] > _EFFORT_RANK[cap]:
+                return cap
+            return effort
+    return effort
+
+
 def _convert_text_format(fmt):
     """responses text.format -> chat response_format(structured output 结构重组)。
 
@@ -199,6 +270,35 @@ def _convert_text_format(fmt):
     return None
 
 
+def _promote_additional_tools(body):
+    """Promote Codex Harness dynamic tool input items to Responses tools.
+
+    Codex 0.147 no longer always sends tool declarations in the top-level
+    ``tools`` field.  It can prepend one or more developer input items shaped
+    as ``{"type": "additional_tools", "tools": [...]}``.  Chat Completions
+    has no equivalent input item, so the proxy must merge those declarations
+    into the canonical Responses tool list before namespace flattening.
+    """
+
+    inp = body.get("input")
+    if not isinstance(inp, list):
+        return
+    promoted = []
+    retained = []
+    for item in inp:
+        if isinstance(item, dict) and item.get("type") == "additional_tools":
+            tools = item.get("tools")
+            if isinstance(tools, list):
+                promoted.extend(tool for tool in tools if isinstance(tool, dict))
+            continue
+        retained.append(item)
+    if not promoted:
+        return
+    existing = body.get("tools")
+    body["tools"] = (list(existing) if isinstance(existing, list) else []) + promoted
+    body["input"] = retained
+
+
 def responses_to_chat(body):
     """responses 请求 -> chat 请求;返回 (chat_req, restore_map)。
 
@@ -207,6 +307,7 @@ def responses_to_chat(body):
     """
     from .namespace import flatten_request_namespaces
 
+    _promote_additional_tools(body)
     restore_map = flatten_request_namespaces(body)
     out = {"model": body.get("model")}
     msgs = []
@@ -229,8 +330,9 @@ def responses_to_chat(body):
         rf = _convert_text_format(text.get("format"))
         if rf is not None:
             out["response_format"] = rf
-        if text.get("verbosity"):
-            out["verbosity"] = text["verbosity"]
+        # text.verbosity("low"/"high")不转发:chat completions 无标准字段,
+        # kspmas 把顶层 verbosity 反序列化为 i32,字符串值直接 400(glm-5.2 实测;
+        # cc-switch 也不透传该字段)。
     if body.get("prompt_cache_key"):
         out["prompt_cache_key"] = body["prompt_cache_key"]
     tools = convert_tools(body.get("tools"))

ksadk/observability/__init__.py

@@ -0,0 +1,25 @@
+"""Local observability exports and trajectory projections."""
+
+from ksadk.observability.session_log import (
+    SESSION_LOG_SCHEMA,
+    SessionLogError,
+    SessionLogResult,
+    export_session_log,
+    verify_session_log,
+)
+from ksadk.observability.trajectory import (
+    PROJECTION_VERSION,
+    encode_sse,
+    project_trajectory_event,
+)
+
+__all__ = [
+    "SESSION_LOG_SCHEMA",
+    "PROJECTION_VERSION",
+    "SessionLogError",
+    "SessionLogResult",
+    "export_session_log",
+    "encode_sse",
+    "project_trajectory_event",
+    "verify_session_log",
+]