[delete-cloud]

Summary

• add agentkit runtime message primitives for interrupt, user_steer, approval_decision, subagent_message, and system_notice
• add an in-memory RuntimeMessageBus with cursor-based idempotent consumption and kind-filtered consumption
• consume runtime messages at pipeline safe points and stop turns on interrupt without advancing the interrupted batch cursor
• leave approval_decision for product approval stores to consume with their own cursor instead of interpreting it in agentkit
• inject run identity, environment summary, elapsed turn time, context budget, active approvals, and current-turn runtime messages into prompt context
• document PR4 runtime-message semantics in AGENTKIT architecture and ADR-0016

Verification

• uv run pytest tests/agentkit/runtime/test_runtime_messages.py tests/agentkit/runtime/test_pipeline.py -q
• uv run pytest tests/agentkit/ -q
• uv run pytest tests/coding_agent/test_pipeline_adapter.py tests/coding_agent/plugins/test_approval.py tests/integration/test_pipeline_e2e.py -q -k "not test_subagent_turn_persisted_tape_flows_into_eval_adapter"
• uv run basedpyright src/agentkit/runtime/messages.py src/agentkit/runtime/pipeline.py tests/agentkit/runtime/test_runtime_messages.py tests/agentkit/runtime/test_pipeline.py --level error
• uv run python -m py_compile src/agentkit/runtime/messages.py src/agentkit/runtime/pipeline.py src/agentkit/runtime/__init__.py tests/agentkit/runtime/test_runtime_messages.py tests/agentkit/runtime/test_pipeline.py
• git diff --check

Known Existing Failure

• Full tests/integration/test_pipeline_e2e.py still includes test_subagent_turn_persisted_tape_flows_into_eval_adapter, which depends on the absent coding-agent/data/eval/golden/parent-child-subagent-001.yaml fixture. The PR verification excludes that known fixture gap.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a runtime message bus system to Agentkit, enabling asynchronous control messages (INTERRUPT, USER_STEER, APPROVAL_DECISION, SUBAGENT_MESSAGE, SYSTEM_NOTICE) to flow into pipeline execution. It introduces cursor-based idempotent consumption semantics, integrates message handling at pipeline stage boundaries, and automatically injects runtime context and messages into the system prompt sent to the LLM model.

Changes

Runtime Message Bus & Pipeline Integration

Layer / File(s)	Summary
Message Types & Protocol src/agentkit/runtime/messages.py, src/agentkit/runtime/__init__.py	Defines RuntimeMessageKind enum, RuntimeMessage frozen dataclass with validation, RuntimeMessageCursor and SequencedRuntimeMessage for sequencing, RuntimeMessageBatch for batched consumption, and RuntimeMessageBus protocol.
Bus Implementation src/agentkit/runtime/messages.py	Implements InMemoryRuntimeMessageBus with process-local storage, duplicate message_id detection on publish, and consume_after() cursor-based filtering with optional limit and next-cursor computation.
Pipeline Integration src/agentkit/runtime/pipeline.py	Extends PipelineContext with runtime_message_bus, runtime_message_cursor, runtime_messages, and runtime_started_at. Adds _consume_runtime_messages() to fetch and advance messages, raising PipelineError on INTERRUPT. Invokes consumption at stage boundaries and before LLM/tool rounds.
Runtime Context Grounding src/agentkit/runtime/pipeline.py	Adds _runtime_context_grounding() to generate a system message dict containing session/run identifiers, environment/workspace info, elapsed time, context budget, active approvals, and current-turn runtime messages. Injects into build_context system prompt.
Message Bus Tests tests/agentkit/runtime/test_runtime_messages.py	Validates RuntimeMessageKind membership, idempotent cursor-based consumption, duplicate message_id rejection, and non-empty message_id enforcement.
Pipeline Integration Tests tests/agentkit/runtime/test_pipeline.py	Adds RuntimeContextEnvironment helper and verifies runtime context/messages injection into model prompt, interrupt handling, and cursor advancement.
Documentation docs/AGENTKIT-ARCHITECTURE.md, docs/adr/0016-stage-environment-runtime-and-tool-orchestration-prs.md	Documents runtime message bus types, consumption semantics, safe-point boundaries, interrupt behavior, and runtime context message contents; updates ADR acceptance criteria.

Sequence Diagram

sequenceDiagram
    actor Ext as External<br/>(Agent/Client)
    participant Bus as RuntimeMessageBus
    participant Pipe as Pipeline
    participant LLM as LLM Model
    
    Ext->>Bus: publish(RuntimeMessage)
    activate Bus
    Bus-->>Ext: SequencedRuntimeMessage
    deactivate Bus
    
    Pipe->>Pipe: run_turn() started
    activate Pipe
    Pipe->>Pipe: stage loop
    
    Note over Pipe,Bus: At each stage boundary
    Pipe->>Bus: consume_after(cursor)
    activate Bus
    Bus-->>Pipe: RuntimeMessageBatch
    deactivate Bus
    
    alt interrupt message received
        Pipe->>Pipe: raise PipelineError
        Note over Pipe: Turn fails, no model call
    else normal messages
        Pipe->>Pipe: _runtime_context_grounding()<br/>(build system message)
        Pipe->>LLM: run(messages with runtime<br/>context grounding)
        activate LLM
        LLM-->>Pipe: response
        deactivate LLM
    end
    
    deactivate Pipe

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• PR #91: Adds AgentRunContext and mounts run_context on PipelineContext, which this PR builds upon to inject runtime context and messages into Pipeline.run_turn.

Poem

🐰 A hop, skip, and message away—
The runtime bus brings control to play!
Interrupts fail fast, bounding from place,
While whispers of state find their way to the base. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title '[codex] Add runtime message bus' clearly and concisely describes the main change: introducing a runtime message bus infrastructure, which is the central feature across all modified files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch runtime-message-bus-pr4

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}