Skip to content

Self-improving AI Employees for everyone

refactor(context): plain conversation store replaces the journal

trohitg0649e567dad1
diff --git a/CLAUDE.md b/CLAUDE.md
index c9881b8c..90d8ca6b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,6 +22,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[Agent Architecture](./docs-internal/agent_architecture.md)** | How AI Agent and Chat Agent discover skills/tools, inject them into LLM prompts, and execute through the provider-neutral `run_native_agent_loop` |
| **[Agent Delegation](./docs-internal/agent_delegation.md)** | How memory, parameters, and execution context flow when one AI agent delegates work to another agent connected as a tool |
| **[Agent Teams](./docs-internal/agent_teams.md)** | Claude SDK Agent Teams pattern - AI Employee and Orchestrator nodes with input-teammates handle for multi-agent coordination |
+| **[Agent Context Flow](./docs-internal/agent_context_flow.md)** | Normative continuity reference — how a conversation survives firings, delegations, and rollovers on both paths. Plain conversation store: one `agent_conversations` row per `(workflow_id, generation, agent_node_id)` → messages JSON, loaded at run start and saved per turn (LangGraph thread_id / OpenAI conversation_id pattern; the journal/thread/epoch machinery is gone). Seeding precedence (carried rollover transcript > stored conversation > bare build, 1 MB guards), LOUD load failures (`ConversationLoadFailed` / `ConversationTooLarge`) vs best-effort saves, the specialized-provider bridge, and the August 2026 "lead forgot its plan" regression. Read before touching `services/agent_context/`, `nodes/context/`, `services/cli_agent/context_bridge.py`, `agent.prepare_payload`, or the team-completion event chain. |
| **[Memory Compaction](./docs-internal/memory_compaction.md)** | Native usage aggregation plus shared client-side summarization through `ChatUnifier` for memory-connected agents. Threshold = `Settings.compaction_ratio` (env `COMPACTION_RATIO`, default 0.8) × model context length; see the document for the per-session override limitation on Temporal runs. |
| **[Pricing Service](./docs-internal/pricing_service.md)** | Centralized cost tracking for LLM tokens and API services (Twitter, Google Maps) with HTTPX event hooks |
| **[Proxy Service](./docs-internal/proxy_service.md)** | Residential proxy provider management with template-based URL formatting, health scoring, and transparent HTTP node injection |
@@ -1385,17 +1386,13 @@ A new chat-model provider is one self-contained folder under `server/nodes/model
Two different things, deliberately separated. Read [RFC-0002](./RFC-0002-AGENT-CONTEXT-AND-MEMORY.md) before touching either.
-**Context** is the backend-owned execution journal — what the agent actually sent and received. The `context` node (`server/nodes/context/`, `input-context` handle) is a **read-only observation surface onto it**. Load-bearing invariant, learned the hard way: *attaching a Context node must never change what the agent sends.* It once did — `context_ref` in the LLM payload selected a second implementation that rebuilt the request from the journal instead of sending `messages`, and the rebuilt transcript dropped the user's prompt, so connecting a Context node made the agent answer an empty question. There is now exactly one LLM step; `context_ref` only says *where to record*.
+**Context** is the plain conversation store — what the agent actually sent and received, as JSON messages. One table (`agent_conversations`, [models/agent_context.py](./server/models/agent_context.py)) keyed by **`(workflow_id, generation, agent_node_id)`** → `messages` (MessageWire list) + `updated_at`; the service is four functions in [`services/agent_context/conversation.py`](./server/services/agent_context/conversation.py) (`load_conversation` / `save_conversation` (per-key lock, whole-list upsert, post-commit notify) / `clear_conversation` / `list_conversations`). Every firing of an agent — chat message or taskTrigger review — loads the row at run start and saves the live message list back per turn, so the one conversation continues across firings; Reset admits a new generation = new key = fresh conversation (old rows stay as inert history until workflow delete). The `context` node (`server/nodes/context/`, `input-context` handle) is the **opt-in switch and viewing panel**, nothing more — it declares no parameters. This is the LangGraph `thread_id` / OpenAI `conversation_id` pattern; the previous hash-chained journal (threads, epochs, checkpoints, blobs, provider bindings, session/task/execution thread routing) is deleted.
-The journal records, it never reconstructs. `agent.execute_llm_step` writes each turn from the exact message list it hands to `ChatUnifier.chat` (`_journal_llm_turn`), immediately after the call returns. `agent.prepare_context` deliberately journals nothing — it runs before the request exists, so anything it wrote would be assembled from configuration. Journal operation ids derive from the per-firing `context_execution_id`, **not** `execution_id`: the latter is generation-scoped, so every message in a generation minted identical ids and the store's idempotency guard silently discarded every turn after the first. They are **also scoped by `agent_node_id`** — two agents wired to one Context node resolve to the same thread, so a firing-only id made them collide on `(thread, operation_id)` and one agent's turns vanished as replays.
+Load-bearing invariants, learned the hard way: (1) *attaching a Context node must never change what the agent sends* — requests are always built from `messages`; `conversation_key` only says where to save. (2) *The store records what was sent, after it was sent* — `agent.execute_llm_step` saves `[...sent, assistant]` immediately after `ChatUnifier.chat` returns; nothing writes before a request exists (the retired `prepare_context` activity did, and journalled fabricated requests). (3) **Loads are LOUD, saves are best-effort** — `agent.prepare_payload` raises `ApplicationError("ConversationLoadFailed")` (retryable) / `ApplicationError("ConversationTooLarge")` (non-retryable, 1 MB cap) rather than silently running an amnesiac agent that burns tokens on an empty prompt; the save runs post-billing and swallows failures with a WARN. (4) Seeding precedence is **carried rollover transcript > stored conversation > bare build** — a `continue_as_new` resume carries the live transcript in its resume marker (size-guarded ≤ 1 MB) and must win over the store. Locked by `tests/temporal/test_agent_workflow.py::TestConversationIdentity`.
-**The one place the journal is read back is the `continue_as_new` rollover.** `AgentWorkflow` rolls over under history pressure *only when `context_ref` is set* (`agent_workflow.py`), and a rollover carries references, not the conversation — so the resumed run rebuilds `messages` from system + memory + prompt alone. Without a replay step that means attaching a Context node is what makes a long run silently forget everything it had said: the same class of bug as the original `context_ref` regression, one boundary later. The resumed run therefore calls `agent.reconstruct_context_messages` (read-only, wraps `reconstruct_message_wire_v2`) before its first LLM step. That activity **degrades instead of raising** — an opaque provider checkpoint or an unreadable thread returns `restored: False` with a reason and the run continues from the rebuilt prompt, because a rehydration miss must never turn an unreadable thread into a dead agent. Locked by `tests/temporal/test_agent_workflow.py::TestContextJournalIdentity`, which also asserts the workflow source carries no comment claiming the LLM activity rebuilds its request from the store — that sentence was false for a long time and is exactly what a future reader would re-implement.
+Both paths implement the same contract: Temporal via `prepare_agent_payload` (load) + `_save_conversation` in the LLM activity; in-process via `AIService._prepare_context` → `_AgentContextRuntime{key, history, database}` + the loop's `conversation_saver=runtime.save` hook. Specialized providers (claude_code / codex / rlm / vertex) use `SpecializedAgentContextBridge` ([services/cli_agent/context_bridge.py](./server/services/cli_agent/context_bridge.py)): `resolve` loads, `augment_prompt` renders the transcript into the prompt, `record_turn(original_prompt, response)` saves — always the ORIGINAL prompt, never the augmented one, or the save nests the transcript inside itself. The claude pool key is the conversation key (`(workflow_id, agent_node_id, generation)`), so a Reset's generation bump fences warm subprocesses at `acquire`; a same-generation panel Clear calls `ClaudeSessionPool.terminate_conversations`. Manual canvas Runs persist nothing (`generation > 0` gate — only Start admits a generation).
-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).
+**Live viewing is emitted at the persistence boundary, not per caller.** `save_conversation` is the one place every writer passes through, and it announces durable saves through the fanout registry in [`services/agent_context/listeners.py`](./server/services/agent_context/listeners.py) — `register_conversation_listener` / `notify_conversation_saved` — with `nodes/context/__init__.py` registering the broadcaster. Same shape as the plugin registries, same reason: the store must never import `nodes/`. The notification fires after the commit, and a listener can never fail a save. The single Context event (`context.updated`) **broadcasts directly via `get_status_broadcaster()`, not through `services.events.dispatch.emit`** — no canary consumer exists for `com.opencompany.context.*`, so `emit`'s Visibility query would match nothing once per save. Payload is identity + count only; the panel refetches through the authorized `get_agent_context` WS handler (`clear_agent_context` is the other handler; the journal-era fork/export handlers are gone). One `case 'context.updated'` in `WebSocketContext.tsx` invalidates `['agentContext']`; the panel 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.
diff --git a/client/src/components/parameterPanel/ContextPanel.tsx b/client/src/components/parameterPanel/ContextPanel.tsx
index 3cb768a1..96726e9b 100644
--- a/client/src/components/parameterPanel/ContextPanel.tsx
+++ b/client/src/components/parameterPanel/ContextPanel.tsx
@@ -1,71 +1,47 @@
-import React, { useMemo, useState } from 'react';
+import React, { useState } from 'react';
import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
import JsonView from '@uiw/react-json-view';
-import {
- Archive,
- ChevronLeft,
- ChevronRight,
- Download,
- GitFork,
- Loader2,
- RefreshCw,
- ShieldCheck,
-} from 'lucide-react';
+import { Loader2, RefreshCw, ShieldCheck, Trash2 } 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';
-import { Progress } from '@/components/ui/progress';
-import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from '@/components/ui/select';
import { useWebSocket } from '@/contexts/WebSocketContext';
-const PAGE_SIZE = 50;
-
-export interface AgentContextEventView {
- sequence: number;
- event_type: string;
- operation_id?: string;
- provider?: string;
- payload_ref?: string;
- payload_hash?: string;
- message_wire_v2?: unknown;
- payload?: unknown;
+interface ConversationMessage {
+ role?: string;
+ content?: unknown;
+ tool_calls?: unknown[];
+ tool_call_id?: string;
+ name?: string;
}
-interface ContextCheckpointView {
- provider?: string;
- strategy?: string;
- covers_through_sequence?: number;
- active_token_count?: number;
- source_revision?: number;
- source_hash?: string;
+interface ConversationMeta {
+ workflow_id: string;
+ generation: number;
+ agent_node_id: string;
+ message_count: number;
+ updated_at?: string | null;
}
interface ContextSnapshot {
- thread_id?: string;
- epoch?: number;
- revision?: number;
- provider?: string;
- fidelity?: string;
- resumable?: boolean;
- active_token_count?: number;
- context_window?: number;
- pressure_ratio?: number;
- provider_binding_status?: string;
- checkpoints?: ContextCheckpointView[];
- events?: AgentContextEventView[];
- active_replay?: unknown;
- next_cursor?: string | null;
+ conversations?: ConversationMeta[];
+ generation?: number | null;
+ agent_node_id?: string | null;
+ updated_at?: string | null;
+ message_count?: number;
+ messages?: ConversationMessage[];
}
-interface ContextResponse extends Partial<ContextSnapshot> {
+interface ContextResponse {
success?: boolean;
context?: ContextSnapshot;
error?: string;
@@ -76,65 +52,49 @@ interface ContextPanelProps {
workflowId?: string;
}
+const conversationValue = (meta: {
+ generation?: number | null;
+ agent_node_id?: string | null;
+}) => `${meta.generation ?? ''}:${meta.agent_node_id ?? ''}`;
+
const contextQueryKey = (
workflowId: string | undefined,
nodeId: string,
- cursor: string | null,
- view: string,
-) => ['agentContext', workflowId ?? '', nodeId, cursor ?? '', view] as const;
+ selected: string,
+) => ['agentContext', workflowId ?? '', nodeId, selected] as const;
-function responseSnapshot(response: ContextResponse | undefined): ContextSnapshot {
- if (!response) return {};
- return response.context ?? response;
-}
-
-function exportDownload(response: unknown, nodeId: string): void {
- if (!response || typeof window === 'undefined') return;
- const envelope = response as {
- filename?: string;
- content?: string;
- export?: unknown;
- };
- const body =
- typeof envelope.content === 'string'
- ? envelope.content
- : JSON.stringify(envelope.export ?? response, null, 2);
- const blob = new Blob([body], { type: 'application/json' });
- const href = URL.createObjectURL(blob);
- const anchor = document.createElement('a');
- anchor.href = href;
- anchor.download = envelope.filename || `context-${nodeId}.json`;
- anchor.click();
- URL.revokeObjectURL(href);
-}
-
-/** Authorized, query-backed Context inspector.
+/** Authorized, query-backed viewer for the plain conversation store.
*
- * Raw journal/replay payloads are fetched only while this panel is open.
- * It never reads transcript data from workflow params, node status, or
- * websocket broadcasts.
+ * One conversation per (workflow, generation, agent node); this panel lists
+ * the stored conversations and renders the selected transcript. It never
+ * reads transcript data from workflow params, node status, or websocket
+ * broadcasts — `context.updated` broadcasts only trigger a refetch through
+ * the authorized `get_agent_context` handler.
*/
const ContextPanel: React.FC<ContextPanelProps> = ({ nodeId, workflowId }) => {
const { sendRequest } = useWebSocket();
const queryClient = useQueryClient();
- const [view, setView] = useState<'journal' | 'active'>('journal');
- const [cursor, setCursor] = useState<string | null>(null);
- const [cursorHistory, setCursorHistory] = useState<Array<string | null>>([]);
+ // '' = server default (the newest stored conversation).
+ const [selected, setSelected] = useState<string>('');
+ const [selectedGeneration, selectedAgent] = selected
+ ? selected.split(/:(.*)/s, 2)
+ : ['', ''];
- const queryKey = contextQueryKey(workflowId, nodeId, cursor, view);
+ const queryKey = contextQueryKey(workflowId, nodeId, selected);
const contextQuery = useQuery<ContextResponse, Error>({
queryKey,
queryFn: () =>
sendRequest<ContextResponse>('get_agent_context', {
workflow_id: workflowId,
context_node_id: nodeId,
- cursor,
- limit: PAGE_SIZE,
- view,
+ ...(selectedGeneration ? { generation: Number(selectedGeneration) } : {}),
+ ...(selectedAgent ? { agent_node_id: selectedAgent } : {}),
}),
enabled: !!workflowId && !!nodeId,
});
- const snapshot = responseSnapshot(contextQuery.data);
+ const snapshot = contextQuery.data?.context ?? {};
+ const conversations = snapshot.conversations ?? [];
+ const messages = snapshot.messages ?? [];
const invalidateContext = async () => {
await queryClient.invalidateQueries({
@@ -146,56 +106,16 @@ const ContextPanel: React.FC<ContextPanelProps> = ({ nodeId, workflowId }) => {
sendRequest('clear_agent_context', {
workflow_id: workflowId,
context_node_id: nodeId,
+ ...(snapshot.generation != null ? { generation: snapshot.generation } : {}),
+ ...(snapshot.agent_node_id ? { agent_node_id: snapshot.agent_node_id } : {}),
}),
onSuccess: async () => {
- setCursor(null);
- setCursorHistory([]);
+ setSelected('');
await invalidateContext();
- toast.success('Context epoch cleared');
+ toast.success('Conversation cleared');
},
- onError: () => toast.error('Failed to clear Context'),
+ onError: () => toast.error('Failed to clear conversation'),
});
- const forkMutation = useMutation({
- mutationFn: () =>
- // No `provider`: the backend derives the binding from the thread.
- // Echoing it from this snapshot would let a stale render fork the
- // epoch onto a provider the thread has already moved off.
- sendRequest('fork_agent_context', {
- workflow_id: workflowId,
- context_node_id: nodeId,
- }),
- onSuccess: async () => {
- await invalidateContext();
- toast.success('Provider context forked');
- },
- onError: () => toast.error('Failed to fork Context'),
- });
- const exportMutation = useMutation({
- mutationFn: () =>
- sendRequest('export_agent_context', {
- workflow_id: workflowId,
- context_node_id: nodeId,
- thread_id: snapshot.thread_id,
- epoch: snapshot.epoch,
- }),
- onSuccess: (response) => {
- exportDownload(response, nodeId);
- toast.success('Context export prepared');
- },
- onError: () => toast.error('Failed to export Context'),
- });
-
- // 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 (
@@ -213,9 +133,9 @@ const ContextPanel: React.FC<ContextPanelProps> = ({ nodeId, workflowId }) => {
<div className="flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto p-6">
<div className="flex flex-wrap items-start justify-between gap-3">
<div>
- <h3 className="text-base font-semibold text-foreground">Agent Context</h3>
+ <h3 className="text-base font-semibold text-foreground">Agent Conversation</h3>
<p className="text-xs text-muted-foreground">
- Exact observable journal and active replay for this Context node.
+ Stored conversation for each connected agent, one per workflow generation.
</p>
</div>
<div className="flex flex-wrap gap-2">
@@ -228,225 +148,98 @@ const ContextPanel: React.FC<ContextPanelProps> = ({ nodeId, workflowId }) => {
<RefreshCw className={contextQuery.isFetching ? 'animate-spin' : ''} />
Refresh
</Button>
- <Button
- variant="outline"
- size="sm"
- onClick={() => forkMutation.mutate()}
- disabled={forkMutation.isPending}
- >
- <GitFork />
- Fork
- </Button>
- <Button
- variant="outline"
- size="sm"
- onClick={() => exportMutation.mutate()}
- disabled={exportMutation.isPending}
- >
- <Download />
- Export
- </Button>
<Button
variant="destructive"
size="sm"
onClick={() => clearMutation.mutate()}
- disabled={clearMutation.isPending}
+ disabled={clearMutation.isPending || messages.length === 0}
>
- <Archive />
- Clear epoch
+ <Trash2 />
+ Clear
</Button>
</div>
</div>
- <div className="grid grid-cols-2 gap-3 lg:grid-cols-4">
- <div className="rounded-md border border-border bg-card p-3">
- <div className="text-xs text-muted-foreground">Thread / epoch</div>
- <div className="truncate text-sm font-medium">
- {snapshot.thread_id || '—'} / {snapshot.epoch ?? '—'}
- </div>
- <div className="text-xs text-muted-foreground">
- Revision {snapshot.revision ?? '—'}
- </div>
- </div>
- <div className="rounded-md border border-border bg-card p-3">
- <div className="text-xs text-muted-foreground">Replay fidelity</div>
- <div className="mt-1 flex flex-wrap gap-1">
- {/* Success is claimed only when the server actually reported both
- a fidelity and resumability. Defaulting an absent verdict to
- green asserted a guarantee the server never made. */}
- <Badge
- variant={
- !snapshot.fidelity || snapshot.resumable !== true ? 'warning' : 'success'
- }
- >
- {snapshot.fidelity || 'unknown'}
- </Badge>
- {snapshot.resumable === false && <Badge variant="outline">non-resumable</Badge>}
- </div>
- </div>
- <div className="rounded-md border border-border bg-card p-3">
- <div className="text-xs text-muted-foreground">Provider</div>
- <div className="text-sm font-medium">{snapshot.provider || '—'}</div>
- <div className="text-xs text-muted-foreground">
- {/* "unbound" is a real server verdict, so it must not double as
- the placeholder for "the server said nothing". */}
- Binding {snapshot.provider_binding_status || '—'}
- </div>
- </div>
- <div className="rounded-md border border-border bg-card p-3">
- <div className="text-xs text-muted-foreground">Active pressure</div>
- <div className="mb-2 text-sm font-medium">
- {snapshot.active_token_count ?? 0}
- {snapshot.context_window ? ` / ${snapshot.context_window}` : ' tokens'}
- </div>
- {pressurePercent === null ? (
- <div className="text-xs text-muted-foreground">
- Set a context window to track pressure
- </div>
- ) : (
- <Progress value={pressurePercent} />
- )}
- </div>
- </div>
-
- {(snapshot.checkpoints?.length ?? 0) > 0 && (
- <div className="rounded-md border border-border bg-card p-3">
- <div className="mb-2 text-sm font-medium">Checkpoints</div>
- <div className="flex flex-col gap-2">
- {snapshot.checkpoints!.map((checkpoint, index) => (
- <div
- key={`${checkpoint.source_hash || checkpoint.covers_through_sequence || index}`}
- className="flex flex-wrap items-center gap-2 text-xs text-muted-foreground"
- >
- <Badge variant="outline">{checkpoint.strategy || 'portable'}</Badge>
- <span>{checkpoint.provider || 'unknown provider'}</span>
- <span>through #{checkpoint.covers_through_sequence ?? '—'}</span>
- <span>{checkpoint.active_token_count ?? 0} active tokens</span>
- </div>
+ {conversations.length > 1 && (
+ <Select
+ value={selected || conversationValue(snapshot)}
+ onValueChange={setSelected}
+ >
+ <SelectTrigger className="w-full max-w-md">
+ <SelectValue placeholder="Select a conversation" />
+ </SelectTrigger>
+ <SelectContent>
+ {conversations.map((meta) => (
+ <SelectItem key={conversationValue(meta)} value={conversationValue(meta)}>
+ Generation {meta.generation} · {meta.agent_node_id} ·{' '}
+ {meta.message_count} message{meta.message_count === 1 ? '' : 's'}
+ </SelectItem>
))}
- </div>
+ </SelectContent>
+ </Select>
+ )}
+
+ {snapshot.agent_node_id && (
+ <div className="flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
+ <Badge variant="outline">Generation {snapshot.generation ?? '—'}</Badge>
+ <Badge variant="outline">{snapshot.agent_node_id}</Badge>
+ <span>
+ {snapshot.message_count ?? 0} message
+ {(snapshot.message_count ?? 0) === 1 ? '' : 's'}
+ </span>
+ {snapshot.updated_at && <span>updated {snapshot.updated_at}</span>}
</div>
)}
- <Tabs
- value={view}
- onValueChange={(next) => {
- setView(next as 'journal' | 'active');
- setCursor(null);
- setCursorHistory([]);
- }}
- className="min-h-0 flex-1"
- >
- <TabsList>
- <TabsTrigger value="journal">Raw journal</TabsTrigger>
- <TabsTrigger value="active">Active replay</TabsTrigger>
- </TabsList>
- <TabsContent value="journal" className="mt-2">
- {contextQuery.isLoading ? (
- <Loader2 className="h-5 w-5 animate-spin text-muted-foreground" />
- ) : contextQuery.error ? (
- <Alert variant="destructive">
- <AlertTitle>Context unavailable</AlertTitle>
- <AlertDescription>{contextQuery.error.message}</AlertDescription>
- </Alert>
- ) : (snapshot.events?.length ?? 0) === 0 ? (
- <div className="rounded-md border border-dashed border-border p-8 text-center text-sm text-muted-foreground">
- No committed Context events yet.
- </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" />
- ) : (
- snapshot.active_replay ? (
- <div className="rounded-md border border-border bg-card p-3">
+ {contextQuery.isLoading ? (
+ <Loader2 className="h-5 w-5 animate-spin text-muted-foreground" />
+ ) : contextQuery.error ? (
+ <Alert variant="destructive">
+ <AlertTitle>Context unavailable</AlertTitle>
+ <AlertDescription>{contextQuery.error.message}</AlertDescription>
+ </Alert>
+ ) : messages.length === 0 ? (
+ <div className="rounded-md border border-dashed border-border p-8 text-center text-sm text-muted-foreground">
+ No stored conversation yet.
+ </div>
+ ) : (
+ <div className="flex flex-col gap-2">
+ {messages.map((message, index) => (
+ <div
+ key={index}
+ className="rounded-md border border-border bg-card p-3"
+ >
+ <div className="mb-1 flex flex-wrap items-center gap-2">
+ <Badge variant="outline">{message.role || 'message'}</Badge>
+ {message.name && (
+ <span className="font-mono text-xs text-muted-foreground">
+ {message.name}
+ </span>
+ )}
+ </div>
+ {typeof message.content === 'string' && message.content ? (
+ <div className="whitespace-pre-wrap text-sm text-foreground">
+ {message.content}
+ </div>
+ ) : message.content != null ? (
<JsonView
- value={snapshot.active_replay as object}
- collapsed={3}
+ value={message.content as object}
+ collapsed={2}
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>
-
- {view === 'journal' && (
- <div className="flex items-center justify-between">
- <Button
- variant="outline"
- size="sm"
- disabled={cursorHistory.length === 0}
- onClick={() => {
- setCursorHistory((history) => {
- const next = [...history];
- setCursor(next.pop() ?? null);
- return next;
- });
- }}
- >
- <ChevronLeft />
- Previous
- </Button>
- <span className="text-xs text-muted-foreground">Up to {PAGE_SIZE} events per page</span>
- <Button
- variant="outline"
- size="sm"
- disabled={!snapshot.next_cursor}
- onClick={() => {
- if (!snapshot.next_cursor) return;
- setCursorHistory((history) => [...history, cursor]);
- setCursor(snapshot.next_cursor);
- }}
- >
- Next
- <ChevronRight />
- </Button>
+ ) : null}
+ {(message.tool_calls?.length ?? 0) > 0 && (
+ <div className="mt-2">
+ <div className="mb-1 text-xs text-muted-foreground">Tool calls</div>
+ <JsonView
+ value={message.tool_calls as object}
+ collapsed={1}
+ displayDataTypes={false}
+ />
+ </div>
+ )}
+ </div>
+ ))}
</div>
)}
</div>
diff --git a/client/src/components/parameterPanel/__tests__/ContextMemoryPanels.test.tsx b/client/src/components/parameterPanel/__tests__/ContextMemoryPanels.test.tsx
index 8e5bb6ce..9ba31795 100644
--- a/client/src/components/parameterPanel/__tests__/ContextMemoryPanels.test.tsx
+++ b/client/src/components/parameterPanel/__tests__/ContextMemoryPanels.test.tsx
@@ -17,27 +17,28 @@ beforeEach(() => {
});
describe('ContextPanel', () => {
- it('loads authorized journal content through get_agent_context', async () => {
+ it('loads the stored conversation through get_agent_context', async () => {
sendRequest.mockImplementation(async (operation: string) => {
if (operation === 'get_agent_context') {
return {
context: {
- thread_id: 'session:abc',
- epoch: 3,
- revision: 9,
- provider: 'openai',
- fidelity: 'provider_replayable',
- resumable: true,
- active_token_count: 800,
- context_window: 10_000,
- provider_binding_status: 'bound',
- events: [
+ conversations: [
{
- sequence: 7,
- event_type: 'assistant_message',
- message_wire_v2: { role: 'assistant', blocks: [{ type: 'text', text: 'hello' }] },
+ workflow_id: 'wf-1',
+ generation: 2,
+ agent_node_id: 'agent-1',
+ message_count: 2,
+ updated_at: '2026-08-18T00:00:00Z',
},
],
+ generation: 2,
+ agent_node_id: 'agent-1',
+ updated_at: '2026-08-18T00:00:00Z',
+ message_count: 2,
+ messages: [
+ { role: 'user', content: 'hello agent' },
+ { role: 'assistant', content: 'hello operator' },
+ ],
},
};
}
@@ -46,38 +47,72 @@ describe('ContextPanel', () => {
render(<ContextPanel nodeId="ctx-1" workflowId="wf-1" />);
- expect(await screen.findByText('session:abc / 3')).toBeInTheDocument();
- expect(screen.getByText('assistant_message')).toBeInTheDocument();
+ expect(await screen.findByText('hello agent')).toBeInTheDocument();
+ expect(screen.getByText('hello operator')).toBeInTheDocument();
+ expect(screen.getByText('Generation 2')).toBeInTheDocument();
expect(sendRequest).toHaveBeenCalledWith(
'get_agent_context',
expect.objectContaining({
workflow_id: 'wf-1',
context_node_id: 'ctx-1',
- view: 'journal',
- limit: 50,
}),
);
});
- it('invokes backend epoch clearing without synthesizing local Context', async () => {
+ it('invokes backend clearing without synthesizing local Context', async () => {
sendRequest.mockImplementation(async (operation: string) => {
- if (operation === 'get_agent_context') return { context: { events: [] } };
+ if (operation === 'get_agent_context') {
+ return {
+ context: {
+ conversations: [
+ {
+ workflow_id: 'wf-1',
+ generation: 2,
+ agent_node_id: 'agent-1',
+ message_count: 1,
+ updated_at: null,
+ },
+ ],
+ generation: 2,
+ agent_node_id: 'agent-1',
+ updated_at: null,
+ message_count: 1,
+ messages: [{ role: 'user', content: 'hello' }],
+ },
+ };
+ }
if (operation === 'clear_agent_context') return { success: true };
return {};
});
const user = userEvent.setup();
render(<ContextPanel nodeId="ctx-1" workflowId="wf-1" />);
- await screen.findByText('No committed Context events yet.');
- await user.click(screen.getByRole('button', { name: /Clear epoch/i }));
+ await screen.findByText('hello');
+ await user.click(screen.getByRole('button', { name: /Clear/i }));
await waitFor(() =>
expect(sendRequest).toHaveBeenCalledWith('clear_agent_context', {
workflow_id: 'wf-1',
context_node_id: 'ctx-1',
+ generation: 2,
+ agent_node_id: 'agent-1',
}),
);
});
+
+ it('shows the empty state when nothing is stored', async () => {
+ sendRequest.mockImplementation(async (operation: string) => {
+ if (operation === 'get_agent_context') {
+ return { context: { conversations: [], messages: [] } };
+ }
+ return {};
+ });
+ render(<ContextPanel nodeId="ctx-1" workflowId="wf-1" />);
+
+ expect(
+ await screen.findByText('No stored conversation yet.'),
+ ).toBeInTheDocument();
+ });
});
describe('MemoryToolPanel', () => {
diff --git a/client/src/contexts/WebSocketContext.tsx b/client/src/contexts/WebSocketContext.tsx
index 3eeb451f..e6d05530 100644
--- a/client/src/contexts/WebSocketContext.tsx
+++ b/client/src/contexts/WebSocketContext.tsx
@@ -1063,12 +1063,10 @@ 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
+ case 'context.updated': {
+ // CloudEvents-typed conversation lifecycle from
+ // server/nodes/context/_events.py, emitted after every durable
+ // conversation save. The payload is identity + count 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
diff --git a/docs-internal/agent_context_flow.md b/docs-internal/agent_context_flow.md
new file mode 100644
index 00000000..ebeafa80
--- /dev/null
+++ b/docs-internal/agent_context_flow.md
@@ -0,0 +1,190 @@
+# Agent Context & Team Continuity Flow
+
+Normative reference for how an agent's conversation survives across firings,
+delegations, and rollovers — on both execution paths. Read this before
+touching `services/agent_context/`, `nodes/context/`,
+`services/cli_agent/context_bridge.py`, `agent.prepare_payload`,
+`agent.execute_llm_step`, or the team-completion event chain. The invariants
+at the bottom are the "do not break" contract; several were learned from a
+production regression documented at the end.
+
+Companion documents: [RFC-0002](../RFC-0002-AGENT-CONTEXT-AND-MEMORY.md)
+(design rationale for Context vs Memory), [agent_teams.md](./agent_teams.md)
+(team-lead contract), [TEMPORAL_ARCHITECTURE.md](./TEMPORAL_ARCHITECTURE.md)
+(execution engine).
+
+## The one-paragraph model
+
+Context is **plain JSON messages**. One table, `agent_conversations`, keyed
+by **`(workflow_id, generation, agent_node_id)`** → `messages` (a JSON list
+of `MessageWire` dicts) + `updated_at`. A run **loads** the row at start and
+**saves** the whole live message list back after every turn. Every firing of
+an agent — chat messages AND taskTrigger completion reviews — continues the
+one conversation; a workflow Reset admits a new generation, which is a new
+key, which is a fresh conversation. The connected Context node is the
+opt-in switch and the viewing panel, nothing more. This is the industry
+pattern (LangGraph `thread_id`, OpenAI `conversation_id`, Claude Code
+session files): a conversation id maps to a message list, and nothing else.
+
+There are no threads, sessions, epochs, hash chains, checkpoints, blobs, or
+operation ids. Memory (`simpleMemory`) is an ordinary tool — explicit
+remember/recall — and plays no automatic part in continuity.
+
+## The store (`services/agent_context/`)
+
+| Function | Contract |
+|---|---|
+| `load_conversation(db, *, workflow_id, generation, agent_node_id) → List[Dict]` | The stored wires, `[]` when the key has no row. |
+| `save_conversation(db, *, …, messages)` | Whole-list upsert under a per-key asyncio lock; notifies listeners **after** the commit. |
+| `clear_conversation(db, *, workflow_id, generation=None, agent_node_id=None) → int` | Deletes rows, optionally narrowed; returns the count. |
+| `list_conversations(db, *, workflow_id)` | Panel metadata (`generation`, `agent_node_id`, `message_count`, `updated_at`), newest generation first. |
+
+`listeners.py` carries `register_conversation_listener` /
+`notify_conversation_saved`. The store never imports `nodes/`; the Context
+plugin registers its `context.updated` broadcaster from
+`nodes/context/__init__.py` — same layering as the other plugin registries.
+
+## Full loop: chat → assign → child completes → review continues (Temporal path)
+
+```mermaid
+sequenceDiagram
+ autonumber
+ participant User
+ participant CT as chatTrigger firing
+ participant AW as Lead AgentWorkflow
+ participant PP as agent.prepare_payload
+ participant CS as agent_conversations<br/>(wf, gen, lead-node)
+ participant LS as agent.execute_llm_step
+ participant DTW as DelegatedTaskWorkflow
+ participant TT as taskTrigger firing
+
+ User->>CT: message
+ CT->>AW: spawn lead run
+ AW->>PP: prepare payload
+ PP->>CS: load_conversation(key)
+ CS-->>PP: stored wires (or [])
+ PP-->>AW: payload + conversation + conversation_key
+ Note over AW: messages = system + stored (non-system)<br/>+ THIS firing's prompt last
+ AW->>LS: iterate
+ LS->>CS: save_conversation([...sent, assistant])<br/>per turn, best-effort
+ AW->>DTW: task_manager assign
+ DTW-->>TT: task_completed event
+ TT->>AW: spawn review firing (same workflow generation)
+ AW->>PP: prepare payload
+ PP->>CS: load_conversation(SAME key)
+ CS-->>AW: full prior conversation
+ Note over AW: lead remembers its plan →<br/>accepts, assigns next work, finish_team
+```
+
+The review firing works **because the key is the same**: same workflow, same
+generation, same lead agent node. No event routing, session lifting, or
+thread resolution is involved — there is nothing to route.
+
+## Message seeding: what a run's initial `messages` list is
+
+```mermaid
+flowchart TD
+ R[AgentWorkflow run start] --> P{resume marker has<br/>carried transcript?}
+ P -- "yes (continue-as-new)" --> C1["messages = carried transcript verbatim<br/>(exact live conversation, size-guarded ≤ 1 MB)"]
+ P -- no --> Q{payload carries a stored<br/>conversation? (Context node,<br/>generation > 0, non-empty row)}
+ Q -- yes --> C2["system (this firing's)<br/>+ stored wires minus system messages<br/>+ THIS firing's user prompt last"]
+ Q -- no --> C3["bare build:<br/>system + memory markdown (legacy) + prompt"]
+```
+
+Precedence is exactly **carried transcript > stored conversation > bare
+build** and is intentional:
+
+- A rollover resumes the *same* run mid-flight — the live transcript is the
+ truth and must win over any store read.
+- A fresh firing with a Context node continues the *conversation* — the
+ stored row is the truth.
+- The bare build is the cold-start floor.
+
+The carried transcript caps at ~1 MB serialized
+(`_CAN_TRANSCRIPT_MAX_BYTES`) because Temporal's payload error limit is
+2 MiB for the whole continue-as-new argument; over-cap degrades to the
+opening prompt with a warning — never a failure.
+
+## Loading is loud; saving is best-effort
+
+- **Load failures raise.** `agent.prepare_payload` raises
+ `ApplicationError("ConversationLoadFailed")` (retryable) when the row
+ cannot be read, and `ApplicationError("ConversationTooLarge")`
+ (non-retryable, `_SEED_TRANSCRIPT_MAX_BYTES` = 1 MB — clear it from the
+ Context panel) when it is oversized. Running on silently instead would
+ burn tokens on an amnesiac prompt — the exact failure mode this design
+ replaced.
+- **Save failures warn and continue.** The save happens *after* the
+ provider was called and billed, so raising there would fail a completed
+ turn over a bookkeeping write. `_save_conversation`
+ (`agent_activities.py`), the loop's `save_now()` (`agent_runtime.py`),
+ and every specialized-provider `record_turn` call site swallow and log.
+
+## Both execution paths, one contract
+
+| Path | Load | Save |
+|---|---|---|
+| Temporal (`AgentWorkflow`) | `agent.prepare_payload` loads and returns `conversation` + `conversation_key` | `agent.execute_llm_step` saves `[...sent, assistant]` after each provider call |
+| In-process (`services/ai.py`) | `_prepare_context` builds `_AgentContextRuntime{key, history, database}` | the loop's `conversation_saver=runtime.save` fires after each assistant append and after tool results |
+| Specialized providers (claude_code / codex / rlm / vertex) | `SpecializedAgentContextBridge.resolve` loads; `augment_prompt` renders the transcript into the prompt | `record_turn(original_prompt, response)` appends and saves — always the **original** prompt, never the augmented one, or the save nests the transcript inside itself |
+
+The opt-in gate is identical everywhere: the edge-walker descriptor's
+`kind == "context"` plus an admitted `generation > 0` (manual canvas Runs
+persist nothing by design — only Start admits a generation).
+
+For claude, the session-pool key is the conversation key
+(`(workflow_id, agent_node_id, generation)` — `bridge.pool_key`), so a
+Reset's generation bump automatically fences warm subprocesses at `acquire`
+time, and a same-generation panel Clear terminates them explicitly
+(`ClaudeSessionPool.terminate_conversations`).
+
+## The Context node and panel
+
+`nodes/context/` owns the opt-in descriptor (`_descriptor.py`), two WS
+handlers (`get_agent_context` returns
+`{conversations, generation, agent_node_id, updated_at, message_count,
+messages}`; `clear_agent_context` deletes rows and fences warm claude
+processes), and one CloudEvents broadcast (`context.updated`, fired from the
+registered save listener; payload is identity + count only — the panel
+refetches through the authorized handler). The node declares **no
+parameters**; the connection is the whole configuration. Reset rotates
+nothing: the new generation's key is simply empty, and prior generations
+remain readable history until the workflow is deleted (which clears every
+row via the existing archive-outbox drain in
+`services/workflow_storage/handlers.py`).
+
+## Invariants (do not break)
+
+| # | Invariant | Why |
+|---|---|---|
+| 1 | The store observes; it never steers. Requests are always built from `messages`; `conversation_key` only says where to save. | The original `context_ref` regression made attaching a Context node change what the agent sent. |
+| 2 | One key per agent per generation: `(workflow_id, generation, agent_node_id)`. Every firing — chat or task review — continues that one conversation. | Per-firing/per-session keys are how the lead came back amnesiac (`messages=2`). |
+| 3 | Seeding precedence: carried transcript > stored conversation > bare build. | Rollover mid-run truth beats the store; the store beats cold start. |
+| 4 | Load failures are LOUD (`ConversationLoadFailed` / `ConversationTooLarge`); save failures are best-effort. | Never burn tokens on an amnesiac prompt; never fail a billed turn over bookkeeping. |
+| 5 | Save the exact sent list, after the provider call. Nothing writes to the store before a request exists. | The journal's `prepare_context` wrote fabricated requests assembled from configuration. |
+| 6 | Reset = new generation = new key. No epoch machinery; old rows are inert history. | Reset must be a real reset, with zero lifecycle choreography to miss. |
+| 7 | `input-memory` is retired; the conversation store is the continuity carrier. Do not resurrect markdown seeding. | `normalize_workflow_graph` migrates it away and the validator rejects it; two carriers would drift. |
+| 8 | Specialized bridges record the ORIGINAL prompt, never the augmented one. | Recording the rendered transcript nests the conversation inside itself and grows without bound. |
+| 9 | The store never imports `nodes/`; the plugin registers its broadcaster via `register_conversation_listener`, and a listener failure can never fail a save. | Same layering rule as every plugin registry; a UI notification must not break execution. |
+
+## How this broke (August 2026 regression), and why the journal went away
+
+Symptom: a team lead re-invoked by a `taskTrigger` completion started at
+`messages=2`, accepted the task, and returned — "forgot its plan" — after a
+Context node was added.
+
+The original carrier was an append-only **journal** (7 tables: threads,
+hash-chained events, checkpoints, blobs, provider bindings, epochs) with
+per-firing operation ids and session/task/execution thread resolution. It
+failed twice in the same direction: the Temporal path was write-only (fresh
+firings never read the journal back), and completion firings resolved a
+different thread than the chat that started the work. Both were patched —
+and the patched system still carried thread routing, epoch fencing, and
+reconstruction machinery whose only job was to approximate "one agent, one
+conversation".
+
+The replacement makes that property structural instead of routed: the
+conversation key **is** workflow + generation + agent node, so a firing
+cannot land in the wrong conversation because there is no resolution step
+to get wrong. When an agent "ignores" its guidance, check what its
+`messages` list actually contained first.
diff --git a/server/core/database.py b/server/core/database.py
index a364d719..7b0a7759 100644
--- a/server/core/database.py
+++ b/server/core/database.py
@@ -46,12 +46,7 @@ from models.database import (
WorkflowContextArchiveOutbox,
)
from models.agent_context import ( # noqa: F401 - registers SQLModel tables
- AgentContextBlobRecord,
- AgentContextCheckpointRecord,
- AgentContextCompactionAttemptRecord,
- AgentContextEventRecord,
- AgentContextProviderBindingRecord,
- AgentContextThreadRecord,
+ AgentConversation,
)
from models.cache import CacheEntry # SQLite-backed cache for Redis alternative
from core.logging import get_logger
diff --git a/server/models/agent_context.py b/server/models/agent_context.py
index 3d0df25f..960f8e8e 100644
--- a/server/models/agent_context.py
+++ b/server/models/agent_context.py
@@ -1,394 +1,52 @@
-"""Durable Agent Context V2 contracts and normalized persistence records.
-
-The public models in this module are deliberately payload-reference oriented.
-Only :class:`AgentContextEvent` may expose an exact ``MessageWire`` value,
-and only when an authorized caller explicitly loads the journal. Workflow
-graphs, node parameters, Temporal commands, status events, and ordinary node
-outputs use :class:`AgentContextRef` instead.
+"""Durable agent conversation storage.
+
+One row per conversation: the agent's message transcript as plain JSON
+wires (the ``message_to_wire`` shape), keyed by
+``(workflow_id, generation, agent_node_id)``. Every firing of an agent in a
+deployment generation — chat messages, task-completion reviews, anything —
+continues the same conversation. A workflow Reset admits a new generation,
+which is a new key, which is a fresh conversation: no epochs, no fencing.
+
+This is the industry-standard shape (LangGraph ``thread_id`` checkpoints,
+OpenAI ``conversation_id``, Claude Code session transcripts): serialized
+messages under a stable conversation key, loaded at run start, saved per
+turn. See docs-internal/agent_context_flow.md.
"""
from __future__ import annotations
from datetime import datetime, timezone
-from typing import Any, Literal, Optional
+from typing import Any, Optional
-from pydantic import BaseModel, ConfigDict, Field as PydanticField
-from sqlalchemy import (
- Column,
- DateTime,
- Index,
- JSON,
- LargeBinary,
- UniqueConstraint,
-)
+from sqlalchemy import Column, DateTime, JSON, UniqueConstraint
from sqlmodel import Field, SQLModel
-ContextThreadKind = Literal["session", "task", "execution"]
-ContextFidelity = Literal[
- "provider_replayable",
- "provider_bound",
- "observable_only",
-]
-
-
-class AgentContextRef(BaseModel):
- """Bounded reference carried by runtimes and Temporal histories."""
-
- workflow_id: str
- context_node_id: str
- generation: int
- thread_id: str
- epoch: int
- revision: int
-
- model_config = ConfigDict(frozen=True)
-
-
-class AgentContextEvent(BaseModel):
- """One exact, hash-chained observable transition in the raw journal."""
-
- sequence: int = PydanticField(ge=1)
- event_type: str
- message_wire: Optional[dict[str, Any]] = None
- payload_ref: Optional[str] = None
- operation_id: str
- provider: Optional[str] = None
- previous_hash: str
- payload_hash: str
-
- model_config = ConfigDict(frozen=True)
-
-
-class AgentContextCheckpoint(BaseModel):
- """Provider-replayable checkpoint activated over a committed prefix."""
-
- provider: str
- strategy: str
- covers_through_sequence: int = PydanticField(ge=0)
- replay_payload_ref: str
- active_token_count: int = PydanticField(ge=0)
- source_revision: int = PydanticField(ge=0)
- source_hash: str
-
- model_config = ConfigDict(frozen=True)
-
-
-class AgentContextActiveState(BaseModel):
- """Checkpoint plus the exact, still-uncompacted event tail."""
-
- ref: AgentContextRef
- checkpoint: Optional[AgentContextCheckpoint] = None
- tail: list[AgentContextEvent] = PydanticField(default_factory=list)
- active_token_count: int = PydanticField(default=0, ge=0)
-
- model_config = ConfigDict(frozen=True)
-
-
-class AgentContextAppendResult(BaseModel):
- ref: AgentContextRef
- event: AgentContextEvent
- applied: bool
-
- model_config = ConfigDict(frozen=True)
-
-
-class AgentContextCompactionPlan(BaseModel):
- """Lease returned to a compactor before it performs provider work."""
-
- attempt_id: int
- ref: AgentContextRef
- provider: str
- strategy: str
- base_checkpoint: Optional[AgentContextCheckpoint] = None
- committed_prefix: list[AgentContextEvent]
- covers_through_sequence: int
- source_revision: int
- source_hash: str
-
- model_config = ConfigDict(frozen=True)
-
-
-class AgentContextProviderBinding(BaseModel):
- """Metadata-only view of an external provider continuation binding."""
-
- provider: str
- binding_type: str
- binding_ref: str
- epoch: int
- fidelity: ContextFidelity
+class AgentConversation(SQLModel, table=True):
+ """The full message transcript for one agent in one generation."""
- model_config = ConfigDict(frozen=True)
-
-
-class AgentContextThreadSummary(BaseModel):
- """Metadata-only thread listing for an authorized Context panel."""
-
- ref: AgentContextRef
- thread_kind: ContextThreadKind
- provider: Optional[str] = None
- status: str
- active_checkpoint_sequence: int = PydanticField(ge=0)
- active_token_count: int = PydanticField(ge=0)
- updated_at: datetime
-
- model_config = ConfigDict(frozen=True)
-
-
-class AgentContextThreadRecord(SQLModel, table=True):
- """Current control row for one isolated Context thread."""
-
- __tablename__ = "agent_context_threads"
+ __tablename__ = "agent_conversations"
__table_args__ = (
UniqueConstraint(
"workflow_id",
- "context_node_id",
- "generation",
- "thread_id",
- name="uq_agent_context_thread",
- ),
- Index(
- "ix_agent_context_node_generation",
- "workflow_id",
- "context_node_id",
"generation",
+ "agent_node_id",
+ name="uq_agent_conversation_key",
),
)
id: Optional[int] = Field(default=None, primary_key=True)
- workflow_id: str = Field(max_length=255)
- context_node_id: str = Field(max_length=255)
+ workflow_id: str = Field(index=True, max_length=255)
generation: int = Field(index=True)
- thread_id: str = Field(max_length=512)
- thread_kind: str = Field(max_length=20)
- epoch: int = Field(default=1)
- revision: int = Field(default=0)
- next_sequence: int = Field(default=1)
- last_event_hash: str = Field(default="0" * 64, max_length=64)
- active_checkpoint_id: Optional[int] = Field(default=None, index=True)
- active_checkpoint_sequence: int = Field(default=0)
- active_token_count: int = Field(default=0)
- provider: Optional[str] = Field(default=None, max_length=100)
- status: str = Field(default="active", index=True, max_length=20)
- created_at: datetime = Field(
- default_factory=lambda: datetime.now(timezone.utc),
- sa_column=Column(
- DateTime(timezone=True),
- nullable=False,
- ),
+ agent_node_id: str = Field(max_length=255)
+ messages: list[dict[str, Any]] = Field(
+ default_factory=list,
+ sa_column=Column(JSON, nullable=False),
)
updated_at: datetime = Field(
- default_factory=lambda: datetime.now(timezone.utc),
- sa_column=Column(
- DateTime(timezone=True),
- nullable=False,
- ),
- )
- archived_at: Optional[datetime] = Field(
- default=None,
- sa_column=Column(DateTime(timezone=True), nullable=True),
- )
-
-
-class AgentContextEventRecord(SQLModel, table=True):
- """Append-only exact journal entry."""
-
- __tablename__ = "agent_context_events"
- __table_args__ = (
- UniqueConstraint(
- "context_thread_id",
- "sequence",
- name="uq_agent_context_event_sequence",
- ),
- UniqueConstraint(
- "context_thread_id",
- "operation_id",
- name="uq_agent_context_event_operation",
- ),
- Index(
- "ix_agent_context_event_epoch_sequence",
- "context_thread_id",
- "epoch",
- "sequence",
- ),
- )
-
- id: Optional[int] = Field(default=None, primary_key=True)
- context_thread_id: int = Field(
- foreign_key="agent_context_threads.id",
- index=True,
- )
- epoch: int = Field(index=True)
- sequence: int
- event_type: str = Field(max_length=100)
- message_wire: Optional[dict[str, Any]] = Field(
- default=None,
- sa_column=Column(JSON, nullable=True),
- )
- payload_ref: Optional[str] = Field(default=None, max_length=512)
- operation_id: str = Field(max_length=512)
- provider: Optional[str] = Field(default=None, max_length=100)
- previous_hash: str = Field(max_length=64)
- payload_hash: str = Field(max_length=64, index=True)
- created_at: datetime = Field(
- default_factory=lambda: datetime.now(timezone.utc),
- sa_column=Column(DateTime(timezone=True), nullable=False),
- )
-
-
-class AgentContextCheckpointRecord(SQLModel, table=True):
- """Immutable provider replay payload and its journal coverage."""
-
- __tablename__ = "agent_context_checkpoints"
- __table_args__ = (
- UniqueConstraint(
- "context_thread_id",
- "operation_id",
- name="uq_agent_context_checkpoint_operation",
- ),
- Index(
- "ix_agent_context_checkpoint_epoch",
- "context_thread_id",
- "epoch",
- "covers_through_sequence",
- ),
- )
-
- id: Optional[int] = Field(default=None, primary_key=True)
- context_thread_id: int = Field(
- foreign_key="agent_context_threads.id",
- index=True,
- )
- epoch: int = Field(index=True)
- provider: str = Field(max_length=100)
- strategy: str = Field(max_length=100)
- covers_through_sequence: int
- replay_payload_ref: str = Field(max_length=512)
- active_token_count: int = Field(default=0)
- source_revision: int
- source_hash: str = Field(max_length=64)
- operation_id: str = Field(max_length=512)
- status: str = Field(default="active", index=True, max_length=20)
- created_at: datetime = Field(
- default_factory=lambda: datetime.now(timezone.utc),
- sa_column=Column(DateTime(timezone=True), nullable=False),
- )
-
-
-class AgentContextProviderBindingRecord(SQLModel, table=True):
- """Opaque external continuation identity stored by payload reference."""
-
- __tablename__ = "agent_context_provider_bindings"
- __table_args__ = (
- UniqueConstraint(
- "context_thread_id",
- "operation_id",
- name="uq_agent_context_binding_operation",
- ),
- Index(
- "ix_agent_context_binding_lookup",
- "context_thread_id",
- "epoch",
- "provider",
- "binding_type",
- ),
- )
-
- id: Optional[int] = Field(default=None, primary_key=True)
- context_thread_id: int = Field(
- foreign_key="agent_context_threads.id",
- index=True,
- )
- epoch: int = Field(index=True)
- provider: str = Field(max_length=100)
- binding_type: str = Field(max_length=100)
- binding_ref: str = Field(max_length=512)
- binding_hash: str = Field(max_length=64)
- fidelity: str = Field(default="provider_bound", max_length=32)
- operation_id: str = Field(max_length=512)
- status: str = Field(default="active", index=True, max_length=20)
- created_at: datetime = Field(
- default_factory=lambda: datetime.now(timezone.utc),
- sa_column=Column(DateTime(timezone=True), nullable=False),
- )
-
-
-class AgentContextCompactionAttemptRecord(SQLModel, table=True):
- """CAS lease separating expensive compaction from checkpoint activation."""
-
- __tablename__ = "agent_context_compaction_attempts"
- __table_args__ = (
- UniqueConstraint(
- "context_thread_id",
- "operation_id",
- name="uq_agent_context_compaction_operation",
- ),
- )
-
- id: Optional[int] = Field(default=None, primary_key=True)
- context_thread_id: int = Field(
- foreign_key="agent_context_threads.id",
- index=True,
- )
- epoch: int = Field(index=True)
- provider: str = Field(max_length=100)
- strategy: str = Field(max_length=100)
- covers_through_sequence: int
- base_checkpoint_id: Optional[int] = Field(default=None)
- base_checkpoint_sequence: int = Field(default=0)
- source_revision: int
- source_hash: str = Field(max_length=64)
- operation_id: str = Field(max_length=512)
- status: str = Field(default="prepared", index=True, max_length=20)
- checkpoint_id: Optional[int] = Field(default=None)
- error_code: Optional[str] = Field(default=None, max_length=255)
- created_at: datetime = Field(
- default_factory=lambda: datetime.now(timezone.utc),
- sa_column=Column(DateTime(timezone=True), nullable=False),
- )
- completed_at: Optional[datetime] = Field(
- default=None,
- sa_column=Column(DateTime(timezone=True), nullable=True),
- )
-
-
-class AgentContextBlobRecord(SQLModel, table=True):
- """Optional hash-addressed storage for large or opaque exact payloads."""
-
- __tablename__ = "agent_context_blobs"
-
- payload_hash: str = Field(primary_key=True, max_length=64)
- media_type: str = Field(default="application/json", max_length=100)
- json_payload: Optional[Any] = Field(
- default=None,
- sa_column=Column(JSON, nullable=True),
- )
- binary_payload: Optional[bytes] = Field(
- default=None,
- sa_column=Column(LargeBinary, nullable=True),
- )
- byte_size: int = Field(default=0)
- created_at: datetime = Field(
default_factory=lambda: datetime.now(timezone.utc),
sa_column=Column(DateTime(timezone=True), nullable=False),
)
-__all__ = [
- "AgentContextActiveState",
- "AgentContextAppendResult",
- "AgentContextBlobRecord",
- "AgentContextCheckpoint",
- "AgentContextCheckpointRecord",
- "AgentContextCompactionAttemptRecord",
- "AgentContextCompactionPlan",
- "AgentContextEvent",
- "AgentContextEventRecord",
- "AgentContextProviderBinding",
- "AgentContextProviderBindingRecord",
- "AgentContextRef",
- "AgentContextThreadRecord",
- "AgentContextThreadSummary",
- "ContextFidelity",
- "ContextThreadKind",
-]
+__all__ = ["AgentConversation"]
diff --git a/server/nodes/agent/claude_code_agent/_pool.py b/server/nodes/agent/claude_code_agent/_pool.py
index 63591e9a..68578b4f 100644
--- a/server/nodes/agent/claude_code_agent/_pool.py
+++ b/server/nodes/agent/claude_code_agent/_pool.py
@@ -116,8 +116,8 @@ class PooledClaudeSession:
stream-json mode, NOT to the JSONL file.
"""
- # V1 uses a Simple Memory node id. Context V2 uses the exact
- # (context_node_id, thread_id, epoch) tuple.
+ # V1 uses a Simple Memory node id. Context-bound runs use the exact
+ # (workflow_id, agent_node_id, generation) conversation key.
memory_node_id: ClaudePoolKey
process: asyncio.subprocess.Process
cwd: Path
@@ -282,7 +282,7 @@ class ClaudeSessionPool:
for stale_key in stale_keys:
await self._terminate_locked(
stale_key,
- reason="epoch_changed",
+ reason="generation_changed",
)
existing = self._pool.get(memory_node_id)
crashed_uuid = ""
@@ -512,19 +512,19 @@ class ClaudeSessionPool:
async with self._pool_lock:
await self._terminate_locked(memory_node_id)
- async def terminate_context(
+ async def terminate_conversations(
self,
- context_node_id: str,
+ workflow_id: str,
*,
- thread_id: Optional[str] = None,
- keep_epoch: Optional[int] = None,
+ agent_node_id: Optional[str] = None,
+ keep_generation: Optional[int] = None,
) -> int:
- """Terminate warm processes fenced by a Context lifecycle change.
+ """Terminate warm processes whose stored conversation was cleared.
- Context clear/reset handlers can call this immediately after
- ``start_epoch``. ``acquire`` independently performs the same fence,
- so a missed best-effort lifecycle notification cannot reuse an old
- epoch later.
+ A generation bump is fenced independently by ``acquire`` (the
+ conversation key carries the generation), but a same-generation
+ clear from the Context panel must also drop the warm subprocess —
+ it still holds the wiped conversation in memory.
"""
async with self._pool_lock:
@@ -532,14 +532,14 @@ class ClaudeSessionPool:
key
for key in self._pool
if isinstance(key, tuple)
- and key[0] == context_node_id
- and (thread_id is None or key[1] == thread_id)
- and (keep_epoch is None or key[2] != keep_epoch)
+ and key[0] == workflow_id
+ and (agent_node_id is None or key[1] == agent_node_id)
+ and (keep_generation is None or key[2] != keep_generation)
]
for key in keys:
await self._terminate_locked(
key,
- reason="context_epoch_changed",
+ reason="conversation_cleared",
)
return len(keys)
diff --git a/server/nodes/agent/vertex_managed_agent/__init__.py b/server/nodes/agent/vertex_managed_agent/__init__.py
index 9cd238b0..17eacdb3 100644
--- a/server/nodes/agent/vertex_managed_agent/__init__.py
+++ b/server/nodes/agent/vertex_managed_agent/__init__.py
@@ -249,11 +249,7 @@ class VertexManagedAgentNode(ActionNode):
database,
context_data,
provider="vertex",
- fidelity="provider_bound",
- resumable=True,
- operation_prefix=(
- f"vertex-context:{ctx.execution_id or 'run'}:{node_id}"
- ),
+ agent_node_id=node_id,
)
prompt = params.prompt or self._prompt_from_input(input_data)
@@ -262,6 +258,7 @@ class VertexManagedAgentNode(ActionNode):
"vertex_managed_agent: provide a prompt or connect an "
"input node that produced a message."
)
+ original_prompt = prompt
if context_bridge is not None:
prompt = context_bridge.augment_prompt(prompt)
@@ -287,18 +284,6 @@ class VertexManagedAgentNode(ActionNode):
)
on_event = visibility_handler
- if context_bridge is not None:
- async def context_on_event(event: Any) -> None:
- # Persist the complete provider event before the UI-oriented
- # live handler shapes/pulses it.
- await context_bridge.append_observable(
- "provider.stream",
- self._jsonable(event),
- )
- if visibility_handler is not None:
- await visibility_handler(event)
-
- on_event = context_on_event
# ---- memory bridge: interaction/environment chain ids
prev_interaction_id: Optional[str] = None
@@ -309,15 +294,9 @@ class VertexManagedAgentNode(ActionNode):
mem_params = await database.get_node_parameters(memory_node_id) or {}
prev_interaction_id = mem_params.get("vertex_interaction_id") or None
environment = mem_params.get("vertex_environment_id") or "remote"
- elif context_bridge is not None:
- await phase("loading_context")
- binding = await context_bridge.load_binding(
- "interaction_environment"
- )
- prev_interaction_id = (
- str((binding or {}).get("interaction_id") or "") or None
- )
- environment = (binding or {}).get("environment_id") or "remote"
+ # Context-bound runs start a fresh remote interaction every firing:
+ # continuity comes from the stored conversation rendered into the
+ # prompt, not from chained provider interaction ids.
create_kwargs: Dict[str, Any] = {
"agent": params.agent,
@@ -350,40 +329,11 @@ class VertexManagedAgentNode(ActionNode):
create_kwargs["tools"] = declared_tools
async def run_turn(**kw: Any) -> Any:
- if context_bridge is not None:
- await context_bridge.append_observable(
- "provider.request",
- {
- "agent": params.agent,
- "request": kw,
- "has_system_instruction": bool(system_instruction),
- "declared_tools": declared_tools,
- },
- )
try:
- result = await stream_interaction(
+ return await stream_interaction(
client, on_event=on_event, **create_kwargs, **kw
)
- if context_bridge is not None:
- await context_bridge.append_observable(
- "provider.response",
- self._jsonable(result),
- )
- return result
except Exception as exc: # noqa: BLE001 — mapped below
- if context_bridge is not None:
- await context_bridge.append_observable(
- "provider.ambiguous_outcome",
- {
- "error_type": type(exc).__name__,
- "error": str(exc),
- },
- )
- raise NodeUserError(
- "Vertex managed agent interaction failed "
- f"({type(exc).__name__}); inspect the authorized "
- "Context journal for provider details."
- ) from exc
raise_as_user_error(exc, what="Vertex managed agent interaction")
# ---- turn 1 (with one stale-chain retry)
@@ -414,11 +364,7 @@ class VertexManagedAgentNode(ActionNode):
logger.warning(
"[Vertex Agent] unresumable interaction chain for %s (%s) — retrying fresh",
node_id,
- (
- type(cause).__name__
- if context_bridge is not None
- else str(cause).replace("\n", " ")[:120]
- ),
+ str(cause).replace("\n", " ")[:120],
)
if memory_node_id:
await self._save_chain_ids(
@@ -433,16 +379,6 @@ class VertexManagedAgentNode(ActionNode):
else None
),
)
- elif context_bridge is not None:
- await context_bridge.bind_provider(
- "interaction_environment",
- {
- "interaction_id": None,
- "environment_id": None,
- "reset_reason": "unresumable_chain",
- },
- operation_suffix="binding-reset",
- )
prev_interaction_id = None
environment = "remote"
interaction = await run_turn(input=prompt, environment="remote")
@@ -476,11 +412,6 @@ class VertexManagedAgentNode(ActionNode):
function_result = await self._execute_bridged_call(
call, tool_configs, ctx, delegation_wait_seconds=wait
)
- if context_bridge is not None:
- await context_bridge.append_observable(
- "tool.result",
- function_result,
- )
function_results.append(function_result)
turn += 1
await broadcaster.broadcast_agent_progress(
@@ -558,29 +489,20 @@ class VertexManagedAgentNode(ActionNode):
else None
),
)
- elif context_bridge is not None:
+ elif context_bridge is not None and response_text:
await phase("saving_context")
- if status in _RESUMABLE_STATUSES:
- await context_bridge.bind_provider(
- "interaction_environment",
- {
- "interaction_id": getattr(interaction, "id", None),
- "environment_id": environment_id,
- "status": status,
- },
- operation_suffix="interaction-binding",
+ # Best-effort: the provider already ran and billed, so a save
+ # failure must not fail the run.
+ try:
+ await context_bridge.record_turn(
+ original_prompt,
+ response_text,
+ )
+ except Exception as exc: # noqa: BLE001 — best-effort persist
+ logger.warning(
+ "[Vertex Agent] conversation save failed; continuing: %s",
+ exc,
)
- await context_bridge.append_observable(
- "provider.final",
- {
- "status": status,
- "turns": turn,
- "response": response_text,
- "usage": usage,
- "warnings": run_warnings,
- },
- operation_suffix="final",
- )
# ---- usage bookkeeping (tokens billed by Google; recorded for stats)
try:
diff --git a/server/nodes/context/__init__.py b/server/nodes/context/__init__.py
index 685dac27..ad2df308 100644
--- a/server/nodes/context/__init__.py
+++ b/server/nodes/context/__init__.py
@@ -1,73 +1,29 @@
"""Visible, system-managed Agent Context companion node.
-Only replay policy is workflow configuration. Journals, checkpoints,
-provider bindings, epochs, and payload references live exclusively in
-``AgentContextStore`` and never enter node parameters or normal outputs.
+Connecting this node to an agent's ``input-context`` handle opts the agent
+into the plain conversation store: one ``agent_conversations`` row per
+``(workflow_id, generation, agent_node_id)``, loaded at run start and saved
+per turn. The node itself carries no runtime state — the conversation lives
+in the store and is viewed through the panel handlers below.
"""
from __future__ import annotations
-from typing import Literal, Optional
-
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict
from services.plugin import ActionNode, NodeContext, Operation, TaskQueue
class AgentContextParams(BaseModel):
- compaction_mode: Literal[
- "auto",
- "native",
- "portable",
- "disabled",
- ] = Field(
- default="auto",
- title="Compaction Mode",
- description=(
- "Prefer verified provider-native compaction in auto mode, "
- "falling back to a portable structured checkpoint."
- ),
- )
- trigger_ratio: float = Field(
- default=0.8,
- gt=0,
- lt=1,
- title="Context Pressure Trigger",
- description=(
- "Compact when retained next-request input plus output headroom "
- "reaches this fraction of the context window."
- ),
- )
- context_window_override: Optional[int] = Field(
- default=None,
- ge=1024,
- title="Context Window Override",
- description=(
- "Optional model context-window override. Empty uses provider "
- "capability discovery."
- ),
- )
- exact_tail_retention_count: int = Field(
- default=8,
- ge=1,
- le=1000,
- title="Exact Tail Retention",
- description=(
- "Minimum number of recent exact transitions retained after a "
- "checkpoint."
- ),
- )
+ """The Context node is configuration-free; the connection is the opt-in."""
model_config = ConfigDict(extra="forbid")
class AgentContextOutput(BaseModel):
- """Metadata-only execution result; no transcript or provider state."""
+ """Metadata-only execution result; no transcript."""
configured: bool = True
- compaction_mode: str
- trigger_ratio: float
- exact_tail_retention_count: int
model_config = ConfigDict(extra="forbid")
@@ -76,11 +32,11 @@ class AgentContextNode(ActionNode):
type = "context"
version = 2
display_name = "Context"
- subtitle = "Exact Agent State"
+ subtitle = "Agent Conversation"
group = ("memory",)
description = (
- "System-managed exact agent journal, replay checkpoints, and "
- "context-pressure policy"
+ "System-managed durable conversation for connected agents; "
+ "one conversation per agent per workflow generation"
)
component_kind = "model"
handles = (
@@ -117,14 +73,10 @@ class AgentContextNode(ActionNode):
ctx: NodeContext,
params: AgentContextParams,
) -> AgentContextOutput:
- """Return public policy only; durable state stays in the service."""
+ """Report configuration only; conversations stay in the store."""
- del ctx
- return AgentContextOutput(
- compaction_mode=params.compaction_mode,
- trigger_ratio=params.trigger_ratio,
- exact_tail_retention_count=params.exact_tail_retention_count,
- )
+ del ctx, params
+ return AgentContextOutput()
@classmethod
async def reset_execution_state(
@@ -137,62 +89,13 @@ class AgentContextNode(ActionNode):
graph: dict,
database,
) -> dict:
- """Rotate every active thread and fence late generation writes."""
-
- del graph
- if generation <= 0:
- return {
- "reset": False,
- "rotated_threads": 0,
- }
- from services.agent_context import AgentContextStore
- from services.agent_context.lifecycle import (
- fence_context_provider_resources,
- )
-
- from ._events import dispatch_context_epoch_started
-
- store = AgentContextStore(database)
- threads = store.iter_threads(
- workflow_id=str(workflow_id),
- context_node_id=str(node_id),
- generation=generation,
- include_archived=False,
- )
- rotated = 0
- async for thread in threads:
- new_ref = await store.start_epoch(
- thread.ref,
- operation_id=(
- f"workflow-reset:{execution_id}:{node_id}:"
- f"{thread.ref.thread_id}:epoch-{thread.ref.epoch}"
- ),
- provider=thread.provider,
- )
- await fence_context_provider_resources(
- context_node_id=new_ref.context_node_id,
- thread_id=new_ref.thread_id,
- keep_epoch=new_ref.epoch,
- )
- rotated += 1
- try:
- await dispatch_context_epoch_started(
- workflow_id=new_ref.workflow_id,
- context_node_id=new_ref.context_node_id,
- thread_id=new_ref.thread_id,
- epoch=new_ref.epoch,
- revision=new_ref.revision,
- provider=thread.provider,
- reason="workflow_reset",
- )
- except Exception:
- # Lifecycle state is authoritative; event delivery is
- # metadata-only and may be retried by observers.
- pass
- return {
- "reset": True,
- "rotated_threads": rotated,
- }
+ """Nothing to rotate: a Reset admits a new generation, and the
+ generation is part of the conversation key, so the next run starts
+ an empty conversation automatically. Prior-generation rows stay as
+ readable history until the workflow is deleted or cleared."""
+
+ del node_id, workflow_id, execution_id, generation, graph, database
+ return {"reset": False, "rotated_threads": 0}
__all__ = [
@@ -203,9 +106,9 @@ __all__ = [
# Context panel commands are plugin-owned side channels. The node class above
-# stays passive; all durable logic lives in AgentContextStore.
+# stays passive; all durable state lives in the conversation store.
from services.agent_context.listeners import ( # noqa: E402
- register_context_commit_listener,
+ register_conversation_listener,
)
from services.plugin.edge_walker import ( # noqa: E402
register_agent_context_builder,
@@ -213,15 +116,14 @@ from services.plugin.edge_walker import ( # noqa: E402
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 ._events import on_conversation_saved # noqa: E402
from ._handlers import WS_HANDLERS # noqa: E402
register_ws_handlers(WS_HANDLERS)
# The framework walks `input-context` edges but knows nothing about this
-# node's parameters or thread-selection rules; it calls whatever is
-# registered here.
+# node's parameters; 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
+# The store announces durable saves; 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)
+register_conversation_listener(on_conversation_saved)
diff --git a/server/nodes/context/_descriptor.py b/server/nodes/context/_descriptor.py
index 92033253..879f833f 100644
--- a/server/nodes/context/_descriptor.py
+++ b/server/nodes/context/_descriptor.py
@@ -1,10 +1,10 @@
"""Context descriptor construction.
-The ``context`` node is a declarative UI and policy surface onto an agent's
-context scope — it never owns the journal itself (RFC-0002 section 3). What
-it *does* own is the shape of the descriptor handed to the agent runtime:
-which thread the agent resolves, and the policy the operator configured on
-this node.
+The ``context`` node is a declarative opt-in surface onto an agent's
+conversation scope — it never owns the conversation itself (that lives in
+the plain conversation store, keyed by workflow/generation/agent node).
+What it *does* own is the shape of the descriptor handed to the agent
+runtime.
That shape lives here rather than in ``services/plugin/edge_walker.py`` so
the framework carries no knowledge of this plugin's parameters or its
diff --git a/server/nodes/context/_events.py b/server/nodes/context/_events.py
index 398809a5..2653be20 100644
--- a/server/nodes/context/_events.py
+++ b/server/nodes/context/_events.py
@@ -1,125 +1,52 @@
-"""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.
+"""CloudEvents factory for the Context conversation lifecycle.
+
+One event: ``context.updated``, broadcast after every durable conversation
+save. It is broadcast directly via the status broadcaster rather than
+through ``services.events.dispatch.emit`` — no node type registers a canary
+consumer for ``com.opencompany.context.*``, so routing through ``emit``
+would run a Temporal Visibility query guaranteed to match nothing once per
+save.
+
+The payload is identity + revision data only (never transcript content):
+the broadcast fans out to every connected socket, and the panel refetches
+through the authorized ``get_agent_context`` handler.
"""
from __future__ import annotations
-from typing import Any, Dict, Optional
+from typing import Any
-from models.agent_context import AgentContextRef
+from core.logging import get_logger
from services.events.envelope import WorkflowEvent
+logger = get_logger(__name__)
-def context_updated(
- *,
- workflow_id: str,
- context_node_id: str,
- thread_id: str,
- epoch: int,
- 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=data,
- )
+_SOURCE = "opencompany://nodes/context"
-def context_compacted(
+def context_updated(
*,
workflow_id: str,
- context_node_id: str,
- thread_id: str,
- epoch: int,
- revision: int,
- provider: Optional[str],
- strategy: str,
- covers_through_sequence: int,
- active_token_count: int,
+ generation: int,
+ agent_node_id: str,
+ message_count: int,
) -> WorkflowEvent:
- return WorkflowEvent(
- source="opencompany://nodes/context",
- type="com.opencompany.context.compacted",
- 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,
- "strategy": strategy,
- "covers_through_sequence": covers_through_sequence,
- "active_token_count": max(0, active_token_count),
- },
- )
-
+ """One durable conversation save committed."""
-def context_epoch_started(
- *,
- workflow_id: str,
- context_node_id: str,
- thread_id: str,
- epoch: int,
- revision: int,
- provider: Optional[str],
- reason: str,
-) -> WorkflowEvent:
return WorkflowEvent(
- source="opencompany://nodes/context",
- type="com.opencompany.context.epoch.started",
- subject=context_node_id,
- workflow_id=workflow_id,
+ source=_SOURCE,
+ type="com.opencompany.context.updated",
+ subject=str(agent_node_id),
data={
- "workflow_id": workflow_id,
- "context_node_id": context_node_id,
- "thread_id": thread_id,
- "epoch": epoch,
- "revision": revision,
- "provider": provider,
- "reason": reason,
+ "workflow_id": str(workflow_id),
+ "generation": int(generation),
+ "agent_node_id": str(agent_node_id),
+ "message_count": max(0, int(message_count)),
},
)
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.
- """
-
from services.status_broadcaster import get_status_broadcaster
await get_status_broadcaster().broadcast(
@@ -130,65 +57,38 @@ async def _broadcast(event: WorkflowEvent, *, wire_routing_key: str) -> None:
)
-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:
+async def dispatch_context_updated(**metadata: Any) -> None:
await _broadcast(
context_updated(**metadata),
wire_routing_key="context.updated",
)
-async def dispatch_context_compacted(**metadata) -> None:
- await _broadcast(
- context_compacted(**metadata),
- wire_routing_key="context.compacted",
- )
-
-
-async def on_context_commit(
+async def on_conversation_saved(
*,
- ref: AgentContextRef,
- provider: Optional[str],
- active_token_count: int,
- sequence: Optional[int] = None,
+ workflow_id: str,
+ generation: int,
+ agent_node_id: str,
+ message_count: int,
) -> None:
- """Turn a durable store commit into a ``context.updated`` broadcast.
+ """Conversation-save listener registered by the plugin package.
- 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.
+ ``services.agent_context`` must never import ``nodes/``; the plugin
+ registers this adapter via ``register_conversation_listener`` instead.
+ The listener registry already swallows listener failures, so a
+ broadcast problem can never fail a save.
"""
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,
+ workflow_id=workflow_id,
+ generation=generation,
+ agent_node_id=agent_node_id,
+ message_count=message_count,
)
__all__ = [
- "context_compacted",
- "context_epoch_started",
"context_updated",
- "dispatch_context_compacted",
- "dispatch_context_epoch_started",
"dispatch_context_updated",
- "on_context_commit",
+ "on_conversation_saved",
]
diff --git a/server/nodes/context/_handlers.py b/server/nodes/context/_handlers.py
index 5ab1537b..5fe1f430 100644
--- a/server/nodes/context/_handlers.py
+++ b/server/nodes/context/_handlers.py
@@ -1,40 +1,30 @@
-"""Authorized WebSocket handlers for the Context inspector.
+"""Authorized WebSocket handlers for the Context panel.
-Raw journal/replay data is returned only from ``get_agent_context`` after the
-saved workflow is verified to own the requested Context node. Lifecycle
-broadcasts contain metadata only. Exports are deliberately redacted: replay
-payloads, provider bindings, signatures, and message bodies never leave via
-the export path.
+Stored conversations are returned only from ``get_agent_context`` after the
+saved workflow is verified to own the requested Context node. Conversations
+are keyed by ``(workflow_id, generation, agent_node_id)`` in the plain
+conversation store; the Context node is the opt-in switch and the viewing
+surface, not the key.
"""
from __future__ import annotations
-import base64
-import json
-import re
-import uuid
from typing import Any, Awaitable, Callable, Dict, Optional
from fastapi import WebSocket
-from models.agent_context import (
- AgentContextEvent,
- AgentContextThreadSummary,
-)
+from core.logging import get_logger
from services.agent_context import (
- AgentContextStore,
- OpaqueCheckpointError,
- reconstruct_transcript,
+ clear_conversation,
+ list_conversations,
+ load_conversation,
)
-from services.agent_context.lifecycle import fence_context_provider_resources
from services.plugin import NodeUserError
from services.plugin.ws import ws_response
-from ._events import dispatch_context_epoch_started
-
+from ._events import dispatch_context_updated
-_DEFAULT_PAGE_SIZE = 50
-_MAX_PAGE_SIZE = 200
+logger = get_logger(__name__)
def _database():
@@ -43,12 +33,8 @@ def _database():
return container.database()
-def _store() -> AgentContextStore:
- return AgentContextStore(_database())
-
-
def _require_external_socket(websocket: WebSocket) -> None:
- """The internal unauthenticated worker socket may not inspect journals."""
+ """The internal unauthenticated worker socket may not read conversations."""
scope = getattr(websocket, "scope", {}) or {}
if scope.get("path") == "/ws/internal":
@@ -109,220 +95,14 @@ def _optional_generation(data: Dict[str, Any]) -> Optional[int]:
return generation
-async def _select_thread(
- store: AgentContextStore,
- data: Dict[str, Any],
-) -> Optional[AgentContextThreadSummary]:
- generation = _optional_generation(data)
- threads = await store.list_threads(
- workflow_id=str(data["workflow_id"]),
- context_node_id=str(data["context_node_id"]),
- generation=generation,
- include_archived=False,
- )
- requested_thread = str(data.get("thread_id") or "")
- selected = next(
- (
- thread
- for thread in threads
- if not requested_thread
- or thread.ref.thread_id == requested_thread
- ),
- None,
- )
- if requested_thread and selected is None:
- raise NodeUserError("Context thread not found")
- requested_epoch = data.get("epoch")
- if selected is not None and requested_epoch not in (None, ""):
- try:
- epoch = int(requested_epoch)
- except (TypeError, ValueError) as exc:
- raise NodeUserError("epoch must be an integer") from exc
- if epoch != selected.ref.epoch:
- raise NodeUserError("Requested Context epoch is no longer active")
- return selected
-
-
-def _encode_cursor(sequence: Optional[int]) -> Optional[str]:
- if sequence is None:
- return None
- return base64.urlsafe_b64encode(str(sequence).encode()).decode().rstrip("=")
-
-
-def _decode_cursor(value: Any) -> int:
- if value in (None, ""):
- return 0
- if not isinstance(value, str) or len(value) > 32:
- raise NodeUserError("Invalid Context cursor")
- try:
- padded = value + "=" * (-len(value) % 4)
- sequence = int(base64.urlsafe_b64decode(padded).decode())
- except (ValueError, UnicodeDecodeError) as exc:
- raise NodeUserError("Invalid Context cursor") from exc
- if sequence < 0:
- raise NodeUserError("Invalid Context cursor")
- return sequence
-
-
-async def _event_view(
- store: AgentContextStore,
- event: AgentContextEvent,
- *,
- hydrate_payload: bool,
-) -> dict[str, Any]:
- value = event.model_dump(mode="json", exclude_none=True)
- if (
- hydrate_payload
- and event.payload_ref
- and event.payload_ref.startswith("sha256:")
- ):
- try:
- value["payload"] = await store.get_blob(event.payload_ref)
- except Exception:
- # External/missing payload references stay visible as references;
- # a journal page must not fail because an attachment was retired.
- value["payload_unavailable"] = True
- return value
-
-
-def _fidelity(
- provider: Optional[str],
- binding_fidelity: Optional[str],
-) -> tuple[str, bool]:
- if binding_fidelity:
- return binding_fidelity, binding_fidelity != "observable_only"
- normalized = (provider or "").lower()
- if "codex" in normalized or normalized == "rlm":
- return "observable_only", False
- if "claude_code" in normalized or "vertex" in normalized:
- return "provider_bound", True
- if normalized:
- return "provider_replayable", True
- return "unknown", False
-
-
-async def _snapshot(
- store: AgentContextStore,
- thread: AgentContextThreadSummary,
- *,
- threads: list[AgentContextThreadSummary],
- view: str,
- cursor: Any = None,
- limit: int = _DEFAULT_PAGE_SIZE,
-) -> dict[str, Any]:
- ref = thread.ref
- active = await store.load_active(ref)
- checkpoints = await store.list_checkpoints(ref)
- bindings = await store.load_provider_bindings(
- ref,
- provider=thread.provider,
- )
- fidelity, resumable = _fidelity(
- thread.provider,
- bindings[-1].fidelity if bindings else None,
- )
- params = await _database().get_node_parameters(ref.context_node_id) or {}
- context_window = params.get("context_window_override")
- try:
- context_window = int(context_window) if context_window else None
- except (TypeError, ValueError):
- context_window = None
- base: dict[str, Any] = {
- "threads": [
- {
- "thread_id": item.ref.thread_id,
- "generation": item.ref.generation,
- "epoch": item.ref.epoch,
- "revision": item.ref.revision,
- "thread_kind": item.thread_kind,
- "provider": item.provider,
- "status": item.status,
- "active_token_count": item.active_token_count,
- "updated_at": item.updated_at.isoformat(),
- }
- for item in threads
- ],
- "thread_id": ref.thread_id,
- "epoch": ref.epoch,
- "revision": active.ref.revision,
- "provider": thread.provider,
- "fidelity": fidelity,
- "resumable": resumable,
- "active_token_count": active.active_token_count,
- "context_window": context_window,
- "pressure_ratio": (
- active.active_token_count / context_window
- if context_window
- else None
- ),
- "provider_binding_status": "bound" if bindings else "unbound",
- "checkpoints": [
- checkpoint.model_dump(mode="json") for checkpoint in checkpoints
- ],
- }
- if view == "active":
- checkpoint_payload: Any = None
- if active.checkpoint is not None:
- try:
- checkpoint_payload = await store.get_blob(
- active.checkpoint.replay_payload_ref
- )
- except Exception:
- checkpoint_payload = {"unavailable": True}
- base["active_replay"] = {
- "checkpoint": (
- {
- "metadata": active.checkpoint.model_dump(mode="json"),
- "payload": checkpoint_payload,
- }
- if active.checkpoint is not None
- else None
- ),
- "tail": [
- await _event_view(store, event, hydrate_payload=True)
- for event in active.tail
- ],
- }
- base["events"] = []
- base["next_cursor"] = None
- return base
-
- # Scope the journal to the live epoch. Workflow Reset (and Clear epoch)
- # rotate the thread to a fresh epoch and leave the prior events in place
- # as archived history; reading every epoch made a reset look like it had
- # done nothing, because the panel still listed every pre-reset turn.
- events, next_after = await store.load_journal_page(
- active.ref,
- after_sequence=_decode_cursor(cursor),
- limit=limit,
- epoch=active.ref.epoch,
- )
- base["events"] = [
- await _event_view(store, event, hydrate_payload=True)
- for event in events
- ]
- base["active_replay"] = None
- base["next_cursor"] = _encode_cursor(next_after)
- return base
-
-
-def _empty_snapshot() -> dict[str, Any]:
+def _empty_context() -> Dict[str, Any]:
return {
- "threads": [],
- "thread_id": None,
- "epoch": None,
- "revision": None,
- "provider": None,
- "fidelity": "unknown",
- "resumable": False,
- "active_token_count": 0,
- "context_window": None,
- "pressure_ratio": None,
- "provider_binding_status": "unbound",
- "checkpoints": [],
- "events": [],
- "active_replay": None,
- "next_cursor": None,
+ "conversations": [],
+ "generation": None,
+ "agent_node_id": None,
+ "updated_at": None,
+ "message_count": 0,
+ "messages": [],
}
@@ -331,332 +111,124 @@ async def handle_get_agent_context(
data: Dict[str, Any],
websocket: WebSocket,
) -> Dict[str, Any]:
+ """Return the stored conversations for one workflow's Context node.
+
+ ``conversations`` lists every stored row (newest generation first) so
+ the panel can offer a selector; ``messages`` is the transcript of the
+ selected row — the requested ``generation``/``agent_node_id`` when
+ given, else the newest one.
+ """
+
+ workflow_id = str(data.get("workflow_id") or "")
+ context_node_id = str(data.get("context_node_id") or "")
await _authorize_context_node(
websocket=websocket,
- workflow_id=str(data.get("workflow_id") or ""),
- context_node_id=str(data.get("context_node_id") or ""),
+ workflow_id=workflow_id,
+ context_node_id=context_node_id,
)
- store = _store()
generation = _optional_generation(data)
- threads = await store.list_threads(
- workflow_id=str(data["workflow_id"]),
- context_node_id=str(data["context_node_id"]),
- generation=generation,
- include_archived=bool(data.get("include_archived")),
- )
- requested_thread = str(data.get("thread_id") or "")
- thread = next(
+ agent_node_id = str(data.get("agent_node_id") or "") or None
+
+ database = _database()
+ conversations = await list_conversations(database, workflow_id=workflow_id)
+ selected = next(
(
- item
- for item in threads
- if not requested_thread or item.ref.thread_id == requested_thread
+ row
+ for row in conversations
+ if (generation is None or row["generation"] == generation)
+ and (
+ agent_node_id is None
+ or row["agent_node_id"] == agent_node_id
+ )
),
None,
)
- if requested_thread and thread is None:
- raise NodeUserError("Context thread not found")
- requested_epoch = data.get("epoch")
- if thread is not None and requested_epoch not in (None, ""):
- try:
- epoch = int(requested_epoch)
- except (TypeError, ValueError) as exc:
- raise NodeUserError("epoch must be an integer") from exc
- if epoch != thread.ref.epoch:
- raise NodeUserError("Requested Context epoch is no longer active")
- if thread is None:
- return {"success": True, "context": _empty_snapshot()}
- view = str(data.get("view") or "journal")
- if view not in {"journal", "active"}:
- raise NodeUserError("view must be journal or active")
- try:
- limit = int(data.get("limit") or _DEFAULT_PAGE_SIZE)
- except (TypeError, ValueError) as exc:
- raise NodeUserError("limit must be an integer") from exc
- limit = max(1, min(limit, _MAX_PAGE_SIZE))
- return {
- "success": True,
- "context": await _snapshot(
- store,
- thread,
- threads=threads,
- view=view,
- cursor=data.get("cursor"),
- limit=limit,
- ),
- }
+ if selected is None:
+ context = _empty_context()
+ context["conversations"] = conversations
+ return {"success": True, "context": context}
-
-@ws_response
-async def handle_clear_agent_context(
- data: Dict[str, Any],
- websocket: WebSocket,
-) -> Dict[str, Any]:
- await _authorize_context_node(
- websocket=websocket,
- workflow_id=str(data.get("workflow_id") or ""),
- context_node_id=str(data.get("context_node_id") or ""),
- )
- store = _store()
- thread = await _select_thread(store, data)
- if thread is None:
- return {"success": True, "context": _empty_snapshot()}
- operation_id = str(
- data.get("operation_id")
- or f"context-ui-clear:{data.get('request_id') or uuid.uuid4()}"
- )
- new_ref = await store.start_epoch(
- thread.ref,
- operation_id=operation_id,
- provider=thread.provider,
- )
- await fence_context_provider_resources(
- context_node_id=new_ref.context_node_id,
- thread_id=new_ref.thread_id,
- keep_epoch=new_ref.epoch,
- )
- await dispatch_context_epoch_started(
- workflow_id=new_ref.workflow_id,
- context_node_id=new_ref.context_node_id,
- thread_id=new_ref.thread_id,
- epoch=new_ref.epoch,
- revision=new_ref.revision,
- provider=thread.provider,
- reason="clear",
+ messages = await load_conversation(
+ database,
+ workflow_id=workflow_id,
+ generation=selected["generation"],
+ agent_node_id=selected["agent_node_id"],
)
return {
"success": True,
"context": {
- "thread_id": new_ref.thread_id,
- "epoch": new_ref.epoch,
- "revision": new_ref.revision,
+ "conversations": conversations,
+ "generation": selected["generation"],
+ "agent_node_id": selected["agent_node_id"],
+ "updated_at": selected["updated_at"],
+ "message_count": len(messages),
+ "messages": messages,
},
}
-async def _portable_handoff(
- store: AgentContextStore,
- thread: AgentContextThreadSummary,
-) -> str:
- active = await store.load_active(thread.ref)
- portable = True
- try:
- _, messages = await reconstruct_transcript(
- store,
- active.ref,
- )
- except OpaqueCheckpointError:
- portable = False
- # Historical opaque checkpoints cannot be translated. Preserve the
- # exact observable tail and clearly mark the handoff as partial.
- messages = [
- event.message_wire
- for event in active.tail
- if event.message_wire is not None
- ]
- return await store.put_blob(
- {
- "format": "agent-context-portable-handoff-v1",
- "fidelity": (
- "portable" if portable else "observable_only"
- ),
- "messages": messages,
- "source": {
- "workflow_id": thread.ref.workflow_id,
- "context_node_id": thread.ref.context_node_id,
- "generation": thread.ref.generation,
- "thread_id": thread.ref.thread_id,
- "epoch": thread.ref.epoch,
- "revision": active.ref.revision,
- "provider": thread.provider,
- },
- # Metadata is safe inside hash-addressed Context storage; it is
- # not returned by normal graph/status/export paths.
- "source_checkpoint": (
- {
- "provider": active.checkpoint.provider,
- "strategy": active.checkpoint.strategy,
- "covers_through_sequence": (
- active.checkpoint.covers_through_sequence
- ),
- "source_hash": active.checkpoint.source_hash,
- }
- if active.checkpoint is not None
- else None
- ),
- }
- )
-
-
@ws_response
-async def handle_fork_agent_context(
+async def handle_clear_agent_context(
data: Dict[str, Any],
websocket: WebSocket,
) -> Dict[str, Any]:
- await _authorize_context_node(
- websocket=websocket,
- workflow_id=str(data.get("workflow_id") or ""),
- context_node_id=str(data.get("context_node_id") or ""),
- )
- store = _store()
- thread = await _select_thread(store, data)
- if thread is None:
- return {"success": True, "context": _empty_snapshot()}
- # The provider binding is backend-owned (RFC-0002 section 3: the canvas
- # never owns provider bindings). Deriving it from the thread rather than
- # the request also stops a stale client snapshot from forking the epoch
- # onto a provider the thread already moved off.
- provider = str(thread.provider or "portable")
- handoff_ref = await _portable_handoff(store, thread)
- operation_id = str(
- data.get("operation_id")
- or f"context-ui-fork:{data.get('request_id') or uuid.uuid4()}"
- )
- new_ref = await store.fork_provider(
- thread.ref,
- provider=provider,
- operation_id=operation_id,
- portable_handoff_ref=handoff_ref,
- )
- await dispatch_context_epoch_started(
- workflow_id=new_ref.workflow_id,
- context_node_id=new_ref.context_node_id,
- thread_id=new_ref.thread_id,
- epoch=new_ref.epoch,
- revision=new_ref.revision,
- provider=provider,
- reason="fork",
- )
- return {
- "success": True,
- "context": {
- "thread_id": new_ref.thread_id,
- "epoch": new_ref.epoch,
- "revision": new_ref.revision,
- "provider": provider,
- },
- }
+ """Delete stored conversations for one workflow's Context node.
+ Narrowable by ``generation`` and/or ``agent_node_id``; without either,
+ every conversation for the workflow is deleted. Warm claude
+ subprocesses holding a cleared conversation in memory are terminated so
+ the next turn cannot silently continue from wiped state.
+ """
-def _redacted_event(event: AgentContextEvent) -> dict[str, Any]:
- return {
- "sequence": event.sequence,
- "event_type": event.event_type,
- "provider": event.provider,
- "previous_hash": event.previous_hash,
- "payload_hash": event.payload_hash,
- "redacted": True,
- }
-
-
-async def _redacted_export(
- store: AgentContextStore,
- thread: AgentContextThreadSummary,
-) -> dict[str, Any]:
- events: list[AgentContextEvent] = []
- after = 0
- while True:
- page, next_after = await store.load_journal_page(
- thread.ref,
- after_sequence=after,
- limit=_MAX_PAGE_SIZE,
- )
- events.extend(page)
- if next_after is None:
- break
- after = next_after
- checkpoints = await store.list_checkpoints(thread.ref, limit=100)
- return {
- "schema": "opencompany.agent-context.redacted.v1",
- "redacted": True,
- "context": {
- "workflow_id": thread.ref.workflow_id,
- "context_node_id": thread.ref.context_node_id,
- "generation": thread.ref.generation,
- "thread_id": thread.ref.thread_id,
- "epoch": thread.ref.epoch,
- "revision": thread.ref.revision,
- "provider": thread.provider,
- "status": thread.status,
- "active_token_count": thread.active_token_count,
- },
- "checkpoints": [
- {
- "provider": checkpoint.provider,
- "strategy": checkpoint.strategy,
- "covers_through_sequence": (
- checkpoint.covers_through_sequence
- ),
- "active_token_count": checkpoint.active_token_count,
- "source_revision": checkpoint.source_revision,
- "source_hash": checkpoint.source_hash,
- "replay_payload_redacted": True,
- }
- for checkpoint in checkpoints
- ],
- "events": [_redacted_event(event) for event in events],
- "provider_bindings_redacted": True,
- }
-
-
-@ws_response
-async def handle_export_agent_context(
- data: Dict[str, Any],
- websocket: WebSocket,
-) -> Dict[str, Any]:
+ workflow_id = str(data.get("workflow_id") or "")
+ context_node_id = str(data.get("context_node_id") or "")
await _authorize_context_node(
websocket=websocket,
- workflow_id=str(data.get("workflow_id") or ""),
- context_node_id=str(data.get("context_node_id") or ""),
+ workflow_id=workflow_id,
+ context_node_id=context_node_id,
)
- store = _store()
- thread = await _select_thread(store, data)
- export = (
- await _redacted_export(store, thread)
- if thread is not None
- else {
- "schema": "opencompany.agent-context.redacted.v1",
- "redacted": True,
- "context": None,
- "checkpoints": [],
- "events": [],
- "provider_bindings_redacted": True,
- }
+ generation = _optional_generation(data)
+ agent_node_id = str(data.get("agent_node_id") or "") or None
+
+ cleared = await clear_conversation(
+ _database(),
+ workflow_id=workflow_id,
+ generation=generation,
+ agent_node_id=agent_node_id,
)
- safe_id = re.sub(
- r"[^A-Za-z0-9._-]+",
- "-",
- str(data["context_node_id"]),
- ).strip("-")
- return {
- "success": True,
- "filename": f"context-{safe_id or 'export'}-redacted.json",
- "content": json.dumps(
- export,
- ensure_ascii=False,
- indent=2,
- sort_keys=True,
- ),
- "export": export,
- }
+ try:
+ from services.cli_agent.factory import get_session_pool
+
+ pool = get_session_pool("claude")
+ terminate = getattr(pool, "terminate_conversations", None)
+ if callable(terminate):
+ await terminate(workflow_id, agent_node_id=agent_node_id)
+ except Exception as exc:
+ # Best-effort: the acquire-time generation fence still protects
+ # cross-generation reuse; only a same-generation warm process can
+ # linger, and it dies at the idle TTL.
+ logger.debug("[Context] pool termination skipped: %s", exc)
+ try:
+ await dispatch_context_updated(
+ workflow_id=workflow_id,
+ generation=generation or 0,
+ agent_node_id=agent_node_id or context_node_id,
+ message_count=0,
+ )
+ except Exception as exc:
+ logger.debug("[Context] clear broadcast failed: %s", exc)
+ return {"success": True, "cleared": cleared}
-WSHandler = Callable[
- [Dict[str, Any], WebSocket],
- Awaitable[Dict[str, Any]],
-]
+WSHandler = Callable[[Dict[str, Any], WebSocket], Awaitable[Dict[str, Any]]]
WS_HANDLERS: Dict[str, WSHandler] = {
"get_agent_context": handle_get_agent_context,
"clear_agent_context": handle_clear_agent_context,
- "fork_agent_context": handle_fork_agent_context,
- "export_agent_context": handle_export_agent_context,
}
-
__all__ = [
"WS_HANDLERS",
"handle_clear_agent_context",
- "handle_export_agent_context",
- "handle_fork_agent_context",
"handle_get_agent_context",
]
diff --git a/server/services/agent_context/__init__.py b/server/services/agent_context/__init__.py
index 4b4d4a41..731b3d24 100644
--- a/server/services/agent_context/__init__.py
+++ b/server/services/agent_context/__init__.py
@@ -1,56 +1,29 @@
-"""Durable Context V2 storage.
+"""Durable agent conversation storage — plain messages JSON under a key.
-The store is intentionally independent of agent/provider implementations.
-Runtimes append exact transitions and receive bounded references; provider
-adapters own rendering and replay validation.
+``(workflow_id, generation, agent_node_id) → messages`` — loaded at run
+start, saved per turn. See docs-internal/agent_context_flow.md for the
+flow and invariants. The former hash-chained journal (store / runtime /
+compaction / legacy / lifecycle) was retired in favor of this module.
"""
-from services.agent_context.store import (
- AgentContextError,
- AgentContextStore,
- CompactionConflictError,
- ContextArchivedError,
- ContextNotFoundError,
- RevisionConflictError,
- StaleEpochError,
+from services.agent_context.conversation import (
+ clear_conversation,
+ list_conversations,
+ load_conversation,
+ save_conversation,
)
-from services.agent_context.runtime import (
- AgentContextTransitionWriter,
- OpaqueCheckpointError,
- reconstruct_transcript,
- reconstruct_messages,
+from services.agent_context.listeners import (
+ ConversationListener,
+ notify_conversation_saved,
+ register_conversation_listener,
)
-from services.agent_context.compaction import (
- AgentContextCompactionService,
- ContextCompactionCandidate,
- ContextCompactionPolicy,
- ContextCompactionResult,
- ProviderContextAdapter,
- ProviderContextCapabilities,
- get_provider_context_adapter,
- provider_context_request_options,
-)
-from services.agent_context.legacy import import_generation_zero_handoff
__all__ = [
- "AgentContextError",
- "AgentContextCompactionService",
- "AgentContextStore",
- "AgentContextTransitionWriter",
- "CompactionConflictError",
- "ContextCompactionCandidate",
- "ContextCompactionPolicy",
- "ContextCompactionResult",
- "ContextArchivedError",
- "ContextNotFoundError",
- "OpaqueCheckpointError",
- "RevisionConflictError",
- "ProviderContextAdapter",
- "ProviderContextCapabilities",
- "StaleEpochError",
- "get_provider_context_adapter",
- "import_generation_zero_handoff",
- "provider_context_request_options",
- "reconstruct_transcript",
- "reconstruct_messages",
+ "ConversationListener",
+ "clear_conversation",
+ "list_conversations",
+ "load_conversation",
+ "notify_conversation_saved",
+ "register_conversation_listener",
+ "save_conversation",
]
diff --git a/server/services/agent_context/compaction.py b/server/services/agent_context/compaction.py
deleted file mode 100644
index 5857c453..00000000
--- a/server/services/agent_context/compaction.py
+++ /dev/null
@@ -1,771 +0,0 @@
-"""Capability-driven compaction for Agent Context V2.
-
-The raw journal is immutable. This module only selects a committed
-transaction prefix, asks a provider adapter for a replay candidate, validates
-that candidate, and compare-and-swap activates a checkpoint in
-``AgentContextStore``.
-
-Provider-specific behavior is registered behind :class:`ProviderContextAdapter`;
-the orchestration path never switches on provider names.
-"""
-
-from __future__ import annotations
-
-import json
-import re
-from copy import deepcopy
-from dataclasses import dataclass, field
-from typing import Any, Awaitable, Callable, Optional, Protocol, Sequence
-
-from models.agent_context import (
- AgentContextCheckpoint,
- AgentContextCompactionPlan,
- AgentContextEvent,
- AgentContextRef,
-)
-from services.agent_context.store import AgentContextStore
-from services.llm.protocol import message_from_wire, message_to_wire
-from services.model_registry import get_model_registry
-
-
-PortableCompactor = Callable[
- [list[dict[str, Any]], "ContextCompactionPolicy"],
- Awaitable["ContextCompactionCandidate"],
-]
-
-
-@dataclass(frozen=True)
-class ContextCompactionPolicy:
- mode: str = "auto"
- trigger_ratio: float = 0.8
- context_window_override: Optional[int] = None
- exact_tail_retention_count: int = 8
-
- @classmethod
- def from_mapping(
- cls,
- value: Optional[dict[str, Any]],
- ) -> "ContextCompactionPolicy":
- raw = value or {}
- mode = str(raw.get("compaction_mode") or "auto")
- if mode not in {"auto", "native", "portable", "disabled"}:
- mode = "auto"
- try:
- trigger_ratio = float(raw.get("trigger_ratio", 0.8))
- except (TypeError, ValueError):
- trigger_ratio = 0.8
- trigger_ratio = min(0.95, max(0.1, trigger_ratio))
- try:
- override = int(raw.get("context_window_override") or 0) or None
- except (TypeError, ValueError):
- override = None
- if override is not None:
- override = max(1024, override)
- try:
- tail = int(raw.get("exact_tail_retention_count", 8))
- except (TypeError, ValueError):
- tail = 8
- return cls(
- mode=mode,
- trigger_ratio=trigger_ratio,
- context_window_override=override,
- exact_tail_retention_count=max(1, min(1000, tail)),
- )
-
-
-@dataclass(frozen=True)
-class ProviderContextCapabilities:
- context_window: int
- supports_native_compaction: bool = False
- replay_fidelity: str = "provider_replayable"
- native_strategy: Optional[str] = None
-
-
-@dataclass(frozen=True)
-class ContextCompactionCandidate:
- strategy: str
- replay_payload: dict[str, Any]
- active_token_count: int
- lifetime_usage: dict[str, int] = field(default_factory=dict)
-
-
-@dataclass(frozen=True)
-class ContextCompactionResult:
- ref: AgentContextRef
- pressure_tokens: int
- context_window: int
- compacted: bool = False
- checkpoint: Optional[AgentContextCheckpoint] = None
- reason: str = ""
- lifetime_usage: dict[str, int] = field(default_factory=dict)
-
-
-class ProviderContextAdapter(Protocol):
- """Provider replay/pressure boundary required by Context V2."""
-
- def capabilities(self, model: str) -> ProviderContextCapabilities: ...
-
- def measure_active_context(self, rendered_request: Any) -> int: ...
-
- async def compact(
- self,
- committed_prefix: Sequence[AgentContextEvent],
- policy: ContextCompactionPolicy,
- *,
- base_replay: Optional[dict[str, Any]] = None,
- resolved_messages: Optional[list[dict[str, Any]]] = None,
- portable_compactor: Optional[PortableCompactor] = None,
- ) -> Optional[ContextCompactionCandidate]: ...
-
- def validate_replay(
- self,
- candidate: ContextCompactionCandidate,
- ) -> bool: ...
-
- def request_options(
- self,
- *,
- model: str,
- policy: ContextCompactionPolicy,
- context_window: int,
- ) -> Optional[dict[str, Any]]: ...
-
-
-class PortableContextAdapter:
- """Structured portable fallback used when native support is unverified."""
-
- def __init__(self, provider: str = "portable") -> None:
- self.provider = provider
-
- def capabilities(self, model: str) -> ProviderContextCapabilities:
- registry = get_model_registry()
- return ProviderContextCapabilities(
- context_window=registry.get_context_length(model, self.provider),
- )
-
- def measure_active_context(self, rendered_request: Any) -> int:
- # Used only when a provider did not return exact input usage. The
- # estimate is deliberately conservative and deterministic.
- encoded = json.dumps(
- rendered_request,
- ensure_ascii=False,
- separators=(",", ":"),
- default=str,
- ).encode("utf-8")
- return max(1, (len(encoded) + 2) // 3)
-
- async def compact(
- self,
- committed_prefix: Sequence[AgentContextEvent],
- policy: ContextCompactionPolicy,
- *,
- base_replay: Optional[dict[str, Any]] = None,
- resolved_messages: Optional[list[dict[str, Any]]] = None,
- portable_compactor: Optional[PortableCompactor] = None,
- ) -> Optional[ContextCompactionCandidate]:
- if portable_compactor is None:
- return None
- wires = (
- deepcopy(resolved_messages)
- if resolved_messages is not None
- else _base_messages(base_replay)
- )
- if resolved_messages is None:
- wires.extend(_message_wires(committed_prefix))
- if not wires:
- return None
- return await portable_compactor(wires, policy)
-
- def validate_replay(
- self,
- candidate: ContextCompactionCandidate,
- ) -> bool:
- messages = candidate.replay_payload.get("messages")
- if not isinstance(messages, list) or not messages:
- return False
- try:
- for wire in messages:
- if not isinstance(wire, dict):
- return False
- message_from_wire(wire)
- except (TypeError, ValueError):
- return False
- return candidate.active_token_count >= 0
-
- def request_options(
- self,
- *,
- model: str,
- policy: ContextCompactionPolicy,
- context_window: int,
- ) -> Optional[dict[str, Any]]:
- del model, policy, context_window
- return None
-
-
-class NativeOutputContextAdapter(PortableContextAdapter):
- """Replay adapter for providers that emit a compaction output block."""
-
- def __init__(
- self,
- provider: str,
- *,
- model_pattern: str,
- payload_collection: str,
- compaction_type: str = "compaction",
- native_strategy: str,
- minimum_trigger_tokens: int = 1,
- durability_pause: bool = False,
- ) -> None:
- super().__init__(provider)
- self._model_pattern = re.compile(model_pattern, re.IGNORECASE)
- self._payload_collection = payload_collection
- self._compaction_type = compaction_type
- self._native_strategy = native_strategy
- self._minimum_trigger_tokens = minimum_trigger_tokens
- self._durability_pause = durability_pause
-
- def capabilities(self, model: str) -> ProviderContextCapabilities:
- base = super().capabilities(model)
- supported = bool(self._model_pattern.search(model or ""))
- return ProviderContextCapabilities(
- context_window=base.context_window,
- supports_native_compaction=supported,
- replay_fidelity=base.replay_fidelity,
- native_strategy=self._native_strategy if supported else None,
- )
-
- async def compact(
- self,
- committed_prefix: Sequence[AgentContextEvent],
- policy: ContextCompactionPolicy,
- *,
- base_replay: Optional[dict[str, Any]] = None,
- resolved_messages: Optional[list[dict[str, Any]]] = None,
- portable_compactor: Optional[PortableCompactor] = None,
- ) -> Optional[ContextCompactionCandidate]:
- native = self._native_candidate(committed_prefix)
- if native is not None:
- return native
- if policy.mode == "native":
- return None
- return await super().compact(
- committed_prefix,
- policy,
- base_replay=base_replay,
- resolved_messages=resolved_messages,
- portable_compactor=portable_compactor,
- )
-
- def request_options(
- self,
- *,
- model: str,
- policy: ContextCompactionPolicy,
- context_window: int,
- ) -> Optional[dict[str, Any]]:
- capabilities = self.capabilities(model)
- if (
- policy.mode not in {"auto", "native"}
- or not capabilities.supports_native_compaction
- ):
- return None
- threshold = max(
- self._minimum_trigger_tokens,
- int(context_window * policy.trigger_ratio),
- )
- if threshold >= context_window:
- return None
- return {
- "type": "compaction",
- "compact_threshold": threshold,
- "pause_after_compaction": self._durability_pause,
- "strategy": self._native_strategy,
- }
-
- def _native_candidate(
- self,
- committed_prefix: Sequence[AgentContextEvent],
- ) -> Optional[ContextCompactionCandidate]:
- for event in reversed(committed_prefix):
- wire = event.message_wire
- if not isinstance(wire, dict):
- continue
- state = wire.get("provider_state")
- if not isinstance(state, dict) or state.get("provider") != self.provider:
- continue
- payload = state.get("payload")
- if not isinstance(payload, dict):
- continue
- blocks = payload.get(self._payload_collection)
- if not isinstance(blocks, list):
- continue
- marker_index = -1
- for index, block in enumerate(blocks):
- if (
- isinstance(block, dict)
- and block.get("type") == self._compaction_type
- ):
- marker_index = index
- if marker_index < 0:
- continue
- compacted_wire = deepcopy(wire)
- compacted_state = compacted_wire["provider_state"]
- compacted_payload = compacted_state["payload"]
- # Provider documentation requires passing the canonical compacted
- # output unchanged. We only discard blocks preceding the latest
- # provider-issued compaction marker.
- compacted_payload[self._payload_collection] = deepcopy(
- blocks[marker_index:]
- )
- measured = self.measure_active_context([compacted_wire])
- return ContextCompactionCandidate(
- strategy=self._native_strategy,
- replay_payload={"messages": [compacted_wire]},
- active_token_count=measured,
- )
- return None
-
-
-_ADAPTERS: dict[str, ProviderContextAdapter] = {}
-
-
-def register_provider_context_adapter(
- provider: str,
- adapter: ProviderContextAdapter,
-) -> None:
- normalized = provider.strip().lower()
- if not normalized:
- raise ValueError("provider is required")
- current = _ADAPTERS.get(normalized)
- if current is not None and current is not adapter:
- raise ValueError(f"Context adapter already registered for {normalized}")
- _ADAPTERS[normalized] = adapter
-
-
-def get_provider_context_adapter(provider: str) -> ProviderContextAdapter:
- normalized = str(provider or "").strip().lower()
- return _ADAPTERS.get(normalized) or PortableContextAdapter(
- normalized or "portable"
- )
-
-
-def provider_context_request_options(
- *,
- provider: str,
- model: str,
- policy: ContextCompactionPolicy,
-) -> Optional[dict[str, Any]]:
- adapter = get_provider_context_adapter(provider)
- capabilities = adapter.capabilities(model)
- context_window = (
- policy.context_window_override or capabilities.context_window
- )
- return adapter.request_options(
- model=model,
- policy=policy,
- context_window=context_window,
- )
-
-
-class AgentContextCompactionService:
- """CAS checkpoint orchestration over one durable Context store."""
-
- def __init__(self, store: AgentContextStore) -> None:
- self.store = store
-
- async def update_pressure_and_compact(
- self,
- ref: AgentContextRef,
- *,
- operation_id: str,
- provider: str,
- model: str,
- policy: ContextCompactionPolicy,
- active_input_tokens: int,
- output_headroom: int,
- rendered_request: Any = None,
- portable_compactor: Optional[PortableCompactor] = None,
- ) -> ContextCompactionResult:
- adapter = get_provider_context_adapter(provider)
- capabilities = adapter.capabilities(model)
- context_window = (
- policy.context_window_override or capabilities.context_window
- )
- measured_input = (
- max(0, int(adapter.measure_active_context(rendered_request)))
- if rendered_request is not None
- else 0
- )
- pressure_tokens = max(
- 0,
- active_input_tokens,
- measured_input,
- ) + max(
- 0, output_headroom
- )
- current_ref = await self.store.record_active_pressure(
- ref,
- operation_id=f"{operation_id}:pressure",
- active_token_count=pressure_tokens,
- )
- if policy.mode == "disabled":
- return ContextCompactionResult(
- ref=current_ref,
- pressure_tokens=pressure_tokens,
- context_window=context_window,
- reason="disabled",
- )
-
- state = await self.store.load_active(current_ref)
- native_marker_sequence = _native_compaction_marker_sequence(
- adapter,
- state.tail,
- )
- if native_marker_sequence is not None:
- # A native marker is itself the provider-issued replay boundary.
- # Never claim later tool/final events as covered by a candidate
- # whose payload contains only state through this marker.
- coverage = native_marker_sequence
- else:
- coverage = select_compaction_boundary(
- state.tail,
- exact_tail_retention_count=(
- policy.exact_tail_retention_count
- ),
- )
- if coverage is None:
- return ContextCompactionResult(
- ref=state.ref,
- pressure_tokens=pressure_tokens,
- context_window=context_window,
- reason="no_committed_prefix",
- )
-
- native_present = _has_native_compaction_marker(
- adapter,
- state.tail,
- coverage,
- )
- triggered = (
- context_window > 0
- and pressure_tokens >= int(context_window * policy.trigger_ratio)
- )
- if not native_present and not triggered:
- return ContextCompactionResult(
- ref=state.ref,
- pressure_tokens=pressure_tokens,
- context_window=context_window,
- reason="below_threshold",
- )
- if (
- policy.mode == "native"
- and not capabilities.supports_native_compaction
- ):
- return ContextCompactionResult(
- ref=state.ref,
- pressure_tokens=pressure_tokens,
- context_window=context_window,
- reason="native_unsupported",
- )
-
- strategy = (
- capabilities.native_strategy
- if native_present and capabilities.native_strategy
- else "portable"
- )
- plan = await self.store.prepare_compaction(
- state.ref,
- operation_id=f"{operation_id}:prepare",
- provider=provider,
- strategy=strategy,
- covers_through_sequence=coverage,
- )
- base_replay = await self._base_replay(plan)
- source_wires = await self._resolve_plan_messages(
- plan,
- base_replay=base_replay,
- )
- source_pressure = max(
- pressure_tokens,
- adapter.measure_active_context(source_wires)
- + max(0, output_headroom),
- )
- try:
- candidate = await adapter.compact(
- plan.committed_prefix,
- policy,
- base_replay=base_replay,
- resolved_messages=source_wires,
- portable_compactor=portable_compactor,
- )
- if candidate is None:
- await self.store.fail_compaction(
- attempt_id=plan.attempt_id,
- error_code="candidate_unavailable",
- )
- return ContextCompactionResult(
- ref=state.ref,
- pressure_tokens=pressure_tokens,
- context_window=context_window,
- reason="candidate_unavailable",
- )
- candidate_pressure = (
- candidate.active_token_count + max(0, output_headroom)
- )
- if (
- not adapter.validate_replay(candidate)
- or candidate_pressure >= source_pressure
- ):
- await self.store.fail_compaction(
- attempt_id=plan.attempt_id,
- error_code="candidate_validation_failed",
- )
- return ContextCompactionResult(
- ref=state.ref,
- pressure_tokens=pressure_tokens,
- context_window=context_window,
- reason="candidate_validation_failed",
- lifetime_usage=candidate.lifetime_usage,
- )
- replay_ref = await self.store.put_blob(
- candidate.replay_payload
- )
- checkpoint = await self.store.commit_checkpoint(
- state.ref,
- attempt_id=plan.attempt_id,
- operation_id=f"{operation_id}:commit",
- replay_payload_ref=replay_ref,
- active_token_count=candidate_pressure,
- )
- latest = (await self.store.load_active(state.ref)).ref
- return ContextCompactionResult(
- ref=latest,
- pressure_tokens=candidate_pressure,
- context_window=context_window,
- compacted=True,
- checkpoint=checkpoint,
- reason=candidate.strategy,
- lifetime_usage=candidate.lifetime_usage,
- )
- except BaseException:
- await self.store.fail_compaction(
- attempt_id=plan.attempt_id,
- error_code="candidate_exception",
- )
- raise
-
- async def _base_replay(
- self,
- plan: AgentContextCompactionPlan,
- ) -> Optional[dict[str, Any]]:
- if plan.base_checkpoint is None:
- return None
- value = await self.store.get_blob(
- plan.base_checkpoint.replay_payload_ref
- )
- return value if isinstance(value, dict) else None
-
- async def _resolve_plan_messages(
- self,
- plan: AgentContextCompactionPlan,
- *,
- base_replay: Optional[dict[str, Any]],
- ) -> list[dict[str, Any]]:
- snapshot_messages: Optional[list[dict[str, Any]]] = None
- snapshot_sequence = 0
- for event in reversed(plan.committed_prefix):
- if (
- event.event_type != "request.snapshot"
- or not event.payload_ref
- ):
- continue
- payload = await self.store.get_blob(event.payload_ref)
- candidates = (
- payload.get("messages")
- if isinstance(payload, dict)
- else None
- )
- if not isinstance(candidates, list):
- continue
- snapshot_messages = []
- for candidate in candidates:
- if not isinstance(candidate, dict):
- raise ValueError(
- "request snapshot contains a non-message item"
- )
- snapshot_messages.append(
- dict(message_to_wire(message_from_wire(candidate)))
- )
- snapshot_sequence = event.sequence
- break
- wires = (
- snapshot_messages
- if snapshot_messages is not None
- else _base_messages(base_replay)
- )
- wires.extend(
- deepcopy(event.message_wire)
- for event in plan.committed_prefix
- if event.sequence > snapshot_sequence
- and isinstance(event.message_wire, dict)
- )
- return wires
-
-
-def select_compaction_boundary(
- events: Sequence[AgentContextEvent],
- *,
- exact_tail_retention_count: int,
-) -> Optional[int]:
- """Return the newest complete transaction before the retained exact tail."""
-
- if len(events) <= exact_tail_retention_count:
- return None
- last_candidate_index = len(events) - exact_tail_retention_count - 1
- for index in range(last_candidate_index, -1, -1):
- if _is_complete_transaction(events, index):
- return events[index].sequence
- return None
-
-
-def _is_complete_transaction(
- events: Sequence[AgentContextEvent],
- index: int,
-) -> bool:
- event = events[index]
- if event.event_type in {"response.final", "response.truncated"}:
- return True
- wire = event.message_wire
- if event.event_type == "message.assistant" and isinstance(wire, dict):
- calls = wire.get("tool_calls")
- return not isinstance(calls, list) or not calls
- if event.event_type != "message.tool_result":
- return False
-
- assistant_index: Optional[int] = None
- for candidate in range(index - 1, -1, -1):
- if events[candidate].event_type == "message.assistant":
- assistant_index = candidate
- break
- if assistant_index is None:
- return False
- assistant_wire = events[assistant_index].message_wire or {}
- calls = assistant_wire.get("tool_calls")
- if not isinstance(calls, list) or not calls:
- return False
- requested = {
- str(call.get("id") or "")
- for call in calls
- if isinstance(call, dict)
- }
- completed: set[str] = set()
- for result in events[assistant_index + 1 : index + 1]:
- if result.event_type == "message.assistant":
- return False
- if result.event_type != "message.tool_result":
- continue
- result_wire = result.message_wire or {}
- completed.add(str(result_wire.get("tool_call_id") or ""))
- return bool(requested) and requested.issubset(completed)
-
-
-def _message_wires(
- events: Sequence[AgentContextEvent],
-) -> list[dict[str, Any]]:
- return [
- deepcopy(event.message_wire)
- for event in events
- if isinstance(event.message_wire, dict)
- ]
-
-
-def _base_messages(
- replay: Optional[dict[str, Any]],
-) -> list[dict[str, Any]]:
- if not isinstance(replay, dict):
- return []
- messages = replay.get("messages")
- if not isinstance(messages, list):
- return []
- return [
- deepcopy(wire)
- for wire in messages
- if isinstance(wire, dict)
- ]
-
-
-def _has_native_compaction_marker(
- adapter: ProviderContextAdapter,
- tail: Sequence[AgentContextEvent],
- coverage: int,
-) -> bool:
- if not isinstance(adapter, NativeOutputContextAdapter):
- return False
- prefix = [event for event in tail if event.sequence <= coverage]
- return adapter._native_candidate(prefix) is not None
-
-
-def _native_compaction_marker_sequence(
- adapter: ProviderContextAdapter,
- tail: Sequence[AgentContextEvent],
-) -> Optional[int]:
- if not isinstance(adapter, NativeOutputContextAdapter):
- return None
- for event in reversed(tail):
- if adapter._native_candidate([event]) is not None:
- return event.sequence
- return None
-
-
-def _register_builtin_adapters() -> None:
- # OpenAI Responses emits an opaque encrypted ``compaction`` output item.
- register_provider_context_adapter(
- "openai",
- NativeOutputContextAdapter(
- "openai",
- model_pattern=r"^(gpt-5(?:[.-]|$)|o[134](?:[.-]|$))",
- payload_collection="output",
- native_strategy="openai_responses_compaction",
- ),
- )
- # Anthropic's beta Messages compaction returns a replayable compaction
- # block and supports a pause so the block can be committed durably first.
- register_provider_context_adapter(
- "anthropic",
- NativeOutputContextAdapter(
- "anthropic",
- model_pattern=(
- r"^claude-(?:sonnet-4-6|opus-4-[678]|"
- r"fable-5|mythos(?:-5|-preview))$"
- ),
- payload_collection="content",
- native_strategy="anthropic_compact_20260112",
- minimum_trigger_tokens=50_000,
- durability_pause=True,
- ),
- )
- register_provider_context_adapter(
- "gemini",
- PortableContextAdapter("gemini"),
- )
-
-
-_register_builtin_adapters()
-
-
-__all__ = [
- "AgentContextCompactionService",
- "ContextCompactionCandidate",
- "ContextCompactionPolicy",
- "ContextCompactionResult",
- "NativeOutputContextAdapter",
- "PortableCompactor",
- "PortableContextAdapter",
- "ProviderContextAdapter",
- "ProviderContextCapabilities",
- "get_provider_context_adapter",
- "provider_context_request_options",
- "register_provider_context_adapter",
- "select_compaction_boundary",
-]
diff --git a/server/services/agent_context/conversation.py b/server/services/agent_context/conversation.py
new file mode 100644
index 00000000..fab23421
--- /dev/null
+++ b/server/services/agent_context/conversation.py
@@ -0,0 +1,165 @@
+"""Plain conversation persistence: ``key → messages JSON``.
+
+The whole contract:
+
+- ``load_conversation`` — read the transcript at run start (missing row
+ is an empty conversation, never an error).
+- ``save_conversation`` — atomic upsert of the full transcript after a
+ turn, serialized per key by an in-process lock. Best-effort callers
+ (the LLM-step activity) must catch — persistence never fails a run.
+- ``clear_conversation`` — delete rows (panel clear, workflow cleanup).
+- ``list_conversations`` — metadata for the Context panel.
+
+Key = ``(workflow_id, generation, agent_node_id)``. Generation is part of
+the key, so a workflow Reset (new generation) is automatically a fresh
+conversation. Messages are the ``message_to_wire`` JSON dicts — the same
+shape the agent loop holds in memory and carries across continue-as-new.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime, timezone
+from typing import Any, Dict, List
+
+from sqlmodel import select
+
+from core.logging import get_logger
+from models.agent_context import AgentConversation
+from services.agent_context.listeners import notify_conversation_saved
+
+logger = get_logger(__name__)
+
+_LOCKS: Dict[tuple, asyncio.Lock] = {}
+
+
+def _lock(workflow_id: str, generation: int, agent_node_id: str) -> asyncio.Lock:
+ key = (workflow_id, generation, agent_node_id)
+ lock = _LOCKS.get(key)
+ if lock is None:
+ lock = _LOCKS.setdefault(key, asyncio.Lock())
+ return lock
+
+
+async def load_conversation(
+ database: Any,
+ *,
+ workflow_id: str,
+ generation: int,
+ agent_node_id: str,
+) -> List[Dict[str, Any]]:
+ """Return the stored transcript, or ``[]`` for a new conversation."""
+
+ async with database.get_session() as session:
+ result = await session.execute(
+ select(AgentConversation).where(
+ AgentConversation.workflow_id == workflow_id,
+ AgentConversation.generation == generation,
+ AgentConversation.agent_node_id == agent_node_id,
+ )
+ )
+ row = result.scalar_one_or_none()
+ return list(row.messages or []) if row else []
+
+
+async def save_conversation(
+ database: Any,
+ *,
+ workflow_id: str,
+ generation: int,
+ agent_node_id: str,
+ messages: List[Dict[str, Any]],
+) -> None:
+ """Upsert the full transcript for the key; notifies panel listeners."""
+
+ async with _lock(workflow_id, generation, agent_node_id):
+ async with database.get_session() as session:
+ result = await session.execute(
+ select(AgentConversation).where(
+ AgentConversation.workflow_id == workflow_id,
+ AgentConversation.generation == generation,
+ AgentConversation.agent_node_id == agent_node_id,
+ )
+ )
+ row = result.scalar_one_or_none()
+ if row is None:
+ row = AgentConversation(
+ workflow_id=workflow_id,
+ generation=generation,
+ agent_node_id=agent_node_id,
+ )
+ row.messages = [dict(m) for m in messages if isinstance(m, dict)]
+ row.updated_at = datetime.now(timezone.utc)
+ session.add(row)
+ await session.commit()
+ await notify_conversation_saved(
+ workflow_id=workflow_id,
+ generation=generation,
+ agent_node_id=agent_node_id,
+ message_count=len(messages),
+ )
+
+
+async def clear_conversation(
+ database: Any,
+ *,
+ workflow_id: str,
+ generation: int | None = None,
+ agent_node_id: str | None = None,
+) -> int:
+ """Delete matching conversations; returns the number of rows removed."""
+
+ async with database.get_session() as session:
+ query = select(AgentConversation).where(
+ AgentConversation.workflow_id == workflow_id
+ )
+ if generation is not None:
+ query = query.where(AgentConversation.generation == generation)
+ if agent_node_id is not None:
+ query = query.where(
+ AgentConversation.agent_node_id == agent_node_id
+ )
+ result = await session.execute(query)
+ rows = list(result.scalars())
+ for row in rows:
+ await session.delete(row)
+ await session.commit()
+ return len(rows)
+
+
+async def list_conversations(
+ database: Any,
+ *,
+ workflow_id: str,
+) -> List[Dict[str, Any]]:
+ """Panel metadata: one entry per stored conversation for the workflow."""
+
+ async with database.get_session() as session:
+ result = await session.execute(
+ select(AgentConversation)
+ .where(AgentConversation.workflow_id == workflow_id)
+ .order_by(
+ AgentConversation.generation.desc(),
+ AgentConversation.agent_node_id,
+ )
+ )
+ return [
+ {
+ "workflow_id": row.workflow_id,
+ "generation": row.generation,
+ "agent_node_id": row.agent_node_id,
+ "message_count": len(row.messages or []),
+ "updated_at": row.updated_at.isoformat()
+ if row.updated_at
+ else None,
+ }
+ for row in result.scalars()
+ ]
+
+
+__all__ = [
+ "clear_conversation",
+ "list_conversations",
+ "load_conversation",
+ "save_conversation",
+]
diff --git a/server/services/agent_context/legacy.py b/server/services/agent_context/legacy.py
deleted file mode 100644
index 01fc0de0..00000000
--- a/server/services/agent_context/legacy.py
+++ /dev/null
@@ -1,153 +0,0 @@
-"""One-time handoff from immutable generation-zero migration artifacts."""
-
-from __future__ import annotations
-
-import hashlib
-from typing import Any
-
-from models.agent_context import AgentContextRef, AgentContextThreadSummary
-from services.agent_context.store import AgentContextStore
-from services.llm.protocol import Message, message_to_wire
-
-
-async def import_generation_zero_handoff(
- store: AgentContextStore,
- target_ref: AgentContextRef,
-) -> AgentContextRef:
- """Copy legacy partial context into a live generation idempotently.
-
- Graph migration writes recognized legacy state to generation zero so the
- original artifact is immutable. A newly admitted generation receives a
- clearly labelled MessageWire boundary that can participate in normal
- replay. Provider bindings are copied only when their source thread is
- unambiguous; raw binding values remain in the blob store.
- """
-
- if target_ref.generation <= 0:
- return target_ref
- sources = await store.list_threads(
- workflow_id=target_ref.workflow_id,
- context_node_id=target_ref.context_node_id,
- generation=0,
- include_archived=True,
- limit=1000,
- )
- if not sources:
- return target_ref
-
- exact = [
- source
- for source in sources
- if source.ref.thread_id == target_ref.thread_id
- ]
- selected = exact or sorted(sources, key=lambda item: item.ref.thread_id)
- current = target_ref
- for source in selected:
- current = await _import_legacy_events(store, source, current)
-
- # A continuation UUID/interaction ID must not be guessed when multiple
- # legacy Memory sessions could have supplied it.
- if len(selected) == 1:
- await _copy_provider_bindings(store, selected[0], current)
- return current
-
-
-async def _import_legacy_events(
- store: AgentContextStore,
- source: AgentContextThreadSummary,
- target_ref: AgentContextRef,
-) -> AgentContextRef:
- after = 0
- current = target_ref
- while True:
- events, next_after = await store.load_journal_page(
- source.ref,
- after_sequence=after,
- limit=200,
- )
- for event in events:
- if event.event_type != "legacy_partial" or not event.payload_ref:
- continue
- payload = await store.get_blob(event.payload_ref)
- content = (
- payload.get("content")
- if isinstance(payload, dict)
- else None
- )
- if not content:
- continue
- message = Message(
- role="user",
- content=(
- "Legacy conversation context imported with "
- "legacy_partial fidelity. It may be incomplete; treat "
- "the current request and current system instruction as "
- "authoritative.\n\n"
- f"{content}"
- ),
- )
- result = await store.append_transition(
- current,
- event_type="legacy_partial.handoff",
- operation_id=_operation_id(
- "legacy-context-handoff",
- target_ref=current,
- source_identity=(
- f"{source.ref.thread_id}:{event.payload_hash}"
- ),
- ),
- message_wire=dict(message_to_wire(message)),
- payload_ref=event.payload_ref,
- provider="legacy",
- )
- current = result.ref
- if next_after is None:
- break
- after = next_after
- return current
-
-
-async def _copy_provider_bindings(
- store: AgentContextStore,
- source: AgentContextThreadSummary,
- target_ref: AgentContextRef,
-) -> None:
- bindings = await store.load_provider_bindings(source.ref)
- for binding in bindings:
- payload: Any = await store.get_blob(binding.binding_ref)
- await store.bind_provider(
- target_ref,
- provider=binding.provider,
- binding_type=binding.binding_type,
- binding=payload,
- operation_id=_operation_id(
- "legacy-context-binding",
- target_ref=target_ref,
- source_identity=(
- f"{source.ref.thread_id}:{binding.provider}:"
- f"{binding.binding_type}:"
- f"{binding.binding_ref.removeprefix('sha256:')}"
- ),
- ),
- fidelity=binding.fidelity,
- )
-
-
-def _operation_id(
- prefix: str,
- *,
- target_ref: AgentContextRef,
- source_identity: str,
-) -> str:
- # RuntimeMutation IDs are globally unique, not merely unique within a
- # Context thread. Include the complete target fence while keeping the
- # persisted identifier bounded.
- material = (
- f"{target_ref.workflow_id}:{target_ref.context_node_id}:"
- f"{target_ref.generation}:{target_ref.thread_id}:"
- f"{source_identity}"
- )
- return f"{prefix}:{hashlib.sha256(material.encode('utf-8')).hexdigest()}"
-
-
-__all__ = ["import_generation_zero_handoff"]
diff --git a/server/services/agent_context/lifecycle.py b/server/services/agent_context/lifecycle.py
deleted file mode 100644
index ffb607f1..00000000
--- a/server/services/agent_context/lifecycle.py
+++ /dev/null
@@ -1,44 +0,0 @@
-"""Best-effort cleanup for provider resources owned by a Context epoch."""
-
-from __future__ import annotations
-
-from core.logging import get_logger
-
-
-logger = get_logger(__name__)
-
-
-async def fence_context_provider_resources(
- *,
- context_node_id: str,
- thread_id: str,
- keep_epoch: int,
-) -> None:
- """Terminate warm provider state that belongs to an older epoch.
-
- The durable epoch in :class:`AgentContextStore` is authoritative. Pool
- cleanup is intentionally best-effort because the provider bridge also
- rejects stale epoch keys when they are acquired.
- """
-
- try:
- from services.cli_agent.factory import get_session_pool
-
- pool = get_session_pool("claude")
- terminate_context = getattr(pool, "terminate_context", None)
- if terminate_context is not None:
- await terminate_context(
- context_node_id,
- thread_id=thread_id,
- keep_epoch=keep_epoch,
- )
- except Exception as exc:
- logger.warning(
- "[Context] provider resource cleanup failed for %s/%s: %s",
- context_node_id,
- thread_id,
- exc,
- )
-
-
-__all__ = ["fence_context_provider_resources"]
diff --git a/server/services/agent_context/listeners.py b/server/services/agent_context/listeners.py
index 1884cd11..eeb4d818 100644
--- a/server/services/agent_context/listeners.py
+++ b/server/services/agent_context/listeners.py
@@ -1,73 +1,58 @@
-"""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
+"""Save notifications for durable conversation changes.
+
+``save_conversation`` is the one place every writer passes through — the
+in-process agent loop, the Temporal LLM activity, and the CLI-agent bridge.
+Emitting the "conversation advanced" notification there means a new writer
+gets live panel updates for free and no caller carries broadcast code.
+
+Layering: this service must never import ``nodes/`` (plugin
+self-containment), so it owns a fanout registry and the Context plugin
+registers its broadcaster from ``nodes/context/__init__.py`` — the same
+pattern as the other plugin-owned registries.
+
+Contract, and it is load-bearing: :func:`notify_conversation_saved` is
+best-effort. It never raises and never blocks on anything slower than an
+in-process broadcast — saves happen inside the Temporal LLM activity's
+post-send window, where a throwing or slow listener would fail a run over
a UI notification.
"""
from __future__ import annotations
-from typing import Awaitable, Callable, List, Optional
+from typing import Awaitable, Callable, List
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]]
+ConversationListener = Callable[..., Awaitable[None]]
-_LISTENERS: List[ContextCommitListener] = []
-_FANOUT: IdempotentList[ContextCommitListener] = IdempotentList(
- "agent_context_commit",
+_LISTENERS: List[ConversationListener] = []
+_FANOUT: IdempotentList[ConversationListener] = IdempotentList(
+ "agent_conversation_saved",
items=_LISTENERS,
)
-def register_context_commit_listener(listener: ContextCommitListener) -> None:
- """Register a callback fired after a Context thread durably advances.
+def register_conversation_listener(listener: ConversationListener) -> None:
+ """Register a callback fired after a conversation durably saves.
- 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.
+ Idempotent on re-import. 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,
+async def notify_conversation_saved(
*,
- provider: Optional[str],
- active_token_count: int,
- sequence: Optional[int] = None,
+ workflow_id: str,
+ generation: int,
+ agent_node_id: str,
+ message_count: int,
) -> 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.
- """
+ """Announce a durable save. Called only after a successful commit."""
if not _LISTENERS:
return
@@ -75,21 +60,21 @@ async def notify_context_commit(
for listener in list(_LISTENERS):
try:
await listener(
- ref=ref,
- provider=provider,
- active_token_count=active_token_count,
- sequence=sequence,
+ workflow_id=workflow_id,
+ generation=generation,
+ agent_node_id=agent_node_id,
+ message_count=message_count,
)
- except Exception: # noqa: BLE001 -- a notification may never fail a commit
+ except Exception: # noqa: BLE001 — a notification may never fail a save
logger.debug(
- "Context commit listener failed",
+ "Conversation listener failed",
listener=getattr(listener, "__qualname__", repr(listener)),
exc_info=True,
)
__all__ = [
- "ContextCommitListener",
- "notify_context_commit",
- "register_context_commit_listener",
+ "ConversationListener",
+ "notify_conversation_saved",
+ "register_conversation_listener",
]
diff --git a/server/services/agent_context/runtime.py b/server/services/agent_context/runtime.py
deleted file mode 100644
index 1ee89b6e..00000000
--- a/server/services/agent_context/runtime.py
+++ /dev/null
@@ -1,192 +0,0 @@
-"""Small runtime adapters bound to one Context thread."""
-
-from __future__ import annotations
-
-import asyncio
-from typing import Any, Optional
-
-from models.agent_context import (
- AgentContextAppendResult,
- AgentContextRef,
-)
-from services.agent_context.store import AgentContextStore
-from services.llm.protocol import (
- Message,
- message_from_wire,
- message_to_wire,
-)
-
-
-class OpaqueCheckpointError(RuntimeError):
- """Raised when a native replay payload cannot be rendered portably."""
-
-
-class AgentContextTransitionWriter:
- """Epoch-bound implementation of ``AgentContextTransitionSink``.
-
- The writer owns only the latest bounded ref. Payload bodies are moved to
- hash-addressed blob storage before the journal entry is committed.
- """
-
- def __init__(
- self,
- store: AgentContextStore,
- ref: AgentContextRef,
- ) -> None:
- self.store = store
- self.ref = ref
- self._append_lock = asyncio.Lock()
-
- async def append_transition(
- self,
- *,
- event_type: str,
- operation_id: str,
- provider: str,
- message_wire: Optional[dict[str, Any]] = None,
- payload: Optional[dict[str, Any]] = None,
- ) -> AgentContextAppendResult:
- payload_ref = (
- await self.store.put_blob(payload)
- if payload is not None
- else None
- )
- async with self._append_lock:
- result = await self.store.append_transition(
- self.ref,
- event_type=event_type,
- operation_id=operation_id,
- provider=provider,
- message_wire=message_wire,
- payload_ref=payload_ref,
- )
- self.ref = result.ref
- return result
-
-
-async def reconstruct_transcript(
- store: AgentContextStore,
- ref: AgentContextRef,
-) -> tuple[AgentContextRef, list[dict[str, Any]]]:
- """Reconstruct portable checkpoint messages plus the exact live tail.
-
- Provider-native checkpoints are intentionally opaque and must be replayed
- by that provider's context adapter. Portable checkpoints use a JSON
- object containing ``messages`` (or ``message_wire`` /
- ``replay_messages``) and can be reconstructed here.
- """
-
- state = await store.load_active(ref)
- checkpoint_wires: list[dict[str, Any]] = []
- if state.checkpoint is not None:
- payload = await store.get_blob(state.checkpoint.replay_payload_ref)
- candidates: Any
- if isinstance(payload, list):
- candidates = payload
- elif isinstance(payload, dict):
- candidates = (
- payload.get("messages")
- or payload.get("message_wire")
- or payload.get("replay_messages")
- )
- else:
- candidates = None
- if not isinstance(candidates, list):
- raise OpaqueCheckpointError(
- "checkpoint replay payload is provider-native"
- )
- for candidate in candidates:
- if not isinstance(candidate, dict):
- raise OpaqueCheckpointError(
- "portable checkpoint contains a non-message item"
- )
- checkpoint_wires.append(
- dict(message_to_wire(message_from_wire(candidate)))
- )
- # A provider fork starts a fresh epoch from an explicit portable handoff.
- # It is a replay boundary even before the first request snapshot exists.
- handoff_wires: Optional[list[dict[str, Any]]] = None
- handoff_sequence = 0
- for event in reversed(state.tail):
- if event.event_type != "provider_handoff" or not event.payload_ref:
- continue
- payload = await store.get_blob(event.payload_ref)
- candidates = (
- payload.get("messages") if isinstance(payload, dict) else None
- )
- if not isinstance(candidates, list):
- continue
- handoff_wires = []
- for candidate in candidates:
- if not isinstance(candidate, dict):
- raise OpaqueCheckpointError(
- "provider handoff contains a non-message item"
- )
- handoff_wires.append(
- dict(message_to_wire(message_from_wire(candidate)))
- )
- handoff_sequence = event.sequence
- break
-
- # Request snapshots are exact render boundaries. They include system and
- # user messages, which do not otherwise have a standalone transition in
- # the journal. Start from the latest committed snapshot and apply only
- # the assistant/tool transitions that followed it.
- snapshot_wires: Optional[list[dict[str, Any]]] = None
- snapshot_sequence = handoff_sequence
- for event in reversed(state.tail):
- if event.event_type != "request.snapshot" or not event.payload_ref:
- continue
- payload = await store.get_blob(event.payload_ref)
- candidates = (
- payload.get("messages") if isinstance(payload, dict) else None
- )
- if not isinstance(candidates, list):
- continue
- validated: list[dict[str, Any]] = []
- for candidate in candidates:
- if not isinstance(candidate, dict):
- raise OpaqueCheckpointError(
- "request snapshot contains a non-message item"
- )
- validated.append(
- dict(message_to_wire(message_from_wire(candidate)))
- )
- snapshot_wires = validated
- snapshot_sequence = event.sequence
- break
-
- wires = (
- snapshot_wires
- if snapshot_wires is not None
- else (
- handoff_wires
- if handoff_wires is not None
- else checkpoint_wires
- )
- )
- wires.extend(
- dict(event.message_wire)
- for event in state.tail
- if event.sequence > snapshot_sequence
- and event.message_wire is not None
- )
- return state.ref, wires
-
-
-async def reconstruct_messages(
- store: AgentContextStore,
- ref: AgentContextRef,
-) -> tuple[AgentContextRef, list[Message]]:
- """Typed convenience wrapper over :func:`reconstruct_transcript`."""
-
- current_ref, wires = await reconstruct_transcript(store, ref)
- return current_ref, [message_from_wire(wire) for wire in wires]
-
-
-__all__ = [
- "AgentContextTransitionWriter",
- "OpaqueCheckpointError",
- "reconstruct_transcript",
- "reconstruct_messages",
-]
diff --git a/server/services/agent_context/store.py b/server/services/agent_context/store.py
deleted file mode 100644
index bce11823..00000000
--- a/server/services/agent_context/store.py
+++ /dev/null
@@ -1,1911 +0,0 @@
-"""Transactional, append-only storage for Agent Context V2."""
-
-from __future__ import annotations
-
-import hashlib
-import json
-from contextlib import asynccontextmanager
-from copy import deepcopy
-from datetime import datetime, timezone
-from typing import Any, AsyncIterator, Optional
-
-from sqlalchemy import delete, update
-from sqlalchemy.exc import IntegrityError
-from sqlalchemy.ext.asyncio import AsyncSession
-from sqlmodel import select
-
-from models.agent_context import (
- AgentContextActiveState,
- AgentContextAppendResult,
- AgentContextBlobRecord,
- AgentContextCheckpoint,
- AgentContextCheckpointRecord,
- AgentContextCompactionAttemptRecord,
- AgentContextCompactionPlan,
- AgentContextEvent,
- AgentContextEventRecord,
- AgentContextProviderBinding,
- AgentContextProviderBindingRecord,
- AgentContextRef,
- AgentContextThreadRecord,
- AgentContextThreadSummary,
- ContextFidelity,
- ContextThreadKind,
-)
-from models.database import RuntimeMutation
-from services.agent_context.listeners import notify_context_commit
-from services.llm.protocol import (
- message_from_wire,
- message_to_wire,
-)
-
-
-ZERO_HASH = "0" * 64
-_MAX_CAS_ATTEMPTS = 12
-
-
-class AgentContextError(RuntimeError):
- """Base class for stable Context-store failures."""
-
-
-class ContextNotFoundError(AgentContextError):
- pass
-
-
-class ContextArchivedError(AgentContextError):
- pass
-
-
-class StaleEpochError(AgentContextError):
- pass
-
-
-class RevisionConflictError(AgentContextError):
- pass
-
-
-class CompactionConflictError(AgentContextError):
- pass
-
-
-class AgentContextStore:
- """Durable journal/checkpoint repository.
-
- ``database`` can be the application's :class:`core.database.Database` or
- an ``async_sessionmaker``. Keeping this boundary tiny makes the same store
- usable from in-process execution and Temporal activities.
- """
-
- def __init__(self, database: Any):
- self._database = database
-
- @asynccontextmanager
- async def _session(self) -> AsyncIterator[AsyncSession]:
- get_session = getattr(self._database, "get_session", None)
- if callable(get_session):
- async with get_session() as session:
- yield session
- return
- async with self._database() as session:
- yield session
-
- async def resolve_thread(
- self,
- *,
- workflow_id: str,
- context_node_id: str,
- generation: int,
- session_id: Optional[str] = None,
- delegated_task_id: Optional[str] = None,
- execution_id: Optional[str] = None,
- ) -> AgentContextRef:
- """Resolve the RFC priority order into one isolated durable thread."""
-
- kind, source_id = _resolve_thread_identity(
- session_id=session_id,
- delegated_task_id=delegated_task_id,
- execution_id=execution_id,
- )
- thread_id = _thread_id(kind, source_id)
- _validate_identity("workflow_id", workflow_id, 255)
- _validate_identity("context_node_id", context_node_id, 255)
- if generation < 0:
- raise ValueError("generation must be non-negative")
-
- for _ in range(_MAX_CAS_ATTEMPTS):
- async with self._session() as session:
- row = await _select_thread(
- session,
- workflow_id=workflow_id,
- context_node_id=context_node_id,
- generation=generation,
- thread_id=thread_id,
- )
- if row is not None:
- return _to_ref(row)
- row = AgentContextThreadRecord(
- workflow_id=workflow_id,
- context_node_id=context_node_id,
- generation=generation,
- thread_id=thread_id,
- thread_kind=kind,
- last_event_hash=ZERO_HASH,
- )
- session.add(row)
- try:
- await session.commit()
- await session.refresh(row)
- return _to_ref(row)
- except IntegrityError:
- await session.rollback()
- # Another worker resolved the same deterministic thread.
- continue
- raise RevisionConflictError("context_thread_resolution_conflict")
-
- async def load_active(
- self,
- ref: AgentContextRef,
- ) -> AgentContextActiveState:
- """Load the active checkpoint and exact tail for the current epoch."""
-
- async with self._session() as session:
- thread = await self._require_thread(session, ref)
- checkpoint_row: Optional[AgentContextCheckpointRecord] = None
- source_row: Optional[AgentContextEventRecord] = None
- if thread.active_checkpoint_id is not None:
- checkpoint_row = await session.get(
- AgentContextCheckpointRecord,
- thread.active_checkpoint_id,
- )
- if (
- checkpoint_row is None
- or checkpoint_row.context_thread_id != thread.id
- or checkpoint_row.epoch != thread.epoch
- or checkpoint_row.status != "active"
- or checkpoint_row.covers_through_sequence
- != thread.active_checkpoint_sequence
- or checkpoint_row.source_revision > thread.revision
- ):
- raise AgentContextError("active_checkpoint_invariant_broken")
- source_result = await session.execute(
- select(AgentContextEventRecord).where(
- AgentContextEventRecord.context_thread_id
- == thread.id,
- AgentContextEventRecord.epoch == thread.epoch,
- AgentContextEventRecord.sequence
- == checkpoint_row.covers_through_sequence,
- )
- )
- source_row = source_result.scalar_one_or_none()
- if (
- source_row is None
- or source_row.payload_hash != checkpoint_row.source_hash
- ):
- raise AgentContextError(
- "checkpoint_source_integrity_broken"
- )
- await _verified_blob_record(
- session,
- checkpoint_row.replay_payload_ref,
- )
- elif thread.active_checkpoint_sequence != 0:
- raise AgentContextError("active_checkpoint_invariant_broken")
- result = await session.execute(
- select(AgentContextEventRecord)
- .where(
- AgentContextEventRecord.context_thread_id == thread.id,
- AgentContextEventRecord.epoch == thread.epoch,
- AgentContextEventRecord.sequence
- > thread.active_checkpoint_sequence,
- )
- .order_by(AgentContextEventRecord.sequence)
- )
- tail_rows = list(result.scalars().all())
- await _verify_active_event_chain(
- session,
- thread,
- checkpoint_source=source_row,
- tail=tail_rows,
- )
- tail = [_to_event(row) for row in tail_rows]
- return AgentContextActiveState(
- ref=_to_ref(thread),
- checkpoint=(
- _to_checkpoint(checkpoint_row)
- if checkpoint_row is not None
- else None
- ),
- tail=tail,
- active_token_count=max(0, thread.active_token_count),
- )
-
- async def load_thread_summary(
- self,
- ref: AgentContextRef,
- ) -> AgentContextThreadSummary:
- """Load one exact thread's metadata without a bounded list scan."""
-
- async with self._session() as session:
- thread = await self._require_thread(session, ref)
- return _to_thread_summary(thread)
-
- async def list_threads(
- self,
- *,
- workflow_id: str,
- context_node_id: str,
- generation: Optional[int] = None,
- include_archived: bool = False,
- limit: int = 100,
- ) -> list[AgentContextThreadSummary]:
- """List bounded thread metadata without loading journal payloads."""
-
- _validate_identity("workflow_id", workflow_id, 255)
- _validate_identity("context_node_id", context_node_id, 255)
- limit = max(1, min(int(limit), 1000))
- async with self._session() as session:
- statement = select(AgentContextThreadRecord).where(
- AgentContextThreadRecord.workflow_id == workflow_id,
- AgentContextThreadRecord.context_node_id == context_node_id,
- )
- if generation is not None:
- statement = statement.where(
- AgentContextThreadRecord.generation == generation
- )
- if not include_archived:
- statement = statement.where(
- AgentContextThreadRecord.status == "active"
- )
- result = await session.execute(
- statement.order_by(
- AgentContextThreadRecord.generation.desc(),
- AgentContextThreadRecord.updated_at.desc(),
- AgentContextThreadRecord.id.desc(),
- ).limit(limit)
- )
- return [_to_thread_summary(row) for row in result.scalars().all()]
-
- async def iter_threads(
- self,
- *,
- workflow_id: str,
- context_node_id: str,
- generation: Optional[int] = None,
- include_archived: bool = False,
- page_size: int = 250,
- ) -> AsyncIterator[AgentContextThreadSummary]:
- """Keyset-scan thread metadata without a fixed total-result cap.
-
- Lifecycle operations mutate ``updated_at`` while consuming this
- iterator, so pagination is deliberately anchored to the immutable
- database row id instead of the presentation ordering used by
- :meth:`list_threads`.
- """
-
- _validate_identity("workflow_id", workflow_id, 255)
- _validate_identity("context_node_id", context_node_id, 255)
- page_size = max(1, min(int(page_size), 1000))
- after_id = 0
- while True:
- async with self._session() as session:
- statement = select(AgentContextThreadRecord).where(
- AgentContextThreadRecord.workflow_id == workflow_id,
- AgentContextThreadRecord.context_node_id
- == context_node_id,
- AgentContextThreadRecord.id > after_id,
- )
- if generation is not None:
- statement = statement.where(
- AgentContextThreadRecord.generation == generation
- )
- if not include_archived:
- statement = statement.where(
- AgentContextThreadRecord.status == "active"
- )
- result = await session.execute(
- statement.order_by(
- AgentContextThreadRecord.id.asc()
- ).limit(page_size)
- )
- rows = list(result.scalars().all())
- if not rows:
- return
- for row in rows:
- yield _to_thread_summary(row)
- last_id = rows[-1].id
- if last_id is None:
- raise AgentContextError("context_thread_identity_missing")
- after_id = int(last_id)
- if len(rows) < page_size:
- return
-
- async def load_journal_page(
- self,
- ref: AgentContextRef,
- *,
- after_sequence: int = 0,
- limit: int = 50,
- epoch: Optional[int] = None,
- ) -> tuple[list[AgentContextEvent], Optional[int]]:
- """Load raw journal without mutating it; optionally narrow an epoch."""
-
- after_sequence = max(0, int(after_sequence))
- limit = max(1, min(int(limit), 200))
- async with self._session() as session:
- thread = await self._require_thread(session, ref)
- conditions = [
- AgentContextEventRecord.context_thread_id == thread.id,
- AgentContextEventRecord.sequence > after_sequence,
- ]
- if epoch is not None:
- conditions.append(AgentContextEventRecord.epoch == epoch)
- result = await session.execute(
- select(AgentContextEventRecord)
- .where(*conditions)
- .order_by(AgentContextEventRecord.sequence)
- .limit(limit + 1)
- )
- rows = list(result.scalars().all())
- has_more = len(rows) > limit
- page = rows[:limit]
- next_after = page[-1].sequence if has_more and page else None
- return [_to_event(row) for row in page], next_after
-
- async def list_checkpoints(
- self,
- ref: AgentContextRef,
- *,
- limit: int = 20,
- ) -> list[AgentContextCheckpoint]:
- """List current-epoch checkpoint metadata, newest first."""
-
- limit = max(1, min(int(limit), 100))
- async with self._session() as session:
- thread = await self._require_thread(session, ref)
- result = await session.execute(
- select(AgentContextCheckpointRecord)
- .where(
- AgentContextCheckpointRecord.context_thread_id
- == thread.id,
- AgentContextCheckpointRecord.epoch == thread.epoch,
- )
- .order_by(
- AgentContextCheckpointRecord.covers_through_sequence.desc(),
- AgentContextCheckpointRecord.id.desc(),
- )
- .limit(limit)
- )
- return [
- _to_checkpoint(row) for row in result.scalars().all()
- ]
-
- async def append_transition(
- self,
- ref: AgentContextRef,
- *,
- event_type: str,
- operation_id: str,
- message_wire: Optional[dict[str, Any]] = None,
- payload_ref: Optional[str] = None,
- provider: Optional[str] = None,
- expected_revision: Optional[int] = None,
- ) -> AgentContextAppendResult:
- """Append one transition with ordering, hash chaining, and fencing."""
-
- _validate_identity("event_type", event_type, 100)
- _validate_identity("operation_id", operation_id, 512)
- if payload_ref is not None:
- _validate_identity("payload_ref", payload_ref, 512)
- if provider is not None:
- _validate_identity("provider", provider, 100)
- wire = _validate_message_wire(message_wire)
-
- for _ in range(_MAX_CAS_ATTEMPTS):
- async with self._session() as session:
- thread = await self._require_thread(
- session,
- ref,
- permit_archived=True,
- permit_stale_epoch=True,
- )
- existing = await _event_by_operation(
- session,
- thread_id=int(thread.id),
- operation_id=operation_id,
- )
- if existing is not None:
- _assert_idempotent_event_reuse(
- existing,
- event_type=event_type,
- message_wire=wire,
- payload_ref=payload_ref,
- provider=provider,
- )
- return AgentContextAppendResult(
- ref=_to_ref(thread),
- event=_to_event(existing),
- applied=False,
- )
- self._assert_writable(thread, ref)
- if (
- expected_revision is not None
- and thread.revision != expected_revision
- ):
- raise RevisionConflictError(
- f"context_revision_conflict:"
- f"{expected_revision}:{thread.revision}"
- )
-
- sequence = thread.next_sequence
- previous_hash = thread.last_event_hash or ZERO_HASH
- payload_hash = _event_hash(
- sequence=sequence,
- epoch=thread.epoch,
- event_type=event_type,
- message_wire=wire,
- payload_ref=payload_ref,
- operation_id=operation_id,
- provider=provider,
- previous_hash=previous_hash,
- )
- now = datetime.now(timezone.utc)
- event = AgentContextEventRecord(
- context_thread_id=int(thread.id),
- epoch=thread.epoch,
- sequence=sequence,
- event_type=event_type,
- message_wire=deepcopy(wire),
- payload_ref=payload_ref,
- operation_id=operation_id,
- provider=provider,
- previous_hash=previous_hash,
- payload_hash=payload_hash,
- created_at=now,
- )
- result = await session.execute(
- update(AgentContextThreadRecord)
- .where(
- AgentContextThreadRecord.id == thread.id,
- AgentContextThreadRecord.epoch == thread.epoch,
- AgentContextThreadRecord.revision == thread.revision,
- AgentContextThreadRecord.status == "active",
- )
- .values(
- next_sequence=sequence + 1,
- last_event_hash=payload_hash,
- revision=thread.revision + 1,
- provider=provider or thread.provider,
- updated_at=now,
- )
- .execution_options(synchronize_session=False)
- )
- if result.rowcount != 1:
- await session.rollback()
- if expected_revision is not None:
- raise RevisionConflictError(
- "context_revision_conflict"
- )
- continue
- try:
- session.add(event)
- await session.flush()
- session.add(
- RuntimeMutation(
- mutation_id=operation_id,
- resource_type="agent_context",
- resource_id=str(thread.id),
- operation="append_transition",
- result={
- "event_id": event.id,
- "sequence": sequence,
- "payload_hash": payload_hash,
- },
- )
- )
- await session.commit()
- except IntegrityError:
- 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),
- applied=True,
- )
- raise RevisionConflictError("context_append_conflict")
-
- async def record_active_pressure(
- self,
- ref: AgentContextRef,
- *,
- operation_id: str,
- active_token_count: int,
- ) -> AgentContextRef:
- """Persist next-request context pressure without changing the journal.
-
- Pressure is operational metadata, not lifetime billing. The update is
- fenced by the thread revision and idempotent through
- :class:`RuntimeMutation`; transcript or provider payloads never enter
- that ledger.
- """
-
- _validate_identity("operation_id", operation_id, 512)
- if active_token_count < 0:
- raise ValueError("active_token_count must be non-negative")
-
- for _ in range(_MAX_CAS_ATTEMPTS):
- async with self._session() as session:
- thread = await self._require_thread(
- session,
- ref,
- permit_stale_epoch=True,
- )
- prior = await _runtime_mutation(
- session,
- thread_id=int(thread.id),
- operation_id=operation_id,
- operation="record_active_pressure",
- )
- if prior is not None:
- return _to_ref(thread)
- self._assert_writable(thread, ref)
- now = datetime.now(timezone.utc)
- result = await session.execute(
- update(AgentContextThreadRecord)
- .where(
- AgentContextThreadRecord.id == thread.id,
- AgentContextThreadRecord.epoch == thread.epoch,
- AgentContextThreadRecord.revision == thread.revision,
- AgentContextThreadRecord.status == "active",
- )
- .values(
- active_token_count=active_token_count,
- revision=thread.revision + 1,
- updated_at=now,
- )
- .execution_options(synchronize_session=False)
- )
- if result.rowcount != 1:
- await session.rollback()
- continue
- session.add(
- RuntimeMutation(
- mutation_id=operation_id,
- resource_type="agent_context",
- resource_id=str(thread.id),
- operation="record_active_pressure",
- result={"active_token_count": active_token_count},
- )
- )
- try:
- await session.commit()
- except IntegrityError:
- await session.rollback()
- continue
- 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(
- self,
- ref: AgentContextRef,
- *,
- operation_id: str,
- provider: str,
- strategy: str,
- covers_through_sequence: int,
- ) -> AgentContextCompactionPlan:
- """Lease a stable committed prefix without changing active replay."""
-
- _validate_identity("operation_id", operation_id, 512)
- _validate_identity("provider", provider, 100)
- _validate_identity("strategy", strategy, 100)
- async with self._session() as session:
- thread = await self._require_thread(session, ref)
- self._assert_writable(thread, ref)
- existing_result = await session.execute(
- select(AgentContextCompactionAttemptRecord).where(
- AgentContextCompactionAttemptRecord.context_thread_id
- == thread.id,
- AgentContextCompactionAttemptRecord.operation_id
- == operation_id,
- )
- )
- existing = existing_result.scalar_one_or_none()
- if existing is not None:
- return await _to_plan(session, thread, existing)
-
- if (
- covers_through_sequence
- <= thread.active_checkpoint_sequence
- or covers_through_sequence >= thread.next_sequence
- ):
- raise ValueError("invalid_compaction_coverage")
- source_result = await session.execute(
- select(AgentContextEventRecord).where(
- AgentContextEventRecord.context_thread_id == thread.id,
- AgentContextEventRecord.epoch == thread.epoch,
- AgentContextEventRecord.sequence
- == covers_through_sequence,
- )
- )
- source = source_result.scalar_one_or_none()
- if source is None:
- raise ValueError("compaction_source_event_not_found")
- attempt = AgentContextCompactionAttemptRecord(
- context_thread_id=int(thread.id),
- epoch=thread.epoch,
- provider=provider,
- strategy=strategy,
- covers_through_sequence=covers_through_sequence,
- base_checkpoint_id=thread.active_checkpoint_id,
- base_checkpoint_sequence=thread.active_checkpoint_sequence,
- source_revision=thread.revision,
- source_hash=source.payload_hash,
- operation_id=operation_id,
- )
- session.add(attempt)
- try:
- await session.flush()
- session.add(
- RuntimeMutation(
- mutation_id=operation_id,
- resource_type="agent_context",
- resource_id=str(thread.id),
- operation="prepare_compaction",
- result={
- "attempt_id": attempt.id,
- "source_hash": source.payload_hash,
- },
- )
- )
- await session.commit()
- except IntegrityError:
- await session.rollback()
- # The operation can only race with an identical preparation.
- retry = await session.execute(
- select(AgentContextCompactionAttemptRecord).where(
- AgentContextCompactionAttemptRecord.context_thread_id
- == thread.id,
- AgentContextCompactionAttemptRecord.operation_id
- == operation_id,
- )
- )
- attempt = retry.scalar_one_or_none()
- if attempt is None:
- raise RevisionConflictError(
- "compaction_prepare_conflict"
- )
- return await _to_plan(session, thread, attempt)
-
- async def commit_checkpoint(
- self,
- ref: AgentContextRef,
- *,
- attempt_id: int,
- operation_id: str,
- replay_payload_ref: str,
- active_token_count: int,
- ) -> AgentContextCheckpoint:
- """CAS-activate a validated candidate, retaining concurrent tail."""
-
- _validate_identity("operation_id", operation_id, 512)
- _validate_identity("replay_payload_ref", replay_payload_ref, 512)
- if active_token_count < 0:
- raise ValueError("active_token_count must be non-negative")
-
- for _ in range(_MAX_CAS_ATTEMPTS):
- async with self._session() as session:
- thread = await self._require_thread(
- session,
- ref,
- permit_stale_epoch=True,
- )
- existing_result = await session.execute(
- select(AgentContextCheckpointRecord).where(
- AgentContextCheckpointRecord.context_thread_id
- == thread.id,
- AgentContextCheckpointRecord.operation_id
- == operation_id,
- )
- )
- existing = existing_result.scalar_one_or_none()
- if existing is not None:
- return _to_checkpoint(existing)
- self._assert_writable(thread, ref)
- attempt = await session.get(
- AgentContextCompactionAttemptRecord,
- attempt_id,
- )
- if (
- attempt is None
- or attempt.context_thread_id != thread.id
- ):
- raise ContextNotFoundError(
- "compaction_attempt_not_found"
- )
- if attempt.status == "committed" and attempt.checkpoint_id:
- checkpoint = await session.get(
- AgentContextCheckpointRecord,
- attempt.checkpoint_id,
- )
- if checkpoint is None:
- raise AgentContextError(
- "committed_checkpoint_missing"
- )
- return _to_checkpoint(checkpoint)
- if attempt.status != "prepared":
- raise CompactionConflictError(
- f"compaction_attempt_{attempt.status}"
- )
- if attempt.epoch != thread.epoch:
- raise StaleEpochError("compaction_epoch_fenced")
- if (
- attempt.base_checkpoint_id != thread.active_checkpoint_id
- or attempt.base_checkpoint_sequence
- != thread.active_checkpoint_sequence
- ):
- raise CompactionConflictError(
- "active_checkpoint_changed"
- )
- source_result = await session.execute(
- select(AgentContextEventRecord).where(
- AgentContextEventRecord.context_thread_id == thread.id,
- AgentContextEventRecord.epoch == thread.epoch,
- AgentContextEventRecord.sequence
- == attempt.covers_through_sequence,
- )
- )
- source = source_result.scalar_one_or_none()
- if (
- source is None
- or source.payload_hash != attempt.source_hash
- ):
- raise CompactionConflictError(
- "compaction_source_changed"
- )
-
- checkpoint = AgentContextCheckpointRecord(
- context_thread_id=int(thread.id),
- epoch=thread.epoch,
- provider=attempt.provider,
- strategy=attempt.strategy,
- covers_through_sequence=attempt.covers_through_sequence,
- replay_payload_ref=replay_payload_ref,
- active_token_count=active_token_count,
- source_revision=attempt.source_revision,
- source_hash=attempt.source_hash,
- operation_id=operation_id,
- status="active",
- )
- session.add(checkpoint)
- await session.flush()
- now = datetime.now(timezone.utc)
- result = await session.execute(
- update(AgentContextThreadRecord)
- .where(
- AgentContextThreadRecord.id == thread.id,
- AgentContextThreadRecord.epoch == thread.epoch,
- AgentContextThreadRecord.revision == thread.revision,
- AgentContextThreadRecord.active_checkpoint_id
- == attempt.base_checkpoint_id,
- AgentContextThreadRecord.active_checkpoint_sequence
- == attempt.base_checkpoint_sequence,
- )
- .values(
- active_checkpoint_id=checkpoint.id,
- active_checkpoint_sequence=(
- attempt.covers_through_sequence
- ),
- active_token_count=active_token_count,
- revision=thread.revision + 1,
- updated_at=now,
- )
- .execution_options(synchronize_session=False)
- )
- if result.rowcount != 1:
- await session.rollback()
- continue
- if attempt.base_checkpoint_id is not None:
- await session.execute(
- update(AgentContextCheckpointRecord)
- .where(
- AgentContextCheckpointRecord.id
- == attempt.base_checkpoint_id
- )
- .values(status="superseded")
- )
- attempt.status = "committed"
- attempt.checkpoint_id = checkpoint.id
- attempt.completed_at = now
- session.add(
- RuntimeMutation(
- mutation_id=operation_id,
- resource_type="agent_context",
- resource_id=str(thread.id),
- operation="commit_checkpoint",
- result={
- "checkpoint_id": checkpoint.id,
- "source_hash": attempt.source_hash,
- },
- )
- )
- try:
- await session.commit()
- except IntegrityError:
- await session.rollback()
- continue
- return _to_checkpoint(checkpoint)
- raise CompactionConflictError("checkpoint_activation_conflict")
-
- async def fail_compaction(
- self,
- *,
- attempt_id: int,
- error_code: str,
- ) -> None:
- """Record a failed candidate without touching active replay state."""
-
- _validate_identity("error_code", error_code, 255)
- async with self._session() as session:
- attempt = await session.get(
- AgentContextCompactionAttemptRecord,
- attempt_id,
- )
- if attempt is None:
- raise ContextNotFoundError("compaction_attempt_not_found")
- if attempt.status == "prepared":
- attempt.status = "failed"
- attempt.error_code = error_code
- attempt.completed_at = datetime.now(timezone.utc)
- await session.commit()
-
- async def start_epoch(
- self,
- ref: AgentContextRef,
- *,
- operation_id: str,
- provider: Optional[str] = None,
- handoff_payload_ref: Optional[str] = None,
- ) -> AgentContextRef:
- """Rotate an epoch and fence every writer holding the old ref."""
-
- _validate_identity("operation_id", operation_id, 512)
- if provider is not None:
- _validate_identity("provider", provider, 100)
- if handoff_payload_ref is not None:
- _validate_identity(
- "handoff_payload_ref",
- handoff_payload_ref,
- 512,
- )
- request_hash = _mutation_request_hash(
- "start_epoch",
- {
- "provider": provider,
- "handoff_payload_ref": handoff_payload_ref,
- },
- )
- async with self._session() as session:
- thread = await self._require_thread(
- session,
- ref,
- permit_archived=True,
- permit_stale_epoch=True,
- )
- prior = await _runtime_mutation(
- session,
- thread_id=int(thread.id),
- operation_id=operation_id,
- operation="start_epoch",
- )
- if prior is not None:
- _assert_idempotent_mutation_reuse(
- prior,
- request_hash=request_hash,
- )
- return _to_ref(thread)
- self._assert_writable(thread, ref)
- now = datetime.now(timezone.utc)
- next_epoch = thread.epoch + 1
- next_revision = thread.revision + 1
- next_sequence = thread.next_sequence
- last_hash = thread.last_event_hash
- handoff_event: Optional[AgentContextEventRecord] = None
- await session.execute(
- update(AgentContextProviderBindingRecord)
- .where(
- AgentContextProviderBindingRecord.context_thread_id
- == thread.id,
- AgentContextProviderBindingRecord.epoch == thread.epoch,
- AgentContextProviderBindingRecord.status == "active",
- )
- .values(status="archived")
- )
- await session.execute(
- update(AgentContextCheckpointRecord)
- .where(
- AgentContextCheckpointRecord.context_thread_id
- == thread.id,
- AgentContextCheckpointRecord.epoch == thread.epoch,
- AgentContextCheckpointRecord.status == "active",
- )
- .values(status="archived")
- )
- await session.execute(
- update(AgentContextCompactionAttemptRecord)
- .where(
- AgentContextCompactionAttemptRecord.context_thread_id
- == thread.id,
- AgentContextCompactionAttemptRecord.epoch == thread.epoch,
- AgentContextCompactionAttemptRecord.status == "prepared",
- )
- .values(
- status="stale",
- error_code="epoch_rotated",
- completed_at=now,
- )
- )
- if handoff_payload_ref is not None:
- handoff_operation = f"{operation_id}:handoff"
- handoff_hash = _event_hash(
- sequence=next_sequence,
- epoch=next_epoch,
- event_type="provider_handoff",
- message_wire=None,
- payload_ref=handoff_payload_ref,
- operation_id=handoff_operation,
- provider=provider,
- previous_hash=last_hash,
- )
- handoff_event = AgentContextEventRecord(
- context_thread_id=int(thread.id),
- epoch=next_epoch,
- sequence=next_sequence,
- event_type="provider_handoff",
- payload_ref=handoff_payload_ref,
- operation_id=handoff_operation,
- provider=provider,
- previous_hash=last_hash,
- payload_hash=handoff_hash,
- )
- next_sequence += 1
- next_revision += 1
- last_hash = handoff_hash
- result = await session.execute(
- update(AgentContextThreadRecord)
- .where(
- AgentContextThreadRecord.id == thread.id,
- AgentContextThreadRecord.epoch == thread.epoch,
- AgentContextThreadRecord.revision == thread.revision,
- AgentContextThreadRecord.status == "active",
- )
- .values(
- epoch=next_epoch,
- revision=next_revision,
- next_sequence=next_sequence,
- last_event_hash=last_hash,
- active_checkpoint_id=None,
- active_checkpoint_sequence=0,
- active_token_count=0,
- provider=provider,
- updated_at=now,
- )
- .execution_options(synchronize_session=False)
- )
- if result.rowcount != 1:
- await session.rollback()
- raise RevisionConflictError("epoch_rotation_conflict")
- if handoff_event is not None:
- session.add(handoff_event)
- session.add(
- RuntimeMutation(
- mutation_id=operation_id,
- resource_type="agent_context",
- resource_id=str(thread.id),
- operation="start_epoch",
- result={
- "epoch": next_epoch,
- "last_event_hash": last_hash,
- "request_hash": request_hash,
- },
- )
- )
- await session.commit()
- return await self._load_ref(ref)
-
- async def fork_provider(
- self,
- ref: AgentContextRef,
- *,
- provider: str,
- operation_id: str,
- portable_handoff_ref: str,
- ) -> AgentContextRef:
- """Start a provider epoch with a portable handoff boundary."""
-
- return await self.start_epoch(
- ref,
- operation_id=operation_id,
- provider=provider,
- handoff_payload_ref=portable_handoff_ref,
- )
-
- async def bind_provider(
- self,
- ref: AgentContextRef,
- *,
- provider: str,
- binding_type: str,
- binding: Any,
- operation_id: str,
- fidelity: ContextFidelity = "provider_bound",
- ) -> AgentContextProviderBinding:
- """Persist an opaque binding in blob storage and expose only its ref."""
-
- _validate_identity("provider", provider, 100)
- _validate_identity("binding_type", binding_type, 100)
- _validate_identity("operation_id", operation_id, 512)
- binding_ref = await self.put_blob(binding)
- binding_hash = binding_ref.removeprefix("sha256:")
- request_hash = _mutation_request_hash(
- "bind_provider",
- {
- "provider": provider,
- "binding_type": binding_type,
- "binding_hash": binding_hash,
- "fidelity": fidelity,
- },
- )
- async with self._session() as session:
- thread = await self._require_thread(
- session,
- ref,
- permit_stale_epoch=True,
- )
- result = await session.execute(
- select(AgentContextProviderBindingRecord).where(
- AgentContextProviderBindingRecord.context_thread_id
- == thread.id,
- AgentContextProviderBindingRecord.operation_id
- == operation_id,
- )
- )
- record = result.scalar_one_or_none()
- if record is not None:
- _assert_idempotent_binding_reuse(
- record,
- provider=provider,
- binding_type=binding_type,
- binding_hash=binding_hash,
- fidelity=fidelity,
- )
- prior = await _runtime_mutation(
- session,
- thread_id=int(thread.id),
- operation_id=operation_id,
- operation="bind_provider",
- )
- if prior is None:
- raise AgentContextError(
- "context_binding_idempotency_invariant_broken"
- )
- _assert_idempotent_mutation_reuse(
- prior,
- request_hash=request_hash,
- )
- return _to_binding(record)
- self._assert_writable(thread, ref)
- if record is None:
- record = AgentContextProviderBindingRecord(
- context_thread_id=int(thread.id),
- epoch=thread.epoch,
- provider=provider,
- binding_type=binding_type,
- binding_ref=binding_ref,
- binding_hash=binding_hash,
- fidelity=fidelity,
- operation_id=operation_id,
- )
- session.add(record)
- await session.flush()
- session.add(
- RuntimeMutation(
- mutation_id=operation_id,
- resource_type="agent_context",
- resource_id=str(thread.id),
- operation="bind_provider",
- result={
- "binding_id": record.id,
- "binding_hash": binding_hash,
- "request_hash": request_hash,
- },
- )
- )
- await session.commit()
- return _to_binding(record)
-
- async def load_provider_bindings(
- self,
- ref: AgentContextRef,
- *,
- provider: Optional[str] = None,
- ) -> list[AgentContextProviderBinding]:
- async with self._session() as session:
- thread = await self._require_thread(session, ref)
- statement = select(AgentContextProviderBindingRecord).where(
- AgentContextProviderBindingRecord.context_thread_id
- == thread.id,
- AgentContextProviderBindingRecord.epoch == thread.epoch,
- AgentContextProviderBindingRecord.status == "active",
- )
- if provider is not None:
- statement = statement.where(
- AgentContextProviderBindingRecord.provider == provider
- )
- result = await session.execute(
- statement.order_by(AgentContextProviderBindingRecord.id)
- )
- return [_to_binding(row) for row in result.scalars().all()]
-
- async def put_blob(
- self,
- payload: Any,
- *,
- media_type: str = "application/json",
- ) -> str:
- """Store exact JSON or bytes by SHA-256 and return an opaque ref."""
-
- _validate_identity("media_type", media_type, 100)
- if isinstance(payload, (bytes, bytearray, memoryview)):
- binary = bytes(payload)
- encoded = binary
- json_payload = None
- else:
- encoded = _canonical_json(payload)
- binary = None
- json_payload = deepcopy(payload)
- digest = hashlib.sha256(encoded).hexdigest()
- async with self._session() as session:
- existing = await session.get(AgentContextBlobRecord, digest)
- if existing is None:
- session.add(
- AgentContextBlobRecord(
- payload_hash=digest,
- media_type=media_type,
- json_payload=json_payload,
- binary_payload=binary,
- byte_size=len(encoded),
- )
- )
- try:
- await session.commit()
- except IntegrityError:
- await session.rollback()
- return f"sha256:{digest}"
-
- async def get_blob(self, payload_ref: str) -> Any:
- async with self._session() as session:
- row = await _verified_blob_record(session, payload_ref)
- if row.binary_payload is not None:
- return bytes(row.binary_payload)
- return deepcopy(row.json_payload)
-
- async def archive(
- self,
- ref: AgentContextRef,
- *,
- operation_id: str,
- ) -> AgentContextRef:
- """Archive one thread, rotating its epoch to fence late writes."""
-
- _validate_identity("operation_id", operation_id, 512)
- async with self._session() as session:
- thread = await self._require_thread(
- session,
- ref,
- permit_archived=True,
- permit_stale_epoch=True,
- )
- prior = await _runtime_mutation(
- session,
- thread_id=int(thread.id),
- operation_id=operation_id,
- operation="archive",
- )
- if prior is not None:
- return _to_ref(thread)
- if thread.status == "archived":
- return _to_ref(thread)
- self._assert_writable(thread, ref)
- now = datetime.now(timezone.utc)
- result = await session.execute(
- update(AgentContextThreadRecord)
- .where(
- AgentContextThreadRecord.id == thread.id,
- AgentContextThreadRecord.epoch == thread.epoch,
- AgentContextThreadRecord.revision == thread.revision,
- )
- .values(
- status="archived",
- epoch=thread.epoch + 1,
- revision=thread.revision + 1,
- active_checkpoint_id=None,
- active_checkpoint_sequence=0,
- active_token_count=0,
- provider=None,
- archived_at=now,
- updated_at=now,
- )
- .execution_options(synchronize_session=False)
- )
- if result.rowcount != 1:
- await session.rollback()
- raise RevisionConflictError("context_archive_conflict")
- await session.execute(
- update(AgentContextProviderBindingRecord)
- .where(
- AgentContextProviderBindingRecord.context_thread_id
- == thread.id,
- AgentContextProviderBindingRecord.status == "active",
- )
- .values(status="archived")
- )
- await session.execute(
- update(AgentContextCheckpointRecord)
- .where(
- AgentContextCheckpointRecord.context_thread_id
- == thread.id,
- AgentContextCheckpointRecord.status == "active",
- )
- .values(status="archived")
- )
- await session.execute(
- update(AgentContextCompactionAttemptRecord)
- .where(
- AgentContextCompactionAttemptRecord.context_thread_id
- == thread.id,
- AgentContextCompactionAttemptRecord.status == "prepared",
- )
- .values(
- status="stale",
- error_code="context_archived",
- completed_at=now,
- )
- )
- session.add(
- RuntimeMutation(
- mutation_id=operation_id,
- resource_type="agent_context",
- resource_id=str(thread.id),
- operation="archive",
- result={"archived_epoch": thread.epoch},
- )
- )
- await session.commit()
- return await self._load_ref(ref)
-
- async def archive_context(
- self,
- *,
- workflow_id: str,
- context_node_id: str,
- generation: Optional[int] = None,
- operation_id: str,
- ) -> list[AgentContextRef]:
- """Archive Context threads, across every generation by default."""
-
- _validate_identity("operation_id", operation_id, 500)
- async with self._session() as session:
- statement = select(AgentContextThreadRecord).where(
- AgentContextThreadRecord.workflow_id == workflow_id,
- AgentContextThreadRecord.context_node_id == context_node_id,
- )
- if generation is not None:
- statement = statement.where(
- AgentContextThreadRecord.generation == generation
- )
- result = await session.execute(
- statement.order_by(
- AgentContextThreadRecord.generation,
- AgentContextThreadRecord.thread_id,
- AgentContextThreadRecord.id,
- )
- )
- refs = [_to_ref(row) for row in result.scalars().all()]
- archived: list[AgentContextRef] = []
- for index, ref in enumerate(refs):
- archived.append(
- await self.archive(
- ref,
- operation_id=f"{operation_id}:{index}",
- )
- )
- return archived
-
- async def purge(
- self,
- *,
- workflow_id: str,
- context_node_id: str,
- generation: Optional[int] = None,
- ) -> int:
- """Permanently delete a Context journal.
-
- Hash-addressed blobs are intentionally retained here. A global
- mark-and-sweep performed immediately after this transaction can race
- with another transaction that has stored a blob but has not yet
- committed its reference. Blob collection belongs in a separately
- coordinated maintenance job with an age/grace-period fence.
- """
-
- async with self._session() as session:
- statement = select(AgentContextThreadRecord).where(
- AgentContextThreadRecord.workflow_id == workflow_id,
- AgentContextThreadRecord.context_node_id == context_node_id,
- )
- if generation is not None:
- statement = statement.where(
- AgentContextThreadRecord.generation == generation
- )
- result = await session.execute(statement)
- thread_ids = [
- int(row.id)
- for row in result.scalars().all()
- if row.id is not None
- ]
- if not thread_ids:
- return 0
- for model in (
- AgentContextEventRecord,
- AgentContextCheckpointRecord,
- AgentContextProviderBindingRecord,
- AgentContextCompactionAttemptRecord,
- ):
- await session.execute(
- delete(model).where(
- model.context_thread_id.in_(thread_ids)
- )
- )
- await session.execute(
- delete(RuntimeMutation).where(
- RuntimeMutation.resource_type == "agent_context",
- RuntimeMutation.resource_id.in_(
- [str(value) for value in thread_ids]
- ),
- )
- )
- await session.execute(
- delete(AgentContextThreadRecord).where(
- AgentContextThreadRecord.id.in_(thread_ids)
- )
- )
- await session.commit()
- return len(thread_ids)
-
- async def _require_thread(
- self,
- session: AsyncSession,
- ref: AgentContextRef,
- *,
- permit_archived: bool = False,
- permit_stale_epoch: bool = False,
- ) -> AgentContextThreadRecord:
- thread = await _select_thread(
- session,
- workflow_id=ref.workflow_id,
- context_node_id=ref.context_node_id,
- generation=ref.generation,
- thread_id=ref.thread_id,
- )
- if thread is None:
- raise ContextNotFoundError("agent_context_thread_not_found")
- if thread.epoch != ref.epoch and not permit_stale_epoch:
- raise StaleEpochError(
- f"context_epoch_fenced:{ref.epoch}:{thread.epoch}"
- )
- if thread.status == "archived" and not permit_archived:
- raise ContextArchivedError("agent_context_thread_archived")
- return thread
-
- def _assert_writable(
- self,
- thread: AgentContextThreadRecord,
- ref: AgentContextRef,
- ) -> None:
- if thread.epoch != ref.epoch:
- raise StaleEpochError("context_epoch_fenced")
- if thread.status != "active":
- raise ContextArchivedError("agent_context_thread_archived")
-
- async def _load_ref(self, ref: AgentContextRef) -> AgentContextRef:
- async with self._session() as session:
- thread = await _select_thread(
- session,
- workflow_id=ref.workflow_id,
- context_node_id=ref.context_node_id,
- generation=ref.generation,
- thread_id=ref.thread_id,
- )
- if thread is None:
- raise ContextNotFoundError(
- "agent_context_thread_not_found"
- )
- return _to_ref(thread)
-
-
-def _resolve_thread_identity(
- *,
- session_id: Optional[str],
- delegated_task_id: Optional[str],
- execution_id: Optional[str],
-) -> tuple[ContextThreadKind, str]:
- if session_id is not None and session_id.strip():
- return "session", session_id.strip()
- if delegated_task_id is not None and delegated_task_id.strip():
- return "task", delegated_task_id.strip()
- if execution_id is not None and execution_id.strip():
- return "execution", execution_id.strip()
- raise ValueError(
- "execution_id is required when no explicit session or delegated "
- "task is present"
- )
-
-
-def _thread_id(kind: ContextThreadKind, source_id: str) -> str:
- _validate_identity(f"{kind}_id", source_id, 4096)
- raw = f"{kind}:{source_id}"
- if len(raw) <= 512:
- return raw
- return f"{kind}:sha256:{hashlib.sha256(source_id.encode()).hexdigest()}"
-
-
-def _validate_identity(name: str, value: str, max_length: int) -> None:
- if not isinstance(value, str) or not value.strip():
- raise ValueError(f"{name} must be a non-empty string")
- if len(value) > max_length:
- raise ValueError(f"{name} exceeds {max_length} characters")
-
-
-async def _select_thread(
- session: AsyncSession,
- *,
- workflow_id: str,
- context_node_id: str,
- generation: int,
- thread_id: str,
-) -> Optional[AgentContextThreadRecord]:
- result = await session.execute(
- select(AgentContextThreadRecord).where(
- AgentContextThreadRecord.workflow_id == workflow_id,
- AgentContextThreadRecord.context_node_id == context_node_id,
- AgentContextThreadRecord.generation == generation,
- AgentContextThreadRecord.thread_id == thread_id,
- )
- )
- return result.scalar_one_or_none()
-
-
-async def _event_by_operation(
- session: AsyncSession,
- *,
- thread_id: int,
- operation_id: str,
-) -> Optional[AgentContextEventRecord]:
- result = await session.execute(
- select(AgentContextEventRecord).where(
- AgentContextEventRecord.context_thread_id == thread_id,
- AgentContextEventRecord.operation_id == operation_id,
- )
- )
- return result.scalar_one_or_none()
-
-
-def _assert_idempotent_event_reuse(
- existing: AgentContextEventRecord,
- *,
- event_type: str,
- message_wire: Optional[dict[str, Any]],
- payload_ref: Optional[str],
- provider: Optional[str],
-) -> None:
- """Accept an operation retry only when it is the exact same transition."""
-
- stored_hash = _event_record_hash(existing)
- retry_hash = _event_hash(
- sequence=existing.sequence,
- epoch=existing.epoch,
- event_type=event_type,
- message_wire=message_wire,
- payload_ref=payload_ref,
- operation_id=existing.operation_id,
- provider=provider,
- previous_hash=existing.previous_hash,
- )
- if (
- existing.event_type != event_type
- or existing.message_wire != message_wire
- or existing.payload_ref != payload_ref
- or existing.provider != provider
- or stored_hash != existing.payload_hash
- or retry_hash != existing.payload_hash
- ):
- raise AgentContextError("context_operation_id_reuse_mismatch")
-
-
-async def _runtime_mutation(
- session: AsyncSession,
- *,
- thread_id: int,
- operation_id: str,
- operation: str,
-) -> Optional[RuntimeMutation]:
- result = await session.execute(
- select(RuntimeMutation).where(
- RuntimeMutation.resource_type == "agent_context",
- RuntimeMutation.resource_id == str(thread_id),
- RuntimeMutation.mutation_id == operation_id,
- RuntimeMutation.operation == operation,
- )
- )
- return result.scalar_one_or_none()
-
-
-def _mutation_request_hash(
- operation: str,
- inputs: dict[str, Any],
-) -> str:
- """Hash the exact server-controlled inputs for one idempotent mutation."""
-
- return hashlib.sha256(
- _canonical_json(
- {
- "operation": operation,
- "inputs": inputs,
- }
- )
- ).hexdigest()
-
-
-def _assert_idempotent_mutation_reuse(
- mutation: RuntimeMutation,
- *,
- request_hash: str,
-) -> None:
- result = mutation.result if isinstance(mutation.result, dict) else {}
- if result.get("request_hash") != request_hash:
- raise AgentContextError("context_operation_id_reuse_mismatch")
-
-
-def _assert_idempotent_binding_reuse(
- record: AgentContextProviderBindingRecord,
- *,
- provider: str,
- binding_type: str,
- binding_hash: str,
- fidelity: ContextFidelity,
-) -> None:
- if (
- record.provider != provider
- or record.binding_type != binding_type
- or record.binding_hash != binding_hash
- or record.binding_ref != f"sha256:{binding_hash}"
- or record.fidelity != fidelity
- ):
- raise AgentContextError("context_operation_id_reuse_mismatch")
-
-
-def _validate_message_wire(
- value: Optional[dict[str, Any]],
-) -> Optional[dict[str, Any]]:
- if value is None:
- return None
- if not isinstance(value, dict):
- raise TypeError("message_wire must be a JSON object")
- # Round-tripping through the codec enforces JSON-safe provider state,
- # preserves ordered blocks/tool calls, and rejects shapes with no role.
- return dict(message_to_wire(message_from_wire(value)))
-
-
-def _event_hash(
- *,
- sequence: int,
- epoch: int,
- event_type: str,
- message_wire: Optional[dict[str, Any]],
- payload_ref: Optional[str],
- operation_id: str,
- provider: Optional[str],
- previous_hash: str,
-) -> str:
- body = {
- "sequence": sequence,
- "epoch": epoch,
- "event_type": event_type,
- "message_wire": message_wire,
- "payload_ref": payload_ref,
- "operation_id": operation_id,
- "provider": provider,
- "previous_hash": previous_hash,
- }
- return hashlib.sha256(_canonical_json(body)).hexdigest()
-
-
-def _event_record_hash(row: AgentContextEventRecord) -> str:
- return _event_hash(
- sequence=row.sequence,
- epoch=row.epoch,
- event_type=row.event_type,
- message_wire=row.message_wire,
- payload_ref=row.payload_ref,
- operation_id=row.operation_id,
- provider=row.provider,
- previous_hash=row.previous_hash,
- )
-
-
-async def _verify_active_event_chain(
- session: AsyncSession,
- thread: AgentContextThreadRecord,
- *,
- checkpoint_source: Optional[AgentContextEventRecord],
- tail: list[AgentContextEventRecord],
-) -> None:
- """Validate the bounded replay chain and the thread's journal head."""
-
- anchor = checkpoint_source or (tail[0] if tail else None)
- predecessor: Optional[AgentContextEventRecord] = None
- if anchor is not None and anchor.sequence > 1:
- predecessor_result = await session.execute(
- select(AgentContextEventRecord).where(
- AgentContextEventRecord.context_thread_id == thread.id,
- AgentContextEventRecord.sequence == anchor.sequence - 1,
- )
- )
- predecessor = predecessor_result.scalar_one_or_none()
- if predecessor is None:
- raise AgentContextError("context_event_sequence_integrity_broken")
-
- if checkpoint_source is not None:
- _verify_event_record(
- checkpoint_source,
- expected_sequence=checkpoint_source.sequence,
- expected_previous_hash=(
- predecessor.payload_hash if predecessor is not None else ZERO_HASH
- ),
- )
- expected_sequence = checkpoint_source.sequence + 1
- previous_hash = checkpoint_source.payload_hash
- elif tail:
- expected_sequence = tail[0].sequence
- previous_hash = (
- predecessor.payload_hash if predecessor is not None else ZERO_HASH
- )
- if predecessor is None and expected_sequence != 1:
- raise AgentContextError("context_event_sequence_integrity_broken")
- else:
- expected_sequence = thread.next_sequence
- previous_hash = thread.last_event_hash
-
- for row in tail:
- _verify_event_record(
- row,
- expected_sequence=expected_sequence,
- expected_previous_hash=previous_hash,
- )
- expected_sequence += 1
- previous_hash = row.payload_hash
-
- latest_result = await session.execute(
- select(AgentContextEventRecord)
- .where(AgentContextEventRecord.context_thread_id == thread.id)
- .order_by(AgentContextEventRecord.sequence.desc())
- .limit(1)
- )
- latest = latest_result.scalar_one_or_none()
- if latest is None:
- if thread.next_sequence != 1 or thread.last_event_hash != ZERO_HASH:
- raise AgentContextError("context_journal_head_integrity_broken")
- return
- if (
- thread.next_sequence != latest.sequence + 1
- or thread.last_event_hash != latest.payload_hash
- ):
- raise AgentContextError("context_journal_head_integrity_broken")
-
-
-def _verify_event_record(
- row: AgentContextEventRecord,
- *,
- expected_sequence: int,
- expected_previous_hash: str,
-) -> None:
- if row.sequence != expected_sequence:
- raise AgentContextError("context_event_sequence_integrity_broken")
- if row.previous_hash != expected_previous_hash:
- raise AgentContextError("context_event_chain_integrity_broken")
- if _event_record_hash(row) != row.payload_hash:
- raise AgentContextError("context_event_hash_integrity_broken")
-
-
-def _canonical_json(value: Any) -> bytes:
- try:
- return json.dumps(
- value,
- ensure_ascii=False,
- allow_nan=False,
- sort_keys=True,
- separators=(",", ":"),
- ).encode("utf-8")
- except (TypeError, ValueError) as exc:
- raise TypeError("Context payload must be exact JSON data") from exc
-
-
-def _parse_blob_ref(value: str) -> str:
- if not isinstance(value, str) or not value.startswith("sha256:"):
- raise ValueError("invalid_context_blob_ref")
- digest = value.removeprefix("sha256:")
- if len(digest) != 64 or any(
- character not in "0123456789abcdef" for character in digest
- ):
- raise ValueError("invalid_context_blob_ref")
- return digest
-
-
-async def _verified_blob_record(
- session: AsyncSession,
- payload_ref: str,
-) -> AgentContextBlobRecord:
- digest = _parse_blob_ref(payload_ref)
- row = await session.get(AgentContextBlobRecord, digest)
- if row is None:
- raise ContextNotFoundError("context_blob_not_found")
- if row.binary_payload is not None:
- if row.json_payload is not None:
- raise AgentContextError("context_blob_integrity_broken")
- encoded = bytes(row.binary_payload)
- else:
- encoded = _canonical_json(row.json_payload)
- actual_digest = hashlib.sha256(encoded).hexdigest()
- if (
- row.payload_hash != digest
- or actual_digest != digest
- or row.byte_size != len(encoded)
- ):
- raise AgentContextError("context_blob_integrity_broken")
- return row
-
-
-def _to_ref(row: AgentContextThreadRecord) -> AgentContextRef:
- return AgentContextRef(
- workflow_id=row.workflow_id,
- context_node_id=row.context_node_id,
- generation=row.generation,
- thread_id=row.thread_id,
- epoch=row.epoch,
- revision=row.revision,
- )
-
-
-def _to_thread_summary(
- row: AgentContextThreadRecord,
-) -> AgentContextThreadSummary:
- return AgentContextThreadSummary(
- ref=_to_ref(row),
- thread_kind=row.thread_kind, # type: ignore[arg-type]
- provider=row.provider,
- status=row.status,
- active_checkpoint_sequence=max(
- 0,
- row.active_checkpoint_sequence,
- ),
- active_token_count=max(0, row.active_token_count),
- updated_at=row.updated_at,
- )
-
-
-def _to_event(row: AgentContextEventRecord) -> AgentContextEvent:
- return AgentContextEvent(
- sequence=row.sequence,
- event_type=row.event_type,
- message_wire=deepcopy(row.message_wire),
- payload_ref=row.payload_ref,
- operation_id=row.operation_id,
- provider=row.provider,
- previous_hash=row.previous_hash,
- payload_hash=row.payload_hash,
- )
-
-
-def _to_checkpoint(
- row: AgentContextCheckpointRecord,
-) -> AgentContextCheckpoint:
- return AgentContextCheckpoint(
- provider=row.provider,
- strategy=row.strategy,
- covers_through_sequence=row.covers_through_sequence,
- replay_payload_ref=row.replay_payload_ref,
- active_token_count=row.active_token_count,
- source_revision=row.source_revision,
- source_hash=row.source_hash,
- )
-
-
-def _to_binding(
- row: AgentContextProviderBindingRecord,
-) -> AgentContextProviderBinding:
- return AgentContextProviderBinding(
- provider=row.provider,
- binding_type=row.binding_type,
- binding_ref=row.binding_ref,
- epoch=row.epoch,
- fidelity=row.fidelity, # type: ignore[arg-type]
- )
-
-
-async def _to_plan(
- session: AsyncSession,
- thread: AgentContextThreadRecord,
- attempt: AgentContextCompactionAttemptRecord,
-) -> AgentContextCompactionPlan:
- checkpoint: Optional[AgentContextCheckpoint] = None
- if attempt.base_checkpoint_id is not None:
- checkpoint_row = await session.get(
- AgentContextCheckpointRecord,
- attempt.base_checkpoint_id,
- )
- if checkpoint_row is None:
- raise AgentContextError("base_checkpoint_missing")
- checkpoint = _to_checkpoint(checkpoint_row)
- result = await session.execute(
- select(AgentContextEventRecord)
- .where(
- AgentContextEventRecord.context_thread_id == thread.id,
- AgentContextEventRecord.epoch == attempt.epoch,
- AgentContextEventRecord.sequence
- > attempt.base_checkpoint_sequence,
- AgentContextEventRecord.sequence
- <= attempt.covers_through_sequence,
- )
- .order_by(AgentContextEventRecord.sequence)
- )
- prefix = [_to_event(row) for row in result.scalars().all()]
- if not prefix or prefix[-1].payload_hash != attempt.source_hash:
- raise CompactionConflictError("compaction_prefix_changed")
- return AgentContextCompactionPlan(
- attempt_id=int(attempt.id),
- ref=_to_ref(thread),
- provider=attempt.provider,
- strategy=attempt.strategy,
- base_checkpoint=checkpoint,
- committed_prefix=prefix,
- covers_through_sequence=attempt.covers_through_sequence,
- source_revision=attempt.source_revision,
- source_hash=attempt.source_hash,
- )
-
-
-__all__ = [
- "AgentContextError",
- "AgentContextStore",
- "CompactionConflictError",
- "ContextArchivedError",
- "ContextNotFoundError",
- "RevisionConflictError",
- "StaleEpochError",
-]
diff --git a/server/services/agent_runtime.py b/server/services/agent_runtime.py
index 3eff1d44..7d69f9ba 100644
--- a/server/services/agent_runtime.py
+++ b/server/services/agent_runtime.py
@@ -37,33 +37,12 @@ from services.llm.protocol import (
ToolCall,
ToolDef,
Usage,
- message_to_wire,
- messages_to_wire,
)
from services.tool_identity import DuplicateToolNameError
logger = get_logger(__name__)
-class AgentContextTransitionSink(Protocol):
- """Bound, epoch-fenced sink for one Context thread.
-
- Store implementations decide whether payloads are inlined or replaced by
- hash-addressed blob references. The runtime only emits committed
- transitions in provider-observable order.
- """
-
- async def append_transition(
- self,
- *,
- event_type: str,
- operation_id: str,
- provider: str,
- message_wire: Optional[Dict[str, Any]] = None,
- payload: Optional[Dict[str, Any]] = None,
- ) -> Any: ...
-
-
@dataclass
class AgentToolSpec:
"""LLM-visible definition plus local execution/validation metadata."""
@@ -231,8 +210,9 @@ async def run_native_agent_loop(
Awaitable[Optional[List[Message]]],
]
] = None,
- context_transition_sink: Optional[AgentContextTransitionSink] = None,
- context_operation_id: Optional[str] = None,
+ conversation_saver: Optional[
+ Callable[[List[Message]], Awaitable[None]]
+ ] = None,
) -> Dict[str, Any]:
"""Run the shared buffered native tool-agent loop.
@@ -247,27 +227,17 @@ async def run_native_agent_loop(
thinking_parts: List[str] = []
last_response: Optional[LLMResponse] = None
iteration = 0
- if context_transition_sink is not None and not context_operation_id:
- raise ValueError(
- "context_operation_id is required when a Context transition sink is used"
- )
-
- async def persist_transition(
- event_type: str,
- *,
- operation_id: str,
- message: Optional[Message] = None,
- payload: Optional[Dict[str, Any]] = None,
- ) -> None:
- if context_transition_sink is None:
+ async def save_now() -> None:
+ """Persist the full current transcript; never fails the loop."""
+ if conversation_saver is None:
return
- await context_transition_sink.append_transition(
- event_type=event_type,
- operation_id=f"{context_operation_id}:{operation_id}",
- provider=provider,
- message_wire=message_to_wire(message) if message else None,
- payload=payload,
- )
+ try:
+ await conversation_saver(list(messages))
+ except Exception: # noqa: BLE001 — persistence must not fail a turn
+ logger.warning(
+ "[Agent loop] conversation save failed; continuing",
+ exc_info=True,
+ )
for iteration in range(1, max_iterations + 1):
if progress_callback is not None:
@@ -277,30 +247,6 @@ async def run_native_agent_loop(
logger.debug("[Agent loop] progress callback failed: %s", exc)
definitions = [_tool_definition(tool) for tool in current_tools]
- await persist_transition(
- "request.snapshot",
- operation_id=f"iteration:{iteration}:request",
- payload={
- "iteration": iteration,
- "provider": provider,
- "model": model,
- "settings": {
- "temperature": temperature,
- "max_tokens": max_tokens,
- "thinking": asdict(thinking) if thinking is not None else None,
- },
- "messages": messages_to_wire(messages),
- "tools": [
- {
- "name": definition.name,
- "description": definition.description,
- "parameters": definition.parameters,
- }
- for definition in definitions
- ],
- "dynamic_tool_count": len(current_tools),
- },
- )
try:
response = await run_native_llm_step(
chat_unifier,
@@ -317,15 +263,6 @@ async def run_native_agent_loop(
except BaseException as exc:
if isinstance(exc, asyncio.CancelledError):
raise
- await persist_transition(
- "provider.outcome_ambiguous",
- operation_id=f"iteration:{iteration}:provider-error",
- payload={
- "iteration": iteration,
- "error_type": type(exc).__name__,
- "ambiguous": True,
- },
- )
raise
last_response = response
usage = add_usage(usage, response.billing_usage or response.usage)
@@ -338,21 +275,9 @@ async def run_native_agent_loop(
tool_calls=list(response.tool_calls),
)
messages.append(assistant)
- # This commit is intentionally before any requested tool executes.
- await persist_transition(
- "message.assistant",
- operation_id=f"iteration:{iteration}:assistant",
- message=assistant,
- payload={
- "iteration": iteration,
- "finish_reason": response.finish_reason,
- "model": response.model or model,
- "usage": asdict(response.usage),
- "billing_usage": asdict(
- response.billing_usage or response.usage
- ),
- },
- )
+ # This save is intentionally before any requested tool executes,
+ # so a crash mid-tools never loses the assistant's turn.
+ await save_now()
if response.thinking:
thinking_parts.append(
@@ -372,16 +297,8 @@ async def run_native_agent_loop(
and not calls
):
# Anthropic's durability pause returns only a compaction block.
- # It has already been journaled above; continue from that exact
+ # It has already been saved above; continue from that exact
# block instead of exposing it as the user's final response.
- await persist_transition(
- "provider.compaction_paused",
- operation_id=f"iteration:{iteration}:compaction-pause",
- payload={
- "iteration": iteration,
- "finish_reason": response.finish_reason,
- },
- )
if compaction_pause_callback is not None:
replacement = await compaction_pause_callback(
iteration,
@@ -392,17 +309,6 @@ async def run_native_agent_loop(
messages = list(replacement)
continue
if not calls:
- await persist_transition(
- "response.final",
- operation_id=f"iteration:{iteration}:final",
- payload={
- "iteration": iteration,
- "usage": asdict(response.usage),
- "lifetime_usage": asdict(usage),
- "active_input_tokens": response.usage.input_tokens,
- "finish_reason": response.finish_reason,
- },
- )
return {
"messages": messages,
"iteration": iteration,
@@ -454,10 +360,8 @@ async def run_native_agent_loop(
spec = specs[call.name]
spec.execution["tool_call_id"] = call.id
spec.execution["operation_id"] = (
- f"{context_operation_id}:iteration:{iteration}:"
+ f"{provider}:iteration:{iteration}:"
f"tool:{call_index}:{call.id or call.name}"
- if context_operation_id
- else f"{provider}:tool:{call.id or call.name}"
)
result = await tool_executor(call.name, args or {})
except Exception as exc:
@@ -499,23 +403,9 @@ async def run_native_agent_loop(
# in durable state (hydration happens per provider call).
tool_message.blocks.extend(image_blocks_from_tool_result(result))
messages.append(tool_message)
- await persist_transition(
- "message.tool_result",
- operation_id=(
- f"iteration:{iteration}:tool:{call_index}:{call.id or call.name}"
- ),
- message=tool_message,
- payload={
- "iteration": iteration,
- "tool_call_id": call.id,
- "tool_name": call.name,
- "outcome": (
- "error"
- if isinstance(result, dict) and "error" in result
- else "success"
- ),
- },
- )
+
+ # One save per turn covers every tool result appended above.
+ await save_now()
if iteration_new_tools:
current_tools.extend(iteration_new_tools)
@@ -533,16 +423,7 @@ async def run_native_agent_loop(
),
)
messages.append(terminal)
- await persist_transition(
- "response.truncated",
- operation_id=f"iteration:{iteration}:truncated",
- message=terminal,
- payload={
- "iteration": iteration,
- "lifetime_usage": asdict(usage),
- "reason": "recursion_limit",
- },
- )
+ await save_now()
return {
"messages": messages,
"iteration": iteration,
@@ -554,7 +435,6 @@ async def run_native_agent_loop(
__all__ = [
- "AgentContextTransitionSink",
"AgentToolSpec",
"add_usage",
"run_native_llm_step",
diff --git a/server/services/ai.py b/server/services/ai.py
index cc69e856..8c007a69 100644
--- a/server/services/ai.py
+++ b/server/services/ai.py
@@ -6,9 +6,8 @@ Every in-process and durable agent execution goes through
from __future__ import annotations
-import hashlib
import time
-from dataclasses import asdict, dataclass
+from dataclasses import dataclass
from datetime import datetime
from typing import Dict, Any, List, Optional, Type, TYPE_CHECKING
@@ -295,16 +294,32 @@ def _build_skill_system_prompt(skill_data: List[Dict[str, Any]], log_prefix: str
@dataclass
class _AgentContextRuntime:
- """Backend-only execution binding for one visible Context node."""
+ """Plain conversation binding for one Context-connected agent.
- store: Any
- writer: Any
- policy: Any
- request_options: Optional[Dict[str, Any]]
- operation_id: str
+ The key ``(workflow_id, generation, agent_node_id)`` addresses one row in
+ the ``agent_conversations`` store; ``history`` is that row's transcript
+ replayed as native messages, and ``save`` writes the loop's live message
+ list back per turn (called via the agent loop's ``conversation_saver``,
+ which already treats failures as best-effort).
+ """
+
+ workflow_id: str
+ generation: int
+ agent_node_id: str
+ database: Any
history: List[NativeMessage]
- provider: str
- model: str
+
+ async def save(self, messages: List[NativeMessage]) -> None:
+ from services.agent_context import save_conversation
+ from services.llm.protocol import message_to_wire
+
+ await save_conversation(
+ self.database,
+ workflow_id=self.workflow_id,
+ generation=self.generation,
+ agent_node_id=self.agent_node_id,
+ messages=[dict(message_to_wire(message)) for message in messages],
+ )
class AIService:
@@ -345,28 +360,21 @@ class AIService:
context_data: Optional[Dict[str, Any]],
execution_context: Optional[Dict[str, Any]],
workflow_id: Optional[str],
- provider: str,
- model: str,
database: Any,
) -> Optional["_AgentContextRuntime"]:
- """Resolve one backend-owned Context thread and reconstruct replay."""
+ """Load the agent's stored conversation for this generation.
+
+ Returns ``None`` when no Context node is connected or the run carries
+ no admitted generation (manual canvas runs persist nothing by
+ design). A failing load raises instead of silently starting an
+ amnesiac run that burns tokens on an empty prompt.
+ """
if not context_data or context_data.get("kind") != "context":
return None
- from services.agent_context import (
- AgentContextStore,
- AgentContextTransitionWriter,
- ContextCompactionPolicy,
- import_generation_zero_handoff,
- provider_context_request_options,
- reconstruct_transcript,
- )
- from services.llm.protocol import (
- Message,
- message_from_wire,
- message_to_wire,
- )
+ from services.agent_context import load_conversation
+ from services.llm.protocol import message_from_wire
raw_context = execution_context or {}
admitted_workflow_id = str(
@@ -378,19 +386,10 @@ class AIService:
and descriptor_workflow_id
and admitted_workflow_id != descriptor_workflow_id
):
- raise ValueError("Context V2 workflow scope mismatch")
- resolved_workflow_id = (
- admitted_workflow_id or descriptor_workflow_id
- )
- context_node_id = str(
- context_data.get("context_node_id")
- or context_data.get("node_id")
- or ""
- )
- if not resolved_workflow_id or not context_node_id:
- raise ValueError(
- "Context V2 requires workflow_id and context_node_id"
- )
+ raise ValueError("Context workflow scope mismatch")
+ resolved_workflow_id = admitted_workflow_id or descriptor_workflow_id
+ if not resolved_workflow_id:
+ return None
admitted_generation = int(
raw_context.get("generation")
or raw_context.get("workflow_generation")
@@ -402,371 +401,36 @@ class AIService:
and descriptor_generation
and admitted_generation != descriptor_generation
):
- raise ValueError("Context V2 generation scope mismatch")
+ raise ValueError("Context generation scope mismatch")
generation = admitted_generation or descriptor_generation
if generation <= 0:
- raise ValueError(
- "Context V2 requires an admitted workflow generation"
- )
- execution_id = str(
- raw_context.get("execution_id")
- or context_data.get("execution_id")
- or ""
- )
- delegated_task_id = str(
- raw_context.get("delegated_task_id")
- or raw_context.get("parent_task_id")
- or raw_context.get("team_task_id")
- or context_data.get("delegated_task_id")
- or ""
- )
- session_id = str(context_data.get("session_id") or "")
- if not (execution_id or delegated_task_id or session_id):
- raise ValueError(
- "Context V2 requires an execution, delegated task, or "
- "explicit session identity"
- )
-
- store = AgentContextStore(database)
- ref = await store.resolve_thread(
- workflow_id=resolved_workflow_id,
- context_node_id=context_node_id,
- generation=generation,
- session_id=session_id or None,
- delegated_task_id=delegated_task_id or None,
- execution_id=execution_id or None,
- )
- ref = await import_generation_zero_handoff(store, ref)
-
- # A provider transition is an epoch boundary. Opaque state remains
- # archived while the observable MessageWire replay is handed off.
- summary = await store.load_thread_summary(ref)
- if (
- summary.provider
- and summary.provider != provider
- ):
- _, handoff_wires = await reconstruct_transcript(store, ref)
- portable_handoff_wires: list[dict[str, Any]] = []
- for handoff_wire in handoff_wires:
- source_message = message_from_wire(handoff_wire)
- if (
- source_message.provider_state
- and source_message.role == "assistant"
- and not source_message.content
- and not source_message.tool_calls
- ):
- # A native compaction marker is replayable only by its
- # issuing provider. Forking it as "portable" would silently
- # erase the compacted prefix for the destination provider.
- raise ValueError(
- "Provider change requires a portable Context "
- "checkpoint; the active checkpoint is provider-native"
- )
- portable_message = Message(
- role=source_message.role,
- content=source_message.content,
- tool_calls=list(source_message.tool_calls),
- tool_call_id=source_message.tool_call_id,
- name=source_message.name,
- )
- portable_handoff_wires.append(
- dict(message_to_wire(portable_message))
- )
- handoff_ref = await store.put_blob(
- {
- "format": "agent-context-portable-handoff-v1",
- "source_provider": summary.provider,
- "target_provider": provider,
- "messages": portable_handoff_wires,
- }
- )
- ref = await store.fork_provider(
- ref,
- provider=provider,
- operation_id=(
- f"context-provider-fork:{generation}:"
- f"{ref.thread_id}:epoch-{ref.epoch}:"
- f"{summary.provider}-to-{provider}"
- ),
- portable_handoff_ref=handoff_ref,
- )
- try:
- from nodes.context._events import (
- dispatch_context_epoch_started,
- )
-
- await dispatch_context_epoch_started(
- workflow_id=resolved_workflow_id,
- context_node_id=context_node_id,
- thread_id=ref.thread_id,
- epoch=ref.epoch,
- revision=ref.revision,
- provider=provider,
- reason="provider_change",
- )
- except Exception as exc:
- logger.debug(
- "[Context] provider epoch event failed: %s",
- exc,
- )
-
- ref, history_wires = await reconstruct_transcript(store, ref)
- history = [message_from_wire(wire) for wire in history_wires]
- policy = ContextCompactionPolicy.from_mapping(
- context_data.get("policy")
- if isinstance(context_data.get("policy"), dict)
- else None
- )
- request_options = provider_context_request_options(
- provider=provider,
- model=model,
- policy=policy,
- )
- identity = (
- execution_id
- or delegated_task_id
- or session_id
- or ref.thread_id
- )
- material = (
- f"{resolved_workflow_id}:{context_node_id}:{generation}:"
- f"{ref.thread_id}:{ref.epoch}:{ref.revision}:{identity}:{node_id}"
- )
- operation_id = (
- "agent-context:"
- + hashlib.sha256(material.encode("utf-8")).hexdigest()
- )
- return _AgentContextRuntime(
- store=store,
- writer=AgentContextTransitionWriter(store, ref),
- policy=policy,
- request_options=request_options,
- operation_id=operation_id,
- history=history,
- provider=provider,
- model=model,
- )
-
- async def _portable_context_candidate(
- self,
- wires: list[dict[str, Any]],
- _policy: Any,
- *,
- provider: str,
- api_key: str,
- model: str,
- ) -> Any:
- """Create a structured portable checkpoint from observable replay."""
-
- from services.agent_context import ContextCompactionCandidate
- from services.agent_runtime import run_native_llm_step
- from services.llm.protocol import Message, message_from_wire, message_to_wire
- from services.model_registry import get_model_registry
-
- transcript: list[str] = []
- for wire in wires:
- message = message_from_wire(wire)
- line = f"{message.role.upper()}: {message.content}"
- if message.tool_calls:
- line += "\nTOOL_CALLS: " + json.dumps(
- [
- {
- "id": call.id,
- "name": call.name,
- "args": call.args,
- "raw_arguments": call.raw_arguments,
- "parse_error": call.parse_error,
- }
- for call in message.tool_calls
- ],
- ensure_ascii=False,
- default=str,
- )
- if message.tool_call_id:
- line += (
- f"\nTOOL_RESULT_FOR: {message.tool_call_id}"
- f" ({message.name or 'tool'})"
- )
- transcript.append(line)
- prompt = (
- "Create a compact, provider-portable continuation checkpoint for "
- "the agent transcript below. Preserve resolved instructions, "
- "durable facts, exact identifiers, completed and pending tool "
- "work, decisions, errors, constraints, open questions, and the "
- "next action. Never claim a tool ran unless its result appears. "
- "Do not include commentary about summarizing.\n\n"
- + "\n\n".join(transcript)
- )
- max_summary_tokens = min(
- 4096,
- get_model_registry().get_max_output_tokens(model, provider),
- )
- response = await run_native_llm_step(
- self.chat_unifier,
- provider=provider,
- api_key=api_key,
- messages=[Message(role="user", content=prompt)],
- model=model,
- temperature=0.2,
- max_tokens=max_summary_tokens,
- sdk_max_retries=0,
- explicit_max_retries=0,
- )
- summary_message = Message(
- role="user",
- content=(
- "<agent_context_checkpoint>\n"
- f"{response.content}\n"
- "</agent_context_checkpoint>"
- ),
- )
- summary_wire = dict(message_to_wire(summary_message))
- return ContextCompactionCandidate(
- strategy="portable_structured",
- replay_payload={
- "format": "agent-context-portable-v1",
- "messages": [summary_wire],
- },
- active_token_count=max(
- 1,
- (len(summary_message.content.encode("utf-8")) + 2) // 3,
- ),
- lifetime_usage=asdict(
- response.billing_usage or response.usage
- ),
- )
-
- async def _finalize_context(
- self,
- runtime: Optional["_AgentContextRuntime"],
- *,
- final_state: Dict[str, Any],
- api_key: str,
- max_tokens: int,
- operation_suffix: str = "finalize",
- ) -> Optional[Any]:
- if runtime is None:
return None
- from services.agent_context import AgentContextCompactionService
- from services.llm.protocol import message_to_wire
- response = final_state.get("response")
- active_usage = getattr(response, "usage", None)
- active_input = int(
- getattr(active_usage, "input_tokens", 0) or 0
- ) + int(getattr(active_usage, "output_tokens", 0) or 0)
- rendered_messages = [
- dict(message_to_wire(message))
- for message in list(final_state.get("messages") or [])
- ]
try:
- result = await AgentContextCompactionService(
- runtime.store
- ).update_pressure_and_compact(
- runtime.writer.ref,
- operation_id=(
- f"{runtime.operation_id}:{operation_suffix}"
- ),
- provider=runtime.provider,
- model=runtime.model,
- policy=runtime.policy,
- active_input_tokens=active_input,
- output_headroom=max_tokens,
- rendered_request=rendered_messages,
- portable_compactor=lambda wires, policy: (
- self._portable_context_candidate(
- wires,
- policy,
- provider=runtime.provider,
- api_key=api_key,
- model=runtime.model,
- )
- ),
+ wires = await load_conversation(
+ database,
+ workflow_id=resolved_workflow_id,
+ generation=generation,
+ agent_node_id=node_id,
)
- runtime.writer.ref = result.ref
- if result.lifetime_usage:
- final_state["usage"] = _coerce_native_usage(
- final_state.get("usage")
- ) + _coerce_native_usage(result.lifetime_usage)
- try:
- from nodes.context._events import (
- dispatch_context_compacted,
- dispatch_context_updated,
- )
-
- await dispatch_context_updated(
- workflow_id=result.ref.workflow_id,
- context_node_id=result.ref.context_node_id,
- thread_id=result.ref.thread_id,
- epoch=result.ref.epoch,
- revision=result.ref.revision,
- provider=runtime.provider,
- active_token_count=result.pressure_tokens,
- )
- if result.compacted and result.checkpoint is not None:
- await dispatch_context_compacted(
- workflow_id=result.ref.workflow_id,
- context_node_id=result.ref.context_node_id,
- thread_id=result.ref.thread_id,
- epoch=result.ref.epoch,
- revision=result.ref.revision,
- provider=runtime.provider,
- strategy=result.checkpoint.strategy,
- covers_through_sequence=(
- result.checkpoint.covers_through_sequence
- ),
- active_token_count=result.pressure_tokens,
- )
- except Exception as exc:
- logger.debug("[Context] metadata event failed: %s", exc)
- return result
except Exception as exc:
- # A failed candidate never replaces the prior checkpoint. The
- # completed model response remains successful and replayable.
- logger.warning("[Context] compaction skipped: %s", exc)
- return None
-
- async def _commit_context_compaction_pause(
- self,
- runtime: Optional["_AgentContextRuntime"],
- *,
- iteration: int,
- response: LLMResponse,
- messages: List[NativeMessage],
- api_key: str,
- max_tokens: int,
- ) -> Optional[List[NativeMessage]]:
- """Durably activate a provider pause before the next model request."""
-
- if runtime is None:
- return None
- result = await self._finalize_context(
- runtime,
- final_state={
- "response": response,
- "usage": response.billing_usage or response.usage,
- },
- api_key=api_key,
- max_tokens=max_tokens,
- operation_suffix=f"compaction-pause:{iteration}",
- )
- if result is None or not result.compacted:
- return messages
- from services.agent_context import reconstruct_messages
-
- current_ref, replay = await reconstruct_messages(
- runtime.store,
- runtime.writer.ref,
- )
- runtime.writer.ref = current_ref
- # Provider compaction checkpoints replace conversation replay, not the
- # effective request instruction. Anthropic's durability pause occurs
- # mid-loop, so dropping the system message here would silently change
- # the agent's contract on the very next request.
- system_messages = [
- message for message in messages if message.role == "system"
+ raise ValueError(
+ "Conversation load failed for workflow "
+ f"{resolved_workflow_id} generation {generation} agent "
+ f"{node_id}: {exc}"
+ ) from exc
+ history = [
+ message_from_wire(wire)
+ for wire in wires
+ if isinstance(wire, dict)
]
- return [*system_messages, *replay]
+ return _AgentContextRuntime(
+ workflow_id=resolved_workflow_id,
+ generation=generation,
+ agent_node_id=node_id,
+ database=database,
+ history=history,
+ )
def _extract_text_content(self, content, ai_response=None) -> str:
"""Extract text content from various response formats.
@@ -1307,13 +971,12 @@ class AIService:
context_data=memory_data,
execution_context=context,
workflow_id=workflow_id,
- provider=provider,
- model=model,
database=database or self.database,
)
if context_runtime is not None:
- # Simple Memory is an explicit tool in V2. Legacy automatic
- # recall/persistence remains only for immutable V1 snapshots.
+ # Simple Memory is an explicit tool when a Context node is
+ # connected; legacy automatic recall/persistence remains only
+ # for immutable V1 snapshots.
memory_data = None
# Build initial messages for state. The SystemMessage is
@@ -1738,46 +1401,13 @@ class AIService:
max_iterations=recursion_limit,
progress_callback=_emit_progress if broadcaster else None,
rebind_from_operations=_rebind_from_operations if auto_rebind_enabled else None,
- context_management=(
- context_runtime.request_options
- if context_runtime is not None
- else None
- ),
- compaction_pause_callback=(
- (
- lambda iteration, response, messages: (
- self._commit_context_compaction_pause(
- context_runtime,
- iteration=iteration,
- response=response,
- messages=messages,
- api_key=api_key,
- max_tokens=max_tokens,
- )
- )
- )
- if context_runtime is not None
- else None
- ),
- context_transition_sink=(
- context_runtime.writer
- if context_runtime is not None
- else None
- ),
- context_operation_id=(
- context_runtime.operation_id
+ conversation_saver=(
+ context_runtime.save
if context_runtime is not None
else None
),
)
- context_result = await self._finalize_context(
- context_runtime,
- final_state=final_state,
- api_key=api_key,
- max_tokens=max_tokens,
- )
-
# Extract the AI response (last message in the accumulated messages)
all_messages = final_state["messages"]
ai_response = all_messages[-1] if all_messages else None
@@ -1899,13 +1529,9 @@ class AIService:
result["memory"] = {"session_id": session_id, "history_loaded": history_count}
if context_runtime is not None:
result["context"] = {
- "context_node_id": context_runtime.writer.ref.context_node_id,
- "thread_id": context_runtime.writer.ref.thread_id,
- "epoch": context_runtime.writer.ref.epoch,
- "revision": context_runtime.writer.ref.revision,
- "compacted": bool(
- context_result and context_result.compacted
- ),
+ "workflow_id": context_runtime.workflow_id,
+ "generation": context_runtime.generation,
+ "agent_node_id": context_runtime.agent_node_id,
}
log_execution_time(logger, "ai_agent_loop", start_time, time.time())
@@ -2154,8 +1780,6 @@ class AIService:
context_data=memory_data,
execution_context=context,
workflow_id=workflow_id,
- provider=provider,
- model=model,
database=database or self.database,
)
if context_runtime is not None:
@@ -2458,34 +2082,8 @@ class AIService:
max_iterations=recursion_limit,
progress_callback=_emit_progress if broadcaster else None,
rebind_from_operations=_rebind_from_operations if auto_rebind_enabled else None,
- context_management=(
- context_runtime.request_options
- if context_runtime is not None
- else None
- ),
- compaction_pause_callback=(
- (
- lambda iteration, response, current_messages: (
- self._commit_context_compaction_pause(
- context_runtime,
- iteration=iteration,
- response=response,
- messages=current_messages,
- api_key=api_key,
- max_tokens=max_tokens,
- )
- )
- )
- if context_runtime is not None
- else None
- ),
- context_transition_sink=(
- context_runtime.writer
- if context_runtime is not None
- else None
- ),
- context_operation_id=(
- context_runtime.operation_id
+ conversation_saver=(
+ context_runtime.save
if context_runtime is not None
else None
),
@@ -2512,34 +2110,8 @@ class AIService:
thinking=thinking_config,
initial_messages=messages,
max_iterations=1,
- context_management=(
- context_runtime.request_options
- if context_runtime is not None
- else None
- ),
- compaction_pause_callback=(
- (
- lambda iteration, response, current_messages: (
- self._commit_context_compaction_pause(
- context_runtime,
- iteration=iteration,
- response=response,
- messages=current_messages,
- api_key=api_key,
- max_tokens=max_tokens,
- )
- )
- )
- if context_runtime is not None
- else None
- ),
- context_transition_sink=(
- context_runtime.writer
- if context_runtime is not None
- else None
- ),
- context_operation_id=(
- context_runtime.operation_id
+ conversation_saver=(
+ context_runtime.save
if context_runtime is not None
else None
),
@@ -2554,13 +2126,6 @@ class AIService:
)
thinking_content = final_state.get("thinking_content")
- context_result = await self._finalize_context(
- context_runtime,
- final_state=final_state,
- api_key=api_key,
- max_tokens=max_tokens,
- )
-
logger.info(f"[ChatAgent] Response generated, thinking={'yes' if thinking_content else 'no'}, iterations={iterations}")
# Track token usage if memory connected (for compaction service)
@@ -2665,13 +2230,9 @@ class AIService:
result["memory"] = {"session_id": session_id, "history_loaded": history_count}
if context_runtime is not None:
result["context"] = {
- "context_node_id": context_runtime.writer.ref.context_node_id,
- "thread_id": context_runtime.writer.ref.thread_id,
- "epoch": context_runtime.writer.ref.epoch,
- "revision": context_runtime.writer.ref.revision,
- "compacted": bool(
- context_result and context_result.compacted
- ),
+ "workflow_id": context_runtime.workflow_id,
+ "generation": context_runtime.generation,
+ "agent_node_id": context_runtime.agent_node_id,
}
if skill_data:
diff --git a/server/services/cli_agent/context_bridge.py b/server/services/cli_agent/context_bridge.py
index 0d568ae4..50c91977 100644
--- a/server/services/cli_agent/context_bridge.py
+++ b/server/services/cli_agent/context_bridge.py
@@ -1,10 +1,10 @@
-"""Backend-only Context V2 bridge for specialized agent runtimes.
+"""Plain conversation bridge for specialized agent runtimes.
-Canvas Context nodes carry policy and topology only. This module resolves the
-durable thread, writes exact observable provider events to the append-only
-journal, and owns opaque provider continuation bindings. Specialized node
-plugins pass the descriptor returned by ``collect_agent_connections``; they do
-not read or mutate Context node parameters themselves.
+Canvas Context nodes carry policy and topology only. Specialized providers
+(claude_code, codex, rlm, vertex) do not run through the native agent loop,
+so this module gives them the same continuity contract the loop has: load
+the stored conversation for ``(workflow_id, generation, agent_node_id)`` at
+run start, render it into the prompt, and save the exchange back per turn.
The bridge is intentionally absent for legacy ``input-memory`` descriptors so
already-recorded V1 generations retain their original Simple Memory behavior.
@@ -12,265 +12,52 @@ already-recorded V1 generations retain their original Simple Memory behavior.
from __future__ import annotations
-import asyncio
-import hashlib
import json
-import uuid
-from dataclasses import asdict, dataclass, field, is_dataclass
-from typing import Any, Literal, Optional
+from dataclasses import dataclass
+from typing import Any, Optional
-from models.agent_context import (
- AgentContextActiveState,
- AgentContextRef,
- ContextFidelity,
+from services.llm.protocol import (
+ Message,
+ message_from_wire,
+ message_to_wire,
)
-from services.agent_context import (
- AgentContextStore,
- AgentContextTransitionWriter,
- OpaqueCheckpointError,
- import_generation_zero_handoff,
- reconstruct_transcript,
-)
-from services.llm.protocol import Message, message_from_wire, message_to_wire
-
-
-ProviderFidelity = Literal[
- "provider_replayable",
- "provider_bound",
- "observable_only",
-]
def is_context(value: Any) -> bool:
- """Return whether an edge-walker descriptor is a Context V2 reference."""
+ """Return whether an edge-walker descriptor is a Context reference."""
return isinstance(value, dict) and value.get("kind") == "context"
-def _jsonable(value: Any) -> Any:
- """Convert provider SDK/dataclass values into exact JSON-safe payloads."""
-
- if value is None or isinstance(value, (str, int, float, bool)):
- return value
- if isinstance(value, dict):
- return {str(key): _jsonable(item) for key, item in value.items()}
- if isinstance(value, (list, tuple, set, frozenset)):
- return [_jsonable(item) for item in value]
- if is_dataclass(value):
- return _jsonable(asdict(value))
- model_dump = getattr(value, "model_dump", None)
- if callable(model_dump):
- try:
- return _jsonable(model_dump(mode="json", exclude_none=False))
- except TypeError:
- return _jsonable(model_dump())
- if hasattr(value, "__dict__"):
- return {
- str(key): _jsonable(item)
- for key, item in vars(value).items()
- if not str(key).startswith("_")
- }
- return str(value)
-
-
-def _portable_wire(value: dict[str, Any]) -> dict[str, Any]:
- """Validate a portable wire and remove prior-provider opaque state."""
-
- wire = dict(message_to_wire(message_from_wire(value)))
- wire["provider_state"] = {}
- return wire
-
-
-async def _observable_handoff_messages(
- store: AgentContextStore,
- state: AgentContextActiveState,
- *,
- include_message_wires: bool,
-) -> list[dict[str, Any]]:
- """Render exact observable boundaries when native replay is unavailable."""
-
- messages: list[dict[str, Any]] = []
- for event in state.tail:
- if event.event_type in {
- "provider_handoff",
- "request.snapshot",
- }:
- continue
- if event.message_wire is not None:
- if include_message_wires:
- messages.append(_portable_wire(event.message_wire))
- continue
-
- payload = (
- await store.get_blob(event.payload_ref)
- if event.payload_ref
- else None
- )
- envelope = {
- "sequence": event.sequence,
- "event_type": event.event_type,
- "provider": event.provider,
- "operation_id": event.operation_id,
- "payload": _jsonable(payload),
- }
- role = (
- "user"
- if event.event_type in {"provider.request", "request.snapshot"}
- else "assistant"
- )
- messages.append(
- dict(
- message_to_wire(
- Message(
- role=role,
- content=json.dumps(
- envelope,
- ensure_ascii=False,
- sort_keys=True,
- separators=(",", ":"),
- ),
- )
- )
- )
- )
- return messages
-
-
-async def _build_portable_handoff(
- store: AgentContextStore,
- state: AgentContextActiveState,
- *,
- from_provider: str,
- to_provider: str,
-) -> tuple[str, tuple[dict[str, Any], ...]]:
- """Persist a provider-neutral replay payload for an epoch fork."""
+def _wire(role: str, content: str) -> dict[str, Any]:
+ """Build one validated conversation wire from plain text."""
- fidelity = "portable"
- reconstructed: list[dict[str, Any]] = []
- try:
- _, reconstructed = await reconstruct_transcript(
- store,
- state.ref,
- )
- messages = [_portable_wire(item) for item in reconstructed]
- except OpaqueCheckpointError:
- messages = []
- observable_messages = await _observable_handoff_messages(
- store,
- state,
- include_message_wires=not reconstructed,
- )
- if observable_messages:
- messages.extend(observable_messages)
- if not reconstructed:
- fidelity = "observable_only"
-
- payload_ref = await store.put_blob(
- {
- "format": "portable_provider_handoff_v2",
- "fidelity": fidelity,
- "from_provider": from_provider,
- "to_provider": to_provider,
- "source_epoch": state.ref.epoch,
- "messages": messages,
- "source_checkpoint": (
- {
- "provider": state.checkpoint.provider,
- "strategy": state.checkpoint.strategy,
- "covers_through_sequence": (
- state.checkpoint.covers_through_sequence
- ),
- "source_hash": state.checkpoint.source_hash,
- }
- if state.checkpoint is not None
- else None
- ),
- }
- )
- return payload_ref, tuple(messages)
-
-
-async def _pending_handoff_messages(
- store: AgentContextStore,
- ref: AgentContextRef,
-) -> tuple[AgentContextRef, tuple[dict[str, Any], ...]]:
- """Recover an unconsumed handoff after a crash between fork and request."""
-
- state = await store.load_active(ref)
- handoff = next(
- (
- event
- for event in reversed(state.tail)
- if event.event_type == "provider_handoff"
- and event.payload_ref
- ),
- None,
- )
- if handoff is None:
- return state.ref, ()
- if any(
- event.sequence > handoff.sequence
- and event.event_type
- in {
- "provider.result",
- "provider.response",
- "provider.final",
- }
- for event in state.tail
- ):
- return state.ref, ()
- payload = await store.get_blob(handoff.payload_ref)
- candidates = (
- payload.get("messages") if isinstance(payload, dict) else None
- )
- if not isinstance(candidates, list):
- raise ValueError("provider handoff is missing portable messages")
- messages: list[dict[str, Any]] = []
- for candidate in candidates:
- if not isinstance(candidate, dict):
- raise ValueError(
- "provider handoff contains a non-message item"
- )
- messages.append(_portable_wire(candidate))
- return state.ref, tuple(messages)
+ return dict(message_to_wire(Message(role=role, content=content)))
@dataclass
class SpecializedAgentContextBridge:
- """One epoch-bound Context writer for a specialized provider.
+ """One conversation binding for a specialized provider run.
- ``fidelity`` and ``resumable`` are attached to every opaque event. That
- makes the fidelity boundary explicit in the durable record rather than an
- inference made later by the UI.
+ ``history`` is the stored transcript at resolve time; ``record_turn``
+ appends the new exchange and saves the whole conversation back, so a
+ later firing (or a different provider) continues from the same plain
+ JSON messages the native agent loop uses.
"""
- store: AgentContextStore
- writer: AgentContextTransitionWriter
+ database: Any
+ workflow_id: str
+ generation: int
+ agent_node_id: str
provider: str
- operation_prefix: str
- fidelity: ProviderFidelity
- resumable: bool
- portable_handoff_messages: tuple[dict[str, Any], ...] = field(
- default_factory=tuple
- )
-
- def __post_init__(self) -> None:
- self._sequence = 0
- self._sequence_lock = asyncio.Lock()
-
- @property
- def ref(self) -> AgentContextRef:
- return self.writer.ref
+ history: tuple[dict[str, Any], ...] = ()
@property
def pool_key(self) -> tuple[str, str, int]:
- """Claude pool identity; generation is already isolated by node id."""
+ """Claude pool identity; a new generation is a new key, so Reset
+ fences warm subprocesses without a lifecycle notification."""
- return (
- self.ref.context_node_id,
- self.ref.thread_id,
- self.ref.epoch,
- )
+ return (self.workflow_id, self.agent_node_id, self.generation)
@classmethod
async def resolve(
@@ -279,175 +66,92 @@ class SpecializedAgentContextBridge:
descriptor: dict[str, Any],
*,
provider: str,
- fidelity: ProviderFidelity,
- resumable: bool,
- operation_prefix: Optional[str] = None,
+ agent_node_id: str,
) -> "SpecializedAgentContextBridge":
if not is_context(descriptor):
- raise ValueError("specialized Context bridge requires context_v2")
+ raise ValueError("specialized Context bridge requires a context descriptor")
workflow_id = str(descriptor.get("workflow_id") or "")
- context_node_id = str(
- descriptor.get("context_node_id")
- or descriptor.get("node_id")
- or ""
- )
- execution_id = descriptor.get("execution_id")
- delegated_task_id = descriptor.get("delegated_task_id")
- session_id = descriptor.get("session_id")
generation = int(descriptor.get("generation") or 0)
+ if not workflow_id:
+ raise ValueError("specialized Context bridge requires workflow_id")
if generation <= 0:
raise ValueError(
"specialized Context bridge requires an admitted generation"
)
- store = AgentContextStore(database)
- ref = await store.resolve_thread(
- workflow_id=workflow_id,
- context_node_id=context_node_id,
- generation=generation,
- session_id=str(session_id) if session_id else None,
- delegated_task_id=(
- str(delegated_task_id) if delegated_task_id else None
- ),
- execution_id=str(execution_id) if execution_id else None,
- )
- ref = await import_generation_zero_handoff(store, ref)
- # A provider change is an epoch boundary. Preserve a portable index
- # of the active checkpoint/tail in blob storage, archive opaque
- # bindings, and fence every writer holding the previous ref.
- summary = await store.load_thread_summary(ref)
- prior_provider = summary.provider
- portable_messages: tuple[dict[str, Any], ...] = ()
- if (
- prior_provider
- and prior_provider != "legacy"
- and prior_provider != provider
- ):
- state = await store.load_active(ref)
- handoff_ref, portable_messages = (
- await _build_portable_handoff(
- store,
- state,
- from_provider=prior_provider,
- to_provider=provider,
- )
- )
- identity = (
- f"{workflow_id}:{context_node_id}:"
- f"{ref.generation}:{ref.thread_id}:{ref.epoch}:{provider}"
- )
- digest = hashlib.sha256(identity.encode("utf-8")).hexdigest()
- ref = await store.fork_provider(
- ref,
- provider=provider,
- operation_id=f"specialized-provider-fork:{digest}",
- portable_handoff_ref=handoff_ref,
- )
- else:
- ref, portable_messages = await _pending_handoff_messages(
- store,
- ref,
+
+ from services.agent_context import load_conversation
+
+ try:
+ wires = await load_conversation(
+ database,
+ workflow_id=workflow_id,
+ generation=generation,
+ agent_node_id=agent_node_id,
)
- prefix = operation_prefix or (
- f"specialized-context:{provider}:"
- f"{execution_id or delegated_task_id or session_id or uuid.uuid4().hex}"
- )
+ except Exception as exc:
+ # A load failure must be loud: continuing would silently run the
+ # agent amnesiac and burn tokens on an incomplete prompt.
+ raise ValueError(
+ "Conversation load failed for workflow "
+ f"{workflow_id} generation {generation} agent "
+ f"{agent_node_id}: {exc}"
+ ) from exc
return cls(
- store=store,
- writer=AgentContextTransitionWriter(store, ref),
+ database=database,
+ workflow_id=workflow_id,
+ generation=generation,
+ agent_node_id=agent_node_id,
provider=provider,
- operation_prefix=prefix,
- fidelity=fidelity,
- resumable=resumable,
- portable_handoff_messages=portable_messages,
+ history=tuple(w for w in wires if isinstance(w, dict)),
)
def augment_prompt(self, prompt: str) -> str:
- """Render a pending portable handoff into a prompt-only adapter."""
+ """Render the stored conversation into a prompt-only adapter."""
- if not self.portable_handoff_messages:
+ if not self.history:
+ return prompt
+ lines: list[str] = []
+ for wire in self.history:
+ message = message_from_wire(wire)
+ content = message.content
+ if not isinstance(content, str):
+ content = json.dumps(content, ensure_ascii=False, default=str)
+ if not content:
+ continue
+ lines.append(f"{message.role.upper()}: {content}")
+ if not lines:
return prompt
- transcript = json.dumps(
- list(self.portable_handoff_messages),
- ensure_ascii=False,
- sort_keys=True,
- separators=(",", ":"),
- )
return (
- "## Prior agent context (portable MessageWire replay)\n"
- "The backend reconstructed the following committed context "
- "from the previous provider. Treat it as prior conversation "
- "state and continue from it.\n"
- f"{transcript}\n\n"
- "## Current request\n"
- f"{prompt}"
+ "## Prior conversation\n"
+ "The following is the stored conversation for this agent. "
+ "Treat it as prior conversation state and continue from it.\n"
+ + "\n\n".join(lines)
+ + "\n\n## Current request\n"
+ + prompt
)
- async def append_observable(
+ async def record_turn(
self,
- event_type: str,
- payload: Any,
- *,
- operation_suffix: Optional[str] = None,
+ prompt: str,
+ response: Optional[str],
) -> None:
- """Append one exact provider boundary/event before presentation."""
+ """Append one exchange and save the conversation (best-effort)."""
- if operation_suffix is None:
- async with self._sequence_lock:
- self._sequence += 1
- operation_suffix = f"event:{self._sequence}"
- await self.writer.append_transition(
- event_type=event_type,
- operation_id=f"{self.operation_prefix}:{operation_suffix}",
- provider=self.provider,
- payload={
- "fidelity": self.fidelity,
- "resumable": self.resumable,
- "observable_only": self.fidelity == "observable_only",
- "non_resumable": not self.resumable,
- "event": _jsonable(payload),
- },
- )
-
- async def capture_provider_event(self, event: dict[str, Any]) -> None:
- """Raw stream sink called before buffers or 4,000-char UI truncation."""
+ turn: list[dict[str, Any]] = [_wire("user", prompt)]
+ if response:
+ turn.append(_wire("assistant", response))
+ messages = [*self.history, *turn]
- await self.append_observable("provider.stream", event)
-
- async def load_binding(
- self,
- binding_type: str,
- ) -> Optional[dict[str, Any]]:
- """Load the most recently committed binding of ``binding_type``."""
-
- bindings = await self.store.load_provider_bindings(
- self.writer.ref,
- provider=self.provider,
- )
- for binding in reversed(bindings):
- if binding.binding_type != binding_type:
- continue
- payload = await self.store.get_blob(binding.binding_ref)
- return dict(payload) if isinstance(payload, dict) else None
- return None
-
- async def bind_provider(
- self,
- binding_type: str,
- binding: dict[str, Any],
- *,
- operation_suffix: str,
- fidelity: ContextFidelity = "provider_bound",
- ) -> None:
- """Persist an opaque continuation identity outside graph/runtime data."""
+ from services.agent_context import save_conversation
- await self.store.bind_provider(
- self.writer.ref,
- provider=self.provider,
- binding_type=binding_type,
- binding=_jsonable(binding),
- operation_id=f"{self.operation_prefix}:{operation_suffix}",
- fidelity=fidelity,
+ await save_conversation(
+ self.database,
+ workflow_id=self.workflow_id,
+ generation=self.generation,
+ agent_node_id=self.agent_node_id,
+ messages=messages,
)
+ self.history = tuple(messages)
__all__ = [
diff --git a/server/services/cli_agent/service.py b/server/services/cli_agent/service.py
index 5f60c9b5..51a34a71 100644
--- a/server/services/cli_agent/service.py
+++ b/server/services/cli_agent/service.py
@@ -102,6 +102,7 @@ class AICliService:
task_list: List[BaseAICliTaskSpec] = list(tasks)
connected_tools = list(connected_tools or [])
context_bridge: Optional[SpecializedAgentContextBridge] = None
+ context_original_prompts: List[str] = []
if is_context(connected_context):
from services.plugin.deps import get_database
@@ -112,18 +113,13 @@ class AICliService:
get_database(),
connected_context,
provider=provider_id,
- fidelity=(
- "provider_bound"
- if provider_name == "claude"
- else "observable_only"
- ),
- resumable=provider_name == "claude",
- operation_prefix=(
- f"cli-context:{provider_id}:"
- f"{execution_id or connected_context.get('execution_id') or 'run'}:"
- f"{node_id}"
- ),
+ agent_node_id=node_id,
)
+ # The stored conversation is the continuity mechanism; provider
+ # native resume only survives within a warm pool subprocess.
+ # Keep the original prompts so the recorded turn never nests a
+ # rendered transcript inside itself.
+ context_original_prompts = [task.prompt for task in task_list]
task_list = [
task.model_copy(
update={
@@ -135,40 +131,12 @@ class AICliService:
for task in task_list
]
- # Claude's opaque UUID is the only supported CLI continuation
- # identity. Resume it explicitly; never use --continue, whose
- # cwd-wide "latest" lookup can cross Context threads.
- if provider_name == "claude":
- if len(task_list) != 1:
- raise ValueError(
- "Context-bound Claude batches require exactly one "
- "task so one thread maps to one provider session."
- )
- binding = await context_bridge.load_binding("session_uuid")
- resume_uuid = str((binding or {}).get("session_uuid") or "")
- if resume_uuid:
- task = task_list[0]
- task_list[0] = task.model_copy(
- update={
- "resume_session_id": resume_uuid,
- "continue_session": False,
- }
- )
-
- await context_bridge.append_observable(
- "provider.request",
- {
- "node_id": node_id,
- "workflow_id": workflow_id,
- "provider": provider_name,
- "tasks": task_list,
- "tool_node_ids": [
- tool.get("node_id") for tool in (connected_tools or [])
- ],
- "skill_names": list(connected_skill_names or []),
- },
- operation_suffix="request",
- )
+ # One conversation maps to one provider session.
+ if provider_name == "claude" and len(task_list) != 1:
+ raise ValueError(
+ "Context-bound Claude batches require exactly one "
+ "task so one conversation maps to one provider session."
+ )
# Pass the per-workflow workspace dir
# (``data/workspaces/<workflow_id>/`` — injected into ctx by
@@ -227,21 +195,10 @@ class AICliService:
"an existing repo).",
workspace_dir,
)
- aborted = self._abort_not_git_repo(
+ return self._abort_not_git_repo(
provider_name=provider_name,
tasks=task_list,
)
- if context_bridge is not None:
- await context_bridge.append_observable(
- "runtime.error",
- {
- "error": "working_directory_not_git_repo",
- "workspace_dir": str(workspace_dir),
- "tasks": aborted.tasks,
- },
- operation_suffix="result",
- )
- return aborted
logger.info(
"[CC-Agent run_batch] resolved repo_root=%s for workspace=%s",
resolved_repo_root,
@@ -349,11 +306,6 @@ class AICliService:
memory_bound=bool(connected_memory) or (
context_bridge is not None and provider_name == "claude"
),
- context_event_sink=(
- context_bridge.capture_provider_event
- if context_bridge is not None
- else None
- ),
)
async with self._lock:
self._active_sessions[key].append(session)
@@ -412,11 +364,6 @@ class AICliService:
connected_tools=connected_tools or [],
connected_skill_names=list(connected_skill_names or []),
workflow_id=workflow_id,
- context_event_sink=(
- context_bridge.capture_provider_event
- if context_bridge is not None
- else None
- ),
)
]
else:
@@ -424,17 +371,6 @@ class AICliService:
*(run_one(t) for t in task_list),
return_exceptions=False,
)
- except BaseException as exc:
- if context_bridge is not None:
- await context_bridge.append_observable(
- "provider.ambiguous_outcome",
- {
- "error_type": type(exc).__name__,
- "error": str(exc),
- },
- operation_suffix="result",
- )
- raise
finally:
async with self._lock:
self._active_sessions.pop(key, None)
@@ -484,58 +420,25 @@ class AICliService:
)
if context_bridge is not None:
- await context_bridge.append_observable(
- "provider.result",
- {
- "provider": provider_name,
- "tasks": results,
- },
- operation_suffix="result",
- )
- if provider_name == "claude":
- stale_binding = any(
- item.error
- and "No conversation found with session ID"
- in item.error
- for item in results
- )
- if stale_binding:
- await context_bridge.bind_provider(
- "session_uuid",
- {
- "session_uuid": None,
- "stale": True,
- "context_node_id": context_bridge.ref.context_node_id,
- "thread_id": context_bridge.ref.thread_id,
- "epoch": context_bridge.ref.epoch,
- },
- operation_suffix="session-binding-stale",
+ # Persist each completed exchange into the plain conversation
+ # store. Best-effort: the provider already ran and billed, so a
+ # save failure must not fail the batch.
+ for original_prompt, item in zip(
+ context_original_prompts, results
+ ):
+ if not (item.success and item.response):
+ continue
+ try:
+ await context_bridge.record_turn(
+ original_prompt,
+ item.response,
)
- from services.cli_agent.factory import get_session_pool
-
- pool = get_session_pool("claude")
- if pool is not None:
- await pool.terminate(context_bridge.pool_key)
- else:
- resumed = next(
- (
- item
- for item in reversed(results)
- if item.success and item.session_id
- ),
- None,
+ except Exception as exc:
+ logger.warning(
+ "[CC-Agent run_batch] conversation save failed; "
+ "continuing: %s",
+ exc,
)
- if resumed is not None:
- await context_bridge.bind_provider(
- "session_uuid",
- {
- "session_uuid": resumed.session_id,
- "context_node_id": context_bridge.ref.context_node_id,
- "thread_id": context_bridge.ref.thread_id,
- "epoch": context_bridge.ref.epoch,
- },
- operation_suffix="session-binding",
- )
elapsed_ms = int((time.monotonic() - start) * 1000)
n_succeeded = sum(1 for r in results if r.success)
diff --git a/server/services/rlm/service.py b/server/services/rlm/service.py
index 5d6f8c61..34000d79 100644
--- a/server/services/rlm/service.py
+++ b/server/services/rlm/service.py
@@ -55,12 +55,7 @@ class RLMService:
database,
context_data,
provider="rlm",
- fidelity="observable_only",
- resumable=False,
- operation_prefix=(
- f"rlm-context:"
- f"{(context or {}).get('execution_id') or 'run'}:{node_id}"
- ),
+ agent_node_id=node_id,
)
async def broadcast_status(phase: str, details: Dict[str, Any] = None):
@@ -161,15 +156,6 @@ class RLMService:
)
effective_tool_data = canonical_tool_data
- async def record_ambiguous_tool_outcome(
- payload: Dict[str, Any],
- ) -> None:
- if context_bridge is not None:
- await context_bridge.append_observable(
- "tool.ambiguous_outcome",
- payload,
- )
-
custom_tools = ToolBridgeAdapter.bridge(
effective_tool_data,
context,
@@ -178,11 +164,7 @@ class RLMService:
parent_node_id=node_id,
workflow_id=workflow_id,
provider=provider,
- ambiguous_outcome_sink=(
- record_ambiguous_tool_outcome
- if context_bridge is not None
- else None
- ),
+ ambiguous_outcome_sink=None,
)
# === RLM-specific parameters ===
@@ -222,27 +204,6 @@ class RLMService:
augmented_prompt
)
- if context_bridge is not None:
- await context_bridge.append_observable(
- "provider.request",
- {
- "provider": provider,
- "model": model,
- "prompt": augmented_prompt,
- "max_iterations": max_iterations,
- "max_depth": max_depth,
- "max_budget": max_budget,
- "max_timeout": max_timeout,
- "max_tokens": max_tokens,
- "tool_node_ids": [
- item.get("node_id")
- for item in effective_tool_data
- if isinstance(item, dict)
- ],
- },
- operation_suffix="request",
- )
-
def _run_rlm():
from rlm import RLM
from rlm.logger import RLMLogger
@@ -266,16 +227,15 @@ class RLMService:
result = await asyncio.to_thread(_run_rlm)
- if context_bridge is not None:
- await context_bridge.append_observable(
- "provider.result",
- {
- "response": result.response,
- "metadata": result.metadata,
- "usage_summary": result.usage_summary,
- },
- operation_suffix="result",
- )
+ if context_bridge is not None and result.response:
+ # Best-effort: the provider already ran and billed, so a
+ # save failure must not fail the run.
+ try:
+ await context_bridge.record_turn(prompt, result.response)
+ except Exception as exc:
+ logger.warning(
+ "[RLM] conversation save failed; continuing: %s", exc
+ )
# === Memory save (same pattern as execute_chat_agent) ===
if memory_data and memory_data.get("node_id"):
@@ -314,26 +274,13 @@ class RLMService:
}
except Exception as e:
- public_error = (
- str(e)
- if context_bridge is None
- else f"{type(e).__name__}: RLM execution failed"
- )
+ public_error = str(e)
logger.error(
"[RLM] Execution failed type=%s",
type(e).__name__,
- exc_info=context_bridge is None,
+ exc_info=True,
)
execution_time = time.time() - start_time
- if context_bridge is not None:
- await context_bridge.append_observable(
- "provider.error",
- {
- "error_type": type(e).__name__,
- "error": str(e),
- },
- operation_suffix="error",
- )
await broadcast_status("error", {"message": public_error})
return {
"success": False,
diff --git a/server/services/temporal/agent_activities.py b/server/services/temporal/agent_activities.py
index 04e6cba9..1132a438 100644
--- a/server/services/temporal/agent_activities.py
+++ b/server/services/temporal/agent_activities.py
@@ -47,10 +47,16 @@ from typing import Any, Dict, List, Mapping, Optional
from temporalio import activity
from temporalio.exceptions import ApplicationError
-from models.agent_context import AgentContextRef
logger = logging.getLogger(__name__)
+# Byte ceiling for the stored conversation returned by ``prepare_agent_payload``
+# as a fresh-run seed. Conversations are compaction-bounded in tokens but not
+# in bytes, and Temporal's payload error limit is 2 MiB for the whole activity
+# result — over the cap the run degrades to its opening prompt with a warning
+# instead of dying. Mirrors ``_CAN_TRANSCRIPT_MAX_BYTES`` on the rollover path.
+_SEED_TRANSCRIPT_MAX_BYTES = 1_000_000
+
# Activity result shapes — keep these in sync with AgentWorkflow's
# expectations. Pydantic was considered but plain dicts keep the
# payload-serialisation cost flat (Temporal serialises via JSON anyway)
@@ -309,11 +315,12 @@ async def _execute_native_llm_step(payload: Dict[str, Any]) -> Dict[str, Any]:
assistant_wire = message_to_wire(assistant)
usage = asdict(response.usage)
- # Record the turn exactly as it happened: the message list this activity
- # just sent to the provider, and the reply it got back. ``messages`` above
- # IS the argument handed to ``ChatUnifier.chat`` — nothing is rebuilt,
- # inferred, or re-typed, so the journal cannot drift from the request.
- await _journal_llm_turn(
+ # Persist the conversation exactly as it happened: the message list this
+ # activity just sent to the provider plus the reply it got back.
+ # ``messages`` above IS the argument handed to ``ChatUnifier.chat`` —
+ # nothing is rebuilt, inferred, or re-typed, so the stored conversation
+ # cannot drift from the request.
+ await _save_conversation(
payload,
sent=[dict(message_to_wire(message)) for message in messages],
assistant_wire=dict(assistant_wire),
@@ -356,52 +363,41 @@ async def _execute_native_llm_step(payload: Dict[str, Any]) -> Dict[str, Any]:
return result
-async def _journal_llm_turn(
+async def _save_conversation(
payload: Dict[str, Any],
*,
sent: List[Dict[str, Any]],
assistant_wire: Dict[str, Any],
) -> None:
- """Append this turn to the Context journal, when one is attached.
+ """Persist the full transcript for this turn, when a key is attached.
- Observation only: it never influences the request. ``request.snapshot``
- carries the exact list sent, which is what
- :func:`services.agent_context.runtime.reconstruct_transcript`
- documents that event to be — the render boundary that later assistant and
- tool transitions are applied on top of.
+ Persistence only: it never influences the request. ``sent`` is the
+ exact list handed to the provider; ``sent + [assistant]`` IS the
+ conversation after this turn, saved whole (last-write-wins upsert per
+ key). Living inside the LLM activity means per-turn durability with
+ zero extra activities and zero Temporal-history payload.
"""
- ref_data = payload.get("context_ref")
- operation_id = str(payload.get("journal_operation_id") or "")
- if not ref_data or not operation_id:
+ key = payload.get("conversation_key")
+ if not isinstance(key, dict):
return
try:
- store = _context_store()
- ref = _context_ref(ref_data)
- provider = str(payload.get("provider") or "")
- ref = await _append_event(
- store,
- ref,
- event_type="request.snapshot",
- operation_id=f"{operation_id}:request",
- provider=provider,
- payload_ref=await store.put_blob({"messages": sent}),
- )
- await _append_event(
- store,
- ref,
- event_type="message.assistant",
- operation_id=f"{operation_id}:assistant",
- provider=provider,
- message_wire=assistant_wire,
+ from core.container import container
+ from services.agent_context import save_conversation
+
+ await save_conversation(
+ container.database(),
+ workflow_id=str(key.get("workflow_id") or ""),
+ generation=int(key.get("generation") or 0),
+ agent_node_id=str(key.get("agent_node_id") or ""),
+ messages=[*sent, assistant_wire],
)
except Exception:
- # Observation must never fail the run. The provider has already been
- # called and billed by this point, so raising here would fail the turn
- # — and, for a team lead, stall its next delegation — over a bookkeeping
- # write. A thread fenced by Reset or an archived epoch is exactly the
- # expected case: the agent keeps going, the journal just misses a turn.
+ # Persistence must never fail the run. The provider has already
+ # been called and billed by this point, so raising here would fail
+ # the turn — and, for a team lead, stall its next delegation —
+ # over a bookkeeping write.
activity.logger.warning(
- "Context journal write failed; execution continues",
+ "Conversation save failed; execution continues",
exc_info=True,
)
@@ -997,6 +993,59 @@ async def prepare_agent_payload(context: Dict[str, Any]) -> Dict[str, Any]:
memory_content = memory_data.get("memory_content") or ""
memory_window_size = int(memory_data.get("window_size") or 10)
+ # ---- Conversation (plain JSON transcript) ---------------------------
+ # A connected Context node opts the agent into durable conversation
+ # persistence: key (workflow_id, generation, agent_node_id), loaded here
+ # as the fresh-run seed and saved per turn inside the LLM step. Every
+ # firing — chat messages AND task-completion reviews — continues the
+ # same conversation; Reset admits a new generation, which is a new key.
+ # Load failures are LOUD: running the agent with its memory silently
+ # missing wastes billed tokens on a run that has forgotten everything.
+ # A transient DB error gets the activity retry budget; an over-sized
+ # transcript is user-actionable (clear or compact) and fails fast.
+ # See docs-internal/agent_context_flow.md.
+ conversation: List[Dict[str, Any]] = []
+ conversation_key: Optional[Dict[str, Any]] = None
+ generation = int(context.get("generation") or 0)
+ if (
+ context_descriptor.get("kind") == "context"
+ and workflow_id
+ and generation > 0
+ ):
+ conversation_key = {
+ "workflow_id": str(workflow_id),
+ "generation": generation,
+ "agent_node_id": node_id,
+ }
+ try:
+ from services.agent_context import load_conversation
+
+ conversation = await load_conversation(
+ database,
+ **conversation_key,
+ )
+ except Exception as exc:
+ raise ApplicationError(
+ f"Conversation load failed for agent {node_id!r} "
+ f"(generation {generation}): {type(exc).__name__}",
+ type="ConversationLoadFailed",
+ non_retryable=False,
+ ) from exc
+ if conversation:
+ seed_bytes = len(
+ json.dumps(conversation, default=str).encode("utf-8")
+ )
+ if seed_bytes > _SEED_TRANSCRIPT_MAX_BYTES:
+ raise ApplicationError(
+ f"Stored conversation for agent {node_id!r} is "
+ f"{seed_bytes} bytes (limit "
+ f"{_SEED_TRANSCRIPT_MAX_BYTES}). Clear the conversation "
+ "from the Context panel or lower the compaction "
+ "threshold, then run again.",
+ type="ConversationTooLarge",
+ non_retryable=True,
+ )
+
# ---- Tools ----------------------------------------------------------
# We call ``ai_service._build_tool_from_node`` once here ONLY to
# extract the LLM-visible tool name (the workflow needs it to map
@@ -1182,6 +1231,8 @@ async def prepare_agent_payload(context: Dict[str, Any]) -> Dict[str, Any]:
"memory_content": memory_content,
"memory_window_size": memory_window_size,
"context_descriptor": context_descriptor,
+ "conversation": conversation,
+ "conversation_key": conversation_key,
"max_iterations": effective_recursion_limit,
"thinking_config": thinking_config_dict,
"compaction_threshold": compaction_threshold,
@@ -1835,20 +1886,20 @@ def collect_agent_activities() -> List[Any]:
register_task_execution,
finish_agent_delegation,
finalize_agent_team,
- # Context journal surface: thread resolution for the view-only
- # journal, plus the conversation summarizer.
- prepare_context,
+ # Conversation persistence is inside execute_llm_step (save) and
+ # prepare_agent_payload (load); the summarizer is the one extra
+ # activity this surface needs.
compact_context,
]
# ---------------------------------------------------------------------------
-# Agent Context journal surface (view-only).
+# Conversation persistence surface.
#
-# The journal observes the agent; it never feeds the request and is never
-# read back on rollover — continue_as_new carries the live transcript.
-# ``_journal_llm_turn`` records each turn, ``prepare_context`` resolves the
-# thread, and ``compact_context`` summarizes the live conversation.
+# Persistence observes the agent; it never feeds the request directly.
+# ``prepare_agent_payload`` loads the stored conversation as a fresh-run
+# seed, ``_save_conversation`` (inside the LLM step) persists each turn,
+# and ``compact_context`` summarizes the live conversation.
# ---------------------------------------------------------------------------
_SENSITIVE_GRAPH_KEYS = frozenset(
@@ -1878,94 +1929,12 @@ def _strip_credentials(value: Any) -> Any:
if isinstance(value, tuple):
return [_strip_credentials(item) for item in value]
return value
-def _context_ref(value: Mapping[str, Any]) -> AgentContextRef:
- return AgentContextRef.model_validate(dict(value))
-def _ref_dict(ref: AgentContextRef) -> Dict[str, Any]:
- return ref.model_dump(mode="json")
-def _hash_from_ref(payload_ref: str) -> str:
- return str(payload_ref).removeprefix("sha256:")
-def _context_store():
- from core.container import container
- from services.agent_context import AgentContextStore
-
- return AgentContextStore(container.database())
def _non_retryable(message: str, error_type: str) -> ApplicationError:
return ApplicationError(
message,
type=error_type,
non_retryable=True,
)
-def _context_node_id(context: Mapping[str, Any]) -> str:
- """Return the exactly-one Context companion wired to this agent."""
-
- node_id = str(context.get("node_id") or "")
- nodes = {
- str(node.get("id")): node
- for node in context.get("nodes") or []
- if isinstance(node, dict) and node.get("id")
- }
- candidates: list[str] = []
- for edge in context.get("edges") or []:
- if not isinstance(edge, dict) or str(edge.get("target") or "") != node_id:
- continue
- handle = edge.get("targetHandle") or edge.get("target_handle")
- if handle != "input-context":
- continue
- source_id = str(edge.get("source") or "")
- if (nodes.get(source_id) or {}).get("type") == "context":
- candidates.append(source_id)
- unique = sorted(set(candidates))
- if len(unique) != 1:
- raise _non_retryable(
- (
- f"Context V2 agent {node_id!r} requires exactly one Context "
- f"companion; found {len(unique)}."
- ),
- "InvalidAgentContextTopology",
- )
- return unique[0]
-def _thread_inputs(context: Mapping[str, Any]) -> Dict[str, Optional[str]]:
- """Resolve a delegated-task, explicit-session, or execution thread.
-
- Delegation always gets an isolated task thread even when the parent
- propagates its chat session id into the child context.
- """
-
- raw_session = str(
- context.get("context_session_id")
- or context.get("session_id")
- or ""
- ).strip()
- # ``default`` is the UI placeholder, not an explicit chat identity.
- session_id = raw_session if raw_session and raw_session != "default" else None
- # Controlled deployments deliberately replace the caller's session with
- # their generation-scoped data namespace. That namespace is not an
- # explicit conversation and must not collapse independent trigger
- # firings into one persistent session thread.
- data_scope_id = str(context.get("data_scope_id") or "").strip()
- if session_id and data_scope_id and session_id == data_scope_id:
- session_id = None
- delegated_task_id = str(
- context.get("delegated_task_id")
- or context.get("task_id")
- or context.get("parent_task_id")
- or context.get("team_task_id")
- or (context.get("invocation") or {}).get("task_id")
- or ""
- ).strip() or None
- if delegated_task_id is not None:
- session_id = None
- execution_id = str(
- context.get("context_execution_id")
- or context.get("execution_id")
- or context.get("data_scope_id")
- or ""
- ).strip() or None
- return {
- "session_id": session_id,
- "delegated_task_id": delegated_task_id,
- "execution_id": execution_id,
- }
def _tool_identity(tool: Mapping[str, Any]) -> Dict[str, Any]:
return {
"name": str(tool.get("name") or ""),
@@ -1974,72 +1943,6 @@ def _tool_identity(tool: Mapping[str, Any]) -> Dict[str, Any]:
"version": int(tool.get("version") or 1),
"task_queue": str(tool.get("dispatch_task_queue") or ""),
}
-async def _append_event(
- store: Any,
- ref: AgentContextRef,
- *,
- event_type: str,
- operation_id: str,
- provider: Optional[str] = None,
- message_wire: Optional[Dict[str, Any]] = None,
- payload_ref: Optional[str] = None,
-) -> AgentContextRef:
- result = await store.append_transition(
- ref,
- event_type=event_type,
- operation_id=operation_id,
- provider=provider,
- message_wire=message_wire,
- payload_ref=payload_ref,
- )
- return result.ref
[email protected](name="agent.prepare_context")
-async def prepare_context(payload: Dict[str, Any]) -> Dict[str, Any]:
- """Resolve the Context thread this agent journals into. Read-only."""
-
- context = dict(payload.get("context") or payload)
- workflow_id = str(context.get("workflow_id") or "")
- generation = int(context.get("generation") or 0)
- graph_version = int(
- context.get("graphVersion")
- or context.get("graph_version")
- or 0
- )
- if not workflow_id or generation <= 0 or graph_version < 2:
- raise _non_retryable(
- "Context V2 requires a normalized graph and a positive workflow generation.",
- "InvalidAgentContextGeneration",
- )
-
- context_node_id = _context_node_id(context)
- context["generation"] = generation
- context["graphVersion"] = graph_version
-
- # This activity resolves a thread and nothing else.
- #
- # It used to call ``prepare_agent_payload`` a second time to build a
- # runtime snapshot. That function is NOT a pure read — for a team lead it
- # calls ``get_or_create_execution_team``, so attaching a Context node made
- # the whole team-creation path run twice per turn and interfered with
- # multi-agent delegation. Nothing consumed the snapshot either: the LLM
- # step builds its request from ``messages``, and the workflow reads only
- # ``context_ref`` from this result.
- store = _context_store()
- thread = await store.resolve_thread(
- workflow_id=workflow_id,
- context_node_id=context_node_id,
- generation=generation,
- **_thread_inputs(context),
- )
- # Nothing is journalled here either. This runs BEFORE the request exists,
- # so anything written would be assembled from configuration rather than
- # recorded from what was sent — which is how the journal came to hold a
- # fabricated request, the system prompt typed as a tool result, and the
- # user's prompt twice. ``agent.execute_llm_step`` journals each turn from
- # the exact message list it hands to ``ChatUnifier.chat``.
- return {"context_ref": _ref_dict(thread)}
-
-
@activity.defn(name="agent.compact_context")
async def compact_context(payload: Dict[str, Any]) -> Dict[str, Any]:
"""Summarize the live conversation into a compact replacement.
diff --git a/server/services/temporal/agent_workflow.py b/server/services/temporal/agent_workflow.py
index efc5570a..77bf183a 100644
--- a/server/services/temporal/agent_workflow.py
+++ b/server/services/temporal/agent_workflow.py
@@ -633,16 +633,6 @@ class AgentWorkflow:
task_scope_execution_id = str(
payload.get("team_execution_id") or execution_id
)
- # Journal operation ids must be unique per FIRING, not per generation.
- # ``execution_id`` is generation-scoped (``1:execution:10``), so every
- # chat message within one generation minted identical operation ids
- # and the store's idempotency guard discarded turns 2..N as replays —
- # only the first message a generation ever saw was recorded. The
- # trigger listener already plumbs a per-firing ``context_execution_id``
- # (the child workflow id) for exactly this purpose.
- journal_operation_id = (
- str(context.get("context_execution_id") or "") or execution_id
- )
# Needed by every terminal result, including agents that never make a
# tool call (for example downstream taskTrigger automation). It was
# previously initialized only inside the tool-call branch.
@@ -694,36 +684,20 @@ class AgentWorkflow:
"result": {"iterations": 0, "usage": {}},
}
- # ---- Context journal (view-only) --------------------------------
- # A Context node makes the backend journal every turn the agent sends,
- # for the Context panel. It never steers the request: the LLM activity
- # always builds from ``messages``, and ``context_ref`` only says where
- # to record. The rollover does NOT read the journal back — the live
- # transcript itself crosses the continue-as-new boundary.
- context_ref: Optional[Dict[str, Any]] = None
- if payload.get("context_descriptor"):
- await self._wait_until_resumed()
- prepared_context = await workflow.execute_activity(
- "agent.prepare_context",
- args=[
- {
- "context": context,
- "operation_id": f"{journal_operation_id}:prepare",
- }
- ],
- activity_id="prepare-context",
- start_to_close_timeout=PERSIST_TURN_TIMEOUT * 2,
- retry_policy=AGENT_ACTIVITY_RETRY,
- )
- context_ref = prepared_context.get("context_ref")
- if resume:
- context_ref = resume.get("context_ref") or context_ref
+ # ---- Conversation persistence -----------------------------------
+ # A connected Context node opts the agent into the plain conversation
+ # store: ``prepare_payload`` loaded the stored transcript (and the
+ # key), and the LLM-step activity saves each turn. Persistence never
+ # steers the request — the activity always builds from ``messages``;
+ # the key only says where to save.
+ conversation_key = payload.get("conversation_key")
# ---- Build the message list -------------------------------------
- # A resumed run continues from the exact transcript the previous run
- # carried across continue_as_new. Only a fresh run builds the
- # system + memory + prompt opening.
+ # Precedence: carried rollover transcript (a resumed run continues
+ # mid-flight) > stored conversation (a fresh firing continues the
+ # conversation, with this firing's prompt appended) > bare opening.
carried_transcript = list(resume.get("transcript") or [])
+ stored_conversation = list(payload.get("conversation") or [])
messages: List[Dict[str, Any]] = []
user_prompt = payload.get("user_prompt") or ""
memory_markdown = payload.get("memory_content") or ""
@@ -731,6 +705,21 @@ class AgentWorkflow:
system = payload.get("system_message") or ""
if carried_transcript:
messages = [dict(message) for message in carried_transcript]
+ elif stored_conversation:
+ # This firing's system message stays authoritative; stored
+ # system messages are dropped so policy/skill changes take
+ # effect. The new prompt arrives as the latest user message.
+ if system:
+ messages.append(_native_message(role="system", content=system))
+ messages.extend(
+ dict(wire)
+ for wire in stored_conversation
+ if isinstance(wire, dict) and wire.get("role") != "system"
+ )
+ if user_prompt:
+ messages.append(
+ _native_message(role="user", content=user_prompt)
+ )
else:
if system:
messages.append(_native_message(role="system", content=system))
@@ -823,25 +812,13 @@ class AgentWorkflow:
"temperature": payload.get("temperature", 0.7),
"max_tokens": payload.get("max_tokens", 4096),
"thinking_config": payload.get("thinking_config"),
- # Journalling only. The activity always builds its request
- # from ``messages`` above; these just tell it where to
- # record the turn it actually sent. A Context node observes
+ # Persistence only. The activity always builds its request
+ # from ``messages`` above; the key just tells it where to
+ # save the turn it actually sent. A Context node observes
# the agent, it never steers it.
**(
- {
- "context_ref": context_ref,
- # Scoped by agent node as well as firing: two
- # agents wired to one Context node resolve to the
- # same thread, so a firing-only id made them mint
- # identical operation ids, collide on
- # (thread, operation_id), and have their turns
- # discarded by the store's idempotency guard.
- "journal_operation_id": (
- f"{journal_operation_id}:{agent_node_id}"
- f":iter:{iteration}"
- ),
- }
- if context_ref
+ {"conversation_key": conversation_key}
+ if conversation_key
else {}
),
# A provider may stop a turn to compact rather than to
@@ -2221,7 +2198,6 @@ class AgentWorkflow:
{
**context,
_RESUME_MARKER: {
- "context_ref": context_ref,
"iteration": iteration + 1,
"execution_id": execution_id,
"transcript": carried,
diff --git a/server/services/workflow_context_migration.py b/server/services/workflow_context_migration.py
index 3133d3a6..33ad0f5f 100644
--- a/server/services/workflow_context_migration.py
+++ b/server/services/workflow_context_migration.py
@@ -1,9 +1,13 @@
-"""Durable second phase for Context V2 workflow normalization.
-
-The pure graph migration returns state-import receipts after canonical IDs are
-known. This module commits those receipts before the normalized graph replaces
-its legacy topology, so a failed import never silently discards the only copy
-of legacy conversation state.
+"""Second phase for Context workflow normalization.
+
+The pure graph migration (``services/workflow_migrations.py``) returns
+state-import receipts after canonical IDs are known. With the plain
+conversation store (``key → messages JSON``) there is no journal to import
+legacy markdown into: a migrated graph simply starts its next generation
+with an empty conversation, and the legacy markdown remains inert on the
+old node parameters (``SimpleMemoryParams`` declares ``extra="ignore"``).
+The receipt-processing entry points are kept so callers need no changes,
+but they are deliberate no-ops now.
"""
from __future__ import annotations
@@ -11,7 +15,9 @@ from __future__ import annotations
import asyncio
from typing import Any, Iterable, Mapping
-from services.agent_context import AgentContextStore
+from core.logging import get_logger
+
+logger = get_logger(__name__)
async def load_node_parameters(
@@ -42,77 +48,20 @@ async def import_legacy_context_receipts(
database: Any,
receipts: Iterable[Mapping[str, Any]],
) -> int:
- """Idempotently preserve Markdown and provider bindings as artifacts."""
-
- store = AgentContextStore(database)
- imported = 0
- for receipt in receipts:
- workflow_id = str(receipt.get("workflow_id") or "")
- context_node_id = str(receipt.get("context_node_id") or "")
- operation_id = str(receipt.get("operation_id") or "")
- if not workflow_id or not context_node_id or not operation_id:
- raise ValueError("invalid_context_import_receipt")
-
- # Generation zero is the immutable migration epoch. A new execution
- # imports it as a portable handoff into its own generation/thread.
- ref = await store.resolve_thread(
- workflow_id=workflow_id,
- context_node_id=context_node_id,
- generation=0,
- session_id=str(
- receipt.get("legacy_session_id")
- or receipt.get("agent_node_id")
- or "legacy"
- ),
- )
- markdown = receipt.get("markdown")
- payload_ref = None
- if markdown:
- payload_ref = await store.put_blob(
- {
- "format": "legacy_markdown",
- "fidelity": "legacy_partial",
- "content": str(markdown),
- "source_memory_node_id": receipt.get(
- "legacy_memory_node_id"
- ),
- }
- )
- await store.append_transition(
- ref,
- event_type="legacy_partial",
- operation_id=operation_id,
- payload_ref=payload_ref,
- provider="legacy",
- )
+ """No-op under the plain conversation store.
- bindings = dict(receipt.get("provider_bindings") or {})
- claude_session = bindings.get("last_session_id")
- if claude_session:
- await store.bind_provider(
- ref,
- provider="claude_code",
- binding_type="session_uuid",
- binding={"session_uuid": str(claude_session)},
- operation_id=f"{operation_id}:claude-session",
- fidelity="provider_bound",
- )
- vertex_interaction = bindings.get("vertex_interaction_id")
- vertex_environment = bindings.get("vertex_environment_id")
- if vertex_interaction or vertex_environment:
- await store.bind_provider(
- ref,
- provider="vertex",
- binding_type="interaction_environment",
- binding={
- "interaction_id": vertex_interaction,
- "environment_id": vertex_environment,
- },
- operation_id=f"{operation_id}:vertex-binding",
- fidelity="provider_bound",
- )
- imported += 1
- return imported
+ Legacy markdown/provider-binding receipts were journal imports; the
+ plain store starts migrated conversations fresh. Logged so a migration
+ that produced receipts is still visible in the operator log.
+ """
+
+ count = sum(1 for _ in receipts)
+ if count:
+ logger.info(
+ f"[migration] {count} legacy context receipt(s) skipped — the "
+ "plain conversation store starts migrated conversations fresh"
+ )
+ return 0
async def persist_parameter_aliases(
@@ -155,38 +104,15 @@ async def archive_removed_contexts(
normalized_nodes: Iterable[Mapping[str, Any]],
aliases: Mapping[str, str],
) -> int:
- """Archive journals whose system Context node left the saved graph."""
+ """No-op under the plain conversation store.
- previous = {
- str(node.get("id") or "")
- for node in previous_nodes
- if node.get("type") == "context" and node.get("id")
- }
- current = {
- str(node.get("id") or "")
- for node in normalized_nodes
- if node.get("type") == "context" and node.get("id")
- }
- # Canonicalization is a rename, not deletion.
- removed = {
- context_id
- for context_id in previous
- if context_id not in current
- and aliases.get(context_id) not in current
- }
- if not removed:
- return 0
- store = AgentContextStore(database)
- for context_id in sorted(removed):
- await store.archive_context(
- workflow_id=workflow_id,
- context_node_id=context_id,
- generation=None,
- operation_id=(
- f"context-node-removed:{workflow_id}:{context_id}"
- ),
- )
- return len(removed)
+ Conversations are keyed by agent node, not Context node; removing a
+ Context node merely opts the agent out of persistence going forward.
+ Stored rows stay until the workflow is deleted (or cleared from the
+ panel) — harmless, and cheaper than guessing which agent they served.
+ """
+
+ return 0
__all__ = [
diff --git a/server/services/workflow_migrations.py b/server/services/workflow_migrations.py
index b9e141b4..3cf0fa8d 100644
--- a/server/services/workflow_migrations.py
+++ b/server/services/workflow_migrations.py
@@ -414,7 +414,7 @@ def normalize_workflow_graph(
)
# Persist the ownership marker for backend edge repair/cascade semantics.
- # It is UI metadata only; runtime state remains in AgentContextStore.
+ # It is UI metadata only; runtime state lives in the conversation store.
agents_for_context: Dict[str, List[str]] = {}
for agent_id, sources in existing_contexts.items():
for source_id in dict.fromkeys(sources):
diff --git a/server/services/workflow_storage/handlers.py b/server/services/workflow_storage/handlers.py
index ddac1a8f..cca3e781 100644
--- a/server/services/workflow_storage/handlers.py
+++ b/server/services/workflow_storage/handlers.py
@@ -293,9 +293,8 @@ async def _drain_context_archive_outbox(
if not pending:
return 0, 0
- from services.agent_context import AgentContextStore
+ from services.agent_context import clear_conversation
- store = AgentContextStore(database)
completed = 0
for receipt in pending:
outbox_id = str(receipt.get("id") or "")
@@ -307,12 +306,9 @@ async def _drain_context_archive_outbox(
)
continue
try:
- await store.archive_context(
- workflow_id=workflow_id,
- context_node_id=context_node_id,
- generation=None,
- operation_id=f"context-archive-outbox:{outbox_id}",
- )
+ # Plain store: deleting the workflow deletes its conversations.
+ # Idempotent per receipt — a second pass finds nothing to clear.
+ await clear_conversation(database, workflow_id=workflow_id)
acknowledged = await database.complete_workflow_context_archive_outbox(
outbox_id=outbox_id,
workflow_id=workflow_id,
@@ -683,16 +679,9 @@ async def _archive_workflow_contexts(database: Any, workflow_id: str) -> int:
if not context_ids:
return 0
- from services.agent_context import AgentContextStore
+ from services.agent_context import clear_conversation
- store = AgentContextStore(database)
- for context_id in context_ids:
- await store.archive_context(
- workflow_id=workflow_id,
- context_node_id=context_id,
- generation=None,
- operation_id=f"workflow-deleted:{workflow_id}:{context_id}",
- )
+ await clear_conversation(database, workflow_id=workflow_id)
return len(context_ids)
diff --git a/server/tests/nodes/test_agent_context_node.py b/server/tests/nodes/test_agent_context_node.py
index 1bbd3bcd..5750302f 100644
--- a/server/tests/nodes/test_agent_context_node.py
+++ b/server/tests/nodes/test_agent_context_node.py
@@ -15,14 +15,9 @@ from services.plugin.edge_walker import collect_agent_connections
from services.ws_handler_registry import get_ws_handlers
-def test_context_node_declares_only_policy_and_dedicated_handle():
+def test_context_node_declares_no_parameters_and_a_dedicated_handle():
schema = AgentContextParams.model_json_schema()
- assert set(schema["properties"]) == {
- "compaction_mode",
- "trigger_ratio",
- "context_window_override",
- "exact_tail_retention_count",
- }
+ assert set(schema.get("properties", {})) == set()
forbidden = {
"journal",
"messages",
@@ -32,7 +27,7 @@ def test_context_node_declares_only_policy_and_dedicated_handle():
"epoch",
"revision",
}
- assert forbidden.isdisjoint(schema["properties"])
+ assert forbidden.isdisjoint(schema.get("properties", {}))
assert AgentContextNode.handles == (
{
"name": "output-context",
@@ -66,7 +61,6 @@ def test_context_policy_rejects_runtime_payloads():
with pytest.raises(ValidationError):
AgentContextParams.model_validate(
{
- "compaction_mode": "auto",
"journal": [{"role": "user", "content": "secret"}],
}
)
@@ -77,24 +71,20 @@ def test_context_panel_handlers_self_register():
assert {
"get_agent_context",
"clear_agent_context",
- "fork_agent_context",
- "export_agent_context",
}.issubset(handlers)
+ # The journal-era handlers are gone with the journal itself.
+ assert "fork_agent_context" not in handlers
+ assert "export_agent_context" not in handlers
@pytest.mark.asyncio
-async def test_context_node_operation_is_policy_only_and_metadata_only():
+async def test_context_node_operation_is_metadata_only():
assert set(AgentContextNode._operations) == {"policy"}
result = await AgentContextNode().policy(
NodeContext(node_id="context-1", node_type="context"),
AgentContextParams(),
)
- assert result.model_dump() == {
- "configured": True,
- "compaction_mode": "auto",
- "trigger_ratio": 0.8,
- "exact_tail_retention_count": 8,
- }
+ assert result.model_dump() == {"configured": True}
@pytest.mark.asyncio
@@ -196,4 +186,7 @@ class TestContextPluginOwnsItsDescriptor:
# one thread; the delegated task is the isolation boundary.
assert got["session_id"] is None
assert got["delegated_task_id"] == "task-9"
- assert got["policy"] == {"compaction_mode": "auto"}
+ # Only DECLARED params travel in the descriptor; the node declares
+ # none, so stored legacy keys (compaction_mode, memory_content)
+ # never leak into the runtime.
+ assert got["policy"] == {}
diff --git a/server/tests/nodes/test_context_events.py b/server/tests/nodes/test_context_events.py
index 04824524..445334d3 100644
--- a/server/tests/nodes/test_context_events.py
+++ b/server/tests/nodes/test_context_events.py
@@ -1,15 +1,15 @@
-"""Wire contract for Context lifecycle events.
+"""Wire contract for the Context conversation lifecycle event.
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.
+ Visibility query that is guaranteed to match nothing -- once per save.
+ 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.
+ socket, so a message body leaking in here would be a disclosure bug, not a
+ display bug.
"""
from __future__ import annotations
@@ -21,7 +21,6 @@ from pathlib import Path
import pytest
-from models.agent_context import AgentContextRef
from nodes.context import _events as context_events
@@ -52,98 +51,50 @@ def test_dispatchers_do_not_run_a_visibility_query():
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)
+def test_cloudevents_envelope_shape():
+ event = context_events.context_updated(
+ workflow_id="workflow-1",
+ generation=2,
+ agent_node_id="1:aiAgent:1",
+ message_count=6,
+ )
- assert event.type == expected_type
+ assert event.type == "com.opencompany.context.updated"
assert event.source == "opencompany://nodes/context"
- assert event.subject == "workflow-1:context:1"
- assert event.data["context_node_id"] == "workflow-1:context:1"
+ assert event.subject == "1:aiAgent:1"
+ assert event.data["agent_node_id"] == "1:aiAgent: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,
+ generation=2,
+ agent_node_id="1:aiAgent:1",
+ message_count=6,
)
- 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",
+ "generation",
+ "agent_node_id",
+ "message_count",
}
-def test_sequence_is_omitted_when_absent():
+def test_negative_message_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=9,
- provider=None,
- active_token_count=0,
+ generation=1,
+ agent_node_id="agent-1",
+ message_count=-5,
)
- 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
+ assert event.data["message_count"] == 0
@pytest.mark.asyncio
-async def test_commit_listener_broadcasts_context_updated(monkeypatch):
+async def test_save_listener_broadcasts_context_updated(monkeypatch):
sent: list = []
async def _capture(**metadata):
@@ -153,31 +104,19 @@ async def test_commit_listener_broadcasts_context_updated(monkeypatch):
context_events, "dispatch_context_updated", _capture
)
- ref = AgentContextRef(
+ await context_events.on_conversation_saved(
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,
+ agent_node_id="1:aiAgent:1",
+ message_count=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,
+ "generation": 2,
+ "agent_node_id": "1:aiAgent:1",
+ "message_count": 5,
}
]
@@ -192,11 +131,7 @@ def test_frontend_handles_every_emitted_wire_key():
source = inspect.getsource(context_events)
emitted = set(re.findall(r'wire_routing_key="([^"]+)"', source))
- assert emitted == {
- "context.updated",
- "context.compacted",
- "context.epoch.started",
- }
+ assert emitted == {"context.updated"}
ws_context = (
Path(__file__).resolve().parents[3]
@@ -217,19 +152,21 @@ def test_frontend_handles_every_emitted_wire_key():
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."
- )
+ from services.agent_context import conversation, listeners
+
+ for module in (conversation, listeners):
+ source = inspect.getsource(module)
+ 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_conversation_listener."
+ )
-def test_plugin_registers_its_commit_listener():
+def test_plugin_registers_its_save_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)
+ assert "register_conversation_listener" in source
+ assert context_events.on_conversation_saved in list(listeners._LISTENERS)
diff --git a/server/tests/nodes/test_specialized_context_bridges.py b/server/tests/nodes/test_specialized_context_bridges.py
index 3df395f4..731328b2 100644
--- a/server/tests/nodes/test_specialized_context_bridges.py
+++ b/server/tests/nodes/test_specialized_context_bridges.py
@@ -161,18 +161,13 @@ async def test_codex_node_routes_observable_context_without_resume(harness):
@pytest.mark.asyncio
-async def test_vertex_uses_context_binding_and_redacts_ids_from_output(harness):
+async def test_vertex_records_context_turn_and_redacts_ids_from_output(harness):
nodes, edges = _context_graph("vertex-1", "vertex_managed_agent")
bridge = MagicMock()
- bridge.load_binding = AsyncMock(
- return_value={
- "interaction_id": "ix-prev",
- "environment_id": "env-prev",
- }
+ bridge.record_turn = AsyncMock()
+ bridge.augment_prompt = MagicMock(
+ side_effect=lambda prompt: f"prior\n{prompt}"
)
- bridge.append_observable = AsyncMock()
- bridge.bind_provider = AsyncMock()
- bridge.augment_prompt = MagicMock(side_effect=lambda prompt: prompt)
interaction = SimpleNamespace(
id="ix-next",
status="completed",
@@ -218,11 +213,13 @@ async def test_vertex_uses_context_binding_and_redacts_ids_from_output(harness):
harness.assert_envelope(result, success=True)
_, kwargs = stream.call_args
- assert kwargs["previous_interaction_id"] == "ix-prev"
- assert kwargs["environment"] == "env-prev"
+ # Context-bound runs never chain remote interactions: continuity comes
+ # from the stored conversation rendered into the prompt.
+ assert "previous_interaction_id" not in kwargs
+ assert kwargs["environment"] == "remote"
+ assert kwargs["input"] == "prior\ncontinue"
assert result["result"]["interaction_id"] is None
assert result["result"]["environment_id"] is None
- bridge.bind_provider.assert_awaited_once()
- binding = bridge.bind_provider.await_args.args[1]
- assert binding["interaction_id"] == "ix-next"
- assert binding["environment_id"] == "env-next"
+ # The exchange is recorded with the ORIGINAL prompt, never the
+ # augmented one, so a later save cannot nest the transcript.
+ bridge.record_turn.assert_awaited_once_with("continue", "answer")
diff --git a/server/tests/services/agent_context/test_commit_listeners.py b/server/tests/services/agent_context/test_commit_listeners.py
deleted file mode 100644
index 2111a79f..00000000
--- a/server/tests/services/agent_context/test_commit_listeners.py
+++ /dev/null
@@ -1,231 +0,0 @@
-"""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=_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=wire,
- )
- replay = await store.append_transition(
- ref,
- event_type="message.assistant",
- operation_id="op-replay",
- message_wire=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=_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=_wire("hello"),
- )
-
- assert result.applied is True
diff --git a/server/tests/services/agent_context/test_compaction.py b/server/tests/services/agent_context/test_compaction.py
deleted file mode 100644
index cf6de4b7..00000000
--- a/server/tests/services/agent_context/test_compaction.py
+++ /dev/null
@@ -1,577 +0,0 @@
-from __future__ import annotations
-
-from typing import Any
-
-import pytest
-
-from models.agent_context import AgentContextEvent
-from services.agent_context.compaction import (
- AgentContextCompactionService,
- ContextCompactionCandidate,
- ContextCompactionPolicy,
- get_provider_context_adapter,
- provider_context_request_options,
- select_compaction_boundary,
-)
-from services.llm.protocol import Message, ToolCall, message_to_wire
-
-from .test_store import ( # noqa: F401, F811
- _resolve,
- _wire,
- context_database,
-)
-
-
-def _event(
- sequence: int,
- event_type: str,
- wire: dict[str, Any] | None = None,
-) -> AgentContextEvent:
- return AgentContextEvent(
- sequence=sequence,
- event_type=event_type,
- message_wire=wire,
- operation_id=f"operation-{sequence}",
- provider="openai",
- previous_hash=f"{sequence - 1:064x}",
- payload_hash=f"{sequence:064x}",
- )
-
-
-def test_boundary_requires_complete_tool_transaction_and_keeps_exact_tail():
- assistant = dict(
- message_to_wire(
- Message(
- role="assistant",
- tool_calls=[
- ToolCall(id="a", name="lookup", args={}),
- ToolCall(id="b", name="lookup", args={}),
- ],
- )
- )
- )
- first_tool = dict(
- message_to_wire(
- Message(role="tool", tool_call_id="a", name="lookup")
- )
- )
- second_tool = dict(
- message_to_wire(
- Message(role="tool", tool_call_id="b", name="lookup")
- )
- )
- events = [
- _event(1, "message.assistant", assistant),
- _event(2, "message.tool_result", first_tool),
- _event(3, "message.tool_result", second_tool),
- _event(4, "request.snapshot"),
- _event(5, "message.assistant", _wire("tail")),
- ]
-
- assert (
- select_compaction_boundary(
- events,
- exact_tail_retention_count=2,
- )
- == 3
- )
- assert (
- select_compaction_boundary(
- events[:2],
- exact_tail_retention_count=1,
- )
- is None
- )
-
-
-def test_final_only_response_is_a_valid_compaction_boundary():
- events = [
- _event(1, "message.assistant", _wire("final answer")),
- _event(2, "response.final"),
- _event(3, "request.snapshot"),
- ]
- assert (
- select_compaction_boundary(
- events,
- exact_tail_retention_count=1,
- )
- == 2
- )
-
-
-async def test_pressure_is_idempotent_and_portable_checkpoint_keeps_tail(
- context_database, # noqa: F811
-):
- from services.agent_context import AgentContextStore
-
- store = AgentContextStore(context_database)
- ref = await _resolve(store)
- assistant_tool = _wire("tool request", with_tool=True)
- tool_result = dict(
- message_to_wire(
- Message(
- role="tool",
- content='{"ok":true}',
- tool_call_id="call-1",
- name="lookup",
- )
- )
- )
- transitions = [
- ("message.assistant", assistant_tool),
- ("message.tool_result", tool_result),
- ("message.assistant", _wire("final answer")),
- ("response.final", None),
- ("request.snapshot", None),
- ]
- for index, (event_type, wire) in enumerate(transitions, start=1):
- ref = (
- await store.append_transition(
- ref,
- event_type=event_type,
- operation_id=f"transition-{index}",
- message_wire=wire,
- provider="gemini",
- )
- ).ref
-
- async def portable_compactor(_wires, _policy):
- return ContextCompactionCandidate(
- strategy="portable_structured",
- replay_payload={
- "messages": [
- dict(
- message_to_wire(
- Message(
- role="user",
- content=(
- "Portable checkpoint: tool completed and "
- "the final answer was delivered."
- ),
- )
- )
- )
- ]
- },
- active_token_count=20,
- lifetime_usage={"input_tokens": 100, "output_tokens": 20},
- )
-
- result = await AgentContextCompactionService(
- store
- ).update_pressure_and_compact(
- ref,
- operation_id="execution-1:context",
- provider="gemini",
- model="gemini-2.5-pro",
- policy=ContextCompactionPolicy(
- mode="portable",
- trigger_ratio=0.8,
- context_window_override=1024,
- exact_tail_retention_count=1,
- ),
- active_input_tokens=0,
- output_headroom=200,
- rendered_request={"messages": ["x" * 3_000]},
- portable_compactor=portable_compactor,
- )
-
- assert result.compacted is True
- assert result.checkpoint is not None
- assert result.checkpoint.covers_through_sequence == 4
- assert result.pressure_tokens == 220
- state = await store.load_active(result.ref)
- assert [event.sequence for event in state.tail] == [5]
- assert state.active_token_count == 220
-
- same_ref = await store.record_active_pressure(
- result.ref,
- operation_id="same-pressure-operation",
- active_token_count=333,
- )
- duplicate = await store.record_active_pressure(
- same_ref,
- operation_id="same-pressure-operation",
- active_token_count=999,
- )
- assert duplicate == same_ref
- assert (await store.load_active(duplicate)).active_token_count == 333
-
-
-async def test_openai_native_candidate_preserves_compacted_output_unchanged():
- wire = _wire("continued answer")
- wire["provider_state"] = {
- "provider": "openai",
- "payload": {
- "api": "responses",
- "output": [
- {"type": "message", "role": "user", "content": []},
- {
- "id": "cmp_1",
- "type": "compaction",
- "encrypted_content": "opaque",
- },
- {
- "id": "msg_2",
- "type": "message",
- "role": "assistant",
- "content": [],
- },
- ],
- },
- }
- adapter = get_provider_context_adapter("openai")
- candidate = await adapter.compact(
- [_event(1, "message.assistant", wire)],
- ContextCompactionPolicy(mode="native"),
- )
-
- assert candidate is not None
- output = candidate.replay_payload["messages"][0]["provider_state"][
- "payload"
- ]["output"]
- assert output == wire["provider_state"]["payload"]["output"][1:]
- assert output[0]["encrypted_content"] == "opaque"
-
-
-async def test_native_checkpoint_stops_at_marker_and_keeps_later_events_exact(
- context_database, # noqa: F811
-):
- from services.agent_context import AgentContextStore
-
- store = AgentContextStore(context_database)
- ref = await _resolve(store)
- marker_wire = _wire("call the tool", with_tool=True)
- marker_wire["provider_state"] = {
- "provider": "openai",
- "payload": {
- "api": "responses",
- "output": [
- {
- "id": "cmp_1",
- "type": "compaction",
- "encrypted_content": "opaque",
- },
- {
- "id": "call_1",
- "type": "function_call",
- "name": "lookup",
- "arguments": '{"query":"call the tool"}',
- },
- ],
- },
- }
- tool_wire = dict(
- message_to_wire(
- Message(
- role="tool",
- content='{"ok":true}',
- tool_call_id="call-1",
- name="lookup",
- )
- )
- )
- transitions = [
- ("message.assistant", marker_wire),
- ("message.tool_result", tool_wire),
- ("message.assistant", _wire("final after tool")),
- ("response.final", None),
- ]
- for index, (event_type, wire) in enumerate(transitions, start=1):
- ref = (
- await store.append_transition(
- ref,
- event_type=event_type,
- operation_id=f"native-boundary-{index}",
- message_wire=wire,
- provider="openai",
- )
- ).ref
-
- result = await AgentContextCompactionService(
- store
- ).update_pressure_and_compact(
- ref,
- operation_id="native-boundary-compaction",
- provider="openai",
- model="gpt-5.6",
- policy=ContextCompactionPolicy(
- mode="native",
- trigger_ratio=0.8,
- context_window_override=1024,
- exact_tail_retention_count=1,
- ),
- active_input_tokens=900,
- output_headroom=100,
- )
-
- assert result.compacted is True
- assert result.checkpoint is not None
- assert result.checkpoint.covers_through_sequence == 1
- state = await store.load_active(result.ref)
- assert state.ref == result.ref
- assert [event.sequence for event in state.tail] == [2, 3, 4]
- assert [event.message_wire for event in state.tail] == [
- tool_wire,
- _wire("final after tool"),
- None,
- ]
-
-
-async def test_compaction_returns_authoritative_ref_after_concurrent_append(
- context_database, # noqa: F811
-):
- from services.agent_context import AgentContextStore
-
- store = AgentContextStore(context_database)
- ref = await _resolve(store)
- for index in range(1, 4):
- ref = (
- await store.append_transition(
- ref,
- event_type="message.assistant",
- operation_id=f"authoritative-ref-{index}",
- message_wire=_wire(f"message-{index}"),
- provider="gemini",
- )
- ).ref
-
- async def compact_with_concurrent_append(_wires, _policy):
- await store.append_transition(
- ref,
- event_type="message.assistant",
- operation_id="authoritative-ref-concurrent",
- message_wire=_wire("concurrent tail"),
- provider="gemini",
- )
- return ContextCompactionCandidate(
- strategy="portable_structured",
- replay_payload={"messages": [_wire("summary")]},
- active_token_count=10,
- )
-
- result = await AgentContextCompactionService(
- store
- ).update_pressure_and_compact(
- ref,
- operation_id="authoritative-ref-compaction",
- provider="gemini",
- model="gemini-2.5-pro",
- policy=ContextCompactionPolicy(
- mode="portable",
- trigger_ratio=0.8,
- context_window_override=1024,
- exact_tail_retention_count=1,
- ),
- active_input_tokens=900,
- output_headroom=100,
- portable_compactor=compact_with_concurrent_append,
- )
-
- state = await store.load_active(result.ref)
- assert result.compacted is True
- assert result.ref == state.ref
- assert [event.sequence for event in state.tail] == [3, 4]
-
-
-def test_native_request_options_are_capability_driven():
- openai = provider_context_request_options(
- provider="openai",
- model="gpt-5.6",
- policy=ContextCompactionPolicy(
- mode="auto",
- trigger_ratio=0.8,
- context_window_override=100_000,
- ),
- )
- anthropic = provider_context_request_options(
- provider="anthropic",
- model="claude-sonnet-4-6",
- policy=ContextCompactionPolicy(
- mode="native",
- trigger_ratio=0.6,
- context_window_override=200_000,
- ),
- )
- compatible = provider_context_request_options(
- provider="openrouter",
- model="openai/gpt-5.6",
- policy=ContextCompactionPolicy(mode="auto"),
- )
-
- assert openai == {
- "type": "compaction",
- "compact_threshold": 80_000,
- "pause_after_compaction": False,
- "strategy": "openai_responses_compaction",
- }
- assert anthropic == {
- "type": "compaction",
- "compact_threshold": 120_000,
- "pause_after_compaction": True,
- "strategy": "anthropic_compact_20260112",
- }
- assert compatible is None
-
-
-class _ContextUnifier:
- def __init__(self, responses):
- self.responses = list(responses)
- self.calls: list[dict[str, Any]] = []
-
- async def chat(self, **kwargs):
- from services.llm.protocol import LLMResponse, Usage
-
- self.calls.append(kwargs)
- content = self.responses.pop(0)
- return LLMResponse(
- content=content,
- usage=Usage(
- input_tokens=20,
- output_tokens=5,
- total_tokens=25,
- ),
- )
-
-
- "method_name",
- ["execute_agent", "execute_chat_agent"],
-)
-async def test_ai_service_wires_context_sink_for_both_native_paths(
- context_database, # noqa: F811
- method_name,
-):
- from services.agent_context import AgentContextStore
- from services.ai import AIService
-
- unifier = _ContextUnifier(["context-backed answer"])
- service = AIService(
- auth_service=object(),
- database=context_database,
- cache=None,
- settings=object(),
- chat_unifier=unifier,
- )
- descriptor = {
- "kind": "context",
- "workflow_id": f"workflow-{method_name}",
- "context_node_id": f"context-{method_name}",
- "generation": 1,
- "execution_id": "execution-1",
- "session_id": "chat-1",
- "delegated_task_id": None,
- "policy": {"compaction_mode": "disabled"},
- }
- result = await getattr(service, method_name)(
- node_id="agent-1",
- parameters={
- "provider": "openai",
- "model": "gpt-4o-mini",
- "api_key": "secret",
- "prompt": "exact user prompt",
- "system_message": "exact system prompt",
- },
- memory_data=descriptor,
- workflow_id=descriptor["workflow_id"],
- context={
- "execution_id": "execution-1",
- "workflow_id": descriptor["workflow_id"],
- },
- database=context_database,
- )
-
- assert result["success"] is True, result
- assert result["result"]["context"]["thread_id"] == "session:chat-1"
- assert "memory" not in result["result"]
- assert [message.role for message in unifier.calls[0]["messages"]] == [
- "system",
- "user",
- ]
-
- store = AgentContextStore(context_database)
- ref = await store.resolve_thread(
- workflow_id=descriptor["workflow_id"],
- context_node_id=descriptor["context_node_id"],
- generation=1,
- session_id="chat-1",
- )
- journal, _ = await store.load_journal_page(ref)
- assert [event.event_type for event in journal] == [
- "request.snapshot",
- "message.assistant",
- "response.final",
- ]
- assert all(
- "exact user prompt"
- not in event.model_dump_json()
- for event in journal
- if event.event_type != "message.assistant"
- )
-
-
-async def test_session_thread_reconstructs_exact_prior_turn_on_next_run(
- context_database, # noqa: F811
-):
- from services.ai import AIService
-
- unifier = _ContextUnifier(["first answer", "second answer"])
- service = AIService(
- auth_service=object(),
- database=context_database,
- cache=None,
- settings=object(),
- chat_unifier=unifier,
- )
- base_descriptor = {
- "kind": "context",
- "workflow_id": "workflow-continuity",
- "context_node_id": "context-continuity",
- "generation": 1,
- "session_id": "persistent-chat",
- "delegated_task_id": None,
- "policy": {"compaction_mode": "disabled"},
- }
- for execution_id, prompt in (
- ("execution-1", "first prompt"),
- ("execution-2", "second prompt"),
- ):
- descriptor = {
- **base_descriptor,
- "execution_id": execution_id,
- }
- result = await service.execute_chat_agent(
- node_id="agent-1",
- parameters={
- "provider": "openai",
- "model": "gpt-4o-mini",
- "api_key": "secret",
- "prompt": prompt,
- "system_message": "stable system",
- },
- memory_data=descriptor,
- workflow_id=descriptor["workflow_id"],
- context={"execution_id": execution_id},
- database=context_database,
- )
- assert result["success"] is True, result
-
- second_messages = unifier.calls[1]["messages"]
- assert [message.role for message in second_messages] == [
- "system",
- "user",
- "assistant",
- "user",
- ]
- assert [message.content for message in second_messages] == [
- "stable system",
- "first prompt",
- "first answer",
- "second prompt",
- ]
diff --git a/server/tests/services/agent_context/test_conversation.py b/server/tests/services/agent_context/test_conversation.py
new file mode 100644
index 00000000..58806a5a
--- /dev/null
+++ b/server/tests/services/agent_context/test_conversation.py
@@ -0,0 +1,303 @@
+"""Contract for the plain conversation store.
+
+One ``agent_conversations`` row per ``(workflow_id, generation, agent_node_id)``.
+These tests lock the properties every writer relies on:
+
+* load returns exactly what save committed, per key, isolated across keys
+* save is an upsert — the whole message list replaces the stored one
+* a save notifies listeners only after the durable commit
+* a failing listener can never fail the save
+* clear narrows by generation/agent and reports the deleted row count
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import sys
+import uuid
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from services.agent_context import (
+ clear_conversation,
+ list_conversations,
+ load_conversation,
+ save_conversation,
+)
+from services.agent_context import listeners as listener_module
+from services.llm.protocol import Message, message_to_wire
+
+
+async def conversation_database():
+ # The root conftest stubs core.database for fast plugin tests, so load
+ # the real module privately for transaction coverage.
+ module_name = f"tests._conversation_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".conversation-{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(role: str, content: str) -> dict:
+ return dict(message_to_wire(Message(role=role, content=content)))
+
+
+_KEY = {
+ "workflow_id": "workflow-1",
+ "generation": 2,
+ "agent_node_id": "1:aiAgent:1",
+}
+
+
+async def test_load_returns_exactly_what_save_committed(
+ conversation_database, isolated_listeners
+):
+ messages = [_wire("user", "hello"), _wire("assistant", "hi")]
+ await save_conversation(
+ conversation_database, **_KEY, messages=messages
+ )
+ assert await load_conversation(conversation_database, **_KEY) == messages
+
+
+async def test_missing_key_loads_empty_not_error(conversation_database):
+ assert await load_conversation(conversation_database, **_KEY) == []
+
+
+async def test_save_is_an_upsert_replacing_the_whole_list(
+ conversation_database, isolated_listeners
+):
+ await save_conversation(
+ conversation_database, **_KEY, messages=[_wire("user", "one")]
+ )
+ replacement = [
+ _wire("user", "one"),
+ _wire("assistant", "two"),
+ _wire("user", "three"),
+ ]
+ await save_conversation(
+ conversation_database, **_KEY, messages=replacement
+ )
+ assert await load_conversation(conversation_database, **_KEY) == replacement
+ rows = await list_conversations(
+ conversation_database, workflow_id=_KEY["workflow_id"]
+ )
+ assert len(rows) == 1
+ assert rows[0]["message_count"] == 3
+
+
+async def test_keys_are_isolated_across_generation_and_agent(
+ conversation_database, isolated_listeners
+):
+ await save_conversation(
+ conversation_database, **_KEY, messages=[_wire("user", "gen2")]
+ )
+ await save_conversation(
+ conversation_database,
+ workflow_id="workflow-1",
+ generation=3,
+ agent_node_id=_KEY["agent_node_id"],
+ messages=[_wire("user", "gen3")],
+ )
+ await save_conversation(
+ conversation_database,
+ workflow_id="workflow-1",
+ generation=2,
+ agent_node_id="1:aiAgent:2",
+ messages=[_wire("user", "other agent")],
+ )
+ assert (await load_conversation(conversation_database, **_KEY))[0][
+ "content"
+ ] == "gen2"
+ rows = await list_conversations(
+ conversation_database, workflow_id="workflow-1"
+ )
+ assert len(rows) == 3
+ # Newest generation first.
+ assert rows[0]["generation"] == 3
+
+
+async def test_non_dict_messages_are_dropped_not_saved(
+ conversation_database, isolated_listeners
+):
+ await save_conversation(
+ conversation_database,
+ **_KEY,
+ messages=[_wire("user", "kept"), "not a message", None],
+ )
+ stored = await load_conversation(conversation_database, **_KEY)
+ assert [m["content"] for m in stored] == ["kept"]
+
+
+async def test_save_notifies_after_commit_with_identity_and_count(
+ conversation_database, isolated_listeners
+):
+ observed: list[dict] = []
+
+ async def listener(**kwargs):
+ # The row must already be durable when the listener fires.
+ stored = await load_conversation(conversation_database, **_KEY)
+ kwargs["stored_count"] = len(stored)
+ observed.append(kwargs)
+
+ isolated_listeners.register_conversation_listener(listener)
+ await save_conversation(
+ conversation_database,
+ **_KEY,
+ messages=[_wire("user", "a"), _wire("assistant", "b")],
+ )
+ assert observed == [
+ {
+ "workflow_id": "workflow-1",
+ "generation": 2,
+ "agent_node_id": "1:aiAgent:1",
+ "message_count": 2,
+ "stored_count": 2,
+ }
+ ]
+
+
+async def test_listener_failure_cannot_fail_the_save(
+ conversation_database, isolated_listeners
+):
+ async def broken(**kwargs):
+ raise RuntimeError("listener exploded")
+
+ isolated_listeners.register_conversation_listener(broken)
+ await save_conversation(
+ conversation_database, **_KEY, messages=[_wire("user", "still saved")]
+ )
+ assert len(await load_conversation(conversation_database, **_KEY)) == 1
+
+
+async def test_no_listeners_registered_is_a_no_op(
+ conversation_database, isolated_listeners
+):
+ await save_conversation(
+ conversation_database, **_KEY, messages=[_wire("user", "quiet")]
+ )
+ assert len(await load_conversation(conversation_database, **_KEY)) == 1
+
+
+async def test_concurrent_saves_to_one_key_serialize(
+ conversation_database, isolated_listeners
+):
+ async def writer(n: int):
+ await save_conversation(
+ conversation_database,
+ **_KEY,
+ messages=[_wire("user", f"turn-{n}")],
+ )
+
+ await asyncio.gather(*(writer(n) for n in range(8)))
+ stored = await load_conversation(conversation_database, **_KEY)
+ # Last-writer-wins per whole-list upsert; the row is intact and single.
+ assert len(stored) == 1
+ rows = await list_conversations(
+ conversation_database, workflow_id=_KEY["workflow_id"]
+ )
+ assert len(rows) == 1
+
+
+async def test_clear_narrows_by_generation_and_agent(
+ conversation_database, isolated_listeners
+):
+ for generation in (1, 2):
+ for agent in ("agent-a", "agent-b"):
+ await save_conversation(
+ conversation_database,
+ workflow_id="workflow-1",
+ generation=generation,
+ agent_node_id=agent,
+ messages=[_wire("user", "x")],
+ )
+ cleared = await clear_conversation(
+ conversation_database,
+ workflow_id="workflow-1",
+ generation=1,
+ agent_node_id="agent-a",
+ )
+ assert cleared == 1
+ cleared = await clear_conversation(
+ conversation_database, workflow_id="workflow-1", generation=2
+ )
+ assert cleared == 2
+ cleared = await clear_conversation(
+ conversation_database, workflow_id="workflow-1"
+ )
+ assert cleared == 1
+ assert (
+ await list_conversations(
+ conversation_database, workflow_id="workflow-1"
+ )
+ == []
+ )
+
+
+def test_store_never_imports_the_plugin():
+ """The store must stay importable without ``nodes/``; the plugin
+ registers its broadcaster through the listener registry instead."""
+
+ import inspect
+
+ from services.agent_context import conversation, listeners
+
+ for module in (conversation, listeners):
+ source = inspect.getsource(module)
+ assert "from nodes" not in source
+ assert "import nodes" not in source
diff --git a/server/tests/services/agent_context/test_store.py b/server/tests/services/agent_context/test_store.py
deleted file mode 100644
index 675cc20e..00000000
--- a/server/tests/services/agent_context/test_store.py
+++ /dev/null
@@ -1,1231 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import importlib.util
-import sys
-import uuid
-from pathlib import Path
-from types import SimpleNamespace
-from unittest.mock import AsyncMock
-
-import pytest
-from sqlmodel import select
-
-from models.agent_context import (
- AgentContextBlobRecord,
- AgentContextCheckpointRecord,
- AgentContextEventRecord,
- AgentContextRef,
- AgentContextThreadRecord,
-)
-from nodes.context import AgentContextNode
-from nodes.context import _handlers as context_handlers
-from services.agent_context import (
- AgentContextError,
- AgentContextStore,
- AgentContextTransitionWriter,
- ContextArchivedError,
- StaleEpochError,
- import_generation_zero_handoff,
- reconstruct_transcript,
-)
-from services.llm.protocol import (
- ContentBlock,
- Message,
- ToolCall,
- message_to_wire,
-)
-
-
-async def context_database():
- # Root conftest stubs core.database for fast plugin tests. Load the real
- # module privately for SQLite transaction/restart coverage.
- module_name = f"tests._real_context_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".agent-context-{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 _wire(content: str, *, with_tool: bool = False) -> dict:
- calls = (
- [
- ToolCall(
- id="call-1",
- name="lookup",
- args={"query": content},
- raw_arguments=f'{{"query":"{content}"}}',
- )
- ]
- if with_tool
- else []
- )
- blocks = [ContentBlock(type="text", text=content)]
- if calls:
- blocks.append(ContentBlock(type="tool_call", tool_call=calls[0]))
- return dict(
- message_to_wire(
- Message(
- role="assistant",
- content=content,
- tool_calls=calls,
- blocks=blocks,
- provider_state={
- "openai": {
- "output": [{"type": "reasoning", "id": "rs_1"}]
- }
- },
- )
- )
- )
-
-
-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)
-
-
-async def test_thread_resolution_priority_and_isolation(context_database):
- store = AgentContextStore(context_database)
- execution = await _resolve(store)
- task = await _resolve(
- store,
- delegated_task_id="task-1",
- execution_id="execution-2",
- )
- session = await _resolve(
- store,
- session_id="chat-1",
- delegated_task_id="task-2",
- execution_id="execution-3",
- )
- same_session = await _resolve(
- store,
- session_id="chat-1",
- execution_id="execution-99",
- )
-
- assert execution.thread_id == "execution:execution-1"
- assert task.thread_id == "task:task-1"
- assert session.thread_id == "session:chat-1"
- assert same_session == session
- assert len({execution.thread_id, task.thread_id, session.thread_id}) == 3
- summary = await store.load_thread_summary(task)
- assert summary.ref == task
- assert summary.thread_kind == "task"
-
-
-async def test_generation_zero_legacy_artifact_handoff_is_idempotent(
- context_database,
-):
- store = AgentContextStore(context_database)
- source = await _resolve(
- store,
- generation=0,
- session_id="legacy-session",
- execution_id=None,
- )
- artifact = {
- "format": "legacy_markdown",
- "fidelity": "legacy_partial",
- "content": "# Conversation History\n\nUser: keep this fact",
- }
- artifact_ref = await store.put_blob(artifact)
- source = (
- await store.append_transition(
- source,
- event_type="legacy_partial",
- operation_id="legacy-import-1",
- payload_ref=artifact_ref,
- provider="legacy",
- )
- ).ref
- await store.bind_provider(
- source,
- provider="claude_code",
- binding_type="session_uuid",
- binding={"session_uuid": "session-uuid-1"},
- operation_id="legacy-binding-1",
- )
- target = await _resolve(
- store,
- generation=2,
- session_id="legacy-session",
- execution_id=None,
- )
-
- first = await import_generation_zero_handoff(store, target)
- second = await import_generation_zero_handoff(store, first)
- _, replay = await reconstruct_transcript(store, second)
- bindings = await store.load_provider_bindings(
- second,
- provider="claude_code",
- )
-
- assert len(replay) == 1
- assert "keep this fact" in replay[0]["content"]
- assert (await store.load_active(second)).tail[0].payload_ref == artifact_ref
- assert await store.get_blob(artifact_ref) == artifact
- assert len(bindings) == 1
- assert await store.get_blob(bindings[0].binding_ref) == {
- "session_uuid": "session-uuid-1"
- }
-
- cleared = await store.start_epoch(
- second,
- operation_id="clear-after-legacy-handoff",
- provider="openai",
- )
- cleared = await import_generation_zero_handoff(store, cleared)
- assert (await store.load_active(cleared)).tail == []
- assert await store.load_provider_bindings(
- cleared,
- provider="claude_code",
- ) == []
-
- later_target = await _resolve(
- store,
- generation=3,
- session_id="legacy-session",
- execution_id=None,
- )
- later = await import_generation_zero_handoff(store, later_target)
- _, later_replay = await reconstruct_transcript(store, later)
- assert len(later_replay) == 1
-
-
-async def test_workflow_reset_rotates_only_the_active_generation(
- context_database,
-):
- store = AgentContextStore(context_database)
- migration = await _resolve(store, generation=0)
- current = await _resolve(store, generation=2)
- other = await _resolve(store, generation=3)
-
- result = await AgentContextNode.reset_execution_state(
- node_id=current.context_node_id,
- workflow_id=current.workflow_id,
- execution_id="execution-reset",
- generation=2,
- graph={},
- database=context_database,
- )
- migration_after = (
- await store.list_threads(
- workflow_id=migration.workflow_id,
- context_node_id=migration.context_node_id,
- generation=0,
- )
- )[0].ref
- current_after = (
- await store.list_threads(
- workflow_id=current.workflow_id,
- context_node_id=current.context_node_id,
- generation=2,
- )
- )[0].ref
- other_after = (
- await store.list_threads(
- workflow_id=other.workflow_id,
- context_node_id=other.context_node_id,
- generation=3,
- )
- )[0].ref
-
- assert result["rotated_threads"] == 1
- assert migration_after.epoch == migration.epoch
- assert current_after.epoch == current.epoch + 1
- assert other_after.epoch == other.epoch
-
-
-async def test_workflow_reset_scans_beyond_one_thousand_threads(
- context_database,
- monkeypatch,
-):
- thread_count = 1001
- async with context_database.get_session() as session:
- session.add_all(
- [
- AgentContextThreadRecord(
- workflow_id="workflow-paged-reset",
- context_node_id="context-paged-reset",
- generation=7,
- thread_id=f"session:thread-{index:04d}",
- thread_kind="session",
- )
- for index in range(thread_count)
- ]
- )
- await session.commit()
-
- rotated: list[str] = []
-
- async def rotate(
- self,
- ref,
- *,
- operation_id,
- provider=None,
- handoff_payload_ref=None,
- ):
- del self, operation_id, provider, handoff_payload_ref
- rotated.append(ref.thread_id)
- return ref.model_copy(
- update={
- "epoch": ref.epoch + 1,
- "revision": ref.revision + 1,
- }
- )
-
- monkeypatch.setattr(AgentContextStore, "start_epoch", rotate)
- fence = AsyncMock()
- dispatch = AsyncMock()
- monkeypatch.setattr(
- "services.agent_context.lifecycle."
- "fence_context_provider_resources",
- fence,
- )
- monkeypatch.setattr(
- "nodes.context._events.dispatch_context_epoch_started",
- dispatch,
- )
-
- result = await AgentContextNode.reset_execution_state(
- node_id="context-paged-reset",
- workflow_id="workflow-paged-reset",
- execution_id="execution-paged-reset",
- generation=7,
- graph={},
- database=context_database,
- )
-
- assert result == {
- "reset": True,
- "rotated_threads": thread_count,
- }
- assert len(rotated) == thread_count
- assert len(set(rotated)) == thread_count
- assert fence.await_count == thread_count
- assert dispatch.await_count == thread_count
-
-
-async def test_append_is_exact_ordered_hash_chained_and_idempotent(
- context_database,
-):
- store = AgentContextStore(context_database)
- ref = await _resolve(store)
- first = await store.append_transition(
- ref,
- event_type="assistant",
- operation_id="provider-response-1",
- message_wire=_wire("first", with_tool=True),
- provider="openai",
- )
- duplicate = await store.append_transition(
- ref,
- event_type="assistant",
- operation_id="provider-response-1",
- message_wire=_wire("first", with_tool=True),
- provider="openai",
- )
- with pytest.raises(
- AgentContextError,
- match="context_operation_id_reuse_mismatch",
- ):
- await store.append_transition(
- ref,
- event_type="assistant",
- operation_id="provider-response-1",
- message_wire=_wire(
- "this must not replace the committed event"
- ),
- provider="openai",
- )
- second = await store.append_transition(
- first.ref,
- event_type="tool_result",
- operation_id="tool-result-1",
- message_wire=dict(
- message_to_wire(
- Message(
- role="tool",
- content='{"ok":true}',
- tool_call_id="call-1",
- name="lookup",
- )
- )
- ),
- provider="openai",
- )
-
- state = await store.load_active(second.ref)
- assert [event.sequence for event in state.tail] == [1, 2]
- assert duplicate.applied is False
- assert duplicate.event.payload_hash == first.event.payload_hash
- assert state.tail[0].message_wire == _wire("first", with_tool=True)
- assert state.tail[1].previous_hash == state.tail[0].payload_hash
- assert state.ref.revision == 2
-
-
- ("field", "value", "error_code"),
- [
- (
- "sequence",
- 3,
- "context_event_sequence_integrity_broken",
- ),
- (
- "previous_hash",
- "f" * 64,
- "context_event_chain_integrity_broken",
- ),
- (
- "payload_hash",
- "e" * 64,
- "context_event_hash_integrity_broken",
- ),
- ],
-)
-async def test_load_active_rejects_corrupt_event_chain(
- context_database,
- field,
- value,
- error_code,
-):
- store = AgentContextStore(context_database)
- ref = await _resolve(store)
- first = await store.append_transition(
- ref,
- event_type="message.assistant",
- operation_id="integrity-event-1",
- message_wire=_wire("first"),
- provider="openai",
- )
- second = await store.append_transition(
- first.ref,
- event_type="message.assistant",
- operation_id="integrity-event-2",
- message_wire=_wire("second"),
- provider="openai",
- )
-
- async with context_database.get_session() as session:
- result = await session.execute(
- select(AgentContextEventRecord).where(
- AgentContextEventRecord.operation_id
- == "integrity-event-2"
- )
- )
- event = result.scalar_one()
- setattr(event, field, value)
- await session.commit()
-
- with pytest.raises(AgentContextError, match=error_code):
- await store.load_active(second.ref)
-
-
- ("field", "value", "error_code"),
- [
- (
- "covers_through_sequence",
- 2,
- "active_checkpoint_invariant_broken",
- ),
- (
- "source_hash",
- "f" * 64,
- "checkpoint_source_integrity_broken",
- ),
- ],
-)
-async def test_load_active_rejects_corrupt_checkpoint_source(
- context_database,
- field,
- value,
- error_code,
-):
- store = AgentContextStore(context_database)
- ref = await _resolve(store)
- for index in range(1, 3):
- ref = (
- await store.append_transition(
- ref,
- event_type="message.assistant",
- operation_id=f"checkpoint-integrity-{index}",
- message_wire=_wire(f"message-{index}"),
- provider="openai",
- )
- ).ref
- plan = await store.prepare_compaction(
- ref,
- operation_id="checkpoint-integrity-prepare",
- provider="openai",
- strategy="portable",
- covers_through_sequence=1,
- )
- replay_ref = await store.put_blob({"messages": [_wire("summary")]})
- await store.commit_checkpoint(
- ref,
- attempt_id=plan.attempt_id,
- operation_id="checkpoint-integrity-commit",
- replay_payload_ref=replay_ref,
- active_token_count=10,
- )
-
- async with context_database.get_session() as session:
- result = await session.execute(
- select(AgentContextCheckpointRecord).where(
- AgentContextCheckpointRecord.operation_id
- == "checkpoint-integrity-commit"
- )
- )
- checkpoint = result.scalar_one()
- setattr(checkpoint, field, value)
- await session.commit()
-
- with pytest.raises(AgentContextError, match=error_code):
- await store.load_active(ref)
-
-
-async def test_blob_digest_is_verified_for_direct_and_checkpoint_replay(
- context_database,
-):
- store = AgentContextStore(context_database)
- ref = await _resolve(store)
- first = await store.append_transition(
- ref,
- event_type="message.assistant",
- operation_id="blob-integrity-event-1",
- message_wire=_wire("first"),
- provider="openai",
- )
- second = await store.append_transition(
- first.ref,
- event_type="message.assistant",
- operation_id="blob-integrity-event-2",
- message_wire=_wire("second"),
- provider="openai",
- )
- plan = await store.prepare_compaction(
- second.ref,
- operation_id="blob-integrity-prepare",
- provider="openai",
- strategy="portable",
- covers_through_sequence=1,
- )
- replay_ref = await store.put_blob({"messages": [_wire("summary")]})
- await store.commit_checkpoint(
- second.ref,
- attempt_id=plan.attempt_id,
- operation_id="blob-integrity-commit",
- replay_payload_ref=replay_ref,
- active_token_count=10,
- )
-
- digest = replay_ref.removeprefix("sha256:")
- async with context_database.get_session() as session:
- blob = await session.get(AgentContextBlobRecord, digest)
- assert blob is not None
- blob.json_payload = {"messages": [_wire("tampered")]}
- await session.commit()
-
- with pytest.raises(
- AgentContextError,
- match="context_blob_integrity_broken",
- ):
- await store.get_blob(replay_ref)
- with pytest.raises(
- AgentContextError,
- match="context_blob_integrity_broken",
- ):
- await store.load_active(second.ref)
-
-
-async def test_parallel_appends_serialize_without_losing_events(
- context_database,
-):
- store = AgentContextStore(context_database)
- ref = await _resolve(store)
-
- results = await asyncio.gather(
- *(
- store.append_transition(
- ref,
- event_type="message.assistant",
- operation_id=f"parallel-{index}",
- message_wire=_wire(f"parallel-message-{index}"),
- )
- for index in range(8)
- )
- )
- current = max(results, key=lambda result: result.ref.revision).ref
- state = await store.load_active(current)
- assert [event.sequence for event in state.tail] == list(range(1, 9))
- assert {event.operation_id for event in state.tail} == {
- f"parallel-{index}" for index in range(8)
- }
- for previous, current_event in zip(state.tail, state.tail[1:]):
- assert current_event.previous_hash == previous.payload_hash
-
-
-async def test_epoch_rotation_fences_late_writes_and_keeps_handoff(
- context_database,
-):
- store = AgentContextStore(context_database)
- old_ref = await _resolve(store)
- old_ref = (
- await store.append_transition(
- old_ref,
- event_type="message.assistant",
- operation_id="before-provider-fork",
- message_wire=_wire("old epoch exact message"),
- provider="openai",
- )
- ).ref
- handoff_ref = await store.put_blob(
- {"messages": [_wire("portable exact tail")]}
- )
- new_ref = await store.fork_provider(
- old_ref,
- provider="anthropic",
- operation_id="provider-fork-1",
- portable_handoff_ref=handoff_ref,
- )
-
- assert new_ref.epoch == old_ref.epoch + 1
- current = await store.load_active(new_ref)
- assert [event.event_type for event in current.tail] == [
- "provider_handoff"
- ]
- assert current.tail[0].payload_ref == handoff_ref
- journal, next_cursor = await store.load_journal_page(new_ref)
- assert [event.event_type for event in journal] == [
- "message.assistant",
- "provider_handoff",
- ]
- assert next_cursor is None
- with pytest.raises(StaleEpochError):
- await store.append_transition(
- old_ref,
- event_type="assistant",
- operation_id="late-provider-response",
- message_wire=_wire("late"),
- )
- # Retrying the already-committed rotation is idempotent even with the old
- # reference that it deliberately fenced.
- assert (
- await store.fork_provider(
- old_ref,
- provider="anthropic",
- operation_id="provider-fork-1",
- portable_handoff_ref=handoff_ref,
- )
- ) == new_ref
-
-
-async def test_epoch_rotation_rejects_conflicting_operation_id_reuse(
- context_database,
-):
- store = AgentContextStore(context_database)
- old_ref = await _resolve(store)
- first_handoff = await store.put_blob(
- {"messages": [_wire("first portable handoff")]}
- )
- second_handoff = await store.put_blob(
- {"messages": [_wire("different portable handoff")]}
- )
- await store.fork_provider(
- old_ref,
- provider="anthropic",
- operation_id="provider-fork-conflict",
- portable_handoff_ref=first_handoff,
- )
-
- with pytest.raises(
- AgentContextError,
- match="context_operation_id_reuse_mismatch",
- ):
- await store.fork_provider(
- old_ref,
- provider="openai",
- operation_id="provider-fork-conflict",
- portable_handoff_ref=first_handoff,
- )
- with pytest.raises(
- AgentContextError,
- match="context_operation_id_reuse_mismatch",
- ):
- await store.fork_provider(
- old_ref,
- provider="anthropic",
- operation_id="provider-fork-conflict",
- portable_handoff_ref=second_handoff,
- )
-
-
-async def test_compaction_cas_keeps_concurrent_tail(context_database):
- store = AgentContextStore(context_database)
- ref = await _resolve(store)
- for index in range(1, 4):
- result = await store.append_transition(
- ref,
- event_type="assistant",
- operation_id=f"response-{index}",
- message_wire=_wire(f"message-{index}"),
- provider="openai",
- )
- ref = result.ref
-
- plan = await store.prepare_compaction(
- ref,
- operation_id="compact-prepare-1",
- provider="openai",
- strategy="native",
- covers_through_sequence=2,
- )
- concurrent = await store.append_transition(
- ref,
- event_type="assistant",
- operation_id="response-4",
- message_wire=_wire("message-4"),
- provider="openai",
- )
- replay_ref = await store.put_blob(
- {"provider_output": ["opaque", "native", "items"]}
- )
- checkpoint = await store.commit_checkpoint(
- concurrent.ref,
- attempt_id=plan.attempt_id,
- operation_id="compact-commit-1",
- replay_payload_ref=replay_ref,
- active_token_count=120,
- )
- state = await store.load_active(concurrent.ref.model_copy(
- update={"revision": concurrent.ref.revision + 1}
- ))
-
- assert checkpoint.covers_through_sequence == 2
- assert checkpoint.source_hash == plan.source_hash
- assert [event.sequence for event in state.tail] == [3, 4]
- assert state.checkpoint == checkpoint
- assert state.active_token_count == 120
-
-
-async def test_failed_compaction_preserves_prior_active_state(
- context_database,
-):
- store = AgentContextStore(context_database)
- ref = await _resolve(store)
- for index in range(1, 3):
- ref = (
- await store.append_transition(
- ref,
- event_type="assistant",
- operation_id=f"failure-response-{index}",
- message_wire=_wire(f"failure-{index}"),
- )
- ).ref
- before = await store.load_active(ref)
- plan = await store.prepare_compaction(
- ref,
- operation_id="failed-prepare",
- provider="openai",
- strategy="portable",
- covers_through_sequence=1,
- )
- await store.fail_compaction(
- attempt_id=plan.attempt_id,
- error_code="candidate_did_not_reduce_tokens",
- )
- after = await store.load_active(ref)
- assert after == before
-
-
-async def test_runtime_writer_blobs_payloads_and_reconstructs_portable_replay(
- context_database,
-):
- store = AgentContextStore(context_database)
- writer = AgentContextTransitionWriter(store, await _resolve(store))
- first_wire = _wire("checkpoint-message-1")
- second_wire = _wire("checkpoint-message-2")
- first = await writer.append_transition(
- event_type="message.assistant",
- operation_id="writer-1",
- provider="openai",
- message_wire=first_wire,
- payload={"usage": {"input_tokens": 10}},
- )
- second = await writer.append_transition(
- event_type="message.assistant",
- operation_id="writer-2",
- provider="openai",
- message_wire=second_wire,
- )
- assert writer.ref == second.ref
- assert first.event.payload_ref is not None
- assert await store.get_blob(first.event.payload_ref) == {
- "usage": {"input_tokens": 10}
- }
-
- plan = await store.prepare_compaction(
- writer.ref,
- operation_id="writer-prepare",
- provider="openai",
- strategy="portable",
- covers_through_sequence=1,
- )
- replay_ref = await store.put_blob({"messages": [first_wire]})
- await store.commit_checkpoint(
- writer.ref,
- attempt_id=plan.attempt_id,
- operation_id="writer-commit",
- replay_payload_ref=replay_ref,
- active_token_count=20,
- )
- latest = writer.ref.model_copy(update={"revision": writer.ref.revision + 1})
- reconstructed_ref, wires = await reconstruct_transcript(
- store,
- latest,
- )
- assert reconstructed_ref.revision == latest.revision
- assert wires == [first_wire, second_wire]
-
-
-async def test_reconstruction_uses_latest_exact_request_snapshot(
- context_database,
-):
- store = AgentContextStore(context_database)
- writer = AgentContextTransitionWriter(store, await _resolve(store))
- system = dict(
- message_to_wire(Message(role="system", content="exact system"))
- )
- user = dict(
- message_to_wire(Message(role="user", content="exact user"))
- )
- assistant = _wire("exact assistant")
- await writer.append_transition(
- event_type="request.snapshot",
- operation_id="snapshot-1",
- provider="openai",
- payload={"messages": [system, user], "tools": []},
- )
- await writer.append_transition(
- event_type="message.assistant",
- operation_id="assistant-after-snapshot",
- provider="openai",
- message_wire=assistant,
- )
- # Metadata-only final events must not appear in provider replay.
- await writer.append_transition(
- event_type="response.final",
- operation_id="final-after-snapshot",
- provider="openai",
- payload={"finish_reason": "stop"},
- )
-
- _, wires = await reconstruct_transcript(store, writer.ref)
- assert wires == [system, user, assistant]
-
-
-async def test_provider_binding_is_opaque_and_archived_on_epoch_change(
- context_database,
-):
- store = AgentContextStore(context_database)
- ref = await _resolve(store)
- binding = await store.bind_provider(
- ref,
- provider="claude_code",
- binding_type="session_uuid",
- binding={"uuid": "secret-provider-session"},
- operation_id="bind-1",
- )
-
- assert "secret-provider-session" not in binding.model_dump_json()
- assert await store.get_blob(binding.binding_ref) == {
- "uuid": "secret-provider-session"
- }
- assert await store.load_provider_bindings(ref) == [binding]
- new_ref = await store.start_epoch(
- ref,
- provider="openai",
- operation_id="epoch-after-binding",
- )
- assert await store.load_provider_bindings(new_ref) == []
-
-
-async def test_provider_binding_rejects_conflicting_operation_id_reuse(
- context_database,
-):
- store = AgentContextStore(context_database)
- ref = await _resolve(store)
- binding = await store.bind_provider(
- ref,
- provider="vertex",
- binding_type="interaction_id",
- binding={"interaction_id": "interaction-1"},
- operation_id="binding-conflict",
- )
- duplicate = await store.bind_provider(
- ref,
- provider="vertex",
- binding_type="interaction_id",
- binding={"interaction_id": "interaction-1"},
- operation_id="binding-conflict",
- )
- assert duplicate == binding
-
- conflicting_calls = (
- {
- "provider": "vertex",
- "binding_type": "interaction_id",
- "binding": {"interaction_id": "interaction-2"},
- },
- {
- "provider": "claude_code",
- "binding_type": "session_uuid",
- "binding": {"interaction_id": "interaction-1"},
- },
- {
- "provider": "vertex",
- "binding_type": "interaction_id",
- "binding": {"interaction_id": "interaction-1"},
- "fidelity": "observable_only",
- },
- )
- for call in conflicting_calls:
- with pytest.raises(
- AgentContextError,
- match="context_operation_id_reuse_mismatch",
- ):
- await store.bind_provider(
- ref,
- operation_id="binding-conflict",
- **call,
- )
-
-
-async def test_archive_fences_writes_and_purge_removes_state(context_database):
- store = AgentContextStore(context_database)
- retained_blob_ref = await store.put_blob({"pending_reference": True})
- ref = await _resolve(store)
- ref = (
- await store.append_transition(
- ref,
- event_type="assistant",
- operation_id="before-archive",
- message_wire=_wire("preserved until purge"),
- )
- ).ref
- archived = await store.archive(ref, operation_id="archive-1")
- with pytest.raises((StaleEpochError, ContextArchivedError)):
- await store.append_transition(
- ref,
- event_type="assistant",
- operation_id="after-archive",
- message_wire=_wire("must not commit"),
- )
-
- # Archive is recoverable and idempotent; purge is the separate,
- # explicitly destructive operation.
- assert (
- await store.archive(ref, operation_id="archive-1")
- ) == archived
- assert await store.purge(
- workflow_id=ref.workflow_id,
- context_node_id=ref.context_node_id,
- generation=ref.generation,
- ) == 1
- assert await store.get_blob(retained_blob_ref) == {
- "pending_reference": True
- }
- fresh = await _resolve(store)
- assert fresh.revision == 0
- assert (await store.load_active(fresh)).tail == []
-
-
-async def test_archive_context_defaults_to_every_generation(context_database):
- store = AgentContextStore(context_database)
- generation_two = await _resolve(store, execution_id="execution-g2")
- generation_three = await _resolve(
- store,
- generation=3,
- execution_id="execution-g3",
- )
-
- archived = await store.archive_context(
- workflow_id="workflow-1",
- context_node_id="workflow-1:context:1",
- operation_id="archive-all-generations",
- )
- assert {
- (ref.generation, ref.thread_id) for ref in archived
- } == {
- (2, generation_two.thread_id),
- (3, generation_three.thread_id),
- }
- for ref in archived:
- with pytest.raises(ContextArchivedError):
- await store.load_active(ref)
-
-
-async def test_authorized_handlers_paginate_raw_data_but_redact_exports(
- context_database,
- monkeypatch,
-):
- await context_database.save_workflow(
- "workflow-1",
- "Context test",
- "Context_test",
- {
- "owner_id": "authenticated-user",
- "nodes": [
- {
- "id": "workflow-1:context:1",
- "type": "context",
- "data": {"label": "Context"},
- }
- ],
- "edges": [],
- },
- )
- monkeypatch.setattr(
- context_handlers,
- "_database",
- lambda: context_database,
- )
- socket = SimpleNamespace(
- state=SimpleNamespace(user_id="authenticated-user"),
- scope={"path": "/ws/status"},
- )
- store = AgentContextStore(context_database)
- ref = await _resolve(store)
- secret_payload = {"resolved_system_instruction": "classified prompt"}
- first = await AgentContextTransitionWriter(
- store,
- ref,
- ).append_transition(
- event_type="request.snapshot",
- operation_id="handler-event-1",
- provider="openai",
- payload=secret_payload,
- )
- await store.append_transition(
- first.ref,
- event_type="message.assistant",
- operation_id="handler-event-2",
- provider="openai",
- message_wire=_wire("classified response"),
- )
-
- page = await context_handlers.handle_get_agent_context(
- {
- "workflow_id": "workflow-1",
- "context_node_id": "workflow-1:context:1",
- "view": "journal",
- "limit": 1,
- },
- socket,
- )
- assert page["success"] is True
- assert page["context"]["events"][0]["payload"] == secret_payload
- assert page["context"]["next_cursor"]
- second_page = await context_handlers.handle_get_agent_context(
- {
- "workflow_id": "workflow-1",
- "context_node_id": "workflow-1:context:1",
- "view": "journal",
- "limit": 1,
- "cursor": page["context"]["next_cursor"],
- },
- socket,
- )
- assert [
- event["sequence"] for event in second_page["context"]["events"]
- ] == [2]
-
- exported = await context_handlers.handle_export_agent_context(
- {
- "workflow_id": "workflow-1",
- "context_node_id": "workflow-1:context:1",
- },
- socket,
- )
- assert exported["success"] is True
- assert '"redacted": true' in exported["content"]
- assert "classified prompt" not in exported["content"]
- assert "classified response" not in exported["content"]
- assert "message_wire" not in exported["content"]
- assert "payload_ref" not in exported["content"]
-
- unauthorized = await context_handlers.handle_get_agent_context(
- {
- "workflow_id": "workflow-1",
- "context_node_id": "another-context",
- },
- socket,
- )
- assert unauthorized["success"] is False
- wrong_owner = await context_handlers.handle_get_agent_context(
- {
- "workflow_id": "workflow-1",
- "context_node_id": "workflow-1:context:1",
- },
- SimpleNamespace(
- state=SimpleNamespace(user_id="another-user"),
- scope={"path": "/ws/status"},
- ),
- )
- assert wrong_owner["success"] is False
- internal = await context_handlers.handle_get_agent_context(
- {
- "workflow_id": "workflow-1",
- "context_node_id": "workflow-1:context:1",
- },
- SimpleNamespace(scope={"path": "/ws/internal"}),
- )
- assert internal["success"] is False
-
-
-async def test_clear_and_fork_handlers_rotate_epoch_with_metadata_events(
- context_database,
- monkeypatch,
-):
- await context_database.save_workflow(
- "workflow-1",
- "Context lifecycle",
- "Context_lifecycle",
- {
- "nodes": [
- {
- "id": "workflow-1:context:1",
- "type": "context",
- "data": {},
- }
- ],
- "edges": [],
- },
- )
- monkeypatch.setattr(
- context_handlers,
- "_database",
- lambda: context_database,
- )
- dispatch = AsyncMock()
- monkeypatch.setattr(
- context_handlers,
- "dispatch_context_epoch_started",
- dispatch,
- )
- socket = SimpleNamespace(scope={"path": "/ws/status"})
- store = AgentContextStore(context_database)
- ref = await _resolve(store)
- ref = (
- await store.append_transition(
- ref,
- event_type="message.assistant",
- operation_id="lifecycle-event",
- provider="openai",
- message_wire=_wire("before clear"),
- )
- ).ref
-
- cleared = await context_handlers.handle_clear_agent_context(
- {
- "workflow_id": "workflow-1",
- "context_node_id": "workflow-1:context:1",
- "request_id": "clear-request-1",
- },
- socket,
- )
- assert cleared["success"] is True
- assert cleared["context"]["epoch"] == ref.epoch + 1
- current_ref = ref.model_copy(
- update={
- "epoch": cleared["context"]["epoch"],
- "revision": cleared["context"]["revision"],
- }
- )
- assert (await store.load_active(current_ref)).tail == []
-
- forked = await context_handlers.handle_fork_agent_context(
- {
- "workflow_id": "workflow-1",
- "context_node_id": "workflow-1:context:1",
- "provider": "anthropic",
- "request_id": "fork-request-1",
- },
- socket,
- )
- assert forked["success"] is True
- assert forked["context"]["epoch"] == current_ref.epoch + 1
- latest = current_ref.model_copy(
- update={
- "epoch": forked["context"]["epoch"],
- "revision": forked["context"]["revision"],
- }
- )
- state = await store.load_active(latest)
- assert [event.event_type for event in state.tail] == [
- "provider_handoff"
- ]
- assert dispatch.await_count == 2
- assert dispatch.await_args_list[0].kwargs["reason"] == "clear"
- assert dispatch.await_args_list[1].kwargs["reason"] == "fork"
diff --git a/server/tests/services/cli_agent/test_context_bridge.py b/server/tests/services/cli_agent/test_context_bridge.py
new file mode 100644
index 00000000..2a088d0c
--- /dev/null
+++ b/server/tests/services/cli_agent/test_context_bridge.py
@@ -0,0 +1,196 @@
+"""Contract for the specialized-provider conversation bridge.
+
+Specialized providers (claude_code, codex, rlm, vertex) do not run through
+the native agent loop, so the bridge gives them the same continuity
+contract: load the stored conversation at run start, render it into the
+prompt, save the exchange back per turn.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+import services.agent_context as agent_context
+from services.cli_agent.context_bridge import (
+ SpecializedAgentContextBridge,
+ is_context,
+)
+from services.llm.protocol import Message, message_to_wire
+
+
+def _wire(role: str, content: str) -> dict:
+ return dict(message_to_wire(Message(role=role, content=content)))
+
+
+_DESCRIPTOR = {
+ "kind": "context",
+ "node_id": "wf:context:1",
+ "context_node_id": "wf:context:1",
+ "workflow_id": "workflow-1",
+ "generation": 2,
+ "execution_id": "execution-1",
+}
+
+
+def test_is_context_requires_the_kind_discriminator():
+ assert is_context(_DESCRIPTOR)
+ assert not is_context({"node_id": "memory-1"})
+ assert not is_context(None)
+ assert not is_context("context")
+
+
+async def test_resolve_rejects_generation_zero():
+ with pytest.raises(ValueError, match="admitted generation"):
+ await SpecializedAgentContextBridge.resolve(
+ object(),
+ {**_DESCRIPTOR, "generation": 0},
+ provider="claude_code",
+ agent_node_id="agent-1",
+ )
+
+
+async def test_resolve_rejects_non_context_descriptor():
+ with pytest.raises(ValueError, match="context descriptor"):
+ await SpecializedAgentContextBridge.resolve(
+ object(),
+ {"node_id": "memory-1"},
+ provider="claude_code",
+ agent_node_id="agent-1",
+ )
+
+
+async def test_resolve_loads_the_stored_conversation(monkeypatch):
+ stored = [_wire("user", "first prompt"), _wire("assistant", "first answer")]
+ observed_keys: list[dict] = []
+
+ async def fake_load(database: Any, **key: Any) -> list:
+ observed_keys.append(key)
+ return list(stored)
+
+ monkeypatch.setattr(agent_context, "load_conversation", fake_load)
+ bridge = await SpecializedAgentContextBridge.resolve(
+ object(),
+ _DESCRIPTOR,
+ provider="claude_code",
+ agent_node_id="agent-1",
+ )
+ assert observed_keys == [
+ {
+ "workflow_id": "workflow-1",
+ "generation": 2,
+ "agent_node_id": "agent-1",
+ }
+ ]
+ assert list(bridge.history) == stored
+
+
+async def test_resolve_load_failure_is_loud(monkeypatch):
+ async def broken_load(database: Any, **key: Any) -> list:
+ raise RuntimeError("db locked")
+
+ monkeypatch.setattr(agent_context, "load_conversation", broken_load)
+ with pytest.raises(ValueError, match="Conversation load failed"):
+ await SpecializedAgentContextBridge.resolve(
+ object(),
+ _DESCRIPTOR,
+ provider="claude_code",
+ agent_node_id="agent-1",
+ )
+
+
+def test_pool_key_is_the_conversation_key():
+ bridge = SpecializedAgentContextBridge(
+ database=object(),
+ workflow_id="workflow-1",
+ generation=3,
+ agent_node_id="agent-1",
+ provider="claude_code",
+ )
+ assert bridge.pool_key == ("workflow-1", "agent-1", 3)
+
+
+def test_augment_prompt_renders_stored_history():
+ bridge = SpecializedAgentContextBridge(
+ database=object(),
+ workflow_id="workflow-1",
+ generation=2,
+ agent_node_id="agent-1",
+ provider="claude_code",
+ history=(
+ _wire("user", "first prompt"),
+ _wire("assistant", "first answer"),
+ ),
+ )
+ rendered = bridge.augment_prompt("continue")
+ assert "USER: first prompt" in rendered
+ assert "ASSISTANT: first answer" in rendered
+ assert rendered.strip().endswith("continue")
+ # Prior context precedes the current request.
+ assert rendered.index("first answer") < rendered.index("## Current request")
+
+
+def test_augment_prompt_without_history_is_the_identity():
+ bridge = SpecializedAgentContextBridge(
+ database=object(),
+ workflow_id="workflow-1",
+ generation=2,
+ agent_node_id="agent-1",
+ provider="claude_code",
+ )
+ assert bridge.augment_prompt("continue") == "continue"
+
+
+async def test_record_turn_appends_and_saves_the_whole_conversation(
+ monkeypatch,
+):
+ saved: list[dict] = []
+
+ async def fake_save(database: Any, **kwargs: Any) -> None:
+ saved.append(kwargs)
+
+ monkeypatch.setattr(agent_context, "save_conversation", fake_save)
+ bridge = SpecializedAgentContextBridge(
+ database=object(),
+ workflow_id="workflow-1",
+ generation=2,
+ agent_node_id="agent-1",
+ provider="claude_code",
+ history=(_wire("user", "first"), _wire("assistant", "one")),
+ )
+ await bridge.record_turn("second", "two")
+ assert len(saved) == 1
+ assert saved[0]["workflow_id"] == "workflow-1"
+ assert saved[0]["generation"] == 2
+ assert saved[0]["agent_node_id"] == "agent-1"
+ contents = [m["content"] for m in saved[0]["messages"]]
+ assert contents == ["first", "one", "second", "two"]
+ # The in-memory history advances so a second turn does not lose this one.
+ assert [m["content"] for m in bridge.history] == contents
+
+
+async def test_record_turn_without_response_records_the_prompt_only(
+ monkeypatch,
+):
+ saved: list[dict] = []
+
+ async def fake_save(database: Any, **kwargs: Any) -> None:
+ saved.append(kwargs)
+
+ monkeypatch.setattr(agent_context, "save_conversation", fake_save)
+ bridge = SpecializedAgentContextBridge(
+ database=object(),
+ workflow_id="workflow-1",
+ generation=2,
+ agent_node_id="agent-1",
+ provider="claude_code",
+ )
+ await bridge.record_turn("orphan prompt", None)
+ assert [m["role"] for m in saved[0]["messages"]] == ["user"]
diff --git a/server/tests/services/cli_agent/test_context_v2_bridge.py b/server/tests/services/cli_agent/test_context_v2_bridge.py
deleted file mode 100644
index 8e90d92f..00000000
--- a/server/tests/services/cli_agent/test_context_v2_bridge.py
+++ /dev/null
@@ -1,458 +0,0 @@
-"""Context V2 contracts for specialized CLI providers."""
-
-from __future__ import annotations
-
-import asyncio
-from pathlib import Path
-from types import SimpleNamespace
-from unittest.mock import AsyncMock
-
-import pytest
-
-from models.agent_context import (
- AgentContextActiveState,
- AgentContextEvent,
- AgentContextRef,
-)
-from nodes.agent.claude_code_agent._pool import (
- ClaudeSessionPool,
- PooledClaudeSession,
-)
-from services.agent_context import reconstruct_transcript
-from services.cli_agent.context_bridge import SpecializedAgentContextBridge
-from services.cli_agent.protocol import CanonicalUsage
-from services.cli_agent.service import AICliService
-from services.cli_agent.types import ClaudeTaskSpec, CodexTaskSpec
-
-
-def _bridge(*, fidelity: str, resumable: bool):
- ref = AgentContextRef(
- workflow_id="wf",
- context_node_id="wf:context:1",
- generation=2,
- thread_id="session:chat-1",
- epoch=3,
- revision=4,
- )
- writer = SimpleNamespace(
- ref=ref,
- append_transition=AsyncMock(),
- )
- store = SimpleNamespace()
- return SpecializedAgentContextBridge(
- store=store,
- writer=writer,
- provider="codex",
- operation_prefix="op",
- fidelity=fidelity,
- resumable=resumable,
- )
-
-
-async def test_specialized_bridge_rejects_generation_zero():
- with pytest.raises(ValueError, match="admitted generation"):
- await SpecializedAgentContextBridge.resolve(
- object(),
- {
- "kind": "context",
- "workflow_id": "wf",
- "context_node_id": "ctx",
- "generation": 0,
- "execution_id": "run-1",
- },
- provider="codex",
- fidelity="observable_only",
- resumable=False,
- )
-
-
-async def test_observable_only_event_is_explicitly_non_resumable_and_exact():
- bridge = _bridge(fidelity="observable_only", resumable=False)
- long_text = "x" * 10_000
-
- await bridge.capture_provider_event(
- {"type": "assistant", "content": long_text}
- )
-
- call = bridge.writer.append_transition.await_args.kwargs
- assert call["event_type"] == "provider.stream"
- assert call["payload"]["fidelity"] == "observable_only"
- assert call["payload"]["observable_only"] is True
- assert call["payload"]["non_resumable"] is True
- assert call["payload"]["event"]["content"] == long_text
-
-
-async def test_claude_pool_key_contains_context_thread_and_epoch():
- bridge = _bridge(fidelity="provider_bound", resumable=True)
- assert bridge.pool_key == (
- "wf:context:1",
- "session:chat-1",
- 3,
- )
-
-
-async def test_provider_change_forks_epoch_with_portable_handoff(monkeypatch):
- from services.cli_agent import context_bridge as bridge_module
-
- old_ref = AgentContextRef(
- workflow_id="wf",
- context_node_id="ctx",
- generation=4,
- thread_id="execution:run-1",
- epoch=1,
- revision=2,
- )
- new_ref = old_ref.model_copy(update={"epoch": 2, "revision": 3})
- event = AgentContextEvent(
- sequence=1,
- event_type="provider.result",
- operation_id="old-result",
- provider="codex",
- previous_hash="0" * 64,
- payload_hash="1" * 64,
- payload_ref="sha256:old-result",
- )
- store = SimpleNamespace(
- resolve_thread=AsyncMock(return_value=old_ref),
- load_thread_summary=AsyncMock(
- return_value=SimpleNamespace(ref=old_ref, provider="codex")
- ),
- load_active=AsyncMock(
- return_value=AgentContextActiveState(
- ref=old_ref,
- tail=[event],
- )
- ),
- get_blob=AsyncMock(
- return_value={
- "fidelity": "observable_only",
- "event": {"response": "old provider answer"},
- }
- ),
- put_blob=AsyncMock(return_value="sha256:handoff"),
- fork_provider=AsyncMock(return_value=new_ref),
- )
- monkeypatch.setattr(
- bridge_module,
- "AgentContextStore",
- lambda database: store,
- )
- import_handoff = AsyncMock(return_value=old_ref)
- monkeypatch.setattr(
- bridge_module,
- "import_generation_zero_handoff",
- import_handoff,
- )
-
- bridge = await SpecializedAgentContextBridge.resolve(
- object(),
- {
- "kind": "context",
- "workflow_id": "wf",
- "context_node_id": "ctx",
- "generation": 4,
- "execution_id": "run-1",
- },
- provider="rlm",
- fidelity="observable_only",
- resumable=False,
- )
-
- assert bridge.ref == new_ref
- import_handoff.assert_awaited_once_with(store, old_ref)
- kwargs = store.fork_provider.await_args.kwargs
- assert kwargs["provider"] == "rlm"
- assert kwargs["portable_handoff_ref"] == "sha256:handoff"
- handoff = store.put_blob.await_args.args[0]
- assert handoff["from_provider"] == "codex"
- assert handoff["to_provider"] == "rlm"
- assert handoff["messages"]
- assert "old provider answer" in handoff["messages"][0]["content"]
- replayed = bridge.augment_prompt("new request")
- assert "old provider answer" in replayed
- assert replayed.endswith("new request")
-
- handoff_event = AgentContextEvent(
- sequence=2,
- event_type="provider_handoff",
- operation_id="fork:handoff",
- provider="rlm",
- previous_hash="1" * 64,
- payload_hash="2" * 64,
- payload_ref="sha256:handoff",
- )
- store.load_active.return_value = AgentContextActiveState(
- ref=new_ref,
- tail=[handoff_event],
- )
- store.get_blob.return_value = handoff
- _, reconstructed = await reconstruct_transcript(
- store,
- new_ref,
- )
- assert "old provider answer" in reconstructed[0]["content"]
-
-
-async def test_pending_provider_handoff_is_recovered_before_request(
- monkeypatch,
-):
- from services.cli_agent import context_bridge as bridge_module
-
- ref = AgentContextRef(
- workflow_id="wf",
- context_node_id="ctx",
- generation=4,
- thread_id="execution:run-1",
- epoch=2,
- revision=3,
- )
- handoff = AgentContextEvent(
- sequence=4,
- event_type="provider_handoff",
- operation_id="fork:handoff",
- provider="rlm",
- previous_hash="0" * 64,
- payload_hash="1" * 64,
- payload_ref="sha256:handoff",
- )
- request = AgentContextEvent(
- sequence=5,
- event_type="provider.request",
- operation_id="retry:request",
- provider="rlm",
- previous_hash="1" * 64,
- payload_hash="2" * 64,
- )
- message = {
- "version": 2,
- "role": "assistant",
- "content": "committed prior answer",
- "blocks": [{"type": "text", "text": "committed prior answer"}],
- "tool_calls": [],
- "tool_call_id": None,
- "name": None,
- "provider_state": {},
- }
- store = SimpleNamespace(
- resolve_thread=AsyncMock(return_value=ref),
- load_thread_summary=AsyncMock(
- return_value=SimpleNamespace(ref=ref, provider="rlm")
- ),
- load_active=AsyncMock(
- return_value=AgentContextActiveState(
- ref=ref,
- tail=[handoff, request],
- )
- ),
- get_blob=AsyncMock(
- return_value={"messages": [message]}
- ),
- )
- monkeypatch.setattr(
- bridge_module,
- "AgentContextStore",
- lambda database: store,
- )
- monkeypatch.setattr(
- bridge_module,
- "import_generation_zero_handoff",
- AsyncMock(return_value=ref),
- )
-
- bridge = await SpecializedAgentContextBridge.resolve(
- object(),
- {
- "kind": "context",
- "workflow_id": "wf",
- "context_node_id": "ctx",
- "generation": 4,
- "execution_id": "run-1",
- },
- provider="rlm",
- fidelity="observable_only",
- resumable=False,
- )
-
- assert "committed prior answer" in bridge.augment_prompt("continue")
-
-
-async def test_cli_adapter_sends_portable_handoff_in_effective_prompt(
- monkeypatch,
-):
- bridge = SimpleNamespace(
- augment_prompt=lambda prompt: f"prior portable answer\n{prompt}",
- append_observable=AsyncMock(),
- )
- monkeypatch.setattr(
- "services.cli_agent.service."
- "SpecializedAgentContextBridge.resolve",
- AsyncMock(return_value=bridge),
- )
- monkeypatch.setattr(
- "services.plugin.deps.get_database",
- lambda: object(),
- )
- monkeypatch.setattr(
- AICliService,
- "_resolve_repo_root",
- AsyncMock(return_value=None),
- )
-
- non_directory = Path(__file__).resolve()
- result = await AICliService().run_batch(
- "codex",
- tasks=[CodexTaskSpec(prompt="current request")],
- node_id="codex-1",
- workflow_id="wf",
- workspace_dir=non_directory,
- repo_root=non_directory,
- broadcaster=None,
- connected_context={
- "kind": "context",
- "workflow_id": "wf",
- "context_node_id": "ctx",
- "generation": 2,
- "execution_id": "run-1",
- },
- execution_id="run-1",
- )
-
- assert result.tasks[0].prompt == (
- "prior portable answer\ncurrent request"
- )
- request = bridge.append_observable.await_args_list[0].args[1]
- assert request["tasks"][0].prompt == (
- "prior portable answer\ncurrent request"
- )
-
-
-async def test_pool_terminates_previous_epoch_before_new_context_acquire(
- monkeypatch,
-):
- old_key = ("wf:context:1", "session:chat-1", 1)
- new_key = ("wf:context:1", "session:chat-1", 2)
- old = PooledClaudeSession(
- memory_node_id=old_key,
- process=SimpleNamespace(returncode=None, pid=1),
- cwd=Path.cwd(),
- )
- new = PooledClaudeSession(
- memory_node_id=new_key,
- process=SimpleNamespace(returncode=None, pid=2),
- cwd=Path.cwd(),
- )
- pool = object.__new__(ClaudeSessionPool)
- pool._pool = {old_key: old}
- pool._pool_lock = asyncio.Lock()
- pool._max_size = 16
- terminated = []
-
- async def terminate(key, *, reason="explicit"):
- terminated.append((key, reason))
- pool._pool.pop(key, None)
-
- monkeypatch.setattr(pool, "_terminate_locked", terminate)
- monkeypatch.setattr(pool, "_spawn", AsyncMock(return_value=new))
- monkeypatch.setattr(pool, "_emit_event", AsyncMock())
-
- acquired = await pool.acquire(
- new_key,
- spec=ClaudeTaskSpec(prompt="next epoch"),
- cwd=Path.cwd(),
- env={},
- defaults={},
- mcp_endpoint_url=None,
- mcp_bearer_token=None,
- )
- await pool.release(acquired)
-
- assert terminated == [(old_key, "epoch_changed")]
- assert old_key not in pool._pool
- assert pool._pool[new_key] is new
-
-
-class _FullResponseProvider:
- name = "claude"
-
- @staticmethod
- def is_final_event(event):
- return event.get("type") == "result"
-
- @staticmethod
- def event_to_session_result(events, stderr, exit_code):
- del stderr, exit_code
- return {
- "session_id": "uuid-1",
- "response": events[-1]["result"],
- "canonical_usage": CanonicalUsage(),
- "success": True,
- }
-
- @staticmethod
- def canonical_usage(events):
- del events
- return CanonicalUsage()
-
-
-async def test_pool_sends_full_raw_event_to_context_before_ui_truncation():
- raw = "z" * 10_000
- captured = []
-
- async def sink(event):
- captured.append(event)
-
- session = PooledClaudeSession(
- memory_node_id=("ctx", "execution:1", 1),
- process=SimpleNamespace(returncode=None, pid=1),
- cwd=Path.cwd(),
- context_event_sink=sink,
- )
- pool = object.__new__(ClaudeSessionPool)
- pool._provider = _FullResponseProvider()
-
- event = {"type": "result", "result": raw, "session_id": "uuid-1"}
- await pool._handle_stream_event(session, event)
- result = pool._build_result_from_events(
- session=session,
- events=[event],
- prompt="hello",
- success=True,
- )
-
- assert captured[0]["result"] == raw
- assert len(result.response) == 4_000
-
-
-async def test_pool_surfaces_context_persistence_failure():
- async def broken_sink(event):
- del event
- raise RuntimeError("database unavailable")
-
- session = PooledClaudeSession(
- memory_node_id=("ctx", "execution:1", 1),
- process=SimpleNamespace(returncode=None, pid=1),
- cwd=Path.cwd(),
- context_event_sink=broken_sink,
- )
- pool = object.__new__(ClaudeSessionPool)
- pool._provider = _FullResponseProvider()
-
- await pool._handle_stream_event(
- session,
- {"type": "assistant", "message": {"content": "secret"}},
- )
-
- assert session.result_event.is_set()
- assert "context_event_persistence_failed" in (
- session.context_capture_error or ""
- )
- assert session.events_this_turn == []
diff --git a/server/tests/services/test_native_agent_runtime.py b/server/tests/services/test_native_agent_runtime.py
index 08571904..fba58625 100644
--- a/server/tests/services/test_native_agent_runtime.py
+++ b/server/tests/services/test_native_agent_runtime.py
@@ -264,7 +264,7 @@ async def test_compaction_pause_can_replace_replay_before_next_request():
@pytest.mark.asyncio
-async def test_native_loop_persists_context_transitions_before_tool_execution():
+async def test_native_loop_saves_the_conversation_before_tool_execution():
first_message = Message(
role="assistant",
tool_calls=[ToolCall(id="call-1", name="one", args={"value": 3})],
@@ -283,22 +283,17 @@ async def test_native_loop_persists_context_transitions_before_tool_execution():
),
]
)
- observed: list[tuple[str, str]] = []
+ observed: list[tuple[str, object]] = []
tool = _tool("one")
- class _Sink:
- async def append_transition(self, **kwargs):
- observed.append(("context", kwargs["event_type"]))
- if kwargs.get("message_wire"):
- assert "version" not in kwargs["message_wire"]
- assert kwargs["message_wire"].get("role")
- assert kwargs["operation_id"].startswith("execution-9:")
+ async def save(messages):
+ observed.append(("save", [message.role for message in messages]))
async def execute(_name, args):
assert tool.execution["tool_call_id"] == "call-1"
assert (
tool.execution["operation_id"]
- == "execution-9:iteration:1:tool:1:call-1"
+ == "openai:iteration:1:tool:1:call-1"
)
observed.append(("tool", str(args["value"])))
return {"ok": True}
@@ -313,20 +308,39 @@ async def test_native_loop_persists_context_transitions_before_tool_execution():
initial_messages=[Message(role="system", content="resolved"), Message(role="user", content="go")],
tools=[tool],
tool_executor=execute,
- context_transition_sink=_Sink(),
- context_operation_id="execution-9",
- )
-
- event_names = [value for kind, value in observed if kind == "context"]
- assert event_names == [
- "request.snapshot",
- "message.assistant",
- "message.tool_result",
- "request.snapshot",
- "message.assistant",
- "response.final",
+ conversation_saver=save,
+ )
+
+ saves = [value for kind, value in observed if kind == "save"]
+ # Saved after the assistant append (billing already happened), again
+ # after the tool results, and once more for the final answer.
+ assert saves == [
+ ["system", "user", "assistant"],
+ ["system", "user", "assistant", "tool"],
+ ["system", "user", "assistant", "tool", "assistant"],
]
- assert observed.index(("context", "message.assistant")) < observed.index(("tool", "3"))
+ # The assistant turn is durable BEFORE its tool executes.
+ assert observed.index(("save", saves[0])) < observed.index(("tool", "3"))
+
+
+async def test_native_loop_save_failure_cannot_fail_the_run():
+ unifier = _FakeUnifier([LLMResponse(content="done")])
+
+ async def broken_save(messages):
+ raise RuntimeError("save exploded")
+
+ result = await run_native_agent_loop(
+ unifier,
+ provider="openai",
+ api_key="test",
+ model="gpt-test",
+ temperature=0,
+ max_tokens=100,
+ initial_messages=[Message(role="user", content="go")],
+ conversation_saver=broken_save,
+ )
+ assert result["response"].content == "done"
@pytest.mark.asyncio
diff --git a/server/tests/services/test_rlm_context_v2.py b/server/tests/services/test_rlm_context_v2.py
index c77f4eb7..b59f870b 100644
--- a/server/tests/services/test_rlm_context_v2.py
+++ b/server/tests/services/test_rlm_context_v2.py
@@ -1,4 +1,4 @@
-"""RLM's honest observable-only Context V2 boundary."""
+"""RLM's plain-conversation Context boundary."""
from __future__ import annotations
@@ -15,9 +15,9 @@ from services.rlm.service import RLMService
@pytest.mark.asyncio
-async def test_rlm_records_request_and_result_as_non_resumable_context():
+async def test_rlm_loads_context_into_prompt_and_records_the_turn():
bridge = MagicMock()
- bridge.append_observable = AsyncMock()
+ bridge.record_turn = AsyncMock()
bridge.augment_prompt = MagicMock(
side_effect=lambda prompt: f"portable-history\n{prompt}"
)
@@ -99,19 +99,17 @@ async def test_rlm_records_request_and_result_as_non_resumable_context():
assert result["success"] is True
resolve_kwargs = resolve.await_args.kwargs
- assert resolve_kwargs["fidelity"] == "observable_only"
- assert resolve_kwargs["resumable"] is False
- event_types = [
- call.args[0] for call in bridge.append_observable.await_args_list
- ]
- assert event_types == ["provider.request", "provider.result"]
+ assert resolve_kwargs["provider"] == "rlm"
+ assert resolve_kwargs["agent_node_id"] == "rlm-1"
+ # The stored conversation was rendered into the prompt sent to RLM.
assert prompts == ["portable-history\nsolve"]
- sink = tool_bridge.call_args.kwargs["ambiguous_outcome_sink"]
- assert sink is not None
- await sink({"outcome": "ambiguous", "reason": "tool_timeout"})
- last = bridge.append_observable.await_args
- assert last.args[0] == "tool.ambiguous_outcome"
- assert last.args[1]["reason"] == "tool_timeout"
+ # The exchange was recorded with the ORIGINAL prompt, never the
+ # augmented one — otherwise every save would nest the rendered
+ # transcript inside itself.
+ bridge.record_turn.assert_awaited_once_with(
+ "solve", "answer:portable-history\nsolve"
+ )
+ assert tool_bridge.call_args.kwargs["ambiguous_outcome_sink"] is None
assert "session_id" not in result["result"]
assert "resume" not in result["result"]
diff --git a/server/tests/services/test_workflow_context_archive_outbox.py b/server/tests/services/test_workflow_context_archive_outbox.py
index 6870481b..ce8da859 100644
--- a/server/tests/services/test_workflow_context_archive_outbox.py
+++ b/server/tests/services/test_workflow_context_archive_outbox.py
@@ -8,7 +8,12 @@ from types import SimpleNamespace
import pytest
-from services.agent_context import AgentContextStore
+import services.agent_context as agent_context
+from services.agent_context import (
+ list_conversations,
+ load_conversation,
+ save_conversation,
+)
@pytest.fixture
@@ -185,12 +190,12 @@ async def test_pending_archive_recovers_on_workflow_read(
"workflow",
_graph(with_context=True),
)
- store = AgentContextStore(database)
- await store.resolve_thread(
+ await save_conversation(
+ database,
workflow_id="1",
- context_node_id="ctx",
generation=1,
- session_id="session",
+ agent_node_id="agent",
+ messages=[{"role": "user", "content": "hello"}],
)
# Simulate a process crash after graph commit and before the outbox drain.
@@ -202,19 +207,12 @@ async def test_pending_archive_recovers_on_workflow_read(
)
assert len(await database.list_workflow_context_archive_outbox("1")) == 1
- real_store = AgentContextStore
-
- class _FailingStore:
- def __init__(self, database):
- self.database = database
+ real_clear = agent_context.clear_conversation
- async def archive_context(self, **kwargs):
- raise RuntimeError("simulated_archive_crash")
+ async def failing_clear(*args, **kwargs):
+ raise RuntimeError("simulated_archive_crash")
- monkeypatch.setattr(
- "services.agent_context.AgentContextStore",
- _FailingStore,
- )
+ monkeypatch.setattr(agent_context, "clear_conversation", failing_clear)
monkeypatch.setattr(handlers.container, "database", lambda: database)
first = await handlers.handle_get_workflow(
{"workflow_id": "1"},
@@ -222,17 +220,16 @@ async def test_pending_archive_recovers_on_workflow_read(
)
assert first["context_archives_pending"] == 1
assert (
- await store.list_threads(
+ await load_conversation(
+ database,
workflow_id="1",
- context_node_id="ctx",
- include_archived=True,
+ generation=1,
+ agent_node_id="agent",
)
- )[0].status == "active"
-
- monkeypatch.setattr(
- "services.agent_context.AgentContextStore",
- real_store,
+ != []
)
+
+ monkeypatch.setattr(agent_context, "clear_conversation", real_clear)
recovered = await handlers.handle_get_workflow(
{"workflow_id": "1"},
websocket=None,
@@ -240,13 +237,7 @@ async def test_pending_archive_recovers_on_workflow_read(
assert recovered["context_archives_completed"] == 1
assert recovered["context_archives_pending"] == 0
assert await database.list_workflow_context_archive_outbox("1") == []
- assert (
- await store.list_threads(
- workflow_id="1",
- context_node_id="ctx",
- include_archived=True,
- )
- )[0].status == "archived"
+ assert await list_conversations(database, workflow_id="1") == []
@pytest.mark.asyncio
@@ -264,12 +255,12 @@ async def test_workflow_delete_commits_tombstone_then_archives(
"workflow",
_graph(with_context=True),
)
- store = AgentContextStore(database)
- await store.resolve_thread(
+ await save_conversation(
+ database,
workflow_id="1",
- context_node_id="ctx",
generation=1,
- session_id="session",
+ agent_node_id="agent",
+ messages=[{"role": "user", "content": "hello"}],
)
result = await delete_workflow_with_context_archival(
@@ -288,13 +279,7 @@ async def test_workflow_delete_commits_tombstone_then_archives(
await database.list_workflow_context_archive_outbox("1")
== []
)
- assert (
- await store.list_threads(
- workflow_id="1",
- context_node_id="ctx",
- include_archived=True,
- )
- )[0].status == "archived"
+ assert await list_conversations(database, workflow_id="1") == []
@pytest.mark.asyncio
@@ -330,12 +315,12 @@ async def test_failed_workflow_delete_rolls_back_archive_tombstone(
"second",
_graph(with_context=True),
)
- store = AgentContextStore(database)
- await store.resolve_thread(
+ await save_conversation(
+ database,
workflow_id="2",
- context_node_id="ctx",
generation=1,
- session_id="session",
+ agent_node_id="agent",
+ messages=[{"role": "user", "content": "hello"}],
)
# Enqueuing workflow 2's archive collides with the existing outbox ID.
@@ -349,9 +334,11 @@ async def test_failed_workflow_delete_rolls_back_archive_tombstone(
== []
)
assert (
- await store.list_threads(
+ await load_conversation(
+ database,
workflow_id="2",
- context_node_id="ctx",
- include_archived=True,
+ generation=1,
+ agent_node_id="agent",
)
- )[0].status == "active"
+ != []
+ )
diff --git a/server/tests/temporal/test_agent_workflow.py b/server/tests/temporal/test_agent_workflow.py
index 795ba633..310a62a3 100644
--- a/server/tests/temporal/test_agent_workflow.py
+++ b/server/tests/temporal/test_agent_workflow.py
@@ -94,45 +94,26 @@ class TestDurableTeamDelegationContract:
assert '"execution_id": context.get("execution_id")' in source
-class TestContextJournalIdentity:
- """Every firing must journal, and journal each turn exactly once."""
-
- def test_journal_operation_ids_are_per_firing_not_per_generation(self):
- """``execution_id`` is generation-scoped, so reusing it for journal
- operation ids made every chat message in a generation mint identical
- ids. The store's idempotency guard then discarded turns 2..N as
- replays and only the generation's first message was ever recorded.
- """
- import inspect
-
- from services.temporal.agent_workflow import AgentWorkflow
-
- source = inspect.getsource(AgentWorkflow.run)
- assert 'context.get("context_execution_id")' in source, (
- "journal operation ids must derive from the per-firing "
- "context_execution_id"
- )
- for suffix in (":prepare", ":append", ":llm"):
- assert f"{{journal_operation_id}}" in source
- assert f"{{execution_id}}:iter" not in source
- assert f'f"{{execution_id}}{suffix}"' not in source
+class TestConversationIdentity:
+ """Every firing continues one conversation and saves each turn once."""
- def test_journal_operation_ids_are_scoped_per_agent_node(self):
- """Two agents on one Context node resolve to the same thread.
+ def test_conversation_key_is_workflow_generation_agent(self):
+ """The conversation key is (workflow_id, generation, agent_node_id).
- With a firing-scoped id alone they minted identical operation ids,
- collided on (thread, operation_id) and had their turns discarded as
- replays -- so one of the two agents was simply absent from the journal.
+ The journal design keyed threads per firing/session, so a taskTrigger
+ review resolved a different thread from the chat that started the
+ work and the lead came back amnesiac (messages=2). One key per agent
+ per generation makes every firing continue the same conversation.
"""
import inspect
- from services.temporal.agent_workflow import AgentWorkflow
+ from services.temporal import agent_activities
- source = inspect.getsource(AgentWorkflow.run)
- assert 'f"{journal_operation_id}:{agent_node_id}"' in source, (
- "journal operation ids must include the agent node id, or "
- "sibling agents sharing a Context node overwrite each other"
- )
+ source = inspect.getsource(agent_activities.prepare_agent_payload)
+ assert '"workflow_id"' in source
+ assert '"generation"' in source
+ assert '"agent_node_id"' in source
+ assert "conversation_key" in source
def test_resumed_run_continues_from_the_carried_transcript(self):
"""continue_as_new carries the live transcript itself.
@@ -227,13 +208,12 @@ class TestContextJournalIdentity:
step = inspect.getsource(agent_activities.execute_llm_step)
assert "if payload.get(\"context_ref\")" not in step
- def test_journal_failure_cannot_fail_the_run(self):
- """Observation must never break execution.
+ def test_save_failure_cannot_fail_the_run(self):
+ """Persistence must never break execution.
- The journal write happens after the provider has been called and
+ The conversation save happens after the provider has been called and
billed, so raising there fails the turn over a bookkeeping write — and
- for a team lead, stalls its next delegation. A thread fenced by Reset
- or an archived epoch is an expected condition, not an error.
+ for a team lead, stalls its next delegation.
"""
import ast
import inspect
@@ -241,7 +221,7 @@ class TestContextJournalIdentity:
from services.temporal import agent_activities
fn = ast.parse(
- inspect.getsource(agent_activities._journal_llm_turn)
+ inspect.getsource(agent_activities._save_conversation)
).body[0]
handlers = [
handler
@@ -249,39 +229,38 @@ class TestContextJournalIdentity:
if isinstance(node, ast.Try)
for handler in node.handlers
]
- assert handlers, "_journal_llm_turn must not let a write failure escape"
+ assert handlers, (
+ "_save_conversation must not let a write failure escape"
+ )
assert any(
h.type is None
or (isinstance(h.type, ast.Name) and h.type.id == "Exception")
for h in handlers
)
- def test_journal_records_the_exact_request_never_a_reconstruction(self):
- """The journal must record what was sent, not rebuild it.
+ def test_conversation_records_the_exact_request_never_a_reconstruction(
+ self,
+ ):
+ """The store must record what was sent, not rebuild it.
- ``prepare_context`` runs before the request exists, so anything it
- wrote was assembled from configuration — that is how the journal came
- to hold a fabricated request, the system prompt typed as a tool
- result, and the user's prompt twice. The turn is journalled from the
- exact list handed to ``ChatUnifier.chat``.
+ The retired ``prepare_context`` activity wrote journal entries
+ assembled from configuration before the request existed — that is
+ how the journal came to hold a fabricated request. The turn is saved
+ from the exact list handed to ``ChatUnifier.chat``, after the call.
"""
import inspect
from services.temporal import agent_activities
- prepare = inspect.getsource(agent_activities.prepare_context)
- assert "_append_event" not in prepare, (
- "prepare_context must not journal; it has no request yet"
+ assert not hasattr(agent_activities, "prepare_context"), (
+ "prepare_context journalled configuration before a request "
+ "existed; the plain store saves only what was sent"
)
native = inspect.getsource(agent_activities._execute_native_llm_step)
- sent = native.index("_journal_llm_turn")
+ sent = native.index("_save_conversation")
called = native.index("run_native_llm_step(")
- assert called < sent, "journal the request only after it was sent"
- assert "for message in messages" in native, (
- "the journalled request must be the same `messages` object passed "
- "to the unifier"
- )
+ assert called < sent, "save the request only after it was sent"
def test_root_execution_identity_is_initialized_before_agent_loop(self):
import inspect
@@ -467,7 +446,6 @@ class TestAgentActivities:
"agent.finalize_team",
"agent.finish_delegation",
"agent.persist_turn",
- "agent.prepare_context",
"agent.prepare_payload",
"agent.queue_delegation",
"agent.refresh_tools",
@@ -1183,13 +1161,15 @@ class TestAgentContinueAsNew:
# test_rollover_guards_transcript_size) so the CAN argument stays
# under Temporal's payload error limit.
carried = source[source.index("_RESUME_MARKER:") :][:700]
+ # The conversation key is deliberately NOT carried: prepare_payload
+ # recomputes it deterministically from the descriptor on every run,
+ # resumed or fresh.
for required in (
'"transcript"',
'"usage"',
'"context_usage"',
'"iteration"',
'"execution_id"',
- '"context_ref"',
):
assert required in carried, f"{required} must cross the rollover"
diff --git a/server/tests/temporal/test_agent_workflow_v2.py b/server/tests/temporal/test_agent_workflow_v2.py
index 11586b1b..278efa3f 100644
--- a/server/tests/temporal/test_agent_workflow_v2.py
+++ b/server/tests/temporal/test_agent_workflow_v2.py
@@ -1,4 +1,10 @@
-"""Focused contracts for Context-backed Temporal agent orchestration."""
+"""Focused contracts for Context-backed Temporal agent orchestration.
+
+The retired ``_thread_inputs`` session-routing tests are gone with the
+journal: the plain conversation store keys on
+``(workflow_id, generation, agent_node_id)`` and deliberately ignores
+session identity, so every firing of an agent continues one conversation.
+"""
from __future__ import annotations
@@ -44,56 +50,3 @@ def test_new_generation_routes_to_v2_but_missing_metadata_stays_v1():
}
assert missing_generation["name"] == "AgentWorkflow"
assert missing_version["name"] == "AgentWorkflow"
-
-
-def test_delegated_thread_identity_does_not_inherit_parent_session():
- from services.temporal.agent_activities import _thread_inputs
-
- value = _thread_inputs(
- {
- "session_id": "parent-chat",
- "team_task_id": "task-42",
- "execution_id": "run-1",
- }
- )
- assert value == {
- "session_id": None,
- "delegated_task_id": "task-42",
- "execution_id": "run-1",
- }
-
-
-def test_control_data_scope_is_not_treated_as_explicit_chat_session():
- from services.temporal.agent_activities import _thread_inputs
-
- value = _thread_inputs(
- {
- "session_id": "scope-1",
- "data_scope_id": "scope-1",
- "execution_id": "generation-1",
- "context_execution_id": "firing-42",
- }
- )
- assert value == {
- "session_id": None,
- "delegated_task_id": None,
- "execution_id": "firing-42",
- }
-
-
-def test_explicit_event_session_beats_execution_thread():
- from services.temporal.agent_activities import _thread_inputs
-
- value = _thread_inputs(
- {
- "session_id": "scope-1",
- "data_scope_id": "scope-1",
- "context_session_id": "chat-7",
- "context_execution_id": "firing-42",
- }
- )
- assert value == {
- "session_id": "chat-7",
- "delegated_task_id": None,
- "execution_id": "firing-42",
- }
diff --git a/server/tests/test_context_graph_migration.py b/server/tests/test_context_graph_migration.py
index 56f3f3ee..e8aa75e5 100644
--- a/server/tests/test_context_graph_migration.py
+++ b/server/tests/test_context_graph_migration.py
@@ -517,12 +517,11 @@ async def test_workflow_delete_archives_context_before_graph(
)
)
database.delete_workflow = AsyncMock(return_value=True)
- store = SimpleNamespace(archive_context=AsyncMock(return_value=[]))
+ import services.agent_context as agent_context
+
+ clear = AsyncMock(return_value=0)
monkeypatch.setattr(handlers.container, "database", lambda: database)
- monkeypatch.setattr(
- "services.agent_context.AgentContextStore",
- lambda _: store,
- )
+ monkeypatch.setattr(agent_context, "clear_conversation", clear)
result = await handlers.handle_delete_workflow(
{"workflow_id": "12"},
@@ -535,12 +534,7 @@ async def test_workflow_delete_archives_context_before_graph(
"contexts_archived": 1,
"context_archives_pending": 0,
}
- store.archive_context.assert_awaited_once_with(
- workflow_id="12",
- context_node_id="ctx",
- generation=None,
- operation_id="workflow-deleted:12:ctx",
- )
+ clear.assert_awaited_once_with(database, workflow_id="12")
database.delete_workflow.assert_awaited_once_with("12")