KDCube ReAct v2 Agent

Timeline & Side Effects Model

The timeline is the authoritative, ordered log of everything that happened in a conversation. It is loaded at turn start, updated as the turn progresses, and persisted at turn end as a single JSON artifact.

Contribute vs Announce

Turn lifecycle

1. 1

   Load timeline

   ctx_browser.load_timeline() fetches artifact:conv.timeline.v1 and artifact:conv:sources_pool, hydrating in-memory state for the turn.

2. 2

   Contribute user input

   User prompt and any attachments are contributed as persistent blocks, joining the timeline block stream.

3. 3

   Gate agent (optional)

   Only for new conversations. The gate agent renders the timeline without sources or announce, emits a title block, and contributes it. All subsequent turns skip the gate entirely.

4. 4

   ReAct decision loop

   Each round: render timeline (with sources + announce), call the LLM, execute the chosen tool, contribute results back into the timeline. Repeat until the agent emits a final answer or the iteration budget is exhausted.

5. 5

   Persist

   Both conv.timeline.v1 and conv:sources_pool are written back to storage. The turn log (artifact:turn.log) records the current-turn blocks for fast next-turn reconstruction.

Compaction and TTL pruning

When the rendered timeline would exceed the model's context budget, the runtime compacts earlier blocks into a single conv.range.summary block. The compacted blocks are removed from the persisted payload; future renders start from the summary forward.

Separately, when a session cache_ttl_seconds is configured, blocks older than the TTL are replaced with truncated placeholders on render. A system.message block is appended advising the agent to use react.read(path) to restore any specific logical path.

Block ordering (schematic)

# Typical timeline block sequence (condensed)
[TURN turn_A]
  user.prompt
  user.attachment.meta
  stage.gate                  # optional, new conv only
  stage.react
  react.tool.call             # tool params
  react.tool.result           # rendered artifact metadata
  react.plan                  # JSON snapshot of plan
  react.plan.ack              # human-readable ack
  assistant.completion        # [sources_used: [1,2,3]]

[TURN turn_B]
  user.prompt
  ...
[SOURCES POOL]                # appended at tail (uncached)
[ANNOUNCE]                    # appended at tail (uncached)

Multi-Channel Streaming

ReAct v2's output layer is built on the Channeled Streamer (versatile_streamer.py), a tag-based protocol that routes a single LLM stream into multiple named logical channels, each with independent format, citation replacement, and subscriber fanout.

How it works

The model wraps each logical output in XML-like channel tags:

# Model output (single LLM call, multiple channels)
<channel:thinking>
  Let me check the document structure first...
</channel:thinking>

<channel:answer>
  Based on the report [[S:1]], the key findings are...
</channel:answer>

<channel:followup>
  {"followups": ["Show me the full table", "Compare with last quarter"]}
</channel:followup>

The stream_with_channels() function parses these tags incrementally, routing each chunk to the correct channel handler as it streams. Citation tokens ([[S:n]]) are replaced per-channel without modifying the stored raw output.

Channel types in ReAct v2

Listener attachment and subscriber fanout

Each channel can carry one or more subscribers — side-effect handlers that run alongside the primary emit function. A subscriber on the usage channel, for example, can write source IDs to a timeline record streamer while the answer channel continues streaming to the user uninterrupted.

# Illustrative adaptation (from docs pattern)
from kdcube_ai_app.apps.chat.sdk.streaming.versatile_streamer import (
    ChannelSpec, ChannelSubscribers, stream_with_channels
)

channels = [
    ChannelSpec(name="thinking",  format="markdown", replace_citations=False, emit_marker="thinking"),
    ChannelSpec(name="answer",    format="markdown", replace_citations=True,  emit_marker="answer"),
    ChannelSpec(name="followup",  format="json",     replace_citations=False, emit_marker="followup"),
    ChannelSpec(name="usage",     format="json",     replace_citations=False, emit_marker="answer"),
]

results, meta = await stream_with_channels(
    svc=svc,
    messages=[system_msg, user_msg],
    role="answer.generator.regular",
    channels=channels,
    emit=_emit_wrapper,
    agent="my.react.agent",
    artifact_name="response",
    sources_list=sources_list,
    subscribers=ChannelSubscribers().subscribe("usage", _record_usage_sids),
    return_full_raw=True,
)

answer_text = results["answer"].raw
used_sids   = results["answer"].used_sources
service_err = (meta or {}).get("service_error")

Citation replacement and token savings

Citation tokens ([[S:1]], [[S:1,3]], [[S:2-4]]) are replaced at stream time for markdown and text channels, and replaced with <sup class="cite"> tags for html channels. The stored raw output is never modified; replacement happens only in the bytes sent to the client.

A stateful per-channel citation tokenizer handles tokens split across chunk boundaries, ensuring [[S:n]] is never partially emitted to the client. This allows citation-heavy responses to stream cleanly without client-side parsing.

Composite JSON streaming

For managed JSON artifacts, the CompositeJsonArtifactStreamer can be attached to a JSON channel. As the model streams a JSON object, each top-level field is parsed incrementally and emitted as a per-attribute delta to a separate marker (typically canvas). This enables live structured UI rendering before the full JSON closes.

Memory & Context Management

ReAct v2 approaches memory not as a separate subsystem but as a set of layered strategies on the timeline: caching, compaction, TTL pruning, semantic search, and selective hiding all operate on the same block stream.

Three-checkpoint caching

The context browser inserts up to three cache checkpoints per rendered timeline, enabling providers that support prompt caching (such as Anthropic) to serve most of the context from cache on repeated calls:

• Prev-turn checkpoint — placed on the last block of the previous turn.
• Pre-tail checkpoint — placed offset_rounds before the tail round (when enough rounds exist).
• Tail checkpoint — placed on the last stable round of the current turn.

Sources and announce blocks are appended after all checkpoints and remain uncached every round, ensuring the agent always sees fresh source data and plan status without invalidating the stable prefix cache.

Compaction (edit-over-rewrite framing)

When the visible timeline exceeds the model budget, earlier blocks are compacted into a conv.range.summary block at the cut point. The original blocks are removed from the persisted payload; future renders start from the summary forward. This is an edit-over-rewrite approach — the timeline is surgically trimmed, not discarded and restarted.

TTL-based context expiry efficiency

When cache_ttl_seconds is set in the session configuration, blocks from previous turns are replaced with compact truncated placeholders after the TTL expires. A system.message block is appended to explain the pruning and guide the agent to restore specific paths via react.read(path). This mechanism keeps the active context window efficient for long-lived sessions without losing the ability to recall prior content.

react.memsearch — Persistent recall

Even after compaction or TTL pruning, prior turn content is indexed semantically. react.memsearch allows the agent to query that index for relevant snippets from any historical turn, surfacing them with scores and timestamps. The agent can then selectively reload full content via react.read.

# Docs pattern: semantic recall from past turns
react.memsearch(
    query="database schema discussed last week",
    targets=["assistant", "user"],
    top_k=5,
    days=30
)
# Returns: [{turn_id, text, score, ts}, ...]

react.hide — Selective context pruning

Within a single turn, the agent can replace large blocks in the editable tail window with short placeholders using react.hide. The original content remains accessible via react.read. This is useful for hiding large file artifacts that are no longer needed in the active context window, freeing space for new tool results.

Plan snapshots

Plans are tracked as explicit react.plan JSON snapshot blocks in the timeline, updated each time the decision agent acknowledges progress in its reasoning notes. A human-readable react.plan.ack block is emitted alongside. The active plan is surfaced in the announce section each round; closed or completed plans remain in the timeline history but are no longer re-announced.

# Plan snapshot block (docs pattern, simplified)
{
  "type": "react.plan",
  "mime": "application/json",
  "path": "ar:<turn_id>.react.plan.<plan_id>",
  "text": {
    "plan_id": "plan_abc123",
    "origin_turn_id": "turn_001",
    "steps": [
      { "n": 1, "label": "Gather sources",  "status": "done" },
      { "n": 2, "label": "Draft report",    "status": "pending" }
    ]
  }
}

Code Examples

1 — Channel definition and listener setup

FROM DOCS PATTERN

from kdcube_ai_app.apps.chat.sdk.streaming.versatile_streamer import (
    ChannelSpec, ChannelSubscribers, stream_with_channels
)

# Define channels emitted by the model
channels = [
    ChannelSpec(
        name="answer",
        format="markdown",
        replace_citations=True,
        emit_marker="answer",
    ),
    ChannelSpec(
        name="usage",
        format="json",
        replace_citations=False,
        emit_marker="answer",
    ),
]

# Attach a subscriber to the "usage" channel for side-effect fanout
subscribers = ChannelSubscribers().subscribe("usage", _usage_json_fanout)

# Invoke streaming (docs pattern; see versatile_streamer.py)
results, meta = await stream_with_channels(
    svc=svc,
    messages=[system_msg, user_msg],
    role="answer.generator.regular",
    channels=channels,
    emit=_emit_wrapper,
    agent="my.agent",
    artifact_name="report",
    sources_list=sources_list,
    subscribers=subscribers,
    return_full_raw=True,
)

answer_raw   = results["answer"].raw
used_sources = results["answer"].used_sources
service_err  = (meta or {}).get("service_error")

2 — Multi-channel streaming round with composite JSON

FROM DOCS PATTERN

from kdcube_ai_app.apps.chat.sdk.streaming.versatile_streamer import ChannelSpec, stream_with_channels
from kdcube_ai_app.apps.chat.sdk.streaming.artifacts_channeled_streaming import CompositeJsonArtifactStreamer

# Answer channel carries JSON; composite streamer fans it out to canvas
channels = [
    ChannelSpec(name="answer", format="json", replace_citations=False, emit_marker="answer"),
    ChannelSpec(name="usage",  format="json", replace_citations=False, emit_marker="answer"),
]

results = await stream_with_channels(
    svc=svc,
    messages=[system_msg, user_msg],
    role="answer.generator.regular",
    channels=channels,
    emit=emit_delta,
    agent="my.agent",
    artifact_name="my.json.artifact",
    composite_cfg={"artifactA": "path.to.schema"},
    composite_channel="answer",   # route JSON channel into composite streamer
    composite_marker="canvas",    # emit per-attribute deltas to canvas
)

3 — Source referencing across documents

ILLUSTRATIVE ADAPTATION

# Step 1: Sources are accumulated across turns into conv:sources_pool.
# The pool is loaded at turn start via ctx_browser.load_timeline().

# Step 2: Decision agent loads specific sources by SID range (docs pattern)
# Inside the react decision loop:
react.read(["so:sources_pool[1-5]"])   # loads sources 1 through 5
react.read(["so:sources_pool[1,3,7]"]) # loads sources 1, 3, 7

# Step 3: Agent cites sources inline in generated text
# The streamer replaces [[S:n]] tokens during streaming (never in stored raw)
answer_text = """
According to the analysis [[S:1]], the platform supports
multi-channel streaming [[S:2,3]]. Cache efficiency results
in up to 60% cost reduction [[S:1]].
"""

# Step 4: Client rehydrates citations using sources_used SIDs from the artifact
# matched against current sources_pool in timeline.json
used_sids = results["answer"].used_sources  # e.g. [1, 2, 3]
pool      = timeline_json["sources_pool"]
refs      = [s for s in pool if s["sid"] in used_sids]

4 — react.memsearch for persistent recall

FROM DOCS PATTERN

# Semantic search over past turns — useful after compaction or TTL pruning
# Inside the react decision loop (react.memsearch is a react.* in-loop tool):

react.memsearch(
    query="authentication configuration from last session",
    targets=["assistant", "user"],
    top_k=5,
    days=90
)

# Returns blocks like:
# [{"turn_id": "turn_123", "text": "...", "score": 0.84, "ts": "2026-02-01T...Z"}]

# Then restore the full content if needed:
react.read(["fi:turn_123.files/config.yaml"])