@nimble-way/nimble-js 0.18.0 → 0.19.0

package/src/resources/task-agent/runs.ts

@@ -8,7 +8,10 @@ import { path } from '../../internal/utils/path';
 
 export class Runs extends APIResource {
   /**
-   * List task runs for the caller's workspace and the given agent, newest first.
+   * List runs for this instance.
+   *
+   * `status` accepts a lowercase `TaskRunStatusValue` (e.g. "completed") or a
+   * comma-separated list of them (e.g. "queued,running").
    */
   list(
     agentID: string,
@@ -20,6 +23,9 @@ export class Runs extends APIResource {
 
   /**
    * 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}`).
    */
   cancel(runID: string, params: RunCancelParams, options?: RequestOptions): APIPromise<void> {
     const { agent_id } = params;
@@ -30,7 +36,11 @@ export class Runs extends APIResource {
   }
 
   /**
-   * Poll run status. Repeat until status is 'completed', 'failed', or 'cancelled'.
+   * Fetch a run by id, scoped to the instance.
+   *
+   * 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.
    */
   get(runID: string, params: RunGetParams, options?: RequestOptions): APIPromise<RunGetResponse> {
     const { agent_id } = params;
@@ -38,8 +48,14 @@ export class Runs extends APIResource {
   }
 
   /**
-   * Fetch the result for a terminal run. Returns 408 if still active, 422 with
-   * `AgentRunFailedResult` if failed.
+   * 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,
@@ -51,8 +67,7 @@ export class Runs extends APIResource {
   }
 
   /**
-   * Server-Sent Events stream of real-time progress events for a run. The run must
-   * have been created with `enable_events=true`.
+   * SSE stream of real-time progress events for a run on this instance.
    */
   streamEvents(runID: string, params: RunStreamEventsParams, options?: RequestOptions): APIPromise<unknown> {
     const { agent_id } = params;
@@ -60,18 +75,35 @@ export class Runs extends APIResource {
   }
 }
 
-export type RunListResponse = Array<RunListResponse.RunListResponseItem>;
+/**
+ * Paginated list of task runs for GET /tasks/runs.
+ */
+export interface RunListResponse {
+  items: Array<RunListResponse.Item>;
+
+  total: number;
+
+  limit?: number;
+
+  offset?: number;
+}
 
 export namespace RunListResponse {
-  export interface RunListResponseItem {
+  /**
+   * Task run status returned by list/create/get endpoints.
+   */
+  export interface Item {
     /**
-     * Run identifier.
+     * Run identifier, format "task*run*{uuid}".
      */
     id: string;
 
     created_at: string;
 
-    effort: 'quickest' | 'quick' | 'research' | 'pro' | 'max';
+    /**
+     * Canonical effort tier names for the research graph.
+     */
+    effort: 'low' | 'medium' | 'high' | 'x-high' | 'max';
 
     /**
      * Interaction ID — pass as previous_interaction_id to reuse context.
@@ -83,25 +115,40 @@ export namespace RunListResponse {
      */
     is_active: boolean;
 
+    /**
+     * Lowercase status values used in API responses (distinct from the DB-level
+     * TaskRunStatus enum).
+     */
     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_id: string;
+
     completed_at?: string | null;
 
-    error?: RunListResponseItem.Error | null;
+    /**
+     * Error detail for a failed run.
+     */
+    error?: Item.Error | null;
 
+    /**
+     * Original user prompt before enrichment. Populated for Web Search Agent runs.
+     */
     prompt?: string | null;
 
     started_at?: string | null;
 
-    /**
-     * Web Search Agent instance this run belongs to.
-     */
-    web_search_agent_id?: string | null;
-
     workspace_id?: string | null;
   }
 
-  export namespace RunListResponseItem {
+  export namespace Item {
+    /**
+     * Error detail for a failed run.
+     */
     export interface Error {
       /**
        * Human-readable error description.
@@ -116,15 +163,21 @@ export namespace RunListResponse {
   }
 }
 
+/**
+ * Task run status returned by list/create/get endpoints.
+ */
 export interface RunGetResponse {
   /**
-   * Run identifier.
+   * Run identifier, format "task*run*{uuid}".
    */
   id: string;
 
   created_at: string;
 
-  effort: 'quickest' | 'quick' | 'research' | 'pro' | 'max';
+  /**
+   * Canonical effort tier names for the research graph.
+   */
+  effort: 'low' | 'medium' | 'high' | 'x-high' | 'max';
 
   /**
    * Interaction ID — pass as previous_interaction_id to reuse context.
@@ -136,25 +189,40 @@ export interface RunGetResponse {
    */
   is_active: boolean;
 
+  /**
+   * Lowercase status values used in API responses (distinct from the DB-level
+   * TaskRunStatus enum).
+   */
   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_id: string;
+
   completed_at?: string | null;
 
+  /**
+   * Error detail for a failed run.
+   */
   error?: RunGetResponse.Error | null;
 
+  /**
+   * Original user prompt before enrichment. Populated for Web Search Agent runs.
+   */
   prompt?: string | null;
 
   started_at?: string | null;
 
-  /**
-   * Web Search Agent instance this run belongs to.
-   */
-  web_search_agent_id?: string | null;
-
   workspace_id?: string | null;
 }
 
 export namespace RunGetResponse {
+  /**
+   * Error detail for a failed run.
+   */
   export interface Error {
     /**
      * Human-readable error description.
@@ -168,30 +236,45 @@ export namespace RunGetResponse {
   }
 }
 
+/**
+ * Response for GET /tasks/runs/{run_id}/result — status 'completed'.
+ */
 export type RunGetResultResponse =
-  | RunGetResultResponse.AgentRunResult
-  | RunGetResultResponse.AgentRunFailedResult;
+  | RunGetResultResponse.TaskRunResult
+  | RunGetResultResponse.TaskRunFailedResult;
 
 export namespace RunGetResultResponse {
-  export interface AgentRunResult {
-    output: AgentRunResult.AgentRunTextOutput | AgentRunResult.AgentRunJsonOutput;
+  /**
+   * Response for GET /tasks/runs/{run_id}/result — status 'completed'.
+   */
+  export interface TaskRunResult {
+    /**
+     * Output from the completed task.
+     */
+    output: TaskRunResult.TaskRunTextOutput | TaskRunResult.TaskRunJsonOutput;
 
-    run: AgentRunResult.Run;
+    /**
+     * Task run object with status 'completed'.
+     */
+    run: TaskRunResult.Run;
   }
 
-  export namespace AgentRunResult {
-    export interface AgentRunTextOutput {
+  export namespace TaskRunResult {
+    /**
+     * Text output from a completed task.
+     */
+    export interface TaskRunTextOutput {
       /**
        * The final prose answer.
        */
       content: string;
 
-      trust: AgentRunTextOutput.Trust;
+      trust: TaskRunTextOutput.Trust;
 
       type?: 'text';
     }
 
-    export namespace AgentRunTextOutput {
+    export namespace TaskRunTextOutput {
       export interface Trust {
         claims: Array<Trust.Claim>;
 
@@ -211,8 +294,6 @@ export namespace RunGetResultResponse {
           confidence: 'high' | 'medium' | 'low';
 
           reasoning: string;
-
-          source?: Claim.Source | null;
         }
 
         export namespace Claim {
@@ -223,15 +304,31 @@ export namespace RunGetResultResponse {
 
             extract_template_name?: string | null;
 
-            title?: string | null;
-          }
-
-          export interface Source {
-            type: 'primary' | 'secondary';
-
-            url: string;
-
-            extract_template_name?: string | null;
+            /**
+             * What _kind_ of source this is (classified by the compress LLM), independent of
+             * TrustSourceType (how authoritative it is for a specific claim). Deliberately
+             * uses "official" rather than "primary" so the two axes can never collide.
+             *
+             * Also doubles as the sub-question's `source_intent` (what kind of source a
+             * question _needs_) — the two concepts overlap enough that a single enum lets
+             * `classify_source_importance` compare "what we got" against "what we asked for"
+             * directly.
+             */
+            source_category?: 'official' | 'news' | 'social' | 'academic' | 'aggregator' | 'other' | null;
+
+            /**
+             * What _kind_ of source this is (classified by the compress LLM), independent of
+             * TrustSourceType (how authoritative it is for a specific claim). Deliberately
+             * uses "official" rather than "primary" so the two axes can never collide.
+             *
+             * Also doubles as the sub-question's `source_intent` (what kind of source a
+             * question _needs_) — the two concepts overlap enough that a single enum lets
+             * `classify_source_importance` compare "what we got" against "what we asked for"
+             * directly.
+             */
+            source_intent?: 'official' | 'news' | 'social' | 'academic' | 'aggregator' | 'other' | null;
+
+            source_type?: 'primary' | 'secondary' | null;
 
             title?: string | null;
           }
@@ -244,20 +341,52 @@ export namespace RunGetResultResponse {
 
           extract_template_name?: string | null;
 
+          /**
+           * What _kind_ of source this is (classified by the compress LLM), independent of
+           * TrustSourceType (how authoritative it is for a specific claim). Deliberately
+           * uses "official" rather than "primary" so the two axes can never collide.
+           *
+           * Also doubles as the sub-question's `source_intent` (what kind of source a
+           * question _needs_) — the two concepts overlap enough that a single enum lets
+           * `classify_source_importance` compare "what we got" against "what we asked for"
+           * directly.
+           */
+          source_category?: 'official' | 'news' | 'social' | 'academic' | 'aggregator' | 'other' | null;
+
+          /**
+           * What _kind_ of source this is (classified by the compress LLM), independent of
+           * TrustSourceType (how authoritative it is for a specific claim). Deliberately
+           * uses "official" rather than "primary" so the two axes can never collide.
+           *
+           * Also doubles as the sub-question's `source_intent` (what kind of source a
+           * question _needs_) — the two concepts overlap enough that a single enum lets
+           * `classify_source_importance` compare "what we got" against "what we asked for"
+           * directly.
+           */
+          source_intent?: 'official' | 'news' | 'social' | 'academic' | 'aggregator' | 'other' | null;
+
           title?: string | null;
         }
       }
     }
 
-    export interface AgentRunJsonOutput {
+    /**
+     * Structured JSON output from a completed task, produced when
+     * task_spec.output_schema.type is 'json'.
+     */
+    export interface TaskRunJsonOutput {
+      /**
+       * Data conforming to the caller-supplied JSON schema. A dict for object schemas; a
+       * list for array schemas.
+       */
       content: { [key: string]: unknown } | Array<unknown>;
 
-      trust: AgentRunJsonOutput.Trust;
+      trust: TaskRunJsonOutput.Trust;
 
       type?: 'json';
     }
 
-    export namespace AgentRunJsonOutput {
+    export namespace TaskRunJsonOutput {
       export interface Trust {
         claims: Array<Trust.Claim>;
 
@@ -277,8 +406,6 @@ export namespace RunGetResultResponse {
           path: string;
 
           reasoning: string;
-
-          source?: Claim.Source | null;
         }
 
         export namespace Claim {
@@ -289,15 +416,31 @@ export namespace RunGetResultResponse {
 
             extract_template_name?: string | null;
 
-            title?: string | null;
-          }
-
-          export interface Source {
-            type: 'primary' | 'secondary';
-
-            url: string;
-
-            extract_template_name?: string | null;
+            /**
+             * What _kind_ of source this is (classified by the compress LLM), independent of
+             * TrustSourceType (how authoritative it is for a specific claim). Deliberately
+             * uses "official" rather than "primary" so the two axes can never collide.
+             *
+             * Also doubles as the sub-question's `source_intent` (what kind of source a
+             * question _needs_) — the two concepts overlap enough that a single enum lets
+             * `classify_source_importance` compare "what we got" against "what we asked for"
+             * directly.
+             */
+            source_category?: 'official' | 'news' | 'social' | 'academic' | 'aggregator' | 'other' | null;
+
+            /**
+             * What _kind_ of source this is (classified by the compress LLM), independent of
+             * TrustSourceType (how authoritative it is for a specific claim). Deliberately
+             * uses "official" rather than "primary" so the two axes can never collide.
+             *
+             * Also doubles as the sub-question's `source_intent` (what kind of source a
+             * question _needs_) — the two concepts overlap enough that a single enum lets
+             * `classify_source_importance` compare "what we got" against "what we asked for"
+             * directly.
+             */
+            source_intent?: 'official' | 'news' | 'social' | 'academic' | 'aggregator' | 'other' | null;
+
+            source_type?: 'primary' | 'secondary' | null;
 
             title?: string | null;
           }
@@ -310,20 +453,50 @@ export namespace RunGetResultResponse {
 
           extract_template_name?: string | null;
 
+          /**
+           * What _kind_ of source this is (classified by the compress LLM), independent of
+           * TrustSourceType (how authoritative it is for a specific claim). Deliberately
+           * uses "official" rather than "primary" so the two axes can never collide.
+           *
+           * Also doubles as the sub-question's `source_intent` (what kind of source a
+           * question _needs_) — the two concepts overlap enough that a single enum lets
+           * `classify_source_importance` compare "what we got" against "what we asked for"
+           * directly.
+           */
+          source_category?: 'official' | 'news' | 'social' | 'academic' | 'aggregator' | 'other' | null;
+
+          /**
+           * What _kind_ of source this is (classified by the compress LLM), independent of
+           * TrustSourceType (how authoritative it is for a specific claim). Deliberately
+           * uses "official" rather than "primary" so the two axes can never collide.
+           *
+           * Also doubles as the sub-question's `source_intent` (what kind of source a
+           * question _needs_) — the two concepts overlap enough that a single enum lets
+           * `classify_source_importance` compare "what we got" against "what we asked for"
+           * directly.
+           */
+          source_intent?: 'official' | 'news' | 'social' | 'academic' | 'aggregator' | 'other' | null;
+
           title?: string | null;
         }
       }
     }
 
+    /**
+     * Task run object with status 'completed'.
+     */
     export interface Run {
       /**
-       * Run identifier.
+       * Run identifier, format "task*run*{uuid}".
        */
       id: string;
 
       created_at: string;
 
-      effort: 'quickest' | 'quick' | 'research' | 'pro' | 'max';
+      /**
+       * Canonical effort tier names for the research graph.
+       */
+      effort: 'low' | 'medium' | 'high' | 'x-high' | 'max';
 
       /**
        * Interaction ID — pass as previous_interaction_id to reuse context.
@@ -335,25 +508,40 @@ export namespace RunGetResultResponse {
        */
       is_active: boolean;
 
+      /**
+       * Lowercase status values used in API responses (distinct from the DB-level
+       * TaskRunStatus enum).
+       */
       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_id: string;
+
       completed_at?: string | null;
 
+      /**
+       * Error detail for a failed run.
+       */
       error?: Run.Error | null;
 
+      /**
+       * Original user prompt before enrichment. Populated for Web Search Agent runs.
+       */
       prompt?: string | null;
 
       started_at?: string | null;
 
-      /**
-       * Web Search Agent instance this run belongs to.
-       */
-      web_search_agent_id?: string | null;
-
       workspace_id?: string | null;
     }
 
     export namespace Run {
+      /**
+       * Error detail for a failed run.
+       */
       export interface Error {
         /**
          * Human-readable error description.
@@ -368,13 +556,28 @@ export namespace RunGetResultResponse {
     }
   }
 
-  export interface AgentRunFailedResult {
-    error: AgentRunFailedResult.Error;
+  /**
+   * 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 {
+    /**
+     * Structured error detail.
+     */
+    error: TaskRunFailedResult.Error;
 
-    run: AgentRunFailedResult.Run;
+    /**
+     * Task run object with status 'failed'.
+     */
+    run: TaskRunFailedResult.Run;
   }
 
-  export namespace AgentRunFailedResult {
+  export namespace TaskRunFailedResult {
+    /**
+     * Structured error detail.
+     */
     export interface Error {
       /**
        * Human-readable error description.
@@ -387,15 +590,21 @@ export namespace RunGetResultResponse {
       ref_id: string;
     }
 
+    /**
+     * Task run object with status 'failed'.
+     */
     export interface Run {
       /**
-       * Run identifier.
+       * Run identifier, format "task*run*{uuid}".
        */
       id: string;
 
       created_at: string;
 
-      effort: 'quickest' | 'quick' | 'research' | 'pro' | 'max';
+      /**
+       * Canonical effort tier names for the research graph.
+       */
+      effort: 'low' | 'medium' | 'high' | 'x-high' | 'max';
 
       /**
        * Interaction ID — pass as previous_interaction_id to reuse context.
@@ -407,25 +616,40 @@ export namespace RunGetResultResponse {
        */
       is_active: boolean;
 
+      /**
+       * Lowercase status values used in API responses (distinct from the DB-level
+       * TaskRunStatus enum).
+       */
       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_id: string;
+
       completed_at?: string | null;
 
+      /**
+       * Error detail for a failed run.
+       */
       error?: Run.Error | null;
 
+      /**
+       * Original user prompt before enrichment. Populated for Web Search Agent runs.
+       */
       prompt?: string | null;
 
       started_at?: string | null;
 
-      /**
-       * Web Search Agent instance this run belongs to.
-       */
-      web_search_agent_id?: string | null;
-
       workspace_id?: string | null;
     }
 
     export namespace Run {
+      /**
+       * Error detail for a failed run.
+       */
       export interface Error {
         /**
          * Human-readable error description.
@@ -447,6 +671,10 @@ export interface RunListParams {
   limit?: number;
 
   offset?: number;
+
+  q?: string | null;
+
+  status?: string | null;
 }
 
 export interface RunCancelParams {