feat(sdk,core): add TriggerClient for per-instance SDK configuration

`new TriggerClient({...})` exposes the management surface (tasks, runs,
schedules, envvars, batch, queues, deployments, prompts, auth) as an
explicit instance with its own auth, preview branch, and baseURL.
Multiple clients can coexist in one process without mutating shared
global state.

Identity fields (`accessToken`, `secretKey`, `previewBranch`) and
task-runtime reads (`parentRunId`, `lockToVersion`, `taskContext.ctx`)
are scope-only by default, so a call from inside a task does not leak
parent context into a trigger that hits a different project. `baseURL`
still falls back to `TRIGGER_API_URL` so local-dev and CI overrides
apply without forcing every consumer to pass it explicitly.

Two correctness fixes folded in:
- `configure()` actually overrides on second call (was silent no-op).
- `auth.withAuth()` is concurrency-safe (no longer mutates the global
  config, uses an AsyncLocalStorage scope instead).

Ships with a `references/multi-client` reference project containing an
echo task, a fan-out task, and two external scripts that smoke-test the
isolation guarantees.

Author: ericallam

.changeset/trigger-client.md

@@ -0,0 +1,23 @@
+---
+"@trigger.dev/sdk": patch
+"@trigger.dev/core": patch
+---
+
+Run multiple SDK clients side-by-side. `new TriggerClient({...})` exposes the management API as an explicit instance with its own auth, preview branch, and baseURL, so a single process can trigger tasks across different projects, environments, or preview branches without mutating shared global state.
+
+```ts
+import { TriggerClient } from "@trigger.dev/sdk";
+
+const prod = new TriggerClient({ accessToken: process.env.TRIGGER_PROD_KEY });
+const preview = new TriggerClient({
+  accessToken: process.env.TRIGGER_PREVIEW_KEY,
+  previewBranch: "signup-flow",
+});
+
+await prod.tasks.trigger("send-email", payload);
+await preview.runs.list({ status: ["COMPLETED"] });
+```
+
+Instance calls are isolated by default: identity fields (auth, branch) and task-runtime reads (`parentRunId`, `lockToVersion`, `taskContext.ctx`) are scope-only, so a call from inside a task does not leak parent context into a trigger that hits a different project. `baseURL` still falls back to `TRIGGER_API_URL` so local-dev and CI overrides apply without forcing every consumer to pass it explicitly.
+
+Also fixes `configure()` silently no-op-ing on the second call, and makes `auth.withAuth()` concurrency-safe (parallel calls with different configs no longer stomp each other).

packages/core/src/v3/apiClientManager/index.ts

@@ -1,6 +1,7 @@
 import { ApiClient } from "../apiClient/index.js";
 import { getGlobal, registerGlobal, unregisterGlobal } from "../utils/globals.js";
 import { getEnvVar } from "../utils/getEnv.js";
+import { sdkScope } from "../sdkScope/index.js";
 import { ApiClientConfiguration } from "./types.js";
 
 const API_NAME = "api-client";
@@ -30,11 +31,27 @@ export class APIClientManagerAPI {
   }
 
   get baseURL(): string | undefined {
+    // baseURL is plumbing (where the API lives), not identity. Scoped
+    // instances read their own config first but still fall back to the
+    // process-level TRIGGER_API_URL so local-dev / CI overrides don't
+    // require passing baseURL into every `new TriggerClient(...)`.
+    const scoped = sdkScope.getStore();
+    if (scoped) {
+      return (
+        scoped.apiClientConfig.baseURL ??
+        getEnvVar("TRIGGER_API_URL") ??
+        "https://api.trigger.dev"
+      );
+    }
     const config = this.#getConfig();
     return config?.baseURL ?? getEnvVar("TRIGGER_API_URL") ?? "https://api.trigger.dev";
   }
 
   get accessToken(): string | undefined {
+    const scoped = sdkScope.getStore();
+    if (scoped) {
+      return scoped.apiClientConfig.accessToken ?? scoped.apiClientConfig.secretKey;
+    }
     const config = this.#getConfig();
     return (
       config?.secretKey ??
@@ -45,6 +62,11 @@ export class APIClientManagerAPI {
   }
 
   get branchName(): string | undefined {
+    const scoped = sdkScope.getStore();
+    if (scoped) {
+      const value = scoped.apiClientConfig.previewBranch ?? undefined;
+      return value ? value : undefined;
+    }
     const config = this.#getConfig();
     const value =
       config?.previewBranch ??
@@ -59,8 +81,10 @@ export class APIClientManagerAPI {
       return undefined;
     }
 
-    const requestOptions = this.#getConfig()?.requestOptions;
-    const futureFlags = this.#getConfig()?.future;
+    const scoped = sdkScope.getStore();
+    const source = scoped?.apiClientConfig ?? this.#getConfig();
+    const requestOptions = source?.requestOptions;
+    const futureFlags = source?.future;
 
     return new ApiClient(this.baseURL, this.accessToken, this.branchName, requestOptions, futureFlags);
   }
@@ -74,8 +98,10 @@ export class APIClientManagerAPI {
     }
 
     const branchName = config?.previewBranch ?? this.branchName;
-    const requestOptions = config?.requestOptions ?? this.#getConfig()?.requestOptions;
-    const futureFlags = config?.future ?? this.#getConfig()?.future;
+    const scoped = sdkScope.getStore();
+    const source = scoped?.apiClientConfig ?? this.#getConfig();
+    const requestOptions = config?.requestOptions ?? source?.requestOptions;
+    const futureFlags = config?.future ?? source?.future;
 
     return new ApiClient(baseURL, accessToken, branchName, requestOptions, futureFlags);
   }
@@ -84,17 +110,12 @@ export class APIClientManagerAPI {
     config: ApiClientConfiguration,
     fn: R
   ): Promise<ReturnType<R>> {
-    const originalConfig = this.#getConfig();
-    const $config = { ...originalConfig, ...config };
-    registerGlobal(API_NAME, $config, true);
-
-    return fn().finally(() => {
-      registerGlobal(API_NAME, originalConfig, true);
-    });
+    const merged: ApiClientConfiguration = { ...this.#getConfig(), ...config };
+    return sdkScope.withScope({ apiClientConfig: merged, inheritContext: true }, fn);
   }
 
   public setGlobalAPIClientConfiguration(config: ApiClientConfiguration): boolean {
-    return registerGlobal(API_NAME, config);
+    return registerGlobal(API_NAME, config, true);
   }
 
   #getConfig(): ApiClientConfiguration | undefined {

packages/core/src/v3/index.ts

@@ -11,6 +11,7 @@ export * from "./runtime-api.js";
 export * from "./task-context-api.js";
 export * from "./trace-context-api.js";
 export * from "./apiClientManager-api.js";
+export * from "./sdkScope-api.js";
 export * from "./usage-api.js";
 export * from "./run-metadata-api.js";
 export * from "./wait-until-api.js";

packages/core/src/v3/sdkScope-api.ts

@@ -0,0 +1 @@
+export { sdkScope, type SdkScope } from "./sdkScope/index.js";

packages/core/src/v3/sdkScope/index.ts

@@ -0,0 +1,18 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { ApiClientConfiguration } from "../apiClientManager/types.js";
+
+export type SdkScope = {
+  apiClientConfig: ApiClientConfiguration;
+  inheritContext: boolean;
+};
+
+const storage = new AsyncLocalStorage<SdkScope>();
+
+export const sdkScope = {
+  getStore(): SdkScope | undefined {
+    return storage.getStore();
+  },
+  withScope<R>(scope: SdkScope, fn: () => R): R {
+    return storage.run(scope, fn);
+  },
+};

packages/core/src/v3/taskContext/index.ts

@@ -1,6 +1,7 @@
 import { Attributes } from "@opentelemetry/api";
 import { ServerBackgroundWorker, TaskRunContext } from "../schemas/index.js";
 import { SemanticInternalAttributes } from "../semanticInternalAttributes.js";
+import { sdkScope } from "../sdkScope/index.js";
 import { getGlobal, registerGlobal } from "../utils/globals.js";
 import { TaskContext } from "./types.js";
 
@@ -22,6 +23,7 @@ export class TaskContextAPI {
   }
 
   get isInsideTask(): boolean {
+    if (this.#isolatedFromContext()) return false;
     return this.#getTaskContext() !== undefined;
   }
 
@@ -30,17 +32,25 @@ export class TaskContextAPI {
   }
 
   get ctx(): TaskRunContext | undefined {
+    if (this.#isolatedFromContext()) return undefined;
     return this.#getTaskContext()?.ctx;
   }
 
   get worker(): ServerBackgroundWorker | undefined {
+    if (this.#isolatedFromContext()) return undefined;
     return this.#getTaskContext()?.worker;
   }
 
   get isWarmStart(): boolean | undefined {
+    if (this.#isolatedFromContext()) return undefined;
     return this.#getTaskContext()?.isWarmStart;
   }
 
+  #isolatedFromContext(): boolean {
+    const scope = sdkScope.getStore();
+    return !!scope && !scope.inheritContext;
+  }
+
   get attributes(): Attributes {
     if (this.ctx) {
       return {

packages/trigger-sdk/src/v3/index.ts

@@ -67,5 +67,6 @@ export * as queues from "./queues.js";
 export type { ImportEnvironmentVariablesParams } from "./envvars.js";
 
 export { configure, auth } from "./auth.js";
+export { TriggerClient, type TriggerClientConfig } from "./triggerClient.js";
 export * as prompts from "./prompts.js";
 export * as skills from "./skills.js";

packages/trigger-sdk/src/v3/shared.ts

@@ -22,6 +22,7 @@ import {
   RateLimitError,
   resourceCatalog,
   runtime,
+  sdkScope,
   SemanticInternalAttributes,
   stringifyIO,
   SubtaskUnwrapError,
@@ -129,6 +130,12 @@ export { SubtaskUnwrapError, TaskRunPromise };
 
 export type Context = TaskRunContext;
 
+function scopedEnvVar(name: string): string | undefined {
+  const scope = sdkScope.getStore();
+  if (scope && !scope.inheritContext) return undefined;
+  return getEnvVar(name);
+}
+
 export function queue(options: QueueOptions): Queue {
   resourceCatalog.registerQueueMetadata(options);
 
@@ -740,7 +747,7 @@ export async function batchTriggerById<TTask extends AnyTask>(
             machine: item.options?.machine,
             priority: item.options?.priority,
             region: item.options?.region,
-            lockToVersion: item.options?.version ?? getEnvVar("TRIGGER_VERSION"),
+            lockToVersion: item.options?.version ?? scopedEnvVar("TRIGGER_VERSION"),
             debounce: item.options?.debounce,
           },
         };
@@ -1256,7 +1263,7 @@ export async function batchTriggerTasks<TTasks extends readonly AnyTask[]>(
             machine: item.options?.machine,
             priority: item.options?.priority,
             region: item.options?.region,
-            lockToVersion: item.options?.version ?? getEnvVar("TRIGGER_VERSION"),
+            lockToVersion: item.options?.version ?? scopedEnvVar("TRIGGER_VERSION"),
             debounce: item.options?.debounce,
           },
         };
@@ -1920,7 +1927,7 @@ async function* transformBatchItemsStream<TTask extends AnyTask>(
         machine: item.options?.machine,
         priority: item.options?.priority,
         region: item.options?.region,
-        lockToVersion: item.options?.version ?? getEnvVar("TRIGGER_VERSION"),
+        lockToVersion: item.options?.version ?? scopedEnvVar("TRIGGER_VERSION"),
         debounce: item.options?.debounce,
       },
     };
@@ -2023,7 +2030,7 @@ async function* transformBatchByTaskItemsStream<TTasks extends readonly AnyTask[
         machine: item.options?.machine,
         priority: item.options?.priority,
         region: item.options?.region,
-        lockToVersion: item.options?.version ?? getEnvVar("TRIGGER_VERSION"),
+        lockToVersion: item.options?.version ?? scopedEnvVar("TRIGGER_VERSION"),
         debounce: item.options?.debounce,
       },
     };
@@ -2127,7 +2134,7 @@ async function* transformSingleTaskBatchItemsStream<TPayload>(
         machine: item.options?.machine,
         priority: item.options?.priority,
         region: item.options?.region,
-        lockToVersion: item.options?.version ?? getEnvVar("TRIGGER_VERSION"),
+        lockToVersion: item.options?.version ?? scopedEnvVar("TRIGGER_VERSION"),
         debounce: item.options?.debounce,
       },
     };
@@ -2236,7 +2243,7 @@ async function trigger_internal<TRunTypes extends AnyRunTypes>(
         machine: options?.machine,
         priority: options?.priority,
         region: options?.region,
-        lockToVersion: options?.version ?? getEnvVar("TRIGGER_VERSION"),
+        lockToVersion: options?.version ?? scopedEnvVar("TRIGGER_VERSION"),
         debounce: options?.debounce,
       },
     },
@@ -2322,7 +2329,7 @@ async function batchTrigger_internal<TRunTypes extends AnyRunTypes>(
             machine: item.options?.machine,
             priority: item.options?.priority,
             region: item.options?.region,
-            lockToVersion: item.options?.version ?? getEnvVar("TRIGGER_VERSION"),
+            lockToVersion: item.options?.version ?? scopedEnvVar("TRIGGER_VERSION"),
           },
         };
       })