Skip to content

Self-improving AI Employees for everyone

feat(context): live CloudEvents broadcast for the Context panel

trohitgec435ca3b266
diff --git a/CLAUDE.md b/CLAUDE.md
index 32592f1a..5bdbd4f2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1384,6 +1384,10 @@ The journal records, it never reconstructs. `agent.execute_llm_step` writes each
A 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.md
index 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.started
memory.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 on
demand. 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.tsx
index 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.tsx
index 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.tsx
index 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 }> = ({ chi
break;
}
+ 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 the
diff --git a/client/src/index.css b/client/src/index.css
index 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.md
index 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 factories
See 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.
+
## Verification
Each Phase-A milestone has a verification command:
diff --git a/docs-internal/status_broadcaster.md b/docs-internal/status_broadcaster.md
index 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 IDs
diff --git a/server/nodes/context/__init__.py b/server/nodes/context/__init__.py
index 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: E402
register_agent_context_builder,
)
from services.ws_handler_registry import register_ws_handlers # noqa: E402
from ._descriptor import build_agent_context_descriptor # noqa: E402
+from ._events import on_context_commit # noqa: E402
from ._handlers import WS_HANDLERS # noqa: E402
register_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.py
index 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 AgentContextRef
from 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"] = sequence
return 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.py
index 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.py
new file mode 100644
index 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.py
index 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_commit
from services.llm.protocol import (
MESSAGE_WIRE_VERSION,
message_from_wire,
@@ -507,6 +508,16 @@ class AgentContextStore:
await session.rollback()
continue
updated = 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 updated
raise 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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