@roarkanalytics/sdk 4.2.0 → 4.4.0

package/resources/simulation-tool-fixture.d.ts

@@ -0,0 +1,217 @@
+import { APIResource } from "../core/resource.js";
+import { APIPromise } from "../core/api-promise.js";
+import { RequestOptions } from "../internal/request-options.js";
+export declare class SimulationToolFixture extends APIResource {
+    /**
+     * Create-or-replace by scope: one fixture per tool project-wide, plus one per
+     * (tool, flow variant). Setting the same scope twice replaces the response, so CI
+     * can apply fixtures idempotently. During Roark test calls the tool guard answers
+     * with the fixture verbatim instead of generating a response; real callers are
+     * never affected.
+     *
+     * @example
+     * ```ts
+     * const simulationToolFixture =
+     *   await client.simulationToolFixture.create({
+     *     toolName: 'lookup_availability',
+     *   });
+     * ```
+     */
+    create(body: SimulationToolFixtureCreateParams, options?: RequestOptions): APIPromise<SimulationToolFixtureCreateResponse>;
+    /**
+     * Change the response, description, or enabled state of an existing fixture.
+     *
+     * @example
+     * ```ts
+     * const simulationToolFixture =
+     *   await client.simulationToolFixture.update(
+     *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+     *   );
+     * ```
+     */
+    update(fixtureID: string, body?: SimulationToolFixtureUpdateParams | null | undefined, options?: RequestOptions): APIPromise<SimulationToolFixtureUpdateResponse>;
+    /**
+     * All deterministic tool responses configured for this project, optionally
+     * filtered by tool.
+     *
+     * @example
+     * ```ts
+     * const simulationToolFixtures =
+     *   await client.simulationToolFixture.list();
+     * ```
+     */
+    list(query?: SimulationToolFixtureListParams | null | undefined, options?: RequestOptions): APIPromise<SimulationToolFixtureListResponse>;
+    /**
+     * The tool goes back to scenario-aware generated responses in test calls.
+     *
+     * @example
+     * ```ts
+     * const simulationToolFixture =
+     *   await client.simulationToolFixture.delete(
+     *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+     *   );
+     * ```
+     */
+    delete(fixtureID: string, options?: RequestOptions): APIPromise<SimulationToolFixtureDeleteResponse>;
+}
+export interface SimulationToolFixtureCreateResponse {
+    /**
+     * A deterministic tool response for Roark test calls: where the scenario-aware
+     * model makes mocked tools plausible, a fixture makes one exact, so a simulation
+     * can force the branch under test. Never applies to real callers.
+     */
+    data: SimulationToolFixtureCreateResponse.Data;
+}
+export declare namespace SimulationToolFixtureCreateResponse {
+    /**
+     * A deterministic tool response for Roark test calls: where the scenario-aware
+     * model makes mocked tools plausible, a fixture makes one exact, so a simulation
+     * can force the branch under test. Never applies to real callers.
+     */
+    interface Data {
+        id: string;
+        /**
+         * ISO 8601.
+         */
+        createdAt: string;
+        /**
+         * The flow variant this fixture is pinned to. Null = project-wide.
+         */
+        customerFlowVariantId: string | null;
+        /**
+         * Why this fixture exists.
+         */
+        description: string | null;
+        enabled: boolean;
+        toolName: string;
+        /**
+         * ISO 8601.
+         */
+        updatedAt: string;
+        /**
+         * The exact JSON the tool returns during Roark test calls.
+         */
+        response?: unknown;
+    }
+}
+export interface SimulationToolFixtureUpdateResponse {
+    /**
+     * A deterministic tool response for Roark test calls: where the scenario-aware
+     * model makes mocked tools plausible, a fixture makes one exact, so a simulation
+     * can force the branch under test. Never applies to real callers.
+     */
+    data: SimulationToolFixtureUpdateResponse.Data;
+}
+export declare namespace SimulationToolFixtureUpdateResponse {
+    /**
+     * A deterministic tool response for Roark test calls: where the scenario-aware
+     * model makes mocked tools plausible, a fixture makes one exact, so a simulation
+     * can force the branch under test. Never applies to real callers.
+     */
+    interface Data {
+        id: string;
+        /**
+         * ISO 8601.
+         */
+        createdAt: string;
+        /**
+         * The flow variant this fixture is pinned to. Null = project-wide.
+         */
+        customerFlowVariantId: string | null;
+        /**
+         * Why this fixture exists.
+         */
+        description: string | null;
+        enabled: boolean;
+        toolName: string;
+        /**
+         * ISO 8601.
+         */
+        updatedAt: string;
+        /**
+         * The exact JSON the tool returns during Roark test calls.
+         */
+        response?: unknown;
+    }
+}
+export interface SimulationToolFixtureListResponse {
+    data: Array<SimulationToolFixtureListResponse.Data>;
+}
+export declare namespace SimulationToolFixtureListResponse {
+    /**
+     * A deterministic tool response for Roark test calls: where the scenario-aware
+     * model makes mocked tools plausible, a fixture makes one exact, so a simulation
+     * can force the branch under test. Never applies to real callers.
+     */
+    interface Data {
+        id: string;
+        /**
+         * ISO 8601.
+         */
+        createdAt: string;
+        /**
+         * The flow variant this fixture is pinned to. Null = project-wide.
+         */
+        customerFlowVariantId: string | null;
+        /**
+         * Why this fixture exists.
+         */
+        description: string | null;
+        enabled: boolean;
+        toolName: string;
+        /**
+         * ISO 8601.
+         */
+        updatedAt: string;
+        /**
+         * The exact JSON the tool returns during Roark test calls.
+         */
+        response?: unknown;
+    }
+}
+export interface SimulationToolFixtureDeleteResponse {
+    data: SimulationToolFixtureDeleteResponse.Data;
+}
+export declare namespace SimulationToolFixtureDeleteResponse {
+    interface Data {
+        deleted: boolean;
+    }
+}
+export interface SimulationToolFixtureCreateParams {
+    /**
+     * The tool this fixture answers for.
+     */
+    toolName: string;
+    /**
+     * Pin the fixture to one flow variant (scenario). Omit for a project-wide fixture.
+     * A variant-pinned fixture beats the project-wide one.
+     */
+    customerFlowVariantId?: string;
+    /**
+     * Why this fixture exists.
+     */
+    description?: string;
+    /**
+     * Defaults to true.
+     */
+    enabled?: boolean;
+    /**
+     * The exact JSON to return.
+     */
+    response?: unknown;
+}
+export interface SimulationToolFixtureUpdateParams {
+    description?: string | null;
+    enabled?: boolean;
+    response?: unknown;
+}
+export interface SimulationToolFixtureListParams {
+    /**
+     * Only fixtures for this tool.
+     */
+    toolName?: string;
+}
+export declare namespace SimulationToolFixture {
+    export { type SimulationToolFixtureCreateResponse as SimulationToolFixtureCreateResponse, type SimulationToolFixtureUpdateResponse as SimulationToolFixtureUpdateResponse, type SimulationToolFixtureListResponse as SimulationToolFixtureListResponse, type SimulationToolFixtureDeleteResponse as SimulationToolFixtureDeleteResponse, type SimulationToolFixtureCreateParams as SimulationToolFixtureCreateParams, type SimulationToolFixtureUpdateParams as SimulationToolFixtureUpdateParams, type SimulationToolFixtureListParams as SimulationToolFixtureListParams, };
+}
+//# sourceMappingURL=simulation-tool-fixture.d.ts.map

package/resources/simulation-tool-fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulation-tool-fixture.d.ts","sourceRoot":"","sources":["../src/resources/simulation-tool-fixture.ts"],"names":[],"mappings":"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"}

package/resources/simulation-tool-fixture.js

@@ -0,0 +1,69 @@
+"use strict";
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimulationToolFixture = void 0;
+const resource_1 = require("../core/resource.js");
+const path_1 = require("../internal/utils/path.js");
+class SimulationToolFixture extends resource_1.APIResource {
+    /**
+     * Create-or-replace by scope: one fixture per tool project-wide, plus one per
+     * (tool, flow variant). Setting the same scope twice replaces the response, so CI
+     * can apply fixtures idempotently. During Roark test calls the tool guard answers
+     * with the fixture verbatim instead of generating a response; real callers are
+     * never affected.
+     *
+     * @example
+     * ```ts
+     * const simulationToolFixture =
+     *   await client.simulationToolFixture.create({
+     *     toolName: 'lookup_availability',
+     *   });
+     * ```
+     */
+    create(body, options) {
+        return this._client.post('/v1/simulation/tool-fixture', { body, ...options });
+    }
+    /**
+     * Change the response, description, or enabled state of an existing fixture.
+     *
+     * @example
+     * ```ts
+     * const simulationToolFixture =
+     *   await client.simulationToolFixture.update(
+     *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+     *   );
+     * ```
+     */
+    update(fixtureID, body = {}, options) {
+        return this._client.put((0, path_1.path) `/v1/simulation/tool-fixture/${fixtureID}`, { body, ...options });
+    }
+    /**
+     * All deterministic tool responses configured for this project, optionally
+     * filtered by tool.
+     *
+     * @example
+     * ```ts
+     * const simulationToolFixtures =
+     *   await client.simulationToolFixture.list();
+     * ```
+     */
+    list(query = {}, options) {
+        return this._client.get('/v1/simulation/tool-fixture', { query, ...options });
+    }
+    /**
+     * The tool goes back to scenario-aware generated responses in test calls.
+     *
+     * @example
+     * ```ts
+     * const simulationToolFixture =
+     *   await client.simulationToolFixture.delete(
+     *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+     *   );
+     * ```
+     */
+    delete(fixtureID, options) {
+        return this._client.delete((0, path_1.path) `/v1/simulation/tool-fixture/${fixtureID}`, options);
+    }
+}
+exports.SimulationToolFixture = SimulationToolFixture;
+//# sourceMappingURL=simulation-tool-fixture.js.map

package/resources/simulation-tool-fixture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulation-tool-fixture.js","sourceRoot":"","sources":["../src/resources/simulation-tool-fixture.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAG/C,oDAA8C;AAE9C,MAAa,qBAAsB,SAAQ,sBAAW;IACpD;;;;;;;;;;;;;;OAcG;IACH,MAAM,CACJ,IAAuC,EACvC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,6BAA6B,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CACJ,SAAiB,EACjB,OAA6D,EAAE,EAC/D,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,+BAA+B,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChG,CAAC;IAED;;;;;;;;;OASG;IACH,IAAI,CACF,QAA4D,EAAE,EAC9D,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,6BAA6B,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,SAAiB,EAAE,OAAwB;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAA,WAAI,EAAA,+BAA+B,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;IACtF,CAAC;CACF;AAzED,sDAyEC"}

package/resources/simulation-tool-fixture.mjs

@@ -0,0 +1,65 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+import { APIResource } from "../core/resource.mjs";
+import { path } from "../internal/utils/path.mjs";
+export class SimulationToolFixture extends APIResource {
+    /**
+     * Create-or-replace by scope: one fixture per tool project-wide, plus one per
+     * (tool, flow variant). Setting the same scope twice replaces the response, so CI
+     * can apply fixtures idempotently. During Roark test calls the tool guard answers
+     * with the fixture verbatim instead of generating a response; real callers are
+     * never affected.
+     *
+     * @example
+     * ```ts
+     * const simulationToolFixture =
+     *   await client.simulationToolFixture.create({
+     *     toolName: 'lookup_availability',
+     *   });
+     * ```
+     */
+    create(body, options) {
+        return this._client.post('/v1/simulation/tool-fixture', { body, ...options });
+    }
+    /**
+     * Change the response, description, or enabled state of an existing fixture.
+     *
+     * @example
+     * ```ts
+     * const simulationToolFixture =
+     *   await client.simulationToolFixture.update(
+     *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+     *   );
+     * ```
+     */
+    update(fixtureID, body = {}, options) {
+        return this._client.put(path `/v1/simulation/tool-fixture/${fixtureID}`, { body, ...options });
+    }
+    /**
+     * All deterministic tool responses configured for this project, optionally
+     * filtered by tool.
+     *
+     * @example
+     * ```ts
+     * const simulationToolFixtures =
+     *   await client.simulationToolFixture.list();
+     * ```
+     */
+    list(query = {}, options) {
+        return this._client.get('/v1/simulation/tool-fixture', { query, ...options });
+    }
+    /**
+     * The tool goes back to scenario-aware generated responses in test calls.
+     *
+     * @example
+     * ```ts
+     * const simulationToolFixture =
+     *   await client.simulationToolFixture.delete(
+     *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+     *   );
+     * ```
+     */
+    delete(fixtureID, options) {
+        return this._client.delete(path `/v1/simulation/tool-fixture/${fixtureID}`, options);
+    }
+}
+//# sourceMappingURL=simulation-tool-fixture.mjs.map

package/resources/simulation-tool-fixture.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulation-tool-fixture.mjs","sourceRoot":"","sources":["../src/resources/simulation-tool-fixture.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,6BAAyB;AAG/C,OAAO,EAAE,IAAI,EAAE,mCAA+B;AAE9C,MAAM,OAAO,qBAAsB,SAAQ,WAAW;IACpD;;;;;;;;;;;;;;OAcG;IACH,MAAM,CACJ,IAAuC,EACvC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,6BAA6B,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CACJ,SAAiB,EACjB,OAA6D,EAAE,EAC/D,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,+BAA+B,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChG,CAAC;IAED;;;;;;;;;OASG;IACH,IAAI,CACF,QAA4D,EAAE,EAC9D,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,6BAA6B,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,SAAiB,EAAE,OAAwB;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAA,+BAA+B,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;IACtF,CAAC;CACF"}

package/resources/simulation.d.mts

@@ -2,6 +2,33 @@ import { APIResource } from "../core/resource.mjs";
 import { APIPromise } from "../core/api-promise.mjs";
 import { RequestOptions } from "../internal/request-options.mjs";
 export declare 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>;
     /**
      * Starts a simulation and returns the run.
      *
@@ -32,6 +59,39 @@ export declare class Simulation extends APIResource {
      */
     run(body: SimulationRunParams, options?: RequestOptions): APIPromise<SimulationRunResponse>;
 }
+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 declare 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.
+     */
+    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;
+        /**
+         * GENERATED = the scenario-aware model answered; FIXTURE = a pinned deterministic
+         * response you configured answered.
+         */
+        source: 'GENERATED' | 'FIXTURE';
+        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.
@@ -72,6 +132,33 @@ export declare namespace SimulationRunResponse {
         status: 'PENDING' | 'QUEUED' | 'CREATING_SNAPSHOTS' | 'CREATING_SIMULATIONS' | 'PREPARING_CAPACITY' | 'RUNNING_SIMULATIONS' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'CANCELLING' | 'ENDING_SIMULATIONS';
     }
 }
+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 | SimulationRunParams.RunSimulationFromTemplate;
 export declare namespace SimulationRunParams {
     interface RunSimulationFromConfig {
@@ -734,6 +821,6 @@ export declare namespace SimulationRunParams {
     }
 }
 export declare namespace Simulation {
-    export { type SimulationRunResponse as SimulationRunResponse, type SimulationRunParams as SimulationRunParams, };
+    export { type SimulationMockToolResponse as SimulationMockToolResponse, type SimulationRunResponse as SimulationRunResponse, type SimulationMockToolParams as SimulationMockToolParams, type SimulationRunParams as SimulationRunParams, };
 }
 //# sourceMappingURL=simulation.d.mts.map

package/resources/simulation.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"simulation.d.mts","sourceRoot":"","sources":["../src/resources/simulation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"simulation.d.mts","sourceRoot":"","sources":["../src/resources/simulation.ts"],"names":[],"mappings":"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"}

package/resources/simulation.d.ts

@@ -2,6 +2,33 @@ import { APIResource } from "../core/resource.js";
 import { APIPromise } from "../core/api-promise.js";
 import { RequestOptions } from "../internal/request-options.js";
 export declare 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>;
     /**
      * Starts a simulation and returns the run.
      *
@@ -32,6 +59,39 @@ export declare class Simulation extends APIResource {
      */
     run(body: SimulationRunParams, options?: RequestOptions): APIPromise<SimulationRunResponse>;
 }
+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 declare 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.
+     */
+    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;
+        /**
+         * GENERATED = the scenario-aware model answered; FIXTURE = a pinned deterministic
+         * response you configured answered.
+         */
+        source: 'GENERATED' | 'FIXTURE';
+        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.
@@ -72,6 +132,33 @@ export declare namespace SimulationRunResponse {
         status: 'PENDING' | 'QUEUED' | 'CREATING_SNAPSHOTS' | 'CREATING_SIMULATIONS' | 'PREPARING_CAPACITY' | 'RUNNING_SIMULATIONS' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'CANCELLING' | 'ENDING_SIMULATIONS';
     }
 }
+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 | SimulationRunParams.RunSimulationFromTemplate;
 export declare namespace SimulationRunParams {
     interface RunSimulationFromConfig {
@@ -734,6 +821,6 @@ export declare namespace SimulationRunParams {
     }
 }
 export declare namespace Simulation {
-    export { type SimulationRunResponse as SimulationRunResponse, type SimulationRunParams as SimulationRunParams, };
+    export { type SimulationMockToolResponse as SimulationMockToolResponse, type SimulationRunResponse as SimulationRunResponse, type SimulationMockToolParams as SimulationMockToolParams, type SimulationRunParams as SimulationRunParams, };
 }
 //# sourceMappingURL=simulation.d.ts.map