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

ksadk/conversations/runtime_stream_events.py

@@ -10,6 +10,7 @@ from ksadk.conversations.run_kinds import (
     trigger_from_resume_input,
     validate_run_mode,
 )
+from ksadk.conversations.runtime_baseline import record_baseline_turn
 from ksadk.conversations.runtime_compaction import preview_auto_compaction
 from ksadk.conversations.runtime_constants import (
     ASSISTANT_STREAM_SNAPSHOT_INTERVAL_SECONDS,
@@ -46,6 +47,7 @@ from ksadk.conversations.runtime_observability import (
     _set_conversation_usage_attributes,
     _set_prompt_cache_attributes,
     _set_prompt_source_attributes,
+    _set_skill_eval_result_attributes,
     _set_span_attribute,
     _span_current_context,
     _span_feedback_metadata,
@@ -57,6 +59,7 @@ from ksadk.conversations.runtime_persistence import (
     append_reasoning_event,
     append_run_checkpoint_event,
     append_run_status_event,
+    prepare_stream_identity_session,
 )
 from ksadk.conversations.runtime_preparation import _refresh_history, build_run_input
 from ksadk.conversations.runtime_resume import (
@@ -72,6 +75,7 @@ from ksadk.conversations.runtime_resume import (
     _tool_receipt_metadata,
 )
 from ksadk.model_policy import fallback_model_for_exception, model_policy_options_for_model
+from ksadk.runtime.skill_eval_result import skill_eval_response_fields
 from ksadk.runtime_context import (
     PlatformInvocationContext,
     platform_invocation_scope,
@@ -83,35 +87,6 @@ from ksadk.tools.gateway import (
 )
 
 
-def _record_baseline_turn(
-    *,
-    prepared: Any,
-    model: str | None,
-    usage: Any,
-    ptl: bool,
-    attempts: int,
-    turn_start_monotonic: float | None,
-) -> None:
-    """env-gated 旁路采集：未启用时 no-op，启用时记录一条 turn 基线。不进决策路径。"""
-    from ksadk.context_engine.baseline import record_baseline_turn
-
-    latency_ms = None
-    if turn_start_monotonic is not None:
-        latency_ms = int((time.monotonic() - turn_start_monotonic) * 1000)
-    record_baseline_turn(
-        getattr(prepared, "shadow_context_plan", None),
-        session_id=getattr(prepared, "session_id", ""),
-        invocation_id=getattr(prepared, "invocation_id", ""),
-        model=str(model or ""),
-        usage=usage if isinstance(usage, Mapping) else None,
-        compaction_triggered=bool(getattr(prepared, "compaction_triggered", False)),
-        compaction_trigger=str(getattr(prepared, "compaction_trigger", "") or ""),
-        prompt_too_long=ptl,
-        retry_attempts=attempts,
-        turn_latency_ms=latency_ms,
-    )
-
-
 async def _iter_conversation_turn_events(
     *,
     runner: Any,
@@ -145,6 +120,18 @@ async def _iter_conversation_turn_events(
     _governance_record_turn_start(governance)
     entry_run_mode = validate_run_mode(run_mode)
     entry_run_trigger = trigger_from_resume_input(resume_input)
+    (
+        user_id,
+        session_id,
+        invocation_identity,
+        public_request_metadata,
+    ) = await prepare_stream_identity_session(
+        agent_id=agent_id,
+        user_id=user_id,
+        session_id=session_id,
+        request_metadata=request_metadata,
+        session_service_provider=provider,
+    )
     if resume_input is None:
         compaction_preview = await preview_auto_compaction(
             agent_id=agent_id,
@@ -220,9 +207,10 @@ async def _iter_conversation_turn_events(
         yield {"type": "error", "message": str(exc) or "Agent 运行失败"}
         return
     _inject_runner_deferred_tools_for_request(runner, prepared)
+    effective_user_id = prepared.user_id or user_id
     ambient_contexts = _build_runner_ambient_contexts(
         runner=runner,
-        user_id=user_id,
+        user_id=effective_user_id,
         user_input=prepared.user_input,
     )
     prepared.memory_recall_events = ambient_contexts.get("memory_recall_events", [])
@@ -231,7 +219,7 @@ async def _iter_conversation_turn_events(
     runtime_context = PlatformInvocationContext(
         session=SessionContext.from_payload(prepared.session_context),
         agent_id=agent_id,
-        user_id=user_id,
+        user_id=effective_user_id,
         account_id=str(account_id or ""),
         session_id=prepared.session_id,
         history=list(prepared.history),
@@ -250,6 +238,7 @@ async def _iter_conversation_turn_events(
         kb_context=ambient_contexts.get("kb_context"),
         memory_context=ambient_contexts.get("memory_context"),
         tool_approval_mode=str(prepared.request_metadata.get("tool_approval_mode") or ""),
+        identity=invocation_identity,
     )
     if prepared.compaction_triggered:
         yield {
@@ -293,7 +282,7 @@ async def _iter_conversation_turn_events(
         _set_conversation_span_attributes(
             span,
             agent_id=agent_id,
-            user_id=user_id,
+            user_id=effective_user_id,
             session_id=prepared.session_id,
             invocation_id=prepared.invocation_id,
             runner_name=runner_name,
@@ -309,7 +298,7 @@ async def _iter_conversation_turn_events(
         yield {
             "type": "started",
             "session_id": prepared.session_id,
-            "metadata": {**trace_metadata, **dict(request_metadata or {})},
+            "metadata": {**trace_metadata, **public_request_metadata},
         }
         await append_run_status_event(
             session_id=prepared.session_id,
@@ -329,6 +318,7 @@ async def _iter_conversation_turn_events(
         emitted_anything = False
         emitted_response_artifacts = False
         saw_final_chunk = False
+        result_fields: dict[str, Any] = {}
         responses_output: list[Any] = []
         responses_response_id: str | None = response_id
         runner_agentengine_metadata: dict[str, Any] = {}
@@ -756,6 +746,9 @@ async def _iter_conversation_turn_events(
                                 return
                             if chunk_type == "final":
                                 saw_final_chunk = True
+                                result_fields = skill_eval_response_fields(chunk)
+                                if result_fields:
+                                    _set_skill_eval_result_attributes(span, result_fields["skill_eval_result"])
                                 final_text = str(chunk.get("output", ""))
                                 if final_text:
                                     accumulated_text = final_text
@@ -946,7 +939,7 @@ async def _iter_conversation_turn_events(
         )
         await _auto_save_ltm_turn(
             agent_id=agent_id,
-            user_id=user_id,
+            user_id=effective_user_id,
             prepared=prepared,
             output_text=accumulated_text,
             runner_type=runtime_context.runner_type,
@@ -969,7 +962,7 @@ async def _iter_conversation_turn_events(
             usage=assistant_metadata.get("usage"),
         )
         _set_prompt_source_attributes(span, getattr(prepared, "compiled_prompt", None))
-        _record_baseline_turn(
+        record_baseline_turn(
             prepared=prepared,
             model=model,
             usage=assistant_metadata.get("usage"),
@@ -980,6 +973,7 @@ async def _iter_conversation_turn_events(
         _finish_span()
         yield {
             "type": "completed",
+            **result_fields,
             "output_text": accumulated_text,
             "model": model,
             "session_id": prepared.session_id,

ksadk/conversations/runtime_streaming.py

@@ -205,6 +205,8 @@ async def _stream_conversation_semantic_events(
                     event.get("metadata") if isinstance(event.get("metadata"), Mapping) else None
                 ),
                 usage=event.get("usage") if isinstance(event.get("usage"), Mapping) else None,
+                timing=event.get("timing") if isinstance(event.get("timing"), Mapping) else None,
+                skill_eval_result=event.get("skill_eval_result"),
             )
             yield _response_sse("response.completed", final_payload)
 
@@ -626,6 +628,8 @@ async def _stream_responses_semantic_events(
                 status="failed",
                 metadata=response_metadata,
                 usage=event.get("usage") if isinstance(event.get("usage"), Mapping) else None,
+                timing=event.get("timing") if isinstance(event.get("timing"), Mapping) else None,
+                skill_eval_result=event.get("skill_eval_result"),
                 error={"message": event.get("message") or "Agent 运行失败"},
             )
             yield _response_sse("response.failed", failed_payload)
@@ -641,6 +645,8 @@ async def _stream_responses_semantic_events(
                 status="cancelled",
                 metadata=response_metadata,
                 usage=event.get("usage") if isinstance(event.get("usage"), Mapping) else None,
+                timing=event.get("timing") if isinstance(event.get("timing"), Mapping) else None,
+                skill_eval_result=event.get("skill_eval_result"),
             )
             yield _response_sse("response.cancelled", cancelled_payload)
             return
@@ -704,6 +710,8 @@ async def _stream_responses_semantic_events(
                 status="completed",
                 metadata=response_metadata,
                 usage=event.get("usage") if isinstance(event.get("usage"), Mapping) else None,
+                timing=event.get("timing") if isinstance(event.get("timing"), Mapping) else None,
+                skill_eval_result=event.get("skill_eval_result"),
                 output_items=(
                     event.get("responses_output")
                     if isinstance(event.get("responses_output"), Sequence)

ksadk/events/adapters/_codex_items.py

@@ -42,6 +42,7 @@ from ksadk.events.identity import stable_event_id, stable_item_id, stable_part_i
 
 _CODEX_0_147_0_NOTIFICATION_METHODS = frozenset("""
     account/login/completed account/rateLimits/updated account/updated app/list/updated
+    autoApprovalReview/strictReviewRequired
     command/exec/outputDelta configWarning deprecationNotice error
     externalAgentConfig/import/completed externalAgentConfig/import/progress fs/changed
     fuzzyFileSearch/sessionCompleted fuzzyFileSearch/sessionUpdated guardianWarning
@@ -50,16 +51,23 @@ _CODEX_0_147_0_NOTIFICATION_METHODS = frozenset("""
     item/commandExecution/terminalInteraction item/completed item/fileChange/outputDelta
     item/fileChange/patchUpdated item/mcpToolCall/progress item/plan/delta
     item/reasoning/summaryPartAdded item/reasoning/summaryTextDelta item/reasoning/textDelta
-    item/started mcpServer/oauthLogin/completed mcpServer/startupStatus/updated
-    model/rerouted model/safetyBuffering/updated model/verification process/exited
-    process/outputDelta remoteControl/status/changed serverRequest/resolved skills/changed
-    thread/archived thread/closed thread/compacted thread/deleted thread/goal/cleared
-    thread/environment/connected thread/environment/disconnected
-    thread/goal/updated thread/name/updated thread/realtime/closed thread/realtime/error
+    item/started mcpServer/event/stream/notification mcpServer/oauthLogin/completed
+    mcpServer/startupStatus/updated
+    model/rerouted model/safetyBuffering/updated model/verification
+    modelProvider/authRecoveryCompleted modelProvider/authRecoveryStarted
+    process/exited process/outputDelta project/changed
+    remoteControl/status/changed serverRequest/resolved skills/changed
+    thread/archived thread/attachment/updated thread/closed thread/compacted thread/deleted
+    thread/goal/cleared thread/environment/connected thread/environment/disconnected
+    thread/goal/updated thread/name/updated thread/project/updated thread/queue/changed
+    thread/realtime/closed thread/realtime/error
+    thread/realtime/item/completed thread/realtime/item/started
+    thread/realtime/item/transcript/delta
     thread/realtime/itemAdded thread/realtime/outputAudio/delta thread/realtime/sdp
     thread/realtime/started thread/realtime/transcript/delta thread/realtime/transcript/done
-    thread/settings/updated thread/started thread/status/changed thread/tokenUsage/updated
-    thread/unarchived turn/completed turn/diff/updated turn/moderationMetadata
+    thread/reverted thread/settings/updated thread/started thread/status/changed
+    thread/tokenUsage/updated thread/unarchived turn/completed turn/diff/updated
+    turn/moderationMetadata
     turn/plan/updated turn/started warning windows/worldWritableWarning
     windowsSandbox/setupCompleted
     """.split())

ksadk/events/adapters/_langgraph_support.py

@@ -17,6 +17,7 @@ from ksadk.events.canonical import (
     ItemUpdated,
     RuntimeEvent,
     SourceRef,
+    UsageReported,
 )
 from ksadk.events.content import (
     ContentSnapshot,
@@ -32,6 +33,7 @@ from ksadk.events.identity import (
     stable_part_id,
     stable_scope_id,
 )
+from ksadk.runners.base_runner import BaseRunner
 
 # Native content-block types that carry a tool call identity.
 _TOOL_CALL_BLOCKS = frozenset(
@@ -423,9 +425,41 @@ def _map_whole_message(
                 ),
             )
         )
+    usage = BaseRunner._message_usage(payload)
+    if usage:
+        usage_item_id = stable_item_id("langgraph", state.scope_id, "$run")
+        emitted.append(
+            UsageReported(
+                **env(
+                    state.scope_id,
+                    state.parent_scope_id,
+                    usage_item_id,
+                    "usage.reported",
+                    "usage",
+                    source,
+                ),
+                input_tokens=usage["input_tokens"],
+                output_tokens=usage["output_tokens"],
+                total_tokens=usage["total_tokens"],
+                cached_tokens=_usage_detail(usage.get("input_token_details"), "cached"),
+                reasoning_tokens=_usage_detail(usage.get("output_token_details"), "reasoning"),
+            )
+        )
     return tuple(emitted)
 
 
+def _usage_detail(details: Any, key: str) -> int:
+    if not isinstance(details, Mapping):
+        return 0
+    value = details.get(key)
+    if value is None and key == "cached":
+        value = details.get("cache_read") or details.get("cached_tokens")
+    try:
+        return int(value or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
 def _envelope(
     context: LangGraphAdapterContext,
     occurrence_key: str,

ksadk/events/session_event.py

@@ -1,4 +1,4 @@
-"""Generic single-log SessionEvent store port（Phase 1 Task 2）。
+"""Generic single-log SessionEvent store port（Kernel Task 2）。
 
 把 control/runtime/workflow 等 family 的 ``SessionEventEnvelope/v1`` 收敛进
 同一个 session event log，复用 Session backend 的原子 per-session seq。
@@ -79,7 +79,7 @@ def validate_write_guard(
     """Typed write permission: no bare booleans, no nullable fences.
 
     AdmissionWriteGuard 只允许 admission 产生的 ``control.command_accepted`` /
-    ``control.command_rejected``。ActivationWriteGuard 在 Phase 1 允许
+    ``control.command_rejected``。ActivationWriteGuard 在 Kernel 允许
     worker/control/runtime facts；activation_id/fencing_token 与 lease 的
     事务内比较由 Task 3 的 AgentKernelStore 承接。
     """

ksadk/harness/__init__.py

@@ -22,10 +22,24 @@ _EXPORTS = {
     "HarnessReasoningTurn": ("ksadk.harness.reasoner", "HarnessReasoningTurn"),
     "HarnessToolCall": ("ksadk.harness.reasoner", "HarnessToolCall"),
     "LiteLLMHarnessReasoner": ("ksadk.harness.reasoner", "LiteLLMHarnessReasoner"),
+    "AcceptanceCheck": ("ksadk.harness.run_control", "AcceptanceCheck"),
+    "MilestoneSpec": ("ksadk.harness.run_control", "MilestoneSpec"),
+    "RunControlSpec": ("ksadk.harness.run_control", "RunControlSpec"),
+    "RunLimits": ("ksadk.harness.run_control", "RunLimits"),
+    "StagnationPolicy": ("ksadk.harness.run_control", "StagnationPolicy"),
     "HarnessRuntime": ("ksadk.harness.runtime", "HarnessRuntime"),
     "HarnessRuntimeAdapter": ("ksadk.harness.runtime", "HarnessRuntimeAdapter"),
     "HarnessSandboxExecutor": ("ksadk.harness.sandbox", "HarnessSandboxExecutor"),
     "SandboxPolicyDenied": ("ksadk.harness.sandbox", "SandboxPolicyDenied"),
+    "ToolDeliverySemantics": (
+        "ksadk.harness.tool_reliability",
+        "ToolDeliverySemantics",
+    ),
+    "ToolReliability": ("ksadk.harness.tool_reliability", "ToolReliability"),
+    "classify_tool_reliability": (
+        "ksadk.harness.tool_reliability",
+        "classify_tool_reliability",
+    ),
 }
 
 __all__ = list(_EXPORTS)

ksadk/harness/app.py

@@ -10,6 +10,7 @@ from typing import Any, Callable, Optional, Protocol, Sequence
 from fastapi import FastAPI
 
 from ksadk.harness.config import HarnessConfig
+from ksadk.harness.insights import HarnessInsightsRegistry, mount_insights
 from ksadk.harness.reasoner import HarnessReasoner
 from ksadk.harness.runtime import HarnessRuntimeAdapter
 from ksadk.runtime import (
@@ -88,6 +89,8 @@ class HarnessApp:
         registry = RuntimeRegistry()
         registry.register(self._runtime_type, lambda _context: self.adapter())
         self._executor = RuntimeExecutor(registry)
+        # P3 补强：长任务洞察登记处（Studio 经 /insights API 消费）。
+        self._insights = HarnessInsightsRegistry()
 
         from ksadk.sessions import create_session_service
 
@@ -120,6 +123,11 @@ class HarnessApp:
     def executor(self) -> RuntimeExecutor:
         return self._executor
 
+    @property
+    def insights(self) -> HarnessInsightsRegistry:
+        """长任务洞察登记处（context-trace / token-report 的数据源）。"""
+        return self._insights
+
     @property
     def launch_context(self) -> RuntimeLaunchContext:
         return self._launch_context
@@ -260,6 +268,9 @@ class HarnessApp:
         )
         app.state.runtime.session_service = self._session_service
         app.state.runtime.harness_capabilities = self._capabilities
+        # P3 补强：Studio 消费端（长任务方案 §3.2）——/insights/runs/...
+        # 的 context-trace / token-report / compaction-trace 纯 dict 投影。
+        mount_insights(app, self._insights)
         for plugin in self._plugins:
             plugin.after_build(app, self._config)
         self._fastapi_app = app

ksadk/harness/artifact_store.py

@@ -0,0 +1,213 @@
+"""Harness Artifact Store（缺口 5 / plan §6.2 大结果外置）。
+
+工具产出的大结果（报表、文件、生成物）落工作区磁盘，State/事件流只带
+引用（``artifact.created`` payload 的 ``uri``）。同一 ``(run, name)`` 重复
+保存递增 ``version``，历史版本保留可下载。
+
+存储形态：内容文件 ``{root}/{run_id}/{name}.v{version}`` + SQLite 索引
+（run_id / name / version / mime / content_hash / bytes / created_at）。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ArtifactRecord:
+    run_id: str
+    name: str
+    version: int
+    mime: str
+    content_hash: str
+    bytes: int
+    uri: str
+    created_at: str
+
+
+class ArtifactStore:
+    """Run 作用域 Artifact 持久化（线程安全由 SQLite 连接锁保证）。"""
+
+    def __init__(self, root: str | Path, db_path: str | Path | None = None) -> None:
+        self._root = Path(root)
+        self._root.mkdir(parents=True, exist_ok=True)
+        self._db = sqlite3.connect(str(db_path or self._root / "artifacts.sqlite3"))
+        self._db.execute(
+            """
+            CREATE TABLE IF NOT EXISTS artifacts (
+                run_id TEXT NOT NULL,
+                name TEXT NOT NULL,
+                version INTEGER NOT NULL,
+                mime TEXT NOT NULL DEFAULT "text/plain",
+                content_hash TEXT NOT NULL,
+                bytes INTEGER NOT NULL,
+                uri TEXT NOT NULL,
+                created_at TEXT NOT NULL,
+                PRIMARY KEY (run_id, name, version)
+            )
+            """
+        )
+        self._db.commit()
+
+    # ------------------------------------------------------------- 写入
+
+    def save(
+        self, *, run_id: str, name: str, content: bytes, mime: str = "text/plain"
+    ) -> ArtifactRecord:
+        name = _safe_name(name)
+        if not name:
+            raise ValueError("artifact name 不能为空")
+        run_id = _safe_name(run_id)
+        if not run_id:
+            raise ValueError("run_id 不能为空")
+        version = self._next_version(run_id, name)
+        digest = "sha256:" + hashlib.sha256(content).hexdigest()
+        directory = self._root / run_id
+        directory.mkdir(parents=True, exist_ok=True)
+        file_path = directory / f"{name}.v{version}"
+        # 目录穿越防线：规范化后必须仍在 Store 根目录内（run_id/name 已各
+        # 自过 _safe_name，此处校验最终落点，防御纵深）。
+        _assert_within_root(self._root, file_path)
+        file_path.write_bytes(content)
+        uri = f"artifact://{run_id}/{name}@v{version}"
+        record = ArtifactRecord(
+            run_id=run_id,
+            name=name,
+            version=version,
+            mime=mime,
+            content_hash=digest,
+            bytes=len(content),
+            uri=uri,
+            created_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        )
+        self._db.execute(
+            "INSERT INTO artifacts VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                record.run_id,
+                record.name,
+                record.version,
+                record.mime,
+                record.content_hash,
+                record.bytes,
+                record.uri,
+                record.created_at,
+            ),
+        )
+        self._db.commit()
+        return record
+
+    # ------------------------------------------------------------- 读取
+
+    def list(self, run_id: str, *, name: str | None = None) -> list[ArtifactRecord]:
+        run_id = _safe_name(run_id)
+        query = "SELECT * FROM artifacts WHERE run_id = ?"
+        params: list[Any] = [run_id]
+        if name is not None:
+            query += " AND name = ?"
+            params.append(_safe_name(name))
+        query += " ORDER BY name, version"
+        rows = self._db.execute(query, params).fetchall()
+        return [_record(row) for row in rows]
+
+    def latest(self, run_id: str, name: str) -> ArtifactRecord | None:
+        records = self.list(run_id, name=name)
+        return records[-1] if records else None
+
+    def read(self, record: ArtifactRecord) -> bytes:
+        return self._read_uri(record.uri)
+
+    def read_latest(self, run_id: str, name: str) -> bytes | None:
+        record = self.latest(run_id, name)
+        return None if record is None else self.read(record)
+
+    def _read_uri(self, uri: str) -> bytes:
+        # uri: artifact://{run_id}/{name}@v{version}
+        try:
+            body = uri[len("artifact://") :]
+            run_id, rest = body.split("/", 1)
+            name, version = rest.rsplit("@v", 1)
+            file_path = self._root / _safe_name(run_id) / f"{_safe_name(name)}.v{int(version)}"
+        except ValueError as exc:
+            raise ValueError(f"非法 artifact uri: {uri!r}") from exc
+        _assert_within_root(self._root, file_path)
+        if not file_path.is_file():
+            raise FileNotFoundError(f"artifact 内容缺失: {uri}")
+        return file_path.read_bytes()
+
+    # ------------------------------------------------------------- 内部
+
+    def _next_version(self, run_id: str, name: str) -> int:
+        row = self._db.execute(
+            "SELECT MAX(version) FROM artifacts WHERE run_id = ? AND name = ?",
+            (run_id, name),
+        ).fetchone()
+        return (row[0] or 0) + 1
+
+    def close(self) -> None:
+        self._db.close()
+
+
+class BudgetedArtifactStore:
+    """Run 级写入守卫；在委托真实 Store 前原子检查数量预算。"""
+
+    def __init__(self, store: ArtifactStore, *, run_id: str, max_artifacts: int) -> None:
+        self._store = store
+        self._run_id = run_id
+        self._max_artifacts = max_artifacts
+
+    def save(self, *, run_id: str, name: str, content: bytes, mime: str = "text/plain"):
+        if run_id != self._run_id:
+            raise ValueError("budgeted artifact store run_id mismatch")
+        if len(self._store.list(run_id)) >= self._max_artifacts:
+            raise ArtifactBudgetExceeded(
+                f"artifact budget {self._max_artifacts} exhausted before write"
+            )
+        return self._store.save(run_id=run_id, name=name, content=content, mime=mime)
+
+    def list(self, run_id: str, *, name: str | None = None):
+        return self._store.list(run_id, name=name)
+
+    def __getattr__(self, name: str):
+        return getattr(self._store, name)
+
+
+class ArtifactBudgetExceeded(ValueError):
+    """Artifact 写入在产生文件或索引副作用前被预算拒绝。"""
+
+
+def _safe_name(name: str) -> str:
+    keep = [c if (c.isalnum() or c in "-_.") else "_" for c in str(name or "").strip()]
+    return "".join(keep)[:128]
+
+
+def _assert_within_root(root: Path, path: Path) -> None:
+    root_resolved = root.resolve()
+    path_resolved = path.resolve()
+    if root_resolved != path_resolved and root_resolved not in path_resolved.parents:
+        raise ValueError(f"artifact 路径越界: {path}")
+
+
+def _record(row: tuple) -> ArtifactRecord:
+    return ArtifactRecord(
+        run_id=row[0],
+        name=row[1],
+        version=int(row[2]),
+        mime=row[3],
+        content_hash=row[4],
+        bytes=int(row[5]),
+        uri=row[6],
+        created_at=row[7],
+    )
+
+
+__all__ = [
+    "ArtifactBudgetExceeded",
+    "ArtifactRecord",
+    "ArtifactStore",
+    "BudgetedArtifactStore",
+]