diff --git a/coding-agent/docs/developer_console/CURRENT_STATE.md b/coding-agent/docs/developer_console/CURRENT_STATE.md new file mode 100644 index 000000000..2b55fcece --- /dev/null +++ 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. diff --git a/coding-agent/docs/developer_console/GOAL_PROGRESS.md b/coding-agent/docs/developer_console/GOAL_PROGRESS.md new file mode 100644 index 000000000..06731c135 --- /dev/null +++ b/coding-agent/docs/developer_console/GOAL_PROGRESS.md @@ -0,0 +1,98 @@ +# Developer Console G54-G63 Goal Progress + +Date started: 2026-05-20 + +## Phase Scope + +This phase adds a Developer Console / Debug UI over existing Coding Agent APIs, +stores, metrics, and observability contracts. It must not reimplement or change +AgentKit Core, durable runtime, context retrieval, memory, action safety, +release hardening, or observability platform semantics. + +## Global Constraints + +- Keep AgentKit Core generic. +- Do not rewrite AgentKit pipeline. +- Do not change G00-G53 behavior. +- Do not implement schedules, desktop app, bridge, proactive agent, or full + Docker sandbox in this phase. +- Do not require external services, production credentials, or real LLM calls. +- Do not expose secrets or raw sensitive content beyond existing sanitized API + contracts. +- Do not bypass approval/action policy from console pages. +- Do not add raw prompt/content/message/result/secret/text/command output, + stdout, stderr, or env values to tracing attributes or UI-visible metadata + unless explicitly allowed by an existing sanitized API contract. + +## Planned Goals + +| Goal | Scope | +| --- | --- | +| G54 | Current-state UI/API/debug surface map. | +| G55 | Developer Console ADR and UI contract. | +| G56 | Minimal console shell and navigation. | +| G57 | Sessions and runs list. | +| G58 | Run detail and event replay. | +| G59 | HITL interaction inbox. | +| G60 | Tape and context inspector. | +| G61 | Memory, action, and validation inspector. | +| G62 | Observability and release integration. | +| G63 | E2E smoke and final docs. | + +## G54 Developer Console Current State Map + +Status: passed local verification; pending PR. + +### Intended Files + +- `docs/developer_console/CURRENT_STATE.md` +- `docs/developer_console/GOAL_PROGRESS.md` + +### Verification Commands + +- `test -f docs/developer_console/CURRENT_STATE.md` +- `test -f docs/developer_console/GOAL_PROGRESS.md` +- `rg -n "Recommended MVP: server-rendered HTML|No blocker found for G54|GET /runs/\\{run_id\\}/events|GET /metrics|PGTapeStore.info|AgentInteractionRecord" docs/developer_console/CURRENT_STATE.md` +- `rg -n "G54 Developer Console Current State Map|G55|G63|Do not change G00-G53 behavior" docs/developer_console/GOAL_PROGRESS.md` +- `git diff --check -- .` + +### Stop Criteria + +- Stop if an equivalent Developer Console already exists and this plan would + duplicate it. +- Stop if the current UI/API surface cannot be mapped without production code + changes. +- Stop if later console goals would require rewriting AgentKit Core or changing + G00-G53 semantics. + +### Changed Files + +- `docs/developer_console/CURRENT_STATE.md` +- `docs/developer_console/GOAL_PROGRESS.md` + +### Tests Run + +- `test -f docs/developer_console/CURRENT_STATE.md` +- `test -f docs/developer_console/GOAL_PROGRESS.md` +- `rg -n "Recommended MVP: server-rendered HTML|No blocker found for G54|GET /runs/\\{run_id\\}/events|GET /metrics|PGTapeStore.info|AgentInteractionRecord" docs/developer_console/CURRENT_STATE.md` +- `rg -n "G54 Developer Console Current State Map|G55|G63|Do not change G00-G53 behavior" docs/developer_console/GOAL_PROGRESS.md` +- `git diff --check -- .` + +### Results + +- Developer Console current-state document exists and maps the existing HTTP + server, APIs, store capabilities, tests, response shapes, and likely future + modification files. +- Progress ledger exists and includes G54-G63 scope and constraints. +- Evidence checks found the recommended server-rendered HTML MVP direction, + absence of an equivalent console, runtime replay API, metrics endpoint, tape + debug capability, and durable interaction record references. +- `git diff --check -- .` passed. + +### Remaining Risks + +- G54 is documentation-only. No console routes, UI contract, API helpers, or + HTML rendering exist yet. +- Existing APIs do not yet expose global run listing, interaction inbox, + tape debug, context inspector, memory evidence, or release verification pages + through console routes.