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.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""``httpx`` wrapper for the Controller's cross-platform control IPC.
C5 of Plan 2 (see ``docs/plans/workbench-dispatch-architecture.md``).
The UI server runs as its own subprocess; this module is how it reaches
``core.internal_server`` to start agent turns and observe their lifecycle.
Single responsibility: keep all the endpoint discovery / httpx-transport /
SSE-parsing boilerplate out of the UI route bodies. Routes call
``dispatch_async(...)`` to start a fire-and-forget turn (the reply arrives over
the persistent ``message.new`` session stream, not the response),
``stream_events(...)`` to subscribe to the controller's event feed, and
``cancel_dispatch`` / ``send_now`` / ``turn_state`` / ``health`` for the
turn-control surface — each raising ``InternalServerUnavailable`` so the route
can degrade gracefully.
"""
from __future__ import annotations
import asyncio
import json
import logging
import os
import stat
from pathlib import Path
from typing import Any, AsyncIterator, Optional
import httpx
from core import control_ipc
logger = logging.getLogger(__name__)
_SOCKET_ERRORS = (httpx.TransportError, OSError)
_SOCKET_CONNECT_ERRORS = (httpx.ConnectError, httpx.ConnectTimeout, OSError)
_OWNER_ONLY_SOCKET_MODES = frozenset({0o600, 0o700})
_CHECK_POSIX_SOCKET_MODE = os.name != "nt"
# A transport deadline shorter than the operation it wraps turns a slow
# success into a reported failure while the controller keeps working, and
# leaves the caller free to retry into the unfinished operation. Both of these
# must therefore stay outside the bound of the work they wait on;
# ``tests/test_internal_client_timeouts.py`` asserts the relationship against
# the sources below rather than trusting these numbers to stay in step.
#
class InternalServerUnavailable(Exception):
"""Raised when the dispatch socket cannot be reached before acceptance."""
class InternalServerTimeout(Exception):
"""Raised when the internal server accepts a probe but does not answer in time."""
def default_socket_path() -> Path:
"""Mirror ``core.internal_server.default_socket_path`` without an
import cycle.
``core.internal_server`` lives in the controller process and we
deliberately don't import controller-side modules from the UI
server. Duplicating the one-line path-derivation keeps the
boundaries clean.
"""
return control_ipc.default_unix_socket_path()
def _platform_name() -> str:
return os.name
def _resolve_endpoint(socket_path: Optional[Path]) -> control_ipc.ControlIpcClientEndpoint:
platform_name = _platform_name()
if socket_path is not None or platform_name != "nt":
return control_ipc.ControlIpcClientEndpoint(
transport="unix",
socket_path=_verified_socket_path(socket_path),
)
try:
endpoint = control_ipc.resolve_client_endpoint(
platform_name=platform_name,
socket_path=socket_path,
)
except control_ipc.ControlIpcDescriptorError as exc:
raise InternalServerUnavailable(str(exc)) from exc
return endpoint
async def _resolve_endpoint_async(
socket_path: Optional[Path],
) -> control_ipc.ControlIpcClientEndpoint:
"""Keep endpoint discovery and filesystem checks off the UI event loop."""
return await asyncio.to_thread(_resolve_endpoint, socket_path)
def _async_transport(endpoint: control_ipc.ControlIpcClientEndpoint) -> httpx.AsyncBaseTransport:
if endpoint.transport == "unix":
return httpx.AsyncHTTPTransport(uds=str(endpoint.socket_path))
return httpx.AsyncHTTPTransport()
def _sync_transport(endpoint: control_ipc.ControlIpcClientEndpoint) -> httpx.BaseTransport:
if endpoint.transport == "unix":
return httpx.HTTPTransport(uds=str(endpoint.socket_path))
return httpx.HTTPTransport()
def _validate_response(
response: httpx.Response,
endpoint: control_ipc.ControlIpcClientEndpoint,
) -> None:
descriptor = endpoint.descriptor
if descriptor is None:
return
if response.status_code == 401:
raise InternalServerUnavailable("control IPC authentication was rejected")
response_instance = response.headers.get(control_ipc.CONTROL_IPC_INSTANCE_HEADER)
if not control_ipc.response_instance_matches(descriptor, response_instance):
raise InternalServerUnavailable("control IPC response came from a stale instance")
def _verified_socket_path(socket_path: Optional[Path]) -> Path:
"""Return an owner-only controller socket without following filesystem links."""
target = (socket_path or default_socket_path()).expanduser()
try:
info = target.lstat()
except FileNotFoundError as exc:
raise InternalServerUnavailable(f"dispatch socket missing at {target}") from exc
except OSError as exc:
raise InternalServerUnavailable(f"dispatch socket cannot be inspected at {target}") from exc
if stat.S_ISLNK(info.st_mode) or not stat.S_ISSOCK(info.st_mode):
raise InternalServerUnavailable(f"dispatch socket is unsafe at {target}")
if hasattr(os, "getuid") and info.st_uid != os.getuid():
raise InternalServerUnavailable(f"dispatch socket owner mismatch at {target}")
if _CHECK_POSIX_SOCKET_MODE and stat.S_IMODE(info.st_mode) not in _OWNER_ONLY_SOCKET_MODES:
raise InternalServerUnavailable(f"dispatch socket mode mismatch at {target}")
return target
async def stream_dispatch(
payload: dict[str, Any],
*,
socket_path: Optional[Path] = None,
timeout: float = 1800.0,
) -> AsyncIterator[tuple[str, dict[str, Any]]]:
"""Send a dispatch request and yield the turn's SSE events as they arrive.
Each yielded tuple is ``(event_name, parsed_data)`` — e.g. ``("turn.start",
{...})``, ``("turn.chunk", {...})``, ``("turn.end", {...})``. The caller
re-encodes them for the browser. Raises ``InternalServerUnavailable`` for
connect-time failures so the caller can degrade.
NB: the web **Chat** page no longer uses this (it's fire-and-forget +
``message.new``); this streaming round-trip backs the **Show-page** dispatch
flow (``_run_show_event_dispatch`` re-publishes each event as ``show.dispatch``).
"""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url, headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=5.0),
) as client:
try:
stream = client.stream("POST", "/internal/dispatch", json=payload)
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
async with stream as resp:
_validate_response(resp, endpoint)
if resp.status_code >= 400:
detail = await resp.aread()
raise InternalServerUnavailable(
f"dispatch endpoint returned {resp.status_code}: {detail!r}"
)
current_event: Optional[str] = None
async for line in resp.aiter_lines():
if not line:
# Blank line ends an SSE event block; reset the
# event-name buffer so a missing ``event:`` field
# on the next block defaults to ``message``.
current_event = None
continue
if line.startswith("event:"):
current_event = line.split(":", 1)[1].strip()
elif line.startswith("data:"):
raw = line[5:].lstrip()
try:
parsed = json.loads(raw)
except json.JSONDecodeError:
logger.warning("internal_client: invalid SSE data line %r", raw)
continue
yield (current_event or "message", parsed)
except InternalServerUnavailable:
raise
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
async def stream_events(
*,
socket_path: Optional[Path] = None,
) -> AsyncIterator[tuple[str, Any]]:
"""Subscribe to the controller's long-lived ``GET /internal/events`` feed.
Yields ``(event_name, parsed_data)`` for each event, e.g.
``("inbox.session.updated", {...inbox row...})``. The read timeout is
disabled (the connection is meant to stay open); raises
``InternalServerUnavailable`` on connect failure so the UI server's
subscriber loop can back off and reconnect.
"""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(None, connect=5.0),
) as client:
try:
stream = client.stream("GET", "/internal/events")
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
async with stream as resp:
_validate_response(resp, endpoint)
if resp.status_code >= 400:
detail = await resp.aread()
raise InternalServerUnavailable(
f"events endpoint returned {resp.status_code}: {detail!r}"
)
current_event: Optional[str] = None
async for line in resp.aiter_lines():
if not line:
current_event = None
continue
if line.startswith("event:"):
current_event = line.split(":", 1)[1].strip()
elif line.startswith("data:"):
raw = line[5:].lstrip()
try:
parsed = json.loads(raw)
except json.JSONDecodeError:
logger.warning("internal_client: invalid SSE data line %r", raw)
continue
yield (current_event or "message", parsed)
except InternalServerUnavailable:
raise
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
async def publish_event(
event_type: str,
data: dict[str, Any],
*,
socket_path: Optional[Path] = None,
timeout: float = 5.0,
) -> dict[str, Any]:
"""Ask the Controller process to publish an allowlisted SSE notification."""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=2.0),
) as client:
resp = await client.post("/internal/events", json={"type": event_type, "data": data})
_validate_response(resp, endpoint)
if resp.status_code >= 400:
detail = await resp.aread()
raise InternalServerUnavailable(f"events publish returned {resp.status_code}: {detail!r}")
return resp.json()
except InternalServerUnavailable:
raise
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
def publish_event_sync(
event_type: str,
data: dict[str, Any],
*,
socket_path: Optional[Path] = None,
timeout: float = 5.0,
) -> dict[str, Any]:
"""Synchronous wrapper for CLI/child-process notification publishers."""
endpoint = _resolve_endpoint(socket_path)
transport = _sync_transport(endpoint)
try:
with httpx.Client(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=2.0),
) as client:
resp = client.post("/internal/events", json={"type": event_type, "data": data})
_validate_response(resp, endpoint)
if resp.status_code >= 400:
raise InternalServerUnavailable(
f"events publish returned {resp.status_code}: {resp.content!r}"
)
return resp.json()
except InternalServerUnavailable:
raise
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
def record_skill_observation_sync(
observation: dict[str, Any], *, socket_path: Optional[Path] = None,
timeout: float = 0.25,
) -> dict[str, Any]:
"""Best-effort queue submission; the response is not a durable receipt."""
endpoint = _resolve_endpoint(socket_path)
try:
with httpx.Client(
transport=_sync_transport(endpoint),
base_url=endpoint.base_url, headers=endpoint.headers,
timeout=httpx.Timeout(timeout),
) as client:
response = client.post("/internal/skill-observations", json=observation)
_validate_response(response, endpoint)
if response.status_code != 202:
raise InternalServerUnavailable("Skill observation rejected")
return response.json()
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable("Skill observation transport unavailable") from exc
def computer_use_sync(
*,
caller_session_id: str,
tool: str,
arguments: dict[str, Any],
socket_path: Optional[Path] = None,
timeout: float | None = None,
) -> dict[str, Any]:
"""Run one Controller-owned Computer Use request for the caller's active Turn.
The Controller owns the active-Turn check. Once IPC connects, a transport
failure is acceptance-ambiguous because the driver operation may already
have completed, so callers receive the same observe-before-retry error as
a response timeout.
"""
endpoint = _resolve_endpoint(socket_path)
payload = {
"caller_session_id": caller_session_id,
"tool": tool,
"arguments": arguments,
}
try:
with httpx.Client(
transport=_sync_transport(endpoint),
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=5.0),
) as client:
response = client.post("/internal/computer-use", json=payload)
_validate_response(response, endpoint)
body = response.json() if response.content else {}
except _SOCKET_CONNECT_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
except httpx.TimeoutException as exc:
raise InternalServerTimeout(
f"Computer Use request may have completed; observe again before retrying: {exc}"
) from exc
except httpx.TransportError as exc:
raise InternalServerTimeout(
f"Computer Use request may have completed; observe again before retrying: {exc}"
) from exc
if not isinstance(body, dict):
raise InternalServerUnavailable("computer-use endpoint returned invalid JSON")
return {"status_code": response.status_code, "body": body}
def mcp_request_sync(
operation: str,
payload: dict[str, Any],
*,
socket_path: Optional[Path] = None,
) -> dict[str, Any]:
"""Run one Controller-owned MCP Hub operation (``core/mcp_hub/runtime.py``).
The owner bounds every operation itself (connect, call and generation
timeouts), so the read waits for its definitive answer. Once IPC connected,
a transport failure is acceptance-ambiguous and raises
``InternalServerTimeout``.
"""
endpoint = _resolve_endpoint(socket_path)
try:
with httpx.Client(
transport=_sync_transport(endpoint),
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(None, connect=5.0),
) as client:
response = client.post("/internal/mcp", json={"operation": operation, "payload": payload})
_validate_response(response, endpoint)
body = response.json() if response.content else {}
except _SOCKET_CONNECT_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
except httpx.TransportError as exc:
raise InternalServerTimeout(str(exc)) from exc
if not isinstance(body, dict):
raise InternalServerUnavailable("mcp endpoint returned invalid JSON")
return body
async def mcp_request(
operation: str,
payload: dict[str, Any],
*,
socket_path: Optional[Path] = None,
) -> dict[str, Any]:
"""Async twin of :func:`mcp_request_sync` for the Web UI process."""
endpoint = await _resolve_endpoint_async(socket_path)
try:
async with httpx.AsyncClient(
transport=_async_transport(endpoint),
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(None, connect=5.0),
) as client:
response = await client.post("/internal/mcp", json={"operation": operation, "payload": payload})
_validate_response(response, endpoint)
except _SOCKET_CONNECT_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
except httpx.TransportError as exc:
raise InternalServerTimeout(str(exc)) from exc
body = response.json() if response.content else {}
if not isinstance(body, dict):
raise InternalServerUnavailable("mcp endpoint returned invalid JSON")
return body
def resolve_computer_script_endpoint(
socket_path: Optional[Path] = None,
) -> control_ipc.ControlIpcClientEndpoint:
"""Resolve and verify the Controller endpoint before launching Node."""
return _resolve_endpoint(socket_path)
def computer_script_endpoint_payload(
endpoint: control_ipc.ControlIpcClientEndpoint,
) -> dict[str, Any]:
"""Serialize one already-verified endpoint for the shipped Node runner."""
if endpoint.transport == "unix":
if endpoint.socket_path is None:
raise InternalServerUnavailable("control IPC Unix endpoint has no socket")
return {
"transport": "unix",
"socket_path": str(endpoint.socket_path),
}
descriptor = endpoint.descriptor
if descriptor is None:
raise InternalServerUnavailable("control IPC TCP endpoint has no descriptor")
return {
"transport": "tcp",
"host": descriptor.host,
"port": descriptor.port,
"headers": endpoint.headers,
"instance_id": descriptor.instance_id,
"instance_header": control_ipc.CONTROL_IPC_INSTANCE_HEADER,
}
def _computer_script_post_sync(
endpoint: control_ipc.ControlIpcClientEndpoint,
path: str,
payload: dict[str, Any],
*,
timeout: float,
) -> dict[str, Any]:
try:
with httpx.Client(
transport=_sync_transport(endpoint),
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=5.0),
) as client:
response = client.post(path, json=payload)
_validate_response(response, endpoint)
try:
body = response.json() if response.content else {}
except (json.JSONDecodeError, UnicodeDecodeError) as exc:
raise InternalServerUnavailable(
f"{path} returned invalid JSON"
) from exc
except _SOCKET_CONNECT_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
except (httpx.TimeoutException, httpx.TransportError) as exc:
raise InternalServerTimeout(str(exc)) from exc
if not isinstance(body, dict):
raise InternalServerUnavailable(f"{path} returned invalid JSON")
return {"status_code": response.status_code, "body": body}
def computer_script_open_sync(
*,
endpoint: control_ipc.ControlIpcClientEndpoint,
caller_session_id: str,
timeout_seconds: float,
request_timeout: float = 10.0,
) -> dict[str, Any]:
"""Open one exact-Turn-bound script connection."""
return _computer_script_post_sync(
endpoint,
"/internal/computer-script/open",
{
"caller_session_id": caller_session_id,
"timeout_seconds": timeout_seconds,
},
timeout=request_timeout,
)
def computer_script_close_sync(
*,
endpoint: control_ipc.ControlIpcClientEndpoint,
connection_token: str,
timeout: float = 5.0,
) -> dict[str, Any]:
"""Best-effort close for a script connection known to the Python runner."""
return _computer_script_post_sync(
endpoint,
"/internal/computer-script/close",
{"connection_token": connection_token},
timeout=timeout,
)
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],
*,
socket_path: Optional[Path] = None,
timeout: float | None = 10.0,
) -> dict[str, Any]:
"""Start a fire-and-forget turn on the controller and return immediately.
Hits ``POST /internal/dispatch_async``: the controller starts the turn and
responds ``202`` right away (the reply arrives over the persistent
``message.new`` session stream, not this response). Returns
``{"status_code", "body"}`` so the caller can distinguish a started turn
from one accepted into the shared queue. A pre-connect failure raises
``InternalServerUnavailable``; a post-connect timeout raises
``InternalServerTimeout`` because acceptance is unknown.
"""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=5.0),
) as client:
resp = await client.post("/internal/dispatch_async", json=payload)
_validate_response(resp, endpoint)
except _SOCKET_CONNECT_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
except httpx.TimeoutException as exc:
# Once the socket connected, a timeout is acceptance-unknown: the
# controller request may still settle the durable reservation.
raise InternalServerTimeout(str(exc)) from exc
return {"status_code": resp.status_code, "body": resp.json() if resp.content else {}}
async def archive_session(session_id: str, *, socket_path: Optional[Path] = None) -> dict[str, Any]:
"""Await accepted archive completion, without a transport reporting deadline."""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(None, connect=5.0),
) as client:
resp = await client.post("/internal/sessions/archive", json={"session_id": session_id})
_validate_response(resp, endpoint)
except _SOCKET_CONNECT_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
except httpx.TimeoutException as exc:
raise InternalServerTimeout(str(exc)) from exc
return {"status_code": resp.status_code, "body": resp.json() if resp.content else {}}
async def reconcile_platforms(
*,
socket_path: Optional[Path] = None,
timeout: float = 30.0,
) -> dict[str, Any]:
"""Ask the controller to hot-apply the persisted platform configuration."""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=5.0),
) as client:
resp = await client.post("/internal/reconcile-platforms")
_validate_response(resp, endpoint)
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
return {"status_code": resp.status_code, "body": resp.json() if resp.content else {}}
async def scope_session_hint(
*,
platform: str,
scope: str,
native_id: str,
thread_id: str = "",
socket_path: Optional[Path] = None,
timeout: float = 5.0,
) -> bool:
"""Ask the controller whether a scope's current session runs another Agent than its route."""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=2.0),
) as client:
resp = await client.post(
"/internal/scope-session-hint",
json={"platform": platform, "scope": scope, "id": native_id, "thread_id": thread_id},
)
_validate_response(resp, endpoint)
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
if resp.status_code != 200:
raise InternalServerUnavailable(f"scope session hint returned {resp.status_code}")
return bool((resp.json() or {}).get("needs_new_session"))
async def invalidate_activity_streaming(
*,
socket_path: Optional[Path] = None,
timeout: float = 5.0,
) -> dict[str, Any]:
"""Make the controller re-read the persisted Agent Activity display flag."""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url, headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=2.0),
) as client:
resp = await client.post("/internal/invalidate-activity-streaming")
_validate_response(resp, endpoint)
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
return {"status_code": resp.status_code, "body": resp.json() if resp.content else {}}
async def backend_application(
backend: str, *, socket_path: Optional[Path] = None, timeout: float = 5.0,
) -> dict[str, Any]:
from modules.agents.catalog import AGENT_BACKENDS
if backend not in AGENT_BACKENDS:
raise ValueError("unsupported_backend")
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport, base_url=endpoint.base_url, headers=endpoint.headers, timeout=timeout,
) as client:
response = await client.get(f"/internal/backend-application/{backend}")
_validate_response(response, endpoint)
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
return {"status_code": response.status_code, "body": response.json() if response.content else {}}
async def create_opencode_generation_lease(
purpose: str,
*,
ttl_seconds: float,
socket_path: Optional[Path] = None,
timeout: float = 180.0,
) -> dict[str, Any]:
"""Ask the controller to pin an OpenCode generation; it may start one first."""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=5.0),
) as client:
response = await client.post(
"/internal/opencode/generation-leases",
json={"purpose": purpose, "ttl_seconds": ttl_seconds},
)
_validate_response(response, endpoint)
except _SOCKET_CONNECT_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
except httpx.TimeoutException as exc:
raise InternalServerTimeout(str(exc)) from exc
return {"status_code": response.status_code, "body": response.json() if response.content else {}}
async def release_opencode_generation_lease(
lease_id: str,
*,
socket_path: Optional[Path] = None,
timeout: float = 10.0,
) -> dict[str, Any]:
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport, base_url=endpoint.base_url, headers=endpoint.headers, timeout=timeout,
) as client:
response = await client.post(f"/internal/opencode/generation-leases/{lease_id}/release")
_validate_response(response, endpoint)
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
return {"status_code": response.status_code, "body": response.json() if response.content else {}}
async def reconcile_agent_backends(
backends: list[str],
*,
socket_path: Optional[Path] = None,
timeout: float = 30.0,
) -> dict[str, Any]:
"""Ask the controller to hot-apply persisted Agent backend config."""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=5.0),
) as client:
resp = await client.post(
"/internal/reconcile-agent-backends",
json={"backends": backends},
)
_validate_response(resp, endpoint)
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
return {"status_code": resp.status_code, "body": resp.json() if resp.content else {}}
async def test_backend_auth(
backend: str,
*,
model: str | None = None,
socket_path: Optional[Path] = None,
timeout: float = 60.0,
) -> dict[str, Any]:
"""Run a Settings connection probe on the controller-owned Agent runtime."""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
payload: dict[str, Any] = {"backend": backend}
if model:
payload["model"] = model
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=5.0),
) as client:
resp = await client.post("/internal/backend-auth/test", json=payload)
_validate_response(resp, endpoint)
except _SOCKET_CONNECT_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
except httpx.TimeoutException as exc:
raise InternalServerTimeout(str(exc)) from exc
return {"status_code": resp.status_code, "body": resp.json() if resp.content else {}}
async def propose_bot_handle(
display_name: str,
role: str = "",
*,
socket_path: Optional[Path] = None,
timeout: float = 6.0,
) -> Optional[str]:
"""Ask the controller for the main Bot's model's handle proposal (``core.bot_handles``); None without one."""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=2.0),
) as client:
resp = await client.post(
"/internal/bots/handle-suggestion", json={"display_name": display_name, "role": role}
)
_validate_response(resp, endpoint)
except _SOCKET_CONNECT_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
except httpx.TimeoutException as exc:
raise InternalServerTimeout(str(exc)) from exc
body = resp.json() if resp.content else {}
handle = body.get("handle") if isinstance(body, dict) and resp.status_code == 200 else None
return handle if isinstance(handle, str) and handle else None
async def notify_vault_request_created(
request_payload: dict[str, Any],
*,
socket_path: Optional[Path] = None,
timeout: float = 5.0,
) -> dict[str, Any]:
"""Ask the controller to send the IM degradation notice for a Vault request."""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=2.0),
) as client:
resp = await client.post("/internal/vault/request-created", json={"request": request_payload})
_validate_response(resp, endpoint)
if resp.status_code >= 400:
detail = await resp.aread()
raise InternalServerUnavailable(
f"vault request notification returned {resp.status_code}: {detail!r}"
)
except InternalServerUnavailable:
raise
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
return {"status_code": resp.status_code, "body": resp.json() if resp.content else {}}
def notify_vault_request_created_sync(
request_payload: dict[str, Any],
*,
socket_path: Optional[Path] = None,
timeout: float = 5.0,
) -> dict[str, Any]:
"""Synchronous wrapper for CLI/UI-server Vault request notifications."""
endpoint = _resolve_endpoint(socket_path)
transport = _sync_transport(endpoint)
try:
with httpx.Client(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=2.0),
) as client:
resp = client.post("/internal/vault/request-created", json={"request": request_payload})
_validate_response(resp, endpoint)
if resp.status_code >= 400:
raise InternalServerUnavailable(
f"vault request notification returned {resp.status_code}: {resp.content!r}"
)
except InternalServerUnavailable:
raise
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
return {"status_code": resp.status_code, "body": resp.json() if resp.content else {}}
async def cancel_dispatch(
session_id: str,
*,
run_id: str | None = None,
socket_path: Optional[Path] = None,
) -> dict[str, Any]:
"""Ask the controller to cancel a running ``dispatch_turn`` for
``session_id``.
Returns the controller's JSON response on success. Raises
``InternalServerUnavailable`` if the socket is missing / unreachable
so the UI route can fall back gracefully.
"""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
# The cancel now WAITS for the backend interrupt to confirm before
# acking (so a refused stop keeps the turn cancellable), and a
# Claude interrupt / OpenCode abort can take a few seconds — give it
# room so a slow-but-successful stop isn't read-timed-out into a 500.
timeout=httpx.Timeout(30.0, connect=1.0),
) as client:
resp = await client.post(
f"/internal/cancel/{session_id}",
params={"run_id": run_id} if run_id is not None else None,
)
_validate_response(resp, endpoint)
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
return {"status_code": resp.status_code, "body": resp.json() if resp.content else {}}
async def end_running_agent(payload: dict[str, Any], *, socket_path: Optional[Path] = None) -> dict[str, Any]:
"""Ask the controller to terminate one running agent's live runtime.
``payload`` identifies the target (backend/state/composite_key/base_session_id
/pid). Returns ``{status_code, body}``; raises ``InternalServerUnavailable``
on socket failure. A Claude interrupt / OpenCode abort can take a few seconds,
so the timeout matches ``cancel_dispatch``.
"""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(30.0, connect=1.0),
) as client:
resp = await client.post("/internal/running-agents/end", json=payload)
_validate_response(resp, endpoint)
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
return {"status_code": resp.status_code, "body": resp.json() if resp.content else {}}
async def _show_access_request(
path: str,
payload: dict[str, Any],
*,
read_timeout: float | None,
socket_path: Optional[Path] = None,
) -> dict[str, Any]:
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url, headers=endpoint.headers,
timeout=httpx.Timeout(read_timeout, connect=1.0),
) as client:
resp = await client.post(path, json=payload)
_validate_response(resp, endpoint)
except httpx.ReadTimeout as exc:
raise InternalServerTimeout(str(exc)) from exc
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
return {"status_code": resp.status_code, "body": resp.json() if resp.content else {}}
async def show_access_settings_read(
payload: dict[str, Any],
*,
socket_path: Optional[Path] = None,
) -> dict[str, Any]:
return await _show_access_request(
"/internal/show-access/settings-read",
payload,
read_timeout=10.0,
socket_path=socket_path,
)
async def show_access_apply(
payload: dict[str, Any],
*,
socket_path: Optional[Path] = None,
) -> dict[str, Any]:
return await _show_access_request(
"/internal/show-access/apply",
payload,
# Once accepted, the controller serializes this non-cancellable SQLite
# write. Wait for its definitive CAS result so a slow commit is never
# reported as a timeout that invites an ambiguous retry.
read_timeout=None,
socket_path=socket_path,
)
async def send_now(
session_id: str,
*,
expected_delivery_id: str | None = None,
socket_path: Optional[Path] = None,
) -> dict[str, Any]:
"""Ask the controller to run a session's send-while-busy queue immediately
("立即发送"): interrupt any running turn + flush the queue. Returns
``{status_code, body}``; raises ``InternalServerUnavailable`` on socket
failure so the UI route can degrade.
"""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
# send-now interrupts the running turn before flushing, and that
# backend stop can take a few seconds — match the cancel timeout so a
# slow-but-successful interrupt isn't read-timed-out.
timeout=httpx.Timeout(30.0, connect=1.0),
) as client:
resp = await client.post(
f"/internal/send-now/{session_id}",
params=(
{"expected_delivery_id": expected_delivery_id}
if expected_delivery_id
else None
),
)
_validate_response(resp, endpoint)
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
return {"status_code": resp.status_code, "body": resp.json() if resp.content else {}}
async def turn_state(session_id: str, *, socket_path: Optional[Path] = None) -> dict[str, Any]:
"""Query whether a turn is in flight for ``session_id`` so a freshly loaded /
reconnected Chat page can restore its Stop/working state. Returns
``{status_code, body}``; raises ``InternalServerUnavailable`` on socket
failure so the route can degrade (assume idle)."""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(1.0, connect=0.2),
) as client:
resp = await client.get(f"/internal/turn-state/{session_id}")
_validate_response(resp, endpoint)
except httpx.ReadTimeout as exc:
raise InternalServerTimeout(str(exc)) from exc
except _SOCKET_CONNECT_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
return {"status_code": resp.status_code, "body": resp.json() if resp.content else {}}
async def request_preview(
session_id: str,
*,
context_seq: int | None = None,
socket_path: Optional[Path] = None,
) -> dict[str, Any]:
"""Ask the controller to reconstruct locally; only a safe artifact summary crosses back."""
from core.handlers.request_preview import preview_caller
# Check and capture the invoking principal before any IPC operation. Never drop remote claims.
caller = preview_caller()
endpoint = await _resolve_endpoint_async(socket_path)
try:
async with httpx.AsyncClient(
transport=_async_transport(endpoint), base_url=endpoint.base_url,
headers=endpoint.headers, timeout=httpx.Timeout(60.0, connect=0.5),
) as client:
response = await client.post("/internal/debug/request/preview", json={
"session_id": session_id, "context_seq": context_seq, "caller": caller,
})
_validate_response(response, endpoint)
except httpx.ReadTimeout as exc:
raise InternalServerTimeout("Request preview timed out") from exc
except _SOCKET_CONNECT_ERRORS as exc:
raise InternalServerUnavailable("Request preview controller unavailable") from exc
return {"status_code": response.status_code, "body": response.json() if response.content else {}}
async def list_running_agents(
*,
run_ids: Optional[list[str]] = None,
socket_path: Optional[Path] = None,
) -> dict[str, Any]:
"""Fetch the controller's read-only running-agents snapshot.
Returns ``{status_code, body}``; raises ``InternalServerUnavailable`` on
socket failure so the web route can render an explicit "runtime unreachable"
state instead of a misleading "0 running". The snapshot reads in-memory
registries plus a small DB enrichment, so the read timeout is a touch longer
than ``turn_state``.
"""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(3.0, connect=0.5),
) as client:
if run_ids is None:
resp = await client.get("/internal/running-agents")
else:
resp = await client.post(
"/internal/running-agents/snapshot",
json={"run_ids": run_ids},
)
_validate_response(resp, endpoint)
except httpx.ReadTimeout as exc:
raise InternalServerTimeout(str(exc)) from exc
except _SOCKET_CONNECT_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
return {"status_code": resp.status_code, "body": resp.json() if resp.content else {}}
def _parse_health_response(
response: httpx.Response,
endpoint: control_ipc.ControlIpcClientEndpoint,
) -> dict[str, Any] | None:
_validate_response(response, endpoint)
if response.status_code != 200:
return None
try:
payload = response.json()
except (json.JSONDecodeError, UnicodeDecodeError):
return None
if (
not isinstance(payload, dict)
or payload.get("ok") is not True
or payload.get("service") != "vibe-remote-internal"
or payload.get("version") != 1
):
return None
runtime_id = payload.get("desktop_runtime_id")
if runtime_id is not None:
from vibe.desktop_runtime import DESKTOP_RUNTIME_ID_ENV, desktop_runtime_id
if (
not isinstance(runtime_id, str)
or desktop_runtime_id({DESKTOP_RUNTIME_ID_ENV: runtime_id}) != runtime_id
):
return None
return payload
async def health_identity(socket_path: Optional[Path] = None) -> dict[str, Any] | None:
"""Return the validated Controller health identity, or ``None`` on failure."""
try:
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(2.0, connect=1.0),
) as client:
response = await client.get("/internal/health")
return _parse_health_response(response, endpoint)
except Exception:
return None
async def desktop_capabilities(
socket_path: Optional[Path] = None,
) -> dict[str, Any]:
"""Read the desktop capability contract from the authoritative Controller.
A released Controller that predates this endpoint answers 404. That is a
definitive schema-0 result; transport failures remain transient so the
desktop shell can retain a same-Controller cached answer.
"""
endpoint = await _resolve_endpoint_async(socket_path)
transport = _async_transport(endpoint)
try:
async with httpx.AsyncClient(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(2.0, connect=1.0),
) as client:
response = await client.get("/internal/desktop/capabilities")
_validate_response(response, endpoint)
if response.status_code == 404:
return {
"computer_use_schema": 0,
"controller_id": "legacy",
}
if response.status_code >= 400:
raise InternalServerUnavailable(
f"desktop capabilities endpoint returned {response.status_code}"
)
try:
payload = response.json()
except (json.JSONDecodeError, UnicodeDecodeError) as exc:
raise InternalServerUnavailable(
"desktop capabilities response was not JSON"
) from exc
schema = payload.get("computer_use_schema") if isinstance(payload, dict) else None
controller_id = payload.get("controller_id") if isinstance(payload, dict) else None
if (
isinstance(schema, bool)
or not isinstance(schema, int)
or schema < 0
or not isinstance(controller_id, str)
or not controller_id
):
raise InternalServerUnavailable(
"desktop capabilities response was malformed"
)
return {
"computer_use_schema": schema,
"controller_id": controller_id,
}
except InternalServerUnavailable:
raise
except httpx.TimeoutException as exc:
raise InternalServerTimeout(str(exc)) from exc
except _SOCKET_ERRORS as exc:
raise InternalServerUnavailable(str(exc)) from exc
def health_identity_sync(socket_path: Optional[Path] = None) -> dict[str, Any] | None:
"""Synchronous Controller identity probe for CLI lifecycle decisions."""
try:
endpoint = _resolve_endpoint(socket_path)
transport = _sync_transport(endpoint)
with httpx.Client(
transport=transport,
base_url=endpoint.base_url,
headers=endpoint.headers,
timeout=httpx.Timeout(2.0, connect=1.0),
) as client:
response = client.get("/internal/health")
return _parse_health_response(response, endpoint)
except Exception:
return None
async def health(socket_path: Optional[Path] = None) -> bool:
"""Probe ``GET /internal/health``. Returns False on any failure.
Useful for UI startup checks and for the fallback decision in the
streaming route body so we can decline cleanly before opening the
longer-lived dispatch stream.
"""
return await health_identity(socket_path) is not None
def health_sync(
socket_path: Optional[Path] = None,
*,
timeout: float = 2.0,
) -> bool:
"""Synchronously probe the controller health endpoint.
Dependency reconciliation runs in a worker thread and must distinguish a
connectable controller from a stale Unix-socket pathname left by a crashed
process.
"""
try:
endpoint = _resolve_endpoint(socket_path)
except InternalServerUnavailable:
return False
transport = _sync_transport(endpoint)
try:
with httpx.Client(
transport=transport,
base_url=endpoint.base_url, headers=endpoint.headers,
timeout=httpx.Timeout(timeout, connect=min(timeout, 1.0)),
) as client:
resp = client.get("/internal/health")
_validate_response(resp, endpoint)
return resp.status_code == 200 and (resp.json() or {}).get("ok") is True
except Exception:
return False