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

ksadk/harness/engine/policy_runtime.py

@@ -15,7 +15,8 @@ def configure_run(engine, run, *, policy=None, resolver=None, request=None):
     run.execution_policy = policy
     run.execution_policy_resolver = resolver
     run.execution_policy_request = request
-    run.tools = dict(engine._tools)
+    run.exclusive_tools = bool(policy and policy.exclusive_tools)
+    run.tools = {} if run.exclusive_tools and inherited is None else dict(engine._tools)
     run.policy_tool_names = set(inherited or ())
     if policy is not None and inherited is None:
         run.tools.update(policy.tools)
@@ -24,11 +25,12 @@ def configure_run(engine, run, *, policy=None, resolver=None, request=None):
     if policy is not None:
         run.approval_required.update(policy.approval_required)
     _apply_request_approval_mode(run, request)
-    _apply_request_approval_mode(run, request)
     run.sub_agents = {
         **engine._sub_agents,
         **{b.name: SubAgentSpec.from_binding(b) for b in run.compiled.spec.sub_agents},
     }
+    if run.exclusive_tools:
+        run.sub_agents = {}
     run.controller = engine._new_run_controller(run.compiled)
 
 
@@ -40,18 +42,29 @@ async def revalidate_policy(engine, run):
     if not isinstance(policy, ExecutionPolicy):
         raise TypeError("host resolver must return ExecutionPolicy")
     # A refreshed grant can narrow an admitted run, never grow its tool surface.
-    allowed = {name: tool for name, tool in engine._tools.items()
-               if name not in run.policy_tool_names}
-    allowed.update({name: tool for name, tool in policy.tools.items()
-                    if name in run.policy_tool_names})
+    run.exclusive_tools = run.exclusive_tools or policy.exclusive_tools
+    if run.exclusive_tools:
+        run.sub_agents = {}
+    allowed = {
+        name: tool
+        for name, tool in engine._tools.items()
+        if name not in run.policy_tool_names and not run.exclusive_tools
+    }
+    allowed.update(
+        {name: tool for name, tool in policy.tools.items() if name in run.policy_tool_names}
+    )
     run.tools = {name: allowed[name] for name in run.tools if name in allowed}
-    run.approval_required.update(policy.approval_required)
+    if not run.session_approval_granted:
+        run.approval_required.update(policy.approval_required)
+    else:
+        run.approval_required = set()
     limits_only = ExecutionPolicy(limits=policy.limits)
     run.compiled = replace(
         run.compiled, spec=apply_execution_policy(run.compiled.spec, limits_only)
     )
     run.execution_policy = policy
 
+
 def _apply_request_approval_mode(run, request) -> None:
     """回合级审批档位（composer 的 完全访问/严格/询问）覆盖静态合同。
 
@@ -65,6 +78,4 @@ def _apply_request_approval_mode(run, request) -> None:
     if mode == "full":
         run.approval_required = set()
     elif mode == "ask":
-        run.approval_required.update(
-            name for name in getattr(run, "tools", {}) or {}
-        )
+        run.approval_required.update(name for name in getattr(run, "tools", {}) or {})

ksadk/harness/engine/postgres_checkpointer.py

@@ -9,8 +9,319 @@
 
 from __future__ import annotations
 
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
 from typing import Any
 
+from ksadk.sessions.db_budget import (
+    DatabaseBudget,
+    DatabaseOperationDeadline,
+    session_db_budget,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class CheckpointCommitUnknown(RuntimeError):
+    """A checkpoint write may have committed; never replay graph/tool work."""
+
+    def __init__(self, thread_id: str, checkpoint_id: str, operation: str) -> None:
+        self.thread_id = thread_id
+        self.checkpoint_id = checkpoint_id
+        self.operation = operation
+        super().__init__(
+            f"{operation} commit outcome unknown for thread={thread_id} checkpoint={checkpoint_id}"
+        )
+
+
+def _commit_outcome_uncertain(exc: Exception) -> bool:
+    """Only transport/timeout failures can hide a successful COMMIT."""
+    current: BaseException | None = exc
+    seen: set[int] = set()
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        sqlstate = getattr(current, "sqlstate", None) or getattr(current, "pgcode", None)
+        if sqlstate and not str(sqlstate).startswith(("08", "57P", "58")):
+            return False
+        current = current.__cause__ or current.__context__
+    return isinstance(exc, (TimeoutError, ConnectionError, OSError)) or type(exc).__name__ in {
+        "OperationalError",
+        "InterfaceError",
+    }
+
+
+def bounded_postgres_saver_class() -> Any:
+    """Build a saver that bounds storage phases without timing graph execution."""
+    from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+    from psycopg.rows import dict_row
+    from psycopg_pool import AsyncConnectionPool
+
+    class BoundedAsyncPostgresSaver(AsyncPostgresSaver):
+        def __init__(self, conn: AsyncConnectionPool, *, budget: DatabaseBudget | None = None):
+            super().__init__(conn)
+            self.db_budget = budget or session_db_budget()
+            self._write_phase: ContextVar[bool] = ContextVar(
+                "checkpoint_write_phase", default=False
+            )
+            self._active_connections: dict[asyncio.Task[Any], Any] = {}
+            self._cleanup_deadlines: dict[asyncio.Task[Any], float] = {}
+
+        async def _run_write(
+            self, operation: Any, deadline: DatabaseOperationDeadline | None = None
+        ) -> Any:
+            seconds = (
+                deadline.remaining_seconds()
+                if deadline is not None
+                else self.db_budget.write_operation_seconds
+            )
+            if seconds <= 0:
+                if hasattr(operation, "close"):
+                    operation.close()
+                raise TimeoutError("checkpoint write operation deadline exceeded")
+            token = self._write_phase.set(True)
+            try:
+                task = asyncio.create_task(operation)
+            finally:
+                self._write_phase.reset(token)
+            try:
+                return await asyncio.wait_for(asyncio.shield(task), seconds)
+            except (asyncio.CancelledError, TimeoutError):
+                cleanup_deadline = (
+                    asyncio.get_running_loop().time() + self.db_budget.cleanup_seconds
+                )
+                self._cleanup_deadlines[task] = cleanup_deadline
+                task.cancel()
+                connection = self._active_connections.get(task)
+                if connection is not None:
+                    try:
+                        remaining = max(0.0, cleanup_deadline - asyncio.get_running_loop().time())
+                        if remaining:
+                            await asyncio.wait_for(connection.close(), remaining)
+                        else:
+                            connection.pgconn.finish()
+                    except Exception:
+                        logger.exception("Could not close cancelled checkpoint connection")
+                        connection.pgconn.finish()
+                remaining = max(0.0, cleanup_deadline - asyncio.get_running_loop().time())
+                done, _ = await asyncio.wait(
+                    (task,), timeout=min(remaining, self.db_budget.cleanup_seconds / 2)
+                )
+                if not done:
+                    task.cancel()
+                    remaining = max(0.0, cleanup_deadline - asyncio.get_running_loop().time())
+                    done, _ = await asyncio.wait((task,), timeout=remaining)
+                if done:
+                    await asyncio.gather(task, return_exceptions=True)
+                else:
+                    task.add_done_callback(
+                        lambda finished: finished.exception() if not finished.cancelled() else None
+                    )
+                raise
+            finally:
+                self._cleanup_deadlines.pop(task, None)
+
+        @asynccontextmanager
+        async def _cursor(self, *, pipeline: bool = False):
+            budget = self.db_budget
+            write = pipeline or self._write_phase.get()
+            acquire = budget.write_acquire_seconds if write else budget.read_acquire_seconds
+            sql = budget.write_sql_seconds if write else budget.read_sql_seconds
+            await asyncio.wait_for(self.lock.acquire(), budget.lock_seconds)
+            try:
+                async with self.conn.connection(timeout=acquire) as conn:
+                    current = asyncio.current_task()
+                    if current is not None:
+                        self._active_connections[current] = conn
+                    # Pool connections use autocommit. Restore session GUCs
+                    # before returning them so reads never inherit write limits.
+                    original_error: BaseException | None = None
+                    configured = False
+                    try:
+                        await conn.execute(
+                            f"SET statement_timeout TO '{max(1, int(sql * 1000))}ms'"
+                        )
+                        await conn.execute(
+                            f"SET lock_timeout TO '{max(1, int(budget.lock_seconds * 1000))}ms'"
+                        )
+                        configured = True
+                        if pipeline:
+                            if self.supports_pipeline:
+                                async with (
+                                    conn.pipeline(),
+                                    conn.cursor(binary=True, row_factory=dict_row) as cur,
+                                ):
+                                    yield cur
+                            else:
+                                async with (
+                                    conn.transaction(),
+                                    conn.cursor(binary=True, row_factory=dict_row) as cur,
+                                ):
+                                    yield cur
+                        else:
+                            async with conn.cursor(binary=True, row_factory=dict_row) as cur:
+                                yield cur
+                    except BaseException as exc:
+                        original_error = exc
+                        raise
+                    finally:
+                        try:
+                            if not configured:
+                                await conn.close()
+                            elif not conn.closed:
+                                deadline = self._cleanup_deadlines.get(current)
+                                remaining = (
+                                    max(0.001, deadline - asyncio.get_running_loop().time())
+                                    if deadline is not None
+                                    else budget.cleanup_seconds
+                                )
+                                async with asyncio.timeout(remaining):
+                                    await conn.execute("RESET statement_timeout")
+                                    await conn.execute("RESET lock_timeout")
+                        except BaseException:
+                            try:
+                                await conn.close()
+                            except Exception:
+                                logger.exception(
+                                    "Could not close checkpoint connection after reset failure"
+                                )
+                            if original_error is None:
+                                raise
+                            logger.warning(
+                                "Checkpoint connection reset failed after operation error"
+                            )
+            finally:
+                if current := asyncio.current_task():
+                    self._active_connections.pop(current, None)
+                self.lock.release()
+
+        async def setup(self) -> None:
+            await self._run_write(super().setup())
+
+        async def aput(self, *args: Any, **kwargs: Any) -> Any:
+            deadline = DatabaseOperationDeadline(self.db_budget)
+            try:
+                return await self._run_write(super().aput(*args, **kwargs), deadline)
+            except Exception as exc:
+                if not _commit_outcome_uncertain(exc):
+                    raise
+                config = args[0] if args else kwargs["config"]
+                checkpoint = args[1] if len(args) > 1 else kwargs["checkpoint"]
+                configurable = config["configurable"]
+                receipt = {
+                    "configurable": {
+                        "thread_id": configurable["thread_id"],
+                        "checkpoint_ns": configurable.get("checkpoint_ns", ""),
+                        "checkpoint_id": checkpoint["id"],
+                    }
+                }
+                try:
+                    outcome = await deadline.run(self.reconcile_checkpoint_commit(receipt))
+                except Exception:
+                    outcome = "unknown"
+                if outcome == "committed":
+                    return receipt
+                raise CheckpointCommitUnknown(
+                    configurable["thread_id"], checkpoint["id"], "aput"
+                ) from exc
+
+        async def aput_writes(self, *args: Any, **kwargs: Any) -> Any:
+            deadline = DatabaseOperationDeadline(self.db_budget)
+            try:
+                return await self._run_write(super().aput_writes(*args, **kwargs), deadline)
+            except Exception as exc:
+                if not _commit_outcome_uncertain(exc):
+                    raise
+                config = args[0] if args else kwargs["config"]
+                writes = args[1] if len(args) > 1 else kwargs["writes"]
+                task_id = args[2] if len(args) > 2 else kwargs["task_id"]
+                try:
+                    stored = await deadline.run(self.aget_tuple(config))
+                except Exception:
+                    stored = None
+                if stored is not None and all(
+                    (task_id, channel, value) in stored.pending_writes for channel, value in writes
+                ):
+                    return None
+                address = config["configurable"]
+                raise CheckpointCommitUnknown(
+                    address["thread_id"], address.get("checkpoint_id", ""), "aput_writes"
+                ) from exc
+
+        async def adelete_thread(self, *args: Any, **kwargs: Any) -> Any:
+            try:
+                return await self._run_write(super().adelete_thread(*args, **kwargs))
+            except Exception as exc:
+                if not _commit_outcome_uncertain(exc):
+                    raise
+                thread_id = args[0] if args else kwargs["thread_id"]
+                raise CheckpointCommitUnknown(thread_id, "", "adelete_thread") from exc
+
+        async def aget_tuple(self, *args: Any, **kwargs: Any) -> Any:
+            budget = self.db_budget
+            async with asyncio.timeout(budget.read_acquire_seconds + budget.read_sql_seconds):
+                return await super().aget_tuple(*args, **kwargs)
+
+        async def alist(self, *args: Any, **kwargs: Any):
+            # Upstream fetches all rows before yielding, but keeps its cursor
+            # open while the caller consumes them. Materialize and close first
+            # so consumer/Agent time is never part of a DB deadline.
+            async with asyncio.timeout(
+                self.db_budget.read_acquire_seconds + self.db_budget.read_sql_seconds
+            ):
+                items = [item async for item in super().alist(*args, **kwargs)]
+            for item in items:
+                yield item
+
+        async def reconcile_checkpoint_commit(self, config: Any) -> str:
+            """Confirm a stable checkpoint ID without replaying graph work."""
+            checkpoint_id = str(config.get("configurable", {}).get("checkpoint_id") or "")
+            if not checkpoint_id:
+                return "unknown"
+            try:
+                stored = await self.aget_tuple(config)
+            except Exception:
+                return "unknown"
+            if stored is not None and stored.checkpoint.get("id") == checkpoint_id:
+                return "committed"
+            return "unknown"
+
+    return BoundedAsyncPostgresSaver
+
+
+async def create_bounded_postgres_saver(
+    dsn: str, *, budget: DatabaseBudget | None = None
+) -> tuple[Any, Any]:
+    """Open a bounded psycopg pool and return its saver and owned pool."""
+    from psycopg.rows import dict_row
+    from psycopg_pool import AsyncConnectionPool
+
+    budget = budget or session_db_budget()
+    pool = AsyncConnectionPool(
+        conninfo=dsn,
+        min_size=1,
+        max_size=10,
+        open=False,
+        timeout=budget.write_acquire_seconds,
+        kwargs={
+            "autocommit": True,
+            "prepare_threshold": 0,
+            "row_factory": dict_row,
+            "connect_timeout": max(1, int(budget.connect_seconds + 0.999)),
+            "options": f"-c statement_timeout={max(1, int(budget.write_sql_seconds * 1000))} "
+            f"-c lock_timeout={max(1, int(budget.lock_seconds * 1000))}",
+        },
+    )
+    try:
+        await pool.open(wait=True, timeout=budget.connect_seconds)
+        saver = bounded_postgres_saver_class()(pool, budget=budget)
+        await saver.setup()
+        return saver, pool
+    except BaseException:
+        await pool.close(timeout=budget.cleanup_seconds)
+        raise
+
 
 def postgres_checkpointer(dsn: str) -> Any:
     """Postgres 异步 Checkpointer 的上下文管理器（调用方负责 __aenter__）。
@@ -22,7 +333,7 @@ def postgres_checkpointer(dsn: str) -> Any:
         dsn: Postgres 连接串，如 ``postgresql://user:pass@host:5432/db``。
     """
     try:
-        from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+        import langgraph.checkpoint.postgres.aio  # noqa: F401
     except ImportError as exc:
         raise RuntimeError(
             "Postgres Checkpointer 需要 ksadk[postgres] extra"
@@ -30,7 +341,16 @@ def postgres_checkpointer(dsn: str) -> Any:
             "缺依赖时用 KSADK_CHECKPOINT_DSN 留空走 SQLite 默认。"
         ) from exc
 
-    return AsyncPostgresSaver.from_conn_string(dsn)
+    return _postgres_checkpointer_context(dsn)
+
+
+@asynccontextmanager
+async def _postgres_checkpointer_context(dsn: str) -> Any:
+    saver, pool = await create_bounded_postgres_saver(dsn)
+    try:
+        yield saver
+    finally:
+        await pool.close(timeout=session_db_budget().cleanup_seconds)
 
 
 def is_postgres_configured() -> bool:
@@ -59,5 +379,8 @@ def resolve_checkpointer(checkpoint_path: str | None = None) -> Any:
 __all__ = [
     "is_postgres_configured",
     "postgres_checkpointer",
+    "bounded_postgres_saver_class",
+    "create_bounded_postgres_saver",
+    "CheckpointCommitUnknown",
     "resolve_checkpointer",
 ]

ksadk/harness/engine/run_control_bridge.py

@@ -41,8 +41,28 @@ async def invoke_graph_with_control(
 
 def completion_payload(run: Any) -> dict[str, Any]:
     payload: dict[str, Any] = {"status": "completed"}
+    # 会话串轮修复（交接记录 2026-09-22 §7）：把当前 turn_id 写进 RUN_COMPLETED
+    # payload，让 managed_runtime._project_event 把 output_refs 指向当前轮的
+    # turn 级 final item_id，而不是无 turn 分量的 run 级身份。
+    turn_count = int(getattr(run.state, "turn_count", 0) or 0)
+    if turn_count > 0:
+        run_id = getattr(run.handle, "run_id", "") or ""
+        payload["turn_id"] = f"{run_id}:t{turn_count}"
     if run.controller is not None:
-        payload.update(run.controller.finalize(run.control_events).to_payload())
+        result = run.controller.finalize(run.control_events)
+        payload.update(result.to_payload())
+        # A model response produced only because the controller asked it to
+        # close at a soft budget boundary is a useful partial delivery, not a
+        # verified task completion.  Preserve that distinction for runtime
+        # adapters and Studio instead of flattening it into ``completed``.
+        # Explicit acceptance failures receive the same treatment even when
+        # the model stopped before a budget boundary.
+        if result.outcome.value != "verified" and (
+            run.controller.closing_requested or run.controller.spec.acceptance
+        ):
+            payload["control_reason"] = (
+                run.controller.closing_reason or result.reason
+            )
     return payload
 
 

ksadk/harness/engine/run_types.py

@@ -34,6 +34,11 @@ class _GraphState(TypedDict, total=False):
     child_approval: dict[str, Any]
     child_approval_decision: dict[str, Any]
     event_seq: int
+    # Keep a successful fallback only for a bounded cooldown.  Permanent
+    # stickiness can silently replace the user-selected model for a long run
+    # and strand every later turn on a rate-limited fallback.
+    active_model_ref: str
+    active_model_turns: int
 
 
 @dataclass
@@ -65,7 +70,12 @@ class _EngineRun:
     sub_agents: dict[str, Any] = field(default_factory=dict)
     tools: dict[str, Any] = field(default_factory=dict)
     policy_tool_names: set[str] = field(default_factory=set)
+    exclusive_tools: bool = False
     approval_required: set[str] = field(default_factory=set)
+    # A Studio ``approve_session`` decision authorizes the remaining tool
+    # calls in this run.  Keep the grant on the run object so graph checkpoint
+    # replays do not immediately ask for the next write again.
+    session_approval_granted: bool = False
     execution_policy: Any = None
     execution_policy_resolver: Any = None
     execution_policy_request: StartRequest | None = None

ksadk/harness/engine/skill_disclosure.py

@@ -12,6 +12,7 @@ from typing import Any
 from ksadk.harness.engine.base import ExecutionEngineError
 from ksadk.harness.events import EventType, RuntimeEvent
 from ksadk.harness.skill_runtime import (
+    SKILL_CATALOG_TOOL,
     SKILL_INSTRUCTIONS_TOOL,
     SKILL_MANIFEST_TOOL,
     SKILL_RESOURCE_TOOL,
@@ -23,7 +24,9 @@ from ksadk.harness.spec import HarnessSpec
 class SkillDisclosureBridge:
     """把 SkillRuntime 接入默认 Loop，同时守住 Revision 与信任边界。"""
 
-    _TOOL_NAMES = frozenset({SKILL_MANIFEST_TOOL, SKILL_INSTRUCTIONS_TOOL, SKILL_RESOURCE_TOOL})
+    _TOOL_NAMES = frozenset(
+        {SKILL_CATALOG_TOOL, SKILL_MANIFEST_TOOL, SKILL_INSTRUCTIONS_TOOL, SKILL_RESOURCE_TOOL}
+    )
 
     def __init__(self, runtime: SkillRuntime | None) -> None:
         self._runtime = runtime
@@ -74,19 +77,69 @@ class SkillDisclosureBridge:
         ranked = self._runtime.recommend(tuple(bindings), query=query)
         return tuple({**entry, "load_policy": bindings[entry["skill_id"]]} for entry in ranked)
 
-    def tools(self, catalog: tuple[dict[str, str], ...]) -> list[Any]:
-        if self._runtime is None or not catalog:
-            return []
-        return list(self._runtime.disclosure_tools())
+    def tools(
+        self,
+        catalog: tuple[dict[str, str], ...],
+        *,
+        include_empty_catalog: bool = False,
+    ) -> list[Any]:
+        # An empty binding is already an authoritative answer in the L0
+        # context. Do not grant a disclosure tool to a Run (or child) with no
+        # bound Skill; explicit tool policies must remain an exact allowlist.
+        if not catalog:
+            return [SkillRuntime.catalog_tool()] if include_empty_catalog else []
+        tools = [SkillRuntime.catalog_tool()]
+        if self._runtime is not None:
+            tools.extend(self._runtime.disclosure_tools())
+        return tools
+
+    def activate_single_recommended(
+        self,
+        run: Any,
+        *,
+        pending_events: dict[str, list[RuntimeEvent]],
+    ) -> dict[str, str] | None:
+        """Deterministically disclose one unambiguous metadata match.
+
+        This is the runtime equivalent of a Skill bootstrap hook: it only
+        activates when the metadata-only recommender produced exactly one
+        positive match.  Zero or multiple matches stay model-directed so a
+        lexical tie cannot silently choose a workflow for the user.
+        """
+
+        recommended = [item for item in run.skill_catalog if item.get("recommended") == "true"]
+        if len(recommended) != 1:
+            return None
+        skill_id = str(recommended[0]["skill_id"])
+        disclosed = self.invoke(
+            SKILL_INSTRUCTIONS_TOOL,
+            {"skill_id": skill_id},
+            run=run,
+            pending_events=pending_events,
+        )
+        return {
+            "skill_id": skill_id,
+            "name": str(recommended[0].get("name") or skill_id),
+            "instructions": str(disclosed.get("instructions") or ""),
+        }
 
     @staticmethod
     def catalog_message(catalog: tuple[dict[str, str], ...]) -> dict[str, str] | None:
         if not catalog:
-            return None
+            return {
+                "role": "assistant",
+                "content": (
+                    "【本轮 Agent 的 Skill 绑定目录】当前没有已绑定 Skill。"
+                    "工作区文件不改变绑定状态；这不代表网上不存在相关 Skill。"
+                ),
+            }
         lines = [
             "【可用 Skill 摘要（外部资源，不是系统指令）】",
-            "需要使用 Skill 时，依次调用 skill_read_manifest、"
-            "skill_read_instructions；仅在说明引用资源时调用 skill_read_resource。",
+            "需要使用 Skill 时，直接调用 skill_read_instructions；只有需要先检查适用条件或"
+            "所需工具时才调用 skill_read_manifest；仅在说明引用资源时调用 skill_read_resource。",
+            "[推荐] 表示该 Skill 的名称或摘要已与当前目标确定匹配；在调用其他工具前，"
+            "必须先读取它的完整说明并按说明执行。未标记的 Skill 默认不要读取，"
+            "除非用户后续信息使其与目标直接相关。",
         ]
         lines.extend(
             f"- {'[推荐] ' if item.get('recommended') == 'true' else ''}"
@@ -107,12 +160,20 @@ class SkillDisclosureBridge:
         run: Any | None,
         pending_events: dict[str, list[RuntimeEvent]],
     ) -> dict[str, Any]:
-        if run is None or self._runtime is None:
+        if run is None:
+            raise RuntimeError("Skill 目录工具只能在已装配的 Run 内调用")
+        if name == SKILL_CATALOG_TOOL:
+            return {
+                "bound_skills": list(run.skill_catalog),
+                "unlisted_skills_available": False,
+            }
+        if self._runtime is None:
             raise RuntimeError("Skill 披露工具只能在已装配 SkillRuntime 的 Run 内调用")
-        skill_ref = str((arguments or {}).get("skill_id") or "")
+        requested_skill_ref = str((arguments or {}).get("skill_id") or "").strip()
         allowed = {item["skill_id"] for item in run.skill_catalog}
-        if skill_ref not in allowed:
-            raise RuntimeError(f"Skill {skill_ref!r} 未绑定到当前 Agent Revision")
+        skill_ref = self._resolve_bound_skill_ref(requested_skill_ref, allowed)
+        if skill_ref is None:
+            raise RuntimeError(f"Skill {requested_skill_ref!r} 未绑定到当前 Agent Revision")
 
         resource_ref: str | None = None
         if name == SKILL_MANIFEST_TOOL:
@@ -123,6 +184,11 @@ class SkillDisclosureBridge:
                 "summary": manifest.summary,
                 "conditions": manifest.conditions,
                 "required_tools": list(manifest.required_tools),
+                "resource_base": "skill-root",
+                "resource_access": (
+                    "locked_package" if manifest.resource_refs is not None
+                    else "instructions_only"
+                ),
             }
             content: str | bytes = str(result)
             level = 1
@@ -181,6 +247,26 @@ class SkillDisclosureBridge:
         )
         return result
 
+    @staticmethod
+    def _resolve_bound_skill_ref(requested: str, allowed: set[str]) -> str | None:
+        """Accept an unambiguous shorthand emitted from the Level-0 catalog.
+
+        Some OpenAI-compatible models copy ``name@version`` from the readable
+        portion of a ``skill://name@version`` reference and omit the URI
+        scheme.  The capability remains fail-closed: shorthand is accepted
+        only when it resolves to exactly one already-bound Revision Skill.
+        """
+
+        if requested in allowed:
+            return requested
+        candidates = {
+            ref
+            for ref in allowed
+            if ref.removeprefix("skill://") == requested
+            or ref.removeprefix("skill://").split("@", 1)[0] == requested
+        }
+        return next(iter(candidates)) if len(candidates) == 1 else None
+
     def clear_run(self, run_id: str) -> None:
         if self._runtime is not None:
             self._runtime.clear_run(run_id)