@roarkanalytics/sdk-mcp 4.12.1 → 4.13.0

package/oauth.mjs

@@ -8,6 +8,8 @@
 // key (minted at consent with the permissions the user picked, expiring and
 // rotated by the client's refresh token), so it is forwarded to customer-api as
 // the SDK bearer unchanged: customer-api validates it on every call.
+import { createHash } from 'node:crypto';
+import { readEnv } from "./util.mjs";
 /** Thrown when a request cannot be authorized; carries the WWW-Authenticate value to return. */
 export class UnauthorizedError extends Error {
     wwwAuthenticate;
@@ -90,4 +92,130 @@ export const requireBearer = (req, config, connector = ORIGIN_CONNECTOR) => {
     }
     return options;
 };
+/** The SDK's own default, for when neither an option nor the environment names one. */
+export const DEFAULT_API_BASE_URL = 'https://api.roark.ai';
+/**
+ * The base URL the SDK will actually call, resolved exactly the way the SDK resolves it:
+ * explicit option, then `ROARK_BASE_URL`, then the default.
+ *
+ * This has to agree with the SDK or the liveness check asks the wrong host. `launchStreamableHTTPServer`
+ * passes no `clientOptions` at all, so for the deployed server the answer always comes from the
+ * environment: a hardcoded prod default would send every check to prod while data calls went to
+ * whatever `ROARK_BASE_URL` names. On any stage but prod that turns a valid token into a 401 from
+ * a server it was never issued for, and this file would then refuse every request - a dead
+ * connector, which is strictly worse than the bug it is here to fix.
+ */
+export const resolveApiBaseUrl = (clientOptions = {}) => clientOptions.baseURL ?? readEnv('ROARK_BASE_URL') ?? DEFAULT_API_BASE_URL;
+/**
+ * How long a verdict is reused. `newServer` runs per POST, not per session, so an uncached check
+ * would add a round trip to every single MCP request. The window is what a revoked token buys:
+ * it can still complete a handshake and read the tool list for up to this long. It cannot read
+ * anything, because every data path carries the same token to customer-api and is refused there
+ * immediately.
+ */
+const BEARER_CACHE_TTL_MS = 60_000;
+/**
+ * An unreachable customer-api is handled by the catch below, but a customer-api that accepts the
+ * connection and then never answers is not: without a deadline every MCP request would hang on
+ * it, which is worse than the failure this check exists to report. A hang becomes `unknown` like
+ * any other transport failure.
+ */
+const BEARER_CHECK_TIMEOUT_MS = 3_000;
+/**
+ * Bounded so that spraying invented tokens cannot grow the process's memory. Keys are hashes,
+ * not the tokens themselves: these are live credentials and there is no reason to keep a second
+ * copy of them in a long-lived map.
+ */
+const BEARER_CACHE_MAX = 1_000;
+const bearerVerdicts = new Map();
+/**
+ * Checks already in flight, so concurrent requests bearing the same uncached token make one call
+ * rather than one each. That is the common shape right after a verdict expires, and whenever a
+ * client opens several requests at once.
+ */
+const inFlightChecks = new Map();
+/** Test seam. */
+export const clearBearerVerdictCache = () => {
+    bearerVerdicts.clear();
+    inFlightChecks.clear();
+};
+const hashToken = (token) => createHash('sha256').update(token).digest('hex');
+const rememberVerdict = (key, verdict, expiresAt) => {
+    // Evict the oldest entry rather than clearing the map. A `clear()` would let anyone spraying
+    // invented tokens flush every valid verdict too, making legitimate callers pay a round trip
+    // each and handing customer-api the extra work. Map iterates in insertion order, so the first
+    // key is the oldest.
+    if (bearerVerdicts.size >= BEARER_CACHE_MAX) {
+        const oldest = bearerVerdicts.keys().next();
+        if (!oldest.done)
+            bearerVerdicts.delete(oldest.value);
+    }
+    bearerVerdicts.set(key, { verdict, expiresAt });
+};
+/**
+ * Asks customer-api whether a bearer is still live, via the `/v1/me` endpoint it already exposes
+ * for exactly this ("who is this credential"), and caches the answer briefly.
+ *
+ * Only a 401 counts as invalid. A 403 means the token authenticated and then failed a permission
+ * check, which is a live token; treating it as invalid would tell a client to re-authorize when
+ * re-authorizing cannot help. Anything else - a 5xx, a timeout, a DNS failure - is `unknown`.
+ */
+export const verifyBearer = async (token, deps) => {
+    const { baseURL, fetchImpl = fetch, now = Date.now, ttlMs = BEARER_CACHE_TTL_MS, timeoutMs = BEARER_CHECK_TIMEOUT_MS, } = deps;
+    const key = hashToken(token);
+    const cached = bearerVerdicts.get(key);
+    if (cached && cached.expiresAt > now())
+        return cached.verdict;
+    const alreadyRunning = inFlightChecks.get(key);
+    if (alreadyRunning)
+        return alreadyRunning;
+    const check = (async () => {
+        let response;
+        try {
+            response = await fetchImpl(`${stripSlash(baseURL)}/v1/me`, {
+                method: 'GET',
+                headers: { Authorization: `Bearer ${token}` },
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch {
+            return 'unknown';
+        }
+        const verdict = response.status === 401 ? 'invalid'
+            : response.ok ? 'valid'
+                : 'unknown';
+        // An `unknown` is never cached: a blip would otherwise pin the answer for the whole TTL.
+        if (verdict !== 'unknown')
+            rememberVerdict(key, verdict, now() + ttlMs);
+        return verdict;
+    })();
+    inFlightChecks.set(key, check);
+    try {
+        return await check;
+    }
+    finally {
+        inFlightChecks.delete(key);
+    }
+};
+/**
+ * Rejects a bearer customer-api has already disowned, with the 401 + WWW-Authenticate that tells
+ * an MCP client to re-run the OAuth flow.
+ *
+ * Without this the resource server only checked that a token was PRESENT. A revoked, expired or
+ * entirely invented token completed `initialize` and `tools/list`, and the caller learned nothing
+ * until a tool call failed with an opaque 401 in its result text. No data was reachable - every
+ * data path revalidates at customer-api - but a client that never sees a 401 from the resource
+ * server has no reason to refresh, which for a 24h token means a connector that looks connected
+ * and silently cannot work.
+ *
+ * `unknown` is allowed through deliberately. Failing closed would turn a customer-api blip into a
+ * dead connector for everyone, and it would buy no confidentiality: the token still has to pass
+ * customer-api on the very next call that touches data.
+ */
+export const requireLiveBearer = async (token, config, connector, deps) => {
+    const verdict = await verifyBearer(token, deps);
+    if (verdict !== 'invalid')
+        return;
+    throw new UnauthorizedError('The access token is expired or has been revoked', bearerChallenge(config, connector, 'invalid_token', 'The access token is expired or has been revoked'));
+};
 //# sourceMappingURL=oauth.mjs.map

package/oauth.mjs.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roarkanalytics/sdk-mcp",
-  "version": "4.12.1",
+  "version": "4.13.0",
   "description": "The official MCP Server for the Roark API",
   "author": "Roark <james@roark.ai>",
   "types": "./index.d.ts",

package/server.js

@@ -19,7 +19,7 @@ const instructions_1 = require("./instructions.js");
 const methods_1 = require("./methods.js");
 const newMcpServer = async ({ stainlessApiKey, customInstructionsPath, }) => new mcp_js_1.McpServer({
     name: 'roarkanalytics_sdk_api',
-    version: '4.12.1', // x-release-please-version
+    version: '4.13.0', // x-release-please-version
 }, {
     instructions: await (0, instructions_1.getInstructions)({ stainlessApiKey, customInstructionsPath }),
     capabilities: { tools: {}, logging: {} },

package/server.mjs

@@ -10,7 +10,7 @@ import { getInstructions } from "./instructions.mjs";
 import { blockedMethodsForCodeTool } from "./methods.mjs";
 export const newMcpServer = async ({ stainlessApiKey, customInstructionsPath, }) => new McpServer({
     name: 'roarkanalytics_sdk_api',
-    version: '4.12.1', // x-release-please-version
+    version: '4.13.0', // x-release-please-version
 }, {
     instructions: await getInstructions({ stainlessApiKey, customInstructionsPath }),
     capabilities: { tools: {}, logging: {} },

package/src/http.ts

@@ -15,6 +15,8 @@ import {
   ORIGIN_CONNECTOR,
   protectedResourceMetadata,
   requireBearer,
+  requireLiveBearer,
+  resolveApiBaseUrl,
   UnauthorizedError,
 } from './oauth';
 import { initMcpServer, newMcpServer } from './server';
@@ -52,7 +54,20 @@ const newServer = async ({
   // not be able to make us do that.
   let authOptions: Partial<ClientOptions>;
   if (mcpOptions.oauth) {
-    authOptions = requireBearer(req, mcpOptions.oauth, connectorFrom(req));
+    const connector = connectorFrom(req);
+    const authorized = requireBearer(req, mcpOptions.oauth, connector);
+    // Presence is not validity. Ask customer-api whether the token is still live, so a revoked or
+    // expired one is answered with 401 + WWW-Authenticate here - the signal a client needs to
+    // re-run the OAuth flow - rather than completing the handshake and failing later inside a
+    // tool result, where nothing is listening for it.
+    //
+    // The base URL is resolved the way the SDK resolves it, NOT defaulted to prod: this server is
+    // launched without `clientOptions`, so on any stage but prod a prod default would check the
+    // token against a server that never issued it and refuse every request.
+    await requireLiveBearer(authorized.bearerToken, mcpOptions.oauth, connector, {
+      baseURL: resolveApiBaseUrl(clientOptions),
+    });
+    authOptions = authorized;
   } else {
     authOptions = parseClientAuthHeaders(req, false);
   }

package/src/local-docs-search.ts

@@ -1001,9 +1001,9 @@ const EMBEDDED_METHODS: MethodEntry[] = [
     qualified: 'client.simulationJob.lookup',
     params: ['roarkPhoneNumber: string;', 'callReceivedAt?: string;'],
     response:
-      "{ data: { agentEndpoint: { id: string; name: string; phoneNumber: string; type: string; }; createdAt: string; enrichment: { outcome: 'NOT_REQUESTED' | 'WAITING' | 'MERGED' | 'TIMED_OUT' | 'SKIPPED' | 'UNKNOWN'; requested: boolean; metricsNotCollected?: number; metricsScoredOnSimulationInstead?: number; waitEndedAt?: string; waitStartedAt?: string; }; failureOwner: 'ROARK' | 'AGENT'; invalidation: { invalidatedAt: string; reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED' | 'REQUIRED_STAGE_INCOMPLETE' | 'CALLER_NEVER_TOOK_OVER' | 'AGENT_NEVER_SPOKE'; detail?: string; }; persona: { id: string; accent: string; age: 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY'; backgroundNoise: string; baseEmotion: string; confirmationStyle: 'EXPLICIT' | 'VAGUE'; createdAt: string; gender: 'MALE' | 'FEMALE'; hasDisfluencies: boolean; idleMessageMaxSpokenCount: number; idleMessageResetCountOnUserSpeechEnabled: boolean; idleMessages: string[]; idleTimeoutSeconds: number; intentClarity: 'CLEAR' | 'INDIRECT' | 'VAGUE'; interruption: 'OFF' | 'BACKCHANNEL' | 'OCCASIONAL' | 'HEAVY'; language: string; memoryReliability: 'HIGH' | 'LOW'; name: string; properties: object; responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK' | 'BARGE_IN'; speechClarity: 'CLEAR' | 'VAGUE' | 'RAMBLING'; speechPace: 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'; understoodLanguages: string[]; updatedAt: string; backstoryPrompt?: string; description?: string; displayName?: string; secondaryLanguage?: 'EN'; }; processingStatus: string; queuePosition: number; runPlan: { id: string; name: string; variables: object; }; scenario: { id: string; description?: string; }; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }; }",
+      "{ data: { agentEndpoint: { id: string; name: string; phoneNumber: string; type: string; }; backgroundNoise: { backgroundNoise: string; backgroundNoiseVolume: number; source: 'ENVIRONMENT' | 'PERSONA'; }; createdAt: string; enrichment: { outcome: 'NOT_REQUESTED' | 'WAITING' | 'MERGED' | 'TIMED_OUT' | 'SKIPPED' | 'UNKNOWN'; requested: boolean; metricsNotCollected?: number; metricsScoredOnSimulationInstead?: number; waitEndedAt?: string; waitStartedAt?: string; }; failureOwner: 'ROARK' | 'AGENT'; invalidation: { invalidatedAt: string; reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED' | 'REQUIRED_STAGE_INCOMPLETE' | 'CALLER_NEVER_TOOK_OVER' | 'AGENT_NEVER_SPOKE'; detail?: string; }; persona: { id: string; accent: string; age: 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY'; backgroundNoise: string; baseEmotion: string; confirmationStyle: 'EXPLICIT' | 'VAGUE'; createdAt: string; gender: 'MALE' | 'FEMALE'; hasDisfluencies: boolean; idleMessageMaxSpokenCount: number; idleMessageResetCountOnUserSpeechEnabled: boolean; idleMessages: string[]; idleTimeoutSeconds: number; intentClarity: 'CLEAR' | 'INDIRECT' | 'VAGUE'; interruption: 'OFF' | 'BACKCHANNEL' | 'OCCASIONAL' | 'HEAVY'; language: string; memoryReliability: 'HIGH' | 'LOW'; name: string; properties: object; responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK' | 'BARGE_IN'; speechClarity: 'CLEAR' | 'VAGUE' | 'RAMBLING'; speechPace: 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'; understoodLanguages: string[]; updatedAt: string; backstoryPrompt?: string; description?: string; displayName?: string; secondaryLanguage?: 'EN'; }; processingStatus: string; queuePosition: number; runPlan: { id: string; name: string; variables: object; }; scenario: { id: string; description?: string; }; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }; }",
     markdown:
-      "## lookup\n\n`client.simulationJob.lookup(roarkPhoneNumber: string, callReceivedAt?: string): { data: object; }`\n\n**get** `/v1/simulation/job/lookup`\n\nFind the matching simulation using the number used by the Roark simulation agent.\n\n### Parameters\n\n- `roarkPhoneNumber: string`\n  Phone number provisioned by Roark for the simulation job in E.164 format. In the case of an inbound simulation, this is the number that calls your agent; in the case of an outbound simulation, this is the number you call from your agent.\n\n- `callReceivedAt?: string`\n  ISO 8601 timestamp of when the call was received. Alternatively, any time between the start and end of the call is valid. Defaults to the current time, which fetches any jobs that are currently ongoing.\n\n### Returns\n\n- `{ data: { agentEndpoint: { id: string; name: string; phoneNumber: string; type: string; }; createdAt: string; enrichment: { outcome: 'NOT_REQUESTED' | 'WAITING' | 'MERGED' | 'TIMED_OUT' | 'SKIPPED' | 'UNKNOWN'; requested: boolean; metricsNotCollected?: number; metricsScoredOnSimulationInstead?: number; waitEndedAt?: string; waitStartedAt?: string; }; failureOwner: 'ROARK' | 'AGENT'; invalidation: { invalidatedAt: string; reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED' | 'REQUIRED_STAGE_INCOMPLETE' | 'CALLER_NEVER_TOOK_OVER' | 'AGENT_NEVER_SPOKE'; detail?: string; }; persona: { id: string; accent: string; age: 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY'; backgroundNoise: string; baseEmotion: string; confirmationStyle: 'EXPLICIT' | 'VAGUE'; createdAt: string; gender: 'MALE' | 'FEMALE'; hasDisfluencies: boolean; idleMessageMaxSpokenCount: number; idleMessageResetCountOnUserSpeechEnabled: boolean; idleMessages: string[]; idleTimeoutSeconds: number; intentClarity: 'CLEAR' | 'INDIRECT' | 'VAGUE'; interruption: 'OFF' | 'BACKCHANNEL' | 'OCCASIONAL' | 'HEAVY'; language: string; memoryReliability: 'HIGH' | 'LOW'; name: string; properties: object; responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK' | 'BARGE_IN'; speechClarity: 'CLEAR' | 'VAGUE' | 'RAMBLING'; speechPace: 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'; understoodLanguages: string[]; updatedAt: string; backstoryPrompt?: string; description?: string; displayName?: string; secondaryLanguage?: 'EN'; }; processingStatus: string; queuePosition: number; runPlan: { id: string; name: string; variables: object; }; scenario: { id: string; description?: string; }; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }; }`\n\n  - `data: { agentEndpoint: { id: string; name: string; phoneNumber: string; type: string; }; createdAt: string; enrichment: { outcome: 'NOT_REQUESTED' | 'WAITING' | 'MERGED' | 'TIMED_OUT' | 'SKIPPED' | 'UNKNOWN'; requested: boolean; metricsNotCollected?: number; metricsScoredOnSimulationInstead?: number; waitEndedAt?: string; waitStartedAt?: string; }; failureOwner: 'ROARK' | 'AGENT'; invalidation: { invalidatedAt: string; reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED' | 'REQUIRED_STAGE_INCOMPLETE' | 'CALLER_NEVER_TOOK_OVER' | 'AGENT_NEVER_SPOKE'; detail?: string; }; persona: { id: string; accent: string; age: 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY'; backgroundNoise: string; baseEmotion: string; confirmationStyle: 'EXPLICIT' | 'VAGUE'; createdAt: string; gender: 'MALE' | 'FEMALE'; hasDisfluencies: boolean; idleMessageMaxSpokenCount: number; idleMessageResetCountOnUserSpeechEnabled: boolean; idleMessages: string[]; idleTimeoutSeconds: number; intentClarity: 'CLEAR' | 'INDIRECT' | 'VAGUE'; interruption: 'OFF' | 'BACKCHANNEL' | 'OCCASIONAL' | 'HEAVY'; language: string; memoryReliability: 'HIGH' | 'LOW'; name: string; properties: object; responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK' | 'BARGE_IN'; speechClarity: 'CLEAR' | 'VAGUE' | 'RAMBLING'; speechPace: 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'; understoodLanguages: string[]; updatedAt: string; backstoryPrompt?: string; description?: string; displayName?: string; secondaryLanguage?: 'EN'; }; processingStatus: string; queuePosition: number; runPlan: { id: string; name: string; variables: object; }; scenario: { id: string; description?: string; }; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }`\n\n### Example\n\n```typescript\nimport Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark();\n\nconst response = await client.simulationJob.lookup({ roarkPhoneNumber: 'roarkPhoneNumber' });\n\nconsole.log(response);\n```",
+      "## lookup\n\n`client.simulationJob.lookup(roarkPhoneNumber: string, callReceivedAt?: string): { data: object; }`\n\n**get** `/v1/simulation/job/lookup`\n\nFind the matching simulation using the number used by the Roark simulation agent.\n\n### Parameters\n\n- `roarkPhoneNumber: string`\n  Phone number provisioned by Roark for the simulation job in E.164 format. In the case of an inbound simulation, this is the number that calls your agent; in the case of an outbound simulation, this is the number you call from your agent.\n\n- `callReceivedAt?: string`\n  ISO 8601 timestamp of when the call was received. Alternatively, any time between the start and end of the call is valid. Defaults to the current time, which fetches any jobs that are currently ongoing.\n\n### Returns\n\n- `{ data: { agentEndpoint: { id: string; name: string; phoneNumber: string; type: string; }; backgroundNoise: { backgroundNoise: string; backgroundNoiseVolume: number; source: 'ENVIRONMENT' | 'PERSONA'; }; createdAt: string; enrichment: { outcome: 'NOT_REQUESTED' | 'WAITING' | 'MERGED' | 'TIMED_OUT' | 'SKIPPED' | 'UNKNOWN'; requested: boolean; metricsNotCollected?: number; metricsScoredOnSimulationInstead?: number; waitEndedAt?: string; waitStartedAt?: string; }; failureOwner: 'ROARK' | 'AGENT'; invalidation: { invalidatedAt: string; reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED' | 'REQUIRED_STAGE_INCOMPLETE' | 'CALLER_NEVER_TOOK_OVER' | 'AGENT_NEVER_SPOKE'; detail?: string; }; persona: { id: string; accent: string; age: 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY'; backgroundNoise: string; baseEmotion: string; confirmationStyle: 'EXPLICIT' | 'VAGUE'; createdAt: string; gender: 'MALE' | 'FEMALE'; hasDisfluencies: boolean; idleMessageMaxSpokenCount: number; idleMessageResetCountOnUserSpeechEnabled: boolean; idleMessages: string[]; idleTimeoutSeconds: number; intentClarity: 'CLEAR' | 'INDIRECT' | 'VAGUE'; interruption: 'OFF' | 'BACKCHANNEL' | 'OCCASIONAL' | 'HEAVY'; language: string; memoryReliability: 'HIGH' | 'LOW'; name: string; properties: object; responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK' | 'BARGE_IN'; speechClarity: 'CLEAR' | 'VAGUE' | 'RAMBLING'; speechPace: 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'; understoodLanguages: string[]; updatedAt: string; backstoryPrompt?: string; description?: string; displayName?: string; secondaryLanguage?: 'EN'; }; processingStatus: string; queuePosition: number; runPlan: { id: string; name: string; variables: object; }; scenario: { id: string; description?: string; }; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }; }`\n\n  - `data: { agentEndpoint: { id: string; name: string; phoneNumber: string; type: string; }; backgroundNoise: { backgroundNoise: string; backgroundNoiseVolume: number; source: 'ENVIRONMENT' | 'PERSONA'; }; createdAt: string; enrichment: { outcome: 'NOT_REQUESTED' | 'WAITING' | 'MERGED' | 'TIMED_OUT' | 'SKIPPED' | 'UNKNOWN'; requested: boolean; metricsNotCollected?: number; metricsScoredOnSimulationInstead?: number; waitEndedAt?: string; waitStartedAt?: string; }; failureOwner: 'ROARK' | 'AGENT'; invalidation: { invalidatedAt: string; reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED' | 'REQUIRED_STAGE_INCOMPLETE' | 'CALLER_NEVER_TOOK_OVER' | 'AGENT_NEVER_SPOKE'; detail?: string; }; persona: { id: string; accent: string; age: 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY'; backgroundNoise: string; baseEmotion: string; confirmationStyle: 'EXPLICIT' | 'VAGUE'; createdAt: string; gender: 'MALE' | 'FEMALE'; hasDisfluencies: boolean; idleMessageMaxSpokenCount: number; idleMessageResetCountOnUserSpeechEnabled: boolean; idleMessages: string[]; idleTimeoutSeconds: number; intentClarity: 'CLEAR' | 'INDIRECT' | 'VAGUE'; interruption: 'OFF' | 'BACKCHANNEL' | 'OCCASIONAL' | 'HEAVY'; language: string; memoryReliability: 'HIGH' | 'LOW'; name: string; properties: object; responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK' | 'BARGE_IN'; speechClarity: 'CLEAR' | 'VAGUE' | 'RAMBLING'; speechPace: 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'; understoodLanguages: string[]; updatedAt: string; backstoryPrompt?: string; description?: string; displayName?: string; secondaryLanguage?: 'EN'; }; processingStatus: string; queuePosition: number; runPlan: { id: string; name: string; variables: object; }; scenario: { id: string; description?: string; }; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }`\n\n### Example\n\n```typescript\nimport Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark();\n\nconst response = await client.simulationJob.lookup({ roarkPhoneNumber: 'roarkPhoneNumber' });\n\nconsole.log(response);\n```",
     perLanguage: {
       typescript: {
         method: 'client.simulationJob.lookup',
@@ -1032,9 +1032,9 @@ const EMBEDDED_METHODS: MethodEntry[] = [
     qualified: 'client.simulationJob.getByID',
     params: ['jobId: string;'],
     response:
-      "{ data: { agentEndpoint: { id: string; name: string; phoneNumber: string; type: string; }; createdAt: string; enrichment: { outcome: 'NOT_REQUESTED' | 'WAITING' | 'MERGED' | 'TIMED_OUT' | 'SKIPPED' | 'UNKNOWN'; requested: boolean; metricsNotCollected?: number; metricsScoredOnSimulationInstead?: number; waitEndedAt?: string; waitStartedAt?: string; }; failureOwner: 'ROARK' | 'AGENT'; invalidation: { invalidatedAt: string; reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED' | 'REQUIRED_STAGE_INCOMPLETE' | 'CALLER_NEVER_TOOK_OVER' | 'AGENT_NEVER_SPOKE'; detail?: string; }; persona: { id: string; accent: string; age: 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY'; backgroundNoise: string; baseEmotion: string; confirmationStyle: 'EXPLICIT' | 'VAGUE'; createdAt: string; gender: 'MALE' | 'FEMALE'; hasDisfluencies: boolean; idleMessageMaxSpokenCount: number; idleMessageResetCountOnUserSpeechEnabled: boolean; idleMessages: string[]; idleTimeoutSeconds: number; intentClarity: 'CLEAR' | 'INDIRECT' | 'VAGUE'; interruption: 'OFF' | 'BACKCHANNEL' | 'OCCASIONAL' | 'HEAVY'; language: string; memoryReliability: 'HIGH' | 'LOW'; name: string; properties: object; responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK' | 'BARGE_IN'; speechClarity: 'CLEAR' | 'VAGUE' | 'RAMBLING'; speechPace: 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'; understoodLanguages: string[]; updatedAt: string; backstoryPrompt?: string; description?: string; displayName?: string; secondaryLanguage?: 'EN'; }; processingStatus: string; queuePosition: number; runPlan: { id: string; name: string; variables: object; }; scenario: { id: string; description?: string; }; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }; }",
+      "{ data: { agentEndpoint: { id: string; name: string; phoneNumber: string; type: string; }; backgroundNoise: { backgroundNoise: string; backgroundNoiseVolume: number; source: 'ENVIRONMENT' | 'PERSONA'; }; createdAt: string; enrichment: { outcome: 'NOT_REQUESTED' | 'WAITING' | 'MERGED' | 'TIMED_OUT' | 'SKIPPED' | 'UNKNOWN'; requested: boolean; metricsNotCollected?: number; metricsScoredOnSimulationInstead?: number; waitEndedAt?: string; waitStartedAt?: string; }; failureOwner: 'ROARK' | 'AGENT'; invalidation: { invalidatedAt: string; reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED' | 'REQUIRED_STAGE_INCOMPLETE' | 'CALLER_NEVER_TOOK_OVER' | 'AGENT_NEVER_SPOKE'; detail?: string; }; persona: { id: string; accent: string; age: 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY'; backgroundNoise: string; baseEmotion: string; confirmationStyle: 'EXPLICIT' | 'VAGUE'; createdAt: string; gender: 'MALE' | 'FEMALE'; hasDisfluencies: boolean; idleMessageMaxSpokenCount: number; idleMessageResetCountOnUserSpeechEnabled: boolean; idleMessages: string[]; idleTimeoutSeconds: number; intentClarity: 'CLEAR' | 'INDIRECT' | 'VAGUE'; interruption: 'OFF' | 'BACKCHANNEL' | 'OCCASIONAL' | 'HEAVY'; language: string; memoryReliability: 'HIGH' | 'LOW'; name: string; properties: object; responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK' | 'BARGE_IN'; speechClarity: 'CLEAR' | 'VAGUE' | 'RAMBLING'; speechPace: 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'; understoodLanguages: string[]; updatedAt: string; backstoryPrompt?: string; description?: string; displayName?: string; secondaryLanguage?: 'EN'; }; processingStatus: string; queuePosition: number; runPlan: { id: string; name: string; variables: object; }; scenario: { id: string; description?: string; }; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }; }",
     markdown:
-      "## getById\n\n`client.simulationJob.getByID(jobId: string): { data: object; }`\n\n**get** `/v1/simulation/job/{jobId}`\n\nGet a individual simulation run directly by its ID. This is generally part of a larger simulation run plan job.\n\n### Parameters\n\n- `jobId: string`\n\n### Returns\n\n- `{ data: { agentEndpoint: { id: string; name: string; phoneNumber: string; type: string; }; createdAt: string; enrichment: { outcome: 'NOT_REQUESTED' | 'WAITING' | 'MERGED' | 'TIMED_OUT' | 'SKIPPED' | 'UNKNOWN'; requested: boolean; metricsNotCollected?: number; metricsScoredOnSimulationInstead?: number; waitEndedAt?: string; waitStartedAt?: string; }; failureOwner: 'ROARK' | 'AGENT'; invalidation: { invalidatedAt: string; reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED' | 'REQUIRED_STAGE_INCOMPLETE' | 'CALLER_NEVER_TOOK_OVER' | 'AGENT_NEVER_SPOKE'; detail?: string; }; persona: { id: string; accent: string; age: 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY'; backgroundNoise: string; baseEmotion: string; confirmationStyle: 'EXPLICIT' | 'VAGUE'; createdAt: string; gender: 'MALE' | 'FEMALE'; hasDisfluencies: boolean; idleMessageMaxSpokenCount: number; idleMessageResetCountOnUserSpeechEnabled: boolean; idleMessages: string[]; idleTimeoutSeconds: number; intentClarity: 'CLEAR' | 'INDIRECT' | 'VAGUE'; interruption: 'OFF' | 'BACKCHANNEL' | 'OCCASIONAL' | 'HEAVY'; language: string; memoryReliability: 'HIGH' | 'LOW'; name: string; properties: object; responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK' | 'BARGE_IN'; speechClarity: 'CLEAR' | 'VAGUE' | 'RAMBLING'; speechPace: 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'; understoodLanguages: string[]; updatedAt: string; backstoryPrompt?: string; description?: string; displayName?: string; secondaryLanguage?: 'EN'; }; processingStatus: string; queuePosition: number; runPlan: { id: string; name: string; variables: object; }; scenario: { id: string; description?: string; }; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }; }`\n\n  - `data: { agentEndpoint: { id: string; name: string; phoneNumber: string; type: string; }; createdAt: string; enrichment: { outcome: 'NOT_REQUESTED' | 'WAITING' | 'MERGED' | 'TIMED_OUT' | 'SKIPPED' | 'UNKNOWN'; requested: boolean; metricsNotCollected?: number; metricsScoredOnSimulationInstead?: number; waitEndedAt?: string; waitStartedAt?: string; }; failureOwner: 'ROARK' | 'AGENT'; invalidation: { invalidatedAt: string; reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED' | 'REQUIRED_STAGE_INCOMPLETE' | 'CALLER_NEVER_TOOK_OVER' | 'AGENT_NEVER_SPOKE'; detail?: string; }; persona: { id: string; accent: string; age: 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY'; backgroundNoise: string; baseEmotion: string; confirmationStyle: 'EXPLICIT' | 'VAGUE'; createdAt: string; gender: 'MALE' | 'FEMALE'; hasDisfluencies: boolean; idleMessageMaxSpokenCount: number; idleMessageResetCountOnUserSpeechEnabled: boolean; idleMessages: string[]; idleTimeoutSeconds: number; intentClarity: 'CLEAR' | 'INDIRECT' | 'VAGUE'; interruption: 'OFF' | 'BACKCHANNEL' | 'OCCASIONAL' | 'HEAVY'; language: string; memoryReliability: 'HIGH' | 'LOW'; name: string; properties: object; responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK' | 'BARGE_IN'; speechClarity: 'CLEAR' | 'VAGUE' | 'RAMBLING'; speechPace: 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'; understoodLanguages: string[]; updatedAt: string; backstoryPrompt?: string; description?: string; displayName?: string; secondaryLanguage?: 'EN'; }; processingStatus: string; queuePosition: number; runPlan: { id: string; name: string; variables: object; }; scenario: { id: string; description?: string; }; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }`\n\n### Example\n\n```typescript\nimport Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark();\n\nconst response = await client.simulationJob.getByID('7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f');\n\nconsole.log(response);\n```",
+      "## getById\n\n`client.simulationJob.getByID(jobId: string): { data: object; }`\n\n**get** `/v1/simulation/job/{jobId}`\n\nGet a individual simulation run directly by its ID. This is generally part of a larger simulation run plan job.\n\n### Parameters\n\n- `jobId: string`\n\n### Returns\n\n- `{ data: { agentEndpoint: { id: string; name: string; phoneNumber: string; type: string; }; backgroundNoise: { backgroundNoise: string; backgroundNoiseVolume: number; source: 'ENVIRONMENT' | 'PERSONA'; }; createdAt: string; enrichment: { outcome: 'NOT_REQUESTED' | 'WAITING' | 'MERGED' | 'TIMED_OUT' | 'SKIPPED' | 'UNKNOWN'; requested: boolean; metricsNotCollected?: number; metricsScoredOnSimulationInstead?: number; waitEndedAt?: string; waitStartedAt?: string; }; failureOwner: 'ROARK' | 'AGENT'; invalidation: { invalidatedAt: string; reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED' | 'REQUIRED_STAGE_INCOMPLETE' | 'CALLER_NEVER_TOOK_OVER' | 'AGENT_NEVER_SPOKE'; detail?: string; }; persona: { id: string; accent: string; age: 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY'; backgroundNoise: string; baseEmotion: string; confirmationStyle: 'EXPLICIT' | 'VAGUE'; createdAt: string; gender: 'MALE' | 'FEMALE'; hasDisfluencies: boolean; idleMessageMaxSpokenCount: number; idleMessageResetCountOnUserSpeechEnabled: boolean; idleMessages: string[]; idleTimeoutSeconds: number; intentClarity: 'CLEAR' | 'INDIRECT' | 'VAGUE'; interruption: 'OFF' | 'BACKCHANNEL' | 'OCCASIONAL' | 'HEAVY'; language: string; memoryReliability: 'HIGH' | 'LOW'; name: string; properties: object; responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK' | 'BARGE_IN'; speechClarity: 'CLEAR' | 'VAGUE' | 'RAMBLING'; speechPace: 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'; understoodLanguages: string[]; updatedAt: string; backstoryPrompt?: string; description?: string; displayName?: string; secondaryLanguage?: 'EN'; }; processingStatus: string; queuePosition: number; runPlan: { id: string; name: string; variables: object; }; scenario: { id: string; description?: string; }; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }; }`\n\n  - `data: { agentEndpoint: { id: string; name: string; phoneNumber: string; type: string; }; backgroundNoise: { backgroundNoise: string; backgroundNoiseVolume: number; source: 'ENVIRONMENT' | 'PERSONA'; }; createdAt: string; enrichment: { outcome: 'NOT_REQUESTED' | 'WAITING' | 'MERGED' | 'TIMED_OUT' | 'SKIPPED' | 'UNKNOWN'; requested: boolean; metricsNotCollected?: number; metricsScoredOnSimulationInstead?: number; waitEndedAt?: string; waitStartedAt?: string; }; failureOwner: 'ROARK' | 'AGENT'; invalidation: { invalidatedAt: string; reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED' | 'REQUIRED_STAGE_INCOMPLETE' | 'CALLER_NEVER_TOOK_OVER' | 'AGENT_NEVER_SPOKE'; detail?: string; }; persona: { id: string; accent: string; age: 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY'; backgroundNoise: string; baseEmotion: string; confirmationStyle: 'EXPLICIT' | 'VAGUE'; createdAt: string; gender: 'MALE' | 'FEMALE'; hasDisfluencies: boolean; idleMessageMaxSpokenCount: number; idleMessageResetCountOnUserSpeechEnabled: boolean; idleMessages: string[]; idleTimeoutSeconds: number; intentClarity: 'CLEAR' | 'INDIRECT' | 'VAGUE'; interruption: 'OFF' | 'BACKCHANNEL' | 'OCCASIONAL' | 'HEAVY'; language: string; memoryReliability: 'HIGH' | 'LOW'; name: string; properties: object; responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK' | 'BARGE_IN'; speechClarity: 'CLEAR' | 'VAGUE' | 'RAMBLING'; speechPace: 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'; understoodLanguages: string[]; updatedAt: string; backstoryPrompt?: string; description?: string; displayName?: string; secondaryLanguage?: 'EN'; }; processingStatus: string; queuePosition: number; runPlan: { id: string; name: string; variables: object; }; scenario: { id: string; description?: string; }; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }`\n\n### Example\n\n```typescript\nimport Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark();\n\nconst response = await client.simulationJob.getByID('7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f');\n\nconsole.log(response);\n```",
     perLanguage: {
       typescript: {
         method: 'client.simulationJob.getByID',
@@ -1455,9 +1455,9 @@ const EMBEDDED_METHODS: MethodEntry[] = [
     qualified: 'client.simulationRunPlanJob.getByID',
     params: ['jobId: string;'],
     response:
-      '{ data: { createdAt: string; simulationJobs: { agentEndpoint: object; createdAt: string; invalidation: object; persona: object; processingStatus: string; scenario: object; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }[]; simulationRunPlanId: string; simulationRunPlanJobId: string; status: string; endedAt?: string; startedAt?: string; sweepAttribution?: { caveats: string[]; checks: object[]; falseDiscoveryRate: number; foundUnattributedFailureRate: number; minArmCalls: number; minimumDetectableGap: number; testableValueCount: number; testedComparisonCount: number; values: object[]; }; verdict?: { checks: object[]; failures: object[]; passed: boolean; score: number; }; }; }',
+      '{ data: { createdAt: string; simulationJobs: { agentEndpoint: object; backgroundNoise: object; createdAt: string; invalidation: object; persona: object; processingStatus: string; scenario: object; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }[]; simulationRunPlanId: string; simulationRunPlanJobId: string; status: string; endedAt?: string; startedAt?: string; sweepAttribution?: { caveats: string[]; checks: object[]; falseDiscoveryRate: number; foundUnattributedFailureRate: number; minArmCalls: number; minimumDetectableGap: number; testableValueCount: number; testedComparisonCount: number; values: object[]; }; verdict?: { checks: object[]; failures: object[]; passed: boolean; score: number; }; }; }',
     markdown:
-      "## getById\n\n`client.simulationRunPlanJob.getByID(jobId: string): { data: object; }`\n\n**get** `/v1/simulation/plan/job/{jobId}`\n\nRetrieve details of a simulation plan job including all associated simulation jobs (calls)\n\n### Parameters\n\n- `jobId: string`\n\n### Returns\n\n- `{ data: { createdAt: string; simulationJobs: { agentEndpoint: object; createdAt: string; invalidation: object; persona: object; processingStatus: string; scenario: object; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }[]; simulationRunPlanId: string; simulationRunPlanJobId: string; status: string; endedAt?: string; startedAt?: string; sweepAttribution?: { caveats: string[]; checks: object[]; falseDiscoveryRate: number; foundUnattributedFailureRate: number; minArmCalls: number; minimumDetectableGap: number; testableValueCount: number; testedComparisonCount: number; values: object[]; }; verdict?: { checks: object[]; failures: object[]; passed: boolean; score: number; }; }; }`\n\n  - `data: { createdAt: string; simulationJobs: { agentEndpoint: { id: string; name: string; phoneNumber: string; type: string; }; createdAt: string; invalidation: { invalidatedAt: string; reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED' | 'REQUIRED_STAGE_INCOMPLETE' | 'CALLER_NEVER_TOOK_OVER' | 'AGENT_NEVER_SPOKE'; detail?: string; }; persona: { id: string; accent: string; age: 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY'; backgroundNoise: string; baseEmotion: string; confirmationStyle: 'EXPLICIT' | 'VAGUE'; createdAt: string; gender: 'MALE' | 'FEMALE'; hasDisfluencies: boolean; idleMessageMaxSpokenCount: number; idleMessageResetCountOnUserSpeechEnabled: boolean; idleMessages: string[]; idleTimeoutSeconds: number; intentClarity: 'CLEAR' | 'INDIRECT' | 'VAGUE'; interruption: 'OFF' | 'BACKCHANNEL' | 'OCCASIONAL' | 'HEAVY'; language: string; memoryReliability: 'HIGH' | 'LOW'; name: string; properties: object; responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK' | 'BARGE_IN'; speechClarity: 'CLEAR' | 'VAGUE' | 'RAMBLING'; speechPace: 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'; understoodLanguages: string[]; updatedAt: string; backstoryPrompt?: string; description?: string; displayName?: string; secondaryLanguage?: 'EN'; }; processingStatus: string; scenario: { id: string; description?: string; }; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }[]; simulationRunPlanId: string; simulationRunPlanJobId: string; status: string; endedAt?: string; startedAt?: string; sweepAttribution?: { caveats: string[]; checks: { attribution: 'PROPERTY_ATTRIBUTABLE' | 'FOUND_UNATTRIBUTED' | 'WITHIN_NOISE'; evaluated: number; failed: number; failureRate: number; metricDefinitionId: string; metricName: string; worseValues: object[]; }[]; falseDiscoveryRate: number; foundUnattributedFailureRate: number; minArmCalls: number; minimumDetectableGap: number; testableValueCount: number; testedComparisonCount: number; values: { attempted: number; counted: number; isBaseline: boolean; label: string; score: number; testable: boolean; value: string; }[]; }; verdict?: { checks: { evaluatedSims: number; inherited: boolean; metricDefinitionId: string; minPassRate: number; passRate: number; passed: boolean; passedSims: number; metricName?: string; }[]; failures: { status: string; type: 'RUN_NOT_COMPLETED'; } | { evaluatedCalls: number; expectedCalls: number; type: 'INCOMPLETE_COVERAGE'; } | { metricDefinitionId: string; type: 'METRIC_NOT_EVALUATED'; metricName?: string; } | { inherited: boolean; metricDefinitionId: string; minPassRate: number; passRate: number; type: 'METRIC_BELOW_MIN_PASS_RATE'; metricName?: string; }[]; passed: boolean; score: number; }; }`\n\n### Example\n\n```typescript\nimport Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark();\n\nconst response = await client.simulationRunPlanJob.getByID('7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f');\n\nconsole.log(response);\n```",
+      "## getById\n\n`client.simulationRunPlanJob.getByID(jobId: string): { data: object; }`\n\n**get** `/v1/simulation/plan/job/{jobId}`\n\nRetrieve details of a simulation plan job including all associated simulation jobs (calls)\n\n### Parameters\n\n- `jobId: string`\n\n### Returns\n\n- `{ data: { createdAt: string; simulationJobs: { agentEndpoint: object; backgroundNoise: object; createdAt: string; invalidation: object; persona: object; processingStatus: string; scenario: object; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }[]; simulationRunPlanId: string; simulationRunPlanJobId: string; status: string; endedAt?: string; startedAt?: string; sweepAttribution?: { caveats: string[]; checks: object[]; falseDiscoveryRate: number; foundUnattributedFailureRate: number; minArmCalls: number; minimumDetectableGap: number; testableValueCount: number; testedComparisonCount: number; values: object[]; }; verdict?: { checks: object[]; failures: object[]; passed: boolean; score: number; }; }; }`\n\n  - `data: { createdAt: string; simulationJobs: { agentEndpoint: { id: string; name: string; phoneNumber: string; type: string; }; backgroundNoise: { backgroundNoise: string; backgroundNoiseVolume: number; source: 'ENVIRONMENT' | 'PERSONA'; }; createdAt: string; invalidation: { invalidatedAt: string; reason: 'SCRIPT_DIVERGED' | 'REQUIRED_STEP_NOT_REACHED' | 'REQUIRED_STAGE_INCOMPLETE' | 'CALLER_NEVER_TOOK_OVER' | 'AGENT_NEVER_SPOKE'; detail?: string; }; persona: { id: string; accent: string; age: 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY'; backgroundNoise: string; baseEmotion: string; confirmationStyle: 'EXPLICIT' | 'VAGUE'; createdAt: string; gender: 'MALE' | 'FEMALE'; hasDisfluencies: boolean; idleMessageMaxSpokenCount: number; idleMessageResetCountOnUserSpeechEnabled: boolean; idleMessages: string[]; idleTimeoutSeconds: number; intentClarity: 'CLEAR' | 'INDIRECT' | 'VAGUE'; interruption: 'OFF' | 'BACKCHANNEL' | 'OCCASIONAL' | 'HEAVY'; language: string; memoryReliability: 'HIGH' | 'LOW'; name: string; properties: object; responseTiming: 'RELAXED' | 'NORMAL' | 'QUICK' | 'BARGE_IN'; speechClarity: 'CLEAR' | 'VAGUE' | 'RAMBLING'; speechPace: 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST'; understoodLanguages: string[]; updatedAt: string; backstoryPrompt?: string; description?: string; displayName?: string; secondaryLanguage?: 'EN'; }; processingStatus: string; scenario: { id: string; description?: string; }; simulationJobId: string; status: string; callId?: string; completedAt?: string; roarkPhoneNumber?: string; startedAt?: string; }[]; simulationRunPlanId: string; simulationRunPlanJobId: string; status: string; endedAt?: string; startedAt?: string; sweepAttribution?: { caveats: string[]; checks: { attribution: 'PROPERTY_ATTRIBUTABLE' | 'FOUND_UNATTRIBUTED' | 'WITHIN_NOISE'; evaluated: number; failed: number; failureRate: number; metricDefinitionId: string; metricName: string; worseValues: object[]; }[]; falseDiscoveryRate: number; foundUnattributedFailureRate: number; minArmCalls: number; minimumDetectableGap: number; testableValueCount: number; testedComparisonCount: number; values: { attempted: number; counted: number; isBaseline: boolean; label: string; score: number; testable: boolean; value: string; }[]; }; verdict?: { checks: { evaluatedSims: number; inherited: boolean; metricDefinitionId: string; minPassRate: number; passRate: number; passed: boolean; passedSims: number; metricName?: string; }[]; failures: { status: string; type: 'RUN_NOT_COMPLETED'; } | { evaluatedCalls: number; expectedCalls: number; type: 'INCOMPLETE_COVERAGE'; } | { metricDefinitionId: string; type: 'METRIC_NOT_EVALUATED'; metricName?: string; } | { inherited: boolean; metricDefinitionId: string; minPassRate: number; passRate: number; type: 'METRIC_BELOW_MIN_PASS_RATE'; metricName?: string; }[]; passed: boolean; score: number; }; }`\n\n### Example\n\n```typescript\nimport Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark();\n\nconst response = await client.simulationRunPlanJob.getByID('7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f');\n\nconsole.log(response);\n```",
     perLanguage: {
       typescript: {
         method: 'client.simulationRunPlanJob.getByID',

package/src/oauth.ts

@@ -9,8 +9,10 @@
 // rotated by the client's refresh token), so it is forwarded to customer-api as
 // the SDK bearer unchanged: customer-api validates it on every call.
 
+import { createHash } from 'node:crypto';
 import { IncomingMessage } from 'node:http';
 import { ClientOptions } from '@roarkanalytics/sdk';
+import { readEnv } from './util';
 
 export type OAuthConfig = {
   /** Authorization server issuer, e.g. https://mcp-oauth.api.roark.ai */
@@ -121,7 +123,7 @@ export const requireBearer = (
   req: IncomingMessage,
   config: OAuthConfig,
   connector: Connector = ORIGIN_CONNECTOR,
-): Partial<ClientOptions> => {
+): Partial<ClientOptions> & { bearerToken: string } => {
   const token = extractBearer(req);
   if (!token) {
     throw new UnauthorizedError('Missing bearer token', bearerChallenge(config, connector));
@@ -129,9 +131,176 @@ export const requireBearer = (
   // Assigned rather than conditionally spread: a spread of `cond && { project }` is not checked
   // against `ClientOptions`, so on an SDK without the option the pin would compile and then
   // silently vanish. This way the dependency is enforced by the build.
-  const options: Partial<ClientOptions> = { bearerToken: token };
+  const options: Partial<ClientOptions> & { bearerToken: string } = { bearerToken: token };
   if (connector.kind === 'project') {
     options.project = connector.projectId;
   }
   return options;
 };
+
+/**
+ * What customer-api says about a bearer: `unknown` means it could not be asked, not that the
+ * token is fine.
+ */
+export type BearerVerdict = 'valid' | 'invalid' | 'unknown';
+
+/** The SDK's own default, for when neither an option nor the environment names one. */
+export const DEFAULT_API_BASE_URL = 'https://api.roark.ai';
+
+/**
+ * The base URL the SDK will actually call, resolved exactly the way the SDK resolves it:
+ * explicit option, then `ROARK_BASE_URL`, then the default.
+ *
+ * This has to agree with the SDK or the liveness check asks the wrong host. `launchStreamableHTTPServer`
+ * passes no `clientOptions` at all, so for the deployed server the answer always comes from the
+ * environment: a hardcoded prod default would send every check to prod while data calls went to
+ * whatever `ROARK_BASE_URL` names. On any stage but prod that turns a valid token into a 401 from
+ * a server it was never issued for, and this file would then refuse every request - a dead
+ * connector, which is strictly worse than the bug it is here to fix.
+ */
+export const resolveApiBaseUrl = (clientOptions: Pick<ClientOptions, 'baseURL'> = {}): string =>
+  clientOptions.baseURL ?? readEnv('ROARK_BASE_URL') ?? DEFAULT_API_BASE_URL;
+
+/**
+ * How long a verdict is reused. `newServer` runs per POST, not per session, so an uncached check
+ * would add a round trip to every single MCP request. The window is what a revoked token buys:
+ * it can still complete a handshake and read the tool list for up to this long. It cannot read
+ * anything, because every data path carries the same token to customer-api and is refused there
+ * immediately.
+ */
+const BEARER_CACHE_TTL_MS = 60_000;
+
+/**
+ * An unreachable customer-api is handled by the catch below, but a customer-api that accepts the
+ * connection and then never answers is not: without a deadline every MCP request would hang on
+ * it, which is worse than the failure this check exists to report. A hang becomes `unknown` like
+ * any other transport failure.
+ */
+const BEARER_CHECK_TIMEOUT_MS = 3_000;
+
+/**
+ * Bounded so that spraying invented tokens cannot grow the process's memory. Keys are hashes,
+ * not the tokens themselves: these are live credentials and there is no reason to keep a second
+ * copy of them in a long-lived map.
+ */
+const BEARER_CACHE_MAX = 1_000;
+
+const bearerVerdicts = new Map<string, { verdict: 'valid' | 'invalid'; expiresAt: number }>();
+
+/**
+ * Checks already in flight, so concurrent requests bearing the same uncached token make one call
+ * rather than one each. That is the common shape right after a verdict expires, and whenever a
+ * client opens several requests at once.
+ */
+const inFlightChecks = new Map<string, Promise<BearerVerdict>>();
+
+/** Test seam. */
+export const clearBearerVerdictCache = (): void => {
+  bearerVerdicts.clear();
+  inFlightChecks.clear();
+};
+
+const hashToken = (token: string): string => createHash('sha256').update(token).digest('hex');
+
+const rememberVerdict = (key: string, verdict: 'valid' | 'invalid', expiresAt: number): void => {
+  // Evict the oldest entry rather than clearing the map. A `clear()` would let anyone spraying
+  // invented tokens flush every valid verdict too, making legitimate callers pay a round trip
+  // each and handing customer-api the extra work. Map iterates in insertion order, so the first
+  // key is the oldest.
+  if (bearerVerdicts.size >= BEARER_CACHE_MAX) {
+    const oldest = bearerVerdicts.keys().next();
+    if (!oldest.done) bearerVerdicts.delete(oldest.value);
+  }
+  bearerVerdicts.set(key, { verdict, expiresAt });
+};
+
+export interface VerifyBearerDeps {
+  /** customer-api base URL. Use {@link resolveApiBaseUrl} rather than passing a literal. */
+  baseURL: string;
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+  ttlMs?: number;
+  timeoutMs?: number;
+}
+
+/**
+ * Asks customer-api whether a bearer is still live, via the `/v1/me` endpoint it already exposes
+ * for exactly this ("who is this credential"), and caches the answer briefly.
+ *
+ * Only a 401 counts as invalid. A 403 means the token authenticated and then failed a permission
+ * check, which is a live token; treating it as invalid would tell a client to re-authorize when
+ * re-authorizing cannot help. Anything else - a 5xx, a timeout, a DNS failure - is `unknown`.
+ */
+export const verifyBearer = async (token: string, deps: VerifyBearerDeps): Promise<BearerVerdict> => {
+  const {
+    baseURL,
+    fetchImpl = fetch,
+    now = Date.now,
+    ttlMs = BEARER_CACHE_TTL_MS,
+    timeoutMs = BEARER_CHECK_TIMEOUT_MS,
+  } = deps;
+  const key = hashToken(token);
+
+  const cached = bearerVerdicts.get(key);
+  if (cached && cached.expiresAt > now()) return cached.verdict;
+
+  const alreadyRunning = inFlightChecks.get(key);
+  if (alreadyRunning) return alreadyRunning;
+
+  const check = (async (): Promise<BearerVerdict> => {
+    let response: Response;
+    try {
+      response = await fetchImpl(`${stripSlash(baseURL)}/v1/me`, {
+        method: 'GET',
+        headers: { Authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch {
+      return 'unknown';
+    }
+
+    const verdict: BearerVerdict =
+      response.status === 401 ? 'invalid'
+      : response.ok ? 'valid'
+      : 'unknown';
+    // An `unknown` is never cached: a blip would otherwise pin the answer for the whole TTL.
+    if (verdict !== 'unknown') rememberVerdict(key, verdict, now() + ttlMs);
+    return verdict;
+  })();
+
+  inFlightChecks.set(key, check);
+  try {
+    return await check;
+  } finally {
+    inFlightChecks.delete(key);
+  }
+};
+
+/**
+ * Rejects a bearer customer-api has already disowned, with the 401 + WWW-Authenticate that tells
+ * an MCP client to re-run the OAuth flow.
+ *
+ * Without this the resource server only checked that a token was PRESENT. A revoked, expired or
+ * entirely invented token completed `initialize` and `tools/list`, and the caller learned nothing
+ * until a tool call failed with an opaque 401 in its result text. No data was reachable - every
+ * data path revalidates at customer-api - but a client that never sees a 401 from the resource
+ * server has no reason to refresh, which for a 24h token means a connector that looks connected
+ * and silently cannot work.
+ *
+ * `unknown` is allowed through deliberately. Failing closed would turn a customer-api blip into a
+ * dead connector for everyone, and it would buy no confidentiality: the token still has to pass
+ * customer-api on the very next call that touches data.
+ */
+export const requireLiveBearer = async (
+  token: string,
+  config: OAuthConfig,
+  connector: Connector,
+  deps: VerifyBearerDeps,
+): Promise<void> => {
+  const verdict = await verifyBearer(token, deps);
+  if (verdict !== 'invalid') return;
+  throw new UnauthorizedError(
+    'The access token is expired or has been revoked',
+    bearerChallenge(config, connector, 'invalid_token', 'The access token is expired or has been revoked'),
+  );
+};

package/src/server.ts

@@ -28,7 +28,7 @@ export const newMcpServer = async ({
   new McpServer(
     {
       name: 'roarkanalytics_sdk_api',
-      version: '4.12.1', // x-release-please-version
+      version: '4.13.0', // x-release-please-version
     },
     {
       instructions: await getInstructions({ stainlessApiKey, customInstructionsPath }),