# Agentctl session lifecycle (Kandev)

This document explains how **agentctl** fits into the Kandev execution flow, what “ready” means, and which parts of the system depend on agentctl being up.

## What agentctl is

`agentctl` is a sidecar process that runs inside each agent container (or standalone runtime). It provides:

- **HTTP API** for lifecycle operations (`/health`, `/api/v1/start`, `/api/v1/stop`, etc.)
- **ACP bridge** (stdin/stdout JSON‑RPC) to the agent process (Auggie/Codex/etc.)
- **WebSockets** for streaming ACP updates and agent output
- **Shell access** to the workspace (terminal output + input)

It is the backend’s *control plane* for an agent execution.

## High‑level flow (runtime‑agnostic)

```
User action (start task)
   |
   v
Kandev orchestrator
   |
   | 1) Create task session in DB
   | 2) Launch agent runtime (Docker or standalone)
   v
agentctl process starts
   |
   | 3) HTTP server comes up (health + control APIs)
   v
Backend waits for agentctl readiness
   |
   | 4) agentctl ready => shell/workspace access available
   v
ACP session initialization
   |
   | 5) initialize -> session/new or session/load
   | 6) prompt is sent
   v
Agent runs, ACP updates stream
   |
   | 7) session/update notifications => WS to client
   v
Task session state transitions
```

## “Ready” concepts (important distinction)

There are **two different “ready” moments**:

1) **agentctl ready**
   - Meaning: agentctl HTTP server is healthy and can accept requests.
   - Practical impact: shell/workspace endpoints become usable.
   - Source: `lifecycle.Manager.waitForAgentctlReady`.
   - Today: only logged; **not emitted as a WS event**.

2) **agent ready** (prompt completed)
   - Meaning: agent finished the current prompt and is idle/ready for follow‑up.
   - Source: `events.AgentReady` (after prompt completion).
   - Today: internal event for orchestrator state transitions.

The frontend should not rely on “agent ready” when it needs shell access; shell access depends on agentctl readiness instead.

## Current backend signals

- **agentctl readiness**
  - `agentctl is ready` (agentctl client log)
  - `agentctl ready - shell/workspace access available` (lifecycle manager log)

- **agent ready** (post‑prompt)
  - `events.AgentReady` internal event (used by orchestrator state transitions)

There is **no WS event** that tells the client “agentctl is ready.”

## Where shell streaming depends on agentctl

- Client calls `shell.subscribe` (WS request)
- Backend checks:
  - agent execution exists for the task
  - agentctl is connected
- Backend starts a streaming loop that relays agentctl shell output as `shell.output` WS notifications

If agentctl isn’t ready yet, `shell.subscribe` fails and the frontend currently retries.

## Suggested improvement (optional)

Introduce a WS notification like:

```
{ "action": "task.session.agentctl_ready", "payload": { "task_id": "...", "task_session_id": "..." } }
```

So the client can subscribe once and only request shell after it receives readiness.

## End‑to‑end diagram (detailed)

```
Client                      Backend (Kandev)                   agentctl                Agent
  |                                |                             |                      |
  | orchestrator.start             |                             |                      |
  |------------------------------->|                             |                      |
  |                                | create task session         |                      |
  |                                | launch runtime              |                      |
  |                                |---------------------------->| process starts       |
  |                                |                             | HTTP server up       |
  |                                | waitForAgentctlReady        |                      |
  |                                |---------------------------->| /health              |
  |                                |<----------------------------| 200 OK               |
  |                                | (agentctl ready)            |                      |
  |                                | ACP initialize              |                      |
  |                                |---------------------------->| initialize           |
  |                                | ACP session/new             |                      |
  |                                |---------------------------->| session/new          |
  |                                | ACP prompt                  |                      |
  |                                |---------------------------->| session/prompt       |
  |                                |                             |--------------------->|
  |                                |                             |  agent runs          |
  |                                | WS stream                   |                      |
  |<-------------------------------| (session/update notifications)                      |
```

## References

- `apps/backend/internal/agent/lifecycle/manager.go` (waitForAgentctlReady)
- `apps/backend/internal/agentctl/client/client.go` (WaitForReady)
- `apps/backend/internal/agent/handlers/shell_handlers.go` (shell.subscribe)
- `apps/backend/internal/events/types.go` (`AgentReady`)