Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

feat(computer): add a persistent JavaScript kernel for vibe computer js (#2882)

Maxdbcf8abe4f3e
diff --git a/core/computer_cli.py b/core/computer_cli.py
index 419c82242..e801fd73d 100644
--- a/core/computer_cli.py
+++ b/core/computer_cli.py
@@ -38,6 +38,14 @@ OBSERVATION_TOOLS = frozenset(
SCREENSHOT_TOOLS = frozenset({"get_window_state", "zoom"})
+# Upper bound on how long one ``vibe computer js`` call can stay admitted: the
+# Controller leases its exact-Turn connection for this long, and every path
+# (queue cap, per-call timeout, cancel grace, kernel start) settles inside it.
+# The CLI waits at least this long so it never gives up before the Controller.
+COMPUTER_JS_CONNECTION_LEASE_SECONDS = 3600.0
+COMPUTER_JS_CLIENT_MARGIN_SECONDS = 60.0
+
+
class ComputerCliError(ValueError):
"""The CLI request cannot be translated into a driver call."""
@@ -194,6 +202,15 @@ _COMPUTER_ERROR_I18N_KEYS = {
"invalid_computer_script_descriptor": "computer.cli.error.scriptInvalidDescriptor",
"invalid_selector": "computer.cli.error.scriptInvalidSelector",
"invalid_timeout": "computer.cli.error.scriptInvalidTimeout",
+ "invalid_computer_js_code": "computer.cli.error.jsCodeInvalid",
+ "invalid_computer_js_request": "computer.cli.error.requestRejected",
+ "computer_js_code_too_large": "computer.cli.error.jsCodeTooLarge",
+ "js_call_inactive": "computer.cli.error.jsCallInactive",
+ "js_kernel_error": "computer.cli.error.jsKernelError",
+ "js_kernel_busy": "computer.cli.error.jsKernelBusy",
+ "js_kernel_reset": "computer.cli.error.jsKernelReset",
+ "js_kernel_unavailable": "computer.cli.error.jsKernelUnavailable",
+ "js_timeout": "computer.cli.error.jsTimeout",
"not_found": "computer.cli.error.scriptTargetNotFound",
"observe_first": "computer.cli.error.observeFirst",
"platform_unsupported": "computer.cli.error.platformUnsupported",
diff --git a/core/computer_js_kernels.py b/core/computer_js_kernels.py
new file mode 100644
index 000000000..a91e35d27
--- /dev/null
+++ b/core/computer_js_kernels.py
@@ -0,0 +1,691 @@
+"""Controller-owned persistent JavaScript kernels for ``vibe computer js``.
+
+One Node process per Avibe Session keeps top-level bindings between calls.
+The kernel holds no desktop capability of its own: every call opens an
+ordinary exact-Turn script connection (``ComputerScriptSessionManager``) and
+the kernel uses that token only while the call executes. The Controller's
+existing ``/internal/computer-script`` routes therefore keep every safety rule
+(target locks, observe-first, handle descriptors, confirm).
+
+Lifecycle, all owned here:
+
+- started lazily by the first call; a call that started a kernel reports
+ ``kernel_fresh: true`` so the agent knows earlier bindings are gone;
+- calls in one Session are serialized;
+- a call is cancelled at its timeout or when its Turn ends; a kernel that does
+ not settle the cancel is killed and the call reports ``js_kernel_reset``;
+- killed on ``js-reset``, idle, Session archive, Computer Use off, and service
+ shutdown. The kernel also exits when the Controller's socket closes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+import itertools
+import json
+import logging
+import os
+from pathlib import Path
+import signal
+import socket
+import tempfile
+from typing import TYPE_CHECKING, Any, Callable
+
+from core.computer_cli import COMPUTER_JS_CONNECTION_LEASE_SECONDS as _CONNECTION_LEASE_SECONDS
+from vibe.computer_script_runner import (
+ _failure_envelope,
+ _prune_retained_artifact_runs,
+ _sdk_directory,
+)
+
+if TYPE_CHECKING:
+ from core.computer_script_sessions import ComputerScriptSessionManager
+
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TIMEOUT_MS = 30_000
+MAX_TIMEOUT_MS = 300_000
+MAX_CODE_BYTES = 1024 * 1024
+IDLE_SECONDS = 15 * 60
+KILL_GRACE_SECONDS = 2.0
+SPAWN_TIMEOUT_SECONDS = 10.0
+STATUS_POLL_SECONDS = 15.0
+# Each call's connection is leased for the script-connection maximum; it is
+# closed as soon as the call ends, and its Turn ending invalidates it at once.
+# The execution deadline starts only when the call holds the Session lock, and
+# the queue cap keeps every queued call's whole wait inside this lease.
+QUEUE_LIMIT = 8
+_MESSAGE_LIMIT_BYTES = 16 * 1024 * 1024
+_ARTIFACT_PREFIX = "avibe-computer-js-"
+_KERNEL_FD_ENV = "AVIBE_COMPUTER_KERNEL_FD"
+_KERNEL_ENV_KEYS = ("PATH", "HOME", "TMPDIR", "LANG", "LC_ALL", "TZ")
+_RESET_MESSAGE = "The JavaScript kernel was reset; all bindings were discarded."
+
+
+class _KernelGone(RuntimeError):
+ """The kernel process ended before the call settled."""
+
+ def __init__(self, reason: str) -> None:
+ self.reason = reason
+ super().__init__(reason)
+
+
+def _envelope(
+ code: str,
+ message: str,
+ *,
+ name: str = "ControllerError",
+ params: dict[str, Any] | None = None,
+ ambiguous: bool = False,
+) -> dict[str, Any]:
+ return _failure_envelope(
+ name=name,
+ code=code,
+ message=message,
+ params=params or {},
+ step="script",
+ last_completed_step=None,
+ screenshot_path=None,
+ ambiguous=ambiguous,
+ )
+
+
+def _failed(
+ error: dict[str, Any],
+ *,
+ kernel_fresh: bool = False,
+) -> dict[str, Any]:
+ return {
+ "ok": False,
+ "error": error,
+ "console": "",
+ "screenshots": [],
+ "kernel_fresh": kernel_fresh,
+ }
+
+
+def _default_endpoint_payload() -> dict[str, Any]:
+ from vibe.internal_client import (
+ computer_script_endpoint_payload,
+ resolve_computer_script_endpoint,
+ )
+
+ return computer_script_endpoint_payload(resolve_computer_script_endpoint())
+
+
+def _default_node() -> Path | None:
+ from vibe.desktop_runtime import private_desktop_node_bin
+
+ return private_desktop_node_bin()
+
+
+def _kernel_platform_supported() -> bool:
+ # The kernel transport (inherited socketpair, process-group kill) is POSIX.
+ # Computer Use itself is macOS-only in Phase 1; Windows IPC and termination
+ # belong to the future Windows Computer Use lane.
+ return os.name == "posix"
+
+
+def _default_status() -> Any:
+ from core.computer_use import effective_computer_use_status
+
+ return effective_computer_use_status()
+
+
+@dataclass
+class _Kernel:
+ process: asyncio.subprocess.Process
+ writer: asyncio.StreamWriter
+ artifact_directory: Path
+ ready: asyncio.Future[None]
+ pending: dict[int, asyncio.Future[dict[str, Any]]] = field(default_factory=dict)
+ reader_task: asyncio.Task[None] | None = None
+ alive: bool = True
+
+
+@dataclass(eq=False)
+class _Admitted:
+ """One admitted call, queued or executing, with its cancellation signal."""
+
+ cancel: asyncio.Future[str]
+ executing: bool = False
+ reset_reason: str | None = None
+
+
+@dataclass
+class _Slot:
+ lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+ kernel: _Kernel | None = None
+ idle_handle: asyncio.TimerHandle | None = None
+ calls: set[_Admitted] = field(default_factory=set)
+ # Set once by _invalidate_slot. An invalidated slot is never reused: it
+ # refuses any later lock holder and never starts a kernel.
+ invalidated: str | None = None
+
+
+class ComputerJsKernelManager:
+ """Own one persistent JavaScript kernel per Avibe Session."""
+
+ def __init__(
+ self,
+ script_sessions: "ComputerScriptSessionManager",
+ *,
+ node_resolver: Callable[[], Path | None] = _default_node,
+ endpoint_resolver: Callable[[], dict[str, Any]] = _default_endpoint_payload,
+ status_reader: Callable[[], Any] = _default_status,
+ idle_seconds: float = IDLE_SECONDS,
+ kill_grace_seconds: float = KILL_GRACE_SECONDS,
+ status_poll_seconds: float = STATUS_POLL_SECONDS,
+ queue_limit: int = QUEUE_LIMIT,
+ ) -> None:
+ self._script_sessions = script_sessions
+ self._node_resolver = node_resolver
+ self._endpoint_resolver = endpoint_resolver
+ self._status_reader = status_reader
+ self._idle_seconds = idle_seconds
+ self._kill_grace_seconds = kill_grace_seconds
+ self._status_poll_seconds = status_poll_seconds
+ self._queue_limit = queue_limit
+ self._slots: dict[str, _Slot] = {}
+ self._in_flight: dict[str, asyncio.Future[str]] = {}
+ self._call_ids = itertools.count(1)
+ self._status_task: asyncio.Task[None] | None = None
+ self._background: set[asyncio.Task[Any]] = set()
+
+ # Public surface -----------------------------------------------------
+
+ async def evaluate(
+ self,
+ caller_session_id: str,
+ code: Any,
+ timeout_ms: Any,
+ ) -> dict[str, Any]:
+ """Run one call in the caller Session's kernel and return its report."""
+
+ if not isinstance(code, str) or not code.strip():
+ return _failed(_envelope("invalid_computer_js_code", "Code must be non-empty text."))
+ if len(code.encode("utf-8")) > MAX_CODE_BYTES:
+ return _failed(
+ _envelope(
+ "computer_js_code_too_large",
+ "The code exceeded the size limit.",
+ params={"limit_bytes": MAX_CODE_BYTES},
+ )
+ )
+ if (
+ isinstance(timeout_ms, bool)
+ or not isinstance(timeout_ms, int)
+ or not 1 <= timeout_ms <= MAX_TIMEOUT_MS
+ ):
+ return _failed(
+ _envelope(
+ "invalid_timeout",
+ "The timeout is outside the supported range.",
+ params={"max_ms": MAX_TIMEOUT_MS},
+ )
+ )
+
+ from core.computer_script_sessions import ComputerScriptSessionError
+
+ # Admission happens when the request enters, before it queues: the call
+ # is bound to the Turn that issued it, never to whichever Turn is live
+ # when the lock frees up.
+ try:
+ opened = self._script_sessions.open(caller_session_id, _CONNECTION_LEASE_SECONDS)
+ except ComputerScriptSessionError as exc:
+ return _failed(_envelope(exc.code, exc.code))
+ session_id = opened["session_id"]
+ token = opened["connection_token"]
+ call = _Admitted(cancel=asyncio.get_running_loop().create_future())
+ self._in_flight[token] = call.cancel
+ slot = self._slots.setdefault(session_id, _Slot())
+ try:
+ if sum(not admitted.executing for admitted in slot.calls) >= self._queue_limit:
+ return _failed(
+ _envelope(
+ "js_kernel_busy",
+ "Too many calls are already waiting in this Session.",
+ params={"queue_limit": self._queue_limit},
+ )
+ )
+ slot.calls.add(call)
+ if not await self._acquire(slot.lock, call.cancel):
+ return self._cancelled(call)
+ try:
+ call.executing = True
+ self._cancel_idle(slot)
+ return await self._evaluate_locked(slot, call, token, code, timeout_ms)
+ finally:
+ self._schedule_idle(slot)
+ slot.lock.release()
+ finally:
+ slot.calls.discard(call)
+ self._in_flight.pop(token, None)
+ self._script_sessions.close(token)
+
+ def reset(self, caller_session_id: str) -> dict[str, Any]:
+ """Discard the caller Session's kernel and every binding in it."""
+
+ from core.computer_script_sessions import ComputerScriptSessionError
+
+ try:
+ session_id = self._script_sessions.check_caller(caller_session_id)
+ except ComputerScriptSessionError as exc:
+ return {"ok": False, "error": _envelope(exc.code, exc.code)}
+ slot = self._slots.get(session_id)
+ discarded = bool(slot and slot.kernel and slot.kernel.alive)
+ self._invalidate_slot(session_id, "reset")
+ return {"ok": True, "discarded": discarded}
+
+ def on_token_invalidated(self, token: str, code: str) -> None:
+ """Cancel the call bound to a script connection that just ended."""
+
+ cancel = self._in_flight.get(token)
+ if cancel is not None and not cancel.done():
+ cancel.set_result(code)
+
+ def discard_session(self, session_id: str) -> None:
+ """Kill a Session's kernel when the Session is archived."""
+
+ self._invalidate_slot(session_id, "session_archived")
+
+ def close_all(self) -> None:
+ """Kill every kernel on service shutdown."""
+
+ for session_id in list(self._slots):
+ self._invalidate_slot(session_id, "shutdown")
+ if self._status_task is not None:
+ self._status_task.cancel()
+ self._status_task = None
+
+ def _invalidate_slot(self, session_id: str, reason: str) -> None:
+ """The one entry for reset, archive, Computer Use off, and shutdown.
+
+ It kills the kernel and cancels every call admitted to the slot: the
+ executing call and every queued call report ``js_kernel_reset`` with
+ ``reason``, and no queued call ever executes. The slot leaves the
+ registry, so only calls admitted after this point get a new kernel.
+ """
+
+ slot = self._slots.pop(session_id, None)
+ if slot is None:
+ return
+ slot.invalidated = reason
+ self._kill_slot(slot, reason)
+ for admitted in slot.calls:
+ if not admitted.cancel.done():
+ admitted.reset_reason = reason
+ admitted.cancel.set_result("js_kernel_reset")
+
+ def _cancelled(self, call: _Admitted, *, kernel_fresh: bool = False) -> dict[str, Any]:
+ if call.reset_reason is not None:
+ return {**self._reset_report(call.reset_reason), "kernel_fresh": kernel_fresh}
+ code = call.cancel.result()
+ return _failed(_envelope(code, code), kernel_fresh=kernel_fresh)
+
+ # Calls --------------------------------------------------------------
+
+ @staticmethod
+ async def _acquire(lock: asyncio.Lock, cancel: asyncio.Future[str]) -> bool:
+ """Wait for the Session lock unless the call's connection ends first."""
+
+ if cancel.done():
+ return False
+ acquire = asyncio.ensure_future(lock.acquire())
+
+ def give_back(task: asyncio.Future[Any]) -> None:
+ if not task.cancelled() and task.exception() is None:
+ lock.release()
+
+ try:
+ await asyncio.wait({acquire, cancel}, return_when=asyncio.FIRST_COMPLETED)
+ except asyncio.CancelledError:
+ acquire.add_done_callback(give_back)
+ acquire.cancel()
+ raise
+ if cancel.done():
+ acquire.add_done_callback(give_back)
+ acquire.cancel()
+ return False
+ return True
+
+ async def _evaluate_locked(
+ self,
+ slot: _Slot,
+ call: _Admitted,
+ token: str,
+ code: str,
+ timeout_ms: int,
+ ) -> dict[str, Any]:
+ if slot.invalidated is not None or call.cancel.done():
+ return self._cancelled(call)
+ status = await self._computer_use_status()
+ if slot.invalidated is not None or call.cancel.done():
+ return self._cancelled(call)
+ if getattr(status, "status", None) == "off":
+ for session_id, candidate in list(self._slots.items()):
+ if candidate is slot:
+ self._invalidate_slot(session_id, "computer_use_off")
+ return _failed(
+ _envelope(
+ "computer_use_unavailable",
+ "Computer Use is off.",
+ params={"status": "off", "reason": getattr(status, "reason", None)},
+ )
+ )
+ kernel_fresh = False
+ kernel = slot.kernel
+ if kernel is None or not kernel.alive:
+ if not _kernel_platform_supported():
+ return _failed(
+ _envelope(
+ "platform_unsupported",
+ "The JavaScript kernel is unavailable on this platform.",
+ )
+ )
+ try:
+ kernel = await self._spawn()
+ if slot.invalidated is not None:
+ # Invalidated while starting: never hand this slot a kernel.
+ self._kill(kernel, slot.invalidated)
+ return self._cancelled(call, kernel_fresh=True)
+ except _KernelGone as exc:
+ return _failed(
+ _envelope(
+ "js_kernel_unavailable",
+ "The JavaScript kernel could not be started.",
+ params={"reason": exc.reason},
+ )
+ )
+ slot.kernel = kernel
+ kernel_fresh = True
+ if call.cancel.done():
+ return self._cancelled(call, kernel_fresh=kernel_fresh)
+ report = await self._run_call(slot, kernel, token, call.cancel, code, timeout_ms)
+ return {**report, "kernel_fresh": kernel_fresh}
+
+ async def _run_call(
+ self,
+ slot: _Slot,
+ kernel: _Kernel,
+ token: str,
+ cancel: asyncio.Future[str],
+ code: str,
+ timeout_ms: int,
+ ) -> dict[str, Any]:
+ call_id = next(self._call_ids)
+ settled: asyncio.Future[dict[str, Any]] = asyncio.get_running_loop().create_future()
+ kernel.pending[call_id] = settled
+ try:
+ await self._send(
+ kernel,
+ {
+ "type": "eval",
+ "id": call_id,
+ "code": code,
+ "connection_token": token,
+ },
+ )
+ await asyncio.wait(
+ {settled, cancel},
+ timeout=timeout_ms / 1000,
+ return_when=asyncio.FIRST_COMPLETED,
+ )
+ if not settled.done():
+ reason = cancel.result() if cancel.done() else "js_timeout"
+ await self._send(kernel, {"type": "cancel", "id": call_id, "code": reason})
+ try:
+ await asyncio.wait_for(
+ asyncio.shield(settled),
+ self._kill_grace_seconds,
+ )
+ except asyncio.TimeoutError:
+ self._kill_slot(slot, "unsettled")
+ return self._report(settled.result())
+ except _KernelGone as exc:
+ return self._reset_report(exc.reason)
+ except asyncio.CancelledError:
+ # The CLI request went away; never leave the kernel busy with a
+ # call nobody will collect.
+ if kernel.alive:
+ try:
+ await self._send(kernel, {"type": "cancel", "id": call_id})
+ except _KernelGone:
+ pass
+ raise
+ finally:
+ kernel.pending.pop(call_id, None)
+
+ @staticmethod
+ def _report(message: dict[str, Any]) -> dict[str, Any]:
+ console = message.get("console")
+ screenshots = message.get("screenshots")
+ report: dict[str, Any] = {
+ "ok": message.get("ok") is True,
+ "console": console if isinstance(console, str) else "",
+ "screenshots": [
+ item for item in screenshots if isinstance(item, str)
+ ]
+ if isinstance(screenshots, list)
+ else [],
+ }
+ if report["ok"]:
+ report["result"] = message.get("result")
+ if isinstance(message.get("result_text"), str):
+ report["result_text"] = message["result_text"]
+ else:
+ error = message.get("error")
+ report["error"] = (
+ error
+ if isinstance(error, dict)
+ else _envelope(
+ "computer_script_protocol_error",
+ "The kernel returned an invalid result.",
+ ambiguous=True,
+ )
+ )
+ return report
+
+ @staticmethod
+ def _reset_report(reason: str) -> dict[str, Any]:
+ return {
+ "ok": False,
+ "error": _envelope(
+ "js_kernel_reset",
+ _RESET_MESSAGE,
+ name="KernelReset",
+ params={"reason": reason},
+ ambiguous=True,
+ ),
+ "console": "",
+ "screenshots": [],
+ }
+
+ # Kernel process -----------------------------------------------------
+
+ async def _spawn(self) -> _Kernel:
+ node = self._node_resolver()
+ kernel_script = _sdk_directory() / "kernel.mjs"
+ if node is None or not kernel_script.is_file():
+ raise _KernelGone("runtime_unavailable")
+ try:
+ endpoint = await asyncio.to_thread(self._endpoint_resolver)
+ except Exception as exc:
+ raise _KernelGone("controller_unavailable") from exc
+
+ artifact_directory = Path(tempfile.mkdtemp(prefix=_ARTIFACT_PREFIX)).resolve()
+ os.chmod(artifact_directory, 0o700)
+ (artifact_directory / ".active").touch(mode=0o600)
+ parent, child = socket.socketpair()
+ environment = {
+ key: os.environ[key] for key in _KERNEL_ENV_KEYS if key in os.environ
+ }
+ environment[_KERNEL_FD_ENV] = str(child.fileno())
+ try:
+ process = await asyncio.create_subprocess_exec(
+ str(node),
+ str(kernel_script),
+ stdin=asyncio.subprocess.DEVNULL,
+ stdout=asyncio.subprocess.DEVNULL,
+ stderr=asyncio.subprocess.DEVNULL,
+ pass_fds=(child.fileno(),),
+ start_new_session=True,
+ env=environment,
+ cwd=str(artifact_directory),
+ )
+ except OSError as exc:
+ parent.close()
+ await asyncio.to_thread(self._release_artifacts, artifact_directory)
+ raise _KernelGone("spawn_failed") from exc
+ finally:
+ child.close()
+
+ reader, writer = await asyncio.open_connection(
+ sock=parent,
+ limit=_MESSAGE_LIMIT_BYTES,
+ )
+ kernel = _Kernel(
+ process=process,
+ writer=writer,
+ artifact_directory=artifact_directory,
+ ready=asyncio.get_running_loop().create_future(),
+ )
+ kernel.reader_task = asyncio.create_task(self._read(kernel, reader))
+ try:
+ await self._send(
+ kernel,
+ {
+ "type": "init",
+ "endpoint": endpoint,
+ "artifact_directory": str(artifact_directory),
+ },
+ )
+ await asyncio.wait_for(asyncio.shield(kernel.ready), SPAWN_TIMEOUT_SECONDS)
+ except (asyncio.TimeoutError, _KernelGone) as exc:
+ self._kill(kernel, "spawn_failed")
+ raise _KernelGone("spawn_failed") from exc
+ self._ensure_status_watch()
+ return kernel
+
+ async def _read(self, kernel: _Kernel, reader: asyncio.StreamReader) -> None:
+ try:
+ while True:
+ line = await reader.readline()
+ if not line:
+ break
+ message = json.loads(line)
+ if message.get("type") == "ready":
+ if not kernel.ready.done():
+ kernel.ready.set_result(None)
+ elif message.get("type") == "result":
+ settled = kernel.pending.get(message.get("id"))
+ if settled is not None and not settled.done():
+ settled.set_result(message)
+ except (ValueError, OSError, asyncio.LimitOverrunError):
+ logger.warning("Computer Use JavaScript kernel sent an invalid message")
+ finally:
+ self._kill(kernel, "exited")
+
+ async def _send(self, kernel: _Kernel, message: dict[str, Any]) -> None:
+ if not kernel.alive:
+ raise _KernelGone("exited")
+ try:
+ kernel.writer.write(json.dumps(message, ensure_ascii=False).encode() + b"\n")
+ await kernel.writer.drain()
+ except (OSError, RuntimeError) as exc:
+ self._kill(kernel, "exited")
+ raise _KernelGone("exited") from exc
+
+ def _kill(self, kernel: _Kernel, reason: str) -> None:
+ if not kernel.alive:
+ return
+ kernel.alive = False
+ try:
+ os.killpg(kernel.process.pid, signal.SIGKILL)
+ except (ProcessLookupError, PermissionError):
+ pass
+ kernel.writer.close()
+ gone = _KernelGone(reason)
+ if not kernel.ready.done():
+ kernel.ready.set_exception(gone)
+ kernel.ready.exception()
+ for settled in kernel.pending.values():
+ if not settled.done():
+ settled.set_exception(gone)
+ reaper = asyncio.get_running_loop().create_task(self._reap(kernel))
+ self._background.add(reaper)
+ reaper.add_done_callback(self._background.discard)
+
+ async def _reap(self, kernel: _Kernel) -> None:
+ try:
+ await asyncio.wait_for(kernel.process.wait(), 5.0)
+ except asyncio.TimeoutError:
+ logger.warning("Computer Use JavaScript kernel %s was not reaped", kernel.process.pid)
+ if kernel.reader_task is not None and kernel.reader_task is not asyncio.current_task():
+ kernel.reader_task.cancel()
+ # Pruning walks the temp directory; keep it off the Controller loop.
+ await asyncio.to_thread(self._release_artifacts, kernel.artifact_directory)
+
+ @staticmethod
+ def _release_artifacts(directory: Path) -> None:
+ # Screenshots stay readable after the kernel ends; only the newest
+ # inactive kernel directories are retained.
+ (directory / ".active").unlink(missing_ok=True)
+ _prune_retained_artifact_runs(directory.parent, _ARTIFACT_PREFIX)
+
+ def _kill_slot(self, slot: _Slot, reason: str) -> None:
+ self._cancel_idle(slot)
+ if slot.kernel is not None:
+ self._kill(slot.kernel, reason)
+ slot.kernel = None
+
+ # Idle and Computer Use off ------------------------------------------
+
+ def _cancel_idle(self, slot: _Slot) -> None:
+ if slot.idle_handle is not None:
+ slot.idle_handle.cancel()
+ slot.idle_handle = None
+
+ def _schedule_idle(self, slot: _Slot) -> None:
+ self._cancel_idle(slot)
+ if slot.kernel is None or not slot.kernel.alive:
+ return
+
+ def expire() -> None:
+ slot.idle_handle = None
+ # A queued call re-arms the timer when it finishes.
+ if not slot.lock.locked():
+ self._kill_slot(slot, "idle")
+
+ slot.idle_handle = asyncio.get_running_loop().call_later(
+ self._idle_seconds,
+ expire,
+ )
+
+ async def _computer_use_status(self) -> Any:
+ try:
+ return await asyncio.to_thread(self._status_reader)
+ except Exception:
+ logger.warning("Computer Use status read failed", exc_info=True)
+ return None
+
+ def _ensure_status_watch(self) -> None:
+ if self._status_task is None or self._status_task.done():
+ self._status_task = asyncio.get_running_loop().create_task(
+ self._watch_status()
+ )
+
+ async def _watch_status(self) -> None:
+ while any(
+ slot.kernel is not None and slot.kernel.alive
+ for slot in self._slots.values()
+ ):
+ await asyncio.sleep(self._status_poll_seconds)
+ status = await self._computer_use_status()
+ if getattr(status, "status", None) == "off":
+ # Executing and queued calls are cancelled with the kernel:
+ # they report js_kernel_reset, and no binding outlives off.
+ for session_id in list(self._slots):
+ self._invalidate_slot(session_id, "computer_use_off")
diff --git a/core/computer_script_sessions.py b/core/computer_script_sessions.py
index b5eb42d97..240ff5a47 100644
--- a/core/computer_script_sessions.py
+++ b/core/computer_script_sessions.py
@@ -109,6 +109,16 @@ class ComputerScriptSessionManager:
"timeout_ms": int(float(timeout_seconds) * 1000),
}
+ def check_caller(self, caller_session_id: str) -> str:
+ """Return the caller's Session when it has a live active Turn."""
+
+ admission, admission_error = self._turn_manager.begin_computer_use_request(
+ caller_session_id
+ )
+ if admission is None:
+ raise ComputerScriptSessionError(admission_error)
+ return admission.session_id
+
def admit(self, token: str) -> _ScriptBinding:
binding = self._bindings.get(token)
if binding is None:
diff --git a/core/controller.py b/core/controller.py
index 497802794..8bc9975be 100644
--- a/core/controller.py
+++ b/core/controller.py
@@ -267,6 +267,7 @@ class Controller:
self.computer_use_server = None
self.computer_script_sessions = None
self.computer_script_interactions = None
+ self.computer_js_kernels = None
self.runtime_ownership = RuntimeOwnershipProvider(
self.session_turns._sqlite_engine()
)
@@ -1704,6 +1705,9 @@ class Controller:
raise workbench_sessions_service.ReservedSessionError(raw_session_id)
async def retire_computer_use_session() -> None:
+ js_kernels = getattr(self, "computer_js_kernels", None)
+ if js_kernels is not None:
+ js_kernels.discard_session(raw_session_id)
computer_server = getattr(self, "computer_use_server", None)
retire_session = getattr(computer_server, "retire_session", None)
if not callable(retire_session):
@@ -2584,6 +2588,10 @@ class Controller:
self._internal_server_task = None
async def _close_computer_use_server() -> None:
+ js_kernels = getattr(self, "computer_js_kernels", None)
+ self.computer_js_kernels = None
+ if js_kernels is not None:
+ js_kernels.close_all()
script_interactions = getattr(
self,
"computer_script_interactions",
diff --git a/core/internal_server.py b/core/internal_server.py
index 983160b5d..06b831808 100644
--- a/core/internal_server.py
+++ b/core/internal_server.py
@@ -226,6 +226,16 @@ def create_app(
computer_script_sessions.add_invalidation_listener(
computer_script_interactions.invalidate_token,
)
+ from core.computer_js_kernels import MAX_CODE_BYTES, ComputerJsKernelManager
+
+ computer_js_kernels = getattr(controller, "computer_js_kernels", None)
+ if not isinstance(computer_js_kernels, ComputerJsKernelManager):
+ computer_js_kernels = ComputerJsKernelManager(computer_script_sessions)
+ controller.computer_js_kernels = computer_js_kernels
+ # A Turn that ends mid-call cancels that call; the kernel keeps its bindings.
+ computer_script_sessions.add_invalidation_listener(
+ computer_js_kernels.on_token_invalidated,
+ )
# The turn registry (``session_id -> Turn``) is owned by the manager and tests
# inspect it via ``app.state``. Flush intents live on each ``Turn`` (set by
@@ -1091,6 +1101,60 @@ def create_app(
"closed": computer_script_sessions.close(connection_token),
}
+ def _computer_js_request_error(code: str, status_code: int) -> JSONResponse:
+ from vibe.computer_script_runner import _failure_envelope
+
+ return JSONResponse(
+ status_code=status_code,
+ content={
+ "ok": False,
+ "error": _failure_envelope(
+ name="ControllerError",
+ code=code,
+ message=code,
+ params={"limit_bytes": MAX_CODE_BYTES} if status_code == 413 else {},
+ step="script",
+ last_completed_step=None,
+ screenshot_path=None,
+ ambiguous=False,
+ ),
+ },
+ )
+
+ @app.post("/internal/computer-js/eval")
+ async def _computer_js_eval(request: Request) -> Any:
+ try:
+ payload = await _bounded_json_object(
+ request,
+ limit=MAX_CODE_BYTES * 2 + 4096,
+ )
+ except _RequestBodyTooLarge:
+ return _computer_js_request_error("computer_js_code_too_large", 413)
+ caller_session_id = payload.get("caller_session_id")
+ if set(payload) != {
+ "caller_session_id",
+ "code",
+ "timeout_ms",
+ } or not isinstance(caller_session_id, str) or not caller_session_id.strip():
+ return _computer_js_request_error("invalid_computer_js_request", 400)
+ return await computer_js_kernels.evaluate(
+ caller_session_id.strip(),
+ payload.get("code"),
+ payload.get("timeout_ms"),
+ )
+
+ @app.post("/internal/computer-js/reset")
+ async def _computer_js_reset(request: Request) -> Any:
+ payload = await _safe_json(request)
+ caller_session_id = payload.get("caller_session_id")
+ if (
+ set(payload) != {"caller_session_id"}
+ or not isinstance(caller_session_id, str)
+ or not caller_session_id.strip()
+ ):
+ return _computer_js_request_error("invalid_computer_js_request", 400)
+ return computer_js_kernels.reset(caller_session_id.strip())
+
@app.post("/internal/show-access/settings-read")
async def _show_access_settings_read(request: Request) -> Any:
from core.show_pages import ShowPageError, ShowPageStore, show_access_payload
diff --git a/skills/computer-use/SKILL.md b/skills/computer-use/SKILL.md
index 6b67e5af2..98a686e54 100644
--- a/skills/computer-use/SKILL.md
+++ b/skills/computer-use/SKILL.md
@@ -74,6 +74,41 @@ await draft.expect({ role: "textbox", label: "To" }).toHaveValue(to);
await send.click();
```
+## Persistent JavaScript kernel
+
+Use `run` for a complete reusable flow saved as a file. Use `js` for
+step-by-step exploration that keeps variables between calls:
+
+```text
+vibe computer js --code 'const mail = await computer.app({ bundleId: "com.apple.mail" })'
+vibe computer js --code 'const inbox = await mail.waitFor({ role: "AXWindow", labelContains: "Inbox" }); inbox'
+vibe computer js --code @/tmp/next-step.js --timeout-ms 60000
+vibe computer js-reset
+```
+
+Each Avibe Session has one kernel with `computer` and `avibe` preloaded and
+top-level `await` supported. Top-level bindings persist until
+`vibe computer js-reset`, which discards them without closing any app. The JSON
+output adds `result`, a capped `console` tail, `screenshots`, and
+`kernel_fresh`. Each call has a 30-second default timeout (`--timeout-ms`, at
+most 300000); a timed-out call is cancelled and the kernel keeps its bindings.
+A call that does not settle after cancellation fails with `js_kernel_reset`:
+the kernel was killed and all bindings were discarded. Idle kernels (about 15
+minutes), archived Sessions, Computer Use turning off, and service restarts
+also discard the kernel. Whenever a call reports `kernel_fresh: true`, earlier
+bindings are gone; rebuild them instead of assuming they exist.
+
+Every call is bound to the current Turn. Timers and Computer Use requests
+belong to the call that started them: once that call ends, completes, times
+out, or loses its Turn, its timers never fire and its requests never settle, so
+leftover code stays frozen. Code you wire to wake it yourself (for example
+`fetch`, or a promise a later call resolves) can still change bindings but can
+never reach the Controller or the desktop. Run `vibe computer js-reset` when you
+need a guaranteed clean state. Handles and
+element references stored in variables can go stale between calls (driver idle
+TTL, or a person changing the app); that surfaces as the usual stale-handle or
+`observe_first` error, so observe again instead of retrying blindly.
+
Every single-operation leaf accepts `--args-json OBJECT`, `--args-json @FILE`,
repeatable `--arg NAME=VALUE`, and `--json`. The two screenshot operations also
accept `--output PATH`; the CLI writes or confirms the caller-selected PNG and
diff --git a/tests/test_computer_cli.py b/tests/test_computer_cli.py
index dc335c0fc..342bf6017 100644
--- a/tests/test_computer_cli.py
+++ b/tests/test_computer_cli.py
@@ -59,6 +59,8 @@ def _bind_socket(path: Path) -> socket.socket:
def test_parser_covers_the_allowlisted_driver_operations_without_session_id() -> None:
commands = [
(["computer", "run", "./script.mjs"], ("run",)),
+ (["computer", "js", "--code", "1"], ("js",)),
+ (["computer", "js-reset"], ("js-reset",)),
(["computer", "observe", "apps"], ("observe", "apps")),
(["computer", "observe", "windows"], ("observe", "windows")),
(["computer", "observe", "window"], ("observe", "window")),
@@ -86,7 +88,7 @@ def test_parser_covers_the_allowlisted_driver_operations_without_session_id() ->
else:
command_path = (args.computer_command,)
assert command_path == path
- if path != ("run",):
+ if path not in {("run",), ("js",), ("js-reset",)}:
assert tool_for_command(path)
with pytest.raises(SystemExit):
@@ -122,6 +124,11 @@ def test_packaged_skill_examples_parse_and_match_the_pinned_driver_schema() -> N
if args.computer_command == "run":
assert args.file.endswith(".mjs")
continue
+ if args.computer_command == "js":
+ assert args.code.strip() and 1 <= args.timeout_ms <= 300000
+ continue
+ if args.computer_command == "js-reset":
+ continue
if args.computer_command == "observe":
path = ("observe", args.computer_observe_command)
elif args.computer_command == "clipboard":
@@ -148,9 +155,15 @@ def test_packaged_skill_examples_parse_and_match_the_pinned_driver_schema() -> N
assert documented_flags == {
"--arg",
"--args-json",
+ "--code",
"--json",
"--output",
+ "--timeout-ms",
+ }
+ documented_js = {
+ command.split()[2] for command in commands if command.split()[2].startswith("js")
}
+ assert documented_js == {"js", "js-reset"}
parser.parse_args(
[
"computer",
@@ -382,6 +395,9 @@ def test_computer_cli_error_translations_exist_in_all_supported_languages() -> N
"computer.cli.error.scriptRuntimeInvalid",
"computer.cli.error.scriptTimedOut",
"computer.cli.error.scriptFailed",
+ "computer.cli.error.jsFailed",
+ "computer.cli.error.jsCodeFile",
+ "computer.cli.error.jsTimeoutRange",
}
for catalog_path in sorted(Path("vibe/i18n").glob("*.json")):
catalog = json.loads(catalog_path.read_text(encoding="utf-8"))
diff --git a/tests/test_computer_js_kernel.py b/tests/test_computer_js_kernel.py
new file mode 100644
index 000000000..06aa90fa9
--- /dev/null
+++ b/tests/test_computer_js_kernel.py
@@ -0,0 +1,609 @@
+"""Hermetic tests for the persistent ``vibe computer js`` kernel.
+
+Each test runs the real internal server on a private Unix socket, the real
+script-connection manager, and the shipped Node kernel. Only the desktop
+driver (``ComputerUseServer``) and the Computer Use status are fakes, so no
+test can reach the owner's desktop, TCC state, or running service.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+from contextlib import asynccontextmanager
+import json
+import shutil
+import tempfile
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, AsyncIterator
+
+import httpx
+import pytest
+
+from core import internal_server, session_turns
+from core.computer_js_kernels import ComputerJsKernelManager
+from core.computer_script_sessions import ComputerScriptSessionManager
+from modules.im import MessageContext
+
+
+NODE = shutil.which("node")
+pytestmark = pytest.mark.skipif(NODE is None, reason="Node.js is required")
+SESSION = "ses-js"
+
+
+def _context(turn_id: str) -> MessageContext:
+ return MessageContext(
+ user_id="owner",
+ channel_id="channel",
+ platform="avibe",
+ platform_specific={"agent_session_id": SESSION, "turn_token": turn_id},
+ )
+
+
+class _Driver:
+ """Fake desktop driver: records every tool call the Controller admits."""
+
+ def __init__(self) -> None:
+ self.calls: list[tuple[str, dict[str, Any]]] = []
+ self.image: bytes | None = None
+ self.delay = 0.0
+
+ async def call_tool(self, name: str, arguments: dict, *, handle_descriptor=None) -> dict:
+ del handle_descriptor
+ self.calls.append((name, arguments))
+ await asyncio.sleep(self.delay)
+ payload = {"apps": [{"pid": 41, "bundle_id": "com.apple.mail", "name": "Mail"}]}
+ content = []
+ if self.image is not None:
+ encoded = base64.b64encode(self.image).decode("ascii")
+ content.append({"type": "image", "data": encoded, "mimeType": "image/png"})
+ return {"isError": False, "structuredContent": payload, "content": content}
+
+
+class _Harness:
+ def __init__(self, controller: SimpleNamespace, client: httpx.AsyncClient) -> None:
+ self.controller = controller
+ self.client = client
+ self.driver: _Driver = controller.computer_use_server
+ self.kernels: ComputerJsKernelManager = controller.computer_js_kernels
+ self.status = "ready"
+ self._turns: list[asyncio.Task[Any]] = []
+ self.start_turn("turn-1")
+
+ def start_turn(self, turn_id: str) -> asyncio.Task[Any]:
+ task = asyncio.create_task(asyncio.sleep(3600))
+ self._turns.append(task)
+ self.controller.session_turns.in_flight[SESSION] = session_turns.Turn(
+ task=task,
+ context=_context(turn_id),
+ logical_turn_id=turn_id,
+ )
+ return task
+
+ async def js(self, code: str, timeout_ms: int = 5000) -> dict[str, Any]:
+ response = await self.client.post(
+ "/internal/computer-js/eval",
+ json={"caller_session_id": SESSION, "code": code, "timeout_ms": timeout_ms},
+ )
+ return response.json()
+
+ async def reset(self) -> dict[str, Any]:
+ response = await self.client.post(
+ "/internal/computer-js/reset",
+ json={"caller_session_id": SESSION},
+ )
+ return response.json()
+
+ def kernel_process(self) -> Any:
+ return self.kernels._slots[SESSION].kernel.process
+
+ async def close(self) -> None:
+ self.kernels.close_all()
+ self.controller.computer_script_sessions.close_all()
+ for task in self._turns:
+ task.cancel()
+ await asyncio.gather(*self._turns, return_exceptions=True)
+ await asyncio.sleep(0.05)
+
+
+@asynccontextmanager
+async def _harness(**manager_options: Any) -> AsyncIterator[_Harness]:
+ import uvicorn
+
+ socket_directory = Path(tempfile.mkdtemp(prefix="avibe-js-", dir="/tmp"))
+ socket_path = socket_directory / "c.sock"
+ controller = SimpleNamespace(
+ computer_use_server=_Driver(),
+ controller_id="controller-test",
+ _session_id_from_context=lambda context: context.platform_specific["agent_session_id"],
+ )
+ holder: dict[str, _Harness] = {}
+ controller.session_turns = session_turns.SessionTurnManager(controller)
+ controller.computer_script_sessions = ComputerScriptSessionManager(controller.session_turns)
+ controller.computer_js_kernels = ComputerJsKernelManager(
+ controller.computer_script_sessions,
+ endpoint_resolver=lambda: {"transport": "unix", "socket_path": str(socket_path)},
+ node_resolver=lambda: Path(NODE),
+ status_reader=lambda: SimpleNamespace(status=holder["h"].status, reason=None),
+ **manager_options,
+ )
+ # create_app reuses these owners and wires the Turn-end listener.
+ app = internal_server.create_app(controller)
+ server = uvicorn.Server(uvicorn.Config(app, uds=str(socket_path), log_level="warning", lifespan="off"))
+ serving = asyncio.create_task(server.serve())
+ while not server.started:
+ await asyncio.sleep(0.01)
+ transport = httpx.AsyncHTTPTransport(uds=str(socket_path))
+ async with httpx.AsyncClient(transport=transport, base_url="http://controller", timeout=30) as client:
+ harness = _Harness(controller, client)
+ holder["h"] = harness
+ try:
+ yield harness
+ finally:
+ await harness.close()
+ server.should_exit = True
+ await serving
+ shutil.rmtree(socket_directory, ignore_errors=True)
+
+
+def _run(scenario) -> Any:
+ async def main() -> Any:
+ async with _harness(**getattr(scenario, "options", {})) as harness:
+ return await scenario(harness)
+
+ return asyncio.run(main())
+
+
+def test_bindings_persist_across_calls_and_report_console_and_freshness() -> None:
+ async def scenario(h: _Harness) -> list[dict]:
+ return [
+ await h.js("const base = await Promise.resolve(40); function add(n) { return base + n }"),
+ await h.js("console.log('adding', 2); add(2)"),
+ await h.js("let base2 = add(3); ({ base, base2, sum: base + base2 })"),
+ await h.js("(await computer.app({ bundleId: 'com.apple.mail' })) !== undefined"),
+ ]
+
+ first, second, third, fourth = _run(scenario)
+ assert first["ok"] is True and first["kernel_fresh"] is True
+ assert second == {
+ "ok": True,
+ "result": 42,
+ "console": "adding 2\n",
+ "screenshots": [],
+ "kernel_fresh": False,
+ }
+ assert third["result"] == {"base": 40, "base2": 43, "sum": 83}
+ assert fourth["ok"] is True and fourth["result"] is True
+
+
+def test_sdk_requests_carry_the_exact_turn_binding_and_report_screenshots() -> None:
+ async def scenario(h: _Harness) -> tuple[dict, list[tuple[str, dict]], bytes]:
+ h.driver.image = b"png-fixture"
+ report = await h.js("await computer.app({ bundleId: 'com.apple.mail' }); null")
+ return report, h.driver.calls, Path(report["screenshots"][0]).read_bytes()
+
+ report, calls, image = _run(scenario)
+ assert calls == [("list_apps", {"session": SESSION})]
+ assert len(report["screenshots"]) == 1 and image == b"png-fixture"
+
+
+def test_js_reset_discards_bindings_and_the_next_call_is_fresh() -> None:
+ async def scenario(h: _Harness) -> tuple[dict, dict, dict]:
+ await h.js("const kept = 1")
+ reset = await h.reset()
+ after = await h.js("typeof kept")
+ again = await h.reset()
+ return reset, after, again
+
+ reset, after, again = _run(scenario)
+ assert reset == {"ok": True, "discarded": True}
+ assert after["result"] == "undefined" and after["kernel_fresh"] is True
+ assert again == {"ok": True, "discarded": True}
+
+
+def test_timeout_cancels_the_call_and_keeps_the_kernel() -> None:
+ async def scenario(h: _Harness) -> tuple[dict, dict]:
+ await h.js("let survivor = 'kept'")
+ stuck = await h.js("await new Promise(() => {})", timeout_ms=200)
+ after = await h.js("survivor")
+ return stuck, after
+
+ stuck, after = _run(scenario)
+ assert stuck["ok"] is False
+ assert stuck["error"]["code"] == "js_timeout"
+ assert stuck["error"]["ambiguous"] is True
+ assert stuck["kernel_fresh"] is False
+ assert after == {**after, "ok": True, "result": "kept", "kernel_fresh": False}
+
+
+def test_sync_loop_kills_the_kernel_and_reports_the_reset() -> None:
+ async def scenario(h: _Harness) -> tuple[dict, dict, int | None]:
+ await h.js("let lost = 1")
+ process = h.kernel_process()
+ looping = await h.js("while (true) {}", timeout_ms=200)
+ await asyncio.wait_for(process.wait(), 5)
+ after = await h.js("typeof lost")
+ return looping, after, process.returncode
+
+ scenario.options = {"kill_grace_seconds": 0.3}
+ looping, after, returncode = _run(scenario)
+ assert looping["ok"] is False
+ assert looping["error"]["code"] == "js_kernel_reset"
+ assert "all bindings were discarded" in looping["error"]["message"]
+ assert returncode is not None
+ assert after["kernel_fresh"] is True and after["result"] == "undefined"
+
+
+def test_idle_kernel_is_reaped_and_the_next_call_is_fresh() -> None:
+ async def scenario(h: _Harness) -> tuple[int | None, dict]:
+ await h.js("let idle = 1")
+ process = h.kernel_process()
+ await asyncio.wait_for(process.wait(), 5)
+ return process.returncode, await h.js("typeof idle")
+
+ scenario.options = {"idle_seconds": 0.2}
+ returncode, after = _run(scenario)
+ assert returncode is not None
+ assert after["kernel_fresh"] is True and after["result"] == "undefined"
+
+
+def test_computer_use_off_kills_the_kernel_and_refuses_calls() -> None:
+ async def scenario(h: _Harness) -> tuple[int | None, dict]:
+ await h.js("1")
+ process = h.kernel_process()
+ h.status = "off"
+ await asyncio.wait_for(process.wait(), 5)
+ refused = await h.js("1")
+ return process.returncode, refused
+
+ scenario.options = {"status_poll_seconds": 0.05}
+ returncode, refused = _run(scenario)
+ assert returncode is not None
+ assert refused["error"]["code"] == "computer_use_unavailable"
+
+
+def test_leftover_timer_of_an_ended_call_never_fires() -> None:
+ async def scenario(h: _Harness) -> tuple[dict, list]:
+ await h.js(
+ "globalThis.fired = false; setTimeout(() => { fired = true;"
+ " computer.app({ bundleId: 'com.apple.mail' }) }, 100); null"
+ )
+ # The timer is due while this later call is executing.
+ later = await h.js("await new Promise((r) => setTimeout(r, 300)); fired")
+ return later, h.driver.calls
+
+ later, calls = _run(scenario)
+ assert later["result"] is False
+ assert calls == []
+
+
+def test_cancelled_continuation_cannot_overwrite_a_later_binding() -> None:
+ async def scenario(h: _Harness) -> tuple[dict, dict]:
+ cancelled = await h.js(
+ "var x = 0; await new Promise((r) => setTimeout(r, 300)); x = 1",
+ timeout_ms=100,
+ )
+ await h.js("x = 2")
+ await asyncio.sleep(0.5)
+ return cancelled, await h.js("x")
+
+ cancelled, after = _run(scenario)
+ assert cancelled["error"]["code"] == "js_timeout"
+ assert after["result"] == 2 and after["kernel_fresh"] is False
+
+
+def test_sdk_request_of_a_cancelled_call_never_settles() -> None:
+ async def scenario(h: _Harness) -> tuple[dict, dict]:
+ h.driver.delay = 0.4
+ cancelled = await h.js(
+ "globalThis.outcome = 'pending'; await computer.app({ bundleId: 'com.apple.mail' })"
+ ".then(() => { outcome = 'resolved' }, (error) => { outcome = error.code })",
+ timeout_ms=150,
+ )
+ await asyncio.sleep(0.8)
+ return cancelled, await h.js("outcome")
+
+ cancelled, after = _run(scenario)
+ assert cancelled["error"]["code"] == "js_timeout"
+ assert after["result"] == "pending"
+
+
+def test_a_continuation_resumed_by_a_later_call_cannot_reach_the_controller() -> None:
+ """Known-by-design residual: the model can wake a cancelled continuation
+ itself, which may change bindings but never reaches the Controller."""
+
+ async def scenario(h: _Harness) -> tuple[dict, list]:
+ await h.js(
+ "globalThis.after = 'waiting'; await new Promise((r) => { globalThis.release = r });"
+ " after = 'resumed'; await computer.app({ bundleId: 'com.apple.mail' })",
+ timeout_ms=150,
+ )
+ later = await h.js("release(); await new Promise((r) => setTimeout(r, 200)); after")
+ return later, h.driver.calls
+
+ later, calls = _run(scenario)
+ assert later["result"] == "resumed"
+ assert calls == []
+
+
+def test_turn_end_cancels_the_call_and_keeps_bindings() -> None:
+ async def scenario(h: _Harness) -> tuple[dict, dict, dict]:
+ turn = h.controller.session_turns.in_flight[SESSION]
+ pending = asyncio.create_task(
+ h.js("var survivor = 'kept'; await new Promise(() => {})", timeout_ms=10000)
+ )
+ await asyncio.sleep(0.5)
+ turn.task.cancel()
+ ended = await asyncio.wait_for(pending, 5)
+ refused = await h.js("1")
+ h.start_turn("turn-2")
+ after = await h.js("survivor")
+ return ended, refused, after
+
+ ended, refused, after = _run(scenario)
+ assert ended["error"]["code"] == "script_turn_ended"
+ assert refused["error"]["code"] == "active_turn_required"
+ assert after["result"] == "kept" and after["kernel_fresh"] is False
+
+
+def test_a_queued_call_stays_bound_to_its_turn() -> None:
+ async def scenario(h: _Harness) -> tuple[dict, dict, dict, list]:
+ await h.js("1")
+ turn_a = h.controller.session_turns.in_flight[SESSION]
+ running = asyncio.create_task(h.js("await new Promise((r) => setTimeout(r, 500))"))
+ await asyncio.sleep(0.2)
+ queued = asyncio.create_task(
+ h.js("globalThis.executed = true; await computer.app({ bundleId: 'com.apple.mail' })")
+ )
+ await asyncio.sleep(0.1)
+ # Turn B is live before the queued Turn-A call can take the lock.
+ turn_a.task.cancel()
+ h.start_turn("turn-b")
+ first, second = await asyncio.wait_for(asyncio.gather(running, queued), 5)
+ after = await h.js("typeof executed")
+ return first, second, after, h.driver.calls
+
+ first, second, after, calls = _run(scenario)
+ assert first["error"]["code"] == "script_turn_ended"
+ assert second["error"]["code"] == "script_turn_ended"
+ assert after["result"] == "undefined" and after["kernel_fresh"] is False
+ assert calls == []
+
+
+def test_computer_use_off_cancels_an_executing_call() -> None:
+ async def scenario(h: _Harness) -> tuple[dict, int | None]:
+ await h.js("1")
+ process = h.kernel_process()
+ running = asyncio.create_task(h.js("await new Promise(() => {})", timeout_ms=10000))
+ await asyncio.sleep(0.2)
+ h.status = "off"
+ report = await asyncio.wait_for(running, 5)
+ await asyncio.wait_for(process.wait(), 5)
+ return report, process.returncode
+
+ scenario.options = {"status_poll_seconds": 0.05}
+ report, returncode = _run(scenario)
+ assert report["error"]["code"] == "js_kernel_reset"
+ assert report["error"]["params"] == {"reason": "computer_use_off"}
+ assert returncode is not None
+
+
+async def _reset_event(h: _Harness) -> None:
+ await h.reset()
+
+
+async def _archive_event(h: _Harness) -> None:
+ h.kernels.discard_session(SESSION)
+
+
+async def _off_event(h: _Harness) -> None:
+ h.status = "off"
+
+
+async def _shutdown_event(h: _Harness) -> None:
+ h.kernels.close_all()
+
+
+ ("event", "reason"),
+ [
+ (_reset_event, "reset"),
+ (_archive_event, "session_archived"),
+ (_off_event, "computer_use_off"),
+ (_shutdown_event, "shutdown"),
+ ],
+)
+def test_invalidation_cancels_every_admitted_call(event, reason: str) -> None:
+ """Invariant: calls admitted before an invalidation never execute."""
+
+ async def scenario(h: _Harness) -> tuple[list[dict], list, Any]:
+ await h.js("1")
+ executing = asyncio.create_task(h.js("await new Promise(() => {})", timeout_ms=10000))
+ await asyncio.sleep(0.2)
+ queued = [
+ asyncio.create_task(
+ h.js("globalThis.executed = true; await computer.app({ bundleId: 'com.apple.mail' })")
+ )
+ for _ in range(3)
+ ]
+ await asyncio.sleep(0.1)
+ await event(h)
+ reports = await asyncio.wait_for(asyncio.gather(executing, *queued), 5)
+ await asyncio.sleep(0.2)
+ return reports, h.driver.calls, h.kernels._slots.get(SESSION)
+
+ scenario.options = {"status_poll_seconds": 0.05}
+ reports, calls, slot = _run(scenario)
+ for report in reports:
+ assert report["error"]["code"] == "js_kernel_reset"
+ assert report["error"]["params"] == {"reason": reason}
+ assert calls == []
+ assert slot is None
+
+
+def test_a_queued_call_keeps_its_full_budget_after_taking_the_lock() -> None:
+ async def scenario(h: _Harness) -> dict:
+ await h.js("1")
+ first = asyncio.create_task(h.js("await new Promise((r) => setTimeout(r, 600))"))
+ await asyncio.sleep(0.1)
+ second = await h.js(
+ "await new Promise((r) => setTimeout(r, 300)); 'finished'",
+ timeout_ms=400,
+ )
+ await first
+ return second
+
+ assert _run(scenario)["result"] == "finished"
+
+
+def test_the_session_queue_is_capped() -> None:
+ async def scenario(h: _Harness) -> dict:
+ await h.js("1")
+ executing = asyncio.create_task(h.js("await new Promise((r) => setTimeout(r, 400))"))
+ await asyncio.sleep(0.1)
+ queued = asyncio.create_task(h.js("1"))
+ await asyncio.sleep(0.05)
+ refused = await h.js("1")
+ await asyncio.gather(executing, queued)
+ return refused
+
+ scenario.options = {"queue_limit": 1}
+ assert _run(scenario)["error"]["code"] == "js_kernel_busy"
+
+
+def test_non_posix_platform_is_refused_before_any_process_starts(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from core import computer_js_kernels
+
+ async def no_process(*_args, **_kwargs):
+ raise AssertionError("a kernel process was started")
+
+ monkeypatch.setattr(computer_js_kernels, "_kernel_platform_supported", lambda: False)
+ monkeypatch.setattr(computer_js_kernels.asyncio, "create_subprocess_exec", no_process)
+
+ async def scenario(h: _Harness) -> dict:
+ return await h.js("1")
+
+ report = _run(scenario)
+ assert report["error"]["code"] == "platform_unsupported"
+ assert report["kernel_fresh"] is False
+
+
+def test_the_cli_never_stops_waiting_before_the_controller_lease_ends() -> None:
+ from core.computer_cli import COMPUTER_JS_CONNECTION_LEASE_SECONDS
+ from core.computer_js_kernels import (
+ KILL_GRACE_SECONDS,
+ MAX_TIMEOUT_MS,
+ QUEUE_LIMIT,
+ SPAWN_TIMEOUT_SECONDS,
+ )
+ from vibe.internal_client import computer_js_client_timeout_seconds
+
+ assert computer_js_client_timeout_seconds() >= COMPUTER_JS_CONNECTION_LEASE_SECONDS
+ # Every queued predecessor plus the call itself settles inside the lease.
+ per_call = MAX_TIMEOUT_MS / 1000 + KILL_GRACE_SECONDS + SPAWN_TIMEOUT_SECONDS
+ assert (QUEUE_LIMIT + 1) * per_call <= COMPUTER_JS_CONNECTION_LEASE_SECONDS
+
+
+def test_concurrent_calls_in_one_session_are_serialized() -> None:
+ async def scenario(h: _Harness) -> Any:
+ await h.js("globalThis.order = []")
+ first = asyncio.create_task(
+ h.js("order.push('a1'); await new Promise((r) => setTimeout(r, 200)); order.push('a2')")
+ )
+ await asyncio.sleep(0.05)
+ second = asyncio.create_task(h.js("order.push('b')"))
+ await asyncio.gather(first, second)
+ return (await h.js("order"))["result"]
+
+ assert _run(scenario) == ["a1", "a2", "b"]
+
+
+def test_exceptions_and_unserializable_results_are_reported() -> None:
+ async def scenario(h: _Harness) -> tuple[dict, dict]:
+ thrown = await h.js("null.boom")
+ cyclic = await h.js("const loop = {}; loop.self = loop; loop")
+ return thrown, cyclic
+
+ thrown, cyclic = _run(scenario)
+ assert thrown["error"]["code"] == "js_exception"
+ assert thrown["error"]["name"] == "TypeError"
+ assert "stack" in thrown["error"]["params"]
+ assert cyclic["ok"] is True and cyclic["result"] is None
+ assert "Circular" in cyclic["result_text"]
+
+
+ ("language", "expected"),
+ [
+ ("en", "The JavaScript call failed: The JavaScript kernel was reset"),
+ ("zh", "JavaScript 调用失败:JavaScript 内核已重置"),
+ ],
+)
+def test_cli_envelope_and_localized_errors(
+ monkeypatch: pytest.MonkeyPatch,
+ capsys,
+ tmp_path: Path,
+ language: str,
+ expected: str,
+) -> None:
+ from vibe import cli
+
+ monkeypatch.setenv("AVIBE_SESSION_ID", "ses-cli")
+ monkeypatch.setattr(cli, "_configured_cli_language", lambda: language)
+ seen: list[dict] = []
+ code_file = tmp_path / "step.js"
+ code_file.write_text("1 + 1", encoding="utf-8")
+
+ def succeed(**kwargs):
+ seen.append(kwargs)
+ return {
+ "status_code": 200,
+ "body": {"ok": True, "result": 2, "console": "", "screenshots": [], "kernel_fresh": True},
+ }
+
+ monkeypatch.setattr("vibe.internal_client.computer_js_eval_sync", succeed)
+ args = cli.build_parser().parse_args(["computer", "js", "--code", f"@{code_file}"])
+ assert cli.cmd_computer(args) == 0
+ assert seen == [{"caller_session_id": "ses-cli", "code": "1 + 1", "timeout_ms": 30000}]
+ assert json.loads(capsys.readouterr().out) == {
+ "schema_version": 1,
+ "ok": True,
+ "kind": "computer_js",
+ "result": 2,
+ "console": "",
+ "screenshots": [],
+ "kernel_fresh": True,
+ }
+
+ error = {
+ "name": "KernelReset",
+ "code": "js_kernel_reset",
+ "message": "raw",
+ "params": {"reason": "unsettled"},
+ "step": "script",
+ "last_completed_step": None,
+ "screenshot_path": None,
+ "ambiguous": True,
+ }
+ monkeypatch.setattr(
+ "vibe.internal_client.computer_js_eval_sync",
+ lambda **_kwargs: {
+ "status_code": 200,
+ "body": {"ok": False, "error": error, "console": "", "screenshots": [], "kernel_fresh": False},
+ },
+ )
+ args = cli.build_parser().parse_args(["computer", "js", "--code", "while (true) {}"])
+ with pytest.raises(cli.TaskCliError) as exc_info:
+ cli.cmd_computer(args)
+ assert str(exc_info.value).startswith(expected)
+ assert exc_info.value.code == "js_kernel_reset"
+ assert exc_info.value.details["error"] == error
+
+ with pytest.raises(cli.TaskCliError) as exc_info:
+ cli.cmd_computer(
+ cli.build_parser().parse_args(["computer", "js", "--code", "1", "--timeout-ms", "300001"])
+ )
+ assert exc_info.value.code == "invalid_timeout"
diff --git a/tests/test_distribution_artifacts.py b/tests/test_distribution_artifacts.py
index 5096cae6e..001c3c268 100644
--- a/tests/test_distribution_artifacts.py
+++ b/tests/test_distribution_artifacts.py
@@ -64,6 +64,7 @@ def _assert_members_and_metadata(members, metadata):
"vibe/ui/dist/index.html",
"vibe/computer_sdk/index.mjs",
"vibe/computer_sdk/index.d.ts",
+ "vibe/computer_sdk/kernel.mjs",
"vibe/computer_sdk/failure-envelope.json",
"vibe/computer_sdk/loader.mjs",
"vibe/computer_sdk/package.json",
diff --git a/vibe/cli.py b/vibe/cli.py
index ab728e6bc..07ea7c6e3 100644
--- a/vibe/cli.py
+++ b/vibe/cli.py
@@ -724,6 +724,85 @@ def cmd_skill(args) -> int:
return 1
+def _cmd_computer_js(args, caller_session_id: str, translate) -> int:
+ """Evaluate in, or reset, the caller Session's persistent JavaScript kernel."""
+
+ from core.computer_cli import translate_computer_error
+ from vibe.internal_client import (
+ InternalServerTimeout,
+ InternalServerUnavailable,
+ computer_js_eval_sync,
+ computer_js_reset_sync,
+ )
+
+ help_command = f"vibe computer {args.computer_command} --help"
+ try:
+ if args.computer_command == "js-reset":
+ response = computer_js_reset_sync(caller_session_id=caller_session_id)
+ else:
+ code = args.code
+ if code.startswith("@"):
+ source = Path(code[1:]).expanduser()
+ try:
+ code = source.read_text(encoding="utf-8")
+ except (OSError, UnicodeError) as exc:
+ raise TaskCliError(
+ translate("computer.cli.error.jsCodeFile", path=str(source), error=str(exc)),
+ code="computer_js_code_unreadable",
+ help_command=help_command,
+ ) from exc
+ if not 1 <= args.timeout_ms <= 300000:
+ raise TaskCliError(
+ translate("computer.cli.error.jsTimeoutRange"),
+ code="invalid_timeout",
+ help_command=help_command,
+ )
+ response = computer_js_eval_sync(
+ caller_session_id=caller_session_id,
+ code=code,
+ timeout_ms=args.timeout_ms,
+ )
+ except InternalServerUnavailable as exc:
+ raise TaskCliError(
+ translate("computer.cli.error.serviceUnavailable", error=str(exc)),
+ code="controller_unavailable",
+ hint=translate("computer.cli.hint.serviceUnavailable"),
+ ) from exc
+ except InternalServerTimeout as exc:
+ raise TaskCliError(
+ translate("computer.cli.error.requestTimedOut", error=str(exc)),
+ code="computer_use_timeout",
+ hint=translate("computer.cli.hint.requestTimedOut"),
+ ) from exc
+
+ body = response.get("body")
+ if not isinstance(body, dict) or not isinstance(body.get("ok"), bool):
+ raise TaskCliError(
+ translate("computer.cli.error.invalidResponse"),
+ code="invalid_computer_use_response",
+ )
+ report = {key: value for key, value in body.items() if key not in {"ok", "error"}}
+ if body["ok"]:
+ kind = "computer_js_reset" if args.computer_command == "js-reset" else "computer_js"
+ print(json.dumps(_cli_payload(kind, **report), ensure_ascii=False, indent=2))
+ return 0
+ error = body.get("error")
+ if not isinstance(error, dict):
+ error = {"code": "invalid_computer_use_response", "params": {}}
+ code = str(error.get("code") or "computer_use_error")
+ message = translate_computer_error(
+ error,
+ translate=translate,
+ fallback=f"{error.get('name') or 'Error'}: {error.get('message') or code}",
+ )
+ raise TaskCliError(
+ translate("computer.cli.error.jsFailed", error=message),
+ code=code,
+ details={"error": error, **report},
+ help_command=help_command,
+ )
+
+
def cmd_computer(args) -> int:
"""Run one Controller-owned Computer Use operation for the active Turn."""
@@ -784,6 +863,8 @@ def cmd_computer(args) -> int:
) from exc
print(json.dumps(result, ensure_ascii=False, sort_keys=True))
return 0
+ if args.computer_command in {"js", "js-reset"}:
+ return _cmd_computer_js(args, caller_session_id, translate)
if args.computer_command == "observe":
command_path = ("observe", args.computer_observe_command)
elif args.computer_command == "clipboard":
@@ -17535,7 +17616,7 @@ def build_parser():
)
computer_subparsers = computer_parser.add_subparsers(
dest="computer_command",
- metavar="{run,observe,zoom,click,type,key,hotkey,scroll,drag,set-value,clipboard,launch,force-quit}",
+ metavar="{run,js,js-reset,observe,zoom,click,type,key,hotkey,scroll,drag,set-value,clipboard,launch,force-quit}",
)
computer_subparsers.required = True
@@ -17562,6 +17643,34 @@ def build_parser():
help=i18n_t("computer.cli.help.scriptArg", computer_help_language),
)
+ computer_js_parser = computer_subparsers.add_parser(
+ "js",
+ help=i18n_t("computer.cli.help.js", computer_help_language),
+ description=i18n_t("computer.cli.help.jsDescription", computer_help_language),
+ error_help_command="vibe computer js --help",
+ error_hint=i18n_t("computer.cli.hint.invalidArguments", computer_help_language),
+ error_i18n_key="computer.cli.error.invalidArguments",
+ )
+ computer_js_parser.add_argument(
+ "--code",
+ required=True,
+ help=i18n_t("computer.cli.help.jsCode", computer_help_language),
+ )
+ computer_js_parser.add_argument(
+ "--timeout-ms",
+ type=int,
+ default=30000,
+ help=i18n_t("computer.cli.help.jsTimeout", computer_help_language),
+ )
+ computer_subparsers.add_parser(
+ "js-reset",
+ help=i18n_t("computer.cli.help.jsReset", computer_help_language),
+ description=i18n_t("computer.cli.help.jsReset", computer_help_language),
+ error_help_command="vibe computer js-reset --help",
+ error_hint=i18n_t("computer.cli.hint.invalidArguments", computer_help_language),
+ error_i18n_key="computer.cli.error.invalidArguments",
+ )
+
def _add_computer_options(command_parser) -> None:
command_parser.add_argument(
"--args-json",
@@ -19564,6 +19673,8 @@ _CLI_COMMAND_FLOORS: dict[tuple[str, ...], Optional[str]] = {
("computer", "observe", "windows"): "member",
("computer", "observe", "window"): "member",
("computer", "run"): "member",
+ ("computer", "js"): "member",
+ ("computer", "js-reset"): "member",
("computer", "zoom"): "member",
("computer", "click"): "member",
("computer", "type"): "member",
diff --git a/vibe/computer_script_runner.py b/vibe/computer_script_runner.py
index 580e9e749..65cb76fd1 100644
--- a/vibe/computer_script_runner.py
+++ b/vibe/computer_script_runner.py
@@ -344,7 +344,10 @@ def _retain_only_screenshot(
shutil.rmtree(candidate, ignore_errors=True)
-def _prune_retained_artifact_runs(parent: Path) -> None:
+def _prune_retained_artifact_runs(
+ parent: Path,
+ prefix: str = _ARTIFACT_DIRECTORY_PREFIX,
+) -> None:
candidates: list[tuple[float, Path]] = []
try:
entries = list(parent.iterdir())
@@ -352,7 +355,7 @@ def _prune_retained_artifact_runs(parent: Path) -> None:
return
for candidate in entries:
if (
- not candidate.name.startswith(_ARTIFACT_DIRECTORY_PREFIX)
+ not candidate.name.startswith(prefix)
or candidate.name.startswith(_SUPERVISOR_DIRECTORY_PREFIX)
or not candidate.is_dir()
or candidate.is_symlink()
diff --git a/vibe/computer_sdk/kernel.mjs b/vibe/computer_sdk/kernel.mjs
new file mode 100644
index 000000000..78202df02
--- /dev/null
+++ b/vibe/computer_sdk/kernel.mjs
@@ -0,0 +1,296 @@
+// Persistent JavaScript kernel for ``vibe computer js``.
+//
+// The Controller owns this process: it starts it lazily for one Avibe Session,
+// talks to it over the inherited socket named by AVIBE_COMPUTER_KERNEL_FD
+// (stdio is /dev/null), and kills it on timeout, idle, reset, archive, or
+// shutdown. Every desktop effect still goes through the Controller's
+// /internal/computer-script routes with the exact-Turn token of the call that
+// is executing; outside an executing call there is no token to use.
+//
+// Evaluation uses V8's REPL mode through the in-process inspector, the same
+// semantics as the DevTools console: top-level await, and top-level `let`,
+// `const`, `class`, and `function` bindings that persist across calls and may
+// be redeclared. It needs no parser, no extra dependency, and no experimental
+// Node flag; a module-based design would lose non-exported bindings.
+
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import inspector from "node:inspector";
+import net from "node:net";
+import path from "node:path";
+import { inspect } from "node:util";
+import * as runtime from "./runtime.mjs";
+import { avibe, computer } from "./index.mjs";
+
+const CONSOLE_TAIL_MAX_BYTES = 16 * 1024;
+const RESULT_TEXT_MAX_CHARS = 16 * 1024;
+const STACK_MAX_CHARS = 4 * 1024;
+const RETAINED_CALL_DIRECTORIES = 10;
+
+const channel = new net.Socket({
+ fd: Number(process.env.AVIBE_COMPUTER_KERNEL_FD),
+ readable: true,
+ writable: true,
+});
+const session = new inspector.Session();
+const captureKey = `__avibeKernelCapture_${randomUUID().replaceAll("-", "")}`;
+let captured;
+let artifactRoot;
+let callSequence = 0;
+let current;
+
+Object.defineProperty(globalThis, captureKey, {
+ value: (value) => {
+ captured = value;
+ },
+ enumerable: false,
+ configurable: false,
+ writable: false,
+});
+Object.defineProperty(globalThis, "computer", { value: computer, enumerable: true });
+Object.defineProperty(globalThis, "avibe", { value: avibe, enumerable: true });
+
+// Timers belong to the call that scheduled them. Once that call ends (it
+// completed, timed out, or its Turn ended) its callbacks are dropped, so a
+// cancelled continuation waiting on a timer never resumes to touch bindings.
+function owned(callback, onDropped) {
+ const owner = runtime.kernelCalls.getStore();
+ if (typeof callback !== "function" || owner === undefined) {
+ return callback;
+ }
+ return function ownedCallback(...args) {
+ if (owner.active === true) {
+ return Reflect.apply(callback, this, args);
+ }
+ onDropped?.();
+ return undefined;
+ };
+}
+for (const name of ["setTimeout", "setImmediate", "queueMicrotask"]) {
+ const original = globalThis[name];
+ globalThis[name] = function (callback, ...rest) {
+ return Reflect.apply(original, this, [owned(callback), ...rest]);
+ };
+}
+const originalSetInterval = globalThis.setInterval;
+globalThis.setInterval = function (callback, ...rest) {
+ let handle;
+ handle = Reflect.apply(originalSetInterval, this, [
+ owned(callback, () => clearInterval(handle)),
+ ...rest,
+ ]);
+ return handle;
+};
+
+function send(message) {
+ let line;
+ try {
+ line = JSON.stringify(message);
+ } catch {
+ line = undefined;
+ }
+ if (line === undefined || Buffer.byteLength(line) > runtime.PROTOCOL_FILE_MAX_BYTES) {
+ const error = new Error("The call result exceeded the protocol size limit.");
+ error.name = "ControllerError";
+ error.code = "computer_script_protocol_error";
+ error.params = { limit_bytes: runtime.PROTOCOL_FILE_MAX_BYTES };
+ line = JSON.stringify({
+ type: "result",
+ id: message.id,
+ ok: false,
+ error: runtime.failureEnvelope(error),
+ console: message.console ?? "",
+ screenshots: message.screenshots ?? [],
+ });
+ }
+ channel.write(`${line}\n`);
+}
+
+function post(method, params) {
+ return new Promise((resolve, reject) => {
+ session.post(method, params, (error, result) =>
+ error ? reject(error) : resolve(result),
+ );
+ });
+}
+
+async function materialize(remote) {
+ if (!remote || remote.type === "undefined") {
+ return undefined;
+ }
+ if (remote.objectId) {
+ captured = undefined;
+ await post("Runtime.callFunctionOn", {
+ objectId: remote.objectId,
+ functionDeclaration: `function () { globalThis[${JSON.stringify(captureKey)}](this); }`,
+ silent: true,
+ });
+ return captured;
+ }
+ const special = remote.unserializableValue;
+ if (typeof special === "string") {
+ return special.endsWith("n") ? BigInt(special.slice(0, -1)) : Number(special);
+ }
+ return remote.value;
+}
+
+function jsonResult(value) {
+ if (value === undefined) {
+ return { result: null };
+ }
+ try {
+ const encoded = JSON.stringify(value);
+ if (encoded !== undefined) {
+ return { result: JSON.parse(encoded) };
+ }
+ } catch {
+ // Cyclic or BigInt values are reported as inspected text below.
+ }
+ return {
+ result: null,
+ result_text: inspect(value, { depth: 4, breakLength: 120 }).slice(
+ 0,
+ RESULT_TEXT_MAX_CHARS,
+ ),
+ };
+}
+
+function newCall(message) {
+ callSequence += 1;
+ const artifactDirectory = path.join(artifactRoot, `call-${callSequence}`);
+ fs.mkdirSync(artifactDirectory, { recursive: true, mode: 0o700 });
+ pruneCallDirectories();
+ let consoleTail = Buffer.alloc(0);
+ return {
+ id: message.id,
+ active: true,
+ connectionToken: message.connection_token,
+ agent: new http.Agent({ keepAlive: true, maxSockets: 1, maxFreeSockets: 1 }),
+ artifactDirectory,
+ screenshots: [],
+ progress: runtime.newProgress(),
+ appendConsole(encoded) {
+ const combined = Buffer.concat([consoleTail, encoded]);
+ consoleTail = combined.subarray(
+ Math.max(0, combined.length - CONSOLE_TAIL_MAX_BYTES),
+ );
+ },
+ consoleText() {
+ return consoleTail.toString("utf8");
+ },
+ };
+}
+
+function pruneCallDirectories() {
+ const directories = fs
+ .readdirSync(artifactRoot)
+ .filter((name) => /^call-\d+$/.test(name))
+ .sort((a, b) => Number(a.slice(5)) - Number(b.slice(5)));
+ for (const name of directories.slice(0, -RETAINED_CALL_DIRECTORIES)) {
+ fs.rmSync(path.join(artifactRoot, name), { recursive: true, force: true });
+ }
+}
+
+function settle(call, outcome) {
+ if (current !== call || !call.active) {
+ return;
+ }
+ call.active = false;
+ current = undefined;
+ // In-flight requests of an ended call are dropped with its agent, so a
+ // later call never queues behind them.
+ call.agent.destroy();
+ send({
+ type: "result",
+ id: call.id,
+ ...outcome,
+ console: call.consoleText(),
+ screenshots: call.screenshots,
+ });
+}
+
+function failure(call, error, defaultCode) {
+ return runtime.kernelCalls.run(call, () => {
+ const envelope = runtime.failureEnvelope(error, { defaultCode });
+ // A plain exception from the agent's own code carries no Controller
+ // context, so its stack is the useful part.
+ if (envelope.code === "js_exception" && typeof error?.stack === "string") {
+ envelope.params = { ...envelope.params, stack: error.stack.slice(0, STACK_MAX_CHARS) };
+ }
+ return envelope;
+ });
+}
+
+async function evaluate(message) {
+ const call = newCall(message);
+ current = call;
+ const group = `call-${call.id}`;
+ try {
+ const response = await runtime.kernelCalls.run(call, () =>
+ post("Runtime.evaluate", {
+ expression: message.code,
+ replMode: true,
+ awaitPromise: true,
+ silent: true,
+ objectGroup: group,
+ }),
+ );
+ if (response.exceptionDetails) {
+ const thrown = await materialize(response.exceptionDetails.exception);
+ settle(call, { ok: false, error: failure(call, thrown, "js_exception") });
+ } else {
+ settle(call, { ok: true, ...jsonResult(await materialize(response.result)) });
+ }
+ } catch (error) {
+ settle(call, { ok: false, error: failure(call, error, "js_kernel_error") });
+ } finally {
+ post("Runtime.releaseObjectGroup", { objectGroup: group }).catch(() => {});
+ }
+}
+
+function cancel(message) {
+ const call = current;
+ if (!call || call.id !== message.id) {
+ return;
+ }
+ const error = new Error("The JavaScript call was cancelled.");
+ error.name = "Cancelled";
+ error.code = typeof message.code === "string" ? message.code : "js_timeout";
+ error.ambiguous = true;
+ settle(call, { ok: false, error: failure(call, error, error.code) });
+}
+
+function handle(message) {
+ if (message.type === "init") {
+ runtime.configureKernel({ endpoint: message.endpoint });
+ artifactRoot = message.artifact_directory;
+ session.connect();
+ send({ type: "ready" });
+ } else if (message.type === "eval" && current === undefined) {
+ void evaluate(message);
+ } else if (message.type === "cancel") {
+ cancel(message);
+ }
+}
+
+let buffered = "";
+channel.setEncoding("utf8");
+channel.on("data", (chunk) => {
+ buffered += chunk;
+ let newline = buffered.indexOf("\n");
+ while (newline >= 0) {
+ const line = buffered.slice(0, newline);
+ buffered = buffered.slice(newline + 1);
+ newline = buffered.indexOf("\n");
+ try {
+ handle(JSON.parse(line));
+ } catch {
+ process.exit(70);
+ }
+ }
+});
+// The Controller is the only owner; once its end of the socket closes, no
+// call can ever be admitted again.
+channel.on("end", () => process.exit(0));
+channel.on("error", () => process.exit(0));
diff --git a/vibe/computer_sdk/runtime.mjs b/vibe/computer_sdk/runtime.mjs
index a9cc91c0f..672a9a731 100644
--- a/vibe/computer_sdk/runtime.mjs
+++ b/vibe/computer_sdk/runtime.mjs
@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
import fs from "node:fs";
import http from "node:http";
import path from "node:path";
@@ -26,13 +27,44 @@ export const FAILURE_ENVELOPE_FIELDS = Object.freeze(
let state;
let agent;
-let currentStep = "script";
-let lastCompletedStep;
-let lastScreenshotPath;
-let lastOwnedScreenshotPath;
let screenshotSequence = 0;
let diagnosticTail = Buffer.alloc(0);
let consoleDiagnosticsInstalled = false;
+const scriptProgress = newProgress();
+
+// A persistent kernel (``vibe computer js``) runs many calls in one process.
+// Each call's store carries its exact-Turn connection token, its own HTTP
+// agent, and its own diagnostics. Timers and promises created during a call
+// inherit that store, so once the call ends (``active`` becomes false) they
+// can no longer reach the Controller.
+export const kernelCalls = new AsyncLocalStorage();
+
+export function newProgress() {
+ return {
+ step: "script",
+ lastCompletedStep: undefined,
+ screenshotPath: undefined,
+ ownedScreenshotPath: undefined,
+ };
+}
+
+function activeKernelCall() {
+ const call = kernelCalls.getStore();
+ return call && call.active === true ? call : undefined;
+}
+
+// A request owned by a call that has ended never settles: neither a result nor
+// an error can resume that call's code after the next call has started.
+export function frozenKernelCall(call = kernelCalls.getStore()) {
+ return state?.kernel === true && call !== undefined && call.active !== true;
+}
+
+function progress() {
+ if (!state?.kernel) {
+ return scriptProgress;
+ }
+ return kernelCalls.getStore()?.progress ?? newProgress();
+}
export class ControllerFault extends Error {
constructor(code, message, params = {}, options = {}) {
@@ -78,6 +110,15 @@ function controllerFault(
});
}
+export function configureKernel(config) {
+ if (state !== undefined) {
+ throw new Error("computer SDK runtime is already configured");
+ }
+ validateEndpoint(config?.endpoint);
+ state = { endpoint: config.endpoint, kernel: true };
+ installConsoleDiagnostics();
+}
+
export function configureRuntime(config) {
if (state !== undefined) {
throw new Error("computer SDK runtime is already configured");
@@ -141,11 +182,12 @@ export async function sleepWithinDeadline(milliseconds) {
}
export async function runStep(label, operation) {
- currentStep = label;
+ const current = progress();
+ current.step = label;
persistRuntimeState();
try {
const result = await operation();
- lastCompletedStep = label;
+ current.lastCompletedStep = label;
return result;
} catch (error) {
if (error && typeof error === "object" && !error.step) {
@@ -153,7 +195,7 @@ export async function runStep(label, operation) {
}
throw error;
} finally {
- currentStep = "script";
+ current.step = "script";
persistRuntimeState();
}
}
@@ -162,7 +204,6 @@ export async function callTool(tool, argumentsValue, options = {}) {
const body = await postJson(
"/internal/computer-script/request",
{
- connection_token: state.connectionToken,
tool,
arguments: argumentsValue,
descriptor: options.descriptor ?? null,
@@ -209,7 +250,6 @@ export async function callScriptInteraction(operation, message) {
let body;
try {
body = await postJson(`/internal/computer-script/${operation}`, {
- connection_token: state.connectionToken,
message,
});
} catch (error) {
@@ -274,7 +314,7 @@ function recordScreenshot(result) {
try {
screenshotSequence += 1;
const target = path.join(
- state.artifactDirectory,
+ activeKernelCall()?.artifactDirectory ?? state.artifactDirectory,
`observation-${screenshotSequence}.png`,
);
fs.writeFileSync(target, Buffer.from(image.data, "base64"), { mode: 0o600 });
@@ -286,11 +326,19 @@ function recordScreenshot(result) {
}
function replaceDiagnosticScreenshot(target, options = {}) {
- const previousOwned = lastOwnedScreenshotPath;
- lastScreenshotPath = target;
- lastOwnedScreenshotPath = options.owned === true ? target : undefined;
+ const current = progress();
+ const call = activeKernelCall();
+ current.screenshotPath = target;
+ if (call) {
+ // A kernel call reports every screenshot it produced; its directory is
+ // pruned by call, not by screenshot.
+ call.screenshots.push(target);
+ return;
+ }
+ const previousOwned = current.ownedScreenshotPath;
+ current.ownedScreenshotPath = options.owned === true ? target : undefined;
persistRuntimeState();
- if (previousOwned && previousOwned !== lastOwnedScreenshotPath) {
+ if (previousOwned && previousOwned !== current.ownedScreenshotPath) {
try {
fs.unlinkSync(previousOwned);
} catch {
@@ -300,8 +348,32 @@ function replaceDiagnosticScreenshot(target, options = {}) {
}
}
-async function postJson(requestPath, payload, requestOptions = {}) {
+function requestBinding() {
requireConfigured();
+ if (!state.kernel) {
+ return { connectionToken: state.connectionToken, agent };
+ }
+ const call = activeKernelCall();
+ if (!call) {
+ throw controllerFault(
+ "js_call_inactive",
+ "Computer Use requests are only allowed while a vibe computer js call is executing.",
+ {},
+ { controllerPayload: { dispatched: false } },
+ );
+ }
+ return call;
+}
+
+async function postJson(requestPath, requestPayload, requestOptions = {}) {
+ if (frozenKernelCall()) {
+ return new Promise(() => {});
+ }
+ const binding = requestBinding();
+ const payload = {
+ connection_token: binding.connectionToken,
+ ...requestPayload,
+ };
const localTimeout =
Number.isFinite(requestOptions.timeoutMs) && requestOptions.timeoutMs >= 0
? requestOptions.timeoutMs
@@ -324,7 +396,7 @@ async function postJson(requestPath, payload, requestOptions = {}) {
path: requestPath,
method: "POST",
headers,
- agent,
+ agent: binding.agent,
}
: {
hostname: endpoint.host,
@@ -332,7 +404,7 @@ async function postJson(requestPath, payload, requestOptions = {}) {
path: requestPath,
method: "POST",
headers,
- agent,
+ agent: binding.agent,
};
return new Promise((resolve, reject) => {
@@ -340,7 +412,7 @@ async function postJson(requestPath, payload, requestOptions = {}) {
let timer;
const requestState = { sent: false };
const settle = (callback, value) => {
- if (settled) {
+ if (settled || frozenKernelCall(binding)) {
return;
}
settled = true;
@@ -457,13 +529,7 @@ export async function closeScriptConnection() {
return;
}
try {
- await postJson(
- "/internal/computer-script/close",
- {
- connection_token: state.connectionToken,
- },
- { timeoutMs: 500 },
- );
+ await postJson("/internal/computer-script/close", {}, { timeoutMs: 500 });
} finally {
agent.destroy();
}
@@ -492,6 +558,11 @@ function installConsoleDiagnostics() {
function appendDiagnostic(args) {
const line = args.map(formatDiagnosticValue).join(" ");
const encoded = Buffer.from(`${line}\n`, "utf8");
+ if (state?.kernel) {
+ // Output from a finished call (or outside any call) belongs to no report.
+ activeKernelCall()?.appendConsole(encoded);
+ return;
+ }
if (encoded.length >= DIAGNOSTIC_TAIL_MAX_BYTES) {
diagnosticTail = Buffer.from(
encoded.subarray(encoded.length - DIAGNOSTIC_TAIL_MAX_BYTES),
@@ -576,9 +647,9 @@ function persistRuntimeState() {
writeCappedJsonFile(
state.runtimeStatePath,
{
- step: currentStep || "script",
- last_completed_step: lastCompletedStep ?? null,
- screenshot_path: lastScreenshotPath ?? null,
+ step: scriptProgress.step || "script",
+ last_completed_step: scriptProgress.lastCompletedStep ?? null,
+ screenshot_path: scriptProgress.screenshotPath ?? null,
diagnostics: diagnosticTail.toString("utf8"),
},
PROTOCOL_FILE_MAX_BYTES,
@@ -589,19 +660,20 @@ function persistRuntimeState() {
}
export function failureContext(error) {
+ const current = progress();
return {
step:
error && typeof error === "object" && typeof error.step === "string"
? error.step
- : currentStep || "script",
- last_completed_step: lastCompletedStep ?? null,
+ : current.step || "script",
+ last_completed_step: current.lastCompletedStep ?? null,
screenshot_path:
error &&
typeof error === "object" &&
(typeof error.screenshot_path === "string" ||
typeof error.screenshotPath === "string")
? error.screenshot_path || error.screenshotPath
- : lastScreenshotPath,
+ : current.screenshotPath,
};
}
@@ -646,7 +718,7 @@ export function failureEnvelope(error, options = {}) {
}
function requireConfigured() {
- if (!state || !agent) {
+ if (!state || (!state.kernel && !agent)) {
throw new Error("computer SDK runtime is not configured");
}
}
diff --git a/vibe/i18n/en.json b/vibe/i18n/en.json
index 96ed69f8c..6ac7b35c3 100644
--- a/vibe/i18n/en.json
+++ b/vibe/i18n/en.json
@@ -878,6 +878,11 @@
"runDescription": "Run an ESM file with the shipped @avibe/computer module, bound to this exact Avibe Agent Turn.",
"scriptFile": "Path to a readable .mjs script.",
"scriptArg": "Pass one script argument as name=value or name=@file. Values remain strings.",
+ "js": "Evaluate JavaScript in this Session's persistent Computer Use kernel",
+ "jsDescription": "Evaluate code in a Node kernel that keeps top-level bindings between calls in this Avibe Session. computer and avibe are preloaded; top-level await is supported. Each call is bound to the current Agent Turn.",
+ "jsCode": "JavaScript source, or @FILE to read it from a UTF-8 file.",
+ "jsTimeout": "Per-call timeout in milliseconds (default 30000, max 300000).",
+ "jsReset": "Discard this Session's JavaScript kernel and all of its bindings; open apps are untouched",
"observe": "Observe apps, windows, or one exact window",
"observeApps": "List visible applications",
"observeWindows": "List windows",
@@ -944,6 +949,17 @@
"scriptTargetNotFound": "The requested Computer Use target was not found.",
"scriptTurnEnded": "The Avibe Turn that launched this script has ended.",
"scriptWindowOrderUnavailable": "Window order is unavailable for this selector.",
+ "jsFailed": "The JavaScript call failed: {error}",
+ "jsCodeFile": "Cannot read JavaScript from {path}: {error}",
+ "jsTimeoutRange": "--timeout-ms must be between 1 and 300000.",
+ "jsCodeInvalid": "The JavaScript code must be non-empty text.",
+ "jsCodeTooLarge": "The JavaScript code exceeded the size limit.",
+ "jsTimeout": "The call exceeded its timeout and was cancelled. The kernel and its bindings were kept. Earlier actions may have happened; observe before retrying.",
+ "jsKernelReset": "The JavaScript kernel was reset; all bindings were discarded. Earlier actions may have happened; observe before retrying.",
+ "jsCallInactive": "Computer Use requests are only allowed while a vibe computer js call is executing.",
+ "jsKernelBusy": "Too many JavaScript calls are already waiting in this Session. Wait for them to finish, then retry.",
+ "jsKernelUnavailable": "The JavaScript kernel could not be started.",
+ "jsKernelError": "The JavaScript kernel failed while evaluating the call.",
"missingCallerSession": "Computer Use requires an Avibe Agent caller Session.",
"missingCallerTurn": "Computer Use requires the caller's Avibe Session to have an active Turn.",
"serviceUnavailable": "Avibe service is unavailable: {error}",
diff --git a/vibe/i18n/zh.json b/vibe/i18n/zh.json
index 0142e84bf..a3e03fd8d 100644
--- a/vibe/i18n/zh.json
+++ b/vibe/i18n/zh.json
@@ -878,6 +878,11 @@
"runDescription": "使用随 Avibe 发货的 @avibe/computer 模块运行 ESM 文件,并绑定到当前这个 Avibe Agent Turn。",
"scriptFile": "可读的 .mjs 脚本路径。",
"scriptArg": "以 name=value 或 name=@file 传入脚本参数;值保持为字符串。",
+ "js": "在本 Session 的常驻 Computer Use 内核中执行 JavaScript",
+ "jsDescription": "在一个 Node 内核中执行代码,同一 Avibe Session 的多次调用之间保留顶层变量。已预载 computer 和 avibe,支持顶层 await。每次调用都绑定到当前 Agent Turn。",
+ "jsCode": "JavaScript 源码,或用 @FILE 从 UTF-8 文件读取。",
+ "jsTimeout": "单次调用超时(毫秒,默认 30000,最大 300000)。",
+ "jsReset": "丢弃本 Session 的 JavaScript 内核及其全部变量;已打开的应用不受影响",
"observe": "观察应用、窗口或一个精确窗口",
"observeApps": "列出可见应用",
"observeWindows": "列出窗口",
@@ -944,6 +949,17 @@
"scriptTargetNotFound": "未找到请求的 Computer Use 目标。",
"scriptTurnEnded": "启动此脚本的 Avibe Turn 已结束。",
"scriptWindowOrderUnavailable": "此选择器无法确定窗口顺序。",
+ "jsFailed": "JavaScript 调用失败:{error}",
+ "jsCodeFile": "无法从 {path} 读取 JavaScript:{error}",
+ "jsTimeoutRange": "--timeout-ms 必须在 1 到 300000 之间。",
+ "jsCodeInvalid": "JavaScript 代码必须是非空文本。",
+ "jsCodeTooLarge": "JavaScript 代码超过了大小上限。",
+ "jsTimeout": "调用超时,已被取消。内核及其变量均已保留。之前的操作可能已经生效,重试前请先重新观察。",
+ "jsKernelReset": "JavaScript 内核已重置,所有变量均已丢弃。之前的操作可能已经生效,重试前请先重新观察。",
+ "jsCallInactive": "只有在 vibe computer js 调用执行期间才能发起 Computer Use 请求。",
+ "jsKernelBusy": "本 Session 已有过多 JavaScript 调用在排队,请等它们结束后再重试。",
+ "jsKernelUnavailable": "无法启动 JavaScript 内核。",
+ "jsKernelError": "JavaScript 内核在执行本次调用时出错。",
"missingCallerSession": "Computer Use 需要 Avibe Agent 调用方 Session。",
"missingCallerTurn": "Computer Use 要求调用方 Avibe Session 当前有活动 Turn。",
"serviceUnavailable": "Avibe 服务不可用:{error}",
diff --git a/vibe/internal_client.py b/vibe/internal_client.py
index 051591434..f2bb51376 100644
--- a/vibe/internal_client.py
+++ b/vibe/internal_client.py
@@ -484,6 +484,57 @@ def computer_script_close_sync(
)
+def computer_js_client_timeout_seconds() -> float:
+ """How long the CLI waits for one js call: never less than the Controller lease."""
+
+ from core.computer_cli import (
+ COMPUTER_JS_CLIENT_MARGIN_SECONDS,
+ COMPUTER_JS_CONNECTION_LEASE_SECONDS,
+ )
+
+ return COMPUTER_JS_CONNECTION_LEASE_SECONDS + COMPUTER_JS_CLIENT_MARGIN_SECONDS
+
+
+def computer_js_eval_sync(
+ *,
+ caller_session_id: str,
+ code: str,
+ timeout_ms: int,
+ socket_path: Optional[Path] = None,
+) -> dict[str, Any]:
+ """Run one call in the caller Session's persistent JavaScript kernel.
+
+ The Controller settles every admitted call inside its connection lease, so
+ the client waits for that lease plus a margin.
+ """
+
+ return _computer_script_post_sync(
+ _resolve_endpoint(socket_path),
+ "/internal/computer-js/eval",
+ {
+ "caller_session_id": caller_session_id,
+ "code": code,
+ "timeout_ms": timeout_ms,
+ },
+ timeout=computer_js_client_timeout_seconds(),
+ )
+
+
+def computer_js_reset_sync(
+ *,
+ caller_session_id: str,
+ socket_path: Optional[Path] = None,
+) -> dict[str, Any]:
+ """Discard the caller Session's JavaScript kernel and its bindings."""
+
+ return _computer_script_post_sync(
+ _resolve_endpoint(socket_path),
+ "/internal/computer-js/reset",
+ {"caller_session_id": caller_session_id},
+ timeout=10.0,
+ )
+
+
async def dispatch_async(
payload: dict[str, Any],
*,