@salesforce/agentic-common 0.5.0 → 0.7.0

package/README.md

@@ -6,7 +6,8 @@ interface consumed by the other packages in this monorepo.
 
 ## Quick Start
 
-> **Closed source.** This package is published to npm under the [Salesforce Public Code License](../../LICENSE.txt) and is for use by Salesforce only.
+> **Closed source.** This package is published to npm under the [Salesforce Public Code License](../../LICENSE.txt) and
+> is for use by Salesforce only.
 
 ```typescript
 import { EventBus, LogBus } from '@salesforce/agentic-common';
@@ -81,6 +82,35 @@ enum SfApiEnv {
 }
 ```
 
+### `inferSfApiEnv(instanceUrl, options?): SfApiEnv`
+
+Maps a Salesforce instance URL to a `SfApiEnv`. `OrgConnection.getInferredSfApiEnv()` is the typical entry point; direct
+callers use this when they have an `instanceUrl` but not a connection (e.g. building a Salesforce platform MCP URL from
+a token + instance URL).
+
+Resolution order:
+
+1. If `SF_API_ENV` is set to a valid value, return it.
+2. STM patterns → `Stage`.
+3. OrgFarm dev / perf / test sub-segments under `.pc-rnd.` → `Dev` / `Perf` / `Test`.
+4. `.pc-rnd.` host with no recognized sub-segment → `options.pcRndFallback ?? Test`. `.pc-rnd.` is an internal-only
+   OrgFarm domain (by definition not Prod), so the default degrades a future unrecognized sub-segment to a sibling
+   non-prod host rather than leaking traffic from a non-prod org to the Prod servlet.
+5. `.crm.dev` workspaces, `localhost.sfdcdev.`, `.internal.` → `Dev`.
+6. Anything else → `Prod`.
+
+```typescript
+function inferSfApiEnv(instanceUrl: string, options?: { pcRndFallback?: SfApiEnv }): SfApiEnv;
+```
+
+```typescript
+import { SfApiEnv, inferSfApiEnv } from '@salesforce/agentic-common';
+
+inferSfApiEnv('https://myorg.test1.pc-rnd.salesforce.com'); // SfApiEnv.Test
+inferSfApiEnv('https://myorg.qa1.pc-rnd.salesforce.com'); // SfApiEnv.Test (default fallback)
+inferSfApiEnv('https://myorg.qa1.pc-rnd.salesforce.com', { pcRndFallback: SfApiEnv.Prod }); // SfApiEnv.Prod
+```
+
 ### `Clock` / `RealClock`
 
 Abstract time source for dependency injection. Use `RealClock` in production; extend `Clock` in tests for deterministic
@@ -261,8 +291,8 @@ Splits a markdown document into its YAML frontmatter block and body content. Rec
 frontmatter block at the start of a document and normalizes CRLF line endings to LF. When no frontmatter block is
 present, `frontmatter` is `null` and `body` is the full input.
 
-The frontmatter is returned unparsed so callers can choose whether to parse it as YAML, JSON, or treat it as opaque
-text — keeping a YAML runtime out of `@salesforce/agentic-common`.
+The frontmatter is returned unparsed so callers can choose whether to parse it as YAML, JSON, or treat it as opaque text
+— keeping a YAML runtime out of `@salesforce/agentic-common`.
 
 ```typescript
 import { splitFrontmatterAndBody } from '@salesforce/agentic-common';
@@ -279,6 +309,24 @@ type FrontmatterSplit = {
 };
 ```
 
+### `backfillCreatedAt<T extends { createdAt?: Date }>(messages: T[], clock: Clock): T[]`
+
+Backfills missing `createdAt` timestamps on a batch of message-shaped records, stepping per-position via
+`clock.nextAfter` so a bulk insert produces strictly-ascending timestamps rather than ms-precision ties tie-broken by
+stable sort. Records that already carry a `createdAt` pass through unchanged (same reference, no clone). Records missing
+one are cloned with a freshly-stepped value: the first missing position seeds from `clock.now()`, each subsequent
+missing position uses `clock.nextAfter(<prior>)`.
+
+Used by `sfdx-agent-sdk`'s `ChatSession.addContext()` and both harnesses' `addContext` boundaries so the read-side
+"every Message has populated `createdAt`; sort ascending" contract is upheld regardless of consumer-construction style.
+Generic over the record shape, so any consumer with a `createdAt?: Date` field can reuse the same policy.
+
+```typescript
+import { backfillCreatedAt, RealClock } from '@salesforce/agentic-common';
+
+const filled = backfillCreatedAt(messages, new RealClock());
+```
+
 ## Development
 
 See [DEVELOPING.md](../../DEVELOPING.md) for build-from-source setup, scripts, and monorepo commands.

package/dist/backfill-created-at.d.ts

@@ -0,0 +1,24 @@
+import type { Clock } from './clock.js';
+/**
+ * Backfills missing `createdAt` timestamps on a batch of message-shaped
+ * records, stepping per-position via `clock.nextAfter` so a bulk insert
+ * produces strictly-ascending timestamps rather than ms-precision ties
+ * tie-broken by stable sort.
+ *
+ * Records that already carry a `createdAt` are returned unchanged (same
+ * reference, no clone). Records missing one are cloned with a freshly-
+ * stepped `createdAt`. The first missing position seeds from `clock.now()`;
+ * each subsequent missing position uses `clock.nextAfter(<prior>)`.
+ *
+ * Generic over the record shape so this can be reused by:
+ * - The SDK's `DefaultChatSession.addContext` (over `Message`)
+ * - Both production harnesses' `addContext` boundaries
+ *
+ * Anywhere the message-shape contract requires an ascending sortable
+ * timestamp, this is the single backfill site so the three implementations
+ * can't drift on subtle policy questions (clamp-to-lastExplicit, behavior
+ * at the boundary between explicit and implicit positions, etc.).
+ */
+export declare function backfillCreatedAt<T extends {
+    createdAt?: Date;
+}>(messages: T[], clock: Clock): T[];

package/dist/backfill-created-at.js

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Backfills missing `createdAt` timestamps on a batch of message-shaped
+ * records, stepping per-position via `clock.nextAfter` so a bulk insert
+ * produces strictly-ascending timestamps rather than ms-precision ties
+ * tie-broken by stable sort.
+ *
+ * Records that already carry a `createdAt` are returned unchanged (same
+ * reference, no clone). Records missing one are cloned with a freshly-
+ * stepped `createdAt`. The first missing position seeds from `clock.now()`;
+ * each subsequent missing position uses `clock.nextAfter(<prior>)`.
+ *
+ * Generic over the record shape so this can be reused by:
+ * - The SDK's `DefaultChatSession.addContext` (over `Message`)
+ * - Both production harnesses' `addContext` boundaries
+ *
+ * Anywhere the message-shape contract requires an ascending sortable
+ * timestamp, this is the single backfill site so the three implementations
+ * can't drift on subtle policy questions (clamp-to-lastExplicit, behavior
+ * at the boundary between explicit and implicit positions, etc.).
+ */
+export function backfillCreatedAt(messages, clock) {
+    let last;
+    return messages.map((m) => {
+        if (m.createdAt)
+            return m;
+        last = last ? clock.nextAfter(last) : clock.now();
+        return { ...m, createdAt: last };
+    });
+}
+//# sourceMappingURL=backfill-created-at.js.map

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { backfillCreatedAt } from './backfill-created-at.js';
 export { Clock, RealClock } from './clock.js';
 export { type OrgConnection, RealOrgConnection } from './connection.js';
 export { type OrgConnectionFactory, RealOrgConnectionFactory } from './connection-factory.js';
@@ -7,5 +8,5 @@ export { type UniqueIDGenerator, UUIDGenerator } from './id-generator.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';
-export { SfApiEnv } from './sf-api-env.js';
+export { inferSfApiEnv, SfApiEnv } from './sf-api-env.js';
 export { buildSummaryPrompt } from './summary-prompt.js';

package/dist/index.js

@@ -2,6 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
+export { backfillCreatedAt } from './backfill-created-at.js';
 export { Clock, RealClock } from './clock.js';
 export { RealOrgConnection } from './connection.js';
 export { RealOrgConnectionFactory } from './connection-factory.js';
@@ -11,6 +12,6 @@ export { UUIDGenerator } from './id-generator.js';
 export { LogBus } from './log.js';
 export { splitFrontmatterAndBody } from './markdown-frontmatter.js';
 export { BackoffRetryer, DEFAULT_RETRY_OPTIONS, NoOpRetryer, } from './retryer.js';
-export { SfApiEnv } from './sf-api-env.js';
+export { inferSfApiEnv, SfApiEnv } from './sf-api-env.js';
 export { buildSummaryPrompt } from './summary-prompt.js';
 //# sourceMappingURL=index.js.map

package/dist/sf-api-env.d.ts

@@ -16,6 +16,19 @@ export declare enum SfApiEnv {
  *    - OrgFarm dev patterns (`.devX.*.pc-rnd.*`) or workspaces (`.crm.dev`) → `dev`
  *    - OrgFarm perf patterns (`.perfXX.*.pc-rnd.*`) → `perf`
  *    - OrgFarm test patterns (`.testX.*.pc-rnd.*`) → `test`
+ *    - `pc-rnd` hosts with no recognized sub-segment → `options.pcRndFallback` (default `test`)
  *    - Everything else (including unrecognized internal URLs) → `prod`
+ *
+ * @param instanceUrl - Salesforce org instance URL.
+ * @param options - Optional resolution overrides.
+ * @param options.pcRndFallback - Environment to return when the URL is a `.pc-rnd.`
+ *   host that does not match a recognized `.devN.` / `.perfN.` / `.testN.` sub-segment.
+ *   Defaults to {@link SfApiEnv.Test}: `.pc-rnd.` is an internal-only OrgFarm domain,
+ *   so by definition not Prod — a future unrecognized sub-segment degrades to a
+ *   sibling non-prod host instead of leaking traffic from a non-prod org to the
+ *   Prod servlet. Callers with a stronger guarantee (e.g. inputs are pre-validated
+ *   to be Prod-class hosts) can pass another value to override.
  */
-export declare function inferSfApiEnv(instanceUrl: string): SfApiEnv;
+export declare function inferSfApiEnv(instanceUrl: string, options?: {
+    pcRndFallback?: SfApiEnv;
+}): SfApiEnv;

package/dist/sf-api-env.js

@@ -21,9 +21,20 @@ export var SfApiEnv;
  *    - OrgFarm dev patterns (`.devX.*.pc-rnd.*`) or workspaces (`.crm.dev`) → `dev`
  *    - OrgFarm perf patterns (`.perfXX.*.pc-rnd.*`) → `perf`
  *    - OrgFarm test patterns (`.testX.*.pc-rnd.*`) → `test`
+ *    - `pc-rnd` hosts with no recognized sub-segment → `options.pcRndFallback` (default `test`)
  *    - Everything else (including unrecognized internal URLs) → `prod`
+ *
+ * @param instanceUrl - Salesforce org instance URL.
+ * @param options - Optional resolution overrides.
+ * @param options.pcRndFallback - Environment to return when the URL is a `.pc-rnd.`
+ *   host that does not match a recognized `.devN.` / `.perfN.` / `.testN.` sub-segment.
+ *   Defaults to {@link SfApiEnv.Test}: `.pc-rnd.` is an internal-only OrgFarm domain,
+ *   so by definition not Prod — a future unrecognized sub-segment degrades to a
+ *   sibling non-prod host instead of leaking traffic from a non-prod org to the
+ *   Prod servlet. Callers with a stronger guarantee (e.g. inputs are pre-validated
+ *   to be Prod-class hosts) can pass another value to override.
  */
-export function inferSfApiEnv(instanceUrl) {
+export function inferSfApiEnv(instanceUrl, options) {
     const envVar = process.env['SF_API_ENV']?.toLowerCase();
     if (envVar && Object.values(SfApiEnv).includes(envVar)) {
         return envVar;
@@ -44,6 +55,7 @@ export function inferSfApiEnv(instanceUrl) {
         if (/\.test\d+\./.test(lower)) {
             return SfApiEnv.Test;
         }
+        return options?.pcRndFallback ?? SfApiEnv.Test;
     }
     if (lower.includes('.crm.dev') || lower.includes('localhost.sfdcdev.') || lower.includes('.internal.')) {
         return SfApiEnv.Dev;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/agentic-common",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Shared primitives and common utilities for the Salesforce agentic DX packages",
   "type": "module",
   "exports": {