kandev/docs/session-resumption-ll.md

Session Resumption LLD

Goals

• Support multiple active sessions per task.
• Resume sessions after backend restart without relying on user navigation.
• Distinguish resumable vs non-resumable agents (no resume_token).
• Keep session state consistent across backend, agentctl, and UI.
• Support local and remote executors.

Key Assumptions

• A session is the unit of execution; each session has at most one active agent execution.
• Task can have multiple sessions concurrently (active or historical).
• Agents that support session resumption provide a resume_token in session metadata.
• Agents that do not support resumption cannot resume after restart.
• Remote executors keep running across backend restarts; the backend must reconnect.

Data Model (existing + additions)

• task_sessions
  • id, task_id, state, agent_profile_id, agent_execution_id, metadata (includes resume_token)
  • worktree_id, worktree_path, worktree_branch
  • executor_id (local/remote)
• executors_running (persistent table)
  • id (executor instance id), session_id, task_id, runtime
  • agentctl_url, agentctl_port, container_id (docker), pid (local)
  • status: starting | ready | error | stopped
  • supports_session_resume, supports_workspace_only
  • resume_token
  • workspace_path, worktree_id, worktree_path, worktree_branch
  • last_seen_at, error_message
• executors_cache (in-memory only)
  • execution_id, session_id, runtime, status, agentctl_url/port, workspace_path

Note: agentctl state is derived from executors_running.status and health checks.

Agent Capability

• Add supports_session_resume boolean to agent registry or agent profile.
• When false, mark session as non-resumable on backend restart.
• UI should show: “This agent cannot resume previous sessions. Create a new session.”

Executor Types

• Local Docker: containers survive backend restart; recover via Docker APIs.
• Local Standalone: agentctl processes are local and typically do not survive restart.
• Remote Executor: agentctl runs remotely; survives backend restart; backend must reconnect.

Startup Flow (Backend)

Goal: recover agentctl instances from executors_running on backend start, not when a user opens a session.

1. Load executors

   • Query executors_running where status in (starting, ready).

2. Reject non-resumable executors

   • If supports_session_resume=false, mark related sessions ERROR and set error_message=not_resumable.

3. Resume executors by runtime

   • Local Docker:
     • Verify Docker daemon running.
     • Locate containers by executors_running.container_id or session label.
     • If container missing: mark executor error, mark sessions ERROR.
     • If container running: healthcheck agentctl.
   • Local Standalone:
     • Verify worktree path exists.
     • If missing: mark executor error, mark sessions ERROR.
     • Start agentctl process and healthcheck.
   • Remote Executor:
     • Call Health() on agentctl_url.
     • If unreachable: mark executor error, mark sessions ERROR.

4. Sync executor cache

   • Register running executions in executors_cache keyed by session_id.
   • Update executors_running.last_seen_at.

5. Enable workspace access

   • If agentctl is healthy, set executors_running.status=ready.
   • Shell/fs/git are enabled regardless of agent resume.

6. Resume agent session

   • If supports_session_resume=true and resume_token present, resume agent.
   • On success: set session.state = WAITING_FOR_INPUT.
   • On failure: set session.state = ERROR, update error_message.

7. Publish updates

   • Emit session agentctl events to UI.

Executor Resumption Capability

Executors should report whether agent session resume is supported by the runtime + agent, so the backend can decouple executor lifecycle from agent lifecycle.

Agentctl Capability Probe

After agentctl is reachable, call a capability endpoint (new or existing) to determine:

• supports_session_resume: whether the agent can resume with the session resumption token.
• supports_workspace_only: whether workspace-only mode is available (for git/fs/shell without agent).

Note: requires_new_session is redundant with supports_session_resume=false. If we keep it, it must be a derived/alias field, not an independent signal.

This allows:\n

• Executor resume (agentctl + workspace streams) even if agent resume is not possible.
• The UI to enable shell/git/files regardless of agent resumption outcome.

Session Resumption Flow (Backend)

Triggered when user explicitly requests resume.

1. Validate session:

   • Session exists and belongs to task.
   • Agent profile supports resume and session has resume_token.
   • Worktree exists if required.

2. Create agentctl instance (local only):

   • Call LaunchAgent with session_id, worktree_path, worktree_branch.
   • Persist executors_running.status=starting.

3. Start agent process and resume:

   • Resume agent session with resume_token.
   • On success:
     • session.state = WAITING_FOR_INPUT
     • executors_running.status = ready
     • task.state = REVIEW
   • On failure:
     • session.state = ERROR
     • executors_running.status = error
     • Persist error_message.

Session Status API

task.session.status

Return session-specific status (no task-level fallback):

• session_id, task_id, state, agent_profile_id
• executor_status, agent_execution_id, runtime
• is_agent_running (based on execution for that session)
• is_resumable (resume supported + resume_token present)
• needs_resume (no running execution + resumable)
• resume_reason (e.g., agent_not_running, not_resumable, missing_resume_token)
• worktree_path, worktree_branch

WebSocket Events

Session-scoped events:

• session.agentctl_starting
• session.agentctl_ready
• session.agentctl_error
• session.state_changed
• session.message.added, session.message.updated

Payloads must include session_id and task_id.

Frontend Flow

1. SSR page loads session + task + messages and hydrates store.
2. useSessionResumption
   • Calls task.session.status.
   • If needs_resume && is_resumable: show “Resume session” CTA or auto-resume (configurable).
   • If !is_resumable: show “Create new session” CTA.
3. UI states
   • executor_status=starting: show spinner and disable shell/file panels.
   • executor_status=ready: allow shell/file access.
   • executor_status=error: show error badge and retry/resume action.

Multi-Session per Task Considerations

• Executor and lifecycle manager must key executions by session_id (done).
• task.session.status must only check execution.SessionID == sessionID.
• WebSocket subscriptions should be per-session to avoid cross-session updates.

Non-Resumable Agents

• Add supports_session_resume=false in agent registry/profile.
• Backend returns is_resumable=false in status.
• UI displays a banner: “This agent doesn’t support resuming. Start a new session.”

Open Decisions

• Whether to keep executors_running lean or store full runtime metadata.
• Auto-resume on backend startup vs on-demand (current request: startup).
• Whether to auto-resume all resumable sessions or only those in RUNNING/WAITING_FOR_INPUT.
• Remote executor reconnect timeout/backoff policy.

Resumption Flow Diagrams

Local Docker Executor (agentctl container survives)

Backend Restart
  |
  |-- load executors_running (starting/ready)
  |-- docker: RecoverInstances()
  |        -> map container to executors_running.id or session_id label
  |-- agentctl Health()
  |-- agentctl Capabilities? (supports_session_resume)
  |-- register AgentExecution(session_id, runtime=local_docker)
  |-- executors_running.status = ready  (workspace-only enabled)
  |
  |-- if supports_session_resume & resume_token present:
  |       ResumeSession
  |       session.state = WAITING_FOR_INPUT
  |   else:
  |       session.state = ERROR (not_resumable)
  |
  '-- WS events to UI:
        session.agentctl_ready / session.state_changed

Local Standalone Executor (agentctl does NOT survive)

Backend Restart
  |
  |-- load executors_running (starting/ready)
  |-- no local instances to recover
  |-- LaunchAgent from executors_running (workspace-only)
  |-- executors_running.status = starting
  |-- agentctl Health()
  |-- agentctl Capabilities? (supports_session_resume)
  |-- executors_running.status = ready  (workspace-only enabled)
  |
  |-- if supports_session_resume & resume_token present:
  |       ResumeSession
  |       session.state = WAITING_FOR_INPUT
  |   else:
  |       session.state = ERROR (not_resumable)
  |
  '-- WS events to UI:
        session.agentctl_starting / ready / error

Remote Executor (agentctl survives remotely)

Backend Restart
  |
  |-- load executors_running: agentctl_url, id
  |-- connect to agentctl Health()
  |-- agentctl Capabilities? (supports_session_resume)
  |-- register AgentExecution(session_id, runtime=remote)
  |-- executors_running.status = ready  (workspace-only enabled)
  |
  |-- if supports_session_resume & resume_token present:
  |       ResumeSession
  |       session.state = WAITING_FOR_INPUT
  |   else:
  |       session.state = ERROR (not_resumable)
  |
  '-- WS events to UI:
        session.agentctl_ready / session.state_changed

Executor vs Agent Resumption

Separating executor resume from agent resume allows:

• Shell/git/files to function as soon as agentctl is reachable.
• Agent resume to fail gracefully without losing workspace access.

Example UI behavior:

1. session.agentctl_ready -> enable shell/git/files panels.
2. If supports_session_resume=false -> show “Create new session to continue messaging.”
3. If resume fails -> show error but keep workspace panels active.