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

ksadk/harness/observability/otel_exporter.py

@@ -0,0 +1,218 @@
+"""RuntimeEvent → OpenTelemetry Span 适配 + OTLP 导出（plan §13 / 方案 P0）。
+
+在 RuntimeEvent 事件流之上加 OTel Span 适配层，不改 RuntimeEvent 契约。
+按 ``KSADK_OTEL_ENDPOINT`` 环境变量开关；无配置时不导出（零侵入）。
+
+Span 层级映射（plan §13.1 事件层级）::
+
+    Run     → root Span
+    Turn    → child Span of Run
+    Model   → child Span of Turn
+    Tool    → child Span of Turn
+    Context → child Span of Turn（compaction/planned）
+    Approval→ child Span of Turn
+    Memory  → child Span of Turn
+
+成对事件（started/completed）由 Span 自动计时；单次事件（delta/usage）记为
+Span 事件（OTel Event，非 Span）。Tool Call begin/end 成对包裹。
+
+配置::
+
+    KSADK_OTEL_ENDPOINT=http://otel-collector:4318/v1/traces
+    KSADK_OTEL_SERVICE_NAME=ksadk-harness  (默认)
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from ksadk.harness.events import EventType, RuntimeEvent
+
+#: 事件 → OTel Span 名映射（started 事件创建 Span，completed/failed 结束）。
+_SPAN_EVENTS: dict[str, str] = {
+    EventType.RUN_STARTED: "harness.run",
+    EventType.TURN_STARTED: "harness.turn",
+    EventType.MODEL_CALL_STARTED: "harness.model_call",
+    EventType.TOOL_CALL_BEGIN: "harness.tool_call",
+    EventType.CONTEXT_COMPACTION_STARTED: "harness.compaction",
+    EventType.CHECKPOINT_CREATED: "harness.checkpoint",
+}
+
+#: started 事件 → 对应的结束事件（completed/failed/end/canceled）。
+_SPAN_END_EVENTS: dict[str, set[str]] = {
+    EventType.RUN_STARTED: {
+        EventType.RUN_COMPLETED,
+        EventType.RUN_FAILED,
+        EventType.RUN_CANCELED,
+    },
+    EventType.TURN_STARTED: {EventType.TURN_COMPLETED},
+    EventType.MODEL_CALL_STARTED: {
+        EventType.MODEL_CALL_COMPLETED,
+        EventType.MODEL_CALL_FAILED,
+    },
+    EventType.TOOL_CALL_BEGIN: {EventType.TOOL_CALL_END},
+    EventType.CONTEXT_COMPACTION_STARTED: {EventType.CONTEXT_COMPACTION_COMPLETED},
+}
+
+
+class OTelSpanAdapter:
+    """把 RuntimeEvent 流适配为 OpenTelemetry Span。
+
+    用法：引擎在 stream 事件时调 :meth:`on_event`；适配器内部维护 Span 栈，
+    started 事件创建 Span，结束事件结束 Span。
+
+    无 ``KSADK_OTEL_ENDPOINT`` 时为 no-op（不创建 TracerProvider）。
+    """
+
+    def __init__(
+        self,
+        *,
+        endpoint: str | None = None,
+        service_name: str = "ksadk-harness",
+    ) -> None:
+        self._endpoint = endpoint or os.getenv("KSADK_OTEL_ENDPOINT", "")
+        self._service_name = os.getenv("KSADK_OTEL_SERVICE_NAME", service_name)
+        self._tracer: Any | None = None
+        self._provider: Any | None = None
+        self._spans: dict[str, Any] = {}  # span_key → Span
+        self._span_counter: int = 0
+        if self._endpoint:
+            self._setup_otel()
+
+    def _setup_otel(self) -> None:
+        """初始化 OTel TracerProvider + OTLP HTTP exporter。"""
+        from opentelemetry import trace
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+        resource = Resource.create({"service.name": self._service_name})
+        provider = TracerProvider(resource=resource)
+        exporter = OTLPSpanExporter(endpoint=self._endpoint)
+        provider.add_span_processor(BatchSpanProcessor(exporter))
+        trace.set_tracer_provider(provider)
+        self._provider = provider
+        self._tracer = trace.get_tracer("ksadk.harness")
+
+    @property
+    def enabled(self) -> bool:
+        return self._tracer is not None
+
+    def on_event(self, event: RuntimeEvent) -> None:
+        """处理一个 RuntimeEvent——创建/结束对应 OTel Span。"""
+        if not self._tracer:
+            return
+
+        et = event.event_type
+
+        # started 事件 → 创建 Span
+        if et in _SPAN_EVENTS:
+            span_name = _SPAN_EVENTS[et]
+            span_key = self._span_key(event, et)
+            if span_key in self._spans:
+                return  # 已存在（重复 started，不重复创建）
+            parent_key = self._parent_key(event, et)
+            parent_span = self._spans.get(parent_key) if parent_key else None
+            context = parent_span.set_span_on_parent() if parent_span else None
+            span = self._tracer.start_span(
+                span_name,
+                context=context,
+                attributes=self._attributes(event),
+            )
+            self._spans[span_key] = span
+            return
+
+        # 结束事件 → 结束对应 Span
+        for started_et, end_events in _SPAN_END_EVENTS.items():
+            if et in end_events:
+                span_key = self._span_key(event, started_et)
+                span = self._spans.pop(span_key, None)
+                if span:
+                    if et.endswith(".failed") or et.endswith(".canceled"):
+                        span.set_attribute("otel.status_code", "ERROR")
+                        span.set_attribute(
+                            "error.message", str(event.payload.get("error") or "")
+                        )
+                    else:
+                        span.set_attribute("otel.status_code", "OK")
+                    span.end()
+                return
+
+        # 单次事件 → 记为 Span Event（非新 Span）
+        if self._spans:
+            turn_key = self._span_key(event, EventType.TURN_STARTED)
+            span = self._spans.get(turn_key) or self._spans.get(
+                self._span_key(event, EventType.RUN_STARTED)
+            )
+            if span:
+                span.add_event(
+                    et,
+                    attributes={
+                        k: str(v) for k, v in event.payload.items() if v is not None
+                    },
+                )
+
+    def flush(self) -> None:
+        """强制刷新所有待导出的 Span（进程退出前调）。"""
+        if self._provider:
+            try:
+                self._provider.force_flush()
+            except Exception:  # noqa: BLE001 - 导出失败不阻断主流程
+                pass
+
+    def shutdown(self) -> None:
+        """关闭 TracerProvider。"""
+        if self._provider:
+            try:
+                self._provider.shutdown()
+            except Exception:  # noqa: BLE001
+                pass
+            self._provider = None
+            self._tracer = None
+
+    # ---- helpers ----
+
+    def _span_key(self, event: RuntimeEvent, started_et: str) -> str:
+        """Span 唯一键：run_id + started_event_type + call_id/tool_id。"""
+        run_id = event.run_id or event.invocation_id
+        extra = ""
+        if started_et == EventType.TOOL_CALL_BEGIN:
+            extra = f":{event.payload.get('call_id', '')}"
+        elif started_et == EventType.MODEL_CALL_STARTED:
+            extra = f":{event.payload.get('attempt', '')}"
+        return f"{run_id}:{started_et}{extra}"
+
+    def _parent_key(self, event: RuntimeEvent, started_et: str) -> str | None:
+        """Span 父键：Turn/Tool 的父是 Run/Turn。"""
+        run_id = event.run_id or event.invocation_id
+        if started_et == EventType.TURN_STARTED:
+            return f"{run_id}:{EventType.RUN_STARTED}"
+        if started_et in (
+            EventType.MODEL_CALL_STARTED,
+            EventType.TOOL_CALL_BEGIN,
+            EventType.CONTEXT_COMPACTION_STARTED,
+        ):
+            return f"{run_id}:{EventType.TURN_STARTED}"
+        return None
+
+    @staticmethod
+    def _attributes(event: RuntimeEvent) -> dict[str, Any]:
+        """从 RuntimeEvent 提取 OTel Span 属性。"""
+        attrs: dict[str, Any] = {
+            "harness.event_type": event.event_type,
+            "harness.agent_id": event.agent_id,
+            "harness.session_id": event.session_id,
+            "harness.run_id": event.run_id or event.invocation_id,
+            "harness.seq_id": event.seq_id,
+        }
+        if event.phase:
+            attrs["harness.phase"] = event.phase
+        for key, value in event.payload.items():
+            if value is not None and isinstance(value, (str, int, float, bool)):
+                attrs[f"harness.payload.{key}"] = value
+        return attrs
+
+
+__all__ = ["OTelSpanAdapter"]

ksadk/harness/progress_adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Host adapters for Native session-local planning tools."""
+
+from .native_todo import NativeTodoToolPort, install_todo_tool
+
+__all__ = ["NativeTodoToolPort", "install_todo_tool"]

ksadk/harness/progress_adapters/native_todo.py

@@ -0,0 +1,75 @@
+"""Reserved TodoWrite routing; the reducer commits the validated plan atomically."""
+
+from __future__ import annotations
+
+from ..native.ports import RunConfiguration, ToolPort, ToolRequest, ToolResult
+from ..native.task_progress import (
+    TODO_WRITE_DEFINITION,
+    TODO_WRITE_NAME,
+    parse_task_progress,
+    summarize_task_progress,
+)
+from ..native.tool_recovery import query_sealed_tool_result
+
+
+class NativeTodoToolPort:
+    def __init__(self, delegate: ToolPort) -> None:
+        if not callable(getattr(delegate, "execute", None)):
+            raise ValueError("todo tool delegate must implement execute")
+        self.delegate = delegate
+
+    async def reconcile(self, request: ToolRequest) -> ToolResult:
+        return await query_sealed_tool_result(
+            self.delegate, request, owned_names=(TODO_WRITE_NAME,)
+        )
+
+    async def recover_prepared(self, request: ToolRequest) -> ToolResult:
+        return await query_sealed_tool_result(
+            self.delegate, request, owned_names=(TODO_WRITE_NAME,), method="recover_prepared"
+        )
+
+    async def resume_prepared(self, request: ToolRequest) -> ToolResult:
+        return await query_sealed_tool_result(
+            self.delegate, request, owned_names=(TODO_WRITE_NAME,), method="resume_prepared"
+        )
+
+    async def resume_checkpoint(self, request: ToolRequest) -> ToolResult:
+        return await query_sealed_tool_result(
+            self.delegate, request, owned_names=(TODO_WRITE_NAME,), method="resume_checkpoint"
+        )
+
+    async def execute(self, request: ToolRequest) -> ToolResult:
+        if request.call.name != TODO_WRITE_NAME:
+            result = await self.delegate.execute(request)
+            return ToolResult.model_validate_json(result.model_dump_json())
+        if request.definition != TODO_WRITE_DEFINITION:
+            return ToolResult(status="error", content={"reason": "todo_definition_mismatch"})
+        try:
+            items = parse_task_progress(request.call.arguments)
+        except ValueError:
+            return ToolResult(status="error", content={"reason": "invalid_task_progress"})
+        return ToolResult(
+            status="ok",
+            content={
+                "todos": list(items),
+                "summary": summarize_task_progress(items),
+                "authority": "model_planning_only",
+            },
+        )
+
+
+def install_todo_tool(
+    configuration: RunConfiguration, tools: ToolPort
+) -> tuple[RunConfiguration, NativeTodoToolPort]:
+    existing = next(
+        (definition for definition in configuration.tools if definition.name == TODO_WRITE_NAME),
+        None,
+    )
+    if existing is not None and existing != TODO_WRITE_DEFINITION:
+        raise ValueError("reserved_todo_tool_conflict")
+    definitions = (
+        configuration.tools
+        if existing is not None
+        else (*configuration.tools, TODO_WRITE_DEFINITION)
+    )
+    return configuration.model_copy(update={"tools": definitions}), NativeTodoToolPort(tools)

ksadk/harness/prompt_cache.py

@@ -0,0 +1,132 @@
+"""Prompt Cache 边界诊断（只记录 Hash，不持久化 Prompt 正文）。"""
+
+from __future__ import annotations
+
+import hashlib
+from collections import OrderedDict
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PromptCacheDiagnostic:
+    """一次稳定 Prompt 前缀观察结果。"""
+
+    stable_prompt_hash: str
+    previous_stable_prompt_hash: str
+    cache_break: bool
+    reason: str
+
+    def to_payload(self) -> dict[str, str | bool]:
+        return {
+            "stable_prompt_hash": self.stable_prompt_hash,
+            "previous_stable_prompt_hash": self.previous_stable_prompt_hash,
+            "cache_break": self.cache_break,
+            "reason": self.reason,
+        }
+
+
+class PromptCacheTracker:
+    """进程内有界诊断器。
+
+    Provider 的真实缓存命中仍以 ``usage.reported.cached_tokens`` 为准；本类只
+    判断 KsADK 稳定 Prompt 合同是否发生变化。LRU 有界，重启后首个观察记为
+    ``cold_start``，不会把本地缓存状态伪装成云端事实。
+    G19：``notify_compaction``/``notify_cache_deletion`` 标记预期 break，
+    observe 时跳过告警（reason 标 expected_*）。
+    """
+
+    def __init__(self, *, max_scopes: int = 1024) -> None:
+        if max_scopes < 1:
+            raise ValueError("max_scopes 必须为正整数")
+        self._max_scopes = max_scopes
+        self._hashes: OrderedDict[str, str] = OrderedDict()
+        # G19 预期下降抑制：compaction / cache deletion 期间的 break 不告警
+        self._expected_break: str | None = None
+
+    def observe(
+        self,
+        *,
+        scope: str,
+        stable_prompt_hash: str,
+        changed_section: str | None = None,
+    ) -> PromptCacheDiagnostic:
+        current = stable_prompt_hash.strip()
+        previous = self._hashes.pop(scope, "")
+        if current:
+            self._hashes[scope] = current
+            while len(self._hashes) > self._max_scopes:
+                self._hashes.popitem(last=False)
+
+        if not current:
+            return PromptCacheDiagnostic(
+                stable_prompt_hash="",
+                previous_stable_prompt_hash=previous,
+                cache_break=False,
+                reason="stable_prompt_unavailable",
+            )
+        if not previous:
+            reason, cache_break = "cold_start", False
+        elif previous == current:
+            reason, cache_break = "stable_prompt_reused", False
+        else:
+            # G17 强制理由：cache_break=True 须含具体变更 section key；
+            # 未传则标 unknown（可见降级，不静默）。
+            changed = changed_section or "unknown"
+            # G19 预期下降抑制：compaction / cache deletion 期间的 break 不告警
+            if self._expected_break is not None:
+                reason, cache_break = self._expected_break, False
+                self._expected_break = None
+            else:
+                reason, cache_break = f"stable_prompt_changed:{changed}", True
+        return PromptCacheDiagnostic(
+            stable_prompt_hash=current,
+            previous_stable_prompt_hash=previous,
+            cache_break=cache_break,
+            reason=reason,
+        )
+
+    # G19 预期下降抑制：compaction / cache deletion 期间的 break 标预期
+    def notify_compaction(self) -> None:
+        self._expected_break = "expected_compaction"
+
+    def notify_cache_deletion(self) -> None:
+        self._expected_break = "expected_cache_deletion"
+
+
+@dataclass(frozen=True)
+class CacheBreakSnapshot:
+    """G19 缓存失效归因：多维度定容快照（只存 hash，不存正文）。
+
+    维度：instructions / system_sections / tool_set / model_ref。
+    ``diff`` 返回发生变化的维度名集合，供 reason 定位。
+    """
+
+    instructions: str
+    system_sections: str
+    tool_set: str
+    model_ref: str
+
+    def __post_init__(self) -> None:
+        # 定容：把传入正文替换为 hash（不存原文）
+        object.__setattr__(self, "instructions", self._hash(self.instructions))
+        object.__setattr__(self, "system_sections", self._hash(self.system_sections))
+        object.__setattr__(self, "tool_set", self._hash(self.tool_set))
+
+    @staticmethod
+    def _hash(text: str) -> str:
+        return hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]
+
+    def diff(self, other: "CacheBreakSnapshot") -> list[str]:
+        changed: list[str] = []
+        if self.instructions != other.instructions:
+            changed.append("instructions")
+        if self.system_sections != other.system_sections:
+            changed.append("system_sections")
+        if self.tool_set != other.tool_set:
+            changed.append("tool_set")
+        if self.model_ref != other.model_ref:
+            changed.append("model_ref")
+        return changed
+
+
+__all__ = ["CacheBreakSnapshot", "PromptCacheDiagnostic", "PromptCacheTracker"]

ksadk/harness/public_activity.py

@@ -0,0 +1,213 @@
+"""Small, display-safe facts about actions, never a copy of tool arguments."""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import shlex
+from pathlib import PurePosixPath
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+_SENSITIVE = re.compile(
+    r"(?i)(?:api[_ -]?key|secret|password|passwd|authorization|bearer|token|"
+    r"sk-[a-z0-9]|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})"
+)
+_SECRET_VALUE = re.compile(
+    r"(?i)(?:\b(?:api[_ -]?key|secret|password|passwd|authorization|access[_ -]?token|"
+    r"refresh[_ -]?token)\b\s*[:=]\s*\S+|\bbearer\s+\S+|\bsk-[a-z0-9_-]{12,})"
+)
+
+
+def _text(value: Any) -> str:
+    # Tool arguments are untrusted payloads.  Keep the deliberately broad
+    # policy here: even a credential-shaped field name or URL path is enough
+    # to omit the action rather than risk displaying it.
+    if not isinstance(value, str) or _SENSITIVE.search(value):
+        return ""
+    # Free-text search requests can embed URLs too; never publish credentials.
+    if re.search(r"https?://[^\s/]*@", value):
+        return ""
+    return " ".join(value.split())[:180]
+
+
+def public_commentary_text(value: Any, *, limit: int = 360) -> str:
+    """Return model-authored text that is safe to show as public progress.
+
+    This accepts only the assistant's public text channel.  Provider reasoning,
+    tool arguments and tool results never call this helper.  Fail closed for
+    credentials and for tool-protocol fragments that some OpenAI-compatible
+    providers accidentally place in ``content`` alongside a tool call.
+    """
+    # Public assistant prose may legitimately discuss concepts such as a
+    # "token budget".  Only reject text that contains a credential value;
+    # unlike tool arguments, this channel has already been separated from
+    # provider reasoning and tool payloads.
+    if not isinstance(value, str) or _SECRET_VALUE.search(value):
+        return ""
+    if re.search(r"https?://[^\s/]*@", value):
+        return ""
+    if re.search(
+        r"(?i)(?:<\|\s*DSML\s*\||</?calls?>|</?invoke\b|<parameter\b|"
+        r"tool_calls?\s*[:=]|function_call\s*[:=])",
+        value,
+    ):
+        return ""
+    # Child conclusions are often Markdown.  The activity feed is prose, so
+    # remove presentation markers while retaining the actual conclusion.
+    text = re.sub(r"(?m)^\s{0,3}(?:#{1,6}\s+|>\s*|[-*+]\s+|\d+[.)]\s+)", "", value)
+    text = text.replace("**", "").replace("__", "").replace("`", "")
+    text = " ".join(text.split()).strip()
+    # Streaming providers can occasionally leave a trailing punctuation-only
+    # content fragment after a tool call.  It conveys no progress and would
+    # otherwise render as a stray activity row such as ``。``.
+    if not re.search(r"[A-Za-z0-9\u3400-\u9fff]", text):
+        return ""
+    # Tool-preface boilerplate is not a useful user-facing checkpoint.  It is
+    # intentionally omitted instead of translated into another canned phrase.
+    if re.fullmatch(
+        r"(?i)(?:let me|i(?:'ll| will)|we(?:'ll| will))\s+"
+        r"(?:delegate|search|look up|check|call|use|run)\b.*",
+        text,
+    ):
+        return ""
+    if len(text) <= limit:
+        return text
+    shortened = text[:limit]
+    boundary = max(shortened.rfind(mark) for mark in "。！？；.!?;")
+    if boundary >= max(40, limit // 2):
+        shortened = shortened[: boundary + 1]
+    return shortened.rstrip() + "…"
+
+
+def tool_public_action(payload: dict[str, Any]) -> dict[str, str] | None:
+    """Allowlist display fields; omit results, command arguments and credentials."""
+    name = str(payload.get("name") or "").lower()
+    args = payload.get("args")
+    if not isinstance(args, dict):
+        return None
+    if name == "web_search":
+        query = _text(args.get("query"))
+        return {"text": f"搜索资料：{query}"} if query else None
+    if name == "web_fetch":
+        try:
+            url = urlsplit(str(args.get("url") or ""))
+            host = url.hostname or ""
+            if url.scheme not in {"https", "http"} or not host:
+                return None
+            if host == "localhost" or "." not in host or host.endswith((".local", ".internal")):
+                return None
+            try:
+                if not ipaddress.ip_address(host).is_global:
+                    return None
+            except ValueError:
+                pass
+            # Queries, fragments and URL credentials never become presentation data.
+            safe = urlunsplit((url.scheme, host, url.path, "", ""))
+            if not _text(safe) or len(safe) > 300:
+                return None
+            return {"text": f"查看网页：{host}{url.path}", "href": safe}
+        except ValueError:
+            return None
+    if name in {
+        "read_workspace_file",
+        "write_workspace_file",
+        "edit_workspace_file",
+        "list_workspace_files",
+    }:
+        target = _text(PurePosixPath(str(args.get("path") or "").replace("\\", "/")).name)
+        if not target or target in {".", "..", ".env"}:
+            return None
+        verb = (
+            "保存文件"
+            if name == "write_workspace_file"
+            else "编辑文件"
+            if name == "edit_workspace_file"
+            else "查看文件"
+            if name == "read_workspace_file"
+            else "查看目录"
+        )
+        return {"text": f"{verb}：{target}"}
+    # Skill / MCP 披露 / 知识库：这几类工具此前没有 public_action，
+    # Studio 活动流只能显示笼统的"使用工具处理任务"。这里补上**一句话动作**，
+    # 只暴露名字与用途，绝不带参数原文或结果。
+    if name in {"skill_read_manifest", "skill_read_instructions", "skill_read_resource"}:
+        skill = _text(
+            args.get("skill")
+            or args.get("skill_name")
+            or args.get("name")
+            or args.get("resource_ref")
+            or ""
+        )
+        verb = "读取 Skill 说明" if name != "skill_read_manifest" else "读取 Skill 清单"
+        return {"text": f"{verb}：{skill}" if skill else verb}
+    if name == "mcp_list_tools":
+        server = _text(args.get("server_id") or args.get("server") or "")
+        return {"text": f"查看 MCP 工具清单：{server}" if server else "查看 MCP 工具清单"}
+    if name == "mcp_read_tool_schema":
+        tool = _text(args.get("tool_name") or args.get("tool") or "")
+        server = _text(args.get("server_id") or args.get("server") or "")
+        target = f"{server}/{tool}" if server and tool else tool or server
+        return {"text": f"读取 MCP 工具说明：{target}" if target else "读取 MCP 工具说明"}
+    if name == "mcp_call_tool":
+        tool = _text(args.get("tool_name") or args.get("tool") or "")
+        server = _text(args.get("server_id") or args.get("server") or "")
+        target = f"{server}/{tool}" if server and tool else tool or server
+        return {
+            "text": (
+                f"调用 MCP 工具：{target}（参数未展示）"
+                if target
+                else "调用 MCP 工具（参数未展示）"
+            )
+        }
+    if name in {
+        "search_knowledge",
+        "search_knowledge_base",
+        "knowledge_search",
+        "search_knowledge_bases",
+    }:
+        query = _text(args.get("query") or args.get("q") or args.get("keywords") or "")
+        return {"text": f"检索知识库：{query}" if query else "检索知识库"}
+    if name == "artifact_read":
+        target = _text(PurePosixPath(str(args.get("uri") or args.get("artifact_uri") or "")).name)
+        return {"text": f"读取外置结果：{target}" if target else "读取外置结果"}
+    if name == "sandbox_read_file":
+        target = _text(PurePosixPath(str(args.get("path") or "").replace("\\", "/")).name)
+        return {"text": f"查看沙箱文件：{target}" if target else "查看沙箱文件"}
+    if name == "sandbox_run_command":
+        try:
+            words = shlex.split(str(args.get("command") or ""))
+        except ValueError:
+            return None
+        command = PurePosixPath(words[0]).name if words else ""
+        return (
+            {"text": f"运行沙箱命令：{command}（参数未展示）"}
+            if command
+            else {"text": "运行沙箱命令（参数未展示）"}
+        )
+    if name in {"execute_skills", "run_code"}:
+        return {"text": "执行 Skill" if name == "execute_skills" else "运行代码"}
+    if name in {"exec_command", "run_command", "execute_command", "run_workspace_command"}:
+        try:
+            words = shlex.split(str(args.get("command") or args.get("cmd") or ""))
+        except ValueError:
+            return None
+        command = PurePosixPath(words[0]).name if words else ""
+        if command in {
+            "rg",
+            "git",
+            "ls",
+            "cat",
+            "sed",
+            "python",
+            "python3",
+            "node",
+            "npm",
+            "uv",
+            "pytest",
+        }:
+            return {"text": f"运行命令：{command}（参数未展示）"}
+    return None
+
+
+__all__ = ["public_commentary_text", "tool_public_action"]

ksadk/harness/public_output.py

@@ -0,0 +1,30 @@
+"""Host-owned optional retention of explicitly public tool output."""
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+_sink = ContextVar("ksadk_public_output_sink", default=None)
+
+
+@contextmanager
+def public_output_scope(sink):
+    token = _sink.set(sink)
+    try:
+        yield
+    finally:
+        _sink.reset(token)
+
+
+def retain_public_output(text: str, *, incomplete: bool = False) -> str | None:
+    sink = _sink.get()
+    if sink is None:
+        return None
+    try:
+        return sink(text, incomplete=incomplete)
+    except Exception:
+        # Presentation storage cannot change execution or cause a tool retry.
+        return None
+
+
+def current_public_output_sink():
+    return _sink.get()