@opencode-ai/sdk 0.1.0-alpha.14 → 0.1.0-alpha.16

package/src/client.ts

@@ -16,7 +16,16 @@ import * as Errors from './core/error';
 import * as Uploads from './core/uploads';
 import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
-import { App, AppInitResponse, AppResource } from './resources/app';
+import {
+  App,
+  AppInitResponse,
+  AppLogParams,
+  AppLogResponse,
+  AppModesResponse,
+  AppResource,
+  LogLevel,
+  Mode,
+} from './resources/app';
 import {
   Config,
   ConfigProvidersResponse,
@@ -28,7 +37,7 @@ import {
   Provider,
 } from './resources/config';
 import { Event, EventListResponse } from './resources/event';
-import { File, FileReadParams, FileReadResponse, FileStatusResponse } from './resources/file';
+import { File, FileReadParams, FileReadResponse, FileResource, FileStatusResponse } from './resources/file';
 import {
   Find,
   FindFilesParams,
@@ -37,12 +46,14 @@ import {
   FindSymbolsResponse,
   FindTextParams,
   FindTextResponse,
+  Match,
+  Symbol,
 } from './resources/find';
 import {
+  AssistantMessage,
   FilePart,
   Message,
-  MessagePart,
-  ReasoningPart,
+  Part,
   Session,
   SessionAbortResponse,
   SessionChatParams,
@@ -54,20 +65,22 @@ import {
   SessionResource,
   SessionSummarizeParams,
   SessionSummarizeResponse,
-  SourceURLPart,
+  StepFinishPart,
   StepStartPart,
   TextPart,
-  ToolCall,
-  ToolInvocationPart,
-  ToolPartialCall,
-  ToolResult,
+  ToolPart,
+  ToolStateCompleted,
+  ToolStateError,
+  ToolStatePending,
+  ToolStateRunning,
+  UserMessage,
 } from './resources/session';
 import { type Fetch } from './internal/builtin-types';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
 import { FinalRequestOptions, RequestOptions } from './internal/request-options';
 import { readEnv } from './internal/utils/env';
 import {
-  type LogLevel,
+  type LogLevel as ClientLogLevel,
   type Logger,
   formatRequestDetails,
   loggerFor,
@@ -89,6 +102,8 @@ export interface ClientOptions {
    *
    * Note that request timeouts are retried by default, so in a worst-case scenario you may wait
    * much longer than this timeout before the promise succeeds or fails.
+   *
+   * @unit milliseconds
    */
   timeout?: number | undefined;
   /**
@@ -133,7 +148,7 @@ export interface ClientOptions {
    *
    * Defaults to process.env['OPENCODE_LOG'] or 'warn' if it isn't set.
    */
-  logLevel?: LogLevel | undefined;
+  logLevel?: ClientLogLevel | undefined;
 
   /**
    * Set the logger.
@@ -151,7 +166,7 @@ export class Opencode {
   maxRetries: number;
   timeout: number;
   logger: Logger | undefined;
-  logLevel: LogLevel | undefined;
+  logLevel: ClientLogLevel | undefined;
   fetchOptions: MergedRequestInit | undefined;
 
   private fetch: Fetch;
@@ -198,7 +213,7 @@ export class Opencode {
    * Create a new client instance re-using the same options given to the current client with optional overriding.
    */
   withOptions(options: Partial<ClientOptions>): this {
-    return new (this.constructor as any as new (props: ClientOptions) => typeof this)({
+    const client = new (this.constructor as any as new (props: ClientOptions) => typeof this)({
       ...this._options,
       baseURL: this.baseURL,
       maxRetries: this.maxRetries,
@@ -209,6 +224,7 @@ export class Opencode {
       fetchOptions: this.fetchOptions,
       ...options,
     });
+    return client;
   }
 
   /**
@@ -354,7 +370,9 @@ export class Opencode {
 
     await this.prepareOptions(options);
 
-    const { req, url, timeout } = this.buildRequest(options, { retryCount: maxRetries - retriesRemaining });
+    const { req, url, timeout } = await this.buildRequest(options, {
+      retryCount: maxRetries - retriesRemaining,
+    });
 
     await this.prepareRequest(req, { url, options });
 
@@ -432,7 +450,7 @@ export class Opencode {
     } with status ${response.status} in ${headersTime - startTime}ms`;
 
     if (!response.ok) {
-      const shouldRetry = this.shouldRetry(response);
+      const shouldRetry = await this.shouldRetry(response);
       if (retriesRemaining && shouldRetry) {
         const retryMessage = `retrying, ${retriesRemaining} attempts remaining`;
 
@@ -531,7 +549,7 @@ export class Opencode {
     }
   }
 
-  private shouldRetry(response: Response): boolean {
+  private async shouldRetry(response: Response): Promise<boolean> {
     // Note this is not a standard header.
     const shouldRetryHeader = response.headers.get('x-should-retry');
 
@@ -608,10 +626,10 @@ export class Opencode {
     return sleepSeconds * jitter * 1000;
   }
 
-  buildRequest(
+  async buildRequest(
     inputOptions: FinalRequestOptions,
     { retryCount = 0 }: { retryCount?: number } = {},
-  ): { req: FinalizedRequestInit; url: string; timeout: number } {
+  ): Promise<{ req: FinalizedRequestInit; url: string; timeout: number }> {
     const options = { ...inputOptions };
     const { method, path, query, defaultBaseURL } = options;
 
@@ -619,7 +637,7 @@ export class Opencode {
     if ('timeout' in options) validatePositiveInteger('timeout', options.timeout);
     options.timeout = options.timeout ?? this.timeout;
     const { bodyHeaders, body } = this.buildBody({ options });
-    const reqHeaders = this.buildHeaders({ options: inputOptions, method, bodyHeaders, retryCount });
+    const reqHeaders = await this.buildHeaders({ options: inputOptions, method, bodyHeaders, retryCount });
 
     const req: FinalizedRequestInit = {
       method,
@@ -635,7 +653,7 @@ export class Opencode {
     return { req, url, timeout: options.timeout };
   }
 
-  private buildHeaders({
+  private async buildHeaders({
     options,
     method,
     bodyHeaders,
@@ -645,7 +663,7 @@ export class Opencode {
     method: HTTPMethod;
     bodyHeaders: HeadersLike;
     retryCount: number;
-  }): Headers {
+  }): Promise<Headers> {
     let idempotencyHeaders: HeadersLike = {};
     if (this.idempotencyHeader && method !== 'get') {
       if (!options.idempotencyKey) options.idempotencyKey = this.defaultIdempotencyKey();
@@ -730,14 +748,14 @@ export class Opencode {
   event: API.Event = new API.Event(this);
   app: API.AppResource = new API.AppResource(this);
   find: API.Find = new API.Find(this);
-  file: API.File = new API.File(this);
+  file: API.FileResource = new API.FileResource(this);
   config: API.ConfigResource = new API.ConfigResource(this);
   session: API.SessionResource = new API.SessionResource(this);
 }
 Opencode.Event = Event;
 Opencode.AppResource = AppResource;
 Opencode.Find = Find;
-Opencode.File = File;
+Opencode.FileResource = FileResource;
 Opencode.ConfigResource = ConfigResource;
 Opencode.SessionResource = SessionResource;
 export declare namespace Opencode {
@@ -745,10 +763,21 @@ export declare namespace Opencode {
 
   export { Event as Event, type EventListResponse as EventListResponse };
 
-  export { AppResource as AppResource, type App as App, type AppInitResponse as AppInitResponse };
+  export {
+    AppResource as AppResource,
+    type App as App,
+    type LogLevel as LogLevel,
+    type Mode as Mode,
+    type AppInitResponse as AppInitResponse,
+    type AppLogResponse as AppLogResponse,
+    type AppModesResponse as AppModesResponse,
+    type AppLogParams as AppLogParams,
+  };
 
   export {
     Find as Find,
+    type Match as Match,
+    type Symbol as Symbol,
     type FindFilesResponse as FindFilesResponse,
     type FindSymbolsResponse as FindSymbolsResponse,
     type FindTextResponse as FindTextResponse,
@@ -758,7 +787,8 @@ export declare namespace Opencode {
   };
 
   export {
-    File as File,
+    FileResource as FileResource,
+    type File as File,
     type FileReadResponse as FileReadResponse,
     type FileStatusResponse as FileStatusResponse,
     type FileReadParams as FileReadParams,
@@ -777,18 +807,20 @@ export declare namespace Opencode {
 
   export {
     SessionResource as SessionResource,
+    type AssistantMessage as AssistantMessage,
     type FilePart as FilePart,
     type Message as Message,
-    type MessagePart as MessagePart,
-    type ReasoningPart as ReasoningPart,
+    type Part as Part,
     type Session as Session,
-    type SourceURLPart as SourceURLPart,
+    type StepFinishPart as StepFinishPart,
     type StepStartPart as StepStartPart,
     type TextPart as TextPart,
-    type ToolCall as ToolCall,
-    type ToolInvocationPart as ToolInvocationPart,
-    type ToolPartialCall as ToolPartialCall,
-    type ToolResult as ToolResult,
+    type ToolPart as ToolPart,
+    type ToolStateCompleted as ToolStateCompleted,
+    type ToolStateError as ToolStateError,
+    type ToolStatePending as ToolStatePending,
+    type ToolStateRunning as ToolStateRunning,
+    type UserMessage as UserMessage,
     type SessionListResponse as SessionListResponse,
     type SessionDeleteResponse as SessionDeleteResponse,
     type SessionAbortResponse as SessionAbortResponse,
@@ -800,6 +832,7 @@ export declare namespace Opencode {
     type SessionSummarizeParams as SessionSummarizeParams,
   };
 
+  export type MessageAbortedError = API.MessageAbortedError;
   export type ProviderAuthError = API.ProviderAuthError;
   export type UnknownError = API.UnknownError;
 }

package/src/core/streaming.ts

@@ -5,6 +5,8 @@ import { findDoubleNewlineIndex, LineDecoder } from '../internal/decoders/line';
 import { ReadableStreamToAsyncIterable } from '../internal/shims';
 import { isAbortError } from '../internal/errors';
 import { encodeUTF8 } from '../internal/utils/bytes';
+import { loggerFor } from '../internal/utils/log';
+import type { Opencode } from '../client';
 
 type Bytes = string | ArrayBuffer | Uint8Array | null | undefined;
 
@@ -16,16 +18,24 @@ export type ServerSentEvent = {
 
 export class Stream<Item> implements AsyncIterable<Item> {
   controller: AbortController;
+  #client: Opencode | undefined;
 
   constructor(
     private iterator: () => AsyncIterator<Item>,
     controller: AbortController,
+    client?: Opencode,
   ) {
     this.controller = controller;
+    this.#client = client;
   }
 
-  static fromSSEResponse<Item>(response: Response, controller: AbortController): Stream<Item> {
+  static fromSSEResponse<Item>(
+    response: Response,
+    controller: AbortController,
+    client?: Opencode,
+  ): Stream<Item> {
     let consumed = false;
+    const logger = client ? loggerFor(client) : console;
 
     async function* iterator(): AsyncIterator<Item, any, undefined> {
       if (consumed) {
@@ -38,8 +48,8 @@ export class Stream<Item> implements AsyncIterable<Item> {
           try {
             yield JSON.parse(sse.data);
           } catch (e) {
-            console.error(`Could not parse message into JSON:`, sse.data);
-            console.error(`From chunk:`, sse.raw);
+            logger.error(`Could not parse message into JSON:`, sse.data);
+            logger.error(`From chunk:`, sse.raw);
             throw e;
           }
         }
@@ -54,14 +64,18 @@ export class Stream<Item> implements AsyncIterable<Item> {
       }
     }
 
-    return new Stream(iterator, controller);
+    return new Stream(iterator, controller, client);
   }
 
   /**
    * Generates a Stream from a newline-separated ReadableStream
    * where each item is a JSON value.
    */
-  static fromReadableStream<Item>(readableStream: ReadableStream, controller: AbortController): Stream<Item> {
+  static fromReadableStream<Item>(
+    readableStream: ReadableStream,
+    controller: AbortController,
+    client?: Opencode,
+  ): Stream<Item> {
     let consumed = false;
 
     async function* iterLines(): AsyncGenerator<string, void, unknown> {
@@ -101,7 +115,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
       }
     }
 
-    return new Stream(iterator, controller);
+    return new Stream(iterator, controller, client);
   }
 
   [Symbol.asyncIterator](): AsyncIterator<Item> {
@@ -131,8 +145,8 @@ export class Stream<Item> implements AsyncIterable<Item> {
     };
 
     return [
-      new Stream(() => teeIterator(left), this.controller),
-      new Stream(() => teeIterator(right), this.controller),
+      new Stream(() => teeIterator(left), this.controller, this.#client),
+      new Stream(() => teeIterator(right), this.controller, this.#client),
     ];
   }
 

package/src/internal/parse.ts

@@ -24,10 +24,10 @@ export async function defaultParseResponse<T>(client: Opencode, props: APIRespon
       // that if you set `stream: true` the response type must also be `Stream<T>`
 
       if (props.options.__streamClass) {
-        return props.options.__streamClass.fromSSEResponse(response, props.controller) as any;
+        return props.options.__streamClass.fromSSEResponse(response, props.controller, client) as any;
       }
 
-      return Stream.fromSSEResponse(response, props.controller) as any;
+      return Stream.fromSSEResponse(response, props.controller, client) as any;
     }
 
     // fetch refuses to read the body when the status code is 204.

package/src/internal/request-options.ts

@@ -10,17 +10,70 @@ import { type HeadersLike } from './headers';
 export type FinalRequestOptions = RequestOptions & { method: HTTPMethod; path: string };
 
 export type RequestOptions = {
+  /**
+   * The HTTP method for the request (e.g., 'get', 'post', 'put', 'delete').
+   */
   method?: HTTPMethod;
+
+  /**
+   * The URL path for the request.
+   *
+   * @example "/v1/foo"
+   */
   path?: string;
+
+  /**
+   * Query parameters to include in the request URL.
+   */
   query?: object | undefined | null;
+
+  /**
+   * The request body. Can be a string, JSON object, FormData, or other supported types.
+   */
   body?: unknown;
+
+  /**
+   * HTTP headers to include with the request. Can be a Headers object, plain object, or array of tuples.
+   */
   headers?: HeadersLike;
+
+  /**
+   * The maximum number of times that the client will retry a request in case of a
+   * temporary failure, like a network error or a 5XX error from the server.
+   *
+   * @default 2
+   */
   maxRetries?: number;
+
   stream?: boolean | undefined;
+
+  /**
+   * The maximum amount of time (in milliseconds) that the client should wait for a response
+   * from the server before timing out a single request.
+   *
+   * @unit milliseconds
+   */
   timeout?: number;
+
+  /**
+   * Additional `RequestInit` options to be passed to the underlying `fetch` call.
+   * These options will be merged with the client's default fetch options.
+   */
   fetchOptions?: MergedRequestInit;
+
+  /**
+   * An AbortSignal that can be used to cancel the request.
+   */
   signal?: AbortSignal | undefined | null;
+
+  /**
+   * A unique key for this request to enable idempotency.
+   */
   idempotencyKey?: string;
+
+  /**
+   * Override the default base URL for this specific request.
+   */
   defaultBaseURL?: string | undefined;
 
   __binaryResponse?: boolean | undefined;

package/src/resources/app.ts

@@ -18,6 +18,20 @@ export class AppResource extends APIResource {
   init(options?: RequestOptions): APIPromise<AppInitResponse> {
     return this._client.post('/app/init', options);
   }
+
+  /**
+   * Write a log entry to the server logs
+   */
+  log(body: AppLogParams, options?: RequestOptions): APIPromise<AppLogResponse> {
+    return this._client.post('/log', { body, ...options });
+  }
+
+  /**
+   * List all modes
+   */
+  modes(options?: RequestOptions): APIPromise<AppModesResponse> {
+    return this._client.get('/mode', options);
+  }
 }
 
 export interface App {
@@ -28,8 +42,6 @@ export interface App {
   path: App.Path;
 
   time: App.Time;
-
-  user: string;
 }
 
 export namespace App {
@@ -50,8 +62,65 @@ export namespace App {
   }
 }
 
+/**
+ * Log level
+ */
+export type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+
+export interface Mode {
+  name: string;
+
+  tools: { [key: string]: boolean };
+
+  model?: Mode.Model;
+
+  prompt?: string;
+}
+
+export namespace Mode {
+  export interface Model {
+    modelID: string;
+
+    providerID: string;
+  }
+}
+
 export type AppInitResponse = boolean;
 
+export type AppLogResponse = boolean;
+
+export type AppModesResponse = Array<Mode>;
+
+export interface AppLogParams {
+  /**
+   * Log level
+   */
+  level: 'debug' | 'info' | 'error' | 'warn';
+
+  /**
+   * Log message
+   */
+  message: string;
+
+  /**
+   * Service name for the log entry
+   */
+  service: string;
+
+  /**
+   * Additional metadata for the log entry
+   */
+  extra?: { [key: string]: unknown };
+}
+
 export declare namespace AppResource {
-  export { type App as App, type AppInitResponse as AppInitResponse };
+  export {
+    type App as App,
+    type LogLevel as LogLevel,
+    type Mode as Mode,
+    type AppInitResponse as AppInitResponse,
+    type AppLogResponse as AppLogResponse,
+    type AppModesResponse as AppModesResponse,
+    type AppLogParams as AppLogParams,
+  };
 }