@banata-boxes/sdk 0.1.0 → 0.1.1

package/src/index.ts

@@ -84,6 +84,18 @@ export interface BillingInfo {
   };
 }
 
+export interface LaunchedBrowserSession {
+  cdpUrl: string;
+  sessionId: string;
+  previewViewerUrl: string | null;
+  close: () => Promise<void>;
+  getPreviewConnection: () => Promise<PreviewConnectionInfo | null>;
+  getPreviewViewerUrl: () => Promise<string | null>;
+  startPreview: () => Promise<PreviewCommandResponse>;
+  navigatePreview: (url: string) => Promise<PreviewCommandResponse>;
+  resizePreview: (size: { width?: number; height?: number }) => Promise<PreviewCommandResponse>;
+}
+
 export type WebhookEventType =
   | "session.created"
   | "session.assigned"
@@ -152,6 +164,76 @@ export interface RetryConfig {
   maxDelayMs?: number;
 }
 
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export interface PreviewConnectionInfo {
+  rawUrl: string;
+  token: string;
+  sessionId: string;
+  wsUrl: string;
+  startUrl: string;
+  navigateUrl: string;
+  resizeUrl: string;
+}
+
+export function buildPreviewViewerUrl(
+  connectionUrl: string | null | undefined,
+  appUrl: string = "https://boxes.banata.dev",
+): string | null {
+  if (!connectionUrl) {
+    return null;
+  }
+
+  try {
+    const parsed = new URL(connectionUrl);
+    const token = parsed.searchParams.get("token");
+    const session = parsed.searchParams.get("session");
+    const machine = parsed.searchParams.get("machine");
+    if (!token || !session) {
+      return null;
+    }
+
+    const backendProtocol =
+      parsed.protocol === "wss:"
+        ? "https:"
+        : parsed.protocol === "ws:"
+          ? "http:"
+          : parsed.protocol;
+    const viewerUrl = new URL("/preview", appUrl);
+    viewerUrl.searchParams.set("backend", `${backendProtocol}//${parsed.host}`);
+    viewerUrl.searchParams.set("token", token);
+    viewerUrl.searchParams.set("session", session);
+    if (machine) {
+      viewerUrl.searchParams.set("machine", machine);
+    }
+    return viewerUrl.toString();
+  } catch {
+    return null;
+  }
+}
+
+export interface PreviewCommandResponse<TPreview = unknown> {
+  ok: boolean;
+  preview?: TPreview;
+  [key: string]: unknown;
+}
+
+export interface OpenCodeConnectionInfo {
+  rawUrl: string;
+  token: string;
+  sessionId: string;
+  stateUrl: string;
+  messagesUrl: string;
+  promptUrl: string;
+  eventsUrl: string;
+}
+
 export class BanataError extends Error {
   /** HTTP status code (0 for network errors) */
   status: number;
@@ -189,15 +271,239 @@ function sleep(ms: number): Promise<void> {
   return new Promise((r) => setTimeout(r, ms));
 }
 
+function derivePreviewConnection(
+  rawUrl: string | null | undefined,
+): PreviewConnectionInfo | null {
+  if (!rawUrl) {
+    return null;
+  }
+
+  try {
+    const parsed = new URL(rawUrl);
+    const token = parsed.searchParams.get("token");
+    const sessionId = parsed.searchParams.get("session");
+    if (!token || !sessionId) {
+      return null;
+    }
+
+    const httpProtocol =
+      parsed.protocol === "https:" || parsed.protocol === "wss:"
+        ? "https:"
+        : "http:";
+    const wsProtocol =
+      parsed.protocol === "https:"
+        ? "wss:"
+        : parsed.protocol === "http:"
+          ? "ws:"
+          : parsed.protocol;
+    const search = `token=${encodeURIComponent(token)}&session=${encodeURIComponent(sessionId)}`;
+    const isDirectPreviewUrl =
+      parsed.pathname.endsWith("/ws") && parsed.pathname.includes("/preview/");
+
+    if (isDirectPreviewUrl) {
+      const basePath = parsed.pathname.slice(0, -3);
+      return {
+        rawUrl,
+        token,
+        sessionId,
+        startUrl: `${httpProtocol}//${parsed.host}${basePath}/start?${search}`,
+        navigateUrl: `${httpProtocol}//${parsed.host}${basePath}/navigate?${search}`,
+        resizeUrl: `${httpProtocol}//${parsed.host}${basePath}/resize?${search}`,
+        wsUrl: `${wsProtocol}//${parsed.host}${parsed.pathname}?${search}`,
+      };
+    }
+
+    return {
+      rawUrl,
+      token,
+      sessionId,
+      startUrl: `${httpProtocol}//${parsed.host}/preview/start?${search}`,
+      navigateUrl: `${httpProtocol}//${parsed.host}/preview/navigate?${search}`,
+      resizeUrl: `${httpProtocol}//${parsed.host}/preview/resize?${search}`,
+      wsUrl: `${wsProtocol}//${parsed.host}/preview/ws?${search}`,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function deriveOpenCodeConnection(
+  rawUrl: string | null | undefined,
+): OpenCodeConnectionInfo | null {
+  if (!rawUrl) {
+    return null;
+  }
+
+  try {
+    const parsed = new URL(rawUrl);
+    const token = parsed.searchParams.get("token");
+    const sessionId = parsed.searchParams.get("session");
+    if (!token || !sessionId) {
+      return null;
+    }
+
+    const httpProtocol =
+      parsed.protocol === "https:" || parsed.protocol === "wss:"
+        ? "https:"
+        : "http:";
+    const search = `token=${encodeURIComponent(token)}&session=${encodeURIComponent(sessionId)}`;
+
+    return {
+      rawUrl,
+      token,
+      sessionId,
+      stateUrl: `${httpProtocol}//${parsed.host}/opencode/state?${search}`,
+      messagesUrl: `${httpProtocol}//${parsed.host}/opencode/messages?${search}`,
+      promptUrl: `${httpProtocol}//${parsed.host}/opencode/prompt-async?${search}`,
+      eventsUrl: `${httpProtocol}//${parsed.host}/opencode/events?${search}`,
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function parseJsonResponse(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+async function requestPreviewEndpoint<T>(
+  url: string,
+  init: RequestInit,
+): Promise<T> {
+  const response = await fetch(url, init);
+  const payload = await parseJsonResponse(response);
+
+  if (!response.ok) {
+    const message =
+      payload && typeof payload === "object" && !Array.isArray(payload) && typeof (payload as Record<string, unknown>).error === "string"
+        ? String((payload as Record<string, unknown>).error)
+        : typeof payload === "string"
+          ? payload
+          : `Preview request failed (${response.status})`;
+    throw new BanataError(message, response.status);
+  }
+
+  return payload as T;
+}
+
+function shouldFallbackFromDirectConnection(error: unknown): boolean {
+  if (error instanceof BanataError) {
+    return error.status === 0 || error.status >= 500;
+  }
+
+  if (error instanceof Error) {
+    const maybeCause = error.cause as
+      | { code?: string; name?: string }
+      | undefined;
+    const code = maybeCause?.code;
+    return (
+      code === "ECONNRESET" ||
+      code === "ECONNREFUSED" ||
+      code === "ENOTFOUND" ||
+      code === "ETIMEDOUT" ||
+      code === "UND_ERR_CONNECT_TIMEOUT" ||
+      error.name === "TypeError"
+    );
+  }
+
+  return false;
+}
+
+function parseSseBlock(block: string): { type: string; data: JsonValue | string | null; raw: string } | null {
+  const trimmed = block.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  let eventType = "message";
+  const dataLines: string[] = [];
+
+  for (const line of trimmed.split(/\r?\n/)) {
+    if (line.startsWith("event:")) {
+      eventType = line.slice("event:".length).trim() || "message";
+      continue;
+    }
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice("data:".length).trimStart());
+    }
+  }
+
+  const rawData = dataLines.join("\n");
+  if (!rawData) {
+    return { type: eventType, data: null, raw: trimmed };
+  }
+
+  try {
+    return {
+      type: eventType,
+      data: JSON.parse(rawData) as JsonValue,
+      raw: trimmed,
+    };
+  } catch {
+    return {
+      type: eventType,
+      data: rawData,
+      raw: trimmed,
+    };
+  }
+}
+
+function isBrowserSessionOperationallyReady(
+  session: BrowserSession,
+): session is BrowserSession & { cdpUrl: string } {
+  return (
+    (session.status === "ready" || session.status === "active") &&
+    Boolean(session.cdpUrl)
+  );
+}
+
+function isSandboxSessionOperationallyReady(
+  session: SandboxSession,
+): boolean {
+  if (session.status !== "ready" && session.status !== "active") {
+    return false;
+  }
+
+  const browserMode = session.capabilities?.browser?.mode ?? "none";
+  if (browserMode !== "none") {
+    if (!session.pairedBrowser?.cdpUrl) {
+      return false;
+    }
+  }
+
+  if (session.capabilities?.opencode?.enabled) {
+    if (
+      !session.opencode ||
+      session.opencode.status === "failed" ||
+      session.opencode.status === "disabled"
+    ) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
 export class BrowserCloud {
   private apiKey: string;
   private baseUrl: string;
+  private appUrl: string;
   private retryConfig: Required<RetryConfig>;
 
-  constructor(config: { apiKey: string; baseUrl?: string; retry?: RetryConfig }) {
+  constructor(config: { apiKey: string; baseUrl?: string; appUrl?: string; retry?: RetryConfig }) {
     if (!config.apiKey) throw new Error('API key is required');
     this.apiKey = config.apiKey;
-    this.baseUrl = config.baseUrl ?? 'https://api.banata.dev';
+    this.baseUrl = config.baseUrl ?? 'https://api.boxes.banata.dev';
+    this.appUrl = config.appUrl ?? 'https://boxes.banata.dev';
     this.retryConfig = {
       maxRetries: config.retry?.maxRetries ?? 3,
       baseDelayMs: config.retry?.baseDelayMs ?? 500,
@@ -294,12 +600,13 @@ export class BrowserCloud {
   /** Create a new browser session */
   async createBrowser(config: BrowserConfig = {}): Promise<BrowserSession> {
     const { timeout, waitTimeoutMs, ...rest } = config;
+    const requestBody: Record<string, unknown> = { ...rest };
+    if (waitTimeoutMs !== undefined) {
+      requestBody.waitTimeoutMs = waitTimeoutMs;
+    }
     return this.request<BrowserSession>('/v1/browsers', {
       method: 'POST',
-      body: JSON.stringify({
-        ...rest,
-        waitTimeoutMs: waitTimeoutMs ?? timeout,
-      }),
+      body: JSON.stringify(requestBody),
     });
   }
 
@@ -317,6 +624,60 @@ export class BrowserCloud {
     });
   }
 
+  /** Derive the preview websocket/start endpoints for a live browser session. */
+  async getPreviewConnection(sessionId: string): Promise<PreviewConnectionInfo | null> {
+    const session = await this.getBrowser(sessionId);
+    return derivePreviewConnection(session.cdpUrl);
+  }
+
+  async getPreviewViewerUrl(sessionId: string): Promise<string | null> {
+    const session = await this.getBrowser(sessionId);
+    return buildPreviewViewerUrl(session.cdpUrl, this.appUrl);
+  }
+
+  /** Start the remote browser preview backend for a live browser session. */
+  async startPreview(sessionId: string): Promise<PreviewCommandResponse> {
+    const connection = await this.getPreviewConnection(sessionId);
+    if (!connection) {
+      throw new BanataError("Browser preview is not available for this session", 409);
+    }
+    return requestPreviewEndpoint<PreviewCommandResponse>(connection.startUrl, {
+      method: "POST",
+    });
+  }
+
+  /** Navigate the live browser preview session. */
+  async navigatePreview(
+    sessionId: string,
+    url: string,
+  ): Promise<PreviewCommandResponse> {
+    const connection = await this.getPreviewConnection(sessionId);
+    if (!connection) {
+      throw new BanataError("Browser preview is not available for this session", 409);
+    }
+    return requestPreviewEndpoint<PreviewCommandResponse>(connection.navigateUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ url }),
+    });
+  }
+
+  /** Resize the live browser preview session if the preview backend supports it. */
+  async resizePreview(
+    sessionId: string,
+    size: { width?: number; height?: number },
+  ): Promise<PreviewCommandResponse> {
+    const connection = await this.getPreviewConnection(sessionId);
+    if (!connection) {
+      throw new BanataError("Browser preview is not available for this session", 409);
+    }
+    return requestPreviewEndpoint<PreviewCommandResponse>(connection.resizeUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(size),
+    });
+  }
+
   /** Wait until session is ready and return CDP URL */
   async waitForReady(
     sessionId: string,
@@ -327,7 +688,7 @@ export class BrowserCloud {
     while (Date.now() - start < timeoutMs) {
       const session = await this.getBrowser(sessionId);
 
-      if ((session.status === 'ready' || session.status === 'active') && session.cdpUrl) {
+      if (isBrowserSessionOperationallyReady(session)) {
         return session.cdpUrl;
       }
       if (session.status === 'failed') {
@@ -361,32 +722,38 @@ export class BrowserCloud {
    */
   async launch(
     config: BrowserConfig = {}
-  ): Promise<{
-    cdpUrl: string;
-    sessionId: string;
-    close: () => Promise<void>;
-  }> {
+  ): Promise<LaunchedBrowserSession> {
     const session = await this.createBrowser(config);
     let cdpUrl: string;
-    try {
-      cdpUrl = await this.waitForReady(
-        session.id,
-        config.timeout ?? 30_000
-      );
-    } catch (err) {
-      // Clean up the orphaned session on timeout/failure
+    if (isBrowserSessionOperationallyReady(session)) {
+      cdpUrl = session.cdpUrl;
+    } else {
       try {
-        await this.closeBrowser(session.id);
-      } catch {
-        // Best-effort cleanup — session will be cleaned by stale cron
+        cdpUrl = await this.waitForReady(
+          session.id,
+          config.timeout ?? 30_000
+        );
+      } catch (err) {
+        try {
+          await this.closeBrowser(session.id);
+        } catch {
+          // Best-effort cleanup — session will be cleaned by stale cron
+        }
+        throw err;
       }
-      throw err;
     }
 
     return {
       cdpUrl,
       sessionId: session.id,
+      previewViewerUrl: buildPreviewViewerUrl(cdpUrl, this.appUrl),
       close: () => this.closeBrowser(session.id),
+      getPreviewConnection: () => this.getPreviewConnection(session.id),
+      getPreviewViewerUrl: () => this.getPreviewViewerUrl(session.id),
+      startPreview: () => this.startPreview(session.id),
+      navigatePreview: (url: string) => this.navigatePreview(session.id, url),
+      resizePreview: (size: { width?: number; height?: number }) =>
+        this.resizePreview(session.id, size),
     };
   }
 
@@ -456,7 +823,7 @@ export class BrowserCloud {
 export interface SandboxConfig {
   /** Sandbox runtime: bun, python, or base shell */
   runtime?: 'bun' | 'python' | 'base';
-  /** Sandbox size: small (512MB), medium (1GB), large (2GB) */
+  /** Sandbox size hint. The current hosted platform normalizes all sizes to the standard 4GB sandbox shape. */
   size?: 'small' | 'medium' | 'large';
   /** Environment variables to inject into the sandbox */
   env?: Record<string, string>;
@@ -472,7 +839,7 @@ export interface SandboxConfig {
   waitUntilReady?: boolean;
   /** Max time in ms for the API to wait before falling back to a queued response */
   waitTimeoutMs?: number;
-  /** Timeout in ms to wait for sandbox to become ready (default: 30000) */
+  /** Timeout in ms to wait for sandbox to become ready (default: 120000) */
   timeout?: number;
 }
 
@@ -488,6 +855,10 @@ export interface SandboxCapabilities {
     persistentProfile?: boolean;
     streamPreview?: boolean;
     humanInLoop?: boolean;
+    viewport?: {
+      width?: number;
+      height?: number;
+    };
   };
   documents?: {
     libreofficeHeadless?: boolean;
@@ -561,6 +932,17 @@ export interface SandboxBrowserPreviewState {
   updatedAt?: number;
 }
 
+export interface SandboxTaskReport {
+  result: string;
+  report: string;
+  url?: string;
+  stepsCompleted?: number;
+  actions?: string[];
+  durationMs?: number;
+  usage?: JsonValue;
+  completedAt: number;
+}
+
 export type SandboxHumanHandoffReason =
   | "mfa"
   | "captcha"
@@ -625,6 +1007,7 @@ export interface SandboxWorkerRuntimeState {
   pairedBrowser: SandboxPairedBrowser | null;
   artifacts: SandboxArtifacts | null;
   humanHandoff: SandboxHumanHandoffState | null;
+  lastTaskReport?: SandboxTaskReport | null;
 }
 
 export interface SandboxOpencodePromptResponse {
@@ -652,6 +1035,23 @@ export interface SandboxBrowserControlResponse {
   pairedBrowser: SandboxPairedBrowser | null;
 }
 
+export interface SandboxOpencodeStateResponse {
+  ok: boolean;
+  opencode: SandboxOpencodeState | null;
+}
+
+export interface SandboxOpencodeMessagesResponse {
+  ok: boolean;
+  sessionId: string | null;
+  messages: JsonValue;
+}
+
+export interface SandboxOpencodeStreamEvent {
+  type: string;
+  data: JsonValue | string | null;
+  raw: string;
+}
+
 export interface SandboxHumanHandoffResponse {
   ok: boolean;
   handoff: SandboxHumanHandoffState;
@@ -694,11 +1094,35 @@ export interface LaunchedSandbox {
       noReply?: boolean;
     },
   ) => Promise<SandboxOpencodePromptResponse>;
+  promptAsync: (
+    prompt: string,
+    options?: {
+      agent?: "build" | "plan";
+      sessionId?: string;
+    },
+  ) => Promise<SandboxOpencodePromptResponse>;
+  getOpencodeState: (options?: {
+    ensureSession?: boolean;
+    agent?: "build" | "plan";
+  }) => Promise<SandboxOpencodeStateResponse>;
+  getOpencodeConnection: () => Promise<OpenCodeConnectionInfo | null>;
+  listOpencodeMessages: (options?: {
+    sessionId?: string;
+  }) => Promise<SandboxOpencodeMessagesResponse>;
+  streamOpencodeEvents: (options?: {
+    sessionId?: string;
+  }) => AsyncGenerator<SandboxOpencodeStreamEvent, void, void>;
   checkpoint: () => Promise<SandboxCheckpointResponse>;
   getRuntime: () => Promise<SandboxRuntimeState>;
   getPreview: () => Promise<SandboxBrowserPreviewInfo>;
+  getPreviewConnection: () => Promise<PreviewConnectionInfo | null>;
+  getPreviewViewerUrl: () => Promise<string | null>;
+  startPreview: () => Promise<PreviewCommandResponse<SandboxBrowserPreviewState>>;
+  navigatePreview: (url: string) => Promise<PreviewCommandResponse<SandboxBrowserPreviewState>>;
+  resizePreview: (size: { width?: number; height?: number }) => Promise<PreviewCommandResponse<SandboxBrowserPreviewState>>;
   getHandoff: () => Promise<SandboxHumanHandoffInfo>;
   browserPreviewUrl: string | null;
+  browserPreviewViewerUrl: string | null;
   setControl: (
     mode: "ai" | "human" | "shared",
     options?: { controller?: string; leaseMs?: number },
@@ -745,12 +1169,14 @@ export interface SandboxRuntimeState {
   browserPreview: SandboxBrowserPreviewState | null;
   humanHandoff: SandboxHumanHandoffState | null;
   artifacts: SandboxArtifacts | null;
+  lastTaskReport?: SandboxTaskReport | null;
   runtime: SandboxWorkerRuntimeState | null;
 }
 
 export interface SandboxBrowserPreviewInfo {
   id: string;
   browserPreviewUrl: string | null;
+  browserPreviewViewerUrl: string | null;
   previewBaseUrl: string | null;
   browserPreview: SandboxBrowserPreviewState | null;
   humanHandoff: SandboxHumanHandoffState | null;
@@ -778,12 +1204,14 @@ export interface SandboxHumanHandoffInfo {
 export class BanataSandbox {
   private apiKey: string;
   private baseUrl: string;
+  private appUrl: string;
   private retryConfig: Required<RetryConfig>;
 
-  constructor(config: { apiKey: string; baseUrl?: string; retry?: RetryConfig }) {
+  constructor(config: { apiKey: string; baseUrl?: string; appUrl?: string; retry?: RetryConfig }) {
     if (!config.apiKey) throw new Error('API key is required');
     this.apiKey = config.apiKey;
-    this.baseUrl = config.baseUrl ?? 'https://api.banata.dev';
+    this.baseUrl = config.baseUrl ?? 'https://api.boxes.banata.dev';
+    this.appUrl = config.appUrl ?? 'https://boxes.banata.dev';
     this.retryConfig = {
       maxRetries: config.retry?.maxRetries ?? 3,
       baseDelayMs: config.retry?.baseDelayMs ?? 500,
@@ -879,12 +1307,13 @@ export class BanataSandbox {
   /** Create a new sandbox session */
   async create(config: SandboxConfig = {}): Promise<SandboxSession> {
     const { timeout, waitTimeoutMs, ...rest } = config;
+    const requestBody: Record<string, unknown> = { ...rest };
+    if (waitTimeoutMs !== undefined) {
+      requestBody.waitTimeoutMs = waitTimeoutMs;
+    }
     return this.request<SandboxSession>('/v1/sandboxes', {
       method: 'POST',
-      body: JSON.stringify({
-        ...rest,
-        waitTimeoutMs: waitTimeoutMs ?? timeout,
-      }),
+      body: JSON.stringify(requestBody),
     });
   }
 
@@ -911,14 +1340,14 @@ export class BanataSandbox {
   /** Wait until sandbox is ready and return the session */
   async waitForReady(
     id: string,
-    timeoutMs: number = 30_000
+    timeoutMs: number = 120_000
   ): Promise<SandboxSession> {
     const start = Date.now();
 
     while (Date.now() - start < timeoutMs) {
       const session = await this.get(id);
 
-      if (session.status === 'ready' || session.status === 'active') {
+      if (isSandboxSessionOperationallyReady(session)) {
         return session;
       }
       if (session.status === 'failed') {
@@ -1013,6 +1442,180 @@ export class BanataSandbox {
     );
   }
 
+  async getOpencodeState(
+    id: string,
+    options: {
+      ensureSession?: boolean;
+      agent?: "build" | "plan";
+    } = {},
+  ): Promise<SandboxOpencodeStateResponse> {
+    const connection = await this.getOpencodeConnection(id);
+    if (connection) {
+      try {
+        const url = new URL(connection.stateUrl);
+        if (options.ensureSession !== undefined) {
+          url.searchParams.set("ensureSession", String(options.ensureSession));
+        }
+        if (options.agent) {
+          url.searchParams.set("agent", options.agent);
+        }
+        return await requestPreviewEndpoint<SandboxOpencodeStateResponse>(url.toString(), {
+          method: "GET",
+        });
+      } catch (error) {
+        if (!shouldFallbackFromDirectConnection(error)) {
+          throw error;
+        }
+      }
+    }
+
+    const query = new URLSearchParams({ id });
+    if (options.ensureSession !== undefined) {
+      query.set("ensureSession", String(options.ensureSession));
+    }
+    if (options.agent) {
+      query.set("agent", options.agent);
+    }
+    return this.request<SandboxOpencodeStateResponse>(
+      `/v1/sandboxes/opencode/state?${query.toString()}`,
+    );
+  }
+
+  async getOpencodeConnection(id: string): Promise<OpenCodeConnectionInfo | null> {
+    const preview = await this.getPreview(id);
+    return deriveOpenCodeConnection(
+      preview.browserPreviewUrl ??
+        preview.browserPreview?.publicUrl ??
+        preview.pairedBrowser?.previewUrl ??
+        null,
+    );
+  }
+
+  async listOpencodeMessages(
+    id: string,
+    options: {
+      sessionId?: string;
+    } = {},
+  ): Promise<SandboxOpencodeMessagesResponse> {
+    const connection = await this.getOpencodeConnection(id);
+    if (connection) {
+      try {
+        const url = new URL(connection.messagesUrl);
+        if (options.sessionId) {
+          url.searchParams.set("opencodeSessionId", options.sessionId);
+        }
+        return await requestPreviewEndpoint<SandboxOpencodeMessagesResponse>(url.toString(), {
+          method: "GET",
+        });
+      } catch (error) {
+        if (!shouldFallbackFromDirectConnection(error)) {
+          throw error;
+        }
+      }
+    }
+
+    const query = new URLSearchParams({ id });
+    if (options.sessionId) {
+      query.set("sessionId", options.sessionId);
+    }
+    return this.request<SandboxOpencodeMessagesResponse>(
+      `/v1/sandboxes/opencode/messages?${query.toString()}`,
+    );
+  }
+
+  async *streamOpencodeEvents(
+    id: string,
+    options: {
+      sessionId?: string;
+    } = {},
+  ): AsyncGenerator<SandboxOpencodeStreamEvent, void, void> {
+    const connection = await this.getOpencodeConnection(id);
+    let response: Response;
+    if (connection) {
+      try {
+        const url = new URL(connection.eventsUrl);
+        if (options.sessionId) {
+          url.searchParams.set("opencodeSessionId", options.sessionId);
+        }
+        response = await fetch(url.toString(), {
+          method: "GET",
+        });
+      } catch (error) {
+        if (!shouldFallbackFromDirectConnection(error)) {
+          throw error;
+        }
+        const query = new URLSearchParams({ id });
+        if (options.sessionId) {
+          query.set("sessionId", options.sessionId);
+        }
+        response = await fetch(
+          `${this.baseUrl}/v1/sandboxes/opencode/events?${query.toString()}`,
+          {
+            method: "GET",
+            headers: this.headers,
+          },
+        );
+      }
+    } else {
+      const query = new URLSearchParams({ id });
+      if (options.sessionId) {
+        query.set("sessionId", options.sessionId);
+      }
+      response = await fetch(
+        `${this.baseUrl}/v1/sandboxes/opencode/events?${query.toString()}`,
+        {
+          method: "GET",
+          headers: this.headers,
+        },
+      );
+    }
+
+    if (!response.ok) {
+      const payload = await parseJsonResponse(response);
+      const message =
+        payload && typeof payload === "object" && !Array.isArray(payload) && typeof (payload as Record<string, unknown>).error === "string"
+          ? String((payload as Record<string, unknown>).error)
+          : typeof payload === "string"
+            ? payload
+            : `Failed to open OpenCode event stream (${response.status})`;
+      throw new BanataError(message, response.status);
+    }
+
+    if (!response.body) {
+      throw new BanataError("OpenCode event stream did not provide a response body", 502);
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffered = "";
+
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+
+        buffered += decoder.decode(value, { stream: true });
+        const blocks = buffered.split(/\r?\n\r?\n/);
+        buffered = blocks.pop() ?? "";
+
+        for (const block of blocks) {
+          const parsed = parseSseBlock(block);
+          if (parsed) {
+            yield parsed;
+          }
+        }
+      }
+
+      buffered += decoder.decode();
+      const trailing = parseSseBlock(buffered);
+      if (trailing) {
+        yield trailing;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
   async prompt(
     id: string,
     prompt: string,
@@ -1022,6 +1625,25 @@ export class BanataSandbox {
       noReply?: boolean;
     } = {},
   ): Promise<SandboxOpencodePromptResponse> {
+    const connection = await this.getOpencodeConnection(id);
+    if (connection) {
+      try {
+        return await requestPreviewEndpoint<SandboxOpencodePromptResponse>(connection.promptUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            prompt,
+            agent: options.agent,
+            sessionId: options.sessionId,
+          }),
+        });
+      } catch (error) {
+        if (!shouldFallbackFromDirectConnection(error)) {
+          throw error;
+        }
+      }
+    }
+
     return this.request<SandboxOpencodePromptResponse>('/v1/sandboxes/opencode/prompt', {
       method: 'POST',
       body: JSON.stringify({
@@ -1034,6 +1656,44 @@ export class BanataSandbox {
     });
   }
 
+  async promptAsync(
+    id: string,
+    prompt: string,
+    options: {
+      agent?: "build" | "plan";
+      sessionId?: string;
+    } = {},
+  ): Promise<SandboxOpencodePromptResponse> {
+    const connection = await this.getOpencodeConnection(id);
+    if (connection) {
+      try {
+        return await requestPreviewEndpoint<SandboxOpencodePromptResponse>(connection.promptUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            prompt,
+            agent: options.agent,
+            sessionId: options.sessionId,
+          }),
+        });
+      } catch (error) {
+        if (!shouldFallbackFromDirectConnection(error)) {
+          throw error;
+        }
+      }
+    }
+
+    return this.request<SandboxOpencodePromptResponse>('/v1/sandboxes/opencode/prompt-async', {
+      method: 'POST',
+      body: JSON.stringify({
+        id,
+        prompt,
+        agent: options.agent,
+        sessionId: options.sessionId,
+      }),
+    });
+  }
+
   async checkpoint(id: string): Promise<SandboxCheckpointResponse> {
     return this.request<SandboxCheckpointResponse>('/v1/sandboxes/checkpoint', {
       method: 'POST',
@@ -1058,9 +1718,69 @@ export class BanataSandbox {
   }
 
   async getPreview(id: string): Promise<SandboxBrowserPreviewInfo> {
-    return this.request<SandboxBrowserPreviewInfo>(
+    const preview = await this.request<SandboxBrowserPreviewInfo>(
       `/v1/sandboxes/browser-preview?id=${encodeURIComponent(id)}`
     );
+    return {
+      ...preview,
+      browserPreviewViewerUrl: buildPreviewViewerUrl(
+        preview.browserPreviewUrl,
+        this.appUrl,
+      ),
+    };
+  }
+
+  async getPreviewConnection(id: string): Promise<PreviewConnectionInfo | null> {
+    const preview = await this.getPreview(id);
+    return derivePreviewConnection(preview.browserPreviewUrl);
+  }
+
+  async getPreviewViewerUrl(id: string): Promise<string | null> {
+    const preview = await this.getPreview(id);
+    return (
+      preview.browserPreviewViewerUrl ??
+      buildPreviewViewerUrl(preview.browserPreviewUrl, this.appUrl)
+    );
+  }
+
+  async startPreview(id: string): Promise<PreviewCommandResponse<SandboxBrowserPreviewState>> {
+    const connection = await this.getPreviewConnection(id);
+    if (!connection) {
+      throw new BanataError("Sandbox browser preview is not available", 409);
+    }
+    return requestPreviewEndpoint<PreviewCommandResponse<SandboxBrowserPreviewState>>(connection.startUrl, {
+      method: "POST",
+    });
+  }
+
+  async navigatePreview(
+    id: string,
+    url: string,
+  ): Promise<PreviewCommandResponse<SandboxBrowserPreviewState>> {
+    const connection = await this.getPreviewConnection(id);
+    if (!connection) {
+      throw new BanataError("Sandbox browser preview is not available", 409);
+    }
+    return requestPreviewEndpoint<PreviewCommandResponse<SandboxBrowserPreviewState>>(connection.navigateUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ url }),
+    });
+  }
+
+  async resizePreview(
+    id: string,
+    size: { width?: number; height?: number },
+  ): Promise<PreviewCommandResponse<SandboxBrowserPreviewState>> {
+    const connection = await this.getPreviewConnection(id);
+    if (!connection) {
+      throw new BanataError("Sandbox browser preview is not available", 409);
+    }
+    return requestPreviewEndpoint<PreviewCommandResponse<SandboxBrowserPreviewState>>(connection.resizeUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(size),
+    });
   }
 
   async getHandoff(id: string): Promise<SandboxHumanHandoffInfo> {
@@ -1160,40 +1880,65 @@ export class BanataSandbox {
     const created = await this.create(config);
     let session: SandboxSession;
 
-    try {
-      session = await this.waitForReady(
-        created.id,
-        config.timeout ?? 30_000
-      );
-    } catch (err) {
-      // Clean up the orphaned sandbox on timeout/failure
+    if (isSandboxSessionOperationallyReady(created)) {
+      session = created;
+    } else {
       try {
-        await this.kill(created.id);
-      } catch {
-        // Best-effort cleanup
+        session = await this.waitForReady(
+          created.id,
+          config.timeout ?? 120_000
+        );
+      } catch (err) {
+        // Clean up the orphaned sandbox on timeout/failure
+        try {
+          await this.kill(created.id);
+        } catch {
+          // Best-effort cleanup
+        }
+        throw err;
       }
-      throw err;
     }
 
-    const sessionId = session.id;
-    const terminalUrl = session.terminalUrl ?? '';
-    const browserPreviewUrl =
-      session.browserPreview?.publicUrl ??
-      session.pairedBrowser?.previewUrl ??
-      null;
+      const sessionId = session.id;
+      const terminalUrl = session.terminalUrl ?? '';
+      const browserPreviewUrl =
+        session.browserPreview?.publicUrl ??
+        session.pairedBrowser?.previewUrl ??
+        null;
+      const browserPreviewViewerUrl = buildPreviewViewerUrl(
+        browserPreviewUrl,
+        this.appUrl,
+      );
 
     return {
       sessionId,
       terminalUrl,
       browserPreviewUrl,
+      browserPreviewViewerUrl,
       exec: (command: string, args?: string[]) =>
         this.exec(sessionId, command, args),
       runCode: (code: string) =>
         this.runCode(sessionId, code),
       prompt: (prompt, options) => this.prompt(sessionId, prompt, options),
+      promptAsync: (prompt, options) =>
+        this.promptAsync(sessionId, prompt, options),
+      getOpencodeState: (options) =>
+        this.getOpencodeState(sessionId, options),
+      getOpencodeConnection: () =>
+        this.getOpencodeConnection(sessionId),
+      listOpencodeMessages: (options) =>
+        this.listOpencodeMessages(sessionId, options),
+      streamOpencodeEvents: (options) =>
+        this.streamOpencodeEvents(sessionId, options),
       checkpoint: () => this.checkpoint(sessionId),
       getRuntime: () => this.getRuntime(sessionId),
       getPreview: () => this.getPreview(sessionId),
+      getPreviewConnection: () => this.getPreviewConnection(sessionId),
+      getPreviewViewerUrl: () => this.getPreviewViewerUrl(sessionId),
+      startPreview: () => this.startPreview(sessionId),
+      navigatePreview: (url: string) => this.navigatePreview(sessionId, url),
+      resizePreview: (size: { width?: number; height?: number }) =>
+        this.resizePreview(sessionId, size),
       getHandoff: () => this.getHandoff(sessionId),
       setControl: (mode, options) => this.setControl(sessionId, mode, options),
       takeControl: (options) => this.setControl(sessionId, "human", options),