casedev 0.22.1 → 0.24.0

package/src/resources/agent/v1/agents.ts

@@ -5,6 +5,9 @@ import { APIPromise } from '../../../core/api-promise';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
+/**
+ * Create, manage, and execute AI agents with tool access, sandbox environments, and async run workflows
+ */
 export class Agents extends APIResource {
   /**
    * Creates a new agent definition with a scoped API key. The agent can then be used
@@ -31,8 +34,11 @@ export class Agents extends APIResource {
   /**
    * Lists all active agents for the authenticated organization.
    */
-  list(options?: RequestOptions): APIPromise<AgentListResponse> {
-    return this._client.get('/agent/v1/agents', options);
+  list(
+    query: AgentListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<AgentListResponse> {
+    return this._client.get('/agent/v1/agents', { query, ...options });
   }
 
   /**
@@ -123,6 +129,13 @@ export interface AgentUpdateResponse {
 
 export interface AgentListResponse {
   agents?: Array<AgentListResponse.Agent>;
+
+  hasMore?: boolean;
+
+  /**
+   * Pass as cursor to fetch the next page
+   */
+  nextCursor?: string | null;
 }
 
 export namespace AgentListResponse {
@@ -166,12 +179,14 @@ export interface AgentCreateParams {
   description?: string;
 
   /**
-   * Denylist of tools the agent cannot use
+   * Denylist of tools the agent cannot use. Mutually exclusive with enabledTools —
+   * set one or the other, not both.
    */
   disabledTools?: Array<string> | null;
 
   /**
-   * Allowlist of tools the agent can use
+   * Allowlist of tools the agent can use. Mutually exclusive with disabledTools —
+   * set one or the other, not both.
    */
   enabledTools?: Array<string> | null;
 
@@ -215,25 +230,67 @@ export namespace AgentCreateParams {
 }
 
 export interface AgentUpdateParams {
-  description?: string;
+  /**
+   * Updated agent description. Pass null to clear if supported by the client.
+   */
+  description?: string | null;
 
+  /**
+   * Denylist of tools the agent cannot use. Mutually exclusive with enabledTools —
+   * set one or the other, not both. Pass null to clear.
+   */
   disabledTools?: Array<string> | null;
 
+  /**
+   * Allowlist of tools the agent can use. Mutually exclusive with disabledTools —
+   * set one or the other, not both. Pass null to clear.
+   */
   enabledTools?: Array<string> | null;
 
+  /**
+   * Updated system instructions that guide agent behavior
+   */
   instructions?: string;
 
+  /**
+   * Model identifier the agent should use for future runs
+   */
   model?: string;
 
+  /**
+   * Updated agent display name
+   */
   name?: string;
 
+  /**
+   * Sandbox configuration override for future agent runs. Pass null to clear.
+   */
   sandbox?: unknown | null;
 
+  /**
+   * Vault group IDs the agent can access. Pass null to clear.
+   */
   vaultGroups?: Array<string> | null;
 
+  /**
+   * Vault IDs the agent can access directly. Pass null to clear.
+   */
   vaultIds?: Array<string> | null;
 }
 
+export interface AgentListParams {
+  /**
+   * Pagination cursor (agent ID from previous page). Returns agents created before
+   * this agent.
+   */
+  cursor?: string;
+
+  /**
+   * Maximum number of agents to return (default 50, max 250)
+   */
+  limit?: number;
+}
+
 export declare namespace Agents {
   export {
     type AgentCreateResponse as AgentCreateResponse,
@@ -243,5 +300,6 @@ export declare namespace Agents {
     type AgentDeleteResponse as AgentDeleteResponse,
     type AgentCreateParams as AgentCreateParams,
     type AgentUpdateParams as AgentUpdateParams,
+    type AgentListParams as AgentListParams,
   };
 }

package/src/resources/agent/v1/chat.ts

@@ -7,6 +7,9 @@ import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
+/**
+ * Create, manage, and execute AI agents with tool access, sandbox environments, and async run workflows
+ */
 export class Chat extends APIResource {
   /**
    * Creates a persistent OpenCode chat session in a Modal sandbox. Session state is
@@ -52,18 +55,27 @@ export class Chat extends APIResource {
   }
 
   /**
-   * Streams a single assistant turn as normalized state events with stable turn,
-   * message, and part ids. Emits session.usage before turn.completed when token data
-   * is available.
+   * Streams a single assistant turn as normalized SSE events with stable turn,
+   * message, and part IDs. Emits events: `turn.started`, `turn.status`,
+   * `message.created`, `message.part.updated`, `message.completed`, `session.usage`,
+   * `turn.completed`.
+   *
+   * **When to use this endpoint:** Recommended for building custom chat UIs that
+   * need real-time streaming progress. This is the primary streaming endpoint for
+   * new integrations.
+   *
+   * **Alternatives:**
+   *
+   * - `POST /chat/:id/message` — synchronous, returns complete response as JSON
+   *   (best for server-to-server)
    */
   respond(
     id: string,
-    params: ChatRespondParams,
+    body: ChatRespondParams,
     options?: RequestOptions,
   ): APIPromise<Stream<ChatRespondResponse>> {
-    const { body } = params;
     return this._client.post(path`/agent/v1/chat/${id}/respond`, {
-      body: body,
+      body,
       ...options,
       headers: buildHeaders([{ Accept: 'text/event-stream' }, options?.headers]),
       stream: true,
@@ -71,12 +83,21 @@ export class Chat extends APIResource {
   }
 
   /**
-   * Proxies a message to the OpenCode session bound to this chat.
+   * Sends a message and returns the complete response as a single JSON body. Blocks
+   * until the agent turn completes.
+   *
+   * **When to use this endpoint:** Best for server-to-server integrations,
+   * background processing, or any context where you want the full response in one
+   * call without managing an SSE stream.
+   *
+   * **Alternatives:**
+   *
+   * - `POST /chat/:id/respond` — streaming SSE with normalized events (recommended
+   *   for custom chat UIs)
    */
-  sendMessage(id: string, params: ChatSendMessageParams, options?: RequestOptions): APIPromise<void> {
-    const { body } = params;
+  sendMessage(id: string, body: ChatSendMessageParams, options?: RequestOptions): APIPromise<void> {
     return this._client.post(path`/agent/v1/chat/${id}/message`, {
-      body: body,
+      body,
       ...options,
       headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
@@ -98,24 +119,6 @@ export class Chat extends APIResource {
       stream: true,
     }) as APIPromise<Stream<ChatStreamResponse>>;
   }
-
-  /**
-   * Streams a single assistant turn as AI SDK UIMessageChunk SSE events for direct
-   * client rendering.
-   */
-  uiStream(
-    id: string,
-    params: ChatUiStreamParams,
-    options?: RequestOptions,
-  ): APIPromise<Stream<ChatUiStreamResponse>> {
-    const { body } = params;
-    return this._client.post(path`/agent/v1/chat/${id}/ui-stream`, {
-      body: body,
-      ...options,
-      headers: buildHeaders([{ Accept: 'text/event-stream' }, options?.headers]),
-      stream: true,
-    }) as APIPromise<Stream<ChatUiStreamResponse>>;
-  }
 }
 
 export interface ChatCreateResponse {
@@ -150,8 +153,6 @@ export type ChatRespondResponse = string;
 
 export type ChatStreamResponse = string;
 
-export type ChatUiStreamResponse = string;
-
 export interface ChatCreateParams {
   /**
    * Idle timeout before session is eligible for snapshot/termination. Defaults to 15
@@ -182,23 +183,53 @@ export interface ChatReplyToQuestionParams {
   id: string;
 
   /**
-   * Body param
+   * Body param: Answer selections for each prompt element in the pending question
    */
   answers: Array<Array<string>>;
 }
 
 export interface ChatRespondParams {
   /**
-   * OpenCode message payload. Passed through 1:1.
+   * Message content parts. Currently only "text" type is supported. Additional types
+   * (e.g. file, image) may be added in future versions.
    */
-  body: unknown;
+  parts?: Array<ChatRespondParams.Part>;
+}
+
+export namespace ChatRespondParams {
+  export interface Part {
+    /**
+     * The message text content
+     */
+    text: string;
+
+    /**
+     * Part type. Currently only "text" is supported.
+     */
+    type: 'text';
+  }
 }
 
 export interface ChatSendMessageParams {
   /**
-   * OpenCode message payload. Passed through 1:1.
+   * Message content parts. Currently only "text" type is supported. Additional types
+   * (e.g. file, image) may be added in future versions.
    */
-  body: unknown;
+  parts?: Array<ChatSendMessageParams.Part>;
+}
+
+export namespace ChatSendMessageParams {
+  export interface Part {
+    /**
+     * The message text content
+     */
+    text: string;
+
+    /**
+     * Part type. Currently only "text" is supported.
+     */
+    type: 'text';
+  }
 }
 
 export interface ChatStreamParams {
@@ -208,13 +239,6 @@ export interface ChatStreamParams {
   lastEventId?: number;
 }
 
-export interface ChatUiStreamParams {
-  /**
-   * OpenCode message payload. Passed through 1:1.
-   */
-  body: unknown;
-}
-
 export declare namespace Chat {
   export {
     type ChatCreateResponse as ChatCreateResponse,
@@ -222,12 +246,10 @@ export declare namespace Chat {
     type ChatCancelResponse as ChatCancelResponse,
     type ChatRespondResponse as ChatRespondResponse,
     type ChatStreamResponse as ChatStreamResponse,
-    type ChatUiStreamResponse as ChatUiStreamResponse,
     type ChatCreateParams as ChatCreateParams,
     type ChatReplyToQuestionParams as ChatReplyToQuestionParams,
     type ChatRespondParams as ChatRespondParams,
     type ChatSendMessageParams as ChatSendMessageParams,
     type ChatStreamParams as ChatStreamParams,
-    type ChatUiStreamParams as ChatUiStreamParams,
   };
 }

package/src/resources/agent/v1/execute.ts

@@ -4,11 +4,21 @@ import { APIResource } from '../../../core/resource';
 import { APIPromise } from '../../../core/api-promise';
 import { RequestOptions } from '../../../internal/request-options';
 
+/**
+ * Create, manage, and execute AI agents with tool access, sandbox environments, and async run workflows
+ */
 export class Execute extends APIResource {
   /**
    * Creates an ephemeral agent and immediately executes a run. Returns the run ID
    * for polling status and results. This is the fastest way to run an agent without
    * managing agent lifecycle.
+   *
+   * **Ephemeral agent lifecycle:** The agent created by this endpoint is
+   * automatically soft-deleted and its scoped API key revoked when the run completes
+   * (whether it succeeds, fails, or times out). Ephemeral agents do not appear in
+   * GET /agent/v1/agents listings. The returned agentId is valid only for the
+   * duration of the run — do not store it for reuse. For persistent, reusable
+   * agents, use POST /agent/v1/agents instead.
    */
   create(body: ExecuteCreateParams, options?: RequestOptions): APIPromise<ExecuteCreateResponse> {
     return this._client.post('/agent/v1/execute', { body, ...options });
@@ -17,7 +27,8 @@ export class Execute extends APIResource {
 
 export interface ExecuteCreateResponse {
   /**
-   * Ephemeral agent ID (auto-created)
+   * Ephemeral agent ID (auto-created). This agent is soft-deleted when the run
+   * completes and should not be stored for reuse.
    */
   agentId?: string;
 
@@ -38,12 +49,14 @@ export interface ExecuteCreateParams {
   prompt: string;
 
   /**
-   * Denylist of tools the agent cannot use
+   * Denylist of tools the agent cannot use. Mutually exclusive with enabledTools —
+   * set one or the other, not both.
    */
   disabledTools?: Array<string> | null;
 
   /**
-   * Allowlist of tools the agent can use
+   * Allowlist of tools the agent can use. Mutually exclusive with disabledTools —
+   * set one or the other, not both.
    */
   enabledTools?: Array<string> | null;
 

package/src/resources/agent/v1/index.ts

@@ -9,6 +9,7 @@ export {
   type AgentDeleteResponse,
   type AgentCreateParams,
   type AgentUpdateParams,
+  type AgentListParams,
 } from './agents';
 export {
   Chat,
@@ -17,18 +18,17 @@ export {
   type ChatCancelResponse,
   type ChatRespondResponse,
   type ChatStreamResponse,
-  type ChatUiStreamResponse,
   type ChatCreateParams,
   type ChatReplyToQuestionParams,
   type ChatRespondParams,
   type ChatSendMessageParams,
   type ChatStreamParams,
-  type ChatUiStreamParams,
 } from './chat';
 export { Execute, type ExecuteCreateResponse, type ExecuteCreateParams } from './execute';
 export {
   Run,
   type RunCreateResponse,
+  type RunListResponse,
   type RunCancelResponse,
   type RunEventsResponse,
   type RunExecResponse,
@@ -36,6 +36,7 @@ export {
   type RunGetStatusResponse,
   type RunWatchResponse,
   type RunCreateParams,
+  type RunListParams,
   type RunEventsParams,
   type RunWatchParams,
 } from './run';

package/src/resources/agent/v1/run.ts

@@ -7,6 +7,9 @@ import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
+/**
+ * Create, manage, and execute AI agents with tool access, sandbox environments, and async run workflows
+ */
 export class Run extends APIResource {
   /**
    * Creates a run in queued state. Call POST /agent/v1/run/:id/exec to start
@@ -16,6 +19,14 @@ export class Run extends APIResource {
     return this._client.post('/agent/v1/run', { body, ...options });
   }
 
+  /**
+   * Lists agent runs for the authenticated organization. Supports filtering by
+   * agent, status, and cursor-based pagination.
+   */
+  list(query: RunListParams | null | undefined = {}, options?: RequestOptions): APIPromise<RunListResponse> {
+    return this._client.get('/agent/v1/run', { query, ...options });
+  }
+
   /**
    * Cancels a running or queued run. Idempotent — cancelling a finished run returns
    * its current status.
@@ -85,6 +96,40 @@ export interface RunCreateResponse {
   status?: 'queued';
 }
 
+export interface RunListResponse {
+  hasMore?: boolean;
+
+  /**
+   * Pass as cursor to fetch the next page
+   */
+  nextCursor?: string | null;
+
+  runs?: Array<RunListResponse.Run>;
+}
+
+export namespace RunListResponse {
+  export interface Run {
+    id?: string;
+
+    agentId?: string;
+
+    completedAt?: string | null;
+
+    createdAt?: string;
+
+    model?: string | null;
+
+    /**
+     * Truncated to first 200 characters
+     */
+    prompt?: string;
+
+    startedAt?: string | null;
+
+    status?: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+  }
+}
+
 export interface RunCancelResponse {
   id?: string;
 
@@ -311,6 +356,13 @@ export interface RunCreateParams {
    */
   prompt: string;
 
+  /**
+   * HTTPS callback URL to receive a notification when the run completes. Registered
+   * atomically with the run — eliminates the race condition of calling /watch after
+   * /exec. Additional watchers can still be added via POST /run/:id/watch.
+   */
+  callbackUrl?: string | null;
+
   /**
    * Additional guidance for this run
    */
@@ -328,6 +380,29 @@ export interface RunCreateParams {
   objectIds?: Array<string> | null;
 }
 
+export interface RunListParams {
+  /**
+   * Filter by agent ID
+   */
+  agentId?: string;
+
+  /**
+   * Pagination cursor (run ID from previous page). Returns runs created before this
+   * run.
+   */
+  cursor?: string;
+
+  /**
+   * Maximum number of runs to return (default 50, max 250)
+   */
+  limit?: number;
+
+  /**
+   * Filter by run status
+   */
+  status?: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+}
+
 export interface RunEventsParams {
   /**
    * Replay events after this sequence number
@@ -345,6 +420,7 @@ export interface RunWatchParams {
 export declare namespace Run {
   export {
     type RunCreateResponse as RunCreateResponse,
+    type RunListResponse as RunListResponse,
     type RunCancelResponse as RunCancelResponse,
     type RunEventsResponse as RunEventsResponse,
     type RunExecResponse as RunExecResponse,
@@ -352,6 +428,7 @@ export declare namespace Run {
     type RunGetStatusResponse as RunGetStatusResponse,
     type RunWatchResponse as RunWatchResponse,
     type RunCreateParams as RunCreateParams,
+    type RunListParams as RunListParams,
     type RunEventsParams as RunEventsParams,
     type RunWatchParams as RunWatchParams,
   };

package/src/resources/agent/v1/v1.ts

@@ -6,6 +6,7 @@ import {
   AgentCreateParams,
   AgentCreateResponse,
   AgentDeleteResponse,
+  AgentListParams,
   AgentListResponse,
   AgentRetrieveResponse,
   AgentUpdateParams,
@@ -25,8 +26,6 @@ import {
   ChatSendMessageParams,
   ChatStreamParams,
   ChatStreamResponse,
-  ChatUiStreamParams,
-  ChatUiStreamResponse,
 } from './chat';
 import * as ExecuteAPI from './execute';
 import { Execute, ExecuteCreateParams, ExecuteCreateResponse } from './execute';
@@ -41,6 +40,8 @@ import {
   RunExecResponse,
   RunGetDetailsResponse,
   RunGetStatusResponse,
+  RunListParams,
+  RunListResponse,
   RunWatchParams,
   RunWatchResponse,
 } from './run';
@@ -67,11 +68,13 @@ export declare namespace V1 {
     type AgentDeleteResponse as AgentDeleteResponse,
     type AgentCreateParams as AgentCreateParams,
     type AgentUpdateParams as AgentUpdateParams,
+    type AgentListParams as AgentListParams,
   };
 
   export {
     Run as Run,
     type RunCreateResponse as RunCreateResponse,
+    type RunListResponse as RunListResponse,
     type RunCancelResponse as RunCancelResponse,
     type RunEventsResponse as RunEventsResponse,
     type RunExecResponse as RunExecResponse,
@@ -79,6 +82,7 @@ export declare namespace V1 {
     type RunGetStatusResponse as RunGetStatusResponse,
     type RunWatchResponse as RunWatchResponse,
     type RunCreateParams as RunCreateParams,
+    type RunListParams as RunListParams,
     type RunEventsParams as RunEventsParams,
     type RunWatchParams as RunWatchParams,
   };
@@ -96,12 +100,10 @@ export declare namespace V1 {
     type ChatCancelResponse as ChatCancelResponse,
     type ChatRespondResponse as ChatRespondResponse,
     type ChatStreamResponse as ChatStreamResponse,
-    type ChatUiStreamResponse as ChatUiStreamResponse,
     type ChatCreateParams as ChatCreateParams,
     type ChatReplyToQuestionParams as ChatReplyToQuestionParams,
     type ChatRespondParams as ChatRespondParams,
     type ChatSendMessageParams as ChatSendMessageParams,
     type ChatStreamParams as ChatStreamParams,
-    type ChatUiStreamParams as ChatUiStreamParams,
   };
 }