feat(sdk): prefer short-lived run tokens with credential compatibility

Prefer short-lived run tokens for supported SDK operations inside tasks,
while preserving explicit credential precedence and environment-key
compatibility where needed.

- Resolve implicit credentials per request, HTTP retry, page and
streaming connection. Missing, malformed, expired or older narrow-scope
run tokens select compatibility credentials before the request.
Authentication failures never retry with a more privileged key.
- Use run tokens for environment/default queries. Project and
organization queries select compatibility credentials before sending the
request.
- Keep same-branch PREVIEW and DEVELOPMENT requests on run tokens.
Requests targeting another branch select compatibility credentials.
DEVELOPMENT's `default` sentinel targets the root dev environment.
STAGING and PRODUCTION ignore branch targeting for credential selection,
matching server authentication.
- Mint scoped public tokens server-side when using run tokens. Server
minting keeps its 30-day maximum, and longer requests fail rather than
falling back to root-key signing. Root-key local signing, including
scope-less tokens, is unchanged and can still sign longer lifetimes.
- AgentChat resolves implicit credentials for every connection,
including network reconnects and EOF resubscriptions, and for input
appends. Explicit credentials remain explicit.
- Send bounded SDK credential-selection metadata through request headers
only for implicit in-task selection. The server records internal
authentication telemetry; the SDK does not emit rollout counters through
customer OpenTelemetry providers. Explicit credentials and calls outside
tasks do not emit selection headers.

Mono-RevId: cb4c2727cf43e082dc58929b5e4fa10e1d565b75

Author: carderne

.changeset/short-lived-run-api-credentials.md

@@ -0,0 +1,8 @@
+---
+"@trigger.dev/core": patch
+"@trigger.dev/sdk": patch
+---
+
+Use short-lived run tokens for supported SDK operations inside deployed tasks when available, retaining environment-key compatibility for unsupported operations and missing or expired tokens. Explicit credentials still take precedence. Public-token helpers use server-side minting with run tokens rather than signing locally.
+
+Project and organization queries, and branch overrides targeting another PREVIEW or DEVELOPMENT environment, keep using compatibility credentials. Branch headers do not change credential selection in STAGING or PRODUCTION. Chat subscriptions reread implicit credentials for each connection.

packages/core/src/v3/apiClient/core.ts

@@ -2,6 +2,10 @@ import { z as z3 } from "zod/v3";
 import { z } from "zod/v4";
 import { fromZodError } from "zod-validation-error/v4";
 import type { RetryOptions } from "../schemas/index.js";
+import {
+  SDK_CREDENTIAL_OPERATION_HEADER,
+  SDK_CREDENTIAL_REASON_HEADER,
+} from "../sdkCredentialTelemetry.js";
 import { calculateNextRetryDelay } from "../utils/retries.js";
 import { ApiConnectionError, ApiError, ApiSchemaValidationError } from "./errors.js";
 
@@ -32,6 +36,8 @@ export const defaultRetryOptions = {
 
 export type ZodFetchOptions<TData = any> = {
   retry?: RetryOptions;
+  resolveAccessToken?: () => string;
+  resolveHeaders?: () => Record<string, string>;
   tracer?: TriggerTracer;
   name?: string;
   attributes?: Attributes;
@@ -254,8 +260,22 @@ async function _doZodFetchWithRetries<TResponseBodySchema extends AnyZodSchema>(
   attempt = 1
 ): Promise<ZodFetchResult<inferZodSchemaOutput<TResponseBodySchema>>> {
   try {
+    let attemptRequestInit = requestInit;
+    if (options?.resolveHeaders || options?.resolveAccessToken) {
+      const headers = new Headers(requestInit?.headers);
+      headers.delete(SDK_CREDENTIAL_OPERATION_HEADER);
+      headers.delete(SDK_CREDENTIAL_REASON_HEADER);
+      if (options.resolveHeaders) {
+        for (const [key, value] of Object.entries(options.resolveHeaders()))
+          headers.set(key, value);
+      } else if (options.resolveAccessToken) {
+        headers.set("Authorization", `Bearer ${options.resolveAccessToken()}`);
+      }
+      attemptRequestInit = { ...requestInit, headers };
+    }
+
     const response = await context.with(suppressTracing(context.active()), () =>
-      fetch(url, requestInitWithCache(requestInit))
+      fetch(url, requestInitWithCache(attemptRequestInit))
     );
 
     const responseHeaders = createResponseHeaders(response.headers);