@salesforce/sfdx-agent-sdk 0.40.0 → 0.42.0

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to `@salesforce/sfdx-agent-sdk` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.42.0] - 2026-08-04
+
+### Features
+- **agentic-common,agent-sdk**: reusable env-aware event-bus hierarchy @W-23694153@ ([#732](https://github.com/forcedotcom/agentic-dx/pull/732))
+
+### Chores
+- **deps-dev**: bump eslint from 10.7.0 to 10.8.0 in the eslint group ([#728](https://github.com/forcedotcom/agentic-dx/pull/728))
+
+## [0.41.0] - 2026-08-03
+
+### Features
+- **agent-sdk,harnesses**: emit Tier-1 logBus siblings for lifecycle telemetry @W-23547150@ ([#716](https://github.com/forcedotcom/agentic-dx/pull/716))
+
 ## [0.40.0] - 2026-08-03
 
 ### Features

package/README.md

@@ -228,6 +228,37 @@ function onApprovalRequest(event: ToolApprovalRequestEvent): Promise<boolean> {
 }
 ```
 
+### Environment Context
+
+Every `TelemetryEvent` and `LogRecord` the SDK emits carries optional, **flat** identity fields — stamped once, at the
+event's construction site, by the origin bus (not appended per-subscriber). Subscribe via `onTelemetry` / `onLog` at any
+scope and read the fields directly (e.g. `event.orgId`); because they're flat top-level fields (not nested), log
+pipelines like Pino → Splunk can filter on them without dotted-path escaping.
+
+```typescript
+type EnvironmentFields = {
+  instanceType?: string; // INSTANCE_TYPE — what kind of running instance this is
+  instanceId?: string; // INSTANCE_ID   — this specific running instance
+  orgId?: string; // ORG_ID
+  userId?: string; // USER_ID
+  featureId?: string; // FEATURE_ID, falling back to legacy LLMG_FEATURE_ID
+};
+```
+
+The fields are populated from these **generic** environment variables, read once when the buses are constructed. Each
+field is optional — present only when its variable holds a non-empty value, so in a plain local process the fields are
+absent entirely. A deployment maps its own concepts onto the generic vars at the environment boundary (e.g. a DX
+Workspace container exports `INSTANCE_TYPE=$DXW_TEMPLATE_NAME` / `INSTANCE_ID=$SFDX_INSTANCE_ID`), so the SDK never
+learns deployment-specific names. These fields are a convenience for single-tenant deployments and are subject to
+change; the type and readers are re-exported from `@salesforce/agentic-common`:
+
+- `readEnvironmentContext(env?)` — maps the generic env vars onto an `EnvironmentFields` bag.
+- `resolveFeatureId(env?)` — `FEATURE_ID` → legacy `LLMG_FEATURE_ID` → `undefined`.
+
+The bus hierarchy that stamps these (`TimestampedEventBus` / `EnvironmentAwareEventBus` / the reusable
+`BaseTelemetryEventBus`) lives in `@salesforce/agentic-common` — see that package's README to build env-stamped
+telemetry for a service of your own.
+
 ### Configuration Types
 
 #### `AgentConfig`
@@ -1546,6 +1577,13 @@ Abandoning the iterator mid-stream emits no terminal telemetry — the stream di
 Harness implementations may emit additional structured logs through their own `LogBus`. Those records surface to
 consumers via the same `onLog` channel.
 
+Selected lifecycle moments are reported on **both** channels: the typed telemetry event, plus a log record carrying the
+same facts for log sinks. On those records `message` is human-readable prose intended for display and may be reworded;
+`context.event_type` carries the matching `TelemetryEvent` type and is the stable field to filter, alert, and join on.
+Records paired this way today are `agent-created`, `agent-destroyed`, `session-created`, `session-destroyed`,
+`chat-stream-completed`, `chat-stream-error`, `tool-execution-completed` (only when `isError` is true), and the harness
+MCP events `mcp-server-discovery-completed`, `mcp-server-discovery-failed`, and `mcp-server-status-changed`.
+
 ## Development
 
 See [DEVELOPING.md](DEVELOPING.md) for build-from-source setup, scripts, E2E testing, and packaging.

package/dist/agent-manager.d.ts

@@ -4,7 +4,7 @@ import type { HarnessFactory } from './harness/harness-factory.js';
 import { type AgentConfig } from './harness/harness-config.js';
 import { type Agent } from './agent.js';
 import type { HooksForAgent } from './types/redaction.js';
-import type { TelemetryEventCallback } from './types/telemetry-events.js';
+import { type TelemetryEventCallback } from './types/telemetry-events.js';
 import type { WireCommunicationEventCallback } from './types/wire-communication-event.js';
 import type { ProviderHint } from './types/model-connectivity-info.js';
 import { type AgentConnectivityResolver } from './agent-connectivity-resolver.js';

package/dist/agent-manager.js

@@ -12,6 +12,7 @@ import { AgentSDKError, AgentSDKErrorType } from './errors.js';
 import { TelemetryRouter } from './internal/telemetry-router.js';
 import { WireCommunicationRouter } from './internal/wire-communication-router.js';
 import { AgentIdentityStore } from './internal/agent-identity-store.js';
+import { createTelemetryBus } from './types/telemetry-events.js';
 import { DefaultAgentConnectivityResolver } from './agent-connectivity-resolver.js';
 /**
  * Concrete implementation of {@link AgentManager}. **Not exported** from
@@ -32,7 +33,10 @@ export class DefaultAgentManager {
     identityStore;
     agents = new Map();
     restoreFailures = [];
-    telemetryBus = new EventBus();
+    // Constructed in the constructor body so it uses the injected `clock` (tests inject a StubClock for
+    // deterministic timestamps); env context is self-read from the process. The `logBus` is supplied by
+    // `createAgentManager` (already clock-bound) so the identity store can share it.
+    telemetryBus;
     logBus;
     wireBus = new EventBus();
     router;
@@ -47,6 +51,7 @@ export class DefaultAgentManager {
         this.identityStore = identityStore;
         this.agentIdGenerator = agentIdGenerator;
         this.clock = clock;
+        this.telemetryBus = createTelemetryBus(this.clock);
         this.logBus = logBus;
         this.router = new TelemetryRouter(harness);
         this.wireRouter = new WireCommunicationRouter(harness);
@@ -189,13 +194,15 @@ export class DefaultAgentManager {
         this.wireRouter.registerAgent(agentId);
         const agent = new DefaultAgent(this.harness, agentId, projectRoot, config, runtime.modelConnectivityInfo, runtime.orgConnection, runtime.orgJwt, this.agentConnectivityResolver, this.harnessSupportedProviderHints, this.hooksForAgent, this.identityStore, this.router, agentSlice, { telemetry: this.telemetryBus, log: this.logBus }, this.clock, this.agentIdGenerator);
         this.agents.set(agentId, agent);
-        this.telemetryBus.emit({
-            type: 'agent-created',
-            timestamp: this.clock.now(),
-            agentId,
-            projectRoot,
-            modelName: runtime.modelConnectivityInfo.model.name,
-        });
+        const agentCreatedAt = this.clock.now();
+        const modelName = runtime.modelConnectivityInfo.model.name;
+        // Tier-1 pair: share one tick across the telemetry event and its colocated log sibling.
+        this.telemetryBus.emitTelemetry({ type: 'agent-created', agentId, projectRoot, modelName }, agentCreatedAt);
+        this.logBus.emitLog({
+            level: 'info',
+            message: 'Agent created',
+            context: { event_type: 'agent-created', agentId, projectRoot, modelName },
+        }, agentCreatedAt);
         if (options.rehydrateThreads) {
             // If thread enumeration or session attachment fails, the restore is a full failure
             // (the user would otherwise see an agent marked `ready` whose chat sessions return 404).
@@ -351,7 +358,10 @@ export async function createAgentManager(storageRootFolder, harnessFactory, opti
             `Update the SDK or harness package.`, AgentSDKErrorType.INCOMPATIBLE_HARNESS);
     }
     const agentConnectivityResolver = options?.connectivityResolver ?? new DefaultAgentConnectivityResolver();
-    return DefaultAgentManager.__build(harness, harnessFactory.supportedProviderHints, agentConnectivityResolver, options?.hooksForAgent, storageRootFolder, new UUIDGenerator(), new RealClock(), new LogBus());
+    const clock = new RealClock();
+    return DefaultAgentManager.__build(harness, harnessFactory.supportedProviderHints, agentConnectivityResolver, options?.hooksForAgent, storageRootFolder, new UUIDGenerator(), clock, 
+    // The manager's root log bus shares the manager clock and self-reads the process environment context.
+    new LogBus(clock));
 }
 function isSupportedProtocolVersion(version) {
     return (typeof version === 'number' &&

package/dist/agent.d.ts

@@ -8,7 +8,7 @@ import type { ModelConnectivityInfo, ProviderHint } from './types/model-connecti
 import type { AgentIdentityStore } from './internal/agent-identity-store.js';
 import type { TelemetryRouter, TelemetrySlice } from './internal/telemetry-router.js';
 import type { HooksForAgent } from './types/redaction.js';
-import type { TelemetryBus, TelemetryEventCallback } from './types/telemetry-events.js';
+import { type TelemetryBus, type TelemetryEventCallback } from './types/telemetry-events.js';
 /**
  * Parent bus pair wired at construction time so an agent's events bubble upward into the manager's buses.
  */

package/dist/agent.js

@@ -2,10 +2,11 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-import { EventBus, LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
+import { LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
 import { toHarnessConfig } from './harness/harness-config.js';
 import { DefaultChatSession } from './chat-session.js';
 import { AgentSDKError, AgentSDKErrorType } from './errors.js';
+import { createTelemetryBus } from './types/telemetry-events.js';
 /**
  * Default implementation of {@link Agent} that delegates
  * agent and thread operations to an {@link AgentHarness}.
@@ -25,8 +26,10 @@ export class DefaultAgent {
     sessions = new Map();
     sessionSliceUnregisters = new Map();
     router;
-    telemetryBus = new EventBus();
-    logBus = new LogBus();
+    // Constructed in the constructor body so they use the injected `clock` (tests inject a StubClock for
+    // deterministic timestamps); env context is self-read from the process.
+    telemetryBus;
+    logBus;
     inboundUnsubs;
     parentUnsubs;
     clock;
@@ -67,6 +70,8 @@ export class DefaultAgent {
         this.identityStore = identityStore;
         this.router = router;
         this.clock = clock;
+        this.telemetryBus = createTelemetryBus(this.clock);
+        this.logBus = new LogBus(this.clock);
         this.idGenerator = idGenerator;
         this.inboundUnsubs = [inbound.telemetry.forwardTo(this.telemetryBus), inbound.log.forwardTo(this.logBus)];
         this.parentUnsubs = [this.telemetryBus.forwardTo(parent.telemetry), this.logBus.forwardTo(parent.log)];
@@ -283,11 +288,14 @@ export class DefaultAgent {
         }
         this.sessions.clear();
         await this.harness.destroyAgent(this.agentId);
-        this.telemetryBus.emit({
-            type: 'agent-destroyed',
-            timestamp: this.clock.now(),
-            agentId: this.agentId,
-        });
+        const agentDestroyedAt = this.clock.now();
+        // Tier-1 pair: share one tick across the telemetry event and its colocated log sibling.
+        this.telemetryBus.emitTelemetry({ type: 'agent-destroyed', agentId: this.agentId }, agentDestroyedAt);
+        this.logBus.emitLog({
+            level: 'info',
+            message: 'Agent destroyed',
+            context: { event_type: 'agent-destroyed', agentId: this.agentId },
+        }, agentDestroyedAt);
         for (const unsub of this.inboundUnsubs)
             unsub();
         for (const unsub of this.parentUnsubs)
@@ -347,12 +355,14 @@ export class DefaultAgent {
         }, getContextWindow, { clock: this.clock, idGenerator: this.idGenerator, persistRememberedRule });
         this.sessions.set(threadId, session);
         this.sessionSliceUnregisters.set(threadId, () => this.router.unregisterSession(threadId));
-        this.telemetryBus.emit({
-            type: 'session-created',
-            timestamp: this.clock.now(),
-            agentId: this.agentId,
-            threadId,
-        });
+        const sessionCreatedAt = this.clock.now();
+        // Tier-1 pair: share one tick across the telemetry event and its colocated log sibling.
+        this.telemetryBus.emitTelemetry({ type: 'session-created', agentId: this.agentId, threadId }, sessionCreatedAt);
+        this.logBus.emitLog({
+            level: 'info',
+            message: 'Chat session created',
+            context: { event_type: 'session-created', agentId: this.agentId, threadId },
+        }, sessionCreatedAt);
         return session;
     }
     detachSession(threadId, session) {

package/dist/chat-session.d.ts

@@ -4,7 +4,7 @@ import type { StreamOptions } from './harness/harness-config.js';
 import type { TelemetrySlice } from './internal/telemetry-router.js';
 import type { ChatEvent, ChatStreamResult } from './types/events.js';
 import type { Message, MessagePart } from './types/messages.js';
-import type { TelemetryBus, TelemetryEventCallback } from './types/telemetry-events.js';
+import { type TelemetryBus, type TelemetryEventCallback } from './types/telemetry-events.js';
 import type { ToolPolicyRule, ToolResultInfo } from './types/tools.js';
 import type { ContextUsage } from './types/usage.js';
 /**

package/dist/chat-session.js

@@ -4,6 +4,7 @@
  */
 import { backfillCreatedAt, EventBus, LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
 import { AgentSDKError, AgentSDKErrorType } from './errors.js';
+import { createTelemetryBus, } from './types/telemetry-events.js';
 /**
  * Default implementation of {@link ChatSession} that delegates all operations
  * to an {@link AgentHarness}. The session holds its agent ID and thread ID
@@ -14,8 +15,10 @@ export class DefaultChatSession {
     agentId;
     threadId;
     chatEventBus = new EventBus();
-    telemetryBus = new EventBus();
-    logBus = new LogBus();
+    // Constructed in the constructor body so they use the injected `clock` (tests inject a StubClock for
+    // deterministic timestamps); env context is self-read from the process.
+    telemetryBus;
+    logBus;
     inboundUnsubs;
     parentUnsubs;
     clock;
@@ -86,6 +89,8 @@ export class DefaultChatSession {
         this.clock = deps.clock ?? new RealClock();
         this.idGenerator = deps.idGenerator ?? new UUIDGenerator();
         this.persistRememberedRule = deps.persistRememberedRule;
+        this.telemetryBus = createTelemetryBus(this.clock);
+        this.logBus = new LogBus(this.clock);
         this.inboundUnsubs = [inbound.telemetry.forwardTo(this.telemetryBus), inbound.log.forwardTo(this.logBus)];
         this.parentUnsubs = [this.telemetryBus.forwardTo(parent.telemetry), this.logBus.forwardTo(parent.log)];
     }
@@ -229,24 +234,45 @@ export class DefaultChatSession {
         const finishedAt = this.clock.now();
         const durationMs = finishedAt.getTime() - startedAt.getTime();
         if (lastError !== undefined) {
-            this.telemetryBus.emit({
+            // Tier-1 pair: share one tick across the telemetry event and its colocated log sibling.
+            this.telemetryBus.emitTelemetry({
                 type: 'chat-stream-error',
-                timestamp: finishedAt,
                 agentId: this.agentId,
                 threadId: this.threadId,
                 durationMs,
                 error: lastError,
-            });
+            }, finishedAt);
+            this.logBus.emitLog({
+                level: 'error',
+                message: 'Chat stream failed',
+                context: {
+                    event_type: 'chat-stream-error',
+                    agentId: this.agentId,
+                    threadId: this.threadId,
+                    durationMs,
+                },
+                error: lastError,
+            }, finishedAt);
         }
         else {
-            this.telemetryBus.emit({
+            this.telemetryBus.emitTelemetry({
                 type: 'chat-stream-completed',
-                timestamp: finishedAt,
                 agentId: this.agentId,
                 threadId: this.threadId,
                 durationMs,
                 usage: finishUsage,
-            });
+            }, finishedAt);
+            this.logBus.emitLog({
+                level: 'info',
+                message: 'Chat stream completed',
+                context: {
+                    event_type: 'chat-stream-completed',
+                    agentId: this.agentId,
+                    threadId: this.threadId,
+                    durationMs,
+                    ...(finishUsage !== undefined ? { usage: finishUsage } : {}),
+                },
+            }, finishedAt);
         }
     }
     /**
@@ -420,12 +446,18 @@ export class DefaultChatSession {
         if (this.disposed) {
             return;
         }
-        this.telemetryBus.emit({
-            type: 'session-destroyed',
-            timestamp: this.clock.now(),
-            agentId: this.agentId,
-            threadId: this.threadId,
-        });
+        const sessionDestroyedAt = this.clock.now();
+        // Tier-1 pair: share one tick across the telemetry event and its colocated log sibling.
+        this.telemetryBus.emitTelemetry({ type: 'session-destroyed', agentId: this.agentId, threadId: this.threadId }, sessionDestroyedAt);
+        this.logBus.emitLog({
+            level: 'info',
+            message: 'Chat session destroyed',
+            context: {
+                event_type: 'session-destroyed',
+                agentId: this.agentId,
+                threadId: this.threadId,
+            },
+        }, sessionDestroyedAt);
         for (const unsub of this.inboundUnsubs)
             unsub();
         for (const unsub of this.parentUnsubs)
@@ -436,9 +468,10 @@ export class DefaultChatSession {
         this.disposed = true;
     }
     emitToolApprovalResolved(toolCallId, approved, policyWritten) {
-        this.telemetryBus.emit({
+        // No Tier-1 logBus sibling: tool-approval-resolved fires per gated
+        // tool call — interactive-UI signal, not on-call triage
+        this.telemetryBus.emitTelemetry({
             type: 'tool-approval-resolved',
-            timestamp: this.clock.now(),
             agentId: this.agentId,
             threadId: this.threadId,
             toolCallId,
@@ -476,9 +509,10 @@ export class DefaultChatSession {
     deriveToolTelemetry(event) {
         if (event.type === 'tool-call') {
             this.toolStartMs.set(event.toolCallId, this.clock.now().getTime());
-            this.telemetryBus.emit({
+            // No Tier-1 logBus sibling: tool-execution-started pairs 1:1 with
+            // tool-execution-completed; the completion (isError=true) is the triage signal
+            this.telemetryBus.emitTelemetry({
                 type: 'tool-execution-started',
-                timestamp: this.clock.now(),
                 agentId: this.agentId,
                 threadId: this.threadId,
                 toolCallId: event.toolCallId,
@@ -492,19 +526,40 @@ export class DefaultChatSession {
             if (start === undefined)
                 return;
             this.toolStartMs.delete(event.toolCallId);
-            this.telemetryBus.emit({
+            const completedAt = this.clock.now();
+            const durationMs = completedAt.getTime() - start;
+            const isError = event.isError === true;
+            this.telemetryBus.emitTelemetry({
                 type: 'tool-execution-completed',
-                timestamp: this.clock.now(),
                 agentId: this.agentId,
                 threadId: this.threadId,
                 toolCallId: event.toolCallId,
                 toolName: event.toolName,
-                durationMs: this.clock.now().getTime() - start,
-                isError: event.isError === true,
+                durationMs,
+                isError,
                 ...(event.error ? { error: event.error } : {}),
                 ...(event.annotations ? { annotations: event.annotations } : {}),
                 ...(event.serverName ? { serverName: event.serverName } : {}),
-            });
+            }, completedAt);
+            // Tier-1 logBus sibling only when isError=true; share the tick with the telemetry event.
+            if (isError) {
+                this.logBus.emitLog({
+                    level: 'error',
+                    message: 'Tool execution failed',
+                    context: {
+                        event_type: 'tool-execution-completed',
+                        agentId: this.agentId,
+                        threadId: this.threadId,
+                        toolCallId: event.toolCallId,
+                        toolName: event.toolName,
+                        durationMs,
+                        isError: true,
+                        ...(event.annotations ? { annotations: event.annotations } : {}),
+                        ...(event.serverName ? { serverName: event.serverName } : {}),
+                    },
+                    ...(event.error ? { error: event.error } : {}),
+                }, completedAt);
+            }
         }
         else if (event.type === 'tool-approval-request') {
             // Record the (toolName, serverName?) so a later settle with
@@ -523,9 +578,8 @@ export class DefaultChatSession {
                 toolName: event.bareToolName ?? event.toolCall.toolName,
                 ...(event.serverName ? { serverName: event.serverName } : {}),
             });
-            this.telemetryBus.emit({
+            this.telemetryBus.emitTelemetry({
                 type: 'tool-approval-requested',
-                timestamp: this.clock.now(),
                 agentId: this.agentId,
                 threadId: this.threadId,
                 toolCallId: event.toolCall.toolCallId,
@@ -574,13 +628,9 @@ export class DefaultChatSession {
      */
     emitChatStreamStarted(trigger) {
         const startedAt = this.clock.now();
-        this.telemetryBus.emit({
-            type: 'chat-stream-started',
-            timestamp: startedAt,
-            agentId: this.agentId,
-            threadId: this.threadId,
-            trigger,
-        });
+        // chat-stream-started pairs 1:1 with chat-stream-completed, which already carries outcomes.
+        // Pin the timestamp to `startedAt` (also threaded out for duration math), rather than re-reading the clock.
+        this.telemetryBus.emitTelemetry({ type: 'chat-stream-started', agentId: this.agentId, threadId: this.threadId, trigger }, startedAt);
         return startedAt;
     }
     /**
@@ -597,14 +647,20 @@ export class DefaultChatSession {
         this.chatEventBus.emit({ type: 'error', error });
         this.chatEventBus.emit({ type: 'finish', finishReason: 'error' });
         const finishedAt = this.clock.now();
-        this.telemetryBus.emit({
-            type: 'chat-stream-error',
-            timestamp: finishedAt,
-            agentId: this.agentId,
-            threadId: this.threadId,
-            durationMs: finishedAt.getTime() - startedAt.getTime(),
+        const durationMs = finishedAt.getTime() - startedAt.getTime();
+        // Tier-1 pair: share one tick across the telemetry event and its colocated log sibling.
+        this.telemetryBus.emitTelemetry({ type: 'chat-stream-error', agentId: this.agentId, threadId: this.threadId, durationMs, error }, finishedAt);
+        this.logBus.emitLog({
+            level: 'error',
+            message: 'Chat stream failed',
+            context: {
+                event_type: 'chat-stream-error',
+                agentId: this.agentId,
+                threadId: this.threadId,
+                durationMs,
+            },
             error,
-        });
+        }, finishedAt);
     }
     /**
      * issue #529 contract change: a settle call (`approveToolCall` /

package/dist/harness/harness-bus-owner.d.ts

@@ -1,5 +1,5 @@
-import { LogBus, type LogRecord, type Unsubscribe } from '@salesforce/agentic-common';
-import type { TelemetryEvent, TelemetryEventCallback } from '../types/telemetry-events.js';
+import { type Clock, type EnvironmentFields, LogBus, type LogRecord, type Unsubscribe } from '@salesforce/agentic-common';
+import { type TelemetryEvent, type TelemetryEventCallback } from '../types/telemetry-events.js';
 import type { WireCommunicationEvent, WireCommunicationEventCallback } from '../types/wire-communication-event.js';
 /**
  * Composition helper used by `AgentHarness` implementations to own telemetry and log buses.
@@ -16,6 +16,14 @@ export declare class HarnessBusOwner {
     private readonly logBus;
     private readonly wireBus;
     private disposed;
+    /**
+     * @param clock - Time source for event timestamps. Harnesses that construct their own event `timestamp`
+     *   (the common case) can leave this defaulted; the value is preserved regardless via the emit override.
+     * @param environment - Identity context stamped onto telemetry/log events. Defaults to reading the
+     *   process's generic identity env vars (production zero-wiring); tests pass an explicit context (e.g. `{}`)
+     *   for determinism.
+     */
+    constructor(clock?: Clock, environment?: EnvironmentFields);
     /**
      * Returns the log bus so harness implementations can hand it to pure helpers (e.g. message
      * mappers / event adapters) that need to emit structured logs. Returns `undefined` after

package/dist/harness/harness-bus-owner.js

@@ -2,8 +2,9 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-import { EventBus, LogBus } from '@salesforce/agentic-common';
+import { EventBus, LogBus, } from '@salesforce/agentic-common';
 import { AgentSDKError, AgentSDKErrorType } from '../errors.js';
+import { createTelemetryBus, } from '../types/telemetry-events.js';
 /**
  * Composition helper used by `AgentHarness` implementations to own telemetry and log buses.
  *
@@ -15,10 +16,24 @@ import { AgentSDKError, AgentSDKErrorType } from '../errors.js';
  * can reuse it.
  */
 export class HarnessBusOwner {
-    telemetryBus = new EventBus();
-    logBus = new LogBus();
+    // Env-aware origin buses stamp the process environment fields (plus preserve the harness-supplied
+    // timestamp) onto every telemetry event / log record emitted here. The wire bus is intentionally a plain
+    // EventBus — wire-communication events carry no environment context.
+    telemetryBus;
+    logBus;
     wireBus = new EventBus();
     disposed = false;
+    /**
+     * @param clock - Time source for event timestamps. Harnesses that construct their own event `timestamp`
+     *   (the common case) can leave this defaulted; the value is preserved regardless via the emit override.
+     * @param environment - Identity context stamped onto telemetry/log events. Defaults to reading the
+     *   process's generic identity env vars (production zero-wiring); tests pass an explicit context (e.g. `{}`)
+     *   for determinism.
+     */
+    constructor(clock, environment) {
+        this.telemetryBus = createTelemetryBus(clock, environment);
+        this.logBus = new LogBus(clock, environment);
+    }
     /**
      * Returns the log bus so harness implementations can hand it to pure helpers (e.g. message
      * mappers / event adapters) that need to emit structured logs. Returns `undefined` after
@@ -65,11 +80,18 @@ export class HarnessBusOwner {
     }
     emitTelemetry(event) {
         this.assertNotDisposed();
-        this.telemetryBus.emit(event);
+        // Harnesses construct a full event with their own `timestamp` but do NOT set env-identity fields — those
+        // are bus-owned, stamped by the env-aware bus below. We split off `timestamp` (passed as the override so
+        // the harness's real emit time is preserved) and forward the rest as the payload. (The bus folds the
+        // payload last, so a harness that DID set an env field would override the bus's value; no harness does,
+        // so this is moot — env identity is the bus's responsibility by design.)
+        const { timestamp, ...payload } = event;
+        this.telemetryBus.emitTelemetry(payload, timestamp);
     }
     emitLog(record) {
         this.assertNotDisposed();
-        this.logBus.emit(record);
+        const { timestamp, ...payload } = record;
+        this.logBus.emitLog(payload, timestamp);
     }
     logDebug(message, context) {
         this.assertNotDisposed();

package/dist/index.d.ts

@@ -25,6 +25,8 @@ export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
 export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent, ChatStreamErrorEvent, ChatStreamStartedEvent, ChatStreamTrigger, LlmRetryEvent, McpServerDiscoveryCompletedEvent, McpServerDiscoveryFailedEvent, McpServerDiscoveryStartedEvent, McpServerStatusChangedEvent, SessionCreatedEvent, SessionDestroyedEvent, TelemetryEvent, TelemetryEventCallback, ToolApprovalPolicyResolvedEvent, ToolApprovalRequestedEvent, ToolApprovalResolvedEvent, ToolExecutionCompletedEvent, ToolExecutionStartedEvent, } from './types/telemetry-events.js';
 export type { LogLevel, LogRecord, Unsubscribe } from '@salesforce/agentic-common';
+export type { EnvironmentFields } from '@salesforce/agentic-common';
+export { readEnvironmentContext, resolveFeatureId } from '@salesforce/agentic-common';
 export { resolveMcpServerHeaders } from './mcp-auth.js';
 export type { OrgConnection, OrgConnectionFactory } from '@salesforce/agentic-common';
 export type { JSONWebToken, JWTOptions, RequiredJWTHeaders, RequiredJWTPayload } from '@salesforce/agentic-common';

package/dist/index.js

@@ -21,6 +21,7 @@ export { ApiKeyConnectivityResolver } from './api-key-connectivity-resolver.js';
 export { WireCommunicationFileWriter, } from './wire-communication-file-writer.js';
 // ── Errors ───────────────────────────────────────────────────────────
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
+export { readEnvironmentContext, resolveFeatureId } from '@salesforce/agentic-common';
 // ── MCP Auth ────────────────────────────────────────────────────────
 export { resolveMcpServerHeaders } from './mcp-auth.js';
 export { Workspace } from './workspace.js';

package/dist/internal/telemetry-router.d.ts

@@ -1,14 +1,19 @@
-import { LogBus } from '@salesforce/agentic-common';
+import { EventBus, LogBus } from '@salesforce/agentic-common';
 import type { AgentHarness } from '../harness/agent-harness.js';
-import type { TelemetryBus } from '../types/telemetry-events.js';
+import type { TelemetryEvent } from '../types/telemetry-events.js';
 /**
  * A pair of buses (telemetry + log) scoped to a single agent, session, or the unrouted catch-all.
  *
  * `DefaultAgent` and `DefaultChatSession` receive their slice at construction time and wire `forwardTo()`
  * from the slice bus into their own bus so events bubble upward through the hierarchy.
+ *
+ * Slice buses are **forward-only**: they re-emit events routed from the harness (or forwarded up from a child)
+ * and never construct events themselves, so they carry no environment context — a plain `EventBus<TelemetryEvent>`
+ * and a zero-context `LogBus`. Environment stamping happens once, on the origin bus that constructs the event
+ * (a harness `HarnessBusOwner` bus, or a manager/agent/session's own telemetry/log bus).
  */
 export type TelemetrySlice = {
-    readonly telemetry: TelemetryBus;
+    readonly telemetry: EventBus<TelemetryEvent>;
     readonly log: LogBus;
 };
 /**

package/dist/internal/telemetry-router.js

@@ -122,8 +122,11 @@ export class TelemetryRouter {
     }
     static createSlice() {
         return {
+            // Forward-only buses: they only re-emit routed/forwarded (already-stamped) events, never originate
+            // one, so the LogBus is explicitly zero-context — no `process.env` read, and no risk of a future
+            // origin-method call re-stamping a forwarded record.
             telemetry: new EventBus(),
-            log: new LogBus(),
+            log: new LogBus(undefined, {}),
         };
     }
 }

package/dist/types/telemetry-events.d.ts

@@ -1,4 +1,4 @@
-import type { EventBus } from '@salesforce/agentic-common';
+import { BaseTelemetryEventBus, type EnvironmentAwareEvent } from '@salesforce/agentic-common';
 import type { McpServerErrorDetail, McpServerStatus, McpToolAnnotations } from '../mcp-config.js';
 import type { Decision, ToolPolicyRule } from './tools.js';
 import type { UsageMetadata } from './usage.js';
@@ -8,10 +8,13 @@ import type { UsageMetadata } from './usage.js';
  * The union is stable public API; consumers subscribe via `onTelemetry()` on `AgentManager`, `Agent`, or
  * `ChatSession`. Routing fields (`agentId`, `threadId`) are typed on the variants that carry them so
  * internal dispatch does not need to reach into a context bag.
+ *
+ * Every variant extends {@link EnvironmentAwareEvent}, so it carries `timestamp` plus the flat, optional
+ * environment-context identity fields (`instanceType`, `instanceId`, `orgId`, `userId`, `featureId`) — stamped
+ * by the origin {@link TelemetryBus}, never mutated on by downstream subscribers.
  */
-type Base<T extends string> = {
+type Base<T extends string> = EnvironmentAwareEvent & {
     type: T;
-    timestamp: Date;
 };
 export type AgentCreatedEvent = Base<'agent-created'> & {
     agentId: string;
@@ -194,5 +197,37 @@ export type LlmRetryEvent = Base<'llm-retry'> & {
 };
 export type TelemetryEvent = AgentCreatedEvent | AgentDestroyedEvent | SessionCreatedEvent | SessionDestroyedEvent | ChatStreamStartedEvent | ChatStreamCompletedEvent | ChatStreamErrorEvent | ToolExecutionStartedEvent | ToolExecutionCompletedEvent | ToolApprovalRequestedEvent | ToolApprovalResolvedEvent | ToolApprovalPolicyResolvedEvent | McpServerDiscoveryStartedEvent | McpServerDiscoveryCompletedEvent | McpServerDiscoveryFailedEvent | McpServerStatusChangedEvent | LlmRetryEvent;
 export type TelemetryEventCallback = (event: TelemetryEvent) => void;
-export type TelemetryBus = EventBus<TelemetryEvent>;
+/**
+ * The domain fields a caller supplies to {@link TelemetryBus.emitTelemetry} — a {@link TelemetryEvent} minus the
+ * bus-owned base fields (`timestamp` and the environment-identity fields). Distributive over the union so each
+ * variant keeps its own domain fields. Subscribers still receive the full `TelemetryEvent`; the bus adds the
+ * base fields at the origin.
+ */
+export type TelemetryEventInput = TelemetryEvent extends infer T ? T extends EnvironmentAwareEvent ? Omit<T, keyof EnvironmentAwareEvent> : never : never;
+/**
+ * The SDK's telemetry bus: the reusable {@link BaseTelemetryEventBus} from `@salesforce/agentic-common`
+ * specialized to the SDK's {@link TelemetryEvent} union. Callers pass only a variant's domain fields to
+ * {@link emitTelemetry}; the bus builds the full event through the inherited `super`-chained `create*Event`
+ * builders, stamping `timestamp` (from the injected clock, or a pinned override) and the process environment
+ * context. Subscribers receive the full `TelemetryEvent`.
+ *
+ * Because the SDK's variants are concrete, `{ ...base, ...payload }` is a provable `TelemetryEvent` — no type
+ * assertion. Future harness-specific telemetry would follow the same pattern with its own union subclass.
+ */
+export declare class TelemetryBus extends BaseTelemetryEventBus<TelemetryEvent> {
+    /**
+     * Emit a telemetry event from its domain fields (`type` plus variant fields). The bus builds the full event
+     * off the `super`-chained env-aware base — the payload already carries its own `type`, so this folds it onto
+     * the base rather than calling `createBaseTelemetryEvent` (which is for concrete `emit<Variant>` sugar that
+     * hardcodes the type). Stamps `timestamp` (injected clock, or a pinned override) and the environment
+     * context. Subscribers receive the full `TelemetryEvent`.
+     *
+     * Narrows the base-class `emitTelemetry(event: E)` to accept only domain fields ({@link TelemetryEventInput}
+     * omits the bus-owned base fields). A caller passing a full `TelemetryEvent` still type-checks — the extra
+     * base fields are just re-spread and harmlessly overwritten by the freshly-built base.
+     */
+    emitTelemetry(event: TelemetryEventInput, timestamp?: Date): void;
+}
+/** Constructs a {@link TelemetryBus}. Mirrors `new LogBus(...)` from `@salesforce/agentic-common`. */
+export declare function createTelemetryBus(...args: ConstructorParameters<typeof TelemetryBus>): TelemetryBus;
 export {};

package/dist/types/telemetry-events.js

@@ -2,5 +2,35 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-export {};
+import { BaseTelemetryEventBus } from '@salesforce/agentic-common';
+/**
+ * The SDK's telemetry bus: the reusable {@link BaseTelemetryEventBus} from `@salesforce/agentic-common`
+ * specialized to the SDK's {@link TelemetryEvent} union. Callers pass only a variant's domain fields to
+ * {@link emitTelemetry}; the bus builds the full event through the inherited `super`-chained `create*Event`
+ * builders, stamping `timestamp` (from the injected clock, or a pinned override) and the process environment
+ * context. Subscribers receive the full `TelemetryEvent`.
+ *
+ * Because the SDK's variants are concrete, `{ ...base, ...payload }` is a provable `TelemetryEvent` — no type
+ * assertion. Future harness-specific telemetry would follow the same pattern with its own union subclass.
+ */
+export class TelemetryBus extends BaseTelemetryEventBus {
+    /**
+     * Emit a telemetry event from its domain fields (`type` plus variant fields). The bus builds the full event
+     * off the `super`-chained env-aware base — the payload already carries its own `type`, so this folds it onto
+     * the base rather than calling `createBaseTelemetryEvent` (which is for concrete `emit<Variant>` sugar that
+     * hardcodes the type). Stamps `timestamp` (injected clock, or a pinned override) and the environment
+     * context. Subscribers receive the full `TelemetryEvent`.
+     *
+     * Narrows the base-class `emitTelemetry(event: E)` to accept only domain fields ({@link TelemetryEventInput}
+     * omits the bus-owned base fields). A caller passing a full `TelemetryEvent` still type-checks — the extra
+     * base fields are just re-spread and harmlessly overwritten by the freshly-built base.
+     */
+    emitTelemetry(event, timestamp) {
+        this.emit({ ...this.createEnvironmentAwareEvent(timestamp), ...event });
+    }
+}
+/** Constructs a {@link TelemetryBus}. Mirrors `new LogBus(...)` from `@salesforce/agentic-common`. */
+export function createTelemetryBus(...args) {
+    return new TelemetryBus(...args);
+}
 //# sourceMappingURL=telemetry-events.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -43,17 +43,17 @@
     "LICENSE.txt"
   ],
   "dependencies": {
-    "@salesforce/agentic-common": "0.13.0"
+    "@salesforce/agentic-common": "0.14.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.36.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.39.0",
-    "@salesforce/sfdx-agent-harness-openai": "0.5.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.38.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.41.0",
+    "@salesforce/sfdx-agent-harness-openai": "0.7.0",
     "@types/node": "^22.20.0",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.22",
-    "eslint": "^10.7.0",
+    "eslint": "^10.8.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",