agentengine-sdk-python 0.8.1__py3-none-any.whl → 0.8.3__py3-none-any.whl

ksadk/configs/env_registry.py

@@ -1,18 +1,16 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
-
-
-@dataclass(frozen=True)
-class EnvVarSpec:
-    name: str
-    module: str
-    purpose: str
-    default: str = ""
-    sensitive: bool = False
-
+from ksadk.configs.env_registry_pcm import PCM_ENV_VAR_REGISTRY_ITEMS
+from ksadk.configs.env_var_spec import EnvVarSpec
 
 _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
+    EnvVarSpec(
+        "KSADK_AGENT_EVAL",
+        "evaluation",
+        "Enable internal Agent evaluation integration.",
+        "0",
+        documented=False,
+    ),
     EnvVarSpec("KSADK_ADK_RESUMABLE", "runners", "Enable ADK invocation resume support.", "false"),
     EnvVarSpec("KSADK_ADK_SESSION_BACKEND", "sessions", "ADK-native session backend selector."),
     EnvVarSpec("KSADK_ADK_SESSION_PATH", "sessions", "ADK-native SQLite session database path."),
@@ -234,12 +232,42 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "Isolate native Codex state under the project workspace; set to 0 for debugging only.",
         "1",
     ),
+    EnvVarSpec(
+        "KSADK_DSH_BIN",
+        "plugins",
+        (
+            "Optional absolute path to the managed DSH command; must match the pinned "
+            "toolchain version."
+        ),
+    ),
+    EnvVarSpec(
+        "KSADK_DSH_HOME",
+        "plugins",
+        (
+            "Directory containing the isolated DSH Profile; defaults to .agentkit/dsh-home "
+            "in the workspace."
+        ),
+    ),
+    EnvVarSpec(
+        "KSADK_DSH_PROFILE",
+        "plugins",
+        "DSH Profile name used by Studio and the plugin bridge.",
+        "studio",
+    ),
     EnvVarSpec(
         "KSADK_STUDIO_NO_SECURITY",
         "studio",
         "Disable Studio loopback session and CSRF checks for controlled tests only.",
         "0",
     ),
+    EnvVarSpec(
+        "KSADK_STUDIO_AUTHORIZER",
+        "studio",
+        "Internal authoring backend selector; bounded chat is the default and the "
+        "filesystem-capable Codex authorizer requires an explicit opt-in.",
+        "chat",
+        documented=False,
+    ),
     EnvVarSpec(
         "KSADK_STUDIO_SESSION_TOKEN",
         "studio",
@@ -278,6 +306,19 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "Enable L2 snip deterministic redundancy removal in compaction pipeline.",
         "true",
     ),
+    *PCM_ENV_VAR_REGISTRY_ITEMS,
+    EnvVarSpec(
+        "KSADK_DEPLOYMENT_MODE",
+        "runtime",
+        "Deployment-mode ownership declaration.",
+        documented=False,
+    ),
+    EnvVarSpec(
+        "KSADK_EVAL_COMMIT",
+        "evaluation",
+        "Source commit recorded by evaluation runs.",
+        documented=False,
+    ),
     EnvVarSpec(
         "KSADK_CORE_RUNTIME_REQUIREMENTS",
         "builders",
@@ -334,6 +375,15 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "LangGraph PostgreSQL checkpoint DSN.",
         sensitive=True,
     ),
+    EnvVarSpec(
+        "KSADK_LANGGRAPH_AUTO_CHECKPOINT",
+        "sessions",
+        (
+            "Allow a hosted LangGraph runner to rebuild a factory-exported graph with the "
+            "managed PostgreSQL saver."
+        ),
+        "false",
+    ),
     EnvVarSpec(
         "KSADK_LOCAL_SKILLS_DIR", "skills", "Local directory containing extracted Skill packages."
     ),
@@ -453,12 +503,30 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "runners",
         "Header name for remote Responses session propagation.",
     ),
+    EnvVarSpec(
+        "KSADK_RUNTIME_IMAGE_SOURCE_COMMIT",
+        "runtime",
+        "Build-injected source commit for Runtime image provenance.",
+        documented=False,
+    ),
+    EnvVarSpec(
+        "KSADK_RUNTIME_IMAGE_WHEEL_SHA256",
+        "runtime",
+        "Build-injected wheel digest for Runtime image provenance.",
+        documented=False,
+    ),
     EnvVarSpec(
         "KSADK_RUNTIME_PORT", "cli", "Runtime HTTP port exported to template runtimes.", "8080"
     ),
     EnvVarSpec(
         "KSADK_RUNTIME_REQUIREMENTS", "builders", "Internal bundled runtime requirements constant."
     ),
+    EnvVarSpec(
+        "KSADK_RUNTIME_STATE_DIR",
+        "runtime",
+        "Internal Runtime state directory override.",
+        documented=False,
+    ),
     EnvVarSpec(
         "KSADK_ALLOW_POD_PROCESS_TOOLS",
         "sandbox",
@@ -589,6 +657,20 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "KSADK_SESSION_DSN", "sessions", "Conversation session database DSN.", sensitive=True
     ),
     EnvVarSpec("KSADK_SESSION_NAMESPACE", "sessions", "Conversation session namespace."),
+    EnvVarSpec(
+        "KSADK_AGENT_ID",
+        "platform",
+        "Stable AgentEngine agent identity used only as a fallback checkpoint namespace.",
+    ),
+    EnvVarSpec(
+        "KSADK_AGENT_KERNEL",
+        "kernel",
+        (
+            "Opt in to Agent Kernel ingress locally; managed deployment may use "
+            "AGENT_KERNEL_ENABLED instead."
+        ),
+        "false",
+    ),
     EnvVarSpec("KSADK_SESSION_PATH", "sessions", "Conversation local SQLite database path."),
     EnvVarSpec(
         "KSADK_SESSION_PG_CONNECT_TIMEOUT",
@@ -756,7 +838,7 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "KSADK_WEB_VERSION",
         "web",
         "Published KsADK Web npm version used for a reproducible wheel build.",
-        "0.3.1",
+        "0.3.4",
     ),
     EnvVarSpec(
         "KSADK_WORKING_SET_MAX_FILES",

ksadk/configs/env_registry_pcm.py

@@ -0,0 +1,181 @@
+"""Prompt, Context and Memory environment-variable registry entries."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from ksadk.configs.env_var_spec import EnvVarSpec
+
+_PCM_ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
+    EnvVarSpec("KSADK_BASELINE_COLLECT", "context", "Enable PCM baseline collection.", "0"),
+    EnvVarSpec(
+        "KSADK_BASELINE_EXECUTION_TARGET", "context", "PCM baseline execution target label."
+    ),
+    EnvVarSpec(
+        "KSADK_BASELINE_FLUSH_EACH_TURN",
+        "context",
+        "Flush PCM baseline output after every turn.",
+        "0",
+    ),
+    EnvVarSpec("KSADK_BASELINE_PATH", "context", "PCM baseline JSONL output path."),
+    EnvVarSpec("KSADK_COMPACT_HARD_LIMIT_PCT", "context", "Hard compaction threshold percentage."),
+    EnvVarSpec(
+        "KSADK_COMPACT_HARD_LIMIT_PCT_DEFAULT",
+        "context",
+        "Default hard compaction threshold percentage.",
+    ),
+    EnvVarSpec("KSADK_COMPACT_SOFT_LIMIT_PCT", "context", "Soft compaction threshold percentage."),
+    EnvVarSpec(
+        "KSADK_COMPACT_SOFT_LIMIT_PCT_DEFAULT",
+        "context",
+        "Default soft compaction threshold percentage.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_CACHE_BREAK_OBSERVABILITY",
+        "context",
+        "Enable prompt cache-break diagnostics.",
+        "0",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_CONTRIBUTOR_ALLOW_PLATFORM_TRUST",
+        "context",
+        "Allow trusted platform context contributors.",
+        "0",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_CONTRIBUTOR_FAILURE_MODE",
+        "context",
+        "Context contributor failure policy.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_CONTRIBUTOR_TIMEOUT_MS",
+        "context",
+        "Context contributor timeout in milliseconds.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_EMERGENCY_KEEP_TAIL_GROUPS",
+        "context",
+        "Recent event groups retained during emergency compaction.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_ENGINE_V2_ENABLED", "context", "Enable the PCM context planner.", "0"
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_HARD_LIMIT_PERCENT",
+        "context",
+        "Hard request-context budget threshold percentage.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_KEEP_TAIL_GROUPS",
+        "context",
+        "Recent event groups retained during normal compaction.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_MAX_RETRY_AFTER_PTL",
+        "context",
+        "Maximum controlled retries after prompt-too-long.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_RULE_FILES_MAX_TOKENS", "context", "Combined rule-file token budget."
+    ),
+    EnvVarSpec("KSADK_CONTEXT_RULE_FILE_MAX_TOKENS", "context", "Per rule-file token budget."),
+    EnvVarSpec(
+        "KSADK_CONTEXT_SAFETY_BUFFER_TOKENS", "context", "Reserved context-window safety buffer."
+    ),
+    EnvVarSpec("KSADK_CONTEXT_SEMANTIC_ENABLED", "context", "Enable semantic compaction.", "0"),
+    EnvVarSpec(
+        "KSADK_CONTEXT_SEMANTIC_TIMEOUT_MS",
+        "context",
+        "Semantic compaction timeout in milliseconds.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_SOFT_LIMIT_PERCENT",
+        "context",
+        "Soft request-context budget threshold percentage.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_TOOL_RESULT_MAX_TOKENS",
+        "context",
+        "Maximum token budget for one tool result.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_WORKING_STATE_ENABLED",
+        "context",
+        "Enable structured working-state extraction.",
+        "0",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_WORKING_STATE_EXTRACTION_TIMEOUT_MS",
+        "context",
+        "Working-state extraction timeout in milliseconds.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_WORKING_STATE_MAX_TOKENS", "context", "Working-state token budget."
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_WORKING_STATE_MIN_TOKEN_GROWTH",
+        "context",
+        "Minimum growth before refreshing working state.",
+    ),
+    EnvVarSpec(
+        "KSADK_LTM_FORCE_INMEMORY",
+        "memory",
+        "Force in-memory long-term-memory backend for tests.",
+        "0",
+    ),
+    EnvVarSpec("KSADK_MEMORY_CORE_MAX_TOKENS", "memory", "Core-memory token budget."),
+    EnvVarSpec("KSADK_MEMORY_DB_PATH", "memory", "Local PCM memory database path."),
+    EnvVarSpec("KSADK_MEMORY_ENABLED", "memory", "Enable platform memory projection.", "0"),
+    EnvVarSpec(
+        "KSADK_MEMORY_FLUSH_BEFORE_COMPACTION",
+        "memory",
+        "Flush memory candidates before compaction.",
+        "0",
+    ),
+    EnvVarSpec("KSADK_MEMORY_FLUSH_ENABLED", "memory", "Enable memory candidate commit.", "0"),
+    EnvVarSpec("KSADK_MEMORY_MIN_SCORE", "memory", "Minimum memory recall relevance score."),
+    EnvVarSpec(
+        "KSADK_MEMORY_MAX_RECORDS",
+        "memory",
+        "Maximum retained records for the local PCM memory provider.",
+        "10000",
+    ),
+    EnvVarSpec("KSADK_MEMORY_PROVIDER", "memory", "Platform memory provider selector."),
+    EnvVarSpec("KSADK_MEMORY_RECALL_MAX_TOKENS", "memory", "Memory recall token budget."),
+    EnvVarSpec("KSADK_MEMORY_RECALL_TOP_K", "memory", "Maximum recalled memory items."),
+    EnvVarSpec(
+        "KSADK_MEMORY_RETENTION_DAYS",
+        "memory",
+        "Retention period in days for the local PCM memory provider.",
+        "90",
+    ),
+    EnvVarSpec(
+        "KSADK_MEMORY_WRITE_MODE",
+        "memory",
+        "Memory write mode: off, explicit-only, or candidate.",
+    ),
+    EnvVarSpec(
+        "KSADK_PLATFORM_SAFETY_TEXT",
+        "prompt",
+        "Platform safety rules injected by the prompt compiler.",
+    ),
+    EnvVarSpec(
+        "KSADK_PROMPT_AUTO_DISCOVERY", "prompt", "Enable project prompt-source discovery.", "0"
+    ),
+    EnvVarSpec(
+        "KSADK_PROMPT_COMPILER_ENABLED", "prompt", "Enable structured prompt compilation.", "0"
+    ),
+    EnvVarSpec(
+        "KSADK_TOKENIZER_PROVIDER", "context", "Tokenizer provider used for context accounting."
+    ),
+)
+
+# PCM rollout, budget and diagnostic environment variables are internal runtime
+# controls. Public users configure the same behavior through AgentSpec policies,
+# so these names intentionally do not expand the public environment reference.
+PCM_ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = tuple(
+    replace(item, documented=False) for item in _PCM_ENV_VAR_REGISTRY_ITEMS
+)
+
+
+__all__ = ["PCM_ENV_VAR_REGISTRY_ITEMS"]

ksadk/configs/env_var_spec.py

@@ -0,0 +1,18 @@
+"""Shared environment-variable registry value object."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class EnvVarSpec:
+    name: str
+    module: str
+    purpose: str
+    default: str = ""
+    sensitive: bool = False
+    documented: bool = True
+
+
+__all__ = ["EnvVarSpec"]

ksadk/configs/global_config.py

@@ -43,6 +43,11 @@ CONFIG_GROUPS = {
         # 嵌套对象，get_env_from_global_config 跳过它（不当 env-var），build 保留它
         "IDENTITY_CACHE",
     ],
+    "evaluation": [
+        "AGENT_EVAL_BASE_URL",
+        "AGENT_EVAL_API_TOKEN",
+        "AGENT_EVAL_ACCOUNT_ID",
+    ],
     # 未来可扩展更多分组
     # "observability": ["OTEL_EXPORTER_OTLP_ENDPOINT", ...],
     # "plugins": {...},

ksadk/configs/settings.py

@@ -628,3 +628,12 @@ def setup_environment(agent_path: Path | str):
         setup_proxy_redirect_if_enabled()
     except Exception:  # noqa: BLE001  代理可选,失败不影响主流程(默认关时本就不触发)
         pass
+
+    # 5. 沙箱控制面 URL 内网探测:在 Pod 内探测 198 公共服务网内网地址,
+    # 可达则覆盖 E2B_API_URL 为内网域名,private_only 节点也能访问沙箱控制面。
+    try:
+        from ksadk.sandbox import setup_sandbox_api_url_if_needed
+
+        setup_sandbox_api_url_if_needed()
+    except Exception:  # noqa: BLE001  沙箱可选,失败不影响主流程
+        pass

ksadk/context_engine/__init__.py

@@ -0,0 +1,98 @@
+"""Context Engine —— Prompt/Context/Memory 的运行时上下文协调层。
+
+数据模型、capability 合同与 shadow 可观测基线已落地；后续 PR 新增 planner / assembler /
+policies / contributors 的实际逻辑。本模块导出稳定类型与运行时合同。
+"""
+
+from ksadk.context_engine.assembler import AssembledInput, ContextAssembler, assemble
+from ksadk.context_engine.capabilities import (
+    DEFAULT_CONTEXT_CAPABILITIES,
+    CapabilityCircuitOpen,
+    ContextAccuracy,
+    ContextCapabilities,
+    ContextIntegrationMode,
+    ContextOwner,
+    DeploymentMode,
+    adk_context_capabilities,
+    assert_capability_not_circuit_open,
+    capabilities_for_runner,
+    capabilities_for_runtime_type,
+    capability_hash,
+    codex_context_capabilities,
+    deepagents_context_capabilities,
+    detect_capability_mismatch,
+    is_capability_circuit_open,
+    langchain_context_capabilities,
+    langgraph_context_capabilities,
+    mark_capability_mismatch,
+    reset_capability_circuit,
+)
+from ksadk.context_engine.models import (
+    CONTEXT_POLICY_VERSION,
+    ContextBudget,
+    ContextDecision,
+    ContextItem,
+    ContextKind,
+    ContextPlan,
+)
+from ksadk.context_engine.planner import ContextPlanner, build_budget
+from ksadk.context_engine.policies import (
+    ContextBudgetPolicy,
+    ContextPolicy,
+    SectionBudget,
+    compute_budget_tokens,
+)
+from ksadk.context_engine.projection import PROJECTION_VERSION, ProjectionResult
+from ksadk.context_engine.tokenizer import (
+    HEURISTIC_TOKENIZER_NAME,
+    HeuristicTokenCounter,
+    TokenCounter,
+    get_default_token_counter,
+)
+
+__all__ = [
+    "AssembledInput",
+    "CONTEXT_POLICY_VERSION",
+    "ContextAssembler",
+    "ContextAccuracy",
+    "ContextBudget",
+    "ContextBudgetPolicy",
+    "ContextCapabilities",
+    "ContextDecision",
+    "ContextIntegrationMode",
+    "ContextItem",
+    "ContextKind",
+    "ContextOwner",
+    "ContextPlan",
+    "ContextPlanner",
+    "ContextPolicy",
+    "DEFAULT_CONTEXT_CAPABILITIES",
+    "DeploymentMode",
+    "HEURISTIC_TOKENIZER_NAME",
+    "HeuristicTokenCounter",
+    "PROJECTION_VERSION",
+    "ProjectionResult",
+    "SectionBudget",
+    "TokenCounter",
+    "adk_context_capabilities",
+    "assemble",
+    "build_budget",
+    "capabilities_for_runner",
+    "capabilities_for_runtime_type",
+    "capability_hash",
+    "codex_context_capabilities",
+    "compute_budget_tokens",
+    "deepagents_context_capabilities",
+    "detect_capability_mismatch",
+    "get_default_token_counter",
+    "is_capability_circuit_open",
+    "langchain_context_capabilities",
+    "langgraph_context_capabilities",
+    "mark_capability_mismatch",
+    "reset_capability_circuit",
+    "assert_capability_not_circuit_open",
+    "CapabilityCircuitOpen",
+    "allowed_ownership_choices",
+    "validate_ownership_for_runtime",
+    "resolve_ownership",
+]

ksadk/context_engine/assembler.py

@@ -0,0 +1,176 @@
+"""Context Assembler —— 把 ContextPlan.selected 投影成 messages/responses 输入（方案 §8）。
+
+Assembler 是 KsADK-owned（``ksadk_hosted``）路径的最终输入组装器：把 ``ContextPlan.selected``
+按方案 §7.4 的稳定前缀→部署级→动态后缀顺序投影成 Chat/Responses 格式。assisted/native 路径
+不调用本模块，由 RuntimeAdapter 自行投影（方案 §6.2）。
+
+第一个版本只实现 Chat messages 与 Responses items 两种合法投影，不含模型调用；actual_token
+由调用方在收到 usage 后回填 ``ContextPlan.runtime_reported_input_tokens``。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from ksadk.context_engine.models import ContextItem, ContextPlan
+
+ProjectionFormat = Literal["chat", "responses"]
+
+
+@dataclass(frozen=True)
+class AssembledInput:
+    """组装后的模型输入（shadow/可观测用，不直接发模型）。"""
+
+    format: ProjectionFormat
+    system: str
+    messages: list[dict[str, Any]]
+    responses_items: list[dict[str, Any]]
+    estimated_tokens: int
+    warnings: tuple[str, ...] = ()
+
+
+def _item_text(item: ContextItem) -> str:
+    content = item.content
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for part in content:
+            if isinstance(part, str):
+                parts.append(part)
+            elif isinstance(part, dict):
+                t = part.get("text") or part.get("content")
+                if isinstance(t, str):
+                    parts.append(t)
+        return "\n".join(parts)
+    return str(content or "")
+
+
+def _split_prompt_and_rest(selected: list[ContextItem]) -> tuple[str, list[ContextItem]]:
+    """稳定前缀（compiled_prompt）单独提为 system，其余按顺序进入 messages。"""
+    prompt_text = ""
+    rest: list[ContextItem] = []
+    for item in selected:
+        if item.kind == "compiled_prompt":
+            prompt_text = (
+                (prompt_text + "\n\n" + _item_text(item)).strip("\n\n")
+                if prompt_text
+                else _item_text(item)
+            )
+        else:
+            rest.append(item)
+    return prompt_text, rest
+
+
+def _role_for(item: ContextItem) -> str:
+    if item.kind == "current_input":
+        return "user"
+    if item.kind == "history_round":
+        # history_round 的 content 形如 {"role": "...", "content": ...} 或带 role metadata
+        role = item.metadata.get("role")
+        if isinstance(role, str):
+            return role
+        return "assistant"
+    if item.kind == "tool_result":
+        return "tool"
+    return "assistant"
+
+
+def _current_input_last(items: list[ContextItem]) -> list[ContextItem]:
+    """Keep the canonical current input at the end of Chat chronology.
+
+    Planner order represents retention priority, not physical message order. If
+    ``current_input`` is projected before selected history, the runner can treat
+    it as history and inject it again as the new input. Preserve every other
+    item's relative order and move only ``current_input`` to the end.
+    """
+
+    return [item for item in items if item.kind != "current_input"] + [
+        item for item in items if item.kind == "current_input"
+    ]
+
+
+class ContextAssembler:
+    """把 ContextPlan 投影成 Chat/Responses 输入（方案 §8）。
+
+    纯函数式、无副作用。``assemble_chat`` 输出 OpenAI Chat 风格 messages；
+    ``assemble_responses`` 输出 Responses API items。两者共用同一 selected 顺序。
+    """
+
+    def assemble_chat(self, plan: ContextPlan) -> AssembledInput:
+        system, rest = _split_prompt_and_rest(plan.selected)
+        rest = _current_input_last(rest)
+        messages: list[dict[str, Any]] = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        warnings: list[str] = []
+        for item in rest:
+            role = _role_for(item)
+            content = _item_text(item)
+            if item.metadata.get("truncated_to_tokens") is not None:
+                warnings.append(f"{item.item_id}:truncated")
+            if item.metadata.get("replaced_with_artifact_summary"):
+                warnings.append(f"{item.item_id}:artifact_summary")
+            messages.append({"role": role, "content": content, "name": item.metadata.get("name")})
+        return AssembledInput(
+            format="chat",
+            system=system,
+            messages=messages,
+            responses_items=[],
+            estimated_tokens=plan.planned_input_tokens,
+            warnings=tuple(warnings),
+        )
+
+    def assemble_responses(self, plan: ContextPlan) -> AssembledInput:
+        system, rest = _split_prompt_and_rest(plan.selected)
+        rest = _current_input_last(rest)
+        items: list[dict[str, Any]] = []
+        if system:
+            items.append(
+                {
+                    "type": "message",
+                    "role": "system",
+                    "content": [{"type": "input_text", "text": system}],
+                }
+            )
+        warnings: list[str] = []
+        for item in rest:
+            role = _role_for(item)
+            content = _item_text(item)
+            if item.metadata.get("truncated_to_tokens") is not None:
+                warnings.append(f"{item.item_id}:truncated")
+            if item.kind == "tool_result":
+                # Responses function_call_output
+                call_id = str(
+                    item.metadata.get("call_id") or item.metadata.get("tool_call_id") or ""
+                )
+                items.append(
+                    {"type": "function_call_output", "call_id": call_id, "output": content}
+                )
+            else:
+                item_type = "input_text" if role == "user" else "output_text"
+                items.append(
+                    {
+                        "type": "message",
+                        "role": role,
+                        "content": [{"type": item_type, "text": content}],
+                    }
+                )
+        return AssembledInput(
+            format="responses",
+            system=system,
+            messages=[],
+            responses_items=items,
+            estimated_tokens=plan.planned_input_tokens,
+            warnings=tuple(warnings),
+        )
+
+
+def assemble(plan: ContextPlan, *, fmt: ProjectionFormat = "chat") -> AssembledInput:
+    """便捷入口。"""
+    asm = ContextAssembler()
+    return asm.assemble_chat(plan) if fmt == "chat" else asm.assemble_responses(plan)
+
+
+__all__ = ["AssembledInput", "ContextAssembler", "ProjectionFormat", "assemble"]