@runappsai/sdk 0.0.0-stage → 0.3.0

package/src/chat.ts

@@ -0,0 +1,368 @@
+import type { Transport } from "./transport.js";
+import type { Usage } from "./types.js";
+import type { SDKEvents } from "./events.js";
+import { wrapEvents, wrapStream } from "./event-wrap.js";
+import { APIError } from "./errors.js";
+
+/* ------------------------------------------------------------------ */
+/* Request types                                                       */
+/* ------------------------------------------------------------------ */
+
+/**
+ * A single message in a chat conversation. Content is a string for plain
+ * text, or an array of `ContentPart` for multi-modal messages.
+ */
+export interface ChatMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string | ContentPart[] | null;
+  name?: string;
+  tool_call_id?: string;
+  tool_calls?: ChatToolCall[];
+}
+
+/** One block inside a multi-modal message content array.
+ *
+ * Multi-modal LLMs see content as a heterogeneous list — some mix
+ * text + images (gpt-4o, claude), some accept video frames or raw
+ * audio (Gemini 2.x). The shape mirrors OpenAI's chat completions
+ * schema and is forwarded verbatim to the gateway; unsupported
+ * variants are rejected server-side with a clear error rather than
+ * silently ignored. */
+export type ContentPart =
+  | { type: "text"; text: string }
+  | { type: "image_url"; image_url: { url: string; detail?: "auto" | "low" | "high" } }
+  | { type: "video_url"; video_url: { url: string } }
+  | { type: "audio_url"; audio_url: { url: string } };
+
+export interface ChatTool {
+  type: "function";
+  function: {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+  };
+}
+
+export interface StreamOptions {
+  include_usage: boolean;
+}
+
+/**
+ * Names of platform-executed tools the SDK can ask the gateway to run on
+ * its behalf during a chat completion.  When you set `server_tools` on a
+ * `ChatCompletionParams`, the gateway resolves each name to its tool
+ * schema, sends both server tools and your own `tools` (if any) to the
+ * model, then handles any server-tool calls itself — looping with the
+ * model until it produces a final answer.  Your code only sees the final
+ * response; you don't have to implement web search yourself.
+ *
+ * The whitelist is intentionally narrow.  For image, audio, file, and
+ * vision generation the SDK already exposes dedicated endpoints
+ * (`client.image.*`, `client.audio.*`, etc.) that callers should hit
+ * directly instead of paying for an LLM-in-the-middle.  Search-class
+ * tools live here because they need the model in the loop — "search →
+ * read result → fetch → answer" can't be expressed as a single call.
+ */
+export type ServerToolName = "web_search" | "web_fetch" | "twitter_search";
+
+/** Typed constants for {@link ServerToolName} so you get autocomplete. */
+export const ServerTools = {
+  WebSearch: "web_search",
+  WebFetch: "web_fetch",
+  TwitterSearch: "twitter_search",
+} as const;
+
+export interface ChatCompletionParams {
+  model: string;
+  messages: ChatMessage[];
+  temperature?: number;
+  top_p?: number;
+  max_tokens?: number;
+  stop?: string[];
+  frequency_penalty?: number;
+  presence_penalty?: number;
+  n?: number;
+  tools?: ChatTool[];
+  tool_choice?: unknown;
+  user?: string;
+  metadata?: Record<string, unknown>;
+  stream?: boolean;
+  stream_options?: StreamOptions;
+  /**
+   * Names of platform-executed tools — the gateway will run these for
+   * you and loop with the model until it produces a final answer.  Mix
+   * freely with your own `tools`: the model can call either; the
+   * platform handles the server ones, your code handles the rest.
+   */
+  server_tools?: ServerToolName[];
+  /**
+   * Maximum number of LLM round-trips the server-tool loop will make
+   * (default 5, hard cap 10).  Only meaningful when `server_tools` is
+   * set.  Tune up for chains like "search → fetch → answer", down for
+   * tighter cost guarantees.
+   */
+  max_server_iterations?: number;
+  /**
+   * One of the app's private prompts, kept out of the browser: the
+   * gateway reads `bundle.json (or .runapps/prompts/)<id>.md` from the app's bundle, fills
+   * `{{var}}` placeholders from `vars`, and prepends it as the system
+   * message. `template` sends the text inline instead — for a creator's
+   * local dev server, before a bundle exists; the gateway accepts it
+   * only from the app's creator.
+   */
+  prompt?: { id?: string; vars?: Record<string, unknown>; template?: string };
+  /** Pass-through for provider-specific knobs. */
+  [extra: string]: unknown;
+}
+
+/* ------------------------------------------------------------------ */
+/* Response types                                                      */
+/* ------------------------------------------------------------------ */
+
+export interface ChatToolCall {
+  index?: number;
+  id?: string;
+  type?: string;
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+
+export interface ChatChoiceMessage {
+  role: string;
+  content: string | null;
+  tool_calls?: ChatToolCall[];
+}
+
+export interface ChatChoice {
+  index: number;
+  message: ChatChoiceMessage;
+  finish_reason: string;
+}
+
+export interface ChatCompletion {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  choices: ChatChoice[];
+  usage: Usage;
+}
+
+export interface ChatChunkDelta {
+  role?: string;
+  content?: string;
+  tool_calls?: ChatToolCall[];
+}
+
+export interface ChatChunkChoice {
+  index: number;
+  delta: ChatChunkDelta;
+  finish_reason?: string | null;
+}
+
+export interface ChatCompletionChunk {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  choices: ChatChunkChoice[];
+  usage?: Usage;
+}
+
+/* ------------------------------------------------------------------ */
+/* Convenience builders                                                */
+/* ------------------------------------------------------------------ */
+
+export const userMessage = (content: string): ChatMessage =>
+  ({ role: "user", content });
+
+export const systemMessage = (content: string): ChatMessage =>
+  ({ role: "system", content });
+
+export const assistantMessage = (content: string): ChatMessage =>
+  ({ role: "assistant", content });
+
+export const toolResultMessage = (toolCallId: string, content: string): ChatMessage =>
+  ({ role: "tool", tool_call_id: toolCallId, content });
+
+export const userMessageParts = (...parts: ContentPart[]): ChatMessage =>
+  ({ role: "user", content: parts });
+
+export const textPart = (text: string): ContentPart => ({ type: "text", text });
+
+export const imagePart = (
+  url: string,
+  detail?: "auto" | "low" | "high",
+): ContentPart => ({
+  type: "image_url",
+  image_url: detail ? { url, detail } : { url },
+});
+
+/**
+ * Video content part. Only supported by chat models whose
+ * input_modalities includes `"video"` (currently Gemini 3.x). Other
+ * models 400 at the gateway. URL may be http(s) or a
+ * `data:video/mp4;base64,...` inline upload.
+ */
+export const videoPart = (url: string): ContentPart => ({
+  type: "video_url",
+  video_url: { url },
+});
+
+/**
+ * Audio content part. Only supported by chat models whose
+ * input_modalities includes `"audio"` (currently Gemini 3.x). Other
+ * models 400 at the gateway. URL may be http(s) or a
+ * `data:audio/wav;base64,...` inline upload.
+ */
+export const audioPart = (url: string): ContentPart => ({
+  type: "audio_url",
+  audio_url: { url },
+});
+
+/* ------------------------------------------------------------------ */
+/* Service                                                             */
+/* ------------------------------------------------------------------ */
+
+export class ChatService {
+  constructor(
+    private readonly transport: Transport,
+    private readonly events: SDKEvents,
+  ) {}
+
+  /**
+   * Create a chat completion (non-streaming).
+   *
+   * Streaming is forced off — pass `stream()` instead for incremental output.
+   */
+  async create(
+    params: ChatCompletionParams,
+    init?: { signal?: AbortSignal },
+  ): Promise<ChatCompletion> {
+    const body = { ...params, stream: false };
+    return wrapEvents(
+      this.events,
+      { model: params.model, capability: "text" },
+      () =>
+        this.transport.postJSON<ChatCompletion>(
+          "/v1/chat/completions",
+          body,
+          init,
+        ),
+      (r) => ({
+        totalTokens: r.usage?.completion_tokens,
+        costUSD: r.usage?.total_cost,
+        finishReason: r.choices?.[0]?.finish_reason,
+      }),
+    );
+  }
+
+  /**
+   * Create a streaming chat completion. Returns an async iterator over
+   * `ChatCompletionChunk`. The final chunk carries `usage` (token / cost
+   * totals) — `stream_options.include_usage` is set automatically.
+   *
+   * ```ts
+   * let cost = 0;
+   * for await (const chunk of client.chat.stream({ ... })) {
+   *   for (const c of chunk.choices) process.stdout.write(c.delta.content ?? "");
+   *   if (chunk.usage) cost = chunk.usage.total_cost;
+   * }
+   * ```
+   *
+   * Also fires `request:streamDelta` on `client.events` for each chunk
+   * that carried text — drives the badge's tokens/sec rate display.
+   */
+  async *stream(
+    params: ChatCompletionParams,
+    init?: { signal?: AbortSignal },
+  ): AsyncGenerator<ChatCompletionChunk, void, unknown> {
+    const body = {
+      ...params,
+      stream: true,
+      stream_options: params.stream_options ?? { include_usage: true },
+    };
+    const sourceGen = async function* (this: ChatService) {
+      const resp = await this.transport.postJSONStream(
+        "/v1/chat/completions",
+        body,
+        init,
+      );
+      if (!resp.body) {
+        throw new Error("runapps: streaming response had no body");
+      }
+      yield* parseSSE<ChatCompletionChunk>(resp.body);
+    }.bind(this);
+    yield* wrapStream(
+      this.events,
+      { model: params.model, capability: "text" },
+      sourceGen,
+      (chunk) => ({
+        deltaText: chunk.choices?.[0]?.delta?.content ?? "",
+        completionTokens: chunk.usage?.completion_tokens,
+        costUSD: chunk.usage?.total_cost,
+        finishReason: chunk.choices?.[0]?.finish_reason ?? undefined,
+      }),
+    );
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* SSE parsing                                                         */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Decode an `text/event-stream` body into a stream of parsed JSON chunks.
+ * Stops at the `[DONE]` sentinel. Lines that don't start with `data: ` are
+ * ignored (keep-alive comments, etc.).
+ */
+async function* parseSSE<T>(
+  body: ReadableStream<Uint8Array>,
+): AsyncGenerator<T, void, unknown> {
+  const decoder = new TextDecoder();
+  const reader = body.getReader();
+  let buffer = "";
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+
+      let nl: number;
+      while ((nl = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, nl).replace(/\r$/, "");
+        buffer = buffer.slice(nl + 1);
+        if (!line.startsWith("data: ")) continue;
+        const data = line.slice(6).trim();
+        if (data === "[DONE]") return;
+        if (!data) continue;
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(data);
+        } catch (e) {
+          throw new Error(
+            `runapps: decode stream chunk: ${(e as Error).message}`,
+          );
+        }
+        // The gateway reports mid-stream failures as an SSE error event
+        // (`data: {"error":{...}}`) followed by [DONE]. Such an event has no
+        // "choices", so without this it would surface as an empty chunk and
+        // the stream would end looking merely empty.
+        const err = (parsed as { error?: { code?: number; type?: string; message?: string } })
+          .error;
+        if (err) {
+          throw new APIError(
+            err.code ?? 0,
+            err.type ?? "upstream_error",
+            err.message ?? data,
+          );
+        }
+        yield parsed as T;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/client.ts

@@ -0,0 +1,250 @@
+import { Transport } from "./transport.js";
+import { ChatService } from "./chat.js";
+import { ModelsService } from "./models.js";
+import { ImageService } from "./image.js";
+import { AudioService } from "./audio.js";
+import { VideoService } from "./video.js";
+import { ComputerService } from "./computer.js";
+import { FilesService } from "./files.js";
+import { EmbeddingsService } from "./embeddings.js";
+import { BrowserAuth, type BrowserUser } from "./browser-auth.js";
+import { SDKEvents } from "./events.js";
+
+// The platform, not the bare gateway: personal rk_ keys are checked and
+// billed by www.runapps.ai, which forwards to the gateway. api.runapps.ai
+// only knows the gateway's own keys.
+const DEFAULT_BASE_URL = "https://www.runapps.ai";
+
+/**
+ * Auth strategy.
+ *
+ *   - `"static"` (default): use `apiKey` or `apiKeyResolver` directly.
+ *   - `"runapps"`: opt into the built-in browser auth flow that
+ *     handshakes with `https://www.runapps.ai/api/sdk/grant`.  No
+ *     external auth.js script needed; the SDK consumes the URL
+ *     fragment after the redirect-back, exposes `client.user` and
+ *     `client.signIn()`, and renders an identity badge.  Only useful
+ *     in browsers — in Node this falls back to throwing the same
+ *     "missing apiKey" error you'd get with no auth config.
+ */
+// "runapps" is the current name of the platform sign-in; "runjobs" is the
+// same thing under the name from before the rename.
+export type AuthProvider = "static" | "runapps" | "runjobs";
+
+export interface ClientOptions {
+  /** Static gateway API key (typically prefixed `gw-` / `rj_` / `rrt_`).
+   *  Required unless `apiKeyResolver` or `authProvider: "runapps"` is supplied. */
+  apiKey?: string;
+  /**
+   * Dynamic API key resolver.  See `AuthProvider` for the typical
+   * runapps.ai browser-bundle wiring.
+   *
+   * Wins over `apiKey` when both are supplied.
+   */
+  apiKeyResolver?: () => string | Promise<string>;
+  /**
+   * Auth strategy — defaults to `"static"`.  Pass `"runapps"` to
+   * activate the built-in browser auth flow against runapps.ai;
+   * baseURL defaults to `https://www.runapps.ai` in that mode.
+   */
+  authProvider?: AuthProvider;
+  /**
+   * Show the floating identity badge in `runjobs` auth mode.
+   * **Default `true`** — the badge is now a desktop-ball-style
+   * real-time activity indicator (LED dot + progress ring around
+   * the avatar + click-through popover with active calls / recent
+   * completions / session totals). Set `false` only when the
+   * bundle ships its own status UI and you don't want the platform
+   * badge in the corner.
+   */
+  showIdentityBadge?: boolean;
+  /**
+   * Which corner the identity badge floats in. Defaults to
+   * `"bottom-right"` — the canonical tray-app position. Switch to
+   * `"bottom-left"` when the bundle's own UI occupies the right
+   * gutter (e.g. a chat dock); the top corners are useful for
+   * fullscreen / portrait kiosk layouts.
+   *
+   * The popover anchors itself to the same corner — bottom-left
+   * badge → popover opens up + right of the badge; top-* badges →
+   * popover opens down. Each corner only nudges the CSS; the badge
+   * + popover content is identical.
+   */
+  badgePosition?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+  /**
+   * @deprecated Use `showIdentityBadge` instead.  Kept for back-compat;
+   * acts as `showIdentityBadge: !hideIdentityBadge` when set.
+   */
+  hideIdentityBadge?: boolean;
+  /**
+   * Pin the runapps.ai grant flow to a specific project (only used
+   * when `authProvider: "runapps"`).  When set, `/api/sdk/grant`
+   * receives `project_id=<value>` and mints an `rrt_*` resource
+   * token bound to THAT project — required for `client.files.*`
+   * calls from any origin that isn't a registered (origin, app)
+   * pair (e.g. a bundle running on `localhost:5173` during dev).
+   *
+   * Production bundles served from a registered origin can omit
+   * this; the gateway derives the project from the (origin, app)
+   * pair.
+   */
+  project?: string;
+  /** Override the default base URL, `https://www.runapps.ai` (the
+   *  platform: personal keys and app tokens are both accepted there). */
+  baseURL?: string;
+  /** Optional fetch override (e.g. node-fetch with custom agent). */
+  fetch?: typeof fetch;
+}
+
+/**
+ * Top-level RunApps SDK client.  Construct once, share across services.
+ *
+ * Browser bundle (resource projects on runapps.ai):
+ *
+ * ```html
+ * <script src="https://cdn.jsdelivr.net/npm/@runappsai/sdk/dist/sdk.umd.js"></script>
+ * <script>
+ *   const client = new RunApps.Client({ authProvider: "runapps" });
+ *   const res = await client.chat.create({
+ *     model: "gpt-4o-mini",
+ *     messages: [{ role: "user", content: "hello" }],
+ *   });
+ * </script>
+ * ```
+ *
+ * Node / server-side:
+ *
+ * ```ts
+ * import { RunApps } from "@runappsai/sdk";
+ * const client = new RunApps({ apiKey: process.env.RUNJOBS_API_KEY! });
+ * ```
+ */
+export class RunApps {
+  readonly chat: ChatService;
+  readonly models: ModelsService;
+  readonly image: ImageService;
+  readonly audio: AudioService;
+  readonly video: VideoService;
+  readonly computer: ComputerService;
+  readonly files: FilesService;
+  readonly embeddings: EmbeddingsService;
+
+  /**
+   * Browser auth helper, populated only when `authProvider: "runapps"`.
+   * Use `client.signIn()` and `client.user` for the common cases; the
+   * full instance is exposed for advanced flows (manual `onTokenChange`
+   * subscription, etc.).
+   */
+  readonly auth: BrowserAuth | null = null;
+
+  /**
+   * Runtime event bus for SDK-call telemetry. Every LLM-ish service
+   * (chat / embeddings / image / audio / video / computer) fires
+   * `request:start`, `request:streamDelta`, `request:end`, and
+   * `request:error` events here so UI overlays — like the bottom-right
+   * identity badge's activity ring — can render real-time state
+   * without business code threading anything through.
+   *
+   * Zero-cost when nobody subscribes (emit is a few property reads).
+   * Subscribe via `client.events.on("request:start", handler)` — the
+   * returned closure is the unsubscribe.
+   */
+  readonly events: SDKEvents = new SDKEvents();
+
+  constructor(options: ClientOptions = {}) {
+    const provider = options.authProvider ?? "static";
+    let apiKeyResolver = options.apiKeyResolver;
+    let baseURL = options.baseURL;
+    let onUnauthorized: (() => void) | undefined;
+
+    if (provider === "runapps" || provider === "runjobs") {
+      // The grant page (/api/sdk/grant) and the gateway both live on
+      // www.runapps.ai.  An explicit baseURL keeps control.
+      baseURL = baseURL ?? "https://www.runapps.ai";
+      // Badge default: SHOWN. The badge is now a real-time activity
+      // indicator (LED + ring + popover) — useful enough that we'd
+      // rather have the rare "I already have my own UI" bundle opt
+      // OUT with `showIdentityBadge: false` than have every bundle
+      // miss the live feedback by default. The legacy
+      // `hideIdentityBadge` flag still wins when set, for callers
+      // that explicitly suppressed the badge under the old default.
+      const showBadge =
+        options.showIdentityBadge !== undefined
+          ? options.showIdentityBadge
+          : options.hideIdentityBadge !== undefined
+            ? !options.hideIdentityBadge
+            : true;
+      const auth = new BrowserAuth({
+        origin: baseURL,
+        hideBadge: !showBadge,
+        // Pipe the shared event bus into BrowserAuth so the badge can
+        // render its real-time activity ring / LED / popover. Safe to
+        // pass even when the caller never subscribes — emit is a few
+        // property reads when nobody's listening.
+        events: this.events,
+        ...(options.badgePosition !== undefined && { badgePosition: options.badgePosition }),
+        ...(options.project !== undefined && { project: options.project }),
+      });
+      (this as { auth: BrowserAuth | null }).auth = auth;
+      // The browser auth resolver wins over any caller-supplied one
+      // because the auth flow owns token issuance + refresh from now on.
+      apiKeyResolver = auth.getToken;
+      // 401 from the gateway → token was revoked server-side (typically
+      // because the user unsubscribed in another tab).  Drop the cached
+      // token so the transport's auto-retry hits a fresh signIn() flow.
+      onUnauthorized = () => auth.invalidate();
+    }
+
+    if (!options.apiKey && !apiKeyResolver) {
+      throw new Error(
+        "runapps: pass either `apiKey`, `apiKeyResolver`, or `authProvider: \"runapps\"`",
+      );
+    }
+    const transport = new Transport({
+      baseURL: baseURL ?? DEFAULT_BASE_URL,
+      ...(options.apiKey !== undefined && { apiKey: options.apiKey }),
+      ...(apiKeyResolver !== undefined && { apiKeyResolver }),
+      ...(onUnauthorized !== undefined && { onUnauthorized }),
+      ...(options.fetch ? { fetchImpl: options.fetch } : {}),
+    });
+    // Service constructors receive the shared event bus so each call
+    // path (chat/embeddings/image/audio/video/computer) can emit
+    // start/end/error around its network operations. Files and Models
+    // intentionally don't take it — they're infrastructure, not
+    // user-facing LLM calls, and surfacing them would clutter the
+    // badge with /v1/models polls.
+    this.chat = new ChatService(transport, this.events);
+    this.models = new ModelsService(transport);
+    this.image = new ImageService(transport, this.events);
+    this.audio = new AudioService(transport, this.events);
+    this.video = new VideoService(transport, this.events);
+    this.computer = new ComputerService(transport, this.events);
+    // `project` also scopes the file URLs (/v1/p/<project>/files/...),
+    // so two apps never issue byte-identical file requests.  Omitted →
+    // legacy unscoped /v1/files/... paths.
+    this.files = new FilesService(transport, options.project);
+    this.embeddings = new EmbeddingsService(transport, this.events);
+  }
+
+  /** Force a redirect to the runapps.ai grant page.  No-op in static
+   *  auth mode or in Node. */
+  signIn(): void {
+    this.auth?.signIn();
+  }
+
+  /**
+   * Clear the cached token + identity from memory and localStorage.
+   * The next API call will trigger sign-in again (redirect to grant
+   * page).  Wire this to a "Sign out" button in your settings UI.
+   *
+   * No-op in static auth mode or in Node.
+   */
+  signOut(): void {
+    this.auth?.signOut();
+  }
+
+  /** Currently-authenticated user (runapps auth mode), or null. */
+  get user(): BrowserUser | null {
+    return this.auth?.user ?? null;
+  }
+}

package/src/computer.ts

@@ -0,0 +1,80 @@
+import type { Transport } from "./transport.js";
+import type { Usage } from "./types.js";
+import type { SDKEvents } from "./events.js";
+import { wrapEvents } from "./event-wrap.js";
+
+/** Single-step computer-use request — a screenshot + history → next action(s). */
+export interface ComputerStepParams {
+  /**
+   * Conversation history including screenshots and tool results. Each
+   * entry has `role` + `content` (string or array of blocks). Format is
+   * intentionally opaque to support both Anthropic and OpenAI computer-use
+   * protocols — the gateway adapts.
+   */
+  messages: Record<string, unknown>[];
+  /** Screen resolution. Defaults to 1920×1080 if omitted. */
+  display_width?: number;
+  display_height?: number;
+  max_tokens?: number;
+  enable_zoom?: boolean;
+  /** OpenAI Responses-API state chaining. */
+  previous_response_id?: string;
+  /** Follow-up `computer_call_output` for OpenAI's Responses API. */
+  openai_input?: unknown;
+  user?: string;
+}
+
+/** One block of a computer-use response: text, tool_use (Anthropic), or computer_call (OpenAI). */
+export interface ComputerContentBlock {
+  type: string;
+  text?: string;
+  id?: string;
+  name?: string;
+  /** Anthropic tool input (raw JSON). */
+  input?: unknown;
+  call_id?: string;
+  /** OpenAI computer-call action. */
+  action?: Record<string, unknown>;
+}
+
+export interface ComputerResponse {
+  content: ComputerContentBlock[];
+  stop_reason?: string;
+  usage: Usage;
+  response_id?: string;
+  /** "anthropic" | "openai" — which protocol the upstream returned. */
+  protocol?: string;
+}
+
+export class ComputerService {
+  constructor(
+    private readonly transport: Transport,
+    private readonly events: SDKEvents,
+  ) {}
+
+  /**
+   * Execute one step of a computer-use agent loop. Given a screenshot
+   * and conversation history, returns the next action(s) the model
+   * wants the caller to execute.
+   */
+  async step(
+    model: string,
+    params: ComputerStepParams,
+    init?: { signal?: AbortSignal },
+  ): Promise<ComputerResponse> {
+    return wrapEvents(
+      this.events,
+      { model, capability: "computer_use" },
+      () =>
+        this.transport.postJSON<ComputerResponse>(
+          "/v1/computer/step",
+          { model, ...params },
+          init,
+        ),
+      (r) => ({
+        totalTokens: r.usage?.completion_tokens,
+        costUSD: r.usage?.total_cost,
+      }),
+    );
+  }
+}