Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
Goal:
Split durable session metadata from process-local runtime handles as the next
ADR-0058 implementation slice, without changing runtime behavior, persisted
session payloads, or public HTTP/CLI APIs.

Scope:
- Introduce a narrow `SessionRuntimeHandle` structure for process-local fields
such as task, runtime pipeline/context/adapter, runtime message bus, approval
cursor, event queues, and approval coordination objects.
- Introduce or prepare a `SessionRecord` boundary for durable session metadata
while preserving the existing stored session payload shape.
- Move access inside `SessionManager` toward explicit durable-record vs runtime
handle usage in the smallest behavior-preserving slice.
- Add focused regression coverage proving persisted session data excludes
process-local handles and hydrated sessions can reacquire runtime state.

Out of scope:
- Do not change HTTP request/response schemas.
- Do not change session store, runtime store, tape store, or checkpoint store
persisted formats.
- Do not introduce `RunCoordinator` or `LocalDaemonExecutor` behavior yet.
- Do not replace `ExecutionBinding` persistence with `RunTarget` persistence in
this slice.
- Do not change `coding_agent run` behavior.

Context:
- ADRs:
- `docs/adr/0058-local-daemon-control-plane-executor-architecture.md`
- `docs/adr/0055-session-resume-and-interrupted-run-semantics.md`
- `docs/adr/0015-enforce-owner-routed-http-event-streams.md`
- Postmortem patterns:
- `postmortem/patterns/PM-0015-require-store-backed-requests-across-http-approval-flow.md`
- `postmortem/patterns/PM-0021-guard-event-stream-registration-against-disappearing-sessions.md`
- `postmortem/patterns/PM-0022-revalidate-event-stream-ownership-after-queue-attach.md`
- `postmortem/patterns/PM-0023-make-event-stream-cleanup-and-teardown-idempotent.md`
- Relevant files:
- `src/coding_agent/server/session_manager.py`
- `src/coding_agent/server/stores/session_store.py`
- `tests/ui/test_session_persistence.py`
- `tests/ui/test_session_manager_runtime.py`
- `tests/ui/test_session_manager_public_api.py`
- `tests/ui/test_http_server_failover.py`

Target tests:
- `uv run pytest tests/agentkit/ tests/coding_agent/ tests/cli/ -k "session or runtime or resume or checkpoint" -v`
- `uv run pytest tests/agentkit/ tests/coding_agent/ tests/cli/ -k "event or queue or owner or close or delete" -v`
- `uv run ruff check src/coding_agent/server/session_manager.py tests/coding_agent/ tests/cli/`

Loop policy:
- Engineer implements the smallest correct change and runs the target tests.
- Reviewer reviews only the resulting diff and affected tests.
- Reviewer reports only P1/P2 findings.
- Engineer fixes only accepted P1/P2 findings and reruns the same target tests.
- Verifier reruns the exact target tests and reports pass/fail only.

Stop conditions:
- Stop if the split requires changing persisted session payloads or public API
schemas.
- Stop if `RunCoordinator`, executor ownership, or daemon lifecycle design is
needed to proceed.
- Stop after one review/fix/retest cycle.
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# ADR-0058: Local daemon control plane and executor architecture

**Status**: Proposed
**Status**: Accepted
**Date**: 2026-06-02

## Context
Expand Down Expand Up @@ -121,20 +121,29 @@ This ADR does not implement that path.

## Acceptance Criteria

- [ ] `RunTarget`, `WorkspaceRef`, `ExecutorRef`, `IsolationPolicy`, and
- [x] `RunTarget`, `WorkspaceRef`, `ExecutorRef`, `IsolationPolicy`, and
`RunConstraints` exist under `src/coding_agent/runs/`.
- [ ] `ExecutionBinding -> RunTarget` adapter maps local, cloud,
- [x] `ExecutionBinding -> RunTarget` adapter maps local, cloud,
external-worker, and local-attached compatibility bindings without changing
existing serialized `ExecutionBinding` payloads.
- [ ] New code in the run-placement skeleton imports canonical binding models
- [x] New code in the run-placement skeleton imports canonical binding models
from `coding_agent.environment.execution_binding`, not server/ui aliases.
- [ ] `test_local_execution_binding_maps_to_local_daemon_run_target`
- [ ] `test_cloud_execution_binding_maps_to_managed_pool_run_target`
- [ ] `test_external_worker_binding_maps_to_external_worker_run_target`
- [ ] `test_local_attached_binding_maps_to_local_attached_run_target`
- [ ] `test_run_target_rejects_empty_annotations_key`
- [ ] `uv run pytest tests/coding_agent/test_run_target.py tests/ui/test_execution_binding.py -v`
- [ ] `uv run ruff check src/coding_agent/runs tests/coding_agent/test_run_target.py`
- [x] `test_local_execution_binding_maps_to_local_daemon_run_target`
- [x] `test_cloud_execution_binding_maps_to_managed_pool_run_target`
- [x] `test_external_worker_binding_maps_to_external_worker_run_target`
- [x] `test_local_attached_binding_maps_to_local_attached_run_target`
- [x] `test_run_target_rejects_empty_annotations_key`
- [x] `uv run pytest tests/coding_agent/test_run_target.py tests/ui/test_execution_binding.py -v`
- [x] `uv run ruff check src/coding_agent/runs tests/coding_agent/test_run_target.py`

## Follow-up Implementation Tasks

- Split durable `SessionRecord` data from process-local `SessionRuntimeHandle`
state.
- Introduce a `RunCoordinator` boundary that selects an executor from
`RunTarget`.
- Move runtime ownership behind `LocalDaemonExecutor`.
- Demote `coding_agent run` to an inline testkit/devkit compatibility path.

## References

Expand Down
Loading