feat(sessions): add ACP session resume and sidebar playback

Implement thread-level ACP session selection and resume across backend
providers and the Web UI. Persist agentOptions.sessionId, add thread
session listing, bind effective session IDs during turns, and emit
session_bound so selected sessions survive across turns.

Update prompt construction and chat replay to be session-aware, including
session-scoped history filtering, transcript merge fallback behavior, and
a paginated right-side session sidebar with switch/new-session actions.
This prevents duplicated context after session/load and makes resumed
sessions visible and controllable in the UI.

Author: beyond5959

PROGRESS.md

@@ -575,3 +575,32 @@ This file is the source of milestone progress, validation commands, and next act
 - 2026-03-09: hid the Web UI Reasoning switch when the active agent exposes fewer than two reasoning choices, so agents without switchable reasoning no longer show a dead control.
 - 2026-03-09: switched Kimi model/reasoning catalog queries to local `config.toml` when available, so startup catalog refresh and thread config/model operations no longer create empty Kimi sessions; real prompt turns still use ACP.
 - 2026-03-11: added opt-in `--debug` startup flag; when enabled, stderr now emits sanitized `acp.message` traces for ACP stdio and embedded-runtime request/response traffic, including session prompts, updates, and permission flows.
+- 2026-03-11: added ACP session browsing/resume support across built-in agents:
+  - introduced shared agent session abstractions for `session/list`, bound-session reporting, and initialize capability parsing.
+  - built-in providers now:
+    - list sessions through ACP `session/list` when supported.
+    - load persisted `agentOptions.sessionId` through ACP `session/load` before prompting.
+    - report the effective session id back to HTTP turns so the server can persist it.
+  - added `GET /v1/threads/{threadId}/sessions` with cursor passthrough and graceful `supported=false` fallback for agents without ACP session-history support.
+  - turn SSE now emits `session_bound`, and the server persists the thread session id without closing the active provider.
+  - once a thread is bound to an ACP session, prompt building skips local recent-turn injection to avoid duplicating already-loaded ACP context.
+  - Web UI now renders a right-side session sidebar with first-page load, `Show more`, active-session highlighting, and `New session` reset.
+  - executed validation:
+    - pass: `cd internal/webui/web && npm run build`
+    - pass: `go test ./internal/httpapi -run 'TestThreadSessionsListEndpoint|TestTurnSessionBoundPersistsSessionIDAndSkipsContextInjection' -count=1`
+    - pass: `go test ./...`
+
+- 2026-03-11: fixed Web UI session playback when selecting an existing ACP session from the right sidebar.
+  - the active chat view now treats `(threadId, sessionId)` as its render scope instead of refreshing only on `threadId` changes.
+  - `loadHistory()` now filters locally persisted turns by each turn's `session_bound` event so the center chat panel replays the selected session's ngent-recorded turns instead of leaving the previous session on screen.
+  - session changes reported mid-stream by `session_bound` defer the full chat refresh until the active turn completes, so the live streaming bubble is not destroyed.
+  - executed validation:
+    - pass: `cd internal/webui/web && npm run build`
+    - pass: `go test ./...`
+
+- 2026-03-11: fixed Web UI history replay for legacy session threads whose `/history` data lacks per-turn `session_bound` events.
+  - session-scoped history filtering now falls back to showing all turns when a thread has no annotated session markers at all, instead of rendering an empty chat pane despite non-empty `/history`.
+  - when a thread has exactly one annotated session, the selected session view also keeps older unannotated turns so pre-annotation history is still visible for that same session.
+  - executed validation:
+    - pass: `cd internal/webui/web && npm run build`
+    - pass: `go test ./...`

cmd/ngent/main.go

@@ -159,12 +159,14 @@ func main() {
 		TurnController:  turnController,
 		TurnAgentFactory: func(thread storage.Thread) (agentimpl.Streamer, error) {
 			modelID := extractModelID(thread.AgentOptionsJSON)
+			sessionID := extractSessionID(thread.AgentOptionsJSON)
 			configOverrides := extractConfigOverrides(thread.AgentOptionsJSON)
 			switch thread.AgentID {
 			case "codex":
 				return codexagent.New(codexagent.Config{
 					Dir:             thread.CWD,
 					ModelID:         modelID,
+					SessionID:       sessionID,
 					ConfigOverrides: configOverrides,
 					Name:            "codex-embedded",
 					RuntimeConfig:   codexRuntimeConfig,
@@ -173,30 +175,35 @@ func main() {
 				return opencodeagent.New(opencodeagent.Config{
 					Dir:             thread.CWD,
 					ModelID:         modelID,
+					SessionID:       sessionID,
 					ConfigOverrides: configOverrides,
 				})
 			case "gemini":
 				return geminiagent.New(geminiagent.Config{
 					Dir:             thread.CWD,
 					ModelID:         modelID,
+					SessionID:       sessionID,
 					ConfigOverrides: configOverrides,
 				})
 			case "kimi":
 				return kimiagent.New(kimiagent.Config{
 					Dir:             thread.CWD,
 					ModelID:         modelID,
+					SessionID:       sessionID,
 					ConfigOverrides: configOverrides,
 				})
 			case "qwen":
 				return qwenagent.New(qwenagent.Config{
 					Dir:             thread.CWD,
 					ModelID:         modelID,
+					SessionID:       sessionID,
 					ConfigOverrides: configOverrides,
 				})
 			case "claude":
 				return claudeagent.New(claudeagent.Config{
 					Dir:             thread.CWD,
 					ModelID:         modelID,
+					SessionID:       sessionID,
 					ConfigOverrides: configOverrides,
 					Name:            "claude-embedded",
 				})
@@ -672,6 +679,19 @@ func extractModelID(agentOptionsJSON string) string {
 	return strings.TrimSpace(opts.ModelID)
 }
 
+func extractSessionID(agentOptionsJSON string) string {
+	var opts struct {
+		SessionID string `json:"sessionId"`
+	}
+	if strings.TrimSpace(agentOptionsJSON) == "" {
+		return ""
+	}
+	if err := json.Unmarshal([]byte(agentOptionsJSON), &opts); err != nil {
+		return ""
+	}
+	return strings.TrimSpace(opts.SessionID)
+}
+
 func extractConfigOverrides(agentOptionsJSON string) map[string]string {
 	var opts struct {
 		ConfigOverrides map[string]any `json:"configOverrides"`

docs/ACCEPTANCE.md

@@ -282,3 +282,25 @@ This checklist defines executable acceptance checks for requirements 1-16.
   - `go test ./cmd/ngent -count=1`
   - `cd internal/webui/web && npm run build`
   - `go test ./...`
+
+## Requirement 23: ACP Session Sidebar and Resume
+
+- Operation:
+  - create a thread/agent in the Web UI or API.
+  - query `GET /v1/threads/{threadId}/sessions` and verify the first page of ACP sessions plus `nextCursor`.
+  - request the next page through the returned cursor.
+  - start a turn on a thread without `sessionId` and observe session binding.
+  - start a follow-up turn on the now-bound thread.
+- Expected:
+  - the backend proxies ACP `session/list` through `GET /v1/threads/{threadId}/sessions`.
+  - response includes `supported`, `sessions`, and `nextCursor`.
+  - the Web UI renders a right-side session sidebar with:
+    - first-page load on active thread selection.
+    - `Show more` pagination when `nextCursor` is present.
+    - `New session` action that clears the selected `sessionId`.
+  - turn SSE emits `session_bound`, and the thread persists `agentOptions.sessionId`.
+  - once a thread is session-bound, subsequent prompt building no longer injects prior local turns into the provider prompt.
+- Verification commands (executed 2026-03-11):
+  - `go test ./internal/httpapi -run 'TestThreadSessionsListEndpoint|TestTurnSessionBoundPersistsSessionIDAndSkipsContextInjection' -count=1`
+  - `cd internal/webui/web && npm run build`
+  - `go test ./...`

docs/DECISIONS.md

@@ -714,3 +714,50 @@ Use this template for new decisions.
   - always log ACP payloads at info level (rejected: too noisy and unsafe for normal operation).
   - add per-provider bespoke debug flags (rejected: fragmented UX and duplicated plumbing).
   - expose raw unredacted ACP dumps (rejected: conflicts with repository logging/redaction requirements).
+
+## ADR-036: Persist thread-level ACP session selection and resume through provider sessions
+
+- Status: Accepted
+- Date: 2026-03-11
+- Context:
+  - users need to browse an agent's historical ACP sessions and continue a conversation from an existing provider-owned session.
+  - hub threads already persist local turn history, but blindly injecting that history into prompts duplicates context once ACP `session/load` has restored the provider's own transcript.
+  - the frontend needs paginated session discovery and a lightweight way to switch between "new session" and "existing session" without changing the SQLite schema.
+- Decision:
+  - persist the selected ACP session id in `threads.agent_options_json` as `sessionId`.
+  - expose `GET /v1/threads/{threadId}/sessions` backed by ACP `session/list`, using a fresh provider instance so sidebar discovery does not disturb cached turn runtimes.
+  - extend built-in providers to:
+    - load `sessionId` through ACP `session/load` when present.
+    - create a fresh session through `session/new` otherwise.
+    - report the effective session id back during turn setup so the server can persist it and emit SSE `session_bound`.
+  - once `sessionId` is present on a thread, skip local recent-turn prompt injection and rely on ACP session state for continuation.
+  - keep Web UI session selection as a thread metadata mutation (`PATCH /v1/threads/{threadId}`) and model the "New session" action as clearing `sessionId`.
+- Consequences:
+  - session continuation survives provider restart/server restart when the agent supports ACP `session/load`.
+  - right-sidebar session browsing stays paginated (`nextCursor`/`Show more`) and does not require schema changes.
+  - local SQLite history remains a hub-local view and is no longer the source of truth for resumed ACP context on bound threads.
+  - historical ACP transcript import is deferred and tracked separately as a known limitation.
+- Alternatives considered:
+  - import the full ACP transcript from `session/load` into SQLite immediately (rejected: larger behavioral change, requires reliable transcript reconstruction).
+  - keep relying on hub prompt injection even after binding to an ACP session (rejected: duplicates already-restored conversation context).
+  - add a dedicated sessions table instead of reusing `agentOptions` JSON (rejected: unnecessary schema churn for a single thread-scoped selection value).
+
+## ADR-037: Scope Web UI chat playback to the selected ACP session
+
+- Status: Accepted
+- Date: 2026-03-11
+- Context:
+  - the Web UI session sidebar switches `agentOptions.sessionId` on the active thread without changing `threadId`.
+  - local history remains stored per thread, and each turn's effective ACP session is persisted through the `session_bound` event stream.
+  - refreshing the chat area only on thread changes leaves stale messages visible after choosing a different session from the sidebar.
+- Decision:
+  - treat `(threadId, sessionId)` as the client-side chat render scope.
+  - when the active thread's selected session changes outside an active turn, rebuild the chat area and reload history for that scope.
+  - filter locally persisted turns by their `session_bound` event so the center chat panel renders only turns recorded for the selected session; an empty `sessionId` shows only unbound turns.
+- Consequences:
+  - clicking a session in the sidebar replays that session's ngent-recorded turns instead of keeping the previously rendered session on screen.
+  - session changes reported during a live turn do not wipe the streaming bubble; the full refresh is deferred until the turn finishes.
+  - transcript content that predates ngent participation is still not imported from the provider and remains covered by KI-021.
+- Alternatives considered:
+  - add a session-scoped history endpoint immediately (rejected: larger server contract change while turn events already contain the session discriminator).
+  - keep all thread turns visible regardless of selected session (rejected: does not meet the expected session playback behavior).

docs/KNOWN_ISSUES.md

@@ -189,3 +189,12 @@
 - Follow-up plan:
   - add richer preflight diagnostics for Kimi auth/runtime readiness beyond PATH existence.
   - keep validating future Kimi CLI releases and narrow the fallback path once upstream command syntax stabilizes.
+
+- ID: KI-021
+- Title: Resumed ACP sessions do not backfill prior transcript into hub history
+- Status: Open
+- Severity: Medium
+- Affects: threads that select an existing ACP `sessionId` from the Web UI/API
+- Symptom: after choosing an existing session, ngent resumes context through ACP `session/load`, but the center chat/history panel still shows only turns created through ngent itself; earlier provider-owned transcript is not imported into SQLite or rendered in the chat area.
+- Workaround: select the target session before starting new hub turns, and rely on the provider's restored context for continuity even though older messages are not shown locally.
+- Follow-up plan: evaluate reconstructing/importing transcript data from `session/load` replayed `session/update` events into local hub history without duplicating future turns.

docs/SPEC.md

@@ -374,3 +374,59 @@ and upstream ACP schema:
 - Limitation:
   - this is a compatibility fallback, not full interactive tool-user-input UX.
   - multi-question/multi-select semantics and arbitrary free-text answers are not yet exposed through hub APIs/UI.
+
+## 15. ACP Session Sidebar and Resume (2026-03-11)
+
+### 15.1 Thread Metadata
+
+- `threads.agent_options_json` now may contain:
+  - `modelId`
+  - `configOverrides`
+  - `sessionId`
+- `sessionId` is optional and represents the selected provider-owned ACP session that the thread should resume.
+
+### 15.2 Backend API
+
+- New endpoint: `GET /v1/threads/{threadId}/sessions`
+  - ownership/tenancy matches existing thread endpoints.
+  - query string:
+    - `cursor` (optional): forwarded to ACP `session/list`.
+  - response:
+    - `threadId`
+    - `supported`
+    - `sessions`
+    - `nextCursor`
+- Session selection remains a normal thread metadata update:
+  - `PATCH /v1/threads/{threadId}` with `agentOptions.sessionId="<existing>"` binds an existing ACP session.
+  - `PATCH /v1/threads/{threadId}` with `agentOptions.sessionId` omitted/empty clears the binding and means "create a new session on next turn".
+
+### 15.3 Provider Behavior
+
+- Built-in providers parse ACP initialize capabilities and distinguish:
+  - `session/list` availability for sidebar discovery.
+  - `session/load` availability for actual session resume.
+- Turn setup:
+  - if thread `sessionId` is present, provider calls ACP `session/load`.
+  - otherwise provider calls ACP `session/new`.
+  - provider reports the effective session id back through a thread-scoped callback.
+- HTTP turn handling persists the bound session id back into `threads.agent_options_json` and emits SSE `session_bound`.
+
+### 15.4 Prompt Construction
+
+- For threads without `sessionId`, prompt construction remains unchanged:
+  - inject rolling summary + recent visible turns + current user input.
+- For threads with `sessionId`, prompt construction returns only the current user input.
+  - rationale: ACP `session/load` already restored the provider's own transcript, so reinjecting hub-local turns would duplicate context.
+
+### 15.5 Web UI
+
+- Layout:
+  - left sidebar: thread/agent list.
+  - center: chat.
+  - right sidebar: session list for the active thread.
+- Session sidebar behavior:
+  - loads the first page automatically when a thread becomes active.
+  - shows `Show more` when `nextCursor` is present.
+  - highlights the currently selected `sessionId`.
+  - offers `New session` to clear `sessionId`.
+  - refreshes after turns complete so newly created/bound sessions appear in the list.

go.mod

@@ -3,7 +3,7 @@ module github.com/beyond5959/ngent
 go 1.24
 
 require (
-	github.com/beyond5959/acp-adapter v0.1.1-0.20260309073758-eaebd1bcc076
+	github.com/beyond5959/acp-adapter v0.3.0
 	github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e
 	modernc.org/sqlite v1.18.2
 )

go.sum

@@ -1,5 +1,5 @@
-github.com/beyond5959/acp-adapter v0.1.1-0.20260309073758-eaebd1bcc076 h1:0Q7e/2W8gKrOGddyStzalOAtCjB6Qpomu2epFQjdNk8=
-github.com/beyond5959/acp-adapter v0.1.1-0.20260309073758-eaebd1bcc076/go.mod h1:cr4I+9+la75oUge+Pr97KlcdQrkwIG6VwWHbc9ALxSE=
+github.com/beyond5959/acp-adapter v0.3.0 h1:g9LHARs5jHgtPOP9lEfWQYYlbwE9NHmz4QfU8k6jldo=
+github.com/beyond5959/acp-adapter v0.3.0/go.mod h1:cr4I+9+la75oUge+Pr97KlcdQrkwIG6VwWHbc9ALxSE=
 github.com/dustin/go-humanize v1.0.0 h1:VSnTsYCnlFHaM2/igO1h6X3HA71jcobQuxemgkq4zYo=
 github.com/dustin/go-humanize v1.0.0/go.mod h1:HtrtbFcZ19U5GC7JDqmcUSB87Iq5E25KnS6fMYU6eOk=
 github.com/google/go-cmp v0.5.3 h1:x95R7cp+rSeeqAMI2knLtQ0DKlaBhv2NrtrOvafPHRo=

internal/agents/acpsession/session.go

@@ -0,0 +1,91 @@
+package acpsession
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/beyond5959/ngent/internal/agents"
+)
+
+// Capabilities describes ACP session support discovered during initialize.
+type Capabilities struct {
+	CanList bool
+	CanLoad bool
+}
+
+// ParseInitializeCapabilities extracts ACP session capabilities from initialize.
+func ParseInitializeCapabilities(raw json.RawMessage) Capabilities {
+	var payload struct {
+		AgentCapabilities map[string]json.RawMessage `json:"agentCapabilities"`
+	}
+	if len(raw) == 0 || json.Unmarshal(raw, &payload) != nil {
+		return Capabilities{}
+	}
+
+	caps := Capabilities{}
+	if enabledFeature(payload.AgentCapabilities["loadSession"]) {
+		caps.CanLoad = true
+	}
+
+	var sessionCaps map[string]json.RawMessage
+	if rawSessionCaps, ok := payload.AgentCapabilities["sessionCapabilities"]; ok {
+		_ = json.Unmarshal(rawSessionCaps, &sessionCaps)
+	}
+	if enabledFeature(sessionCaps["list"]) {
+		caps.CanList = true
+	}
+	if enabledFeature(sessionCaps["load"]) || enabledFeature(sessionCaps["resume"]) {
+		caps.CanLoad = true
+	}
+	return caps
+}
+
+// ParseSessionListResult decodes one ACP session/list result payload.
+func ParseSessionListResult(raw json.RawMessage) (agents.SessionListResult, error) {
+	var payload struct {
+		Sessions []struct {
+			SessionID string         `json:"sessionId"`
+			CWD       string         `json:"cwd"`
+			Title     string         `json:"title"`
+			UpdatedAt string         `json:"updatedAt"`
+			Meta      map[string]any `json:"_meta"`
+		} `json:"sessions"`
+		NextCursor string `json:"nextCursor"`
+	}
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		return agents.SessionListResult{}, fmt.Errorf("decode session/list result: %w", err)
+	}
+
+	result := agents.SessionListResult{
+		NextCursor: strings.TrimSpace(payload.NextCursor),
+		Sessions:   make([]agents.SessionInfo, 0, len(payload.Sessions)),
+	}
+	for _, session := range payload.Sessions {
+		result.Sessions = append(result.Sessions, agents.SessionInfo{
+			SessionID: session.SessionID,
+			CWD:       session.CWD,
+			Title:     session.Title,
+			UpdatedAt: session.UpdatedAt,
+			Meta:      session.Meta,
+		})
+	}
+	return agents.CloneSessionListResult(result), nil
+}
+
+func enabledFeature(raw json.RawMessage) bool {
+	raw = json.RawMessage(strings.TrimSpace(string(raw)))
+	if len(raw) == 0 {
+		return false
+	}
+	switch string(raw) {
+	case "null", "false", `""`:
+		return false
+	}
+
+	var boolValue bool
+	if err := json.Unmarshal(raw, &boolValue); err == nil {
+		return boolValue
+	}
+	return true
+}