@cloudflare/sandbox 0.13.0-next.651.1 → 0.13.0-next.709.1

package/dist/opencode/index.d.ts

@@ -1,14 +1,15 @@
-import { n as Sandbox } from "../sandbox-D_MMqExx.js";
-import "../rpc-types-PBUY-xXM.js";
-import { s as OpencodeStartupContext } from "../contexts-BS0Bs6IU.js";
+import { D as OpenCodeStartupContext } from "../contexts-1EsLHByO.js";
+import "../process-types-GStiZ8f8.js";
+import "../filesystem-BWAZCZER.js";
+import { c as SandboxExtension, l as SandboxLike } from "../index-Bs4bqXDR.js";
 import { OpencodeClient } from "@opencode-ai/sdk/v2/client";
 import { Config } from "@opencode-ai/sdk/v2";
 
-//#region src/opencode/types.d.ts
+//#region ../../extensions/opencode/src/types.d.ts
 /**
  * Configuration options for starting OpenCode server
  */
-interface OpencodeOptions {
+interface OpenCodeOptions {
   /** Port for OpenCode server (default: 4096) */
   port?: number;
   /** Working directory for OpenCode (default: container's cwd) */
@@ -21,7 +22,7 @@ interface OpencodeOptions {
 /**
  * Server lifecycle management
  */
-interface OpencodeServer {
+interface OpenCodeServer {
   /** Port the server is running on */
   port: number;
   /** Base URL for SDK client (http://localhost:{port}) */
@@ -29,182 +30,153 @@ interface OpencodeServer {
   /** Close the server gracefully */
   close(): Promise<void>;
 }
-/**
- * Result from createOpencode()
- * Client type comes from @opencode-ai/sdk (user's version)
- */
-interface OpencodeResult<TClient = OpencodeClient> {
-  /** OpenCode SDK client with Sandbox transport */
-  client: TClient;
-  /** Server lifecycle management */
-  server: OpencodeServer;
-}
 /**
  * Error thrown when OpenCode server fails to start
  */
-declare class OpencodeStartupError extends Error {
+declare class OpenCodeStartupError extends Error {
   readonly code: "OPENCODE_STARTUP_FAILED";
-  readonly context: OpencodeStartupContext;
-  constructor(message: string, context: OpencodeStartupContext, options?: ErrorOptions);
+  readonly context: OpenCodeStartupContext;
+  constructor(message: string, context: OpenCodeStartupContext, options?: ErrorOptions);
+}
+//#endregion
+//#region ../../extensions/opencode/src/opencode.d.ts
+interface OpenCodeSandboxLike extends SandboxLike {
+  exec: NonNullable<SandboxLike['exec']>;
+  getProcess: NonNullable<SandboxLike['getProcess']>;
+  listProcesses: NonNullable<SandboxLike['listProcesses']>;
+  containerFetch(request: Request, port: number): Promise<Response>;
 }
 //#endregion
-//#region src/opencode/opencode.d.ts
+//#region ../../extensions/opencode/src/lifecycle.d.ts
+/** Resolved server metadata that is safe to return across the RPC boundary. */
+interface OpenCodeServerInfo {
+  port: number;
+  url: string;
+}
+/** Snapshot of the resolved lifecycle configuration. */
+interface OpenCodeConfig {
+  port: number;
+  directory?: string;
+}
+/** Current server status as observed in the container. */
+interface OpenCodeStatus extends OpenCodeServerInfo {
+  running: boolean;
+}
 /**
- * Starts an OpenCode server inside a Sandbox container.
- *
- * This function manages the server lifecycle only - use `createOpencode()` if you
- * also need a typed SDK client for programmatic access.
- *
- * If an OpenCode server is already running on the specified port, this function
- * will reuse it instead of starting a new one.
- *
- * @param sandbox - The Sandbox instance to run OpenCode in
- * @param options - Configuration options
- * @returns Promise resolving to server handle { port, url, close() }
- *
- * @example
- * ```typescript
- * import { getSandbox } from '@cloudflare/sandbox'
- * import { createOpencodeServer } from '@cloudflare/sandbox/opencode'
- *
- * const sandbox = getSandbox(env.Sandbox, 'my-agent')
- * const server = await createOpencodeServer(sandbox, {
- *   directory: '/home/user/my-project',
- *   config: {
- *     provider: {
- *       anthropic: {
- *         options: { apiKey: env.ANTHROPIC_KEY }
- *       },
- *       // Or use Cloudflare AI Gateway (with unified billing, no provider keys needed).
- *       // 'cloudflare-ai-gateway': {
- *       //   options: {
- *       //     accountId: env.CF_ACCOUNT_ID,
- *       //     gatewayId: env.CF_GATEWAY_ID,
- *       //     apiToken: env.CF_API_TOKEN
- *       //   },
- *       //   models: { 'anthropic/claude-sonnet-4-5-20250929': {} }
- *       // }
- *     }
- *   }
- * })
- *
- * // Proxy requests to the web UI
- * return sandbox.containerFetch(request, server.port)
- *
- * // When done
- * await server.close()
- * ```
+ * The slice of `DurableObjectStorage` the handle uses to persist desired-state.
+ * Pass `this.ctx.storage` so the server config survives a Durable Object
+ * eviction (cold start) and is recovered lazily on the next `start()`.
  */
-declare function createOpencodeServer(sandbox: Sandbox<unknown>, options?: OpencodeOptions): Promise<OpencodeServer>;
+interface OpenCodeStateStorage {
+  get<T>(key: string): Promise<T | undefined>;
+  put<T>(key: string, value: T): Promise<void>;
+}
+/** Options for {@link withOpenCode}: server defaults plus optional storage. */
+interface WithOpenCodeOptions extends OpenCodeOptions {
+  /** Persist desired-state here so it survives DO eviction. */
+  storage?: OpenCodeStateStorage;
+}
 /**
- * Creates an OpenCode server inside a Sandbox container and returns a typed SDK client.
- *
- * This function is API-compatible with OpenCode's own createOpencode(), but uses
- * Sandbox process management instead of Node.js spawn. The returned client uses
- * a custom fetch adapter to route requests through the Sandbox container.
- *
- * If an OpenCode server is already running on the specified port, this function
- * will reuse it instead of starting a new one.
+ * DO-resident lifecycle handle for an OpenCode server. Owns the durable
+ * `opencode serve` process: start/reuse, stop, status, and request proxying.
  *
- * @param sandbox - The Sandbox instance to run OpenCode in
- * @param options - Configuration options
- * @returns Promise resolving to { client, server }
+ * It extends {@link SandboxExtension}, so the DO stub exposes it as
+ * `sandbox.opencode` and method calls dispatch through `callExtension` — the
+ * same path the interpreter extension uses. `createOpenCodeClient` consumes the
+ * same handle from either the Worker stub or the in-DO object.
  *
- * @example
- * ```typescript
- * import { getSandbox } from '@cloudflare/sandbox'
- * import { createOpencode } from '@cloudflare/sandbox/opencode'
- *
- * const sandbox = getSandbox(env.Sandbox, 'my-agent')
- * const { client, server } = await createOpencode(sandbox, {
- *   directory: '/home/user/my-project',
- *   config: {
- *     provider: {
- *       anthropic: {
- *         options: { apiKey: env.ANTHROPIC_KEY }
- *       },
- *       // Or use Cloudflare AI Gateway (with unified billing, no provider keys needed).
- *       // 'cloudflare-ai-gateway': {
- *       //   options: {
- *       //     accountId: env.CF_ACCOUNT_ID,
- *       //     gatewayId: env.CF_GATEWAY_ID,
- *       //     apiToken: env.CF_API_TOKEN
- *       //   },
- *       //   models: { 'anthropic/claude-sonnet-4-5-20250929': {} }
- *       // }
- *     }
- *   },
- *   // Optional: Pass additional environment variables (e.g., for OTEL telemetry)
- *   env: {
- *     OTEL_EXPORTER_OTLP_ENDPOINT: 'http://127.0.0.1:4318',
- *     TRACEPARENT: '00-abc123-def456-01'
- *   }
- * })
- *
- * // Use the SDK client for programmatic access
- * const session = await client.session.create()
- *
- * // When done
- * await server.close()
- * ```
+ * The server starts lazily: nothing runs until `start()` (or `fetch()`, which
+ * calls it) is invoked. To start optimistically, call `opencode.start()` from
+ * your Sandbox subclass's `onStart`.
  */
-declare function createOpencode<TClient = OpencodeClient>(sandbox: Sandbox<unknown>, options?: OpencodeOptions): Promise<OpencodeResult<TClient>>;
+declare class OpenCodeHandle extends SandboxExtension {
+  #private;
+  constructor(sandbox: OpenCodeSandboxLike, defaults?: OpenCodeOptions, storage?: OpenCodeStateStorage, stateIndex?: number);
+  /**
+   * Start or reuse the OpenCode server, returning RPC-safe metadata. With no
+   * options it reuses the last-used config, recovering persisted desired-state
+   * after a cold start. Retries once on a transient `CONTAINER_UNAVAILABLE`
+   * (e.g. a rollout in flight).
+   */
+  start(options?: OpenCodeOptions): Promise<OpenCodeServerInfo>;
+  /** Stop the running server, if one was started through this handle. */
+  stop(): Promise<void>;
+  /** Report whether the named OpenCode server is currently running. */
+  status(): Promise<OpenCodeStatus>;
+  /** Snapshot of the resolved configuration the client builder reads. */
+  config(): Promise<OpenCodeConfig>;
+  /**
+   * Start the server then route a request into the container. This is the
+   * transport the SDK client's `fetch` adapter and the Worker proxy use, so it
+   * works identically from the Worker stub (one RPC hop) or in-DO (local).
+   */
+  fetch(request: Request): Promise<Response>;
+}
 /**
- * Proxy a request directly to the OpenCode server.
+ * Factory — attach as a field on a Sandbox subclass:
+ * `opencode = withOpenCode(this, { directory, config, storage: this.ctx.storage })`.
  *
- * Unlike `proxyToOpencode()`, this helper does not apply any web UI redirects
- * or query parameter rewrites. Use it for API/CLI traffic where raw request
- * forwarding is preferred.
+ * Pass `storage` to persist desired-state so the server is recovered after a DO
+ * eviction (cold start). The server starts lazily on first use.
  */
-declare function proxyToOpencodeServer(request: Request, sandbox: Sandbox<unknown>, server: OpencodeServer): Promise<Response>;
+declare function withOpenCode(sandbox: OpenCodeSandboxLike, options?: WithOpenCodeOptions): OpenCodeHandle;
+//#endregion
+//#region ../../extensions/opencode/src/client.d.ts
 /**
- * Proxy a request to the OpenCode web UI.
- *
- * This function handles the redirect and proxying only - you must start the
- * server separately using `createOpencodeServer()`.
+ * Build a typed OpenCode SDK client from a lifecycle handle.
  *
- * Specifically handles:
- * 1. Ensuring the `?url=` parameter is set (required for OpenCode's frontend to
- *    make API calls through the proxy instead of directly to localhost:4096)
- * 2. Proxying the request to the container
+ * Works against either the Worker stub (`sandbox.opencode`) or the in-DO object
+ * (`this.opencode`): it ensures the server through the handle, reads the stored
+ * config, and routes every request through `handle.fetch`. Because the handle
+ * owns `containerFetch`, this helper never touches sandbox transport directly.
  *
- * @param request - The incoming HTTP request
- * @param sandbox - The Sandbox instance running OpenCode
- * @param server - The OpenCode server handle from createOpencodeServer()
- * @returns Response from OpenCode or a redirect response
- *
- * @example
- * ```typescript
- * import { getSandbox } from '@cloudflare/sandbox'
- * import { createOpencodeServer, proxyToOpencode } from '@cloudflare/sandbox/opencode'
+ * The SDK is imported lazily so the peer dependency is only required when an
+ * OpenCode client is actually built.
+ */
+declare function createOpenCodeClient<TClient = OpencodeClient>(handle: OpenCodeHandle, options?: OpenCodeOptions): Promise<TClient>;
+//#endregion
+//#region ../../extensions/opencode/src/proxy.d.ts
+/** Configuration for {@link createOpenCodeProxy}. */
+interface OpenCodeProxyOptions {
+  /** Origin the OpenCode web UI should call back through. Defaults to the request origin. */
+  callbackOrigin?: string;
+}
+/**
+ * Proxy a request to the OpenCode web UI through a lifecycle handle.
  *
- * export default {
- *   async fetch(request: Request, env: Env) {
- *     const sandbox = getSandbox(env.Sandbox, 'opencode')
- *     const server = await createOpencodeServer(sandbox, {
- *       directory: '/home/user/project',
- *       config: {
- *         provider: {
- *           anthropic: {
- *             options: { apiKey: env.ANTHROPIC_KEY }
- *           },
- *           // Optional: Route all providers through Cloudflare AI Gateway
- *           'cloudflare-ai-gateway': {
- *             options: {
- *               accountId: env.CF_ACCOUNT_ID,
- *               gatewayId: env.CF_GATEWAY_ID,
- *               apiToken: env.CF_API_TOKEN
- *             }
- *           }
- *         }
- *       }
- *     })
- *     return proxyToOpencode(request, sandbox, server)
+ * For an initial HTML page load that still lacks the `?url=` parameter, returns
+ * a redirect that adds it (so the OpenCode frontend calls back through the
+ * proxy instead of `127.0.0.1:4096`). Every other request is routed through
+ * `handle.fetch`, which ensures the server is running before forwarding into the
+ * container.
+ */
+declare function proxyToOpenCodeUI(request: Request, handle: OpenCodeHandle, options?: OpenCodeProxyOptions): Response | Promise<Response>;
+/**
+ * Curried Worker fetch wrapper for OpenCode.
+ *
+ * `createOpenCodeProxy(resolve, options?)` captures a lazy per-request resolver
+ * for the OpenCode lifecycle handle (`sandbox.opencode`) and returns a function
+ * that wraps the user's worker entrypoint.
+ *
+ * The wrapped handler runs first. If it returns a 404 (or has no `fetch`), the
+ * request falls through to the OpenCode web-UI proxy — the redirect handshake
+ * for HTML loads and an ensure-then-forward into the container for everything
+ * else. A 404 from the user handler is the "not mine, proxy it" signal, so the
+ * handler only needs to own its own routes and `return new Response('Not
+ * found', { status: 404 })` for the rest.
+ *
+ * ```ts
+ * export default createOpenCodeProxy(
+ *   (env) => getSandbox(env.Sandbox, 'my-sandbox').opencode
+ * )({
+ *   async fetch(request, env) {
+ *     // handle your own routes, else:
+ *     return new Response('Not found', { status: 404 });
  *   }
- * }
+ * });
  * ```
  */
-declare function proxyToOpencode(request: Request, sandbox: Sandbox<unknown>, server: OpencodeServer): Response | Promise<Response>;
+declare function createOpenCodeProxy<Env>(resolve: (env: Env) => OpenCodeHandle, options?: OpenCodeProxyOptions): (handler: ExportedHandler<Env>) => ExportedHandler<Env>;
 //#endregion
-export { type OpencodeOptions, type OpencodeResult, type OpencodeServer, OpencodeStartupError, createOpencode, createOpencodeServer, proxyToOpencode, proxyToOpencodeServer };
+export { type OpenCodeConfig, OpenCodeHandle, type OpenCodeOptions, type OpenCodeProxyOptions, type OpenCodeServer, type OpenCodeServerInfo, OpenCodeStartupError, type OpenCodeStateStorage, type OpenCodeStatus, type WithOpenCodeOptions, createOpenCodeClient, createOpenCodeProxy, proxyToOpenCodeUI, withOpenCode };
 //# sourceMappingURL=index.d.ts.map

package/dist/opencode/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/opencode/types.ts","../../src/opencode/opencode.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;UAOiB,eAAA;EAAA;EAcA,IAAA,CAAA,EAAA,MAAA;EAaA;EAAyB,SAAA,CAAA,EAAA,MAAA;EAEhC;EAEA,MAAA,CAAA,EAzBC,MAyBD;EAAc;EAMX,GAAA,CAAA,EA7BL,MA6BK,CAAA,MAAA,EAAA,MAAqB,CAAA;;;;;AAAa,UAvB9B,cAAA,CAuB8B;;;;EC+QzB,GAAA,EAAA,MAAA;EACX;EACC,KAAA,EAAA,EDlSD,OCkSC,CAAA,IAAA,CAAA;;;;AAsEZ;;AACW,UDlWM,cCkWN,CAAA,UDlW+B,cCkW/B,CAAA,CAAA;EACC;EACc,MAAA,EDlWhB,OCkWgB;EAAf;EAAR,MAAA,EDhWO,cCgWP;;AA0BH;;;AAGU,cDvXG,oBAAA,SAA6B,KAAA,CCuXhC;EACC,SAAA,IAAA,EAAA,yBAAA;EAAR,SAAA,OAAA,EDtXwB,sBCsXxB;EAAO,WAAA,CAAA,OAAA,EAAA,MAAA,EAAA,OAAA,EDlXG,sBCkXH,EAAA,OAAA,CAAA,EDjXI,YCiXJ;AAmDV;;;;;;;ADhdA;AAcA;AAaA;;;;;AAUA;;;;;;;;;AC+QA;;;;;;AAwEA;;;;;;;;AA6BA;;;;;;;AAuDA;;;;;AAIsB,iBAhKA,oBAAA,CAgKA,OAAA,EA/JX,OA+JW,CAAA,OAAA,CAAA,EAAA,OAAA,CAAA,EA9JV,eA8JU,CAAA,EA7JnB,OA6JmB,CA7JX,cA6JW,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAxFA,yBAAyB,yBACpC,4BACC,kBACT,QAAQ,eAAe;;;;;;;;iBA0BV,qBAAA,UACL,kBACA,0BACD,iBACP,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmDK,eAAA,UACL,kBACA,0BACD,iBACP,WAAW,QAAQ"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../../extensions/opencode/src/types.ts","../../../../extensions/opencode/src/opencode.ts","../../../../extensions/opencode/src/lifecycle.ts","../../../../extensions/opencode/src/client.ts","../../../../extensions/opencode/src/proxy.ts"],"sourcesContent":[],"mappings":"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"}