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

ksadk/harness/artifact_adapters/native_tool.py

@@ -0,0 +1,222 @@
+"""Reserved ArtifactRead tool backed by the runtime's scoped ArtifactPort."""
+
+from __future__ import annotations
+
+from ksadk.harness.native.artifact_read_contract import (
+    ARTIFACT_READ_DEFINITION as ARTIFACT_READ_DEFINITION,
+)
+from ksadk.harness.native.artifact_read_contract import (
+    ARTIFACT_READ_NAME as ARTIFACT_READ_NAME,
+)
+from ksadk.harness.native.ports import (
+    ArtifactPort,
+    ArtifactReadRequest,
+    ArtifactRef,
+    RunConfiguration,
+    ToolDefinition,
+    ToolPort,
+    ToolRequest,
+    ToolResult,
+)
+from ksadk.harness.native.tool_recovery import query_sealed_tool_result
+
+from .native_page_budget import (
+    ArtifactPageBudget,
+    ArtifactPageCapacityError,
+    ArtifactPagePolicy,
+    capacity_error_content,
+)
+from .native_search_budget import ArtifactSearchPolicy, search_definition
+
+
+class NativeArtifactToolPort:
+    def __init__(self, delegate: ToolPort, artifacts: ArtifactPort, *,
+                 page_policy: ArtifactPagePolicy | None = None,
+                 definitions: tuple[ToolDefinition, ...] = ()) -> None:
+        if not callable(getattr(delegate, "execute", None)):
+            raise ValueError("artifact tool delegate must implement execute")
+        if not callable(getattr(artifacts, "read", None)):
+            raise ValueError("artifact port must implement read")
+        if page_policy is not None and not isinstance(page_policy, ArtifactPagePolicy):
+            raise ValueError("artifact_page_policy_invalid")
+        self._delegate, self._artifacts = delegate, artifacts
+        self._page_policy, self._definitions = page_policy, definitions
+        self._definition = ARTIFACT_READ_DEFINITION.model_copy(update={
+            "feedback_profile_digest": page_policy.digest,
+        }) if page_policy is not None else ARTIFACT_READ_DEFINITION
+
+    async def reconcile(self, request: ToolRequest) -> ToolResult:
+        return await query_sealed_tool_result(
+            self._delegate, request, owned_names=(ARTIFACT_READ_NAME,)
+        )
+
+    async def recover_prepared(self, request: ToolRequest) -> ToolResult:
+        return await query_sealed_tool_result(
+            self._delegate, request, owned_names=(ARTIFACT_READ_NAME,), method="recover_prepared"
+        )
+
+    async def resume_prepared(self, request: ToolRequest) -> ToolResult:
+        return await query_sealed_tool_result(
+            self._delegate, request, owned_names=(ARTIFACT_READ_NAME,), method="resume_prepared"
+        )
+
+    async def resume_checkpoint(self, request: ToolRequest) -> ToolResult:
+        return await query_sealed_tool_result(
+            self._delegate, request, owned_names=(ARTIFACT_READ_NAME,), method="resume_checkpoint"
+        )
+
+    async def execute(self, request: ToolRequest) -> ToolResult:
+        if request.call.name != ARTIFACT_READ_NAME:
+            result = await self._delegate.execute(request)
+            return ToolResult.model_validate_json(result.model_dump_json())
+        if request.definition != self._definition:
+            return ToolResult(status="error", content={"code": "artifact_definition_mismatch"})
+        arguments = request.call.arguments
+        if set(arguments).difference({"uri", "offset_chars", "limit_chars"}):
+            return ToolResult(status="error", content={"code": "invalid_artifact_read"})
+        uri = arguments.get("uri")
+        offset = arguments.get("offset_chars", 0)
+        limit = arguments.get("limit_chars", 16000)
+        if (
+            not isinstance(uri, str)
+            or not uri
+            or type(offset) is not int
+            or offset < 0
+            or type(limit) is not int
+            or not 1 <= limit <= 32000
+        ):
+            return ToolResult(status="error", content={"code": "invalid_artifact_read"})
+        allowed = {ref.uri: ref for ref in request.available_artifacts}
+        ref = allowed.get(uri)
+        if ref is None:
+            return ToolResult(status="error", content={"code": "artifact_not_available"})
+        page_budget = None
+        if self._page_policy is not None:
+            try:
+                page_budget = self._page_policy.resolve(request, self._definitions)
+                if not isinstance(page_budget, ArtifactPageBudget):
+                    raise ValueError("artifact_page_budget_invalid")
+                empty_page = {
+                    "uri": ref.uri, "content": "", "offset_chars": offset,
+                    "next_offset_chars": offset, "complete": False,
+                    "content_hash": ref.content_hash, "size_bytes": ref.size_bytes,
+                    "mime_type": ref.mime_type,
+                }
+                if page_budget.admit_result is None:
+                    # Preserve the original public subclass method contract.
+                    if not page_budget.fits(empty_page):
+                        raise page_budget.unavailable(empty_page)
+                elif not page_budget.fits(empty_page, check_admission=False):
+                    # The empty page is only a structural preflight, not an
+                    # observed result for complete-request admission.
+                    raise page_budget.unavailable(empty_page, check_admission=False)
+            except ArtifactPageCapacityError as exc:
+                return ToolResult(status="error", content=capacity_error_content(exc))
+            except (ValueError, KeyError):
+                return ToolResult(
+                    status="error", content={"code": "artifact_page_budget_unavailable"}
+                )
+        try:
+            page = await self._artifacts.read(
+                ArtifactReadRequest(
+                    scope=request.scope,
+                    run_id=request.run_id,
+                    ref=ArtifactRef.model_validate(ref),
+                    offset_chars=offset,
+                    limit_chars=limit,
+                )
+            )
+        except Exception:
+            return ToolResult(status="error", content={"code": "artifact_read_failed"})
+        if page.ref != ref or page.offset_chars != offset or len(page.content) > limit:
+            return ToolResult(status="error", content={"code": "artifact_read_mismatch"})
+        content = {
+                "uri": ref.uri,
+                "content": page.content,
+                "offset_chars": page.offset_chars,
+                "next_offset_chars": page.next_offset_chars,
+                "complete": page.complete,
+                "content_hash": ref.content_hash,
+                "size_bytes": ref.size_bytes,
+                "mime_type": ref.mime_type,
+            }
+        if page_budget is not None:
+            try:
+                content = page_budget.select(content)
+            except ArtifactPageCapacityError as exc:
+                return ToolResult(status="error", content=capacity_error_content(exc))
+            except ValueError:
+                return ToolResult(
+                    status="error", content={"code": "artifact_page_budget_unavailable"}
+                )
+        return ToolResult(status="ok", content=content)
+
+
+def install_artifact_tool(
+    configuration: RunConfiguration,
+    tools: ToolPort,
+    artifacts: ArtifactPort | None,
+    *,
+    enable_search: bool = False,
+    page_policy: ArtifactPagePolicy | None = None,
+    search_policy: ArtifactSearchPolicy | None = None,
+) -> tuple[RunConfiguration, ToolPort]:
+    if page_policy is not None and not isinstance(page_policy, ArtifactPagePolicy):
+        raise ValueError("artifact_page_policy_invalid")
+    if search_policy is not None and (
+        not isinstance(search_policy, ArtifactSearchPolicy) or not enable_search
+    ):
+        raise ValueError("artifact_search_policy_invalid")
+    if artifacts is None:
+        return configuration, tools
+    definition = ARTIFACT_READ_DEFINITION.model_copy(update={
+        "feedback_profile_digest": page_policy.digest,
+    }) if page_policy is not None else ARTIFACT_READ_DEFINITION
+    existing = next(
+        (tool for tool in configuration.tools if tool.name == ARTIFACT_READ_NAME), None
+    )
+    if existing is not None and existing != definition:
+        raise ValueError("reserved_artifact_tool_conflict")
+    definitions = (
+        configuration.tools
+        if existing is not None
+        else (*configuration.tools, definition)
+    )
+    if enable_search:
+        from .native_search import ARTIFACT_SEARCH_DEFINITION, NativeArtifactSearchPort
+
+        search_expected = search_definition(search_policy)
+        search = next((t for t in definitions if t.name == ARTIFACT_SEARCH_DEFINITION.name), None)
+        if search is not None and search != search_expected:
+            raise ValueError("reserved_artifact_tool_conflict")
+        if search is None:
+            definitions = (*definitions, search_expected)
+    configuration = configuration.model_copy(update={"tools": definitions})
+    if page_policy is not None and page_policy.bind_configuration is not None:
+        bound = page_policy.bind_configuration(configuration)
+        if (not isinstance(bound, ArtifactPagePolicy) or bound.digest != page_policy.digest
+                or bound.bind_configuration is not None):
+            raise ValueError("artifact_page_configuration_binding_invalid")
+        page_policy = bound
+    if search_policy is not None and search_policy.bind_configuration is not None:
+        bound = search_policy.bind_configuration(configuration)
+        if (not isinstance(bound, ArtifactSearchPolicy) or bound.digest != search_policy.digest
+                or bound.bind_configuration is not None):
+            raise ValueError("artifact_search_configuration_binding_invalid")
+        search_policy = bound
+    if enable_search:
+        tools = NativeArtifactSearchPort(
+            tools, artifacts, search_policy=search_policy, definitions=definitions,
+        )
+    return (
+        configuration,
+        NativeArtifactToolPort(tools, artifacts, page_policy=page_policy, definitions=definitions),
+    )
+
+
+__all__ = [
+    "ARTIFACT_READ_DEFINITION",
+    "ARTIFACT_READ_NAME",
+    "NativeArtifactToolPort",
+    "install_artifact_tool",
+]

ksadk/harness/artifact_store.py

@@ -15,6 +15,7 @@ import sqlite3
 import time
 from dataclasses import dataclass
 from pathlib import Path
+from threading import RLock
 from typing import Any
 
 
@@ -31,12 +32,15 @@ class ArtifactRecord:
 
 
 class ArtifactStore:
-    """Run 作用域 Artifact 持久化（线程安全由 SQLite 连接锁保证）。"""
+    """Run 作用域持久化；同一 owner 的版本分配、索引和关闭使用同一锁。"""
 
     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._lock = RLock()
+        self._db = sqlite3.connect(
+            str(db_path or self._root / "artifacts.sqlite3"), check_same_thread=False,
+        )
         self._db.execute(
             """
             CREATE TABLE IF NOT EXISTS artifacts (
@@ -58,6 +62,12 @@ class ArtifactStore:
 
     def save(
         self, *, run_id: str, name: str, content: bytes, mime: str = "text/plain"
+    ) -> ArtifactRecord:
+        with self._lock:
+            return self._save(run_id=run_id, name=name, content=content, mime=mime)
+
+    def _save(
+        self, *, run_id: str, name: str, content: bytes, mime: str = "text/plain"
     ) -> ArtifactRecord:
         name = _safe_name(name)
         if not name:
@@ -111,7 +121,8 @@ class ArtifactStore:
             query += " AND name = ?"
             params.append(_safe_name(name))
         query += " ORDER BY name, version"
-        rows = self._db.execute(query, params).fetchall()
+        with self._lock:
+            rows = self._db.execute(query, params).fetchall()
         return [_record(row) for row in rows]
 
     def latest(self, run_id: str, name: str) -> ArtifactRecord | None:
@@ -121,6 +132,10 @@ class ArtifactStore:
     def read(self, record: ArtifactRecord) -> bytes:
         return self._read_uri(record.uri)
 
+    def read_uri(self, uri: str) -> bytes:
+        """按 URI 读取 artifact 内容（G10 artifact_read 取回路径）。"""
+        return self._read_uri(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)
@@ -149,7 +164,8 @@ class ArtifactStore:
         return (row[0] or 0) + 1
 
     def close(self) -> None:
-        self._db.close()
+        with self._lock:
+            self._db.close()
 
 
 class BudgetedArtifactStore:
@@ -163,11 +179,12 @@ class BudgetedArtifactStore:
     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)
+        with self._store._lock:
+            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)

ksadk/harness/browser_adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Optional browser adapters; importing this package does not load Playwright."""
+
+from .native_playwright import NativePlaywrightBrowser
+from .native_vision import NativeVisionBrowser
+
+__all__ = ["NativePlaywrightBrowser", "NativeVisionBrowser"]

ksadk/harness/browser_adapters/native_browser_tool.py

@@ -0,0 +1,92 @@
+"""Locked browser action contract, shared by model projection and execution."""
+
+from ..native.ports import ToolDefinition
+
+
+def browser_tool_definition() -> ToolDefinition:
+    session = {
+        "session_id": {"type": "string", "minLength": 1},
+        "generation": {"type": "integer", "minimum": 1},
+    }
+    timeout = {"timeout_ms": {"type": "integer", "minimum": 1, "maximum": 120000}}
+
+    def action_schema(
+        action: str, required: tuple[str, ...] = (), optional_timeout: bool = True
+    ) -> dict:
+        fields = {
+            "action": {"const": action},
+            **({} if action == "open" else session),
+            **({} if not optional_timeout else timeout),
+            **{name: properties[name] for name in required},
+            **(
+                {"duration_ms": properties["duration_ms"]}
+                if action in {"click", "press"}
+                else {}
+            ),
+            **({"button": properties["button"]} if action == "click" else {}),
+            **({"steps": properties["steps"]} if action == "move" else {}),
+            **({name: properties[name] for name in ("x", "y")} if action == "scroll" else {}),
+            **(
+                {"element_ref": properties["element_ref"]}
+                if action in {"click", "fill", "press"} else {}
+            ),
+        }
+        return {
+            "type": "object",
+            "additionalProperties": False,
+            "required": ["action", *([] if action == "open" else session),
+                         *(name for name in required if name != "selector")],
+            "properties": fields,
+            **({"oneOf": [{"required": ["selector"]}, {"required": ["element_ref"]}]}
+               if action in {"click", "fill", "press"} else {}),
+            **({"dependentRequired": {"x": ["y"], "y": ["x"]}} if action == "scroll" else {}),
+        }
+
+    properties = {
+        "url": {"type": "string", "minLength": 1},
+        "selector": {"type": "string", "minLength": 1},
+        "element_ref": {"type": "string", "minLength": 1, "maxLength": 64},
+        "value": {"type": ["string", "integer"]},
+        "key": {"type": ["string", "integer"], "minimum": 0, "maximum": 9, "minLength": 1},
+        "button": {"enum": ["left", "right", "middle"]},
+        "x": {"type": "integer", "minimum": 0, "maximum": 4096},
+        "y": {"type": "integer", "minimum": 0, "maximum": 4096},
+        "steps": {"type": "integer", "minimum": 1, "maximum": 30},
+        "delta_x": {"type": "integer", "minimum": -10000, "maximum": 10000},
+        "delta_y": {"type": "integer", "minimum": -10000, "maximum": 10000},
+        "duration_ms": {"type": "integer", "minimum": 0, "maximum": 5000},
+    }
+    return ToolDefinition(
+        name="native_browser",
+        observation_role="browser",
+        description=(
+            "Operate a persistent scoped browser. First call open with only action; "
+            "it creates a blank session and returns session_ref. Then call navigate "
+            "with the URL, session_id and generation from that ref. Reuse the same "
+            "session_id and generation for click, fill, press, move, scroll, screenshot and close. "
+            "For fill, value is text; an integer is accepted as its decimal text. "
+            "For press, key is a string or a single digit integer. "
+            "For click/fill/press, use exactly one of element_ref from returned controls "
+            "or a CSS selector. Prefer element_ref for an observed control: it targets the "
+            "same DOM node after reordering; a stale ref returns a fresh observation. "
+            "Click and press can hold their input for duration_ms (0–5000) before release. "
+            "Click can choose left/right/middle button; move uses viewport CSS pixel x/y. "
+            "Scroll uses signed delta_x/delta_y CSS pixels, optionally at an x/y viewport point. "
+            "Wheel dispatch does not prove scrolling settled; inspect the returned observation. "
+            "Observations include screenshots; action success is not task acceptance."
+        ),
+        parameters={
+            "type": "object",
+            "oneOf": [
+                action_schema("open", optional_timeout=False),
+                action_schema("navigate", ("url",)),
+                action_schema("click", ("selector",)),
+                action_schema("fill", ("selector", "value")),
+                action_schema("press", ("selector", "key")),
+                action_schema("move", ("x", "y")),
+                action_schema("scroll", ("delta_x", "delta_y")),
+                action_schema("screenshot"),
+                action_schema("close"),
+            ],
+        },
+    )

ksadk/harness/browser_adapters/native_dom_snapshot.py

@@ -0,0 +1,187 @@
+"""Bounded host-owned DOM handles, never stored in page globals or attributes."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+# One page task returns metadata and the exact elements used to produce it.
+# Input values stay excluded; page-provided text does not mint reference IDs.
+DOM_CAPTURE = r"""() => {
+  const semantic = Array.from(document.querySelectorAll(
+    'button,input,textarea,select,a[href],[role="button"],[contenteditable="true"]'
+  ));
+  const pointer = Array.from(document.querySelectorAll('*')).slice(0, 4000)
+    .filter((el) => {
+      const isPointer = getComputedStyle(el).cursor === 'pointer';
+      return isPointer && (!el.parentElement
+        || getComputedStyle(el.parentElement).cursor !== 'pointer');
+    });
+  const nodes = Array.from(new Set([...semantic, ...pointer]));
+  const visible = nodes.filter((el) => {
+    const rect = el.getBoundingClientRect();
+    const style = getComputedStyle(el);
+    const type = (el.getAttribute('type') || '').toLowerCase();
+    return rect.width > 0 && rect.height > 0 && style.visibility !== 'hidden'
+      && style.display !== 'none' && type !== 'password' && type !== 'hidden';
+  });
+  const structuralSelector = (el) => {
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === 1 && parts.length < 20) {
+      const id = node.id && globalThis.CSS?.escape
+        ? '#' + CSS.escape(node.id) : null;
+      if (id && document.querySelectorAll(id).length === 1) {
+        parts.unshift(id);
+        break;
+      }
+      const tag = node.tagName.toLowerCase();
+      const siblings = node.parentElement
+        ? Array.from(node.parentElement.children).filter(
+          (sibling) => sibling.tagName === node.tagName
+        ) : [node];
+      parts.unshift(tag + ':nth-of-type(' + (siblings.indexOf(node) + 1) + ')');
+      node = node.parentElement;
+    }
+    if (node && node.parentElement && parts.length >= 20) return null;
+    const candidate = parts.join(' > ');
+    return candidate && candidate.length <= 512
+      && document.querySelectorAll(candidate).length === 1 ? candidate : null;
+  };
+  const refElements = visible.slice(0, 40);
+  const controls = refElements.map((el) => {
+    const tag = el.tagName.toLowerCase();
+    const rect = el.getBoundingClientRect();
+    const inViewport = rect.right > 0 && rect.bottom > 0
+      && rect.left < innerWidth && rect.top < innerHeight;
+    const hitX = Math.max(0, Math.min(innerWidth - 1,
+      (Math.max(0, rect.left) + Math.min(innerWidth, rect.right)) / 2));
+    const hitY = Math.max(0, Math.min(innerHeight - 1,
+      (Math.max(0, rect.top) + Math.min(innerHeight, rect.bottom)) / 2));
+    const hit = inViewport ? document.elementFromPoint(hitX, hitY) : null;
+    const id = el.id && globalThis.CSS?.escape ? '#' + CSS.escape(el.id) : null;
+    const duplicateId = Boolean(id && document.querySelectorAll(id).length > 1);
+    const selector = duplicateId ? null : id || structuralSelector(el);
+    const label = el.getAttribute('aria-label') || el.labels?.[0]?.innerText
+      || el.getAttribute('placeholder') || el.innerText || '';
+    return {
+      tag,
+      role: el.getAttribute('role') || '',
+      label: String(label).trim().slice(0, 160),
+      selector,
+      duplicate_id: duplicateId,
+      clickable: tag === 'button' || el.getAttribute('role') === 'button'
+        || getComputedStyle(el).cursor === 'pointer',
+      hit_test_reachable: !inViewport ? null : !el.matches(':disabled')
+        && (hit === el || el.contains(hit))
+    };
+  });
+  return {refElements, meta: {
+    url: location.href,
+    title: document.title,
+    text: document.body?.innerText || '',
+    focus: document.activeElement?.tagName || '',
+    scroll_x: Math.round(window.scrollX),
+    scroll_y: Math.round(window.scrollY),
+    lifecycle: document.readyState,
+    pointer_lock_active: Boolean(document.pointerLockElement),
+    controls
+  }};
+}"""
+
+
+async def _dispose(handles: list[Any]) -> None:
+    for handle in handles:
+        try:
+            await handle.dispose()
+        except Exception:
+            # Navigation/closing can already have released the execution context.
+            pass
+
+
+class BrowserElementRefs:
+    """Latest bounded observation; unchanged DOM nodes retain their opaque ID."""
+
+    def __init__(self) -> None:
+        self._elements: dict[str, Any] = {}
+
+    async def clear(self) -> None:
+        previous, self._elements = self._elements, {}
+        await _dispose(list(previous.values()))
+
+    async def capture(self, page: Any) -> tuple[dict, tuple[str | None, ...]]:
+        transient: list[Any] = []
+        acquired: list[Any] = []
+        adopted = False
+        try:
+            collection = await page.evaluate_handle(DOM_CAPTURE)
+            transient.append(collection)
+            metadata = await collection.get_property("meta")
+            transient.append(metadata)
+            nodes = await collection.get_property("refElements")
+            transient.append(nodes)
+            meta = await metadata.json_value()
+            if not isinstance(meta, dict):
+                raise ValueError("invalid DOM snapshot")
+            handles: dict[int, Any] = {}
+            for index, handle in (await nodes.get_properties()).items():
+                acquired.append(handle)
+                element = handle.as_element()
+                if index.isdecimal() and int(index) < 40 and element is not None:
+                    handles[int(index)] = element
+            prior_tokens = list(self._elements)
+            prior_handles = list(self._elements.values())
+            if prior_handles:
+                try:
+                    same_document = await prior_handles[0].evaluate(
+                        "node => node.ownerDocument === document"
+                    )
+                except Exception:
+                    same_document = False
+                if not same_document:
+                    # A successful click can navigate without _navigate().
+                    # Its old execution context cannot supply refs to the new
+                    # document; this does not justify replaying that click.
+                    await self.clear()
+                    prior_tokens, prior_handles = [], []
+            # Compare actual node identity in one browser task, without writing
+            # refs into an untrusted DOM/global map or one RPC per element pair.
+            matches = (
+                await nodes.evaluate(
+                    "(nodes, prior) => nodes.map(node => prior.indexOf(node))",
+                    prior_handles,
+                )
+                if handles
+                else []
+            )
+            refs: dict[str, Any] = {}
+            tokens: list[str | None] = []
+            controls = meta.get("controls", [])
+            for index in range(min(40, len(controls))):
+                element = handles.get(index)
+                if element is None:
+                    tokens.append(None)
+                    continue
+                match = matches[index] if index < len(matches) else -1
+                token = prior_tokens[match] if 0 <= match < len(prior_tokens) else uuid.uuid4().hex
+                refs[token] = element
+                tokens.append(token)
+            previous, self._elements = self._elements, refs
+            adopted = True
+            await _dispose(
+                list(previous.values()) + [h for h in acquired if h not in refs.values()]
+            )
+            return meta, tuple(tokens)
+        finally:
+            if not adopted:
+                await _dispose(acquired)
+            await _dispose(transient)
+
+    async def resolve(self, token: str) -> Any | None:
+        element = self._elements.get(token)
+        if element is None:
+            return None
+        try:
+            return element if await element.evaluate("node => node.isConnected") else None
+        except Exception:
+            return None