Teknium
836 lines
37 KiB
Python
836 lines
37 KiB
Python
"""Session adapter for codex app-server runtime.
|
|
|
|
Owns one Codex thread per Hermes session: drives ``turn/start``, consumes
|
|
streaming notifications via CodexEventProjector, bridges server-initiated
|
|
approval requests, translates cancellation, and returns a TurnResult that
|
|
AIAgent.run_conversation() splices into ``messages``. Synchronous from the
|
|
caller's view: the client's reader threads feed blocking-with-timeout queues
|
|
that this adapter polls, matching AIAgent's chat_completions loop.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
import os
|
|
import threading
|
|
import time
|
|
from dataclasses import dataclass, field
|
|
from typing import Any, Callable, Optional
|
|
|
|
from agent.codex_responses_adapter import _format_responses_error
|
|
from agent.redact import redact_sensitive_text
|
|
from agent.transports.codex_app_server import (
|
|
CodexAppServerClient,
|
|
CodexAppServerError,
|
|
)
|
|
from agent.transports.codex_event_projector import CodexEventProjector, ProjectionResult
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
|
|
# Tail of codex stderr attached to generic user-facing errors: small enough to
|
|
# stay legible, large enough to surface a config/provider/auth diagnostic.
|
|
_STDERR_TAIL_LINES = 12
|
|
|
|
# Hermes' tools.terminal.security_mode -> Codex permissions profile id.
|
|
# Missing config -> workspace-write (Codex's own default).
|
|
_HERMES_TO_CODEX_PERMISSION_PROFILE = {
|
|
"auto": "workspace-write", "approval-required": "read-only-with-approval",
|
|
"unrestricted": "full-access", "yolo": "full-access", # yolo: backstop alias used by some skills/tests
|
|
}
|
|
|
|
|
|
@dataclass
|
|
class TurnResult:
|
|
"""Result of one user→assistant→tool turn through the codex app-server."""
|
|
|
|
final_text: str = ""
|
|
projected_messages: list[dict] = field(default_factory=list)
|
|
tool_iterations: int = 0
|
|
interrupted: bool = False
|
|
error: Optional[str] = None # Set if turn ended in a non-recoverable error
|
|
turn_id: Optional[str] = None
|
|
thread_id: Optional[str] = None
|
|
token_usage_last: Optional[dict[str, Any]] = None
|
|
model_context_window: Optional[int] = None
|
|
compacted: bool = False
|
|
# Codex subprocess is likely wedged (turn timeout, post-tool watchdog, token
|
|
# refresh failure): caller should retire the session so the next turn respawns.
|
|
should_retire: bool = False
|
|
|
|
|
|
# Some codex versions stream ``<turn_aborted>`` as raw agentMessage text when an
|
|
# interrupt/upstream error tears the turn down without emitting turn/completed.
|
|
_TURN_ABORTED_MARKERS = ("<turn_aborted>", "<turn_aborted/>")
|
|
|
|
|
|
def _notification_scope_ids(note: dict) -> tuple[Optional[str], Optional[str]]:
|
|
"""Extract the thread/turn identity carried by a notification (top-level, then turn/item)."""
|
|
params = (note.get("params") or {}) if isinstance(note, dict) else None
|
|
if not isinstance(params, dict):
|
|
return None, None
|
|
turn, item = params.get("turn") or {}, params.get("item") or {}
|
|
|
|
def first(*lookups: tuple[Any, str, str]) -> Any:
|
|
"""``src.get(a) or src.get(b)`` over successive dict sources until one is not None."""
|
|
for src, primary, fallback in lookups:
|
|
if isinstance(src, dict):
|
|
observed = src.get(primary) or src.get(fallback)
|
|
if observed is not None:
|
|
return observed
|
|
return None
|
|
|
|
return (
|
|
first((params, "threadId", "thread_id"), (turn, "threadId", "thread_id"), (item, "threadId", "thread_id")),
|
|
first((params, "turnId", "turn_id"), (turn, "id", "turnId"), (item, "turnId", "turn_id")),
|
|
)
|
|
|
|
|
|
def _notification_belongs_to_turn(note: dict, *, thread_id: Optional[str], turn_id: Optional[str]) -> bool:
|
|
"""Whether a multiplexed notification belongs to this turn.
|
|
|
|
One JSON-RPC connection can carry parent and hosted subagent threads; an
|
|
explicitly foreign thread/turn event must not mutate this transcript.
|
|
Unscoped notifications remain accepted for protocol compatibility.
|
|
"""
|
|
if not isinstance(note, dict):
|
|
return False
|
|
observed_thread_id, observed_turn_id = _notification_scope_ids(note)
|
|
if thread_id is not None and observed_thread_id is not None and str(observed_thread_id) != str(thread_id):
|
|
return False
|
|
return not (turn_id is not None and observed_turn_id is not None and str(observed_turn_id) != str(turn_id))
|
|
|
|
|
|
def _coerce_turn_input_text(user_input: Any) -> str:
|
|
"""Collapse Hermes/OpenAI rich content parts into app-server text input.
|
|
|
|
``turn/start`` sends text items only; TUI image attachments arrive as content
|
|
parts, so keep text and replace image payloads with a marker.
|
|
"""
|
|
if isinstance(user_input, str):
|
|
return user_input
|
|
if not isinstance(user_input, list):
|
|
return "" if user_input is None else str(user_input)
|
|
parts: list[str] = []
|
|
for item in user_input:
|
|
if not isinstance(item, dict):
|
|
keep = item.strip() if isinstance(item, str) else item is not None
|
|
if keep:
|
|
parts.append(str(item))
|
|
continue
|
|
item_type = item.get("type")
|
|
if item_type in {"text", "input_text"}:
|
|
text = item.get("text") or item.get("content") or ""
|
|
if text:
|
|
parts.append(str(text))
|
|
elif item_type in {"image", "image_url", "input_image"}:
|
|
parts.append("[image attached]")
|
|
text = "\n\n".join(p for p in parts if p).strip()
|
|
return text or "What do you see in this image?"
|
|
|
|
|
|
# Substrings in codex stderr / JSON-RPC errors signalling expired OAuth creds.
|
|
# Conservative on purpose: only redirect to `codex login` on a strong signal,
|
|
# otherwise the original error surfaces verbatim.
|
|
_OAUTH_REFRESH_FAILURE_HINTS = (
|
|
"invalid_grant", "invalid grant",
|
|
"refresh token", "refresh_token", "token refresh", "token_refresh",
|
|
"token has expired", "expired_token", "expired token",
|
|
"not authenticated", "unauthenticated", "unauthorized", "401 unauthorized",
|
|
"re-authenticate", "reauthenticate", "please log in", "please login",
|
|
"auth profile", "no auth profile", "oauth",
|
|
)
|
|
|
|
_OAUTH_REAUTH_HINT = (
|
|
"Codex authentication failed — your ChatGPT/Codex login looks expired or invalid. Run `codex login` to refresh, "
|
|
"then retry. (Fall back to default runtime with `/codex-runtime auto` if the issue persists.)"
|
|
)
|
|
|
|
|
|
def _classify_oauth_failure(*parts: str) -> Optional[str]:
|
|
"""Re-auth hint if any part looks like a codex OAuth/token-refresh failure, else None."""
|
|
haystack = " ".join(p for p in parts if p).lower()
|
|
if haystack and any(needle in haystack for needle in _OAUTH_REFRESH_FAILURE_HINTS):
|
|
return _OAUTH_REAUTH_HINT
|
|
return None
|
|
|
|
|
|
@dataclass
|
|
class _ServerRequestRouting:
|
|
"""Default approval policies when no interactive callback is wired in.
|
|
|
|
Used by tests + cron / non-interactive contexts; the live CLI passes an
|
|
approval_callback that defers to tools.approval.prompt_dangerous_approval().
|
|
"""
|
|
|
|
auto_approve_exec: bool = False
|
|
auto_approve_apply_patch: bool = False
|
|
|
|
|
|
class CodexAppServerSession:
|
|
"""One Codex thread per Hermes session, lifetime owned by AIAgent.
|
|
|
|
Not thread-safe: one caller drives it at a time (projector, thread_id and
|
|
turn state are owned by the caller thread), like AIAgent.run_conversation().
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
*,
|
|
cwd: Optional[str] = None,
|
|
codex_bin: str = "codex",
|
|
codex_home: Optional[str] = None,
|
|
permission_profile: Optional[str] = None,
|
|
approval_callback: Optional[Callable[..., str]] = None,
|
|
on_event: Optional[Callable[[dict], None]] = None,
|
|
request_routing: Optional[_ServerRequestRouting] = None,
|
|
client_factory: Optional[Callable[..., CodexAppServerClient]] = None,
|
|
) -> None:
|
|
self._cwd = cwd or os.getcwd()
|
|
self._codex_bin = codex_bin
|
|
self._codex_home = codex_home
|
|
self._permission_profile = permission_profile or _HERMES_TO_CODEX_PERMISSION_PROFILE.get(
|
|
os.environ.get("HERMES_TERMINAL_SECURITY_MODE", "auto"), "workspace-write"
|
|
)
|
|
self._approval_callback = approval_callback
|
|
self._on_event = on_event # Display hook (kawaii spinner ticks etc.)
|
|
self._routing = request_routing or _ServerRequestRouting()
|
|
self._client_factory = client_factory or CodexAppServerClient
|
|
|
|
self._client: Optional[CodexAppServerClient] = None
|
|
self._thread_id: Optional[str] = None
|
|
self._interrupt_event = threading.Event()
|
|
self._active_turn_id: Optional[str] = None
|
|
self._active_turn_lock = threading.Lock()
|
|
# In-progress fileChange items by id (item/started -> item/completed):
|
|
# approval params don't carry the changeset, so this feeds the prompt summary.
|
|
self._pending_file_changes: dict[str, str] = {}
|
|
self._closed = False
|
|
|
|
def ensure_started(self) -> str:
|
|
"""Spawn, handshake, and ``thread/start``; idempotent, returns the codex thread id."""
|
|
if self._thread_id is not None:
|
|
return self._thread_id
|
|
if self._client is None:
|
|
self._client = self._client_factory(codex_bin=self._codex_bin, codex_home=self._codex_home)
|
|
self._client.initialize(client_name="hermes", client_title="Hermes Agent", client_version=_get_hermes_version())
|
|
# Permissions are intentionally NOT sent on thread/start: on codex 0.130
|
|
# ``thread/start.permissions`` is gated behind experimentalApi and also
|
|
# requires a matching ``[permissions]`` table in ~/.codex/config.toml.
|
|
# Users configure a write-capable profile there, as for any codex use.
|
|
result = self._client.request("thread/start", {"cwd": self._cwd}, timeout=15)
|
|
# Different codex versions serialize the id under thread.id / sessionId / threadId.
|
|
thread_obj = result.get("thread") or {}
|
|
thread_id = (
|
|
thread_obj.get("id") or thread_obj.get("sessionId") or result.get("sessionId") or result.get("threadId")
|
|
)
|
|
if not thread_id:
|
|
raise CodexAppServerError(
|
|
code=-32603,
|
|
message=f"codex thread/start returned no thread id (payload keys: {sorted(result.keys())})",
|
|
)
|
|
self._thread_id = thread_id
|
|
logger.info(
|
|
"codex app-server thread started: id=%s profile=%s cwd=%s", thread_id[:8], self._permission_profile, self._cwd
|
|
)
|
|
return thread_id
|
|
|
|
def close(self) -> None:
|
|
if self._closed:
|
|
return
|
|
self._closed = True
|
|
with self._active_turn_lock:
|
|
self._active_turn_id = None
|
|
if self._client is not None:
|
|
try:
|
|
self._client.close()
|
|
except Exception: # pragma: no cover - best-effort cleanup
|
|
pass
|
|
self._client = None
|
|
self._thread_id = None
|
|
|
|
def __enter__(self) -> "CodexAppServerSession":
|
|
return self
|
|
|
|
def __exit__(self, *exc: Any) -> None:
|
|
self.close()
|
|
|
|
def request_interrupt(self) -> None:
|
|
"""Idempotent: signal the active turn loop to issue turn/interrupt and unwind."""
|
|
self._interrupt_event.set()
|
|
|
|
def request_steer(self, text: str) -> bool:
|
|
"""Append user guidance to the active Codex turn via ``turn/steer``."""
|
|
cleaned = str(text or "").strip()
|
|
if not cleaned:
|
|
return False
|
|
with self._active_turn_lock:
|
|
turn_id = self._active_turn_id
|
|
thread_id = self._thread_id
|
|
client = self._client
|
|
if not turn_id or not thread_id or client is None:
|
|
return False
|
|
try:
|
|
response = client.request(
|
|
"turn/steer",
|
|
{"threadId": thread_id, "input": [{"type": "text", "text": cleaned}], "expectedTurnId": turn_id},
|
|
timeout=10,
|
|
)
|
|
except (CodexAppServerError, TimeoutError):
|
|
logger.debug("turn/steer rejected for active Codex turn", exc_info=True)
|
|
return False
|
|
accepted_turn_id = response.get("turnId") if isinstance(response, dict) else None
|
|
return accepted_turn_id in {None, turn_id}
|
|
|
|
def _format_error_with_stderr(self, prefix: str, exc: Any = "", *, tail_lines: int = _STDERR_TAIL_LINES) -> str:
|
|
"""User-facing error string for generic codex failures.
|
|
|
|
Appends the redacted (force=True) stderr tail so provider/auth secrets
|
|
never leak into chat output, while codex's opaque 'Internal error' text
|
|
becomes diagnosable. Specific classifications (OAuth, wedge watchdog)
|
|
produce their own clean hint instead.
|
|
"""
|
|
exc_str = str(exc) if exc != "" and exc is not None else ""
|
|
base = f"{prefix}: {exc_str}" if exc_str else prefix
|
|
try:
|
|
tail = self._client.stderr_tail(tail_lines) if self._client is not None else []
|
|
except Exception: # pragma: no cover - diagnostic best-effort
|
|
return base
|
|
joined = "\n".join(line.rstrip() for line in tail if line)
|
|
if not joined.strip():
|
|
return base
|
|
redacted = redact_sensitive_text(joined, force=True)
|
|
return f"{base}\ncodex stderr (last {len(tail)} lines):\n{redacted}"
|
|
|
|
def _stderr_blob(self, n: int) -> str:
|
|
return "\n".join(self._client.stderr_tail(n))
|
|
|
|
@staticmethod
|
|
def _retire(result: TurnResult, error: str) -> None:
|
|
"""Record a terminal error and flag the session for respawn on the next turn."""
|
|
result.error = error
|
|
result.should_retire = True
|
|
|
|
def _set_classified_error(self, result: TurnResult, prefix: str, classify_text: str, detail: Any) -> None:
|
|
"""OAuth failures become the re-auth hint AND retire the session (token store
|
|
is broken even though JSON-RPC is fine); everything else gets the stderr tail."""
|
|
hint = _classify_oauth_failure(classify_text, self._stderr_blob(40))
|
|
if hint is not None:
|
|
self._retire(result, hint)
|
|
else:
|
|
result.error = self._format_error_with_stderr(prefix, detail)
|
|
|
|
def _start_for(self, result: TurnResult) -> bool:
|
|
"""ensure_started() into ``result``; startup failures surface as TurnResult.error
|
|
(retiring the session) instead of raw codex exceptions reaching AIAgent."""
|
|
try:
|
|
self.ensure_started()
|
|
except (CodexAppServerError, TimeoutError) as exc:
|
|
self._retire(result, self._format_error_with_stderr("codex app-server startup failed", exc))
|
|
return False
|
|
assert self._client is not None and self._thread_id is not None
|
|
result.thread_id = self._thread_id
|
|
return True
|
|
|
|
def _request_for(self, result: TurnResult, method: str, params: dict, label: str) -> Optional[dict]:
|
|
"""Issue ``method``; on failure fill ``result.error`` and return None.
|
|
A timeout is a strong wedge signal and always retires the session."""
|
|
try:
|
|
return self._client.request(method, params, timeout=10)
|
|
except CodexAppServerError as exc:
|
|
self._set_classified_error(result, f"{label} failed", exc.message, exc)
|
|
except TimeoutError as exc:
|
|
hint = _classify_oauth_failure(self._stderr_blob(40))
|
|
self._retire(result, hint or self._format_error_with_stderr(f"{label} timed out", exc))
|
|
return None
|
|
|
|
def _subprocess_died(self, result: TurnResult) -> bool:
|
|
"""Bail out early (rather than waiting on the deadline) when codex exited."""
|
|
if self._client.is_alive():
|
|
return False
|
|
hint = _classify_oauth_failure(self._stderr_blob(60))
|
|
self._retire(
|
|
result,
|
|
hint or self._format_error_with_stderr("codex app-server subprocess exited unexpectedly", tail_lines=20),
|
|
)
|
|
return True
|
|
|
|
def _absorb_notification(
|
|
self, result: TurnResult, projector: CodexEventProjector, note: dict
|
|
) -> tuple[ProjectionResult, bool]:
|
|
"""Fan one in-scope notification out to display, accounting, file-change
|
|
tracking and the projector. Returns (projection, aborted) where aborted
|
|
means the agent text carried a ``<turn_aborted>`` marker (terminal)."""
|
|
if self._on_event is not None:
|
|
try:
|
|
self._on_event(note)
|
|
except Exception: # pragma: no cover - display callback
|
|
logger.debug("on_event callback raised", exc_info=True)
|
|
_apply_token_usage_notification(result, note)
|
|
_apply_compaction_notification(result, note)
|
|
self._track_pending_file_change(note)
|
|
projection = projector.project(note)
|
|
if projection.messages:
|
|
result.projected_messages.extend(projection.messages)
|
|
if projection.is_tool_iteration:
|
|
result.tool_iterations += 1
|
|
aborted = False
|
|
if projection.final_text is not None:
|
|
# Multiple agentMessage items per turn: the last one is canonical.
|
|
result.final_text = projection.final_text
|
|
if _has_turn_aborted_marker(projection.final_text):
|
|
aborted = True
|
|
result.interrupted = True
|
|
result.error = result.error or "codex reported turn_aborted"
|
|
return projection, aborted
|
|
|
|
def run_turn(
|
|
self,
|
|
user_input: Any,
|
|
*,
|
|
turn_timeout: float = 600.0,
|
|
notification_poll_timeout: float = 0.25,
|
|
post_tool_quiet_timeout: float = 90.0,
|
|
) -> TurnResult:
|
|
"""Send a user message and block until turn/completed, bridging approvals
|
|
and projecting items into Hermes' messages shape.
|
|
|
|
post_tool_quiet_timeout: if codex completes a tool and then stays silent
|
|
this long, fast-fail and retire instead of burning the full turn deadline.
|
|
"""
|
|
result = TurnResult()
|
|
if not self._start_for(result):
|
|
self._interrupt_event.clear()
|
|
return result
|
|
# Do not clear first: a hard stop arriving during ensure_started() must
|
|
# be honored before launching a Codex turn.
|
|
if self._interrupt_event.is_set():
|
|
result.interrupted = True
|
|
self._interrupt_event.clear()
|
|
return result
|
|
projector = CodexEventProjector()
|
|
|
|
ts = self._request_for(
|
|
result,
|
|
"turn/start",
|
|
{"threadId": self._thread_id, "input": [{"type": "text", "text": _coerce_turn_input_text(user_input)}]},
|
|
"turn/start",
|
|
)
|
|
if ts is None:
|
|
self._interrupt_event.clear()
|
|
return result
|
|
|
|
result.turn_id = (ts.get("turn") or {}).get("id")
|
|
with self._active_turn_lock:
|
|
self._active_turn_id = result.turn_id
|
|
# Post-tool watchdog: armed on each tool completion, cleared by any other activity.
|
|
last_tool_completion_at: Optional[float] = None
|
|
|
|
def watchdog_tripped() -> bool:
|
|
if (
|
|
last_tool_completion_at is not None
|
|
and (time.monotonic() - last_tool_completion_at) > post_tool_quiet_timeout
|
|
):
|
|
self._issue_interrupt(result.turn_id)
|
|
result.interrupted = True
|
|
self._retire(
|
|
result,
|
|
f"codex went silent for {post_tool_quiet_timeout:.0f}s after a tool result; "
|
|
f"retiring app-server session.",
|
|
)
|
|
return True
|
|
return False
|
|
|
|
def on_server_request(sreq: dict) -> bool:
|
|
nonlocal last_tool_completion_at
|
|
# Drain pending notifications first (bounded) so per-turn state such
|
|
# as _pending_file_changes is current for the approval decision, and
|
|
# so display events around approvals still reach on_event.
|
|
turn_complete = False
|
|
for _ in range(8):
|
|
pending = self._client.take_notification(timeout=0)
|
|
if pending is None:
|
|
break
|
|
if not _notification_belongs_to_turn(
|
|
pending, thread_id=self._thread_id, turn_id=result.turn_id
|
|
):
|
|
logger.debug(
|
|
"ignoring foreign codex notification while draining "
|
|
"server request: method=%s",
|
|
pending.get("method"),
|
|
)
|
|
continue
|
|
proj, aborted = self._absorb_notification(result, projector, pending)
|
|
if proj.is_tool_iteration:
|
|
last_tool_completion_at = time.monotonic()
|
|
if aborted:
|
|
turn_complete = True
|
|
self._handle_server_request(sreq)
|
|
# An approval round-trip is live signal — don't let it trip the watchdog.
|
|
last_tool_completion_at = None
|
|
return turn_complete
|
|
|
|
def on_note(note: dict, method: str) -> bool:
|
|
nonlocal last_tool_completion_at
|
|
projection, aborted = self._absorb_notification(result, projector, note)
|
|
if projection.is_tool_iteration:
|
|
last_tool_completion_at = time.monotonic()
|
|
elif projection.messages or projection.final_text is not None:
|
|
last_tool_completion_at = None
|
|
if method != "turn/completed":
|
|
return aborted
|
|
turn_obj = (note.get("params") or {}).get("turn") or {}
|
|
turn_status = turn_obj.get("status")
|
|
if turn_status and turn_status not in {"completed", "interrupted"}:
|
|
err_obj = turn_obj.get("error")
|
|
if err_obj:
|
|
err_msg = _format_responses_error(err_obj, str(turn_status))
|
|
self._set_classified_error(
|
|
result, f"turn ended status={turn_status}", err_msg, err_msg
|
|
)
|
|
return True
|
|
|
|
self._drive_turn(
|
|
result,
|
|
turn_timeout=turn_timeout,
|
|
notification_poll_timeout=notification_poll_timeout,
|
|
timeout_label="turn",
|
|
before_poll=watchdog_tripped,
|
|
on_server_request=on_server_request,
|
|
on_note=on_note,
|
|
accept_final_text_at_deadline=True,
|
|
)
|
|
with self._active_turn_lock:
|
|
self._active_turn_id = None
|
|
self._interrupt_event.clear()
|
|
return result
|
|
|
|
def _drive_turn(
|
|
self,
|
|
result: TurnResult,
|
|
*,
|
|
turn_timeout: float,
|
|
notification_poll_timeout: float,
|
|
timeout_label: str,
|
|
on_server_request: Callable[[dict], bool],
|
|
on_note: Callable[[dict, str], bool],
|
|
before_poll: Optional[Callable[[], bool]] = None,
|
|
pre_scope_filter: Optional[Callable[[dict, str], bool]] = None,
|
|
accept_final_text_at_deadline: bool = False,
|
|
) -> None:
|
|
"""Shared poll loop for run_turn / compact_thread until turn/completed or deadline.
|
|
|
|
Per iteration: interrupt -> subprocess death -> ``before_poll`` (watchdog) ->
|
|
server requests (answered before notifications so codex isn't blocked) ->
|
|
one notification, filtered by ``pre_scope_filter`` then by turn scope, handed
|
|
to ``on_note``. Hooks return True to mark the turn complete / stop the loop.
|
|
A deadline without completion interrupts and retires the session — a turn
|
|
that never finished is a strong sign the next turn shouldn't inherit this codex.
|
|
"""
|
|
deadline = time.monotonic() + turn_timeout
|
|
turn_complete = False
|
|
while time.monotonic() < deadline and not turn_complete:
|
|
if self._interrupt_event.is_set():
|
|
self._issue_interrupt(result.turn_id)
|
|
result.interrupted = True
|
|
break
|
|
if self._subprocess_died(result):
|
|
break
|
|
if before_poll is not None and before_poll():
|
|
break
|
|
sreq = self._client.take_server_request(timeout=0)
|
|
if sreq is not None:
|
|
if on_server_request(sreq):
|
|
turn_complete = True
|
|
continue
|
|
note = self._client.take_notification(timeout=notification_poll_timeout)
|
|
if note is None:
|
|
continue
|
|
method = note.get("method", "")
|
|
if pre_scope_filter is not None and not pre_scope_filter(note, method):
|
|
continue
|
|
if not _notification_belongs_to_turn(
|
|
note, thread_id=self._thread_id, turn_id=result.turn_id
|
|
):
|
|
logger.debug("ignoring foreign codex notification: method=%s", method)
|
|
continue
|
|
if on_note(note, method):
|
|
turn_complete = True
|
|
|
|
if (
|
|
accept_final_text_at_deadline
|
|
and not turn_complete
|
|
and not result.interrupted
|
|
and result.final_text
|
|
and result.error is None
|
|
):
|
|
logger.warning(
|
|
"codex app-server turn reached deadline after a completed "
|
|
"assistant message but before turn/completed; accepting "
|
|
"the assistant text as the terminal response"
|
|
)
|
|
turn_complete = True
|
|
|
|
if not turn_complete and not result.interrupted:
|
|
self._issue_interrupt(result.turn_id)
|
|
result.interrupted = True
|
|
if not result.error:
|
|
result.error = self._format_error_with_stderr(f"{timeout_label} timed out after {turn_timeout}s")
|
|
result.should_retire = True
|
|
|
|
def compact_thread(
|
|
self,
|
|
*,
|
|
turn_timeout: float = 600.0,
|
|
notification_poll_timeout: float = 0.25,
|
|
) -> TurnResult:
|
|
"""Trigger Codex-native history compaction for the current thread.
|
|
|
|
``thread/compact/start`` returns immediately (with no turn id); progress
|
|
streams through normal turn/item notifications, so we wait for the
|
|
matching ``turn/completed`` to treat the return as a compaction boundary.
|
|
"""
|
|
result = TurnResult()
|
|
if not self._start_for(result):
|
|
return result
|
|
self._interrupt_event.clear()
|
|
projector = CodexEventProjector()
|
|
|
|
if self._request_for(
|
|
result, "thread/compact/start", {"threadId": self._thread_id}, "thread/compact/start"
|
|
) is None:
|
|
return result
|
|
|
|
def pre_scope_filter(note: dict, method: str) -> bool:
|
|
if result.turn_id is not None:
|
|
return True
|
|
observed_thread_id, observed_turn_id = _notification_scope_ids(note)
|
|
if method == "turn/started":
|
|
if observed_thread_id is not None and str(observed_thread_id) != str(self._thread_id):
|
|
logger.debug("ignoring foreign compact turn/started: thread=%s", observed_thread_id)
|
|
return False
|
|
if observed_turn_id is None:
|
|
logger.debug("ignoring compact turn/started without a turn id")
|
|
return False
|
|
result.turn_id = str(observed_turn_id)
|
|
elif observed_turn_id is not None or method in {"item/completed", "turn/completed"}:
|
|
# Until the new turn/started arrives, terminal/projectable
|
|
# events are stale or can't be attributed to this compaction.
|
|
logger.debug("ignoring codex notification before compact turn start: method=%s", method)
|
|
return False
|
|
return True
|
|
|
|
def on_note(note: dict, method: str) -> bool:
|
|
_, aborted = self._absorb_notification(result, projector, note)
|
|
if method not in {"turn/started", "turn/completed"}:
|
|
return aborted
|
|
turn_obj = (note.get("params") or {}).get("turn") or {}
|
|
result.turn_id = turn_obj.get("id") or result.turn_id
|
|
if method == "turn/started":
|
|
return aborted
|
|
turn_status = turn_obj.get("status")
|
|
if turn_status == "interrupted":
|
|
result.interrupted = True
|
|
result.error = result.error or "compact turn interrupted"
|
|
elif turn_status and turn_status != "completed":
|
|
err_msg = _format_responses_error(turn_obj.get("error"), str(turn_status))
|
|
self._set_classified_error(
|
|
result, f"compact turn ended status={turn_status}", err_msg, err_msg
|
|
)
|
|
return True
|
|
|
|
def on_server_request(sreq: dict) -> bool:
|
|
self._handle_server_request(sreq)
|
|
return False
|
|
|
|
self._drive_turn(
|
|
result,
|
|
turn_timeout=turn_timeout,
|
|
notification_poll_timeout=notification_poll_timeout,
|
|
timeout_label="compact turn",
|
|
on_server_request=on_server_request,
|
|
on_note=on_note,
|
|
pre_scope_filter=pre_scope_filter,
|
|
)
|
|
return result
|
|
|
|
def _issue_interrupt(self, turn_id: Optional[str]) -> None:
|
|
if self._client is None or self._thread_id is None or turn_id is None:
|
|
return
|
|
try:
|
|
self._client.request("turn/interrupt", {"threadId": self._thread_id, "turnId": turn_id}, timeout=5)
|
|
except CodexAppServerError as exc:
|
|
# "no active turn to interrupt" is fine — already done.
|
|
logger.debug("turn/interrupt non-fatal: %s", exc)
|
|
except TimeoutError:
|
|
logger.warning("turn/interrupt timed out")
|
|
|
|
def _handle_server_request(self, req: dict) -> None:
|
|
"""Answer a codex server request (approval / elicitation) via Hermes' approval flow.
|
|
|
|
Method names verified live against codex 0.130.0. Permission escalations
|
|
are always declined: the user chose their profile in ~/.codex/config.toml.
|
|
Unknown methods get a clean JSON-RPC error so codex doesn't hang.
|
|
"""
|
|
if self._client is None:
|
|
return
|
|
method = req.get("method", "")
|
|
rid = req.get("id")
|
|
params = req.get("params") or {}
|
|
handler = self._SERVER_REQUEST_HANDLERS.get(method)
|
|
if handler is None:
|
|
logger.warning("Unknown codex server request: %s", method)
|
|
self._client.respond_error(rid, code=-32601, message=f"Unsupported method: {method}")
|
|
return
|
|
self._client.respond(rid, handler(self, params))
|
|
|
|
def _respond_elicitation(self, params: dict) -> dict:
|
|
"""MCP elicitation (tool confirmation, OAuth, form data): auto-accept for our
|
|
own hermes-tools server (the user opted in by enabling the runtime; it exposes
|
|
nothing codex's shell can't already do); decline others so the user opts in
|
|
via codex's own auth flow."""
|
|
action = "accept" if (params.get("serverName") or "") == "hermes-tools" else "decline"
|
|
return {"action": action, "content": None, "_meta": None}
|
|
|
|
_SERVER_REQUEST_HANDLERS: dict[str, Callable[..., dict]] = {
|
|
"item/commandExecution/requestApproval": lambda self, p: {"decision": self._decide_exec_approval(p)},
|
|
"item/fileChange/requestApproval": lambda self, p: {"decision": self._decide_apply_patch_approval(p)},
|
|
"item/permissions/requestApproval": lambda self, p: {"decision": "decline"},
|
|
"mcpServer/elicitation/request": _respond_elicitation,
|
|
}
|
|
|
|
def _run_approval_callback(self, command: str, description: str, log_label: str) -> str:
|
|
try:
|
|
choice = self._approval_callback(command, description, allow_permanent=False)
|
|
return _approval_choice_to_codex_decision(choice)
|
|
except Exception:
|
|
logger.exception("approval_callback raised on %s", log_label)
|
|
return "decline"
|
|
|
|
def _decide_exec_approval(self, params: dict) -> str:
|
|
"""Decide a Codex exec approval request — protocol-level routing only.
|
|
|
|
Hermes approval mode/timeout resolution lives upstream: codex_runtime.py
|
|
derives ``auto_approve_exec`` from tools.approval, and the callback runs
|
|
the shared approval gate. Do not re-read approval config here.
|
|
"""
|
|
if self._routing.auto_approve_exec:
|
|
return "accept"
|
|
if self._approval_callback is None:
|
|
return "decline" # fail-closed when no callback wired
|
|
# ``cwd`` is Optional on codex's side; fall back so the prompt is never empty.
|
|
description = f"Codex requests exec in {params.get('cwd') or self._cwd or '<unknown>'}"
|
|
if params.get("reason"):
|
|
description += f" — {params['reason']}"
|
|
return self._run_approval_callback(params.get("command") or "", description, "exec request")
|
|
|
|
def _decide_apply_patch_approval(self, params: dict) -> str:
|
|
"""Decide a Codex apply_patch approval request (routing only; see _decide_exec_approval)."""
|
|
if self._routing.auto_approve_apply_patch:
|
|
return "accept"
|
|
if self._approval_callback is None:
|
|
return "decline"
|
|
# Params carry reason + grantRoot only; the changeset comes from the
|
|
# fileChange item cached by _track_pending_file_change.
|
|
reason = params.get("reason")
|
|
grant_root = params.get("grantRoot")
|
|
change_summary = self._pending_file_changes.get(params.get("itemId") or "") or None
|
|
description_parts = [p for p in (reason, change_summary) if p]
|
|
if grant_root:
|
|
description_parts.append(f"grants write to {grant_root}")
|
|
description = "; ".join(description_parts) if description_parts else "Codex requests to apply a patch"
|
|
command_label = (
|
|
f"apply_patch: {change_summary}" if change_summary
|
|
else f"apply_patch: {reason}" if reason
|
|
else "apply_patch"
|
|
)
|
|
return self._run_approval_callback(command_label, description, "apply_patch")
|
|
|
|
def _track_pending_file_change(self, note: dict) -> None:
|
|
"""Maintain _pending_file_changes from item/started + item/completed so the
|
|
apply_patch approval prompt can show what's actually changing."""
|
|
method = note.get("method", "")
|
|
item = (note.get("params") or {}).get("item") or {}
|
|
item_id = item.get("id") or ""
|
|
if item.get("type") != "fileChange" or not item_id:
|
|
return
|
|
if method == "item/completed":
|
|
self._pending_file_changes.pop(item_id, None)
|
|
elif method == "item/started":
|
|
raw_changes = item.get("changes") or []
|
|
if not raw_changes:
|
|
self._pending_file_changes[item_id] = "1 change pending"
|
|
return
|
|
changes = [ch for ch in raw_changes if isinstance(ch, dict)]
|
|
kinds: dict[str, int] = {}
|
|
for ch in changes:
|
|
kind = (ch.get("kind") or {}).get("type") or "update"
|
|
kinds[kind] = kinds.get(kind, 0) + 1
|
|
paths: list[str] = [ch["path"] for ch in changes if ch.get("path")]
|
|
counts = ", ".join(f"{n} {k}" for k, n in sorted(kinds.items()))
|
|
preview = ", ".join(paths[:3])
|
|
if len(paths) > 3:
|
|
preview += f", +{len(paths) - 3} more"
|
|
self._pending_file_changes[item_id] = f"{counts}: {preview}" if preview else counts
|
|
|
|
|
|
def _apply_token_usage_notification(result: TurnResult, note: dict) -> None:
|
|
"""Capture token usage: codex emits it as a separate thread/tokenUsage/updated
|
|
notification (cumulative totals + last-turn breakdown), not on turn/completed."""
|
|
if not isinstance(note, dict) or note.get("method") != "thread/tokenUsage/updated":
|
|
return
|
|
token_usage = (note.get("params") or {}).get("tokenUsage") or {}
|
|
if not isinstance(token_usage, dict):
|
|
return
|
|
last = token_usage.get("last")
|
|
if isinstance(last, dict):
|
|
result.token_usage_last = dict(last)
|
|
window = token_usage.get("modelContextWindow")
|
|
if isinstance(window, int) and window > 0:
|
|
result.model_context_window = window
|
|
|
|
|
|
def _apply_compaction_notification(result: TurnResult, note: dict) -> None:
|
|
"""Capture Codex-native compaction boundaries: a contextCompaction item
|
|
(recent builds) or the deprecated thread/compacted notification (older builds)."""
|
|
if not isinstance(note, dict):
|
|
return
|
|
method = note.get("method") or ""
|
|
params = note.get("params") or {}
|
|
if not isinstance(params, dict):
|
|
return
|
|
if method != "thread/compacted":
|
|
item = params.get("item") if method in {"item/started", "item/completed"} else None
|
|
if not isinstance(item, dict) or item.get("type") != "contextCompaction":
|
|
return
|
|
result.compacted = True
|
|
result.thread_id = params.get("threadId") or result.thread_id
|
|
result.turn_id = params.get("turnId") or result.turn_id
|
|
|
|
|
|
# Hermes 'once'/'session'/'always'/'deny'(/'timeout') -> codex approval decisions
|
|
# (codex-rs app-server-protocol v2). Only the wire translation lives here; the
|
|
# approval mode/timeout resolution stays in tools/approval.py. "deny" and
|
|
# "timeout" both decline — codex has no "prompt expired" wire value.
|
|
_APPROVAL_CHOICE_TO_DECISION = {"once": "accept", "session": "acceptForSession", "always": "acceptForSession"}
|
|
|
|
|
|
def _approval_choice_to_codex_decision(choice: str) -> str:
|
|
"""Map a Hermes approval choice onto codex's approval decision wire value."""
|
|
return _APPROVAL_CHOICE_TO_DECISION.get(choice, "decline")
|
|
|
|
|
|
def _has_turn_aborted_marker(text: str) -> bool:
|
|
"""True if ``text`` carries a raw ``<turn_aborted>`` marker (terminal without turn/completed)."""
|
|
return bool(text) and any(marker in text for marker in _TURN_ABORTED_MARKERS)
|
|
|
|
|
|
def _get_hermes_version() -> str:
|
|
"""Best-effort Hermes version string for codex's userAgent line."""
|
|
try:
|
|
from importlib.metadata import version
|
|
|
|
return version("hermes-agent")
|
|
except Exception: # pragma: no cover
|
|
return "0.0.0"
|