Skip to content

Foundation / Real-time Patterns

Real-time Patterns

Three hooks that form the real-time subscription layer for AI-native treasury interfaces. All use only React — no third-party state libraries. All are React Strict Mode safe.

Color rule: Blue (--ds-color-temporal) governs all real-time activity indicators. Gold (--ds-color-validation) for stale/threshold warnings. Green/red (--ds-color-outcome-*) for health outcomes.

Hook 1 of 3

useAgentStream

Subscribes to a simulated SSE stream, delivering content in token-sized chunks. Returns accumulated chunks, stream lifecycle status, and time-to-first-token.

useAgentStreamstatus: idle
Press Start to begin stream simulation.
import { useAgentStream } from "@/hooks/useAgentStream";

const { chunks, status, latency, start, reset } = useAgentStream({
  content: "Your agent response text here...",
  chunkInterval: 40,   // ms between chunks
  chunkSize: 3,        // chars per chunk
  ttft: 320,           // simulated time-to-first-token
});

// chunks: string[]        — accumulated text pieces
// status: StreamStatus    — "idle" | "streaming" | "complete" | "error"
// latency: number | null  — ms to first token
PropTypeDefaultDescription
contentstringFinance commentaryText to stream character by character
chunkIntervalnumber40Delay between each chunk delivery in ms
chunkSizenumber3Characters delivered per chunk
ttftnumber320Simulated time-to-first-token in ms

Hook 2 of 3

usePositionFeed

Simulates live FX position ticks at a configurable interval with tunable volatility. Returns the current position book, the timestamp of the last tick, and the per-position delta.

usePositionFeed
PairRateNotionalP&LTrend
EUR/USD1.08475.0M+12,340
GBP/USD1.26342.5M-4,210
USD/JPY149.720010.0M+31,500
USD/CHF0.90511.0M+880
import { usePositionFeed } from "@/hooks/usePositionFeed";

const { positions, lastUpdate, delta, running, pause, resume } = usePositionFeed({
  interval: 1500,     // tick frequency in ms
  volatility: 0.3,   // 0=frozen, 1=very volatile
});

// positions:  Position[]    — current live book
// lastUpdate: Date | null   — timestamp of last tick
// delta:      PositionDelta[] — rateDelta + pnlDelta per pair since last tick
PropTypeDefaultDescription
intervalnumber1500Milliseconds between ticks
volatilitynumber (0–1)0.3Rate movement magnitude. 0 = no movement, 1 = highly volatile

Hook 3 of 3

useAgentHeartbeat

Polls a simulated agent status registry on a configurable interval. Marks agents as stale when they exceed the staleness window. Returns the agent list, last poll timestamp, and a top-level stale flag.

useAgentHeartbeat
PositionAnalyst
FX Risk
IDLE
Computing VaR for EUR/USD book
ComplianceGuard
Regulatory
IDLE
Awaiting task
LiquidityOracle
Funding
IDLE
Monitoring intraday cashflow
SettlementBot
Ops
IDLE
Awaiting SWIFT confirmation #8823
import { useAgentHeartbeat } from "@/hooks/useAgentHeartbeat";

const { agents, lastPing, stale, ping } = useAgentHeartbeat({
  interval: 3000,       // poll frequency in ms
  staleAfterMs: 8000,   // threshold before marking agent stale
});

// agents:   AgentRecord[]  — array with { id, name, role, status, lastSeenMs, currentTask }
// lastPing: Date | null    — when the last poll completed
// stale:    boolean        — true if ANY agent is stale or offline
// ping:     () => void     — force an immediate poll
PropTypeDefaultDescription
intervalnumber3000Poll interval in ms
staleAfterMsnumber8000Milliseconds without response before an agent is marked stale

Usage Rules

When to use each hook

useAgentStream

Agent reply panels, streaming response components, token-by-token chat interfaces.

usePositionFeed

Live FX monitor, real-time P&L panels, treasury position dashboards with tick data.

useAgentHeartbeat

Multi-agent orchestration views, agent fleet status bars, ops dashboards monitoring autonomous worker health.

Do

Use --ds-color-temporal for all streaming/polling indicators.

Provide pause/resume controls on feeds that auto-update.

Show a staleness warning (gold) before showing offline (red).

Use tabular-nums for all rate and P&L values.

Don't

Don't use red for streaming — blue owns in-flight activity.

Don't skip cleanup on unmount — always clear timers and intervals.

Don't poll faster than 1s intervals in production without backpressure.

Don't show raw ms timestamps — format with toLocaleTimeString().

Related