diff --git a/docs/architecture/rfcs/typescript-control-plane-migration-v0.md b/docs/architecture/rfcs/typescript-control-plane-migration-v0.md index a51674dc62..9bf0bff241 100644 --- a/docs/architecture/rfcs/typescript-control-plane-migration-v0.md +++ b/docs/architecture/rfcs/typescript-control-plane-migration-v0.md @@ -2002,7 +2002,7 @@ server. | CLI-only after the TS CLI cutover | Import and execute the TS kernel in the CLI process; no daemon | | App-only | Embed the same kernel in the App runtime | | App + CLI + scheduler, or concurrent clients | One managed local authority daemon; clients connect to the active writer | -| Migration while Python remains the CLI | One idle-exiting loopback runtime bridges Python to the migrated TS kernel | +| Migration while Python remains the CLI | An idle-exiting loopback runtime bridges Python to the migrated TS kernel by default. On POSIX, an explicit stdio setting uses a child process owned by each CLI invocation. | If an authority daemon owns a registry/workspace, a CLI process must connect to it instead of opening a second direct writer. Runtime discovery and startup @@ -2017,6 +2017,13 @@ regression covers first ping and typed write, then abrupt exit and receipt replay. This repair preserves lock reclaim ages, startup deadlines and retry classification; broader process/storage recovery remains separately qualified. +The stdio bridge lets the Python CLI and its settlement subprocess run when +the host denies local sockets. It shares the typed dispatcher, bounded file +snapshots, authority provider and writer fences with the loopback bridge. +The caller authenticates the child before dispatch. Closing the pipe retires +the child after its current request. An ambiguous response requires reading +the exact durable receipt before any retry. + ### 2.3 TypeScript owns migrated effects The target is not “TypeScript decides, Python always executes”. TypeScript may diff --git a/docs/architecture/rfcs/typescript-control-plane-migration-v0.zh-CN.md b/docs/architecture/rfcs/typescript-control-plane-migration-v0.zh-CN.md index 30eaee9601..748d294ec9 100644 --- a/docs/architecture/rfcs/typescript-control-plane-migration-v0.zh-CN.md +++ b/docs/architecture/rfcs/typescript-control-plane-migration-v0.zh-CN.md @@ -1439,7 +1439,7 @@ handler 不会新增 server。 | TS CLI cutover 后的 CLI-only | CLI 进程内 import 并执行 TS kernel;没有 daemon | | 仅 App | App runtime 内嵌同一 kernel | | App + CLI + scheduler,或多个并发 client | 一个 managed local authority daemon;client 连接当前 writer | -| Python 仍是 CLI 的迁移期 | 一个 idle-exiting loopback runtime 把 Python 桥接到已迁 TS kernel | +| Python 仍是 CLI 的迁移期 | 默认由空闲退出的回环 runtime 把 Python 桥接到已迁 TS kernel。POSIX 可显式选择由每个 CLI 进程持有的标准输入输出子进程。 | 如果 authority daemon 已拥有某个 registry/workspace,CLI 必须连接它,而不能 绕过它再打开第二个直接 writer。Runtime discovery 与启动全自动;用户无需配置 @@ -1452,6 +1452,11 @@ handler 不会新增 server。 并验证替代 runtime 写入和回执重放;锁的 stale age、启动预算、认证、writer 权限 和重试分类均保持不变。这只关闭该发布顺序缺口,不代表长期运维或跨平台资格完成。 +宿主禁止本地 socket 时,Python CLI 和它启动的结算子进程可用标准输入输出 +桥接。同一套类型化分派、限长文件快照、权威存储与写入栅栏适用于两种传输。 +调用方先认证子进程,再发送业务请求。管道关闭后,子进程完成当前请求再退出。 +响应不明确时,重试前先读取该操作的确切持久回执。 + ### 2.3 TypeScript 拥有已迁 effect 目标不是“TypeScript 决策、Python 永远执行”。TypeScript 可以拥有 atomic diff --git a/docs/product/runtimes/codex-cli/codex-cli-tui-loop.md b/docs/product/runtimes/codex-cli/codex-cli-tui-loop.md index 2b3a241af2..18b7a566b8 100644 --- a/docs/product/runtimes/codex-cli/codex-cli-tui-loop.md +++ b/docs/product/runtimes/codex-cli/codex-cli-tui-loop.md @@ -76,6 +76,14 @@ do not migrate existing automations. Existing authority and cadence floors remai LoopX should be the control plane. Codex CLI should remain the executor and the user's live console. +When the Codex sandbox blocks loopback TCP on macOS or Linux, set +`LOOPX_EFFECT_RUNTIME_TRANSPORT=stdio` in the shell that starts Codex. +LoopX commands and their settlement subprocesses inherit the setting. Run +`loopx doctor --deep` from that environment to verify the Node/SQLite runtime. +The CLI uses the configured authority store and needs write access to the +project state and its normal temporary directory for large snapshots. +Launch Codex with the setting unset to use the default loopback bridge. + ## Operating Modes ### 1. TUI Bootstrap diff --git a/loopx/control_plane/coordination/sqlite_runtime.ts b/loopx/control_plane/coordination/sqlite_runtime.ts index 62882ea835..8bbdb7ea6f 100644 --- a/loopx/control_plane/coordination/sqlite_runtime.ts +++ b/loopx/control_plane/coordination/sqlite_runtime.ts @@ -86,7 +86,8 @@ let cached: {driver: typeof import("node:sqlite"); info: SqliteRuntimeInfo} | un */ function servingManagedRuntime(): boolean { const token = process.env.LOOPX_EFFECT_RUNTIME_TOKEN; - return typeof token === "string" && token.length > 0; + return typeof token === "string" && token.length > 0 && + process.env.LOOPX_EFFECT_RUNTIME_TRANSPORT !== "stdio"; } /** Probe only an in-memory database before any authority path is created. */ diff --git a/loopx/control_plane/effect_runtime.py b/loopx/control_plane/effect_runtime.py index cd12ec2df0..1171723ee3 100644 --- a/loopx/control_plane/effect_runtime.py +++ b/loopx/control_plane/effect_runtime.py @@ -1,5 +1,6 @@ from __future__ import annotations +import atexit import errno import hashlib import json @@ -26,7 +27,7 @@ from .runtime.file_reads import iter_binary_file_reads from .runtime.private_permissions import protect_private_path, require_private_path from .runtime.node_probe import ( - HOST_PERMISSION_RECOMMENDATION, + HOST_PERMISSION_RECOMMENDATION as HOST_PERMISSION_RECOMMENDATION, MINIMUM_NODE_VERSION as MINIMUM_NODE_VERSION, MINIMUM_NODE_VERSION_TEXT as MINIMUM_NODE_VERSION_TEXT, STARTUP_READY_TIMEOUT_SECONDS as STARTUP_READY_TIMEOUT_SECONDS, @@ -34,6 +35,22 @@ probe_node as _probe_node, ) from .content_digest import BARE_SHA256_PATTERN +from .runtime.effect_client_errors import ( + EffectRuntimeConflict as EffectRuntimeConflict, + EffectRuntimeHostPermissionError as EffectRuntimeHostPermissionError, + EffectRuntimeInternalError as EffectRuntimeInternalError, + EffectRuntimeIOError as EffectRuntimeIOError, + EffectRuntimeLockTimeout as EffectRuntimeLockTimeout, + EffectRuntimeNodeProbeError as EffectRuntimeNodeProbeError, + EffectRuntimePermanentIOError as EffectRuntimePermanentIOError, + EffectRuntimeRejected as EffectRuntimeRejected, + EffectRuntimeRemoteError as EffectRuntimeRemoteError, + EffectRuntimeResponseAmbiguous as EffectRuntimeResponseAmbiguous, + EffectRuntimeStartupError as EffectRuntimeStartupError, + EffectRuntimeTransientIOError as EffectRuntimeTransientIOError, + _remote_runtime_error, +) +from .runtime.stdio_transport import EffectRuntimeStdio EFFECT_RUNTIME_REQUEST_SCHEMA_VERSION = "loopx_effect_runtime_request_v0" EFFECT_RUNTIME_RESPONSE_SCHEMA_VERSION = "loopx_effect_runtime_response_v1" @@ -176,152 +193,6 @@ def todo_projection_request_identity() -> object | None: return state if state is not None and not state._closed else None -class EffectRuntimeRemoteError(RuntimeError): - """A typed exception returned by the managed TypeScript runtime.""" - - def __init__( - self, - message: str, - *, - error_kind: str, - diagnostic_code: str, - ) -> None: - super().__init__(message) - self.error_kind = error_kind - self.diagnostic_code = diagnostic_code - - -class EffectRuntimeRejected(EffectRuntimeRemoteError): - """A typed request reached the runtime but failed semantic validation.""" - - def __init__( - self, - message: str, - *, - diagnostic_code: str = "invalid_request", - details: tuple[str, ...] = (), - ) -> None: - super().__init__( - message, - error_kind="request_rejected", - diagnostic_code=diagnostic_code, - ) - self.details = details - - -class EffectRuntimeConflict(EffectRuntimeRemoteError): - """The request conflicted with newer persisted state.""" - - def __init__(self, message: str, *, diagnostic_code: str) -> None: - super().__init__( - message, - error_kind="conflict", - diagnostic_code=diagnostic_code, - ) - - -class EffectRuntimeIOError(EffectRuntimeRemoteError): - """A managed runtime filesystem operation failed.""" - - def __init__( - self, - message: str, - *, - error_kind: str, - diagnostic_code: str, - transient: bool, - ) -> None: - super().__init__( - message, - error_kind=error_kind, - diagnostic_code=diagnostic_code, - ) - self.transient = transient - - -class EffectRuntimeTransientIOError(EffectRuntimeIOError): - """A retryable managed runtime filesystem operation failed.""" - - def __init__(self, message: str, *, diagnostic_code: str) -> None: - super().__init__( - message, - error_kind="io_transient", - diagnostic_code=diagnostic_code, - transient=True, - ) - - -class EffectRuntimePermanentIOError(EffectRuntimeIOError): - """A non-retryable managed runtime filesystem operation failed.""" - - def __init__(self, message: str, *, diagnostic_code: str) -> None: - super().__init__( - message, - error_kind="io_permanent", - diagnostic_code=diagnostic_code, - transient=False, - ) - - -class EffectRuntimeLockTimeout(EffectRuntimeRemoteError): - """A managed mutation lock could not be acquired before its deadline.""" - - def __init__(self, message: str, *, diagnostic_code: str) -> None: - super().__init__( - message, - error_kind="lock_timeout", - diagnostic_code=diagnostic_code, - ) - - -class EffectRuntimeInternalError(EffectRuntimeRemoteError): - """The managed handler failed outside a declared request or I/O error.""" - - def __init__(self, message: str, *, diagnostic_code: str) -> None: - super().__init__( - message, - error_kind="internal_failure", - diagnostic_code=diagnostic_code, - ) - - -class EffectRuntimeStartupError(RuntimeError): - """The managed runtime could not reach a request-serving state.""" - - def __init__(self, message: str, *, diagnostic_code: str) -> None: - super().__init__(message) - self.diagnostic_code = diagnostic_code - - -class EffectRuntimeHostPermissionError(EffectRuntimeStartupError): - """The host denied local runtime access before any request was dispatched.""" - - recommended_action = HOST_PERMISSION_RECOMMENDATION - - def __init__(self) -> None: - super().__init__( - "Host permission denied access to the local TypeScript Effect runtime " - "before request dispatch; no capability operation was executed", - diagnostic_code="runtime_host_permission_denied", - ) - - -class EffectRuntimeNodeProbeError(EffectRuntimeStartupError): - """A pre-dispatch toolchain observation requires caller recovery.""" - - -class EffectRuntimeResponseAmbiguous(EffectRuntimeStartupError): - """The request may have executed even though its response was lost.""" - - def __init__(self, method: str, *, timeout: float) -> None: - super().__init__( - f"TypeScript Effect runtime returned no verifiable response for {method} " - f"(request budget {timeout:g}s); the operation may have committed. Read its exact " - "durable receipt before any retry", - diagnostic_code="runtime_response_ambiguous", - ) - - def _control_plane_root() -> Path: return Path(__file__).resolve().parent @@ -594,6 +465,33 @@ def _node_executable() -> str: return probe.executable +def _runtime_environment(token: str) -> dict[str, str]: + environment = os.environ.copy() + environment["LOOPX_EFFECT_RUNTIME_TOKEN"] = token + # Fixed launch context. Snapshot ACL checks on Windows also use this interpreter. + environment["LOOPX_EFFECT_RUNTIME_PYTHON"] = sys.executable + environment["LOOPX_EFFECT_RUNTIME_PYTHON_BIN"] = sys.executable + return environment + + +def _uses_stdio_runtime() -> bool: + transport = os.environ.get("LOOPX_EFFECT_RUNTIME_TRANSPORT", "tcp") + if transport == "tcp": + return False + if transport != "stdio": + raise EffectRuntimeStartupError( + "Set LOOPX_EFFECT_RUNTIME_TRANSPORT to stdio or tcp", + diagnostic_code="invalid_runtime_transport", + ) + if os.name != "posix": + raise EffectRuntimeStartupError( + "The Effect runtime stdio transport requires POSIX pipes. Set " + "LOOPX_EFFECT_RUNTIME_TRANSPORT to tcp on this platform", + diagnostic_code="unsupported_runtime_transport", + ) + return True + + def _pid_is_alive(value: object) -> bool: return process_is_alive(value) @@ -902,6 +800,8 @@ def restart_effect_runtime(*, timeout: float = 5.0, wait_for_exit: bool = False) exit-time cache write, whereas filesystem cleanup requires observed exit. """ + if _uses_stdio_runtime(): + return _restart_stdio_runtime(timeout) fingerprint = _runtime_fingerprint() info_path = _runtime_info_path(fingerprint) info = _runtime_info_for_request(info_path, fingerprint=fingerprint) @@ -991,6 +891,34 @@ def _encode_rpc_json(value: Mapping[str, Any]) -> bytes: ) +def _tcp_response_frame( + info: Mapping[str, Any], encoded: bytes, *, method: str, timeout: float, +) -> bytes: + chunks: list[bytes] = [] + size = 0 + try: + connection = socket.create_connection( + (str(info["host"]), int(info["port"])), timeout=timeout + ) + except PermissionError as exc: + raise EffectRuntimeHostPermissionError() from exc + with connection: + try: + connection.settimeout(timeout) + # sendall can fail after dispatch. From here a retry needs a receipt. + connection.sendall(encoded) + while chunk := connection.recv(64 * 1024): + chunks.append(chunk) + size += len(chunk) + if size > MAX_RESPONSE_BYTES: + raise RuntimeError("TypeScript Effect runtime response is oversized") + if b"\n" in chunk: + break + except (OSError, RuntimeError) as exc: + raise EffectRuntimeResponseAmbiguous(method, timeout=timeout) from exc + return b"".join(chunks) + + def _request_with_info( info: Mapping[str, Any], *, @@ -999,6 +927,7 @@ def _request_with_info( params: Mapping[str, Any], timeout: float, large_local_snapshot: bool = False, + pipe: EffectRuntimeStdio | None = None, ) -> dict[str, Any]: request = { "schema_version": EFFECT_RUNTIME_REQUEST_SCHEMA_VERSION, @@ -1051,34 +980,15 @@ def _request_with_info( "TypeScript Effect runtime request is oversized", diagnostic_code="request_too_large", ) - chunks: list[bytes] = [] - size = 0 - try: - connection = socket.create_connection( - (str(info["host"]), int(info["port"])), timeout=timeout - ) - except PermissionError as exc: - raise EffectRuntimeHostPermissionError() from exc - with connection: + if pipe is None: + frame = _tcp_response_frame(info, encoded, method=method, timeout=timeout) + else: try: - connection.settimeout(timeout) - # sendall may have delivered a prefix before it raises. From this - # point onward the caller cannot prove that no effect ran. - connection.sendall(encoded) - while True: - chunk = connection.recv(64 * 1024) - if not chunk: - break - chunks.append(chunk) - size += len(chunk) - if size > MAX_RESPONSE_BYTES: - raise RuntimeError("TypeScript Effect runtime response is oversized") - if b"\n" in chunk: - break - except (OSError, RuntimeError) as exc: + frame = pipe.exchange(encoded, timeout, MAX_RESPONSE_BYTES) + except (OSError, EOFError, ValueError) as exc: raise EffectRuntimeResponseAmbiguous(method, timeout=timeout) from exc try: - response = json.loads(b"".join(chunks).split(b"\n", 1)[0]) + response = json.loads(frame.split(b"\n", 1)[0]) except (ValueError, RecursionError): # Decoder limits can fail after commit; they cannot authorize a retry. raise EffectRuntimeResponseAmbiguous(method, timeout=timeout) from None @@ -1245,54 +1155,6 @@ def _read_local_snapshot_response( raise EffectRuntimeResponseAmbiguous(method, timeout=timeout) from exc -def _remote_runtime_error(value: object) -> EffectRuntimeRemoteError: - if not isinstance(value, Mapping): - return EffectRuntimeInternalError( - "TypeScript Effect runtime returned an invalid error envelope", - diagnostic_code="invalid_error_envelope", - ) - kind = value.get("kind") - code = value.get("code") - message = value.get("message") - if ( - not isinstance(kind, str) - or not kind - or not isinstance(code, str) - or not code - ): - return EffectRuntimeInternalError( - "TypeScript Effect runtime returned an invalid error envelope", - diagnostic_code="invalid_error_envelope", - ) - rendered = " ".join( - str(message or "TypeScript Effect runtime request failed").split() - ) - rendered = rendered[:240] or "TypeScript Effect runtime request failed" - if kind == "request_rejected": - details = value.get("details", []) - if (not isinstance(details, list) or len(details) > 128 - or any(not isinstance(detail, str) or len(detail) > 240 for detail in details)): - return EffectRuntimeInternalError( - "TypeScript Effect runtime returned invalid request validation details", - diagnostic_code="invalid_error_envelope", - ) - return EffectRuntimeRejected(rendered, diagnostic_code=code, details=tuple(details)) - if kind == "conflict": - return EffectRuntimeConflict(rendered, diagnostic_code=code) - if kind == "io_transient": - return EffectRuntimeTransientIOError(rendered, diagnostic_code=code) - if kind == "io_permanent": - return EffectRuntimePermanentIOError(rendered, diagnostic_code=code) - if kind == "lock_timeout": - return EffectRuntimeLockTimeout(rendered, diagnostic_code=code) - if kind == "internal_failure": - return EffectRuntimeInternalError(rendered, diagnostic_code=code) - return EffectRuntimeInternalError( - "TypeScript Effect runtime returned an unsupported error kind", - diagnostic_code="unsupported_error_kind", - ) - - def _read_startup_stderr(capture: IO[bytes]) -> bytes: """Return the bounded stderr a managed runtime wrote before it exited.""" @@ -1450,12 +1312,7 @@ def _start_runtime(*, fingerprint: str, info_path: Path) -> dict[str, Any]: if existing is not None: return existing token = secrets.token_urlsafe(32) - environment = os.environ.copy() - environment["LOOPX_EFFECT_RUNTIME_TOKEN"] = token - # Fixed daemon context, never a model-supplied executable argument. - environment["LOOPX_EFFECT_RUNTIME_PYTHON"] = sys.executable - # Windows snapshot ACL facts use this parent-selected interpreter only. - environment["LOOPX_EFFECT_RUNTIME_PYTHON_BIN"] = sys.executable + environment = _runtime_environment(token) # Capture stderr so a rejected startup can publish a typed # startup diagnostic instead of a bare exit status. The capture # is an unlinked temporary file, so it cannot deadlock the child on a @@ -1545,6 +1402,156 @@ def _start_runtime(*, fingerprint: str, info_path: Path) -> dict[str, Any]: lock.unlink(missing_ok=True) +@dataclass(frozen=True) +class _StdioRuntime: + fingerprint: str + token: str + pipe: EffectRuntimeStdio + identity: dict[str, Any] | None + + +_stdio_runtime: _StdioRuntime | None = None +_stdio_runtime_lock = Lock() + + +def _reset_stdio_runtime_after_fork() -> None: + global _stdio_runtime, _stdio_runtime_lock + if _stdio_runtime is not None: + _stdio_runtime.pipe.close() + _stdio_runtime = None + _stdio_runtime_lock = Lock() + + +if hasattr(os, "register_at_fork"): + os.register_at_fork(after_in_child=_reset_stdio_runtime_after_fork) + + +@atexit.register +def _close_stdio_runtime_at_exit() -> None: + if _stdio_runtime is not None: + _stdio_runtime.pipe.close(wait_seconds=0.2) + + +def _start_stdio_runtime(fingerprint: str) -> _StdioRuntime: + token = secrets.token_urlsafe(32) + try: + pipe = EffectRuntimeStdio( + [ + _node_executable(), + "--no-warnings", + "--experimental-strip-types", + str(_control_plane_root() / "effect_runtime_stdio.ts"), + fingerprint, + ], + _runtime_environment(token), + ) + except PermissionError as exc: + raise EffectRuntimeHostPermissionError() from exc + except OSError as exc: + raise EffectRuntimeStartupError( + "TypeScript Effect runtime process could not be launched", + diagnostic_code="runtime_launch_failed", + ) from exc + try: + ping = _request_with_info( + {"token": token}, + request_id=str(uuid.uuid4()), + method="runtime.ping", + params={}, + timeout=STARTUP_READY_TIMEOUT_SECONDS, + pipe=pipe, + ).get("result") + if ( + not isinstance(ping, Mapping) + or ping.get("ready") is not True + or ping.get("pid") != pipe.pid + or ping.get("fingerprint") != fingerprint + ): + raise EffectRuntimeStartupError( + "TypeScript Effect runtime returned an invalid process identity", + diagnostic_code="semantic_probe_shape_mismatch", + ) + except (EffectRuntimeRemoteError, EffectRuntimeResponseAmbiguous) as exc: + pipe.close(reap_in_background=True) + # The readiness exchange is read-only. No caller effect has been sent. + raise EffectRuntimeStartupError( + "TypeScript Effect runtime did not become ready over stdio", + diagnostic_code="runtime_exited_before_ready", + ) from exc + except BaseException: + pipe.close(reap_in_background=True) + raise + return _StdioRuntime(fingerprint, token, pipe, runtime_identity_from_info(ping)) + + +@contextmanager +def _stdio_runtime_access(timeout: float) -> Iterator[None]: + if not _stdio_runtime_lock.acquire(timeout=timeout): + raise EffectRuntimeStartupError( + "TypeScript Effect runtime was busy before request dispatch", + diagnostic_code="runtime_request_timeout", + ) + try: + yield + finally: + _stdio_runtime_lock.release() + + +def _request_stdio_runtime( + fingerprint: str, *, request_id: str, method: str, params: Mapping[str, Any], + timeout: float, large_local_snapshot: bool, +) -> dict[str, Any]: + global _stdio_runtime + with _stdio_runtime_access(timeout): + runtime = _stdio_runtime + if runtime is None or runtime.fingerprint != fingerprint or not runtime.pipe.alive: + if runtime is not None: + runtime.pipe.close(reap_in_background=True) + _stdio_runtime = None + runtime = _start_stdio_runtime(fingerprint) + _stdio_runtime = runtime + try: + response = _request_with_info( + {"token": runtime.token}, + request_id=request_id, + method=method, + params=params, + timeout=timeout, + large_local_snapshot=large_local_snapshot, + pipe=runtime.pipe, + ) + except (EffectRuntimeResponseAmbiguous, KeyboardInterrupt, SystemExit): + runtime.pipe.close(reap_in_background=True) + _stdio_runtime = None + raise + if method == "runtime.shutdown": + runtime.pipe.close(reap_in_background=True) + _stdio_runtime = None + return response + + +def _restart_stdio_runtime(timeout: float) -> dict[str, Any]: + global _stdio_runtime + with _stdio_runtime_access(timeout): + runtime = _stdio_runtime + _stdio_runtime = None + was_running = runtime is not None and runtime.pipe.alive + stopped = runtime is not None and runtime.pipe.close( + wait_seconds=timeout, reap_in_background=True, + ) + status = "not_running" + if was_running: + status = "stopped" if stopped else "shutdown_pending" + return { + "schema_version": EFFECT_RUNTIME_RESTART_SCHEMA_VERSION, + "status": status, + "stopped": was_running and stopped, + "previous_runtime_identity": runtime.identity if runtime is not None else None, + "info_path": None, + "transport": "stdio", + } + + def effect_runtime_request( method: str, params: Mapping[str, Any], @@ -1555,9 +1562,19 @@ def effect_runtime_request( ) -> dict[str, Any]: """Call the managed TS runtime, retrying only idempotent typed effects.""" + use_stdio = _uses_stdio_runtime() fingerprint = _runtime_fingerprint_for_request() - info_path = _runtime_info_path(fingerprint) request_id = str(uuid.uuid4()) + if use_stdio: + return _request_stdio_runtime( + fingerprint, + request_id=request_id, + method=method, + params=params, + timeout=timeout, + large_local_snapshot=large_local_snapshot, + ) + info_path = _runtime_info_path(fingerprint) last_error: OSError | RuntimeError | None = None for attempt in range(2 if retry_safe else 1): info: dict[str, Any] | None = None @@ -1706,11 +1723,20 @@ def _serving_runtime_identity() -> dict[str, Any] | None: return runtime_identity_from_info(info) -def _sqlite_restart_recommendation(identity: Mapping[str, Any] | None) -> str | None: +def _sqlite_restart_recommendation( + identity: Mapping[str, Any] | None, *, process_scoped: bool = False, +) -> str | None: """Name the repair for a serving runtime that cannot run SQLite authority.""" if identity is None or identity.get("sqlite_authority_qualified") is True: return None + if process_scoped: + return ( + "The stdio Effect runtime uses Node " + f"{identity.get('node_version')} with SQLite " + f"{identity.get('sqlite_version')}. Rerun this command on a PATH " + "with qualified Node 22.22.3 or newer to use SQLite authority." + ) # The File path is ready but the SQLite authority lane is not: the serving # runtime keeps its own Node, so installing Node alone would not repair it. return ( @@ -1735,15 +1761,26 @@ def collect_effect_runtime_readiness(*, deep: bool = False) -> dict[str, object] locator_state: _RuntimeLocatorState = "missing" recorded_pid_alive: bool | None = None host_permission_error: EffectRuntimeHostPermissionError | None = None + transport_recommendation: str | None = None locator_info: dict[str, Any] | None = None + use_stdio = False + live_stdio: _StdioRuntime | None = None try: + use_stdio = _uses_stdio_runtime() fingerprint = _runtime_fingerprint() - ( - locator_state, - recorded_pid_alive, - locator_read_diagnostic, - locator_info, - ) = _inspect_runtime_locator(fingerprint, recover=True) + locator_read_diagnostic = None + if use_stdio: + runtime = _stdio_runtime + if runtime is not None and runtime.fingerprint == fingerprint and runtime.pipe.alive: + live_stdio = runtime + recorded_pid_alive = True + else: + ( + locator_state, + recorded_pid_alive, + locator_read_diagnostic, + locator_info, + ) = _inspect_runtime_locator(fingerprint, recover=True) except EffectRuntimeHostPermissionError as exc: locator_state = "invalid" if ready: @@ -1754,31 +1791,40 @@ def collect_effect_runtime_readiness(*, deep: bool = False) -> dict[str, object] except (OSError, EffectRuntimeStartupError) as exc: if ready: ready = False - status = "package_invalid" runtime_diagnostic_code = getattr( exc, "diagnostic_code", "packaged_runtime_source_unreadable", ) + if runtime_diagnostic_code in {"invalid_runtime_transport", "unsupported_runtime_transport"}: + status = "probe_failed" + transport_recommendation = str(exc) + else: + status = "package_invalid" else: if ready: runtime_diagnostic_code = ( locator_read_diagnostic or runtime_diagnostic_code ) if ready: - runtime_state = "running" if locator_info is not None else "stopped" - runtime_identity = runtime_identity_from_info(locator_info) + runtime_state = "running" if live_stdio is not None or locator_info is not None else "stopped" + runtime_identity = ( + live_stdio.identity if live_stdio is not None + else runtime_identity_from_info(locator_info) + ) runtime_lifecycle: dict[str, object] = { "schema_version": "loopx_effect_runtime_lifecycle_v0", "management": "on_demand_managed", "state": runtime_state, "manual_start_required": False, "restart_policy": "automatic_on_next_control_plane_request", - "idle_shutdown": True, + "idle_shutdown": not use_stdio, "diagnostic_code": runtime_diagnostic_code, "locator_state": locator_state, "recorded_pid_alive": recorded_pid_alive, } + if use_stdio: + runtime_lifecycle["transport"] = "stdio" result: dict[str, object] = { "schema_version": EFFECT_RUNTIME_READINESS_SCHEMA_VERSION, "ready": ready, @@ -1795,13 +1841,13 @@ def collect_effect_runtime_readiness(*, deep: bool = False) -> dict[str, object] if host_permission_error is not None else None if ready - else probe.recommended_action + else transport_recommendation or probe.recommended_action or "Repair the packaged LoopX runtime, then rerun `loopx doctor --deep`." ), } if ready: result["recommended_action"] = ( - _sqlite_restart_recommendation(runtime_identity) + _sqlite_restart_recommendation(runtime_identity, process_scoped=use_stdio) or result["recommended_action"] ) if not ready or not deep: @@ -1822,11 +1868,16 @@ def collect_effect_runtime_readiness(*, deep: bool = False) -> dict[str, object] ) except RuntimeError as exc: probe_error = exc - ( - locator_state, - recorded_pid_alive, - post_probe_diagnostic, - ) = _locator_projection_after_probe(fingerprint) + if use_stdio: + runtime = _stdio_runtime + recorded_pid_alive = runtime is not None and runtime.pipe.alive + post_probe_diagnostic = None + else: + ( + locator_state, + recorded_pid_alive, + post_probe_diagnostic, + ) = _locator_projection_after_probe(fingerprint) if probe_error is not None: diagnostic_code = getattr( probe_error, @@ -1880,7 +1931,10 @@ def collect_effect_runtime_readiness(*, deep: bool = False) -> dict[str, object] } # The probe just started the runtime, so its identity is only readable now; # report the Node/SQLite pair that will serve the following requests. - serving_identity = _serving_runtime_identity() or runtime_identity + serving_identity = ( + runtime_identity_from_info(ping) if use_stdio + else _serving_runtime_identity() + ) or runtime_identity return { **result, "semantic_probe": "passed", @@ -1893,7 +1947,7 @@ def collect_effect_runtime_readiness(*, deep: bool = False) -> dict[str, object] "recorded_pid_alive": recorded_pid_alive, }, "recommended_action": ( - _sqlite_restart_recommendation(serving_identity) + _sqlite_restart_recommendation(serving_identity, process_scoped=use_stdio) or result["recommended_action"] ), } diff --git a/loopx/control_plane/effect_runtime_exchange.ts b/loopx/control_plane/effect_runtime_exchange.ts new file mode 100644 index 0000000000..4ed054db1d --- /dev/null +++ b/loopx/control_plane/effect_runtime_exchange.ts @@ -0,0 +1,127 @@ +import type { FileHandle } from "node:fs/promises"; + +import type { JsonObject } from "./effect_program.ts"; +import { + type EffectRuntimeHandler, + dispatchEffectRuntimeMethod, +} from "./effect_runtime_handlers.ts"; +import { + EffectRuntimeRequestError, + effectRuntimeErrorPayload, +} from "./effect_runtime_errors.ts"; +import { + MAX_INLINE_RESPONSE_BYTES, + openPrivateResponseSink, + readPrivateJsonSnapshot, + writePrivateResponse, +} from "./effect_runtime_snapshot.ts"; +import localSnapshotMethods from "./effect_runtime_snapshot_methods.json" with { type: "json" }; +import { + requireJsonObject as requiredObject, + requireNonEmptyString as requiredString, +} from "./runtime_decode.ts"; + +const REQUEST_SCHEMA = "loopx_effect_runtime_request_v0"; +const RESPONSE_SCHEMA = "loopx_effect_runtime_response_v1"; +export const MAX_REQUEST_BYTES = 8 * 1024 * 1024; +// Transport eligibility stays shared with the caller. The selected handler owns authority. +const LOCAL_SNAPSHOT_METHODS = new Set(localSnapshotMethods); + +function asParams(value: unknown): JsonObject { + return typeof value === "object" && value !== null && !Array.isArray(value) + ? (value as JsonObject) + : {}; +} + +function encode(value: JsonObject): Buffer { + return Buffer.from(`${JSON.stringify(value)}\n`); +} + +function failure(requestId: string, error: unknown): JsonObject { + return { + schema_version: RESPONSE_SCHEMA, + request_id: requestId, + ok: false, + error: effectRuntimeErrorPayload(error), + }; +} + +export function oversizedEffectRuntimeRequest(): Buffer { + return encode(failure("unknown", new EffectRuntimeRequestError( + "Effect runtime request exceeds the 8 MiB limit", + "request_too_large", + ))); +} + +async function encodeResponse(response: JsonObject, sink: FileHandle | null): Promise { + const encoded = encode(response); + if (encoded.length <= MAX_INLINE_RESPONSE_BYTES) return encoded; + // A success may already be durable. Return no frame when the existing + // bounded snapshot path cannot deliver it, so callers recover its receipt. + if (sink === null) return null; + return encode({ + schema_version: RESPONSE_SCHEMA, + request_id: response.request_id, + ok: true, + result_ref: await writePrivateResponse(sink, encoded), + }); +} + +export async function exchangeEffectRuntimeRequest( + line: string, token: string, handlers: ReadonlyMap, +): Promise { + let requestId = "unknown"; + let sink: FileHandle | null = null; + let response: JsonObject; + try { + let parsed: unknown; + try { + parsed = JSON.parse(line); + } catch { + throw new EffectRuntimeRequestError( + "Effect runtime request is not valid JSON", + "malformed_json", + ); + } + const request = requiredObject(parsed, "Effect runtime request"); + requestId = requiredString(request.request_id, "request_id"); + if (request.schema_version !== REQUEST_SCHEMA || request.token !== token) { + throw new EffectRuntimeRequestError( + "Effect runtime request authentication failed", + "authentication_failed", + ); + } + const method = requiredString(request.method, "method"); + if (request.params_ref !== undefined || request.response_sink !== undefined) { + if (!LOCAL_SNAPSHOT_METHODS.has(method) || request.response_sink === undefined || + (request.params_ref !== undefined && request.params !== undefined)) { + throw new EffectRuntimeRequestError("local snapshot transport is unavailable for this request"); + } + sink = await openPrivateResponseSink(request.response_sink); + } + let params: JsonObject; + if (request.params_ref !== undefined) { + const ref = requiredObject(request.params_ref, "params snapshot reference"); + if (ref.schema_version !== "loopx_effect_runtime_snapshot_v0") { + throw new EffectRuntimeRequestError("invalid local snapshot schema"); + } + params = requiredObject(await readPrivateJsonSnapshot(ref), "snapshot params"); + } else { + params = asParams(request.params); + } + const result = await dispatchEffectRuntimeMethod(handlers, method, params); + response = { + schema_version: RESPONSE_SCHEMA, + request_id: requestId, + ok: true, + result, + }; + } catch (error) { + response = failure(requestId, error); + } + try { + return await encodeResponse(response, sink); + } finally { + await sink?.close(); + } +} diff --git a/loopx/control_plane/effect_runtime_handlers.ts b/loopx/control_plane/effect_runtime_handlers.ts index 6fbe7ec4ab..927d4e80b6 100644 --- a/loopx/control_plane/effect_runtime_handlers.ts +++ b/loopx/control_plane/effect_runtime_handlers.ts @@ -26,6 +26,7 @@ import { } from "./effect_program.ts"; import { EffectRuntimeRequestError } from "./effect_runtime_errors.ts"; +import type { SqliteRuntimeIdentity } from "./coordination/sqlite_runtime.ts"; import { optionalNonEmptyString as optionalString, requireBoolean, @@ -38,7 +39,7 @@ import { import type {TurnJournalInspectionRequest} from "./turn_driver/turn_journal.ts"; -type EffectRuntimeHandler = (params: JsonObject) => unknown | Promise; +export type EffectRuntimeHandler = (params: JsonObject) => unknown | Promise; // Resolve only the selected module/handler, never cache its params or decision. // Node owns module caching; the existing runtime fingerprint owns invalidation. @@ -57,6 +58,7 @@ export interface EffectRuntimeHandlerContext { fingerprint: string; /** Physical publication path observed by the managed server, not its caller. */ readonly infoPath?: string; + readonly localRuntimeIdentity?: SqliteRuntimeIdentity; requestShutdown: () => void; } @@ -254,7 +256,9 @@ export function createEffectRuntimeHandlers( [ "runtime.ping", () => ({ ready: true, pid: process.pid, fingerprint: context.fingerprint, - ...(context.infoPath === undefined ? {} : {info_path: context.infoPath}) }), + ...(context.infoPath === undefined ? {} : {info_path: context.infoPath}), + ...(context.localRuntimeIdentity === undefined + ? {} : {runtime_identity: context.localRuntimeIdentity}) }), ], [ "runtime.shutdown", diff --git a/loopx/control_plane/effect_runtime_server.ts b/loopx/control_plane/effect_runtime_server.ts index 1dacb9e7e8..f632c7af47 100644 --- a/loopx/control_plane/effect_runtime_server.ts +++ b/loopx/control_plane/effect_runtime_server.ts @@ -1,33 +1,21 @@ import { writeSync } from "node:fs"; import { createServer, type Socket } from "node:net"; -import { realpath, type FileHandle } from "node:fs/promises"; +import { realpath } from "node:fs/promises"; -import type { JsonObject } from "./effect_program.ts"; -import localSnapshotMethods from "./effect_runtime_snapshot_methods.json" with { type: "json" }; +import { createEffectRuntimeHandlers } from "./effect_runtime_handlers.ts"; import { - createEffectRuntimeHandlers, - dispatchEffectRuntimeMethod, -} from "./effect_runtime_handlers.ts"; -import { - EffectRuntimeRequestError, - effectRuntimeErrorPayload, -} from "./effect_runtime_errors.ts"; + exchangeEffectRuntimeRequest, + MAX_REQUEST_BYTES, + oversizedEffectRuntimeRequest, +} from "./effect_runtime_exchange.ts"; +import { effectRuntimeErrorPayload } from "./effect_runtime_errors.ts"; import { atomicWriteJson, withFileMutationLock } from "./effect_runtime_io.ts"; import { retireRuntime } from "./effect_runtime_compile_cache.ts"; import { sqliteRuntimeIdentity } from "./coordination/sqlite_runtime.ts"; -import {MAX_INLINE_RESPONSE_BYTES, openPrivateResponseSink, readPrivateJsonSnapshot, writePrivateResponse} from "./effect_runtime_snapshot.ts"; -import { - requireJsonObject as requiredObject, - requireNonEmptyString as requiredString, -} from "./runtime_decode.ts"; +import { requireNonEmptyString as requiredString } from "./runtime_decode.ts"; -const REQUEST_SCHEMA = "loopx_effect_runtime_request_v0"; -const RESPONSE_SCHEMA = "loopx_effect_runtime_response_v1"; const INFO_SCHEMA = "loopx_effect_runtime_info_v0"; const STARTUP_ERROR_SCHEMA = "loopx_effect_runtime_startup_error_v0"; -const MAX_REQUEST_BYTES = 8 * 1024 * 1024; -// Explicit opt-in: ordinary effects retain a bounded request/response wire. -const LOCAL_SNAPSHOT_METHODS = new Set(localSnapshotMethods); const DEFAULT_IDLE_MS = 5 * 60 * 1_000; // Bounds for LOOPX_EFFECT_RUNTIME_IDLE_MS. The upper bound is the largest // delay `setTimeout` accepts: a larger delay overflows and fires immediately, @@ -40,12 +28,6 @@ const INVALID_IDLE_TIMEOUT_CODE = "invalid_idle_timeout"; const MAX_REPORTED_RAW_LENGTH = 32; let shutdownRequested = false; -function asObject(value: unknown): JsonObject { - return typeof value === "object" && value !== null && !Array.isArray(value) - ? (value as JsonObject) - : {}; -} - function parseArg(name: string): string { const index = process.argv.indexOf(name); if (index < 0 || index + 1 >= process.argv.length) { @@ -127,23 +109,6 @@ function resetIdleTimer(server: ReturnType): void { idleTimer.unref(); } -async function writeResponse(socket: Socket, response: JsonObject, sink: FileHandle | null): Promise { - const encoded = Buffer.from(`${JSON.stringify(response)}\n`); - if (encoded.length <= MAX_INLINE_RESPONSE_BYTES) { - socket.end(encoded); - return; - } - if (sink === null) { - // The operation may already have committed. Never downgrade a lost large - // response to a safe request rejection or retry it automatically. - socket.destroy(); - return; - } - const ref = await writePrivateResponse(sink, encoded); - socket.end(`${JSON.stringify({schema_version: RESPONSE_SCHEMA, - request_id: response.request_id, ok: true, result_ref: ref})}\n`); -} - const sockets = new Set(); const server = createServer((socket) => { sockets.add(socket); @@ -163,15 +128,7 @@ const server = createServer((socket) => { raw = ""; socket.pause(); socket.removeAllListeners("data"); - socket.end(`${JSON.stringify({ - schema_version: RESPONSE_SCHEMA, - request_id: "unknown", - ok: false, - error: effectRuntimeErrorPayload(new EffectRuntimeRequestError( - "Effect runtime request exceeds the 8 MiB limit", - "request_too_large", - )), - })}\n`); + socket.end(oversizedEffectRuntimeRequest()); return; } raw += chunk; @@ -182,86 +139,25 @@ const server = createServer((socket) => { pendingRequests += 1; clearTimeout(idleTimer); void (async () => { - let requestId = "unknown"; - let sink: FileHandle | null = null; - let dispatched = false; try { // The locator becomes visible inside the publication lock. A first // response must wait for its release: otherwise an immediate process // death can strand an incomplete cleanup claim before the next write. await publicationReady; - let parsed: unknown; - try { - parsed = JSON.parse( - raw.slice(0, raw.indexOf("\n")), - ); - } catch { - throw new EffectRuntimeRequestError( - "Effect runtime request is not valid JSON", - "malformed_json", - ); - } - const request = requiredObject(parsed, "Effect runtime request"); - requestId = requiredString(request.request_id, "request_id"); - if (request.schema_version !== REQUEST_SCHEMA || request.token !== token) { - throw new EffectRuntimeRequestError( - "Effect runtime request authentication failed", - "authentication_failed", - ); - } - const method = requiredString(request.method, "method"); - if (request.params_ref !== undefined || request.response_sink !== undefined) { - if (!LOCAL_SNAPSHOT_METHODS.has(method) || request.response_sink === undefined || - (request.params_ref !== undefined && request.params !== undefined)) { - throw new EffectRuntimeRequestError("local snapshot transport is unavailable for this request"); - } - sink = await openPrivateResponseSink(request.response_sink); - } - let params: JsonObject; - if (request.params_ref !== undefined) { - const ref = requiredObject(request.params_ref, "params snapshot reference"); - if (ref.schema_version !== "loopx_effect_runtime_snapshot_v0") { - throw new EffectRuntimeRequestError("invalid local snapshot schema"); - } - params = requiredObject(await readPrivateJsonSnapshot(ref), "snapshot params"); - } else { - params = asObject(request.params); - } - const result = await dispatchEffectRuntimeMethod( - handlers, - method, - params, + const frame = await exchangeEffectRuntimeRequest( + raw.slice(0, raw.indexOf("\n")), token, handlers, ); - dispatched = true; - await writeResponse(socket, { - schema_version: RESPONSE_SCHEMA, - request_id: requestId, - ok: true, - result, - }, sink); - } catch (error) { - if (dispatched) socket.destroy(); - else { - try { - await writeResponse(socket, { - schema_version: RESPONSE_SCHEMA, - request_id: requestId, - ok: false, - error: effectRuntimeErrorPayload(error), - }, sink); - } catch { socket.destroy(); } - } + if (frame === null) socket.destroy(); + else socket.end(frame); + } catch { + socket.destroy(); } finally { - try { - await sink?.close(); - } finally { - pendingRequests -= 1; - if (pendingRequests === 0) resolveDrain?.(); - // Stop accepting new work immediately on shutdown, but drain every - // already accepted handler, including those whose caller disconnected. - if (shutdownRequested && server.listening) server.close(); - resetIdleTimer(server); - } + pendingRequests -= 1; + if (pendingRequests === 0) resolveDrain?.(); + // Stop accepting new work immediately on shutdown, but drain every + // already accepted handler, including those whose caller disconnected. + if (shutdownRequested && server.listening) server.close(); + resetIdleTimer(server); } })(); }); diff --git a/loopx/control_plane/effect_runtime_stdio.ts b/loopx/control_plane/effect_runtime_stdio.ts new file mode 100644 index 0000000000..410e309d94 --- /dev/null +++ b/loopx/control_plane/effect_runtime_stdio.ts @@ -0,0 +1,52 @@ +import { createEffectRuntimeHandlers } from "./effect_runtime_handlers.ts"; +import { + exchangeEffectRuntimeRequest, + MAX_REQUEST_BYTES, + oversizedEffectRuntimeRequest, +} from "./effect_runtime_exchange.ts"; +import { sqliteRuntimeIdentity } from "./coordination/sqlite_runtime.ts"; +import { requireNonEmptyString } from "./runtime_decode.ts"; + +const fingerprint = requireNonEmptyString(process.argv[2], "runtime fingerprint"); +const token = requireNonEmptyString(process.env.LOOPX_EFFECT_RUNTIME_TOKEN, "runtime token"); +let stopping = false; +const handlers = createEffectRuntimeHandlers({ + fingerprint, + localRuntimeIdentity: sqliteRuntimeIdentity(), + requestShutdown: () => { stopping = true; }, +}); + +// A caller can disconnect while an admitted effect is still running. Finish +// that effect before observing the failed write and retiring this process. +process.stdout.on("error", () => undefined); +function reply(frame: Buffer): Promise { + return new Promise(resolve => process.stdout.write(frame, error => resolve(!error))); +} + +async function serve(): Promise { + let chunks: Buffer[] = []; + let bytes = 0; + for await (const chunk of process.stdin) { + let start = 0; + while (start < chunk.length) { + const end = chunk.indexOf(10, start); + const part = chunk.subarray(start, end === -1 ? chunk.length : end + 1) as Buffer; + bytes += part.length; + if (bytes > MAX_REQUEST_BYTES) { + await reply(oversizedEffectRuntimeRequest()); + return; + } + chunks.push(part); + if (end === -1) break; + const line = Buffer.concat(chunks, bytes).toString("utf8", 0, bytes - 1); + chunks = []; + bytes = 0; + const response = await exchangeEffectRuntimeRequest(line, token, handlers); + if (response === null) return; + if (!await reply(response) || stopping) return; + start = end + 1; + } + } +} + +await serve(); diff --git a/loopx/control_plane/runtime/effect_client_errors.py b/loopx/control_plane/runtime/effect_client_errors.py new file mode 100644 index 0000000000..5a045a754d --- /dev/null +++ b/loopx/control_plane/runtime/effect_client_errors.py @@ -0,0 +1,201 @@ +"""Typed error envelopes shared by the Effect runtime transports.""" + +from __future__ import annotations + +from collections.abc import Mapping + +from .node_probe import HOST_PERMISSION_RECOMMENDATION + + +class EffectRuntimeRemoteError(RuntimeError): + """A typed exception returned by the managed TypeScript runtime.""" + + def __init__( + self, + message: str, + *, + error_kind: str, + diagnostic_code: str, + ) -> None: + super().__init__(message) + self.error_kind = error_kind + self.diagnostic_code = diagnostic_code + + +class EffectRuntimeRejected(EffectRuntimeRemoteError): + """A typed request reached the runtime but failed semantic validation.""" + + def __init__( + self, + message: str, + *, + diagnostic_code: str = "invalid_request", + details: tuple[str, ...] = (), + ) -> None: + super().__init__( + message, + error_kind="request_rejected", + diagnostic_code=diagnostic_code, + ) + self.details = details + + +class EffectRuntimeConflict(EffectRuntimeRemoteError): + """The request conflicted with newer persisted state.""" + + def __init__(self, message: str, *, diagnostic_code: str) -> None: + super().__init__( + message, + error_kind="conflict", + diagnostic_code=diagnostic_code, + ) + + +class EffectRuntimeIOError(EffectRuntimeRemoteError): + """A managed runtime filesystem operation failed.""" + + def __init__( + self, + message: str, + *, + error_kind: str, + diagnostic_code: str, + transient: bool, + ) -> None: + super().__init__( + message, + error_kind=error_kind, + diagnostic_code=diagnostic_code, + ) + self.transient = transient + + +class EffectRuntimeTransientIOError(EffectRuntimeIOError): + """A retryable managed runtime filesystem operation failed.""" + + def __init__(self, message: str, *, diagnostic_code: str) -> None: + super().__init__( + message, + error_kind="io_transient", + diagnostic_code=diagnostic_code, + transient=True, + ) + + +class EffectRuntimePermanentIOError(EffectRuntimeIOError): + """A non-retryable managed runtime filesystem operation failed.""" + + def __init__(self, message: str, *, diagnostic_code: str) -> None: + super().__init__( + message, + error_kind="io_permanent", + diagnostic_code=diagnostic_code, + transient=False, + ) + + +class EffectRuntimeLockTimeout(EffectRuntimeRemoteError): + """A managed mutation lock could not be acquired before its deadline.""" + + def __init__(self, message: str, *, diagnostic_code: str) -> None: + super().__init__( + message, + error_kind="lock_timeout", + diagnostic_code=diagnostic_code, + ) + + +class EffectRuntimeInternalError(EffectRuntimeRemoteError): + """The managed handler failed outside a declared request or I/O error.""" + + def __init__(self, message: str, *, diagnostic_code: str) -> None: + super().__init__( + message, + error_kind="internal_failure", + diagnostic_code=diagnostic_code, + ) + + +class EffectRuntimeStartupError(RuntimeError): + """The managed runtime could not reach a request-serving state.""" + + def __init__(self, message: str, *, diagnostic_code: str) -> None: + super().__init__(message) + self.diagnostic_code = diagnostic_code + + +class EffectRuntimeHostPermissionError(EffectRuntimeStartupError): + """The host denied local runtime access before any request was dispatched.""" + + recommended_action = HOST_PERMISSION_RECOMMENDATION + + def __init__(self) -> None: + super().__init__( + "Host permission denied access to the local TypeScript Effect runtime " + "before request dispatch; no capability operation was executed", + diagnostic_code="runtime_host_permission_denied", + ) + + +class EffectRuntimeNodeProbeError(EffectRuntimeStartupError): + """A pre-dispatch toolchain observation requires caller recovery.""" + + +class EffectRuntimeResponseAmbiguous(EffectRuntimeStartupError): + """The request may have executed even though its response was lost.""" + + def __init__(self, method: str, *, timeout: float) -> None: + super().__init__( + f"TypeScript Effect runtime returned no verifiable response for {method} " + f"(request budget {timeout:g}s); the operation may have committed. Read its exact " + "durable receipt before any retry", + diagnostic_code="runtime_response_ambiguous", + ) + + +def _remote_runtime_error(value: object) -> EffectRuntimeRemoteError: + if not isinstance(value, Mapping): + return EffectRuntimeInternalError( + "TypeScript Effect runtime returned an invalid error envelope", + diagnostic_code="invalid_error_envelope", + ) + kind = value.get("kind") + code = value.get("code") + message = value.get("message") + if ( + not isinstance(kind, str) + or not kind + or not isinstance(code, str) + or not code + ): + return EffectRuntimeInternalError( + "TypeScript Effect runtime returned an invalid error envelope", + diagnostic_code="invalid_error_envelope", + ) + rendered = " ".join( + str(message or "TypeScript Effect runtime request failed").split() + ) + rendered = rendered[:240] or "TypeScript Effect runtime request failed" + if kind == "request_rejected": + details = value.get("details", []) + if (not isinstance(details, list) or len(details) > 128 + or any(not isinstance(detail, str) or len(detail) > 240 for detail in details)): + return EffectRuntimeInternalError( + "TypeScript Effect runtime returned invalid request validation details", + diagnostic_code="invalid_error_envelope", + ) + return EffectRuntimeRejected(rendered, diagnostic_code=code, details=tuple(details)) + if kind == "conflict": + return EffectRuntimeConflict(rendered, diagnostic_code=code) + if kind == "io_transient": + return EffectRuntimeTransientIOError(rendered, diagnostic_code=code) + if kind == "io_permanent": + return EffectRuntimePermanentIOError(rendered, diagnostic_code=code) + if kind == "lock_timeout": + return EffectRuntimeLockTimeout(rendered, diagnostic_code=code) + if kind == "internal_failure": + return EffectRuntimeInternalError(rendered, diagnostic_code=code) + return EffectRuntimeInternalError( + "TypeScript Effect runtime returned an unsupported error kind", + diagnostic_code="unsupported_error_kind", + ) diff --git a/loopx/control_plane/runtime/stdio_transport.py b/loopx/control_plane/runtime/stdio_transport.py new file mode 100644 index 0000000000..19c755cecf --- /dev/null +++ b/loopx/control_plane/runtime/stdio_transport.py @@ -0,0 +1,97 @@ +"""Bounded byte transport for a process-owned Effect runtime.""" + +from __future__ import annotations + +import os +import selectors +import subprocess +import time +from collections.abc import Mapping, Sequence +from threading import Thread + + +class EffectRuntimeStdio: + """Exchange one newline-delimited frame at a time with a local child.""" + + def __init__(self, argv: Sequence[str], env: Mapping[str, str]) -> None: + self._process = subprocess.Popen( + argv, + env=env, + stdin=subprocess.PIPE, + stdout=subprocess.PIPE, + stderr=subprocess.DEVNULL, + bufsize=0, + start_new_session=True, + ) + assert self._process.stdin is not None and self._process.stdout is not None + self._input = self._process.stdin + self._output = self._process.stdout + self._owner_pid = os.getpid() + try: + os.set_blocking(self._input.fileno(), False) + os.set_blocking(self._output.fileno(), False) + except OSError: + self.close(reap_in_background=True) + raise + + @property + def pid(self) -> int: + return self._process.pid + + @property + def alive(self) -> bool: + return self._owner_pid == os.getpid() and self._process.poll() is None + + def exchange(self, frame: bytes, timeout: float, limit: int) -> bytes: + deadline = time.monotonic() + timeout + write_fd = self._input.fileno() + read_fd = self._output.fileno() + pending = memoryview(frame) + with selectors.DefaultSelector() as selector: + selector.register(write_fd, selectors.EVENT_WRITE) + while pending: + remaining = deadline - time.monotonic() + if remaining <= 0 or not selector.select(remaining): + raise TimeoutError("Effect runtime pipe write timed out") + try: + written = os.write(write_fd, pending) + except BlockingIOError: + continue + pending = pending[written:] + + selector.unregister(write_fd) + selector.register(read_fd, selectors.EVENT_READ) + result = bytearray() + while True: + remaining = deadline - time.monotonic() + if remaining <= 0 or not selector.select(remaining): + raise TimeoutError("Effect runtime pipe read timed out") + try: + block = os.read(read_fd, min(64 * 1024, limit + 1 - len(result))) + except BlockingIOError: + continue + if not block: + raise EOFError("Effect runtime pipe closed before its response") + result.extend(block) + if len(result) > limit: + raise ValueError("Effect runtime pipe response is oversized") + end = block.find(b"\n") + if end >= 0: + if end != len(block) - 1: + raise ValueError("Unexpected additional data on the Effect runtime pipe") + return bytes(result) + + def close(self, *, wait_seconds: float = 0.0, reap_in_background: bool = False) -> bool: + # EOF retires the stream. Never terminate a child that may be finishing + # an already dispatched mutation. A fork only closes its own copies. + self._input.close() + self._output.close() + if self._owner_pid != os.getpid(): + return False + try: + self._process.wait(timeout=wait_seconds) + except subprocess.TimeoutExpired: + if reap_in_background: + Thread(target=self._process.wait, daemon=True).start() + return False + return True diff --git a/tests/control_plane/runtime_retirement_diagnostics.py b/tests/control_plane/runtime_retirement_diagnostics.py index b4bce531c1..a246c74cb3 100644 --- a/tests/control_plane/runtime_retirement_diagnostics.py +++ b/tests/control_plane/runtime_retirement_diagnostics.py @@ -40,7 +40,7 @@ def instrument_copied_runtime(root: Path) -> None: """Observe the private fixture copy; production modules are never edited.""" server = root / "effect_runtime_server.ts" text = server.read_text() - text = _replace(text, 'const REQUEST_SCHEMA =', TRACE + '\nconst REQUEST_SCHEMA =') + text = _replace(text, 'const INFO_SCHEMA =', TRACE + '\nconst INFO_SCHEMA =') for before, after in ( ('shutdownRequested = true;', 'shutdownRequested = true; fixtureTrace("shutdown_requested");'), ('server.on("close", () => {', 'server.on("close", () => { fixtureTrace("close", {pending: pendingRequests});'), diff --git a/tests/control_plane/test_effect_runtime_integration.py b/tests/control_plane/test_effect_runtime_integration.py index 4b39243ecd..996422d6d1 100644 --- a/tests/control_plane/test_effect_runtime_integration.py +++ b/tests/control_plane/test_effect_runtime_integration.py @@ -1971,11 +1971,16 @@ def test_rpc_json_preserves_legacy_values_with_valid_utf8(text: str) -> None: ).encode("ascii") +@pytest.mark.parametrize("transport", [ + "tcp", + pytest.param("stdio", marks=pytest.mark.skipif(os.name != "posix", reason="POSIX pipes")), +]) @pytest.mark.parametrize("repeats,snapshot", [(380_000, False), (900_000, True)]) def test_complete_unicode_context_uses_actual_wire_bytes_and_snapshot_fallback( - tmp_path: Path, monkeypatch, repeats: int, snapshot: bool, + tmp_path: Path, monkeypatch, repeats: int, snapshot: bool, transport: str, ) -> None: monkeypatch.setattr(effect_runtime, "_runtime_dir", lambda: tmp_path / "runtime") + monkeypatch.setenv("LOOPX_EFFECT_RUNTIME_TRANSPORT", transport) # The smaller source fits 8 MiB in UTF-8 but exceeds it when ASCII-escaped. text = "保留🙂" * repeats + "\nFinal constraint: retain the original Goal." params = { @@ -1987,11 +1992,11 @@ def test_complete_unicode_context_uses_actual_wire_bytes_and_snapshot_fallback( "require_full_goal_source": True, } assert len(json.dumps(params).encode()) > 8 * 1024 * 1024 - original_send = socket.socket.sendall captured: list[dict[str, object]] = [] + delivered_snapshots: list[str] = [] temporary_paths: list[Path] = [] - def observe_send(connection, data, flags=0): + def observe_request(data): request = json.loads(data) if request["method"] == "work_item.context.project": captured.append(request) @@ -2006,9 +2011,26 @@ def observe_send(connection, data, flags=0): temporary_paths.extend([path, Path(request["response_sink"])]) else: assert "保留🙂".encode() in data and request["params"] == params + original_send = socket.socket.sendall + original_exchange = effect_runtime.EffectRuntimeStdio.exchange + original_read_snapshot = effect_runtime._read_local_snapshot_response + + def observe_send(connection, data, flags=0): + observe_request(data) return original_send(connection, data, flags) + def observe_exchange(pipe, data, timeout, limit): + observe_request(data) + return original_exchange(pipe, data, timeout, limit) + + def observe_read_snapshot(envelope, sink, **kwargs): + result = original_read_snapshot(envelope, sink, **kwargs) + delivered_snapshots.append(kwargs["request_id"]) + return result + monkeypatch.setattr(socket.socket, "sendall", observe_send) + monkeypatch.setattr(effect_runtime.EffectRuntimeStdio, "exchange", observe_exchange) + monkeypatch.setattr(effect_runtime, "_read_local_snapshot_response", observe_read_snapshot) try: result = effect_runtime.effect_runtime_result( "work_item.context.project", params, large_local_snapshot=snapshot, @@ -2017,12 +2039,64 @@ def observe_send(connection, data, flags=0): assert result["work_context"]["sources"][0]["content"]["text"] == text assert len(captured) == 1 assert ("params_ref" in captured[0]) is snapshot + assert delivered_snapshots == ([captured[0]["request_id"]] if snapshot else []) assert all(not path.exists() for path in temporary_paths) assert effect_runtime.effect_runtime_result("runtime.ping", {})["pid"] > 0 finally: effect_runtime.effect_runtime_result("runtime.shutdown", {}, retry_safe=False) +@pytest.mark.skipif(os.name != "posix", reason="POSIX pipes") +def test_stdio_runtime_is_process_owned_and_never_uses_tcp( + tmp_path: Path, monkeypatch, +) -> None: + monkeypatch.setattr(effect_runtime, "_runtime_dir", lambda: tmp_path / "runtime") + monkeypatch.delenv("LOOPX_EFFECT_RUNTIME_TRANSPORT", raising=False) + tcp = effect_runtime.effect_runtime_result("runtime.ping", {}) + try: + with monkeypatch.context() as pipe_env: + pipe_env.setenv("LOOPX_EFFECT_RUNTIME_TRANSPORT", "stdio") + + def refuse_tcp(*args, **kwargs): + pytest.fail("stdio tried to discover or connect to the TCP daemon") + + pipe_env.setattr(socket, "create_connection", refuse_tcp) + pipe_env.setattr(effect_runtime, "_inspect_runtime_locator", refuse_tcp) + assert effect_runtime.restart_effect_runtime()["status"] == "not_running" + shallow = effect_runtime.collect_effect_runtime_readiness() + assert shallow["runtime_lifecycle"]["state"] == "stopped" + try: + ping = effect_runtime.effect_runtime_result("runtime.ping", {}) + assert ping["pid"] != tcp["pid"] + ids = { + "goal_id": "pipe-fixture", "agent_id": "pipe-agent", + "todo_id": "pipe-todo", + } + + def effect_id(index: int) -> str: + result = effect_runtime.effect_runtime_result( + "settlement.identity", {**ids, "turn_instance_id": str(index)}, + ) + return result["effect_id"] + + with ThreadPoolExecutor(max_workers=4) as pool: + assert list(pool.map(effect_id, range(8))) == [ + f"pipe-fixture:pipe-agent:pipe-todo:{index}" for index in range(8) + ] + deep = effect_runtime.collect_effect_runtime_readiness(deep=True) + assert deep["semantic_probe"] == "passed" + assert deep["runtime_lifecycle"]["transport"] == "stdio" + assert deep["runtime_lifecycle"]["locator_state"] == "missing" + assert deep["runtime_identity"] == effect_runtime.runtime_identity_from_info(ping) + assert effect_runtime.effect_runtime_result("runtime.ping", {}) == ping + finally: + assert effect_runtime.restart_effect_runtime(wait_for_exit=True)["status"] == "stopped" + + assert effect_runtime.effect_runtime_result("runtime.ping", {}) == tcp + finally: + effect_runtime.restart_effect_runtime(wait_for_exit=True) + + def test_fragmented_utf8_request_dispatches_only_the_first_complete_frame( tmp_path: Path, monkeypatch, ) -> None: diff --git a/tests/control_plane/test_quota_spend_commit_runtime.py b/tests/control_plane/test_quota_spend_commit_runtime.py index 45ce9713e6..cf61c1119b 100644 --- a/tests/control_plane/test_quota_spend_commit_runtime.py +++ b/tests/control_plane/test_quota_spend_commit_runtime.py @@ -1,6 +1,7 @@ from __future__ import annotations import json +import os from concurrent.futures import ThreadPoolExecutor from pathlib import Path @@ -12,6 +13,7 @@ QuotaRunIndexConflict, build_quota_slot_spend_event, record_quota_slot_spend_from_preview, + replay_quota_spend_by_effect_ref, ) from loopx.control_plane.projects.registry_codec import ( source_session_registry_transaction, @@ -210,6 +212,53 @@ def test_python_facade_serializes_concurrent_exact_effect_retries( assert len(index_path.read_text(encoding="utf-8").splitlines()) == 1 +@pytest.mark.skipif(os.name != "posix", reason="POSIX pipes") +def test_stdio_lost_spend_response_recovers_exact_receipt_without_a_second_debit( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setenv("LOOPX_EFFECT_RUNTIME_TRANSPORT", "stdio") + monkeypatch.setattr(effect_runtime, "_runtime_dir", lambda: tmp_path / "runtime") + effect_ref = "stdio-ambiguous-spend#quota_spend" + preview = _preview(effect_ref=effect_ref) + exchange = effect_runtime.EffectRuntimeStdio.exchange + delivered: list[str] = [] + + def lose_commit_reply(pipe, frame, timeout, limit): + response = exchange(pipe, frame, timeout, limit) + request = json.loads(frame) + if request["method"] == "quota.spend.commit" and request["params"].get("execute") is True: + delivered.append(request["request_id"]) + if len(delivered) == 1: + assert json.loads(response)["result"]["payload"]["appended"] is True + raise EOFError("simulated disconnect after the durable commit") + return response + + monkeypatch.setattr(effect_runtime.EffectRuntimeStdio, "exchange", lose_commit_reply) + try: + original = effect_runtime.effect_runtime_result("runtime.ping", {}) + with pytest.raises(effect_runtime.EffectRuntimeResponseAmbiguous, match="quota.spend.commit"): + _commit(tmp_path, preview) + assert len(delivered) == 1 + recovered = replay_quota_spend_by_effect_ref( + tmp_path, goal_id=GOAL_ID, effect_ref=effect_ref, agent_id=AGENT_ID, read_only=True, + ) + assert recovered["ok"] and recovered["replay_found"] + assert recovered["effect_ref"] == effect_ref + assert recovered["appended"] is False and recovered["idempotent_replay"] is True + current = effect_runtime.effect_runtime_result("runtime.ping", {}) + assert current["pid"] != original["pid"] + index = tmp_path / "goals" / GOAL_ID / "runs" / "index.jsonl" + rows = index.read_bytes() + assert len(rows.splitlines()) == 1 + assert json.loads(rows)["quota_spend_commit"]["effect_id"] == effect_ref + assert len(delivered) == 1 + replayed = _commit(tmp_path, preview) + assert replayed["appended"] is False and replayed["idempotent_replay"] is True + assert index.read_bytes() == rows and len(delivered) == 2 + finally: + effect_runtime.restart_effect_runtime(wait_for_exit=True) + + @pytest.mark.parametrize("context_size", [128, 1_100_000]) def test_complete_spend_context_survives_preview_commit_and_replay( tmp_path: Path, context_size: int,