@nimble-way/nimble-js 1.0.0 → 1.2.0

package/src/resources/agents/agents.ts

@@ -12,6 +12,7 @@ import {
   RunResultParams,
   RunResultResponse,
   RunStreamEventsParams,
+  RunStreamEventsResponse,
   Runs,
 } from './runs';
 import * as TemplatesAPI from './templates';
@@ -80,6 +81,14 @@ export class Agents extends APIResource {
   get(agentID: string, options?: RequestOptions): APIPromise<AgentGetResponse> {
     return this._client.get(path`/v2/agents/${agentID}`, options);
   }
+
+  /**
+   * Creates a minimal persistent Web Search Agent and starts a run for it. The
+   * response includes `web_search_agent_id` for later agent and run queries.
+   */
+  run(body: AgentRunParams, options?: RequestOptions): APIPromise<AgentRunResponse> {
+    return this._client.post('/v2/agents/runs', { body, ...options });
+  }
 }
 
 export interface AgentCreateResponse {
@@ -103,11 +112,6 @@ export interface AgentCreateResponse {
    */
   display_name: string;
 
-  /**
-   * Domain expertise or operating context for the agent.
-   */
-  domain_expertise: string;
-
   /**
    * Default effort level for this agent's runs.
    */
@@ -133,6 +137,11 @@ export interface AgentCreateResponse {
    */
   output_schema: { [key: string]: unknown } | null;
 
+  /**
+   * Skill or operating context for the agent.
+   */
+  skill: string;
+
   /**
    * Source guidance for the agent.
    */
@@ -287,11 +296,6 @@ export interface AgentUpdateResponse {
    */
   display_name: string;
 
-  /**
-   * Domain expertise or operating context for the agent.
-   */
-  domain_expertise: string;
-
   /**
    * Default effort level for this agent's runs.
    */
@@ -317,6 +321,11 @@ export interface AgentUpdateResponse {
    */
   output_schema: { [key: string]: unknown } | null;
 
+  /**
+   * Skill or operating context for the agent.
+   */
+  skill: string;
+
   /**
    * Source guidance for the agent.
    */
@@ -494,11 +503,6 @@ export namespace AgentListResponse {
      */
     display_name: string;
 
-    /**
-     * Domain expertise or operating context for the agent.
-     */
-    domain_expertise: string;
-
     /**
      * Default effort level for this agent's runs.
      */
@@ -524,6 +528,11 @@ export namespace AgentListResponse {
      */
     output_schema: { [key: string]: unknown } | null;
 
+    /**
+     * Skill or operating context for the agent.
+     */
+    skill: string;
+
     /**
      * Source guidance for the agent.
      */
@@ -679,11 +688,6 @@ export interface AgentGetResponse {
    */
   display_name: string;
 
-  /**
-   * Domain expertise or operating context for the agent.
-   */
-  domain_expertise: string;
-
   /**
    * Default effort level for this agent's runs.
    */
@@ -709,6 +713,11 @@ export interface AgentGetResponse {
    */
   output_schema: { [key: string]: unknown } | null;
 
+  /**
+   * Skill or operating context for the agent.
+   */
+  skill: string;
+
   /**
    * Source guidance for the agent.
    */
@@ -842,6 +851,80 @@ export namespace AgentGetResponse {
   }
 }
 
+export interface AgentRunResponse {
+  /**
+   * Run identifier, format "task*run*{uuid}".
+   */
+  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?: AgentRunResponse.Error | null;
+
+  /**
+   * Prompt submitted for the run.
+   */
+  prompt?: string | null;
+
+  /**
+   * When the run started executing.
+   */
+  started_at?: string | null;
+}
+
+export namespace AgentRunResponse {
+  /**
+   * Error details when the run failed.
+   */
+  export interface Error {
+    /**
+     * Human-readable error description.
+     */
+    message: string;
+
+    /**
+     * Reference ID (equals the run id).
+     */
+    ref_id: string;
+  }
+}
+
 export interface AgentCreateParams {
   /**
    * Stable agent name.
@@ -858,11 +941,6 @@ export interface AgentCreateParams {
    */
   display_name?: string | null;
 
-  /**
-   * Domain expertise or operating context for the agent.
-   */
-  domain_expertise?: string | null;
-
   /**
    * Default effort level for this agent's runs.
    */
@@ -888,6 +966,11 @@ export interface AgentCreateParams {
    */
   output_schema?: { [key: string]: unknown } | null;
 
+  /**
+   * Skill or operating context for the agent.
+   */
+  skill?: string | null;
+
   /**
    * Source guidance for the agent.
    */
@@ -1003,6 +1086,132 @@ export interface AgentListParams {
   workspace_id?: string | null;
 }
 
+export interface AgentRunParams {
+  /**
+   * User prompt or task instructions for the run.
+   */
+  input: string;
+
+  /**
+   * Stable agent name. On this no-agent-id route, an unseen name creates a new
+   * agent; an existing name reuses it. Ignored on the /{agent_id}/runs route.
+   */
+  agent_name?: string | null;
+
+  /**
+   * Canonical effort tier names for the research graph.
+   */
+  effort?: 'low' | 'medium' | 'high' | 'x-high' | 'max' | null;
+
+  /**
+   * Whether to stream run events when supported.
+   */
+  enable_events?: boolean;
+
+  /**
+   * 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;
+
+  /**
+   * Origin of public API runs. Public requests are always API-originated.
+   */
+  origin?: 'api';
+
+  /**
+   * JSON schema overriding the agent's default structured output for this run.
+   */
+  output_schema?: { [key: string]: unknown } | null;
+
+  /**
+   * Previous interaction identifier used to continue a conversation.
+   */
+  previous_interaction_id?: string | null;
+
+  /**
+   * Skill override for this run. One-time only, except when this run creates a new
+   * agent via agent_name, in which case it becomes the new agent's stored skill.
+   */
+  skill?: string | null;
+
+  /**
+   * Source guidance overriding the agent default.
+   */
+  sources?: AgentRunParams.Sources | null;
+
+  /**
+   * Only settable when this run creates a new agent (via agent_name, or when no
+   * agent is resolved), in which case it becomes the new agent's stored use_case.
+   * For a run against an existing agent, this must match the agent's own use_case —
+   * passing the same value is accepted as a no-op, a different value is rejected.
+   */
+  use_case?: 'research' | 'enrichment' | 'dataset_building' | null;
+}
+
+export namespace AgentRunParams {
+  /**
+   * 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;
+    }
+  }
+}
+
 Agents.Templates = Templates;
 Agents.Runs = Runs;
 
@@ -1012,9 +1221,11 @@ export declare namespace Agents {
     type AgentUpdateResponse as AgentUpdateResponse,
     type AgentListResponse as AgentListResponse,
     type AgentGetResponse as AgentGetResponse,
+    type AgentRunResponse as AgentRunResponse,
     type AgentCreateParams as AgentCreateParams,
     type AgentUpdateParams as AgentUpdateParams,
     type AgentListParams as AgentListParams,
+    type AgentRunParams as AgentRunParams,
   };
 
   export {
@@ -1030,6 +1241,7 @@ export declare namespace Agents {
     type RunListResponse as RunListResponse,
     type RunGetResponse as RunGetResponse,
     type RunResultResponse as RunResultResponse,
+    type RunStreamEventsResponse as RunStreamEventsResponse,
     type RunCreateParams as RunCreateParams,
     type RunListParams as RunListParams,
     type RunGetParams as RunGetParams,

package/src/resources/agents/index.ts

@@ -6,9 +6,11 @@ export {
   type AgentUpdateResponse,
   type AgentListResponse,
   type AgentGetResponse,
+  type AgentRunResponse,
   type AgentCreateParams,
   type AgentUpdateParams,
   type AgentListParams,
+  type AgentRunParams,
 } from './agents';
 export {
   Runs,
@@ -16,6 +18,7 @@ export {
   type RunListResponse,
   type RunGetResponse,
   type RunResultResponse,
+  type RunStreamEventsResponse,
   type RunCreateParams,
   type RunListParams,
   type RunGetParams,

package/src/resources/agents/runs.ts

@@ -2,6 +2,7 @@
 
 import { APIResource } from '../../core/resource';
 import { APIPromise } from '../../core/api-promise';
+import { Stream } from '../../core/streaming';
 import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
@@ -60,12 +61,17 @@ export class Runs extends APIResource {
    * (`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> {
+  streamEvents(
+    runID: string,
+    params: RunStreamEventsParams,
+    options?: RequestOptions,
+  ): APIPromise<Stream<RunStreamEventsResponse>> {
     const { agent_id } = params;
     return this._client.get(path`/v2/agents/${agent_id}/runs/${runID}/events`, {
       ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+      headers: buildHeaders([{ Accept: 'text/event-stream' }, options?.headers]),
+      stream: true,
+    }) as APIPromise<Stream<RunStreamEventsResponse>>;
   }
 }
 
@@ -870,12 +876,20 @@ export namespace RunResultResponse {
   }
 }
 
+export type RunStreamEventsResponse = unknown;
+
 export interface RunCreateParams {
   /**
    * User prompt or task instructions for the run.
    */
   input: string;
 
+  /**
+   * Stable agent name. On this no-agent-id route, an unseen name creates a new
+   * agent; an existing name reuses it. Ignored on the /{agent_id}/runs route.
+   */
+  agent_name?: string | null;
+
   /**
    * Canonical effort tier names for the research graph.
    */
@@ -892,6 +906,11 @@ export interface RunCreateParams {
    */
   input_data?: Array<{ [key: string]: unknown }> | { [key: string]: unknown } | null;
 
+  /**
+   * Origin of public API runs. Public requests are always API-originated.
+   */
+  origin?: 'api';
+
   /**
    * JSON schema overriding the agent's default structured output for this run.
    */
@@ -902,10 +921,24 @@ export interface RunCreateParams {
    */
   previous_interaction_id?: string | null;
 
+  /**
+   * Skill override for this run. One-time only, except when this run creates a new
+   * agent via agent_name, in which case it becomes the new agent's stored skill.
+   */
+  skill?: string | null;
+
   /**
    * Source guidance overriding the agent default.
    */
   sources?: RunCreateParams.Sources | null;
+
+  /**
+   * Only settable when this run creates a new agent (via agent_name, or when no
+   * agent is resolved), in which case it becomes the new agent's stored use_case.
+   * For a run against an existing agent, this must match the agent's own use_case —
+   * passing the same value is accepted as a no-op, a different value is rejected.
+   */
+  use_case?: 'research' | 'enrichment' | 'dataset_building' | null;
 }
 
 export namespace RunCreateParams {
@@ -995,6 +1028,7 @@ export declare namespace Runs {
     type RunListResponse as RunListResponse,
     type RunGetResponse as RunGetResponse,
     type RunResultResponse as RunResultResponse,
+    type RunStreamEventsResponse as RunStreamEventsResponse,
     type RunCreateParams as RunCreateParams,
     type RunListParams as RunListParams,
     type RunGetParams as RunGetParams,

package/src/resources/agents/templates.ts

@@ -69,11 +69,6 @@ export namespace TemplateListResponse {
      */
     display_name: string;
 
-    /**
-     * Domain expertise or operating context for the template.
-     */
-    domain_expertise: string;
-
     /**
      * Default effort level for runs created from this template.
      */
@@ -94,6 +89,11 @@ export namespace TemplateListResponse {
      */
     output_schema: { [key: string]: unknown } | null;
 
+    /**
+     * Skill or operating context for the template.
+     */
+    skill: string;
+
     /**
      * Ordered source groups for the template.
      */
@@ -200,11 +200,6 @@ export interface TemplateGetResponse {
    */
   display_name: string;
 
-  /**
-   * Domain expertise or operating context for the template.
-   */
-  domain_expertise: string;
-
   /**
    * Default effort level for runs created from this template.
    */
@@ -225,6 +220,11 @@ export interface TemplateGetResponse {
    */
   output_schema: { [key: string]: unknown } | null;
 
+  /**
+   * Skill or operating context for the template.
+   */
+  skill: string;
+
   /**
    * Ordered source groups for the template.
    */

package/src/resources/index.ts

@@ -7,9 +7,11 @@ export {
   type AgentUpdateResponse,
   type AgentListResponse,
   type AgentGetResponse,
+  type AgentRunResponse,
   type AgentCreateParams,
   type AgentUpdateParams,
   type AgentListParams,
+  type AgentRunParams,
 } from './agents/agents';
 export { Batches, type BatchGetResponse, type BatchProgressResponse } from './batches';
 export {

package/src/streaming.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/streaming instead */
+export * from './core/streaming';

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '1.0.0'; // x-release-please-version
+export const VERSION = '1.2.0'; // x-release-please-version

package/streaming.d.mts

@@ -0,0 +1,3 @@
+/** @deprecated Import from ./core/streaming instead */
+export * from "./core/streaming.mjs";
+//# sourceMappingURL=streaming.d.mts.map

package/streaming.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.mts","sourceRoot":"","sources":["src/streaming.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,qCAAiC"}

package/streaming.d.ts

@@ -0,0 +1,3 @@
+/** @deprecated Import from ./core/streaming instead */
+export * from "./core/streaming.js";
+//# sourceMappingURL=streaming.d.ts.map

package/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["src/streaming.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,oCAAiC"}

package/streaming.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("./internal/tslib.js");
+/** @deprecated Import from ./core/streaming instead */
+tslib_1.__exportStar(require("./core/streaming.js"), exports);
+//# sourceMappingURL=streaming.js.map

package/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["src/streaming.ts"],"names":[],"mappings":";;;AAAA,uDAAuD;AACvD,8DAAiC"}

package/streaming.mjs

@@ -0,0 +1,3 @@
+/** @deprecated Import from ./core/streaming instead */
+export * from "./core/streaming.mjs";
+//# sourceMappingURL=streaming.mjs.map

package/streaming.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.mjs","sourceRoot":"","sources":["src/streaming.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,qCAAiC"}

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.0.0";
+export declare const VERSION = "1.2.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.0.0";
+export declare const VERSION = "1.2.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '1.0.0'; // x-release-please-version
+exports.VERSION = '1.2.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '1.0.0'; // x-release-please-version
+export const VERSION = '1.2.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map