@roarkanalytics/sdk 3.10.0 → 3.12.0

package/resources/simulation.d.mts

@@ -5,9 +5,16 @@ export declare class Simulation extends APIResource {
     /**
      * Starts a simulation and returns the run.
      *
-     * Send `plan` to describe a simulation and run it once. Add `saveAsPlan` to keep
-     * that configuration as a reusable run plan. Send `planId` instead to run a plan
-     * you already have.
+     * Send `template` to run one of the built-in templates: it supplies the metrics
+     * and checks, and for some templates the flows too, so the request only names the
+     * agent and the direction. Send `plan` to describe a simulation yourself and run
+     * it once. Send `planId` to run a plan you already have.
+     *
+     * `template` and `plan` both resolve to a run plan, returned as
+     * `simulationRunPlanId`. Add `saveAsPlan` to keep it, or read it back to see
+     * exactly what ran. A plan built from a template is a snapshot: retuning the
+     * template later never changes what that plan runs, which is what makes a saved
+     * one safe to pin in CI.
      *
      * @example
      * ```ts
@@ -65,7 +72,7 @@ export declare namespace SimulationRunResponse {
         status: 'PENDING' | 'QUEUED' | 'CREATING_SNAPSHOTS' | 'CREATING_SIMULATIONS' | 'PREPARING_CAPACITY' | 'RUNNING_SIMULATIONS' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'CANCELLING' | 'ENDING_SIMULATIONS';
     }
 }
-export type SimulationRunParams = SimulationRunParams.RunSimulationFromConfig | SimulationRunParams.RunSimulationFromPlanID;
+export type SimulationRunParams = SimulationRunParams.RunSimulationFromConfig | SimulationRunParams.RunSimulationFromPlanID | SimulationRunParams.RunSimulationFromTemplate;
 export declare namespace SimulationRunParams {
     interface RunSimulationFromConfig {
         /**
@@ -169,6 +176,21 @@ export declare namespace SimulationRunParams {
              * once with a different persona override or different variables.
              */
             flows?: Array<Plan.Flow>;
+            /**
+             * Let the run add metrics by itself off the attached flows, on top of the
+             * `metrics` named here.
+             *
+             * Two attach this way today: Agent Expectations wherever an attached flow has
+             * agent expectations written on it, and Keypad Entry wherever one has steps where
+             * the agent is expected to press keys. Both grade something authored on the flow
+             * that nothing else measures, which is why it is on by default.
+             *
+             * Set false when the `metrics` list is meant to be exhaustive: a plan testing only
+             * whether the caller can complete the flow may not want the agent graded on its
+             * expectations as well. False also pins the plan against any automatic metric
+             * Roark adds later.
+             */
+            includeAutomaticMetrics?: boolean;
             /**
              * Also collect each attached flow's own metrics, on top of the `metrics` named
              * here.
@@ -252,7 +274,7 @@ export declare namespace SimulationRunParams {
                 /**
                  * The customer flow to run.
                  */
-                id: string;
+                id?: string;
                 /**
                  * `"ALL"` runs every edge case the flow has when the run starts, so one added
                  * later is covered. An array runs only the ones you name, each able to carry its
@@ -267,6 +289,12 @@ export declare namespace SimulationRunParams {
                  * Runs everything this attachment resolves as that persona instead of its own.
                  */
                 personaOverrideId?: string | null;
+                /**
+                 * The Roark-curated flow to run, by its stable slug. Use instead of `id` for a run
+                 * you keep in version control: a curated flow’s id differs between deployments,
+                 * its slug does not. Your own flows have no slug and are named by `id`.
+                 */
+                slug?: string;
                 /**
                  * Values for everything it resolves.
                  */
@@ -279,11 +307,18 @@ export declare namespace SimulationRunParams {
                     /**
                      * The edge case to run.
                      */
-                    id: string;
+                    id?: string;
                     /**
                      * Run this one as that persona instead of its own.
                      */
                     personaOverrideId?: string | null;
+                    /**
+                     * The edge case to run, by its stable slug, matched within this flow. Use instead
+                     * of `id` for a run you keep in version control: a curated edge case’s id differs
+                     * between deployments and changes outright if it is renamed. Your own edge cases
+                     * have no slug and are named by `id`.
+                     */
+                    slug?: string;
                     /**
                      * Values for this one only.
                      */
@@ -411,6 +446,186 @@ export declare namespace SimulationRunParams {
             };
         }
     }
+    interface RunSimulationFromTemplate {
+        /**
+         * The agent endpoints to call. No template can know these.
+         */
+        agentEndpoints: Array<RunSimulationFromTemplate.AgentEndpoint>;
+        /**
+         * Direction of the simulation (INBOUND or OUTBOUND)
+         */
+        direction: 'INBOUND' | 'OUTBOUND';
+        /**
+         * The template to run, as listed by GET /v1/simulation/template.
+         */
+        template: string;
+        /**
+         * Phrases that trigger end of call. Empty array disables the feature.
+         */
+        endCallPhrases?: Array<string>;
+        /**
+         * Semantic conditions that trigger end of call. The LLM evaluates the conversation
+         * against these conditions. Defaults to the template's `defaultEndCallReasons`, as
+         * returned by GET /v1/simulation/template. Pass an empty array to run with none.
+         */
+        endCallReasons?: Array<string>;
+        /**
+         * Merge the customer's own recording of the real call into each simulation, so
+         * metrics can be scored against the live leg as well as the simulated one. This is
+         * the API equivalent of the dashboard's live-enrichment toggle.
+         *
+         * With this on, the run provisions a phone number and holds each call open for up
+         * to 15 minutes waiting for a matching call to be posted to POST /v1/call. A call
+         * matches on the provisioned number (`roarkPhoneNumber` on the job) with a start
+         * time inside the simulation window. If nothing arrives, the simulation still
+         * completes and any `LIVE`-sourced metric produces no value.
+         *
+         * Required by any metric whose `requiresLiveConversation` is true: without it that
+         * metric is silently skipped.
+         */
+        enrichWithLiveConversation?: boolean;
+        /**
+         * Execution mode (PARALLEL or SEQUENTIAL)
+         */
+        executionMode?: 'PARALLEL' | 'SEQUENTIAL_SAME_RUN_PLAN' | 'SEQUENTIAL_PROJECT';
+        /**
+         * The flows to run, in the same shape a run plan takes them.
+         *
+         * Required when the template lists no flows of its own: it presets what to
+         * measure, and this says what to measure it on. Optional when it does, where these
+         * REPLACE the ones it would have run, so you can narrow a suite to the cases you
+         * care about. Either way, GET /v1/simulation/template lists the flows and variant
+         * ids each template covers.
+         */
+        flows?: Array<RunSimulationFromTemplate.Flow>;
+        /**
+         * Number of iterations to run for each test case (1-10000)
+         */
+        iterationCount?: number;
+        /**
+         * Maximum number of concurrent simulation jobs
+         */
+        maxConcurrentJobs?: number;
+        /**
+         * Defaults to the template's `defaultMaxSimulationDurationSeconds`, as returned by
+         * GET /v1/simulation/template.
+         */
+        maxSimulationDurationSeconds?: number;
+        /**
+         * What to call this. Defaults to the template's name and the date, and required
+         * with `saveAsPlan`.
+         */
+        name?: string;
+        /**
+         * Keeps the resolved configuration as a run plan, listed by GET
+         * /v1/simulation/plan and re-runnable with `planId`. Requires `name`.
+         */
+        saveAsPlan?: boolean;
+        /**
+         * Timeout in seconds for silence detection
+         */
+        silenceTimeoutSeconds?: number;
+        /**
+         * Values for the {{variables}} the run resolves. An object applies them
+         * everywhere; an array targets a flow, its happy path, or one of its edge cases
+         * with `flowId`.
+         *
+         * The scenario-scoped form the other variants accept is not valid here: a template
+         * run is always flow-based, so there would be no scenario for it to reach.
+         */
+        variables?: {
+            [key: string]: string;
+        } | Array<RunSimulationFromTemplate.UnionMember1>;
+    }
+    namespace RunSimulationFromTemplate {
+        interface AgentEndpoint {
+            id: string;
+        }
+        /**
+         * One customer flow attached to a run plan, and which of its ways of running you
+         * cover.
+         *
+         * Attaching the same flow more than once with different overrides is how you fan
+         * it out across personas or values.
+         */
+        interface Flow {
+            /**
+             * The customer flow to run.
+             */
+            id?: string;
+            /**
+             * `"ALL"` runs every edge case the flow has when the run starts, so one added
+             * later is covered. An array runs only the ones you name, each able to carry its
+             * own persona override and values.
+             */
+            edgeCases?: 'ALL' | Array<Flow.UnionMember1>;
+            /**
+             * Run the flow's happy path. Resolved when the run starts, so it follows the flow.
+             */
+            happyPath?: boolean;
+            /**
+             * Runs everything this attachment resolves as that persona instead of its own.
+             */
+            personaOverrideId?: string | null;
+            /**
+             * The Roark-curated flow to run, by its stable slug. Use instead of `id` for a run
+             * you keep in version control: a curated flow’s id differs between deployments,
+             * its slug does not. Your own flows have no slug and are named by `id`.
+             */
+            slug?: string;
+            /**
+             * Values for everything it resolves.
+             */
+            variables?: {
+                [key: string]: string;
+            };
+        }
+        namespace Flow {
+            interface UnionMember1 {
+                /**
+                 * The edge case to run.
+                 */
+                id?: string;
+                /**
+                 * Run this one as that persona instead of its own.
+                 */
+                personaOverrideId?: string | null;
+                /**
+                 * The edge case to run, by its stable slug, matched within this flow. Use instead
+                 * of `id` for a run you keep in version control: a curated edge case’s id differs
+                 * between deployments and changes outright if it is renamed. Your own edge cases
+                 * have no slug and are named by `id`.
+                 */
+                slug?: string;
+                /**
+                 * Values for this one only.
+                 */
+                variables?: {
+                    [key: string]: string;
+                };
+            }
+        }
+        interface UnionMember1 {
+            /**
+             * A customer flow this plan runs.
+             */
+            flowId: string;
+            /**
+             * The values to apply.
+             */
+            variables: {
+                [key: string]: string;
+            };
+            /**
+             * Narrow to one edge case of that flow.
+             */
+            edgeCaseId?: string;
+            /**
+             * Narrow to the flow's happy path.
+             */
+            happyPath?: true;
+        }
+    }
 }
 export declare namespace Simulation {
     export { type SimulationRunResponse as SimulationRunResponse, type SimulationRunParams as SimulationRunParams, };

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

@@ -5,9 +5,16 @@ export declare class Simulation extends APIResource {
     /**
      * Starts a simulation and returns the run.
      *
-     * Send `plan` to describe a simulation and run it once. Add `saveAsPlan` to keep
-     * that configuration as a reusable run plan. Send `planId` instead to run a plan
-     * you already have.
+     * Send `template` to run one of the built-in templates: it supplies the metrics
+     * and checks, and for some templates the flows too, so the request only names the
+     * agent and the direction. Send `plan` to describe a simulation yourself and run
+     * it once. Send `planId` to run a plan you already have.
+     *
+     * `template` and `plan` both resolve to a run plan, returned as
+     * `simulationRunPlanId`. Add `saveAsPlan` to keep it, or read it back to see
+     * exactly what ran. A plan built from a template is a snapshot: retuning the
+     * template later never changes what that plan runs, which is what makes a saved
+     * one safe to pin in CI.
      *
      * @example
      * ```ts
@@ -65,7 +72,7 @@ export declare namespace SimulationRunResponse {
         status: 'PENDING' | 'QUEUED' | 'CREATING_SNAPSHOTS' | 'CREATING_SIMULATIONS' | 'PREPARING_CAPACITY' | 'RUNNING_SIMULATIONS' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'CANCELLING' | 'ENDING_SIMULATIONS';
     }
 }
-export type SimulationRunParams = SimulationRunParams.RunSimulationFromConfig | SimulationRunParams.RunSimulationFromPlanID;
+export type SimulationRunParams = SimulationRunParams.RunSimulationFromConfig | SimulationRunParams.RunSimulationFromPlanID | SimulationRunParams.RunSimulationFromTemplate;
 export declare namespace SimulationRunParams {
     interface RunSimulationFromConfig {
         /**
@@ -169,6 +176,21 @@ export declare namespace SimulationRunParams {
              * once with a different persona override or different variables.
              */
             flows?: Array<Plan.Flow>;
+            /**
+             * Let the run add metrics by itself off the attached flows, on top of the
+             * `metrics` named here.
+             *
+             * Two attach this way today: Agent Expectations wherever an attached flow has
+             * agent expectations written on it, and Keypad Entry wherever one has steps where
+             * the agent is expected to press keys. Both grade something authored on the flow
+             * that nothing else measures, which is why it is on by default.
+             *
+             * Set false when the `metrics` list is meant to be exhaustive: a plan testing only
+             * whether the caller can complete the flow may not want the agent graded on its
+             * expectations as well. False also pins the plan against any automatic metric
+             * Roark adds later.
+             */
+            includeAutomaticMetrics?: boolean;
             /**
              * Also collect each attached flow's own metrics, on top of the `metrics` named
              * here.
@@ -252,7 +274,7 @@ export declare namespace SimulationRunParams {
                 /**
                  * The customer flow to run.
                  */
-                id: string;
+                id?: string;
                 /**
                  * `"ALL"` runs every edge case the flow has when the run starts, so one added
                  * later is covered. An array runs only the ones you name, each able to carry its
@@ -267,6 +289,12 @@ export declare namespace SimulationRunParams {
                  * Runs everything this attachment resolves as that persona instead of its own.
                  */
                 personaOverrideId?: string | null;
+                /**
+                 * The Roark-curated flow to run, by its stable slug. Use instead of `id` for a run
+                 * you keep in version control: a curated flow’s id differs between deployments,
+                 * its slug does not. Your own flows have no slug and are named by `id`.
+                 */
+                slug?: string;
                 /**
                  * Values for everything it resolves.
                  */
@@ -279,11 +307,18 @@ export declare namespace SimulationRunParams {
                     /**
                      * The edge case to run.
                      */
-                    id: string;
+                    id?: string;
                     /**
                      * Run this one as that persona instead of its own.
                      */
                     personaOverrideId?: string | null;
+                    /**
+                     * The edge case to run, by its stable slug, matched within this flow. Use instead
+                     * of `id` for a run you keep in version control: a curated edge case’s id differs
+                     * between deployments and changes outright if it is renamed. Your own edge cases
+                     * have no slug and are named by `id`.
+                     */
+                    slug?: string;
                     /**
                      * Values for this one only.
                      */
@@ -411,6 +446,186 @@ export declare namespace SimulationRunParams {
             };
         }
     }
+    interface RunSimulationFromTemplate {
+        /**
+         * The agent endpoints to call. No template can know these.
+         */
+        agentEndpoints: Array<RunSimulationFromTemplate.AgentEndpoint>;
+        /**
+         * Direction of the simulation (INBOUND or OUTBOUND)
+         */
+        direction: 'INBOUND' | 'OUTBOUND';
+        /**
+         * The template to run, as listed by GET /v1/simulation/template.
+         */
+        template: string;
+        /**
+         * Phrases that trigger end of call. Empty array disables the feature.
+         */
+        endCallPhrases?: Array<string>;
+        /**
+         * Semantic conditions that trigger end of call. The LLM evaluates the conversation
+         * against these conditions. Defaults to the template's `defaultEndCallReasons`, as
+         * returned by GET /v1/simulation/template. Pass an empty array to run with none.
+         */
+        endCallReasons?: Array<string>;
+        /**
+         * Merge the customer's own recording of the real call into each simulation, so
+         * metrics can be scored against the live leg as well as the simulated one. This is
+         * the API equivalent of the dashboard's live-enrichment toggle.
+         *
+         * With this on, the run provisions a phone number and holds each call open for up
+         * to 15 minutes waiting for a matching call to be posted to POST /v1/call. A call
+         * matches on the provisioned number (`roarkPhoneNumber` on the job) with a start
+         * time inside the simulation window. If nothing arrives, the simulation still
+         * completes and any `LIVE`-sourced metric produces no value.
+         *
+         * Required by any metric whose `requiresLiveConversation` is true: without it that
+         * metric is silently skipped.
+         */
+        enrichWithLiveConversation?: boolean;
+        /**
+         * Execution mode (PARALLEL or SEQUENTIAL)
+         */
+        executionMode?: 'PARALLEL' | 'SEQUENTIAL_SAME_RUN_PLAN' | 'SEQUENTIAL_PROJECT';
+        /**
+         * The flows to run, in the same shape a run plan takes them.
+         *
+         * Required when the template lists no flows of its own: it presets what to
+         * measure, and this says what to measure it on. Optional when it does, where these
+         * REPLACE the ones it would have run, so you can narrow a suite to the cases you
+         * care about. Either way, GET /v1/simulation/template lists the flows and variant
+         * ids each template covers.
+         */
+        flows?: Array<RunSimulationFromTemplate.Flow>;
+        /**
+         * Number of iterations to run for each test case (1-10000)
+         */
+        iterationCount?: number;
+        /**
+         * Maximum number of concurrent simulation jobs
+         */
+        maxConcurrentJobs?: number;
+        /**
+         * Defaults to the template's `defaultMaxSimulationDurationSeconds`, as returned by
+         * GET /v1/simulation/template.
+         */
+        maxSimulationDurationSeconds?: number;
+        /**
+         * What to call this. Defaults to the template's name and the date, and required
+         * with `saveAsPlan`.
+         */
+        name?: string;
+        /**
+         * Keeps the resolved configuration as a run plan, listed by GET
+         * /v1/simulation/plan and re-runnable with `planId`. Requires `name`.
+         */
+        saveAsPlan?: boolean;
+        /**
+         * Timeout in seconds for silence detection
+         */
+        silenceTimeoutSeconds?: number;
+        /**
+         * Values for the {{variables}} the run resolves. An object applies them
+         * everywhere; an array targets a flow, its happy path, or one of its edge cases
+         * with `flowId`.
+         *
+         * The scenario-scoped form the other variants accept is not valid here: a template
+         * run is always flow-based, so there would be no scenario for it to reach.
+         */
+        variables?: {
+            [key: string]: string;
+        } | Array<RunSimulationFromTemplate.UnionMember1>;
+    }
+    namespace RunSimulationFromTemplate {
+        interface AgentEndpoint {
+            id: string;
+        }
+        /**
+         * One customer flow attached to a run plan, and which of its ways of running you
+         * cover.
+         *
+         * Attaching the same flow more than once with different overrides is how you fan
+         * it out across personas or values.
+         */
+        interface Flow {
+            /**
+             * The customer flow to run.
+             */
+            id?: string;
+            /**
+             * `"ALL"` runs every edge case the flow has when the run starts, so one added
+             * later is covered. An array runs only the ones you name, each able to carry its
+             * own persona override and values.
+             */
+            edgeCases?: 'ALL' | Array<Flow.UnionMember1>;
+            /**
+             * Run the flow's happy path. Resolved when the run starts, so it follows the flow.
+             */
+            happyPath?: boolean;
+            /**
+             * Runs everything this attachment resolves as that persona instead of its own.
+             */
+            personaOverrideId?: string | null;
+            /**
+             * The Roark-curated flow to run, by its stable slug. Use instead of `id` for a run
+             * you keep in version control: a curated flow’s id differs between deployments,
+             * its slug does not. Your own flows have no slug and are named by `id`.
+             */
+            slug?: string;
+            /**
+             * Values for everything it resolves.
+             */
+            variables?: {
+                [key: string]: string;
+            };
+        }
+        namespace Flow {
+            interface UnionMember1 {
+                /**
+                 * The edge case to run.
+                 */
+                id?: string;
+                /**
+                 * Run this one as that persona instead of its own.
+                 */
+                personaOverrideId?: string | null;
+                /**
+                 * The edge case to run, by its stable slug, matched within this flow. Use instead
+                 * of `id` for a run you keep in version control: a curated edge case’s id differs
+                 * between deployments and changes outright if it is renamed. Your own edge cases
+                 * have no slug and are named by `id`.
+                 */
+                slug?: string;
+                /**
+                 * Values for this one only.
+                 */
+                variables?: {
+                    [key: string]: string;
+                };
+            }
+        }
+        interface UnionMember1 {
+            /**
+             * A customer flow this plan runs.
+             */
+            flowId: string;
+            /**
+             * The values to apply.
+             */
+            variables: {
+                [key: string]: string;
+            };
+            /**
+             * Narrow to one edge case of that flow.
+             */
+            edgeCaseId?: string;
+            /**
+             * Narrow to the flow's happy path.
+             */
+            happyPath?: true;
+        }
+    }
 }
 export declare namespace Simulation {
     export { type SimulationRunResponse as SimulationRunResponse, type SimulationRunParams as SimulationRunParams, };

package/resources/simulation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../src/resources/simulation.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,4BAAyB;AAC/C,OAAO,EAAE,UAAU,EAAE,+BAA4B;AACjD,OAAO,EAAE,cAAc,EAAE,uCAAoC;AAE7D,qBAAa,UAAW,SAAQ,WAAW;IACzC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,GAAG,CAAC,IAAI,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,qBAAqB,CAAC;CAG5F;AAED,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,IAAI,EAAE,qBAAqB,CAAC,IAAI,CAAC;CAClC;AAED,yBAAiB,qBAAqB,CAAC;IACrC;;OAEG;IACH,UAAiB,IAAI;QACnB;;WAEG;QACH,SAAS,EAAE,MAAM,CAAC;QAElB;;;WAGG;QACH,WAAW,EAAE,OAAO,CAAC;QAErB;;WAEG;QACH,kBAAkB,EAAE,MAAM,CAAC;QAE3B;;;WAGG;QACH,mBAAmB,EAAE,MAAM,CAAC;QAE5B;;WAEG;QACH,sBAAsB,EAAE,MAAM,CAAC;QAE/B;;;WAGG;QACH,MAAM,EACF,SAAS,GACT,QAAQ,GACR,oBAAoB,GACpB,sBAAsB,GACtB,oBAAoB,GACpB,qBAAqB,GACrB,WAAW,GACX,QAAQ,GACR,WAAW,GACX,WAAW,GACX,YAAY,GACZ,oBAAoB,CAAC;KAC1B;CACF;AAED,MAAM,MAAM,mBAAmB,GAC3B,mBAAmB,CAAC,uBAAuB,GAC3C,mBAAmB,CAAC,uBAAuB,CAAC;AAEhD,MAAM,CAAC,OAAO,WAAW,mBAAmB,CAAC;IAC3C,UAAiB,uBAAuB;QACtC;;WAEG;QACH,IAAI,EAAE,uBAAuB,CAAC,IAAI,CAAC;QAEnC;;;;;;;WAOG;QACH,UAAU,CAAC,EAAE,OAAO,CAAC;QAErB;;;;;;;;;;;;;;;;;;;;;;;;WAwBG;QACH,SAAS,CAAC,EACN;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE,GACzB,KAAK,CAAC,uBAAuB,CAAC,YAAY,CAAC,GAC3C,KAAK,CAAC,uBAAuB,CAAC,YAAY,CAAC,CAAC;KACjD;IAED,UAAiB,uBAAuB,CAAC;QACvC;;WAEG;QACH,UAAiB,IAAI;YACnB;;eAEG;YACH,cAAc,EAAE,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAE1C;;eAEG;YACH,SAAS,EAAE,SAAS,GAAG,UAAU,CAAC;YAElC;;eAEG;YACH,4BAA4B,EAAE,MAAM,CAAC;YAErC;;;eAGG;YACH,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAE5B;;eAEG;YACH,WAAW,CAAC,EAAE,MAAM,CAAC;YAErB;;eAEG;YACH,cAAc,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;YAE/B;;;eAGG;YACH,cAAc,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;YAE/B;;;;;;;;;;;;;eAaG;YACH,0BAA0B,CAAC,EAAE,OAAO,CAAC;YAErC;;eAEG;YACH,aAAa,CAAC,EAAE,UAAU,GAAG,0BAA0B,GAAG,oBAAoB,CAAC;YAE/E;;;eAGG;YACH,KAAK,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAEzB;;;;;;;;;;;eAWG;YACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;YAE7B;;eAEG;YACH,cAAc,CAAC,EAAE,MAAM,CAAC;YAExB;;eAEG;YACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;YAE3B;;;eAGG;YACH,IAAI,CAAC,EAAE,MAAM,CAAC;YAEd;;;eAGG;YACH,QAAQ,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAE/B;;;eAGG;YACH,SAAS,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAEjC;;eAEG;YACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;SAChC;QAED,UAAiB,IAAI,CAAC;YACpB,UAAiB,aAAa;gBAC5B,EAAE,EAAE,MAAM,CAAC;aACZ;YAED,UAAiB,MAAM;gBACrB;;mBAEG;gBACH,EAAE,CAAC,EAAE,MAAM,CAAC;gBAEZ;;;;;;;;;mBASG;gBACH,kBAAkB,CAAC,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC;gBAEjD;;;mBAGG;gBACH,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAElB;;;mBAGG;gBACH,IAAI,CAAC,EAAE,MAAM,CAAC;aACf;YAED;;;;;;eAMG;YACH,UAAiB,IAAI;gBACnB;;mBAEG;gBACH,EAAE,EAAE,MAAM,CAAC;gBAEX;;;;mBAIG;gBACH,SAAS,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;gBAE7C;;mBAEG;gBACH,SAAS,CAAC,EAAE,OAAO,CAAC;gBAEpB;;mBAEG;gBACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;gBAElC;;mBAEG;gBACH,SAAS,CAAC,EAAE;oBAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;iBAAE,CAAC;aACvC;YAED,UAAiB,IAAI,CAAC;gBACpB,UAAiB,YAAY;oBAC3B;;uBAEG;oBACH,EAAE,EAAE,MAAM,CAAC;oBAEX;;uBAEG;oBACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;oBAElC;;uBAEG;oBACH,SAAS,CAAC,EAAE;wBAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;qBAAE,CAAC;iBACvC;aACF;YAED,UAAiB,OAAO;gBACtB,EAAE,EAAE,MAAM,CAAC;aACZ;YAED,UAAiB,QAAQ;gBACvB;;mBAEG;gBACH,EAAE,EAAE,MAAM,CAAC;gBAEX;;;mBAGG;gBACH,SAAS,CAAC,EAAE;oBAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;iBAAE,CAAC;aACvC;SACF;QAED,UAAiB,YAAY;YAC3B;;eAEG;YACH,MAAM,EAAE,MAAM,CAAC;YAEf;;eAEG;YACH,SAAS,EAAE;gBAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;aAAE,CAAC;YAErC;;eAEG;YACH,UAAU,CAAC,EAAE,MAAM,CAAC;YAEpB;;eAEG;YACH,SAAS,CAAC,EAAE,IAAI,CAAC;SAClB;QAED,UAAiB,YAAY;YAC3B;;eAEG;YACH,UAAU,EAAE,MAAM,CAAC;YAEnB;;eAEG;YACH,SAAS,EAAE;gBAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;aAAE,CAAC;SACtC;KACF;IAED,UAAiB,uBAAuB;QACtC;;;WAGG;QACH,MAAM,EAAE,MAAM,CAAC;QAEf;;;;;;;;;;;;;;;;;;;;;;;;WAwBG;QACH,SAAS,CAAC,EACN;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE,GACzB,KAAK,CAAC,uBAAuB,CAAC,YAAY,CAAC,GAC3C,KAAK,CAAC,uBAAuB,CAAC,YAAY,CAAC,CAAC;KACjD;IAED,UAAiB,uBAAuB,CAAC;QACvC,UAAiB,YAAY;YAC3B;;eAEG;YACH,MAAM,EAAE,MAAM,CAAC;YAEf;;eAEG;YACH,SAAS,EAAE;gBAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;aAAE,CAAC;YAErC;;eAEG;YACH,UAAU,CAAC,EAAE,MAAM,CAAC;YAEpB;;eAEG;YACH,SAAS,CAAC,EAAE,IAAI,CAAC;SAClB;QAED,UAAiB,YAAY;YAC3B;;eAEG;YACH,UAAU,EAAE,MAAM,CAAC;YAEnB;;eAEG;YACH,SAAS,EAAE;gBAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;aAAE,CAAC;SACtC;KACF;CACF;AAED,MAAM,CAAC,OAAO,WAAW,UAAU,CAAC;IAClC,OAAO,EACL,KAAK,qBAAqB,IAAI,qBAAqB,EACnD,KAAK,mBAAmB,IAAI,mBAAmB,GAChD,CAAC;CACH"}
+{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../src/resources/simulation.ts"],"names":[],"mappings":"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"}

package/resources/simulation.js

@@ -7,9 +7,16 @@ class Simulation extends resource_1.APIResource {
     /**
      * Starts a simulation and returns the run.
      *
-     * Send `plan` to describe a simulation and run it once. Add `saveAsPlan` to keep
-     * that configuration as a reusable run plan. Send `planId` instead to run a plan
-     * you already have.
+     * Send `template` to run one of the built-in templates: it supplies the metrics
+     * and checks, and for some templates the flows too, so the request only names the
+     * agent and the direction. Send `plan` to describe a simulation yourself and run
+     * it once. Send `planId` to run a plan you already have.
+     *
+     * `template` and `plan` both resolve to a run plan, returned as
+     * `simulationRunPlanId`. Add `saveAsPlan` to keep it, or read it back to see
+     * exactly what ran. A plan built from a template is a snapshot: retuning the
+     * template later never changes what that plan runs, which is what makes a saved
+     * one safe to pin in CI.
      *
      * @example
      * ```ts

package/resources/simulation.js.map

@@ -1 +1 @@
-{"version":3,"file":"simulation.js","sourceRoot":"","sources":["../src/resources/simulation.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAI/C,MAAa,UAAW,SAAQ,sBAAW;IACzC;;;;;;;;;;;;;;;;;;;;OAoBG;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;AAzBD,gCAyBC"}
+{"version":3,"file":"simulation.js","sourceRoot":"","sources":["../src/resources/simulation.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAI/C,MAAa,UAAW,SAAQ,sBAAW;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;AAhCD,gCAgCC"}

package/resources/simulation.mjs

@@ -4,9 +4,16 @@ export class Simulation extends APIResource {
     /**
      * Starts a simulation and returns the run.
      *
-     * Send `plan` to describe a simulation and run it once. Add `saveAsPlan` to keep
-     * that configuration as a reusable run plan. Send `planId` instead to run a plan
-     * you already have.
+     * Send `template` to run one of the built-in templates: it supplies the metrics
+     * and checks, and for some templates the flows too, so the request only names the
+     * agent and the direction. Send `plan` to describe a simulation yourself and run
+     * it once. Send `planId` to run a plan you already have.
+     *
+     * `template` and `plan` both resolve to a run plan, returned as
+     * `simulationRunPlanId`. Add `saveAsPlan` to keep it, or read it back to see
+     * exactly what ran. A plan built from a template is a snapshot: retuning the
+     * template later never changes what that plan runs, which is what makes a saved
+     * one safe to pin in CI.
      *
      * @example
      * ```ts