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

ksadk/studio/native_child_mcp.py

@@ -0,0 +1,87 @@
+"""Borrow an activation's exact MCP tool surface without owning its transports.
+
+Remote tool effects stay on the original bound resources. A child's local
+workspace isolation cannot isolate those resources or make calls replay-safe.
+The original surface owns schema, Scope, approval and activation checks.
+"""
+
+from ksadk.harness.native.ports import RunConfiguration, ToolDefinition, ToolPort, ToolResult
+from ksadk.harness.native.state import RunScope
+from ksadk.harness.native.studio_admission import studio_mapping_digest
+from ksadk.harness.native.subagents import ChildRunRequest
+from ksadk.studio.native_mcp_tool_port import NativeMcpToolSurface
+
+
+class _BorrowedChildMcpTools:
+    def __init__(self, *, child, names, executor, tools):
+        self.child, self.names, self.executor, self.tools = child, frozenset(names), executor, tools
+
+    async def execute(self, request):
+        if request.scope != self.child.scope or request.run_id != self.child.child_run_id:
+            return ToolResult(status="error", content={"code": "child_mcp_run_binding_mismatch"})
+        if request.call.name in self.names:
+            return await self.executor.execute(request)
+        if self.tools is None:
+            return ToolResult(status="error", content={"code": "child_tool_not_granted"})
+        return await self.tools.execute(request)
+
+
+class StudioChildMcp:
+    def __init__(
+        self,
+        *,
+        scope: RunScope,
+        surface: NativeMcpToolSurface,
+        activation_binding_digest: str,
+    ) -> None:
+        self.scope = scope
+        self.definitions = tuple(
+            ToolDefinition.model_validate_json(item.model_dump_json())
+            for item in surface.definitions
+        )
+        self.tool_names = tuple(item.name for item in self.definitions)
+        if len(set(self.tool_names)) != len(self.tool_names):
+            raise ValueError("child_mcp_tool_name_duplicate")
+        self.executor = surface.executor
+        self.binding_digest = studio_mapping_digest(
+            {
+                "policy": "studio-child-borrowed-mcp/v1",
+                "activation_binding": activation_binding_digest,
+                "definitions": [item.model_dump(mode="json") for item in self.definitions],
+            }
+        )
+
+    def bind(
+        self,
+        child: ChildRunRequest,
+        configuration: RunConfiguration,
+        tools: ToolPort | None,
+    ) -> tuple[RunConfiguration, ToolPort]:
+        if child.parent_scope != self.scope or child.scope != self.scope:
+            raise ValueError("child_mcp_binding_scope_mismatch")
+        if not set(self.tool_names).issubset(child.role.tool_names):
+            raise ValueError("child_mcp_role_grant_mismatch")
+        if child.role.concurrent_safe and any(not item.read_only for item in self.definitions):
+            raise ValueError("child_mcp_concurrent_effects_unsupported")
+        by_name = {item.name: item for item in configuration.tools}
+        for item in self.definitions:
+            if item.name in by_name:
+                raise ValueError("child_mcp_tool_name_conflict")
+        configuration = RunConfiguration.model_validate(
+            {
+                **configuration.model_dump(),
+                "tools": (*configuration.tools, *self.definitions),
+                "host_binding_digest": studio_mapping_digest(
+                    {
+                        "parent_binding": configuration.host_binding_digest,
+                        "inherited_mcp_binding": self.binding_digest,
+                    }
+                ),
+            }
+        )
+        return configuration, _BorrowedChildMcpTools(
+            child=child,
+            names=self.tool_names,
+            executor=self.executor,
+            tools=tools,
+        )

ksadk/studio/native_child_publication.py

@@ -0,0 +1,68 @@
+"""Resolve previous file publication from original scoped Run effect receipts.
+
+OpenCode task_id and ZCode resumed child sessions preserve continuation origin.
+KsADK publication authority remains its own RunStore; immutable disk inventory
+alone, child prose and model messages never advance the merge comparison base.
+"""
+
+from ksadk.harness.native.ports import ToolResult
+from ksadk.harness.workspace_adapters.native_isolation import ChildFilePublication
+
+MERGE_SCHEMA = "native.child-file-merge/v2"
+
+
+def _confirmed_publication(reader, parent, child):
+    cursor = parent
+    while True:
+        for event in reversed(reader.store.events(cursor.scope, cursor.run_id)):
+            if event.kind != "effect.prepared" or event.payload.get("kind") != "tool":
+                continue
+            operation = event.payload["operation_key"]
+            intent = reader.store.get_intent(cursor.scope, cursor.run_id, operation)
+            call = (intent.payload.get("call")
+                    if intent is not None and intent.kind == "tool" else None)
+            if (not isinstance(call, dict) or call.get("name") != "native_child_merge"
+                    or call.get("arguments") != {"child_run_id": child.run_id}):
+                continue
+            receipt = reader.store.get_receipt(cursor.scope, cursor.run_id, operation)
+            if receipt is None or receipt.status != "committed":
+                continue
+            try:
+                result = ToolResult.model_validate(receipt.result)
+            except ValueError:
+                continue
+            content = result.content
+            if (result.status != "ok" or not isinstance(content, dict)
+                    or content.get("schema_version") != MERGE_SCHEMA
+                    or content.get("ok") is not True
+                    or content.get("child_run_id") != child.run_id
+                    or content.get("child_revision") != child.workspace_revision):
+                continue
+            grant = content.get("publication")
+            if (not isinstance(grant, dict) or grant.get("revision") != child.workspace_revision
+                    or not isinstance(grant.get("inventory_digest"), str)):
+                raise ValueError("child_publication_receipt_invalid")
+            return ChildFilePublication(grant["revision"], grant["inventory_digest"])
+        if cursor.parent_run_id is None:
+            return None
+        cursor = reader.store.load(parent.scope, cursor.parent_run_id)
+        if cursor.session_id != parent.session_id or not cursor.phase.terminal:
+            return None
+
+
+def previous_child_publication(reader, parent, child):
+    """Only a confirmed publication of this child Session's actual ancestor."""
+    source_id = child.parent_run_id
+    while source_id is not None:
+        resolved = reader._load_session_child(parent, source_id)
+        if resolved is None:
+            return None
+        source, _source_parent = resolved
+        if (source.scope != child.scope or source.session_id != child.session_id
+                or source.origin.get("workspace_isolation_id")
+                != child.origin.get("workspace_isolation_id")):
+            return None
+        if grant := _confirmed_publication(reader, parent, source):
+            return grant
+        source_id = source.parent_run_id
+    return None

ksadk/studio/native_child_skills.py

@@ -0,0 +1,72 @@
+"""Consume the locked Build's readonly Skill knowledge in each child's own Run.
+
+ZCode's child profile explicitly adds Skill to its allowed tool surface. KsADK
+keeps the DSH package source and authorization, never copying the parent's
+disclosure cursor or making Skill text an executable permission grant.
+"""
+
+from ksadk.harness.native.adapters import ToolAuthorizer
+from ksadk.harness.native.ports import RunConfiguration, ToolPort
+from ksadk.harness.native.state import RunScope
+from ksadk.harness.native.studio_admission import studio_mapping_digest
+from ksadk.harness.native.subagents import ChildRunRequest
+from ksadk.harness.skill_adapters.native_disclosure import (
+    DEFINITIONS,
+    NativeSkillDisclosurePort,
+    install_native_skill_tools,
+)
+from ksadk.harness.stores.native_contract import RunStore
+from ksadk.studio.native_skill_source import StudioNativeSkillSource
+
+
+class StudioChildSkills:
+    def __init__(
+        self,
+        *,
+        scope: RunScope,
+        store: RunStore,
+        source: StudioNativeSkillSource,
+        authorize: ToolAuthorizer,
+        activation_binding_digest: str,
+    ) -> None:
+        self.scope, self.store, self.source, self.authorize = scope, store, source, authorize
+        self.refs = tuple(source.refs)
+        if not self.refs:
+            raise ValueError("child_skill_bindings_empty")
+        self.tool_names = tuple(definition.name for definition in DEFINITIONS)
+        self.binding_digest = studio_mapping_digest(
+            {
+                "policy": "studio-child-skill-knowledge/v1",
+                "activation_binding": activation_binding_digest,
+                "refs": self.refs,
+                "bundle_claims": source.binding_claims,
+            }
+        )
+
+    def bind(
+        self,
+        child: ChildRunRequest,
+        configuration: RunConfiguration,
+        tools: ToolPort,
+    ) -> tuple[RunConfiguration, NativeSkillDisclosurePort]:
+        if child.parent_scope != self.scope or child.scope != self.scope:
+            raise ValueError("child_skill_binding_scope_mismatch")
+        configuration = configuration.model_copy(
+            update={
+                "host_binding_digest": studio_mapping_digest(
+                    {
+                        "parent_binding": configuration.host_binding_digest,
+                        "inherited_skill_binding": self.binding_digest,
+                    }
+                ),
+            }
+        )
+        return install_native_skill_tools(
+            configuration,
+            tools,
+            scope=child.scope,
+            source=self.source,
+            skill_refs=self.refs,
+            authorize=self.authorize,
+            store=self.store,
+        )

ksadk/studio/native_child_workspace.py

@@ -0,0 +1,176 @@
+"""Bind local child file isolation and controlled merge to Studio's original host."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+from dataclasses import replace
+from pathlib import Path
+
+from ksadk.harness.execution_policy import (
+    ExecutionPolicy,
+    current_execution_policy,
+    execution_policy_scope,
+)
+from ksadk.harness.native.adapters import StrictToolExecutor, ToolBinding
+from ksadk.harness.native.ports import ToolDefinition, ToolResult
+from ksadk.harness.native.state import RunPhase
+from ksadk.harness.subagent_adapters.native_child_result import NativeChildResultPort
+from ksadk.harness.workspace_adapters.native_isolation import (
+    ChildWorkspaceError,
+    DirectoryChildWorkspaces,
+    builtin_state_database,
+)
+from ksadk.studio.native_child_publication import MERGE_SCHEMA, previous_child_publication
+
+
+async def _joined(operation, *args, **kwargs):
+    # File preparation/publication is owned until its blocking work terminates.
+    # Cancelling an asyncio observer cannot stop an already running thread.
+    task = asyncio.create_task(asyncio.to_thread(operation, *args, **kwargs))
+    canceled = False
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            canceled = True
+    result = task.result()
+    if canceled:
+        raise asyncio.CancelledError
+    return result
+
+
+class _ChildFileTools:
+    def __init__(self, tools, root):
+        self.tools, self.root = tools, root
+
+    async def execute(self, request):
+        policy = current_execution_policy()
+        state_root = self.root.parent / "runtime"
+        isolated = (
+            replace(policy, workspace_root=self.root, tool_state_root=state_root)
+            if policy
+            else ExecutionPolicy(workspace_root=self.root, tool_state_root=state_root)
+        )
+        with execution_policy_scope(isolated):
+            return await self.tools.execute(request)
+
+
+class StudioChildFileWorkspaces:
+    """Only the host's proven SDK file tools may consume this directory grant."""
+
+    def __init__(self, *, source, writable_root, storage, scope, store, authorize, tool_names):
+        self.scope, self.store, self.authorize = scope, store, authorize
+        self.tool_names = frozenset(tool_names)
+        self.files = DirectoryChildWorkspaces(
+            source=source,
+            storage=storage,
+            source_database=builtin_state_database(Path(writable_root), Path(source)),
+        )
+
+    def identity(self, scope, session_id, role):
+        value = {
+            "scope": scope.model_dump(mode="json"),
+            "session_id": session_id,
+            "role": role.model_dump(mode="json"),
+            "source": str(self.files.source),
+        }
+        return hashlib.sha256(json.dumps(value, sort_keys=True).encode()).hexdigest()
+
+    async def bind(self, child, tools):
+        identity = self.identity(child.scope, child.child_session_id, child.role)
+        try:
+            self.store.load(child.scope, child.child_run_id)
+            existing = True
+        except KeyError:
+            existing = child.continuation_of is not None
+        workspace = (
+            await _joined(self.files._load, self.files.storage / identity, identity)
+            if existing
+            else await _joined(self.files.prepare, identity)
+        )
+        return workspace, _ChildFileTools(tools, workspace.root), self.files.observer(workspace)
+
+    def merge_surface(self, roles):
+        reader = NativeChildResultPort(scope=self.scope, store=self.store, roles=roles)
+        role_map = {role.role_id: role for role in roles}
+        definition = ToolDefinition(
+            name="native_child_merge",
+            description=(
+                "Merge an accounted completed file-writing child's isolated changes into "
+                "the parent workspace. The host checks the frozen base and current files; "
+                "conflicts publish nothing and require ordinary parent read/edit repair. "
+                "This operation is not independent task verification."
+            ),
+            parameters={
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["child_run_id"],
+                "properties": {
+                    "child_run_id": {"type": "string", "minLength": 1, "maxLength": 256}
+                },
+            },
+            read_only=False,
+            feedback_profile_digest="sha256:"
+            + hashlib.sha256(
+                (
+                    "studio-child-file-merge/v2\0"
+                    + json.dumps([role.model_dump(mode="json") for role in roles], sort_keys=True)
+                ).encode()
+            ).hexdigest(),
+        )
+
+        async def merge(request):
+            parent = self.store.load(request.scope, request.run_id)
+            source = reader._load_session_child(parent, request.call.arguments["child_run_id"])
+            if source is None:
+                return ToolResult(status="error", content={"error_code": "child_not_accounted"})
+            child, _source_parent = source
+            role = role_map.get(child.origin.get("role"))
+            current = self.store.session_head(child.scope, child.session_id)
+            if (
+                role is None
+                or role.workspace_access != "isolated_write"
+                or child.phase != RunPhase.COMPLETED
+                or child.outcome in {"failed", "blocked", "budget_exhausted"}
+                or current is None
+                or current.run_id != child.run_id
+                or not child.workspace_revision
+            ):
+                return ToolResult(status="error", content={"error_code": "child_merge_unavailable"})
+            identity = self.identity(child.scope, child.session_id, role)
+            if child.origin.get("workspace_isolation_id") != identity:
+                return ToolResult(status="error", content={"error_code": "child_workspace_unbound"})
+            try:
+                workspace = self.files._load(self.files.storage / identity, identity)
+                if child.origin.get("workspace_base_revision") != workspace.base_revision:
+                    raise ChildWorkspaceError("child_workspace_baseline_changed")
+                previous = previous_child_publication(reader, parent, child)
+                result = await _joined(
+                    self.files.merge, workspace, expected_revision=child.workspace_revision,
+                    previous=previous,
+                )
+            except (ChildWorkspaceError, OSError, ValueError):
+                return ToolResult(
+                    status="error",
+                    content={
+                        "error_code": "child_workspace_merge_unavailable",
+                        "instruction": (
+                            "Inspect the saved child workspace and delivery before retrying."
+                        ),
+                    },
+                )
+            return ToolResult(
+                status="ok" if result["ok"] else "error",
+                content={
+                    "schema_version": MERGE_SCHEMA,
+                    "child_run_id": child.run_id,
+                    **result,
+                },
+                workspace_changed_paths=tuple(result["applied"]),
+            )
+
+        return definition, StrictToolExecutor(
+            scope=self.scope, tools=(ToolBinding(definition, merge),), authorize=self.authorize
+        )

ksadk/studio/native_command_policy.py

@@ -0,0 +1,53 @@
+"""Declare command timeouts before admission; never rewrite explicit values."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from copy import deepcopy
+
+from jsonschema import FormatChecker
+from jsonschema.exceptions import ValidationError
+from jsonschema.validators import validator_for
+
+
+class StudioCommandTimeoutPolicy:
+    """A locked SDK command policy, separate from backend resource ceilings."""
+
+    def __init__(self, parameters: dict, *, default: int, maximum: int) -> None:
+        constraint = {"type": "integer", "minimum": 1, "maximum": maximum}
+        self.parameters = deepcopy(parameters)
+        properties = self.parameters.get("properties")
+        if isinstance(properties, dict) and "timeout" in properties:
+            # Retain every original constraint, including enum, nullable unions
+            # and local references. Defaults are declared intrinsic semantics;
+            # JSON Schema validation itself does not insert them.
+            properties["timeout"] = {
+                **constraint, "default": default,
+                "allOf": [properties["timeout"]],
+            }
+        else:
+            self.parameters.setdefault("allOf", []).append({
+                "type": "object", "properties": {"timeout": constraint},
+            })
+        validator_class = validator_for(self.parameters)
+        validator_class.check_schema(self.parameters)
+        self._validator = validator_class(self.parameters, format_checker=FormatChecker())
+        self.default = default
+        self.digest = "sha256:" + hashlib.sha256(json.dumps({
+            "version": "studio.command-timeout-admission/v1",
+            "default": default, "maximum": maximum,
+        }, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+    def prepare(self, arguments: dict) -> dict | None:
+        prepared = dict(arguments)
+        # Only omission uses the declared default. Explicit null, zero or an
+        # out-of-range value cannot silently acquire different semantics.
+        prepared.setdefault("timeout", self.default)
+        try:
+            self._validator.validate(prepared)
+        except ValidationError:
+            # A restricted original schema may not accept the default. The
+            # failure is definite and precedes any execution or quota reserve.
+            return None
+        return prepared