Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
"""Persistent, subscription-only transport for ``codex app-server``.
This module owns the local JSONL protocol, process lifecycle, and the dedicated
Codex identity used by subscription voice. The user signs in directly inside a
Jarvis-owned ``CODEX_HOME``; OAuth tokens are never copied, hard-linked, or
taken over from an ordinary Codex/IDE profile. Credentials are forced into that
profile's file store, and live ``account/read`` is the authoritative account and
plan check.
API-key environment variables are removed so a subscription request cannot
silently become usage-billed API traffic.
The process is lazy and shared by callers. A dead process fails every pending
request and thread subscription, then the next request starts a fresh process.
Requests wait on independent futures, while the write lock covers only one
JSONL frame and its drain. This keeps high-frequency realtime audio appends
from serialising behind unrelated response waits.
"""
from __future__ import annotations
import asyncio
import hashlib
import json
import logging
import os
import platform
import re
import secrets
import shutil
import stat
import subprocess
import sys
import tempfile
import threading
import time
import uuid
from collections.abc import AsyncIterator, Mapping, Sequence
from contextlib import suppress
from dataclasses import dataclass
from pathlib import Path
from typing import TYPE_CHECKING, Any, Final, Literal, get_args
if TYPE_CHECKING:
pass
from dodaios import __version__
from dodaios.core.branding import PRODUCT_NAME
from dodaios.core.process_tree import ProcessTree, make_process_tree
from dodaios.core.process_utils import NO_WINDOW_CREATIONFLAGS
log = logging.getLogger(__name__)
_DEFAULT_REQUEST_TIMEOUT_S: Final = 20.0
# How long a passed cold-start audit may be ridden by a SECOND thread_start on
# the same process (the STUN media-path retry). Short on purpose: warm starts
# minutes later must re-audit in full. ``prime_startup_audit`` mints a wake
# ride under the same TTL — always from an audit that actually completed.
_STARTUP_AUDIT_TTL_S: Final = 10.0
# How long a per-host STUN media-path memory stays valid. Long enough to span
# a working session on one network, short enough that a laptop moving networks
# gets a fresh host-candidate attempt within the hour.
_STUN_MEDIA_PATH_TTL_S: Final = 3600.0
_SHUTDOWN_TIMEOUT_S: Final = 2.0
_DEFAULT_SDP_TIMEOUT_S: Final = 15.0
_DEFAULT_NOTIFICATION_QUEUE_SIZE: Final = 512
CodexAppServerPurpose = Literal["realtime", "text"]
_MAX_REALTIME_START_PROMPT_BYTES: Final = 64_000
_MAX_REALTIME_INITIAL_ITEMS: Final = 128
_MAX_REALTIME_INITIAL_TEXT_BYTES: Final = 32_768
_REALTIME_INITIAL_ROLES: Final = frozenset({"user", "developer", "assistant"})
_SUPPORTED_CODEX_VERSION: Final = "codex-cli 0.147.0"
_LEGACY_CODEX_VERSION: Final = "codex-cli 0.146.0"
_SUPPORTED_CODEX_VERSIONS: Final = (
_SUPPORTED_CODEX_VERSION,
_LEGACY_CODEX_VERSION,
)
_CHILD_LIFELINE_SCRIPT: Final = str(
Path(__file__).parent / "core" / "child_lifeline.py"
)
# SHA-256 of the native executables in OpenAI's six official npm artifacts for
# @openai/codex 0.147.0. The app-server protocol used below is experimental;
# an unknown build is refused instead of assuming its safety semantics match.
_TRUSTED_CODEX_TARGETS: Final = {
("darwin", "arm64"): (
"darwin-arm64",
"aarch64-apple-darwin",
"codex",
"19c4f144c5226a9f17c58e6f0fa854843b0f77a6eb420f40e2745a12f10f5d37",
),
("darwin", "x86_64"): (
"darwin-x64",
"x86_64-apple-darwin",
"codex",
"8080a42da4cef9c4216dace512f29acfe2e526aeeec2a0ce450e5a2b18b84d8a",
),
("linux", "arm64"): (
"linux-arm64",
"aarch64-unknown-linux-musl",
"codex",
"e23d0be344d2496986c985cd3db61e6f649b1ddd900e6afc1b5aaabbffcbb4e2",
),
("linux", "x86_64"): (
"linux-x64",
"x86_64-unknown-linux-musl",
"codex",
"cb0a15567e9a60a5820d54b0f6ae86d504dc3805c1eab21a47f70e3eb7b73a40",
),
("win32", "arm64"): (
"win32-arm64",
"aarch64-pc-windows-msvc",
"codex.exe",
"1f0e8c2dd3c6b471e985fac76908366c1cf31155094fde606fb2d3052cf00584",
),
("win32", "x86_64"): (
"win32-x64",
"x86_64-pc-windows-msvc",
"codex.exe",
"935a1911ed2556e4ffcec995f4886ac2ac425863ba26fed264df62e30272ad9d",
),
}
# Keep the last audited protocol-compatible release available during the pin
# transition. This is a compatibility window, not a semver trust rule: each
# executable is still accepted only by its exact official artifact digest.
_LEGACY_TRUSTED_CODEX_TARGETS: Final = {
("darwin", "arm64"): (
"darwin-arm64",
"aarch64-apple-darwin",
"codex",
"ae1d3ffe6d48aec6a4dc3f50e7eb8e0d11962485a6a9406c5a7012139383da02",
),
("darwin", "x86_64"): (
"darwin-x64",
"x86_64-apple-darwin",
"codex",
"544e2df9e6f09b3f1ceb0405879c83dd099ec015aeed942bb091ff0f29f60dc2",
),
("linux", "arm64"): (
"linux-arm64",
"aarch64-unknown-linux-musl",
"codex",
"cb5e8cb8a333a408ce6adbe0d4fad1845c69772c2216af7c1f88c98a11460dc6",
),
("linux", "x86_64"): (
"linux-x64",
"x86_64-unknown-linux-musl",
"codex",
"2e863156ed35ecc5253b1e2f907a9143077b9f7cb51942070c61996471ff6e04",
),
("win32", "arm64"): (
"win32-arm64",
"aarch64-pc-windows-msvc",
"codex.exe",
"d52efa1d816b305c84c525335f451aafc56398a7e8515b6c6db095c4e4fb0d1d",
),
("win32", "x86_64"): (
"win32-x64",
"x86_64-pc-windows-msvc",
"codex.exe",
"bc343ba420dc2e2e9f59e6fc5e5bf0aae1cd8c771fc319665241fc9c0271fddb",
),
}
_SUBSCRIPTION_HOME_DIRNAME: Final = "codex-subscription-voice"
_SUBSCRIPTION_LOCK_DIRNAME: Final = ".codex-subscription-voice-lock"
_SUBSCRIPTION_LOCK_FILENAME: Final = "owner.lock"
_SUBSCRIPTION_PROFILE_MARKER: Final = ".jarvis-realtime-transport.json"
_SUBSCRIPTION_PROFILE_SCHEMA: Final = 1
_ALLOWED_SUBSCRIPTION_HOME_ENTRIES: Final = frozenset(
{
"auth.json",
"installation_id",
# Codex 0.146 writes this tiny one-time migration marker into its
# CODEX_HOME on a normal run. Without it in the allowlist the
# fail-closed profile check bricked every install right after the
# CLI's first use of the profile.
".sandbox_migration",
"tmp",
_SUBSCRIPTION_PROFILE_MARKER,
}
)
# Desktop-shell droppings, not Codex state: Finder writes ``.DS_Store`` the
# moment anyone LOOKS at the folder, Explorer writes ``Thumbs.db`` /
# ``desktop.ini``, and copying the profile across a network share leaves
# AppleDouble ``._`` siblings. These are ignored rather than allowlisted —
# they carry nothing to validate, and treating one as "the profile contains
# configuration" used to delete a working ChatGPT login on the next Connect.
_OS_METADATA_ENTRY_NAMES: Final = frozenset(
{
".ds_store",
".localized",
".spotlight-v100",
".trashes",
".fseventsd",
"desktop.ini",
"thumbs.db",
"ehthumbs.db",
"$recycle.bin",
"system volume information",
}
)
def _is_os_metadata_entry(name: str) -> bool:
lowered = name.lower()
return lowered in _OS_METADATA_ENTRY_NAMES or lowered.startswith("._")
_ARG0_RUNTIME_DIR_RE: Final = re.compile(r"^codex-arg0[A-Za-z0-9]{6}$")
_MAX_ARG0_RUNTIME_DIRS: Final = 32
_PERSONAL_CHATGPT_PLANS: Final = frozenset(
{"free", "go", "plus", "pro", "prolite"}
)
_SUBSCRIPTION_ENV_ALLOWLIST: Final = frozenset(
{
# Executable/runtime discovery.
"PATH",
"PATHEXT",
"COMSPEC",
"SYSTEMROOT",
"WINDIR",
# Temporary storage used by the CLI/runtime.
"TEMP",
"TMP",
"TMPDIR",
# Portable account/home selection. No provider or cloud variables are
# inherited merely because they happen to exist in Jarvis's process.
"HOME",
"USERPROFILE",
"HOMEDRIVE",
"HOMEPATH",
"APPDATA",
"LOCALAPPDATA",
"CODEX_HOME",
# Locale and terminal shape. These say how text is ENCODED and drawn,
# never who anyone is: without them the child falls back to the C
# locale and mangles every non-ASCII byte it handles. The interactive
# login child already inherits exactly these
# (``dodaios/codex_auth.py::_ISOLATED_CODEX_ENV_ALLOWLIST``); the
# transport dropping them was an undocumented divergence.
"LANG",
"TERM",
"NO_COLOR",
# TLS trust roots. Not credentials — they name WHICH certificate
# authorities to believe, and on hosts that carry their roots in the
# environment (corporate images, Nix, conda, many container bases)
# dropping them left the child with no trust store at all: `codex
# login status` reads a local file and succeeds, so the card said
# "connected" while every call died in the TLS handshake.
"SSL_CERT_FILE",
"SSL_CERT_DIR",
"REQUESTS_CA_BUNDLE",
}
)
# ``LC_*`` is an open family (LC_ALL, LC_CTYPE, LC_MESSAGES, ...), so it is
# matched by prefix. Same reasoning as LANG above: encoding, not identity.
_SUBSCRIPTION_ENV_ALLOWED_PREFIXES: Final = ("LC_",)
def _subscription_env_allowed(name: str) -> bool:
"""Whether one inherited environment variable may reach the child."""
upper = name.upper()
if upper in _OPENAI_BILLING_ENV_NAMES:
# Belt and braces: the allowlist already excludes every billing token,
# but a future entry added there must not silently re-open the
# usage-billed path this transport exists to avoid.
return False
return upper in _SUBSCRIPTION_ENV_ALLOWLIST or upper.startswith(
_SUBSCRIPTION_ENV_ALLOWED_PREFIXES
)
_DISABLED_APP_SERVER_FEATURES: Final = (
"shell_tool",
"apps",
"browser_use",
"computer_use",
"hooks",
"image_generation",
"memories",
"multi_agent",
"multi_agent_v2",
"plugins",
"network_proxy",
"remote_plugin",
"remote_control",
"respect_system_proxy",
"skill_search",
"workspace_dependencies",
"web_search_request",
"external_agent_memory_import",
"chronicle",
)
# Codex 0.147 keeps the effective/session-layer value for ``multi_agent_v2``
# as the scalar supplied by ``--disable``, but config/read attributes that one
# value to the structured feature field ``features.multi_agent_v2.enabled``.
# Canonicalize only this audited release/path pair. The exact origin set,
# sessionFlags source, version, effective value, and allowed session surface
# are still checked below, so this does not admit an additional config field.
_CODEX_CONFIG_ORIGIN_PATH_ALIASES: Final = {
_SUPPORTED_CODEX_VERSION: {
"features.multi_agent_v2.enabled": "features.multi_agent_v2",
},
}
_TRANSPORT_BASE_INSTRUCTIONS: Final = (
"This ephemeral thread exists only to carry a realtime voice transport. "
"Never use tools, inspect files, access the network, or perform actions. "
"Never answer a realtime handoff as a Codex agent; the client-owned Dodaios "
"supervisor handles every handoff."
)
_TRANSPORT_DEVELOPER_INSTRUCTIONS: Final = (
"Transport-only boundary: do not call tools, shell commands, applications, "
"plugins, skills, web search, MCP servers, or other agents. Do not read or "
"write the filesystem. Yield all realtime handoffs to the client."
)
_TEXT_BASE_INSTRUCTIONS: Final = (
"This ephemeral thread serves a conversational voice assistant. Answer the "
"user directly in plain text. Never use tools, inspect files, access the "
"workspace, run commands, browse, or perform actions."
)
_TEXT_DEVELOPER_INSTRUCTIONS: Final = (
"Conversational text-only boundary: return only the assistant reply. Do not "
"call tools, shell commands, applications, plugins, skills, web search, MCP "
"servers, or other agents. Do not read or write the filesystem."
)
_TEXT_MODEL_PROVIDER: Final = "openai"
_OFFICIAL_OPENAI_API_BASE: Final = "https://api.openai.com/v1"
_OFFICIAL_OPENAI_REALTIME_BASE: Final = "https://api.openai.com/v1"
_OFFICIAL_CHATGPT_BASE: Final = "https://chatgpt.com/backend-api/"
_OFFICIAL_CHATGPT_CODEX_BASE: Final = "https://chatgpt.com/backend-api/codex"
_MISSING = object()
# A ChatGPT-authenticated Codex process must not inherit any OpenAI key that
# could make the CLI select a usage-billed path. Include Jarvis's per-feature
# aliases as well as historical Codex aliases seen in existing installations.
_OPENAI_BILLING_ENV_NAMES: Final = frozenset(
{
"CODEX_API_KEY",
"CODEX_OPENAI_API_KEY",
"JARVIS_AGENT_OPENAI_API_KEY",
"JARVIS_REALTIME_OPENAI_API_KEY",
"LOCAL_OPENAI_API_KEY",
"OPENAI_API_KEY",
}
)
_DECLINE_REQUEST_METHODS: Final = frozenset(
{
"item/commandExecution/requestApproval",
"item/fileChange/requestApproval",
}
)
_DYNAMIC_TOOL_REQUEST_METHODS: Final = frozenset({"item/tool/call"})
# Per-host memory of the WebRTC media path the LAST successful connect needed.
# In-process only and TTL-bounded on purpose: network topology is a property
# of this machine on this network right now, so persisting it would replay a
# stale environment. A host recorded here needed a server-reflexive (STUN)
# candidate, which means a host-candidates-only first attempt is known to be
# doomed and would cost a full second open (thread_start bundle included).
# Guarded by a lock because callers may record from executor threads.
_stun_media_path_lock = threading.Lock()
_stun_media_path_memory: dict[str, float] = {}
def _stun_media_path_key(host: str) -> str:
return str(host or "").strip().lower()
def record_media_path_outcome(host: str, *, needed_stun: bool) -> None:
"""Remember whether the last successful connect to ``host`` needed STUN.
Call this only after a connect actually succeeded: a successful
host-candidate path clears the memory, a successful STUN path arms it so
the next open for the same host starts with STUN directly instead of
paying a doomed host-only attempt first.
"""
key = _stun_media_path_key(host)
if not key:
return
with _stun_media_path_lock:
if needed_stun:
_stun_media_path_memory[key] = time.monotonic()
else:
_stun_media_path_memory.pop(key, None)
def media_path_prefers_stun(host: str) -> bool:
"""Whether the last successful connect to ``host`` needed a STUN candidate.
Returns ``False`` for unknown hosts and for stale entries — the memory is
an optimization, never a gate, so forgetting only restores today's
host-candidates-first behavior.
"""
key = _stun_media_path_key(host)
if not key:
return False
with _stun_media_path_lock:
recorded_at = _stun_media_path_memory.get(key)
if recorded_at is None:
return False
if time.monotonic() - recorded_at > _STUN_MEDIA_PATH_TTL_S:
del _stun_media_path_memory[key]
return False
return True
class CodexAppServerError(RuntimeError):
"""Base error for the local app-server transport."""
class CodexSubscriptionUnavailable(CodexAppServerError):
"""The Codex CLI cannot currently use a ChatGPT subscription login."""
class CodexSubscriptionContainmentUnavailable(CodexSubscriptionUnavailable):
"""The host cannot safely bind the experimental child to Jarvis lifetime."""
class CodexSubscriptionProfileMissing(CodexSubscriptionUnavailable):
"""The dedicated subscription-voice profile does not exist yet."""
class CodexSubscriptionBinaryUnsupported(CodexSubscriptionUnavailable):
"""No installed Codex matches the pinned, hash-approved release.
Maps to ``reason_code="not_installed"``: the actionable truth for a
wrong-version or unknown build is "install the supported release", with
the pinned install command — not "your profile needs attention".
"""
class CodexSubscriptionPlanUnsupported(CodexSubscriptionUnavailable):
"""The live account check refused this ChatGPT plan permanently.
A transient startup failure must NOT carry this class: activation stores
it as the sticky ``plan_unsupported`` diagnosis that outlives the toast.
"""
class CodexSubscriptionRuntimeStateInvalid(CodexSubscriptionUnavailable):
"""Codex's own ephemeral scratch under ``tmp/`` is not a shape we accept.
Separate from a bad PROFILE because the recovery differs: this state is
regenerated by the CLI on every run and contains no credential, so the
honest repair is to clear ``tmp/`` — never to delete the profile, which
would take a working ChatGPT login with it over a leftover scratch file.
"""
class CodexSubscriptionInspectionFailed(CodexSubscriptionUnavailable):
"""An OS read error prevented judging the profile — transiently unknown.
Distinct from a genuinely invalid profile: an antivirus-locked directory
or a slow disk must surface as ``busy`` ("checking"), never as "create a
fresh voice-only login".
"""
class CodexAppServerDisconnected(CodexAppServerError):
"""The app-server process exited or its JSONL stream broke."""
class CodexAppServerTimeout(CodexAppServerError):
"""A bounded app-server request or notification wait expired."""
class CodexNotificationOverflow(CodexAppServerError):
"""A subscriber stopped consuming realtime notifications fast enough."""
#: A machine token is safe to forward; free text is not. Anything that is not
#: a short, lowercase, punctuation-free identifier stays redacted.
_RPC_ERROR_TOKEN_RE: Final = re.compile(r"^[a-z0-9_]{1,64}$")
_RPC_ERROR_STATUS_KEYS: Final = (
"httpStatus",
"http_status",
"statusCode",
"status_code",
"status",
)
_RPC_ERROR_TYPE_KEYS: Final = ("type", "errorType", "error_type", "reason")
def _rpc_error_detail(error: Any) -> tuple[int | None, str | None]:
"""Extract ONLY an HTTP status and a bounded error-type token.
Everything else in an app-server error — the message, the account label,
the upstream request detail — stays redacted, which is why this transport
used to surface a plan/quota refusal and a broken transport as the same
opaque "rejected (code -32000)". Those two need opposite reactions from
the user, so the two machine-readable fields that tell them apart are
forwarded and nothing more.
"""
if not isinstance(error, Mapping):
return None, None
scopes: list[Mapping[str, Any]] = [error]
for key in ("data", "error"):
nested = error.get(key)
if isinstance(nested, Mapping):
scopes.append(nested)
deeper = nested.get("error")
if isinstance(deeper, Mapping):
scopes.append(deeper)
status: int | None = None
token: str | None = None
for scope in scopes:
if status is None:
for key in _RPC_ERROR_STATUS_KEYS:
candidate = scope.get(key)
if isinstance(candidate, bool):
continue
if isinstance(candidate, int) and 100 <= candidate <= 599:
status = candidate
break
if token is None:
for key in _RPC_ERROR_TYPE_KEYS:
candidate = scope.get(key)
if not isinstance(candidate, str):
continue
normalized = candidate.strip().lower()
if _RPC_ERROR_TOKEN_RE.fullmatch(normalized):
token = normalized
break
return status, token
class CodexAppServerRPCError(CodexAppServerError):
"""A redacted JSON-RPC error returned by app-server."""
def __init__(
self,
method: str,
code: int | None,
*,
http_status: int | None = None,
error_type: str | None = None,
) -> None:
self.method = method
self.code = code
self.http_status = http_status
self.error_type = error_type
details = []
if code is not None:
details.append(f"code {code}")
if http_status is not None:
# Spelled as a bare status so the shared classifier
# (dodaios/brain/provider_test.py::classify_provider_error) reads
# 402/429 as an account state instead of "possible integration bug".
details.append(f"http {http_status}")
if error_type is not None:
details.append(f"type {error_type}")
suffix = f" ({'; '.join(details)})" if details else ""
super().__init__(f"Codex app-server rejected {method}{suffix}.")
# SSOT for the subscription-status reason-code vocabulary. Mirrors (five-layer
# anti-drift guard, BUG-008 class): the runtime membership guard in
# ``dodaios/ui/web/provider_routes.py::_codex_subscription_status_payload``
# (unknown values degrade to busy with a warning), the TS union in
# ``useProviders.ts``, the exhaustive ``CODEX_STATUS_KEY_BY_REASON`` record in
# ``ProviderTierSection.tsx`` (a new member fails the TS build until mapped;
# the i18n parity test derives its key list from it), and one
# ``apikeys_codex.status_*`` i18n key per member in de/en/es. The Python side
# is pinned by ``test_reason_code_vocabulary_is_pinned``.
# "busy" is transient: the profile is briefly owned by another probe, a
# login/logout, or a starting voice transport. Not a setup defect; callers
# keep their last known state instead of asking the user to reconnect.
CodexSubscriptionReasonCode = Literal[
"ready",
"login_required",
# An interactive login is running right now: the card must invite the
# user to FINISH it in the browser, never to start a second one.
"login_in_progress",
"lifecycle_unavailable",
"not_installed",
"setup_invalid",
# The connected ChatGPT account can never activate this provider (for
# example a business/enterprise plan) — sticky until login/logout.
"plan_unsupported",
"busy",
]
CODEX_SUBSCRIPTION_REASON_CODES: Final = frozenset(
get_args(CodexSubscriptionReasonCode)
)
@dataclass(frozen=True, slots=True)
class CodexAppServerCapability:
"""PII-free snapshot of whether the subscription transport may start."""
available: bool
chatgpt_authenticated: bool
binary_path: str | None
version: str | None
reason: str
reason_code: CodexSubscriptionReasonCode = "setup_invalid"
@dataclass(frozen=True, slots=True)
class CodexAppServerNotification:
"""One thread-scoped app-server notification."""
method: str
params: dict[str, Any]
@dataclass(frozen=True, slots=True)
class CodexRealtimeStartResult:
"""Realtime start acknowledgement plus an optional WebRTC answer SDP."""
response: dict[str, Any]
answer_sdp: str | None
_SUBSCRIPTION_END = object()
_SubscriptionItem = CodexAppServerNotification | BaseException | object
@dataclass(frozen=True, slots=True)
class _SafeTransportWorkspace:
root: Path
instructions: Path
compact_prompt: Path
model_catalog: Path
sqlite_home: Path
log_dir: Path
child_home: Path
child_appdata: Path
child_local_appdata: Path
child_tmp: Path
def codex_subscription_home() -> Path:
"""Jarvis-owned Codex identity used only by realtime subscription voice."""
from dodaios.core.paths import user_data_dir
return user_data_dir() / _SUBSCRIPTION_HOME_DIRNAME
def _subscription_process_lock_path() -> Path:
"""Return an owner-only lock path outside the allowlisted CODEX_HOME."""
from dodaios.core.paths import user_data_dir
from dodaios.core.private_directory import ensure_owner_only_directory
root = user_data_dir()
root.mkdir(parents=True, exist_ok=True)
try:
canonical_root = root.resolve(strict=True)
lock_directory = canonical_root / _SUBSCRIPTION_LOCK_DIRNAME
ensure_owner_only_directory(lock_directory, create=True)
canonical_lock_directory = lock_directory.resolve(strict=True)
except (OSError, RuntimeError) as exc:
raise CodexSubscriptionUnavailable(
"The subscription-voice process lock could not be secured."
) from exc
if canonical_lock_directory.parent != canonical_root:
raise CodexSubscriptionUnavailable(
"The subscription-voice process lock could not be secured."
)
return canonical_lock_directory / _SUBSCRIPTION_LOCK_FILENAME
def _acquire_subscription_process_lock():
"""Acquire the cross-process profile owner or fail without path disclosure."""
from dodaios.core.exclusive_process_lock import (
ExclusiveProcessLock,
ExclusiveProcessLockError,
)
try:
return ExclusiveProcessLock.acquire(
_subscription_process_lock_path(),
protected_directory=codex_subscription_home(),
)
except ExclusiveProcessLockError as exc:
if exc.reason == "busy":
message = "Another Dodaios process is using subscription voice."
else:
message = "The subscription-voice process lock could not be secured."
raise CodexSubscriptionUnavailable(message) from exc
def _is_link_or_reparse(path: Path) -> bool:
metadata = path.lstat()
if stat.S_ISLNK(metadata.st_mode):
return True
reparse_flag = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
return bool(getattr(metadata, "st_file_attributes", 0) & reparse_flag)
def _validate_current_owner(metadata: os.stat_result) -> None:
geteuid = getattr(os, "geteuid", None)
if callable(geteuid) and metadata.st_uid != geteuid():
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile belongs to another user."
)
def _validate_regular_private_file(path: Path) -> None:
try:
metadata = path.lstat()
except OSError as exc:
# An unreadable entry (antivirus hold, slow disk) is transiently
# unknown, never proof of a broken profile.
raise CodexSubscriptionInspectionFailed(
"The dedicated Codex voice profile could not be inspected."
) from exc
if _is_link_or_reparse(path) or not stat.S_ISREG(metadata.st_mode):
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile contains an unsafe filesystem entry."
)
if getattr(metadata, "st_nlink", 1) != 1:
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile contains a linked credential file."
)
_validate_current_owner(metadata)
if sys.platform == "win32":
from dodaios.core.exclusive_process_lock import ( # noqa: PLC0415
ExclusiveProcessLockError,
_validate_windows_file_security,
)
flags = os.O_RDONLY | getattr(os, "O_BINARY", 0)
flags |= getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
descriptor = -1
try:
descriptor = os.open(path, flags)
opened = os.fstat(descriptor)
current = path.lstat()
reparse_flag = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
if (
stat.S_ISLNK(current.st_mode)
or bool(getattr(current, "st_file_attributes", 0) & reparse_flag)
or not stat.S_ISREG(opened.st_mode)
or (opened.st_dev, opened.st_ino) != (current.st_dev, current.st_ino)
):
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile contains an unsafe filesystem entry."
)
_validate_windows_file_security(descriptor)
except CodexSubscriptionUnavailable:
raise
except (ExclusiveProcessLockError, OSError, ValueError) as exc:
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile contains a file that is not owner-only."
) from exc
finally:
if descriptor >= 0:
os.close(descriptor)
def _validate_private_directory(
path: Path,
*,
exact_posix_mode: int | None = None,
require_owner_only: bool = False,
) -> None:
try:
metadata = path.lstat()
except OSError as exc:
# Transiently unreadable, not proven-broken (see the file variant).
raise CodexSubscriptionInspectionFailed(
"The dedicated Codex voice profile could not be inspected."
) from exc
if _is_link_or_reparse(path) or not stat.S_ISDIR(metadata.st_mode):
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile contains an unsafe directory."
)
_validate_current_owner(metadata)
if os.name == "posix":
mode = stat.S_IMODE(metadata.st_mode)
if exact_posix_mode is not None and mode != exact_posix_mode:
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile has unsafe directory permissions."
)
if require_owner_only and exact_posix_mode is None and mode & 0o077:
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile is not owner-only."
)
def _is_trusted_codex_runtime_binary(
path: Path,
*,
trusted_binary_path: str | None = None,
) -> bool:
try:
canonical = path.resolve(strict=True)
if _is_link_or_reparse(canonical) or not canonical.is_file():
return False
if trusted_binary_path is not None:
trusted = Path(trusted_binary_path).resolve(strict=True)
return (
not _is_link_or_reparse(trusted)
and trusted.is_file()
and os.path.normcase(str(canonical))
== os.path.normcase(str(trusted))
)
return (
_trusted_codex_target_for_digest(_sha256_file_cached(canonical))
is not None
)
except OSError: # An unreadable binary is reported as an unavailable capability.
return False
def _validate_windows_arg0_wrapper(
path: Path,
*,
trusted_binary_path: str | None = None,
) -> None:
_validate_regular_private_file(path)
try:
if path.stat().st_size > 4096:
raise ValueError("wrapper is too large")
body = path.read_text(encoding="utf-8")
except (OSError, UnicodeError, ValueError) as exc:
raise CodexSubscriptionRuntimeStateInvalid(
"The dedicated Codex voice profile contains an invalid runtime wrapper."
) from exc
match = re.fullmatch(
r'@echo off\r?\n"([^"\r\n]+)" --codex-run-as-apply-patch %\*\r?\n',
body,
)
if match is None or not _is_trusted_codex_runtime_binary(
Path(match.group(1)),
trusted_binary_path=trusted_binary_path,
):
raise CodexSubscriptionRuntimeStateInvalid(
"The dedicated Codex voice profile contains an untrusted runtime wrapper."
)
def _validate_unix_arg0_alias(
path: Path,
*,
trusted_binary_path: str | None = None,
) -> None:
try:
metadata = path.lstat()
except OSError as exc:
# Transiently unreadable, not proven-broken (see the sibling wraps).
raise CodexSubscriptionInspectionFailed(
"The dedicated Codex voice profile runtime could not be inspected."
) from exc
if not stat.S_ISLNK(metadata.st_mode):
raise CodexSubscriptionRuntimeStateInvalid(
"The dedicated Codex voice profile contains an invalid runtime alias."
)
_validate_current_owner(metadata)
try:
raw_target = Path(os.readlink(path))
target = raw_target if raw_target.is_absolute() else path.parent / raw_target
except OSError as exc:
raise CodexSubscriptionRuntimeStateInvalid(
"The dedicated Codex voice profile contains an unreadable runtime alias."
) from exc
if not _is_trusted_codex_runtime_binary(
target,
trusted_binary_path=trusted_binary_path,
):
raise CodexSubscriptionRuntimeStateInvalid(
"The dedicated Codex voice profile contains an untrusted runtime alias."
)
def _validate_arg0_runtime_dir(
path: Path,
*,
trusted_binary_path: str | None = None,
) -> None:
"""Judge one ``tmp/arg0/codex-arg0XXXXXX`` scratch directory.
Membership is a NAME ALLOWLIST over a required ``.lock``, not set
equality. The exact file set was only ever measured on Windows; the macOS
and Linux sets were assumptions, and one file more or fewer (a Codex point
release, a platform that ships no sandbox helper) turned a healthy install
into ``setup_invalid``. The real security boundary is per entry and
unchanged: every non-lock child must still resolve to the approved binary
(``_validate_unix_arg0_alias`` / ``_validate_windows_arg0_wrapper``), so a
name that merely went missing proves nothing and an extra name still has
to survive that check.
"""
_validate_private_directory(path)
try:
children = {
entry.name: entry
for entry in path.iterdir()
if not _is_os_metadata_entry(entry.name)
}
except OSError as exc:
raise CodexSubscriptionInspectionFailed(
"The dedicated Codex voice profile runtime could not be inspected."
) from exc
if sys.platform == "win32":
allowed = {"apply_patch.bat", "applypatch.bat"}
elif sys.platform == "darwin" or sys.platform.startswith("linux"):
allowed = {
"apply_patch",
"applypatch",
"codex-execve-wrapper",
"codex-linux-sandbox",
}
else:
raise CodexSubscriptionUnavailable(
"This platform's Codex runtime layout is not approved."
)
lock_file = children.get(".lock")
if lock_file is None:
raise CodexSubscriptionRuntimeStateInvalid(
"The dedicated Codex voice profile runtime is missing its lock."
)
unknown = sorted(set(children) - allowed - {".lock"})
if unknown:
raise CodexSubscriptionRuntimeStateInvalid(
"The dedicated Codex voice profile contains unexpected runtime files."
)
_validate_regular_private_file(lock_file)
if lock_file.stat().st_size != 0:
raise CodexSubscriptionRuntimeStateInvalid(
"The dedicated Codex voice profile contains an invalid runtime lock."
)
for name, child in children.items():
if name == ".lock":
continue
if sys.platform == "win32":
_validate_windows_arg0_wrapper(
child,
trusted_binary_path=trusted_binary_path,
)
else:
_validate_unix_arg0_alias(
child,
trusted_binary_path=trusted_binary_path,
)
def _validate_codex_runtime_state(
home: Path,
*,
trusted_binary_path: str | None = None,
) -> None:
installation_id = home / "installation_id"
if installation_id.exists() or installation_id.is_symlink():
_validate_regular_private_file(installation_id)
try:
raw_installation_id = installation_id.read_text(encoding="utf-8")
parsed = uuid.UUID(raw_installation_id)
except (OSError, UnicodeError, ValueError) as exc:
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile has an invalid installation id."
) from exc
if raw_installation_id != str(parsed) or len(raw_installation_id) != 36:
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile has a non-canonical installation id."
)
if os.name == "posix":
mode = stat.S_IMODE(installation_id.stat().st_mode)
if mode not in {0o600, 0o640, 0o644}:
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice installation id has unsafe permissions."
)
runtime_root = home / "tmp"
if not runtime_root.exists() and not runtime_root.is_symlink():
return
trusted_runtime_binary: Path | None = None
if trusted_binary_path is not None:
try:
trusted_runtime_binary = Path(trusted_binary_path).resolve(strict=True)
except OSError as exc:
raise CodexSubscriptionUnavailable(
"The approved Codex runtime binary is unavailable."
) from exc
_validate_private_directory(runtime_root)
try:
runtime_children = {
entry.name: entry
for entry in runtime_root.iterdir()
if not _is_os_metadata_entry(entry.name)
}
except OSError as exc:
raise CodexSubscriptionInspectionFailed(
"The dedicated Codex voice runtime could not be inspected."
) from exc
if set(runtime_children) != {"arg0"}:
raise CodexSubscriptionRuntimeStateInvalid(
"The dedicated Codex voice profile contains unexpected runtime state."
)
arg0_root = runtime_children["arg0"]
_validate_private_directory(
arg0_root,
exact_posix_mode=0o700 if os.name == "posix" else None,
)
try:
process_dirs = tuple(
entry
for entry in arg0_root.iterdir()
if not _is_os_metadata_entry(entry.name)
)
except OSError as exc:
raise CodexSubscriptionInspectionFailed(
"The dedicated Codex voice runtime could not be inspected."
) from exc
if len(process_dirs) > _MAX_ARG0_RUNTIME_DIRS:
raise CodexSubscriptionRuntimeStateInvalid(
"The dedicated Codex voice profile contains excessive runtime state."
)
for process_dir in process_dirs:
if _ARG0_RUNTIME_DIR_RE.fullmatch(process_dir.name) is None:
raise CodexSubscriptionRuntimeStateInvalid(
"The dedicated Codex voice profile contains an unknown runtime directory."
)
_validate_arg0_runtime_dir(
process_dir,
trusted_binary_path=(
str(trusted_runtime_binary)
if trusted_runtime_binary is not None
else None
),
)
if trusted_runtime_binary is not None and not _is_trusted_codex_runtime_binary(
trusted_runtime_binary
):
raise CodexSubscriptionRuntimeStateInvalid(
"The dedicated Codex voice profile references an untrusted runtime binary."
)
def _validated_subscription_home(
*,
create: bool,
require_marker: bool,
trusted_binary_path: str | None = None,
) -> Path:
"""Resolve the isolated profile and reject every non-login artifact."""
from dodaios.core.paths import user_data_dir
from dodaios.core.private_directory import ensure_owner_only_directory
root = user_data_dir()
if create:
root.mkdir(parents=True, exist_ok=True)
elif not root.exists() and not root.is_symlink():
raise CodexSubscriptionProfileMissing(
"The dedicated Codex voice profile has not been created yet."
)
try:
canonical_root = root.resolve(strict=True)
except OSError as exc:
raise CodexSubscriptionInspectionFailed(
"Dodaios's private data directory could not be verified."
) from exc
candidate = canonical_root / _SUBSCRIPTION_HOME_DIRNAME
if not create and not candidate.exists() and not candidate.is_symlink():
raise CodexSubscriptionProfileMissing(
"The dedicated Codex voice profile has not been created yet."
)
try:
ensure_owner_only_directory(candidate, create=create)
except RuntimeError as exc:
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile is not owner-only."
) from exc
try:
canonical_home = candidate.resolve(strict=True)
except OSError as exc:
raise CodexSubscriptionProfileMissing(
"The dedicated Codex voice profile has not been created yet."
) from exc
if canonical_home.parent != canonical_root:
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile escaped Dodaios's private data directory."
)
_validate_private_directory(canonical_home, require_owner_only=True)
try:
entries = tuple(canonical_home.iterdir())
except OSError as exc:
raise CodexSubscriptionInspectionFailed(
"The dedicated Codex voice profile could not be inspected."
) from exc
# Desktop-shell sidecars are skipped entirely: they are not Codex state,
# and judging one as "the profile contains configuration" made merely
# opening the folder in Finder or Explorer cost the user their login.
entries = tuple(
entry for entry in entries if not _is_os_metadata_entry(entry.name)
)
unexpected = [
entry.name
for entry in entries
if entry.name not in _ALLOWED_SUBSCRIPTION_HOME_ENTRIES
]
if unexpected:
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile contains configuration or runtime state. "
"Create a fresh voice-only login."
)
for entry in entries:
if entry.name in {
"auth.json",
".sandbox_migration",
_SUBSCRIPTION_PROFILE_MARKER,
}:
_validate_regular_private_file(entry)
if entry.name == ".sandbox_migration":
# A tiny one-time CLI marker; anything larger is not that file.
try:
oversized = entry.stat().st_size > 4096
except OSError as exc:
raise CodexSubscriptionInspectionFailed(
"The dedicated Codex voice profile could not be inspected."
) from exc
if oversized:
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile contains an unexpected "
"runtime file."
)
_validate_codex_runtime_state(
canonical_home,
trusted_binary_path=trusted_binary_path,
)
marker = canonical_home / _SUBSCRIPTION_PROFILE_MARKER
if require_marker:
try:
marker_data = json.loads(marker.read_text(encoding="utf-8"))
except (OSError, ValueError) as exc:
raise CodexSubscriptionUnavailable(
"Use Dodaios's subscription-voice login before starting voice mode."
) from exc
if marker_data != {
"schema": _SUBSCRIPTION_PROFILE_SCHEMA,
"purpose": "realtime_transport",
}:
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile marker is invalid."
)
return canonical_home
def _rebuild_invalid_subscription_home() -> None:
"""Remove an invalid Jarvis-owned voice profile so login can rebuild it.
Reached only from an explicit user action (Connect / Disconnect): the
directory is Jarvis's own — never user documents — and its only meaningful
content is the dedicated login the user is actively replacing or removing.
Without this, ``setup_invalid`` was an in-app dead end whose card text
demanded a reconnect that failed on the very same validation (AGENTS.md
§3: recoverable IN-APP). A symlinked profile is detached, never followed.
"""
from dodaios.core.paths import user_data_dir
try:
root = user_data_dir().resolve(strict=True)
except OSError as exc:
raise CodexSubscriptionUnavailable(
"Dodaios's private data directory could not be verified."
) from exc
candidate = root / _SUBSCRIPTION_HOME_DIRNAME
try:
if not candidate.exists() and not candidate.is_symlink():
return
if _is_link_or_reparse(candidate):
# Detach the link/junction itself; never follow it.
candidate.unlink()
return
shutil.rmtree(candidate)
except OSError as exc:
raise CodexSubscriptionUnavailable(
"The invalid Codex voice profile could not be removed. Delete the "
f"'{_SUBSCRIPTION_HOME_DIRNAME}' folder in Dodaios's data "
"directory manually."
) from exc
def _clear_subscription_runtime_state() -> None:
"""Delete only Codex's ephemeral ``tmp/`` scratch inside the profile.
The scratch is regenerated on the CLI's next run and holds no credential,
so an unrecognised file in there must cost the user a directory Codex
rebuilds by itself — never the ChatGPT login sitting next to it.
"""
from dodaios.core.paths import user_data_dir
try:
root = user_data_dir().resolve(strict=True)
except OSError as exc:
raise CodexSubscriptionUnavailable(
"Dodaios's private data directory could not be verified."
) from exc
runtime_root = root / _SUBSCRIPTION_HOME_DIRNAME / "tmp"
try:
if not runtime_root.exists() and not runtime_root.is_symlink():
return
if _is_link_or_reparse(runtime_root):
# Detach the link itself; never follow it out of the profile.
runtime_root.unlink()
return
shutil.rmtree(runtime_root)
except OSError as exc:
raise CodexSubscriptionRuntimeStateInvalid(
"The Codex voice runtime state could not be cleared. Close any "
"running Codex process and try again."
) from exc
def _prepare_subscription_login_home() -> Path:
try:
home = _validated_subscription_home(create=True, require_marker=False)
except CodexSubscriptionInspectionFailed:
# Transiently unreadable is NOT license to delete anything.
raise
except CodexSubscriptionRuntimeStateInvalid:
# Codex's own scratch, not the login. Clear ONLY that and re-validate;
# the profile — and the ChatGPT login inside it — survives. If it still
# fails, the honest error reaches the user instead of a silent wipe.
_clear_subscription_runtime_state()
home = _validated_subscription_home(create=True, require_marker=False)
except CodexSubscriptionUnavailable:
# The profile is invalid and the user explicitly asked for a fresh
# login — rebuild the Jarvis-owned directory from scratch. The short
# retry rides out Windows' delete-pending window (an indexer or AV
# briefly holding the freshly removed directory open).
_rebuild_invalid_subscription_home()
last_error: CodexSubscriptionUnavailable | None = None
for _attempt in range(3):
try:
home = _validated_subscription_home(
create=True, require_marker=False
)
break
except CodexSubscriptionUnavailable as exc:
# Windows delete-pending can briefly block the recreate.
last_error = exc
time.sleep(0.2)
else:
raise CodexSubscriptionUnavailable(
"The Codex voice profile could not be rebuilt. "
"Try Connect again in a moment."
) from last_error
marker = home / _SUBSCRIPTION_PROFILE_MARKER
auth_file = home / "auth.json"
if not marker.exists() and auth_file.exists():
raise CodexSubscriptionUnavailable(
"The dedicated Codex voice profile already contains credentials that were "
"not created by Dodaios's direct login flow."
)
if not marker.exists():
payload = json.dumps(
{
"schema": _SUBSCRIPTION_PROFILE_SCHEMA,
"purpose": "realtime_transport",
},
separators=(",", ":"),
)
temporary = home / f"{_SUBSCRIPTION_PROFILE_MARKER}.{secrets.token_hex(4)}.tmp"
try:
temporary.write_text(payload, encoding="utf-8")
os.chmod(temporary, 0o600)
os.replace(temporary, marker)
except BaseException:
with suppress(OSError):
temporary.unlink()
raise
return _validated_subscription_home(create=False, require_marker=True)
def _normalized_machine() -> str:
machine = platform.machine().strip().lower()
return {
"aarch64": "arm64",
"amd64": "x86_64",
"x64": "x86_64",
}.get(machine, machine)
def _sha256_file(path: Path) -> str:
digest = hashlib.sha256()
flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
descriptor = os.open(path, flags)
with os.fdopen(descriptor, "rb") as handle:
opened = os.fstat(handle.fileno())
if not stat.S_ISREG(opened.st_mode):
raise OSError("Codex executable is not a regular file.")
while chunk := handle.read(1024 * 1024):
digest.update(chunk)
completed = os.fstat(handle.fileno())
final = path.stat()
stable_fields = ("st_dev", "st_ino", "st_size", "st_mtime_ns")
# Python 3.12 on Windows exposes different ctime semantics for fstat() and
# path stat(): the former may mirror mtime while the latter reports file
# creation time. Comparing them rejects an unchanged executable. Device,
# inode/file index, size, mtime, and the approved digest still bind the
# opened handle to the final path. POSIX ctime remains a useful extra guard.
if sys.platform != "win32":
stable_fields += ("st_ctime_ns",)
if any(
getattr(opened, field, None) != getattr(completed, field, None)
or getattr(opened, field, None) != getattr(final, field, None)
for field in stable_fields
):
raise OSError("Codex executable changed while it was being verified.")
return digest.hexdigest()
_SHA256_CACHE_MAX_ENTRIES: Final = 16
_SHA256_IDENTITY = tuple[int, int, int, int, int]
_sha256_cache: dict[str, tuple[_SHA256_IDENTITY, str]] = {}
_sha256_cache_lock = threading.Lock()
def _file_identity_signature(identity: os.stat_result) -> _SHA256_IDENTITY:
"""Everything about a file that must be equal for its digest to be reused."""
return (
identity.st_dev,
identity.st_ino,
identity.st_size,
identity.st_mtime_ns,
# POSIX ctime changes on every write regardless of utimes-forgery; on
# Windows this is creation time and merely harmless extra identity.
identity.st_ctime_ns,
)
def _forget_cached_digest(path: Path) -> None:
"""Drop a memoized digest so the next reader hashes the file again."""
key = os.path.normcase(str(path))
with _sha256_cache_lock:
_sha256_cache.pop(key, None)
def _sha256_file_cached(path: Path) -> str:
"""Memoized ``_sha256_file`` keyed on the file's identity signature.
Hashing the ~100 MB native Codex binary dominated the cost of every status
probe, profile validation, and call start — and each of those runs several
times per voice call. The signature (device, inode, size, mtime_ns,
ctime_ns) is read fresh on EVERY call, so any ordinary change to the file
re-hashes it; the digest is then kept for the process lifetime instead of
expiring on a wall-clock timer, because a timer bounded nothing an
attacker could not simply wait out while costing a full re-hash on every
tick.
The memo authorizes STATUS and profile-validation reads only. The copy
that actually RUNS with the user's ChatGPT identity is hashed without the
memo immediately before spawn (``_verify_spawn_binary``), and that
un-memoized verdict overwrites — or purges — the memo, so the executing
path can never be laundered by a cached digest.
"""
try:
identity = path.stat()
except OSError: # An unreadable identity cannot be memoized — hash fresh.
return _sha256_file(path)
key = os.path.normcase(str(path))
signature = _file_identity_signature(identity)
with _sha256_cache_lock:
entry = _sha256_cache.get(key)
if entry is not None and entry[0] == signature:
return entry[1]
digest = _sha256_file(path)
with _sha256_cache_lock:
if len(_sha256_cache) >= _SHA256_CACHE_MAX_ENTRIES:
_sha256_cache.clear()
_sha256_cache[key] = (signature, digest)
return digest
def _verify_spawn_binary(binary_path: str) -> None:
"""Full, un-memoized hash check of the exact file about to be executed.
The memoized hash is fine for status polling; the copy that runs with the
user's ChatGPT identity gets one fresh verification right before spawn so
a stale memo can never launder an in-place swap into execution. A
microsecond rename-over between this check and exec remains possible on
every platform (no portable fexecve); the guard binds the hash to the
path at verification time, which is the strongest portable guarantee.
This un-memoized verdict is also the memo's corrector: a match refreshes
the entry, a mismatch purges it, so a digest the memo believes can never
outlive the evidence that it is wrong.
"""
path = Path(binary_path)
try:
identity: os.stat_result | None = path.stat()
except OSError: # Unreadable identity: verify anyway, just do not memoize.
identity = None
try:
digest = _sha256_file(path)
except OSError:
# The file could not be hashed at all — a memo that still claims this
# path is approved would outlive the only evidence we have.
_forget_cached_digest(path)
raise
if _trusted_codex_target_for_digest(digest) is None:
_forget_cached_digest(path)
raise CodexSubscriptionUnavailable(
"The Codex executable changed since it was verified."
)
if identity is not None:
with _sha256_cache_lock:
_sha256_cache[os.path.normcase(str(path))] = (
_file_identity_signature(identity),
digest,
)
def _codex_package_roots(launcher: Path) -> list[Path]:
"""Return local npm package roots without invoking npm or trusting PATH order."""
search_dirs = [launcher.parent, *list(launcher.parents)[:8]]
for entry in os.environ.get("PATH", "").split(os.pathsep):
if entry.strip():
search_dirs.append(Path(entry))
try:
from dodaios.core.path_augment import candidate_dirs
search_dirs.extend(Path(entry) for entry in candidate_dirs())
except Exception: # noqa: BLE001 - optional discovery must stay fail-closed
log.debug("Codex package-root discovery could not read augmented paths", exc_info=True)
package_roots: list[Path] = []
for directory in search_dirs:
if directory.name == "codex" and directory.parent.name == "@openai":
package_roots.append(directory)
package_roots.extend(
(
directory / "node_modules" / "@openai" / "codex",
directory.parent / "node_modules" / "@openai" / "codex",
directory.parent / "lib" / "node_modules" / "@openai" / "codex",
)
)
return package_roots
def _trusted_codex_targets_for_platform() -> tuple[
tuple[str, tuple[str, str, str, str]], ...
]:
"""Return exact audited releases for this platform, newest first."""
key = (sys.platform, _normalized_machine())
releases = (
(_SUPPORTED_CODEX_VERSION, _TRUSTED_CODEX_TARGETS),
(_LEGACY_CODEX_VERSION, _LEGACY_TRUSTED_CODEX_TARGETS),
)
return tuple(
(version, target)
for version, targets in releases
if (target := targets.get(key)) is not None
)
def _trusted_codex_target_for_digest(
digest: str,
) -> tuple[str, tuple[str, str, str, str]] | None:
"""Resolve an executable digest to its exact audited release."""
for version, target in _trusted_codex_targets_for_platform():
if digest == target[3]:
return version, target
return None
def _trusted_native_codex_binary(resolved_binary: str, version: str | None) -> str:
"""Locate a SHA-256-approved native executable for an audited release.
The hash is the authority: a candidate matching an official artifact IS
the pinned build, whatever the launcher's ``--version`` said. The version
string is advisory only — the npm ``codex`` launcher needs a working
``node`` on PATH just to print it, and a service process without node used
to fail the whole feature here although the native binary was intact.
"""
release_targets = _trusted_codex_targets_for_platform()
if not release_targets:
# A platform gate, not a setup defect: maps to lifecycle_unavailable,
# whose card text says the feature is not available on this OS yet.
raise CodexSubscriptionContainmentUnavailable(
"This operating-system architecture is not approved for the experimental "
"Codex subscription voice transport."
)
try:
launcher = Path(resolved_binary).resolve(strict=True)
except OSError as exc:
raise CodexSubscriptionUnavailable("The Codex CLI binary is unavailable.") from exc
candidates: list[Path] = [launcher]
package_roots = _codex_package_roots(launcher)
for _release, target in release_targets:
variant, triple, executable_name, _expected_hash = target
for package_root in package_roots:
candidates.extend(
(
package_root
/ "node_modules"
/ "@openai"
/ f"codex-{variant}"
/ "vendor"
/ triple
/ "bin"
/ executable_name,
package_root.parent
/ f"codex-{variant}"
/ "vendor"
/ triple
/ "bin"
/ executable_name,
)
)
seen: set[str] = set()
for candidate in candidates:
try:
canonical = candidate.resolve(strict=True)
key = os.path.normcase(str(canonical))
if key in seen:
continue
seen.add(key)
if _is_link_or_reparse(canonical) or not canonical.is_file():
continue
if _trusted_codex_target_for_digest(
_sha256_file_cached(canonical)
) is not None:
return str(canonical)
except OSError: # Unreadable installation candidates are skipped during discovery.
continue
if version is not None and version.startswith("codex-cli") and (
version not in _SUPPORTED_CODEX_VERSIONS
):
# The launcher answered with a real but different release — name the
# required one instead of a generic hash complaint.
raise CodexSubscriptionBinaryUnsupported(
"Subscription voice supports Codex CLI "
f"{_SUPPORTED_CODEX_VERSION.removeprefix('codex-cli ')} or "
f"{_LEGACY_CODEX_VERSION.removeprefix('codex-cli ')}."
)
raise CodexSubscriptionBinaryUnsupported(
"The installed Codex executable does not match an official approved build."
)
_CLI_VERSION_RE: Final = re.compile(
r"codex-cli \d+\.\d+\.\d+(?:[-+][0-9A-Za-z.]+)?"
)
_HEADLESS_LOGIN_REASON: Final = (
"Interactive subscription-voice login is unavailable on headless Linux. "
"Run Dodaios on a desktop to connect this dedicated profile."
)
_NO_LOGIN_TERMINAL_REASON: Final = (
"Interactive subscription-voice login needs a terminal emulator this "
"desktop does not provide. Install one (for example gnome-terminal, "
"konsole, xfce4-terminal, kitty or alacritty) and connect again."
)
_PURE_WAYLAND_LOGIN_REASON: Final = (
"This pure-Wayland session has no XWayland display, so the isolated "
"subscription login cannot auto-open a browser. Connect opens a terminal; "
"follow the device-login URL printed there."
)
def _headless_linux() -> bool:
"""A Linux host with no graphical session at all."""
return (
sys.platform.startswith("linux")
and not os.environ.get("DISPLAY")
and not os.environ.get("WAYLAND_DISPLAY")
)
def _pure_wayland_linux() -> bool:
"""A graphical Linux session with Wayland but no X/XWayland display."""
return bool(
sys.platform.startswith("linux")
and os.environ.get("WAYLAND_DISPLAY")
and not os.environ.get("DISPLAY")
)
def _linux_login_terminal_missing() -> bool:
"""True on a graphical Linux host with no terminal able to host the login.
Separate from the headless check: a screen exists, so the old probe said
"login_required" and the card offered a Connect that could only ever fail.
"""
if not sys.platform.startswith("linux") or _headless_linux():
return False
try:
from dodaios.codex_auth import ( # noqa: PLC0415
linux_login_terminal_available,
)
return not linux_login_terminal_available()
except Exception: # noqa: BLE001 - an unknown probe must not block a login
log.debug("Linux login-terminal probe failed", exc_info=True)
return False
def _login_required_reason_code() -> CodexSubscriptionReasonCode:
"""The honest "please log in" state for THIS host.
On a headless Linux host the interactive browser login is impossible, so
inviting it would only produce an error toast after the click — the
pre-click truth there is ``lifecycle_unavailable`` (visible degradation). The same holds for a graphical Linux desktop that ships no
terminal able to host the login for its full lifetime. An EXISTING login
still reports ready on such hosts.
"""
if _headless_linux() or _linux_login_terminal_missing():
return "lifecycle_unavailable"
return "login_required"
def _login_required_state(reason: str) -> tuple[str, CodexSubscriptionReasonCode]:
"""Reason text and code for a missing login, coherent on every surface.
When the code degrades to ``lifecycle_unavailable`` (headless host), the
text degrades WITH it: otherwise the 409/400 details and the Test verdict
would keep asking for the exact login the card refuses to offer.
"""
code = _login_required_reason_code()
if code == "lifecycle_unavailable":
reason = (
_HEADLESS_LOGIN_REASON
if _headless_linux()
else _NO_LOGIN_TERMINAL_REASON
)
elif _pure_wayland_linux():
reason = _PURE_WAYLAND_LOGIN_REASON
return reason, code
def _displayable_cli_version(raw: str | None) -> str | None:
"""Return the probe output only when it is an actual version string.
The npm launcher prints a localized shell error instead of a version when
``node`` is missing; that text must never reach the UI's version chip or
count as an installed version. The strict pattern also keeps ANSI noise
and unbounded output off the chip.
"""
text = " ".join(str(raw or "").split())
return text if _CLI_VERSION_RE.fullmatch(text) else None
def _read_codex_capability(binary_path: str | None) -> CodexAppServerCapability:
"""Resolve the CLI; app-server itself authoritatively reads its auth store.
Discovery uses ``codex login status``, whose audited output reports only
the mode and never token contents or account PII. Billing authority comes
only from the live ``account/read`` RPC below.
"""
from dodaios.codex_auth import CodexAuthService # lazy: off the boot path
service = CodexAuthService(
binary_path,
codex_home=codex_subscription_home(),
force_file_auth_store=True,
isolate_openai_environment=True,
)
resolved = service._resolve_binary()
if resolved is None:
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=None,
version=None,
reason="Codex CLI is not installed.",
reason_code="not_installed",
)
version = _displayable_cli_version(service._probe_version(resolved))
try:
resolved_binary = _trusted_native_codex_binary(
resolved,
version,
)
# A hash match proves the exact official build even when the npm
# launcher could not print its version (for example: no node on the
# service PATH).
try:
approved = _trusted_codex_target_for_digest(
_sha256_file_cached(Path(resolved_binary))
)
except OSError:
# Test doubles may stand in for the already-authoritative native
# discovery helper. A real discovery result is an existing file.
approved = None
if approved is not None:
version = approved[0]
elif version not in _SUPPORTED_CODEX_VERSIONS:
version = _SUPPORTED_CODEX_VERSION
except CodexSubscriptionContainmentUnavailable as exc: # Expected platform gate becomes status.
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=resolved,
version=version,
reason=str(exc),
reason_code="lifecycle_unavailable",
)
except CodexSubscriptionBinaryUnsupported as exc:
# No audited release is present (wrong version or unknown build). The
# actionable state is "install the supported release" — the card then
# shows the preferred npm command instead of a profile warning.
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=resolved,
version=version,
reason=str(exc),
reason_code="not_installed",
)
except CodexSubscriptionUnavailable as exc:
# Convert setup failure into a safe status snapshot.
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=resolved,
version=version,
reason=str(exc),
reason_code="setup_invalid",
)
try:
home = _validated_subscription_home(
create=False,
require_marker=True,
trusted_binary_path=resolved_binary,
)
except CodexSubscriptionProfileMissing as exc: # Missing login becomes an actionable snapshot.
reason, reason_code = _login_required_state(str(exc))
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=resolved_binary,
version=version,
reason=reason,
reason_code=reason_code,
)
except CodexSubscriptionInspectionFailed as exc:
# An OS read hiccup is transiently unknown, never a proven-broken
# profile that tells the user to recreate their login.
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=resolved_binary,
version=version,
reason=f"{exc} Retrying shortly.",
reason_code="busy",
)
except CodexSubscriptionUnavailable as exc: # Unsafe profile state becomes a status snapshot.
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=resolved_binary,
version=version,
reason=str(exc),
reason_code="setup_invalid",
)
status_log_dir = Path(tempfile.mkdtemp(prefix="jarvis-codex-status-"))
try:
logged_in, login_mode = CodexAuthService(
resolved_binary,
codex_home=home,
force_file_auth_store=True,
isolate_openai_environment=True,
log_dir=status_log_dir,
).login_status()
finally:
shutil.rmtree(status_log_dir, ignore_errors=True)
# Codex 0.146 creates only a persistent installation UUID plus its locked
# tmp/arg0 aliases before parsing config. Validate that exact runtime
# footprint after every status probe; any other state remains fail-closed.
try:
_validated_subscription_home(
create=False,
require_marker=True,
trusted_binary_path=resolved_binary,
)
except CodexSubscriptionProfileMissing as exc:
# Missing login remains a normal not-ready state.
reason, reason_code = _login_required_state(str(exc))
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=resolved_binary,
version=version,
reason=reason,
reason_code=reason_code,
)
except CodexSubscriptionInspectionFailed as exc:
# Transiently unreadable, not proven-broken (see the first block).
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=resolved_binary,
version=version,
reason=f"{exc} Retrying shortly.",
reason_code="busy",
)
except CodexSubscriptionUnavailable as exc: # Profile validation failure is returned to the UI.
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=resolved_binary,
version=version,
reason=str(exc),
reason_code="setup_invalid",
)
if login_mode == "probe_failed":
# The CLI could not be asked (spawn failure or timeout). That is a
# transiently unknown state — publishing it as "login required" would
# flip a connected card to "not connected" on one slow subprocess.
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=resolved_binary,
version=version,
reason="The Codex login status probe failed; retrying shortly.",
reason_code="busy",
)
chatgpt_login = logged_in and login_mode == "chatgpt"
if chatgpt_login:
return CodexAppServerCapability(
available=True,
# Advisory only: the CLI emits a fixed PII-free mode string. The
# live account/read RPC below proves ChatGPT mode and the plan.
chatgpt_authenticated=True,
binary_path=resolved_binary,
version=version,
reason="Dedicated ChatGPT login is available.",
reason_code="ready",
)
reason, reason_code = _login_required_state(
"Use Dodaios's subscription-voice login to connect ChatGPT."
)
return CodexAppServerCapability(
available=True,
chatgpt_authenticated=False,
binary_path=resolved_binary,
version=version,
reason=reason,
reason_code=reason_code,
)
def _subscription_environment(
codex_home: Path,
workspace: _SafeTransportWorkspace,
) -> dict[str, str]:
"""Minimal child environment containing no inherited provider tokens.
``CODEX_HOME`` is the fixed Jarvis-owned identity. Provider, cloud, proxy,
keyring-session, and billing-token environment variables are not inherited.
"""
environment = {
name: value
for name, value in os.environ.items()
if _subscription_env_allowed(name)
}
environment.update(
{
"APPDATA": str(workspace.child_appdata),
"CODEX_HOME": str(codex_home),
"HOME": str(workspace.child_home),
"LOCALAPPDATA": str(workspace.child_local_appdata),
"RUST_BACKTRACE": "0",
"RUST_LOG": "warn",
"TEMP": str(workspace.child_tmp),
"TMP": str(workspace.child_tmp),
"TMPDIR": str(workspace.child_tmp),
"USERPROFILE": str(workspace.child_home),
}
)
environment.pop("HOMEDRIVE", None)
environment.pop("HOMEPATH", None)
# Persisted Remote Control is resolved before initialize/config audit in
# Codex 0.146. This one documented process guard disables that startup
# path before app-server can make any outbound connection.
environment["CODEX_INTERNAL_APP_SERVER_REMOTE_CONTROL_DISABLED"] = "1"
return environment
def _create_safe_transport_workspace(
purpose: CodexAppServerPurpose = "realtime",
) -> _SafeTransportWorkspace:
from dodaios.core.private_directory import ( # noqa: PLC0415
ensure_owner_only_directory,
)
try:
temporary_root = Path(tempfile.gettempdir()).resolve(strict=True)
workspace_label = "voice" if purpose == "realtime" else "text"
root = temporary_root / (
f"jarvis-codex-{workspace_label}-{secrets.token_hex(16)}"
)
ensure_owner_only_directory(root, create=True)
root = root.resolve(strict=True)
if root.parent != temporary_root:
raise RuntimeError("The private workspace escaped its temporary root.")
except (OSError, RuntimeError) as exc:
raise CodexSubscriptionUnavailable(
"The private Codex transport workspace could not be secured."
) from exc
instructions = root / "transport-instructions.md"
compact_prompt = root / "transport-compact-prompt.md"
model_catalog = root / "model-catalog.json"
sqlite_home = root / "sqlite"
log_dir = root / "logs"
child_home = root / "home"
child_appdata = root / "appdata"
child_local_appdata = root / "local-appdata"
child_tmp = root / "tmp"
try:
instruction_floor = (
_TEXT_BASE_INSTRUCTIONS
if purpose == "text"
else _TRANSPORT_BASE_INSTRUCTIONS
)
instructions.write_text(instruction_floor, encoding="utf-8")
compact_prompt.write_text(instruction_floor, encoding="utf-8")
for directory in (
sqlite_home,
log_dir,
child_home,
child_appdata,
child_local_appdata,
child_tmp,
):
directory.mkdir()
model_catalog.write_text(
json.dumps(
{
"models": [
{
"slug": "gpt-5.1-codex",
"display_name": "Dodaios transport boundary",
"description": None,
"supported_reasoning_levels": [],
"shell_type": "disabled",
"visibility": "hide",
"supported_in_api": True,
"priority": 0,
"availability_nux": None,
"upgrade": None,
"base_instructions": instruction_floor,
"model_messages": None,
"support_verbosity": False,
"default_verbosity": None,
"apply_patch_tool_type": None,
"truncation_policy": {"mode": "tokens", "limit": 10_000},
"supports_parallel_tool_calls": False,
"experimental_supported_tools": [],
}
]
},
separators=(",", ":"),
),
encoding="utf-8",
)
except BaseException:
shutil.rmtree(root, ignore_errors=True)
raise
return _SafeTransportWorkspace(
root=root,
instructions=instructions,
compact_prompt=compact_prompt,
model_catalog=model_catalog,
sqlite_home=sqlite_home,
log_dir=log_dir,
child_home=child_home,
child_appdata=child_appdata,
child_local_appdata=child_local_appdata,
child_tmp=child_tmp,
)
def _windows_creationflags(*, allow_breakaway: bool) -> int:
flags = NO_WINDOW_CREATIONFLAGS
if sys.platform == "win32" and allow_breakaway:
flags |= getattr(subprocess, "CREATE_BREAKAWAY_FROM_JOB", 0x01000000)
return flags
def _thread_id_from_params(params: Mapping[str, Any]) -> str | None:
direct = params.get("threadId")
if isinstance(direct, str) and direct:
return direct
for key in ("thread", "turn", "item"):
nested = params.get(key)
if not isinstance(nested, Mapping):
continue
value = nested.get("threadId")
if isinstance(value, str) and value:
return value
if key == "thread":
value = nested.get("id")
if isinstance(value, str) and value:
return value
return None
def _result_dict(method: str, result: Any) -> dict[str, Any]:
if isinstance(result, dict):
return result
raise CodexAppServerError(f"Codex app-server returned an invalid {method} result.")
def _validated_realtime_initial_items(
initial_items: Sequence[Mapping[str, Any]] | None,
) -> list[dict[str, str]]:
"""Bound the exact role/text startup-history surface audited upstream."""
if initial_items is None:
return []
if (
not isinstance(initial_items, Sequence)
or isinstance(initial_items, (str, bytes))
or len(initial_items) > _MAX_REALTIME_INITIAL_ITEMS
):
raise CodexSubscriptionUnavailable(
"Codex realtime startup history is invalid or too large."
)
validated: list[dict[str, str]] = []
total_bytes = 0
for item in initial_items:
if not isinstance(item, Mapping) or set(item) != {"role", "text"}:
raise CodexSubscriptionUnavailable(
"Codex realtime startup history contains an invalid item."
)
role = item.get("role")
text = item.get("text")
if (
not isinstance(role, str)
or role not in _REALTIME_INITIAL_ROLES
or not isinstance(text, str)
):
raise CodexSubscriptionUnavailable(
"Codex realtime startup history contains an invalid role or text."
)
clean_text = text.strip()
if not clean_text:
continue
total_bytes += len(clean_text.encode("utf-8"))
if total_bytes > _MAX_REALTIME_INITIAL_TEXT_BYTES:
raise CodexSubscriptionUnavailable(
"Codex realtime startup history is too large."
)
validated.append({"role": str(role), "text": clean_text})
return validated
def _validated_realtime_audited_optional(
*,
realtime_start_instructions: str | None,
realtime_end_instructions: str | None,
codex_responses_as_items: bool | None,
codex_response_item_prefix: str | None,
codex_response_handoff_mode: str | None,
codex_response_handoff_channel_prefixes: Sequence[str] | None,
) -> dict[str, Any]:
"""Validate the optional 0.147-audited realtime start fields.
Field names mirror the upstream ``ThreadRealtimeStartParams`` schema
byte-for-byte (verified against the codex-cli 0.147.0 binary's serde name
table): ``realtimeStartInstructions``, ``realtimeEndInstructions``,
``codexResponsesAsItems``, ``codexResponseItemPrefix``,
``codexResponseHandoffMode``, ``codexResponseHandoffChannelPrefixes``.
Only fields the caller actually provided are returned; empty strings and
empty sequences count as not provided.
"""
audited: dict[str, Any] = {}
instruction_fields = (
("realtimeStartInstructions", realtime_start_instructions),
("realtimeEndInstructions", realtime_end_instructions),
)
for field_name, value in instruction_fields:
if value is None:
continue
if not isinstance(value, str):
raise CodexSubscriptionUnavailable("Codex realtime session instructions are invalid.")
clean = value.strip()
if len(clean.encode("utf-8")) > _MAX_REALTIME_START_PROMPT_BYTES:
raise CodexSubscriptionUnavailable("Codex realtime session instructions are too large.")
if clean:
audited[field_name] = clean
if codex_responses_as_items is not None:
if not isinstance(codex_responses_as_items, bool):
raise CodexSubscriptionUnavailable("Codex realtime handoff routing fields are invalid.")
audited["codexResponsesAsItems"] = codex_responses_as_items
string_fields = (
("codexResponseItemPrefix", codex_response_item_prefix),
("codexResponseHandoffMode", codex_response_handoff_mode),
)
for field_name, value in string_fields:
if value is None:
continue
if not isinstance(value, str):
raise CodexSubscriptionUnavailable("Codex realtime handoff routing fields are invalid.")
clean = value.strip()
if clean:
audited[field_name] = clean
if codex_response_handoff_channel_prefixes is not None:
if isinstance(codex_response_handoff_channel_prefixes, (str, bytes)) or not isinstance(
codex_response_handoff_channel_prefixes, Sequence
):
raise CodexSubscriptionUnavailable("Codex realtime handoff routing fields are invalid.")
prefixes: list[str] = []
for prefix in codex_response_handoff_channel_prefixes:
if not isinstance(prefix, str) or not prefix.strip():
raise CodexSubscriptionUnavailable(
"Codex realtime handoff routing fields are invalid."
)
prefixes.append(prefix.strip())
if prefixes:
audited["codexResponseHandoffChannelPrefixes"] = prefixes
return audited
def _config_layers(result: Mapping[str, Any]) -> tuple[Mapping[str, Any], ...]:
raw_layers = result.get("layers")
if not isinstance(raw_layers, list):
raise CodexSubscriptionUnavailable(
"Codex effective configuration could not be verified."
)
layers: list[Mapping[str, Any]] = []
for layer in raw_layers:
if not isinstance(layer, Mapping):
raise CodexSubscriptionUnavailable(
"Codex effective configuration contained an invalid layer."
)
config = layer.get("config")
if not isinstance(config, Mapping):
raise CodexSubscriptionUnavailable(
"Codex effective configuration contained an unreadable layer."
)
layers.append(config)
return tuple(layers)
def _config_layer_entries(
result: Mapping[str, Any],
) -> tuple[tuple[str, Mapping[str, Any]], ...]:
raw_layers = result.get("layers")
if not isinstance(raw_layers, list):
raise CodexSubscriptionUnavailable(
"Codex effective configuration could not be verified."
)
entries: list[tuple[str, Mapping[str, Any]]] = []
for layer in raw_layers:
if not isinstance(layer, Mapping):
raise CodexSubscriptionUnavailable(
"Codex effective configuration contained an invalid layer."
)
raw_name = layer.get("name")
if isinstance(raw_name, Mapping):
raw_name = raw_name.get("type")
if not isinstance(raw_name, str) or not raw_name:
raise CodexSubscriptionUnavailable(
"Codex effective configuration contained an unnamed layer."
)
config = layer.get("config")
if not isinstance(config, Mapping):
raise CodexSubscriptionUnavailable(
"Codex effective configuration contained an unreadable layer."
)
entries.append((raw_name, config))
return tuple(entries)
def _layer_value(
layers: Sequence[Mapping[str, Any]], path: Sequence[str]
) -> Any:
"""Return the highest-precedence explicitly configured value for a path."""
for layer in layers: # config/read returns highest precedence first.
value: Any = layer
for part in path:
if not isinstance(value, Mapping) or part not in value:
value = _MISSING
break
value = value[part]
if value is not _MISSING:
return value
return _MISSING
def _mcp_server_ids(layers: Sequence[Mapping[str, Any]]) -> tuple[str, ...]:
names: set[str] = set()
for layer in layers:
servers = layer.get("mcp_servers")
if isinstance(servers, Mapping):
names.update(str(name) for name in servers if str(name))
return tuple(sorted(names))
class CodexNotificationSubscription:
"""A notification queue bound to exactly one app-server thread."""
def __init__(
self,
client: CodexAppServerClient,
thread_id: str,
max_queue_size: int,
) -> None:
self._client = client
self.thread_id = thread_id
self._queue: asyncio.Queue[_SubscriptionItem] = asyncio.Queue(maxsize=max_queue_size)
self._closed = False
async def get(self, timeout_s: float | None = None) -> CodexAppServerNotification:
"""Return the next notification, with an optional bounded wait."""
try:
if timeout_s is None:
item = await self._queue.get()
else:
item = await asyncio.wait_for(self._queue.get(), timeout=timeout_s)
except TimeoutError as exc:
raise CodexAppServerTimeout(
f"Timed out waiting for a Codex notification on {self.thread_id}."
) from exc
if item is _SUBSCRIPTION_END:
raise CodexAppServerDisconnected("Codex notification subscription closed.")
if isinstance(item, BaseException):
raise item
if not isinstance(item, CodexAppServerNotification):
raise CodexAppServerDisconnected("Codex notification stream is invalid.")
return item
async def wait_for(
self, method: str, timeout_s: float | None = None
) -> CodexAppServerNotification:
"""Wait for one method on this subscription.
Non-matching items are consumed only from this subscription. Callers
that need the complete stream should keep their own parallel
subscription; notifications are broadcast to every subscriber.
"""
deadline = None
if timeout_s is not None:
deadline = asyncio.get_running_loop().time() + timeout_s
while True:
remaining = None
if deadline is not None:
remaining = deadline - asyncio.get_running_loop().time()
if remaining <= 0:
raise CodexAppServerTimeout(
f"Timed out waiting for Codex notification {method}."
)
notification = await self.get(remaining)
if notification.method == method:
return notification
def close(self) -> None:
"""Unregister this local subscriber. Safe to call more than once."""
if self._closed:
return
self._closed = True
self._client._remove_subscription(self)
self._replace_queue_with(_SUBSCRIPTION_END)
def _publish(self, item: _SubscriptionItem) -> None:
if self._closed:
return
try:
self._queue.put_nowait(item)
except asyncio.QueueFull:
# Continuing with missing audio/transcript frames would corrupt the
# session invisibly. Terminate this subscriber and replace every
# queued frame with one explicit overflow error instead.
self._closed = True
self._client._remove_subscription(self)
self._replace_queue_with(
CodexNotificationOverflow(
"Codex realtime notification buffer overflowed; session closed."
)
)
def _fail(self, error: BaseException) -> None:
if self._closed:
return
self._closed = True
self._client._remove_subscription(self)
self._replace_queue_with(error)
def _replace_queue_with(self, item: _SubscriptionItem) -> None:
while True:
try:
self._queue.get_nowait()
except asyncio.QueueEmpty: # The terminal item can now fit without a drop.
break
self._queue.put_nowait(item)
async def __aenter__(self) -> CodexNotificationSubscription:
return self
async def __aexit__(self, *_exc: object) -> None:
self.close()
def __aiter__(self) -> AsyncIterator[CodexAppServerNotification]:
return self
async def __anext__(self) -> CodexAppServerNotification:
try:
return await self.get()
except CodexAppServerDisconnected:
raise StopAsyncIteration from None
class CodexAppServerClient:
"""Lazy JSONL client for one persistent ``codex app-server`` process."""
def __init__(
self,
binary_path: str | None = None,
request_timeout_s: float = _DEFAULT_REQUEST_TIMEOUT_S,
*,
purpose: CodexAppServerPurpose = "realtime",
) -> None:
if purpose not in ("realtime", "text"):
raise ValueError("purpose must be 'realtime' or 'text'")
self._binary_path = (binary_path or "").strip() or None
self._purpose: CodexAppServerPurpose = purpose
self._request_timeout_s = max(0.1, float(request_timeout_s))
self._child_environment: dict[str, str] = {}
self._process: asyncio.subprocess.Process | None = None
self._process_tree: ProcessTree | None = None
self._lifeline_write_fd: int | None = None
self._reader_task: asyncio.Task[None] | None = None
self._stderr_task: asyncio.Task[None] | None = None
self._start_lock = asyncio.Lock()
self._thread_start_lock = asyncio.Lock()
self._write_lock = asyncio.Lock()
self._pending: dict[int, tuple[str, asyncio.Future[Any]]] = {}
self._subscriptions: dict[str, set[CodexNotificationSubscription]] = {}
self._next_request_id = 1
self._workspace: _SafeTransportWorkspace | None = None
self._sink_server: asyncio.Server | None = None
self._sink_base_url: str | None = None
self._trusted_binary_path: str | None = None
self._trusted_binary_version: str | None = None
# Ownership epoch of this client's profile reservation; None when the
# client holds none. Releases quote it so stale teardown can never
# touch a newer reservation.
self._profile_transport_epoch: int | None = None
self._owner_loop: asyncio.AbstractEventLoop | None = None
self._transport_provider_id = f"jarvis_voice_{secrets.token_hex(16)}"
self._ready = False
# Set once ``close()`` ran. A closed client has released its profile
# reservation and deleted its workspace, so restarting it would fight
# the successor for the single-owner profile; callers acquire a fresh
# one from ``get_shared_codex_app_server`` instead.
self._closed = False
# The live process whose FULL startup audit (profile, live account,
# config requirements, effective config) just passed. ``thread_start``
# consumes this to skip repeating that identical audit microseconds
# later; every WARM thread start still re-audits. The (process, stamp)
# pair below extends the one-shot token by a short TTL for exactly one
# scenario: a failed host-candidate media path retries with STUN and
# pays a SECOND thread_start seconds after the audit passed — that
# retry rides the same audit instead of re-running three RPCs and a
# profile walk. Warm starts minutes later still re-audit in full, so
# "re-read immediately before EVERY subscription thread" keeps its
# meaning (the wake ride below is the one TTL-bounded exception, and
# it too exists only because a full audit just passed).
self._startup_audit_process: asyncio.subprocess.Process | None = None
self._audited_process: asyncio.subprocess.Process | None = None
self._startup_audit_at = 0.0
# Wake ride minted by ``prime_startup_audit``: a warm/verify pass that
# just COMPLETED the full startup audit stamps this (process, time)
# pair so one wake-word thread start arriving within the same short
# TTL can ride that audit instead of repeating it on the identical
# process. One-shot — thread_start consumes it on first read — and
# never minted without a full audit actually passing, so the audit
# itself is not weakened, only de-duplicated.
self._warm_audit_process: asyncio.subprocess.Process | None = None
self._warm_audit_at = 0.0
def _assert_owner_loop(self) -> asyncio.AbstractEventLoop:
loop = asyncio.get_running_loop()
if self._owner_loop is None:
self._owner_loop = loop
elif self._owner_loop is not loop:
raise CodexSubscriptionUnavailable(
"Codex app-server client ownership cannot cross event loops."
)
return loop
async def capability_status(self) -> CodexAppServerCapability:
"""Return a bounded, PII-free ChatGPT-login capability snapshot.
The caller must already own the profile (``ensure_started`` reserves
the transport first): this probe runs the Codex CLI against
``CODEX_HOME`` and racing it with a login, logout, or another probe
can corrupt the profile's auth and runtime files.
"""
try:
# The subprocesses inside this synchronous probe each have their own
# hard timeout. Do not wrap ``to_thread`` in ``wait_for``: cancelling
# that await leaves the worker thread running against CODEX_HOME and
# would release the profile mutation gate too early.
binary_path = self._binary_path
def _probe_and_publish() -> CodexAppServerCapability:
# While this client reserves the transport, ordinary status
# probes answer "busy". Publishing this authoritative result
# keeps every concurrent status caller truthful during
# app-server startup and wakes waiters parked on the busy
# window. Probe AND publish stay in the worker thread: the
# login mutex can be held across filesystem work, and the
# event loop must never block on it.
capability = _read_codex_capability(binary_path)
with _subscription_login_lock:
_store_subscription_snapshot_locked(binary_path, capability)
return capability
return await asyncio.to_thread(_probe_and_publish)
except TimeoutError: # The returned status reports this bounded probe failure.
# Transiently unknown — everywhere else a failed PROBE maps to
# busy, never to a proven-broken setup.
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=None,
version=None,
reason="Codex login status timed out; retrying shortly.",
reason_code="busy",
)
except Exception as exc: # noqa: BLE001 - status must degrade honestly
log.warning(
"Codex subscription status failed (%s); app-server stays disabled",
type(exc).__name__,
exc_info=True,
)
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=None,
version=None,
reason="Codex login status could not be verified; retrying shortly.",
reason_code="busy",
)
@property
def running(self) -> bool:
process = self._process
return process is not None and process.returncode is None
@property
def ready(self) -> bool:
"""Whether handshake and live ChatGPT account verification completed."""
return self.running and self._ready
async def ensure_started(self) -> None:
"""Start and initialize app-server once, only when first needed."""
self._assert_owner_loop()
if self.ready:
return
if self._closed:
# Restarting a closed client would race the successor for the
# single-owner profile and wedge it behind an unactionable
# "already owned" error. Name the recovery instead.
raise CodexSubscriptionUnavailable(
"This subscription-voice transport was closed. Start voice "
"again to open a new one."
)
async with self._start_lock:
if self.ready:
return
if self._closed:
raise CodexSubscriptionUnavailable(
"This subscription-voice transport was closed. Start voice "
"again to open a new one."
)
if self._process is not None:
await self._close_process(
CodexAppServerDisconnected("Codex app-server exited."),
expected=False,
)
# Off the event loop: reserving may wait out a running status
# probe. Cancellation safety lives entirely in worker threads: a
# cancel can interrupt any await here (even a shielded one, on a
# second cancel), so no loop-side variable may decide whether the
# reservation needs releasing. The reserve worker records its own
# outcome; on cancellation a detached worker waits for it to
# settle and releases the orphan, so the profile can never stay
# parked on "voice is starting" forever.
# Exactly-one-decider contract: the reserve worker and the
# abandoner agree under a tiny lock who releases the epoch, so no
# interleaving of cancellation, executor scheduling, or a second
# ensure_started can leak the reservation OR release a newer one
# (the epoch token makes stale releases no-ops). No timeouts: a
# give-up path would turn executor saturation into a permanent
# claim leak, because the worker would still claim later with
# nobody left to release.
# RT-SPAWN sub-spans: the cold bundle is the biggest single chunk
# of a session open, and without per-step numbers "the handshake
# is slow" is unattributable. Local stamps only; one summary INFO
# on success.
spans: dict[str, int] = {}
bundle_started = time.monotonic()
last_stamp = bundle_started
def _stamp(name: str) -> None:
nonlocal last_stamp
now = time.monotonic()
spans[name] = int((now - last_stamp) * 1000.0)
last_stamp = now
decision_lock = threading.Lock()
abandoned = threading.Event()
published_epoch: list[int] = []
def _reserve() -> None:
# A raising reserve holds nothing and propagates through the
# awaited future; only a SUCCESSFUL reserve needs a decider.
epoch = _reserve_subscription_transport(self)
with decision_lock:
if not abandoned.is_set():
self._profile_transport_epoch = epoch
published_epoch.append(epoch)
return
# The caller was cancelled before we finished: nobody will
# ever use this reservation, so this worker releases it.
_release_subscription_transport(self, epoch)
reserve_future = asyncio.get_running_loop().run_in_executor(
None, _reserve
)
# A cancelled awaiter leaves the worker's exception unretrieved;
# consume it so asyncio does not log a spurious GC error.
reserve_future.add_done_callback(
lambda f: None if f.cancelled() else f.exception()
)
try:
await asyncio.shield(reserve_future)
except asyncio.CancelledError:
with decision_lock:
abandoned.set()
epoch = published_epoch[0] if published_epoch else None
if epoch is not None and self._profile_transport_epoch == epoch:
self._profile_transport_epoch = None
if epoch is not None:
# Already published before the cancel: release off-loop.
try:
threading.Thread(
target=_release_subscription_transport,
args=(self, epoch),
name="codex-reserve-abandon",
daemon=True,
).start()
except RuntimeError:
# Thread exhaustion: a brief inline release beats
# leaking the reservation until restart.
_release_subscription_transport(self, epoch)
raise
_stamp("reserve")
async def _release_after_failure() -> None:
epoch = self._profile_transport_epoch
self._profile_transport_epoch = None
if epoch is not None:
await asyncio.shield(
asyncio.to_thread(
_release_subscription_transport, self, epoch
)
)
try:
capability = await self.capability_status()
except BaseException:
await _release_after_failure()
raise
_stamp("capability_probe")
if not capability.available:
await _release_after_failure()
raise CodexSubscriptionUnavailable(capability.reason)
if not capability.binary_path:
await _release_after_failure()
raise CodexSubscriptionUnavailable("Codex CLI binary is unavailable.")
try:
self._trusted_binary_path = capability.binary_path
self._trusted_binary_version = capability.version
codex_home = await asyncio.to_thread(
_validated_subscription_home,
create=False,
require_marker=True,
trusted_binary_path=self._trusted_binary_path,
)
if self._workspace is None:
self._workspace = await asyncio.to_thread(
_create_safe_transport_workspace, self._purpose
)
self._child_environment = _subscription_environment(
codex_home,
self._workspace,
)
if self._purpose == "realtime":
await self._ensure_sink_started()
_stamp("home_workspace_sink")
await asyncio.to_thread(
_verify_spawn_binary, capability.binary_path
)
_stamp("binary_verify")
await self._spawn(capability.binary_path)
_stamp("spawn")
await self._initialize_live_process()
_stamp("initialize")
await self._verify_live_chatgpt_account()
_stamp("account_verify")
self._audit_config_requirements(
await self._read_config_requirements()
)
final_config = await self._read_effective_config()
self._audit_effective_config(final_config)
await asyncio.to_thread(
_validated_subscription_home,
create=False,
require_marker=True,
trusted_binary_path=self._trusted_binary_path,
)
_stamp("config_audit")
self._ready = True
log.info(
"RT-SPAWN span=ensure_started ms=%d detail=%s",
int((time.monotonic() - bundle_started) * 1000.0),
",".join(f"{name}={ms}" for name, ms in spans.items()),
)
# The audit that just passed is byte-for-byte the one
# ``thread_start`` performs. Record which process it covers so
# the very next thread start rides it instead of repeating
# three RPC round trips and a profile walk on the SAME process
# microseconds later.
self._startup_audit_process = self._process
self._audited_process = self._process
self._startup_audit_at = time.monotonic()
def _announce_ready() -> None:
# Status callers waiting out the "voice is starting"
# window can now read the ready transport state directly.
# Off-loop: the login mutex can be held across filesystem
# work by a probe thread. Shielded so a cancellation
# cannot drop the job from the executor queue and leave
# waiters running into their timeout.
with _subscription_login_lock:
_subscription_state_changed.notify_all()
await asyncio.shield(asyncio.to_thread(_announce_ready))
except BaseException as exc:
if isinstance(exc, CodexSubscriptionPlanUnsupported):
# The COLD activation path discovers the refused plan
# here, inside startup — record the sticky diagnosis where
# the truth appears, or every surface keeps claiming ready
# after the one honest toast fades.
await asyncio.shield(
asyncio.to_thread(
set_codex_subscription_activation_block, str(exc)
)
)
await self._close_process(
CodexAppServerDisconnected("Codex app-server initialization failed."),
expected=False,
)
raise
async def _initialize_live_process(self) -> None:
await self._request_live(
"initialize",
{
"clientInfo": {
# The name is the originator the server reports upstream;
# it keeps the value it was registered with. Only the
# display title follows the product name.
"name": "personal_jarvis",
"title": PRODUCT_NAME,
"version": __version__,
},
"capabilities": {
"experimentalApi": self._purpose == "realtime",
"mcpServerOpenaiFormElicitation": False,
"requestAttestation": False,
},
},
timeout_s=self._request_timeout_s,
)
await self._notify_live("initialized", None)
async def _verify_live_chatgpt_account(self) -> None:
account_result = _result_dict(
"account/read",
await self._request_live(
"account/read",
{"refreshToken": False},
timeout_s=self._request_timeout_s,
),
)
account = account_result.get("account")
account_type = account.get("type") if isinstance(account, Mapping) else None
if account_type != "chatgpt" or account_result.get("requiresOpenaiAuth") is not True:
raise CodexSubscriptionUnavailable(
"Codex app-server is not using ChatGPT authentication."
)
plan_type = account.get("planType") if isinstance(account, Mapping) else None
if plan_type not in _PERSONAL_CHATGPT_PLANS:
raise CodexSubscriptionPlanUnsupported(
"Subscription voice permits only personal ChatGPT accounts; workspace, "
"enterprise, education, and unknown plans are refused."
)
async def require_chatgpt_login(self) -> None:
"""Verify the current app-server account through Codex's real store."""
await self.ensure_started()
try:
await self._verify_live_chatgpt_account()
except CodexSubscriptionUnavailable as exc:
if isinstance(exc, CodexSubscriptionPlanUnsupported):
# Recorded where the truth is discovered — this gate is also
# the LIVE call path, so a plan that turns unsupported after
# activation still flips every status surface to the sticky
# diagnosis instead of leaving them all claiming "ready".
# Off-loop and shielded like its cold-start and warm-path
# siblings: an activation timeout must not drop the queued
# recording job.
await asyncio.shield(
asyncio.to_thread(
set_codex_subscription_activation_block, str(exc)
)
)
await self._close_process(
CodexAppServerDisconnected(
"Codex app-server authentication is not ChatGPT."
),
expected=False,
)
raise
# The verify pass just proved the account; completing the FULL startup
# audit here (off the wake critical path) lets one wake word inside
# the ride TTL skip the byte-identical re-audit in ``thread_start``.
# Priming is a pure wake-latency optimization on top of a login that
# was JUST proven, so it is best-effort: any failure short of the
# unambiguous entitlement loss below is logged and dropped — it never
# fails the login result or closes the just-verified process, and the
# next wake word simply pays the full audit in ``thread_start``.
try:
await self.prime_startup_audit(best_effort=True)
except CodexSubscriptionPlanUnsupported:
# The audit's own live account re-read refused the plan — a real
# entitlement loss, recorded sticky where it was discovered. The
# login result must report it, exactly like the gate above.
raise
except Exception:
log.warning(
"Codex warm-audit priming failed after a proven login; "
"skipping the wake ride (the next wake word re-audits in full)",
exc_info=True,
)
async def prime_startup_audit(self, *, best_effort: bool = False) -> None:
"""Complete the full startup audit now and mint the one-shot wake ride.
Runs the byte-identical audit ``thread_start`` performs (profile walk,
live ``account/read``, config requirements, effective config) under the
same lock that serializes thread starts, then stamps the short-TTL
one-shot ride token. A wake word arriving within the TTL rides this
just-passed audit instead of paying it again on the same process; a
wake word arriving later re-audits in full, so "re-read immediately
before EVERY subscription thread" keeps its meaning. The token is only
ever minted from an audit that actually completed — this method never
skips or weakens any check, it only moves the identical work off the
wake critical path.
With ``best_effort=True`` (the ``require_chatgpt_login`` warm path) a
refusal other than the permanently-recorded plan loss leaves the live
process untouched and re-raises for the caller to log-and-drop: the
account was proven moments earlier, so an ambiguous refusal must not
tear down a just-verified process over a wake-latency optimization.
"""
await self.ensure_started()
async with self._thread_start_lock:
live_process = self._process
if live_process is None or live_process.returncode is not None:
raise CodexAppServerDisconnected("Codex app-server is not running.")
if (
self._audited_process is live_process
and time.monotonic() - self._startup_audit_at <= _STARTUP_AUDIT_TTL_S
):
# A full audit of this very process passed within the TTL
# (cold start or a warm thread_start re-audit). Re-mint the
# wake ride from that stamp — its TTL still counts from the
# moment the audit actually passed.
self._warm_audit_process = live_process
self._warm_audit_at = self._startup_audit_at
return
try:
await asyncio.to_thread(
_validated_subscription_home,
create=False,
require_marker=True,
trusted_binary_path=self._trusted_binary_path,
)
await self._verify_live_chatgpt_account()
self._audit_config_requirements(await self._read_config_requirements())
self._audit_effective_config(await self._read_effective_config())
except CodexSubscriptionUnavailable as exc:
if isinstance(exc, CodexSubscriptionPlanUnsupported):
# Same recording rule as the cold-start and warm-call
# paths: the sticky diagnosis is written where the truth
# is discovered.
await asyncio.shield(
asyncio.to_thread(set_codex_subscription_activation_block, str(exc))
)
elif best_effort:
# Ambiguous between a transient hiccup (an antivirus-locked
# profile directory, a config read racing a restart) and a
# real state change — and the account was proven moments
# ago. Keep the just-verified process alive and re-raise
# for the caller to log-and-drop; the next wake word
# re-audits in full.
raise
error = type(exc)(str(exc))
await self._close_process(
CodexAppServerDisconnected("Codex app-server safety state changed."),
expected=False,
)
raise error from None
self._audited_process = live_process
self._startup_audit_at = time.monotonic()
self._warm_audit_process = live_process
self._warm_audit_at = self._startup_audit_at
async def _read_effective_config(self) -> dict[str, Any]:
return _result_dict(
"config/read",
await self._request_live(
"config/read",
{"cwd": self._safe_thread_cwd(), "includeLayers": True},
timeout_s=self._request_timeout_s,
),
)
async def _read_config_requirements(self) -> dict[str, Any]:
return _result_dict(
"configRequirements/read",
await self._request_live(
"configRequirements/read",
{},
timeout_s=self._request_timeout_s,
),
)
@staticmethod
def _audit_config_requirements(result: Mapping[str, Any]) -> None:
if set(result) != {"requirements"} or result.get("requirements") is not None:
raise CodexSubscriptionUnavailable(
"Codex subscription voice refuses managed configuration requirements."
)
async def _ensure_sink_started(self) -> None:
if self._sink_server is not None:
return
async def reject_connection(
_reader: asyncio.StreamReader,
writer: asyncio.StreamWriter,
) -> None:
try:
writer.write(
b"HTTP/1.1 403 Forbidden\r\nContent-Length: 0\r\n"
b"Connection: close\r\n\r\n"
)
await writer.drain()
except (ConnectionError, OSError): # Diagnostic peer may close before reply.
pass
finally:
writer.close()
with suppress(Exception):
await writer.wait_closed()
try:
server = await asyncio.start_server(reject_connection, "127.0.0.1", 0)
except OSError as exc:
raise CodexSubscriptionUnavailable(
"The local Codex billing-isolation sink could not be started."
) from exc
sockets = server.sockets or ()
if len(sockets) != 1:
server.close()
await server.wait_closed()
raise CodexSubscriptionUnavailable(
"The local Codex billing-isolation sink is unavailable."
)
address = sockets[0].getsockname()
if not isinstance(address, tuple) or len(address) < 2:
server.close()
await server.wait_closed()
raise CodexSubscriptionUnavailable(
"The local Codex billing-isolation sink returned an invalid address."
)
self._sink_server = server
self._sink_base_url = f"http://127.0.0.1:{int(address[1])}/v1"
def _audit_effective_config(
self,
result: Mapping[str, Any],
) -> None:
entries = _config_layer_entries(result)
layers = tuple(config for _name, config in entries)
session_layers = [config for name, config in entries if name == "sessionFlags"]
if len(session_layers) != 1:
raise CodexSubscriptionUnavailable(
"Codex session configuration provenance could not be verified."
)
for name, config in entries:
if name != "sessionFlags" and config:
raise CodexSubscriptionUnavailable(
"Codex subscription voice refuses non-empty user, project, system, "
"MDM, enterprise, profile, or legacy configuration layers."
)
expected_paths: dict[tuple[str, ...], Any] = {
("analytics", "enabled"): False,
("approval_policy",): "never",
("cli_auth_credentials_store",): "file",
("chatgpt_base_url",): _OFFICIAL_CHATGPT_BASE,
("history", "persistence"): "none",
("include_apps_instructions",): False,
("include_collaboration_mode_instructions",): False,
("include_environment_context",): False,
("include_permissions_instructions",): False,
("memories", "dedicated_tools"): False,
("memories", "generate_memories"): False,
("memories", "use_memories"): False,
("log_dir",): self._log_dir(),
("model_instructions_file",): self._safe_instructions_file(),
("notify",): [],
("openai_base_url",): _OFFICIAL_OPENAI_API_BASE,
("orchestrator", "mcp", "enabled"): False,
("orchestrator", "skills", "enabled"): False,
("otel", "exporter"): "none",
("otel", "log_user_prompt"): False,
("otel", "metrics_exporter"): "none",
("otel", "trace_exporter"): "none",
("project_doc_max_bytes",): 0,
("sandbox_mode",): "read-only",
("sqlite_home",): self._sqlite_home(),
("skills", "bundled", "enabled"): False,
("skills", "include_instructions"): False,
("tools", "web_search"): False,
}
for feature in _DISABLED_APP_SERVER_FEATURES:
expected_paths[("features", feature)] = False
if self._purpose == "realtime":
expected_paths.update(
{
("experimental_realtime_webrtc_call_base_url",): (
_OFFICIAL_CHATGPT_CODEX_BASE
),
("experimental_realtime_start_instructions",): "",
("experimental_realtime_ws_backend_prompt",): "",
("experimental_realtime_ws_base_url",): (
_OFFICIAL_OPENAI_REALTIME_BASE
),
("model_provider",): self._transport_provider_id,
("experimental_compact_prompt_file",): (
self._compact_prompt_file()
),
("model_catalog_json",): self._model_catalog_file(),
("features", "realtime_conversation"): True,
}
)
provider_prefix = ("model_providers", self._transport_provider_id)
expected_paths.update(
{
(*provider_prefix, "base_url"): self._provider_sink_base_url(),
(*provider_prefix, "name"): "OpenAI ChatGPT subscription voice",
(*provider_prefix, "requires_openai_auth"): True,
(*provider_prefix, "request_max_retries"): 0,
(*provider_prefix, "supports_standalone_web_search"): False,
(*provider_prefix, "supports_websockets"): False,
(*provider_prefix, "stream_max_retries"): 0,
(*provider_prefix, "wire_api"): "responses",
}
)
else:
expected_paths.update(
{
("model_provider",): _TEXT_MODEL_PROVIDER,
("features", "realtime_conversation"): False,
}
)
if sys.platform == "win32":
expected_paths[("windows", "sandbox")] = "unelevated"
for path, expected in expected_paths.items():
if _layer_value(layers, path) != expected:
raise CodexSubscriptionUnavailable(
"Codex effective configuration failed the transport safety audit."
)
allowed_paths = set(expected_paths)
def walk(value: Any, prefix: tuple[str, ...] = ()) -> list[tuple[str, ...]]:
if isinstance(value, Mapping):
leaves: list[tuple[str, ...]] = []
for key, child in value.items():
leaves.extend(walk(child, (*prefix, str(key))))
return leaves
return [prefix]
if any(path not in allowed_paths for path in walk(session_layers[0])):
raise CodexSubscriptionUnavailable(
"Codex session flags exposed an unapproved configuration surface."
)
raw_layers = result.get("layers")
if not isinstance(raw_layers, list):
raise CodexSubscriptionUnavailable(
"Codex configuration provenance could not be verified."
)
session_metadata = [
layer
for layer in raw_layers
if isinstance(layer, Mapping)
and isinstance(layer.get("name"), Mapping)
and layer["name"].get("type") == "sessionFlags"
]
if len(session_metadata) != 1:
raise CodexSubscriptionUnavailable(
"Codex session configuration provenance could not be verified."
)
session_version = session_metadata[0].get("version")
if not isinstance(session_version, str) or not session_version:
raise CodexSubscriptionUnavailable(
"Codex session configuration version could not be verified."
)
origins = result.get("origins")
expected_origin_keys = {
".".join(path)
for path, expected in expected_paths.items()
if expected not in ([], {})
}
if not isinstance(origins, Mapping):
raise CodexSubscriptionUnavailable(
"Codex configuration origins failed the transport safety audit."
)
origin_keys = set(origins)
aliases = _CODEX_CONFIG_ORIGIN_PATH_ALIASES.get(
self._trusted_binary_version or "", {}
)
canonical_origin_keys = {aliases.get(key, key) for key in origin_keys}
if (
len(canonical_origin_keys) != len(origin_keys)
or canonical_origin_keys != expected_origin_keys
):
raise CodexSubscriptionUnavailable(
"Codex configuration origins failed the transport safety audit."
)
for metadata in origins.values():
source = metadata.get("name") if isinstance(metadata, Mapping) else None
if (
not isinstance(source, Mapping)
or source.get("type") != "sessionFlags"
or metadata.get("version") != session_version
):
raise CodexSubscriptionUnavailable(
"A Codex safety setting came from an unapproved configuration layer."
)
public_config = result.get("config")
if not isinstance(public_config, Mapping):
raise CodexSubscriptionUnavailable(
"Codex effective configuration could not be verified."
)
public_expected = {
"analytics": {"enabled": False},
"approval_policy": "never",
"model_provider": (
self._transport_provider_id
if self._purpose == "realtime"
else _TEXT_MODEL_PROVIDER
),
"sandbox_mode": "read-only",
}
for key, expected in public_expected.items():
if public_config.get(key) != expected:
raise CodexSubscriptionUnavailable(
"Codex managed configuration overrode a required safety setting."
)
async def _spawn(
self,
binary_path: str,
) -> None:
command = [binary_path, "app-server", "--strict-config"]
command.extend(
(
"--enable" if self._purpose == "realtime" else "--disable",
"realtime_conversation",
)
)
for feature in _DISABLED_APP_SERVER_FEATURES:
command.extend(("--disable", feature))
command.extend(
(
"-c",
"notify=[]",
"-c",
'openai_base_url="https://api.openai.com/v1"',
"-c",
'chatgpt_base_url="https://chatgpt.com/backend-api/"',
"-c",
"tools.web_search=false",
"-c",
'history.persistence="none"',
"-c",
"include_apps_instructions=false",
"-c",
"include_collaboration_mode_instructions=false",
"-c",
"include_environment_context=false",
"-c",
"include_permissions_instructions=false",
"-c",
"memories.dedicated_tools=false",
"-c",
"memories.generate_memories=false",
"-c",
"memories.use_memories=false",
"-c",
"orchestrator.mcp.enabled=false",
"-c",
"orchestrator.skills.enabled=false",
"-c",
"skills.bundled.enabled=false",
"-c",
"skills.include_instructions=false",
"-c",
(
"model_instructions_file="
f"{json.dumps(self._safe_instructions_file())}"
),
"-c",
f"log_dir={json.dumps(self._log_dir())}",
"-c",
f"sqlite_home={json.dumps(self._sqlite_home())}",
"-c",
"analytics.enabled=false",
"-c",
'cli_auth_credentials_store="file"',
"-c",
"project_doc_max_bytes=0",
"-c",
'otel.exporter="none"',
"-c",
'otel.trace_exporter="none"',
"-c",
'otel.metrics_exporter="none"',
"-c",
"otel.log_user_prompt=false",
"-c",
'approval_policy="never"',
"-c",
'sandbox_mode="read-only"',
)
)
if self._purpose == "realtime":
command.extend(
(
"-c",
'experimental_realtime_ws_base_url="https://api.openai.com/v1"',
"-c",
"experimental_realtime_webrtc_call_base_url="
'"https://chatgpt.com/backend-api/codex"',
"-c",
'experimental_realtime_start_instructions=""',
"-c",
'experimental_realtime_ws_backend_prompt=""',
"-c",
"experimental_compact_prompt_file="
f"{json.dumps(self._compact_prompt_file())}",
"-c",
f"model_catalog_json={json.dumps(self._model_catalog_file())}",
)
)
provider = f"model_providers.{self._transport_provider_id}"
command.extend(
(
"-c",
f'{provider}.name="OpenAI ChatGPT subscription voice"',
"-c",
f"{provider}.base_url={json.dumps(self._provider_sink_base_url())}",
"-c",
f'{provider}.wire_api="responses"',
"-c",
f"{provider}.requires_openai_auth=true",
"-c",
f"{provider}.supports_websockets=false",
"-c",
f"{provider}.supports_standalone_web_search=false",
"-c",
f"{provider}.request_max_retries=0",
"-c",
f"{provider}.stream_max_retries=0",
"-c",
f'model_provider="{self._transport_provider_id}"',
)
)
else:
command.extend(("-c", f'model_provider="{_TEXT_MODEL_PROVIDER}"'))
if sys.platform == "win32":
command.extend(("-c", 'windows.sandbox="unelevated"'))
kwargs: dict[str, Any] = {
"env": dict(self._child_environment),
"stdin": asyncio.subprocess.PIPE,
"stdout": asyncio.subprocess.PIPE,
"stderr": asyncio.subprocess.PIPE,
"cwd": self._safe_thread_cwd(),
}
lifeline_read_fd: int | None = None
lifeline_write_fd: int | None = None
tree = make_process_tree("codex-app-server")
if not bool(getattr(tree, "supports_containment", False)):
tree.close()
raise CodexSubscriptionUnavailable(
"Codex app-server process-tree containment is unavailable."
)
try:
if sys.platform != "win32":
# Off-loop: the login mutex this helper takes can be held by a
# probe thread across filesystem work; the audio loop must not
# wait on it.
profile_lock_fds = await asyncio.to_thread(
_subscription_transport_pass_fds, self
)
lifeline_read_fd, lifeline_write_fd = os.pipe()
os.set_inheritable(lifeline_read_fd, True)
os.set_inheritable(lifeline_write_fd, False)
keep_fd_args: list[str] = []
for descriptor in profile_lock_fds:
# The lifeline supervisor spawns the REAL child with
# close_fds, so every descriptor above stdio stopped here
# unless it is re-declared. Without these pairs the profile
# lock was held by the supervisor, not by the app-server
# the docstring promises holds it.
keep_fd_args.extend(("--keep-fd", str(descriptor)))
command = [
sys.executable,
"-I",
_CHILD_LIFELINE_SCRIPT,
str(lifeline_read_fd),
*keep_fd_args,
"--",
*command,
]
kwargs["start_new_session"] = True
kwargs["pass_fds"] = (*profile_lock_fds, lifeline_read_fd)
except BaseException:
tree.close()
for descriptor in (lifeline_read_fd, lifeline_write_fd):
if descriptor is not None:
with suppress(OSError):
os.close(descriptor)
raise
try:
try:
process = await asyncio.create_subprocess_exec(
*command,
creationflags=_windows_creationflags(allow_breakaway=True),
**kwargs,
)
except PermissionError:
if sys.platform != "win32":
raise
log.warning(
"Codex app-server breakaway was denied; retrying with no-window "
"process flags"
)
process = await asyncio.create_subprocess_exec(
*command,
creationflags=_windows_creationflags(allow_breakaway=False),
**kwargs,
)
except BaseException:
tree.close()
if lifeline_write_fd is not None:
with suppress(OSError):
os.close(lifeline_write_fd)
raise
finally:
if lifeline_read_fd is not None:
with suppress(OSError):
os.close(lifeline_read_fd)
self._process = process
self._process_tree = tree
self._lifeline_write_fd = lifeline_write_fd
try:
tree.assign(process.pid)
except Exception as exc: # noqa: BLE001 - containment is mandatory
self._process = None
self._process_tree = None
self._close_lifeline()
with suppress(ProcessLookupError, OSError):
process.kill()
with suppress(Exception):
await asyncio.wait_for(process.wait(), timeout=_SHUTDOWN_TIMEOUT_S)
tree.close()
raise CodexSubscriptionUnavailable(
"Codex app-server process containment could not be established."
) from exc
self._reader_task = asyncio.create_task(
self._reader_loop(process), name="codex-app-server-stdout"
)
self._stderr_task = asyncio.create_task(
self._stderr_loop(process), name="codex-app-server-stderr"
)
log.info("Codex app-server process started; account verification pending")
def _close_lifeline(self) -> None:
descriptor = self._lifeline_write_fd
self._lifeline_write_fd = None
if descriptor is not None:
with suppress(OSError):
os.close(descriptor)
async def request(
self,
method: str,
params: Mapping[str, Any] | None = None,
*,
timeout_s: float | None = None,
) -> Any:
"""Send one request and await only its own response future."""
await self.ensure_started()
return await self._request_live(method, params, timeout_s=timeout_s)
async def notify(self, method: str, params: Mapping[str, Any] | None = None) -> None:
"""Send a client notification after lazily starting the process."""
await self.ensure_started()
await self._notify_live(method, params)
async def _request_live(
self,
method: str,
params: Mapping[str, Any] | None,
*,
timeout_s: float | None,
) -> Any:
process = self._require_live_process()
request_id = self._next_request_id
self._next_request_id += 1
future: asyncio.Future[Any] = asyncio.get_running_loop().create_future()
self._pending[request_id] = (method, future)
message: dict[str, Any] = {"id": request_id, "method": method}
if params is not None:
message["params"] = dict(params)
try:
await self._write_frame(process, message)
budget = self._request_timeout_s if timeout_s is None else timeout_s
try:
return await asyncio.wait_for(asyncio.shield(future), timeout=budget)
except TimeoutError as exc:
raise CodexAppServerTimeout(
f"Codex app-server request {method} timed out."
) from exc
finally:
self._pending.pop(request_id, None)
if not future.done():
future.cancel()
async def _notify_live(self, method: str, params: Mapping[str, Any] | None) -> None:
process = self._require_live_process()
message: dict[str, Any] = {"method": method}
if params is not None:
message["params"] = dict(params)
await self._write_frame(process, message)
def _require_live_process(self) -> asyncio.subprocess.Process:
process = self._process
if process is None or process.returncode is not None:
raise CodexAppServerDisconnected("Codex app-server is not running.")
return process
async def _write_frame(
self, process: asyncio.subprocess.Process, message: Mapping[str, Any]
) -> None:
try:
payload = (
json.dumps(message, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+ b"\n"
)
except (TypeError, ValueError) as exc:
raise CodexAppServerError("Codex app-server request is not JSON-safe.") from exc
async with self._write_lock:
if process is not self._process or process.returncode is not None:
raise CodexAppServerDisconnected("Codex app-server exited.")
stdin = process.stdin
if stdin is None:
raise CodexAppServerDisconnected("Codex app-server stdin is unavailable.")
try:
stdin.write(payload)
await stdin.drain()
except (BrokenPipeError, ConnectionError, OSError) as exc:
# Identity guard (mirror of _reader_loop's finally): a drain
# that outlived a teardown-and-restart must not close the NEW
# process or release the successor's reservation.
if process is self._process:
await self._close_process(
CodexAppServerDisconnected("Codex app-server input closed."),
expected=False,
)
raise CodexAppServerDisconnected("Codex app-server input closed.") from exc
async def _reader_loop(self, process: asyncio.subprocess.Process) -> None:
stream = process.stdout
if stream is None:
if process is self._process:
await self._close_process(
CodexAppServerDisconnected("Codex app-server stdout is unavailable."),
expected=False,
)
return
try:
while True:
line = await stream.readline()
if not line:
break
try:
message = json.loads(line.decode("utf-8"))
except (UnicodeDecodeError, json.JSONDecodeError):
log.warning(
"Codex app-server emitted an invalid JSONL frame (%d bytes; "
"content redacted)",
len(line),
)
continue
if not isinstance(message, dict):
log.warning("Codex app-server emitted a non-object JSONL frame")
continue
await self._handle_message(process, message)
except asyncio.CancelledError:
raise
except Exception as exc: # noqa: BLE001 - convert transport failure
log.warning("Codex app-server stdout reader failed (%s)", type(exc).__name__)
finally:
if process is self._process:
await self._close_process(
CodexAppServerDisconnected("Codex app-server output closed."),
expected=False,
)
async def _stderr_loop(self, process: asyncio.subprocess.Process) -> None:
stream = process.stderr
if stream is None:
return
try:
while True:
line = await stream.readline()
if not line:
return
# Stderr can contain prompts, paths, account labels, or upstream
# request details. Record that diagnostics exist without
# copying their contents into Jarvis's world-readable logs.
log.debug(
"Codex app-server diagnostic received (%d bytes; content redacted)",
len(line),
)
except asyncio.CancelledError:
raise
except Exception as exc: # noqa: BLE001 - stderr is diagnostic only
log.warning("Codex app-server stderr reader failed (%s)", type(exc).__name__)
async def _handle_message(
self, process: asyncio.subprocess.Process, message: dict[str, Any]
) -> None:
if process is not self._process:
return
request_id = message.get("id")
method = message.get("method")
if request_id is not None and isinstance(method, str):
await self._deny_server_request(process, request_id, method)
return
if request_id is not None and ("result" in message or "error" in message):
if not isinstance(request_id, int):
return
pending = self._pending.get(request_id)
if pending is None:
log.debug("Codex app-server returned an unknown request id")
return
pending_method, future = pending
if future.done():
return
if "error" in message:
error = message.get("error")
code = error.get("code") if isinstance(error, Mapping) else None
http_status, error_type = _rpc_error_detail(error)
future.set_exception(
CodexAppServerRPCError(
pending_method,
code if isinstance(code, int) else None,
http_status=http_status,
error_type=error_type,
)
)
else:
future.set_result(message.get("result"))
return
if isinstance(method, str):
params = message.get("params")
safe_params = dict(params) if isinstance(params, Mapping) else {}
thread_id = _thread_id_from_params(safe_params)
if thread_id is None:
return
notification = CodexAppServerNotification(method, safe_params)
for subscription in tuple(self._subscriptions.get(thread_id, ())):
subscription._publish(notification)
async def _deny_server_request(
self, process: asyncio.subprocess.Process, request_id: Any, method: str
) -> None:
"""Fail closed for every server-initiated action request."""
if method in _DECLINE_REQUEST_METHODS:
response: dict[str, Any] = {
"id": request_id,
"result": {"decision": "decline"},
}
elif method in _DYNAMIC_TOOL_REQUEST_METHODS:
response = {
"id": request_id,
"result": {"contentItems": [], "success": False},
}
else:
response = {
"id": request_id,
"error": {
"code": -32000,
"message": "Dodaios does not permit server-initiated actions.",
},
}
log.warning("Denied Codex app-server request method %s", method)
await self._write_frame(process, response)
def subscribe(
self,
thread_id: str,
*,
max_queue_size: int = _DEFAULT_NOTIFICATION_QUEUE_SIZE,
) -> CodexNotificationSubscription:
"""Register a local broadcast subscription before starting a session."""
self._assert_owner_loop()
if not isinstance(thread_id, str) or not thread_id.strip():
raise ValueError("thread_id must be a non-empty string")
if max_queue_size < 1:
raise ValueError("max_queue_size must be at least one")
subscription = CodexNotificationSubscription(self, thread_id, max_queue_size=max_queue_size)
self._subscriptions.setdefault(thread_id, set()).add(subscription)
return subscription
def _remove_subscription(self, subscription: CodexNotificationSubscription) -> None:
subscribers = self._subscriptions.get(subscription.thread_id)
if not subscribers:
return
subscribers.discard(subscription)
if not subscribers:
self._subscriptions.pop(subscription.thread_id, None)
def _safe_thread_cwd(self) -> str:
if self._workspace is None:
raise CodexSubscriptionUnavailable(
"Codex transport workspace is unavailable."
)
return str(self._workspace.root)
def _safe_instructions_file(self) -> str:
"""Return the isolated transport-only model instructions file."""
if self._workspace is None:
raise CodexSubscriptionUnavailable(
"Codex transport instruction boundary is unavailable."
)
return str(self._workspace.instructions)
def _compact_prompt_file(self) -> str:
if self._workspace is None:
raise CodexSubscriptionUnavailable(
"Codex transport compact-prompt boundary is unavailable."
)
return str(self._workspace.compact_prompt)
def _model_catalog_file(self) -> str:
if self._workspace is None:
raise CodexSubscriptionUnavailable(
"Codex transport model catalog is unavailable."
)
return str(self._workspace.model_catalog)
def _sqlite_home(self) -> str:
if self._workspace is None:
raise CodexSubscriptionUnavailable(
"Codex transport SQLite boundary is unavailable."
)
return str(self._workspace.sqlite_home)
def _log_dir(self) -> str:
if self._workspace is None:
raise CodexSubscriptionUnavailable(
"Codex transport log boundary is unavailable."
)
return str(self._workspace.log_dir)
def _provider_sink_base_url(self) -> str:
if not self._sink_base_url:
raise CodexSubscriptionUnavailable(
"Codex billing-isolation sink is unavailable."
)
return self._sink_base_url
def _audit_thread_start_response(self, result: Mapping[str, Any]) -> None:
thread = result.get("thread")
sandbox = result.get("sandbox")
expected_cwd = os.path.normcase(os.path.abspath(self._safe_thread_cwd()))
response_cwd = result.get("cwd")
thread_cwd = thread.get("cwd") if isinstance(thread, Mapping) else None
instruction_sources = result.get("instructionSources", [])
if (
not isinstance(thread, Mapping)
or not isinstance(thread.get("id"), str)
or not thread["id"]
or thread.get("ephemeral") is not True
or thread.get("modelProvider") != self._transport_provider_id
or not isinstance(response_cwd, str)
or os.path.normcase(os.path.abspath(response_cwd)) != expected_cwd
or not isinstance(thread_cwd, str)
or os.path.normcase(os.path.abspath(thread_cwd)) != expected_cwd
or result.get("approvalPolicy") != "never"
or result.get("model") != "gpt-5.1-codex"
or result.get("modelProvider") != self._transport_provider_id
or sandbox != {"type": "readOnly", "networkAccess": False}
or instruction_sources != []
):
raise CodexSubscriptionUnavailable(
"Codex returned an unsafe or unverifiable voice thread boundary."
)
def _audit_text_thread_start_response(
self,
result: Mapping[str, Any],
*,
expected_model: str | None,
) -> None:
"""Verify the stable text thread kept the subscription safety floor."""
thread = result.get("thread")
sandbox = result.get("sandbox")
expected_cwd = os.path.normcase(os.path.abspath(self._safe_thread_cwd()))
response_cwd = result.get("cwd")
thread_cwd = thread.get("cwd") if isinstance(thread, Mapping) else None
response_model = result.get("model")
thread_model = thread.get("model") if isinstance(thread, Mapping) else None
model_ok = (
isinstance(response_model, str)
and bool(response_model)
and isinstance(thread_model, str)
and bool(thread_model)
)
if expected_model:
model_ok = (
model_ok
and response_model == expected_model
and thread_model == expected_model
)
if (
not isinstance(thread, Mapping)
or not isinstance(thread.get("id"), str)
or not thread["id"]
or thread.get("ephemeral") is not True
or thread.get("modelProvider") != _TEXT_MODEL_PROVIDER
or not isinstance(response_cwd, str)
or os.path.normcase(os.path.abspath(response_cwd)) != expected_cwd
or not isinstance(thread_cwd, str)
or os.path.normcase(os.path.abspath(thread_cwd)) != expected_cwd
or result.get("approvalPolicy") != "never"
or result.get("modelProvider") != _TEXT_MODEL_PROVIDER
or not model_ok
or sandbox != {"type": "readOnly", "networkAccess": False}
or result.get("instructionSources", []) != []
):
raise CodexSubscriptionUnavailable(
"Codex returned an unsafe or unverifiable text thread boundary."
)
async def text_thread_start(
self,
*,
base_instructions: str | None = None,
developer_instructions: str | None = None,
model: str | None = None,
) -> dict[str, Any]:
"""Start one isolated stable App Server text thread for subscription voice."""
if self._purpose != "text":
raise CodexSubscriptionUnavailable(
"A realtime Codex transport cannot create text-generation threads."
)
selected_model = str(model or "").strip()
if selected_model and not re.fullmatch(
r"[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}", selected_model
):
raise CodexSubscriptionUnavailable(
"Codex subscription model id contains unsupported characters."
)
await self.ensure_started()
session_config: dict[str, Any] = {
"analytics": {"enabled": False},
"cli_auth_credentials_store": "file",
"chatgpt_base_url": _OFFICIAL_CHATGPT_BASE,
"features": {
**{feature: False for feature in _DISABLED_APP_SERVER_FEATURES},
"realtime_conversation": False,
},
"history": {"persistence": "none"},
"include_apps_instructions": False,
"include_collaboration_mode_instructions": False,
"include_environment_context": False,
"include_permissions_instructions": False,
"memories": {
"dedicated_tools": False,
"generate_memories": False,
"use_memories": False,
},
"log_dir": self._log_dir(),
"model_instructions_file": self._safe_instructions_file(),
"model_provider": _TEXT_MODEL_PROVIDER,
"notify": [],
"openai_base_url": _OFFICIAL_OPENAI_API_BASE,
"orchestrator": {
"mcp": {"enabled": False},
"skills": {"enabled": False},
},
"otel": {
"exporter": "none",
"log_user_prompt": False,
"metrics_exporter": "none",
"trace_exporter": "none",
},
"project_doc_max_bytes": 0,
"sandbox_mode": "read-only",
"skills": {
"bundled": {"enabled": False},
"include_instructions": False,
},
"sqlite_home": self._sqlite_home(),
"tools": {"web_search": False},
}
params: dict[str, Any] = {
"allowProviderModelFallback": False,
"approvalPolicy": "never",
"baseInstructions": (
str(base_instructions or "").strip() or _TEXT_BASE_INSTRUCTIONS
),
"config": session_config,
"cwd": self._safe_thread_cwd(),
"developerInstructions": (
str(developer_instructions or "").strip()
or _TEXT_DEVELOPER_INSTRUCTIONS
),
"dynamicTools": None,
"environments": [],
"ephemeral": True,
"modelProvider": _TEXT_MODEL_PROVIDER,
"runtimeWorkspaceRoots": [],
"sandbox": "read-only",
"selectedCapabilityRoots": [],
}
if selected_model:
params["model"] = selected_model
async with self._thread_start_lock:
await self.ensure_started()
live_process = self._process
audit_is_fresh = (
live_process is not None
and self._startup_audit_process is live_process
)
self._startup_audit_process = None
try:
if not audit_is_fresh:
await asyncio.to_thread(
_validated_subscription_home,
create=False,
require_marker=True,
trusted_binary_path=self._trusted_binary_path,
)
await self._verify_live_chatgpt_account()
self._audit_config_requirements(
await self._read_config_requirements()
)
self._audit_effective_config(await self._read_effective_config())
except CodexSubscriptionUnavailable as exc:
if isinstance(exc, CodexSubscriptionPlanUnsupported):
await asyncio.shield(
asyncio.to_thread(
set_codex_subscription_activation_block, str(exc)
)
)
error = type(exc)(str(exc))
await self._close_process(
CodexAppServerDisconnected(
"Codex app-server safety state changed."
),
expected=False,
)
raise error from None
result = _result_dict(
"thread/start",
await self._request_live(
"thread/start", params, timeout_s=self._request_timeout_s
),
)
try:
self._audit_text_thread_start_response(
result, expected_model=selected_model or None
)
except CodexSubscriptionUnavailable:
await self._close_process(
CodexAppServerDisconnected(
"Codex app-server returned an unsafe text thread boundary."
),
expected=False,
)
raise
return result
async def thread_start(
self,
*,
base_instructions: str | None = None,
developer_instructions: str | None = None,
cwd: str | Path | None = None,
model: str | None = None,
ephemeral: bool = True,
extra: Mapping[str, Any] | None = None,
# EXPLICIT opt-in for one scenario only: a failed host-candidate media
# path retrying with STUN may ride an audit that passed within the TTL
# instead of running a third identical copy. Every ordinary (warm)
# thread start keeps the full re-audit — the account can switch under
# a shared process between calls, and that doctrine stays intact.
ride_recent_audit: bool = False,
) -> dict[str, Any]:
"""Start a verified ChatGPT-only transport thread outside the workspace."""
if self._purpose != "realtime":
raise CodexSubscriptionUnavailable(
"A text Codex transport cannot create realtime voice threads."
)
# cwd/model/ephemeral stay caller-proof: the audit below pins them to
# the safe values, so a caller cannot widen the boundary. Instructions
# are different — they are the voice's identity, one-speaker rule and
# language rule. Discarding them here (as an earlier revision did)
# silently shipped the "dumb pipe" transport text instead, so the live
# model never learned it may request handoffs and answered greetings
# out of persona. The transport constants remain the fail-closed floor
# whenever a caller passes nothing.
del cwd, model, ephemeral
base_text = (
str(base_instructions or "").strip() or _TRANSPORT_BASE_INSTRUCTIONS
)
developer_text = (
str(developer_instructions or "").strip()
or _TRANSPORT_DEVELOPER_INSTRUCTIONS
)
await self.ensure_started()
if extra:
raise CodexSubscriptionUnavailable(
"Custom Codex thread/start fields are disabled for subscription voice."
)
params: dict[str, Any] = {}
params.update(
{
"allowProviderModelFallback": False,
"approvalPolicy": "never",
"baseInstructions": base_text,
"config": {
"analytics": {"enabled": False},
"cli_auth_credentials_store": "file",
"chatgpt_base_url": _OFFICIAL_CHATGPT_BASE,
"experimental_realtime_webrtc_call_base_url": (
_OFFICIAL_CHATGPT_CODEX_BASE
),
"experimental_realtime_start_instructions": "",
"experimental_realtime_ws_backend_prompt": (
""
),
"experimental_realtime_ws_base_url": (
_OFFICIAL_OPENAI_REALTIME_BASE
),
"features": {
**{
feature: False
for feature in _DISABLED_APP_SERVER_FEATURES
},
"realtime_conversation": True,
},
"history": {"persistence": "none"},
"include_apps_instructions": False,
"include_collaboration_mode_instructions": False,
"include_environment_context": False,
"include_permissions_instructions": False,
"memories": {
"dedicated_tools": False,
"generate_memories": False,
"use_memories": False,
},
"experimental_compact_prompt_file": self._compact_prompt_file(),
"log_dir": self._log_dir(),
"model_catalog_json": self._model_catalog_file(),
"model_instructions_file": self._safe_instructions_file(),
"model_provider": self._transport_provider_id,
"model_providers": {
self._transport_provider_id: {
"base_url": self._provider_sink_base_url(),
"name": "OpenAI ChatGPT subscription voice",
"request_max_retries": 0,
"requires_openai_auth": True,
"stream_max_retries": 0,
"supports_standalone_web_search": False,
"supports_websockets": False,
"wire_api": "responses",
}
},
"notify": [],
"openai_base_url": _OFFICIAL_OPENAI_API_BASE,
"orchestrator": {
"mcp": {"enabled": False},
"skills": {"enabled": False},
},
"otel": {
"exporter": "none",
"log_user_prompt": False,
"metrics_exporter": "none",
"trace_exporter": "none",
},
"project_doc_max_bytes": 0,
"sandbox_mode": "read-only",
"sqlite_home": self._sqlite_home(),
"skills": {
"bundled": {"enabled": False},
"include_instructions": False,
},
"tools": {"web_search": False},
},
"cwd": self._safe_thread_cwd(),
"developerInstructions": developer_text,
"dynamicTools": None,
"environments": [],
"ephemeral": True,
"model": "gpt-5.1-codex",
"modelProvider": self._transport_provider_id,
"runtimeWorkspaceRoots": [],
"sandbox": "read-only",
"selectedCapabilityRoots": [],
}
)
# account/read at process initialization is not durable: `codex login
# --with-api-key` may switch the shared process while it remains alive.
# Re-read immediately before EVERY subscription thread and serialize
# this check with its thread/start frame.
async with self._thread_start_lock:
await self.ensure_started()
# ...with ONE exception: a cold start that finished inside this
# very call already ran the identical audit against the identical
# process, and nothing but this coroutine has touched it since.
# Repeating it cost three RPC round trips plus a profile walk (and
# a ~100 MB re-hash on a cold memo) on every first call. The token
# is consumed here, under the same lock that serializes the
# thread/start frame, so exactly one thread start can ride it and
# every WARM start still re-audits.
live_process = self._process
# The wake ride minted by ``prime_startup_audit`` is one-shot:
# reading it here consumes it whether or not it is still fresh,
# so a second wake on the same warm process always re-audits.
warm_ride_process = self._warm_audit_process
warm_ride_at = self._warm_audit_at
self._warm_audit_process = None
self._warm_audit_at = 0.0
audit_is_fresh = live_process is not None and (
self._startup_audit_process is live_process
or (
warm_ride_process is live_process
and time.monotonic() - warm_ride_at <= _STARTUP_AUDIT_TTL_S
)
or (
ride_recent_audit
and getattr(self, "_audited_process", None) is live_process
and time.monotonic()
- getattr(self, "_startup_audit_at", 0.0)
<= _STARTUP_AUDIT_TTL_S
)
)
self._startup_audit_process = None
try:
if not audit_is_fresh:
await asyncio.to_thread(
_validated_subscription_home,
create=False,
require_marker=True,
trusted_binary_path=self._trusted_binary_path,
)
await self._verify_live_chatgpt_account()
self._audit_config_requirements(
await self._read_config_requirements()
)
self._audit_effective_config(
await self._read_effective_config()
)
# This full audit is byte-identical to the cold-start one;
# stamp it so a STUN media-path retry seconds from now can
# ride it instead of running a THIRD copy.
self._audited_process = live_process
self._startup_audit_at = time.monotonic()
except CodexSubscriptionUnavailable as exc:
if isinstance(exc, CodexSubscriptionPlanUnsupported):
# The WARM call path re-judges the live account before
# every thread — the same recording rule as the cold
# start applies, or a plan that changed between calls
# would fail every call while every surface says ready.
await asyncio.shield(
asyncio.to_thread(
set_codex_subscription_activation_block, str(exc)
)
)
# Preserve the subclass: callers and future recorders may
# discriminate on it.
error = type(exc)(str(exc))
await self._close_process(
CodexAppServerDisconnected(
"Codex app-server safety state changed."
),
expected=False,
)
raise error from None
result = _result_dict(
"thread/start",
await self._request_live(
"thread/start", params, timeout_s=self._request_timeout_s
),
)
try:
self._audit_thread_start_response(result)
except CodexSubscriptionUnavailable:
await self._close_process(
CodexAppServerDisconnected(
"Codex app-server returned an unsafe thread boundary."
),
expected=False,
)
raise
return result
async def turn_start(
self,
thread_id: str,
input_items: Sequence[Mapping[str, Any]] | str,
*,
extra: Mapping[str, Any] | None = None,
) -> dict[str, Any]:
"""Start a future text turn while retaining the thread safety floor."""
if isinstance(input_items, str):
rendered_input: list[dict[str, Any]] = [{"type": "text", "text": input_items}]
else:
rendered_input = [dict(item) for item in input_items]
params = dict(extra or {})
params.update(
{
"approvalPolicy": "never",
"environments": [],
"input": rendered_input,
"threadId": thread_id,
}
)
return _result_dict("turn/start", await self.request("turn/start", params))
async def _teardown_request(
self, method: str, params: Mapping[str, Any]
) -> dict[str, Any]:
"""Send a teardown RPC, but never START a process just to send it.
``request`` lazily starts app-server, which is right for real work and
wrong for cleanup: when the process is already gone, so is the
ephemeral thread this call would tidy up, and the plain ``request``
path paid a 15-25 s cold start only to have the caller's short cleanup
budget expire and poison the client. Nothing is hidden — the skip is
logged, and a LIVE process still gets the real RPC and its real error.
"""
if not self.running:
log.debug(
"Skipping Codex %s: the app-server process is already gone",
method,
)
return {}
return _result_dict(
method, await self._request_live(method, params, timeout_s=None)
)
async def turn_interrupt(self, thread_id: str, turn_id: str) -> dict[str, Any]:
"""Interrupt one exact app-server turn by its schema-defined ids."""
return await self._teardown_request(
"turn/interrupt",
{"threadId": thread_id, "turnId": turn_id},
)
async def thread_unsubscribe(self, thread_id: str) -> dict[str, Any]:
"""Unload a completed ephemeral voice thread from app-server."""
return await self._teardown_request(
"thread/unsubscribe", {"threadId": thread_id}
)
def realtime_start_instructions_supported(self) -> bool:
"""Whether ``realtimeStartInstructions`` will actually be transmitted.
Cheap, synchronous capability probe for the adapter layer, derived
from the same trusted-binary gate ``realtime_start`` applies before
sending any 0.147-audited field: ``True`` only when this client is
bound to the audited 0.147.0 binary, whose schema accepts the field
(per call, ``realtime_start`` additionally requires the audited v3
protocol). This is the adapter's basis for deciding whether to blank
its fallback prompt — when the field would be withheld, the fallback
must stay in place instead.
"""
return self._trusted_binary_version == _SUPPORTED_CODEX_VERSION
async def realtime_start(
self,
thread_id: str,
*,
output_modality: str = "audio",
offer_sdp: str | None = None,
prompt: str | None = None,
trusted_prompt: str | None = None,
initial_items: Sequence[Mapping[str, Any]] | None = None,
voice: str | None = None,
version: str | None = None,
model: str | None = None,
include_startup_context: bool | None = None,
client_managed_handoffs: bool | None = None,
realtime_start_instructions: str | None = None,
realtime_end_instructions: str | None = None,
codex_responses_as_items: bool | None = None,
codex_response_item_prefix: str | None = None,
codex_response_handoff_mode: str | None = None,
codex_response_handoff_channel_prefixes: Sequence[str] | None = None,
extra: Mapping[str, Any] | None = None,
sdp_timeout_s: float = _DEFAULT_SDP_TIMEOUT_S,
) -> CodexRealtimeStartResult:
"""Start realtime and capture WebRTC SDP without a notification race."""
if extra:
raise CodexSubscriptionUnavailable(
"Custom Codex realtime fields are disabled for subscription voice."
)
del prompt, include_startup_context, client_managed_handoffs
if trusted_prompt is not None and not isinstance(trusted_prompt, str):
raise CodexSubscriptionUnavailable(
"Codex realtime startup instructions are invalid."
)
start_prompt = (trusted_prompt or "").strip()
if len(start_prompt.encode("utf-8")) > _MAX_REALTIME_START_PROMPT_BYTES:
raise CodexSubscriptionUnavailable(
"Codex realtime startup instructions are too large."
)
startup_items = _validated_realtime_initial_items(initial_items)
if startup_items and version != "v3":
raise CodexSubscriptionUnavailable(
"Codex realtime startup history requires the audited v3 protocol."
)
audited_optional = _validated_realtime_audited_optional(
realtime_start_instructions=realtime_start_instructions,
realtime_end_instructions=realtime_end_instructions,
codex_responses_as_items=codex_responses_as_items,
codex_response_item_prefix=codex_response_item_prefix,
codex_response_handoff_mode=codex_response_handoff_mode,
codex_response_handoff_channel_prefixes=codex_response_handoff_channel_prefixes,
)
params = {
"clientManagedHandoffs": True,
"includeStartupContext": False,
"outputModality": output_modality,
"prompt": start_prompt,
"threadId": thread_id,
}
# Added in audited 0.147.0. Older approved binaries must not receive an
# unknown field, while 0.147 explicitly suppresses the automatic
# delegation acknowledgement that otherwise speaks over Jarvis.
trusted_current_binary = (
version == "v3"
and self._trusted_binary_version == _SUPPORTED_CODEX_VERSION
)
if startup_items:
if trusted_current_binary:
params["initialItems"] = startup_items
else:
# Same rule as the audited fields below: an older approved
# binary must never receive an unknown field. A thread rebuild
# on 0.146 restores the call without its history instead of
# failing the whole start on serde.
log.warning(
"Codex realtime start dropped initialItems (%d startup-history "
"items) for this binary: the field exists only in the audited "
"0.147.0 release.",
len(startup_items),
)
if trusted_current_binary:
params["delegationAckFiller"] = False
# Same 0.147/v3 gate for the caller-provided audited fields: the
# start/end instruction slots and the codexResponse* handoff
# routing controls. Outside the gate they are omitted (and named
# in the log) rather than sent — an older approved binary must
# never receive unknown fields.
params.update(audited_optional)
elif audited_optional:
log.info(
"Codex realtime start omitted 0.147-audited fields for this binary/protocol: %s",
", ".join(sorted(audited_optional)),
)
optional: dict[str, Any] = {
"version": version,
"voice": voice,
}
for key, value in optional.items():
if value is not None:
params[key] = value
if model is not None and model.strip():
params["model"] = model.strip()
if offer_sdp is not None:
# The upstream v3 SDP parser reads line-by-line and answers
# "Failed to parse offer: failed to unmarshal SDP: EOF" for an
# offer whose LAST line has no terminator — which is exactly what
# Jarvis's ingress validation produces (it strips the offer).
# Proven live 2026-08-01: the identical offer passes WITH a
# trailing CRLF and fails without one.
if not offer_sdp.endswith("\n"):
offer_sdp = offer_sdp + "\r\n"
params["transport"] = {"type": "webrtc", "sdp": offer_sdp}
sdp_subscription = self.subscribe(thread_id) if offer_sdp is not None else None
try:
response = _result_dict(
"thread/realtime/start",
await self.request("thread/realtime/start", params),
)
answer_sdp: str | None = None
if sdp_subscription is not None:
# Wait for the answer, but FAIL FAST on a realtime error or
# close: the upstream refusal (for example the 403 that ended
# the experimental v1 protocol) used to hide behind a blind
# 15s timeout instead of reaching the user as its honest text.
deadline = asyncio.get_running_loop().time() + sdp_timeout_s
while True:
remaining = deadline - asyncio.get_running_loop().time()
if remaining <= 0:
raise CodexAppServerTimeout(
"Timed out waiting for the Codex WebRTC answer."
)
notification = await sdp_subscription.get(remaining)
if notification.method == "thread/realtime/sdp":
candidate = notification.params.get("sdp")
if not isinstance(candidate, str) or not candidate:
raise CodexAppServerError(
"Codex app-server returned an invalid WebRTC answer."
)
answer_sdp = candidate
break
if notification.method == "thread/realtime/error":
message = " ".join(
str(notification.params.get("message", "") or "").split()
)[:300]
raise CodexAppServerError(
"Codex realtime start failed: "
+ (message or "unspecified realtime error")
)
if notification.method == "thread/realtime/closed":
raise CodexAppServerError(
"Codex realtime transport closed before answering."
)
return CodexRealtimeStartResult(response=response, answer_sdp=answer_sdp)
finally:
if sdp_subscription is not None:
sdp_subscription.close()
async def realtime_append_audio(
self,
thread_id: str,
*,
data: str,
sample_rate: int,
num_channels: int,
samples_per_channel: int | None = None,
item_id: str | None = None,
) -> dict[str, Any]:
audio: dict[str, Any] = {
"data": data,
"sampleRate": int(sample_rate),
"numChannels": int(num_channels),
}
if samples_per_channel is not None:
audio["samplesPerChannel"] = int(samples_per_channel)
if item_id is not None:
audio["itemId"] = item_id
return _result_dict(
"thread/realtime/appendAudio",
await self.request(
"thread/realtime/appendAudio",
{"threadId": thread_id, "audio": audio},
),
)
async def realtime_append_text(
self, thread_id: str, text: str, *, role: str = "user"
) -> dict[str, Any]:
return _result_dict(
"thread/realtime/appendText",
await self.request(
"thread/realtime/appendText",
{"threadId": thread_id, "text": text, "role": role},
),
)
async def realtime_append_speech(self, thread_id: str, text: str) -> dict[str, Any]:
return _result_dict(
"thread/realtime/appendSpeech",
await self.request(
"thread/realtime/appendSpeech",
{"threadId": thread_id, "text": text},
),
)
async def realtime_list_voices(self, thread_id: str) -> dict[str, Any]:
"""Read the server's realtime voice roster (``RealtimeVoicesList``).
Same JSON-RPC plumbing as the other realtime methods. A server build
without ``thread/realtime/listVoices`` answers with a JSON-RPC error
that surfaces as :class:`CodexAppServerRPCError`, so callers can fall
back to their audited static roster instead of failing the session.
"""
return _result_dict(
"thread/realtime/listVoices",
await self.request("thread/realtime/listVoices", {"threadId": thread_id}),
)
async def realtime_stop(self, thread_id: str) -> dict[str, Any]:
return await self._teardown_request(
"thread/realtime/stop", {"threadId": thread_id}
)
async def _close_process(self, error: CodexAppServerDisconnected, *, expected: bool) -> None:
process = self._process
if process is None:
self._ready = False
self._startup_audit_process = None
self._audited_process = None
self._startup_audit_at = 0.0
self._warm_audit_process = None
self._warm_audit_at = 0.0
self._close_lifeline()
if self._profile_transport_epoch is not None:
# Epoch first, release off-loop and shielded: a cancellation
# must neither skip the release nor drop the queued job (a
# queued to_thread future CAN be cancelled before its thread
# starts — shield keeps it alive).
epoch = self._profile_transport_epoch
self._profile_transport_epoch = None
await asyncio.shield(
asyncio.to_thread(_release_subscription_transport, self, epoch)
)
return
self._process = None
self._ready = False
self._startup_audit_process = None
self._audited_process = None
self._startup_audit_at = 0.0
self._warm_audit_process = None
self._warm_audit_at = 0.0
tree = self._process_tree
self._process_tree = None
reader_task = self._reader_task
stderr_task = self._stderr_task
self._reader_task = None
self._stderr_task = None
# Captured SYNCHRONOUSLY with self._process = None: the reaping below
# awaits for seconds without _start_lock, and a parallel ensure_started
# may re-reserve (new epoch) and re-spawn (new lifeline FD) meanwhile.
# Reading these fields late in the finally would tear down the NEW
# life's state — closing the fresh child's lifeline kills its process
# group on POSIX, and releasing the fresh epoch strips a live call's
# profile reservation.
lifeline_fd = self._lifeline_write_fd
self._lifeline_write_fd = None
release_epoch = self._profile_transport_epoch
self._profile_transport_epoch = None
for _method, future in tuple(self._pending.values()):
if not future.done():
future.set_exception(error)
self._pending.clear()
for subscriptions in tuple(self._subscriptions.values()):
for subscription in tuple(subscriptions):
subscription._fail(error)
self._subscriptions.clear()
stdin = process.stdin
if stdin is not None:
with suppress(Exception):
stdin.close()
# Everything past stdin-close awaits repeatedly; a SECOND cancellation
# landing on any of those awaits must still run the resource cleanup
# (job-object handle, lifeline FD, reservation epoch) — hence the
# try/finally around the whole reaping tail.
try:
current = asyncio.current_task()
tasks = [
task
for task in (reader_task, stderr_task)
if task is not None and task is not current and not task.done()
]
for task in tasks:
task.cancel()
if tasks:
await asyncio.gather(*tasks, return_exceptions=True)
if process.returncode is None:
# EOF is Codex's graceful app-server shutdown path. Give its
# Arg0PathEntryGuard time to remove the locked tmp/arg0
# directory before terminating the contained tree.
with suppress(TimeoutError):
await asyncio.wait_for(
process.wait(), timeout=_SHUTDOWN_TIMEOUT_S
)
if process.returncode is None:
with suppress(ProcessLookupError, OSError):
process.terminate()
try:
await asyncio.wait_for(process.wait(), timeout=_SHUTDOWN_TIMEOUT_S)
except TimeoutError: # The grace expired, so hard-kill the contained tree.
with suppress(ProcessLookupError, OSError):
process.kill()
with suppress(Exception):
await asyncio.wait_for(process.wait(), timeout=_SHUTDOWN_TIMEOUT_S)
finally:
# Sync resource cleanup first (safe under any cancellation), the
# awaited release last: its shield keeps the queued job alive even
# if this await is interrupted again. ONLY the entry-time local
# copies are used here — never re-read from self (see above).
if tree is not None:
tree.close()
if lifeline_fd is not None:
with suppress(OSError):
os.close(lifeline_fd)
if release_epoch is not None:
await asyncio.shield(
asyncio.to_thread(
_release_subscription_transport, self, release_epoch
)
)
if not expected:
log.warning("Codex app-server connection reset")
async def close(self) -> None:
"""Reap the app-server tree and release local temporary state.
Closing also RETIRES this client from the shared registry. Without
that, ``get_shared_codex_app_server`` kept handing the same corpse to
the next caller — whose ``ensure_started`` then paid a full cold start
against a client whose workspace had already been deleted. Eviction is
idempotent and runs even when the teardown itself fails, because a
client nobody can use must never be reachable.
"""
self._assert_owner_loop()
try:
async with self._start_lock:
await self._close_process(
CodexAppServerDisconnected("Codex app-server client closed."),
expected=True,
)
workspace = self._workspace
self._workspace = None
self._child_environment = {}
sink_server = self._sink_server
self._sink_server = None
self._sink_base_url = None
if sink_server is not None:
sink_server.close()
with suppress(Exception):
await sink_server.wait_closed()
if workspace is not None:
with suppress(OSError):
await asyncio.to_thread(shutil.rmtree, workspace.root)
finally:
self._closed = True
_evict_shared_codex_app_server(self)
async def poison(self) -> None:
"""Fail closed after an uncertain remote cleanup."""
await self.close()
# Keyed on the binary path ALONE, never on the acquiring event loop. The
# resource behind a client is process-global (one OS profile lock, one
# app-server child bound to it), so a per-loop client could only ever be a
# client that can never reserve the profile — the second loop got one and
# every call from it failed with "already owned by another client".
_shared_clients: dict[tuple[str, CodexAppServerPurpose], CodexAppServerClient] = {}
_shared_clients_lock = threading.Lock()
# Invariant: WORKER threads may hold this lock across filesystem work (the
# cross-process profile lock is acquired under it: mkdir, resolve, ACL
# validation — its OS locking call itself is non-blocking). Event-loop code
# must therefore NEVER take this lock directly — always go through
# asyncio.to_thread (shielded where a cancellation must not drop the job).
_subscription_login_lock = threading.Lock()
_subscription_login_in_flight = False
_subscription_login_process: Any | None = None
_subscription_profile_mutating = False
_subscription_active_transports: set[int] = set()
# The one client currently holding the reservation. Kept as an object (not
# just its id) so an off-loop reserve can tell a live owner from one whose
# event loop died, and so status reads do not depend on the client still
# being registered.
_subscription_transport_owner: CodexAppServerClient | None = None
_subscription_transport_process_lock: Any | None = None
# Monotonic ownership token for the transport reservation: bumped on every
# reserve (including same-client adoption), quoted by every release. A stale
# holder's release becomes a no-op instead of tearing down a live reservation.
_subscription_transport_epoch: int = 0
_subscription_mutation_process_lock: Any | None = None
# Status probes must never report a broken setup just because the profile is
# briefly owned by another probe or mutation (the UI fires several concurrent
# refreshes; each losing caller used to flap the card to "needs attention").
# Concurrent callers wait on this condition (it shares _subscription_login_lock)
# and share the owner's result. The last completed probe is cached briefly so a
# refresh burst costs one CLI probe instead of one per request.
# Slightly above the login flow's 5s status polling so a poll usually hits
# the cache instead of paying a fresh CLI probe on every tick.
_SUBSCRIPTION_SNAPSHOT_CACHE_TTL_S: Final = 8.0
_SUBSCRIPTION_SNAPSHOT_WAIT_TIMEOUT_S: Final = 10.0
# A snapshot served while the profile is briefly owned elsewhere may be stale,
# but never arbitrarily old: beyond this bound the caller reports busy instead
# of a status another process may have changed long ago.
_SUBSCRIPTION_SNAPSHOT_STALE_MAX_S: Final = 60.0
# How long user actions (login, logout, call start) wait for a read-only
# status probe to release the profile before failing honestly.
_SUBSCRIPTION_PROBE_WAIT_S: Final = 5.0
_subscription_state_changed = threading.Condition(_subscription_login_lock)
_subscription_snapshot_cache: CodexAppServerCapability | None = None
_subscription_snapshot_cache_key: str = ""
_subscription_snapshot_cache_at: float = 0.0
# True when the cached entry memoizes a RAISED probe (not a real status). A
# failure memo exists only to keep coalesced waiters off a broken CLI within
# the fresh TTL; it must never be served as "what was true before" on the
# stale path, or one transient hiccup would paint the card broken for the
# whole next busy window.
_subscription_snapshot_cache_is_failure = False
# True only while codex_subscription_auth_snapshot itself owns the profile.
# Distinguishes the read-only probe from real mutations (login/logout), so
# user actions can wait out a probe instead of failing with a message that
# blames a login that does not exist.
_subscription_status_probe_active = False
def _subscription_cache_key(binary_path: str | None) -> str:
return (binary_path or "").strip() or "<default>"
def _cached_subscription_snapshot_locked(
binary_path: str | None, *, allow_stale: bool
) -> CodexAppServerCapability | None:
"""Return the last completed probe result; caller holds the login lock.
``allow_stale`` serves the last known status while the profile is briefly
owned elsewhere, bounded by ``_SUBSCRIPTION_SNAPSHOT_STALE_MAX_S``.
In-process mutations invalidate the cache when they BEGIN and again when
they finish; a probe that was already mid-flight when a mutation started
may still store its (pre-mutation) result during the mutation window, so
a stale read can briefly reflect the pre-mutation truth until the
mutation's closing invalidation lands.
"""
if _subscription_snapshot_cache is None:
return None
if _subscription_snapshot_cache_key != _subscription_cache_key(binary_path):
return None
if allow_stale and _subscription_snapshot_cache_is_failure:
return None
age = time.monotonic() - _subscription_snapshot_cache_at
limit = (
_SUBSCRIPTION_SNAPSHOT_STALE_MAX_S
if allow_stale
else _SUBSCRIPTION_SNAPSHOT_CACHE_TTL_S
)
if age <= limit:
return _subscription_snapshot_cache
return None
def _store_subscription_snapshot_locked(
binary_path: str | None,
snapshot: CodexAppServerCapability,
*,
is_failure: bool = False,
) -> None:
global _subscription_snapshot_cache, _subscription_snapshot_cache_key
global _subscription_snapshot_cache_at
global _subscription_snapshot_cache_is_failure
_subscription_snapshot_cache = snapshot
_subscription_snapshot_cache_key = _subscription_cache_key(binary_path)
_subscription_snapshot_cache_at = time.monotonic()
_subscription_snapshot_cache_is_failure = is_failure
# Waiters parked on a busy window get the fresh result immediately.
_subscription_state_changed.notify_all()
def _invalidate_subscription_snapshot_locked() -> None:
"""Drop the cached status after anything that can change the profile."""
global _subscription_snapshot_cache, _subscription_snapshot_cache_key
global _subscription_snapshot_cache_at
global _subscription_snapshot_cache_is_failure
global _subscription_activation_block
_subscription_snapshot_cache = None
_subscription_snapshot_cache_key = ""
_subscription_snapshot_cache_at = 0.0
_subscription_snapshot_cache_is_failure = False
# The sticky activation block is deliberately NOT cleared here: cache
# invalidation happens on every mutation attempt, including an ABORTED
# re-login, and a closed browser window is no evidence the refused plan
# changed. The block clears only on explicit new evidence — a VERIFIED
# fresh login, a logout, or a passed activation.
# Sticky reason the connected login cannot activate (for example a
# business/enterprise ChatGPT plan, refused by the live account check). The
# one honest 409 toast fades in seconds; without this, every surface keeps
# claiming "ready" for an account that can never work.
_subscription_activation_block: str | None = None
def _set_subscription_activation_block_locked(message: str | None) -> None:
"""Caller holds ``_subscription_login_lock``."""
global _subscription_activation_block
_subscription_activation_block = (message or "").strip() or None
def set_codex_subscription_activation_block(message: str | None) -> None:
"""Record (or clear with ``None``) why activation is impossible."""
with _subscription_login_lock:
_set_subscription_activation_block_locked(message)
def codex_subscription_activation_block() -> str | None:
with _subscription_login_lock:
return _subscription_activation_block
def _await_status_probe_completion_locked() -> None:
"""Wait briefly for a status probe to release the profile.
Caller holds ``_subscription_login_lock``. A status probe is read-only and
short; failing a user action because a background refresh happens to own
the profile — with an error naming a login that does not exist — is worse
than waiting the probe out.
"""
deadline = time.monotonic() + _SUBSCRIPTION_PROBE_WAIT_S
while _subscription_status_probe_active:
remaining = deadline - time.monotonic()
if remaining <= 0:
raise CodexSubscriptionUnavailable(
"A subscription-voice status check is still running. "
"Try again in a moment."
)
_subscription_state_changed.wait(timeout=remaining)
def _subscription_transport_pass_fds(
client: CodexAppServerClient,
) -> tuple[int, ...]:
"""Return the owner lock FD inherited by a POSIX app-server child."""
with _subscription_login_lock:
if _subscription_active_transports != {id(client)}:
raise CodexSubscriptionUnavailable(
"The subscription-voice process lock has no unique owner."
)
process_lock = _subscription_transport_process_lock
if process_lock is None:
raise CodexSubscriptionUnavailable(
"The subscription-voice process lock is unavailable."
)
try:
descriptor = int(process_lock.fileno())
except (AttributeError, OSError, TypeError, ValueError) as exc:
raise CodexSubscriptionUnavailable(
"The subscription-voice process lock cannot be inherited."
) from exc
if descriptor < 0:
raise CodexSubscriptionUnavailable(
"The subscription-voice process lock cannot be inherited."
)
return (descriptor,)
def _owner_loop_is_dead(client: CodexAppServerClient) -> bool:
"""True when this client's owning event loop can never run it again."""
loop = client._owner_loop
return loop is not None and loop.is_closed()
def _reap_dead_loop_transport_locked(client: CodexAppServerClient) -> None:
"""Kill an orphan whose owning loop died; caller holds the login lock.
Mirrors the shutdown sweep's dead-loop branch: the loop that owns the
child can never reap it, so the tree is killed and the lifeline closed
BEFORE the reservation is handed on — an orphan must never keep running
against ``CODEX_HOME`` while the profile reads as free.
"""
orphan_process = client._process
client._process = None
orphan_tree = client._process_tree
client._process_tree = None
client._ready = False
if orphan_process is not None and orphan_process.returncode is None:
with suppress(ProcessLookupError, OSError):
orphan_process.kill()
if orphan_tree is not None:
with suppress(Exception):
orphan_tree.close()
with suppress(Exception):
client._close_lifeline()
client._profile_transport_epoch = None
def _reserve_subscription_transport(client: CodexAppServerClient) -> int:
"""Reserve the profile for this client and return an ownership epoch.
The epoch is the anti-stale-release token: every reservation (including a
re-reservation by the same client after a crash or cancelled start) bumps
it, and ``_release_subscription_transport`` only honors the CURRENT epoch.
Without it, an abandon worker or a slow ``_close_process`` from a previous
life could tear down a reservation a newer start legitimately owns.
"""
global _subscription_transport_process_lock, _subscription_transport_epoch
global _subscription_transport_owner
with _subscription_login_lock:
_await_status_probe_completion_locked()
if _subscription_profile_mutating:
raise CodexSubscriptionUnavailable(
"The subscription-voice profile is being changed."
)
client_id = id(client)
if _subscription_active_transports:
if (
_subscription_active_transports == {client_id}
and _subscription_transport_process_lock is not None
):
# Adoption: the new start supersedes any stale holder, whose
# pending releases become no-ops via the epoch bump.
_subscription_transport_owner = client
_subscription_transport_epoch += 1
return _subscription_transport_epoch
owner = _subscription_transport_owner
if (
owner is not None
and owner is not client
and _subscription_active_transports == {id(owner)}
and _subscription_transport_process_lock is not None
and _owner_loop_is_dead(owner)
):
# The holder's event loop is gone for good: it can never
# release the reservation itself, and refusing forever would
# make subscription voice unusable until a restart. Reap its
# orphan and hand the SAME process lock to the new owner.
log.warning(
"Reclaiming the subscription-voice reservation from a "
"client whose event loop is closed"
)
_reap_dead_loop_transport_locked(owner)
_subscription_active_transports.discard(id(owner))
_subscription_active_transports.add(client_id)
_subscription_transport_owner = client
_subscription_transport_epoch += 1
return _subscription_transport_epoch
raise CodexSubscriptionUnavailable(
"Subscription voice is already running elsewhere in Dodaios. "
"End the active voice session before starting another one."
)
_subscription_transport_process_lock = _acquire_subscription_process_lock()
_subscription_active_transports.add(client_id)
_subscription_transport_owner = client
_subscription_transport_epoch += 1
return _subscription_transport_epoch
def _force_drop_subscription_transport(client: CodexAppServerClient) -> None:
"""Unconditionally drop a dead client's reservation (no epoch check).
Safe ONLY for a client whose owner loop is closed: it can never reserve
again, and no other client can hold the reservation while its id is in
the set. Without this, a close that nulled the epoch before its loop died
left the profile permanently "starting" with login/logout refused.
"""
global _subscription_transport_process_lock, _subscription_transport_owner
with _subscription_login_lock:
_subscription_active_transports.discard(id(client))
if _subscription_transport_owner is client:
_subscription_transport_owner = None
if not _subscription_active_transports:
process_lock = _subscription_transport_process_lock
_subscription_transport_process_lock = None
if process_lock is not None:
process_lock.close()
_subscription_state_changed.notify_all()
def _release_subscription_transport(
client: CodexAppServerClient, epoch: int
) -> None:
"""Release the reservation, but only when ``epoch`` is still current."""
global _subscription_transport_process_lock, _subscription_transport_owner
with _subscription_login_lock:
if epoch != _subscription_transport_epoch:
# A newer reservation owns the profile now; this release belongs
# to a superseded holder and must not touch the live state.
return
_subscription_active_transports.discard(id(client))
if _subscription_transport_owner is client:
_subscription_transport_owner = None
if not _subscription_active_transports:
process_lock = _subscription_transport_process_lock
_subscription_transport_process_lock = None
if process_lock is not None:
process_lock.close()
_subscription_state_changed.notify_all()
def _release_subscription_mutation_process_lock_locked() -> None:
"""Release the mutation owner while ``_subscription_login_lock`` is held."""
global _subscription_mutation_process_lock
process_lock = _subscription_mutation_process_lock
_subscription_mutation_process_lock = None
if process_lock is not None:
process_lock.close()
def _handoff_subscription_mutation_lock_to_login_guard() -> None:
"""Release the parent lock only after the guardian has signalled waiting."""
global _subscription_mutation_process_lock
with _subscription_login_lock:
process_lock = _subscription_mutation_process_lock
if not _subscription_profile_mutating or process_lock is None:
raise CodexSubscriptionUnavailable(
"The subscription-login lock handoff is unavailable."
)
_subscription_mutation_process_lock = None
process_lock.close()
def _launch_subscription_login_reaper(target: Any) -> None:
threading.Thread(
target=target,
name="codex-subscription-login-reaper",
daemon=True,
).start()
def _evict_shared_codex_app_server(client: CodexAppServerClient) -> None:
"""Retire a client from the shared registry. Safe to call repeatedly."""
with _shared_clients_lock:
for key in [
key for key, entry in _shared_clients.items() if entry is client
]:
_shared_clients.pop(key, None)
def get_shared_codex_app_server(
binary_path: str | None = None,
*,
purpose: CodexAppServerPurpose = "realtime",
) -> CodexAppServerClient:
"""Return a shared client for Jarvis's fixed subscription identity.
One client per binary and purpose, process-wide. The dedicated profile still
permits only one live child at a time. A caller on a different event loop is
refused HERE with an actionable message rather than being handed a client
that cannot reserve the single-owner profile and fails deep inside a call.
"""
try:
loop = asyncio.get_running_loop()
except RuntimeError as exc:
raise CodexSubscriptionUnavailable(
"The shared Codex app-server must be acquired from its owning event loop."
) from exc
if purpose not in ("realtime", "text"):
raise ValueError("purpose must be 'realtime' or 'text'")
key = ((binary_path or "").strip() or "<default>", purpose)
with _shared_clients_lock:
client = _shared_clients.get(key)
if client is not None:
owner = client._owner_loop
if owner is loop:
return client
if owner is not None and not owner.is_closed():
raise CodexSubscriptionUnavailable(
"Subscription voice is already running elsewhere in "
"Dodaios. End the active voice session before starting "
"another one."
)
# The owning loop is gone for good; this entry can never be used
# or closed again. Retire it here — the reservation it may still
# hold is reclaimed off-loop by the next reserve, which can kill
# the orphan safely.
log.warning(
"Replacing a Codex app-server client whose owner loop is closed"
)
_shared_clients.pop(key, None)
client = CodexAppServerClient(binary_path=binary_path, purpose=purpose)
client._owner_loop = loop
_shared_clients[key] = client
return client
def _local_subscription_auth_snapshot_locked(
binary_path: str | None = None,
) -> CodexAppServerCapability | None:
"""Return an in-memory status while the dedicated profile is already owned.
The caller holds ``_subscription_login_lock``. Starting another Codex CLI
against the same profile during login, logout, startup, or a live transport
can race its auth and runtime files, so these states must never be probed.
``binary_path`` only fills cosmetic fields (the version chip) from the
cache; ownership decisions never depend on it.
"""
if _subscription_login_in_flight:
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=None,
version=None,
reason="Dedicated ChatGPT subscription login is in progress.",
# Its own state, not login_required: the card must invite the
# user to FINISH the running browser login, never to start a
# second one.
reason_code="login_in_progress",
)
if _subscription_profile_mutating:
# Checked before the transport branch: during disconnect-and-logout
# both are set, and reporting the closing transport as still ready
# would be a lie for the whole teardown window.
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=None,
version=None,
reason="Dedicated subscription voice status is being checked or changed.",
reason_code="busy",
)
if _subscription_active_transports:
# The reservation holder is tracked directly: it stays authoritative
# even after the client was retired from the shared registry (a closed
# owner loop), where a registry scan would have found nothing and
# reported a live call as "starting".
owner = _subscription_transport_owner
ready_client = (
owner
if owner is not None
and id(owner) in _subscription_active_transports
and owner.ready
else None
)
if ready_client is not None:
# The bounded cache read applies the age ceiling and the
# failure-memo exclusion — never read the raw cache here.
cached = _cached_subscription_snapshot_locked(
binary_path, allow_stale=True
)
cached_version = cached.version if cached is not None else None
return CodexAppServerCapability(
available=True,
chatgpt_authenticated=True,
binary_path=(
ready_client._trusted_binary_path or ready_client._binary_path
),
# Cosmetic: keep the version chip alive during a call instead
# of blanking it while the profile cannot be probed.
version=cached_version,
reason="Dedicated ChatGPT subscription voice is active.",
reason_code="ready",
)
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=None,
version=None,
reason="Dedicated ChatGPT subscription voice is starting.",
reason_code="busy",
)
return None
def codex_subscription_auth_snapshot(
binary_path: str | None = None,
) -> CodexAppServerCapability:
"""Return a lightweight snapshot without starting ``codex app-server``.
Concurrent callers never see a fake broken setup: while another probe or a
profile mutation owns the profile, this serves the last completed result,
or waits briefly for the owner and re-evaluates. Only a cold start that
stays contended past the bounded wait reports the transient ``busy`` state.
"""
global _subscription_mutation_process_lock, _subscription_profile_mutating
global _subscription_status_probe_active
deadline = time.monotonic() + _SUBSCRIPTION_SNAPSHOT_WAIT_TIMEOUT_S
with _subscription_state_changed:
while True:
local_snapshot = _local_subscription_auth_snapshot_locked(binary_path)
if local_snapshot is not None:
if local_snapshot.reason_code != "busy":
return local_snapshot
cached = _cached_subscription_snapshot_locked(
binary_path, allow_stale=True
)
if cached is not None:
return cached
remaining = deadline - time.monotonic()
if remaining <= 0:
return local_snapshot
_subscription_state_changed.wait(timeout=remaining)
continue
cached = _cached_subscription_snapshot_locked(
binary_path, allow_stale=False
)
if cached is not None:
return cached
try:
_subscription_mutation_process_lock = (
_acquire_subscription_process_lock()
)
except CodexSubscriptionUnavailable as exc:
# Another process (a second Jarvis instance or CLI session)
# briefly owns the profile. Serve the last known status; a
# transient lock is not a setup defect.
stale = _cached_subscription_snapshot_locked(
binary_path, allow_stale=True
)
if stale is not None:
log.debug(
"Subscription profile owned by another process (%s); "
"serving the last known status.",
exc,
)
return stale
return CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=None,
version=None,
reason=str(exc),
reason_code="busy",
)
_subscription_profile_mutating = True
_subscription_status_probe_active = True
break
try:
snapshot = _read_codex_capability(binary_path)
except Exception as exc:
# Cache the failure briefly so waiters coalesced behind this probe do
# not each retry the broken CLI serially; the owner still raises so
# its caller sees the real error. A RAISED probe is "transiently
# unknown" (busy), never a proven-broken setup: presenting one
# antivirus-slowed hash or tempdir hiccup as "reconnect your account"
# is the exact lie this pipeline exists to prevent.
with _subscription_login_lock:
_store_subscription_snapshot_locked(
binary_path,
CodexAppServerCapability(
available=False,
chatgpt_authenticated=False,
binary_path=None,
version=None,
reason=(
"The Codex status probe failed "
f"({type(exc).__name__}); retrying shortly."
),
reason_code="busy",
),
# Flagged so the stale path never serves this memo as "what
# was true before" — it exists only to keep coalesced waiters
# off a broken CLI within the fresh TTL.
is_failure=True,
)
raise
else:
with _subscription_login_lock:
_store_subscription_snapshot_locked(binary_path, snapshot)
return snapshot
finally:
with _subscription_login_lock:
_release_subscription_mutation_process_lock_locked()
_subscription_profile_mutating = False
_subscription_status_probe_active = False
_subscription_state_changed.notify_all()
def start_codex_subscription_login(
binary_path: str | None = None,
) -> subprocess.Popen[bytes]:
"""Start a fresh direct ChatGPT login in the dedicated voice profile."""
global _subscription_login_in_flight, _subscription_login_process
global _subscription_mutation_process_lock, _subscription_profile_mutating
from dodaios.codex_auth import CodexAuthService
if _headless_linux():
raise CodexSubscriptionUnavailable(_HEADLESS_LOGIN_REASON)
if _linux_login_terminal_missing():
# Same pre-click truth the card shows, so the click and the card can
# never disagree about why this desktop cannot host the login.
raise CodexSubscriptionUnavailable(_NO_LOGIN_TERMINAL_REASON)
with _subscription_login_lock:
_await_status_probe_completion_locked()
if _subscription_profile_mutating or _subscription_login_in_flight:
raise CodexSubscriptionUnavailable(
"A subscription-voice login is already in progress."
)
if _subscription_active_transports:
raise CodexSubscriptionUnavailable(
"Disconnect active subscription voice before starting login."
)
_subscription_mutation_process_lock = (
_acquire_subscription_process_lock()
)
_subscription_profile_mutating = True
_subscription_login_in_flight = True
_invalidate_subscription_snapshot_locked()
log_dir: Path | None = None
try:
home = _prepare_subscription_login_home()
capability = _read_codex_capability(binary_path)
if not capability.available or not capability.binary_path:
raise CodexSubscriptionUnavailable(capability.reason)
approved = next(
(
(release, target)
for release, target in _trusted_codex_targets_for_platform()
if release == capability.version
),
None,
)
if approved is None:
raise CodexSubscriptionUnavailable(
"This platform has no approved Codex subscription runtime."
)
_release, target = approved
lock_path = _subscription_process_lock_path()
from dodaios.core.private_directory import ( # noqa: PLC0415
ensure_owner_only_directory,
)
log_dir = lock_path.parent / f"login-{secrets.token_hex(16)}"
ensure_owner_only_directory(log_dir, create=True)
process = CodexAuthService(
capability.binary_path,
codex_home=home,
force_file_auth_store=True,
isolate_openai_environment=True,
log_dir=log_dir,
visible_login=True,
lifetime_lock_path=lock_path,
login_guard_directory=log_dir,
login_guard_handoff=(
_handoff_subscription_mutation_lock_to_login_guard
),
trusted_binary_sha256=target[3],
).start_login()
except RuntimeError as exc:
if log_dir is not None:
shutil.rmtree(log_dir, ignore_errors=True)
with _subscription_login_lock:
_release_subscription_mutation_process_lock_locked()
_subscription_profile_mutating = False
_subscription_login_in_flight = False
_invalidate_subscription_snapshot_locked()
_subscription_state_changed.notify_all()
raise CodexSubscriptionUnavailable(str(exc)) from exc
except BaseException:
if log_dir is not None:
shutil.rmtree(log_dir, ignore_errors=True)
with _subscription_login_lock:
_release_subscription_mutation_process_lock_locked()
_subscription_profile_mutating = False
_subscription_login_in_flight = False
_invalidate_subscription_snapshot_locked()
_subscription_state_changed.notify_all()
raise
with _subscription_login_lock:
_subscription_login_process = process
def cleanup_login() -> None:
global _subscription_login_in_flight, _subscription_login_process
global _subscription_profile_mutating
login_verified = False
try:
process.wait()
try:
post_login = _read_codex_capability(capability.binary_path)
login_verified = bool(
post_login.available
and post_login.chatgpt_authenticated
and post_login.reason_code == "ready"
)
if not login_verified:
log.warning(
"Dedicated subscription login did not produce a verified "
"ChatGPT login (%s)",
post_login.reason_code,
)
except (CodexAppServerError, OSError) as exc:
log.warning(
"Dedicated subscription login post-check failed (%s)",
type(exc).__name__,
)
finally:
release_guard = getattr(process, "release_profile_lock", None)
if callable(release_guard):
try:
release_guard()
except (OSError, RuntimeError) as exc:
log.warning(
"Dedicated subscription login guard release failed (%s)",
type(exc).__name__,
)
if log_dir is not None:
shutil.rmtree(log_dir, ignore_errors=True)
with _subscription_login_lock:
if _subscription_login_process is process:
_subscription_login_process = None
_subscription_login_in_flight = False
_subscription_profile_mutating = False
_release_subscription_mutation_process_lock_locked()
_invalidate_subscription_snapshot_locked()
if login_verified:
# A VERIFIED fresh login is new evidence — the next
# activation re-judges the plan. An aborted login
# window keeps the recorded verdict.
_set_subscription_activation_block_locked(None)
_subscription_state_changed.notify_all()
try:
_launch_subscription_login_reaper(cleanup_login)
except BaseException:
# Without a reaper the login flags would stay set until restart and
# the profile would wedge as "login in progress". The guarded process
# has no kill(); its guardian owns the OS profile lock, so ask it to
# reap and release (the documented guardian path), then restore a
# clean not-logged-in state.
release_guard = getattr(process, "release_profile_lock", None)
if callable(release_guard):
try:
release_guard()
except (OSError, RuntimeError) as exc:
log.warning(
"Login guard release failed after reaper launch failure (%s)",
type(exc).__name__,
)
if log_dir is not None:
shutil.rmtree(log_dir, ignore_errors=True)
with _subscription_login_lock:
if _subscription_login_process is process:
_subscription_login_process = None
_subscription_login_in_flight = False
_subscription_profile_mutating = False
_release_subscription_mutation_process_lock_locked()
_invalidate_subscription_snapshot_locked()
_subscription_state_changed.notify_all()
raise
return process
def _delete_codex_subscription_auth_locked() -> tuple[bool, str | None]:
"""Delete the dedicated auth file while the caller owns the mutation lock."""
try:
home = _validated_subscription_home(create=False, require_marker=True)
except CodexSubscriptionProfileMissing: # Logging out an absent profile is idempotent success.
return True, None
except CodexSubscriptionInspectionFailed as exc:
# Transiently unreadable — refuse honestly instead of deleting blind.
return False, f"{exc} Try again in a moment."
except CodexSubscriptionUnavailable:
# Disconnecting must work IN-APP even when the profile is invalid:
# removing the whole Jarvis-owned directory deletes the credential
# AND clears the invalid state in one explicit user action.
try:
_rebuild_invalid_subscription_home()
except CodexSubscriptionUnavailable as exc:
# The route returns this honest failure as its 409 detail.
return False, str(exc)
return True, None
auth_file = home / "auth.json"
if not auth_file.exists() and not auth_file.is_symlink():
return True, None
try:
_validate_regular_private_file(auth_file)
except CodexSubscriptionInspectionFailed as exc:
# Same contract as the profile-level branch above: transiently
# unreadable refuses honestly instead of escaping as a raw error.
return False, f"{exc} Try again in a moment."
try:
auth_file.unlink()
except OSError as exc: # Return a path-free deletion error to the authenticated caller.
return (
False,
"Dedicated subscription credentials could not be removed "
f"({type(exc).__name__}).",
)
try:
_validated_subscription_home(create=False, require_marker=True)
except CodexSubscriptionUnavailable: # noqa: S110 - the logout already succeeded; this recheck is advisory.
# The credential IS deleted — reporting failure here would show a
# 409 for a logout that actually happened.
log.warning(
"Post-logout profile revalidation failed; the login file is gone",
exc_info=True,
)
return True, None
def logout_codex_subscription(
binary_path: str | None = None,
) -> tuple[bool, str | None]:
"""Delete only the dedicated file-backed login; missing is success.
Synchronous and potentially slow (it can wait out a status probe and does
filesystem work under the profile lock) — call it from a worker thread,
never on the event loop. The HTTP route uses the async
``disconnect_and_logout_codex_subscription`` wrapper instead.
"""
global _subscription_mutation_process_lock, _subscription_profile_mutating
del binary_path # Kept for the stable route/helper signature.
with _subscription_login_lock:
_await_status_probe_completion_locked()
if _subscription_profile_mutating or _subscription_login_in_flight:
raise CodexSubscriptionUnavailable(
"Subscription voice cannot log out while login is in progress."
)
if _subscription_active_transports:
raise CodexSubscriptionUnavailable(
"Subscription voice is still active; disconnect it before logout."
)
_subscription_mutation_process_lock = (
_acquire_subscription_process_lock()
)
_subscription_profile_mutating = True
_invalidate_subscription_snapshot_locked()
try:
return _delete_codex_subscription_auth_locked()
finally:
with _subscription_login_lock:
_release_subscription_mutation_process_lock_locked()
_subscription_profile_mutating = False
_invalidate_subscription_snapshot_locked()
# The judged login is gone; the plan verdict goes with it.
_set_subscription_activation_block_locked(None)
_subscription_state_changed.notify_all()
def _begin_subscription_disconnect_mutation() -> None:
"""Claim the profile for disconnect; runs off-loop (it may wait briefly)."""
global _subscription_mutation_process_lock, _subscription_profile_mutating
global _subscription_transport_process_lock
with _subscription_login_lock:
_await_status_probe_completion_locked()
if _subscription_profile_mutating or _subscription_login_in_flight:
raise CodexSubscriptionUnavailable(
"Subscription voice cannot log out while login is in progress."
)
if _subscription_active_transports:
process_lock = _subscription_transport_process_lock
if process_lock is None:
raise CodexSubscriptionUnavailable(
"The active subscription-voice process lock is unavailable."
)
_subscription_mutation_process_lock = process_lock
_subscription_transport_process_lock = None
else:
_subscription_mutation_process_lock = (
_acquire_subscription_process_lock()
)
_subscription_profile_mutating = True
_invalidate_subscription_snapshot_locked()
def _finish_subscription_disconnect_mutation() -> None:
"""Release the disconnect claim; runs off-loop (the mutex may be busy)."""
global _subscription_mutation_process_lock, _subscription_profile_mutating
global _subscription_transport_process_lock
with _subscription_login_lock:
if _subscription_active_transports:
if _subscription_transport_process_lock is not None:
log.error(
"Subscription voice has two process-lock owners during logout"
)
_release_subscription_mutation_process_lock_locked()
else:
_subscription_transport_process_lock = (
_subscription_mutation_process_lock
)
_subscription_mutation_process_lock = None
else:
_release_subscription_mutation_process_lock_locked()
_subscription_profile_mutating = False
_invalidate_subscription_snapshot_locked()
# The judged login is gone; the plan verdict goes with it.
_set_subscription_activation_block_locked(None)
_subscription_state_changed.notify_all()
async def disconnect_and_logout_codex_subscription(
binary_path: str | None = None,
) -> tuple[bool, str | None]:
"""Atomically block starts, close the transport, and delete its login."""
del binary_path # Kept for the stable route/helper signature.
# Cleanup binds to OUR claim only: _begin... raising because a FOREIGN
# owner is mutating must not clear that owner's state. The whole
# decide-and-release lives in worker threads synchronized by a
# threading.Event — never in a loop-side variable — because a SECOND
# task cancellation interrupts even a shielded await, and a decision
# read on the loop at that moment would miss a claim the worker is
# about to complete (the permanent-wedge class).
claim_settled = threading.Event()
claim_failed: list[BaseException] = []
def _claim() -> None:
try:
_begin_subscription_disconnect_mutation()
except BaseException as exc:
claim_failed.append(exc)
raise
finally:
claim_settled.set()
def _settle() -> None:
# Off-loop: waits for the claim thread to settle, then releases our
# claim. Once this thread starts it always finishes, whatever happens
# to the coroutine that spawned it. The wait is unbounded on purpose:
# a give-up timeout would turn executor saturation into a permanent
# claim leak (the claim thread still runs later, with nobody left to
# release it), while the claim itself is bounded by construction
# (probe wait <= 5s plus lock acquisition).
claim_settled.wait()
if not claim_failed:
_finish_subscription_disconnect_mutation()
claim_future = asyncio.get_running_loop().run_in_executor(None, _claim)
# A cancelled awaiter leaves the worker's exception unretrieved; consume
# it so asyncio does not log a spurious GC error.
claim_future.add_done_callback(
lambda f: None if f.cancelled() else f.exception()
)
try:
await asyncio.shield(claim_future)
await asyncio.shield(close_shared_codex_app_servers())
return await asyncio.to_thread(_delete_codex_subscription_auth_locked)
finally:
# Shield keeps the settle job alive even if this await is interrupted
# by another cancellation; the job itself cannot be skipped because
# nothing can cancel an executor future the loop never cancels.
await asyncio.shield(asyncio.to_thread(_settle))
async def codex_subscription_login_ready(binary_path: str | None = None) -> bool:
"""Return the lightweight dedicated-profile login snapshot.
Transient ``busy`` fails OPEN, mirroring the realtime provider's
``external_login_ready``: a caller acting on this answer performs the
authoritative live account verification anyway, while failing closed here
turns a healthy install into "connect this provider first" for the busy
window.
"""
if await asyncio.to_thread(codex_subscription_activation_block):
# The live account gate refused this login permanently; readiness
# surfaces must stop advertising a provider that can never start.
return False
try:
snapshot = await asyncio.to_thread(
codex_subscription_auth_snapshot,
binary_path,
)
except (CodexAppServerError, OSError):
# Readiness probes fail closed without starting transport.
return False
if snapshot.reason_code == "busy":
return True
return bool(snapshot.available and snapshot.chatgpt_authenticated)
async def close_shared_codex_app_servers() -> None:
"""Close all shared transports, primarily for application shutdown/tests."""
current_loop = asyncio.get_running_loop()
with _shared_clients_lock:
entries = tuple(_shared_clients.items())
failures: list[BaseException] = []
for key, client in entries:
owner_loop = client._owner_loop or current_loop
try:
if owner_loop is current_loop:
await client.close()
elif owner_loop.is_running():
future = asyncio.run_coroutine_threadsafe(client.close(), owner_loop)
await asyncio.wrap_future(future)
elif owner_loop.is_closed():
# The owner loop is gone for good; this entry can never be
# closed properly again. Escalating forever would make every
# later logout answer 409 for the process lifetime — drop the
# entry and free its reservation best-effort instead.
log.warning(
"Dropping Codex app-server entry whose owner loop is closed"
)
# The dead loop can never reap its child: kill the tree and
# close the lifeline best-effort BEFORE freeing the profile,
# so no orphan keeps running against CODEX_HOME while the
# reservation reads as free.
orphan_process = client._process
client._process = None
orphan_tree = client._process_tree
client._process_tree = None
if orphan_process is not None and orphan_process.returncode is None:
with suppress(ProcessLookupError, OSError):
orphan_process.kill()
if orphan_tree is not None:
with suppress(Exception):
orphan_tree.close()
with suppress(Exception):
client._close_lifeline()
# Unconditional: a close that nulled the epoch before its
# loop died would otherwise leave the reservation forever.
client._profile_transport_epoch = None
await asyncio.shield(
asyncio.to_thread(
_force_drop_subscription_transport, client
)
)
else:
raise CodexSubscriptionUnavailable(
"A Codex app-server owner loop is unavailable for safe shutdown."
)
except BaseException as exc: # noqa: BLE001 - collect every owner-loop failure
failures.append(exc)
continue
with _shared_clients_lock:
if _shared_clients.get(key) is client:
_shared_clients.pop(key, None)
if failures:
raise CodexSubscriptionUnavailable(
"Not every Codex app-server could be closed on its owning event loop."
) from failures[0]
__all__ = [
"CodexAppServerPurpose",
"CodexAppServerCapability",
"CodexAppServerClient",
"CodexAppServerDisconnected",
"CodexAppServerError",
"CodexAppServerNotification",
"CodexAppServerRPCError",
"CodexAppServerTimeout",
"CodexNotificationOverflow",
"CodexNotificationSubscription",
"CodexRealtimeStartResult",
"CodexSubscriptionProfileMissing",
"CodexSubscriptionContainmentUnavailable",
"CodexSubscriptionBinaryUnsupported",
"CodexSubscriptionInspectionFailed",
"CodexSubscriptionPlanUnsupported",
"CodexSubscriptionRuntimeStateInvalid",
"CodexSubscriptionUnavailable",
"CODEX_SUBSCRIPTION_REASON_CODES",
"codex_subscription_activation_block",
"set_codex_subscription_activation_block",
"codex_subscription_auth_snapshot",
"codex_subscription_home",
"codex_subscription_login_ready",
"close_shared_codex_app_servers",
"disconnect_and_logout_codex_subscription",
"get_shared_codex_app_server",
"logout_codex_subscription",
"start_codex_subscription_login",
]