@nimble-way/nimble-js 0.19.0 → 1.0.0

package/src/resources/{task-agent → agents}/runs.ts

@@ -8,105 +8,182 @@ import { path } from '../../internal/utils/path';
 
 export class Runs extends APIResource {
   /**
-   * List runs for this instance.
+   * Start an agent run. The run executes asynchronously: the response returns
+   * immediately with status `queued`, then poll `GET .../runs/{run_id}` until
+   * `completed` and fetch the output from `GET .../runs/{run_id}/result` — or set
+   * `enable_events: true` and follow `GET .../runs/{run_id}/events` for live
+   * progress.
    *
-   * `status` accepts a lowercase `TaskRunStatusValue` (e.g. "completed") or a
-   * comma-separated list of them (e.g. "queued,running").
+   * To enrich existing records instead of researching from scratch, pass them in
+   * `input_data`; this requires an `output_schema` (on the request or the agent).
+   */
+  create(agentID: string, body: RunCreateParams, options?: RequestOptions): APIPromise<RunCreateResponse> {
+    return this._client.post(path`/v2/agents/${agentID}/runs`, { body, ...options });
+  }
+
+  /**
+   * List the runs of an agent, newest first, paginated with `offset`/`limit`.
    */
   list(
     agentID: string,
     query: RunListParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<RunListResponse> {
-    return this._client.get(path`/v1/task-agents/${agentID}/runs`, { query, ...options });
+    return this._client.get(path`/v2/agents/${agentID}/runs`, { query, ...options });
   }
 
   /**
-   * Cancel an in-progress or queued run.
-   *
-   * Verb is POST + `/cancel` action segment per the AGENTS-1666 spec (replaces the
-   * old `DELETE …/runs/{run_id}`).
+   * Retrieve a run's current state. Poll this endpoint after creating a run: the run
+   * is finished once `status` is `completed`, `failed`, or `cancelled`.
    */
-  cancel(runID: string, params: RunCancelParams, options?: RequestOptions): APIPromise<void> {
+  get(runID: string, params: RunGetParams, options?: RequestOptions): APIPromise<RunGetResponse> {
     const { agent_id } = params;
-    return this._client.post(path`/v1/task-agents/${agent_id}/runs/${runID}/cancel`, {
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+    return this._client.get(path`/v2/agents/${agent_id}/runs/${runID}`, options);
   }
 
   /**
-   * Fetch a run by id, scoped to the instance.
+   * Fetch the output of a completed run. The `output` is `type: "text"` (a prose
+   * answer) or `type: "json"` (structured data matching the output schema), plus
+   * `trust` metadata with per-claim citations for the answer.
    *
-   * A run resolves only when (run_id, agent_id) match — otherwise 404. This means a
-   * stale URL with a swapped agent_id won't leak runs across instances even if the
-   * run_id is real.
+   * While the run is still `queued` or `running` this endpoint returns `409`; if the
+   * run `failed` or was `cancelled` it returns `422` with the run and error details.
    */
-  get(runID: string, params: RunGetParams, options?: RequestOptions): APIPromise<RunGetResponse> {
+  result(runID: string, params: RunResultParams, options?: RequestOptions): APIPromise<RunResultResponse> {
     const { agent_id } = params;
-    return this._client.get(path`/v1/task-agents/${agent_id}/runs/${runID}`, options);
+    return this._client.get(path`/v2/agents/${agent_id}/runs/${runID}/result`, options);
   }
 
   /**
-   * Fetch the result for a terminal run on this instance.
-   *
-   * Mirrors the previous flat `GET /tasks/runs/:run_id/result` semantics:
-   *
-   * - 404 when the run doesn't belong to the agent.
-   * - 408 when the run is still active.
-   * - 422 (with TaskRunFailedResult body) when the run failed or was cancelled.
-   * - 200 (with TaskRunResult body) on success.
-   */
-  getResult(
-    runID: string,
-    params: RunGetResultParams,
-    options?: RequestOptions,
-  ): APIPromise<RunGetResultResponse> {
+   * Stream a run's progress as
+   * [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)
+   * (`text/event-stream`). Create the run with `enable_events: true` to have events
+   * published. A keep-alive comment is sent every 15 seconds.
+   */
+  streamEvents(runID: string, params: RunStreamEventsParams, options?: RequestOptions): APIPromise<void> {
     const { agent_id } = params;
-    return this._client.get(path`/v1/task-agents/${agent_id}/runs/${runID}/result`, options);
+    return this._client.get(path`/v2/agents/${agent_id}/runs/${runID}/events`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
   }
+}
 
+export interface RunCreateResponse {
   /**
-   * SSE stream of real-time progress events for a run on this instance.
+   * Run identifier, format "task*run*{uuid}".
    */
-  streamEvents(runID: string, params: RunStreamEventsParams, options?: RequestOptions): APIPromise<unknown> {
-    const { agent_id } = params;
-    return this._client.get(path`/v1/task-agents/${agent_id}/runs/${runID}/events`, options);
+  id: string;
+
+  /**
+   * When the run was created.
+   */
+  created_at: string;
+
+  /**
+   * Effort level used for the run.
+   */
+  effort: 'low' | 'medium' | 'high' | 'x-high' | 'max';
+
+  /**
+   * Interaction ID.
+   */
+  interaction_id: string;
+
+  /**
+   * True while status is 'queued' or 'running'.
+   */
+  is_active: boolean;
+
+  /**
+   * Current run status.
+   */
+  status: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+
+  /**
+   * Web Search Agent instance this run belongs to.
+   */
+  web_search_agent_id: string;
+
+  /**
+   * When the run completed.
+   */
+  completed_at?: string | null;
+
+  /**
+   * Error details when the run failed.
+   */
+  error?: RunCreateResponse.Error | null;
+
+  /**
+   * Prompt submitted for the run.
+   */
+  prompt?: string | null;
+
+  /**
+   * When the run started executing.
+   */
+  started_at?: string | null;
+}
+
+export namespace RunCreateResponse {
+  /**
+   * Error details when the run failed.
+   */
+  export interface Error {
+    /**
+     * Human-readable error description.
+     */
+    message: string;
+
+    /**
+     * Reference ID (equals the run id).
+     */
+    ref_id: string;
   }
 }
 
-/**
- * Paginated list of task runs for GET /tasks/runs.
- */
 export interface RunListResponse {
+  /**
+   * Items returned in this page.
+   */
   items: Array<RunListResponse.Item>;
 
-  total: number;
+  /**
+   * Maximum number of items returned.
+   */
+  limit: number;
 
-  limit?: number;
+  /**
+   * Number of items skipped before this page.
+   */
+  offset: number;
 
-  offset?: number;
+  /**
+   * Total number of items matching the query.
+   */
+  total: number;
 }
 
 export namespace RunListResponse {
-  /**
-   * Task run status returned by list/create/get endpoints.
-   */
   export interface Item {
     /**
      * Run identifier, format "task*run*{uuid}".
      */
     id: string;
 
+    /**
+     * When the run was created.
+     */
     created_at: string;
 
     /**
-     * Canonical effort tier names for the research graph.
+     * Effort level used for the run.
      */
     effort: 'low' | 'medium' | 'high' | 'x-high' | 'max';
 
     /**
-     * Interaction ID — pass as previous_interaction_id to reuse context.
+     * Interaction ID.
      */
     interaction_id: string;
 
@@ -116,38 +193,39 @@ export namespace RunListResponse {
     is_active: boolean;
 
     /**
-     * Lowercase status values used in API responses (distinct from the DB-level
-     * TaskRunStatus enum).
+     * Current run status.
      */
     status: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
 
     /**
-     * Web Search Agent instance this run belongs to. Every task run is agent-bound
-     * (see AGENTS-1666). Use this to build the nested URL
-     * /api/v2/web-search-agents/{web_search_agent_id}/runs/{id}.
+     * Web Search Agent instance this run belongs to.
      */
     web_search_agent_id: string;
 
+    /**
+     * When the run completed.
+     */
     completed_at?: string | null;
 
     /**
-     * Error detail for a failed run.
+     * Error details when the run failed.
      */
     error?: Item.Error | null;
 
     /**
-     * Original user prompt before enrichment. Populated for Web Search Agent runs.
+     * Prompt submitted for the run.
      */
     prompt?: string | null;
 
+    /**
+     * When the run started executing.
+     */
     started_at?: string | null;
-
-    workspace_id?: string | null;
   }
 
   export namespace Item {
     /**
-     * Error detail for a failed run.
+     * Error details when the run failed.
      */
     export interface Error {
       /**
@@ -163,24 +241,24 @@ export namespace RunListResponse {
   }
 }
 
-/**
- * Task run status returned by list/create/get endpoints.
- */
 export interface RunGetResponse {
   /**
    * Run identifier, format "task*run*{uuid}".
    */
   id: string;
 
+  /**
+   * When the run was created.
+   */
   created_at: string;
 
   /**
-   * Canonical effort tier names for the research graph.
+   * Effort level used for the run.
    */
   effort: 'low' | 'medium' | 'high' | 'x-high' | 'max';
 
   /**
-   * Interaction ID — pass as previous_interaction_id to reuse context.
+   * Interaction ID.
    */
   interaction_id: string;
 
@@ -190,38 +268,39 @@ export interface RunGetResponse {
   is_active: boolean;
 
   /**
-   * Lowercase status values used in API responses (distinct from the DB-level
-   * TaskRunStatus enum).
+   * Current run status.
    */
   status: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
 
   /**
-   * Web Search Agent instance this run belongs to. Every task run is agent-bound
-   * (see AGENTS-1666). Use this to build the nested URL
-   * /api/v2/web-search-agents/{web_search_agent_id}/runs/{id}.
+   * Web Search Agent instance this run belongs to.
    */
   web_search_agent_id: string;
 
+  /**
+   * When the run completed.
+   */
   completed_at?: string | null;
 
   /**
-   * Error detail for a failed run.
+   * Error details when the run failed.
    */
   error?: RunGetResponse.Error | null;
 
   /**
-   * Original user prompt before enrichment. Populated for Web Search Agent runs.
+   * Prompt submitted for the run.
    */
   prompt?: string | null;
 
+  /**
+   * When the run started executing.
+   */
   started_at?: string | null;
-
-  workspace_id?: string | null;
 }
 
 export namespace RunGetResponse {
   /**
-   * Error detail for a failed run.
+   * Error details when the run failed.
    */
   export interface Error {
     /**
@@ -236,72 +315,111 @@ export namespace RunGetResponse {
   }
 }
 
-/**
- * Response for GET /tasks/runs/{run_id}/result — status 'completed'.
- */
-export type RunGetResultResponse =
-  | RunGetResultResponse.TaskRunResult
-  | RunGetResultResponse.TaskRunFailedResult;
+export type RunResultResponse =
+  | RunResultResponse.TaskRunResultPublicV2
+  | RunResultResponse.TaskRunFailedResultPublicV2;
 
-export namespace RunGetResultResponse {
-  /**
-   * Response for GET /tasks/runs/{run_id}/result — status 'completed'.
-   */
-  export interface TaskRunResult {
+export namespace RunResultResponse {
+  export interface TaskRunResultPublicV2 {
     /**
      * Output from the completed task.
      */
-    output: TaskRunResult.TaskRunTextOutput | TaskRunResult.TaskRunJsonOutput;
+    output: TaskRunResultPublicV2.TaskRunTextOutputPublicV2 | TaskRunResultPublicV2.TaskRunJsonOutputPublicV2;
 
     /**
      * Task run object with status 'completed'.
      */
-    run: TaskRunResult.Run;
+    run: TaskRunResultPublicV2.Run;
   }
 
-  export namespace TaskRunResult {
-    /**
-     * Text output from a completed task.
-     */
-    export interface TaskRunTextOutput {
+  export namespace TaskRunResultPublicV2 {
+    export interface TaskRunTextOutputPublicV2 {
       /**
        * The final prose answer.
        */
       content: string;
 
-      trust: TaskRunTextOutput.Trust;
+      /**
+       * Trust and citation metadata for the output.
+       */
+      trust: TaskRunTextOutputPublicV2.Trust;
 
+      /**
+       * Output content type.
+       */
       type?: 'text';
     }
 
-    export namespace TaskRunTextOutput {
+    export namespace TaskRunTextOutputPublicV2 {
+      /**
+       * Trust and citation metadata for the output.
+       */
       export interface Trust {
+        /**
+         * Per-claim trust, keyed by callout markers in the answer text.
+         */
         claims: Array<Trust.Claim>;
 
-        confidence: 'high' | 'medium' | 'low';
+        /**
+         * Overall confidence in the answer.
+         */
+        confidence: 'high' | 'medium' | 'low' | 'pre_existing';
 
+        /**
+         * Why this confidence level was assigned.
+         */
         reasoning: string;
 
+        /**
+         * Sources consulted while producing the answer.
+         */
         sources: Array<Trust.Source>;
       }
 
       export namespace Trust {
+        /**
+         * Trust metadata for one claim in a prose answer, keyed by callout marker.
+         */
         export interface Claim {
+          /**
+           * Callout marker number referencing this claim in the answer text.
+           */
           callout: number;
 
+          /**
+           * Citations backing this claim.
+           */
           citations: Array<Claim.Citation>;
 
-          confidence: 'high' | 'medium' | 'low';
+          /**
+           * Confidence in this claim.
+           */
+          confidence: 'high' | 'medium' | 'low' | 'pre_existing';
 
+          /**
+           * Why this confidence level was assigned.
+           */
           reasoning: string;
         }
 
         export namespace Claim {
+          /**
+           * A citation backing a specific claim in the answer.
+           */
           export interface Citation {
+            /**
+             * URL of the cited page.
+             */
             url: string;
 
+            /**
+             * Verbatim excerpts supporting the claim.
+             */
             excerpts?: Array<string> | null;
 
+            /**
+             * Extract template used to read the source, when one was used.
+             */
             extract_template_name?: string | null;
 
             /**
@@ -328,17 +446,35 @@ export namespace RunGetResultResponse {
              */
             source_intent?: 'official' | 'news' | 'social' | 'academic' | 'aggregator' | 'other' | null;
 
+            /**
+             * How authoritative the source is: 'primary' or 'secondary'.
+             */
             source_type?: 'primary' | 'secondary' | null;
 
+            /**
+             * Title of the cited page.
+             */
             title?: string | null;
           }
         }
 
+        /**
+         * A source consulted while producing the answer.
+         */
         export interface Source {
+          /**
+           * How authoritative the source is: 'primary' or 'secondary'.
+           */
           type: 'primary' | 'secondary';
 
+          /**
+           * URL of the source page.
+           */
           url: string;
 
+          /**
+           * Extract template used to read the source, when one was used.
+           */
           extract_template_name?: string | null;
 
           /**
@@ -365,55 +501,101 @@ export namespace RunGetResultResponse {
            */
           source_intent?: 'official' | 'news' | 'social' | 'academic' | 'aggregator' | 'other' | null;
 
+          /**
+           * Title of the source page.
+           */
           title?: string | null;
         }
       }
     }
 
-    /**
-     * Structured JSON output from a completed task, produced when
-     * task_spec.output_schema.type is 'json'.
-     */
-    export interface TaskRunJsonOutput {
+    export interface TaskRunJsonOutputPublicV2 {
       /**
-       * Data conforming to the caller-supplied JSON schema. A dict for object schemas; a
-       * list for array schemas.
+       * The final structured output.
        */
       content: { [key: string]: unknown } | Array<unknown>;
 
-      trust: TaskRunJsonOutput.Trust;
+      /**
+       * Trust and citation metadata for the output.
+       */
+      trust: TaskRunJsonOutputPublicV2.Trust;
 
+      /**
+       * Output content type.
+       */
       type?: 'json';
     }
 
-    export namespace TaskRunJsonOutput {
+    export namespace TaskRunJsonOutputPublicV2 {
+      /**
+       * Trust and citation metadata for the output.
+       */
       export interface Trust {
+        /**
+         * Per-value trust, keyed by JSON path in the structured output.
+         */
         claims: Array<Trust.Claim>;
 
-        confidence: 'high' | 'medium' | 'low';
+        /**
+         * Overall confidence in the answer.
+         */
+        confidence: 'high' | 'medium' | 'low' | 'pre_existing';
 
+        /**
+         * Why this confidence level was assigned.
+         */
         reasoning: string;
 
+        /**
+         * Sources consulted while producing the answer.
+         */
         sources: Array<Trust.Source>;
       }
 
       export namespace Trust {
+        /**
+         * Trust metadata for one value in a structured (JSON) answer, keyed by JSON path.
+         */
         export interface Claim {
+          /**
+           * Citations backing this value.
+           */
           citations: Array<Claim.Citation>;
 
-          confidence: 'high' | 'medium' | 'low';
+          /**
+           * Confidence in this value.
+           */
+          confidence: 'high' | 'medium' | 'low' | 'pre_existing';
 
+          /**
+           * JSON path of the value in the structured output this claim refers to.
+           */
           path: string;
 
+          /**
+           * Why this confidence level was assigned.
+           */
           reasoning: string;
         }
 
         export namespace Claim {
+          /**
+           * A citation backing a specific claim in the answer.
+           */
           export interface Citation {
+            /**
+             * URL of the cited page.
+             */
             url: string;
 
+            /**
+             * Verbatim excerpts supporting the claim.
+             */
             excerpts?: Array<string> | null;
 
+            /**
+             * Extract template used to read the source, when one was used.
+             */
             extract_template_name?: string | null;
 
             /**
@@ -440,17 +622,35 @@ export namespace RunGetResultResponse {
              */
             source_intent?: 'official' | 'news' | 'social' | 'academic' | 'aggregator' | 'other' | null;
 
+            /**
+             * How authoritative the source is: 'primary' or 'secondary'.
+             */
             source_type?: 'primary' | 'secondary' | null;
 
+            /**
+             * Title of the cited page.
+             */
             title?: string | null;
           }
         }
 
+        /**
+         * A source consulted while producing the answer.
+         */
         export interface Source {
+          /**
+           * How authoritative the source is: 'primary' or 'secondary'.
+           */
           type: 'primary' | 'secondary';
 
+          /**
+           * URL of the source page.
+           */
           url: string;
 
+          /**
+           * Extract template used to read the source, when one was used.
+           */
           extract_template_name?: string | null;
 
           /**
@@ -477,6 +677,9 @@ export namespace RunGetResultResponse {
            */
           source_intent?: 'official' | 'news' | 'social' | 'academic' | 'aggregator' | 'other' | null;
 
+          /**
+           * Title of the source page.
+           */
           title?: string | null;
         }
       }
@@ -491,15 +694,18 @@ export namespace RunGetResultResponse {
        */
       id: string;
 
+      /**
+       * When the run was created.
+       */
       created_at: string;
 
       /**
-       * Canonical effort tier names for the research graph.
+       * Effort level used for the run.
        */
       effort: 'low' | 'medium' | 'high' | 'x-high' | 'max';
 
       /**
-       * Interaction ID — pass as previous_interaction_id to reuse context.
+       * Interaction ID.
        */
       interaction_id: string;
 
@@ -509,38 +715,39 @@ export namespace RunGetResultResponse {
       is_active: boolean;
 
       /**
-       * Lowercase status values used in API responses (distinct from the DB-level
-       * TaskRunStatus enum).
+       * Current run status.
        */
       status: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
 
       /**
-       * Web Search Agent instance this run belongs to. Every task run is agent-bound
-       * (see AGENTS-1666). Use this to build the nested URL
-       * /api/v2/web-search-agents/{web_search_agent_id}/runs/{id}.
+       * Web Search Agent instance this run belongs to.
        */
       web_search_agent_id: string;
 
+      /**
+       * When the run completed.
+       */
       completed_at?: string | null;
 
       /**
-       * Error detail for a failed run.
+       * Error details when the run failed.
        */
       error?: Run.Error | null;
 
       /**
-       * Original user prompt before enrichment. Populated for Web Search Agent runs.
+       * Prompt submitted for the run.
        */
       prompt?: string | null;
 
+      /**
+       * When the run started executing.
+       */
       started_at?: string | null;
-
-      workspace_id?: string | null;
     }
 
     export namespace Run {
       /**
-       * Error detail for a failed run.
+       * Error details when the run failed.
        */
       export interface Error {
         /**
@@ -556,25 +763,19 @@ export namespace RunGetResultResponse {
     }
   }
 
-  /**
-   * Response for GET /tasks/runs/{run_id}/result when the run failed.
-   *
-   * Returned with HTTP 422 so callers can distinguish a failed run from a missing
-   * one (404) or an active one (408).
-   */
-  export interface TaskRunFailedResult {
+  export interface TaskRunFailedResultPublicV2 {
     /**
      * Structured error detail.
      */
-    error: TaskRunFailedResult.Error;
+    error: TaskRunFailedResultPublicV2.Error;
 
     /**
      * Task run object with status 'failed'.
      */
-    run: TaskRunFailedResult.Run;
+    run: TaskRunFailedResultPublicV2.Run;
   }
 
-  export namespace TaskRunFailedResult {
+  export namespace TaskRunFailedResultPublicV2 {
     /**
      * Structured error detail.
      */
@@ -599,15 +800,18 @@ export namespace RunGetResultResponse {
        */
       id: string;
 
+      /**
+       * When the run was created.
+       */
       created_at: string;
 
       /**
-       * Canonical effort tier names for the research graph.
+       * Effort level used for the run.
        */
       effort: 'low' | 'medium' | 'high' | 'x-high' | 'max';
 
       /**
-       * Interaction ID — pass as previous_interaction_id to reuse context.
+       * Interaction ID.
        */
       interaction_id: string;
 
@@ -617,38 +821,39 @@ export namespace RunGetResultResponse {
       is_active: boolean;
 
       /**
-       * Lowercase status values used in API responses (distinct from the DB-level
-       * TaskRunStatus enum).
+       * Current run status.
        */
       status: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
 
       /**
-       * Web Search Agent instance this run belongs to. Every task run is agent-bound
-       * (see AGENTS-1666). Use this to build the nested URL
-       * /api/v2/web-search-agents/{web_search_agent_id}/runs/{id}.
+       * Web Search Agent instance this run belongs to.
        */
       web_search_agent_id: string;
 
+      /**
+       * When the run completed.
+       */
       completed_at?: string | null;
 
       /**
-       * Error detail for a failed run.
+       * Error details when the run failed.
        */
       error?: Run.Error | null;
 
       /**
-       * Original user prompt before enrichment. Populated for Web Search Agent runs.
+       * Prompt submitted for the run.
        */
       prompt?: string | null;
 
+      /**
+       * When the run started executing.
+       */
       started_at?: string | null;
-
-      workspace_id?: string | null;
     }
 
     export namespace Run {
       /**
-       * Error detail for a failed run.
+       * Error details when the run failed.
        */
       export interface Error {
         /**
@@ -665,27 +870,118 @@ export namespace RunGetResultResponse {
   }
 }
 
-export type RunStreamEventsResponse = unknown;
+export interface RunCreateParams {
+  /**
+   * User prompt or task instructions for the run.
+   */
+  input: string;
 
-export interface RunListParams {
-  limit?: number;
+  /**
+   * Canonical effort tier names for the research graph.
+   */
+  effort?: 'low' | 'medium' | 'high' | 'x-high' | 'max' | null;
 
-  offset?: number;
+  /**
+   * Whether to stream run events when supported.
+   */
+  enable_events?: boolean;
 
-  q?: string | null;
+  /**
+   * Existing records to ENRICH: a list of partial rows, or a single object,
+   * mirroring output_schema's shape.
+   */
+  input_data?: Array<{ [key: string]: unknown }> | { [key: string]: unknown } | null;
+
+  /**
+   * JSON schema overriding the agent's default structured output for this run.
+   */
+  output_schema?: { [key: string]: unknown } | null;
 
-  status?: string | null;
+  /**
+   * Previous interaction identifier used to continue a conversation.
+   */
+  previous_interaction_id?: string | null;
+
+  /**
+   * Source guidance overriding the agent default.
+   */
+  sources?: RunCreateParams.Sources | null;
 }
 
-export interface RunCancelParams {
-  agent_id: string;
+export namespace RunCreateParams {
+  /**
+   * Source guidance overriding the agent default.
+   */
+  export interface Sources {
+    /**
+     * Source groups the agent is allowed to use.
+     */
+    allow?: Array<Sources.Allow>;
+
+    /**
+     * Free-text guidance describing sources or domains to avoid.
+     */
+    avoid?: string | null;
+
+    /**
+     * Source groups the agent should not use.
+     */
+    block?: Array<Sources.Block>;
+
+    /**
+     * Free-text guidance describing sources or domains to prioritize.
+     */
+    prioritize?: string | null;
+  }
+
+  export namespace Sources {
+    export interface Allow {
+      /**
+       * Domains included in this source group.
+       */
+      domains: Array<string>;
+
+      /**
+       * Source group title.
+       */
+      title: string;
+
+      /**
+       * Zero-based source group position.
+       */
+      order?: number;
+    }
+
+    export interface Block {
+      /**
+       * Domains included in this source group.
+       */
+      domains: Array<string>;
+
+      /**
+       * Source group title.
+       */
+      title: string;
+
+      /**
+       * Zero-based source group position.
+       */
+      order?: number;
+    }
+  }
+}
+
+export interface RunListParams {
+  limit?: number;
+
+  offset?: number;
 }
 
 export interface RunGetParams {
   agent_id: string;
 }
 
-export interface RunGetResultParams {
+export interface RunResultParams {
   agent_id: string;
 }
 
@@ -695,14 +991,14 @@ export interface RunStreamEventsParams {
 
 export declare namespace Runs {
   export {
+    type RunCreateResponse as RunCreateResponse,
     type RunListResponse as RunListResponse,
     type RunGetResponse as RunGetResponse,
-    type RunGetResultResponse as RunGetResultResponse,
-    type RunStreamEventsResponse as RunStreamEventsResponse,
+    type RunResultResponse as RunResultResponse,
+    type RunCreateParams as RunCreateParams,
     type RunListParams as RunListParams,
-    type RunCancelParams as RunCancelParams,
     type RunGetParams as RunGetParams,
-    type RunGetResultParams as RunGetResultParams,
+    type RunResultParams as RunResultParams,
     type RunStreamEventsParams as RunStreamEventsParams,
   };
 }