Core

Core

Edge adaptation of the upstream agent loop, agent registry, and turn lifecycle.

Upstream reference: Core

What Upstream Provides

The core subsystem provides the foundational agent infrastructure that every composition builds on:

• AgentRegistry () — creates, resumes, and disposes agents. Each agent owns a session, an inbox (next-turn / next-step message queues), and a scoped cordis context. The disposer is a capability — only the creator can tear down the agent.
  • AgentLoop — the concrete driver implementing the contract. Processes inbox messages through the step pipeline: pre-step validation → model request → streaming → tool execution → post-step. Transitions between and status.
  • Agent events — scope-filtered dispatch: , , , , , , and inbox events.
  • Inbox management — two ordered message lists ( and ) with append, prepend, replace, remove, clear, and splice operations, all recorded as durable events.

What Edge Changed

Direct Reuse AgentRegistry + AgentLoop

Both plugins are installed as-is with zero modification. Agent creation, session binding, inbox management, step pipeline, model streaming, and tool dispatch are entirely upstream code.

Transport Bridge Turn lifecycle management

Upstream's agent loop runs in the same process as the caller — a turn starts when the caller sends a message and ends when the agent goes idle. Edge adds a transport layer around this because the caller (browser) is remote:

• ** map** — tracks which sessions have running turns in the DO. Prevents concurrent turns on the same session across interleaved HTTP requests.
  • **** — atomically claims the session slot and opens/resumes an agent before accepting the prompt. Ensures no two requests own the same session simultaneously.
  • **** — wraps the upstream turn in a flush-then-publish pipeline: listens to , flushes to DO SQL, then publishes the event over WebSocket. Binds the shell backend for the turn duration.
  • Admission control — gates prompt admission behind a persistence flush, ensuring the user message is durable before the model sees it. The upstream agent loop itself runs unchanged inside this wrapper — it doesn't know it's being observed and published over a network.

Transport Bridge Status broadcast

When a turn starts, Edge broadcasts over WebSocket. When it ends, . Upstream reads directly from memory; Edge translates this into network frames.

What Edge Did NOT Change

• Agent creation, session binding, and disposal lifecycle
  • Inbox management and message queue semantics
  • Step pipeline (pre-step → request → streaming → tool execution → post-step)
  • Scope-filtered event dispatch
  • Model request preparation and retry policy
  • Turn-stopping negotiation ( waterfall)

Performance Characteristics

Turn lifecycle overhead

Edge adds three costs on top of upstream's turn:

• Claim check: one Map lookup per prompt to verify no concurrent turn — O(1), sub-microsecond.
  • Flush barrier: each event is flushed to DO SQL before WebSocket publish. This adds a synchronous SQL write per event (~1ms). Upstream flushes at checkpoint boundaries; Edge flushes per-event for stronger durability guarantees.
  • Shell binding: associates the Computer VFS workspace with the agent for the turn duration — one Map insertion, released in .

Concurrent sessions

A single Durable Object instance (named ) manages all workspaces and sessions — mirroring upstream's single-process architecture. The map ensures at most one turn runs per session, while different sessions can interleave within the same DO. Isolation comes from application-level scoping (cordis agent scopes, VFS workspace paths), not from separate runtime instances.

Agent reuse across turns

When a session already has a live agent (from a previous turn that hasn't been disposed), reuses it — no agent creation cost. Cold sessions (after DO restart) pay the agent resume cost: load session header + event log from DO SQL + rebuild in-memory state.

Architecture Summary

Component	Category	Edge Code
AgentRegistry	Reuse	One call
AgentLoop	Reuse	One call
Turn lifecycle wrapper	Bridge	+
Status broadcast	Bridge	WebSocket frames

Key observation: The core agent infrastructure runs entirely upstream code. Edge wraps each turn in a claim → flush → publish pipeline to bridge the network gap between the DO and the browser. The agent loop doesn't know it's running on Cloudflare — it sees the same cordis context, the same session, and the same tool registry as upstream.

Known Limitations & Future Direction

The current single-DO architecture mirrors upstream's single-process design but inherits Cloudflare-specific ceilings:

• Memory: 128 MB per DO shared by all active sessions — limits the number of concurrent turns with large context windows.

  • SQL storage: 10 GB per DO for all session event logs — long-lived deployments with many sessions will eventually hit this.
  • Concurrency: DO is single-threaded — multiple sessions interleave but don't truly parallelize.
  • Subagent isolation: agents within the same DO share memory and can't be resource-isolated. The natural evolution is session-per-DO: each session gets its own Durable Object with independent memory, storage, and lifecycle. This requires:

• A router DO (or the entry Worker) managing workspace → session → DO-id mapping.

  • Layered VFS: shared agent-level storage (workspace code, config) accessible across session DOs, plus session-local storage (temp files, spill, tool output) isolated per DO. The shared layer could use R2 or a dedicated workspace DO.
  • Subagent via DO fork: child agents spawned as independent DOs with their own memory budget, communicating results back to the parent via DO-to-DO fetch.