@salesforce/sfdx-agent-harness-mastra 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,66 @@
+# @salesforce/sfdx-agent-harness-mastra
+
+Mastra-backed `AgentHarness` implementation for [`@salesforce/sfdx-agent-sdk`](../sfdx-agent-sdk). Provides
+`MastraHarnessFactory`, the entry point consumers pass to `createAgentManager`.
+
+## Install
+
+```bash
+npm install @salesforce/sfdx-agent-sdk @salesforce/sfdx-agent-harness-mastra
+```
+
+## Quick start
+
+```ts
+import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
+import { MastraHarnessFactory } from '@salesforce/sfdx-agent-harness-mastra';
+
+const manager = await createAgentManager('/path/to/storage', new MastraHarnessFactory());
+```
+
+See the [`@salesforce/sfdx-agent-sdk` README](../sfdx-agent-sdk/README.md) for the full consumer-facing API. For
+internal architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Public API
+
+| Export                                | Kind      | Description                                                                               |
+| ------------------------------------- | --------- | ----------------------------------------------------------------------------------------- |
+| `MastraHarnessFactory`                | class     | `HarnessFactory` that produces a Mastra-backed `AgentHarness` bound to a storage root.    |
+| `MastraModelConfigFactory`            | interface | Strategy for creating model configurations; injected into `MastraHarnessFactory`.         |
+| `ResolvedModelConfig`                 | type      | Return type of `MastraModelConfigFactory.create()` — wraps a `MastraModelConfig`.         |
+| `DefaultMastraModelConfigFactory`     | class     | Default factory using the Salesforce LLM Gateway (`SalesforceMastraModelGateway`).        |
+| `LLMGExpressMastraModelConfigFactory` | class     | Factory for LLM Gateway Express (API-key-authenticated, OpenAI-compatible endpoint).      |
+| `LLMGExpressConfig`                   | type      | Configuration for `LLMGExpressMastraModelConfigFactory` (`apiKey`, `baseUrl`, `modelId`). |
+
+### Using LLM Gateway Express
+
+```ts
+import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
+import { MastraHarnessFactory, LLMGExpressMastraModelConfigFactory } from '@salesforce/sfdx-agent-harness-mastra';
+
+const harnessFactory = new MastraHarnessFactory(
+  new LLMGExpressMastraModelConfigFactory({
+    apiKey: process.env.LLMG_EXPRESS_API_KEY!,
+    baseUrl: process.env.LLMG_EXPRESS_BASE_URL!,
+    modelId: 'claude-sonnet-4-20250514',
+  }),
+);
+
+const manager = await createAgentManager('/path/to/storage', harnessFactory);
+```
+
+## Development
+
+```bash
+npm run build              # TypeScript compilation
+npm run test               # Unit tests with coverage
+npm run lint               # ESLint
+npm run lint:fix           # Auto-fix ESLint issues
+npm run format             # Prettier
+npm run clean              # Remove build artifacts
+```
+
+From the repo root:
+
+- `npm run build -w @salesforce/sfdx-agent-harness-mastra`
+- `npm run test -w @salesforce/sfdx-agent-harness-mastra`

package/dist/default-model-config-factory.d.ts

@@ -0,0 +1,11 @@
+import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
+import type { MastraModelConfigFactory, ResolvedModelConfig } from './model-config-factory.js';
+/**
+ * Default model configuration factory that uses the Salesforce LLM Gateway.
+ *
+ * Wraps the LLMGatewayClient in a SalesforceMastraModelGateway and calls
+ * resolveLanguageModel() to produce the LanguageModelV2 that Mastra consumes.
+ */
+export declare class DefaultMastraModelConfigFactory implements MastraModelConfigFactory {
+    create(llmGatewayClient: LLMGatewayClient): ResolvedModelConfig;
+}

package/dist/default-model-config-factory.js

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { SalesforceMastraModelGateway } from './salesforce-llm-gateway.js';
+/**
+ * Default model configuration factory that uses the Salesforce LLM Gateway.
+ *
+ * Wraps the LLMGatewayClient in a SalesforceMastraModelGateway and calls
+ * resolveLanguageModel() to produce the LanguageModelV2 that Mastra consumes.
+ */
+export class DefaultMastraModelConfigFactory {
+    create(llmGatewayClient) {
+        const agentGateway = new SalesforceMastraModelGateway(llmGatewayClient);
+        return { model: agentGateway.resolveLanguageModel() };
+    }
+}
+//# sourceMappingURL=default-model-config-factory.js.map

package/dist/default-model-config-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-model-config-factory.js","sourceRoot":"","sources":["../src/default-model-config-factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,OAAO,+BAA+B;IACxC,MAAM,CAAC,gBAAkC;QACrC,MAAM,YAAY,GAAG,IAAI,4BAA4B,CAAC,gBAAgB,CAAC,CAAC;QACxE,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,oBAAoB,EAAE,EAAE,CAAC;IAC1D,CAAC;CACJ"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { MastraHarnessFactory } from './mastra-harness-factory.js';
+export type { MastraModelConfigFactory, ResolvedModelConfig } from './model-config-factory.js';
+export { DefaultMastraModelConfigFactory } from './default-model-config-factory.js';
+export { LLMGExpressMastraModelConfigFactory, type LLMGExpressConfig } from './llmg-express-model-config-factory.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export { MastraHarnessFactory } from './mastra-harness-factory.js';
+export { DefaultMastraModelConfigFactory } from './default-model-config-factory.js';
+export { LLMGExpressMastraModelConfigFactory } from './llmg-express-model-config-factory.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;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEnE,OAAO,EAAE,+BAA+B,EAAE,MAAM,mCAAmC,CAAC;AACpF,OAAO,EAAE,mCAAmC,EAA0B,MAAM,wCAAwC,CAAC"}

package/dist/llmg-express-model-config-factory.d.ts

@@ -0,0 +1,23 @@
+import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
+import type { MastraModelConfigFactory, ResolvedModelConfig } from './model-config-factory.js';
+export interface LLMGExpressConfig {
+    /** API key for authenticating with LLM Gateway Express. */
+    apiKey: string;
+    /** Base URL of the OpenAI-compatible endpoint. */
+    baseUrl: string;
+    /** Model identifier at the endpoint (e.g., 'claude-sonnet-4-20250514'). */
+    modelId: string;
+}
+/**
+ * Model configuration factory for LLM Gateway Express (non-production,
+ * API-key-authenticated, OpenAI-compatible endpoint).
+ *
+ * This factory ignores the LLMGatewayClient parameter entirely and produces
+ * a Mastra OpenAICompatibleConfig that Mastra resolves internally using its
+ * built-in OpenAI-compatible provider support.
+ */
+export declare class LLMGExpressMastraModelConfigFactory implements MastraModelConfigFactory {
+    private readonly config;
+    constructor(config: LLMGExpressConfig);
+    create(_llmGatewayClient: LLMGatewayClient): ResolvedModelConfig;
+}

package/dist/llmg-express-model-config-factory.js

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Model configuration factory for LLM Gateway Express (non-production,
+ * API-key-authenticated, OpenAI-compatible endpoint).
+ *
+ * This factory ignores the LLMGatewayClient parameter entirely and produces
+ * a Mastra OpenAICompatibleConfig that Mastra resolves internally using its
+ * built-in OpenAI-compatible provider support.
+ */
+export class LLMGExpressMastraModelConfigFactory {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    create(_llmGatewayClient) {
+        const model = {
+            providerId: 'llmg-express',
+            modelId: this.config.modelId,
+            url: this.config.baseUrl,
+            apiKey: this.config.apiKey,
+        };
+        return { model };
+    }
+}
+//# sourceMappingURL=llmg-express-model-config-factory.js.map

package/dist/llmg-express-model-config-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llmg-express-model-config-factory.js","sourceRoot":"","sources":["../src/llmg-express-model-config-factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAeH;;;;;;;GAOG;AACH,MAAM,OAAO,mCAAmC;IACf;IAA7B,YAA6B,MAAyB;QAAzB,WAAM,GAAN,MAAM,CAAmB;IAAG,CAAC;IAE1D,MAAM,CAAC,iBAAmC;QACtC,MAAM,KAAK,GAA2B;YAClC,UAAU,EAAE,cAAc;YAC1B,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YACxB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;SAC7B,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,CAAC;IACrB,CAAC;CACJ"}

package/dist/mastra-event-adapter.d.ts

@@ -0,0 +1,73 @@
+import type { ChunkType } from '@mastra/core/stream';
+import { type LogBus } from '@salesforce/agentic-common';
+import type { ChatEvent } from '@salesforce/sfdx-agent-sdk';
+/**
+ * Adapts Mastra `ChunkType` stream events to our {@link ChatEvent} discriminated union.
+ *
+ * ### Usage
+ *
+ * This adapter is intended to be used by `MastraHarness.stream()` to convert
+ * Mastra's framework-specific `fullStream` output into the harness-agnostic
+ * `eventStream` expected by `ChatSession`.
+ *
+ * ```typescript
+ * // Inside MastraHarness.stream():
+ * const output = await agent.stream(message, options);
+ * const adapter = new MastraEventAdapter();
+ *
+ * async function* createEventStream() {
+ *     for await (const chunk of output.fullStream) {
+ *         const event = adapter.toChatEvent(chunk);
+ *         if (event) yield event;
+ *     }
+ * }
+ * ```
+ *
+ * ### Stream Event Mapping
+ *
+ * | Mastra ChunkType        | Our ChatEvent             | Payload Mapping                                        |
+ * | ----------------------- | ------------------------- | ------------------------------------------------------ |
+ * | `text-delta`            | `text-delta`              | `{ text }` from `payload.text`                         |
+ * | `reasoning-delta`       | `reasoning-delta`         | `{ text }` from `payload.text`                         |
+ * | `tool-call`             | `tool-call`               | `{ toolCallId, toolName, args }`                       |
+ * | `tool-call-approval`    | `tool-approval-request`   | `{ toolCall: { toolCallId, toolName, args } }` — stream suspends |
+ * | `tool-result`           | `tool-result`             | `{ toolCallId, toolName, result, isError: false }`     |
+ * | `tool-error`            | `tool-result`             | `{ toolCallId, toolName, result: error, isError: true}`|
+ * | `step-start`            | `step-start`              | `{ stepIndex }` from step metadata                     |
+ * | `step-finish`           | `step-finish`             | `{ stepIndex, finishReason, usage }` from `stepResult` |
+ * | `finish`                | `finish`                  | `{ finishReason, usage }` from `output`                |
+ * | `error` / `tripwire`    | `error`                   | `{ error, code? }`                                     |
+ * | `abort`                 | `error`                   | `{ error: DOMException('AbortError'), code: 'abort' }` |
+ * | `start`                 | `start`                   | Symmetric counterpart to `finish`                      |
+ * | `text-start`,           | *(skipped)*               | Informational lifecycle events — `undefined` returned  |
+ * | `text-end`,             |                           |                                                        |
+ * | `reasoning-start`,      |                           |                                                        |
+ * | `reasoning-end`         |                           |                                                        |
+ * | `source`, `file`,       | *(skipped)*               | Known but unsupported — future ChatEvent candidates    |
+ * | `tool-call-delta`,      |                           |                                                        |
+ * | `tool-call-suspended`,  |                           |                                                        |
+ * | `object`, `tool-output` |                           |                                                        |
+ * | *(all others)*          | `unmapped-chunk`          | `{ chunkType, rawChunk }` for observability            |
+ *
+ * Stateful per stream — a new instance must be created for each `MastraHarness.stream()` call.
+ */
+export declare class MastraEventAdapter {
+    private readonly logBus?;
+    private stepIndex;
+    /**
+     * @param logBus - Optional structured-log sink. When supplied, the adapter emits a `debug`
+     *   log for each chunk it intentionally drops (informational lifecycle events the SDK
+     *   doesn't model, and known-but-unsupported chunk types) so consumers can observe what's
+     *   being filtered without it leaking into the public `ChatEvent` stream.
+     */
+    constructor(logBus?: LogBus | undefined);
+    /**
+     * Convert a Mastra stream chunk to a ChatEvent.
+     *
+     * @param chunk - A Mastra `ChunkType` from `agent.stream().fullStream`.
+     * @returns The corresponding {@link ChatEvent}, `undefined` for
+     *   informational chunks that should be silently skipped, or an
+     *   `UnmappedChunkEvent` for truly unrecognized chunk types.
+     */
+    toChatEvent(chunk: ChunkType): ChatEvent | undefined;
+}

package/dist/mastra-event-adapter.js

@@ -0,0 +1,204 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { getErrorMessage } from '@salesforce/agentic-common';
+/**
+ * Adapts Mastra `ChunkType` stream events to our {@link ChatEvent} discriminated union.
+ *
+ * ### Usage
+ *
+ * This adapter is intended to be used by `MastraHarness.stream()` to convert
+ * Mastra's framework-specific `fullStream` output into the harness-agnostic
+ * `eventStream` expected by `ChatSession`.
+ *
+ * ```typescript
+ * // Inside MastraHarness.stream():
+ * const output = await agent.stream(message, options);
+ * const adapter = new MastraEventAdapter();
+ *
+ * async function* createEventStream() {
+ *     for await (const chunk of output.fullStream) {
+ *         const event = adapter.toChatEvent(chunk);
+ *         if (event) yield event;
+ *     }
+ * }
+ * ```
+ *
+ * ### Stream Event Mapping
+ *
+ * | Mastra ChunkType        | Our ChatEvent             | Payload Mapping                                        |
+ * | ----------------------- | ------------------------- | ------------------------------------------------------ |
+ * | `text-delta`            | `text-delta`              | `{ text }` from `payload.text`                         |
+ * | `reasoning-delta`       | `reasoning-delta`         | `{ text }` from `payload.text`                         |
+ * | `tool-call`             | `tool-call`               | `{ toolCallId, toolName, args }`                       |
+ * | `tool-call-approval`    | `tool-approval-request`   | `{ toolCall: { toolCallId, toolName, args } }` — stream suspends |
+ * | `tool-result`           | `tool-result`             | `{ toolCallId, toolName, result, isError: false }`     |
+ * | `tool-error`            | `tool-result`             | `{ toolCallId, toolName, result: error, isError: true}`|
+ * | `step-start`            | `step-start`              | `{ stepIndex }` from step metadata                     |
+ * | `step-finish`           | `step-finish`             | `{ stepIndex, finishReason, usage }` from `stepResult` |
+ * | `finish`                | `finish`                  | `{ finishReason, usage }` from `output`                |
+ * | `error` / `tripwire`    | `error`                   | `{ error, code? }`                                     |
+ * | `abort`                 | `error`                   | `{ error: DOMException('AbortError'), code: 'abort' }` |
+ * | `start`                 | `start`                   | Symmetric counterpart to `finish`                      |
+ * | `text-start`,           | *(skipped)*               | Informational lifecycle events — `undefined` returned  |
+ * | `text-end`,             |                           |                                                        |
+ * | `reasoning-start`,      |                           |                                                        |
+ * | `reasoning-end`         |                           |                                                        |
+ * | `source`, `file`,       | *(skipped)*               | Known but unsupported — future ChatEvent candidates    |
+ * | `tool-call-delta`,      |                           |                                                        |
+ * | `tool-call-suspended`,  |                           |                                                        |
+ * | `object`, `tool-output` |                           |                                                        |
+ * | *(all others)*          | `unmapped-chunk`          | `{ chunkType, rawChunk }` for observability            |
+ *
+ * Stateful per stream — a new instance must be created for each `MastraHarness.stream()` call.
+ */
+export class MastraEventAdapter {
+    logBus;
+    stepIndex = 0;
+    /**
+     * @param logBus - Optional structured-log sink. When supplied, the adapter emits a `debug`
+     *   log for each chunk it intentionally drops (informational lifecycle events the SDK
+     *   doesn't model, and known-but-unsupported chunk types) so consumers can observe what's
+     *   being filtered without it leaking into the public `ChatEvent` stream.
+     */
+    constructor(logBus) {
+        this.logBus = logBus;
+    }
+    /**
+     * Convert a Mastra stream chunk to a ChatEvent.
+     *
+     * @param chunk - A Mastra `ChunkType` from `agent.stream().fullStream`.
+     * @returns The corresponding {@link ChatEvent}, `undefined` for
+     *   informational chunks that should be silently skipped, or an
+     *   `UnmappedChunkEvent` for truly unrecognized chunk types.
+     */
+    toChatEvent(chunk) {
+        switch (chunk.type) {
+            case 'text-delta':
+                return { type: 'text-delta', text: chunk.payload.text };
+            case 'reasoning-delta':
+                return { type: 'reasoning-delta', text: chunk.payload.text };
+            case 'tool-call':
+                return {
+                    type: 'tool-call',
+                    toolCallId: chunk.payload.toolCallId,
+                    toolName: chunk.payload.toolName,
+                    args: (chunk.payload.args ?? {}),
+                };
+            case 'tool-call-approval':
+                return {
+                    type: 'tool-approval-request',
+                    toolCall: {
+                        toolCallId: chunk.payload.toolCallId,
+                        toolName: chunk.payload.toolName,
+                        args: chunk.payload.args,
+                    },
+                };
+            case 'tool-result':
+                return {
+                    type: 'tool-result',
+                    toolCallId: chunk.payload.toolCallId,
+                    toolName: chunk.payload.toolName,
+                    result: chunk.payload.result,
+                    isError: false,
+                };
+            case 'tool-error':
+                return {
+                    type: 'tool-result',
+                    toolCallId: chunk.payload.toolCallId,
+                    toolName: chunk.payload.toolName,
+                    result: getErrorMessage(chunk.payload.error),
+                    isError: true,
+                };
+            case 'step-start':
+                return { type: 'step-start', stepIndex: this.stepIndex++ };
+            case 'step-finish':
+                return {
+                    type: 'step-finish',
+                    stepIndex: Math.max(this.stepIndex - 1, 0),
+                    finishReason: mapFinishReason(chunk.payload.stepResult.reason),
+                    usage: mapUsage(chunk.payload.output.usage),
+                };
+            case 'finish': {
+                const rawReason = chunk.payload.stepResult.reason;
+                // Mastra/AI SDK have no dedicated 'max-steps' finish reason. When the step
+                // limit is hit, Mastra terminates the loop and reports the LLM's last reason
+                // — 'tool-calls' — because the model wanted to invoke tools but the loop was
+                // killed before they could execute. A terminal `finish` with 'tool-calls' can
+                // ONLY occur during truncation; normal tool-call progress produces `step-finish`
+                // (the loop continues). This positional invariant is the detection mechanism.
+                const event = {
+                    type: 'finish',
+                    finishReason: rawReason === 'tool-calls' ? 'max-steps' : mapFinishReason(rawReason),
+                    usage: mapUsage(chunk.payload.output.usage),
+                };
+                this.stepIndex = 0;
+                return event;
+            }
+            case 'error': {
+                const rawError = chunk.payload.error;
+                return {
+                    type: 'error',
+                    error: rawError instanceof Error ? rawError : new Error(String(rawError)),
+                };
+            }
+            case 'tripwire':
+                return {
+                    type: 'error',
+                    error: new Error(chunk.payload.reason),
+                    code: 'tripwire',
+                };
+            case 'abort':
+                return {
+                    type: 'error',
+                    error: new DOMException('The stream was aborted.', 'AbortError'),
+                    code: 'abort',
+                };
+            case 'start':
+                return { type: 'start' };
+            // Informational lifecycle chunks from the harness with no semantic
+            // equivalent in our harness-agnostic ChatEvent model. Silently dropped.
+            case 'text-start':
+            case 'text-end':
+            case 'reasoning-start':
+            case 'reasoning-end':
+                this.logBus?.debug('Skipping informational Mastra chunk', { chunkType: chunk.type });
+                return undefined;
+            // Known harness chunk types not yet supported in the SDK's ChatEvent
+            // model. Silently dropped to avoid leaking harness internals via
+            // unmapped-chunk. Candidates for future ChatEvent variants when the
+            // corresponding features (citations, file generation, tool arg
+            // streaming, tool suspension, structured output) are supported.
+            case 'source':
+            case 'file':
+            case 'tool-call-delta':
+            case 'tool-call-input-streaming-start':
+            case 'tool-call-input-streaming-end':
+            case 'tool-call-suspended':
+            case 'object':
+            case 'tool-output':
+                this.logBus?.debug('Skipping unsupported Mastra chunk type', { chunkType: chunk.type });
+                return undefined;
+            default:
+                return { type: 'unmapped-chunk', chunkType: chunk.type, rawChunk: chunk };
+        }
+    }
+}
+function mapFinishReason(reason) {
+    if (reason === 'unknown')
+        return 'other';
+    return reason;
+}
+function mapUsage(usage) {
+    if (!usage)
+        return undefined;
+    return {
+        inputTokens: usage.inputTokens ?? undefined,
+        outputTokens: usage.outputTokens ?? undefined,
+        totalTokens: usage.totalTokens ?? undefined,
+        reasoningTokens: usage.reasoningTokens,
+        cachedInputTokens: usage.cachedInputTokens,
+    };
+}
+//# sourceMappingURL=mastra-event-adapter.js.map

package/dist/mastra-event-adapter.js.map

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

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

@@ -0,0 +1,9 @@
+import type { AgentHarness, HarnessFactory } from '@salesforce/sfdx-agent-sdk';
+import type { MastraModelConfigFactory } from './model-config-factory.js';
+export declare class MastraHarnessFactory implements HarnessFactory {
+    private readonly modelConfigFactory?;
+    readonly harnessId = "mastra";
+    readonly protocolVersion = 1;
+    constructor(modelConfigFactory?: MastraModelConfigFactory | undefined);
+    create(storageRootFolder: string): Promise<AgentHarness>;
+}

package/dist/mastra-harness-factory.js

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { MastraHarness } from './mastra-harness.js';
+export class MastraHarnessFactory {
+    modelConfigFactory;
+    harnessId = 'mastra';
+    protocolVersion = 1;
+    constructor(modelConfigFactory) {
+        this.modelConfigFactory = modelConfigFactory;
+    }
+    async create(storageRootFolder) {
+        return new MastraHarness(storageRootFolder, this.modelConfigFactory);
+    }
+}
+//# sourceMappingURL=mastra-harness-factory.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mastra-harness-factory.js","sourceRoot":"","sources":["../src/mastra-harness-factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,MAAM,OAAO,oBAAoB;IAIA;IAHpB,SAAS,GAAG,QAAQ,CAAC;IACrB,eAAe,GAAG,CAAC,CAAC;IAE7B,YAA6B,kBAA6C;QAA7C,uBAAkB,GAAlB,kBAAkB,CAA2B;IAAG,CAAC;IAE9E,KAAK,CAAC,MAAM,CAAC,iBAAyB;QAClC,OAAO,IAAI,aAAa,CAAC,iBAAiB,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;IACzE,CAAC;CACJ"}