session-containers

Session Containers & Runners

This skill covers Docker container management, session runners, idle disposal, and reconnection. For session creation/activation/switching, see the session-lifecycle skill.

Key Components

Component	Location	Role
SessionRunner	orchestrator/session-runner.ts	In-process implementation (test-only). Spawns agent/terminal directly
ContainerSessionRunner	orchestrator/container-session-runner.ts	Production implementation. Delegates to per-session Docker container via HTTP+SSE
SessionContainerManager	orchestrator/session-container.ts	Docker orchestration: create, destroy, health monitor, orphan cleanup
SessionRunnerRegistry	orchestrator/session-runner.ts	App-level map of session ID -> runner

Runner Lifecycle

SessionRunnerRegistry

• Maintains Map<string, SessionRunnerInterface> (session ID -> runner)
• getOrCreate(sessionId, sessionDir, agentId):
  1. Return existing non-disposed runner if found
  2. Call runner factory to create new runner
  3. Register "disposed" listener for auto-cleanup from map
  4. Wire runner.on("idle") -> onRunnerIdle(sessionId) callback
• get(sessionId): Returns runner if exists and not disposed
• Max 10 concurrent runners; evicts oldest idle runner if at capacity
• disposeAll(opts?) for graceful shutdown and full reset. Forced — it kills running agents unless the caller passes { preserveAgent: true }, which shutdown does and full reset does not

Runner Factory (Production)

buildRunnerFactory() (in app-lifecycle.ts) handles three cases, keyed on the container's current status. A pre-booted standby container (warm pool — see the session-lifecycle skill) shows up here as an existing container that is running or starting, so it's just a data condition on these same cases — there is no separate "warm" code path.

factory(opts):
  existing = containerManager.get(opts.sessionId)

  CASE 1: existing && status === "running"          (incl. a ready standby)
    -> mgr.claimStandby(sessionId)                  (clears standby flag if set)
    -> Reconnect: new ContainerSessionRunner({ workerUrl: existing.workerUrl })
    -> No container creation -- SSE replay delivers current state. Instant.

  CASE 2: existing && status === "starting"         (standby still booting)
    -> runner = new ContainerSessionRunner({ workerUrl: "http://0.0.0.0:0" })
    -> poll up to 30s (500ms): once running -> claimStandby + setWorkerUrl
       if it never becomes ready -> fall through to a fresh create
    (returns runner immediately; the poll runs in a fire-and-forget async block)

  CASE 3: no existing container, OR stale (stopping/stopped)
    -> runner = new ContainerSessionRunner({ workerUrl: "http://0.0.0.0:0" })
    -> createContainerForRunner({ destroyExisting: !!existing })
       (destroys the stale one first, then mgr.create + runner.setWorkerUrl)