@nimble-way/nimble-js 0.19.0 → 0.20.0

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

@@ -7,21 +7,18 @@ export declare class Runs extends APIResource {
      *
      * `status` accepts a lowercase `TaskRunStatusValue` (e.g. "completed") or a
      * comma-separated list of them (e.g. "queued,running").
-     */
-    list(agentID: string, query?: RunListParams | null | undefined, options?: RequestOptions): APIPromise<RunListResponse>;
-    /**
-     * 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}`).
+     * @deprecated
      */
-    cancel(runID: string, params: RunCancelParams, options?: RequestOptions): APIPromise<void>;
+    list(agentID: string, query?: RunListParams | null | undefined, options?: RequestOptions): APIPromise<RunListResponse>;
     /**
      * 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.
+     *
+     * @deprecated
      */
     get(runID: string, params: RunGetParams, options?: RequestOptions): APIPromise<RunGetResponse>;
     /**
@@ -33,38 +30,51 @@ export declare class Runs extends APIResource {
      * - 408 when the run is still active.
      * - 422 (with TaskRunFailedResult body) when the run failed or was cancelled.
      * - 200 (with TaskRunResult body) on success.
+     *
+     * @deprecated
      */
     getResult(runID: string, params: RunGetResultParams, options?: RequestOptions): APIPromise<RunGetResultResponse>;
     /**
      * SSE stream of real-time progress events for a run on this instance.
+     *
+     * @deprecated
      */
-    streamEvents(runID: string, params: RunStreamEventsParams, options?: RequestOptions): APIPromise<unknown>;
+    streamEvents(runID: string, params: RunStreamEventsParams, options?: RequestOptions): APIPromise<void>;
 }
-/**
- * Paginated list of task runs for GET /tasks/runs.
- */
 export interface RunListResponse {
+    /**
+     * Items returned in this page.
+     */
     items: Array<RunListResponse.Item>;
+    /**
+     * Maximum number of items returned.
+     */
+    limit: number;
+    /**
+     * Number of items skipped before this page.
+     */
+    offset: number;
+    /**
+     * Total number of items matching the query.
+     */
     total: number;
-    limit?: number;
-    offset?: number;
 }
 export declare namespace RunListResponse {
-    /**
-     * Task run status returned by list/create/get endpoints.
-     */
     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;
         /**
@@ -72,31 +82,33 @@ export declare 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;
     }
     namespace Item {
         /**
-         * Error detail for a failed run.
+         * Error details when the run failed.
          */
         interface Error {
             /**
@@ -110,21 +122,21 @@ export declare 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;
     /**
@@ -132,31 +144,33 @@ 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 declare namespace RunGetResponse {
     /**
-     * Error detail for a failed run.
+     * Error details when the run failed.
      */
     interface Error {
         /**
@@ -169,54 +183,93 @@ export declare namespace RunGetResponse {
         ref_id: string;
     }
 }
-/**
- * Response for GET /tasks/runs/{run_id}/result — status 'completed'.
- */
-export type RunGetResultResponse = RunGetResultResponse.TaskRunResult | RunGetResultResponse.TaskRunFailedResult;
+export type RunGetResultResponse = RunGetResultResponse.TaskRunResultPublicV1 | RunGetResultResponse.TaskRunFailedResultPublicV1;
 export declare namespace RunGetResultResponse {
-    /**
-     * Response for GET /tasks/runs/{run_id}/result — status 'completed'.
-     */
-    interface TaskRunResult {
+    interface TaskRunResultPublicV1 {
         /**
          * Output from the completed task.
          */
-        output: TaskRunResult.TaskRunTextOutput | TaskRunResult.TaskRunJsonOutput;
+        output: TaskRunResultPublicV1.TaskRunTextOutputPublicV1 | TaskRunResultPublicV1.TaskRunJsonOutputPublicV1;
         /**
          * Task run object with status 'completed'.
          */
-        run: TaskRunResult.Run;
+        run: TaskRunResultPublicV1.Run;
     }
-    namespace TaskRunResult {
-        /**
-         * Text output from a completed task.
-         */
-        interface TaskRunTextOutput {
+    namespace TaskRunResultPublicV1 {
+        interface TaskRunTextOutputPublicV1 {
             /**
              * The final prose answer.
              */
             content: string;
-            trust: TaskRunTextOutput.Trust;
+            /**
+             * Trust and citation metadata for the output.
+             */
+            trust: TaskRunTextOutputPublicV1.Trust;
+            /**
+             * Output content type.
+             */
             type?: 'text';
         }
-        namespace TaskRunTextOutput {
+        namespace TaskRunTextOutputPublicV1 {
+            /**
+             * Trust and citation metadata for the output.
+             */
             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>;
             }
             namespace Trust {
+                /**
+                 * Trust metadata for one claim in a prose answer, keyed by callout marker.
+                 */
                 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;
                 }
                 namespace Claim {
+                    /**
+                     * A citation backing a specific claim in the answer.
+                     */
                     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;
                         /**
                          * What _kind_ of source this is (classified by the compress LLM), independent of
@@ -240,13 +293,31 @@ export declare namespace RunGetResultResponse {
                          * directly.
                          */
                         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.
+                 */
                 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;
                     /**
                      * What _kind_ of source this is (classified by the compress LLM), independent of
@@ -270,43 +341,89 @@ export declare namespace RunGetResultResponse {
                      * directly.
                      */
                     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'.
-         */
-        interface TaskRunJsonOutput {
+        interface TaskRunJsonOutputPublicV1 {
             /**
-             * 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: TaskRunJsonOutputPublicV1.Trust;
+            /**
+             * Output content type.
+             */
             type?: 'json';
         }
-        namespace TaskRunJsonOutput {
+        namespace TaskRunJsonOutputPublicV1 {
+            /**
+             * Trust and citation metadata for the output.
+             */
             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>;
             }
             namespace Trust {
+                /**
+                 * Trust metadata for one value in a structured (JSON) answer, keyed by JSON path.
+                 */
                 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;
                 }
                 namespace Claim {
+                    /**
+                     * A citation backing a specific claim in the answer.
+                     */
                     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;
                         /**
                          * What _kind_ of source this is (classified by the compress LLM), independent of
@@ -330,13 +447,31 @@ export declare namespace RunGetResultResponse {
                          * directly.
                          */
                         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.
+                 */
                 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;
                     /**
                      * What _kind_ of source this is (classified by the compress LLM), independent of
@@ -360,6 +495,9 @@ export declare namespace RunGetResultResponse {
                      * directly.
                      */
                     source_intent?: 'official' | 'news' | 'social' | 'academic' | 'aggregator' | 'other' | null;
+                    /**
+                     * Title of the source page.
+                     */
                     title?: string | null;
                 }
             }
@@ -372,13 +510,16 @@ export declare namespace RunGetResultResponse {
              * 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;
             /**
@@ -386,31 +527,33 @@ export declare 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;
         }
         namespace Run {
             /**
-             * Error detail for a failed run.
+             * Error details when the run failed.
              */
             interface Error {
                 /**
@@ -424,23 +567,17 @@ export declare 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).
-     */
-    interface TaskRunFailedResult {
+    interface TaskRunFailedResultPublicV1 {
         /**
          * Structured error detail.
          */
-        error: TaskRunFailedResult.Error;
+        error: TaskRunFailedResultPublicV1.Error;
         /**
          * Task run object with status 'failed'.
          */
-        run: TaskRunFailedResult.Run;
+        run: TaskRunFailedResultPublicV1.Run;
     }
-    namespace TaskRunFailedResult {
+    namespace TaskRunFailedResultPublicV1 {
         /**
          * Structured error detail.
          */
@@ -462,13 +599,16 @@ export declare namespace RunGetResultResponse {
              * 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;
             /**
@@ -476,31 +616,33 @@ export declare 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;
         }
         namespace Run {
             /**
-             * Error detail for a failed run.
+             * Error details when the run failed.
              */
             interface Error {
                 /**
@@ -515,15 +657,9 @@ export declare namespace RunGetResultResponse {
         }
     }
 }
-export type RunStreamEventsResponse = unknown;
 export interface RunListParams {
     limit?: number;
     offset?: number;
-    q?: string | null;
-    status?: string | null;
-}
-export interface RunCancelParams {
-    agent_id: string;
 }
 export interface RunGetParams {
     agent_id: string;
@@ -535,6 +671,6 @@ export interface RunStreamEventsParams {
     agent_id: string;
 }
 export declare namespace Runs {
-    export { type RunListResponse as RunListResponse, type RunGetResponse as RunGetResponse, type RunGetResultResponse as RunGetResultResponse, type RunStreamEventsResponse as RunStreamEventsResponse, type RunListParams as RunListParams, type RunCancelParams as RunCancelParams, type RunGetParams as RunGetParams, type RunGetResultParams as RunGetResultParams, type RunStreamEventsParams as RunStreamEventsParams, };
+    export { type RunListResponse as RunListResponse, type RunGetResponse as RunGetResponse, type RunGetResultResponse as RunGetResultResponse, type RunListParams as RunListParams, type RunGetParams as RunGetParams, type RunGetResultParams as RunGetResultParams, type RunStreamEventsParams as RunStreamEventsParams, };
 }
 //# sourceMappingURL=runs.d.ts.map