Skip to content

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

Keep session and turn attribution across a whole SSE turn

Rufus5a37d9b87563
diff --git a/packages/core/openexecutive/alerts/pipeline.py b/packages/core/openexecutive/alerts/pipeline.py
index 2a04cb91..d32d5994 100644
--- a/packages/core/openexecutive/alerts/pipeline.py
+++ b/packages/core/openexecutive/alerts/pipeline.py
@@ -238,15 +238,47 @@ async def evaluate_and_dispatch(
def schedule_evaluation(event: AlertEvent) -> None:
"""Fire-and-forget evaluation. Safe to call from sync or async context.
- Mirrors memory.episodic.schedule_extraction's GC-safe pattern.
+ Mirrors memory.episodic.schedule_extraction's GC-safe pattern, including
+ its audit-context snapshot: the triage model call happens in a task that
+ starts after the caller's ``with set_turn(...)`` has exited, so without
+ carrying the ids explicitly every triage row records with
+ ``session_id=NULL``. The thread branch needs it even more — a new thread
+ starts from an empty context and inherits nothing.
+
+ A caller with no turn bound (the scheduler, an external-monitor sweep)
+ snapshots ``(None, None)`` and is unchanged: those really are
+ out-of-turn calls.
"""
+ from openexecutive.audit.context import get_active_ids
+
+ audit_sid, audit_tid = get_active_ids()
try:
loop = asyncio.get_running_loop()
- task = loop.create_task(evaluate_and_dispatch(event))
+ task = loop.create_task(_evaluate_in_turn(event, audit_sid, audit_tid))
_background_tasks.add(task)
task.add_done_callback(_background_tasks.discard)
except RuntimeError:
threading.Thread(
- target=lambda: asyncio.run(evaluate_and_dispatch(event)),
+ target=lambda: asyncio.run(
+ _evaluate_in_turn(event, audit_sid, audit_tid)
+ ),
daemon=True,
).start()
+
+
+async def _evaluate_in_turn(
+ event: AlertEvent,
+ audit_session_id: str | None,
+ audit_turn_id: str | None,
+) -> None:
+ """Re-bind the scheduling caller's audit ids, then evaluate."""
+ from openexecutive.audit.context import set_turn
+
+ if audit_session_id is None and audit_turn_id is None:
+ # Nothing to restore — and binding (None, None) would clobber any
+ # ambient turn rather than preserve it.
+ await evaluate_and_dispatch(event)
+ return
+
+ with set_turn(session_id=audit_session_id, turn_id=audit_turn_id):
+ await evaluate_and_dispatch(event)
diff --git a/packages/core/openexecutive/api/routes/chat.py b/packages/core/openexecutive/api/routes/chat.py
index 6dd3a9cb..30281a94 100644
--- a/packages/core/openexecutive/api/routes/chat.py
+++ b/packages/core/openexecutive/api/routes/chat.py
@@ -316,6 +316,21 @@ async def _run_chat_turn(
timeout_s += settings.committee_extra_timeout_s
async def event_generator():
+ # Bind the turn for the whole SSE body, not just its first step.
+ # `_sse_body` drives the executive with `asyncio.wait_for`, which
+ # wraps every `__anext__()` in a fresh Task that copies the context
+ # at that moment — so a binding made *inside* the executive's own
+ # generator lands in a throwaway per-step context and is gone by the
+ # next resume. Everything after step one (the whole tool-call loop
+ # and the specialist fan-out) then records with no session or turn.
+ # Bound out here, in the generator Starlette itself drives, every
+ # step inherits it. `set_turn` saves and restores rather than using
+ # Token.reset precisely so it survives that task-hopping.
+ with set_turn(session_id=session.session_id, turn_id=turn_id):
+ async for evt in _sse_body():
+ yield evt
+
+ async def _sse_body():
from openexecutive.memory.session_store import (
save_message,
update_session_timestamp,
@@ -346,6 +361,7 @@ async def _run_chat_turn(
peer_memory_context=peer_memory_context,
briefing_context=briefing_context,
page_context_block=page_context_block,
+ turn_id=turn_id,
).__aiter__()
else:
stream = executive.stream_chat(
@@ -359,6 +375,7 @@ async def _run_chat_turn(
peer_memory_context=peer_memory_context,
briefing_context=briefing_context,
page_context_block=page_context_block,
+ turn_id=turn_id,
).__aiter__()
# Whole-turn deadline, not per-chunk: a stream that drips bytes
diff --git a/packages/core/openexecutive/memory/episodic.py b/packages/core/openexecutive/memory/episodic.py
index 899d8310..99e02cac 100644
--- a/packages/core/openexecutive/memory/episodic.py
+++ b/packages/core/openexecutive/memory/episodic.py
@@ -1846,13 +1846,45 @@ async def extract_and_store(
assistant_response: str,
db_path: Path = DB_PATH,
session_id: str = "",
+ audit_session_id: str | None = None,
+ audit_turn_id: str | None = None,
) -> None:
"""Extract memorable items from a conversation turn and persist them.
`session_id` is forwarded to store_decision/store_advice so the stored
rows can later be scoped back to this conversation via format_for_prompt.
Runs as a background task — never blocks the response stream.
+
+ `audit_session_id` / `audit_turn_id` are the caller's audit ContextVars,
+ snapshotted by schedule_extraction before this task was spawned and
+ re-bound here. A background task starts from a context in which the
+ caller's `with set_turn(...)` has already exited, so without them this
+ function's model call records unattributed.
"""
+ from openexecutive.audit.context import set_turn
+
+ if audit_session_id is None and audit_turn_id is None:
+ # Nothing to restore. Binding (None, None) here would CLOBBER an
+ # ambient turn for a caller that awaits this directly from inside
+ # its own `with set_turn(...)` — the exact opposite of the bug this
+ # parameter exists to fix.
+ await _extract_and_store(
+ user_message, assistant_response, db_path, session_id
+ )
+ return
+
+ with set_turn(session_id=audit_session_id, turn_id=audit_turn_id):
+ await _extract_and_store(
+ user_message, assistant_response, db_path, session_id
+ )
+
+
+async def _extract_and_store(
+ user_message: str,
+ assistant_response: str,
+ db_path: Path,
+ session_id: str,
+) -> None:
try:
from openexecutive.audit.usage import log_model_usage
from openexecutive.config import get_settings
@@ -1982,10 +2014,27 @@ def schedule_extraction(
Pass `session_id` to tag extracted decisions and advice with the
originating conversation so format_for_prompt can scope them later.
"""
+ from openexecutive.audit.context import get_active_ids
+
+ # Snapshot the audit ContextVars at scheduling time. By the time the
+ # background task runs, the caller's ``with set_turn(...)`` block has
+ # exited and the vars are back to None — so without this snapshot the
+ # memory_extractor's own model call records with ``session_id=NULL``
+ # and is invisible in the per-session view. Same pattern as
+ # memory.honcho_client's background syncs. The thread branch needs it
+ # even more: a new thread starts from an empty context, so nothing is
+ # inherited there at all.
+ audit_sid, audit_tid = get_active_ids()
try:
loop = asyncio.get_running_loop()
task = loop.create_task(
- extract_and_store(user_message, assistant_response, session_id=session_id)
+ extract_and_store(
+ user_message,
+ assistant_response,
+ session_id=session_id,
+ audit_session_id=audit_sid,
+ audit_turn_id=audit_tid,
+ )
)
# Hold a strong reference so GC cannot cancel the task mid-flight.
_background_tasks.add(task)
@@ -1994,7 +2043,13 @@ def schedule_extraction(
# No running event loop (CLI context) — run in a daemon thread.
threading.Thread(
target=lambda: asyncio.run(
- extract_and_store(user_message, assistant_response, session_id=session_id)
+ extract_and_store(
+ user_message,
+ assistant_response,
+ session_id=session_id,
+ audit_session_id=audit_sid,
+ audit_turn_id=audit_tid,
+ )
),
daemon=True,
).start()
diff --git a/packages/core/openexecutive/orchestrator/executive.py b/packages/core/openexecutive/orchestrator/executive.py
index 8618d294..bf82a7d6 100644
--- a/packages/core/openexecutive/orchestrator/executive.py
+++ b/packages/core/openexecutive/orchestrator/executive.py
@@ -489,6 +489,7 @@ class Executive:
briefing_context: str = "",
channel_context_block: str = "",
page_context_block: str = "",
+ turn_id: str | None = None,
) -> AsyncIterator[str | dict[str, Any]]:
"""Stream a response from the Executive, routing to specialists as needed.
@@ -557,7 +558,10 @@ class Executive:
# Bound BEFORE prefetch so the Honcho audit row inherits the
# turn link (otherwise it lands with session_id=NULL and is
# invisible in the session-grouped audit view).
- turn_id = f"t-{uuid.uuid4().hex[:12]}"
+ # A caller-supplied id wins: the SSE route binds the turn at route
+ # level and must agree with us, or one turn splits across two ids.
+ # Every other entry point passes nothing and keeps its own id.
+ turn_id = turn_id or f"t-{uuid.uuid4().hex[:12]}"
t0 = time.monotonic()
full_response = ""
@@ -659,21 +663,27 @@ class Executive:
MIN_TURN_CHARS_FOR_EXTRACTION,
schedule_extraction,
)
- if len(full_response) + len(user_message) >= MIN_TURN_CHARS_FOR_EXTRACTION:
- schedule_extraction(user_message, full_response, session_id=session.session_id)
- # Mirror the completed exchange into Honcho so its server-side
- # extraction can update the peer card. Fire-and-forget; the
- # wrapper no-ops when person_id is None or Honcho is disabled.
- #
# Re-bind the audit ContextVars for the duration of these calls so
# the fire-and-forget tasks they schedule can snapshot the right
# session_id/turn_id (the main `with set_turn(...)` block above
# exited at the end of the `async for` so the ContextVars are back
- # to None by now). Without this wrapper, every sync_turn /
- # sync_department_turn audit row would land with session_id=NULL
- # and be invisible in the per-session audit view.
+ # to None by now). Without this wrapper, every extraction /
+ # sync_turn / sync_department_turn audit row would land with
+ # session_id=NULL and be invisible in the per-session audit view.
with set_turn(session_id=session.session_id, turn_id=turn_id):
+ # Inside the wrapper: schedule_extraction snapshots the vars at
+ # call time, so scheduling it out here would snapshot (None,
+ # None) and the memory_extractor's model call would record
+ # unattributed however correct the snapshot itself was.
+ if len(full_response) + len(user_message) >= MIN_TURN_CHARS_FOR_EXTRACTION:
+ schedule_extraction(
+ user_message, full_response, session_id=session.session_id
+ )
+
+ # Mirror the completed exchange into Honcho so its server-side
+ # extraction can update the peer card. Fire-and-forget; the
+ # wrapper no-ops when person_id is None or Honcho is disabled.
from openexecutive.memory.honcho_client import sync_turn as _honcho_sync
_honcho_sync(
user_message,
@@ -710,6 +720,7 @@ class Executive:
briefing_context: str = "",
channel_context_block: str = "",
page_context_block: str = "",
+ turn_id: str | None = None,
) -> AsyncIterator[str | dict[str, Any]]:
"""Committee-reviewed variant of stream_chat.
@@ -764,7 +775,10 @@ class Executive:
# Generated and bound BEFORE the Honcho prefetch so the peer_memory
# audit row inherits the turn link (else it lands with
# session_id=NULL and is invisible in the session-grouped view).
- turn_id = f"t-{uuid.uuid4().hex[:12]}"
+ # A caller-supplied id wins: the SSE route binds the turn at route
+ # level and must agree with us, or one turn splits across two ids.
+ # Every other entry point passes nothing and keeps its own id.
+ turn_id = turn_id or f"t-{uuid.uuid4().hex[:12]}"
# Stash on the function frame so the closing audit_log("committee_review")
# at the end of this function can carry the same turn_id.
_committee_turn_id = turn_id
diff --git a/packages/core/tests/unit/test_audit_context.py b/packages/core/tests/unit/test_audit_context.py
index dbf400a3..2633e39c 100644
--- a/packages/core/tests/unit/test_audit_context.py
+++ b/packages/core/tests/unit/test_audit_context.py
@@ -14,7 +14,7 @@ Context-independent.
from __future__ import annotations
import asyncio
-from collections.abc import AsyncIterator
+from unittest import mock
import pytest
@@ -92,3 +92,113 @@ def test_set_turn_exit_runs_even_on_exception() -> None:
assert get_active_ids() == ("leaky-s", "leaky-t")
raise RuntimeError("boom")
assert get_active_ids() == (None, None)
+
+
+# --------------------------------------------------------------------- #
+# Fire-and-forget actors must carry the scheduling turn with them
+# --------------------------------------------------------------------- #
+
+
+def test_schedule_extraction_carries_the_scheduling_turn() -> None:
+ """The memory_extractor's model call runs in a task spawned after the
+ caller's `with set_turn(...)` has exited, so the ids must be
+ snapshotted at scheduling time and re-bound inside the task. Without
+ that, every extraction row records with session_id=NULL."""
+ import asyncio
+
+ from openexecutive.audit.context import get_active_ids, set_turn
+ from openexecutive.memory import episodic
+
+ seen: list[tuple[str | None, str | None]] = []
+
+ async def _fake_extract(*_a: object, **_k: object) -> None:
+ seen.append(get_active_ids())
+
+ async def _go() -> None:
+ # Deliberately nested, not merged: the set_turn block must EXIT
+ # while the patch stays active, so the background task runs in
+ # exactly the unbound context it sees in production. Merging the two
+ # would keep the turn bound across the awaits and the test would
+ # pass without the fix.
+ with mock.patch.object(episodic, "_extract_and_store", _fake_extract):
+ with set_turn(session_id="s-1", turn_id="t-1"):
+ episodic.schedule_extraction("u", "a", session_id="s-1")
+ # The caller's block has exited — exactly the window in which
+ # the background task actually runs.
+ await asyncio.sleep(0)
+ await asyncio.sleep(0)
+
+ asyncio.run(_go())
+ assert seen == [("s-1", "t-1")]
+
+
+def test_schedule_evaluation_carries_the_scheduling_turn() -> None:
+ """Same contract for triage, which is a copy of the same pattern."""
+ from openexecutive.alerts import pipeline
+ from openexecutive.alerts.models import AlertEvent
+ from openexecutive.audit.context import get_active_ids, set_turn
+
+ seen: list[tuple[str | None, str | None]] = []
+
+ async def _fake_eval(*_a: object, **_k: object) -> None:
+ seen.append(get_active_ids())
+
+ async def _go() -> None:
+ with mock.patch.object(pipeline, "evaluate_and_dispatch", _fake_eval):
+ with set_turn(session_id="s-2", turn_id="t-2"):
+ pipeline.schedule_evaluation(
+ AlertEvent(source="test", external_id="e-1", title="t", body="b")
+ )
+ await asyncio.sleep(0)
+ await asyncio.sleep(0)
+
+ asyncio.run(_go())
+ assert seen == [("s-2", "t-2")]
+
+
+def test_out_of_turn_scheduling_stays_unattributed() -> None:
+ """A scheduler or monitor sweep with no turn bound must keep recording
+ (None, None) — those really are out-of-turn calls, and inventing an id
+ for them would mask the next regression of this kind."""
+ import asyncio
+
+ from openexecutive.audit.context import get_active_ids
+ from openexecutive.memory import episodic
+
+ seen: list[tuple[str | None, str | None]] = []
+
+ async def _fake_extract(*_a: object, **_k: object) -> None:
+ seen.append(get_active_ids())
+
+ async def _go() -> None:
+ with mock.patch.object(episodic, "_extract_and_store", _fake_extract):
+ episodic.schedule_extraction("u", "a", session_id="")
+ await asyncio.sleep(0)
+ await asyncio.sleep(0)
+
+ asyncio.run(_go())
+ assert seen == [(None, None)]
+
+
+def test_direct_extraction_does_not_clobber_an_ambient_turn() -> None:
+ """Awaiting the extractor directly from inside a live turn must keep
+ that turn's ids. Binding the snapshot unconditionally would overwrite
+ them with (None, None) — the very failure this plumbing exists to fix,
+ reintroduced from the other direction."""
+ from openexecutive.audit.context import get_active_ids, set_turn
+ from openexecutive.memory import episodic
+
+ seen: list[tuple[str | None, str | None]] = []
+
+ async def _fake_extract(*_a: object, **_k: object) -> None:
+ seen.append(get_active_ids())
+
+ async def _go() -> None:
+ with (
+ mock.patch.object(episodic, "_extract_and_store", _fake_extract),
+ set_turn(session_id="s-amb", turn_id="t-amb"),
+ ):
+ await episodic.extract_and_store("u", "a")
+
+ asyncio.run(_go())
+ assert seen == [("s-amb", "t-amb")]
diff --git a/packages/core/tests/unit/test_chat_route_turn_attribution.py b/packages/core/tests/unit/test_chat_route_turn_attribution.py
new file mode 100644
index 00000000..d8079305
--- /dev/null
+++ b/packages/core/tests/unit/test_chat_route_turn_attribution.py
@@ -0,0 +1,202 @@
+"""Every step of an SSE turn must record under the same session and turn.
+
+`_sse_body` drives the executive with `asyncio.wait_for`, which wraps each
+`__anext__()` in a fresh Task that copies the context at that moment. A
+`set_turn(...)` entered *inside* the executive's own async generator
+therefore lands in a throwaway per-step context and is gone by the next
+resume — so only the work done during step one carries a session and turn.
+Everything after it, which is the entire tool-call loop and the specialist
+fan-out, records with `(None, None)` and is invisible in the per-session
+audit view.
+
+The fix binds the turn in `event_generator`, the generator Starlette itself
+drives, so every resumed step inherits it.
+
+The contract pinned here:
+ 1. every resume step of the stream sees the same non-None (session, turn);
+ 2. the id the route logs is the id the executive uses — binding without
+ unifying them would split one turn across two ids, which is worse
+ than the all-NULL state it replaces;
+ 3. work scheduled from inside the stream (the fan-out's own tasks) still
+ inherits the binding, since a child task copies the live context;
+ 4. entry points that pass no turn_id keep generating their own.
+"""
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+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
+
+
[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()
+
+
+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.knowledge import retriever
+ from openexecutive.onboarding import profile_builder
+
+ monkeypatch.setattr(
+ profile_builder, "load_or_create_profile", lambda: CompanyProfile()
+ )
+ monkeypatch.setattr(retriever, "retrieve", lambda **_k: "")
+
+
+def _run_turn(
+ monkeypatch: pytest.MonkeyPatch, steps: int = 4
+) -> tuple[list[tuple[str | None, str | None]], list[str | None]]:
+ """Drive one real SSE turn; return what each resume step observed.
+
+ The fake executive records `get_active_ids()` immediately before each
+ yield, which is exactly where the real tool loop and specialist
+ fan-out do their recording.
+ """
+ from openexecutive.audit.context import get_active_ids
+ from openexecutive.orchestrator import executive as exec_mod
+
+ seen: list[tuple[str | None, str | None]] = []
+ received_turn_ids: list[str | None] = []
+
+ class _RecordingExecutive:
+ _THINKING = exec_mod.Executive._THINKING
+
+ def __init__(self, **_kwargs: Any) -> None:
+ pass
+
+ async def stream_chat(
+ self, *, turn_id: str | None = None, **_kwargs: Any
+ ) -> AsyncIterator[str]:
+ received_turn_ids.append(turn_id)
+ for i in range(steps):
+ seen.append(get_active_ids())
+ yield f"chunk-{i} "
+
+ monkeypatch.setattr(exec_mod, "Executive", _RecordingExecutive)
+
+ app = FastAPI()
+ app.include_router(chat_route.router)
+ client = TestClient(app)
+ resp = client.post("/chat", json={"message": "attribute this turn"})
+ assert resp.status_code == 200
+ return seen, received_turn_ids
+
+
+def test_every_resume_step_sees_the_same_session_and_turn(
+ temp_db: Path, patched_deps: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The regression itself.
+
+ Before the route-level bind, step one saw real ids and every later
+ step saw (None, None) — so the tool loop and the fan-out, which is
+ where nearly all of a turn's work happens, recorded unattributed.
+ """
+ seen, _ = _run_turn(monkeypatch, steps=4)
+
+ assert len(seen) == 4
+ assert all(sid is not None for sid, _ in seen), (
+ f"a resume step lost its session id: {seen}"
+ )
+ assert all(tid is not None for _, tid in seen), (
+ f"a resume step lost its turn id: {seen}"
+ )
+ assert len(set(seen)) == 1, (
+ f"steps disagreed about which turn they belong to: {set(seen)}"
+ )
+
+
+def test_route_and_executive_agree_on_the_turn_id(
+ temp_db: Path, patched_deps: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """Binding without unifying would be worse than the bug it fixes.
+
+ The route logs one id and the executive used to mint another, so a
+ turn would land half under each — fragmenting the audit view instead
+ of merely leaving it empty.
+ """
+ seen, received_turn_ids = _run_turn(monkeypatch, steps=2)
+
+ assert received_turn_ids and received_turn_ids[0] is not None, (
+ "the route must pass its own turn_id into the executive"
+ )
+ bound_turn_ids = {tid for _, tid in seen}
+ assert bound_turn_ids == {received_turn_ids[0]}
+
+
+def test_work_scheduled_mid_stream_inherits_the_binding(
+ temp_db: Path, patched_deps: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A task spawned from inside the stream copies the live context.
+
+ This is how the specialist fan-out records — if the binding were only
+ present on the driving task, `asyncio.gather` children would still
+ come out unattributed.
+ """
+ import asyncio
+
+ from openexecutive.audit.context import get_active_ids
+ from openexecutive.orchestrator import executive as exec_mod
+
+ from_child: list[tuple[str | None, str | None]] = []
+
+ class _FanOutExecutive:
+ _THINKING = exec_mod.Executive._THINKING
+
+ def __init__(self, **_kwargs: Any) -> None:
+ pass
+
+ async def stream_chat(self, **_kwargs: Any) -> AsyncIterator[str]:
+ yield "first "
+
+ async def _child() -> None:
+ from_child.append(get_active_ids())
+
+ await asyncio.gather(_child(), _child())
+ yield "second "
+
+ monkeypatch.setattr(exec_mod, "Executive", _FanOutExecutive)
+
+ app = FastAPI()
+ app.include_router(chat_route.router)
+ client = TestClient(app)
+ assert client.post("/chat", json={"message": "fan out"}).status_code == 200
+
+ assert len(from_child) == 2
+ for session_id, turn_id in from_child:
+ assert session_id is not None
+ assert turn_id is not None
+
+
+def test_turn_id_is_generated_when_the_caller_supplies_none() -> None:
+ """Slack, Discord, Telegram, email and the CLI pass nothing and must
+ keep minting their own — the parameter is additive, not required."""
+ import inspect
+
+ from openexecutive.orchestrator.executive import Executive
+
+ for fn in (Executive.stream_chat, Executive.stream_chat_with_committee):
+ param = inspect.signature(fn).parameters["turn_id"]
+ assert param.default is None, f"{fn.__name__} must not require turn_id"