@salesforce/sfdx-agent-sdk 0.1.0

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

@@ -0,0 +1,34 @@
+import { LogBus, type LogRecord, type Unsubscribe } from '@salesforce/agentic-common';
+import type { TelemetryEvent, TelemetryEventCallback } from '../types/telemetry-events.js';
+/**
+ * Composition helper used by `AgentHarness` implementations to own telemetry and log buses.
+ *
+ * Harnesses instantiate one of these as a private field and delegate `onTelemetry()` / `onLog()` to it; they
+ * then emit events by calling the owner's `emitTelemetry()` / `logDebug()` / etc. Dispose clears both buses;
+ * further calls throw `AgentSDKError('DISPOSED')`.
+ *
+ * Exported from the public `index.ts` so third-party `AgentHarness` implementations in sibling packages
+ * can reuse it.
+ */
+export declare class HarnessBusOwner {
+    private readonly telemetryBus;
+    private readonly logBus;
+    private disposed;
+    /**
+     * 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
+     * `dispose()` so callers in late-shutdown paths (e.g. teardown races) can fall through to a
+     * no-op rather than catching `DISPOSED`.
+     */
+    getLogBus(): LogBus | undefined;
+    onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
+    onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    emitTelemetry(event: TelemetryEvent): void;
+    emitLog(record: LogRecord): void;
+    logDebug(message: string, context?: Record<string, unknown>): void;
+    logInfo(message: string, context?: Record<string, unknown>): void;
+    logWarn(message: string, context?: Record<string, unknown>, error?: Error): void;
+    logError(message: string, error?: Error, context?: Record<string, unknown>): void;
+    dispose(): void;
+    private assertNotDisposed;
+}

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

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { EventBus, LogBus } from '@salesforce/agentic-common';
+import { AgentSDKError, AgentSDKErrorType } from '../errors.js';
+/**
+ * Composition helper used by `AgentHarness` implementations to own telemetry and log buses.
+ *
+ * Harnesses instantiate one of these as a private field and delegate `onTelemetry()` / `onLog()` to it; they
+ * then emit events by calling the owner's `emitTelemetry()` / `logDebug()` / etc. Dispose clears both buses;
+ * further calls throw `AgentSDKError('DISPOSED')`.
+ *
+ * Exported from the public `index.ts` so third-party `AgentHarness` implementations in sibling packages
+ * can reuse it.
+ */
+export class HarnessBusOwner {
+    telemetryBus = new EventBus();
+    logBus = new LogBus();
+    disposed = false;
+    /**
+     * 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
+     * `dispose()` so callers in late-shutdown paths (e.g. teardown races) can fall through to a
+     * no-op rather than catching `DISPOSED`.
+     */
+    getLogBus() {
+        if (this.disposed)
+            return undefined;
+        return this.logBus;
+    }
+    onTelemetry(callback) {
+        this.assertNotDisposed();
+        return this.telemetryBus.on(callback);
+    }
+    onLog(callback) {
+        this.assertNotDisposed();
+        return this.logBus.on(callback);
+    }
+    emitTelemetry(event) {
+        this.assertNotDisposed();
+        this.telemetryBus.emit(event);
+    }
+    emitLog(record) {
+        this.assertNotDisposed();
+        this.logBus.emit(record);
+    }
+    logDebug(message, context) {
+        this.assertNotDisposed();
+        this.logBus.debug(message, context);
+    }
+    logInfo(message, context) {
+        this.assertNotDisposed();
+        this.logBus.info(message, context);
+    }
+    logWarn(message, context, error) {
+        this.assertNotDisposed();
+        this.logBus.warn(message, context, error);
+    }
+    logError(message, error, context) {
+        this.assertNotDisposed();
+        this.logBus.error(message, error, context);
+    }
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.telemetryBus.dispose();
+        this.logBus.dispose();
+        this.disposed = true;
+    }
+    assertNotDisposed() {
+        if (this.disposed) {
+            throw new AgentSDKError('Harness buses have been disposed.', AgentSDKErrorType.DISPOSED);
+        }
+    }
+}
+//# sourceMappingURL=harness-bus-owner.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"harness-bus-owner.js","sourceRoot":"","sources":["../../src/harness/harness-bus-owner.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAoC,MAAM,4BAA4B,CAAC;AAChG,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGhE;;;;;;;;;GASG;AACH,MAAM,OAAO,eAAe;IACP,YAAY,GAAiB,IAAI,QAAQ,EAAkB,CAAC;IAC5D,MAAM,GAAW,IAAI,MAAM,EAAE,CAAC;IACvC,QAAQ,GAAY,KAAK,CAAC;IAElC;;;;;OAKG;IACH,SAAS;QACL,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,SAAS,CAAC;QACpC,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,WAAW,CAAC,QAAgC;QACxC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,QAAqC;QACvC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED,aAAa,CAAC,KAAqB;QAC/B,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,OAAO,CAAC,MAAiB;QACrB,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAED,QAAQ,CAAC,OAAe,EAAE,OAAiC;QACvD,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,OAAO,CAAC,OAAe,EAAE,OAAiC;QACtD,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,OAAe,EAAE,OAAiC,EAAE,KAAa;QACrE,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;IAED,QAAQ,CAAC,OAAe,EAAE,KAAa,EAAE,OAAiC;QACtE,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO;QACH,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,OAAO;QACX,CAAC;QACD,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACzB,CAAC;IAEO,iBAAiB;QACrB,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,MAAM,IAAI,aAAa,CAAC,mCAAmC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QAC7F,CAAC;IACL,CAAC;CACJ"}

package/dist/harness/harness-config.d.ts

@@ -0,0 +1,89 @@
+import type { ToolDefinition } from '../types/tools.js';
+import type { MCPConfiguration } from '../mcp-config.js';
+import type { JSONWebToken, ModelName } from '@salesforce/llm-gateway-sdk';
+/**
+ * Configuration for an agent's behavior and capabilities.
+ * This excludes identity; `agentId` is handled separately.
+ */
+export type AgentConfig = {
+    /**
+     * Optional org alias (or username) to run this agent under.
+     *
+     * If omitted, the agent resolves auth in this order:
+     * - If `projectRoot` is an SFDX project and has a local `target-org` set, use that org.
+     * - Otherwise, use the default org configured on the machine.
+     */
+    orgAlias?: string;
+    /** The model to use for this agent. */
+    modelId?: ModelName;
+    /** Human-readable name for the agent. */
+    name?: string;
+    /** Description of the agent's purpose. ACP/OASF-ready metadata. */
+    description?: string;
+    /** System instructions defining the agent's behavior. */
+    instructions?: string;
+    /** Custom tools available to this agent. */
+    tools?: ToolDefinition[];
+    /** MCP server connections providing additional tools. */
+    mcpServers?: MCPConfiguration;
+    /** Filesystem paths to skill directories. Supports paths relative to the project root and absolute paths. */
+    skills?: string[];
+};
+/**
+ * Harness-facing configuration for creating/updating an agent.
+ *
+ * This is derived from {@link AgentConfig} but intentionally excludes org resolution concerns
+ * (e.g. `orgAlias`) and includes resolved runtime artifacts (`orgJwt`) that the harness needs.
+ */
+export type HarnessAgentConfig = Omit<AgentConfig, 'orgAlias'> & {
+    /**
+     * Self-refreshing JWT for the resolved org. Harness implementations SHOULD pass this
+     * to {@link resolveMcpServerHeaders} when mapping remote MCP server configs to their native
+     * transport format, so that Salesforce Hosted MCP Servers receive automatic auth injection.
+     */
+    orgJwt?: JSONWebToken;
+};
+/**
+ * Converts a consumer-facing {@link AgentConfig} into a {@link HarnessAgentConfig}
+ * ready for the harness layer.
+ *
+ * Strips `orgAlias` since org resolution is handled above the harness and attaches
+ * the resolved `orgJwt` so harness implementations can use {@link resolveMcpServerHeaders}
+ * to inject auth for Salesforce Hosted MCP Servers.
+ */
+export declare function toHarnessConfig(config: AgentConfig, orgJwt?: JSONWebToken): HarnessAgentConfig;
+/**
+ * Per-call options controlling streaming behavior.
+ */
+export type StreamOptions = {
+    /** Signal to abort the streaming operation. */
+    abortSignal?: AbortSignal;
+    /**
+     * When `true`, the harness requires human approval before executing any
+     * native tool (e.g., MCP tools). The stream emits a `tool-approval-request`
+     * event and suspends until the consumer calls `approveToolCall()` or
+     * `declineToolCall()`.
+     *
+     * Does not affect consumer-executed tools (those defined via `AgentConfig.tools`
+     * without an execute handler) — the consumer already controls execution for
+     * those via `submitToolResult()`.
+     */
+    requireToolApproval?: boolean;
+    /**
+     * Maximum number of LLM call steps the agent may take per `stream()` invocation.
+     * Each step is one LLM call (which may produce text, tool calls, or both).
+     *
+     * Defaults to {@link DEFAULT_MAX_STEPS} when omitted.
+     * Must be at least 1.
+     */
+    maxSteps?: number;
+};
+/**
+ * Default maximum steps for a single agent stream invocation.
+ *
+ * Set high enough to be effectively unlimited for real tasks — the practical
+ * ceiling is the context window and cost, not this counter. This exists only
+ * as a safety net against infinite tool-retry loops. Mastra requires a finite
+ * value (its internal default is only 5, far too low for agentic workflows).
+ */
+export declare const DEFAULT_MAX_STEPS = 1024;

package/dist/harness/harness-config.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Converts a consumer-facing {@link AgentConfig} into a {@link HarnessAgentConfig}
+ * ready for the harness layer.
+ *
+ * Strips `orgAlias` since org resolution is handled above the harness and attaches
+ * the resolved `orgJwt` so harness implementations can use {@link resolveMcpServerHeaders}
+ * to inject auth for Salesforce Hosted MCP Servers.
+ */
+export function toHarnessConfig(config, orgJwt) {
+    const { orgAlias: _, ...rest } = config;
+    return { ...rest, orgJwt };
+}
+/**
+ * Default maximum steps for a single agent stream invocation.
+ *
+ * Set high enough to be effectively unlimited for real tasks — the practical
+ * ceiling is the context window and cost, not this counter. This exists only
+ * as a safety net against infinite tool-retry loops. Mastra requires a finite
+ * value (its internal default is only 5, far too low for agentic workflows).
+ */
+export const DEFAULT_MAX_STEPS = 1024;
+//# sourceMappingURL=harness-config.js.map

package/dist/harness/harness-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness-config.js","sourceRoot":"","sources":["../../src/harness/harness-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyDH;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAmB,EAAE,MAAqB;IACtE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;IACxC,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,CAAC;AAC/B,CAAC;AA+BD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC"}

package/dist/harness/harness-factory.d.ts

@@ -0,0 +1,21 @@
+import type { AgentHarness } from './agent-harness.js';
+/**
+ * Constructs an {@link AgentHarness} on demand.
+ *
+ * The factory advertises its identity and the SDK-to-harness protocol version
+ * it implements so the SDK can reject incompatible harness packages **before**
+ * paying the cost of {@link HarnessFactory.create} (which typically opens
+ * persistent storage and connects to MCP servers).
+ *
+ * After the harness is constructed, the SDK additionally verifies that the
+ * returned harness reports the same `protocolVersion` as the factory. This
+ * guards against a factory that lies about its version or a harness package
+ * whose runtime drifts from its packaging metadata.
+ */
+export interface HarnessFactory {
+    /** Unique identifier for the harness type this factory builds (e.g., `'mastra'`). */
+    readonly harnessId: string;
+    /** SDK-to-harness protocol version implemented by the harness this factory builds. */
+    readonly protocolVersion: number;
+    create(storageRootFolder: string): Promise<AgentHarness>;
+}

package/dist/harness/harness-factory.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export {};
+//# sourceMappingURL=harness-factory.js.map

package/dist/harness/harness-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness-factory.js","sourceRoot":"","sources":["../../src/harness/harness-factory.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/harness/index.d.ts

@@ -0,0 +1,4 @@
+export type { AgentHarness } from './agent-harness.js';
+export type { HarnessFactory } from './harness-factory.js';
+export type { AgentConfig, StreamOptions } from './harness-config.js';
+export { toHarnessConfig, DEFAULT_MAX_STEPS } from './harness-config.js';

package/dist/harness/index.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export { toHarnessConfig, DEFAULT_MAX_STEPS } from './harness-config.js';
+//# sourceMappingURL=index.js.map

package/dist/harness/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/harness/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export type { Message, MessagePart } from './types/messages.js';
+export type { ChatEvent, StartEvent, TextDeltaEvent, ReasoningDeltaEvent, ToolCallEvent, ToolApprovalRequestEvent, ToolResultEvent, StepStartEvent, StepFinishEvent, ErrorEvent, FinishEvent, ChatStreamResult, } from './types/events.js';
+export type { ToolDefinition, ToolCallInfo, ToolResultInfo } from './types/tools.js';
+export type { FinishReason, UsageMetadata } from './types/usage.js';
+export type { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness/harness-config.js';
+export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
+export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpServerInfo, } from './mcp-config.js';
+export { McpServerStatus } from './mcp-config.js';
+export { ModelName } from '@salesforce/llm-gateway-sdk';
+export { SfApiEnv } from '@salesforce/agentic-common';
+export { AgentManager, createAgentManager } from './agent-manager.js';
+export { type Agent } from './agent.js';
+export { type ChatSession, type ChatOptions } from './chat-session.js';
+export type { AgentConnectivityResolver, ResolvedConnectivity } from './agent-connectivity-resolver.js';
+export type { AgentHarness, HarnessFactory } from './harness/index.js';
+export { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
+export { HarnessBusOwner } from './harness/harness-bus-owner.js';
+export { AgentSDKError, AgentSDKErrorType } from './errors.js';
+export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent, ChatStreamErrorEvent, ChatStreamStartedEvent, ChatStreamTrigger, McpServerDiscoveryCompletedEvent, McpServerDiscoveryFailedEvent, McpServerDiscoveryStartedEvent, SessionCreatedEvent, SessionDestroyedEvent, TelemetryEvent, TelemetryEventCallback, ToolApprovalRequestedEvent, ToolApprovalResolvedEvent, ToolExecutionCompletedEvent, ToolExecutionStartedEvent, } from './types/telemetry-events.js';
+export type { LogLevel, LogRecord, Unsubscribe } from '@salesforce/agentic-common';
+export { resolveMcpServerHeaders } from './mcp-auth.js';
+export type { OrgConnection, OrgConnectionFactory } from '@salesforce/agentic-common';
+export { Workspace } from './workspace.js';

package/dist/index.js

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
+export { McpServerStatus } from './mcp-config.js';
+export { ModelName } from '@salesforce/llm-gateway-sdk';
+export { SfApiEnv } from '@salesforce/agentic-common';
+// ── Agent Layer ─────────────────────────────────────────────────────
+export { AgentManager, createAgentManager } from './agent-manager.js';
+export {} from './agent.js';
+export {} from './chat-session.js';
+export { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
+export { HarnessBusOwner } from './harness/harness-bus-owner.js';
+// ── Errors ───────────────────────────────────────────────────────────
+export { AgentSDKError, AgentSDKErrorType } from './errors.js';
+// ── MCP Auth ────────────────────────────────────────────────────────
+export { resolveMcpServerHeaders } from './mcp-auth.js';
+export { Workspace } from './workspace.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuBH,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAQhE,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAEtD,uEAAuE;AACvE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAc,MAAM,YAAY,CAAC;AACxC,OAAO,EAAsC,MAAM,mBAAmB,CAAC;AAKvE,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEjE,wEAAwE;AACxE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AA4B/D,uEAAuE;AACvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAIxD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

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

@@ -0,0 +1,41 @@
+import { LogBus } from '@salesforce/agentic-common';
+import type { AgentHarness } from '../harness/agent-harness.js';
+import type { TelemetryBus } 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.
+ */
+export type TelemetrySlice = {
+    readonly telemetry: TelemetryBus;
+    readonly log: LogBus;
+};
+/**
+ * Splits a single harness's telemetry and log streams into per-agent, per-session, and unrouted sub-streams.
+ *
+ * The router is the only component that subscribes directly to the harness's buses. It examines each event's
+ * routing fields (`agentId` / `threadId` for telemetry; `context.agentId` / `context.threadId` for logs) and
+ * emits onto the corresponding slice bus. `DefaultAgent` / `DefaultChatSession` subscribe to their slice via
+ * `forwardTo()` — there is no downward dispatch from the Manager back into children.
+ *
+ * The router and its slices are internal to this package; consumers subscribe via the public
+ * `onTelemetry()` / `onLog()` methods on `AgentManager` / `Agent` / `ChatSession`.
+ */
+export declare class TelemetryRouter {
+    private readonly agentSlices;
+    private readonly sessionSlices;
+    private readonly unroutedSlice;
+    private readonly harnessUnsubs;
+    private disposed;
+    constructor(harness: Pick<AgentHarness, 'onTelemetry' | 'onLog'>);
+    get unrouted(): TelemetrySlice;
+    registerAgent(agentId: string): TelemetrySlice;
+    unregisterAgent(agentId: string): void;
+    registerSession(threadId: string): TelemetrySlice;
+    unregisterSession(threadId: string): void;
+    dispose(): void;
+    private routeTelemetry;
+    private routeLog;
+    private static createSlice;
+}

package/dist/internal/telemetry-router.js

@@ -0,0 +1,128 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { EventBus, LogBus } from '@salesforce/agentic-common';
+/**
+ * Splits a single harness's telemetry and log streams into per-agent, per-session, and unrouted sub-streams.
+ *
+ * The router is the only component that subscribes directly to the harness's buses. It examines each event's
+ * routing fields (`agentId` / `threadId` for telemetry; `context.agentId` / `context.threadId` for logs) and
+ * emits onto the corresponding slice bus. `DefaultAgent` / `DefaultChatSession` subscribe to their slice via
+ * `forwardTo()` — there is no downward dispatch from the Manager back into children.
+ *
+ * The router and its slices are internal to this package; consumers subscribe via the public
+ * `onTelemetry()` / `onLog()` methods on `AgentManager` / `Agent` / `ChatSession`.
+ */
+export class TelemetryRouter {
+    agentSlices = new Map();
+    sessionSlices = new Map();
+    unroutedSlice;
+    harnessUnsubs = [];
+    disposed = false;
+    constructor(harness) {
+        this.unroutedSlice = TelemetryRouter.createSlice();
+        this.harnessUnsubs.push(harness.onTelemetry((event) => this.routeTelemetry(event)));
+        this.harnessUnsubs.push(harness.onLog((record) => this.routeLog(record)));
+    }
+    get unrouted() {
+        return this.unroutedSlice;
+    }
+    registerAgent(agentId) {
+        let slice = this.agentSlices.get(agentId);
+        if (!slice) {
+            slice = TelemetryRouter.createSlice();
+            this.agentSlices.set(agentId, slice);
+        }
+        return slice;
+    }
+    unregisterAgent(agentId) {
+        const slice = this.agentSlices.get(agentId);
+        if (slice) {
+            slice.telemetry.dispose();
+            slice.log.dispose();
+            this.agentSlices.delete(agentId);
+        }
+    }
+    registerSession(threadId) {
+        let slice = this.sessionSlices.get(threadId);
+        if (!slice) {
+            slice = TelemetryRouter.createSlice();
+            this.sessionSlices.set(threadId, slice);
+        }
+        return slice;
+    }
+    unregisterSession(threadId) {
+        const slice = this.sessionSlices.get(threadId);
+        if (slice) {
+            slice.telemetry.dispose();
+            slice.log.dispose();
+            this.sessionSlices.delete(threadId);
+        }
+    }
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        for (const unsub of this.harnessUnsubs) {
+            unsub();
+        }
+        this.harnessUnsubs.length = 0;
+        for (const slice of this.agentSlices.values()) {
+            slice.telemetry.dispose();
+            slice.log.dispose();
+        }
+        this.agentSlices.clear();
+        for (const slice of this.sessionSlices.values()) {
+            slice.telemetry.dispose();
+            slice.log.dispose();
+        }
+        this.sessionSlices.clear();
+        this.unroutedSlice.telemetry.dispose();
+        this.unroutedSlice.log.dispose();
+        this.disposed = true;
+    }
+    routeTelemetry(event) {
+        const threadId = 'threadId' in event ? event.threadId : undefined;
+        if (threadId !== undefined) {
+            const sessionSlice = this.sessionSlices.get(threadId);
+            if (sessionSlice) {
+                sessionSlice.telemetry.emit(event);
+                return;
+            }
+        }
+        const agentSlice = this.agentSlices.get(event.agentId);
+        if (agentSlice) {
+            agentSlice.telemetry.emit(event);
+            return;
+        }
+        this.unroutedSlice.telemetry.emit(event);
+    }
+    routeLog(record) {
+        const context = record.context;
+        const threadId = typeof context?.['threadId'] === 'string' ? context['threadId'] : undefined;
+        if (threadId !== undefined) {
+            const sessionSlice = this.sessionSlices.get(threadId);
+            if (sessionSlice) {
+                sessionSlice.log.emit(record);
+                return;
+            }
+        }
+        const agentId = typeof context?.['agentId'] === 'string' ? context['agentId'] : undefined;
+        if (agentId !== undefined) {
+            const agentSlice = this.agentSlices.get(agentId);
+            if (agentSlice) {
+                agentSlice.log.emit(record);
+                return;
+            }
+        }
+        this.unroutedSlice.log.emit(record);
+    }
+    static createSlice() {
+        return {
+            telemetry: new EventBus(),
+            log: new LogBus(),
+        };
+    }
+}
+//# sourceMappingURL=telemetry-router.js.map

package/dist/internal/telemetry-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-router.js","sourceRoot":"","sources":["../../src/internal/telemetry-router.ts"],"names":[],"mappings":"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"}

package/dist/mcp-auth.d.ts

@@ -0,0 +1,20 @@
+import type { JSONWebToken } from '@salesforce/llm-gateway-sdk';
+/**
+ * Returns true if the URL matches a Salesforce Hosted MCP Server endpoint.
+ * Covers all environments (prod, dev, test, perf, stage) and all API versions
+ * (beta: v1-beta.2, GA: v1, future versions).
+ */
+export declare function isSalesforcePlatformMcpUrl(url: string | URL): boolean;
+/**
+ * Resolves the final headers for an MCP server request.
+ *
+ * For Salesforce Hosted MCP Server URLs, injects an `Authorization: Bearer <token>`
+ * header (via `orgJwt.getValue()`) when no explicit Authorization header already exists.
+ * For all other URLs the headers are returned unmodified.
+ *
+ * @param url - The MCP server URL.
+ * @param orgJwt - The org's self-refreshing JWT (from HarnessAgentConfig.orgJwt).
+ * @param headers - Existing headers configured on the server.
+ * @returns The resolved headers — original headers plus any injected auth.
+ */
+export declare function resolveMcpServerHeaders(url: string | URL, orgJwt: JSONWebToken | undefined, headers?: Record<string, string>): Promise<Record<string, string>>;

package/dist/mcp-auth.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+const SALESFORCE_PLATFORM_MCP_URL_REGEX = /^https:\/\/((dev|test|perf|stage)\.)?api\.salesforce\.com\/platform\/mcp\//;
+/**
+ * Returns true if the URL matches a Salesforce Hosted MCP Server endpoint.
+ * Covers all environments (prod, dev, test, perf, stage) and all API versions
+ * (beta: v1-beta.2, GA: v1, future versions).
+ */
+export function isSalesforcePlatformMcpUrl(url) {
+    const urlString = url instanceof URL ? url.toString() : url;
+    return SALESFORCE_PLATFORM_MCP_URL_REGEX.test(urlString);
+}
+/**
+ * Resolves the final headers for an MCP server request.
+ *
+ * For Salesforce Hosted MCP Server URLs, injects an `Authorization: Bearer <token>`
+ * header (via `orgJwt.getValue()`) when no explicit Authorization header already exists.
+ * For all other URLs the headers are returned unmodified.
+ *
+ * @param url - The MCP server URL.
+ * @param orgJwt - The org's self-refreshing JWT (from HarnessAgentConfig.orgJwt).
+ * @param headers - Existing headers configured on the server.
+ * @returns The resolved headers — original headers plus any injected auth.
+ */
+export async function resolveMcpServerHeaders(url, orgJwt, headers = {}) {
+    if (!orgJwt)
+        return headers;
+    if (!isSalesforcePlatformMcpUrl(url))
+        return headers;
+    if (hasAuthorizationHeader(headers))
+        return headers;
+    const token = await orgJwt.getValue();
+    return { ...headers, Authorization: `Bearer ${token}` };
+}
+function hasAuthorizationHeader(headers) {
+    return Object.keys(headers).some((key) => key.toLowerCase() === 'authorization');
+}
+//# sourceMappingURL=mcp-auth.js.map

package/dist/mcp-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-auth.js","sourceRoot":"","sources":["../src/mcp-auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,iCAAiC,GAAG,4EAA4E,CAAC;AAEvH;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAiB;IACxD,MAAM,SAAS,GAAG,GAAG,YAAY,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IAC5D,OAAO,iCAAiC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CACzC,GAAiB,EACjB,MAAgC,EAChC,UAAkC,EAAE;IAEpC,IAAI,CAAC,MAAM;QAAE,OAAO,OAAO,CAAC;IAC5B,IAAI,CAAC,0BAA0B,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IACrD,IAAI,sBAAsB,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAEpD,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;IACtC,OAAO,EAAE,GAAG,OAAO,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,CAAC;AAC5D,CAAC;AAED,SAAS,sBAAsB,CAAC,OAA+B;IAC3D,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,eAAe,CAAC,CAAC;AACrF,CAAC"}

package/dist/mcp-config.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Configuration for MCP (Model Context Protocol) servers attached to an agent.
+ * Each server is identified by a unique name key.
+ */
+export type MCPConfiguration = Record<string, MCPServerConfig>;
+/**
+ * Configuration for a single MCP server.
+ * Discriminated union by `type`: either a local stdio process or a remote HTTP/SSE endpoint.
+ *
+ * Borrowed from the OpenCode SDK's `McpLocalConfig` / `McpRemoteConfig` pattern.
+ */
+export type MCPServerConfig = MCPStdioServerConfig | MCPRemoteServerConfig;
+/** MCP server launched as a local subprocess communicating over stdio. */
+export type MCPStdioServerConfig = {
+    type: 'stdio';
+    /** Command to launch the MCP server process. */
+    command: string;
+    /** Arguments passed to the command. */
+    args?: string[];
+    /** Environment variables set when running the server process. */
+    env?: Record<string, string>;
+    /** Whether this server is enabled. Defaults to `true`. */
+    enabled?: boolean;
+    /** Timeout in milliseconds for connecting to the server. */
+    timeout?: number;
+};
+/** MCP server accessible over HTTP/SSE at a remote URL. */
+export type MCPRemoteServerConfig = {
+    type: 'remote';
+    /** URL of the remote MCP server endpoint. */
+    url: string | URL;
+    /** HTTP headers sent with requests to the server. */
+    headers?: Record<string, string>;
+    /** Whether this server is enabled. Defaults to `true`. */
+    enabled?: boolean;
+    /** Timeout in milliseconds for connecting to the server. */
+    timeout?: number;
+};
+/** Connection status of a single MCP server. */
+export declare enum McpServerStatus {
+    Connected = "connected",
+    Connecting = "connecting",
+    Disabled = "disabled",
+    Error = "error"
+}
+/** Runtime status of a configured MCP server, including its discovered tools. */
+export type McpServerInfo = {
+    name: string;
+    status: McpServerStatus;
+    tools: string[];
+    error?: string;
+};

package/dist/mcp-config.js

@@ -0,0 +1,13 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/** Connection status of a single MCP server. */
+export var McpServerStatus;
+(function (McpServerStatus) {
+    McpServerStatus["Connected"] = "connected";
+    McpServerStatus["Connecting"] = "connecting";
+    McpServerStatus["Disabled"] = "disabled";
+    McpServerStatus["Error"] = "error";
+})(McpServerStatus || (McpServerStatus = {}));
+//# sourceMappingURL=mcp-config.js.map