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

ksadk/studio/native_model_recovery.py

@@ -0,0 +1,126 @@
+"""Explicit host grant for the narrow ordinary Studio Chat Completions path.
+
+Route/type checks prove local construction identity, never provider behavior.
+The caller separately attests absence of provider-hosted side effects. This
+private prototype refuses custom clients, metadata and cross-boot recovery.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Literal
+from urllib.parse import urlparse
+
+from pydantic import Field
+
+from ksadk.harness.native.model_takeover import ModelTakeoverCapability
+from ksadk.harness.native.state import Contract
+
+
+def _digest(value) -> str:
+    return hashlib.sha256(
+        json.dumps(value, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()
+
+
+def same_boot_clock_domain() -> str:
+    if sys.platform == "darwin":
+        boot = subprocess.check_output(
+            ["/usr/sbin/sysctl", "-n", "kern.boottime"], text=True, timeout=5
+        ).strip()
+        if not boot.startswith("{ sec = "):
+            raise ValueError("boot clock domain unavailable")
+    elif sys.platform.startswith("linux"):
+        boot = Path("/proc/sys/kernel/random/boot_id").read_text().strip()
+        if len(boot) != 36:
+            raise ValueError("boot clock domain unavailable")
+    else:
+        raise ValueError("same-boot takeover clock unsupported")
+    return _digest({"version": "same-boot-monotonic/v1", "platform": sys.platform, "boot": boot})
+
+
+def route_identity(endpoint: str, model: str) -> str:
+    return _digest({"endpoint": endpoint, "model": model})
+
+
+class StudioModelTakeoverDeclaration(Contract):
+    version: Literal["studio-pure-model-host/v1"] = "studio-pure-model-host/v1"
+    endpoint_model_digest: str = Field(pattern=r"^[0-9a-f]{64}$")
+    # Host assertions, NOT conclusions inferred from the route or class name.
+    provider_side_effects_absent: Literal[True]
+    hard_aggregate_token_or_cost_budget: Literal[False]
+    clock_domain_digest: str = Field(pattern=r"^[0-9a-f]{64}$")
+
+    @property
+    def digest(self):
+        return _digest(self.model_dump(mode="json"))
+
+
+def admit_studio_port(port, declaration: StudioModelTakeoverDeclaration) -> None:
+    from ksadk.model_gateway.client import ModelGatewayClient
+    from ksadk.studio.native_model_port import StudioNativeModelPort
+
+    if type(port) is not StudioNativeModelPort or type(port._client) is not ModelGatewayClient:
+        raise ValueError("model takeover client construction unsupported")
+    model = port._model
+    if (
+        model.metadata
+        or model.discovery
+        or model.wire_api not in {None, "chat"}
+        or not urlparse(model.endpoint_url).path.endswith("/chat/completions")
+        or port._client.transport is not None
+    ):
+        raise ValueError("model takeover request construction unsupported")
+    if route_identity(model.endpoint_url, model.model) != declaration.endpoint_model_digest:
+        raise ValueError("model takeover route identity changed")
+    if declaration.clock_domain_digest != same_boot_clock_domain():
+        raise ValueError("model takeover clock domain changed")
+    port._model_takeover_declaration = declaration
+
+
+def assert_local_function_proposals(options) -> None:
+    allowed = {
+        "messages",
+        "network_policy",
+        "compatibility_profile",
+        "timeout_seconds",
+        "tools",
+        "max_output_tokens",
+        "output_budget_mode",
+        "output_token_parameter",
+        "reasoning_effort",
+        "tool_choice",
+        "parallel_tool_calls",
+    }
+    if set(options) - allowed:
+        raise ValueError("model takeover request options unknown")
+    for tool in options.get("tools", []):
+        if (
+            not isinstance(tool, dict)
+            or set(tool) != {"type", "function"}
+            or tool["type"] != "function"
+        ):
+            raise ValueError("model takeover requires local function proposals")
+
+
+def bound_capability(port, declaration, host_binding_digest):
+    admit_studio_port(port, declaration)
+    return ModelTakeoverCapability(
+        host_binding_digest=host_binding_digest,
+        model_port_identity_digest=_digest(
+            {
+                "port": "StudioNativeModelPort/v1",
+                "route": declaration.endpoint_model_digest,
+                "profile": port._profile_digest,
+                "request": "local-function-proposals-only/v1",
+            }
+        ),
+        provider_side_effects_absent=declaration.provider_side_effects_absent,
+        tool_calls_are_local_proposals=True,
+        hard_aggregate_token_or_cost_budget=declaration.hard_aggregate_token_or_cost_budget,
+        clock_domain_digest=declaration.clock_domain_digest,
+    )

ksadk/studio/native_options.py

@@ -0,0 +1,75 @@
+"""Validate Native Studio opt-in combinations before workspace side effects."""
+
+from ksadk.harness.native.ports import CHILD_RECOVERY_POLICIES
+from ksadk.studio.native_model_recovery import StudioModelTakeoverDeclaration
+
+
+def validate_native_options(
+    *,
+    selected_native_agents,
+    native_harness_default=False,
+    native_harness_durable,
+    native_harness_session_context_read,
+    native_harness_browser_reobserve,
+    native_harness_terminal_child_reconcile,
+    native_harness_prepared_child_recovery,
+    native_harness_child_recovery_policy,
+    native_harness_model_recovery_policy,
+    native_harness_model_recovery_host,
+    harness_engine_selector,
+    native_acceptance_extension,
+    native_delivery_review_policy,
+) -> None:
+    native_enabled = native_harness_default or bool(selected_native_agents)
+    if native_harness_durable and not native_enabled:
+        raise ValueError("Native durable storage requires selected Studio agents")
+    if type(native_harness_session_context_read) is not bool:
+        raise ValueError("Native session context read must be a boolean")
+    if native_harness_session_context_read and not native_enabled:
+        raise ValueError("Native session context read requires selected Studio agents")
+    if type(native_harness_browser_reobserve) is not bool:
+        raise ValueError("Native browser reobservation must be a boolean")
+    if native_harness_browser_reobserve and not native_enabled:
+        raise ValueError("Native browser reobservation requires selected Studio agents")
+    if type(native_harness_terminal_child_reconcile) is not bool:
+        raise ValueError("Native child reconciliation must be a boolean")
+    if native_harness_terminal_child_reconcile and (
+        not native_enabled or not native_harness_durable
+    ):
+        raise ValueError("Native child reconciliation requires selected durable Studio agents")
+    if type(native_harness_prepared_child_recovery) is not bool:
+        raise ValueError("Native prepared child recovery must be a boolean")
+    if native_harness_prepared_child_recovery and (
+        not native_enabled or not native_harness_durable
+    ):
+        raise ValueError("Native prepared child recovery requires selected durable Studio agents")
+    if native_harness_prepared_child_recovery and native_harness_terminal_child_reconcile:
+        raise ValueError("select one Native child recovery policy")
+    if native_harness_child_recovery_policy is not None:
+        if (
+            type(native_harness_child_recovery_policy) is not str
+            or native_harness_child_recovery_policy not in CHILD_RECOVERY_POLICIES
+        ):
+            raise ValueError("Native child recovery policy is invalid")
+        if not native_enabled or not native_harness_durable:
+            raise ValueError("Native child recovery requires selected durable Studio agents")
+        if native_harness_prepared_child_recovery or native_harness_terminal_child_reconcile:
+            raise ValueError("select one Native child recovery policy")
+    if native_harness_model_recovery_policy is not None:
+        if (
+            native_harness_model_recovery_policy != "pure-inference-takeover/v1"
+            or not native_enabled
+            or not native_harness_durable
+            or not isinstance(native_harness_model_recovery_host, StudioModelTakeoverDeclaration)
+        ):
+            raise ValueError("Native model takeover requires declared selected durable agents")
+    elif native_harness_model_recovery_host is not None:
+        raise ValueError("model takeover declaration requires explicit policy")
+    if native_enabled and harness_engine_selector is not None:
+        raise ValueError("Native Studio agent selection conflicts with custom builder")
+    if native_acceptance_extension is not None and not native_enabled:
+        raise ValueError("Native acceptance extension requires selected Studio agents")
+    if native_delivery_review_policy is not None and not native_enabled:
+        raise ValueError("Native delivery review policy requires selected Studio agents")
+    if any(item == "*" for item in selected_native_agents):
+        raise ValueError("Native Studio rollout requires exact Agent IDs")

ksadk/studio/native_output_fields.py

@@ -0,0 +1,58 @@
+"""Compile explicit object field lists; never infer field values or semantics.
+
+Only the recognized final-output clauses supplied by Studio are eligible.
+Bare keys are ASCII identifiers; other supported keys need explicit quotes.
+Unknown syntax, duplicate keys and conflicting declarations add no constraint.
+Nested item declarations are not used to infer an array or field value type.
+"""
+
+import re
+
+_KEY = r"[A-Za-z_][A-Za-z0-9_.-]{0,63}"
+_QUOTED_KEY = rf"(?:{_KEY}|[\u4e00-\u9fff]{{1,32}})"
+_TOKEN = rf'(?:{_KEY}|`{_QUOTED_KEY}`|"{_QUOTED_KEY}")'
+_SEPARATOR = r"\s*(?:[,，、]|\s+(?:and|和|与)\s+)\s*"
+_LIST = re.compile(rf"{_TOKEN}(?:{_SEPARATOR}{_TOKEN})*", re.I)
+_KEY_CLAUSE = re.compile(
+    r"\s*(?:(?:最后|最终)(?:请)?|请)?(?:只|仅)(?:回复|输出|返回)\s*"
+    r"(?:一个|上述|该)?\s*JSON\s*对象\s*[,，]\s*(?:键|字段)(?:仅)?(?:为|是)\s*(?P<keys>.*)",
+    re.I,
+)
+_ITEM_CLAUSE = re.compile(
+    rf"\s*(?P<field>{_TOKEN})\s*的?\s*每项(?:键|字段)(?:为|是)\s*(?P<keys>.*)"
+)
+
+
+def _keys(listing):
+    listing = listing.strip()
+    if not _LIST.fullmatch(listing):
+        return None
+    tokens = re.split(_SEPARATOR, listing, flags=re.I)
+    keys = tuple(t.strip('`"') for t in tokens)
+    if len(keys) > 32 or len(set(keys)) != len(keys):
+        return None
+    return keys
+
+
+def declared_object_fields(clauses):
+    sets = []
+    for shape, clause in clauses:
+        if shape != "json_object":
+            return None
+        parts = re.split(r"[;；]", clause)
+        match = _KEY_CLAUSE.fullmatch(parts[0])
+        if not match:
+            continue
+        keys = _keys(match["keys"])
+        if keys is None:
+            return None
+        # Extra output modifiers cannot be silently discarded. Recognize a
+        # bounded item declaration without inferring its collection/value type.
+        for suffix in parts[1:]:
+            item = _ITEM_CLAUSE.fullmatch(suffix)
+            if not item or item["field"].strip('`"') not in keys or _keys(item["keys"]) is None:
+                return None
+        sets.append(frozenset(keys))
+    if not sets or len(set(sets)) != 1:
+        return None
+    return tuple(sorted(sets[0]))

ksadk/studio/native_planning.py

@@ -0,0 +1,156 @@
+"""Locked Native Studio token/media planning and effect timeout policies."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from functools import partial
+
+from ksadk.harness.native.context_runtime import CompactionPolicy, ContextPlanner
+from ksadk.harness.native.model import ModelProfile
+from ksadk.harness.native.model_replay import project_model_message
+from ksadk.studio.contracts import ContextSpec
+from ksadk.toolsets.workspace_read_budget import estimated_source_units
+
+
+def _estimated_token_counter(text: str) -> int:
+    """Versioned fallback for a provider without a compatible tokenizer.
+
+    Studio's ContextSpec window is measured in tokens. Charging UTF-8 bytes
+    against that window made long coding runs compact after only ~15k provider
+    input tokens on a 64k Build. Reuse the existing CJK-aware estimator with
+    a 25% safety margin; the provider's explicit overflow still triggers the
+    Native bounded force-compaction path. This is not provider usage.
+    """
+    return estimated_source_units(text)
+
+
+def _studio_message_budget(message: dict, *, provider_fields: bool = False) -> int:
+    """Charge image blocks explicitly without counting base64 as text history.
+
+    This is a conservative host budget, not a claim about provider token usage.
+    ZCode's pinned image budget uses 0.125 units per base64 character; keep a
+    minimum reserve for small screenshots whose encoded size understates the
+    provider's image framing cost. The original message is never rewritten.
+    """
+    projected = json.loads(json.dumps(message, ensure_ascii=False))
+    reserve = 0
+    content = projected.get("content")
+    if isinstance(content, list):
+        for block in content:
+            if not isinstance(block, dict) or block.get("type") != "image_url":
+                continue
+            source = block.get("image_url")
+            url = source.get("url") if isinstance(source, dict) else None
+            if not isinstance(url, str):
+                raise ValueError("image URL missing from typed content block")
+            if url.startswith("data:image/") and "," in url:
+                reserve += max(2048, (len(url.partition(",")[2]) + 7) // 8)
+            else:
+                reserve += 8192
+            block["image_url"] = {"url": "[host image budgeted separately]"}
+    framing = {"separators": (",", ":")} if provider_fields else {}
+    text_cost = _estimated_token_counter(
+        json.dumps(projected, ensure_ascii=False, sort_keys=True, **framing)
+    )
+    return text_cost + reserve
+
+
+def _studio_model_message_budget(message: dict, *, profile: ModelProfile) -> int:
+    return _studio_message_budget(project_model_message(message, profile), provider_fields=True)
+
+
+def build_studio_context_planner(
+    profile: ModelProfile, *, context: ContextSpec | None = None,
+    planner_factory=ContextPlanner,
+) -> ContextPlanner:
+    """One locked token/media policy for parent and child Native Runs."""
+    defaults = CompactionPolicy()
+    compaction = context.compaction if context is not None else None
+    trigger = compaction.threshold_ratio if compaction is not None else defaults.trigger_ratio
+    # thresholdRatio is the Build's single-stage trigger, not PCM's soft/hard
+    # thresholds. For an earlier trigger, preserve the existing proportional
+    # recovery headroom; never enlarge the normal post-summary target.
+    target = min(defaults.target_ratio, trigger * defaults.target_ratio / defaults.trigger_ratio)
+    return planner_factory(
+        tool_media_projection_version=(
+            "source-profile-tool-media/v1" if profile.image_input_mode == "text_only" else None
+        ),
+        count_tokens=_estimated_token_counter,
+        count_message_tokens=partial(_studio_model_message_budget, profile=profile),
+        tokenizer_id=(
+            "studio-cjk-ascii-estimate-125-provider-message-fields-plus-image/v2"
+            if profile.image_input_mode == "native"
+            else "studio-cjk-ascii-estimate-125-provider-message-fields/v2"
+        ),
+        summary_budget_unit="estimated tokens",
+        # Keep the target separate from provider usage; admit the complete
+        # continuation/post-summary request within the locked context window.
+        summary_budget_mode="context_bounded_estimate",
+        summary_completion_policy="bounded-committed-summary/v1",
+        subagent_continuity_policy="accounted_child_runs/v1",
+        source_progress_policy="receipt-source-progress/v2",
+        # The estimate and provider tokens can differ. Reserve a
+        # bounded share of the locked context for the summary.
+        # A fixed 2 KiB limit
+        # failed a real code repair after the files were edited;
+        # that failure must not turn completed tool work into a
+        # terminal compaction error on a 32 KiB Build.
+        policy=CompactionPolicy(
+            enabled=compaction.enabled if compaction is not None else defaults.enabled,
+            prune_tool_results=(
+                compaction.prune_tool_results
+                if compaction is not None else defaults.prune_tool_results
+            ),
+            trigger_ratio=trigger,
+            target_ratio=target,
+            fresh_read_max_chars=2000,
+            summary_max_tokens=min(
+                8192,
+                profile.max_output_tokens,
+                max(2048, profile.context_window // 8),
+            ),
+            # In long coding tasks, discarding every recent read
+            # after each summary made the Agent re-read the same
+            # unchanged files until its model budget was spent.
+            # Keep several completed tool batches as a bounded
+            # working set; the planner still enforces the hard
+            # input capacity and preserves the raw transcript.
+            recent_tool_batch_count=4,
+            recent_tool_batch_max_tokens=min(12000, profile.context_window // 6),
+            recent_tool_batches_total_max_tokens=min(24000, profile.context_window // 4),
+        ),
+    )
+
+
+def _native_effect_timeout_seconds(
+    main: ModelProfile,
+    vision: ModelProfile | None = None,
+    *,
+    browser_tool_seconds: int = 0,
+) -> float:
+    """Keep the outer effect lease through browser execution and vision captioning."""
+    profiles = (main, vision) if vision is not None else (main,)
+    bound = max(120.0, *((item.request_timeout_seconds or 60.0) + 15.0 for item in profiles))
+    if browser_tool_seconds:
+        caption_seconds = vision.request_timeout_seconds or 60.0 if vision else 0.0
+        bound = max(bound, browser_tool_seconds + caption_seconds + 15.0)
+    return bound
+
+
+def _locked_browser_timeout_seconds(build: Mapping[str, object]) -> int:
+    capabilities = build.get("capabilities")
+    tools = capabilities.get("tools") if isinstance(capabilities, Mapping) else None
+    if not isinstance(tools, (list, tuple)):
+        return 0
+    for tool in tools:
+        if (
+            isinstance(tool, Mapping)
+            and tool.get("name") == "browser_inspect_workspace"
+            and tool.get("enabled", True) is not False
+        ):
+            value = tool.get("timeoutSeconds", 20)
+            if type(value) is int and 1 <= value <= 3600:
+                return value
+            raise ValueError("native_studio_browser_timeout_invalid")
+    return 0