ummaya 0.2.3 → 0.2.5

package/src/ummaya/llm/client.py

@@ -10,8 +10,9 @@ import logging
 import os
 import random
 import time
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Iterator
 from contextvars import Token
+from copy import deepcopy
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, cast
 
@@ -39,6 +40,7 @@ from ummaya.llm.models import (
     ToolCall,
     ToolDefinition,
 )
+from ummaya.llm.reasoning import ReasoningMode, resolve_reasoning_policy
 from ummaya.llm.usage import UsageTracker
 from ummaya.observability.semconv import (
     ERROR_TYPE,
@@ -167,6 +169,62 @@ def _compute_prompt_hash(system_text: str) -> str:
     return hashlib.sha256(hashed.encode("utf-8")).hexdigest()
 
 
+def _provider_safe_parameters_schema(schema: dict[str, object]) -> dict[str, object]:
+    """Inline Pydantic-local JSON Schema refs before sending tool schemas."""
+    root = deepcopy(schema)
+    defs_obj = root.get("$defs")
+    defs: dict[str, object] = {}
+    if isinstance(defs_obj, dict):
+        defs = {str(name): value for name, value in defs_obj.items()}
+
+    inlined = _inline_local_json_schema_refs(root, defs, ())
+    if not isinstance(inlined, dict):
+        raise ValueError("OpenAI tool parameters schema must be a JSON object")
+    return cast(dict[str, object], inlined)
+
+
+def _inline_local_json_schema_refs(
+    node: object,
+    defs: dict[str, object],
+    stack: tuple[str, ...],
+) -> object:
+    if isinstance(node, list):
+        return [_inline_local_json_schema_refs(item, defs, stack) for item in node]
+    if not isinstance(node, dict):
+        return node
+
+    ref_name = _local_def_ref_name(node.get("$ref"))
+    if ref_name is not None:
+        if ref_name in stack:
+            raise ValueError(f"Cyclic JSON Schema reference is not supported: #/$defs/{ref_name}")
+        if ref_name not in defs:
+            raise ValueError(f"Unknown JSON Schema reference: #/$defs/{ref_name}")
+
+        target = deepcopy(defs[ref_name])
+        expanded = _inline_local_json_schema_refs(target, defs, (*stack, ref_name))
+        siblings = {str(key): value for key, value in node.items() if key not in {"$ref", "$defs"}}
+        if not siblings:
+            return expanded
+        if not isinstance(expanded, dict):
+            raise ValueError(f"JSON Schema reference target must be an object: #/$defs/{ref_name}")
+        merged = cast(dict[str, object], expanded).copy()
+        for key, value in siblings.items():
+            merged[key] = _inline_local_json_schema_refs(value, defs, stack)
+        return merged
+
+    return {
+        str(key): _inline_local_json_schema_refs(value, defs, stack)
+        for key, value in node.items()
+        if key != "$defs"
+    }
+
+
+def _local_def_ref_name(ref: object) -> str | None:
+    if not isinstance(ref, str) or not ref.startswith("#/$defs/"):
+        return None
+    return ref.removeprefix("#/$defs/").replace("~1", "/").replace("~0", "~")
+
+
 class LLMClient:
     """Async LLM client for FriendliAI Serverless endpoint."""
 
@@ -238,6 +296,7 @@ class LLMClient:
         presence_penalty: float = 0.0,
         max_tokens: int = 1024,
         stop: list[str] | None = None,
+        reasoning_mode: ReasoningMode | str | None = None,
     ) -> ChatCompletionResponse:
         """Send a non-streaming chat completion request.
 
@@ -271,6 +330,7 @@ class LLMClient:
             tools=tools,
             tool_choice=tool_choice,
             stream=False,
+            reasoning_mode=reasoning_mode,
         )
 
         logger.debug(
@@ -365,6 +425,7 @@ class LLMClient:
         presence_penalty: float = 0.0,
         max_tokens: int = 1024,
         stop: list[str] | None = None,
+        reasoning_mode: ReasoningMode | str | None = None,
     ) -> AsyncIterator[StreamEvent]:
         """Send a streaming chat completion request.
 
@@ -403,7 +464,9 @@ class LLMClient:
             tools=tools,
             tool_choice=tool_choice,
             stream=True,
+            reasoning_mode=reasoning_mode,
         )
+        allow_reasoning = payload.get("include_reasoning") is True
 
         logger.debug(
             "LLM stream request: model=%s messages=%d",
@@ -447,7 +510,11 @@ class LLMClient:
         _finalize: dict[str, object] = {}
 
         try:
-            async for event in self._stream_with_retry(payload, _finalize):
+            async for event in self._stream_with_retry(
+                payload,
+                _finalize,
+                allow_reasoning=allow_reasoning,
+            ):
                 active_span.detach()
                 yield event
                 active_span.attach()
@@ -490,6 +557,8 @@ class LLMClient:
         self,
         payload: dict[str, object],
         _finalize: dict[str, object],
+        *,
+        allow_reasoning: bool,
     ) -> AsyncIterator[StreamEvent]:
         """Execute stream() with Retry-After-first backoff loop (T015/T016).
 
@@ -564,7 +633,38 @@ class LLMClient:
 
                         # Yield events; watch for mid-stream 429 envelopes (T016)
                         rate_limited_mid_stream = False
-                        async for line in response.aiter_lines():
+                        line_iter = response.aiter_lines()
+                        next_data_line_deadline = (
+                            time.monotonic() + self._config.stream_idle_timeout
+                        )
+                        while True:
+                            try:
+                                timeout_remaining = next_data_line_deadline - time.monotonic()
+                                if timeout_remaining <= 0:
+                                    raise TimeoutError
+                                line = await asyncio.wait_for(
+                                    anext(line_iter),
+                                    timeout=timeout_remaining,
+                                )
+                            except StopAsyncIteration:
+                                break
+                            except TimeoutError as exc:
+                                _duration_ms = (time.monotonic() - _stream_start) * 1000
+                                self._metrics_record_call(
+                                    success=False,
+                                    duration_ms=_duration_ms,
+                                )
+                                _metrics_recorded = True
+                                raise StreamInterruptedError(
+                                    "Stream idle timeout after "
+                                    f"{self._config.stream_idle_timeout:g}s "
+                                    "without a new SSE data line"
+                                ) from exc
+                            if not line.startswith("data: "):
+                                continue
+                            next_data_line_deadline = (
+                                time.monotonic() + self._config.stream_idle_timeout
+                            )
                             if self._is_rate_limit_envelope(line):
                                 rate_limited_mid_stream = True
                                 delay = self._compute_rate_limit_delay(response, attempt, policy)
@@ -607,7 +707,10 @@ class LLMClient:
                             if chunk_info.get("model"):
                                 _response_model = chunk_info["model"]
 
-                            async for event in self._parse_sse_line(line):
+                            async for event in self._parse_sse_line(
+                                line,
+                                allow_reasoning=allow_reasoning,
+                            ):
                                 yield event
                                 if event.type == "done":
                                     _duration_ms = (time.monotonic() - _stream_start) * 1000
@@ -848,7 +951,12 @@ class LLMClient:
             if i + step < n:
                 await asyncio.sleep(_LLM_STREAM_PACE_S)
 
-    async def _parse_sse_line(self, line: str) -> AsyncIterator[StreamEvent]:  # noqa: C901
+    async def _parse_sse_line(
+        self,
+        line: str,
+        *,
+        allow_reasoning: bool = False,
+    ) -> AsyncIterator[StreamEvent]:
         """Parse a single SSE line and yield corresponding StreamEvent(s)."""
         if not line or not line.startswith("data: "):
             return
@@ -859,14 +967,35 @@ class LLMClient:
             yield StreamEvent(type="done")
             return
 
+        chunk = self._decode_sse_payload(payload_text)
+        if chunk is None:
+            return
+
+        usage_event = self._usage_event_from_chunk(chunk)
+        if usage_event is not None:
+            yield usage_event
+
+        async for event in self._events_from_sse_choices(
+            chunk,
+            allow_reasoning=allow_reasoning,
+        ):
+            yield event
+
+    def _decode_sse_payload(self, payload_text: str) -> dict[str, object] | None:
+        """Decode a JSON SSE payload, returning None for malformed chunks."""
         try:
             chunk = json.loads(payload_text)
         except json.JSONDecodeError:
             logger.warning("Failed to parse SSE chunk: %r", payload_text)
-            return
+            return None
+        return chunk if isinstance(chunk, dict) else None
 
+    def _usage_event_from_chunk(self, chunk: dict[str, object]) -> StreamEvent | None:
+        """Debit usage from a stream chunk and return the corresponding event."""
         if "usage" in chunk and chunk["usage"] is not None:
             raw_usage = chunk["usage"]
+            if not isinstance(raw_usage, dict):
+                return None
             usage = TokenUsage(
                 input_tokens=raw_usage.get("prompt_tokens", 0),
                 output_tokens=raw_usage.get("completion_tokens", 0),
@@ -877,66 +1006,104 @@ class LLMClient:
                 usage.output_tokens,
             )
             self._usage.debit(usage)
-            yield StreamEvent(type="usage", usage=usage)
+            return StreamEvent(type="usage", usage=usage)
+        return None
 
+    async def _events_from_sse_choices(
+        self,
+        chunk: dict[str, object],
+        *,
+        allow_reasoning: bool,
+    ) -> AsyncIterator[StreamEvent]:
+        """Yield stream events for the first OpenAI-compatible choice delta."""
         choices = chunk.get("choices")
         if not choices:
             return
+        if not isinstance(choices, list):
+            return
 
         choice = choices[0]
+        if not isinstance(choice, dict):
+            return
         delta = choice.get("delta", {})
+        if not isinstance(delta, dict):
+            return
 
+        async for event in self._events_from_sse_delta(
+            delta,
+            allow_reasoning=allow_reasoning,
+        ):
+            yield event
+
+    async def _events_from_sse_delta(
+        self,
+        delta: dict[str, object],
+        *,
+        allow_reasoning: bool,
+    ) -> AsyncIterator[StreamEvent]:
+        """Yield content, reasoning, and tool-call events from a delta object."""
         if "content" in delta and delta["content"] is not None:
             # CC reference: services/api/claude.ts:2113 (text_delta content_block_delta).
-            content = delta["content"]
+            content = str(delta["content"])
             async for sub in self._pace_text_chunk(content, "content"):
                 yield sub
         elif "reasoning_content" in delta and delta["reasoning_content"] is not None:
-            # CC reference: services/api/claude.ts:2148-2161 (thinking_delta
-            # content_block_delta) — K-EXAONE emits chain-of-thought on a
-            # separate ``delta.reasoning_content`` channel. Forwarding the
-            # same StreamEvent shape on UMMAYA lets the TUI's
-            # ``AssistantThinkingMessage`` component render the reasoning
-            # inline instead of swallowing it. Log only the chunk length —
-            # never the raw content (CoT may contain user PII or sensitive
-            # reasoning about user input).
-            reasoning_text = delta["reasoning_content"]
+            async for sub in self._events_from_reasoning_delta(
+                str(delta["reasoning_content"]),
+                allow_reasoning=allow_reasoning,
+            ):
+                yield sub
+
+        if "tool_calls" in delta and delta["tool_calls"]:
+            for event in self._events_from_tool_call_deltas(delta["tool_calls"]):
+                yield event
+
+    async def _events_from_reasoning_delta(
+        self,
+        reasoning_text: str,
+        *,
+        allow_reasoning: bool,
+    ) -> AsyncIterator[StreamEvent]:
+        """Yield reasoning text only when the request opted into reasoning parsing."""
+        if not allow_reasoning:
             logger.debug(
-                "Forwarding reasoning_content as thinking_delta (len=%d)",
+                "Suppressed unexpected reasoning_content while include_reasoning=false (len=%d)",
                 len(reasoning_text),
             )
-            async for sub in self._pace_text_chunk(reasoning_text, "thinking"):
-                yield sub
+            return
+        logger.debug(
+            "Forwarding reasoning_content as thinking_delta (len=%d)",
+            len(reasoning_text),
+        )
+        async for sub in self._pace_text_chunk(reasoning_text, "thinking"):
+            yield sub
 
-        if "tool_calls" in delta and delta["tool_calls"]:
-            # CC reference: services/api/claude.ts:1997 (tool_use content_block_start)
-            # + services/api/claude.ts:2087 (input_json_delta content_block_delta).
-            # FriendliAI's OpenAI-compatible streaming buffers tool_call argument
-            # JSON across multiple deltas (matching OpenAI's incremental parser).
-            # UMMAYA mirrors CC's pattern by emitting one StreamEvent per delta;
-            # the IPC bridge (stdio.py) accumulates them into the final
-            # ToolCallFrame.
-            for tc_delta in delta["tool_calls"]:
-                func = tc_delta.get("function", {})
-                # Log only tool metadata (index/id/name + arg length).
-                # Raw `arguments` often carries user-provided location strings
-                # or other PII — never log them.
-                _args_field = func.get("arguments")
-                _args_len = len(_args_field) if isinstance(_args_field, str) else 0
-                logger.debug(
-                    "tool_call_delta idx=%s id=%s name=%r args_len=%d",
-                    tc_delta.get("index"),
-                    tc_delta.get("id"),
-                    func.get("name"),
-                    _args_len,
-                )
-                yield StreamEvent(
-                    type="tool_call_delta",
-                    tool_call_index=tc_delta.get("index"),
-                    tool_call_id=tc_delta.get("id"),
-                    function_name=func.get("name"),
-                    function_args_delta=func.get("arguments"),
-                )
+    def _events_from_tool_call_deltas(self, tool_calls: object) -> Iterator[StreamEvent]:
+        """Yield tool-call deltas without logging raw argument content."""
+        if not isinstance(tool_calls, list):
+            return
+        for tc_delta in tool_calls:
+            if not isinstance(tc_delta, dict):
+                continue
+            func = tc_delta.get("function", {})
+            if not isinstance(func, dict):
+                func = {}
+            _args_field = func.get("arguments")
+            _args_len = len(_args_field) if isinstance(_args_field, str) else 0
+            logger.debug(
+                "tool_call_delta idx=%s id=%s name=%r args_len=%d",
+                tc_delta.get("index"),
+                tc_delta.get("id"),
+                func.get("name"),
+                _args_len,
+            )
+            yield StreamEvent(
+                type="tool_call_delta",
+                tool_call_index=tc_delta.get("index"),
+                tool_call_id=tc_delta.get("id"),
+                function_name=func.get("name"),
+                function_args_delta=func.get("arguments"),
+            )
 
     def _build_payload(
         self,
@@ -950,6 +1117,7 @@ class LLMClient:
         tools: list[ToolDefinition | dict[str, object]] | None = None,
         tool_choice: str | dict[str, object] | None = None,
         stream: bool,
+        reasoning_mode: ReasoningMode | str | None = None,
     ) -> dict[str, object]:
         """Construct the JSON payload for a chat completions request.
 
@@ -979,13 +1147,7 @@ class LLMClient:
         is not treated as normal assistant text and is never required for the
         default CLI/TUI path.
         """
-        import os  # noqa: PLC0415 — local import keeps top-level imports thin
-
-        enable_thinking = os.environ.get("UMMAYA_K_EXAONE_THINKING", "false").lower() in (
-            "true",
-            "1",
-            "yes",
-        )
+        reasoning = resolve_reasoning_policy(reasoning_mode)
 
         payload: dict[str, object] = {
             "model": self._config.model,
@@ -999,7 +1161,9 @@ class LLMClient:
             # enable_thinking=False the model emits an answer directly
             # without the <think>...</think> trace, dropping first-token
             # latency from ~60-180s to <10s for typical citizen prompts.
-            "chat_template_kwargs": {"enable_thinking": enable_thinking},
+            "chat_template_kwargs": {"enable_thinking": reasoning.enable_thinking},
+            "parse_reasoning": reasoning.parse_reasoning,
+            "include_reasoning": reasoning.include_reasoning,
         }
         if stop is not None:
             payload["stop"] = stop
@@ -1028,8 +1192,19 @@ class LLMClient:
         reaches FriendliAI's strict OpenAI-compatible validator.
         """
         if isinstance(tool, ToolDefinition):
-            return cast(dict[str, object], tool.model_dump())
-        return cast(dict[str, object], ToolDefinition.model_validate(tool).model_dump())
+            payload = cast(dict[str, object], tool.model_dump())
+        else:
+            payload = cast(dict[str, object], ToolDefinition.model_validate(tool).model_dump())
+
+        function_obj = payload.get("function")
+        if isinstance(function_obj, dict):
+            function = cast(dict[str, object], function_obj)
+            parameters_obj = function.get("parameters")
+            if isinstance(parameters_obj, dict):
+                function["parameters"] = _provider_safe_parameters_schema(
+                    cast(dict[str, object], parameters_obj)
+                )
+        return payload
 
     # ------------------------------------------------------------------
     # Private retry helpers (T015)

package/src/ummaya/llm/config.py

@@ -16,6 +16,7 @@ class LLMClientConfig(BaseSettings):
         UMMAYA_FRIENDLI_MODEL       — model identifier
         UMMAYA_LLM_SESSION_BUDGET   — per-session token budget
         UMMAYA_LLM_TIMEOUT_SECONDS  — HTTP stream timeout budget
+        UMMAYA_LLM_STREAM_IDLE_TIMEOUT_SECONDS — max idle gap between stream lines
     """
 
     model_config = SettingsConfigDict(
@@ -59,6 +60,11 @@ class LLMClientConfig(BaseSettings):
         ),
         description="HTTP request timeout in seconds.",
     )
+    stream_idle_timeout: float = Field(
+        default=90.0,
+        validation_alias="UMMAYA_LLM_STREAM_IDLE_TIMEOUT_SECONDS",
+        description="Maximum idle time between streaming response lines in seconds.",
+    )
     max_retries: int = Field(
         default=3,
         description="Maximum number of retry attempts on transient failures.",
@@ -80,12 +86,11 @@ class LLMClientConfig(BaseSettings):
             raise ValueError("session_budget must be > 0")
         return value
 
-    @field_validator("timeout")
+    @field_validator("timeout", "stream_idle_timeout")
     @classmethod
     def timeout_must_be_positive(cls, value: float) -> float:
-        """Enforce timeout > 0."""
         if value <= 0:
-            raise ValueError("timeout must be > 0")
+            raise ValueError("timeout values must be > 0")
         return value
 
     @field_validator("max_retries")

package/src/ummaya/llm/reasoning.py

@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: Apache-2.0
+"""K-EXAONE/FriendliAI reasoning payload policy."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal
+
+ReasoningMode = Literal["fast", "balanced", "deep", "diagnostic", "auto"]
+ReasoningModeSource = Literal["env", "session", "legacy-env", "default"]
+
+_MODES: set[str] = {"fast", "balanced", "deep", "diagnostic", "auto"}
+
+
+@dataclass(frozen=True)
+class ResolvedReasoningPolicy:
+    """Provider-facing reasoning policy for one request."""
+
+    mode: ReasoningMode
+    source: ReasoningModeSource
+    enable_thinking: bool
+    parse_reasoning: bool
+    include_reasoning: bool
+    persist_thinking: bool = False
+
+
+def parse_reasoning_mode(value: object) -> ReasoningMode | None:
+    """Return a valid reasoning mode from an untrusted value."""
+    if value is None:
+        return None
+    normalized = str(value).lower()
+    if normalized in _MODES:
+        return normalized  # type: ignore[return-value]
+    return None
+
+
+def resolve_reasoning_policy(
+    reasoning_mode: ReasoningMode | str | None = None,
+    *,
+    env: Mapping[str, str] | None = None,
+) -> ResolvedReasoningPolicy:
+    """Resolve request, settings, and env state into FriendliAI payload fields."""
+    effective_env = os.environ if env is None else env
+    env_mode = parse_reasoning_mode(effective_env.get("UMMAYA_K_EXAONE_REASONING_MODE"))
+    if env_mode is not None:
+        return _policy_for(env_mode, "env")
+
+    explicit_mode = parse_reasoning_mode(reasoning_mode)
+    if explicit_mode is not None:
+        return _policy_for(explicit_mode, "session")
+
+    legacy_mode = _legacy_thinking_mode(effective_env)
+    if legacy_mode is not None:
+        return _policy_for(legacy_mode, "legacy-env")
+
+    return _policy_for("balanced", "default")
+
+
+def _legacy_thinking_mode(env: Mapping[str, str]) -> ReasoningMode | None:
+    raw = env.get("UMMAYA_K_EXAONE_THINKING")
+    if raw is None:
+        return None
+    normalized = raw.lower()
+    if normalized in {"1", "true", "yes"}:
+        return "deep"
+    if normalized in {"0", "false", "no"}:
+        return "fast"
+    return None
+
+
+def _policy_for(
+    mode: ReasoningMode,
+    source: ReasoningModeSource,
+) -> ResolvedReasoningPolicy:
+    enable_thinking = mode in {"deep", "diagnostic"}
+    return ResolvedReasoningPolicy(
+        mode=mode,
+        source=source,
+        enable_thinking=enable_thinking,
+        parse_reasoning=True,
+        include_reasoning=enable_thinking,
+    )

package/src/ummaya/primitives/__init__.py

@@ -7,6 +7,7 @@ Exports the active primitive symbols that make up the main-tool surface:
 - ``locate``: geocoding (re-exported from Spec 022).
 - ``send``: write-transaction absorber (Spec 031 US1, T024).
 - ``check``: delegation-only identity binding (Spec 031 US2, T042).
+- ``document``: local public-document authoring and review harness.
 
 ``subscribe`` is intentionally not part of the active surface. National alert
 and notice subscriptions are app/phone push-notification concerns, not a CLI
@@ -18,6 +19,7 @@ from __future__ import annotations
 from collections.abc import Callable
 from typing import Any
 
+from ummaya.primitives.document import document
 from ummaya.primitives.submit import send
 from ummaya.primitives.verify import check
 from ummaya.tools.lookup import find
@@ -46,6 +48,7 @@ PRIMITIVE_REGISTRY: dict[str, Callable[..., Any]] = {
     "locate": locate,
     "send": send,
     "check": check,
+    "document": document,
 }
 
 # Subset of ``PRIMITIVE_REGISTRY`` whose invocation requires a Spec 033
@@ -64,9 +67,9 @@ PRIMITIVE_REGISTRY: dict[str, Callable[..., Any]] = {
 #
 # The complement (``PRIMITIVE_REGISTRY.keys() - GATED_PRIMITIVES``) is the
 # fully auto-allowed set: find / locate.
-GATED_PRIMITIVES: frozenset[str] = frozenset({"check", "send"})
+GATED_PRIMITIVES: frozenset[str] = frozenset({"check", "send", "document"})
 LIGHT_GATE_PRIMITIVES: frozenset[str] = frozenset({"check"})
-HEAVY_GATE_PRIMITIVES: frozenset[str] = frozenset({"send"})
+HEAVY_GATE_PRIMITIVES: frozenset[str] = frozenset({"send", "document"})
 
 # ``__all__`` enumerates the LLM-visible primitive *surface* — the active root
 # verbs. The metadata constants ``PRIMITIVE_REGISTRY``
@@ -77,6 +80,7 @@ __all__ = [
     "locate",
     "send",
     "check",
+    "document",
 ]
 # Metadata constants (GATED_PRIMITIVES / LIGHT_GATE_PRIMITIVES /
 # HEAVY_GATE_PRIMITIVES / PRIMITIVE_REGISTRY) are intentionally NOT in __all__

package/src/ummaya/primitives/delegation.py

@@ -36,7 +36,7 @@ logger = logging.getLogger(__name__)
 # Accepts single-scope strings AND comma-joined multi-scope strings for US1.
 # ---------------------------------------------------------------------------
 
-_SCOPE_VERBS = r"find|locate|send|check|lookup|resolve_location|submit|verify"
+_SCOPE_VERBS = r"find|locate|send|check|document|lookup|resolve_location|submit|verify"
 
 _SINGLE_SCOPE_PATTERN: re.Pattern[str] = re.compile(rf"^({_SCOPE_VERBS}):[a-z0-9_]+\.[a-z0-9_-]+$")
 

package/src/ummaya/primitives/document.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Document primitive placeholder.
+
+The model-facing `document` tool is registered as a concrete GovAPITool by the
+document harness. This coroutine exists so primitive registries and IPC guards
+can identify `document` as an allowed top-level primitive name.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+async def document(*_args: object, **_kwargs: object) -> dict[str, Any]:
+    """Document primitive marker.
+
+    Runtime execution is owned by `ummaya.tools.documents.registry` because it
+    needs session-local artifact stores and format-engine adapters.
+    """
+
+    return {
+        "kind": "error",
+        "reason": "direct_document_primitive_not_bound",
+        "message": "The document primitive must be executed through the registered document tool.",
+    }
+
+
+__all__ = ["document"]

package/src/ummaya/settings.py

@@ -104,9 +104,6 @@ class UmmayaSettings(BaseSettings):
     live_adapter_proxy_timeout_seconds: float = Field(default=30.0, gt=0)
     """HTTP timeout for operator-managed live adapter proxy calls."""
 
-    live_adapter_proxy_token: str = Field(default="")
-    """Optional bearer token for private/self-hosted live adapter gateways."""
-
     live_adapter_gateway_token: str = Field(default="")
     """Optional bearer token required by the hosted live adapter gateway server."""