@salesforce/sfdx-agent-sdk 0.1.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+Terms of Use
+
+Copyright 2026 Salesforce, Inc. All rights reserved.
+
+These Terms of Use govern the download, installation, and/or use of this software provided by Salesforce, Inc. ("Salesforce") (the "Software"), were last updated on March 24, 2026, and constitute a legally binding agreement between you and Salesforce. If you do not agree to these Terms of Use, do not install or use the Software. The Software may link to third-party software components licensed under various open source licenses ("Open Source Components"). These Terms of Use pertain solely to Salesforce's proprietary code in the Software. It does not alter or extend any rights or obligations regarding the Open Source Components. For clarity, your use of the Open Source Components is governed by the terms of the applicable open source license(s). You are solely responsible for complying with the terms and conditions of those open source licenses.
+
+Salesforce grants you a worldwide, non-exclusive, no-charge, royalty-free copyright license to reproduce, revocable, publicly display, publicly perform, sublicense, and distribute the Software and derivative works subject to these Terms. These Terms shall be included in all copies or substantial portions of the Software.
+
+Subject to the limited rights expressly granted hereunder, Salesforce reserves all rights, title, and interest in and to all intellectual property subsisting in the Software. No rights are granted to you hereunder other than as expressly set forth herein. Users residing in countries on the United States Office of Foreign Assets Control sanction list, or which are otherwise subject to a US export embargo, may not use the Software.
+
+Implementation of the Software may require development work, for which you are responsible. The Software may contain bugs, errors and incompatibilities and is made available on an AS IS basis without support, updates, or service level commitments.
+
+Salesforce reserves the right at any time to modify, suspend, or discontinue, the Software (or any part thereof) with or without notice. You agree that Salesforce shall not be liable to you or to any third party for any modification, suspension, or discontinuance.
+
+You agree to defend Salesforce against any claim, demand, suit or proceeding made or brought against Salesforce by a third party arising out of or accruing from (a) your use of the Software, and (b) any application you develop with the Software that infringes any copyright, trademark, trade secret, trade dress, patent, or other intellectual property right of any person or defames any person or violates their rights of publicity or privacy (each a "Claim Against Salesforce"), and will indemnify Salesforce from any damages, attorney fees, and costs finally awarded against Salesforce as a result of, or for any amounts paid by Salesforce under a settlement approved by you in writing of, a Claim Against Salesforce, provided Salesforce (x) promptly gives you written notice of the Claim Against Salesforce, (y) gives you sole control of the defense and settlement of the Claim Against Salesforce (except that you may not settle any Claim Against Salesforce unless it unconditionally releases Salesforce of all liability), and (z) gives you all reasonable assistance, at your expense.
+
+WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE SOFTWARE IS NOT SUPPORTED AND IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL SALESFORCE HAVE ANY LIABILITY FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES, OR DAMAGES BASED ON LOST PROFITS, DATA, OR USE, IN CONNECTION WITH THE SOFTWARE, HOWEVER CAUSED AND WHETHER IN CONTRACT, TORT, OR UNDER ANY OTHER THEORY OF LIABILITY, WHETHER OR NOT YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+These Terms of Use shall be governed exclusively by the internal laws of the State of California, without regard to its conflicts of laws rules. Each party hereby consents to the exclusive jurisdiction of the state and federal courts located in San Francisco County, California to adjudicate any dispute arising out of or relating to these Terms of Use and the download, installation, and/or use of the Software. Except as expressly stated herein, these Terms of Use constitute the entire agreement between the parties, and supersede all prior and contemporaneous agreements, proposals, or representations, written or oral, concerning their subject matter. No modification, amendment, or waiver of any provision of these Terms of Use shall be effective unless it is by an update to these Terms of Use that Salesforce makes available, or is in writing and signed by the party against whom the modification, amendment, or waiver is to be asserted.
+
+Data Privacy: Salesforce may collect, process, and store device, system, and other information related to your use of the Software. This information includes, but is not limited to, IP address, user metrics, and other data ("Usage Data"). Salesforce may use Usage Data for analytics, product development, and marketing purposes. You acknowledge that files generated in conjunction with the Software may contain sensitive or confidential data, and you are solely responsible for anonymizing and protecting such data.

package/README.md

@@ -0,0 +1,508 @@
+# @salesforce/sfdx-agent-sdk
+
+Harness-agnostic SDK for creating and managing AI agents within the Salesforce developer experience. It provides a
+stable API for agent lifecycle, chat sessions, streaming responses, MCP tool integration, and tool approval flows —
+without coupling consumer code to a specific AI framework.
+
+## Quick Start
+
+> This package is not yet published to npm. See [DEVELOPING.md](DEVELOPING.md) to build from source.
+
+```typescript
+import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
+import { MastraHarnessFactory } from '@salesforce/sfdx-agent-harness-mastra';
+
+// 1. Create the manager (validates the storage folder exists)
+const manager = await createAgentManager('/path/to/storage', new MastraHarnessFactory());
+
+// 2. Create an agent
+const agent = await manager.createAgent('/path/to/project', {
+  agentId: 'developer-assistant',
+  modelId: 'llmgateway__OpenAIGPT5',
+  instructions: 'You are a helpful Salesforce developer assistant.',
+});
+
+// 3. Open a chat session and stream a response
+const session = await agent.createChatSession();
+const { eventStream } = await session.chat('Explain Lightning Web Components.');
+
+for await (const event of eventStream) {
+  if (event.type === 'text-delta') {
+    process.stdout.write(event.text);
+  } else if (event.type === 'error') {
+    console.error(event.error.message);
+    break;
+  }
+}
+
+// 4. Shut down
+await manager.shutdown();
+```
+
+## API Reference
+
+### `createAgentManager(storageRootFolder, harnessFactory): Promise<AgentManager>`
+
+Factory function that creates an `AgentManager` backed by the provided `HarnessFactory`. The `storageRootFolder` must be
+an existing directory and is used for persistent state (database, memory). The SDK verifies that the constructed harness
+uses a supported protocol version before returning the manager.
+
+### `AgentManager`
+
+Top-level orchestrator that owns the harness and manages agent lifecycle.
+
+| Method         | Signature                                                                                                                       | Description                                                                                                                |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `createAgent`  | `(projectRoot: string, config?: AgentConfig & { agentId?: string }, options?: { abortSignal?: AbortSignal }) => Promise<Agent>` | Create and register a new agent. `projectRoot` must be an existing directory. If `agentId` is omitted a UUID is generated. |
+| `getAgent`     | `(agentId: string) => Agent`                                                                                                    | Retrieve an agent by ID. Throws `AgentSDKError` (`AGENT_NOT_FOUND`) if missing.                                            |
+| `getAgentIds`  | `() => string[]`                                                                                                                | List all managed agent IDs.                                                                                                |
+| `destroyAgent` | `(agentId: string) => Promise<void>`                                                                                            | Destroy an agent and release its resources. Throws `AgentSDKError` (`AGENT_NOT_FOUND`) if missing.                         |
+| `shutdown`     | `() => Promise<void>`                                                                                                           | Destroy all agents and shut down the harness.                                                                              |
+| `onTelemetry`  | `(callback: TelemetryEventCallback) => Unsubscribe`                                                                             | Subscribe to telemetry across all managed agents.                                                                          |
+| `onLog`        | `(callback: (record: LogRecord) => void) => Unsubscribe`                                                                        | Subscribe to structured logs across all managed agents.                                                                    |
+
+### `Agent`
+
+A configured AI agent. Factory for chat sessions.
+
+| Method                 | Signature                                                                          | Description                                                            |
+| ---------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `getId`                | `() => string`                                                                     | Agent identifier.                                                      |
+| `getProjectRoot`       | `() => string`                                                                     | Absolute project path.                                                 |
+| `getOrgConnectionInfo` | `() => OrgConnectionInfo`                                                          | Org metadata (orgId, alias, instanceUrl, username, env).               |
+| `getAgentConfig`       | `() => AgentConfig`                                                                | Current configuration (shallow copy).                                  |
+| `getMcpServerInfo`     | `() => McpServerInfo[]`                                                            | MCP server status and discovered tools.                                |
+| `updateAgentConfig`    | `(config?: AgentConfig, options?: { abortSignal?: AbortSignal }) => Promise<void>` | Merge new config into the live agent.                                  |
+| `createChatSession`    | `() => Promise<ChatSession>`                                                       | Open a new conversation thread.                                        |
+| `getChatSession`       | `(sessionId: string) => ChatSession`                                               | Retrieve a session. Throws `AgentSDKError` (`CHAT_SESSION_NOT_FOUND`). |
+| `getChatSessionIds`    | `() => string[]`                                                                   | List active session IDs.                                               |
+| `destroyChatSession`   | `(sessionId: string) => Promise<void>`                                             | Destroy a session and its history.                                     |
+| `cloneChatSession`     | `(sourceSessionId: string) => Promise<ChatSession>`                                | Clone a session with its message history.                              |
+| `compactChatSession`   | `(sessionId: string) => Promise<ChatSession>`                                      | Compact a session into a summarized new session.                       |
+| `destroy`              | `() => Promise<void>`                                                              | Destroy the agent and all its sessions.                                |
+| `onTelemetry`          | `(callback: TelemetryEventCallback) => Unsubscribe`                                | Subscribe to telemetry scoped to this agent (and its sessions).        |
+| `onLog`                | `(callback: (record: LogRecord) => void) => Unsubscribe`                           | Subscribe to logs scoped to this agent (and its sessions).             |
+
+### `ChatSession`
+
+A single conversation thread.
+
+| Method              | Signature                                                                             | Description                                                   |
+| ------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `getId`             | `() => string`                                                                        | Session/thread identifier.                                    |
+| `chat`              | `(message: string, options?: ChatOptions) => Promise<ChatStreamResult>`               | Send a message and stream the response.                       |
+| `submitToolResult`  | `(toolResult: ToolResultInfo) => Promise<ChatStreamResult>`                           | Return a consumer-executed tool result and resume the stream. |
+| `approveToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<ChatStreamResult>` | Approve a pending tool call.                                  |
+| `declineToolCall`   | `(toolCallId: string) => Promise<ChatStreamResult>`                                   | Decline a pending tool call.                                  |
+| `getMessageHistory` | `() => Promise<Message[]>`                                                            | Retrieve all messages in chronological order.                 |
+| `clearHistory`      | `() => Promise<void>`                                                                 | Delete all messages.                                          |
+| `addContext`        | `(message: string \| Message[]) => Promise<void>`                                     | Inject context without triggering an LLM response.            |
+| `subscribe`         | `(callback: (event: ChatEvent) => void) => void`                                      | Register a real-time event listener.                          |
+| `unsubscribe`       | `(callback: (event: ChatEvent) => void) => void`                                      | Remove a listener.                                            |
+| `onTelemetry`       | `(callback: TelemetryEventCallback) => Unsubscribe`                                   | Subscribe to telemetry scoped to this session.                |
+| `onLog`             | `(callback: (record: LogRecord) => void) => Unsubscribe`                              | Subscribe to logs scoped to this session.                     |
+| `dispose`           | `() => void`                                                                          | Release session-level event resources. Idempotent.            |
+
+### `ChatStreamResult`
+
+Returned by `chat()`, `submitToolResult()`, `approveToolCall()`, and `declineToolCall()`.
+
+| Property      | Type                        | Description                             |
+| ------------- | --------------------------- | --------------------------------------- |
+| `eventStream` | `AsyncGenerator<ChatEvent>` | Full lifecycle event stream.            |
+| `textStream`  | `AsyncGenerator<string>`    | Convenience stream of text-only tokens. |
+
+### `ChatEvent`
+
+Discriminated union (`event.type`) of streaming events:
+
+| Type                    | Key Fields                                     | Description                                              |
+| ----------------------- | ---------------------------------------------- | -------------------------------------------------------- |
+| `start`                 | —                                              | Stream has begun.                                        |
+| `text-delta`            | `text`                                         | Incremental response text.                               |
+| `reasoning-delta`       | `text`                                         | Chain-of-thought fragment.                               |
+| `tool-call`             | `toolCallId`, `toolName`, `args`               | Tool invocation.                                         |
+| `tool-approval-request` | `toolCall: ToolCallInfo`                       | Engine requests approval before executing a tool.        |
+| `tool-result`           | `toolCallId`, `toolName`, `result`, `isError?` | Tool execution completed.                                |
+| `step-start`            | `stepIndex`                                    | New LLM invocation step began.                           |
+| `step-finish`           | `stepIndex`, `finishReason`, `usage?`          | Step completed with per-step token usage.                |
+| `error`                 | `error`, `code?`                               | Mid-stream error (yielded, not thrown).                  |
+| `finish`                | `finishReason`, `usage?`                       | Stream completed with aggregate token usage.             |
+| `unmapped-chunk`        | `chunkType`, `rawChunk`                        | Unrecognized harness event, preserved for observability. |
+
+### Configuration Types
+
+#### `AgentConfig`
+
+| Field           | Type               | Description                                                          |
+| --------------- | ------------------ | -------------------------------------------------------------------- |
+| `orgAlias?`     | `string`           | Salesforce org alias or username. Falls back to project/default org. |
+| `modelId?`      | `ModelName`        | LLM model identifier (e.g. `'llmgateway__OpenAIGPT5'`).              |
+| `name?`         | `string`           | Human-readable agent name.                                           |
+| `description?`  | `string`           | Agent purpose description.                                           |
+| `instructions?` | `string`           | System instructions for the agent.                                   |
+| `tools?`        | `ToolDefinition[]` | Consumer-executed tool schemas.                                      |
+| `mcpServers?`   | `MCPConfiguration` | MCP server connections.                                              |
+| `skills?`       | `string[]`         | Paths to skill directories (relative to project root or absolute).   |
+
+#### `StreamOptions`
+
+| Field                  | Type          | Description                                                              |
+| ---------------------- | ------------- | ------------------------------------------------------------------------ |
+| `abortSignal?`         | `AbortSignal` | Abort the streaming operation.                                           |
+| `requireToolApproval?` | `boolean`     | When `true`, emits `tool-approval-request` before native tool execution. |
+
+#### `MCPConfiguration`
+
+```typescript
+type MCPConfiguration = Record<string, MCPServerConfig>;
+
+// Stdio server (local subprocess)
+type MCPStdioServerConfig = {
+  type: 'stdio';
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  enabled?: boolean;
+  timeout?: number;
+};
+
+// Remote server (HTTP/SSE)
+type MCPRemoteServerConfig = {
+  type: 'remote';
+  url: string | URL;
+  headers?: Record<string, string>;
+  enabled?: boolean;
+  timeout?: number;
+};
+```
+
+#### `McpServerInfo`
+
+| Field    | Type                                                   | Description                             |
+| -------- | ------------------------------------------------------ | --------------------------------------- |
+| `name`   | `string`                                               | Server identifier.                      |
+| `status` | `'connected' \| 'connecting' \| 'disabled' \| 'error'` | Connection state.                       |
+| `tools`  | `string[]`                                             | Discovered tool names.                  |
+| `error?` | `string`                                               | Error message when status is `'error'`. |
+
+### Tool Types
+
+```typescript
+type ToolDefinition = {
+  name: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+};
+
+type ToolCallInfo = {
+  toolCallId: string;
+  toolName: string;
+  args: Record<string, unknown>;
+};
+
+type ToolResultInfo = {
+  toolCallId: string;
+  toolName: string;
+  result: unknown;
+  isError?: boolean;
+};
+```
+
+### Message Types
+
+```typescript
+type Message = {
+  id: string;
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string | MessagePart[];
+  createdAt?: Date;
+};
+
+type MessagePart = TextPart | ReasoningPart | ToolCallPart | ToolResultPart;
+```
+
+### Usage & Finish Types
+
+```typescript
+type UsageMetadata = {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  reasoningTokens?: number;
+  cachedInputTokens?: number;
+};
+
+type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'other';
+```
+
+### Error Handling
+
+The SDK throws `AgentSDKError` for predictable not-found and compatibility conditions. Each error has a `type` property
+from `AgentSDKErrorType`:
+
+| Type                     | Thrown By                                                                                                                                                                   |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AGENT_NOT_FOUND`        | `AgentManager.getAgent()`, `AgentManager.destroyAgent()`                                                                                                                    |
+| `CHAT_SESSION_NOT_FOUND` | `Agent.getChatSession()`, `Agent.destroyChatSession()`, `Agent.cloneChatSession()`, `Agent.compactChatSession()`                                                            |
+| `COMPACTION_FAILED`      | `Agent.compactChatSession()` when the harness's underlying summarization call rejects. The original error is attached as `cause`; the source session is left intact.        |
+| `DISPOSED`               | `Agent` and `ChatSession` methods called after the owner has been destroyed                                                                                                 |
+| `INCOMPATIBLE_HARNESS`   | `createAgentManager()` when the factory advertises an unsupported `protocolVersion`, or the constructed harness reports a `protocolVersion` that differs from the factory's |
+
+```typescript
+import { AgentSDKError, AgentSDKErrorType } from '@salesforce/sfdx-agent-sdk';
+
+try {
+  manager.getAgent(id);
+} catch (err) {
+  if (err instanceof AgentSDKError && err.type === AgentSDKErrorType.AGENT_NOT_FOUND) {
+    // handle not found
+  }
+}
+```
+
+#### Streaming method failures
+
+The four streaming methods on `ChatSession` — `chat()`, `submitToolResult()`, `approveToolCall()`, and
+`declineToolCall()` — share a single failure contract. Subscribers registered via `subscribe()` are guaranteed to
+receive a terminal event for every turn:
+
+- **Pre-stream failure** (the harness rejects before producing a stream): subscribers receive an `ErrorEvent` followed
+  by a `FinishEvent(finishReason: 'error')`, and the returned promise then rejects with the original error. Wrap the
+  call in `try/catch` if you need to handle this in the caller.
+- **In-stream failure** (the stream yields an `error` event or the underlying generator throws): the `eventStream`
+  yields the `ErrorEvent` (synthesizing one from a thrown exception if needed) and, if no `FinishEvent` was already
+  emitted, appends a synthetic `FinishEvent(finishReason: 'error')` at the end. The returned promise resolves normally;
+  iterate the stream to observe the failure.
+- **Calling a disposed session** throws `AgentSDKError('DISPOSED')` synchronously without notifying subscribers.
+
+### MCP Server Configuration
+
+MCP servers are configured at agent creation. Tool discovery runs in the background — the agent is usable immediately,
+and MCP tools become available once `getMcpServerInfo()` shows `status: 'connected'`.
+
+```typescript
+const agent = await manager.createAgent('/project', {
+  mcpServers: {
+    filesystem: {
+      type: 'stdio',
+      command: 'npx',
+      args: ['-y', '@modelcontextprotocol/server-filesystem', '/path'],
+    },
+  },
+});
+
+// Poll until connected
+const servers = agent.getMcpServerInfo();
+for (const s of servers) {
+  console.log(`${s.name}: ${s.status}, tools: ${s.tools.join(', ')}`);
+}
+```
+
+### Tool Approval Flow
+
+```typescript
+const { eventStream } = await session.chat('Run the deployment', {
+  requireToolApproval: true,
+});
+
+for await (const event of eventStream) {
+  if (event.type === 'tool-approval-request') {
+    const continuation = await session.approveToolCall(event.toolCall.toolCallId);
+    for await (const e of continuation.eventStream) {
+      // process continuation
+    }
+  }
+}
+```
+
+### Consumer-Executed Tools
+
+```typescript
+for await (const event of eventStream) {
+  if (event.type === 'tool-call' && event.toolName === 'my-tool') {
+    const result = await runLocally(event.args);
+    const continuation = await session.submitToolResult({
+      toolCallId: event.toolCallId,
+      toolName: event.toolName,
+      result,
+    });
+    for await (const e of continuation.eventStream) {
+      // process continuation
+    }
+  }
+}
+```
+
+### Connectivity Resolution
+
+#### `ResolvedConnectivity`
+
+Returned by `AgentConnectivityResolver.resolve()`. Contains all resolved runtime artifacts for an agent's org.
+
+| Field              | Type               | Description                                                            |
+| ------------------ | ------------------ | ---------------------------------------------------------------------- |
+| `llmGatewayClient` | `LLMGatewayClient` | Pre-configured and authenticated LLM gateway client.                   |
+| `orgConnection`    | `OrgConnection`    | Authenticated org connection carrying identity and env inference.      |
+| `orgJwt`           | `JSONWebToken`     | Self-refreshing JWT for the resolved org, used for MCP auth injection. |
+
+#### `HarnessAgentConfig`
+
+Harness-facing configuration derived from `AgentConfig`. Strips `orgAlias` (resolved above the harness) and adds:
+
+| Field     | Type           | Description                                                                                                    |
+| --------- | -------------- | -------------------------------------------------------------------------------------------------------------- |
+| `orgJwt?` | `JSONWebToken` | Self-refreshing JWT. Harness implementations pass this to `resolveMcpServerHeaders()` for auto-auth injection. |
+
+### MCP Auth Helpers
+
+#### `resolveMcpServerHeaders(url, orgJwt, headers?): Promise<Record<string, string>>`
+
+Resolves final headers for an MCP server request. For Salesforce Hosted MCP Server URLs
+(`https://[env.]api.salesforce.com/platform/mcp/...`), injects `Authorization: Bearer <token>` when no explicit
+Authorization header already exists. For all other URLs, returns headers unmodified.
+
+#### `isSalesforcePlatformMcpUrl(url): boolean`
+
+Returns `true` if the URL matches a Salesforce Hosted MCP Server endpoint (prod, dev, test, perf, stage).
+
+### Re-exported from `@salesforce/llm-gateway-sdk`
+
+- `ModelName` — enum of supported model identifiers
+- `SfApiEnv` — Salesforce API environment enum (`dev`, `perf`, `prod`, `stage`, `test`)
+
+### Telemetry & structured logs
+
+The SDK exposes typed `TelemetryEvent` / `LogRecord` streams at the manager, agent, and session scopes. See
+[Telemetry & Logs](#telemetry--logs) below for the event catalog, emit contract, and structured-log table.
+
+## Writing a Harness
+
+The SDK ships no harness implementation. Consumers pick one by passing a `HarnessFactory` instance to
+`createAgentManager`. The reference implementation is
+[`@salesforce/sfdx-agent-harness-mastra`](../sfdx-agent-harness-mastra); additional harnesses can ship as independent
+npm packages that depend on this SDK as a `peerDependency`.
+
+Harness authors implement two interfaces and can compose one helper class, all exported from this package:
+
+| Export                        | Role                                                                                                                                   |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `HarnessFactory`              | Construct an `AgentHarness` bound to a storage root. Declares `harnessId` and `protocolVersion`.                                       |
+| `AgentHarness`                | Runtime contract: agent / thread / stream / tool / message lifecycle. Declares its own `harnessId` and `protocolVersion`.              |
+| `SUPPORTED_PROTOCOL_VERSIONS` | Readonly list of harness protocol versions this SDK accepts. `createAgentManager` checks both the factory and the constructed harness. |
+| `HarnessBusOwner`             | Composition helper owning telemetry + log buses with `dispose()` semantics. Reuse it instead of reimplementing bus plumbing.           |
+
+Minimal skeleton:
+
+```typescript
+import {
+  type AgentHarness,
+  type HarnessFactory,
+  HarnessBusOwner,
+  SUPPORTED_PROTOCOL_VERSIONS,
+} from '@salesforce/sfdx-agent-sdk';
+
+class MyHarness implements AgentHarness {
+  readonly harnessId = 'my-harness';
+  readonly protocolVersion = 1;
+
+  private readonly buses = new HarnessBusOwner();
+
+  onTelemetry = this.buses.onTelemetry.bind(this.buses);
+  onLog = this.buses.onLog.bind(this.buses);
+
+  async shutdown() {
+    this.buses.dispose();
+    // release harness-specific resources
+  }
+  // implement the remaining AgentHarness methods (createAgent, stream, …)
+}
+
+export class MyHarnessFactory implements HarnessFactory {
+  readonly harnessId = 'my-harness';
+  readonly protocolVersion = 1;
+  async create(storageRootFolder: string): Promise<AgentHarness> {
+    return new MyHarness(storageRootFolder);
+  }
+}
+```
+
+Protocol-version rules:
+
+- Both `HarnessFactory.protocolVersion` and the constructed `AgentHarness.protocolVersion` must match and must appear in
+  `SUPPORTED_PROTOCOL_VERSIONS`. A mismatch throws `AgentSDKError` with type `INCOMPATIBLE_HARNESS`.
+- Bump when you change a method signature, event payload shape, enum value, or ownership of a responsibility. Do not
+  bump for additive optional fields or internal refactors.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full interface surface and for details on telemetry routing, which the
+SDK handles transparently as long as the harness emits through `HarnessBusOwner`.
+
+## Telemetry & Logs
+
+Subscribe at any of three scopes:
+
+```ts
+manager.onTelemetry((event) => {
+  /* every managed agent */
+});
+agent.onTelemetry((event) => {
+  /* this agent and its sessions */
+});
+session.onTelemetry((event) => {
+  /* this session only */
+});
+
+manager.onLog((record) => {
+  /* level: 'debug' | 'info' | 'warn' | 'error' */
+});
+```
+
+`onTelemetry` / `onLog` return an `Unsubscribe` function. Subscribers receive only events that originate after they
+subscribe — agent-level subscribers do **not** observe their own `agent-created` event because the consumer obtains the
+agent handle as a result of that event being emitted; the same applies to `session-created` for session-level
+subscribers. Subscribe at the parent level if you need to observe creation events.
+
+### `TelemetryEvent` variants
+
+All variants share `{ type: <discriminant>, timestamp: Date }` plus the fields below. Routing fields (`agentId` and
+`threadId`) appear on the variants that carry them.
+
+| `type`                           | Additional fields                                                                                                 |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `agent-created`                  | `agentId`, `projectRoot`, `modelName`                                                                             |
+| `agent-destroyed`                | `agentId`                                                                                                         |
+| `session-created`                | `agentId`, `threadId`                                                                                             |
+| `session-destroyed`              | `agentId`, `threadId`                                                                                             |
+| `chat-stream-started`            | `agentId`, `threadId`, `trigger` (`'chat' \| 'submit-tool-result' \| 'approve-tool-call' \| 'decline-tool-call'`) |
+| `chat-stream-completed`          | `agentId`, `threadId`, `durationMs`, `usage?`                                                                     |
+| `chat-stream-error`              | `agentId`, `threadId`, `durationMs`, `error`                                                                      |
+| `tool-execution-started`         | `agentId`, `threadId`, `toolCallId`, `toolName`                                                                   |
+| `tool-execution-completed`       | `agentId`, `threadId`, `toolCallId`, `toolName`, `durationMs`, `isError`                                          |
+| `tool-approval-requested`        | `agentId`, `threadId`, `toolCallId`, `toolName`                                                                   |
+| `tool-approval-resolved`         | `agentId`, `threadId`, `toolCallId`, `approved`                                                                   |
+| `mcp-server-discovery-started`   | `agentId`, `serverName`                                                                                           |
+| `mcp-server-discovery-completed` | `agentId`, `serverName`, `toolCount`, `durationMs`                                                                |
+| `mcp-server-discovery-failed`    | `agentId`, `serverName`, `durationMs`, `error`                                                                    |
+
+Every chat entry point (`chat`, `submitToolResult`, `approveToolCall`, `declineToolCall`) emits exactly one
+`chat-stream-started` followed by exactly one terminal event — either `chat-stream-completed` (natural completion) or
+`chat-stream-error` (in-stream error, thrown exception, or pre-stream harness rejection). The two terminal events are
+mutually exclusive per stream, and both carry a real `durationMs` measured from the moment `chat-stream-started` fired.
+Abandoning the iterator mid-stream emits no terminal telemetry — the stream did not complete.
+
+### Structured logs
+
+| Level | Source              | Message                                  | Context                             |
+| ----- | ------------------- | ---------------------------------------- | ----------------------------------- |
+| info  | `sfap-env-resolver` | `Inferred SFAP env from instanceUrl`     | `inferred`, `instanceUrl`           |
+| info  | `sfap-env-resolver` | `SF_API_ENV overrides inferred SFAP env` | `envVar`, `inferred`, `instanceUrl` |
+
+Harness implementations may emit additional structured logs through their own `LogBus`. Those records surface to
+consumers via the same `onLog` channel.
+
+## Development
+
+See [DEVELOPING.md](DEVELOPING.md) for build-from-source setup, scripts, E2E testing, and packaging.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for implementation details on the harness abstraction. The reference harness
+implementation lives in [`@salesforce/sfdx-agent-harness-mastra`](../sfdx-agent-harness-mastra).

package/dist/agent-connectivity-resolver.d.ts

@@ -0,0 +1,62 @@
+import { type JSONWebToken, type LLMGatewayClient, type LLMGatewayClientFactory } from '@salesforce/llm-gateway-sdk';
+import { type OrgConnection, type OrgConnectionFactory } from '@salesforce/agentic-common';
+import type { AgentConfig } from './harness/harness-config.js';
+/**
+ * The result of resolving an agent's org connectivity: a ready-to-use authenticated
+ * LLM gateway client and the underlying connection.
+ */
+export type ResolvedConnectivity = {
+    /** Pre-configured and authenticated LLM gateway client for the resolved org. */
+    llmGatewayClient: LLMGatewayClient;
+    /** Authenticated org connection carrying identity and env inference. */
+    orgConnection: OrgConnection;
+    /** Self-refreshing JWT for the resolved org, used for MCP auth injection. */
+    orgJwt: JSONWebToken;
+};
+/**
+ * Resolves the org connectivity needed to create an agent for a given project and
+ * configuration.
+ *
+ * Implementations are responsible for resolving the org's authentication and constructing
+ * an authenticated {@link LLMGatewayClient} and {@link OrgConnection} from an
+ * {@link AgentConfig}.
+ */
+export interface AgentConnectivityResolver {
+    /**
+     * Resolve the org connectivity for an agent.
+     *
+     * @param projectRoot - The root directory of the project the agent operates within.
+     *   Used to find a project-local `target-org` when no `orgAlias` is configured.
+     * @param config - The agent's configuration, including optional org alias and model selection.
+     * @returns The resolved LLM gateway client and org connection metadata.
+     */
+    resolve(projectRoot: string, config: AgentConfig): Promise<ResolvedConnectivity>;
+}
+/**
+ * Default implementation of {@link AgentConnectivityResolver}.
+ *
+ * Delegates org resolution to {@link OrgConnectionFactory} and LLM client creation to
+ * {@link LLMGatewayClientFactory}. Both dependencies are injectable for testing.
+ */
+export declare class DefaultAgentConnectivityResolver implements AgentConnectivityResolver {
+    private readonly connectionFactory;
+    private readonly gatewayClientFactory;
+    /**
+     * @param connectionFactory - Creates authenticated Salesforce org connections.
+     * @param gatewayClientFactory - Creates authenticated LLM gateway clients.
+     */
+    constructor(connectionFactory?: OrgConnectionFactory, gatewayClientFactory?: LLMGatewayClientFactory);
+    /**
+     * Resolves the org, constructs an authenticated LLM gateway client, and
+     * returns the underlying connection.
+     *
+     * If `config.orgAlias` is set, resolves that alias explicitly; otherwise falls back
+     * to the project-local or machine-default org via
+     * {@link OrgConnectionFactory.createFromTargetOrg}.
+     *
+     * @param projectRoot - Project root for project-local org resolution.
+     * @param config - Agent configuration with optional org alias and model ID.
+     * @returns The resolved LLM gateway client and connection.
+     */
+    resolve(projectRoot: string, config: AgentConfig): Promise<ResolvedConnectivity>;
+}

package/dist/agent-connectivity-resolver.js

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { DefaultLLMGatewayClientFactory, Models, createJWTFromConnection, } from '@salesforce/llm-gateway-sdk';
+import { RealOrgConnectionFactory } from '@salesforce/agentic-common';
+/**
+ * Default implementation of {@link AgentConnectivityResolver}.
+ *
+ * Delegates org resolution to {@link OrgConnectionFactory} and LLM client creation to
+ * {@link LLMGatewayClientFactory}. Both dependencies are injectable for testing.
+ */
+export class DefaultAgentConnectivityResolver {
+    connectionFactory;
+    gatewayClientFactory;
+    /**
+     * @param connectionFactory - Creates authenticated Salesforce org connections.
+     * @param gatewayClientFactory - Creates authenticated LLM gateway clients.
+     */
+    constructor(connectionFactory = new RealOrgConnectionFactory(), gatewayClientFactory = new DefaultLLMGatewayClientFactory()) {
+        this.connectionFactory = connectionFactory;
+        this.gatewayClientFactory = gatewayClientFactory;
+    }
+    /**
+     * Resolves the org, constructs an authenticated LLM gateway client, and
+     * returns the underlying connection.
+     *
+     * If `config.orgAlias` is set, resolves that alias explicitly; otherwise falls back
+     * to the project-local or machine-default org via
+     * {@link OrgConnectionFactory.createFromTargetOrg}.
+     *
+     * @param projectRoot - Project root for project-local org resolution.
+     * @param config - Agent configuration with optional org alias and model ID.
+     * @returns The resolved LLM gateway client and connection.
+     */
+    async resolve(projectRoot, config) {
+        const orgConnection = config.orgAlias !== undefined
+            ? await this.connectionFactory.createFromOrgAliasOrUsername(config.orgAlias)
+            : await this.connectionFactory.createFromTargetOrg({ projectRoot });
+        const orgJwt = await createJWTFromConnection(orgConnection);
+        const llmGatewayClient = this.gatewayClientFactory.create(orgJwt, { env: orgConnection.getInferredSfApiEnv() });
+        const modelName = config.modelId ?? Models.getDefault().name;
+        llmGatewayClient.setModel(Models.getByName(modelName));
+        return { llmGatewayClient, orgConnection, orgJwt };
+    }
+}
+//# sourceMappingURL=agent-connectivity-resolver.js.map

package/dist/agent-connectivity-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-connectivity-resolver.js","sourceRoot":"","sources":["../src/agent-connectivity-resolver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACH,8BAA8B,EAC9B,MAAM,EACN,uBAAuB,GAI1B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,wBAAwB,EAAiD,MAAM,4BAA4B,CAAC;AAoCrH;;;;;GAKG;AACH,MAAM,OAAO,gCAAgC;IAMpB;IACA;IANrB;;;OAGG;IACH,YACqB,oBAA0C,IAAI,wBAAwB,EAAE,EACxE,uBAAgD,IAAI,8BAA8B,EAAE;QADpF,sBAAiB,GAAjB,iBAAiB,CAAuD;QACxE,yBAAoB,GAApB,oBAAoB,CAAgE;IACtG,CAAC;IAEJ;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,OAAO,CAAC,WAAmB,EAAE,MAAmB;QAClD,MAAM,aAAa,GACf,MAAM,CAAC,QAAQ,KAAK,SAAS;YACzB,CAAC,CAAC,MAAM,IAAI,CAAC,iBAAiB,CAAC,4BAA4B,CAAC,MAAM,CAAC,QAAQ,CAAC;YAC5E,CAAC,CAAC,MAAM,IAAI,CAAC,iBAAiB,CAAC,mBAAmB,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;QAE5E,MAAM,MAAM,GAAG,MAAM,uBAAuB,CAAC,aAAa,CAAC,CAAC;QAC5D,MAAM,gBAAgB,GAAG,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,aAAa,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;QAEhH,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC,IAAI,CAAC;QAC7D,gBAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC;QAEvD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;IACvD,CAAC;CACJ"}