RFC: Continuous Event Transport for AI Coding Agents

[huan]

Authors

PromptWareOS Core

Abstract

This RFC defines a platform‑agnostic, continuous event transport model that enables AI coding agents to participate as first‑class capability actors in a pure CQRS + Event‑Driven Architecture (EDA) system.

The design preserves CQRS/EDA purity while enabling low‑latency, reactive agent workflows across heterogeneous AI coding agent platforms (wake‑capable, polling‑only, or future systems). It introduces promise‑first semantics, continuous transport sessions, watcher/digestor behavior, and explicit wake signaling—without coupling to any specific agent runtime, UI, or tool execution mechanism.

---

1. Motivation

Modern AI coding agents are fundamentally turn‑based, while real systems are event‑driven. Naïve integrations force the system to wait for human or agent turns, introducing latency, reducing UX quality, and breaking the mental model of reactive systems.

This RFC resolves that tension by:

• Making the transport continuous, not the model
• Treating agents as capability actors under CQRS
• Defining promise‑first semantics for all operations
• Allowing hosts to schedule model invocations when actionable events occur

The result is a system that feels real‑time when possible, and degrades gracefully when not.

---

2. Non‑Goals

This RFC does not:

• Specify UI behavior or terminal tooling
• Require any specific AI agent platform features
• Define concrete scheduling or threading implementations
• Replace existing PromptWareOS CQRS or transport RFCs

---

3. Terminology

• CQRS: Command Query Responsibility Segregation
• EDA: Event‑Driven Architecture
• Capability Actor: An addressable actor with a serialized mailbox
• Session: A continuous transport context
• Promise‑like: An operation whose result resolves in the future
• Watcher: A digestor that observes the transport stream
• BlobPointer: An immutable reference to encrypted, stored payloads

---

4. Design Principles & Invariants

1. Everything is an event or derived from events
2. All operations are promise‑like by default
3. Commands describe intent; events describe facts
4. At‑least‑once delivery + idempotent handlers
5. Strict serialization per capability actor
6. Single join rule: metadata.causation === request.metadata.id
7. Transport is continuous; model execution is scheduled
8. Platform agnosticism is mandatory

---

5. Session Model

5.1 Session Identity

Each continuous transport context MUST be identified by:

• metadata.session

metadata.session groups messages belonging to the same transport context. It MUST NOT overload metadata.id or causation fields.

5.2 Session Lifecycle

Sessions follow the PromptWareOS lifecycle:

BOOTING → READY → QUIESCENT → SHUTTING_DOWN → STOPPED

---

6. Promise Semantics

6.1 Promise‑First Rule

All commands and queries are promise‑like.

There is no synchronous semantic in the protocol. Operations that complete immediately are considered promises resolved immediately.

6.2 Resolution Rules

• Commands

  • response indicates acceptance or rejection only
  • Terminal resolution MUST occur via events

• Queries

  • Terminal resolution MUST occur via response

This rule is normative.

---

7. CQRS Message Semantics

Each message envelope includes:

• kind: command | query | response | event
• metadata.id (unique per message)
• metadata.causation (join rule)
• metadata.session
• metadata.origin

No additional join or correlation rules are defined.

---

8. Capability: System.Shell

8.1 Definition

System.Shell is a capability command representing execution within the system environment. The environment is implementation‑defined and MAY include local, remote, sandboxed, or simulated execution.

8.2 Semantics

• Always promise‑like
• Initial response MAY return a handle
• Output, progress, completion, and failure are delivered as events

No synchronous blocking behavior is defined.

---

9. Continuous Transport Model

The transport MUST support:

• Streaming of CQRS envelopes
• Session‑scoped ordering
• At‑least‑once delivery

Transport framing (NDJSON, streams, sockets, etc.) is implementation‑defined.

---

10. Watcher & Digestor Behavior

10.1 Role

A Watcher observes the continuous transport stream and produces digests suitable for agent consumption.

The watcher:

• Batches messages
• Prioritizes faults and causation‑linked replies
• Emits digests instead of raw streams
• Never issues domain commands

10.2 Compliance

• L2 compliance REQUIRES watcher‑equivalent behavior
• L1 MAY omit watcher behavior

---

11. Wake Semantics

11.1 Agent.Wake

Agent.Wake is a first‑class event signaling that actionable information is available for an agent.

11.2 Actionable Definition

Actionable events include:

1. Messages causally linked to an outstanding agent request
2. Faults or execution failures
3. Explicit decision‑required signals

---

12. Backpressure & Flow Control

Backpressure MUST be represented via CQRS messages:

• Credit‑based flow control
• Queue depth / lag telemetry events

Imperative pausing is prohibited.

---

13. Security & Trust Model

13.1 Trust Posture

AI agents are treated as trusted capability actors.

13.2 Data Protection

Implementations handling sensitive data MUST:

• Encrypt payloads at rest
• Redact secrets before LLM exposure
• Use BlobPointer references for raw data

---

14. Compliance Levels

Level	Description
L1	Poll‑only, turn‑based
L2	Continuous transport + watcher
L3	Wake‑capable scheduling

---

15. Extension Points

The following are explicitly extensible:

• Capability namespaces
• Event types
• Wake reasons
• Flow control strategies

---

Appendix A: Design Invariants Checklist

• Promise‑first semantics
• Event‑based command completion
• Single causation join rule
• Session‑scoped transport
• Watcher for L2

---

Appendix B: Capability Author Checklist

• Idempotent handlers
• No synchronous assumptions
• Events describe facts
• Secrets never streamed

---

Appendix C: Compliance Matrix

See Section 14.

---

Appendix D: Glossary

• Promise‑like: Resolution via future messages
• Watcher: Transport digestor
• Wake: Scheduling signal

---

16. Non-Normative Sequence Diagrams

This section is informative, not normative. It illustrates typical flows using the rules defined above.

16.1 Command → Event → Agent.Wake (Promise Resolution via Events)

Agent            Transport / System           Watcher           Host Scheduler
  |                    |                        |                    |
  | Command (System.Shell)                      |                    |
  |------------------->|                        |                    |
  |                    | Response (accepted)    |                    |
  |<-------------------|                        |                    |
  |                    |                        |                    |
  |                    | Event: OutputChunk     |                    |
  |                    |----------------------->|                    |
  |                    | Event: Completed       |                    |
  |                    |----------------------->|                    |
  |                    |                        | Digest + Wake      |
  |                    |                        |------------------->|
  |                    |                        |                    |
  |            (Agent invoked by host scheduler)                     |

Notes:

• The command is promise-like.
• Terminal resolution occurs via events.
• Agent.Wake is derived from watcher policy.

---

16.2 Query → Response (Immediate Resolution)

Agent            Transport / System
  |                    |
  | Query              |
  |------------------->|
  |                    |
  | Response (result)  |
  |<-------------------|

Notes:

• Queries resolve via responses.
• Still promise-like, even if immediate.

---

16.3 Backpressure via Credit-Based Flow Control

Watcher / Host        Transport
  |                    |
  | Flow.Credit.Grant |
  |------------------->|
  |                    |
  | Event stream (<=N) |
  |<-------------------|
  |                    |

---

End of RFC

[huan]

Technical Architecture Report: Claude Code 2 Background Execution

Status

Informative Technical Analysis (Non-Normative)

Purpose

This document provides a deep technical architecture analysis of the Claude Code 2 background execution feature (background shell commands and background agents). It explains how the feature works, why it works despite LLM turn-based constraints, what internal components must exist, what failure modes reveal about implementation, and what portable design lessons apply to PromptWareOS.

This report is descriptive and analytical, not prescriptive.

---

0. Executive Summary

Claude Code 2 introduces background execution for shell commands and agents, enabling users to continue interacting with the system while long-running tasks proceed concurrently. Although the underlying LLM remains strictly turn-based and token-serial, Claude Code achieves this behavior by introducing a host-side orchestration layer that:

• Executes tools and agents concurrently outside the LLM
• Maintains a task registry and output buffers
• Converts asynchronous task state changes into structured messages ("system reminders")
• Schedules LLM invocations only at defined decision points

The key illusion is continuous work with serialized reasoning. The LLM never runs concurrently; the system around it does.

---

1. Feature Surface and User-Visible Behavior

1.1 Background Shell Execution

From the user’s perspective:

• A shell command can be started in the background
• Control returns immediately to the chat prompt
• Output continues to accumulate
• The user can request output later or be notified when it changes

Observed user-facing primitives:

• Start shell task → immediate acknowledgement with a handle
• Poll output → returns only new output since last check
• Kill shell → terminates task

This strongly implies:

• Non-blocking process spawning
• Persistent process handles
• Incremental output tracking

1.2 Background Agents

Claude Code 2 extends the same backgrounding model to agents:

• A subagent can be launched to perform work
• It continues independently of the main conversation
• Results are surfaced when available

A unified UX gesture (e.g., Ctrl+B) applies to both shells and agents, indicating a shared abstraction: background tasks.

1.3 System Reminders and Notifications

When background tasks produce output or complete, Claude Code injects structured system messages (often described by users as “system reminders”) into the conversation context.

These reminders do not represent user input; they are host-generated events converted into transcript entries to inform the LLM during its next invocation.

---

2. Architectural Model (Conceptual)

2.1 Separation of Planes

Claude Code’s design implies two distinct planes:

Work Plane (Concurrent)

• OS processes (shell commands)
• Background subagents (independent model sessions)
• File IO, network calls, tool execution

Control Plane (Serialized)

• Main agent reasoning
• Transcript management
• Policy decisions (when to wake the agent)

Only the control plane interacts with the LLM directly.

2.2 Event Loop Core

At the heart of Claude Code is a host-side event loop that listens to multiple event sources:

• User input
• Background process stdout/stderr
• Background agent completion
• Timeouts and errors

This loop updates internal state continuously but invokes the LLM only when a decision is required.

2.3 Wake-Up Mechanism

Claude Code changelogs explicitly describe that background tasks can “wake up” the main agent. This does not mean interrupting token generation; it means scheduling a new model call with updated context.

---

3. Core Components (Inferred)

3.1 Task Registry

A central registry likely tracks all background tasks:

• Task ID
• Task type (ShellTask, AgentTask)
• Status (running, completed, failed, killed)
• Ownership (who spawned it)
• Output buffers

The registry is the authoritative source for UI state and reminder generation.

3.2 Output Buffering Subsystem

Observed behavior strongly implies:

• Per-task stdout and stderr buffers
• Offset tracking to support “new output since last check” semantics
• Status flags indicating whether unseen output exists

3.3 Reminder / Notification Subsystem

When buffered output changes or a task completes:

• A reminder condition is triggered
• A structured message is prepared
• That message is appended to the transcript as a system-level entry

This is the bridge from async reality to serialized LLM reasoning.

3.4 Scheduler / Invoker

A scheduler decides:

• Whether an event warrants waking the main agent
• Whether to merely update UI state
• How frequently to invoke the model to avoid spam

---

4. State Machines

4.1 Background Shell Lifecycle

CREATED → RUNNING → (COMPLETED | FAILED | KILLED)

Transitions:

• CREATED → RUNNING on process spawn
• RUNNING → COMPLETED on exit code 0
• RUNNING → FAILED on non-zero exit
• RUNNING → KILLED on explicit termination

Each terminal state should clear output-dirty flags.

4.2 Background Agent Lifecycle

SPAWNED → WORKING → REPORTING → COMPLETED

Reporting may include:

• Partial progress
• Final summary
• Tool outputs

4.3 Dirty Output Flags

A cross-cutting concern:

• Output arrives → mark dirty
• User or watcher consumes output → clear dirty
• Failure to clear leads to reminder floods

---

5. End-to-End Procedures

5.1 Start Background Shell

1. User or agent issues shell command
2. Host spawns process
3. Task registered with ID
4. Immediate acknowledgement returned
5. UI updates to show running task

5.2 Poll Output

1. Host checks buffer offsets
2. Returns only new data
3. Updates internal cursor
4. Clears dirty flag if fully consumed

5.3 Automatic Notification

1. Output arrives asynchronously
2. Dirty flag set
3. Reminder condition evaluated
4. System reminder injected into transcript

5.4 Kill and Cleanup

1. Kill request issued
2. Process terminated
3. Status updated
4. Buffers sealed
5. Reminders should cease

Observed bugs indicate cleanup is non-trivial.

5.5 Background Agent Completion

1. Agent finishes work
2. Result summarized
3. Task marked completed
4. Reminder or wake issued

---

6. Implementation Evidence and Inference

6.1 What Is Explicit

• Background tasks exist
• They can wake the main agent
• Output is incremental
• Unified UX for shell and agents

6.2 What Is Inferred

• Task registry with lifecycle states
• Output offset tracking
• Dirty-flag-based reminder logic
• Host-side scheduler

6.3 What Is Opaque

• Exact data structures
• Internal threading model
• Persistence guarantees

---

7. Failure Modes and Diagnosis

7.1 Reminder Persistence

Likely cause:

• Terminal state not clearing dirty flag
• Registry entry not finalized

7.2 Infinite Reminder Loops

Cause:

• Reminder injection feeds context
• Context growth triggers more reminders
• No digest/throttling layer

7.3 Output Delta Bugs

Cause:

• Offset cursor not advanced
• Output replayed repeatedly

7.4 Scaling Issues

As tasks increase:

• Registry complexity grows
• UI clarity degrades
• Need for listing, filtering, grouping

---

8. Design Lessons (Portable)

1. Async reality, serialized reasoning is the winning pattern
2. Handles + event streams beat blocking outputs
3. Digestors/watchers are essential for token hygiene
4. Wake is a scheduling hint, not a transport push
5. Background execution is a host responsibility, not an LLM feature

These lessons directly informed PromptWareOS’s continuous transport RFC.

---

9. Open Questions

• Exact wake policies
• Automatic vs user-driven polling balance
• Long-term persistence of background tasks
• Multi-session interactions

---

10. Comparative Analysis: Claude Code vs Other Agent Runtimes

This section situates Claude Code 2 within a broader landscape of AI coding agent runtimes, highlighting capability differences rather than product features.

10.1 Claude Code 2

• Continuous transport with background execution
• Host-side scheduler and wake semantics
• Unified abstraction for shells and agents
• Implicit watcher via system reminders

Strengths:

• Low-latency reactivity
• Clear separation of orchestration vs reasoning

Limitations:

• Reminder floods without strong digesting
• Opaque internal state machines

---

10.2 Gemini CLI–Style Agents

• Primarily turn-based
• Limited or no wake capability
• Often rely on explicit polling by the user

Strengths:

• Simpler mental model
• Easier sandboxing

Limitations:

• Higher latency
• Poor fit for continuous workflows

---

10.3 Copilot / Palette-Style IDE Agents

• UI-driven invocation model
• Strong IDE context, weak transport semantics
• Often no continuous event channel

Strengths:

• Rich editor integration
• Immediate user feedback

Limitations:

• No native EDA semantics
• Difficult to support background reactivity

---

11. Failure-Mode Appendix: Lessons for PromptWareOS

Claude Code’s observed failure modes directly inform PromptWareOS design decisions.

11.1 Reminder Floods

Observed: Repeated system reminders even after task completion.

Diagnosis:

• Dirty flags not cleared
• No digest/throttle layer

PromptWareOS Mitigation:

• Mandatory watcher for L2
• Digest-first, BlobPointer spillover

---

11.2 Output Replay Bugs

Observed: Duplicate output on successive polls.

Diagnosis:

• Offset cursor desynchronization

PromptWareOS Mitigation:

• Immutable event logs
• Explicit cursor semantics in adapters

---

11.3 Self-Triggering Loops

Observed: Agent reacts to its own reminders.

PromptWareOS Mitigation:

• metadata.origin filtering
• Causation-based reaction rules

---

12. Agent Runtime Taxonomy (L1 / L2 / L3)

This taxonomy classifies agent runtimes by their ability to support continuous systems.

12.1 L1 — Turn-Based Runtime

• Agent invoked only on user turns
• No background execution awareness
• Polling-only transport

Typical systems: basic chat agents, minimal CLIs

---

12.2 L2 — Continuous Transport Runtime

• Background execution supported
• Watcher/digestor present
• Agent can process events without user typing

Typical systems: Claude Code 2–class runtimes

---

12.3 L3 — Wake-Capable Runtime

• Host scheduler can invoke agent on events
• Near real-time reactivity
• Best UX for EDA systems

Typical systems: Claude Code 2 (with wake), future agent OSs

---

13. Forward-Looking Design Implications

The evolution from L1 to L3 suggests that future AI agents will require:

• Explicit runtime schedulers
• Event-native transports
• Digest-first context management
• Clear separation of reasoning vs execution

PromptWareOS is intentionally designed to be ahead of this curve.

---

Conclusion

Claude Code 2 demonstrates that background execution and agent reactivity are achievable without violating LLM constraints. Its architecture validates the PromptWareOS direction: continuous CQRS transport, watcher-based digestion, promise-first semantics, and platform-agnostic scheduling.

The critical insight is that agents do not need to be concurrent—runtimes do.

---

End of Report