@salesforce/agentic-common 0.11.0 → 0.13.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.13.0] - 2026-06-24
+
+### Chores
+- update dependencies and disable Mastra PostHog telemetry @W-23054815 ([#619](https://github.com/forcedotcom/agentic-dx/pull/619))
+- **deps-dev**: bump @types/node from 22.19.21 to 22.20.0 in the dev-dependencies group ([#613](https://github.com/forcedotcom/agentic-dx/pull/613))
+
+## [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

package/README.md

@@ -2,7 +2,7 @@
 
 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, a Salesforce org connection
-interface, and the `JSONWebToken` family used by both the LLM gateway client and the agent-SDK's connectivity resolvers.
+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.
@@ -258,10 +282,13 @@ function createJWT(options: {
 // Same fail-fast first-mint behavior, but uses an existing OrgConnection.
 function createJWTFromConnection(
   orgConnection: OrgConnection,
-  options?: { mintingPath?: string; featureId?: string },
+  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.
@@ -292,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
@@ -369,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/index.d.ts

@@ -5,6 +5,7 @@ export { type OrgConnectionFactory, RealOrgConnectionFactory } from './connectio
 export { getErrorMessage, getErrorMessageWithStack, isAbortError, wrapError } from './error-utils.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';

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 { 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';

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.11.0",
+  "version": "0.13.0",
   "description": "Shared primitives and common utilities for the Salesforce agentic DX packages",
   "type": "module",
   "exports": {
@@ -30,11 +30,12 @@
     "LICENSE.txt"
   ],
   "dependencies": {
-    "@salesforce/core": "^8.31.1"
+    "@salesforce/core": "^8.31.1",
+    "undici": "^8.5.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^22.19.21",
+    "@types/node": "^22.20.0",
     "@vitest/coverage-istanbul": "^4.1.8",
     "@vitest/eslint-plugin": "^1.6.20",
     "eslint": "^10.5.0",
@@ -51,7 +52,7 @@
     "vitest": "^4.1.8"
   },
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=22.22.0"
   },
   "lint-staged": {
     "*.{js,jsx,ts,tsx,json,md}": [