@agentsdock/server 1.0.8 → 1.0.10-beta.1

package/server/codex_history_repair.py

@@ -659,16 +659,36 @@ class _AsyncDeliveryIndex:
     starts: dict = field(default_factory=dict)
     ends: dict = field(default_factory=dict)
     receipts: dict = field(default_factory=dict)
+    status_queues: dict = field(default_factory=dict)
+    status_body_keys: set = field(default_factory=set)
     steered: set = field(default_factory=set)
     count: int = 0
 
     def observe(self, event: dict) -> None:
         event_type = event.get("type")
-        if (event_type not in {"turn_started", "turn_finished", "turn_steered", "turn_stopped", "turn_queue_run_now",
+        if (event_type not in {"turn_queued", "turn_started", "turn_finished", "turn_steered", "turn_stopped", "turn_queue_run_now",
                               "chat_conversation_message_received", "chat_conversation_message_started", "chat_conversation_message_delivered"}
             or event.get("imported") is True or event.get("forked") is True
             or event.get("backend") not in (None, "codex")):
             return
+        if event_type == "turn_queued":
+            # The private durable request is exact provider input. Public display
+            # labels and wrapper-looking text are never evidence by themselves.
+            queued_id, body = event.get("queued_id"), event.get("request_prompt")
+            if (event.get("purpose") == "cross_chat_handoff_delivery"
+                and event.get("cross_chat_exchange_status") is True
+                and not _runtime_human_provenance(event)
+                and isinstance(queued_id, str) and 0 < len(queued_id) <= 256
+                and isinstance(body, str) and 0 < len(body) <= NATIVE_PROOF_LINE_BYTES):
+                record = {key: event.get(key) for key in ("seq", "cross_chat_exchange_id",
+                    "cross_chat_exchange_leg_id", "source_session_id", "target_session_id")}
+                record["body_key"] = _text_key(body)
+                self.status_queues.setdefault(queued_id, []).append(record)
+                self.status_body_keys.add(record["body_key"])
+                self.count += 1
+                if self.count > MAX_KEYS:
+                    raise _Unproven()
+            return
         run = (event.get("interrupted_run_id") or event.get("run_id")) if event_type == "turn_queue_run_now" else event.get("run_id")
         if (event_type in {"turn_steered", "turn_stopped"} or event.get("native_steer") is True):
             if isinstance(run, str) and 0 < len(run) <= 256 and not run.startswith("import_"):
@@ -686,7 +706,8 @@ class _AsyncDeliveryIndex:
             "provider_thread_id", "provider_turn_id", "cross_chat_envelope_id", "handoff_id", "message_id",
             "source_session_id", "target_session_id", "source_title", "target_run_id", "conversation_mode",
             "kind", "action", "handoff_action", "handoff_body_chars", "handoff_body_sha256",
-            "message_revision", "message_edited_by_user", "exchange_id", "cross_chat_exchange_id")
+            "message_revision", "message_edited_by_user", "exchange_id", "cross_chat_exchange_id",
+            "cross_chat_exchange_leg_id", "cross_chat_exchange_status", "queued_id")
         record = {key: event.get(key) for key in fields
                   if event.get(key) is None or type(event.get(key)) in (int, bool)
                   or isinstance(event.get(key), str) and len(event[key]) <= 512}
@@ -710,11 +731,36 @@ class _AsyncDeliveryIndex:
             raise _Unproven()
 
     def match(self, session_id: str, provider_id: str, run: str, origin: dict,
-              body: tuple[str, str, int] | None, source_ids: set) -> dict | None:
+              body: tuple[str, str, int] | None, source_ids: set, body_key: str = "") -> dict | None:
         starts, ends = self.starts.get(run, []), self.ends.get(run, [])
-        if body is None or len(starts) != 1 or len(ends) != 1 or run in self.steered:
+        if len(starts) != 1 or len(ends) != 1 or run in self.steered:
             return None
         start, end = starts[0], ends[0]
+        if start.get("cross_chat_exchange_status") is True:
+            queued = self.status_queues.get(start.get("queued_id"), [])
+            if len(queued) != 1:
+                return None
+            receipt = queued[0]
+            identity = ("cross_chat_exchange_id", "cross_chat_exchange_leg_id",
+                        "source_session_id", "target_session_id")
+            if (start.get("malformed") or end.get("malformed") or not start.get("body_key")
+                or any(not isinstance(start.get(key), str) or not start[key]
+                       or receipt.get(key) != start[key] or end.get(key) != start[key] for key in identity)
+                or start.get("target_session_id") != session_id or start.get("source_session_id") == session_id
+                or start.get("backend") != "codex" or end.get("backend") != "codex"
+                or end.get("cross_chat_exchange_status") is not True or end.get("transport") != "app-server"
+                or end.get("provider_thread_id") != provider_id or end.get("provider_turn_id") != origin.get("turn_id")
+                or receipt["body_key"] != body_key or source_ids != {origin.get("event_id")} or not origin.get("event_id")
+                or any(type(record.get("seq")) is not int for record in (receipt, start, end))
+                or not receipt["seq"] < start["seq"] < end["seq"]
+                or not isinstance(start.get("id"), str) or not start["id"]):
+                return None
+            times = [_delivery_timestamp(value) for value in (start.get("ts"), origin.get("timestamp"), end.get("ts"))]
+            if any(value is None for value in times) or not times[0] <= times[1] <= times[2]:
+                return None
+            return _native_event_identity(start)
+        if body is None:
+            return None
         envelope = start.get("cross_chat_envelope_id")
         if (start.get("malformed") or end.get("malformed")
             or not isinstance(envelope, str) or not envelope or start.get("backend") != "codex"
@@ -1044,7 +1090,7 @@ def _prove_native_source(thread: str, source: Path, root: Path, batches: dict, c
         native_matches = native.get((native_run, kind, body_key), [])
         if not native_matches and kind == "user":
             delivery = deliveries.match(session_id, thread, native_run, source_origin,
-                                        delivery_bodies.get(key), delivery_source_ids.get(key[0], set()))
+                                        delivery_bodies.get(key), delivery_source_ids.get(key[0], set()), body_key)
             if delivery is not None:
                 native_matches = [delivery]
         if not native_matches and kind == "assistant":
@@ -1155,7 +1201,7 @@ def _prove_pending_async_deliveries(session_id: str, provider_id: str, items: li
         if (item.get("kind") != "user" or not isinstance(item.get("text"), str)
             or not isinstance(origin, dict) or origin.get("provider") != "codex" or origin.get("kind") != "user"
             or origin.get("session_id", provider_id) != provider_id or item.get("source_text_sha256") is not None
-            or not _async_delivery_body(item["text"])):
+            or not (_async_delivery_body(item["text"]) or _text_key(item["text"]) in deliveries.status_body_keys)):
             continue
         candidate = _replay_target({"seq": previous_seq + index + 2, "id": f"pending:{index}", "run_id": run,
             "type": "turn_started", "backend": "codex", "imported": True, "prompt": item["text"],
@@ -1205,8 +1251,7 @@ def filter_native_codex_history_items(session_id: str, provider_id: str, events:
         deliveries = _AsyncDeliveryIndex()
         prove_deliveries = (source_path is not None and root is not None
             and isinstance(sync_checkpoint, dict) and callable(parse_item)
-            and any(item.get("kind") == "user" and isinstance(item.get("text"), str)
-                    and _async_delivery_body(item["text"]) for item in items))
+            and any(item.get("kind") == "user" and isinstance(item.get("text"), str) for item in items))
         previous_seq, owner_count = 0, 0
         for event, _offset, _line in _native_records(events, stamp, budget):
             seq = event.get("seq")

package/server/codex_provider.py

@@ -195,6 +195,19 @@ def session_choice(value) -> str:
     return choice
 
 
+RUNTIME_FIELDS = ("codex_provider", "codex_provider_revision", "codex_provider_binding", "model", "effort", "_codex_provider_removed")
+
+
+def requested_session(session: dict) -> dict:
+    """Desired runtime is separate from the owner of an in-flight turn."""
+    pending = session.get("_codex_provider_pending")
+    return {**session, **pending} if isinstance(pending, dict) else dict(session)
+
+
+def runtime_selection(session: dict) -> dict:
+    return {key: session.get(key) for key in RUNTIME_FIELDS}
+
+
 class ProviderStore:
     """Atomic metadata pointer plus private, endpoint-bound credential records."""
     def __init__(self, root: Path):
@@ -329,6 +342,8 @@ class ProviderStore:
     def for_session(self, session: dict, *, include_key=False) -> dict | None:
         if session_choice(session.get("codex_provider")) == "default":
             return None
+        if session.get("_codex_provider_removed"):
+            raise HTTPException(409, "Configure the custom Codex endpoint before using this chat.")
         revision = session.get("codex_provider_revision")
         selected = self.selection(include_key=include_key, revision=revision, include_revision=True)
         if selected is None:
@@ -345,6 +360,30 @@ class ProviderStore:
             selected["model"] = validate_model(model)
         return selected
 
+    def control(self, session: dict, *, available=True, summary=False) -> dict:
+        requested = requested_session(session)
+        pending = isinstance(session.get("_codex_provider_pending"), dict)
+        requested_provider = session_choice(requested.get("codex_provider"))
+        def endpoint(value):
+            if session_choice(value.get("codex_provider")) != "custom" or value.get("_codex_provider_removed"):
+                return None
+            try:
+                selected = self._public_selections.get(value.get("codex_provider_revision")) or self.for_session(value)
+                return selected.get("base_url") if selected else None
+            except HTTPException:
+                return None
+        return {"pending": pending,
+            "pending_reason": session.get("_codex_provider_pending_reason") if pending else None,
+            "requested_provider": requested_provider,
+            "active_provider": session_choice(session.get("codex_provider")),
+            "requested_model": requested.get("model"), "requested_effort": requested.get("effort"),
+            # The next-turn picker must use the requested endpoint's catalog,
+            # while active runtime fields continue describing running work.
+            # Avoid duplicating the active catalog on ordinary session events.
+            "requested_catalog": self.catalog(available=available, session=requested, summary=summary)
+                if pending and requested_provider == "custom" else None,
+            "requested_base_url": endpoint(requested), "active_base_url": endpoint(session)}
+
     def registration(self, *, include_key=False) -> dict | None:
         # A damaged optional endpoint must not prevent normal Codex startup.
         # Custom chat admission and the admin status route still fail closed.
@@ -575,6 +614,17 @@ class ProviderStore:
             if selected:
                 self._atomic(self._binding_name(thread_id), {"binding": binding(selected),
                     "credential_id": selected.get("credential_id")})
+            else:
+                self._atomic(self._binding_name(thread_id), {"binding": None, "credential_id": None})
+
+    def thread_binding(self, thread_id: str) -> dict:
+        """Snapshot rollback metadata without reopening revoked credentials."""
+        with self.lock:
+            return self._read(self._binding_name(thread_id)) or {"binding": None, "credential_id": None}
+
+    def restore_thread_binding(self, thread_id: str, record: dict) -> None:
+        with self.lock:
+            self._atomic(self._binding_name(thread_id), record)
 
     def for_thread(self, thread_id: str, *, include_key=False) -> dict | None:
         with self.lock:
@@ -1076,7 +1126,7 @@ def create_router(*, authorize, store: ProviderStore, mutate, probe, available,
                     session = session_lookup(session_id) if session_lookup else None
                     if not session:
                         raise HTTPException(404, "Chat not found.")
-                    selected = await asyncio.to_thread(store.for_session, session, include_key=True)
+                    selected = await asyncio.to_thread(store.for_session, requested_session(session), include_key=True)
                 else:
                     selected = await asyncio.to_thread(store.selection, include_key=True, include_revision=True)
                 if selected is None:
@@ -1141,7 +1191,7 @@ def create_router(*, authorize, store: ProviderStore, mutate, probe, available,
             session = session_lookup(session_id) if session_lookup else None
             if not session:
                 raise HTTPException(404, "Chat not found.")
-            selected = await asyncio.to_thread(store.for_session, session, include_key=True)
+            selected = await asyncio.to_thread(store.for_session, requested_session(session), include_key=True)
         else:
             selected = await asyncio.to_thread(store.selection, include_key=True, include_revision=True)
         if selected is None:

package/server/codex_response_stream.py

@@ -0,0 +1,229 @@
+"""Keep nonstandard custom Responses errors visible to native Codex.
+
+An owned loopback transport forwards requests unchanged to one immutable endpoint.
+Only untyped SSE error packets are normalized; native Codex owns all retries.
+"""
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager, suppress
+import hmac
+import json
+import secrets
+import socket
+from urllib.parse import quote
+
+import httpx
+import uvicorn
+from fastapi import FastAPI, Request
+from fastapi.responses import Response, StreamingResponse
+
+from codex_app_server import CodexAppServerManager
+from codex_provider import ENV_KEY, PROVIDER_ID, config_args
+
+# Larger frames pass through unchanged, rather than buffering arbitrary output.
+# This is a parser memory bound, not a response or content size limit.
+_ERROR_FRAME_BYTES = 64 * 1024
+_HOP_HEADERS = {'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
+                'te', 'trailer', 'transfer-encoding', 'upgrade', 'host', 'content-length'}
+
+
+class ErrorFrames:
+    def __init__(self, secret: str):
+        self.secret = secret
+        self.pending = bytearray()
+        self.passthrough = False
+        self.response_id = 'resp_custom_endpoint_error'
+
+    def frame(self, raw: bytes) -> bytes:
+        try:
+            data = b'\n'.join(line[5:].lstrip(b' ') for line in raw.splitlines() if line.startswith(b'data:'))
+            packet = json.loads(data)
+        except (ValueError, UnicodeError):
+            return raw
+        if not isinstance(packet, dict):
+            return raw
+        response = packet.get('response')
+        if isinstance(response, dict) and isinstance(response.get('id'), str):
+            self.response_id = response['id']
+        error = packet.get('error')
+        if packet.get('type') or not error:
+            return raw
+        if isinstance(error, dict):
+            message = error.get('message')
+            if not isinstance(message, str) or not message:
+                return raw
+            code = str(error.get('code') or error.get('type') or 'server_error')
+        elif isinstance(error, str):
+            message, code = error, 'server_error'
+        else:
+            return raw
+        code = {'429': 'rate_limit_exceeded', '401': 'invalid_api_key',
+                '403': 'permission_denied', '400': 'invalid_request_error',
+                '500': 'server_error', '502': 'server_error', '503': 'server_error'}.get(code, code)
+        for value in (self.secret, quote(self.secret, safe='')):
+            if value:
+                message = message.replace(value, '[redacted]')
+        failed = {'type': 'response.failed', 'response': {
+            'id': self.response_id, 'object': 'response', 'created_at': 0,
+            'status': 'failed', 'output': [], 'error': {'code': code, 'message': message}}}
+        return b'event: response.failed\ndata: ' + json.dumps(failed, ensure_ascii=False).encode() + b'\n\n'
+
+    async def stream(self, chunks):
+        # Split at SSE blank lines, including CRLF boundaries across chunks.
+        async for chunk in chunks:
+            self.pending.extend(chunk)
+            while self.pending:
+                lf = self.pending.find(b'\n\n')
+                crlf = self.pending.find(b'\r\n\r\n')
+                endings = [(i, n) for i, n in ((lf, 2), (crlf, 4)) if i >= 0]
+                if endings:
+                    i, n = min(endings)
+                    raw = bytes(self.pending[:i+n]); del self.pending[:i+n]
+                    yield raw if self.passthrough or len(raw) > _ERROR_FRAME_BYTES else self.frame(raw)
+                    self.passthrough = False
+                elif len(self.pending) > _ERROR_FRAME_BYTES:
+                    # Retain only a delimiter tail; do not truncate a large frame.
+                    yield bytes(self.pending[:-3]); del self.pending[:-3]
+                    self.passthrough = True
+                else:
+                    break
+        if self.pending:
+            raw = bytes(self.pending); self.pending.clear()
+            yield raw if self.passthrough else self.frame(raw)
+
+
+class _OwnedConfig(uvicorn.Config):
+    def configure_logging(self):
+        # Do not change the host server's process-wide logging configuration.
+        pass
+
+
+class _OwnedServer(uvicorn.Server):
+    @contextmanager
+    def capture_signals(self):
+        # This transport must never take over its host server's signal handlers.
+        yield
+
+
+class ResponseStreamBridge:
+    def __init__(self, selected: dict):
+        self.upstream = selected['base_url'].rstrip('/')
+        self.key = selected['api_key']
+        self.token = secrets.token_urlsafe(32)
+        self.url = ''
+        self.task = self.server = self.client = self.socket = None
+        app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
+        app.add_api_route('/v1/{path:path}', self.forward, methods=['POST', 'GET', 'DELETE'])
+        self.app = app
+
+    async def start(self):
+        if self.task is not None and not self.task.done():
+            return
+        self.client = httpx.AsyncClient(timeout=None, follow_redirects=False, trust_env=False)
+        self.socket = socket.socket()
+        self.socket.bind(('127.0.0.1', 0)); self.socket.listen(128); self.socket.setblocking(False)
+        self.url = f'http://127.0.0.1:{self.socket.getsockname()[1]}/v1'
+        self.server = _OwnedServer(_OwnedConfig(self.app, log_config=None, access_log=False, lifespan='off', log_level='critical'))
+        self.task = asyncio.create_task(self.server.serve(sockets=[self.socket]))
+        try:
+            while not self.server.started:
+                if self.task.done():
+                    await self.task
+                    raise RuntimeError('Custom response transport could not start')
+                await asyncio.sleep(0)
+        except BaseException:
+            await self.close()
+            raise
+
+    async def forward(self, request: Request, path: str):
+        if not hmac.compare_digest(request.headers.get('authorization', ''), 'Bearer ' + self.token):
+            return Response(status_code=401)
+        # The destination is immutable. A request cannot name a different origin.
+        if not (path == 'responses' or path.startswith('responses/')) or '..' in path.split('/'):
+            return Response(status_code=404)
+        headers = {k: v for k, v in request.headers.items() if k.lower() not in _HOP_HEADERS | {'authorization', 'accept-encoding', 'cookie'}}
+        headers.update(authorization='Bearer ' + self.key, **{'accept-encoding': 'identity'})
+        if 'content-length' in request.headers:
+            headers['content-length'] = request.headers['content-length']
+        uploaded = asyncio.Event()
+        async def upload():
+            try:
+                async for chunk in request.stream(): yield chunk
+            finally:
+                uploaded.set()
+        async def disconnected():
+            # Wait for the upload reader to finish before reading disconnects.
+            # No polling, execution deadline, or competing request-body reader.
+            await uploaded.wait()
+            while (await request.receive()).get('type') != 'http.disconnect':
+                pass
+        req = self.client.build_request(request.method, self.upstream + '/' + path,
+            params=request.query_params.multi_items(), headers=headers, content=upload())
+        sending = asyncio.create_task(self.client.send(req, stream=True))
+        disconnect = asyncio.create_task(disconnected())
+        try:
+            done, _ = await asyncio.wait((sending, disconnect), return_when=asyncio.FIRST_COMPLETED)
+            if disconnect in done:
+                if sending.done() and not sending.cancelled() and sending.exception() is None:
+                    await sending.result().aclose()
+                return Response(status_code=499)
+            upstream = sending.result()
+        except httpx.HTTPError:
+            return Response('Custom endpoint connection failed', status_code=502)
+        finally:
+            for task in (sending, disconnect):
+                if not task.done(): task.cancel()
+            await asyncio.gather(sending, disconnect, return_exceptions=True)
+        headers = {k: v for k, v in upstream.headers.items() if k.lower() not in _HOP_HEADERS | {'content-encoding', 'set-cookie'}}
+        async def body():
+            try:
+                chunks = upstream.aiter_bytes()
+                if upstream.status_code == 200 and 'text/event-stream' in upstream.headers.get('content-type', '').lower():
+                    chunks = ErrorFrames(self.key).stream(chunks)
+                async for chunk in chunks:
+                    yield chunk
+            finally:
+                await upstream.aclose()
+        return StreamingResponse(body(), status_code=upstream.status_code, headers=headers)
+
+    async def close(self):
+        if self.server is not None:
+            self.server.should_exit = True
+            # The owning native process has already closed; cancel only this
+            # listener's in-flight transports, including a silent upstream.
+            tasks = tuple(self.server.server_state.tasks)
+            for task in tasks: task.cancel()
+            if tasks: await asyncio.gather(*tasks, return_exceptions=True)
+        if self.task is not None:
+            # Let Uvicorn close its asyncio listeners and remove their readers.
+            # Cancelling serve() skips shutdown and can leave a stale selector
+            # entry when the next provider reuses the same socket descriptor.
+            with suppress(asyncio.CancelledError): await self.task
+        if self.client is not None: await self.client.aclose()
+        if self.socket is not None: self.socket.close()
+        self.task = self.server = self.client = self.socket = None
+
+
+class CustomCodexAppServerManager(CodexAppServerManager):
+    """Native manager with an owned, credential-scoped stream normalizer."""
+    def __init__(self, *args, selected: dict, **kwargs):
+        self.response_bridge = ResponseStreamBridge(selected)
+        prepare = kwargs.pop('before_start', None)
+        environment = kwargs.pop('env_factory')
+        original_args = tuple(kwargs.get('app_server_args', ()))
+        async def before_start():
+            if prepare is not None: await prepare()
+            await self.response_bridge.start()
+            self.client.app_server_args = (*original_args, *config_args({
+                f'model_providers.{PROVIDER_ID}.base_url': self.response_bridge.url}))
+        def env_factory():
+            return {**environment(), ENV_KEY: self.response_bridge.token}
+        kwargs['sensitive_values'] = (*kwargs.get('sensitive_values', ()), self.response_bridge.token)
+        super().__init__(*args, before_start=before_start, env_factory=env_factory, **kwargs)
+
+    async def close(self):
+        try:
+            await super().close()
+        finally:
+            await self.response_bridge.close()

package/server/codex_side_chat_progress.py

@@ -0,0 +1,110 @@
+"""User-visible native Codex side-thread activity; never project parent/control input."""
+from __future__ import annotations
+
+import asyncio
+from copy import deepcopy
+
+
+class CodexSideChatProgress:
+    def __init__(self, publish, *, thread_id):
+        self.publish = publish
+        self.thread_id = thread_id
+        self.items = {}
+        self.parts = {}
+        self.completed = set()
+        self.pending = None
+        self.dirty = False
+
+    def _item(self, identifier, kind):
+        key = f"{identifier}:{kind}"
+        if key not in self.items:
+            self.items[key] = {"id": key, "kind": kind, "text": "", "status": "running"}
+        return self.items[key]
+
+    @staticmethod
+    def _text(parts):
+        if not isinstance(parts, list):
+            return ""
+        return "\n\n".join(part if isinstance(part, str) else str(part.get("text") or part.get("summary_text") or "")
+                            for part in parts if isinstance(part, (str, dict)))
+
+    def receive(self, packet):
+        method, data = packet.get("method"), packet.get("params") or {}
+        # The transport normally scopes notifications; enforce it here too so
+        # descendant activity cannot become the side assistant's own answer.
+        if data.get("threadId") not in (None, self.thread_id):
+            return
+        item = data.get("item") or {}
+        identifier = str(data.get("itemId") or item.get("id") or "")
+        if not identifier or identifier in self.completed:
+            return
+        changed = False
+        if method in {"item/reasoning/summaryTextDelta", "item/reasoning/textDelta", "item/reasoning/summaryPartAdded"}:
+            kind = "reasoning" if method == "item/reasoning/textDelta" else "reasoning_summary"
+            field = "contentIndex" if kind == "reasoning" else "summaryIndex"
+            index = data.get(field, 0)
+            if not isinstance(index, int) or index < 0:
+                return
+            parts = self.parts.setdefault((identifier, kind), {})
+            parts[index] = parts.get(index, "") + str(data.get("delta") or "")
+            self._item(identifier, kind)["text"] = "\n\n".join(parts[i] for i in sorted(parts))
+            changed = True
+        elif method == "item/agentMessage/delta":
+            # item/started carries the phase. Older runtimes may emit deltas
+            # first; item/completed supplies the authoritative final phase.
+            kind = "commentary" if f"{identifier}:commentary" in self.items else "answer"
+            self._item(identifier, kind)["text"] += str(data.get("delta") or "")
+            changed = True
+        elif method in {"item/started", "item/completed"}:
+            item_type = item.get("type")
+            if item_type == "reasoning":
+                for kind, field in (("reasoning_summary", "summary"), ("reasoning", "content")):
+                    text = self._text(item.get(field))
+                    if text or (identifier, kind) in self.parts:
+                        projected = self._item(identifier, kind)
+                        if text:
+                            projected["text"] = text
+                        changed = True
+            elif item_type == "agentMessage":
+                kind = "commentary" if item.get("phase") == "commentary" else "answer"
+                other = f"{identifier}:{'answer' if kind == 'commentary' else 'commentary'}"
+                if other in self.items:
+                    # Keep its chronological slot when an older runtime omits phase at start.
+                    self.items = {f"{identifier}:{kind}" if key == other else key:
+                                  {**value, "id": f"{identifier}:{kind}", "kind": kind} if key == other else value
+                                  for key, value in self.items.items()}
+                projected = self._item(identifier, kind)
+                if isinstance(item.get("text"), str) and (item["text"] or method == "item/completed"):
+                    projected["text"] = item["text"]
+                changed = True
+            elif item_type in {"commandExecution", "mcpToolCall", "dynamicToolCall", "collabAgentToolCall",
+                               "collabToolCall", "webSearch", "fileChange", "imageView", "imageGeneration"}:
+                projected = self._item(identifier, "tool")
+                projected["tool"] = item_type
+                text = item.get("command") if item_type == "commandExecution" else item.get("tool") or item.get("query") or item.get("path")
+                if not text and item_type == "fileChange":
+                    text = ", ".join(str(change.get("path") or "") for change in item.get("changes", []) if isinstance(change, dict))
+                if text:
+                    projected["text"] = str(text)
+                changed = True
+            if method == "item/completed":
+                self.completed.add(identifier)
+                for key, value in self.items.items():
+                    if key.startswith(identifier + ":"):
+                        value["status"] = "completed"
+        if changed:
+            self.dirty = True
+            if self.pending is None:
+                self.pending = asyncio.create_task(self._publish_later())
+
+    async def _publish_later(self):
+        # Coalesce token bursts; no per-token disk writes or client history reads.
+        await asyncio.sleep(0.1)
+        while self.dirty:
+            self.dirty = False
+            await self.publish(deepcopy(list(self.items.values())))
+        self.pending = None
+
+    async def flush(self):
+        if self.pending is not None:
+            await asyncio.shield(self.pending)

package/server/codex_side_question.py

@@ -179,6 +179,7 @@ class NativeCodexSideChat:
         self._cleaning: asyncio.Task | None = None
         self._process_started = asyncio.Event()
         self._active: asyncio.Task | None = None
+        self._progress = None
         self._lock = asyncio.Lock()
         self._closed = False
 
@@ -186,6 +187,12 @@ class NativeCodexSideChat:
     def closed(self) -> bool:
         return self._closed
 
+    def snapshot_progress(self, task):
+        """Copy exposed native items at Stop without flushing or awaiting IO."""
+        if task is None or task.done() or self._active is not task or self._progress is None:
+            return None
+        return deepcopy(list(self._progress.items.values()))
+
     async def _handle_server_request(self, request_id, method, params):
         # The callback can present approvals through the existing UI, but only
         # for this exact child. Never route a parent's inherited tool request.
@@ -284,7 +291,7 @@ class NativeCodexSideChat:
         elif metadata.get("ephemeral") is not True or metadata.get("path") is not None:
             raise SideQuestionError(503, "Codex did not confirm an ephemeral side chat")
 
-    async def ask(self, question: str) -> str:
+    async def ask(self, question: str, *, runtime_settings: dict | None = None, on_progress=None) -> str:
         if self._closed:
             raise SideQuestionError(409, "Side chat was closed; open a new side chat")
         if self._lock.locked():
@@ -292,6 +299,7 @@ class NativeCodexSideChat:
         async with self._lock:
             self._active = asyncio.current_task()
             turn = None
+            progress = None
             try:
                 if self._opening is None:
                     self._opening = asyncio.create_task(self._open())
@@ -300,14 +308,37 @@ class NativeCodexSideChat:
                 await asyncio.shield(self._opening)
                 if self._closed:
                     raise SideQuestionError(409, "Side chat was closed; open a new side chat")
+                overrides = {**self.turn_overrides, **self.provider_turn_overrides}
+                if runtime_settings is not None:
+                    model = runtime_settings["model"]
+                    effort = runtime_settings.get("effort") or ""
+                    # Explicit default must clear a previous turn's effort;
+                    # null effort alone would inherit it from the thread.
+                    overrides.pop("effort", None)
+                    overrides.update({"model": model, "collaborationMode": {"mode": "default", "settings": {
+                        "model": model, "reasoning_effort": effort or None, "developer_instructions": None}}})
+                    if effort:
+                        overrides["effort"] = effort
+                    if self.provider_config:
+                        from codex_provider import turn_overrides
+                        overrides.update(turn_overrides(model, effort,
+                            summary=runtime_settings.get("reasoning_summary") or "none"))
                 turn = await self._client.start_turn(
                     self.thread_id, [{"type": "text", "text": question}],
-                    overrides={**self.turn_overrides, **self.provider_turn_overrides},
+                    overrides=overrides,
                 )
+                if on_progress is not None:
+                    from codex_side_chat_progress import CodexSideChatProgress
+                    progress = CodexSideChatProgress(on_progress, thread_id=self.thread_id)
+                    self._progress = progress
                 answers: dict[str, str] = {}
                 while True:
                     packet = await turn.next_notification()
                     method, data = packet.get("method"), packet.get("params", {})
+                    if data.get("threadId") not in (None, self.thread_id):
+                        continue
+                    if progress is not None:
+                        progress.receive(packet)
                     if method == "item/completed":
                         item = data.get("item", {})
                         if item.get("type") == "agentMessage" and item.get("phase") in (None, "", "final_answer"):
@@ -323,6 +354,8 @@ class NativeCodexSideChat:
                         answer = "\n\n".join(answers.values()).strip()
                         if not answer:
                             raise SideQuestionError(502, "Codex did not return a side question answer")
+                        if progress is not None:
+                            await progress.flush()
                         return answer
             except CodexAppServerError:
                 await self.close()
@@ -331,9 +364,16 @@ class NativeCodexSideChat:
                 await self.close()
                 raise
             finally:
-                if turn is not None:
-                    await turn.close()
-                self._active = None
+                try:
+                    if progress is not None:
+                        await progress.flush()
+                finally:
+                    try:
+                        if turn is not None:
+                            await turn.close()
+                    finally:
+                        self._progress = None
+                        self._active = None
 
     async def close(self):
         self._closed = True