@nimble-way/nimble-js 0.18.0 → 0.20.0

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

@@ -3,57 +3,113 @@ import { APIPromise } from "../../core/api-promise.js";
 import { RequestOptions } from "../../internal/request-options.js";
 export declare 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").
+     *
+     * @deprecated
      */
     list(agentID: string, query?: RunListParams | null | undefined, options?: RequestOptions): APIPromise<RunListResponse>;
     /**
-     * Cancel an in-progress or queued run.
-     */
-    cancel(runID: string, params: RunCancelParams, options?: RequestOptions): APIPromise<void>;
-    /**
-     * 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.
+     *
+     * @deprecated
      */
     get(runID: string, params: RunGetParams, options?: RequestOptions): APIPromise<RunGetResponse>;
     /**
-     * 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.
+     *
+     * @deprecated
      */
     getResult(runID: string, params: RunGetResultParams, options?: RequestOptions): APIPromise<RunGetResultResponse>;
     /**
-     * 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.
+     *
+     * @deprecated
+     */
+    streamEvents(runID: string, params: RunStreamEventsParams, options?: RequestOptions): APIPromise<void>;
+}
+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.
      */
-    streamEvents(runID: string, params: RunStreamEventsParams, options?: RequestOptions): APIPromise<unknown>;
+    total: number;
 }
-export type RunListResponse = Array<RunListResponse.RunListResponseItem>;
 export declare namespace RunListResponse {
-    interface RunListResponseItem {
+    interface Item {
         /**
-         * Run identifier.
+         * Run identifier, format "task*run*{uuid}".
          */
         id: string;
+        /**
+         * When the run was created.
+         */
         created_at: string;
-        effort: 'quickest' | 'quick' | 'research' | 'pro' | 'max';
         /**
-         * Interaction ID — pass as previous_interaction_id to reuse context.
+         * 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?: RunListResponseItem.Error | null;
+        /**
+         * Error details when the run failed.
+         */
+        error?: Item.Error | null;
+        /**
+         * Prompt submitted for the run.
+         */
         prompt?: string | null;
-        started_at?: string | null;
         /**
-         * Web Search Agent instance this run belongs to.
+         * When the run started executing.
          */
-        web_search_agent_id?: string | null;
-        workspace_id?: string | null;
+        started_at?: string | null;
     }
-    namespace RunListResponseItem {
+    namespace Item {
+        /**
+         * Error details when the run failed.
+         */
         interface Error {
             /**
              * Human-readable error description.
@@ -68,31 +124,54 @@ export declare namespace RunListResponse {
 }
 export interface RunGetResponse {
     /**
-     * Run identifier.
+     * Run identifier, format "task*run*{uuid}".
      */
     id: string;
+    /**
+     * When the run was created.
+     */
     created_at: string;
-    effort: 'quickest' | 'quick' | 'research' | 'pro' | 'max';
     /**
-     * Interaction ID — pass as previous_interaction_id to reuse context.
+     * 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?: RunGetResponse.Error | null;
+    /**
+     * Prompt submitted for the run.
+     */
     prompt?: string | null;
-    started_at?: string | null;
     /**
-     * Web Search Agent instance this run belongs to.
+     * When the run started executing.
      */
-    web_search_agent_id?: string | null;
-    workspace_id?: string | null;
+    started_at?: string | null;
 }
 export declare namespace RunGetResponse {
+    /**
+     * Error details when the run failed.
+     */
     interface Error {
         /**
          * Human-readable error description.
@@ -104,129 +183,378 @@ export declare namespace RunGetResponse {
         ref_id: string;
     }
 }
-export type RunGetResultResponse = RunGetResultResponse.AgentRunResult | RunGetResultResponse.AgentRunFailedResult;
+export type RunGetResultResponse = RunGetResultResponse.TaskRunResultPublicV1 | RunGetResultResponse.TaskRunFailedResultPublicV1;
 export declare namespace RunGetResultResponse {
-    interface AgentRunResult {
-        output: AgentRunResult.AgentRunTextOutput | AgentRunResult.AgentRunJsonOutput;
-        run: AgentRunResult.Run;
+    interface TaskRunResultPublicV1 {
+        /**
+         * Output from the completed task.
+         */
+        output: TaskRunResultPublicV1.TaskRunTextOutputPublicV1 | TaskRunResultPublicV1.TaskRunJsonOutputPublicV1;
+        /**
+         * Task run object with status 'completed'.
+         */
+        run: TaskRunResultPublicV1.Run;
     }
-    namespace AgentRunResult {
-        interface AgentRunTextOutput {
+    namespace TaskRunResultPublicV1 {
+        interface TaskRunTextOutputPublicV1 {
             /**
              * The final prose answer.
              */
             content: string;
-            trust: AgentRunTextOutput.Trust;
+            /**
+             * Trust and citation metadata for the output.
+             */
+            trust: TaskRunTextOutputPublicV1.Trust;
+            /**
+             * Output content type.
+             */
             type?: 'text';
         }
-        namespace AgentRunTextOutput {
+        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;
-                    source?: Claim.Source | null;
                 }
                 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;
-                        title?: string | null;
-                    }
-                    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;
+                        /**
+                         * 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
+                     * 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 of the source page.
+                     */
                     title?: string | null;
                 }
             }
         }
-        interface AgentRunJsonOutput {
+        interface TaskRunJsonOutputPublicV1 {
+            /**
+             * The final structured output.
+             */
             content: {
                 [key: string]: unknown;
             } | Array<unknown>;
-            trust: AgentRunJsonOutput.Trust;
+            /**
+             * Trust and citation metadata for the output.
+             */
+            trust: TaskRunJsonOutputPublicV1.Trust;
+            /**
+             * Output content type.
+             */
             type?: 'json';
         }
-        namespace AgentRunJsonOutput {
+        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;
-                    source?: Claim.Source | null;
                 }
                 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;
-                        title?: string | null;
-                    }
-                    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;
+                        /**
+                         * 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
+                     * 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 of the source page.
+                     */
                     title?: string | null;
                 }
             }
         }
+        /**
+         * Task run object with status 'completed'.
+         */
         interface Run {
             /**
-             * Run identifier.
+             * Run identifier, format "task*run*{uuid}".
              */
             id: string;
+            /**
+             * When the run was created.
+             */
             created_at: string;
-            effort: 'quickest' | 'quick' | 'research' | 'pro' | 'max';
             /**
-             * Interaction ID — pass as previous_interaction_id to reuse context.
+             * 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?: Run.Error | null;
+            /**
+             * Prompt submitted for the run.
+             */
             prompt?: string | null;
-            started_at?: string | null;
             /**
-             * Web Search Agent instance this run belongs to.
+             * When the run started executing.
              */
-            web_search_agent_id?: string | null;
-            workspace_id?: string | null;
+            started_at?: string | null;
         }
         namespace Run {
+            /**
+             * Error details when the run failed.
+             */
             interface Error {
                 /**
                  * Human-readable error description.
@@ -239,11 +567,20 @@ export declare namespace RunGetResultResponse {
             }
         }
     }
-    interface AgentRunFailedResult {
-        error: AgentRunFailedResult.Error;
-        run: AgentRunFailedResult.Run;
+    interface TaskRunFailedResultPublicV1 {
+        /**
+         * Structured error detail.
+         */
+        error: TaskRunFailedResultPublicV1.Error;
+        /**
+         * Task run object with status 'failed'.
+         */
+        run: TaskRunFailedResultPublicV1.Run;
     }
-    namespace AgentRunFailedResult {
+    namespace TaskRunFailedResultPublicV1 {
+        /**
+         * Structured error detail.
+         */
         interface Error {
             /**
              * Human-readable error description.
@@ -254,33 +591,59 @@ export declare namespace RunGetResultResponse {
              */
             ref_id: string;
         }
+        /**
+         * Task run object with status 'failed'.
+         */
         interface Run {
             /**
-             * Run identifier.
+             * Run identifier, format "task*run*{uuid}".
              */
             id: string;
+            /**
+             * When the run was created.
+             */
             created_at: string;
-            effort: 'quickest' | 'quick' | 'research' | 'pro' | 'max';
             /**
-             * Interaction ID — pass as previous_interaction_id to reuse context.
+             * 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?: Run.Error | null;
+            /**
+             * Prompt submitted for the run.
+             */
             prompt?: string | null;
-            started_at?: string | null;
             /**
-             * Web Search Agent instance this run belongs to.
+             * When the run started executing.
              */
-            web_search_agent_id?: string | null;
-            workspace_id?: string | null;
+            started_at?: string | null;
         }
         namespace Run {
+            /**
+             * Error details when the run failed.
+             */
             interface Error {
                 /**
                  * Human-readable error description.
@@ -294,14 +657,10 @@ export declare namespace RunGetResultResponse {
         }
     }
 }
-export type RunStreamEventsResponse = unknown;
 export interface RunListParams {
     limit?: number;
     offset?: number;
 }
-export interface RunCancelParams {
-    agent_id: string;
-}
 export interface RunGetParams {
     agent_id: string;
 }
@@ -312,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