@roarkanalytics/sdk 4.1.0 → 4.3.0

package/resources/simulation.mjs

@@ -1,6 +1,35 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 import { APIResource } from "../core/resource.mjs";
 export class Simulation extends APIResource {
+    /**
+     * The server half of the tool guard for code-first agents. When a guarded tool
+     * fires during a Roark test call, send the invocation here instead of executing
+     * it: Roark answers with a simulated backend response that is valid JSON, shaped
+     * by the tool contract you pass, consistent with the test scenario, and consistent
+     * with earlier mocked responses in the same call. Real callers are never affected:
+     * the guard only diverts when the agent-config resolve response identified the
+     * session as a Roark simulation, and this endpoint independently re-validates the
+     * simulation before answering.
+     *
+     * Failure contract for your wrapper: `404` means the simulation id is unknown to
+     * this project (treat the session as real). `409` means the simulation has already
+     * ended (stale session state: do NOT execute the real tool; return your static
+     * fallback). `5xx` means generation failed (return your static fallback).
+     *
+     * Identical retries (same tool, same arguments) within a few minutes return the
+     * stored response, so double-fired handlers stay consistent.
+     *
+     * @example
+     * ```ts
+     * const response = await client.simulation.mockTool({
+     *   simulationJobId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+     *   toolName: 'book_appointment',
+     * });
+     * ```
+     */
+    mockTool(body, options) {
+        return this._client.post('/v1/simulation/tool-mock', { body, ...options });
+    }
     /**
      * Starts a simulation and returns the run.
      *

package/resources/simulation.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"simulation.mjs","sourceRoot":"","sources":["../src/resources/simulation.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,6BAAyB;AAI/C,MAAM,OAAO,UAAW,SAAQ,WAAW;IACzC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,GAAG,CAAC,IAAyB,EAAE,OAAwB;QACrD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACvE,CAAC;CACF"}
+{"version":3,"file":"simulation.mjs","sourceRoot":"","sources":["../src/resources/simulation.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,6BAAyB;AAI/C,MAAM,OAAO,UAAW,SAAQ,WAAW;IACzC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,QAAQ,CAAC,IAA8B,EAAE,OAAwB;QAC/D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,0BAA0B,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,GAAG,CAAC,IAAyB,EAAE,OAAwB;QACrD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACvE,CAAC;CACF"}

package/src/client.ts

@@ -19,6 +19,8 @@ import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
 import {
   Agent,
+  AgentBuildParams,
+  AgentBuildResponse,
   AgentCreateParams,
   AgentCreateResponse,
   AgentGetByIDResponse,
@@ -190,7 +192,13 @@ import {
   MetricVariantUpdateParams,
   MetricVariantUpdateResponse,
 } from './resources/metric-variant';
-import { Simulation, SimulationRunParams, SimulationRunResponse } from './resources/simulation';
+import {
+  Simulation,
+  SimulationMockToolParams,
+  SimulationMockToolResponse,
+  SimulationRunParams,
+  SimulationRunResponse,
+} from './resources/simulation';
 import {
   SimulationEnvironment,
   SimulationEnvironmentCreateParams,
@@ -1083,7 +1091,9 @@ export declare namespace Roark {
 
   export {
     Simulation as Simulation,
+    type SimulationMockToolResponse as SimulationMockToolResponse,
     type SimulationRunResponse as SimulationRunResponse,
+    type SimulationMockToolParams as SimulationMockToolParams,
     type SimulationRunParams as SimulationRunParams,
   };
 
@@ -1209,10 +1219,12 @@ export declare namespace Roark {
     type AgentCreateResponse as AgentCreateResponse,
     type AgentUpdateResponse as AgentUpdateResponse,
     type AgentListResponse as AgentListResponse,
+    type AgentBuildResponse as AgentBuildResponse,
     type AgentGetByIDResponse as AgentGetByIDResponse,
     type AgentCreateParams as AgentCreateParams,
     type AgentUpdateParams as AgentUpdateParams,
     type AgentListParams as AgentListParams,
+    type AgentBuildParams as AgentBuildParams,
   };
 
   export {

package/src/resources/agent.ts

@@ -49,6 +49,23 @@ export class Agent extends APIResource {
     return this._client.get('/v1/agent', { query, ...options });
   }
 
+  /**
+   * Creates a new Roark-hosted agent from a one-line job description. Roark authors
+   * the system prompt and hosts the config, so the agent is live and self-improvable
+   * from creation.
+   *
+   * @example
+   * ```ts
+   * const response = await client.agent.build({
+   *   jobDescription: 'x',
+   *   name: 'x',
+   * });
+   * ```
+   */
+  build(body: AgentBuildParams, options?: RequestOptions): APIPromise<AgentBuildResponse> {
+    return this._client.post('/v1/agent/build', { body, ...options });
+  }
+
   /**
    * Returns a specific agent by its ID.
    *
@@ -195,6 +212,44 @@ export namespace AgentListResponse {
   }
 }
 
+export interface AgentBuildResponse {
+  data: AgentBuildResponse.Data;
+}
+
+export namespace AgentBuildResponse {
+  export interface Data {
+    /**
+     * Unique identifier of the agent
+     */
+    id: string;
+
+    /**
+     * Creation timestamp in ISO 8601 format
+     */
+    createdAt: string;
+
+    /**
+     * Custom identifier for the agent
+     */
+    customId: string | null;
+
+    /**
+     * Description of the agent
+     */
+    description: string | null;
+
+    /**
+     * Name of the agent
+     */
+    name: string;
+
+    /**
+     * Last update timestamp in ISO 8601 format
+     */
+    updatedAt: string;
+  }
+}
+
 export interface AgentGetByIDResponse {
   data: AgentGetByIDResponse.Data;
 }
@@ -270,14 +325,34 @@ export interface AgentListParams {
   searchText?: string;
 }
 
+export interface AgentBuildParams {
+  /**
+   * One-line description of what the agent should do. Roark authors the system
+   * prompt from this.
+   */
+  jobDescription: string;
+
+  /**
+   * Name of the agent
+   */
+  name: string;
+
+  /**
+   * Optional voice label for the hosted agent
+   */
+  voice?: string | null;
+}
+
 export declare namespace Agent {
   export {
     type AgentCreateResponse as AgentCreateResponse,
     type AgentUpdateResponse as AgentUpdateResponse,
     type AgentListResponse as AgentListResponse,
+    type AgentBuildResponse as AgentBuildResponse,
     type AgentGetByIDResponse as AgentGetByIDResponse,
     type AgentCreateParams as AgentCreateParams,
     type AgentUpdateParams as AgentUpdateParams,
     type AgentListParams as AgentListParams,
+    type AgentBuildParams as AgentBuildParams,
   };
 }

package/src/resources/index.ts

@@ -5,10 +5,12 @@ export {
   type AgentCreateResponse,
   type AgentUpdateResponse,
   type AgentListResponse,
+  type AgentBuildResponse,
   type AgentGetByIDResponse,
   type AgentCreateParams,
   type AgentUpdateParams,
   type AgentListParams,
+  type AgentBuildParams,
 } from './agent';
 export {
   AgentConfig,
@@ -173,7 +175,13 @@ export {
   type MetricVariantDeleteParams,
   type MetricVariantGetByIDParams,
 } from './metric-variant';
-export { Simulation, type SimulationRunResponse, type SimulationRunParams } from './simulation';
+export {
+  Simulation,
+  type SimulationMockToolResponse,
+  type SimulationRunResponse,
+  type SimulationMockToolParams,
+  type SimulationRunParams,
+} from './simulation';
 export {
   SimulationEnvironment,
   type SimulationEnvironmentCreateResponse,

package/src/resources/simulation.ts

@@ -5,6 +5,36 @@ import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
 export class Simulation extends APIResource {
+  /**
+   * The server half of the tool guard for code-first agents. When a guarded tool
+   * fires during a Roark test call, send the invocation here instead of executing
+   * it: Roark answers with a simulated backend response that is valid JSON, shaped
+   * by the tool contract you pass, consistent with the test scenario, and consistent
+   * with earlier mocked responses in the same call. Real callers are never affected:
+   * the guard only diverts when the agent-config resolve response identified the
+   * session as a Roark simulation, and this endpoint independently re-validates the
+   * simulation before answering.
+   *
+   * Failure contract for your wrapper: `404` means the simulation id is unknown to
+   * this project (treat the session as real). `409` means the simulation has already
+   * ended (stale session state: do NOT execute the real tool; return your static
+   * fallback). `5xx` means generation failed (return your static fallback).
+   *
+   * Identical retries (same tool, same arguments) within a few minutes return the
+   * stored response, so double-fired handlers stay consistent.
+   *
+   * @example
+   * ```ts
+   * const response = await client.simulation.mockTool({
+   *   simulationJobId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   toolName: 'book_appointment',
+   * });
+   * ```
+   */
+  mockTool(body: SimulationMockToolParams, options?: RequestOptions): APIPromise<SimulationMockToolResponse> {
+    return this._client.post('/v1/simulation/tool-mock', { body, ...options });
+  }
+
   /**
    * Starts a simulation and returns the run.
    *
@@ -38,6 +68,39 @@ export class Simulation extends APIResource {
   }
 }
 
+export interface SimulationMockToolResponse {
+  /**
+   * A simulated backend response for a guarded tool during a Roark test call. The
+   * real tool was not, and must not be, executed.
+   */
+  data: SimulationMockToolResponse.Data;
+}
+
+export namespace SimulationMockToolResponse {
+  /**
+   * A simulated backend response for a guarded tool during a Roark test call. The
+   * real tool was not, and must not be, executed.
+   */
+  export interface Data {
+    /**
+     * True when this exact invocation (same tool, same arguments) was answered moments
+     * ago and the stored response was returned, e.g. on a retry.
+     */
+    reused: boolean;
+
+    simulationJobId: string;
+
+    toolName: string;
+
+    /**
+     * The simulated tool response: valid JSON, shaped by the tool contract, consistent
+     * with the test scenario and with earlier mocked responses in the same call.
+     * Return this from your tool instead of executing it.
+     */
+    result?: unknown;
+  }
+}
+
 export interface SimulationRunResponse {
   /**
    * A started simulation run.
@@ -97,6 +160,36 @@ export namespace SimulationRunResponse {
   }
 }
 
+export interface SimulationMockToolParams {
+  /**
+   * The simulation this session belongs to, from the agent-config resolve response
+   * (`simulationJobId`). Roark re-validates it against the live simulation before
+   * answering.
+   */
+  simulationJobId: string;
+
+  /**
+   * The tool the agent invoked.
+   */
+  toolName: string;
+
+  /**
+   * The arguments the agent called the tool with, verbatim.
+   */
+  arguments?: { [key: string]: unknown };
+
+  /**
+   * Your session or room identifier, echoed back in logs for correlation.
+   */
+  sessionId?: string;
+
+  /**
+   * The tool's contract: its description and, ideally, its parameter and return
+   * shape. The more contract you pass, the more faithful the simulated response.
+   */
+  toolDescription?: string;
+}
+
 export type SimulationRunParams =
   | SimulationRunParams.RunSimulationFromConfig
   | SimulationRunParams.RunSimulationFromPlanID
@@ -882,7 +975,9 @@ export declare namespace SimulationRunParams {
 
 export declare namespace Simulation {
   export {
+    type SimulationMockToolResponse as SimulationMockToolResponse,
     type SimulationRunResponse as SimulationRunResponse,
+    type SimulationMockToolParams as SimulationMockToolParams,
     type SimulationRunParams as SimulationRunParams,
   };
 }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '4.1.0'; // x-release-please-version
+export const VERSION = '4.3.0'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "4.1.0";
+export declare const VERSION = "4.3.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 = '4.1.0'; // x-release-please-version
+exports.VERSION = '4.3.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

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