Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
feat(context): live CloudEvents broadcast for the Context panel
trohitgec435ca3b266
diff --git a/CLAUDE.md b/CLAUDE.mdindex 32592f1a..5bdbd4f2 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1384,6 +1384,10 @@ The journal records, it never reconstructs. `agent.execute_llm_step` writes eachA Context thread exists only under an admitted generation (`generation > 0`), which only Start assigns — manual canvas Runs journal nothing by design. Each generation gets its own thread, so conversation does not carry across a Stop/Start. Workflow Reset rotates the thread to a fresh epoch and leaves prior events as archived history; the panel's journal view is scoped to the live epoch, or a reset looks like it did nothing.+**Live viewing is emitted at the persistence boundary, not per caller.** `AgentContextStore` is the one place every writer passes through (in-process loop, Temporal LLM activity, CLI-agent bridge), so it announces durable commits through a fanout registry in [`services/agent_context/listeners.py`](./server/services/agent_context/listeners.py) — `register_context_commit_listener` / `notify_context_commit` — and `nodes/context/__init__.py` registers the broadcaster. Same shape as the plugin registries, same reason: the store must never import `nodes/`. A new writer gets live updates for free. Three properties are load-bearing: the notification fires **after commit and after the ref reload** (never ahead of the state it describes); the **idempotent-replay path emits nothing** (a retried activity is not a state change); and a listener **can never fail a commit** — these commits run inside the Temporal LLM activity's heartbeat-silent post-send window under a 60 s `heartbeat_timeout` on a `maximum_attempts=1` policy, so a throwing or slow listener would fail a run over a UI notification. Epoch rotation is deliberately not routed through the store: `start_epoch`'s callers already emit `context.epoch.started` with a `reason` the store cannot know.++The three Context events (`context.updated` / `context.compacted` / `context.epoch.started`) **broadcast directly via `get_status_broadcaster()`, not through `services.events.dispatch.emit`** — `emit` runs a Temporal Visibility query to find workflow consumers, and no node type registers a canary consumer for `com.opencompany.context.*`, so that query is guaranteed to match nothing once per journal append. Payloads are identity + revision only; the panel refetches through the authorized `get_agent_context` handler, so the broadcast grants no read access on its own. Frontend consumption follows the `skill_lifecycle` precedent: three `case` labels in `WebSocketContext.tsx` invalidate `['agentContext']`, and the panel itself contains **no** subscription code. See [event_framework.md → UI-only lifecycle events](./docs-internal/event_framework.md).+**Memory** (`simpleMemory`, plugin `server/nodes/tool/simple_memory/`) is a `ToolNode` on `input-tools` — durable facts the agent explicitly remembers, recalls, updates and forgets. It is not conversation history and has no markdown surface; `SimpleMemoryParams` declares only `reset_policy` (with `extra="ignore"`, so leftover legacy keys on migrated graphs are inert). `reset_policy` is in `server_controlled_fields`, which stops the **model** overriding it through tool arguments — it does not stop the operator editing it.Lifecycle helpers live in `server/services/memory/`; token tracking and compaction thresholds are in **[Memory Compaction](./docs-internal/memory_compaction.md)**. **[Memory Lifecycle](./docs-internal/memory_lifecycle.md)** still documents the pre-RFC-0002 markdown model and is stale.diff --git a/RFC-0002-AGENT-CONTEXT-AND-MEMORY.md b/RFC-0002-AGENT-CONTEXT-AND-MEMORY.mdindex 378dc0cd..c3793b20 100644--- a/RFC-0002-AGENT-CONTEXT-AND-MEMORY.md+++ b/RFC-0002-AGENT-CONTEXT-AND-MEMORY.md@@ -321,6 +321,15 @@ context.epoch.startedmemory.changed```+`context.updated` is emitted from `AgentContextStore`'s commit boundary through+`services/agent_context/listeners.py`, so every writer is covered without+call-site code; `context.epoch.started` stays with `start_epoch`'s callers,+which own the `reason`. All three broadcast directly through the status+broadcaster rather than the Temporal event dispatcher — they have no workflow+consumers, so a Visibility query per journal append would buy nothing.+Notifications fire only after a durable commit, never on an idempotent replay,+and can never fail the commit that triggered them.+Authorized, paginated backend handlers fetch journal or Memory content ondemand. Provider bindings, signatures, recalled secrets, raw journal payloads,and Memory contents are excluded from workflow exports, logs, CloudEvents,diff --git a/client/src/components/output/OutputPanel.tsx b/client/src/components/output/OutputPanel.tsxindex 2eaa00a9..5cd019fb 100644--- a/client/src/components/output/OutputPanel.tsx+++ b/client/src/components/output/OutputPanel.tsx@@ -51,34 +51,6 @@ const TAG_VARIANT: Record<string, 'secondary' | 'info' | 'success'> = {agent_type: 'success',};-/** @uiw/react-json-view palette driven entirely by the active theme's- * --code-* tokens — no isDarkMode branch, so all 12 themes paint Raw JSON in- * their own syntax colors. The CSS vars re-resolve on theme switch (the- * data-theme attribute changes the --code-* values; no React re-render). */-const CODE_JSON_THEME = {- '--w-rjv-background-color': 'var(--code-bg)',- '--w-rjv-color': 'var(--code-text)',- '--w-rjv-key-string': 'var(--code-tag)',- '--w-rjv-line-color': 'var(--code-border)',- '--w-rjv-arrow-color': 'var(--code-gutter-fg)',- '--w-rjv-info-color': 'var(--code-comment)',- '--w-rjv-ellipsis-color': 'var(--code-comment)',- '--w-rjv-brackets-color': 'var(--code-punctuation)',- '--w-rjv-curlybraces-color': 'var(--code-punctuation)',- '--w-rjv-colon-color': 'var(--code-punctuation)',- '--w-rjv-quotes-color': 'var(--code-string)',- '--w-rjv-quotes-string-color': 'var(--code-string)',- '--w-rjv-type-string-color': 'var(--code-string)',- '--w-rjv-type-int-color': 'var(--code-number)',- '--w-rjv-type-float-color': 'var(--code-number)',- '--w-rjv-type-bigint-color': 'var(--code-number)',- '--w-rjv-type-boolean-color': 'var(--code-boolean)',- '--w-rjv-type-null-color': 'var(--code-number)',- '--w-rjv-type-nan-color': 'var(--code-number)',- '--w-rjv-type-undefined-color': 'var(--code-comment)',- '--w-rjv-type-date-color': 'var(--code-string)',-} as React.CSSProperties;-interface Props {results: ExecutionResult[];onClear?: () => void;@@ -193,20 +165,10 @@ export default function OutputPanel({ results, onClear, selectedNode }: Props) {{typeof response !== 'string' ? (// Object/array response — themed JSON viewer (same --code-*// palette as Raw JSON), not stringified-into-markdown.- <JsonView- value={response}- collapsed={2}- displayDataTypes={false}- style={CODE_JSON_THEME}- />+ <JsonView value={response} collapsed={2} displayDataTypes={false} />) : stdoutJson ? (// Terminal node whose stdout is itself JSON — tree view.- <JsonView- value={stdoutJson}- collapsed={2}- displayDataTypes={false}- style={CODE_JSON_THEME}- />+ <JsonView value={stdoutJson} collapsed={2} displayDataTypes={false} />) : isTerminal ? (// CLI text (uiHints.outputMode === 'terminal'): preformatted,// never markdown — `#` would become headings and indentation@@ -254,12 +216,7 @@ export default function OutputPanel({ results, onClear, selectedNode }: Props) {</button>}>- <JsonView- value={raw}- collapsed={2}- displayDataTypes={false}- style={CODE_JSON_THEME}- />+ <JsonView value={raw} collapsed={2} displayDataTypes={false} /></Section></div></div>diff --git a/client/src/components/parameterPanel/ContextPanel.tsx b/client/src/components/parameterPanel/ContextPanel.tsxindex 0351a482..3cb768a1 100644--- a/client/src/components/parameterPanel/ContextPanel.tsx+++ b/client/src/components/parameterPanel/ContextPanel.tsx@@ -1,5 +1,6 @@import React, { useMemo, useState } from 'react';import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';+import JsonView from '@uiw/react-json-view';import {Archive,ChevronLeft,@@ -12,6 +13,12 @@ import {} from 'lucide-react';import { toast } from 'sonner';+import {+ Accordion,+ AccordionContent,+ AccordionItem,+ AccordionTrigger,+} from '@/components/ui/accordion';import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';import { Badge } from '@/components/ui/badge';import { Button } from '@/components/ui/button';@@ -178,25 +185,17 @@ const ContextPanel: React.FC<ContextPanelProps> = ({ nodeId, workflowId }) => {onError: () => toast.error('Failed to export Context'),});- // ``null`` means the server could not compute pressure — it has no context- // window for this thread. Rendering that as 0% would claim an empty context- // window, which reads as healthy; the bar is hidden instead.- const pressurePercent = useMemo<number | null>(() => {- if (typeof snapshot.pressure_ratio === 'number') {- return Math.max(0, Math.min(100, snapshot.pressure_ratio * 100));- }- if (snapshot.active_token_count && snapshot.context_window) {- return Math.max(- 0,- Math.min(100, (snapshot.active_token_count / snapshot.context_window) * 100),- );- }- return null;- }, [- snapshot.active_token_count,- snapshot.context_window,- snapshot.pressure_ratio,- ]);+ // The server owns the pressure rule (it divides by the context window it+ // resolved, and sends null when it has none). This only scales the ratio for+ // <Progress>; re-deriving it from active_token_count / context_window here+ // would be a second copy of that rule, free to drift.+ const pressurePercent = useMemo<number | null>(+ () =>+ typeof snapshot.pressure_ratio === 'number'+ ? Math.max(0, Math.min(100, snapshot.pressure_ratio * 100))+ : null,+ [snapshot.pressure_ratio],+ );if (!workflowId) {return (@@ -355,49 +354,64 @@ const ContextPanel: React.FC<ContextPanelProps> = ({ nodeId, workflowId }) => {No committed Context events yet.</div>) : (- <div className="flex flex-col gap-2">- {snapshot.events!.map((event) => (- <details- key={`${event.sequence}:${event.operation_id || event.event_type}`}- className="rounded-md border border-border bg-card p-3"- >- <summary className="cursor-pointer text-sm">- <span className="font-mono text-xs text-muted-foreground">- #{event.sequence}- </span>{' '}- <span className="font-medium">{event.event_type}</span>- {event.provider && (- <Badge variant="outline" className="ml-2">- {event.provider}- </Badge>- )}- </summary>- <pre className="mt-3 max-h-80 overflow-auto whitespace-pre-wrap break-words rounded bg-muted p-3 text-xs">- {JSON.stringify(- event.message_wire_v2 ??- event.payload ?? {- payload_ref: event.payload_ref,- payload_hash: event.payload_hash,- operation_id: event.operation_id,- },- null,- 2,- )}- </pre>- </details>- ))}- </div>+ // Radix Accordion rather than <details>: it ships the+ // aria-expanded / keyboard semantics, and `type="multiple"`+ // keeps rows independently expandable.+ <Accordion type="multiple" className="flex flex-col gap-2">+ {snapshot.events!.map((event) => {+ const key = `${event.sequence}:${event.operation_id || event.event_type}`;+ return (+ <AccordionItem+ key={key}+ value={key}+ className="rounded-md border border-border bg-card p-3"+ >+ <AccordionTrigger className="gap-2 py-0 text-sm no-underline hover:no-underline">+ <span className="font-mono text-xs text-muted-foreground">+ #{event.sequence}+ </span>+ <span className="font-medium">{event.event_type}</span>+ {event.provider && (+ <Badge variant="outline">{event.provider}</Badge>+ )}+ </AccordionTrigger>+ <AccordionContent className="pt-3 pb-0">+ <JsonView+ value={+ (event.message_wire_v2 ??+ event.payload ?? {+ payload_ref: event.payload_ref,+ payload_hash: event.payload_hash,+ operation_id: event.operation_id,+ }) as object+ }+ collapsed={2}+ displayDataTypes={false}+ />+ </AccordionContent>+ </AccordionItem>+ );+ })}+ </Accordion>)}</TabsContent><TabsContent value="active" className="mt-2">{contextQuery.isLoading ? (<Loader2 className="h-5 w-5 animate-spin text-muted-foreground" />) : (- <pre className="max-h-[32rem] overflow-auto whitespace-pre-wrap break-words rounded-md border border-border bg-muted p-4 text-xs">- {snapshot.active_replay- ? JSON.stringify(snapshot.active_replay, null, 2)- : 'No active replay is available.'}- </pre>+ snapshot.active_replay ? (+ <div className="rounded-md border border-border bg-card p-3">+ <JsonView+ value={snapshot.active_replay as object}+ collapsed={3}+ displayDataTypes={false}+ />+ </div>+ ) : (+ <div className="rounded-md border border-dashed border-border p-8 text-center text-sm text-muted-foreground">+ No active replay is available.+ </div>+ ))}</TabsContent></Tabs>diff --git a/client/src/contexts/WebSocketContext.tsx b/client/src/contexts/WebSocketContext.tsxindex 952848a8..3eeb451f 100644--- a/client/src/contexts/WebSocketContext.tsx+++ b/client/src/contexts/WebSocketContext.tsx@@ -1063,6 +1063,21 @@ export const WebSocketProvider: React.FC<{ children: React.ReactNode }> = ({ chibreak;}+ case 'context.updated':+ case 'context.compacted':+ case 'context.epoch.started': {+ // CloudEvents-typed Context journal lifecycle from+ // server/nodes/context/_events.py, emitted by the store after every+ // durable commit. The payload is identity + revision only, so the+ // panel refetches through the authorized `get_agent_context` handler+ // rather than reading transcript content off a broadcast that+ // reaches every connected client. Prefix invalidation: only a+ // mounted ContextPanel has an active observer, so this is a no-op+ // for everyone else.+ void queryClient.invalidateQueries({ queryKey: ['agentContext'] });+ break;+ }+case 'todos_updated': {// CloudEvents-typed todo-list change from// server/nodes/tool/write_todos/_events.py, emitted via thediff --git a/client/src/index.css b/client/src/index.cssindex 83772513..1ec61b7f 100644--- a/client/src/index.css+++ b/client/src/index.css@@ -358,6 +358,41 @@ html {.console-json-output .token.punctuation { color: var(--code-punctuation); }.console-json-output .token.operator { color: var(--code-operator); }+/* ----------------------------------------------------------------------------+ * @uiw/react-json-view — palette mapped onto the theme's --code-* tokens.+ *+ * The library reads every colour as `var(--w-rjv-*, <fallback>)` (see its+ * esm/index.js), so its documented theming API is plain CSS custom properties.+ * Declaring them here rather than passing one of its bundled theme objects+ * through the `style` prop means: every <JsonView> in the app is themed with no+ * per-call-site code, and all 12 themes repaint on `data-theme` change through+ * the normal cascade instead of a React re-render.+ * -------------------------------------------------------------------------- */++:root {+ --w-rjv-background-color: var(--code-bg);+ --w-rjv-color: var(--code-text);+ --w-rjv-key-string: var(--code-tag);+ --w-rjv-line-color: var(--code-border);+ --w-rjv-arrow-color: var(--code-gutter-fg);+ --w-rjv-info-color: var(--code-comment);+ --w-rjv-ellipsis-color: var(--code-comment);+ --w-rjv-brackets-color: var(--code-punctuation);+ --w-rjv-curlybraces-color: var(--code-punctuation);+ --w-rjv-colon-color: var(--code-punctuation);+ --w-rjv-quotes-color: var(--code-string);+ --w-rjv-quotes-string-color: var(--code-string);+ --w-rjv-type-string-color: var(--code-string);+ --w-rjv-type-int-color: var(--code-number);+ --w-rjv-type-float-color: var(--code-number);+ --w-rjv-type-bigint-color: var(--code-number);+ --w-rjv-type-boolean-color: var(--code-boolean);+ --w-rjv-type-null-color: var(--code-number);+ --w-rjv-type-nan-color: var(--code-number);+ --w-rjv-type-undefined-color: var(--code-comment);+ --w-rjv-type-date-color: var(--code-string);+}+.chat-markdown p { margin: 0 0 8px 0; }.chat-markdown p:last-child { margin-bottom: 0; }.chat-markdown h1,diff --git a/docs-internal/event_framework.md b/docs-internal/event_framework.mdindex edecc356..1dee2654 100644--- a/docs-internal/event_framework.md+++ b/docs-internal/event_framework.md@@ -225,6 +225,63 @@ live in `nodes/<plugin>/_events.py`. Cross-cutting factoriesSee RFC §6.4 for the classification rule + the canonical`telegram/_events.py` example.+### UI-only lifecycle events broadcast directly, never through `emit`++`dispatch.emit` exists to reach **Temporal consumers**: it runs a Visibility+`ListWorkflowExecutions` query to find running listeners, then broadcasts+in-process as a side effect. That query is only worth paying for when some node+type registered the event via `register_canary_trigger_type`.++The Context lifecycle events (`context.updated` / `context.compacted` /+`context.epoch.started`, in `nodes/context/_events.py`) have no canary consumer,+so the query is guaranteed to match nothing — once per journal append. They call+`get_status_broadcaster().broadcast({...})` directly instead, which is the same+pattern `nodes/telegram/_events.py` uses for status. The CloudEvents envelope,+`source`, `type`, `subject` and `data` are identical either way, so the wire+contract the frontend sees does not change.++Rule of thumb: **if no `register_canary_trigger_type` call names your event+type, broadcast it directly.** Reach for `emit` only when a Temporal workflow+has to receive it. `tests/nodes/test_context_events.py` locks this for Context+by parsing the module's imports (AST, not grep, so the docstring can explain+the reasoning without tripping the assertion).++### Context events are emitted at the persistence boundary++`AgentContextStore` is the one place every Context writer passes through — the+in-process agent loop, the Temporal LLM activity, and the CLI-agent bridge all+reach durable state through it. So the "thread advanced" notification is emitted+there rather than at each call site, via a fanout registry in+`services/agent_context/listeners.py`:++```python+register_context_commit_listener(async_fn) # nodes/context/__init__.py+await notify_context_commit(ref, provider=..., active_token_count=..., sequence=...)+```++Same shape as the plugin registries in `plugin_system.md`, and for the same+reason: the store must never import `nodes/`. A new writer gets live updates for+free, and no caller carries broadcast code.++Three properties are load-bearing and have tests in+`tests/services/agent_context/test_commit_listeners.py`:++- **After commit, after reload.** The notification carries the post-commit+ revision and can never be observed ahead of the state it describes.+- **Replays emit nothing.** `append_transition` returns early on a reused+ `operation_id` without committing; broadcasting there would wake every open+ panel for something that did not happen.+- **A listener can never fail a commit.** `notify_context_commit` swallows and+ logs. These commits run inside the Temporal LLM activity's post-send window,+ which is heartbeat-silent under a 60 s `heartbeat_timeout` on a+ `maximum_attempts=1` retry policy — a throwing or slow listener there would+ fail a run over a UI notification.++Epoch rotation is deliberately **not** routed through the store listener:+`start_epoch`'s callers already emit `context.epoch.started` with a `reason`+(`clear` / `fork` / `workflow_reset`) the store cannot know, so emitting from+the store would both duplicate the broadcast and lose the reason.+## VerificationEach Phase-A milestone has a verification command:diff --git a/docs-internal/status_broadcaster.md b/docs-internal/status_broadcaster.mdindex a31c7709..dda9311d 100644--- a/docs-internal/status_broadcaster.md+++ b/docs-internal/status_broadcaster.md@@ -143,6 +143,22 @@ Broadcasts are sent to all connected clients without a request-response correlat| `token_usage_update` | AI execution updates token counters | `{session_id, data: {total, threshold, needs_compaction}}` || `compaction_starting` | Memory compaction begins | `{session_id, node_id}` || `compaction_completed` | Memory compaction ends | `{session_id, success, tokens_before, tokens_after}` |+| `context.updated` | `AgentContextStore` durably advanced a Context thread (journal append or pressure write) — emitted from the store's commit boundary via `register_context_commit_listener`, so every writer (in-process loop, Temporal LLM activity, CLI-agent bridge) is covered without call-site code. Frontend invalidates `['agentContext']`. | `{specversion: "1.0", id, source: "opencompany://nodes/context", type: "com.opencompany.context.updated", subject: context_node_id, time, data: {workflow_id, context_node_id, thread_id, epoch, revision, provider, active_token_count, sequence?}}` |+| `context.compacted` | Context checkpoint activated (in-process finalize) | as above plus `{strategy, covers_through_sequence}` |+| `context.epoch.started` | Epoch rotated — emitted by `start_epoch`'s **callers**, not the store, because only they know the `reason` (`clear` / `fork` / `workflow_reset`) | as above plus `{reason}` |++The three `context.*` events call `get_status_broadcaster().broadcast(...)`+directly rather than `services.events.dispatch.emit`. `emit` exists to reach+Temporal consumers and pays a Visibility `ListWorkflowExecutions` query to find+them; no node type registers a canary consumer for `com.opencompany.context.*`,+so that query can only ever match nothing — once per journal append. Same+pattern as `nodes/telegram/_events.py`. See+[event_framework.md → UI-only lifecycle events](./event_framework.md).++Payloads are identity + revision only — no message bodies, no provider state —+because `_broadcast_in_process` fans out to **every** connected socket with no+per-workflow filtering. The Context panel refetches through the authorized+`get_agent_context` handler, which is where ownership is enforced.## Execution correlation IDsdiff --git a/server/nodes/context/__init__.py b/server/nodes/context/__init__.pyindex f3558d38..685dac27 100644--- a/server/nodes/context/__init__.py+++ b/server/nodes/context/__init__.py@@ -204,12 +204,16 @@ __all__ = [# Context panel commands are plugin-owned side channels. The node class above# stays passive; all durable logic lives in AgentContextStore.+from services.agent_context.listeners import ( # noqa: E402+ register_context_commit_listener,+)from services.plugin.edge_walker import ( # noqa: E402register_agent_context_builder,)from services.ws_handler_registry import register_ws_handlers # noqa: E402from ._descriptor import build_agent_context_descriptor # noqa: E402+from ._events import on_context_commit # noqa: E402from ._handlers import WS_HANDLERS # noqa: E402register_ws_handlers(WS_HANDLERS)@@ -217,3 +221,7 @@ register_ws_handlers(WS_HANDLERS)# node's parameters or thread-selection rules; it calls whatever is# registered here.register_agent_context_builder(build_agent_context_descriptor)+# The store announces durable commits; this plugin decides they are worth a+# `context.updated` broadcast. Registering here keeps the store free of any+# knowledge that a UI exists.+register_context_commit_listener(on_context_commit)diff --git a/server/nodes/context/_events.py b/server/nodes/context/_events.pyindex a4f72682..398809a5 100644--- a/server/nodes/context/_events.py+++ b/server/nodes/context/_events.py@@ -1,9 +1,23 @@-"""Metadata-only Context lifecycle events."""+"""Metadata-only Context lifecycle events.++These are UI lifecycle notifications, not workflow triggers. No node type+registers a canary consumer for ``com.opencompany.context.*``, so routing them+through ``services.events.dispatch.emit`` would run a Temporal Visibility+``ListWorkflowExecutions`` query that is guaranteed to match nothing -- once per+journal append. They are broadcast straight to connected WebSocket clients+instead, which is the canonical plugin pattern (see ``nodes/telegram/_events.py``).++The payload is identity + version only. It carries no message bodies and no+provider state, because the broadcast fans out to every connected socket; the+panel refetches through the authorized ``get_agent_context`` handler, which is+where ownership is enforced.+"""from __future__ import annotations-from typing import Optional+from typing import Any, Dict, Optional+from models.agent_context import AgentContextReffrom services.events.envelope import WorkflowEvent@@ -16,21 +30,27 @@ def context_updated(revision: int,provider: Optional[str],active_token_count: int,+ sequence: Optional[int] = None,) -> WorkflowEvent:+ data: Dict[str, Any] = {+ "workflow_id": workflow_id,+ "context_node_id": context_node_id,+ "thread_id": thread_id,+ "epoch": epoch,+ "revision": revision,+ "provider": provider,+ "active_token_count": max(0, active_token_count),+ }+ if sequence is not None:+ # Lets the panel show "N new events" on the paginated journal view+ # without refetching a page it is not currently looking at.+ data["sequence"] = sequencereturn WorkflowEvent(source="opencompany://nodes/context",type="com.opencompany.context.updated",subject=context_node_id,workflow_id=workflow_id,- data={- "workflow_id": workflow_id,- "context_node_id": context_node_id,- "thread_id": thread_id,- "epoch": epoch,- "revision": revision,- "provider": provider,- "active_token_count": max(0, active_token_count),- },+ data=data,)@@ -92,33 +112,77 @@ def context_epoch_started()-async def dispatch_context_epoch_started(**metadata) -> None:- from services.events.dispatch import emit+async def _broadcast(event: WorkflowEvent, *, wire_routing_key: str) -> None:+ """Send one CloudEvents envelope to connected clients.++ Deliberately not ``services.events.dispatch.emit`` -- see the module+ docstring. The envelope, ``source``, ``type``, ``subject`` and ``data`` are+ identical either way, so the wire contract the frontend sees is unchanged.+ """- await emit(+ from services.status_broadcaster import get_status_broadcaster++ await get_status_broadcaster().broadcast(+ {+ "type": wire_routing_key,+ "data": event.model_dump(mode="json", exclude_none=True),+ }+ )+++async def dispatch_context_epoch_started(**metadata) -> None:+ await _broadcast(context_epoch_started(**metadata),wire_routing_key="context.epoch.started",)async def dispatch_context_updated(**metadata) -> None:- from services.events.dispatch import emit-- await emit(+ await _broadcast(context_updated(**metadata),wire_routing_key="context.updated",)async def dispatch_context_compacted(**metadata) -> None:- from services.events.dispatch import emit-- await emit(+ await _broadcast(context_compacted(**metadata),wire_routing_key="context.compacted",)+async def on_context_commit(+ *,+ ref: AgentContextRef,+ provider: Optional[str],+ active_token_count: int,+ sequence: Optional[int] = None,+) -> None:+ """Turn a durable store commit into a ``context.updated`` broadcast.++ Registered with ``register_context_commit_listener`` from the package+ ``__init__``, so every writer that reaches durable state -- the in-process+ agent loop, the Temporal LLM activity, the CLI-agent bridge -- produces a+ live update with no code at the call site.++ Epoch rotation is deliberately not routed here. ``start_epoch``'s callers+ already emit ``context.epoch.started`` carrying a ``reason``+ (``clear`` / ``fork`` / ``workflow_reset``) that the store cannot know, so a+ store-level emit would both duplicate the broadcast and lose the reason.+ """++ await dispatch_context_updated(+ workflow_id=ref.workflow_id,+ context_node_id=ref.context_node_id,+ thread_id=ref.thread_id,+ epoch=ref.epoch,+ revision=ref.revision,+ provider=provider,+ active_token_count=active_token_count,+ sequence=sequence,+ )++__all__ = ["context_compacted","context_epoch_started",@@ -126,4 +190,5 @@ __all__ = ["dispatch_context_compacted","dispatch_context_epoch_started","dispatch_context_updated",+ "on_context_commit",]diff --git a/server/nodes/context/_handlers.py b/server/nodes/context/_handlers.pyindex 98e0995b..1e16f0f6 100644--- a/server/nodes/context/_handlers.py+++ b/server/nodes/context/_handlers.py@@ -342,7 +342,7 @@ async def handle_get_agent_context(workflow_id=str(data["workflow_id"]),context_node_id=str(data["context_node_id"]),generation=generation,- include_archived=False,+ include_archived=bool(data.get("include_archived")),)requested_thread = str(data.get("thread_id") or "")thread = next(diff --git a/server/services/agent_context/listeners.py b/server/services/agent_context/listeners.pynew file mode 100644index 00000000..1884cd11--- /dev/null+++ b/server/services/agent_context/listeners.py@@ -0,0 +1,95 @@+"""Commit notifications for durable Context state changes.++The store is the one place that knows a Context thread advanced, and it is+the only place every writer passes through -- the in-process agent loop, the+Temporal LLM activity, and the CLI-agent bridge all reach durable state via+:class:`~services.agent_context.store.AgentContextStore`. Emitting the+"thread advanced" notification here rather than at each call site means a new+writer gets live UI updates for free and no caller carries broadcast code.++Layering: the store must never import ``nodes/`` (plugin self-containment).+So this module owns a fanout registry and the Context plugin registers its+broadcaster from ``nodes/context/__init__.py``, exactly like the other+plugin-owned registries (``register_service_refresh``,+``register_output_schema``, ...).++Contract, and it is load-bearing: :func:`notify_context_commit` is+best-effort. It never raises, never rolls back the commit that triggered it,+and never blocks on anything slower than an in-process broadcast. These+commits happen inside the Temporal LLM activity's post-send window, which is+heartbeat-silent under a 60s ``heartbeat_timeout`` on a ``maximum_attempts=1``+retry policy -- an expensive or throwing listener there would fail a run over+a UI notification.+"""++from __future__ import annotations++from typing import Awaitable, Callable, List, Optional++from core.logging import get_logger+from models.agent_context import AgentContextRef+from services.plugin.registry import IdempotentList++logger = get_logger(__name__)++ContextCommitListener = Callable[..., Awaitable[None]]++_LISTENERS: List[ContextCommitListener] = []+_FANOUT: IdempotentList[ContextCommitListener] = IdempotentList(+ "agent_context_commit",+ items=_LISTENERS,+)+++def register_context_commit_listener(listener: ContextCommitListener) -> None:+ """Register a callback fired after a Context thread durably advances.++ Idempotent on re-import (registering the same callable twice is a no-op).+ Listeners are invoked with keyword arguments only, so adding a field later+ does not break an existing listener.+ """++ _FANOUT.register(listener)+++async def notify_context_commit(+ ref: AgentContextRef,+ *,+ provider: Optional[str],+ active_token_count: int,+ sequence: Optional[int] = None,+) -> None:+ """Announce that ``ref`` now points at newly committed durable state.++ Call this only *after* a successful commit and *after* reloading the ref,+ so the notification can never be observed ahead of the state it describes+ and always carries the post-commit revision.++ Never call it on the idempotent-replay path: a replay is not a state+ change, and waking the UI for one produces a phantom update.+ """++ if not _LISTENERS:+ return++ for listener in list(_LISTENERS):+ try:+ await listener(+ ref=ref,+ provider=provider,+ active_token_count=active_token_count,+ sequence=sequence,+ )+ except Exception: # noqa: BLE001 -- a notification may never fail a commit+ logger.debug(+ "Context commit listener failed",+ listener=getattr(listener, "__qualname__", repr(listener)),+ exc_info=True,+ )+++__all__ = [+ "ContextCommitListener",+ "notify_context_commit",+ "register_context_commit_listener",+]diff --git a/server/services/agent_context/store.py b/server/services/agent_context/store.pyindex b37446ff..6154fed1 100644--- a/server/services/agent_context/store.py+++ b/server/services/agent_context/store.py@@ -33,6 +33,7 @@ from models.agent_context import (ContextThreadKind,)from models.database import RuntimeMutation+from services.agent_context.listeners import notify_context_commitfrom services.llm.protocol import (MESSAGE_WIRE_VERSION,message_from_wire,@@ -507,6 +508,16 @@ class AgentContextStore:await session.rollback()continueupdated = await self._load_ref(ref)+ # After commit and after the reload, so the notification can+ # never be observed ahead of the state it announces. The+ # idempotent-replay path above returns before reaching here:+ # a replay is not a state change.+ await notify_context_commit(+ updated,+ provider=provider or thread.provider,+ active_token_count=int(thread.active_token_count or 0),+ sequence=sequence,+ )return AgentContextAppendResult(ref=updated,event=_to_event(event),@@ -582,7 +593,13 @@ class AgentContextStore:except IntegrityError:await session.rollback()continue- return await self._load_ref(ref)+ updated = await self._load_ref(ref)+ await notify_context_commit(+ updated,+ provider=thread.provider,+ active_token_count=active_token_count,+ )+ return updatedraise RevisionConflictError("context_pressure_update_conflict")async def prepare_compaction(diff --git a/server/tests/nodes/test_context_events.py b/server/tests/nodes/test_context_events.pynew file mode 100644index 00000000..04824524--- /dev/null+++ b/server/tests/nodes/test_context_events.py@@ -0,0 +1,235 @@+"""Wire contract for Context lifecycle events.++Two rules are locked here.++1. Context events are UI notifications, not workflow triggers. No node type+ registers a canary consumer for ``com.opencompany.context.*``, so routing+ them through ``services.events.dispatch.emit`` would run a Temporal+ Visibility query that is guaranteed to match nothing -- once per journal+ append. They broadcast directly instead.+2. The payload stays identity-only. The broadcast fans out to every connected+ socket, so a message body or provider state leaking in here would be a+ disclosure bug, not a display bug.+"""++from __future__ import annotations++import ast+import inspect+import re+from pathlib import Path++import pytest++from models.agent_context import AgentContextRef+from nodes.context import _events as context_events+++def _imported_modules(module) -> set[str]:+ """Modules actually imported by ``module``, ignoring prose.++ Parsed rather than grepped so the module docstring can explain *why*+ ``dispatch.emit`` is avoided without tripping the assertion.+ """++ tree = ast.parse(inspect.getsource(module))+ names: set[str] = set()+ for node in ast.walk(tree):+ if isinstance(node, ast.ImportFrom) and node.module:+ names.add(node.module)+ elif isinstance(node, ast.Import):+ names.update(alias.name for alias in node.names)+ return names+++def test_dispatchers_do_not_run_a_visibility_query():+ imported = _imported_modules(context_events)+ assert "services.events.dispatch" not in imported, (+ "Context events must not route through dispatch.emit -- it runs a "+ "Temporal Visibility query per call and no canary consumer exists "+ "for com.opencompany.context.*. Broadcast directly instead."+ )+ assert "services.status_broadcaster" in imported+++ "factory, expected_type",+ [+ ("context_updated", "com.opencompany.context.updated"),+ ("context_compacted", "com.opencompany.context.compacted"),+ ("context_epoch_started", "com.opencompany.context.epoch.started"),+ ],+)+def test_cloudevents_envelope_shape(factory, expected_type):+ kwargs = {+ "workflow_id": "workflow-1",+ "context_node_id": "workflow-1:context:1",+ "thread_id": "session:abc",+ "epoch": 3,+ "revision": 12,+ "provider": "anthropic",+ }+ if factory == "context_updated":+ kwargs["active_token_count"] = 42+ elif factory == "context_compacted":+ kwargs.update(+ active_token_count=42,+ strategy="portable",+ covers_through_sequence=7,+ )+ else:+ kwargs["reason"] = "clear"++ event = getattr(context_events, factory)(**kwargs)++ assert event.type == expected_type+ assert event.source == "opencompany://nodes/context"+ assert event.subject == "workflow-1:context:1"+ assert event.data["context_node_id"] == "workflow-1:context:1"+++def test_updated_payload_carries_identity_only():+ event = context_events.context_updated(+ workflow_id="workflow-1",+ context_node_id="workflow-1:context:1",+ thread_id="session:abc",+ epoch=1,+ revision=9,+ provider="anthropic",+ active_token_count=100,+ sequence=17,+ )++ assert event.data["sequence"] == 17+ # Anything not in this set would be broadcast to every connected client.+ assert set(event.data) == {+ "workflow_id",+ "context_node_id",+ "thread_id",+ "epoch",+ "revision",+ "provider",+ "active_token_count",+ "sequence",+ }+++def test_sequence_is_omitted_when_absent():+ event = context_events.context_updated(+ workflow_id="workflow-1",+ context_node_id="workflow-1:context:1",+ thread_id="session:abc",+ epoch=1,+ revision=9,+ provider=None,+ active_token_count=0,+ )++ assert "sequence" not in event.data+++def test_negative_token_counts_are_clamped():+ event = context_events.context_updated(+ workflow_id="workflow-1",+ context_node_id="workflow-1:context:1",+ thread_id="session:abc",+ epoch=1,+ revision=1,+ provider=None,+ active_token_count=-5,+ )++ assert event.data["active_token_count"] == 0+++async def test_commit_listener_broadcasts_context_updated(monkeypatch):+ sent: list = []++ async def _capture(**metadata):+ sent.append(metadata)++ monkeypatch.setattr(+ context_events, "dispatch_context_updated", _capture+ )++ ref = AgentContextRef(+ workflow_id="workflow-1",+ context_node_id="workflow-1:context:1",+ generation=2,+ thread_id="session:abc",+ epoch=3,+ revision=11,+ )+ await context_events.on_context_commit(+ ref=ref,+ provider="anthropic",+ active_token_count=64,+ sequence=5,+ )++ assert sent == [+ {+ "workflow_id": "workflow-1",+ "context_node_id": "workflow-1:context:1",+ "thread_id": "session:abc",+ "epoch": 3,+ "revision": 11,+ "provider": "anthropic",+ "active_token_count": 64,+ "sequence": 5,+ }+ ]+++def test_frontend_handles_every_emitted_wire_key():+ """The panel goes live only if the frontend switches on these keys.++ Same direction as tests/test_frontend_no_node_type_copies.py: the backend+ owns the wire key, and renaming one here would otherwise silently stop the+ Context panel refreshing with no test failing anywhere.+ """++ source = inspect.getsource(context_events)+ emitted = set(re.findall(r'wire_routing_key="([^"]+)"', source))+ assert emitted == {+ "context.updated",+ "context.compacted",+ "context.epoch.started",+ }++ ws_context = (+ Path(__file__).resolve().parents[3]+ / "client"+ / "src"+ / "contexts"+ / "WebSocketContext.tsx"+ )+ if not ws_context.exists(): # server-only checkouts+ pytest.skip("client sources not present")+ consumed = ws_context.read_text(encoding="utf-8")+ for key in sorted(emitted):+ assert f"case '{key}'" in consumed, (+ f"{key} is broadcast by nodes/context/_events.py but no case "+ f"handles it in WebSocketContext.tsx -- the Context panel would "+ f"silently stop updating."+ )+++def test_store_never_imports_the_plugin():+ from services.agent_context import store++ source = inspect.getsource(store)+ assert "nodes." not in source and "from nodes" not in source, (+ "The store must stay free of plugin knowledge; the Context plugin "+ "registers its broadcaster via register_context_commit_listener."+ )+++def test_plugin_registers_its_commit_listener():+ import nodes.context as context_plugin+ from services.agent_context import listeners++ source = inspect.getsource(context_plugin)+ assert "register_context_commit_listener" in source+ assert context_events.on_context_commit in list(listeners._LISTENERS)diff --git a/server/tests/services/agent_context/test_commit_listeners.py b/server/tests/services/agent_context/test_commit_listeners.pynew file mode 100644index 00000000..40a8c40e--- /dev/null+++ b/server/tests/services/agent_context/test_commit_listeners.py@@ -0,0 +1,231 @@+"""Contract for the Context commit-notification fanout.++The store is the single place every Context writer passes through, so it is+where the "thread advanced" notification is emitted. These tests lock the+three properties that make that safe:++* a notification is emitted only after durable commit, carrying post-commit state+* an idempotent replay emits nothing (a replay is not a state change)+* a failing listener can never fail, slow, or roll back the commit+"""++from __future__ import annotations++import importlib.util+import sys+import uuid+from pathlib import Path+from types import SimpleNamespace++import pytest++from models.agent_context import AgentContextRef+from services.agent_context import AgentContextStore+from services.agent_context import listeners as listener_module+from services.llm.protocol import Message, message_to_wire+++async def context_database():+ # Mirrors tests/services/agent_context/test_store.py: the root conftest+ # stubs core.database for fast plugin tests, so load the real module+ # privately for transaction coverage.+ module_name = f"tests._commit_listener_database_{uuid.uuid4().hex}"+ spec = importlib.util.spec_from_file_location(+ module_name,+ Path(__file__).resolve().parents[3] / "core" / "database.py",+ )+ assert spec is not None and spec.loader is not None+ module = importlib.util.module_from_spec(spec)+ sys.modules[module_name] = module+ spec.loader.exec_module(module)++ db_path = Path.cwd() / f".commit-listener-{uuid.uuid4().hex}.db"+ settings = SimpleNamespace(+ database_url=f"sqlite+aiosqlite:///{db_path.as_posix()}",+ database_echo=False,+ database_pool_size=5,+ database_max_overflow=5,+ )+ database = module.Database(settings)+ await database.startup()+ try:+ yield database+ finally:+ await database.shutdown()+ sys.modules.pop(module_name, None)+ for candidate in (+ db_path,+ Path(f"{db_path}-wal"),+ Path(f"{db_path}-shm"),+ ):+ candidate.unlink(missing_ok=True)+++def isolated_listeners():+ """Swap the process-wide fanout for an empty one, then restore it.++ The Context plugin registers its broadcaster at import time, so without+ this every test in this file would also hit a real WebSocket broadcast.+ """++ original = list(listener_module._LISTENERS)+ listener_module._LISTENERS.clear()+ try:+ yield listener_module+ finally:+ listener_module._LISTENERS.clear()+ listener_module._LISTENERS.extend(original)+++def _wire(content: str) -> dict:+ return dict(message_to_wire(Message(role="assistant", content=content)))+++async def _resolve(store: AgentContextStore, **overrides) -> AgentContextRef:+ values = {+ "workflow_id": "workflow-1",+ "context_node_id": "workflow-1:context:1",+ "generation": 2,+ "execution_id": "execution-1",+ }+ values.update(overrides)+ return await store.resolve_thread(**values)+++def _recorder(sink: list) -> callable:+ async def _listener(**kwargs):+ sink.append(kwargs)++ return _listener+++async def test_append_notifies_with_post_commit_state(+ context_database, isolated_listeners+):+ store = AgentContextStore(context_database)+ ref = await _resolve(store)+ seen: list = []+ isolated_listeners.register_context_commit_listener(_recorder(seen))++ result = await store.append_transition(+ ref,+ event_type="message.assistant",+ operation_id="op-1",+ message_wire_v2=_wire("hello"),+ provider="anthropic",+ )++ assert result.applied is True+ assert len(seen) == 1+ notified = seen[0]+ # The notification must describe committed state, never a projection of+ # it: same revision the caller got back, and the sequence just written.+ assert notified["ref"] == result.ref+ assert notified["ref"].revision == result.ref.revision+ assert notified["provider"] == "anthropic"+ assert notified["sequence"] == result.event.sequence+++async def test_idempotent_replay_emits_nothing(+ context_database, isolated_listeners+):+ store = AgentContextStore(context_database)+ ref = await _resolve(store)+ seen: list = []+ isolated_listeners.register_context_commit_listener(_recorder(seen))++ wire = _wire("hello")+ first = await store.append_transition(+ ref,+ event_type="message.assistant",+ operation_id="op-replay",+ message_wire_v2=wire,+ )+ replay = await store.append_transition(+ ref,+ event_type="message.assistant",+ operation_id="op-replay",+ message_wire_v2=wire,+ )++ assert first.applied is True+ assert replay.applied is False+ # A retried activity is not a state change. Broadcasting here would wake+ # every open panel for something that did not happen.+ assert len(seen) == 1+++async def test_listener_failure_cannot_fail_the_commit(+ context_database, isolated_listeners+):+ store = AgentContextStore(context_database)+ ref = await _resolve(store)++ async def _explode(**_kwargs):+ raise RuntimeError("listener is broken")++ survived: list = []+ isolated_listeners.register_context_commit_listener(_explode)+ isolated_listeners.register_context_commit_listener(_recorder(survived))++ result = await store.append_transition(+ ref,+ event_type="message.assistant",+ operation_id="op-boom",+ message_wire_v2=_wire("hello"),+ )++ # The commit stands, and one broken listener does not starve the others.+ assert result.applied is True+ assert len(survived) == 1+ active = await store.load_active(result.ref)+ assert len(active.tail) == 1+++async def test_pressure_update_notifies_once_per_commit(+ context_database, isolated_listeners+):+ store = AgentContextStore(context_database)+ ref = await _resolve(store)+ seen: list = []+ isolated_listeners.register_context_commit_listener(_recorder(seen))++ updated = await store.record_active_pressure(+ ref,+ operation_id="pressure-1",+ active_token_count=1234,+ )+ await store.record_active_pressure(+ ref,+ operation_id="pressure-1",+ active_token_count=1234,+ )++ assert len(seen) == 1+ assert seen[0]["active_token_count"] == 1234+ assert seen[0]["ref"].revision == updated.revision+ # Pressure is not a journal append, so there is no sequence to report.+ assert seen[0]["sequence"] is None+++async def test_no_listeners_registered_is_a_no_op(+ context_database, isolated_listeners+):+ store = AgentContextStore(context_database)+ ref = await _resolve(store)++ result = await store.append_transition(+ ref,+ event_type="message.assistant",+ operation_id="op-quiet",+ message_wire_v2=_wire("hello"),+ )++ assert result.applied is True