Add eager Docker image pull on agent start (#6)

When the agent starts, it now begins pulling the workspace image in the
background. This prevents users from waiting for the image download when
creating their first workspace.

Features:
- Pulls image immediately when agent starts
- Retries every 20s if Docker isn't available yet
- Non-blocking - agent starts normally while pull happens
- Skips if local image already exists

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: gricha

src/agent/run.ts

@@ -6,6 +6,7 @@ import { HOST_WORKSPACE_NAME } from '../shared/types';
 import { DEFAULT_AGENT_PORT } from '../shared/constants';
 import { WorkspaceManager } from '../workspace/manager';
 import { containerRunning, getContainerName } from '../docker';
+import { startEagerImagePull } from '../docker/eager-pull';
 import { TerminalWebSocketServer } from '../terminal/websocket';
 import { ChatWebSocketServer } from '../chat/websocket';
 import { OpencodeWebSocketServer } from '../chat/opencode-websocket';
@@ -204,6 +205,8 @@ export async function startAgent(options: StartAgentOptions = {}): Promise<void>
     console.log(`[agent] WebSocket terminal: ws://localhost:${port}/rpc/terminal/:name`);
     console.log(`[agent] WebSocket chat (Claude): ws://localhost:${port}/rpc/chat/:name`);
     console.log(`[agent] WebSocket chat (OpenCode): ws://localhost:${port}/rpc/opencode/:name`);
+
+    startEagerImagePull();
   });
 
   const shutdown = () => {

src/docker/eager-pull.ts

@@ -0,0 +1,77 @@
+import { imageExists, tryPullImage, getDockerVersion } from './index';
+import { WORKSPACE_IMAGE_LOCAL, WORKSPACE_IMAGE_REGISTRY } from '../shared/constants';
+
+const RETRY_INTERVAL_MS = 20000;
+const MAX_RETRIES = 10;
+
+let pullInProgress = false;
+let pullComplete = false;
+
+async function isDockerAvailable(): Promise<boolean> {
+  try {
+    await getDockerVersion();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function pullWorkspaceImage(): Promise<boolean> {
+  const localExists = await imageExists(WORKSPACE_IMAGE_LOCAL);
+  if (localExists) {
+    console.log('[agent] Workspace image already available locally');
+    return true;
+  }
+
+  console.log(`[agent] Pulling workspace image from ${WORKSPACE_IMAGE_REGISTRY}...`);
+  const pulled = await tryPullImage(WORKSPACE_IMAGE_REGISTRY);
+
+  if (pulled) {
+    console.log('[agent] Workspace image pulled successfully');
+    return true;
+  }
+
+  console.log('[agent] Failed to pull image - will retry later or build on first workspace create');
+  return false;
+}
+
+export async function startEagerImagePull(): Promise<void> {
+  if (pullInProgress || pullComplete) {
+    return;
+  }
+
+  pullInProgress = true;
+
+  const attemptPull = async (attempt: number): Promise<void> => {
+    if (attempt > MAX_RETRIES) {
+      console.log('[agent] Max retries reached for image pull - giving up background pull');
+      pullInProgress = false;
+      return;
+    }
+
+    const dockerAvailable = await isDockerAvailable();
+
+    if (!dockerAvailable) {
+      if (attempt === 1) {
+        console.log('[agent] Docker not available - will retry in background');
+      }
+      setTimeout(() => attemptPull(attempt + 1), RETRY_INTERVAL_MS);
+      return;
+    }
+
+    const success = await pullWorkspaceImage();
+
+    if (success) {
+      pullComplete = true;
+      pullInProgress = false;
+    } else {
+      setTimeout(() => attemptPull(attempt + 1), RETRY_INTERVAL_MS);
+    }
+  };
+
+  attemptPull(1);
+}
+
+export function isImagePullComplete(): boolean {
+  return pullComplete;
+}