Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

feat(chat): add a stop button and raise the turn ceiling to 300s

Rufus3e25dcbc1256
diff --git a/.env.example b/.env.example
index 9eb1b1bf..d5579aa2 100644
--- a/.env.example
+++ b/.env.example
@@ -129,6 +129,20 @@ LOCAL_INCLUDE_USAGE_ACCOUNTING=false
# (Server-side web search has no local equivalent and is disabled for local
# models; tool-use quality depends on the model you choose.)
+# --- Chat turn timeouts -------------------------------------------------------
+# Whole-turn wall-clock ceiling for a streaming /chat turn, in seconds. A turn
+# that exceeds it is cut off and whatever streamed so far is persisted. Users
+# can also end a turn themselves with the Stop button (POST /chat/stop), which
+# is what makes a ceiling this generous reasonable.
+# CHAT_STREAM_TIMEOUT_S=300
+# Extra allowance added on top when a message opts in to Committee review, so
+# 360s in total at the defaults.
+# COMMITTEE_EXTRA_TIMEOUT_S=60
+# Per-call ceiling for the onboarding interview. Kept separate from the chat
+# ceiling: the wizard retries twice, so a 300s value here would mean a 10-minute
+# hang before the user sees a timeout.
+# INTERVIEW_TIMEOUT_S=120
+
# --- Honcho per-person memory ------------------------------------------------
# External memory layer (https://honcho.dev) that gives the Executive a
# per-person peer card shared across Slack, Discord, Telegram, email, and the
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fb22f5e6..4b9ad00e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -53,7 +53,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
new `app_migrations` table); the sweep can be deleted in the release after
next.
+### Changed
+- **The chat turn ceiling is now 300s (360s with Committee review)**, up from
+ 120s/180s: deep multi-specialist turns were being cut off mid-answer. A
+ ceiling this generous is only reasonable because a turn can now be ended by
+ the user, so the two changes ship together. The onboarding interview, which
+ previously borrowed `CHAT_STREAM_TIMEOUT_S`, gets its own
+ `INTERVIEW_TIMEOUT_S` (still 120s) — it retries twice, so inheriting the new
+ ceiling would have meant a 10-minute hang before the wizard surfaced a
+ timeout.
+
+### Fixed
+- **A turn broken off early is no longer missing from the next turn's
+ context.** On the disconnect and timeout paths the route persisted the
+ partial turn to SQLite, but the Executive's post-turn block — which mirrors
+ it into the live in-memory session — was skipped, and a cached session never
+ re-reads its history from the DB. The next turn in the same process then
+ prompted as though the turn had never happened, while a page reload showed
+ it. The route now mirrors the turn itself on every broken-out path.
+- **The UI proxy now forwards client disconnects upstream.** `signal:
+ req.signal` was missing from the backend proxy's `fetch`, so the API never
+ saw `http.disconnect` and its `request.is_disconnected()` check could not
+ fire in production: closing a tab left the turn running to completion against
+ Anthropic and the partial reply was never saved.
+- **A disconnected turn no longer keeps working after the client is gone.**
+ The SSE driver races the stop switch with `asyncio.wait`, which — unlike the
+ `asyncio.wait_for` it replaced — does not cancel its futures when the task
+ awaiting it is cancelled. Since Starlette cancels the response body on
+ `http.disconnect`, the in-flight step is now cancelled in a `finally`, so a
+ closed tab cannot leave a specialist or tool round running with no deadline
+ and no persistence.
+
### Added
+- **Stop button in chat.** A reply can now be halted mid-stream, from the main
+ chat composer and the Ask OE side panel (Escape works too). Whatever the
+ Executive had written is kept, persisted and marked *Stopped by you*, so a
+ truncated answer is not read back as a complete one after a reload. The
+ client mints a `client_turn_id` and sends it with the turn; `POST /chat/stop`
+ halts it. Keying on a client-minted id is what makes the button live from the
+ moment Send is pressed — the server spends several seconds fetching context
+ before the response stream exists, and a stop inside that window costs
+ nothing because no model call has been made yet. An unknown id and another
+ caller's turn both return 404, so the endpoint cannot be used to probe which
+ turns are live.
- **Conversational onboarding.** `/onboard` now opens with "tell me about your
company" instead of a 12-step form. The user writes a paragraph (and can
attach a deck, one-pager or brief), the new `onboarding_interviewer` agent
diff --git a/packages/core/openexecutive/api/models.py b/packages/core/openexecutive/api/models.py
index 8db76268..4e59ed62 100644
--- a/packages/core/openexecutive/api/models.py
+++ b/packages/core/openexecutive/api/models.py
@@ -56,6 +56,23 @@ class ChatRequest(BaseModel):
committee_review: bool = False
# Set by the Ask OE side panel only; absent on the main chat page.
page_context: PageContext | None = None
+ # Client-minted id for THIS turn, so the client can address it via
+ # POST /chat/stop from the moment Send is pressed. It is deliberately not
+ # the audit `turn_id` (that keeps its server-minted `t-` shape, which audit
+ # queries filter on) — see `_clean_client_turn_id` in api/routes/chat.py.
+ # Bounded, but deliberately NOT pattern-validated here: a malformed id only
+ # means this turn can't be stopped, and 422-ing the whole chat turn over it
+ # would contradict `_clean_client_turn_id`, which drops it and carries on.
+ # The max_length is a size bound, not a format check.
+ client_turn_id: str | None = Field(None, max_length=64)
+
+
+class StopChatRequest(BaseModel):
+ """Body of POST /chat/stop — the `client_turn_id` sent with the turn."""
+
+ client_turn_id: str = Field(
+ ..., min_length=8, max_length=64, pattern=r"^[A-Za-z0-9-]+$"
+ )
class ChatResponse(BaseModel):
diff --git a/packages/core/openexecutive/api/routes/chat.py b/packages/core/openexecutive/api/routes/chat.py
index 4a1921ed..488b4f6d 100644
--- a/packages/core/openexecutive/api/routes/chat.py
+++ b/packages/core/openexecutive/api/routes/chat.py
@@ -8,12 +8,12 @@ import re
import sqlite3
import time
import uuid
-from typing import Any
+from typing import Any, NamedTuple
from fastapi import APIRouter, File, Form, HTTPException, Request, UploadFile
from fastapi.responses import StreamingResponse
-from openexecutive.api.models import ChatRequest, PageContext
+from openexecutive.api.models import ChatRequest, PageContext, StopChatRequest
from openexecutive.audit import log_event as audit_log
from openexecutive.integrations.attachments import build_attachment_output
from openexecutive.orchestrator.debug_events import DebugCollector
@@ -67,6 +67,317 @@ def _clean_session_id(session_id: str | None) -> str | None:
return session_id
+# Client-minted turn ids address an in-flight turn from POST /chat/stop. The
+# charset is deliberately NARROWER than _SESSION_ID_RE: this value reaches log
+# lines (same log-injection argument as above) and nothing here needs the
+# integration-shaped ids a session id has to carry — a uuid4 is the only
+# expected shape.
+# `\Z`, not `$`: `$` also matches before a trailing newline, so `re.match`
+# would accept "aaaaaaaa\n" and register an id with a newline in it.
+_CLIENT_TURN_ID_RE = re.compile(r"^[A-Za-z0-9-]{8,64}\Z")
+
+# Upper bound on the live-turn registry. Entries are popped in _sse_body's
+# `finally`, so this only matters if a turn dies somewhere that bypasses it;
+# the cap keeps such a leak from growing without limit.
+_STOP_REGISTRY_MAX = 512
+
+# Headroom on top of the whole-turn deadline before a registry entry is
+# considered stranded. Covers the pre-stream context fetch and the post-stream
+# persistence, neither of which counts against the turn deadline.
+_STOP_TTL_GRACE_S = 120.0
+
+
+class _StopEntry(NamedTuple):
+ event: asyncio.Event
+ # Who may stop this turn. NOT the raw `caller_person_id`: that resolves to
+ # None for a signed-in user who isn't on the People roster yet, for a fresh
+ # install with no principal, and on any transient DB error during lookup —
+ # so comparing person ids directly would make every such caller the owner
+ # of every other such caller's turn. See `_stop_owner_key`.
+ owner: str
+ turn_id: str
+ # Monotonic registration time, used to reclaim entries stranded by a path
+ # that never reaches `_sse_body`'s `finally`.
+ started_at: float
+
+
+# client_turn_id -> stop switch for every currently-streaming chat turn. Same
+# shape as `_active_cancellations` in api/routes/evals.py — structurally the
+# identical mechanism (id -> event registry, a POST that flips it, a terminal
+# SSE event, the streamer popping the entry in its `finally`).
+#
+# The vocabulary differs on purpose and the split is worth knowing about when
+# grepping: evals "cancels" a RUN the user started and may not be watching, and
+# says `canceled`; chat "stops" a reply that is being written in front of the
+# user, and says `stopped`, because that is the word on the button. If you are
+# looking for every stoppable-async pattern in this codebase, grep both.
+#
+# Single-process only — exactly like `_sessions` above and `_last_turn_*` below. A second
+# uvicorn worker would break in-flight session continuity before it broke this.
+_active_stops: dict[str, _StopEntry] = {}
+
+
+def _clean_client_turn_id(client_turn_id: str | None) -> str | None:
+ """Drop a client-supplied turn id that isn't a plausible id.
+
+ Dropped rather than rejected, following `_clean_session_id`: a malformed id
+ only means this turn cannot be stopped, which is never a reason to fail the
+ turn itself.
+ """
+ if client_turn_id is None:
+ return None
+ if not _CLIENT_TURN_ID_RE.match(client_turn_id):
+ logger.warning("chat.client_turn_id_rejected len=%d", len(client_turn_id))
+ return None
+ return client_turn_id
+
+
+# Strong references to detached rename tasks, so GC cannot cancel one
+# mid-flight. Mirrors `memory.episodic._background_tasks`.
+_rename_tasks: set[asyncio.Task[None]] = set()
+
+
+def _rename_session_in_background(
+ session_id: str, message: str, full_response: str, turn_id: str
+) -> None:
+ """Generate and store a session title without holding up the stream.
+
+ Used on the stop path only. Everywhere else the rename is awaited so the
+ sidebar has the good title by the time the client acts on `done`.
+ """
+ from openexecutive.config import get_settings
+ from openexecutive.memory.session_store import update_session_title
+ from openexecutive.utils.session_title import generate_session_title
+
+ async def _run() -> None:
+ try:
+ new_title = await asyncio.wait_for(
+ generate_session_title(message, full_response),
+ timeout=get_settings().utility_fast_timeout_s,
+ )
+ if new_title:
+ update_session_title(session_id, new_title)
+ except Exception:
+ # asyncio.TimeoutError is an Exception subclass in 3.11+, so this
+ # covers the timeout and any DB failure. A missed rename only
+ # leaves the placeholder title.
+ logger.exception("chat.title_update_failed turn_id=%s", turn_id)
+
+ try:
+ task = asyncio.create_task(_run())
+ except RuntimeError: # pragma: no cover - no running loop (CLI context)
+ return
+ _rename_tasks.add(task)
+ task.add_done_callback(_rename_tasks.discard)
+
+
+def _stop_owner_key(request: Request, caller_person_id: int | None) -> str:
+ """A stable identity for "who may stop this turn".
+
+ Prefers the roster Person id, then the verified caller email, then a
+ local-trust sentinel. The email step matters: `_resolve_caller_person_id`
+ collapses every unrostered signed-in user to None, and two different people
+ must not end up owning each other's turns just because neither is on the
+ roster yet. The UI proxy strips client-sent `x-caller-*` and re-stamps the
+ header from the verified session, so the email cannot be spoofed.
+
+ The sentinel is only reached when there is no header at all — CLI and
+ direct curl against a local API, where there is no identity to separate.
+ """
+ if caller_person_id is not None:
+ return f"person:{caller_person_id}"
+ email = (request.headers.get("x-caller-email") or "").strip().lower()
+ if email:
+ return f"email:{email}"
+ return "local"
+
+
+def _sweep_stale_stops() -> None:
+ """Reclaim entries that outlived any turn that could still be running.
+
+ Entries are normally popped in `_sse_body`'s `finally`, but that only runs
+ once Starlette starts consuming the generator. Anything that strands an
+ entry would otherwise hold its slot for the life of the process — and since
+ a full registry now refuses NEW turns rather than evicting live ones, 512
+ strandings would silently take the Stop button away from everybody until a
+ restart. The TTL is generous: it only needs to exceed the longest a turn
+ can legitimately hold a slot.
+ """
+ # Imported lazily, like every other `get_settings` use in this module.
+ from openexecutive.config import get_settings
+
+ settings = get_settings()
+ ttl = (
+ settings.chat_stream_timeout_s
+ + settings.committee_extra_timeout_s
+ + _STOP_TTL_GRACE_S
+ )
+ cutoff = time.monotonic() - ttl
+ stale = [k for k, e in _active_stops.items() if e.started_at < cutoff]
+ for key in stale:
+ _active_stops.pop(key, None)
+ if stale:
+ logger.warning("chat.stop_registry_swept count=%d", len(stale))
+
+
+def _register_stop(
+ client_turn_id: str, owner: str, turn_id: str
+) -> asyncio.Event | None:
+ """Register a stop switch for a turn that is about to stream.
+
+ Returns None when the turn could not be registered, which only costs it the
+ Stop button — never the turn itself.
+ """
+ _sweep_stale_stops()
+ if client_turn_id in _active_stops:
+ # A live turn already owns this id (client retry, double submit, a
+ # scripted caller reusing a value). Overwriting would make the first
+ # turn permanently unstoppable and point Stop at the wrong one, and
+ # whichever finished first would pop the other's entry.
+ logger.warning("chat.stop_id_collision turn_id=%s", turn_id)
+ return None
+ if len(_active_stops) >= _STOP_REGISTRY_MAX:
+ # Deliberately refuse the NEW turn rather than evicting the oldest
+ # entry: entries are popped when their turn ends, so the oldest is
+ # typically a long-running LIVE turn, and evicting it would silently
+ # take the Stop button away from the person most likely to want it.
+ logger.warning("chat.stop_registry_full turn_id=%s", turn_id)
+ return None
+ event = asyncio.Event()
+ _active_stops[client_turn_id] = _StopEntry(
+ event, owner, turn_id, time.monotonic()
+ )
+ return event
+
+
+def _release_stop(client_turn_id: str | None, turn_id: str | None = None) -> None:
+ """Drop a turn's registry entry, but only if it is still that turn's.
+
+ The identity check stops one turn from popping an entry belonging to a
+ different turn that reused the same client id.
+ """
+ if not client_turn_id:
+ return
+ entry = _active_stops.get(client_turn_id)
+ if entry is None:
+ return
+ if turn_id is not None and entry.turn_id != turn_id:
+ return
+ _active_stops.pop(client_turn_id, None)
+
+
+class _StreamStep(NamedTuple):
+ """One step of the SSE driver loop.
+
+ Exactly one of these is true: `item` holds a produced value, or `exhausted`
+ / `stopped` / `timed_out` says why nothing was produced.
+ """
+
+ item: Any = None
+ produced: bool = False
+ exhausted: bool = False
+ stopped: bool = False
+ timed_out: bool = False
+
+
+async def _cancel_stream_step(anext_task: asyncio.Task[Any], turn_id: str) -> None:
+ """Cancel an in-flight `__anext__` step and wait for it to unwind.
+
+ `cancel()` only *requests* cancellation; the throw is not delivered until
+ the task next runs. Two things depend on actually awaiting it:
+
+ - `aclose()` on an async generator whose `__anext__` task is still running
+ raises RuntimeError("asynchronous generator is already running").
+ - The await is what stops the work. The CancelledError propagates into
+ whatever the Executive is awaiting — the Anthropic stream, a tool call, a
+ specialist gather — which is why executive.py re-raises CancelledError
+ out of its `gather(return_exceptions=True)` calls rather than treating it
+ as a tool failure.
+ """
+ if anext_task.done():
+ return
+ anext_task.cancel()
+ try:
+ await anext_task
+ except (asyncio.CancelledError, StopAsyncIteration):
+ # Deliberately not `suppress(BaseException)`: that would hide real
+ # cleanup errors. Catching CancelledError here can also swallow an
+ # OUTER cancel re-delivered during this await, but we are called from a
+ # `finally` while that cancellation is already propagating, so it
+ # continues on its way regardless — and the inner `cancel()` above has
+ # already been requested, which is the part that must not be skipped.
+ pass
+ except Exception:
+ logger.exception("chat.stream_step_failed turn_id=%s", turn_id)
+
+
+async def _next_stream_step(
+ stream: Any,
+ stop_waiter: asyncio.Task[bool] | None,
+ remaining: float,
+ turn_id: str,
+) -> _StreamStep:
+ """Advance `stream` one step, racing the stop switch and the deadline.
+
+ Extracted from the driver loop because the ordering here is load-bearing in
+ several ways and is much easier to reason about — and to test — on its own.
+
+ `asyncio.wait_for` cannot be used: it owns its inner task and cancels it on
+ timeout, leaving nothing to race a second future against. But that also
+ means we inherit a duty `wait_for` used to discharge for us. `asyncio.wait`
+ does NOT cancel its futures when the task awaiting it is cancelled, and
+ Starlette cancels this whole body on `http.disconnect` — so without the
+ `finally` below, a closed tab would leave `__anext__` running a full
+ specialist or tool round with no deadline, no registry entry and no
+ persistence. The `finally` is the load-bearing part of this function.
+ """
+ # One Task per step — exactly what `asyncio.wait_for` built here before,
+ # and like it this COPIES the current context, so the `set_turn` /
+ # `set_session` bindings made in `event_generator` are inherited by every
+ # step. See that function's comment for why that matters.
+ anext_task: asyncio.Task[Any] = asyncio.ensure_future(stream.__anext__())
+ try:
+ waiters: set[asyncio.Future[Any]] = {anext_task}
+ if stop_waiter is not None:
+ waiters.add(stop_waiter)
+ await asyncio.wait(
+ waiters, timeout=remaining, return_when=asyncio.FIRST_COMPLETED
+ )
+
+ if anext_task.done():
+ # Deliver a produced item even when the stop fired in the same
+ # tick. The work is already paid for, and an `action_taken` here
+ # would otherwise be dropped from the chips we persist. There is no
+ # await between the `wait` above and this check, so nothing can slip
+ # in between them.
+ try:
+ return _StreamStep(item=anext_task.result(), produced=True)
+ except StopAsyncIteration:
+ return _StreamStep(exhausted=True)
+
+ if stop_waiter is not None and stop_waiter.done():
+ return _StreamStep(stopped=True)
+ return _StreamStep(timed_out=True)
+ finally:
+ # Every exit: stop, deadline, AND an outer cancellation from a client
+ # disconnect. Never leave the step running.
+ await _cancel_stream_step(anext_task, turn_id)
+
+
+def _request_stop(client_turn_id: str, owner: str) -> str | None:
+ """Flip a turn's stop switch. Returns its server `turn_id`, or None.
+
+ None covers BOTH "no such live turn" and "not yours" on purpose: the two
+ must be indistinguishable to the caller, or the endpoint becomes an oracle
+ for which turn ids are live.
+ """
+ entry = _active_stops.get(client_turn_id)
+ if entry is None or entry.owner != owner:
+ return None
+ entry.event.set()
+ return entry.turn_id
+
+
def _get_or_create_session(session_id: str | None, request: Request) -> Any:
from openexecutive.memory.session_store import load_messages
from openexecutive.onboarding.profile_builder import load_or_create_profile
@@ -230,6 +541,7 @@ async def _run_chat_turn(
attachment_blocks: list[dict[str, Any]] | None,
request: Request,
page_context: PageContext | None = None,
+ client_turn_id: str | None = None,
) -> StreamingResponse:
"""Shared streaming-chat handler for both the JSON and multipart routes.
@@ -250,7 +562,46 @@ async def _run_chat_turn(
turn_id = f"t-{uuid.uuid4().hex[:12]}"
collector = DebugCollector(t0=t0, turn_id=turn_id)
- session = _get_or_create_session(session_id, request)
+ # Resolve the caller and arm the stop switch FIRST, before the session
+ # load, the audit write and the context fan-out below. Every one of those
+ # happens before the StreamingResponse exists, so the client has no SSE
+ # byte to learn a server id from and can only address the turn by the id it
+ # minted itself. Registering here makes the Stop button live from as close
+ # to "the moment Send was pressed" as the server can manage; a stop landing
+ # in this window also costs zero tokens, because the Executive is never
+ # asked for a first step.
+ #
+ # `_resolve_caller_person_id` is used for Honcho's per-person memory and
+ # for tagging the session row's owner (so /sessions can filter the sidebar
+ # by signed-in user); see its docstring for the precedence rule that
+ # protects against cross-identity leakage.
+ caller_person_id = _resolve_caller_person_id(request)
+ client_turn_id = _clean_client_turn_id(client_turn_id)
+ stop_event: asyncio.Event | None = None
+ if client_turn_id:
+ stop_event = _register_stop(
+ client_turn_id, _stop_owner_key(request, caller_person_id), turn_id
+ )
+ if stop_event is None:
+ # Refused (id collision, or the registry is at its cap). The turn
+ # still runs; it just isn't stoppable. Drop our handle so the
+ # `finally` below can't pop an entry belonging to another turn.
+ client_turn_id = None
+ else:
+ logger.info("chat.stop_registered turn_id=%s", turn_id)
+
+ # Guarded for the same reason as the gather further down: the stop switch
+ # is already registered, and `_sse_body`'s `finally` — which normally
+ # releases it — only runs once Starlette starts consuming the generator.
+ # This call can realistically raise (a hand-edited `company/profile.yaml`
+ # that no longer parses, or a locked SQLite DB), and a stranded entry is
+ # now permanent-ish: the registry refuses new turns at its cap rather than
+ # evicting live ones, so enough of them would disable Stop for everybody.
+ try:
+ session = _get_or_create_session(session_id, request)
+ except BaseException:
+ _release_stop(client_turn_id, turn_id)
+ raise
is_first_turn = len(session.conversation_history) == 0
logger.info(
@@ -273,11 +624,6 @@ async def _run_chat_turn(
full={"message": message},
)
- # Resolve the caller. Used for Honcho's per-person memory AND for
- # tagging the session row's owner (so /sessions can filter the
- # sidebar by signed-in user). See `_resolve_caller_person_id` for
- # the precedence rule that protects against cross-identity leakage.
- caller_person_id = _resolve_caller_person_id(request)
# Let the caller schedule to their own addresses. Runs per turn rather than
# only on session creation so a newly-added address works without a fresh
# session; note it only ever ADDS, so an address removed from the roster
@@ -379,37 +725,48 @@ async def _run_chat_turn(
# instead of only the ones that reach the recorder.
session.trusted_alert_ids = set()
- retrieved_context, episodic_context, peer_memory_context, briefing_context = await asyncio.gather(
- asyncio.to_thread(
- retrieve,
- query=message,
- specialist_name=None,
- store=request.app.state.store if hasattr(request.app.state, "store") else None,
- ),
- _do_episodic(),
- _do_prefetch(),
- _do_briefing(),
- )
-
- sources = _extract_sources(retrieved_context)
- collector.emit("knowledge_retrieved", {
- "query": message,
- "chunk_count": len(sources),
- "sources": sources,
- })
- logger.info("chat.knowledge_done turn_id=%s chunks=%d", turn_id, len(sources))
-
- page_context_block = _build_page_context_block(page_context)
-
- executive = Executive(mcp_gateway=getattr(request.app.state, "mcp_gateway", None))
- settings = get_settings()
- timeout_s = settings.chat_stream_timeout_s
-
- if committee_review:
- # Committee adds reviewer fan-out + a full revision pass on top of
- # the draft. Extend the whole-turn deadline so the route doesn't
- # cut us off mid-revision.
- timeout_s += settings.committee_extra_timeout_s
+ # `_sse_body`'s `finally` is what normally releases the registry entry, but
+ # it only runs once Starlette starts consuming the generator. Everything
+ # from here to the `StreamingResponse` below therefore needs its own
+ # guard — the gather, the page-context builder and the settings load can
+ # all raise, and the entry would otherwise be stranded until the registry
+ # cap evicted it.
+ try:
+ retrieved_context, episodic_context, peer_memory_context, briefing_context = await asyncio.gather(
+ asyncio.to_thread(
+ retrieve,
+ query=message,
+ specialist_name=None,
+ store=request.app.state.store if hasattr(request.app.state, "store") else None,
+ ),
+ _do_episodic(),
+ _do_prefetch(),
+ _do_briefing(),
+ )
+ sources = _extract_sources(retrieved_context)
+ collector.emit("knowledge_retrieved", {
+ "query": message,
+ "chunk_count": len(sources),
+ "sources": sources,
+ })
+ logger.info("chat.knowledge_done turn_id=%s chunks=%d", turn_id, len(sources))
+
+ page_context_block = _build_page_context_block(page_context)
+
+ executive = Executive(
+ mcp_gateway=getattr(request.app.state, "mcp_gateway", None)
+ )
+ settings = get_settings()
+ timeout_s = settings.chat_stream_timeout_s
+
+ if committee_review:
+ # Committee adds reviewer fan-out + a full revision pass on top of
+ # the draft. Extend the whole-turn deadline so the route doesn't
+ # cut us off mid-revision.
+ timeout_s += settings.committee_extra_timeout_s
+ except BaseException:
+ _release_stop(client_turn_id, turn_id)
+ raise
async def event_generator():
# Bind the turn AND the session for the whole SSE body, not just its
@@ -454,6 +811,7 @@ async def _run_chat_turn(
exec_t0 = time.monotonic()
timed_out = False
client_disconnected = False
+ stopped = False
try:
# Flush knowledge_retrieved (and any other pre-stream events) first.
@@ -526,10 +884,22 @@ async def _run_chat_turn(
"assistant",
full_response,
action_chips=json.dumps(action_chips) if action_chips else None,
+ stopped=stopped,
)
+ # The Executive's own post-turn block (executive.py, after its
+ # `async for`) is what normally mirrors the turn into the live
+ # in-memory Session. On every broken-out path it is skipped,
+ # because the generator is closed at its yield — and
+ # `_get_or_create_session` never re-reads history for a session
+ # already in `_sessions`. Without this the NEXT turn in this
+ # process would build its prompt as though the stopped turn had
+ # never happened, while a page reload showed it.
+ if stopped or client_disconnected or timed_out:
+ session.add_user_message(message)
+ session.add_assistant_message(full_response)
logger.info(
- "chat.turn_persisted turn_id=%s is_first_turn=%s disconnected=%s",
- turn_id, is_first_turn, client_disconnected,
+ "chat.turn_persisted turn_id=%s is_first_turn=%s disconnected=%s stopped=%s",
+ turn_id, is_first_turn, client_disconnected, stopped,
)
# First-turn rename: replace the truncated-message
@@ -541,7 +911,22 @@ async def _run_chat_turn(
# Hard timeout on the title call so a slow/hung Haiku can't
# stall the SSE `done` event indefinitely. On timeout we
# leave the placeholder title in place.
- if is_first_turn:
+ if is_first_turn and stopped:
+ # The rename is a Haiku round-trip with a
+ # `utility_fast_timeout_s` budget (10s by default), and on
+ # the stop path the user is waiting on the stream to close
+ # — a stop that takes ten seconds to finish is not a stop.
+ # But it cannot simply be skipped either: the rename only
+ # ever runs on a first turn, and the mirror above has
+ # already made this turn part of the history, so turn 2
+ # would not be a first turn and the session would keep its
+ # truncated-message placeholder title forever. Run it
+ # detached instead, so the stream closes immediately and
+ # the sidebar picks the title up on its next refresh.
+ _rename_session_in_background(
+ session.session_id, message, full_response, turn_id
+ )
+ elif is_first_turn:
from openexecutive.memory.session_store import (
update_session_title,
)
@@ -563,60 +948,106 @@ async def _run_chat_turn(
"chat.title_update_failed turn_id=%s", turn_id
)
- while True:
- if await request.is_disconnected():
- client_disconnected = True
- logger.info("chat.client_disconnected turn_id=%s", turn_id)
- break
-
- remaining = deadline - time.monotonic()
- if remaining <= 0:
- timed_out = True
- logger.warning(
- "chat.timeout turn_id=%s timeout_s=%s collected_chunks=%d",
- turn_id, timeout_s, chunk_count,
- )
- break
+ # One long-lived waiter, created once. Re-creating it per iteration
+ # would race `Event.set()` and could miss a stop that landed
+ # between two steps.
+ stop_waiter: asyncio.Task[bool] | None = (
+ asyncio.ensure_future(stop_event.wait())
+ if stop_event is not None
+ else None
+ )
+ try:
+ while True:
+ if stop_event is not None and stop_event.is_set():
+ # Catches a stop that landed before this step — including
+ # during the pre-stream context gather, where we have not
+ # asked the Executive for anything yet and the stop
+ # therefore costs nothing.
+ stopped = True
+ logger.info(
+ "chat.stopped turn_id=%s chunks=%d", turn_id, chunk_count
+ )
+ break
+
+ if await request.is_disconnected():
+ client_disconnected = True
+ logger.info("chat.client_disconnected turn_id=%s", turn_id)
+ break
+
+ remaining = deadline - time.monotonic()
+ if remaining <= 0:
+ timed_out = True
+ logger.warning(
+ "chat.timeout turn_id=%s timeout_s=%s collected_chunks=%d",
+ turn_id, timeout_s, chunk_count,
+ )
+ break
- try:
- item = await asyncio.wait_for(stream.__anext__(), timeout=remaining)
- except StopAsyncIteration:
- break
- except TimeoutError:
- timed_out = True
- logger.warning(
- "chat.timeout turn_id=%s timeout_s=%s collected_chunks=%d",
- turn_id, timeout_s, chunk_count,
+ step = await _next_stream_step(
+ stream, stop_waiter, remaining, turn_id
)
- break
- if isinstance(item, str):
- if item == Executive._THINKING:
- data = json.dumps({
- "type": "thinking",
- "session_id": session.session_id,
- })
+ if step.exhausted:
+ break
+
+ if step.produced:
+ item = step.item
+ if isinstance(item, str):
+ if item == Executive._THINKING:
+ data = json.dumps({
+ "type": "thinking",
+ "session_id": session.session_id,
+ })
+ else:
+ full_response += item
+ chunk_count += 1
+ data = json.dumps({
+ "type": "chunk",
+ "content": item,
+ "session_id": session.session_id,
+ })
+ yield f"data: {data}\n\n"
+ else:
+ if isinstance(item, dict) and item.get("type") == "action_taken":
+ action_chips.append(item)
+ yield f"data: {json.dumps(item)}\n\n"
+
+ if stop_event is not None and stop_event.is_set():
+ stopped = True
+ logger.info(
+ "chat.stopped turn_id=%s chunks=%d", turn_id, chunk_count
+ )
+ break
+ continue
+
+ if step.stopped:
+ stopped = True
+ logger.info(
+ "chat.stopped turn_id=%s chunks=%d", turn_id, chunk_count
+ )
else:
- full_response += item
- chunk_count += 1
- data = json.dumps({
- "type": "chunk",
- "content": item,
- "session_id": session.session_id,
- })
- yield f"data: {data}\n\n"
- else:
- if isinstance(item, dict) and item.get("type") == "action_taken":
- action_chips.append(item)
- yield f"data: {json.dumps(item)}\n\n"
+ timed_out = True
+ logger.warning(
+ "chat.timeout turn_id=%s timeout_s=%s collected_chunks=%d",
+ turn_id, timeout_s, chunk_count,
+ )
+ break
+ finally:
+ if stop_waiter is not None:
+ # Otherwise: "Task was destroyed but it is pending".
+ stop_waiter.cancel()
logger.info(
- "chat.executive_done turn_id=%s chunks=%d duration_s=%.2f timed_out=%s disconnected=%s",
- turn_id, chunk_count, time.monotonic() - exec_t0, timed_out, client_disconnected,
+ "chat.executive_done turn_id=%s chunks=%d duration_s=%.2f timed_out=%s disconnected=%s stopped=%s",
+ turn_id, chunk_count, time.monotonic() - exec_t0, timed_out,
+ client_disconnected, stopped,
)
# Best-effort cancel of the underlying iterator if we broke out early.
- if timed_out or client_disconnected:
+ # On the stop path the awaited cancellation above has already closed
+ # the generator, so this is a no-op there; it stays as the safety net
+ # for the other break-outs.
+ if timed_out or client_disconnected or stopped:
aclose = getattr(stream, "aclose", None)
if aclose is not None:
with contextlib.suppress(Exception):
@@ -630,8 +1061,36 @@ async def _run_chat_turn(
await _persist_turn()
return
+ # Persist BEFORE the terminal frames on every path, including the
+ # stop. Yielding first would mean that closing the tab in the gap
+ # between the `stopped` frame and this call loses the partial reply
+ # — which is the one thing the feature exists to preserve. The
+ # first-turn title call, which used to make that gap ~10s wide, is
+ # skipped on the stop path above, so persisting first no longer
+ # makes the button feel dead.
await _persist_turn()
+ if stopped:
+ # Not an `error` event — a stop is a user decision, not a
+ # failure.
+ yield f"data: {json.dumps({'type': 'stopped', 'session_id': session.session_id})}\n\n"
+ # The Executive is cancelled before its own post-turn block runs,
+ # so the outbound `chat_turn` row it would have written never
+ # happens. Record the stop here instead, or the audit log shows
+ # an inbound turn with no response side at all.
+ audit_log(
+ "chat_turn",
+ f"Stopped by user after {chunk_count} chunk(s)",
+ session_id=session.session_id,
+ turn_id=turn_id,
+ actor="executive",
+ details={
+ "direction": "out",
+ "stopped": True,
+ "chunks": chunk_count,
+ },
+ )
+
if timed_out:
err_evt = collector.emit("turn_error", {"reason": "timeout", "timeout_s": timeout_s})
yield f"data: {json.dumps(collector.to_sse_dict(err_evt))}\n\n"
@@ -646,6 +1105,7 @@ async def _run_chat_turn(
"chunks": chunk_count,
"duration_s": round(time.monotonic() - exec_t0, 3),
"timed_out": timed_out,
+ "stopped": stopped,
})
yield f"data: {json.dumps(collector.to_sse_dict(complete_evt))}\n\n"
@@ -675,7 +1135,9 @@ async def _run_chat_turn(
"duration_s": round(time.monotonic() - exec_t0, 3),
"timed_out": timed_out,
"client_disconnected": client_disconnected,
+ "stopped": stopped,
}
+ _release_stop(client_turn_id, turn_id)
return StreamingResponse(
event_generator(),
@@ -696,7 +1158,33 @@ async def chat_stream(body: ChatRequest, request: Request) -> StreamingResponse:
attachment_blocks=None,
request=request,
page_context=body.page_context,
+ client_turn_id=body.client_turn_id,
+ )
+
+
[email protected]("/chat/stop")
+async def chat_stop(body: StopChatRequest, request: Request) -> dict[str, str]:
+ """Stop an in-flight /chat turn, addressed by its `client_turn_id`.
+
+ 404 means "no live turn of yours with that id" — a turn that already
+ finished and a turn belonging to someone else are deliberately
+ indistinguishable from here, so this can't be used to probe which ids are
+ live. Stopping is best-effort by design: the SSE stream stays open and
+ remains the authority on how the turn actually ended.
+ """
+ client_turn_id = _clean_client_turn_id(body.client_turn_id)
+ stopped_turn_id = (
+ _request_stop(
+ client_turn_id,
+ _stop_owner_key(request, _resolve_caller_person_id(request)),
+ )
+ if client_turn_id
+ else None
)
+ if stopped_turn_id is None:
+ raise HTTPException(status_code=404, detail="No in-flight turn with that id")
+ logger.info("chat.stop_requested turn_id=%s", stopped_turn_id)
+ return {"status": "stopping", "turn_id": stopped_turn_id}
@router.post("/chat/upload")
@@ -705,6 +1193,9 @@ async def chat_upload(
message: str = Form(..., min_length=1, max_length=32000),
session_id: str | None = Form(None),
committee_review: bool = Form(False),
+ # Size bound only — see the note on ChatRequest.client_turn_id for why the
+ # format is checked by `_clean_client_turn_id` instead of rejected here.
+ client_turn_id: str | None = Form(None, max_length=64),
files: list[UploadFile] = File(...), # noqa: B008 — FastAPI multipart marker, mirrors the pattern for File parameters
) -> StreamingResponse:
"""Streaming chat turn with file/photo attachments.
@@ -765,6 +1256,7 @@ async def chat_upload(
committee_review=committee_review,
attachment_blocks=image_blocks or None,
request=request,
+ client_turn_id=client_turn_id,
)
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yaml
index 895e9b11..a24ba543 100644
--- a/packages/core/openexecutive/architecture/architecture-facts.yaml
+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml
@@ -1763,7 +1763,7 @@ today:
chat:
module: openexecutive.api.routes.chat
- endpoint: POST /chat — server-sent events stream of the live turn.
+ endpoint: POST /chat — server-sent events stream of the live turn. POST /chat/stop halts one mid-flight.
sse_event_types:
- "chunk — one text delta from the assistant response stream. Fields: type, content, session_id."
- "thinking — keepalive emitted at the start of EVERY tool-use round, not just specialist ones. Fields: type, session_id. It carries no tool information, so the UI uses it purely as an in-flight boolean and takes the wording from the `activity` event that immediately precedes it. It used to be the sole driver of a hardcoded 'Consulting specialists…' string, which is why an MCP or calendar round looked like a specialist fan-out."
@@ -1773,8 +1773,116 @@ chat:
- "action_taken — emitted whenever the Executive's tool-use loop completes a side-effecting tool call. Fields: type, tool, summary (≤80 chars, human-readable), target (person / channel ref / resource), link (optional in-app path the UI drills into), iteration. See `openexecutive.orchestrator.action_chips.SIDE_EFFECTING_TOOLS` for the canonical instrumented set; read-only tools (consult_specialist, lookup_person, list_people, search_skills, load_skill, search_tools, web_search, ask_about_person, list_workflows) never emit this event. The chip is suppressed when the handler returned an error payload — no green ✓ over a red outcome."
- "debug_event — internal observability for the Agent Activity panel (knowledge_retrieved, routing_decision, specialist_start/done, synthesis_start, skill_invocation, mcp_invocation, web_search_invocation, committee_*). Not part of the user-visible conversation."
- "form_patch — emitted when the Executive calls `propose_form_values` (Ask OE panel form-fill tier). Fields: type, form_id, fields (name → proposed value map), rationale, iteration. The panel applies the values into the registered on-screen form as highlighted suggestions; nothing is saved server-side and the user submits through the form's normal Save. NOT persisted with the assistant message (same deferred-persistence bucket as the action-chip note below predating chip persistence) — reopening a panel session loses the proposal cards, though values already applied to a form are unaffected."
+ - "stopped — the user halted the turn via POST /chat/stop. Carries type + session_id. ALWAYS followed by `done` over the same still-open stream: the server winds the turn down and reports, rather than the connection simply dying, so a consumer's state machine reaches its normal terminal state and there is no abort path to special-case. Deliberately NOT an `error` — a stop is a user decision, not a failure — so a consumer that ignores the event degrades to 'the turn ended normally', which is the safe reading. Whatever the Executive produced before the stop is persisted and flagged (chat_messages.stopped)."
- "done — final marker carrying the resolved session_id; UI uses this to commit the streamed assistant message and clear the pending-prompt state."
- "error — terminal error before/after streaming. Always followed by `done` so the stream consumer's state-machine reaches a clean end."
+ stop_control: |
+ The Stop button. The CLIENT mints a `client_turn_id` (uuid4) and sends it
+ with the turn; `POST /chat/stop` takes that id and sets an asyncio.Event
+ the SSE driver loop races against `stream.__anext__()`.
+
+ Why a client-minted id rather than the server's `turn_id`: `_run_chat_turn`
+ runs its context fan-out (RAG + episodic + Honcho prefetch + briefing)
+ BEFORE constructing the StreamingResponse, so no header and no SSE byte —
+ and therefore no server-issued id — reaches the client for several seconds.
+ That is exactly the window where stopping is free, because the Executive
+ has not been asked for a first step and no model call has been made. A
+ client id is live from the moment Send is pressed and closes it.
+
+ The client id is NOT reused as the audit `turn_id`: that keeps its
+ server-minted `t-` + 12-hex shape, which audit queries filter on, and
+ letting a client choose an audit key is the thing `_clean_session_id`
+ exists to prevent. `_CLIENT_TURN_ID_RE` is deliberately narrower than
+ `_SESSION_ID_RE` (the value reaches log lines). A malformed id is DROPPED,
+ not rejected — it only means that turn is not stoppable, which is never a
+ reason to fail the turn.
+
+ Authorization: the registry stores an OWNER KEY, not the raw
+ `caller_person_id`. That id is None for a signed-in user not yet on the
+ People roster, for a fresh install with no principal, and on any transient
+ DB error during lookup — so comparing person ids directly would make every
+ such caller the owner of every other such caller's turn. `_stop_owner_key`
+ falls back person id -> verified email -> "local" (no caller header at all,
+ i.e. CLI/curl against a local API). The UI proxy strips client-sent
+ `x-caller-*` and re-stamps from the verified NextAuth session, so the email
+ cannot be spoofed. Unknown id and "not yours" both return 404, on purpose —
+ distinguishing them would make the endpoint an oracle for which turn ids
+ are live.
+
+ Registration is refused rather than forced on two conditions, and a refused
+ turn simply isn't stoppable (it always still runs): an id already held by a
+ live turn (overwriting would make the first turn unstoppable and point Stop
+ at the wrong one), and a full registry. At the cap the NEW turn is refused
+ rather than the oldest evicted — entries are popped when their turn ends,
+ so the oldest is typically a long-running live turn whose owner is the most
+ likely person to reach for Stop.
+
+ A malformed `client_turn_id` on /chat is DROPPED, never rejected: failing a
+ whole chat turn over an unstoppable id would be the wrong trade. On
+ /chat/stop the id *is* the payload, so a bad one is a 422.
+
+ How the work actually stops: the route cancels the pending `__anext__`
+ task and AWAITS it before touching the generator again (cancel() only
+ requests cancellation, and `aclose()` on a generator whose step is still
+ running raises RuntimeError). The CancelledError propagates into whatever
+ the Executive is awaiting — the Anthropic stream, a tool call, a specialist
+ gather — which is why executive.py re-raises CancelledError out of its
+ `gather(return_exceptions=True)` calls rather than treating it as a tool
+ failure.
+
+ `asyncio.wait` carries a duty `wait_for` used to discharge: it does NOT
+ cancel its futures when the task awaiting it is cancelled, and Starlette
+ cancels the SSE body on `http.disconnect`. `_next_stream_step` therefore
+ cancels the pending step in a `finally`, so a closed tab cannot leave
+ `__anext__` running a full specialist or tool round with no deadline, no
+ registry entry and no persistence. That `finally` is the load-bearing part
+ of the function; tests/unit/test_chat_stream_step.py pins it.
+
+ The route persists BEFORE emitting the terminal frames on every path,
+ including the stop: closing the tab in the gap between a `stopped` frame
+ and the write would lose the partial reply, which is the one thing the
+ feature exists to preserve. The first-turn session-title call (a Haiku
+ round-trip with a ~10s budget) is skipped on the stop path, so persisting
+ first does not make the button feel dead.
+
+ `_active_stops` is single-process, exactly like `_sessions` and
+ `_last_turn_*` in the same module and `_active_cancellations` in
+ api/routes/evals.py (the pattern this copies). A second uvicorn worker
+ would break in-flight session continuity before it broke stop. It is
+ bounded (`_STOP_REGISTRY_MAX`) so a leaked entry cannot grow without limit.
+
+ Two accepted consequences, by design rather than oversight:
+ - A stopped turn writes the inbound `chat_turn` audit row plus an
+ explicit outbound one marked `stopped`. The Executive's own outbound
+ row never happens, because it is cancelled before its post-turn block.
+ - A side-effecting tool cancelled mid-flight may already have fired (the
+ DM sent, the event booked) without emitting its `action_taken` chip.
+ Identical to the pre-existing whole-turn timeout behaviour.
+ - A stop landing before the Executive produces anything saves nothing —
+ not even the user message, since storing it alone would break the
+ user/assistant alternation the stored history relies on. The UI matches
+ that by taking the message back and returning its text to the composer
+ (unless files were attached, where silently dropping the selection
+ would be worse), so the live view and a reload agree.
+ - A stopped FIRST turn is renamed detached rather than inline. The rename
+ only ever runs on a first turn, and the stopped turn is part of the
+ history, so simply skipping it would leave the placeholder title
+ forever; awaiting it would add a ~10s Haiku round-trip to a stop.
+ - Stopping a COMMITTEE turn during its silent draft phase saves nothing.
+ `stream_chat_with_committee` accumulates the draft into a local and
+ never yields it (only the revised stream reaches the client), so
+ `full_response` is empty and `_persist_turn` returns on its empty
+ guard. The turn simply ends with no assistant message. The UI matches
+ this by not appending an empty bubble, so the live view and a reload
+ agree. Changing it means restructuring the draft phase.
+
+ The route also mirrors a broken-out turn into the live in-memory Session.
+ The Executive's post-turn block is skipped whenever its generator closes
+ early, and `_get_or_create_session` never re-reads history for a session it
+ already holds — so without this the NEXT turn would prompt as though the
+ stopped turn never happened while a page reload showed it. This applies to
+ the disconnect and timeout paths too, where it was a latent bug.
+
ask_oe_page_context: |
The Ask OE side panel (packages/ui/src/components/askoe/*, available on
every AppShell route — not `/`, which IS the chat) sends an optional
@@ -1790,6 +1898,18 @@ chat:
prefix, so conditional inclusion would invalidate the cache whenever
panel and non-panel turns alternate. Guarded by
tests/unit/test_executive_form_patch.py::test_tool_list_is_cache_stable_and_includes_form_tool.
+ persisted_message_fields: |
+ Two per-message fields survive a reload alongside the prose, both attached
+ by `load_messages` only when set so an untouched row keeps the exact dict
+ shape every consumer expects:
+ - `chat_messages.action_chips` — JSON list of the turn's action chips.
+ - `chat_messages.stopped` — 1 when the user halted the reply mid-stream,
+ so a truncated answer is not read back as a complete one. Additive
+ migration guarded by a PRAGMA check, same shape as action_chips.
+ Safe to ride along into `Session.conversation_history`: the Executive
+ rebuilds each history turn as {"role", "content"}, so neither key ever
+ reaches the Anthropic payload.
+
activity_labels: |
The in-flight progress line. `orchestrator/activity_labels.py` is the
sibling of `action_chips.py`: same tool -> phrase mapping, but
diff --git a/packages/core/openexecutive/architecture/prebuilt/api.json b/packages/core/openexecutive/architecture/prebuilt/api.json
index b0c65f86..e3715a46 100644
--- a/packages/core/openexecutive/architecture/prebuilt/api.json
+++ b/packages/core/openexecutive/architecture/prebuilt/api.json
@@ -1,7 +1,7 @@
{
"section_id": "api",
"title": "API Reference",
- "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). CORS is restricted to configured UI origins. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat` | SSE stream of a live Executive turn. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. Each round of tool calls also emits an `activity` event (`{type, label, tool, iteration}`) naming what is running — progress only, forwarded verbatim and never persisted with the message, unlike an `action_taken` chip. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}/messages` | List and read saved chat sessions. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive` | Roster CRUD and scope lookups. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. |\n| `agents` | `GET /agents`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `POST /artifacts/{id}/archive` | Browsable research/document artifacts. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. Reviewed in the briefing — there is no separate proposals page. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model, and by source — the part of the system that made the calls — including server-side web-search counts). |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes (unauthenticated). |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}` | Upload, list, view extracted text, and delete indexed company docs. Upload is keyed on the filename, so re-uploading a document replaces its chunks rather than duplicating them, and `DELETE` removes the rows as well as the file. `domain` must be one of the eight specialist domains or `general`; anything else is a 400 rather than a 200 that indexes where no specialist can retrieve. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. The run endpoint streams SSE; its `awaiting_human` event carries `delivery` (`self` \\| `sent` \\| `suppressed` \\| `alerted` \\| `failed`) alongside `person_id` / `question` / `awaiting_until`, because the outbound guard or an unreachable approver means the question may never have been asked — a client must not render “waiting on them” for those. A paused run ends the stream with neither `done` nor `error`, so that `awaiting_human` frame carries `terminal: true` to say so explicitly, plus `resumable` — whether the run continues by itself once answered or stops at the gate. `GET /workflows/runs/{run_id}` returns the run row with the resume payload replaced by a small `resume_progress` summary (`gate_step_id`, `completed_step_ids`, or `null`): the payload holds every completed step's full text, and the run-detail page polls this endpoint while a run is unfinished. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. `/search` is the introspection parallel of `retriever.retrieve` and mirrors its filters — including the `general` catch-all on the company collection — so the panel cannot report a specialist seeing nothing that it does retrieve in chat. It accepts `general` in `domain_filter` for the same reason. `/search` applies the same review gate as `retrieve()` — withheld (pending or rejected) built-in, external and failure rows are dropped, so the panel never advertises knowledge the Executive cannot use; it degrades to unfiltered rather than failing if review state is unreadable. `POST /knowledge/builtin` refuses a name already held by shipped content, and `POST|DELETE /knowledge/failures` now register and deregister for review — without that a user-authored failure case study had no review row, so no SME decision could block it. |\n| `skills` | `/skills`, `/skills/search` | Skill registry CRUD and search. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. |\n| `memories` | `/memories/{decisions,initiatives,advice}`, `GET /memories/people` | Episodic-memory record management, plus the read-only peer-memory overview the Pulse People tab reads (`{status: ok|disabled|error, people: [...], conclusion_total}`; `?recent=` 1–50, default 5). |\n| `review` | `/review/items`, `/review/stats`, `/review/trusted-defaults`, `POST /review/curate`, `POST /review/bulk-approve` | Knowledge review queue and annotations. Shipped knowledge registers as a trusted default (`approved` with a NULL `reviewed_at`), so the queue starts empty; `curate` (`{domain, action: start|stop}`, domain required) opts one domain in or out, and `trusted-defaults` returns domain → unreviewed count. `bulk-approve` takes a non-empty `domain`, `item_ids` (max 500) or `all_pending: true`, and 400s with no selector; it returns `{approved_count, item_ids}`. |\n| `onboarding` | `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Non-archived people with an email, offered to the UI's sign-in gate. The gate takes the **union** of this roster and its own `ALLOWED_EMAILS` env list, so env entries always work (and are checked first, short-circuiting the fetch) and roster entries are additive — a roster change can never revoke a configured operator. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |",
+ "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). CORS is restricted to configured UI origins. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat`, `POST /chat/stop` | SSE stream of a live Executive turn. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. Each round of tool calls also emits an `activity` event (`{type, label, tool, iteration}`) naming what is running — progress only, forwarded verbatim and never persisted with the message, unlike an `action_taken` chip. The client mints a `client_turn_id` and sends it with the turn; `POST /chat/stop` takes that id and halts the turn mid-flight, so the button is live from the moment Send is pressed rather than only once the first SSE byte arrives. A stopped turn emits a `stopped` event and then the usual `done` over the same still-open stream — never an `error` — and whatever streamed so far is persisted and flagged. The endpoint returns 404 both for an unknown id and for another caller's turn, so it cannot be used to probe which turns are live. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}/messages` | List and read saved chat sessions. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive` | Roster CRUD and scope lookups. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. |\n| `agents` | `GET /agents`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `POST /artifacts/{id}/archive` | Browsable research/document artifacts. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. Reviewed in the briefing — there is no separate proposals page. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model, and by source — the part of the system that made the calls — including server-side web-search counts). |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes (unauthenticated). |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}` | Upload, list, view extracted text, and delete indexed company docs. Upload is keyed on the filename, so re-uploading a document replaces its chunks rather than duplicating them, and `DELETE` removes the rows as well as the file. `domain` must be one of the eight specialist domains or `general`; anything else is a 400 rather than a 200 that indexes where no specialist can retrieve. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. The run endpoint streams SSE; its `awaiting_human` event carries `delivery` (`self` \\| `sent` \\| `suppressed` \\| `alerted` \\| `failed`) alongside `person_id` / `question` / `awaiting_until`, because the outbound guard or an unreachable approver means the question may never have been asked — a client must not render “waiting on them” for those. A paused run ends the stream with neither `done` nor `error`, so that `awaiting_human` frame carries `terminal: true` to say so explicitly, plus `resumable` — whether the run continues by itself once answered or stops at the gate. `GET /workflows/runs/{run_id}` returns the run row with the resume payload replaced by a small `resume_progress` summary (`gate_step_id`, `completed_step_ids`, or `null`): the payload holds every completed step's full text, and the run-detail page polls this endpoint while a run is unfinished. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. `/search` is the introspection parallel of `retriever.retrieve` and mirrors its filters — including the `general` catch-all on the company collection — so the panel cannot report a specialist seeing nothing that it does retrieve in chat. It accepts `general` in `domain_filter` for the same reason. `/search` applies the same review gate as `retrieve()` — withheld (pending or rejected) built-in, external and failure rows are dropped, so the panel never advertises knowledge the Executive cannot use; it degrades to unfiltered rather than failing if review state is unreadable. `POST /knowledge/builtin` refuses a name already held by shipped content, and `POST|DELETE /knowledge/failures` now register and deregister for review — without that a user-authored failure case study had no review row, so no SME decision could block it. |\n| `skills` | `/skills`, `/skills/search` | Skill registry CRUD and search. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. |\n| `memories` | `/memories/{decisions,initiatives,advice}`, `GET /memories/people` | Episodic-memory record management, plus the read-only peer-memory overview the Pulse People tab reads (`{status: ok|disabled|error, people: [...], conclusion_total}`; `?recent=` 1–50, default 5). |\n| `review` | `/review/items`, `/review/stats`, `/review/trusted-defaults`, `POST /review/curate`, `POST /review/bulk-approve` | Knowledge review queue and annotations. Shipped knowledge registers as a trusted default (`approved` with a NULL `reviewed_at`), so the queue starts empty; `curate` (`{domain, action: start|stop}`, domain required) opts one domain in or out, and `trusted-defaults` returns domain → unreviewed count. `bulk-approve` takes a non-empty `domain`, `item_ids` (max 500) or `all_pending: true`, and 400s with no selector; it returns `{approved_count, item_ids}`. |\n| `onboarding` | `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Non-archived people with an email, offered to the UI's sign-in gate. The gate takes the **union** of this roster and its own `ALLOWED_EMAILS` env list, so env entries always work (and are checked first, short-circuiting the fetch) and roster entries are additive — a roster change can never revoke a configured operator. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |",
"mermaid": null,
"generated_at": "2026-09-21T17:53:33Z"
}
diff --git a/packages/core/openexecutive/architecture/prebuilt/lifecycle.json b/packages/core/openexecutive/architecture/prebuilt/lifecycle.json
index fb3f3d02..1b885ecb 100644
--- a/packages/core/openexecutive/architecture/prebuilt/lifecycle.json
+++ b/packages/core/openexecutive/architecture/prebuilt/lifecycle.json
@@ -1,7 +1,7 @@
{
"section_id": "lifecycle",
"title": "Request Lifecycle",
- "markdown": "A single chat message makes a full round-trip through the API, the orchestrator's tool-use loop, a parallel specialist fan-out, and synthesis — all streamed back as server-sent events.\n\n### Steps\n\n1. **Arrival** — the client posts to `POST /chat` (`openexecutive.api.routes.chat`). The turn carries a `<current_speaker>` hint resolved from the caller's `person_id`, plus a `<briefing>` digest of current open alerts (built in parallel with RAG/episodic/peer-memory fetches) so the Executive can discuss any item shown on the `/today` briefing page A turn arriving from a chat adapter instead of the web app also carries a `<channel>` block naming the surface and stating which approvals can be completed there; on Slack the `<briefing>` digest is gated to the principal's DMs. All three ride in the **user turn**, never a cached system block.\n2. **Tool-use loop** — the `Executive` calls Claude. For a cross-domain question the assistant turn emits multiple `consult_specialist` tool-use blocks at once.\n3. **Parallel fan-out** — `openexecutive.orchestrator.router.route_parallel` dispatches those calls concurrently, bounded by `MAX_PARALLEL_SPECIALISTS`; calls past the cap get a skip tool_result.\n4. **Per-specialist RAG** — each specialist runs its own domain-filtered ChromaDB query, then reasons over the retrieved chunks and returns analysis as a tool_result.\n5. **Synthesis** — the Executive feeds the tool_results back to Claude and streams one coherent reply. Every tool round — not just a specialist one — emits an `activity` event naming what is running, immediately followed by a `thinking` keepalive. The label names the *activity*, never the internal agent: \"Putting time on the calendar…\", \"Looking up people…\", or, for an MCP call, the underlying tool by name. A round that really does fan out collapses to the generic \"Consulting specialists…\" — the one voice holds even in the progress line. The keepalive carries no tool information of its own; it used to drive a hardcoded \"Consulting specialists…\" string, so an MCP or calendar round misreported itself as a fan-out.\n6. **Optional committee review** — when enabled, `Executive.stream_chat_with_committee()` runs a silent draft, parallel reviewer critiques, then a streamed revision pass.\n7. **Side effects** — any side-effecting tool call surfaces an `action_taken` chip, which unlike the ephemeral `activity` label is persisted with the assistant message; the stream closes with a `done` event. One side-effecting tool is gated server-side rather than by its description: `ack_alert` will only accept an `alert_id` from the live alert board the server itself derived this turn — the whole live set, not only the rows the `<briefing>` digest printed, since `/today` renders more cards than the digest lists and every one of them is Discuss-able — and it fails closed, so an id it cannot even parse is refused rather than waved through to the handler's own parse. That check runs on **every** session. It used to run only on turns that arrived from a chat channel, keyed on `origin_channel`, which the browser never sets — so the web, the surface the principal actually uses, was unchecked and the model could ack any id, including one quoted out of an alert body by the briefing page's Discuss handoff. What that buys is bounded and worth stating plainly: an id that is invented, closed, snoozed or expired is refused, including one quoted out of an attacker-written alert body; the model being argued into acking the wrong *live* card is not prevented. The board is recorded on the turn's `Session`, and the route binds that session for the **whole** SSE body (`schedule_tools.set_session`, alongside `set_turn`) rather than letting `stream_chat` bind it from inside its own generator. `_sse_body` drives the executive with `asyncio.wait_for(stream.__anext__())`, which runs each step in a fresh Task holding a *copy* of the context, so a binding made inside the generator is discarded with the step that made it: step one sees the session and every later step sees `None`. The tool-call loop runs on those later steps, so the whole guard read an empty set and refused every ack on the web — on live, open cards — until the binding moved out to the route. Anything reading `current_session` mid-turn has the same requirement, and two of them needed more than the binding to behave. `schedule_followup`'s seen-`channel_ref` anti-spam gate refuses a send to an address the session has not seen; with no session it skipped itself, so a web turn could schedule to **any** address, and with an empty one it refused even the principal's own. The route now seeds the caller's own addresses onto the session, so on web the gate means what it means on every other surface. Reply linkage (`_record_outbound_context`, read back by `inbound_hydration` to quote the originating conversation into the turn handling a recipient's reply) is the other: it was never reachable on web, and rather than switch that on for the principal's broadest surface as a side effect it is held back, keyed on an explicit `Session.from_web_chat` flag. Not on an empty `origin_channel` — that names an inbound chat adapter, and the email poller, alert review, the CLI and the unattended workflows all leave it empty while legitimately recording linkage. `scheduled_actions` rows also take their `session_id` from the session. A session that was shown no board has an empty trusted set and can ack nothing, so the unattended passes (the nightly reflection, the research synthesis) are refused by default — they also still withhold the tool outright, which is belt-and-braces rather than the only thing stopping them. After the stream closes, the turn is also handed to the episodic memory extractor (`memory.episodic.schedule_extraction`, fire-and-forget) — on every turn where the principal said anything at all, and only the principal: a turn naming an `origin_channel` must resolve to a person marked `is_principal`, because the quote validator downstream cannot tell whose words it is checking. Both this path and the committee path call the same `should_extract` predicate, and it applies no length floor: the gate used to sum in the assistant's reply, which let a verbose answer drag a trivial turn in and discarded the short, decisive instructions that are the whole point of extracting. A user-side floor would fare no better — \"Do B.\" and \"Done\" are one character apart. See **Memory** for what that cost on a live tenant.\n8. **Tool failures** — a handler that raises instead of returning its JSON error is isolated: both tool gathers run with `return_exceptions=True`, the model gets an error `tool_result` naming only the exception's TYPE — a message can carry a filesystem path, a validation error echoing the input, or a third-party HTTP body, and anything in model context can be quoted back to the user, so the full repr stays in the log and the audit row — and the failure is audited with `ok=false`. Only `CancelledError` is re-raised, so turn-timeout and client-disconnect handling still work. Before this one crashing tool aborted the whole turn, which reached the user as an unexplained apology with no audit row (#136).\n\nWeb search, when invoked on the Anthropic path, executes inside the Anthropic API itself (`web_search_20250305`) and returns within the same generation; for any model routed via OpenRouter the same tool becomes OpenRouter's `openrouter:web_search` server tool, which also runs inside the generation with the same search cap and domain lists.",
+ "markdown": "A single chat message makes a full round-trip through the API, the orchestrator's tool-use loop, a parallel specialist fan-out, and synthesis — all streamed back as server-sent events.\n\n### Steps\n\n1. **Arrival** — the client mints a `client_turn_id` and posts to `POST /chat` (`openexecutive.api.routes.chat`). The turn carries a `<current_speaker>` hint resolved from the caller's `person_id`, plus a `<briefing>` digest of current open alerts (built in parallel with RAG/episodic/peer-memory fetches) so the Executive can discuss any item shown on the `/today` briefing page. A turn arriving from a chat adapter instead of the web app also carries a `<channel>` block naming the surface and stating which approvals can be completed there; on Slack the `<briefing>` digest is gated to the principal's DMs. All three ride in the **user turn**, never a cached system block. The server registers a stop switch under that id *before* the context fetch, so a Stop pressed during those first seconds halts the turn before any model call is made.\n2. **Tool-use loop** — the `Executive` calls Claude. For a cross-domain question the assistant turn emits multiple `consult_specialist` tool-use blocks at once.\n3. **Parallel fan-out** — `openexecutive.orchestrator.router.route_parallel` dispatches those calls concurrently, bounded by `MAX_PARALLEL_SPECIALISTS`; calls past the cap get a skip tool_result.\n4. **Per-specialist RAG** — each specialist runs its own domain-filtered ChromaDB query, then reasons over the retrieved chunks and returns analysis as a tool_result.\n5. **Synthesis** — the Executive feeds the tool_results back to Claude and streams one coherent reply. Every tool round — not just a specialist one — emits an `activity` event naming what is running, immediately followed by a `thinking` keepalive. The label names the *activity*, never the internal agent: \"Putting time on the calendar…\", \"Looking up people…\", or, for an MCP call, the underlying tool by name. A round that really does fan out collapses to the generic \"Consulting specialists…\" — the one voice holds even in the progress line. The keepalive carries no tool information of its own; it used to drive a hardcoded \"Consulting specialists…\" string, so an MCP or calendar round misreported itself as a fan-out.\n6. **Optional committee review** — when enabled, `Executive.stream_chat_with_committee()` runs a silent draft, parallel reviewer critiques, then a streamed revision pass.\n7. **Side effects** — any side-effecting tool call surfaces an `action_taken` chip, which unlike the ephemeral `activity` label is persisted with the assistant message; the stream closes with a `done` event — preceded by a `stopped` event when the user halted the turn, in which case the partial reply is still persisted and flagged so it reads as cut short rather than complete, and is mirrored into the live in-memory session so the next turn's prompt matches what was saved. The stream still ends with `done` event. One side-effecting tool is gated server-side rather than by its description: `ack_alert` will only accept an `alert_id` from the live alert board the server itself derived this turn — the whole live set, not only the rows the `<briefing>` digest printed, since `/today` renders more cards than the digest lists and every one of them is Discuss-able — and it fails closed, so an id it cannot even parse is refused rather than waved through to the handler's own parse. That check runs on **every** session. It used to run only on turns that arrived from a chat channel, keyed on `origin_channel`, which the browser never sets — so the web, the surface the principal actually uses, was unchecked and the model could ack any id, including one quoted out of an alert body by the briefing page's Discuss handoff. What that buys is bounded and worth stating plainly: an id that is invented, closed, snoozed or expired is refused, including one quoted out of an attacker-written alert body; the model being argued into acking the wrong *live* card is not prevented. The board is recorded on the turn's `Session`, and the route binds that session for the **whole** SSE body (`schedule_tools.set_session`, alongside `set_turn`) rather than letting `stream_chat` bind it from inside its own generator. `_sse_body` drives the executive with `asyncio.wait_for(stream.__anext__())`, which runs each step in a fresh Task holding a *copy* of the context, so a binding made inside the generator is discarded with the step that made it: step one sees the session and every later step sees `None`. The tool-call loop runs on those later steps, so the whole guard read an empty set and refused every ack on the web — on live, open cards — until the binding moved out to the route. Anything reading `current_session` mid-turn has the same requirement, and two of them needed more than the binding to behave. `schedule_followup`'s seen-`channel_ref` anti-spam gate refuses a send to an address the session has not seen; with no session it skipped itself, so a web turn could schedule to **any** address, and with an empty one it refused even the principal's own. The route now seeds the caller's own addresses onto the session, so on web the gate means what it means on every other surface. Reply linkage (`_record_outbound_context`, read back by `inbound_hydration` to quote the originating conversation into the turn handling a recipient's reply) is the other: it was never reachable on web, and rather than switch that on for the principal's broadest surface as a side effect it is held back, keyed on an explicit `Session.from_web_chat` flag. Not on an empty `origin_channel` — that names an inbound chat adapter, and the email poller, alert review, the CLI and the unattended workflows all leave it empty while legitimately recording linkage. `scheduled_actions` rows also take their `session_id` from the session. A session that was shown no board has an empty trusted set and can ack nothing, so the unattended passes (the nightly reflection, the research synthesis) are refused by default — they also still withhold the tool outright, which is belt-and-braces rather than the only thing stopping them. After the stream closes, the turn is also handed to the episodic memory extractor (`memory.episodic.schedule_extraction`, fire-and-forget) — on every turn where the principal said anything at all, and only the principal: a turn naming an `origin_channel` must resolve to a person marked `is_principal`, because the quote validator downstream cannot tell whose words it is checking. Both this path and the committee path call the same `should_extract` predicate, and it applies no length floor: the gate used to sum in the assistant's reply, which let a verbose answer drag a trivial turn in and discarded the short, decisive instructions that are the whole point of extracting. A user-side floor would fare no better — \"Do B.\" and \"Done\" are one character apart. See **Memory** for what that cost on a live tenant.\n8. **Tool failures** — a handler that raises instead of returning its JSON error is isolated: both tool gathers run with `return_exceptions=True`, the model gets an error `tool_result` naming only the exception's TYPE — a message can carry a filesystem path, a validation error echoing the input, or a third-party HTTP body, and anything in model context can be quoted back to the user, so the full repr stays in the log and the audit row — and the failure is audited with `ok=false`. Only `CancelledError` is re-raised, so turn-timeout and client-disconnect handling still work. Before this one crashing tool aborted the whole turn, which reached the user as an unexplained apology with no audit row (#136).\n\nWeb search, when invoked on the Anthropic path, executes inside the Anthropic API itself (`web_search_20250305`) and returns within the same generation; for any model routed via OpenRouter the same tool becomes OpenRouter's `openrouter:web_search` server tool, which also runs inside the generation with the same search cap and domain lists.",
"mermaid": "sequenceDiagram\n participant C as Client\n participant API as FastAPI /chat\n participant E as Executive\n participant CL as Claude\n participant S as Specialists\n participant KB as ChromaDB\n C->>API: POST /chat message\n API->>E: start turn\n E->>CL: messages (tool-use loop)\n CL-->>E: consult_specialist calls\n E->>S: route_parallel fan-out\n S->>KB: domain-filtered RAG\n KB-->>S: chunks\n S-->>E: analysis tool_results\n E->>CL: synthesize\n CL-->>E: streamed reply\n E-->>API: SSE chunks then done\n API-->>C: streamed response",
"generated_at": "2026-09-21T17:18:01.394900+00:00"
}
diff --git a/packages/core/openexecutive/config.py b/packages/core/openexecutive/config.py
index 6f843014..d3b72e9a 100644
--- a/packages/core/openexecutive/config.py
+++ b/packages/core/openexecutive/config.py
@@ -361,13 +361,25 @@ class Settings(BaseSettings):
# because hosted Honcho doesn't need an operator-set URL.
return self
- chat_stream_timeout_s: float = Field(120.0, alias="CHAT_STREAM_TIMEOUT_S")
+ # Whole-turn wall-clock ceiling for a streaming chat turn. Raised from 120s
+ # because deep multi-specialist turns were being cut off mid-answer. A
+ # ceiling this high is only tolerable because the user can end a turn
+ # themselves — see POST /chat/stop in api/routes/chat.py.
+ chat_stream_timeout_s: float = Field(300.0, alias="CHAT_STREAM_TIMEOUT_S")
# Extra wall-clock allowance added to chat_stream_timeout_s when a request
- # opts in to Committee review. Committee adds three reviewer calls + one
- # full-pass revision on top of the draft, typically 5–12s.
+ # opts in to Committee review (so 360s in total at the defaults). Committee
+ # adds three reviewer calls + one full-pass revision on top of the draft,
+ # typically 5–12s.
committee_extra_timeout_s: float = Field(60.0, alias="COMMITTEE_EXTRA_TIMEOUT_S")
+ # Per-call ceiling for the onboarding interview. It used to borrow
+ # chat_stream_timeout_s, which meant raising that to 300s would have let the
+ # wizard's 2-attempt retry loop hang for up to 600s before surfacing
+ # InterviewTimeout. Split out at its own former effective value so the
+ # wizard's behaviour is unchanged.
+ interview_timeout_s: float = Field(120.0, alias="INTERVIEW_TIMEOUT_S")
+
# Reasoning effort for deep-reasoning specialists (adaptive thinking +
# `output_config.effort`; translated to OpenRouter `reasoning.effort` on
# that path). Validated at boot: an invalid value used to 400 on Anthropic
diff --git a/packages/core/openexecutive/guide/prebuilt/chat.json b/packages/core/openexecutive/guide/prebuilt/chat.json
index 70e59b5a..48078ee2 100644
--- a/packages/core/openexecutive/guide/prebuilt/chat.json
+++ b/packages/core/openexecutive/guide/prebuilt/chat.json
@@ -1,7 +1,7 @@
{
"section_id": "chat",
"title": "Chat & Briefing",
- "markdown": "**What it is:** The home surface where you talk to the Executive in plain language. It opens on a *briefing* — a quick read of what's happened across the company — and you drop into a chat whenever you want to ask or decide something.\n\n**What it does:**\n\n- Hold a natural conversation with the Executive, which quietly pulls in whichever specialists a question needs.\n- Keep separate chat sessions with full history, so you can pick up where you left off.\n- Attach files to a message — up to 5 per turn, 20 MB each (images, PDF, Word, text, Markdown, CSV) — for the Executive to read alongside your knowledge base.\n- Toggle **Committee** on a question that matters: a slower pass where reviewers challenge the draft answer before you see it.\n- Continue any briefing item straight into a chat thread, with the context already filled in.\n- Open **Agent activity** in the top bar to watch what's happening behind a reply — which specialists were consulted and which tools ran.\n\n*Tip: this is the front door — almost everything else in the app is something the Executive references or acts on from here.*",
+ "markdown": "**What it is:** The home surface where you talk to the Executive in plain language. It opens on a *briefing* — a quick read of what's happened across the company — and you drop into a chat whenever you want to ask or decide something.\n\n**What it does:**\n\n- Hold a natural conversation with the Executive, which quietly pulls in whichever specialists a question needs.\n- Keep separate chat sessions with full history, so you can pick up where you left off.\n- Attach files to a message — up to 5 per turn, 20 MB each (images, PDF, Word, text, Markdown, CSV) — for the Executive to read alongside your knowledge base.\n- Stop a reply while it is still coming — whatever has been written is kept and marked *Stopped by you*, so you can redirect without waiting the answer out. (Escape works too.)\n- Toggle **Committee** on a question that matters: a slower pass where reviewers challenge the draft answer before you see it.\n- Continue any briefing item straight into a chat thread, with the context already filled in.\n- Open **Agent activity** in the top bar to watch what's happening behind a reply — which specialists were consulted and which tools ran.\n\n*Tip: this is the front door — almost everything else in the app is something the Executive references or acts on from here.*",
"mermaid": null,
"generated_at": "2026-06-11T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/memory/episodic.py b/packages/core/openexecutive/memory/episodic.py
index d907954e..a8d8c5f8 100644
--- a/packages/core/openexecutive/memory/episodic.py
+++ b/packages/core/openexecutive/memory/episodic.py
@@ -190,6 +190,7 @@ def initialize_db(db_path: Path = DB_PATH) -> None:
content TEXT NOT NULL,
created_at TEXT NOT NULL,
action_chips TEXT,
+ stopped INTEGER NOT NULL DEFAULT 0,
FOREIGN KEY (session_id) REFERENCES sessions(session_id)
);
CREATE TABLE IF NOT EXISTS scheduled_actions (
@@ -262,6 +263,19 @@ def initialize_db(db_path: Path = DB_PATH) -> None:
if "duplicate column" not in str(exc).lower():
raise
+ # Additive migration: flag an assistant message the user stopped
+ # mid-stream, so the "Stopped" marker survives a reload instead of a
+ # truncated reply reading as a complete one. Legacy rows default to 0.
+ if "stopped" not in _cm_existing:
+ try:
+ conn.execute(
+ "ALTER TABLE chat_messages "
+ "ADD COLUMN stopped INTEGER NOT NULL DEFAULT 0"
+ )
+ except sqlite3.OperationalError as exc:
+ if "duplicate column" not in str(exc).lower():
+ raise
+
# Phase 4 additive columns for scheduled_actions only.
_sa_existing = {
row["name"]
diff --git a/packages/core/openexecutive/memory/honcho_client.py b/packages/core/openexecutive/memory/honcho_client.py
index 46c792a6..0daadff7 100644
--- a/packages/core/openexecutive/memory/honcho_client.py
+++ b/packages/core/openexecutive/memory/honcho_client.py
@@ -1361,7 +1361,7 @@ async def directional_chat(
(which is capped at ``_PREFETCH_CEILING_S``) because the model
deliberately invoked this tool, but still a ceiling — without one a
Honcho hang would pin the entire tool-call loop until
- CHAT_STREAM_TIMEOUT_S fires (~2 min), starving every other tool
+ CHAT_STREAM_TIMEOUT_S fires (5 min by default), starving every other tool
call in the same turn.
"""
t0 = time.monotonic()
diff --git a/packages/core/openexecutive/memory/session_store.py b/packages/core/openexecutive/memory/session_store.py
index 283ff422..254d822f 100644
--- a/packages/core/openexecutive/memory/session_store.py
+++ b/packages/core/openexecutive/memory/session_store.py
@@ -51,17 +51,21 @@ def save_message(
content: str | list[dict[str, Any]],
db_path: Path = DB_PATH,
action_chips: str | None = None,
+ stopped: bool = False,
) -> None:
"""Persist one chat message. ``action_chips`` is a JSON-encoded list of the
assistant turn's action-chip dicts (or None), so reopening a saved session
- restores the ✓ tool-action pills instead of bare prose."""
+ restores the ✓ tool-action pills instead of bare prose. ``stopped`` marks an
+ assistant message the user halted mid-stream, so the reply is not read back
+ as a complete one."""
text = content if isinstance(content, str) else str(content)
now = datetime.now(UTC).isoformat()
with _get_conn(db_path) as conn:
conn.execute(
- "INSERT INTO chat_messages (session_id, role, content, created_at, action_chips) "
- "VALUES (?, ?, ?, ?, ?)",
- (session_id, role, text, now, action_chips),
+ "INSERT INTO chat_messages "
+ "(session_id, role, content, created_at, action_chips, stopped) "
+ "VALUES (?, ?, ?, ?, ?, ?)",
+ (session_id, role, text, now, action_chips, 1 if stopped else 0),
)
@@ -70,7 +74,7 @@ def load_messages(session_id: str, db_path: Path = DB_PATH) -> list[dict[str, An
return []
with _get_conn(db_path) as conn:
rows = conn.execute(
- "SELECT role, content, action_chips FROM chat_messages "
+ "SELECT role, content, action_chips, stopped FROM chat_messages "
"WHERE session_id = ? ORDER BY id",
(session_id,),
).fetchall()
@@ -85,6 +89,13 @@ def load_messages(session_id: str, db_path: Path = DB_PATH) -> list[dict[str, An
chips = None
if chips:
msg["actions"] = chips
+ # Attached only when true, like `actions` above, so untouched rows keep
+ # the exact dict shape every existing consumer expects. Safe to ride
+ # along into `Session.conversation_history`: the Executive rebuilds each
+ # history turn as {"role", "content"}, so extra keys never reach the
+ # Anthropic payload.
+ if row["stopped"]:
+ msg["stopped"] = True
out.append(msg)
return out
diff --git a/packages/core/openexecutive/onboarding/interview.py b/packages/core/openexecutive/onboarding/interview.py
index 82b96137..bd695797 100644
--- a/packages/core/openexecutive/onboarding/interview.py
+++ b/packages/core/openexecutive/onboarding/interview.py
@@ -569,7 +569,7 @@ async def advance(
for attempt in range(2):
try:
response = await asyncio.wait_for(
- _call(), timeout=settings.chat_stream_timeout_s
+ _call(), timeout=settings.interview_timeout_s
)
except TimeoutError as exc: # asyncio.TimeoutError is an alias since 3.11
raise InterviewTimeout(
diff --git a/packages/core/tests/unit/test_chat_route_persistence.py b/packages/core/tests/unit/test_chat_route_persistence.py
index a5356ab9..2ae9ac36 100644
--- a/packages/core/tests/unit/test_chat_route_persistence.py
+++ b/packages/core/tests/unit/test_chat_route_persistence.py
@@ -48,6 +48,7 @@ def _reset_route_state() -> None:
chat_route._sessions.clear()
chat_route._last_turn_events.clear()
chat_route._last_turn_meta.clear()
+ chat_route._active_stops.clear()
@pytest.fixture()
@@ -238,6 +239,18 @@ def test_chat_endpoint_persists_partial_turn_on_disconnect(
assert saved[0]["content"] == "explain our burn rate"
assert saved[1]["content"] == "partial answer"
+ # The live in-memory Session must agree with what was persisted. The
+ # Executive's own post-turn block is skipped when its generator is closed
+ # early, and `_get_or_create_session` never re-reads history for a session
+ # it already holds — so without the route mirroring the turn here, the NEXT
+ # turn in this process would prompt as though this one never happened while
+ # a page reload showed it.
+ session = chat_route._sessions[rows[0]["session_id"]]
+ assert session.conversation_history == [
+ {"role": "user", "content": "explain our burn rate"},
+ {"role": "assistant", "content": "partial answer"},
+ ]
+
def test_chat_endpoint_renames_session_after_first_turn(
temp_db: Path, patched_deps: None, monkeypatch: pytest.MonkeyPatch
diff --git a/packages/core/tests/unit/test_chat_route_stop.py b/packages/core/tests/unit/test_chat_route_stop.py
new file mode 100644
index 00000000..e6f01f0c
--- /dev/null
+++ b/packages/core/tests/unit/test_chat_route_stop.py
@@ -0,0 +1,533 @@
+"""Tests for stopping an in-flight chat turn (the Stop button).
+
+Covers the SSE side of `POST /chat/stop`:
+- A stop mid-stream terminates the turn with `stopped` then `done` (never
+ `error` — a stop is a user decision, not a failure).
+- The partial reply is persisted AND flagged, and lands in the live in-memory
+ Session so the next turn's prompt matches what was saved.
+- A stop that lands before the Executive produces anything persists nothing.
+- The registry entry is always released.
+- The whole-turn deadline still fires when a stop switch exists but is never
+ flipped (i.e. racing the stop waiter did not break `wait_for`'s semantics).
+
+Note on the harness: FastAPI's `TestClient` buffers the whole ASGI response
+before handing it back, so a *concurrent* stop request cannot be delivered
+mid-stream from the test thread. These tests instead flip the switch from
+inside the fake Executive's own generator, which exercises the same race and
+cancellation path deterministically. The endpoint's own contract (404s, caller
+matching) is covered in `test_chat_stop_endpoint.py`.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from openexecutive.api.routes import chat as chat_route
+from openexecutive.memory import episodic, session_store
+from openexecutive.memory.company_profile import CompanyProfile
+
+CLIENT_ID = "stop-me-0000-0001"
+
+
+def _all_sessions(db_path: Path) -> list[dict[str, Any]]:
+ with sqlite3.connect(db_path) as conn:
+ conn.row_factory = sqlite3.Row
+ rows = conn.execute(
+ """
+ SELECT s.session_id, COUNT(m.id) AS message_count
+ FROM sessions s
+ LEFT JOIN chat_messages m ON m.session_id = s.session_id
+ GROUP BY s.session_id
+ """,
+ ).fetchall()
+ return [dict(r) for r in rows]
+
+
+def _events(body: str) -> list[dict[str, Any]]:
+ """Parse the SSE body into the list of JSON payloads it carried."""
+ out: list[dict[str, Any]] = []
+ for line in body.splitlines():
+ if line.startswith("data: "):
+ out.append(json.loads(line[6:]))
+ return out
+
+
[email protected](autouse=True)
+def _reset_route_state() -> None:
+ chat_route._sessions.clear()
+ chat_route._last_turn_events.clear()
+ chat_route._last_turn_meta.clear()
+ chat_route._active_stops.clear()
+
+
+def temp_db(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ monkeypatch.chdir(tmp_path)
+ db_path = Path("./episodic_memory.db").resolve()
+ monkeypatch.setattr(episodic, "DB_PATH", db_path)
+ monkeypatch.setattr(session_store, "DB_PATH", db_path)
+ episodic.initialize_db(db_path)
+ return db_path
+
+
+def patched_deps(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key")
+
+ from openexecutive.onboarding import profile_builder
+
+ monkeypatch.setattr(
+ profile_builder, "load_or_create_profile", lambda: CompanyProfile()
+ )
+
+ from openexecutive.knowledge import retriever
+
+ monkeypatch.setattr(
+ retriever,
+ "retrieve",
+ lambda query, specialist_name=None, store=None: "",
+ )
+
+ from openexecutive.utils import session_title as _title_mod
+
+ async def _no_title(*_args: Any, **_kwargs: Any) -> None:
+ return None
+
+ monkeypatch.setattr(_title_mod, "generate_session_title", _no_title)
+
+ # The audit logger writes to the default ./episodic_memory.db unless the
+ # test isolates it; a stopped turn now emits an outbound row, so without
+ # this the rows leak into other modules' assertions on a full-suite run.
+ from openexecutive import audit
+
+ monkeypatch.setattr(audit, "log_event", lambda *a, **k: None)
+
+
+def _client() -> TestClient:
+ app = FastAPI()
+ app.include_router(chat_route.router)
+ return TestClient(app)
+
+
+def test_stop_mid_stream_ends_turn_and_keeps_partial(
+ temp_db: Path, patched_deps: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A stop after the first chunk ends the turn cleanly and keeps the text."""
+ from openexecutive.orchestrator import executive as exec_mod
+
+ class _StoppableExecutive:
+ _THINKING = exec_mod.Executive._THINKING
+
+ def __init__(self, **_kwargs: Any) -> None:
+ pass
+
+ async def stream_chat(self, **_kwargs: Any) -> Any:
+ yield "partial answer"
+ # Resumed by the route's anext task. Flip the switch, then block:
+ # the route's stop waiter must win the race and cancel this sleep.
+ # If cancellation is broken the test hangs here instead of
+ # finishing, which the elapsed-time assertion below catches.
+ chat_route._request_stop(CLIENT_ID, "local")
+ await asyncio.sleep(30)
+ yield "never reached"
+
+ monkeypatch.setattr(exec_mod, "Executive", _StoppableExecutive)
+
+ t0 = time.monotonic()
+ resp = _client().post(
+ "/chat", json={"message": "explain our burn rate", "client_turn_id": CLIENT_ID}
+ )
+ elapsed = time.monotonic() - t0
+
+ assert resp.status_code == 200
+ # The cancel must be immediate, not "eventually". 30s would mean the stop
+ # waiter never won and we simply drained the fake stream.
+ assert elapsed < 10, f"stop took {elapsed:.1f}s — cancellation is not working"
+
+ types = [e.get("type") for e in _events(resp.text)]
+ assert "stopped" in types
+ assert "done" in types
+ assert types.index("stopped") < types.index("done")
+ # A stop is not a timeout and not a failure.
+ assert "error" not in types
+
+ rows = _all_sessions(temp_db)
+ assert len(rows) == 1
+ assert rows[0]["message_count"] == 2 # user + partial assistant
+
+ saved = session_store.load_messages(rows[0]["session_id"])
+ assert [m["role"] for m in saved] == ["user", "assistant"]
+ assert saved[1]["content"] == "partial answer"
+ assert saved[1]["stopped"] is True
+ # The user turn is not a stopped message.
+ assert "stopped" not in saved[0]
+
+ # The live Session must agree with the DB, or the next turn in this process
+ # would prompt as though the stopped turn never happened.
+ session = chat_route._sessions[rows[0]["session_id"]]
+ assert session.conversation_history == [
+ {"role": "user", "content": "explain our burn rate"},
+ {"role": "assistant", "content": "partial answer"},
+ ]
+
+ # Registry released.
+ assert chat_route._active_stops == {}
+
+
+def test_stop_before_first_chunk_persists_nothing(
+ temp_db: Path, patched_deps: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A stop that lands before any output costs nothing and saves nothing.
+
+ This is the pre-stream window (the context fan-out): the Executive is never
+ asked for a first step, so no model call is ever made.
+ """
+ from openexecutive.orchestrator import executive as exec_mod
+
+ started = {"n": 0}
+
+ class _NeverRunExecutive:
+ _THINKING = exec_mod.Executive._THINKING
+
+ def __init__(self, **_kwargs: Any) -> None:
+ pass
+
+ async def stream_chat(self, **_kwargs: Any) -> Any:
+ started["n"] += 1
+ yield "should never be produced"
+
+ monkeypatch.setattr(exec_mod, "Executive", _NeverRunExecutive)
+
+ # Hand back an already-set event, simulating a stop that arrived while the
+ # route was still fetching context.
+ real_register = chat_route._register_stop
+
+ def _pre_set(client_turn_id: str, caller: Any, turn_id: str) -> asyncio.Event:
+ event = real_register(client_turn_id, caller, turn_id)
+ event.set()
+ return event
+
+ monkeypatch.setattr(chat_route, "_register_stop", _pre_set)
+
+ resp = _client().post(
+ "/chat", json={"message": "never mind", "client_turn_id": CLIENT_ID}
+ )
+ assert resp.status_code == 200
+
+ types = [e.get("type") for e in _events(resp.text)]
+ assert "stopped" in types
+ assert "done" in types
+ assert "chunk" not in types
+ assert started["n"] == 0, "the executive stream was driven despite a pre-set stop"
+
+ rows = _all_sessions(temp_db)
+ assert len(rows) == 1
+ # Nothing to save: no response text means no user/assistant pair, which
+ # keeps the stored history a clean alternation for the next turn.
+ assert rows[0]["message_count"] == 0
+ assert chat_route._active_stops == {}
+
+
+def test_normal_turn_is_unaffected_and_releases_registry(
+ temp_db: Path, patched_deps: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A turn that is never stopped behaves exactly as before."""
+ from openexecutive.orchestrator import executive as exec_mod
+
+ class _NormalExecutive:
+ _THINKING = exec_mod.Executive._THINKING
+
+ def __init__(self, **_kwargs: Any) -> None:
+ pass
+
+ async def stream_chat(self, **_kwargs: Any) -> Any:
+ yield "complete "
+ yield "answer"
+
+ monkeypatch.setattr(exec_mod, "Executive", _NormalExecutive)
+
+ resp = _client().post(
+ "/chat", json={"message": "hello", "client_turn_id": CLIENT_ID}
+ )
+ assert resp.status_code == 200
+
+ types = [e.get("type") for e in _events(resp.text)]
+ assert "stopped" not in types
+ assert "error" not in types
+ assert types[-1] == "done"
+
+ rows = _all_sessions(temp_db)
+ saved = session_store.load_messages(rows[0]["session_id"])
+ assert saved[1]["content"] == "complete answer"
+ # Not flagged, and the key is absent rather than False.
+ assert "stopped" not in saved[1]
+
+ # The Executive's own post-turn block owns the in-memory mirror on this
+ # path; the route must not double-append.
+ session = chat_route._sessions[rows[0]["session_id"]]
+ assert session.conversation_history == []
+
+ assert chat_route._active_stops == {}
+
+
+def test_turn_without_client_turn_id_still_streams(
+ temp_db: Path, patched_deps: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """An omitted or malformed id only means the turn isn't stoppable."""
+ from openexecutive.orchestrator import executive as exec_mod
+
+ class _NormalExecutive:
+ _THINKING = exec_mod.Executive._THINKING
+
+ def __init__(self, **_kwargs: Any) -> None:
+ pass
+
+ async def stream_chat(self, **_kwargs: Any) -> Any:
+ yield "fine"
+
+ monkeypatch.setattr(exec_mod, "Executive", _NormalExecutive)
+
+ resp = _client().post("/chat", json={"message": "hi"})
+ assert resp.status_code == 200
+ assert [e.get("type") for e in _events(resp.text)][-1] == "done"
+ assert chat_route._active_stops == {}
+
+
+def test_timeout_still_fires_with_an_unused_stop_waiter(
+ temp_db: Path, patched_deps: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The deadline must survive racing an unused stop waiter.
+
+ Regression guard for the `wait_for` → `asyncio.wait` rewrite: a stop switch
+ that is registered but never flipped must not swallow the whole-turn
+ deadline.
+ """
+ from openexecutive.config import Settings
+ from openexecutive.orchestrator import executive as exec_mod
+
+ class _HangingExecutive:
+ _THINKING = exec_mod.Executive._THINKING
+
+ def __init__(self, **_kwargs: Any) -> None:
+ pass
+
+ async def stream_chat(self, **_kwargs: Any) -> Any:
+ yield "started"
+ await asyncio.sleep(30)
+ yield "never"
+
+ monkeypatch.setattr(exec_mod, "Executive", _HangingExecutive)
+
+ class _FastTimeout(Settings):
+ def __init__(self, **kw: Any) -> None:
+ super().__init__(**kw)
+ object.__setattr__(self, "chat_stream_timeout_s", 0.2)
+
+ from openexecutive import config as config_mod
+
+ monkeypatch.setattr(config_mod, "get_settings", lambda: _FastTimeout())
+ monkeypatch.setattr(chat_route, "get_settings", _FastTimeout, raising=False)
+
+ t0 = time.monotonic()
+ resp = _client().post(
+ "/chat", json={"message": "hang please", "client_turn_id": CLIENT_ID}
+ )
+ elapsed = time.monotonic() - t0
+
+ assert resp.status_code == 200
+ assert elapsed < 10, "the deadline did not fire — the stop waiter swallowed it"
+
+ events = _events(resp.text)
+ types = [e.get("type") for e in events]
+ assert "error" in types
+ assert "stopped" not in types
+ assert types[-1] == "done"
+ assert chat_route._active_stops == {}
+
+
+def test_item_produced_in_the_same_tick_as_the_stop_is_not_dropped(
+ temp_db: Path, patched_deps: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A tie between the stop waiter and a produced item must favour the item.
+
+ Both futures can complete in the same tick. Branching on the stop first
+ would silently discard work already paid for — and an `action_taken` dict
+ dropped here never reaches the chips persisted with the message, so the
+ user loses the record of a side effect that really happened.
+ """
+ from openexecutive.orchestrator import executive as exec_mod
+
+ class _ChipThenStopExecutive:
+ _THINKING = exec_mod.Executive._THINKING
+
+ def __init__(self, **_kwargs: Any) -> None:
+ pass
+
+ async def stream_chat(self, **_kwargs: Any) -> Any:
+ yield "sending the note"
+ # Stop lands BEFORE the chip is yielded, so by the time the route's
+ # `asyncio.wait` returns, both the item and the stop waiter are
+ # ready. The chip must still be delivered and persisted.
+ chat_route._request_stop(CLIENT_ID, "local")
+ yield {
+ "type": "action_taken",
+ "tool": "send_dm",
+ "summary": "DM sent to Priya",
+ }
+ await asyncio.sleep(30)
+
+ monkeypatch.setattr(exec_mod, "Executive", _ChipThenStopExecutive)
+
+ t0 = time.monotonic()
+ resp = _client().post(
+ "/chat", json={"message": "tell priya", "client_turn_id": CLIENT_ID}
+ )
+ assert time.monotonic() - t0 < 10
+
+ types = [e.get("type") for e in _events(resp.text)]
+ assert "action_taken" in types, "the chip was dropped by the stop"
+ assert "stopped" in types
+ assert types.index("action_taken") < types.index("stopped")
+
+ rows = _all_sessions(temp_db)
+ saved = session_store.load_messages(rows[0]["session_id"])
+ assert saved[1]["stopped"] is True
+ # And it survived into the persisted chips, not just the live stream.
+ assert saved[1]["actions"] == [
+ {"type": "action_taken", "tool": "send_dm", "summary": "DM sent to Priya"}
+ ]
+
+
+def test_partial_is_persisted_before_the_stopped_frame_goes_out(
+ temp_db: Path, patched_deps: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """Persist must precede the terminal frames on the stop path.
+
+ Yielding `stopped` first opens a gap in which closing the tab loses the
+ partial reply — the one thing the feature exists to preserve. Asserted by
+ recording the DB row count at the moment the `stopped` frame is written.
+ """
+ from openexecutive.memory import session_store as store_mod
+ from openexecutive.orchestrator import executive as exec_mod
+
+ class _StoppableExecutive:
+ _THINKING = exec_mod.Executive._THINKING
+
+ def __init__(self, **_kwargs: Any) -> None:
+ pass
+
+ async def stream_chat(self, **_kwargs: Any) -> Any:
+ yield "partial answer"
+ chat_route._request_stop(CLIENT_ID, "local")
+ await asyncio.sleep(30)
+
+ monkeypatch.setattr(exec_mod, "Executive", _StoppableExecutive)
+
+ saved_before_frame: list[int] = []
+ real_save = store_mod.save_message
+ order: list[str] = []
+
+ def _tracking_save(*a: Any, **k: Any) -> Any:
+ order.append("save")
+ return real_save(*a, **k)
+
+ monkeypatch.setattr(store_mod, "save_message", _tracking_save)
+
+ resp = _client().post(
+ "/chat", json={"message": "burn rate?", "client_turn_id": CLIENT_ID}
+ )
+ body = resp.text
+ for line in body.splitlines():
+ if '"stopped"' in line:
+ saved_before_frame.append(len(order))
+ break
+
+ # Both rows (user + assistant) are written before the stopped frame.
+ assert saved_before_frame == [2], (
+ f"expected 2 saves before the stopped frame, saw {saved_before_frame}"
+ )
+
+
+def test_stopped_first_turn_renames_without_blocking_the_stream(
+ temp_db: Path, patched_deps: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The rename must not hold the stream open, but must still happen.
+
+ It is a Haiku round-trip with a ~10s budget, so awaiting it on the stop
+ path would make the button slower than the stop it reports. Skipping it
+ outright is not an option either: the rename only ever runs on a first
+ turn, and the stopped turn is now part of the history, so turn 2 would not
+ be a first turn and the placeholder title would stick forever.
+ """
+ from openexecutive.orchestrator import executive as exec_mod
+ from openexecutive.utils import session_title as title_mod
+
+ started = asyncio.Event()
+ release = asyncio.Event()
+
+ async def _slow_title(*_a: Any, **_k: Any) -> str:
+ started.set()
+ await release.wait()
+ return "Generated Title"
+
+ monkeypatch.setattr(title_mod, "generate_session_title", _slow_title)
+
+ class _StoppableExecutive:
+ _THINKING = exec_mod.Executive._THINKING
+
+ def __init__(self, **_kwargs: Any) -> None:
+ pass
+
+ async def stream_chat(self, **_kwargs: Any) -> Any:
+ yield "partial"
+ chat_route._request_stop(CLIENT_ID, "local")
+ await asyncio.sleep(30)
+
+ monkeypatch.setattr(exec_mod, "Executive", _StoppableExecutive)
+
+ t0 = time.monotonic()
+ resp = _client().post(
+ "/chat", json={"message": "hello there", "client_turn_id": CLIENT_ID}
+ )
+ elapsed = time.monotonic() - t0
+
+ assert resp.status_code == 200
+ # The stream closed without waiting on the (still-blocked) title call.
+ assert elapsed < 10, f"the stream waited on the rename ({elapsed:.1f}s)"
+ assert '"type": "done"' in resp.text
+ # ...but the rename was dispatched rather than dropped.
+ assert started.is_set(), "the stopped first turn never attempted a rename"
+ release.set()
+
+
+def test_registry_is_released_when_the_session_load_fails(
+ temp_db: Path, patched_deps: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A failure between registration and the streaming body must not strand
+ the entry.
+
+ `_sse_body`'s `finally` only runs once Starlette consumes the generator, so
+ anything raising before that has to release the switch itself. Stranded
+ entries are effectively permanent — the registry refuses new turns at its
+ cap rather than evicting live ones — so enough of them would take Stop away
+ from everybody until a restart.
+ """
+ def _boom(*_a: Any, **_k: Any) -> Any:
+ raise RuntimeError("profile.yaml no longer parses")
+
+ monkeypatch.setattr(chat_route, "_get_or_create_session", _boom)
+
+ with pytest.raises(RuntimeError):
+ _client().post(
+ "/chat", json={"message": "hi", "client_turn_id": CLIENT_ID}
+ )
+
+ assert chat_route._active_stops == {}, "the stop entry was stranded"
diff --git a/packages/core/tests/unit/test_chat_route_timeout.py b/packages/core/tests/unit/test_chat_route_timeout.py
index 830610f8..3d14d2ac 100644
--- a/packages/core/tests/unit/test_chat_route_timeout.py
+++ b/packages/core/tests/unit/test_chat_route_timeout.py
@@ -38,6 +38,7 @@ def _reset_route_state() -> None:
chat_route._sessions.clear()
chat_route._last_turn_events.clear()
chat_route._last_turn_meta.clear()
+ chat_route._active_stops.clear()
@pytest.fixture()
diff --git a/packages/core/tests/unit/test_chat_stop_endpoint.py b/packages/core/tests/unit/test_chat_stop_endpoint.py
new file mode 100644
index 00000000..18e7ee15
--- /dev/null
+++ b/packages/core/tests/unit/test_chat_stop_endpoint.py
@@ -0,0 +1,262 @@
+"""Contract tests for `POST /chat/stop`.
+
+These drive the endpoint directly against a hand-seeded registry, so they need
+no streaming turn. The SSE side — what a flipped switch actually does to a live
+turn — is covered in `test_chat_route_stop.py`.
+
+The security property under test: an unknown id and someone else's id must be
+indistinguishable (both 404), or the endpoint becomes an oracle for which turn
+ids are currently live.
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from openexecutive.api.routes import chat as chat_route
+
+
[email protected](autouse=True)
+def _reset_registry() -> None:
+ chat_route._active_stops.clear()
+ yield
+ chat_route._active_stops.clear()
+
+
+def client() -> TestClient:
+ app = FastAPI()
+ app.include_router(chat_route.router)
+ return TestClient(app)
+
+
[email protected](autouse=True)
+def _caller(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Resolve every request to person 7 unless a test overrides it."""
+ monkeypatch.setattr(chat_route, "_resolve_caller_person_id", lambda _r: 7)
+
+
+def _seed(client_turn_id: str, owner: str) -> asyncio.Event:
+ event = asyncio.Event()
+ chat_route._active_stops[client_turn_id] = chat_route._StopEntry(
+ event, owner, "t-abc123456789", time.monotonic()
+ )
+ return event
+
+
+def test_stop_sets_the_event_for_the_owner(client: TestClient) -> None:
+ event = _seed("live-turn-0001", "person:7")
+
+ resp = client.post("/chat/stop", json={"client_turn_id": "live-turn-0001"})
+
+ assert resp.status_code == 200
+ assert resp.json() == {"status": "stopping", "turn_id": "t-abc123456789"}
+ assert event.is_set()
+
+
+def test_unknown_id_is_404(client: TestClient) -> None:
+ resp = client.post("/chat/stop", json={"client_turn_id": "no-such-turn-1"})
+ assert resp.status_code == 404
+
+
+def test_another_callers_turn_is_404_and_keeps_running(client: TestClient) -> None:
+ """Someone else's live turn must look exactly like a turn that never
+ existed — and must not actually be stopped."""
+ event = _seed("someone-elses-1", "person:99")
+
+ resp = client.post("/chat/stop", json={"client_turn_id": "someone-elses-1"})
+
+ assert resp.status_code == 404
+ # Indistinguishable from the unknown-id case above.
+ assert resp.json()["detail"] == "No in-flight turn with that id"
+ assert not event.is_set(), "the victim's turn was stopped"
+
+
+def test_local_caller_owns_local_turns(
+ client: TestClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """No roster id and no caller header — CLI / direct curl against a local
+ API, where there is no identity to separate."""
+ monkeypatch.setattr(chat_route, "_resolve_caller_person_id", lambda _r: None)
+ event = _seed("anon-turn-0001", "local")
+
+ resp = client.post("/chat/stop", json={"client_turn_id": "anon-turn-0001"})
+
+ assert resp.status_code == 200
+ assert event.is_set()
+
+
+def test_unrostered_users_do_not_share_ownership(
+ client: TestClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """Two signed-in users who are not on the People roster both resolve to
+ person_id None. They must NOT therefore own each other's turns — the owner
+ key falls back to the verified email, which the UI proxy stamps from the
+ session and strips from client input."""
+ monkeypatch.setattr(chat_route, "_resolve_caller_person_id", lambda _r: None)
+ victim = _seed("victims-turn-01", "email:[email protected]")
+
+ resp = client.post(
+ "/chat/stop",
+ json={"client_turn_id": "victims-turn-01"},
+ headers={"x-caller-email": "[email protected]"},
+ )
+
+ assert resp.status_code == 404
+ assert not victim.is_set(), "an unrostered user stopped another user's turn"
+
+ # ...and the real owner still can.
+ ok = client.post(
+ "/chat/stop",
+ json={"client_turn_id": "victims-turn-01"},
+ headers={"x-caller-email": "[email protected]"}, # case-insensitive
+ )
+ assert ok.status_code == 200
+ assert victim.is_set()
+
+
+def test_unrostered_caller_cannot_stop_a_rostered_turn(
+ client: TestClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.setattr(chat_route, "_resolve_caller_person_id", lambda _r: None)
+ event = _seed("owned-turn-0001", "person:7")
+
+ resp = client.post("/chat/stop", json={"client_turn_id": "owned-turn-0001"})
+
+ assert resp.status_code == 404
+ assert not event.is_set()
+
+
+ "bad",
+ [
+ "short", # under min_length
+ "has space in it",
+ "has_underscore_x",
+ "newline\ninjection",
+ "trailing-newline\n",
+ "x" * 65, # over max_length
+ ],
+)
+def test_malformed_ids_are_rejected_at_the_edge(client: TestClient, bad: str) -> None:
+ """On /chat/stop the id IS the payload, so a bad one is a bad request.
+
+ (On /chat it is only dropped — failing a whole chat turn over an
+ unstoppable id would be the wrong trade.)
+ """
+ resp = client.post("/chat/stop", json={"client_turn_id": bad})
+ assert resp.status_code == 422
+
+
+def test_clean_client_turn_id_drops_rather_than_raises() -> None:
+ """The /chat side drops a bad id: it only means the turn isn't stoppable,
+ which is never a reason to fail the turn itself."""
+ assert chat_route._clean_client_turn_id(None) is None
+ assert chat_route._clean_client_turn_id("bad id") is None
+ assert chat_route._clean_client_turn_id("tiny") is None
+ # `$` would match before a trailing newline; the regex uses `\Z`.
+ assert chat_route._clean_client_turn_id("aaaaaaaa\n") is None
+ ok = "3f2b9c1a-0000-4000-8000-abcdefabcdef"
+ assert chat_route._clean_client_turn_id(ok) == ok
+
+
+def test_registry_is_bounded_by_refusing_new_turns(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """At the cap, new turns are refused rather than old ones evicted.
+
+ Entries are popped when their turn ends, so the oldest entry is typically a
+ long-running LIVE turn. Evicting it would silently take the Stop button
+ away from the person most likely to be reaching for it.
+ """
+ monkeypatch.setattr(chat_route, "_STOP_REGISTRY_MAX", 4)
+
+ events = [
+ chat_route._register_stop(f"turn-{i:08d}", "person:7", f"t-{i:012d}")
+ for i in range(6)
+ ]
+
+ assert len(chat_route._active_stops) == 4
+ # The first four registered; the last two were refused, not swapped in.
+ assert all(e is not None for e in events[:4])
+ assert events[4] is None and events[5] is None
+ assert "turn-00000000" in chat_route._active_stops
+ assert "turn-00000005" not in chat_route._active_stops
+
+
+def test_duplicate_client_turn_id_is_refused(monkeypatch: pytest.MonkeyPatch) -> None:
+ """A second turn reusing a live id must not hijack the first one's switch."""
+ first = chat_route._register_stop("shared-id-0001", "person:7", "t-first00000")
+ second = chat_route._register_stop("shared-id-0001", "person:7", "t-second0000")
+
+ assert first is not None
+ assert second is None, "the second turn overwrote the first turn's entry"
+ # Stop still reaches the turn that actually owns the id.
+ assert chat_route._request_stop("shared-id-0001", "person:7") == "t-first00000"
+ assert first.is_set()
+
+
+def test_release_ignores_an_entry_owned_by_another_turn() -> None:
+ """The refused second turn must not pop the first turn's entry when it
+ finishes."""
+ chat_route._register_stop("shared-id-0002", "person:7", "t-first00000")
+
+ chat_route._release_stop("shared-id-0002", "t-second0000")
+ assert "shared-id-0002" in chat_route._active_stops
+
+ chat_route._release_stop("shared-id-0002", "t-first00000")
+ assert "shared-id-0002" not in chat_route._active_stops
+
+
+def test_release_is_idempotent_and_ignores_none() -> None:
+ _seed("live-turn-0002", "person:7")
+ chat_route._release_stop("live-turn-0002")
+ chat_route._release_stop("live-turn-0002")
+ chat_route._release_stop(None)
+ assert chat_route._active_stops == {}
+
+
+def test_request_stop_on_empty_registry_returns_none() -> None:
+ assert chat_route._request_stop("live-turn-0003", "person:7") is None
+
+
+def test_stop_endpoint_does_not_echo_the_client_id(client: TestClient) -> None:
+ """The 404 body must not reflect the submitted id back to the caller."""
+ resp = client.post("/chat/stop", json={"client_turn_id": "probe-id-0001"})
+ assert resp.status_code == 404
+ assert "probe-id-0001" not in resp.text
+
+
+def test_stale_entries_are_reclaimed_on_registration() -> None:
+ """A stranded entry must not hold its slot forever.
+
+ Entries are normally popped when the turn ends. Since a full registry now
+ refuses NEW turns rather than evicting live ones, an entry stranded by a
+ path that never reaches that cleanup would otherwise deny somebody a Stop
+ button permanently.
+ """
+ stale_event = asyncio.Event()
+ chat_route._active_stops["stranded-000001"] = chat_route._StopEntry(
+ stale_event, "person:7", "t-stranded000", time.monotonic() - 100_000
+ )
+ fresh = _seed("fresh-turn-0001", "person:7")
+
+ assert chat_route._register_stop("new-turn-00001", "person:7", "t-new00000000")
+
+ assert "stranded-000001" not in chat_route._active_stops
+ # A live entry registered moments ago is untouched.
+ assert "fresh-turn-0001" in chat_route._active_stops
+ assert not fresh.is_set()
+
+
+def test_a_stale_entry_does_not_block_reusing_its_id() -> None:
+ chat_route._active_stops["recycled-00001"] = chat_route._StopEntry(
+ asyncio.Event(), "person:7", "t-old00000000", time.monotonic() - 100_000
+ )
+ event = chat_route._register_stop("recycled-00001", "person:7", "t-new00000000")
+ assert event is not None
+ assert chat_route._active_stops["recycled-00001"].turn_id == "t-new00000000"
diff --git a/packages/core/tests/unit/test_chat_stream_step.py b/packages/core/tests/unit/test_chat_stream_step.py
new file mode 100644
index 00000000..c6848172
--- /dev/null
+++ b/packages/core/tests/unit/test_chat_stream_step.py
@@ -0,0 +1,214 @@
+"""Direct tests for `_next_stream_step`, the SSE driver's one-step race.
+
+This is the most delicate code in the stop feature: it races a produced item
+against the stop switch and the whole-turn deadline, and the ordering matters
+in three independent ways (don't drop a produced item; await a cancellation
+before touching the generator; keep the deadline working). Testing it on its
+own — rather than only through a full ASGI turn — makes each rule fail loudly
+and in isolation.
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+import pytest
+
+from openexecutive.api.routes.chat import _next_stream_step
+
+
+def _waiter(event: asyncio.Event) -> asyncio.Task[bool]:
+ return asyncio.ensure_future(event.wait())
+
+
+async def _drain(task: asyncio.Task[Any] | None) -> None:
+ if task is not None and not task.done():
+ task.cancel()
+
+
+async def test_produced_item_is_returned() -> None:
+ async def gen() -> Any:
+ yield "hello"
+
+ step = await _next_stream_step(gen().__aiter__(), None, 5.0, "t-1")
+ assert step.produced is True
+ assert step.item == "hello"
+ assert not step.stopped and not step.timed_out and not step.exhausted
+
+
+async def test_exhausted_stream_is_reported() -> None:
+ async def gen() -> Any:
+ return
+ yield # pragma: no cover - unreachable; makes this an async generator
+
+ step = await _next_stream_step(gen().__aiter__(), None, 5.0, "t-2")
+ assert step.exhausted is True
+ assert step.produced is False
+
+
+async def test_stop_cancels_a_hanging_step() -> None:
+ """The whole point: a set switch must cut a step that would never finish."""
+ cancelled = {"seen": False}
+
+ async def gen() -> Any:
+ try:
+ await asyncio.sleep(30)
+ yield "never"
+ except asyncio.CancelledError:
+ cancelled["seen"] = True
+ raise
+
+ event = asyncio.Event()
+ waiter = _waiter(event)
+ stream = gen().__aiter__()
+
+ async def flip() -> None:
+ await asyncio.sleep(0.05)
+ event.set()
+
+ asyncio.ensure_future(flip())
+ t0 = time.monotonic()
+ step = await _next_stream_step(stream, waiter, 30.0, "t-3")
+ elapsed = time.monotonic() - t0
+
+ assert step.stopped is True
+ assert step.produced is False
+ assert elapsed < 5, "the step was not cancelled promptly"
+ # The cancellation really reached the generator — this is what stops the
+ # Executive's in-flight Anthropic call / tool gather.
+ assert cancelled["seen"] is True
+ await _drain(waiter)
+
+
+async def test_an_already_set_stop_still_returns_a_ready_item() -> None:
+ """A tie must favour the item: it is already paid for, and an
+ `action_taken` dropped here never reaches the persisted chips."""
+ async def gen() -> Any:
+ yield {"type": "action_taken", "tool": "send_dm"}
+
+ event = asyncio.Event()
+ event.set()
+ waiter = _waiter(event)
+
+ step = await _next_stream_step(gen().__aiter__(), waiter, 5.0, "t-4")
+ assert step.produced is True
+ assert step.item == {"type": "action_taken", "tool": "send_dm"}
+ assert step.stopped is False
+ await _drain(waiter)
+
+
+async def test_deadline_still_fires_without_a_stop_switch() -> None:
+ async def gen() -> Any:
+ await asyncio.sleep(30)
+ yield "never"
+
+ t0 = time.monotonic()
+ step = await _next_stream_step(gen().__aiter__(), None, 0.1, "t-5")
+ assert step.timed_out is True
+ assert time.monotonic() - t0 < 5
+
+
+async def test_deadline_still_fires_with_an_unset_stop_switch() -> None:
+ """Regression guard for the wait_for -> asyncio.wait rewrite: a registered
+ but never-flipped switch must not swallow the deadline."""
+ async def gen() -> Any:
+ await asyncio.sleep(30)
+ yield "never"
+
+ waiter = _waiter(asyncio.Event())
+ step = await _next_stream_step(gen().__aiter__(), waiter, 0.1, "t-6")
+ assert step.timed_out is True
+ assert step.stopped is False
+ await _drain(waiter)
+
+
+async def test_generator_is_closeable_after_a_stop() -> None:
+ """`aclose()` must not raise "asynchronous generator is already running".
+
+ That is what happens if the cancelled step is not awaited before the
+ caller's best-effort `aclose()` runs.
+ """
+ async def gen() -> Any:
+ await asyncio.sleep(30)
+ yield "never"
+
+ event = asyncio.Event()
+ event.set()
+ waiter = _waiter(event)
+ stream = gen().__aiter__()
+
+ step = await _next_stream_step(stream, waiter, 5.0, "t-7")
+ assert step.stopped is True
+ # The caller does exactly this next.
+ await stream.aclose()
+ await _drain(waiter)
+
+
+async def test_a_raising_step_does_not_escape() -> None:
+ """A generator that fails during its cancellation unwind is logged, not
+ propagated — the turn still has a partial reply to persist."""
+ async def gen() -> Any:
+ try:
+ await asyncio.sleep(30)
+ except asyncio.CancelledError:
+ raise RuntimeError("cleanup blew up") from None
+ yield "never"
+
+ event = asyncio.Event()
+ event.set()
+ waiter = _waiter(event)
+
+ step = await _next_stream_step(gen().__aiter__(), waiter, 5.0, "t-8")
+ assert step.stopped is True
+ await _drain(waiter)
+
+
+async def test_outer_cancellation_does_not_orphan_the_step() -> None:
+ """A client disconnect must not leave the Executive running.
+
+ Regression guard for the `wait_for` -> `asyncio.wait` rewrite.
+ `asyncio.wait_for` cancels its inner task when the task awaiting it is
+ cancelled; `asyncio.wait` does NOT. Starlette cancels the whole SSE body on
+ `http.disconnect`, so without the `finally` in `_next_stream_step` a closed
+ tab would leave `__anext__` running a full specialist or tool round with no
+ deadline, no registry entry and no persistence — i.e. unbounded work per
+ abandoned request.
+ """
+ state = {"phase": "init"}
+
+ async def gen() -> Any:
+ try:
+ state["phase"] = "running"
+ await asyncio.sleep(5)
+ state["phase"] = "completed-anyway"
+ yield "late"
+ except asyncio.CancelledError:
+ state["phase"] = "cancelled"
+ raise
+
+ stream = gen().__aiter__()
+ task = asyncio.ensure_future(_next_stream_step(stream, None, 30.0, "t-9"))
+ await asyncio.sleep(0.05)
+
+ task.cancel() # <- what Starlette does on http.disconnect
+ with pytest.raises(asyncio.CancelledError):
+ await task
+
+ assert state["phase"] == "cancelled", (
+ "the executive step was orphaned by the outer cancellation and kept "
+ f"running (phase={state['phase']!r})"
+ )
+
+ # And it stays cancelled — it must not resume and finish its round later.
+ await asyncio.sleep(0.2)
+ assert state["phase"] == "cancelled"
diff --git a/packages/core/tests/unit/test_config_timeouts.py b/packages/core/tests/unit/test_config_timeouts.py
new file mode 100644
index 00000000..f3553a13
--- /dev/null
+++ b/packages/core/tests/unit/test_config_timeouts.py
@@ -0,0 +1,47 @@
+"""Shipped defaults for the chat-turn timeouts.
+
+These pin the numbers themselves, which the other timeout tests deliberately
+do not: they inject short values via `object.__setattr__` to exercise the
+deadline path, so a silent change to the defaults would not fail anything.
+"""
+from __future__ import annotations
+
+import pytest
+
+from openexecutive.config import Settings
+
+
[email protected](autouse=True)
+def _required_env(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key")
+ monkeypatch.setenv("EXEC_EMAIL_ADDRESS", "[email protected]")
+
+
+def test_chat_turn_ceiling_defaults() -> None:
+ s = Settings(_env_file=None)
+ assert s.chat_stream_timeout_s == 300.0
+ assert s.committee_extra_timeout_s == 60.0
+ # The route sums them for a Committee turn.
+ assert s.chat_stream_timeout_s + s.committee_extra_timeout_s == 360.0
+
+
+def test_interview_did_not_inherit_the_chat_ceiling() -> None:
+ """The onboarding interview has its own, lower ceiling.
+
+ It used to borrow `chat_stream_timeout_s`. It retries twice, so inheriting
+ the 300s chat ceiling would mean a 10-minute hang before the wizard
+ surfaces a timeout to the user.
+ """
+ s = Settings(_env_file=None)
+ assert s.interview_timeout_s == 120.0
+ assert s.interview_timeout_s < s.chat_stream_timeout_s
+
+
+def test_timeouts_are_env_overridable(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv("CHAT_STREAM_TIMEOUT_S", "45")
+ monkeypatch.setenv("COMMITTEE_EXTRA_TIMEOUT_S", "15")
+ monkeypatch.setenv("INTERVIEW_TIMEOUT_S", "30")
+ s = Settings(_env_file=None)
+ assert s.chat_stream_timeout_s == 45.0
+ assert s.committee_extra_timeout_s == 15.0
+ assert s.interview_timeout_s == 30.0
diff --git a/packages/core/tests/unit/test_onboarding_interview.py b/packages/core/tests/unit/test_onboarding_interview.py
index 1c516d3c..cd9ab4c2 100644
--- a/packages/core/tests/unit/test_onboarding_interview.py
+++ b/packages/core/tests/unit/test_onboarding_interview.py
@@ -346,7 +346,7 @@ async def test_timeout_raises_interview_timeout(
_install(monkeypatch, Slow())
monkeypatch.setattr(
"openexecutive.onboarding.interview.get_settings",
- lambda: SimpleNamespace(chat_stream_timeout_s=0.01),
+ lambda: SimpleNamespace(interview_timeout_s=0.01),
)
with pytest.raises(iv.InterviewTimeout):
await iv.advance(_opening())
diff --git a/packages/core/tests/unit/test_session_store.py b/packages/core/tests/unit/test_session_store.py
index de83f421..dad625af 100644
--- a/packages/core/tests/unit/test_session_store.py
+++ b/packages/core/tests/unit/test_session_store.py
@@ -177,3 +177,72 @@ def test_save_message_with_list_content(db: Path) -> None:
assert len(msgs) == 1
assert msgs[0]["role"] == "assistant"
assert isinstance(msgs[0]["content"], str)
+
+
+def test_save_message_round_trips_the_stopped_flag(db: Path) -> None:
+ """A stopped assistant turn is flagged, so a truncated reply is not read
+ back as a complete one after a reload."""
+ create_session("s11", "Test", "2024-01-01T00:00:00", db_path=db)
+ save_message("s11", "user", "explain our burn rate", db_path=db)
+ save_message("s11", "assistant", "partial ans", db_path=db, stopped=True)
+
+ msgs = load_messages("s11", db_path=db)
+ assert msgs[1]["stopped"] is True
+ # Attached only when true, like `actions` — an ordinary message keeps the
+ # exact dict shape every existing consumer expects.
+ assert "stopped" not in msgs[0]
+
+
+def test_unstopped_message_omits_the_key(db: Path) -> None:
+ create_session("s12", "Test", "2024-01-01T00:00:00", db_path=db)
+ save_message("s12", "assistant", "complete answer", db_path=db)
+
+ msgs = load_messages("s12", db_path=db)
+ assert "stopped" not in msgs[0]
+
+
+def test_legacy_rows_without_the_column_still_load(tmp_path: Path) -> None:
+ """The additive migration must leave a pre-existing DB readable, with old
+ assistant messages defaulting to not-stopped."""
+ import sqlite3
+
+ db_path = tmp_path / "legacy.db"
+ # Build the pre-migration shape by hand, then let initialize_db migrate it.
+ with sqlite3.connect(db_path) as conn:
+ conn.execute(
+ "CREATE TABLE sessions (session_id TEXT PRIMARY KEY, title TEXT, "
+ "created_at TEXT NOT NULL, updated_at TEXT NOT NULL)"
+ )
+ conn.execute(
+ "CREATE TABLE chat_messages (id INTEGER PRIMARY KEY AUTOINCREMENT, "
+ "session_id TEXT NOT NULL, role TEXT NOT NULL, content TEXT NOT NULL, "
+ "created_at TEXT NOT NULL)"
+ )
+ conn.execute(
+ "INSERT INTO sessions VALUES ('old', 'Old', '2024-01-01', '2024-01-01')"
+ )
+ conn.execute(
+ "INSERT INTO chat_messages (session_id, role, content, created_at) "
+ "VALUES ('old', 'assistant', 'legacy reply', '2024-01-01')"
+ )
+
+ initialize_db(db_path)
+
+ cols = _columns(db_path, "chat_messages")
+ assert "stopped" in cols
+ assert "action_chips" in cols
+
+ msgs = load_messages("old", db_path=db_path)
+ assert msgs[0]["content"] == "legacy reply"
+ assert "stopped" not in msgs[0]
+
+ # And the migrated table still accepts new writes.
+ save_message("old", "assistant", "new reply", db_path=db_path, stopped=True)
+ assert load_messages("old", db_path=db_path)[1]["stopped"] is True
+
+
+def _columns(db_path: Path, table: str) -> set[str]:
+ import sqlite3
+
+ with sqlite3.connect(db_path) as conn:
+ return {row[1] for row in conn.execute(f"PRAGMA table_info({table})")}
diff --git a/packages/ui/scripts/turn-id.test.mjs b/packages/ui/scripts/turn-id.test.mjs
new file mode 100644
index 00000000..5b335b28
--- /dev/null
+++ b/packages/ui/scripts/turn-id.test.mjs
@@ -0,0 +1,49 @@
+import { strict as assert } from "node:assert";
+import test from "node:test";
+
+import { CLIENT_TURN_ID_RE, newClientTurnId } from "../src/lib/turn-id.ts";
+
+test("minted ids match the regex the server enforces", () => {
+ for (let i = 0; i < 50; i++) {
+ const id = newClientTurnId();
+ assert.match(id, CLIENT_TURN_ID_RE, `minted id rejected by server regex: ${id}`);
+ }
+});
+
+test("ids are unique", () => {
+ const seen = new Set();
+ for (let i = 0; i < 200; i++) seen.add(newClientTurnId());
+ assert.equal(seen.size, 200);
+});
+
+// `globalThis.crypto` is a getter-only accessor in Node, so it can only be
+// swapped via defineProperty.
+function withCrypto(stub, fn) {
+ const original = Object.getOwnPropertyDescriptor(globalThis, "crypto");
+ Object.defineProperty(globalThis, "crypto", {
+ value: stub,
+ configurable: true,
+ writable: true,
+ });
+ try {
+ fn();
+ } finally {
+ Object.defineProperty(globalThis, "crypto", original);
+ }
+}
+
+test("getRandomValues fallback still matches the server regex", () => {
+ const real = globalThis.crypto;
+ // Simulate a non-secure context: getRandomValues present, randomUUID gone.
+ withCrypto({ getRandomValues: (a) => real.getRandomValues(a) }, () => {
+ const id = newClientTurnId();
+ assert.match(id, CLIENT_TURN_ID_RE);
+ assert.equal(id.length, 32);
+ });
+});
+
+test("last-resort fallback still matches the server regex", () => {
+ withCrypto(undefined, () => {
+ assert.match(newClientTurnId(), CLIENT_TURN_ID_RE);
+ });
+});
diff --git a/packages/ui/src/app/api/backend/[...path]/route.ts b/packages/ui/src/app/api/backend/[...path]/route.ts
index ff68d0f8..352918ba 100644
--- a/packages/ui/src/app/api/backend/[...path]/route.ts
+++ b/packages/ui/src/app/api/backend/[...path]/route.ts
@@ -77,6 +77,11 @@ async function proxy(req: NextRequest, params: { path: string[] }): Promise<Resp
// Forward the body for non-GET/HEAD. `duplex: "half"` is required by
// Node's fetch when streaming a request body.
body: req.method === "GET" || req.method === "HEAD" ? undefined : req.body,
+ // Propagate a client disconnect upstream. Without this the backend never
+ // sees `http.disconnect`, so its `request.is_disconnected()` check — and
+ // the "persist the partial turn on disconnect" path behind it — never fire,
+ // and a closed tab leaves the turn running to completion against Anthropic.
+ signal: req.signal,
// @ts-expect-error -- `duplex` is valid in Node fetch but not in the TS lib types yet.
duplex: "half",
};
diff --git a/packages/ui/src/app/page.tsx b/packages/ui/src/app/page.tsx
index 336827af..f4e598e8 100644
--- a/packages/ui/src/app/page.tsx
+++ b/packages/ui/src/app/page.tsx
@@ -138,7 +138,12 @@ export default function HomePage() {
);
const handleTurnComplete = useCallback((sessionId: string) => {
- setActiveSessionId(sessionId);
+ // Only adopt a real id. A turn that ends without ever learning one (an
+ // aborted stream) would otherwise set this to "", which <Chat> reads as
+ // "the parent selected a different session" and clears the transcript
+ // with — losing the very reply the stop was meant to keep. The in-flight
+ // flag is cleared either way, so the Agent Activity panel never sticks.
+ if (sessionId) setActiveSessionId(sessionId);
setIsTurnInFlight(false);
refreshSessions();
}, [refreshSessions]);
diff --git a/packages/ui/src/components/Chat.tsx b/packages/ui/src/components/Chat.tsx
index 80e4a5f1..5adb6cb4 100644
--- a/packages/ui/src/components/Chat.tsx
+++ b/packages/ui/src/components/Chat.tsx
@@ -20,6 +20,7 @@ import {
getSuggestedPrompts,
streamChat,
} from "@/lib/api";
+import { isAbortError, useStoppableTurn } from "@/lib/use-stoppable-turn";
interface ChatProps {
onDebugEvent?: (event: DebugEvent) => void;
@@ -61,6 +62,8 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
const [messages, setMessages] = useState<ChatMessage[]>(initialMessages ?? []);
const [input, setInput] = useState(initialInput ?? "");
const [isLoading, setIsLoading] = useState(false);
+ const { isStopping, beginTurn, stop: handleStop, serverAcknowledgedStop, endTurn } =
+ useStoppableTurn();
const [sessionId, setSessionId] = useState<string | undefined>(initialSessionId);
const [streamingContent, setStreamingContent] = useState("");
// Inline action chips that arrived for the in-flight assistant message.
@@ -120,6 +123,26 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
// We pass the prompt explicitly into handleSend so the state-clearing in
// handleSend doesn't race with React batching `setInput("")` after the
// submit reads it back.
+ // Escape stops the turn. This has to be a document listener rather than the
+ // textarea's onKeyDown: the textarea is `disabled` while a turn is in
+ // flight, and a disabled element cannot hold focus or emit key events — so
+ // the one condition under which we want Escape is exactly the one where the
+ // textarea handler can never run.
+ useEffect(() => {
+ if (!isLoading) return;
+ const onKey = (e: KeyboardEvent) => {
+ if (e.key !== "Escape") return;
+ // An overlay that consumed this Escape (a tooltip, a dialog) calls
+ // preventDefault. Stopping the turn as well would make one keypress do
+ // two unrelated things.
+ if (e.defaultPrevented) return;
+ e.preventDefault();
+ void handleStop();
+ };
+ document.addEventListener("keydown", onKey);
+ return () => document.removeEventListener("keydown", onKey);
+ }, [isLoading, handleStop]);
+
const didAutoSubmitRef = useRef(false);
useEffect(() => {
if (didAutoSubmitRef.current) return;
@@ -131,6 +154,16 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
// eslint-disable-next-line react-hooks/exhaustive-deps
}, []);
+ // Every streamed event carries the resolved session id, not just `done`.
+ // Adopting it as soon as it is seen means a turn that ends without `done`
+ // (an aborted stream) still leaves the client pointing at the right session,
+ // rather than falling back to "" and orphaning the conversation.
+ function adoptSessionId(id: string) {
+ if (adoptedSessionIdRef.current === id) return;
+ adoptedSessionIdRef.current = id;
+ setSessionId(id);
+ }
+
async function handleSend(text?: string) {
const message = (text ?? input).trim();
if ((!message && pendingFiles.length === 0) || isLoading) return;
@@ -150,27 +183,34 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
setIsConsulting(false);
setActivityLabel(null);
setCommitteePhase(null);
+ const { clientTurnId, signal } = beginTurn();
onTurnStart?.();
if (textareaRef.current) {
textareaRef.current.style.height = "auto";
}
- try {
- let accumulated = "";
- // Local mirror of streamingActions so the closure builds the final
- // message without depending on the async setState applying first.
- const turnActions: ActionTaken[] = [];
+ // Declared outside the try so the abort path in `catch` can still commit
+ // whatever streamed before the stop.
+ let accumulated = "";
+ // Local mirror of streamingActions so the closure builds the final
+ // message without depending on the async setState applying first.
+ const turnActions: ActionTaken[] = [];
+ let wasStopped = false;
+ try {
for await (const item of streamChat(message, sessionId, {
committeeReview: committeeEnabled,
files: filesForTurn,
+ clientTurnId,
+ signal,
})) {
if (item.type === "debug_event") {
onDebugEvent?.(item);
continue;
}
if (item.type === "chunk" && item.content) {
+ if (item.session_id) adoptSessionId(item.session_id);
accumulated += item.content;
setIsConsulting(false);
setActivityLabel(null);
@@ -194,10 +234,17 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
} else if (item.type === "action_taken") {
turnActions.push(item);
setStreamingActions([...turnActions]);
+ } else if (item.type === "stopped") {
+ // The server acknowledged the stop and is winding the turn down
+ // itself; `done` follows over the same stream. Stand the abort
+ // fallback down, or it would fire mid-wind-down and cost us the
+ // terminal events — including the `session_id` a first turn needs.
+ wasStopped = true;
+ serverAcknowledgedStop();
+ if (item.session_id) adoptSessionId(item.session_id);
} else if (item.type === "done") {
if (item.session_id) {
- adoptedSessionIdRef.current = item.session_id;
- setSessionId(item.session_id);
+ adoptSessionId(item.session_id);
onTurnComplete?.(item.session_id);
}
} else if (item.type === "error") {
@@ -205,25 +252,65 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
}
}
- setMessages((prev) => [
- ...prev,
- {
- role: "assistant",
- content: accumulated,
- actions: turnActions.length > 0 ? turnActions : undefined,
- },
- ]);
+ // A stop before any output persists nothing server-side — not even the
+ // user's message, because saving it alone would break the user/assistant
+ // alternation the stored history relies on. So rather than leave a pair
+ // of bubbles that silently vanish on reload, take the message back and
+ // return the text to the composer: the user stopped before it started,
+ // and can edit and resend. Skipped when files were attached — dropping a
+ // file selection without saying so would be worse than the mismatch.
+ if (wasStopped && !accumulated && turnActions.length === 0) {
+ if (filesForTurn.length === 0) {
+ setMessages((prev) =>
+ prev.length && prev[prev.length - 1].role === "user"
+ ? prev.slice(0, -1)
+ : prev,
+ );
+ setInput(message);
+ }
+ } else if (accumulated || turnActions.length > 0) {
+ setMessages((prev) => [
+ ...prev,
+ {
+ role: "assistant",
+ content: accumulated,
+ actions: turnActions.length > 0 ? turnActions : undefined,
+ stopped: wasStopped || undefined,
+ },
+ ]);
+ }
setStreamingContent("");
setStreamingActions([]);
} catch (err) {
- const detail = err instanceof Error ? err.message : String(err);
- setMessages((prev) => [
- ...prev,
- { role: "assistant", content: `Something went wrong: ${detail}` },
- ]);
+ if (isAbortError(err)) {
+ // Our own safety-net abort fired (the server never sent `stopped`).
+ // Keep whatever streamed; this is a stop, not a failure.
+ if (accumulated || turnActions.length > 0) {
+ setMessages((prev) => [
+ ...prev,
+ {
+ role: "assistant",
+ content: accumulated,
+ actions: turnActions.length > 0 ? turnActions : undefined,
+ stopped: true,
+ },
+ ]);
+ }
+ // `done` never arrived, so nothing else will clear the parent's
+ // in-flight state or refresh the sidebar. Safe to call with an empty
+ // id: the parent only adopts a truthy one (see handleTurnComplete).
+ onTurnComplete?.(adoptedSessionIdRef.current ?? sessionId ?? "");
+ } else {
+ const detail = err instanceof Error ? err.message : String(err);
+ setMessages((prev) => [
+ ...prev,
+ { role: "assistant", content: `Something went wrong: ${detail}` },
+ ]);
+ }
setStreamingContent("");
setStreamingActions([]);
} finally {
+ endTurn();
setIsLoading(false);
setIsConsulting(false);
setActivityLabel(null);
@@ -321,6 +408,7 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
role={msg.role}
content={msg.content}
actions={msg.role === "assistant" ? msg.actions : undefined}
+ stopped={msg.role === "assistant" ? msg.stopped : undefined}
/>
))}
@@ -449,15 +537,28 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
>
Committee
</button>
- <button
- type="button"
- onClick={() => handleSend()}
- disabled={(!input.trim() && pendingFiles.length === 0) || isLoading}
- aria-label="Send message"
- className="flex-shrink-0 min-h-touch min-w-touch w-10 h-10 rounded-xl bg-indigo-500 hover:bg-indigo-400 disabled:opacity-30 disabled:cursor-not-allowed transition-all duration-150 flex items-center justify-center cursor-pointer"
- >
- <Icon name="arrow-send" size="w-4 h-4" className="text-white" />
- </button>
+ {isLoading ? (
+ <button
+ type="button"
+ onClick={handleStop}
+ disabled={isStopping}
+ aria-label="Stop the executive"
+ title="Stop — whatever has been written so far is kept"
+ className="flex-shrink-0 min-h-touch min-w-touch w-10 h-10 rounded-xl bg-surface-overlay border border-line-strong text-fg hover:border-fg-muted disabled:opacity-30 disabled:cursor-not-allowed transition-all duration-150 flex items-center justify-center cursor-pointer"
+ >
+ <Icon name="stop" size="w-3.5 h-3.5" fill="currentColor" />
+ </button>
+ ) : (
+ <button
+ type="button"
+ onClick={() => handleSend()}
+ disabled={!input.trim() && pendingFiles.length === 0}
+ aria-label="Send message"
+ className="flex-shrink-0 min-h-touch min-w-touch w-10 h-10 rounded-xl bg-indigo-500 hover:bg-indigo-400 disabled:opacity-30 disabled:cursor-not-allowed transition-all duration-150 flex items-center justify-center cursor-pointer"
+ >
+ <Icon name="arrow-send" size="w-4 h-4" className="text-white" />
+ </button>
+ )}
</div>
<p className="text-center text-xs text-fg-muted mt-2 inline-flex items-center justify-center gap-1.5 w-full">
<span className="hidden sm:inline">Enter to send · Shift+Enter for new line</span>
diff --git a/packages/ui/src/components/Icon.tsx b/packages/ui/src/components/Icon.tsx
index 4db40d5e..5e59fba6 100644
--- a/packages/ui/src/components/Icon.tsx
+++ b/packages/ui/src/components/Icon.tsx
@@ -29,6 +29,9 @@ export const ICON_PATHS = {
search: "m21 21-5.197-5.197m0 0A7.5 7.5 0 1 0 5.196 5.196a7.5 7.5 0 0 0 10.607 10.607Z",
activity: "M3.75 13.5l10.5-11.25L12 10.5h8.25L9.75 21.75 12 13.5H3.75z",
info: "M11.25 11.25l.041-.02a.75.75 0 011.063.852l-.708 2.836a.75.75 0 001.063.853l.041-.021M21 12a9 9 0 11-18 0 9 9 0 0118 0zm-9-3.75h.008v.008H12V8.25z",
+ // Rounded square. Render it filled — `<Icon name="stop" fill="currentColor" />`
+ // — since `{...rest}` is spread after `fill="none"` below.
+ stop: "M7.5 5.25h9a2.25 2.25 0 0 1 2.25 2.25v9a2.25 2.25 0 0 1-2.25 2.25h-9a2.25 2.25 0 0 1-2.25-2.25v-9A2.25 2.25 0 0 1 7.5 5.25Z",
eye: "M2.036 12.322a1.012 1.012 0 010-.639C3.423 7.51 7.36 4.5 12 4.5c4.638 0 8.573 3.007 9.963 7.178.07.207.07.431 0 .639C20.577 16.49 16.64 19.5 12 19.5c-4.638 0-8.573-3.007-9.963-7.178zM15 12a3 3 0 11-6 0 3 3 0 016 0z",
} as const;
diff --git a/packages/ui/src/components/InfoTip.tsx b/packages/ui/src/components/InfoTip.tsx
index c324aa52..4593a076 100644
--- a/packages/ui/src/components/InfoTip.tsx
+++ b/packages/ui/src/components/InfoTip.tsx
@@ -57,7 +57,12 @@ export default function InfoTip({
if (!wrapRef.current?.contains(e.target as Node)) setOpen(false);
}
function onKey(e: KeyboardEvent) {
- if (e.key === "Escape") setOpen(false);
+ if (e.key === "Escape") {
+ // Mark it consumed so a page-level Escape handler (e.g. Chat's
+ // stop-the-turn shortcut) doesn't also fire on the same keypress.
+ e.preventDefault();
+ setOpen(false);
+ }
}
document.addEventListener("mousedown", onDown);
document.addEventListener("keydown", onKey);
diff --git a/packages/ui/src/components/Message.tsx b/packages/ui/src/components/Message.tsx
index 178a95cd..1ab6938f 100644
--- a/packages/ui/src/components/Message.tsx
+++ b/packages/ui/src/components/Message.tsx
@@ -15,6 +15,10 @@ interface MessageProps {
// workflow opened, person updated, alert flagged…). User messages
// never have actions.
actions?: ActionTaken[];
+ // The user stopped this reply mid-stream. Renders a marker so a truncated
+ // answer isn't read as a complete one — on reload too, since the flag is
+ // persisted with the message.
+ stopped?: boolean;
}
function ActionChip({ action }: { action: ActionTaken }) {
@@ -34,7 +38,7 @@ function ActionChip({ action }: { action: ActionTaken }) {
return inner;
}
-export default function Message({ role, content, isStreaming, actions }: MessageProps) {
+export default function Message({ role, content, isStreaming, actions, stopped }: MessageProps) {
if (role === "user") {
return (
<div className="flex justify-end mb-6">
@@ -84,6 +88,10 @@ export default function Message({ role, content, isStreaming, actions }: Message
))}
</div>
)}
+
+ {stopped && !isStreaming && (
+ <p className="mt-2 text-xs text-fg-muted">Stopped by you</p>
+ )}
</div>
</div>
);
diff --git a/packages/ui/src/components/askoe/AskOEPanel.tsx b/packages/ui/src/components/askoe/AskOEPanel.tsx
index 3d13f72b..2732a143 100644
--- a/packages/ui/src/components/askoe/AskOEPanel.tsx
+++ b/packages/ui/src/components/askoe/AskOEPanel.tsx
@@ -7,6 +7,7 @@ import Message from "@/components/Message";
import { useAskOE } from "@/components/askoe/AskOEContext";
import type { ActionTaken, FormPatch } from "@/lib/api";
import { streamChat } from "@/lib/api";
+import { isAbortError, useStoppableTurn } from "@/lib/use-stoppable-turn";
// One proposal card per form_patch event: what was applied/skipped, the
// Executive's rationale, and an Undo that restores the pre-patch values.
@@ -25,6 +26,8 @@ interface PanelMessage {
content: string;
actions?: ActionTaken[];
patches?: PatchCardData[];
+ /** The user stopped this reply mid-stream. */
+ stopped?: boolean;
}
function PatchCard({
@@ -93,6 +96,8 @@ export default function AskOEPanel() {
// Synchronous in-flight guard: `streaming` state updates async, so two
// rapid Enter presses could both pass the state check before re-render.
const sendingRef = useRef(false);
+ const { isStopping, beginTurn, stop, serverAcknowledgedStop, endTurn } =
+ useStoppableTurn();
useEffect(() => {
scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight });
@@ -139,15 +144,21 @@ export default function AskOEPanel() {
setStreaming(true);
setStreamingContent("");
setActivityLabel(null);
+ const { clientTurnId, signal } = beginTurn();
let content = "";
+ let wasStopped = false;
const actions: ActionTaken[] = [];
const patches: PatchCardData[] = [];
try {
// Page context is snapshotted per turn — current route, form
// descriptor, and live field values at the moment of sending.
const pageContext = ctx.buildPageContext();
- for await (const item of streamChat(trimmed, sessionId, { pageContext })) {
+ for await (const item of streamChat(trimmed, sessionId, {
+ pageContext,
+ clientTurnId,
+ signal,
+ })) {
if (item.type === "chunk" && item.content) {
content += item.content;
setActivityLabel(null);
@@ -160,14 +171,31 @@ export default function AskOEPanel() {
actions.push(item);
} else if (item.type === "error") {
setError(item.message ?? "Something went wrong.");
- } else if (item.type === "done" && item.session_id) {
+ } else if (item.type === "stopped") {
+ // The server is winding the turn down itself and will close with
+ // `done`; stand the abort fallback down so it can.
+ wasStopped = true;
+ serverAcknowledgedStop();
+ if (item.session_id) setSessionId(item.session_id);
+ } else if (
+ (item.type === "done" || item.type === "chunk") &&
+ item.session_id
+ ) {
+ // Adopt the id from any event that carries one, not only `done` —
+ // a turn that ends without `done` would otherwise leave the panel
+ // pointing at no session.
setSessionId(item.session_id);
}
// thinking / phase / debug_event: no panel surface needed.
// `activity` is surfaced — it fills the streaming placeholder.
}
} catch (e) {
- setError(e instanceof Error ? e.message : "Request failed.");
+ if (isAbortError(e)) {
+ // Our own safety-net abort. A stop is not an error.
+ wasStopped = true;
+ } else {
+ setError(e instanceof Error ? e.message : "Request failed.");
+ }
} finally {
// Don't append an empty assistant turn when the request failed
// before producing anything — the error box is the only signal.
@@ -179,16 +207,18 @@ export default function AskOEPanel() {
content,
actions: actions.length ? actions : undefined,
patches: patches.length ? patches : undefined,
+ stopped: wasStopped || undefined,
},
]);
}
+ endTurn();
setStreamingContent("");
setActivityLabel(null);
setStreaming(false);
sendingRef.current = false;
}
},
- [ctx, handlePatch, sessionId, streaming]
+ [beginTurn, ctx, endTurn, handlePatch, serverAcknowledgedStop, sessionId, streaming]
);
const undoPatch = useCallback(
@@ -298,7 +328,12 @@ export default function AskOEPanel() {
{messages.map((m, i) => (
<div key={i}>
- <Message role={m.role} content={m.content} actions={m.actions} />
+ <Message
+ role={m.role}
+ content={m.content}
+ actions={m.actions}
+ stopped={m.stopped}
+ />
{m.patches?.map((card, j) => (
<PatchCard key={j} card={card} onUndo={() => undoPatch(i, j)} />
))}
@@ -340,15 +375,28 @@ export default function AskOEPanel() {
}
className="flex-1 px-3 py-2 text-sm rounded-lg bg-surface-input border border-line text-fg placeholder:text-fg-subtle resize-none focus:outline-none focus:border-indigo-500"
/>
- <button
- type="button"
- disabled={streaming || !input.trim()}
- onClick={() => void send(input)}
- aria-label="Send"
- className="min-h-touch min-w-touch flex items-center justify-center rounded-lg bg-indigo-600 hover:bg-indigo-500 disabled:opacity-40 text-white transition-colors"
- >
- <Icon name="arrow-send" size="w-4 h-4" />
- </button>
+ {streaming ? (
+ <button
+ type="button"
+ disabled={isStopping}
+ onClick={() => void stop()}
+ aria-label="Stop the executive"
+ title="Stop — whatever has been written so far is kept"
+ className="min-h-touch min-w-touch flex items-center justify-center rounded-lg bg-surface-overlay border border-line-strong text-fg hover:border-fg-muted disabled:opacity-40 transition-colors"
+ >
+ <Icon name="stop" size="w-3.5 h-3.5" fill="currentColor" />
+ </button>
+ ) : (
+ <button
+ type="button"
+ disabled={!input.trim()}
+ onClick={() => void send(input)}
+ aria-label="Send"
+ className="min-h-touch min-w-touch flex items-center justify-center rounded-lg bg-indigo-600 hover:bg-indigo-500 disabled:opacity-40 text-white transition-colors"
+ >
+ <Icon name="arrow-send" size="w-4 h-4" />
+ </button>
+ )}
</div>
</div>
</aside>
diff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.ts
index 65f9c7af..dc658c26 100644
--- a/packages/ui/src/lib/api.ts
+++ b/packages/ui/src/lib/api.ts
@@ -48,7 +48,10 @@ export interface ChatChunk {
| "error"
| "thinking"
| "phase"
- | "committee_critique";
+ | "committee_critique"
+ // The user pressed Stop. Always followed by `done` over the same still-open
+ // stream, so the consumer's state machine still reaches a clean end.
+ | "stopped";
content?: string;
session_id?: string;
message?: string;
@@ -137,6 +140,13 @@ export interface StreamChatOptions {
// Ask OE panel only — what page/form the user is looking at. Ignored on
// the multipart route (the panel doesn't support attachments).
pageContext?: PageContext;
+ // Client-minted id for this turn, so it can be addressed by `stopChat`.
+ // Omit it and the turn simply isn't stoppable.
+ clientTurnId?: string;
+ // Safety net only. The normal stop path leaves the stream open and lets the
+ // server wind down and send `stopped` + `done`; this aborts the fetch
+ // outright if that never arrives.
+ signal?: AbortSignal;
}
export async function* streamChat(
@@ -153,10 +163,12 @@ export async function* streamChat(
form.append("message", message);
if (sessionId) form.append("session_id", sessionId);
form.append("committee_review", String(committeeReview));
+ if (opts?.clientTurnId) form.append("client_turn_id", opts.clientTurnId);
for (const file of files) form.append("files", file, file.name);
response = await fetch(`${API_BASE}/chat/upload`, {
method: "POST",
body: form,
+ signal: opts?.signal,
});
} else {
response = await fetch(`${API_BASE}/chat`, {
@@ -167,7 +179,9 @@ export async function* streamChat(
session_id: sessionId,
committee_review: committeeReview,
page_context: opts?.pageContext ?? undefined,
+ client_turn_id: opts?.clientTurnId ?? undefined,
}),
+ signal: opts?.signal,
});
}
@@ -188,24 +202,50 @@ export async function* streamChat(
const decoder = new TextDecoder();
let buffer = "";
- while (true) {
- const { done, value } = await reader.read();
- if (done) break;
-
- buffer += decoder.decode(value, { stream: true });
- const lines = buffer.split("\n");
- buffer = lines.pop() ?? "";
-
- for (const line of lines) {
- if (line.startsWith("data: ")) {
- try {
- const data: StreamItem = JSON.parse(line.slice(6));
- yield data;
- } catch {
- // skip malformed lines
+ try {
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) break;
+
+ buffer += decoder.decode(value, { stream: true });
+ const lines = buffer.split("\n");
+ buffer = lines.pop() ?? "";
+
+ for (const line of lines) {
+ if (line.startsWith("data: ")) {
+ try {
+ const data: StreamItem = JSON.parse(line.slice(6));
+ yield data;
+ } catch {
+ // skip malformed lines
+ }
}
}
}
+ } finally {
+ // `break`-ing out of the caller's `for await` closes this generator but
+ // would otherwise leave the HTTP body open.
+ await reader.cancel().catch(() => {});
+ }
+}
+
+/** Ask the backend to stop an in-flight turn.
+ *
+ * Best-effort and never throws: a 404 just means the turn already ended, and a
+ * network failure is covered by the caller's abort fallback. The SSE stream
+ * stays the authority on how the turn actually finished — this only flips the
+ * server-side switch. Returns whether the server accepted the stop.
+ */
+export async function stopChat(clientTurnId: string): Promise<boolean> {
+ try {
+ const res = await fetch(`${API_BASE}/chat/stop`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ client_turn_id: clientTurnId }),
+ });
+ return res.ok;
+ } catch {
+ return false;
}
}
@@ -769,6 +809,10 @@ export interface ChatMessage {
// `chat_messages.action_chips` so reopening a saved session restores
// them (the backend re-attaches them here via load_messages).
actions?: ActionTaken[];
+ // True when the user stopped this reply mid-stream. Persisted to
+ // `chat_messages.stopped`, so the marker survives a reload rather than
+ // letting a truncated reply read as a complete one.
+ stopped?: boolean;
}
export interface Decision {
diff --git a/packages/ui/src/lib/turn-id.ts b/packages/ui/src/lib/turn-id.ts
new file mode 100644
index 00000000..5b076e51
--- /dev/null
+++ b/packages/ui/src/lib/turn-id.ts
@@ -0,0 +1,27 @@
+// Client-minted id for one chat turn. The client needs an id *before* the
+// request goes out: the backend spends several seconds fetching context
+// (RAG + episodic + Honcho + briefing) before the SSE response even exists,
+// so a server-issued id would leave the Stop button dead during exactly the
+// window where stopping is free — no model call has been made yet.
+//
+// Paired constant: `_CLIENT_TURN_ID_RE` in
+// packages/core/openexecutive/api/routes/chat.py. Keep the two in sync — the
+// server drops an id that doesn't match, which silently makes turns
+// unstoppable. The charset is narrow because the value reaches server log
+// lines.
+export const CLIENT_TURN_ID_RE = /^[A-Za-z0-9-]{8,64}$/;
+
+export function newClientTurnId(): string {
+ // `crypto.randomUUID` needs a secure context; a plain-HTTP LAN dev host
+ // doesn't have one, and a stop button that throws is worse than one that
+ // falls back to a slightly shorter random id.
+ const c = globalThis.crypto;
+ if (typeof c?.randomUUID === "function") return c.randomUUID();
+ if (typeof c?.getRandomValues === "function") {
+ const bytes = c.getRandomValues(new Uint8Array(16));
+ return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+ }
+ // Last resort. Not unguessable, but the id only addresses this browser's own
+ // in-flight turn, and the server also checks the caller owns it.
+ return `t-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
diff --git a/packages/ui/src/lib/use-stoppable-turn.ts b/packages/ui/src/lib/use-stoppable-turn.ts
new file mode 100644
index 00000000..6889bb5a
--- /dev/null
+++ b/packages/ui/src/lib/use-stoppable-turn.ts
@@ -0,0 +1,144 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { stopChat } from "@/lib/api";
+import { newClientTurnId } from "@/lib/turn-id";
+
+// How long to wait for the server's `stopped` + `done` after it accepted the
+// stop, before falling back to aborting the fetch outright.
+//
+// The normal path never reaches the abort: the server flips its switch, cancels
+// the in-flight step and reports back over the still-open stream, which is what
+// lets the client finish the turn the same way it finishes any other. The abort
+// is only for when that never arrives — the backend restarted, or the stream is
+// wedged. Keep this comfortably longer than the server's cancel-and-wind-down
+// latency, or a healthy stop gets truncated into the abort path and loses the
+// server's own accounting of the turn.
+export const STOP_ABORT_GRACE_MS = 8000;
+
+// A stop can beat its own turn's registration (the server registers as early as
+// it can, but not before the request arrives). One retry covers that without
+// aborting a turn that was about to stream normally.
+export const STOP_RETRY_DELAY_MS = 400;
+
+export interface StoppableTurn {
+ /** True between the Stop click and the turn actually ending. */
+ isStopping: boolean;
+ /** Call at the start of a turn; returns the id and signal to send with it. */
+ beginTurn: () => { clientTurnId: string; signal: AbortSignal };
+ /** Wired to the Stop button. */
+ stop: () => Promise<void>;
+ /** Call when the server's `stopped` event arrives — it is winding the turn
+ * down itself, so the abort fallback must stand down. */
+ serverAcknowledgedStop: () => void;
+ /** Call in the turn's `finally` to clear per-turn state. */
+ endTurn: () => void;
+}
+
+/** Stop-button plumbing shared by the main chat and the Ask OE panel.
+ *
+ * Both surfaces stream from the same `streamChat` helper and need the identical
+ * turn-id / abort-controller / grace-timer dance. Keeping it in one place means
+ * a fix to the race applies to both, rather than to whichever file someone
+ * happened to be looking at.
+ */
+export function useStoppableTurn(): StoppableTurn {
+ const [isStopping, setIsStopping] = useState(false);
+ // Mirrors `isStopping` synchronously. The state value is captured at render
+ // time, so two clicks in the same tick would both pass a state-based guard.
+ const isStoppingRef = useRef(false);
+ // Addresses the in-flight turn for `stopChat`. Minted before the request goes
+ // out, so the button is live from the moment Send is pressed — the server
+ // spends seconds fetching context before the stream exists, and a stop in
+ // that window costs nothing because no model call has been made yet.
+ const clientTurnIdRef = useRef<string | null>(null);
+ const abortRef = useRef<AbortController | null>(null);
+ const graceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+ useEffect(
+ () => () => {
+ if (graceTimerRef.current) clearTimeout(graceTimerRef.current);
+ },
+ [],
+ );
+
+ const beginTurn = useCallback(() => {
+ const clientTurnId = newClientTurnId();
+ clientTurnIdRef.current = clientTurnId;
+ const controller = new AbortController();
+ abortRef.current = controller;
+ isStoppingRef.current = false;
+ setIsStopping(false);
+ return { clientTurnId, signal: controller.signal };
+ }, []);
+
+ const armAbortFallback = useCallback(() => {
+ if (graceTimerRef.current) clearTimeout(graceTimerRef.current);
+ graceTimerRef.current = setTimeout(
+ () => abortRef.current?.abort(),
+ STOP_ABORT_GRACE_MS,
+ );
+ }, []);
+
+ const stop = useCallback(async () => {
+ const clientTurnId = clientTurnIdRef.current;
+ if (!clientTurnId || isStoppingRef.current) return;
+ isStoppingRef.current = true;
+ setIsStopping(true);
+
+ const accepted = await stopChat(clientTurnId);
+ if (!accepted) {
+ // 404 means either "already finished" (the stream is about to end on its
+ // own) or "not registered yet" (we beat the server to it). Retry once
+ // before giving up — aborting immediately would truncate a turn that was
+ // about to stream normally, and would leave the server still working.
+ await new Promise((r) => setTimeout(r, STOP_RETRY_DELAY_MS));
+ if (clientTurnIdRef.current === clientTurnId) {
+ await stopChat(clientTurnId);
+ }
+ }
+ // Always give the server room to wind down and send `stopped` + `done`;
+ // never abort immediately. `serverAcknowledgedStop` cancels this.
+ if (clientTurnIdRef.current === clientTurnId) armAbortFallback();
+ }, [armAbortFallback]);
+
+ const serverAcknowledgedStop = useCallback(() => {
+ // The server is ending the turn itself and will close the stream with
+ // `done`. Letting the fallback fire here would abort mid-wind-down and
+ // cost us the server's own terminal events — which is how the client
+ // learns the session id on a first turn.
+ if (graceTimerRef.current) {
+ clearTimeout(graceTimerRef.current);
+ graceTimerRef.current = null;
+ }
+ }, []);
+
+ const endTurn = useCallback(() => {
+ if (graceTimerRef.current) {
+ clearTimeout(graceTimerRef.current);
+ graceTimerRef.current = null;
+ }
+ clientTurnIdRef.current = null;
+ abortRef.current = null;
+ isStoppingRef.current = false;
+ setIsStopping(false);
+ }, []);
+
+ return { isStopping, beginTurn, stop, serverAcknowledgedStop, endTurn };
+}
+
+/** True for the AbortError our own grace-timer fallback raises.
+ *
+ * Matched by name rather than by `instanceof DOMException`: browsers raise a
+ * DOMException, but Node/undici and jsdom can surface a plain Error with the
+ * same name, and treating that as a crash would show "Something went wrong"
+ * for a stop the user asked for.
+ */
+export function isAbortError(err: unknown): boolean {
+ return (
+ typeof err === "object" &&
+ err !== null &&
+ (err as { name?: unknown }).name === "AbortError"
+ );
+}