@salesforce/agentic-common 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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.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 both the LLM gateway client and the agent-SDK's connectivity resolvers.
 
 ## Quick Start
 
@@ -184,20 +184,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 +229,43 @@ 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?: { mintingPath?: string; featureId?: string },
+): Promise<JSONWebToken>;
+```
+
+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 /

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,9 @@ 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 { 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,7 @@ 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 { 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/agentic-common",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Shared primitives and common utilities for the Salesforce agentic DX packages",
   "type": "module",
   "exports": {
@@ -30,14 +30,14 @@
     "LICENSE.txt"
   ],
   "dependencies": {
-    "@salesforce/core": "^8.31.0"
+    "@salesforce/core": "^8.31.1"
   },
   "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",