@salesforce/agentic-common 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to `@salesforce/agentic-common` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.12.0] - 2026-06-22
+
+### Features
+- **agentic-common,harnesses**: route HTTPS_PROXY via injectable undici Dispatcher @W-23121596 ([#610](https://github.com/forcedotcom/agentic-dx/pull/610))
+
+### Docs
+- align SDK + agentic-common docs with current public surface (post-PR-#607) ([#608](https://github.com/forcedotcom/agentic-dx/pull/608))
+
+## [0.11.0] - 2026-06-19
+
+### Features
+- **BREAKING** Major refactor to Unify Connectivity via ModelConnectivityInfo @W-22782317 ([#607](https://github.com/forcedotcom/agentic-dx/pull/607))
+
+### Fixes
+- **harness-claude**: map SDKResultSuccess.is_error to ChatEvent.error ([#593](https://github.com/forcedotcom/agentic-dx/pull/593))
+
+### Chores
+- **deps-dev**: bump @vitest/eslint-plugin from 1.6.19 to 1.6.20 in the vitest group across 1 directory ([#601](https://github.com/forcedotcom/agentic-dx/pull/601))
+- **deps-dev**: bump eslint from 10.4.1 to 10.5.0 in the eslint group across 1 directory ([#600](https://github.com/forcedotcom/agentic-dx/pull/600))
+- **deps**: bump @salesforce/core from 8.31.0 to 8.31.1 ([#603](https://github.com/forcedotcom/agentic-dx/pull/603))
+- **deps-dev**: bump @types/node from 22.19.20 to 22.19.21 in the dev-dependencies group ([#599](https://github.com/forcedotcom/agentic-dx/pull/599))
+
 ## [0.10.0] - 2026-06-09
 
 ### Tests

package/README.md

@@ -1,8 +1,8 @@
 # @salesforce/agentic-common
 
 Shared primitives and common utilities for the Salesforce agentic DX packages. Provides a typed event bus, clock
-abstraction, ID generation, error utilities, log record shape, thin log-emit helpers, and a Salesforce org connection
-interface consumed by the other packages in this monorepo.
+abstraction, ID generation, error utilities, log record shape, thin log-emit helpers, a Salesforce org connection
+interface, and the `JSONWebToken` family used by the agent-SDK's connectivity resolvers.
 
 ## Quick Start
 
@@ -158,6 +158,30 @@ try {
 }
 ```
 
+### `resolveProxyDispatcher()` / `createProxyAwareFetch(dispatcher?)`
+
+Proxy-routing helpers for Node's `fetch`. `resolveProxyDispatcher()` returns an `undici.EnvHttpProxyAgent` built from
+`HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` env vars (or their lowercase forms — undici honors both casings), or
+`undefined` when none is set. `createProxyAwareFetch(dispatcher?)` returns a `fetch`-compatible function that routes
+outbound calls through the supplied dispatcher via `undici.fetch`; when `dispatcher` is `undefined`, it returns
+`globalThis.fetch` unchanged so the no-proxy path has zero overhead.
+
+Designed to be called from harness factories' `create()`; consumers normally don't call them directly. Both production
+harness factories (`MastraHarnessFactory`, `ClaudeHarnessFactory`) build a proxy-aware fetch via these helpers and
+thread it into every in-process HTTP call site (LLM gateway language-model builders + MCP remote transports). No
+`globalThis` mutation.
+
+`EnvHttpProxyAgent` captures `HTTPS_PROXY` and `HTTP_PROXY` at construction; `NO_PROXY` is re-evaluated per dispatch.
+Set `HTTPS_PROXY` / `HTTP_PROXY` BEFORE the first `create()` call so the dispatcher snapshot reflects the right values.
+
+```typescript
+import { createProxyAwareFetch, resolveProxyDispatcher } from '@salesforce/agentic-common';
+
+const dispatcher = resolveProxyDispatcher();
+const fetchFn = createProxyAwareFetch(dispatcher);
+await fetchFn('https://example.com/v1/things');
+```
+
 ### `UniqueIDGenerator` / `UUIDGenerator`
 
 Interface + default implementation for generating unique identifiers. Tests can inject deterministic implementations.
@@ -184,20 +208,25 @@ class EventBus<T> {
   on(callback: EventListener<T>): Unsubscribe;
   emit(event: T): void;
   forwardTo(target: EventBus<T>, enrich?: (event: T) => T): Unsubscribe;
+  forwardWhileSubscribed(target: EventBus<T>, enrich?: (event: T) => T): Unsubscribe;
+  onSubscriberPresenceChange(callback: SubscriberPresenceListener): Unsubscribe;
   dispose(): void;
 }
 
 type EventListener<T> = (event: T) => void;
+type SubscriberPresenceListener = (hasSubscribers: boolean) => void;
 type Unsubscribe = () => void;
 ```
 
-| Method                 | Description                                                                                         |
-| ---------------------- | --------------------------------------------------------------------------------------------------- |
-| `on(callback)`         | Subscribe. Returns an `Unsubscribe` function — no need to hold the callback reference for removal.  |
-| `emit(event)`          | Deliver to all listeners. Listener errors are caught and ignored so one bad listener can't cascade. |
-| `forwardTo(target, ?)` | Subscribe to this bus and re-emit every event onto `target`. Optional `enrich` transforms events.   |
-| `dispose()`            | Remove all listeners. Safe to call multiple times.                                                  |
-| `listenerCount`        | Current listener count (useful for leak-check assertions in tests).                                 |
+| Method                              | Description                                                                                                                                                                                                                                                                                                                                                 |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `on(callback)`                      | Subscribe. Returns an `Unsubscribe` function — no need to hold the callback reference for removal.                                                                                                                                                                                                                                                          |
+| `emit(event)`                       | Deliver to all listeners. Listener errors are caught and ignored so one bad listener can't cascade.                                                                                                                                                                                                                                                         |
+| `forwardTo(target, ?)`              | Subscribe to this bus and re-emit every event onto `target`. Optional `enrich` transforms events. Eager — the upstream subscription stays attached for the full lifetime of the link, even when `target` has zero listeners.                                                                                                                                |
+| `forwardWhileSubscribed(target, ?)` | Lazy peer of `forwardTo`. Only attaches the upstream subscription while `target.listenerCount > 0`; detaches when `target` loses its last listener. Composes naturally — chaining across multiple buses propagates "no listener anywhere downstream" all the way up the chain so an expensive producer can short-circuit on `this.listenerCount > 0` reads. |
+| `onSubscriberPresenceChange(cb)`    | Subscribe to listener-presence transitions. The callback fires `true` on 0 → 1 transitions and `false` on N → 0. Does NOT fire on intermediate listener add/remove. Returns an idempotent `Unsubscribe`. Used by `forwardWhileSubscribed`; also useful when an expensive producer wants to start/stop work based on whether anyone is listening at all.     |
+| `dispose()`                         | Remove all listeners. Fires a final `false` presence notification if there were active listeners. Safe to call multiple times.                                                                                                                                                                                                                              |
+| `listenerCount`                     | Current listener count (useful for leak-check assertions in tests, and for `forwardWhileSubscribed`-style "is anyone listening?" checks).                                                                                                                                                                                                                   |
 
 ### `LogRecord` / `LogBus`
 
@@ -224,6 +253,46 @@ class LogBus extends EventBus<LogRecord> {
 }
 ```
 
+### `JSONWebToken` / `FixedJSONWebToken` / `DynamicJSONWebToken`
+
+Auth primitive for Salesforce-fronted services (LLM gateway, MCP servers, future Apex). `FixedJSONWebToken` parses a
+literal JWT string and reports expiration with a 30-second buffer; `DynamicJSONWebToken` wraps a `FixedJSONWebToken` and
+auto-refreshes via the org's minting endpoint (default `/ide/auth`) when expired. Both implement the same `JSONWebToken`
+interface so consumers don't need to know which kind they hold.
+
+```typescript
+interface JSONWebToken<JWTHeaders, JWTPayload> {
+  getValue(): Promise<string>; // raw serialized JWT
+  getHeaders(): Promise<JWTHeaders>;
+  getPayload(): Promise<JWTPayload>;
+  getTenantKey(): Promise<string>; // from header `tnk`
+  getFeatureId(): string;
+  isExpired(): boolean;
+  onLog(callback: (record: LogRecord) => void): Unsubscribe;
+}
+
+// Resolves a fresh org connection from access token + instance URL, mints + validates the first JWT.
+function createJWT(options: {
+  accessToken: string;
+  instanceUrl: string;
+  mintingPath?: string; // default '/ide/auth'
+  featureId?: string; // default 'VibesService' (or LLMG_FEATURE_ID env var)
+}): Promise<JSONWebToken>;
+
+// Same fail-fast first-mint behavior, but uses an existing OrgConnection.
+function createJWTFromConnection(
+  orgConnection: OrgConnection,
+  options?: CreateJWTFromConnectionOptions, // { mintingPath?: string; featureId?: string }
+): Promise<JSONWebToken>;
+```
+
+`JWTOptions`, `CreateJWTFromConnectionOptions`, `RequiredJWTHeaders`, and `RequiredJWTPayload` are all exported types so
+consumers can name the parameter / generic-instantiation shapes without redeclaring them.
+
+JWT lifecycle log records flow through `onLog`. The token's auto-refresh emits `'Refreshing expired JWT'` (debug),
+`'JWT refreshed'` (info, with `durationMs`), and `'JWT refresh failed'` (error, with the wrapped exception) so operators
+have visibility without subscribing to a separate telemetry channel.
+
 ### `Retryer` / `BackoffRetryer` / `NoOpRetryer`
 
 Generic retry orchestration. Consumers depend on the `Retryer` interface and supply per-call decisions (which errors /
@@ -250,12 +319,30 @@ type RetryCallbacks<T> = {
   isRetryableError?: (err: unknown) => boolean;
   isRetryableResult?: (result: T) => boolean;
   getRetryAfterMs?: (result: T) => number | undefined;
-  onRetry?: (info: { attempt: number; delayMs: number; error?: unknown; result?: T }) => void;
-  onExhausted?: (info: { attempts: number; error?: unknown; result?: T; reason: 'attempts' | 'deadline' }) => void;
+  onRetry?: (info: RetryAttemptInfo<T>) => void;
+  onExhausted?: (info: RetryExhaustedInfo<T>) => void;
   drainResult?: (result: T) => Promise<void>;
 };
+
+type RetryAttemptInfo<T> = {
+  attempt: number; // 1-indexed attempt number that just failed
+  delayMs: number; // jittered or server-driven delay about to be waited
+  error?: unknown; // set if the attempt threw a retryable error
+  result?: T; // set if the attempt returned a retryable result
+};
+
+type RetryExhaustedInfo<T> = {
+  attempts: number; // total attempts made
+  error?: unknown;
+  result?: T;
+  reason: 'attempts' | 'deadline';
+};
 ```
 
+The fully-resolved defaults are exported as `DEFAULT_RETRY_OPTIONS`
+(`{ maxAttempts: 3, initialDelayMs: 100, maxDelayMs: 2000, maxRetryAfterMs: 60_000, backoffFactor: 2, maxTotalElapsedMs: Infinity }`)
+so consumers and tests can share one source of truth.
+
 Use `BackoffRetryer` in production:
 
 ```typescript
@@ -327,6 +414,20 @@ import { backfillCreatedAt, RealClock } from '@salesforce/agentic-common';
 const filled = backfillCreatedAt(messages, new RealClock());
 ```
 
+### `buildSummaryPrompt(transcript: string): string`
+
+Returns a third-person summarization-prompt string asking the model to compress the supplied transcript into a context
+summary. Used by both production harnesses (`@salesforce/sfdx-agent-harness-mastra` /
+`@salesforce/sfdx-agent-harness-claude`) inside their `compactThread` flows so the prompt wording stays uniform across
+implementations — a freshly-summarized thread reads the same regardless of which harness produced it.
+
+```typescript
+import { buildSummaryPrompt } from '@salesforce/agentic-common';
+
+const prompt = buildSummaryPrompt(transcriptText);
+// → "Summarize the following conversation into a concise context summary. ..."
+```
+
 ## Development
 
 See [DEVELOPING.md](../../DEVELOPING.md) for build-from-source setup, scripts, and monorepo commands.

package/dist/event-bus.d.ts

@@ -1,5 +1,6 @@
 export type EventListener<T> = (event: T) => void;
 export type Unsubscribe = () => void;
+export type SubscriberPresenceListener = (hasSubscribers: boolean) => void;
 /**
  * Minimal, typed, object-bound event bus. Carries a single event shape `T`.
  *
@@ -8,6 +9,7 @@ export type Unsubscribe = () => void;
  */
 export declare class EventBus<T> {
     private readonly listeners;
+    private readonly presenceListeners;
     /** Number of currently registered listeners. Useful for leak-check assertions in tests. */
     get listenerCount(): number;
     /**
@@ -22,6 +24,33 @@ export declare class EventBus<T> {
      * passed through it before re-emission. Returns an `Unsubscribe` for the internal subscription.
      */
     forwardTo(target: EventBus<T>, enrich?: (event: T) => T): Unsubscribe;
+    /**
+     * Re-emit events from this bus onto `target`, but only while `target` has at least one subscriber.
+     *
+     * Lazily attaches the upstream subscriber when `target.listenerCount` transitions from 0 → 1, and
+     * detaches when it transitions back to 0. Composes naturally: chaining `forwardWhileSubscribed`
+     * across multiple buses propagates "no listener anywhere downstream" all the way up the chain, so
+     * a producer that's expensive to run (subprocess debug logging, periodic polling, etc.) can read
+     * `this.listenerCount > 0` and skip the work entirely when no consumer cares.
+     *
+     * Returns an `Unsubscribe` that tears down both the lazy upstream subscription (if attached) and
+     * the presence watcher on `target`. Idempotent.
+     */
+    forwardWhileSubscribed(target: EventBus<T>, enrich?: (event: T) => T): Unsubscribe;
+    /**
+     * Subscribe to listener-presence transitions on this bus. The callback fires with `true` when the
+     * listener set transitions from empty to non-empty, and `false` when it goes back to empty. It
+     * does NOT fire on intermediate listener add/remove (e.g. 2 → 1 listener) — only on the 0 ↔ N
+     * transitions that matter for upstream activation.
+     *
+     * Used by `forwardWhileSubscribed` to lazily attach upstream subscribers; also useful when an
+     * expensive producer wants to start/stop work based on whether anyone is listening at all.
+     *
+     * Returns an idempotent `Unsubscribe`. The presence callback is NOT invoked synchronously on
+     * subscribe — callers that need the current state read `this.listenerCount` directly.
+     */
+    onSubscriberPresenceChange(callback: SubscriberPresenceListener): Unsubscribe;
     /** Remove all listeners. Idempotent. */
     dispose(): void;
+    private notifyPresenceChange;
 }

package/dist/event-bus.js

@@ -10,6 +10,7 @@
  */
 export class EventBus {
     listeners = new Set();
+    presenceListeners = new Set();
     /** Number of currently registered listeners. Useful for leak-check assertions in tests. */
     get listenerCount() {
         return this.listeners.size;
@@ -19,9 +20,16 @@ export class EventBus {
      * Safe to call the returned function multiple times — subsequent calls are no-ops.
      */
     on(callback) {
+        const wasEmpty = this.listeners.size === 0;
         this.listeners.add(callback);
+        if (wasEmpty) {
+            this.notifyPresenceChange(true);
+        }
         return () => {
-            this.listeners.delete(callback);
+            const removed = this.listeners.delete(callback);
+            if (removed && this.listeners.size === 0) {
+                this.notifyPresenceChange(false);
+            }
         };
     }
     /** Emit an event to every registered listener. Listener errors are caught and discarded. */
@@ -44,9 +52,87 @@ export class EventBus {
             target.emit(enrich ? enrich(event) : event);
         });
     }
+    /**
+     * Re-emit events from this bus onto `target`, but only while `target` has at least one subscriber.
+     *
+     * Lazily attaches the upstream subscriber when `target.listenerCount` transitions from 0 → 1, and
+     * detaches when it transitions back to 0. Composes naturally: chaining `forwardWhileSubscribed`
+     * across multiple buses propagates "no listener anywhere downstream" all the way up the chain, so
+     * a producer that's expensive to run (subprocess debug logging, periodic polling, etc.) can read
+     * `this.listenerCount > 0` and skip the work entirely when no consumer cares.
+     *
+     * Returns an `Unsubscribe` that tears down both the lazy upstream subscription (if attached) and
+     * the presence watcher on `target`. Idempotent.
+     */
+    forwardWhileSubscribed(target, enrich) {
+        let upstreamUnsub;
+        const attach = () => {
+            // Defensive: `attach` is called from the presence callback (only fires on
+            // 0 → N transitions) OR the link-time check below — never both for the same
+            // `detach`-cycle, so the guard is unreachable through the public API today.
+            // Kept so a future refactor can't accidentally double-subscribe.
+            if (!upstreamUnsub) {
+                upstreamUnsub = this.on((event) => {
+                    target.emit(enrich ? enrich(event) : event);
+                });
+            }
+        };
+        const detach = () => {
+            if (upstreamUnsub) {
+                upstreamUnsub();
+                upstreamUnsub = undefined;
+            }
+        };
+        const presenceUnsub = target.onSubscriberPresenceChange((hasSubscribers) => {
+            if (hasSubscribers)
+                attach();
+            else
+                detach();
+        });
+        if (target.listenerCount > 0) {
+            attach();
+        }
+        return () => {
+            presenceUnsub();
+            detach();
+        };
+    }
+    /**
+     * Subscribe to listener-presence transitions on this bus. The callback fires with `true` when the
+     * listener set transitions from empty to non-empty, and `false` when it goes back to empty. It
+     * does NOT fire on intermediate listener add/remove (e.g. 2 → 1 listener) — only on the 0 ↔ N
+     * transitions that matter for upstream activation.
+     *
+     * Used by `forwardWhileSubscribed` to lazily attach upstream subscribers; also useful when an
+     * expensive producer wants to start/stop work based on whether anyone is listening at all.
+     *
+     * Returns an idempotent `Unsubscribe`. The presence callback is NOT invoked synchronously on
+     * subscribe — callers that need the current state read `this.listenerCount` directly.
+     */
+    onSubscriberPresenceChange(callback) {
+        this.presenceListeners.add(callback);
+        return () => {
+            this.presenceListeners.delete(callback);
+        };
+    }
     /** Remove all listeners. Idempotent. */
     dispose() {
+        const hadSubscribers = this.listeners.size > 0;
         this.listeners.clear();
+        if (hadSubscribers) {
+            this.notifyPresenceChange(false);
+        }
+        this.presenceListeners.clear();
+    }
+    notifyPresenceChange(hasSubscribers) {
+        for (const listener of this.presenceListeners) {
+            try {
+                listener(hasSubscribers);
+            }
+            catch {
+                // Same isolation rule as `emit`: one bad presence callback can't break siblings.
+            }
+        }
     }
 }
 //# sourceMappingURL=event-bus.js.map

package/dist/index.d.ts

@@ -3,8 +3,10 @@ export { Clock, RealClock } from './clock.js';
 export { type OrgConnection, RealOrgConnection } from './connection.js';
 export { type OrgConnectionFactory, RealOrgConnectionFactory } from './connection-factory.js';
 export { getErrorMessage, getErrorMessageWithStack, isAbortError, wrapError } from './error-utils.js';
-export { EventBus, type EventListener, type Unsubscribe } from './event-bus.js';
+export { EventBus, type EventListener, type SubscriberPresenceListener, type Unsubscribe } from './event-bus.js';
 export { type UniqueIDGenerator, UUIDGenerator } from './id-generator.js';
+export { createProxyAwareFetch, resolveProxyDispatcher } from './proxy-dispatcher.js';
+export { type CreateJWTFromConnectionOptions, createJWT, createJWTFromConnection, DynamicJSONWebToken, FixedJSONWebToken, type JSONWebToken, type JWTOptions, type RequiredJWTHeaders, type RequiredJWTPayload, } from './jwt.js';
 export { LogBus, type LogLevel, type LogRecord } from './log.js';
 export { type FrontmatterSplit, splitFrontmatterAndBody } from './markdown-frontmatter.js';
 export { BackoffRetryer, DEFAULT_RETRY_OPTIONS, NoOpRetryer, type Retryer, type RetryAttemptInfo, type RetryCallbacks, type RetryExhaustedInfo, type RetryOptions, } from './retryer.js';

package/dist/index.js

@@ -9,6 +9,8 @@ export { RealOrgConnectionFactory } from './connection-factory.js';
 export { getErrorMessage, getErrorMessageWithStack, isAbortError, wrapError } from './error-utils.js';
 export { EventBus } from './event-bus.js';
 export { UUIDGenerator } from './id-generator.js';
+export { createProxyAwareFetch, resolveProxyDispatcher } from './proxy-dispatcher.js';
+export { createJWT, createJWTFromConnection, DynamicJSONWebToken, FixedJSONWebToken, } from './jwt.js';
 export { LogBus } from './log.js';
 export { splitFrontmatterAndBody } from './markdown-frontmatter.js';
 export { BackoffRetryer, DEFAULT_RETRY_OPTIONS, NoOpRetryer, } from './retryer.js';

package/dist/jwt.d.ts

@@ -0,0 +1,87 @@
+import { Clock } from './clock.js';
+import type { OrgConnection } from './connection.js';
+import { type LogRecord } from './log.js';
+import type { Unsubscribe } from './event-bus.js';
+export type RequiredJWTHeaders = {
+    tnk: string;
+};
+export type RequiredJWTPayload = {
+    exp: number;
+};
+export interface JSONWebToken<JWTHeaders extends RequiredJWTHeaders = RequiredJWTHeaders, JWTPayload extends RequiredJWTPayload = RequiredJWTPayload> {
+    getHeaders(): Promise<JWTHeaders>;
+    getPayload(): Promise<JWTPayload>;
+    getValue(): Promise<string>;
+    getTenantKey(): Promise<string>;
+    getFeatureId(): string;
+    isExpired(): boolean;
+    /**
+     * Subscribe to structured log records emitted during JWT lifecycle. Returns an unsubscribe closure.
+     * Implementations that cannot refresh (e.g. `FixedJSONWebToken`) return a no-op unsubscribe.
+     */
+    onLog(callback: (record: LogRecord) => void): Unsubscribe;
+}
+export type JWTOptions = {
+    accessToken: string;
+    instanceUrl: string;
+    mintingPath?: string;
+    featureId?: string;
+};
+/**
+ * Creates an authenticated, auto-refreshing JWT for the Salesforce LLM Gateway.
+ *
+ * Establishes a connection to the org, mints an initial JWT, and validates it
+ * immediately — callers get a fail-fast error if credentials are invalid rather
+ * than a deferred failure on the first chat request.
+ *
+ * The returned token auto-refreshes transparently when it expires.
+ */
+export declare function createJWT<JWTHeaders extends RequiredJWTHeaders, JWTPayload extends RequiredJWTPayload>(options: JWTOptions): Promise<JSONWebToken<JWTHeaders, JWTPayload>>;
+export type CreateJWTFromConnectionOptions = {
+    mintingPath?: string;
+    featureId?: string;
+};
+/**
+ * Creates an auto-refreshing JWT from an existing {@link OrgConnection}.
+ *
+ * Unlike {@link createJWT}, this does not establish a new connection — use it when
+ * you already have a validated org connection (e.g. inside a connectivity resolver).
+ *
+ * The returned token auto-refreshes transparently when it expires.
+ */
+export declare function createJWTFromConnection<JWTHeaders extends RequiredJWTHeaders, JWTPayload extends RequiredJWTPayload>(orgConnection: OrgConnection, options?: CreateJWTFromConnectionOptions): Promise<JSONWebToken<JWTHeaders, JWTPayload>>;
+export declare class FixedJSONWebToken<JWTHeaders extends RequiredJWTHeaders, JWTPayload extends RequiredJWTPayload> implements JSONWebToken<JWTHeaders, JWTPayload> {
+    private static readonly JWT_PATTERN;
+    private readonly jwtValue;
+    private readonly clock;
+    private readonly header;
+    private readonly payload;
+    private readonly featureId;
+    private readonly utcExpirationInMs;
+    constructor(jwtValue: string, clock?: Clock, featureId?: string);
+    getHeaders(): Promise<JWTHeaders>;
+    getPayload(): Promise<JWTPayload>;
+    getValue(): Promise<string>;
+    getTenantKey(): Promise<string>;
+    isExpired(): boolean;
+    getFeatureId(): string;
+    onLog(_callback: (record: LogRecord) => void): Unsubscribe;
+}
+export declare class DynamicJSONWebToken<JWTHeaders extends RequiredJWTHeaders, JWTPayload extends RequiredJWTPayload> implements JSONWebToken<JWTHeaders, JWTPayload> {
+    private readonly mintingPath;
+    private readonly orgConnection;
+    private readonly clock;
+    private readonly featureId;
+    private readonly logBus;
+    private fixedJWT?;
+    constructor(mintingPath: string, orgConnection: OrgConnection, clock?: Clock, featureId?: string);
+    getHeaders(): Promise<JWTHeaders>;
+    getPayload(): Promise<JWTPayload>;
+    getValue(): Promise<string>;
+    getTenantKey(): Promise<string>;
+    isExpired(): boolean;
+    getFeatureId(): string;
+    onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    private getUnexpiredJwt;
+    private requestFreshJwt;
+}

package/dist/jwt.js

@@ -0,0 +1,183 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { Clock, RealClock } from './clock.js';
+import { RealOrgConnectionFactory } from './connection-factory.js';
+import { getErrorMessage } from './error-utils.js';
+import { LogBus } from './log.js';
+const JWTOptionsDefaults = {
+    mintingPath: '/ide/auth',
+    featureId: process.env['LLMG_FEATURE_ID'] ?? 'VibesService',
+};
+/**
+ * Creates an authenticated, auto-refreshing JWT for the Salesforce LLM Gateway.
+ *
+ * Establishes a connection to the org, mints an initial JWT, and validates it
+ * immediately — callers get a fail-fast error if credentials are invalid rather
+ * than a deferred failure on the first chat request.
+ *
+ * The returned token auto-refreshes transparently when it expires.
+ */
+export async function createJWT(options) {
+    const mintingPath = options.mintingPath ?? JWTOptionsDefaults.mintingPath;
+    const featureId = options.featureId ?? JWTOptionsDefaults.featureId;
+    const orgConnection = await new RealOrgConnectionFactory().createFromCredentials(options.accessToken, options.instanceUrl);
+    const jwt = new DynamicJSONWebToken(mintingPath, orgConnection, new RealClock(), featureId);
+    // Ensures a JWT minting attempt occurs immediately so callers get a fail-fast error for invalid credentials.
+    await jwt.getValue();
+    return jwt;
+}
+/**
+ * Creates an auto-refreshing JWT from an existing {@link OrgConnection}.
+ *
+ * Unlike {@link createJWT}, this does not establish a new connection — use it when
+ * you already have a validated org connection (e.g. inside a connectivity resolver).
+ *
+ * The returned token auto-refreshes transparently when it expires.
+ */
+export async function createJWTFromConnection(orgConnection, options) {
+    const mintingPath = options?.mintingPath ?? JWTOptionsDefaults.mintingPath;
+    const featureId = options?.featureId ?? JWTOptionsDefaults.featureId;
+    const jwt = new DynamicJSONWebToken(mintingPath, orgConnection, new RealClock(), featureId);
+    await jwt.getValue();
+    return jwt;
+}
+export class FixedJSONWebToken {
+    // 'eyJ' strongly suggests that this is a base64 JSON, and so the general shape of the rest of it is enough to presume it's a JWT.
+    static JWT_PATTERN = /eyJ[A-Za-z0-9+=_-]+\.[A-Za-z0-9+=_-]+\.[A-Za-z0-9+=_-]+/;
+    jwtValue;
+    clock;
+    header;
+    payload;
+    featureId;
+    // Expiration time in milliseconds since midnight, January 1, 1970 UTC.
+    utcExpirationInMs;
+    constructor(jwtValue, clock = new RealClock(), featureId = JWTOptionsDefaults.featureId) {
+        if (!FixedJSONWebToken.JWT_PATTERN.test(jwtValue)) {
+            throw new Error(`Invalid JWT token. Value does not match regex: ${FixedJSONWebToken.JWT_PATTERN.toString()}`);
+        }
+        this.jwtValue = jwtValue;
+        this.clock = clock;
+        try {
+            const splitToken = jwtValue.split('.');
+            const base64Header = splitToken[0];
+            const base64Payload = splitToken[1];
+            this.header = JSON.parse(Buffer.from(base64Header, 'base64').toString());
+            if (!('tnk' in this.header) || typeof this.header.tnk !== 'string') {
+                throw new Error("Header is missing required 'tnk' field.");
+            }
+            this.payload = JSON.parse(Buffer.from(base64Payload, 'base64').toString());
+            if (!('exp' in this.payload) || typeof this.payload.exp !== 'number') {
+                throw new Error("Payload is missing required 'exp' field.");
+            }
+            this.utcExpirationInMs = this.payload.exp * 1_000;
+            this.featureId = featureId;
+        }
+        catch (err) {
+            throw new Error(`Invalid JWT token. ${getErrorMessage(err)}`, { cause: err });
+        }
+    }
+    getHeaders() {
+        return Promise.resolve(this.header);
+    }
+    getPayload() {
+        return Promise.resolve(this.payload);
+    }
+    getValue() {
+        return Promise.resolve(this.jwtValue);
+    }
+    getTenantKey() {
+        return Promise.resolve(this.header.tnk);
+    }
+    isExpired() {
+        // Add in a buffer of 30s to prevent the token from expiring while requests are in progress. That is make it
+        // expire 30 seconds earlier to prevent making a new request too close to the actual expiration.
+        const bufferedUtcExpirationInMs = this.utcExpirationInMs - 30_000;
+        const currentDateTime = this.clock.now();
+        return currentDateTime.getTime() > bufferedUtcExpirationInMs;
+    }
+    getFeatureId() {
+        return this.featureId;
+    }
+    onLog(_callback) {
+        return () => { };
+    }
+}
+export class DynamicJSONWebToken {
+    mintingPath;
+    orgConnection;
+    clock;
+    featureId;
+    logBus = new LogBus();
+    fixedJWT;
+    constructor(mintingPath, orgConnection, clock = new RealClock(), featureId = JWTOptionsDefaults.featureId) {
+        this.mintingPath = mintingPath;
+        this.orgConnection = orgConnection;
+        this.clock = clock;
+        this.featureId = featureId;
+    }
+    async getHeaders() {
+        return (await this.getUnexpiredJwt()).getHeaders();
+    }
+    async getPayload() {
+        return (await this.getUnexpiredJwt()).getPayload();
+    }
+    async getValue() {
+        return (await this.getUnexpiredJwt()).getValue();
+    }
+    async getTenantKey() {
+        return (await this.getUnexpiredJwt()).getTenantKey();
+    }
+    isExpired() {
+        // Always false because we refresh the fixed one always if needed
+        return false;
+    }
+    getFeatureId() {
+        return this.featureId;
+    }
+    onLog(callback) {
+        return this.logBus.on(callback);
+    }
+    async getUnexpiredJwt() {
+        if (!this.fixedJWT || (await this.fixedJWT.isExpired())) {
+            this.logBus.debug('Refreshing expired JWT');
+            this.fixedJWT = await this.requestFreshJwt();
+        }
+        return this.fixedJWT;
+    }
+    async requestFreshJwt() {
+        const start = this.clock.now().getTime();
+        let result;
+        try {
+            result = await this.orgConnection.request({
+                method: 'POST',
+                url: new URL(this.mintingPath, this.orgConnection.getInstanceUrl()).toString(),
+                body: '{}',
+                headers: {
+                    'X-Feature-Id': this.getFeatureId(),
+                },
+            });
+        }
+        catch (err) {
+            const wrapped = new Error(`Failed to obtain JWT from ${this.mintingPath}. ${getErrorMessage(err)}`, {
+                cause: err,
+            });
+            this.logBus.error('JWT refresh failed', wrapped, {
+                durationMs: this.clock.now().getTime() - start,
+            });
+            throw wrapped;
+        }
+        if (!result.jwt) {
+            const missingErr = new Error(`Failed to obtain JWT from ${this.mintingPath}. Missing 'jwt' property on result.`);
+            this.logBus.error('JWT refresh failed', missingErr, {
+                durationMs: this.clock.now().getTime() - start,
+            });
+            throw missingErr;
+        }
+        const durationMs = this.clock.now().getTime() - start;
+        this.logBus.info('JWT refreshed', { durationMs });
+        return new FixedJSONWebToken(result.jwt, this.clock);
+    }
+}
+//# sourceMappingURL=jwt.js.map

package/dist/proxy-dispatcher.d.ts

@@ -0,0 +1,39 @@
+import { Dispatcher } from 'undici';
+/**
+ * Resolves a `Dispatcher` from `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` env
+ * vars (either casing — undici honors both), or `undefined` when none is set.
+ *
+ * `EnvHttpProxyAgent` reads `HTTPS_PROXY` and `HTTP_PROXY` at construction and
+ * pins them for the dispatcher's lifetime; `NO_PROXY` is re-evaluated per
+ * dispatch (see undici v8.5 source: `#noProxyChanged` / `#noProxyEnv`). Callers
+ * must set `HTTPS_PROXY` / `HTTP_PROXY` BEFORE invoking this function; later
+ * mutations of those two are not picked up by the returned dispatcher.
+ *
+ * Returning `undefined` when no proxy env is set preserves the zero-wrap fast
+ * path in `createProxyAwareFetch` — `globalThis.fetch` is returned unchanged.
+ * Constructing an `EnvHttpProxyAgent` unconditionally would push every
+ * no-proxy harness through the undici-fetch wrapper.
+ *
+ * Designed to be called from harness factories' `create()` to derive a default
+ * proxy-aware dispatcher per harness instance.
+ */
+export declare function resolveProxyDispatcher(): Dispatcher | undefined;
+/**
+ * Returns a `fetch`-compatible function that routes through `dispatcher` (via
+ * `undici.fetch`). When `dispatcher` is `undefined`, returns `globalThis.fetch`
+ * unchanged so the no-proxy path has zero overhead and no undici-wrapper
+ * shape leaks into the call site.
+ *
+ * Composes with the harness fetch wrappers (`createGatewayFetch`,
+ * `createAuthFetch`): those wrappers add per-request header merging on top
+ * of whatever inner `fetch` they're handed. Routing the inner fetch through
+ * an undici `Dispatcher` is what makes `HTTPS_PROXY` honoring happen — without
+ * any process-wide `setGlobalDispatcher` mutation.
+ *
+ * Verified against the SDKs we hand a `fetch` option to today
+ * (`@anthropic-ai/sdk`, `@anthropic-ai/bedrock-sdk`, `openai`, `@mastra/mcp`
+ * via `@modelcontextprotocol/sdk` `StreamableHTTPClientTransport`): every
+ * outbound HTTP call (including streaming SSE) routes through the injected
+ * `fetch`. See PR #609 for the SDK source-trace findings.
+ */
+export declare function createProxyAwareFetch(dispatcher?: Dispatcher): typeof fetch;

package/dist/proxy-dispatcher.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { Dispatcher, EnvHttpProxyAgent, fetch as undiciFetch } from 'undici';
+/**
+ * Resolves a `Dispatcher` from `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` env
+ * vars (either casing — undici honors both), or `undefined` when none is set.
+ *
+ * `EnvHttpProxyAgent` reads `HTTPS_PROXY` and `HTTP_PROXY` at construction and
+ * pins them for the dispatcher's lifetime; `NO_PROXY` is re-evaluated per
+ * dispatch (see undici v8.5 source: `#noProxyChanged` / `#noProxyEnv`). Callers
+ * must set `HTTPS_PROXY` / `HTTP_PROXY` BEFORE invoking this function; later
+ * mutations of those two are not picked up by the returned dispatcher.
+ *
+ * Returning `undefined` when no proxy env is set preserves the zero-wrap fast
+ * path in `createProxyAwareFetch` — `globalThis.fetch` is returned unchanged.
+ * Constructing an `EnvHttpProxyAgent` unconditionally would push every
+ * no-proxy harness through the undici-fetch wrapper.
+ *
+ * Designed to be called from harness factories' `create()` to derive a default
+ * proxy-aware dispatcher per harness instance.
+ */
+export function resolveProxyDispatcher() {
+    if (!process.env['HTTPS_PROXY'] &&
+        !process.env['HTTP_PROXY'] &&
+        !process.env['https_proxy'] &&
+        !process.env['http_proxy']) {
+        return undefined;
+    }
+    return new EnvHttpProxyAgent();
+}
+/**
+ * Returns a `fetch`-compatible function that routes through `dispatcher` (via
+ * `undici.fetch`). When `dispatcher` is `undefined`, returns `globalThis.fetch`
+ * unchanged so the no-proxy path has zero overhead and no undici-wrapper
+ * shape leaks into the call site.
+ *
+ * Composes with the harness fetch wrappers (`createGatewayFetch`,
+ * `createAuthFetch`): those wrappers add per-request header merging on top
+ * of whatever inner `fetch` they're handed. Routing the inner fetch through
+ * an undici `Dispatcher` is what makes `HTTPS_PROXY` honoring happen — without
+ * any process-wide `setGlobalDispatcher` mutation.
+ *
+ * Verified against the SDKs we hand a `fetch` option to today
+ * (`@anthropic-ai/sdk`, `@anthropic-ai/bedrock-sdk`, `openai`, `@mastra/mcp`
+ * via `@modelcontextprotocol/sdk` `StreamableHTTPClientTransport`): every
+ * outbound HTTP call (including streaming SSE) routes through the injected
+ * `fetch`. See PR #609 for the SDK source-trace findings.
+ */
+export function createProxyAwareFetch(dispatcher) {
+    if (!dispatcher)
+        return globalThis.fetch;
+    // Cast at the boundary: Node's `fetch` and undici's `fetch` have structurally-
+    // identical RequestInfo / Response shapes but TS treats them as distinct nominal
+    // types. Casting via `unknown` keeps the consumer-facing signature as
+    // `typeof fetch` (the WHATWG/Node type) while routing through undici under it.
+    return (input, init) => undiciFetch(input, {
+        ...init,
+        dispatcher,
+    });
+}
+//# sourceMappingURL=proxy-dispatcher.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/agentic-common",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Shared primitives and common utilities for the Salesforce agentic DX packages",
   "type": "module",
   "exports": {
@@ -30,14 +30,15 @@
     "LICENSE.txt"
   ],
   "dependencies": {
-    "@salesforce/core": "^8.31.0"
+    "@salesforce/core": "^8.31.1",
+    "undici": "^8.5.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^22.19.20",
+    "@types/node": "^22.19.21",
     "@vitest/coverage-istanbul": "^4.1.8",
-    "@vitest/eslint-plugin": "^1.6.19",
-    "eslint": "^10.4.1",
+    "@vitest/eslint-plugin": "^1.6.20",
+    "eslint": "^10.5.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",