delete-cloud · May 20, 2026 · May 20, 2026
diff --git a/coding-agent/docs/developer_console/CURRENT_STATE.md b/coding-agent/docs/developer_console/CURRENT_STATE.md
@@ -0,0 +1,307 @@
+# Developer Console Current State
+
+Date: 2026-05-20
+
+## Purpose
+
+This map captures the repository state before the G54-G63 Developer Console /
+Debug UI phase. The phase should add a debug/product surface over existing
+Coding Agent APIs, stores, metrics, and observability contracts. It must not
+rewrite AgentKit Core, change runtime semantics, bypass action policy, or
+expose secrets/raw sensitive content beyond existing sanitized API contracts.
+
+## Current HTTP Server And Router Structure
+
+The HTTP surface is implemented in
+`src/coding_agent/ui/http_server.py` as one FastAPI app:
+
+- `app = FastAPI(...)` is defined in the same module as route handlers.
+- `SessionManager` is a module-level service object used by the route layer.
+- Request limiting is provided through `coding_agent.ui.rate_limit.limiter`.
+- Authentication helpers live in `coding_agent.ui.auth`.
+- Response schemas live in `src/coding_agent/ui/schemas.py`.
+- Prometheus HTTP metrics are recorded by middleware in `http_server.py`.
+
+There is no separate router package, no mounted `APIRouter`, no template engine,
+and no existing `/console` route.
+
+## Existing Static Or Web Assets
+
+No existing web asset directories were found under `src/`:
+
+- no `static/`
+- no `templates/`
+- no `public/`
+- no frontend package or build pipeline
+
+The existing UI surfaces are:
+
+- FastAPI JSON/SSE HTTP API in `src/coding_agent/ui/http_server.py`
+- rich terminal UI modules under `src/coding_agent/ui/`
+- remote CLI client in `src/coding_agent/remote/client.py`
+
+The console should therefore start as server-rendered HTML or minimal static
+HTML generated by the existing FastAPI app, unless a later goal discovers a
+stronger local pattern.
+
+## Existing HTTP APIs
+
+Health and observability:
+
+- `GET /healthz`
+- `GET /readyz`
+- `GET /metrics` when Prometheus metrics are enabled
+
+Session lifecycle and streaming:
+
+- `POST /sessions`
+- `GET /sessions`
+- `GET /sessions/{session_id}`
+- `POST /sessions/{session_id}/prompt`
+- `GET /sessions/{session_id}/events`
+- `POST /sessions/{session_id}/approve`
+- `POST /sessions/{session_id}/cancel`
+- `GET /sessions/{session_id}/result`
+- `DELETE /sessions/{session_id}`
+
+Durable runtime replay:
+
+- `GET /runs/{run_id}`
+- `GET /runs/{run_id}/message-snapshot`
+- `GET /runs/{run_id}/events?last_event_id=...&limit=...`
+
+Workspace and release-result support:
+
+- `GET /workspaces`
+- `GET /workspaces/{workspace_id}`
+- `POST /workspaces/gc`
+- `POST /workspaces/{workspace_id}/retain`
+- `POST /workspaces/{workspace_id}/pin`
+- `POST /workspaces/{workspace_id}/unpin`
+- `DELETE /workspaces/{workspace_id}`
+- `GET /workspaces/{workspace_id}/archive/manifest`
+- `GET /workspaces/{workspace_id}/archive`
+- `GET /sessions/{session_id}/workspace/diff`
+- `GET /sessions/{session_id}/workspace/patch`
+- `GET /sessions/{session_id}/workspace/archive/manifest`
+- `GET /sessions/{session_id}/workspace/archive`
+- `GET /sessions/{session_id}/workspace`
+- `POST /sessions/{session_id}/publish`
+
+Checkpoints:
+
+- `POST /sessions/{session_id}/checkpoints`
+- `GET /sessions/{session_id}/checkpoints`
+- `POST /sessions/{session_id}/checkpoints/{checkpoint_id}/restore`
+
+## Existing Durable Store Capabilities
+
+`src/coding_agent/runtime_store.py` defines durable records and PG persistence:
+
+- `AgentRunRecord`
+- `RuntimeEventRecord`
+- `RunMessageSnapshotRecord`
+- `AgentInteractionRecord`
+- `PGRuntimeStore.create_agent_run(...)`
+- `PGRuntimeStore.update_agent_run(...)`
+- `PGRuntimeStore.load_agent_run(run_id)`
+- `PGRuntimeStore.list_agent_runs(session_id)`
+- `PGRuntimeStore.replay_runtime_events(run_id, after_sequence, limit)`
+- `PGRuntimeStore.load_runtime_event(event_id)`
+- `PGRuntimeStore.save_message_snapshot(...)`
+- `PGRuntimeStore.load_message_snapshot(snapshot_id)`
+- `PGRuntimeStore.list_message_snapshots(run_id)`
+- `PGRuntimeStore.create_agent_interaction(...)`
+- `PGRuntimeStore.resolve_agent_interaction(...)`
+- `PGRuntimeStore.load_agent_interaction(interaction_id)`
+- `PGRuntimeStore.list_agent_interactions(run_id)`
+
+`src/coding_agent/ui/session_manager.py` exposes only part of that store through
+current HTTP helpers:
+
+- `SessionManager.load_runtime_run(run_id)`
+- `SessionManager.load_runtime_message_snapshot(run_id)`
+- `SessionManager.replay_runtime_events(run_id, last_event_id, limit)`
+
+G57-G59 will likely need small Coding Agent HTTP/helper additions to list runs
+by visible session and list interactions by visible run. There is no current
+global list-runs or interaction-inbox HTTP route.
+
+## Tape, Retrieval, Context, And Memory Surfaces
+
+Tape:
+
+- `agentkit.storage.pg.PGTapeStore.info(tape_id)` and
+  `PGTapeStore.search(...)` exist as PG debug capabilities.
+- ADR-0033 documents filters for `kind`, `run_id`, `tool_call_id`, and
+  `anchor_type`.
+- There is no current HTTP route for tape info/search.
+
+Retrieval and context:
+
+- `src/coding_agent/plugins/kb.py` builds retrieval context and metadata-only
+  observability attributes.
+- `src/coding_agent/context_pack.py` defines context pack items, sections,
+  evidence refs, and rendering.
+- Existing tests cover context pack rendering, retrieval metadata, and the
+  context-system smoke path.
+- There is no current HTTP context-inspector route.
+
+Memory:
+
+- `src/coding_agent/plugins/memory.py` records memory summaries with evidence.
+- `src/coding_agent/plugins/storage.py` provides JSONL memory record helpers:
+  `load_memory_records`, `append_memory_record`, and `replace_memory_records`.
+- There is no current HTTP memory evidence route.
+
+## Action, Validation, And Approval Surfaces
+
+Action safety modules live under `src/coding_agent/action_safety/`:
+
+- action observability
+- approval routing
+- command policy
+- patch planning
+- safe edit policy
+- validation runner
+- validation feedback
+- workspace snapshot/restore
+
+Current HTTP approval surface:
+
+- `POST /sessions/{session_id}/approve` resolves the active approval request.
+- Durable approval interactions are persisted in `AgentInteractionRecord` when
+  a runtime store is configured.
+
+Current HTTP workspace/action inspection surface:
+
+- `GET /sessions/{session_id}/workspace/diff`
+- `GET /sessions/{session_id}/workspace/patch`
+- checkpoint capture/restore routes
+
+There is no dedicated HTTP action execution list/detail route, no validation
+result route, and no interaction inbox route. Early console goals should be
+read-only unless using the existing approval endpoint is clearly safe.
+
+## Observability And Release Surfaces
+
+Observability:
+
+- `src/coding_agent/observability.py` owns Coding Agent tracing and metrics
+  backend wiring.
+- Langfuse/OTLP is a tracing exporter.
+- Prometheus is a metrics exporter.
+- `CompositeObservationSink` allows tracing and metrics together.
+- `GET /metrics` exposes Prometheus text when enabled.
+- `docs/observability/LOCAL_STACK.md` documents local Prometheus/Grafana.
+
+Release:
+
+- `docs/release_hardening/release-verification.yaml` lists deterministic release
+  verification gates.
+- `src/coding_agent/verification/release_manifest.py` loads and validates that
+  manifest.
+- There is no current HTTP route that renders release verification status or
+  commands.
+
+## Available Response Shapes From G00-G53
+
+Defined in `src/coding_agent/ui/schemas.py`:
+
+- `SessionSummaryResponse` and `SessionListResponse`
+- `SessionResultResponse`
+- `RuntimeRunResponse`
+- `RuntimeMessageSnapshotResponse`
+- `RuntimeEventResponse` and `RuntimeEventsResponse`
+- `ApprovalResponseSchema`
+- `CheckpointMetadataResponse`, `CheckpointListResponse`,
+  `CheckpointRestoreResponse`
+- `WorkspaceDiffResponse`, `WorkspacePatchResponse`,
+  `WorkspaceArchiveManifestResponse`, `WorkspaceArchiveResponse`
+- `HealthResponse`, `ReadinessResponse`
+
+Runtime store dataclasses in `src/coding_agent/runtime_store.py` provide
+additional shapes not yet exposed directly in HTTP schemas:
+
+- `AgentInteractionRecord`
+- lists of `AgentRunRecord` by session
+- lists of `RunMessageSnapshotRecord` by run
+
+## Existing Tests For HTTP, UI, And Debug Surfaces
+
+Primary HTTP/UI tests:
+
+- `tests/ui/test_http_server.py`
+- `tests/ui/test_session_manager_runtime.py`
+- `tests/ui/test_session_manager_approval_runtime.py`
+- `tests/ui/test_session_persistence.py`
+- `tests/ui/test_session_manager_public_api.py`
+- `tests/ui/test_http_server_workspace_transfer.py`
+- `tests/ui/test_http_server_failover.py`
+- `tests/ui/test_security.py`
+- `tests/ui/test_rate_limit.py`
+
+Phase smoke and contracts:
+
+- `tests/integration/test_durable_runtime_smoke.py`
+- `tests/coding_agent/test_context_system_smoke.py`
+- `tests/coding_agent/action_safety/test_safe_action_smoke.py`
+- `tests/coding_agent/test_observability_platform_smoke.py`
+- `tests/coding_agent/test_release_verification_manifest.py`
+- `tests/coding_agent/test_release_observability_contract.py`
+
+Focused context/action/memory tests:
+
+- `tests/coding_agent/plugins/test_kb.py`
+- `tests/coding_agent/plugins/test_kb_plugin.py`
+- `tests/coding_agent/plugins/test_memory.py`
+- `tests/coding_agent/test_context_pack.py`
+- `tests/coding_agent/action_safety/test_*`
+
+## Recommended Console Shape
+
+Recommended MVP: server-rendered HTML in `src/coding_agent/ui/http_server.py`
+or a small adjacent Coding Agent UI module imported by that server.
+
+Rationale:
+
+- The repository has no frontend build stack.
+- FastAPI is already the product HTTP boundary.
+- Tests can use the existing ASGI `AsyncClient` patterns.
+- Server-rendered HTML can reuse existing auth/session visibility checks.
+- It avoids introducing a client-side framework for debug pages.
+
+An API-only debug console fallback is acceptable for missing data domains, but
+the phase goals explicitly require browsable `/console` pages. Static HTML + JS
+is viable later if route count grows, but it would still call the same existing
+HTTP APIs.
+
+## Later Modification Map
+
+Likely files to modify:
+
+- `src/coding_agent/ui/http_server.py`
+- `src/coding_agent/ui/schemas.py`
+- `src/coding_agent/ui/session_manager.py`
+- `src/coding_agent/runtime_store.py`
+- `tests/ui/test_http_server.py`
+- new console-focused tests under `tests/ui/` or `tests/coding_agent/`
+- `docs/developer_console/GOAL_PROGRESS.md`
+- `docs/developer_console/IMPLEMENTATION_REPORT.md`
+- `docs/developer_console/USAGE.md`
+- a new ADR for Developer Console boundaries
+
+Files to avoid unless a later goal proves they are necessary:
+
+- `src/agentkit/`
+- AgentKit runtime pipeline modules
+- durable runtime semantic code paths outside read/list helpers
+- context retrieval semantics
+- action safety policy semantics
+- observability exporter semantics
+
+## Blocker Assessment
+
+No blocker found for G54. The codebase does not already have an equivalent
+Developer Console implementation. The missing pieces are a console UI surface
+and some read-only helper/API endpoints over already-persisted data.