@salesforce/sfdx-agent-harness-mastra 0.4.0 → 0.6.0

package/README.md

@@ -3,7 +3,8 @@
 Mastra-backed `AgentHarness` implementation for [`@salesforce/sfdx-agent-sdk`](../sfdx-agent-sdk). Provides
 `MastraHarnessFactory`, the entry point consumers pass to `createAgentManager`.
 
-> **Closed source.** This package is published to npm under the [Salesforce Public Code License](../../LICENSE.txt) and is for use by Salesforce only.
+> **Closed source.** This package is published to npm under the [Salesforce Public Code License](../../LICENSE.txt) and
+> is for use by Salesforce only.
 
 ## Install
 
@@ -25,6 +26,8 @@ internal architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ## Public API
 
+### Core
+
 | Export                                | Kind      | Description                                                                               |
 | ------------------------------------- | --------- | ----------------------------------------------------------------------------------------- |
 | `MastraHarnessFactory`                | class     | `HarnessFactory` that produces a Mastra-backed `AgentHarness` bound to a storage root.    |
@@ -34,6 +37,78 @@ internal architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).
 | `LLMGExpressMastraModelConfigFactory` | class     | Factory for LLM Gateway Express (API-key-authenticated, OpenAI-compatible endpoint).      |
 | `LLMGExpressConfig`                   | type      | Configuration for `LLMGExpressMastraModelConfigFactory` (`apiKey`, `baseUrl`, `modelId`). |
 
+### Extension surface
+
+These types let consumers reach Mastra-specific features through the SDK's typed `extensions` slot. The SDK infers
+`MastraAgentHarness` from `MastraHarnessFactory.create()`, so consumers usually don't reference these types explicitly —
+they show up via inference at the call site.
+
+| Export                   | Kind     | Description                                                                                                                                               |
+| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MastraAgentHarness`     | type     | Branded `AgentHarness` subtype; carries the Mastra-specific `extensions` namespace and the inferred config type.                                          |
+| `MastraAgentConfig`      | type     | `AgentConfig` extended with Mastra-only fields (currently `toolSearch`). Inferred at `manager.createAgent` automatically — annotation rarely needed.      |
+| `MastraToolSearchConfig` | type     | Shape of `MastraAgentConfig.toolSearch` (`pool`, `alwaysActive`, `topK`, `ttl`).                                                                          |
+| `formatMcpToolName`      | function | `(serverName: string, toolName: string) => string` — builds the namespaced MCP tool name (`${serverName}_${toolName}`) used in `toolSearch.alwaysActive`. |
+| `ToolSearchHandle`       | type     | Stable interface for the tool-search runtime: `id`, `getStateStats`, `clearState`, `clearAllState`, `cleanupNow`. Wraps Mastra's internal processor.      |
+| `SkillSearchHandle`      | type     | Stable interface for the skill-search runtime: `id` (Mastra's processor has no other public methods today; the harness owns lifecycle).                   |
+
+#### Tool search
+
+Hide a large tool catalog behind Mastra's `search_tools` / `load_tool` meta-tools:
+
+```ts
+import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
+import { MastraHarnessFactory, formatMcpToolName } from '@salesforce/sfdx-agent-harness-mastra';
+
+const manager = await createAgentManager(storageRoot, new MastraHarnessFactory());
+
+const agent = await manager.createAgent(projectRoot, {
+  instructions: '...',
+  tools: [...customTools],
+  mcpServers: { sfdx: { type: 'stdio', command: 'npx', args: ['@salesforce/mcp'] } },
+  toolSearch: {
+    pool: '*', // or an explicit name list
+    alwaysActive: ['lookup_account', formatMcpToolName('sfdx', 'deploy_metadata')],
+    topK: 5, // advisory; defaults to Mastra's 5
+    ttl: 3_600_000, // ms; advisory; defaults to Mastra's 1h
+  },
+});
+```
+
+When `toolSearch` is set, `createAgent` blocks on MCP discovery so MCP tools enter the searchable pool. Without
+`toolSearch`, MCP discovery stays non-blocking (existing behavior). `alwaysActive` tools are visible directly to the
+model; everything else lives in the searchable pool. Unknown `alwaysActive` names are kept (for late MCP discovery);
+unknown `pool` names are dropped.
+
+`MastraToolSearchConfig.topK` and `ttl` are advisory — Mastra applies its own defaults if omitted.
+
+#### Skill search
+
+Skills (`AgentConfig.skills`) load eagerly by default. When `toolSearch` is also set, skills load on demand via
+harness-injected `search_skills` / `load_skill` meta-tools (Mastra's `SkillSearchProcessor`). The gating is deliberate —
+consumers who opt into `toolSearch` get the same on-demand pattern across tools and skills.
+
+#### Operational handles
+
+Reach the tool-search and skill-search runtime state for an agent. The accessors return stable `ToolSearchHandle` /
+`SkillSearchHandle` interfaces — not Mastra's internal processor types — so consumer code keeps compiling across Mastra
+version bumps.
+
+```ts
+const tsHandle = manager.extensions.mastra.getToolSearchProcessor(agent.getId());
+//    ^? ToolSearchHandle | undefined
+const stats = tsHandle?.getStateStats();
+// { threadCount, oldestAccessTime }
+
+const ssHandle = manager.extensions.mastra.getSkillSearchProcessor(agent.getId());
+//    ^? SkillSearchHandle | undefined
+```
+
+Both return `undefined` when the agent doesn't have the corresponding feature configured (or doesn't exist). The
+Mastra-internal pool / index / loaded-tools state is intentionally not on the handle interface; the documented methods
+are `getStateStats()`, `clearState(threadId?)`, `clearAllState()`, and `cleanupNow()` on `ToolSearchHandle`, plus `id`
+on both handles.
+
 ### Using LLM Gateway Express
 
 ```ts

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { MastraHarnessFactory } from './mastra-harness-factory.js';
+export type { MastraAgentHarness } from './mastra-harness.js';
+export { type MastraAgentConfig, type MastraToolSearchConfig, type SkillSearchHandle, type ToolSearchHandle, formatMcpToolName, } from './tool-search.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

@@ -3,6 +3,7 @@
  * See LICENSE.txt for license terms.
  */
 export { MastraHarnessFactory } from './mastra-harness-factory.js';
+export { formatMcpToolName, } from './tool-search.js';
 export { DefaultMastraModelConfigFactory } from './default-model-config-factory.js';
 export { LLMGExpressMastraModelConfigFactory } from './llmg-express-model-config-factory.js';
 //# sourceMappingURL=index.js.map

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

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

package/dist/mastra-harness.d.ts

@@ -1,8 +1,10 @@
 import { Agent } from '@mastra/core/agent';
+import { SkillSearchProcessor, ToolSearchProcessor } from '@mastra/core/processors';
 import type { ChunkType } from '@mastra/core/stream';
 import { MCPClient } from '@mastra/mcp';
-import { type AgentHarness, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerInfo, type Message, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo } from '@salesforce/sfdx-agent-sdk';
+import { type AgentHarness, type WithAgentConfig, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerInfo, type Message, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo } from '@salesforce/sfdx-agent-sdk';
 import type { MastraModelConfigFactory } from './model-config-factory.js';
+import { type MastraAgentConfig, type SkillSearchHandle, type ToolSearchHandle } from './tool-search.js';
 import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
 import { Clock, type LogRecord, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
 import { type ToolsInput } from './utils.js';
@@ -49,8 +51,55 @@ interface MastraAgentState {
     mastraWorkspace?: Workspace;
     /** Tracks the active workflow run per thread for tool approval. */
     activeRuns: Map<string, ActiveRun>;
+    /** Tool-search processor instance, when `toolSearch` is configured on the factory. */
+    toolSearchProcessor?: ToolSearchProcessor;
+    /** Skill-search processor instance, when both `skills` and `toolSearch` are configured. */
+    skillSearchProcessor?: SkillSearchProcessor;
 }
-export declare class MastraHarness implements AgentHarness {
+/**
+ * Branded subtype consumers parameterize over to reach Mastra-specific
+ * runtime objects through the typed `extensions` namespace.
+ *
+ * Wrapped with `WithAgentConfig` so `manager.createAgent` autocompletes
+ * `MastraAgentConfig` fields (e.g. `toolSearch`) without an explicit
+ * type argument. The wrapper is type-only; it never exists at runtime.
+ *
+ * Usage:
+ * ```ts
+ * const manager = await createAgentManager(
+ *     storageRootFolder,
+ *     new MastraHarnessFactory(),
+ * );
+ * // manager.createAgent autocompletes `toolSearch` via WithAgentConfig:
+ * const agent = await manager.createAgent(projectRoot, {
+ *     instructions: '...',
+ *     toolSearch: { pool: '*', alwaysActive: ['lookup_account'] },
+ * });
+ * const processor = manager.extensions.mastra.getToolSearchProcessor(agent.getId());
+ * ```
+ */
+export type MastraAgentHarness = WithAgentConfig<AgentHarness & {
+    readonly harnessId: 'mastra';
+    readonly extensions: {
+        mastra: {
+            /**
+             * Returns a {@link ToolSearchHandle} for an agent, or `undefined`
+             * if the agent has no tool-search configured or doesn't exist.
+             * The handle wraps Mastra's internal `ToolSearchProcessor` with
+             * a stable surface (state stats + thread-state management).
+             */
+            getToolSearchProcessor(agentId: string): ToolSearchHandle | undefined;
+            /**
+             * Returns a {@link SkillSearchHandle} for an agent, or `undefined`
+             * if the agent doesn't have both `skills` and `toolSearch` configured
+             * (skill search is only enabled when both are set; without `toolSearch`,
+             * Mastra falls back to eager skill loading).
+             */
+            getSkillSearchProcessor(agentId: string): SkillSearchHandle | undefined;
+        };
+    };
+}, MastraAgentConfig>;
+export declare class MastraHarness implements MastraAgentHarness {
     private readonly storageRootFolder;
     private readonly modelConfigFactory;
     private readonly clock;
@@ -67,6 +116,11 @@ export declare class MastraHarness implements AgentHarness {
     private readonly memory;
     private readonly mastra;
     private readonly buses;
+    /**
+     * Mastra-specific extension surface, typed off `MastraAgentHarness`. The
+     * SDK never reads this; consumers reach through `manager.extensions.mastra`.
+     */
+    readonly extensions: MastraAgentHarness['extensions'];
     constructor(storageRootFolder: string, modelConfigFactory?: MastraModelConfigFactory, clock?: Clock, idGenerator?: UniqueIDGenerator);
     /**
      * @requirements

package/dist/mastra-harness.js

@@ -7,14 +7,17 @@ import path from 'node:path';
 import { Agent } from '@mastra/core/agent';
 import { Mastra } from '@mastra/core/mastra';
 import { Memory } from '@mastra/memory';
+import { SkillSearchProcessor, ToolSearchProcessor } from '@mastra/core/processors';
 import { LibSQLStore } from '@mastra/libsql';
 import { MCPClient } from '@mastra/mcp';
 import { AgentSDKError, AgentSDKErrorType, DEFAULT_MAX_STEPS, HarnessBusOwner, McpServerStatus, } from '@salesforce/sfdx-agent-sdk';
 import { MastraEventAdapter } from './mastra-event-adapter.js';
 import { mapMastraToMessage, mapMessageToMastra, partToTranscriptText } from './mastra-message-mapper.js';
+import { isStandardSchemaWithJSON, standardSchemaToJSONSchema } from '@mastra/schema-compat';
 import { mapToolDefinitionsToMastraTools } from './mastra-tool-mapper.js';
 import { hasEnabledServers, mapToMastraMCPServers } from './mcp-config-mapper.js';
 import { DefaultMastraModelConfigFactory } from './default-model-config-factory.js';
+import { partitionPool, } from './tool-search.js';
 import { Clock, getErrorMessage, RealClock, splitFrontmatterAndBody, UUIDGenerator, } from '@salesforce/agentic-common';
 import { makeAbortable } from './utils.js';
 import { Workspace, LocalFilesystem, LocalSandbox, WORKSPACE_TOOLS, WORKSPACE_TOOLS_PREFIX, } from '@mastra/core/workspace';
@@ -165,6 +168,78 @@ async function listMarkdownFilesInDirectory(dir) {
     }
     return names.sort().map((name) => path.join(dir, name));
 }
+/**
+ * Projects the namespaced Mastra `ToolAction` map for one MCP server into the
+ * SDK's harness-agnostic `McpToolInfo[]` shape.
+ *
+ * Mastra's `MCPClient` pipes each protocol `Tool` from `tools/list` through
+ * `convertInputSchema` (which yields plain JSON Schema) and then through
+ * `createTool()`, which wraps the result in a Standard Schema envelope —
+ * `tool.inputSchema` ends up as `{ '~standard': { version, vendor, validate,
+ * jsonSchema } }`, **not** the raw JSON Schema the SDK contract promises.
+ * The harness undoes that wrap here via `standardSchemaToJSONSchema(...,
+ * { io: 'input' })` so consumers reading `McpToolInfo.inputSchema` get the
+ * JSON Schema they expect. Conversion adds JSON Schema annotations the
+ * source server may not have declared (`$schema`, `additionalProperties:
+ * false`); both are valid JSON Schema and we forward them untouched.
+ *
+ * Field-by-field forwarding:
+ *
+ * - `name`: the namespaced map key (e.g. `sf_query`).
+ * - `description`: collapsed to `undefined` when Mastra's `tool.description ||
+ *   ""` fallback fired and the original was missing — empty strings are not
+ *   useful UX.
+ * - `inputSchema`: unwrapped from the Standard Schema envelope to JSON
+ *   Schema. If the value is already plain JSON Schema (e.g. from a unit-test
+ *   stub that bypasses `createTool`), it's forwarded as-is. The unwrap
+ *   invokes the provider's lazy JSON-Schema serializer (e.g. Zod's
+ *   `toJSONSchema`), which can throw for unrepresentable types or circular
+ *   refs; on any failure we degrade `inputSchema` to `undefined` (the SDK
+ *   contract types it optional) and emit a `warn` log so the failure is
+ *   observable. A single hostile tool must not erase the full status snapshot.
+ * - `annotations`: passed through structurally; Mastra's `ToolAnnotations`
+ *   interface mirrors the MCP spec field-for-field, matching `McpToolAnnotations`.
+ *
+ * `outputSchema` is not forwarded — `@mastra/mcp` strips it from each wrapped
+ * tool deliberately (see the MCP-spec rationale documented on
+ * {@link McpToolInfo}), so the SDK contract omits the field entirely.
+ */
+function mapMastraToolsToMcpToolInfo(tools, logBus) {
+    return Object.entries(tools).map(([name, tool]) => {
+        const info = { name };
+        const description = tool.description;
+        if (description !== undefined && description !== '') {
+            info.description = description;
+        }
+        const inputSchema = tool.inputSchema;
+        if (isStandardSchemaWithJSON(inputSchema)) {
+            // Real `createTool`-wrapped path. `io: 'input'` selects the input shape
+            // for tool parameters per `@mastra/schema-compat`'s documented contract.
+            // The unwrap calls the provider's lazy JSON-Schema serializer, which
+            // can throw — degrade to `undefined` rather than erase the snapshot.
+            try {
+                info.inputSchema = standardSchemaToJSONSchema(inputSchema, { io: 'input' });
+            }
+            catch (err) {
+                logBus?.warn('Failed to unwrap MCP tool inputSchema; omitting from McpToolInfo', {
+                    toolName: name,
+                    error: getErrorMessage(err),
+                });
+            }
+        }
+        else if (typeof inputSchema === 'object' && inputSchema !== null) {
+            // Plain JSON Schema (no `~standard` envelope) — forward as-is. Reached
+            // by unit-test fixtures that build the tools map directly without going
+            // through `@mastra/mcp`'s wrapping.
+            info.inputSchema = inputSchema;
+        }
+        const annotations = tool.mcp?.annotations;
+        if (annotations !== undefined) {
+            info.annotations = annotations;
+        }
+        return info;
+    });
+}
 export class MastraHarness {
     storageRootFolder;
     modelConfigFactory;
@@ -182,6 +257,24 @@ export class MastraHarness {
     memory;
     mastra;
     buses = new HarnessBusOwner();
+    /**
+     * Mastra-specific extension surface, typed off `MastraAgentHarness`. The
+     * SDK never reads this; consumers reach through `manager.extensions.mastra`.
+     */
+    extensions = {
+        mastra: {
+            // Return type narrows the Mastra-internal processor to the
+            // stable `ToolSearchHandle` surface. The processor *is* a
+            // ToolSearchHandle structurally (it has all the listed methods),
+            // so no runtime wrapping is needed.
+            getToolSearchProcessor: (agentId) => {
+                return this.activeAgents.get(agentId)?.toolSearchProcessor;
+            },
+            getSkillSearchProcessor: (agentId) => {
+                return this.activeAgents.get(agentId)?.skillSearchProcessor;
+            },
+        },
+    };
     constructor(storageRootFolder, modelConfigFactory = new DefaultMastraModelConfigFactory(), clock = new RealClock(), idGenerator = new UUIDGenerator()) {
         this.storageRootFolder = storageRootFolder;
         this.modelConfigFactory = modelConfigFactory;
@@ -219,6 +312,7 @@ export class MastraHarness {
                 await s.ready.catch(() => undefined);
                 await s.client.disconnect();
             }));
+            state.skillSearchProcessor?.dispose();
         }));
         this.activeAgents.clear();
         await this.mastra?.shutdown();
@@ -346,6 +440,13 @@ export class MastraHarness {
         let mastraWorkspace;
         let agent;
         let mastraAgentAdded = false;
+        let toolSearchProcessor;
+        let toolSearchAlwaysActive;
+        let skillSearchProcessor;
+        // `toolSearch` rides through on the consumer's `MastraAgentConfig`
+        // even though `HarnessAgentConfig` itself doesn't declare it —
+        // `toHarnessConfig` preserves extra fields via spread.
+        const toolSearchConfig = config.toolSearch;
         try {
             const allowedPaths = (config.skills ?? []).filter((s) => path.isAbsolute(s));
             const localFs = new LocalFilesystem({ basePath: projectRoot, allowedPaths });
@@ -362,6 +463,38 @@ export class MastraHarness {
                 ])),
             });
             await mastraWorkspace.init();
+            // On-demand skill search: only when both `skills` and `toolSearch`
+            // are configured. Without `toolSearch`, Mastra's built-in eager
+            // skill loading is used (existing behavior).
+            if (mastraWorkspace.skills && toolSearchConfig) {
+                skillSearchProcessor = new SkillSearchProcessor({ workspace: mastraWorkspace });
+            }
+            // When toolSearch is configured, await MCP discovery so MCP tools
+            // can enter the searchable pool. Without it, MCP discovery stays
+            // non-blocking (existing behavior).
+            if (toolSearchConfig) {
+                if (mcpServerStates.size > 0) {
+                    await Promise.allSettled([...mcpServerStates.values()].map((s) => s.ready));
+                }
+                const mcpTools = [...mcpServerStates.values()].reduce((acc, s) => ({ ...acc, ...s.tools }), {});
+                const allTools = { ...customTools, ...mcpTools };
+                const knownNames = new Set(Object.keys(allTools));
+                const partition = partitionPool(toolSearchConfig.pool, toolSearchConfig.alwaysActive, knownNames);
+                toolSearchAlwaysActive = new Set(partition.alwaysActive);
+                const poolTools = {};
+                for (const name of partition.pool) {
+                    if (allTools[name]) {
+                        poolTools[name] = allTools[name];
+                    }
+                }
+                toolSearchProcessor = new ToolSearchProcessor({
+                    tools: poolTools,
+                    search: toolSearchConfig.topK !== undefined ? { topK: toolSearchConfig.topK } : undefined,
+                    ttl: toolSearchConfig.ttl,
+                });
+            }
+            const inputProcessorsList = [skillSearchProcessor, toolSearchProcessor].filter((p) => p !== undefined);
+            const inputProcessors = inputProcessorsList.length > 0 ? inputProcessorsList : undefined;
             agent = new Agent({
                 id: agentId,
                 name: config.name || agentId,
@@ -370,9 +503,21 @@ export class MastraHarness {
                 memory: this.memory,
                 tools: () => {
                     const mcpTools = [...mcpServerStates.values()].reduce((acc, s) => ({ ...acc, ...s.tools }), {});
-                    return { ...customTools, ...mcpTools };
+                    const merged = { ...customTools, ...mcpTools };
+                    if (!toolSearchAlwaysActive) {
+                        return merged;
+                    }
+                    // Only expose alwaysActive tools; the rest are behind search/load.
+                    const active = {};
+                    for (const [name, tool] of Object.entries(merged)) {
+                        if (toolSearchAlwaysActive.has(name)) {
+                            active[name] = tool;
+                        }
+                    }
+                    return active;
                 },
                 workspace: mastraWorkspace,
+                ...(inputProcessors ? { inputProcessors } : {}),
             });
             this.mastra.addAgent(agent);
             mastraAgentAdded = true;
@@ -382,12 +527,17 @@ export class MastraHarness {
                 mcpConfig: config.mcpServers,
                 mastraWorkspace,
                 activeRuns: new Map(),
+                toolSearchProcessor,
+                skillSearchProcessor,
             });
         }
         catch (error) {
             if (mastraAgentAdded) {
                 this.mastra.removeAgent(agentId);
             }
+            // SkillSearchProcessor schedules a TTL cleanup interval; dispose
+            // on failure so we don't leak a timer for a never-registered agent.
+            skillSearchProcessor?.dispose();
             await mastraWorkspace?.destroy().catch(() => undefined);
             await Promise.allSettled(Array.from(mcpServerStates.values()).map((s) => s.client.disconnect().catch(() => undefined)));
             throw error;
@@ -405,6 +555,7 @@ export class MastraHarness {
             await s.ready.catch(() => undefined);
             await s.client.disconnect();
         }));
+        state.skillSearchProcessor?.dispose();
         await state.mastraWorkspace?.destroy();
         this.mastra.removeAgent(agentId);
         return this.activeAgents.delete(agentId);
@@ -427,7 +578,11 @@ export class MastraHarness {
                 results.push({ error: serverState.error, name, status: McpServerStatus.Error, tools: [] });
             }
             else {
-                results.push({ name, status: McpServerStatus.Connected, tools: Object.keys(serverState.tools) });
+                results.push({
+                    name,
+                    status: McpServerStatus.Connected,
+                    tools: mapMastraToolsToMcpToolInfo(serverState.tools, this.buses.getLogBus()),
+                });
             }
         }
         if (state.mcpConfig) {
@@ -697,7 +852,13 @@ export class MastraHarness {
             perPage: false,
         });
         const logBus = this.buses.getLogBus();
+        // Drop Mastra's experimental `'signal'` role (system reminders the agent synthesizes via `createSignal()`,
+        // see `@mastra/core/dist/agent/signals.d.ts` — all `@experimental`). The SDK's `MessageRole` exposes only
+        // `'system' | 'user' | 'assistant' | 'tool'` and surfacing experimental upstream concepts would leak the
+        // harness internals up to consumers. If Mastra promotes signals to stable and we want them, the SDK
+        // contract needs to add the role first.
         return messages
+            .filter((m) => m.role !== 'signal')
             .map((m) => mapMastraToMessage(m, logBus))
             .sort((a, b) => (a.createdAt?.getTime() ?? 0) - (b.createdAt?.getTime() ?? 0));
     }

package/dist/mastra-message-mapper.d.ts

@@ -4,6 +4,9 @@ import { Clock, type LogBus } from '@salesforce/agentic-common';
 /**
  * Converts a Mastra persisted message into the SDK's {@link Message} type.
  *
+ * Callers must filter out Mastra's experimental `'signal'` role before invoking;
+ * those messages have no SDK equivalent and must not surface in `Message[]`.
+ *
  * Parts that have no SDK equivalent (source, file, step-start, and any
  * unrecognized upstream types including AI SDK v5 `data-*` metadata parts)
  * are silently dropped. Unrecognized types emit a structured `warn` log when a

package/dist/mastra-message-mapper.js

@@ -6,6 +6,9 @@ import { Clock, RealClock } from '@salesforce/agentic-common';
 /**
  * Converts a Mastra persisted message into the SDK's {@link Message} type.
  *
+ * Callers must filter out Mastra's experimental `'signal'` role before invoking;
+ * those messages have no SDK equivalent and must not surface in `Message[]`.
+ *
  * Parts that have no SDK equivalent (source, file, step-start, and any
  * unrecognized upstream types including AI SDK v5 `data-*` metadata parts)
  * are silently dropped. Unrecognized types emit a structured `warn` log when a
@@ -13,6 +16,9 @@ import { Clock, RealClock } from '@salesforce/agentic-common';
  * message history retrieval.
  */
 export function mapMastraToMessage(msg, logBus) {
+    if (msg.role === 'signal') {
+        throw new Error("mapMastraToMessage: 'signal' role messages must be filtered out before mapping");
+    }
     const parts = [];
     for (const part of msg.content.parts) {
         const mapped = mapMastraPartToMessagePart(part, logBus);

package/dist/mastra-tool-mapper.js

@@ -34,7 +34,7 @@ export function mapToolDefinitionsToMastraTools(tools) {
         const mastraTool = {
             id: tool.name,
             description: tool.description ?? '',
-            inputSchema: tool.inputSchema,
+            inputSchema: ensureJsonSchemaMarker(tool.inputSchema),
             requireApproval: true,
             execute: async (_inputData, context) => {
                 const resume = context.resumeData;
@@ -52,4 +52,18 @@ export function mapToolDefinitionsToMastraTools(tools) {
     }
     return result;
 }
+const JSON_SCHEMA_DRAFT = 'http://json-schema.org/draft-07/schema#';
+/**
+ * Stamp a Mastra-acceptable `$schema` marker onto an `inputSchema`.
+ * Mastra's `prepareToolsAndToolChoice` requires `$schema` to start with
+ * `http://json-schema.org/` (literal `http://`); anything else crashes.
+ * Existing valid markers are preserved.
+ */
+function ensureJsonSchemaMarker(schema) {
+    const existing = schema['$schema'];
+    if (typeof existing === 'string' && existing.startsWith('http://json-schema.org/')) {
+        return schema;
+    }
+    return { ...schema, $schema: JSON_SCHEMA_DRAFT };
+}
 //# sourceMappingURL=mastra-tool-mapper.js.map

package/dist/salesforce-llm-gateway.d.ts

@@ -1,10 +1,10 @@
 import { MastraModelGateway, type ProviderConfig } from '@mastra/core/llm';
-import type { LanguageModelV2 } from '@ai-sdk/provider';
+import type { LanguageModelV3 } from '@ai-sdk/provider';
 import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
 /**
  * Bridges the Salesforce LLM Gateway SDK to Mastra's MastraModelGateway interface.
  *
- * Translates AI SDK LanguageModelV2 calls into GatewayClient API calls,
+ * Translates AI SDK LanguageModelV3 calls into GatewayClient API calls,
  * mapping prompts, tools, and responses between the two type systems.
  * Uses chat() for non-streaming generation and chatStream() for streaming.
  */
@@ -12,14 +12,11 @@ export declare class SalesforceMastraModelGateway extends MastraModelGateway {
     private readonly gatewayClient;
     readonly id = "sfdc";
     readonly name = "Salesforce LLM Gateway";
-    private lastResponseTextPromise;
-    private resolveLastResponseText?;
     constructor(gatewayClient: LLMGatewayClient);
     getApiKey(_modelId: string): Promise<string>;
     buildUrl(_modelId: string, _envVars: Record<string, string>): string;
     fetchProviders(): Promise<Record<string, ProviderConfig>>;
-    resolveLanguageModel(): LanguageModelV2;
-    takeLastResponseText(): Promise<string | undefined>;
+    resolveLanguageModel(): LanguageModelV3;
     private doGenerate;
     private doStream;
     private buildChatRequest;

package/dist/salesforce-llm-gateway.js

@@ -7,7 +7,7 @@ import { ModelName, Models } from '@salesforce/llm-gateway-sdk';
 /**
  * Bridges the Salesforce LLM Gateway SDK to Mastra's MastraModelGateway interface.
  *
- * Translates AI SDK LanguageModelV2 calls into GatewayClient API calls,
+ * Translates AI SDK LanguageModelV3 calls into GatewayClient API calls,
  * mapping prompts, tools, and responses between the two type systems.
  * Uses chat() for non-streaming generation and chatStream() for streaming.
  */
@@ -15,8 +15,6 @@ export class SalesforceMastraModelGateway extends MastraModelGateway {
     gatewayClient;
     id = 'sfdc';
     name = 'Salesforce LLM Gateway';
-    lastResponseTextPromise = Promise.resolve(undefined);
-    resolveLastResponseText;
     constructor(gatewayClient) {
         super();
         this.gatewayClient = gatewayClient;
@@ -43,7 +41,7 @@ export class SalesforceMastraModelGateway extends MastraModelGateway {
     resolveLanguageModel() {
         const model = this.gatewayClient.getModel();
         return {
-            specificationVersion: 'v2',
+            specificationVersion: 'v3',
             provider: 'salesforce-llm-gateway',
             modelId: model.name,
             supportedUrls: {},
@@ -51,16 +49,10 @@ export class SalesforceMastraModelGateway extends MastraModelGateway {
             doStream: (options) => this.doStream(options),
         };
     }
-    async takeLastResponseText() {
-        const text = await this.lastResponseTextPromise;
-        this.lastResponseTextPromise = Promise.resolve(undefined);
-        return text;
-    }
     async doGenerate(options) {
         const chatRequest = this.buildChatRequest(options);
         const response = await this.gatewayClient.chat(chatRequest);
         const { generatedText, toolInvocations, usage: responseUsage, finishReason: rawFinishReason } = response.data;
-        this.lastResponseTextPromise = Promise.resolve(generatedText || undefined);
         const content = [];
         if (generatedText) {
             content.push({ type: 'text', text: generatedText });
@@ -74,39 +66,20 @@ export class SalesforceMastraModelGateway extends MastraModelGateway {
             });
         }
         const sawToolCalls = (toolInvocations ?? []).length > 0;
-        const finishReason = sawToolCalls
-            ? 'tool-calls'
-            : rawFinishReason === 'length'
-                ? 'length'
-                : 'stop';
-        const usage = responseUsage
-            ? {
-                inputTokens: responseUsage.inputTokens,
-                outputTokens: responseUsage.outputTokens,
-                totalTokens: responseUsage.totalTokens,
-                reasoningTokens: responseUsage.reasoningTokens,
-            }
-            : { inputTokens: undefined, outputTokens: undefined, totalTokens: undefined };
+        const finishReason = mapFinishReason(rawFinishReason, sawToolCalls);
+        const usage = mapUsage(responseUsage);
         return { content, finishReason, usage, warnings: [] };
     }
     async doStream(options) {
         const chatRequest = this.buildChatRequest(options);
         const response = await this.gatewayClient.chatStream(chatRequest);
         let sawToolCalls = false;
-        let aggregatedText = '';
         let textSpanOpen = false;
         let textSpanId = 0;
-        this.lastResponseTextPromise = new Promise((resolve) => {
-            this.resolveLastResponseText = resolve;
-        });
         const stream = new ReadableStream({
             start: async (controller) => {
                 try {
-                    let lastUsage = {
-                        inputTokens: undefined,
-                        outputTokens: undefined,
-                        totalTokens: undefined,
-                    };
+                    let lastUsage = mapUsage(undefined);
                     for await (const chunk of response.data) {
                         if (chunk.generatedText && !chunk.done) {
                             if (!textSpanOpen) {
@@ -118,7 +91,6 @@ export class SalesforceMastraModelGateway extends MastraModelGateway {
                                 delta: chunk.generatedText,
                                 id: `text-${textSpanId}`,
                             });
-                            aggregatedText += chunk.generatedText;
                         }
                         if (chunk.toolInvocations?.length) {
                             // Close any open text span before emitting tool calls so that
@@ -139,18 +111,13 @@ export class SalesforceMastraModelGateway extends MastraModelGateway {
                             }
                         }
                         if (chunk.usage) {
-                            lastUsage = {
-                                inputTokens: chunk.usage.inputTokens,
-                                outputTokens: chunk.usage.outputTokens,
-                                totalTokens: chunk.usage.totalTokens,
-                                reasoningTokens: chunk.usage.reasoningTokens,
-                            };
+                            lastUsage = mapUsage(chunk.usage);
                         }
                         if (chunk.done) {
                             if (textSpanOpen) {
                                 controller.enqueue({ type: 'text-end', id: `text-${textSpanId}` });
                             }
-                            const finishReason = sawToolCalls ? 'tool-calls' : 'stop';
+                            const finishReason = mapFinishReason(chunk.finishReason, sawToolCalls);
                             controller.enqueue({
                                 type: 'finish',
                                 finishReason,
@@ -166,9 +133,6 @@ export class SalesforceMastraModelGateway extends MastraModelGateway {
                     controller.enqueue({ type: 'error', error });
                     controller.close();
                 }
-                finally {
-                    this.resolveLastResponseText?.(aggregatedText || undefined);
-                }
             },
         });
         return { stream };
@@ -224,7 +188,13 @@ export class SalesforceMastraModelGateway extends MastraModelGateway {
                     return msg;
                 }
                 case 'tool':
-                    return message.content.map((part) => ({
+                    // V3's `tool` role content can include `tool-approval-response` parts alongside
+                    // `tool-result` parts. We do not surface tool-approval-request to consumers, so we
+                    // never receive approval-response parts in practice — but filter defensively so
+                    // the gateway is forward-compatible with future approval flows.
+                    return message.content
+                        .filter((part) => part.type === 'tool-result')
+                        .map((part) => ({
                         role: 'tool',
                         content: this.toolResultOutputToString(part.output),
                         tool_call_id: part.toolCallId,
@@ -246,6 +216,8 @@ export class SalesforceMastraModelGateway extends MastraModelGateway {
                     .filter((v) => v.type === 'text')
                     .map((v) => v.text)
                     .join('');
+            case 'execution-denied':
+                return output.reason ?? 'tool execution denied';
         }
     }
     translateTools(options) {
@@ -263,4 +235,69 @@ export class SalesforceMastraModelGateway extends MastraModelGateway {
         }));
     }
 }
+/**
+ * Maps a Salesforce LLM Gateway raw finish-reason string to the AI SDK V3
+ * `LanguageModelV3FinishReason` object shape. V3 finish reasons are an object
+ * with a `unified` enum field (the cross-provider canonical reason) and a `raw`
+ * field (the original provider string, preserved for debugging).
+ *
+ * The gateway's `FinishReason` union spans GPT-5 (`stop` / `length` / `tool_calls`)
+ * and Claude (`end_turn` / `max_tokens` / `tool_use`); we collapse both vocabularies
+ * onto V3's unified set.
+ *
+ * If `sawToolCalls` is true, `unified` is forced to `'tool-calls'` regardless of
+ * what the gateway returned — the gateway can report a non-tool reason even when
+ * tool invocations are present, and Mastra's downstream loop relies on
+ * `'tool-calls'` to schedule the next step.
+ */
+function mapFinishReason(rawFinishReason, sawToolCalls) {
+    const unified = sawToolCalls
+        ? 'tool-calls'
+        : rawFinishReason === 'length' || rawFinishReason === 'max_tokens'
+            ? 'length'
+            : rawFinishReason === 'tool_calls' || rawFinishReason === 'tool_use'
+                ? 'tool-calls'
+                : 'stop';
+    return { unified, raw: rawFinishReason };
+}
+/**
+ * Maps a Salesforce LLM Gateway `TokenUsage` (flat shape) to the AI SDK V3
+ * `LanguageModelV3Usage` shape (nested input/output groups). V3 dropped the
+ * top-level `totalTokens` field; downstream consumers (e.g. `MastraEventAdapter`)
+ * read a flat `totalTokens` from Mastra's `LanguageModelUsage` extension, which
+ * Mastra recomputes as `inputTokens.total + outputTokens.total`.
+ *
+ * Two adaptations matter for token-count fidelity:
+ *
+ * 1. **Reasoning tokens roll up into `outputTokens.total`** to match V3's spec
+ *    that `outputTokens.total = outputTokens.text + outputTokens.reasoning`.
+ *    Without this, GPT-5 responses with reasoning would lose those tokens from
+ *    the recomputed flat `totalTokens` (the V2 path preserved the gateway's
+ *    `totalTokens` directly, which already included reasoning).
+ * 2. **Cache tokens populate `inputTokens.cacheRead` / `cacheWrite`** for Claude
+ *    prompt caching. We do not roll these into `inputTokens.total` because
+ *    Anthropic's accounting treats cache reads as billable input replacement
+ *    (already counted in the gateway's `inputTokens`) and cache writes as a
+ *    separate billable line (not part of `inputTokens`).
+ */
+function mapUsage(responseUsage) {
+    const outputTokens = responseUsage?.outputTokens;
+    const reasoningTokens = responseUsage?.reasoningTokens;
+    const outputTotal = outputTokens === undefined && reasoningTokens === undefined
+        ? undefined
+        : (outputTokens ?? 0) + (reasoningTokens ?? 0);
+    return {
+        inputTokens: {
+            total: responseUsage?.inputTokens,
+            noCache: undefined,
+            cacheRead: responseUsage?.cacheReadTokens,
+            cacheWrite: responseUsage?.cacheWriteTokens,
+        },
+        outputTokens: {
+            total: outputTotal,
+            text: outputTokens,
+            reasoning: reasoningTokens,
+        },
+    };
+}
 //# sourceMappingURL=salesforce-llm-gateway.js.map

package/dist/tool-search.d.ts

@@ -0,0 +1,148 @@
+import type { AgentConfig } from '@salesforce/sfdx-agent-sdk';
+/**
+ * Configuration for hiding a large tool catalog behind Mastra's
+ * search/load workflow. When present on `MastraAgentConfig.toolSearch`,
+ * the harness exposes only `alwaysActive` tools by default and injects
+ * Mastra's `search_tools` / `load_tool` meta-tools for the model to
+ * discover the rest on demand.
+ */
+export type MastraToolSearchConfig = {
+    /**
+     * Tools eligible for search/load. `'*'` means every searchable tool;
+     * an explicit array limits the pool to the listed names.
+     */
+    pool: string[] | '*';
+    /**
+     * Tools that bypass search and are always visible to the model.
+     * Overrides `pool` on overlap. MCP tool names use the harness namespace
+     * prefix, e.g. `sfdx_deploy_metadata` for the `deploy_metadata` tool on
+     * the `sfdx` server.
+     */
+    alwaysActive?: string[];
+    /** Max tools returned per search (advisory). */
+    topK?: number;
+    /** Time-to-live in ms for a granted tool in the active set (advisory). */
+    ttl?: number;
+};
+/**
+ * Mastra-flavored extension of {@link AgentConfig}, adding the Mastra-only
+ * `toolSearch` field. Consumers do not import or pass this type explicitly —
+ * `MastraAgentHarness` brands itself with `MastraAgentConfig` via
+ * `WithAgentConfig`, so `manager.createAgent`'s config parameter resolves to
+ * this shape automatically and `toolSearch` autocompletes on the object
+ * literal.
+ *
+ * @example
+ * ```ts
+ * const agent = await manager.createAgent(projectRoot, {
+ *     instructions: '...',
+ *     tools,
+ *     toolSearch: { pool: '*', alwaysActive: ['lookup_account'] },
+ * });
+ * ```
+ *
+ * Extra fields ride through `toHarnessConfig`'s `...rest` spread to the
+ * harness, which reads `toolSearch` at its boundary via runtime narrowing.
+ */
+export type MastraAgentConfig = AgentConfig & {
+    /** Hide tools behind Mastra's search/load workflow. */
+    toolSearch?: MastraToolSearchConfig;
+};
+/**
+ * Opaque handle to the tool-search runtime state, exposed via
+ * `manager.extensions.mastra.getToolSearchProcessor(agentId)`. Lets consumers
+ * monitor and manage the per-thread loaded-tools state without reaching
+ * into Mastra's internal processor type.
+ *
+ * The underlying object *is* a Mastra `ToolSearchProcessor`; this interface
+ * narrows the public surface to a stable set of methods that won't churn
+ * if Mastra's internal shape changes. Consumers who need the full processor
+ * can still cast (`as unknown as ToolSearchProcessor`), but doing so
+ * accepts coupling to Mastra's version.
+ */
+export interface ToolSearchHandle {
+    /** Stable identifier for the processor (`'tool-search'`). */
+    readonly id: string;
+    /** Snapshot of per-thread state for monitoring. */
+    getStateStats(): {
+        threadCount: number;
+        oldestAccessTime: number | null;
+    };
+    /** Clear loaded tools for a thread (or `'default'` if omitted). */
+    clearState(threadId?: string): void;
+    /** Clear loaded tools across every thread on this processor. */
+    clearAllState(): void;
+    /**
+     * Trigger TTL cleanup eagerly. The processor schedules its own interval;
+     * this is for tests and explicit eviction.
+     * @returns Number of threads cleaned up.
+     */
+    cleanupNow(): number;
+}
+/**
+ * Opaque handle to the skill-search runtime, exposed via
+ * `manager.extensions.mastra.getSkillSearchProcessor(agentId)`.
+ *
+ * The Mastra `SkillSearchProcessor`'s public surface today is just
+ * `dispose()` (and the `id` / `name` / `description` metadata). The
+ * harness owns the lifecycle, so consumers shouldn't call `dispose()`
+ * directly — the handle exposes only the identification fields.
+ *
+ * A future Mastra release that adds public methods (analogous to
+ * `ToolSearchProcessor.getStateStats()`) can extend this interface
+ * without breaking consumers.
+ */
+export interface SkillSearchHandle {
+    /** Stable identifier for the processor (`'skill-search'`). */
+    readonly id: string;
+}
+/**
+ * Build the namespaced tool name Mastra uses for an MCP-discovered tool.
+ *
+ * The Mastra harness namespaces every MCP tool as `${serverName}_${toolName}`
+ * so two MCP servers exposing tools with the same short name (e.g. `query` on
+ * both `sfdx` and `postgres`) don't collide, and so MCP tools never collide
+ * with custom tools defined inline on `AgentConfig.tools`. Only MCP tool
+ * names are namespaced — custom tools keep their declared name unchanged.
+ *
+ * Reach for this when constructing `toolSearch.alwaysActive` entries that
+ * reference MCP tools at agent-creation time, *before* MCP discovery has
+ * settled. Without this helper you'd have to either hard-code the namespaced
+ * string (brittle if the server name changes) or wait for discovery (which
+ * defeats the point of `alwaysActive`).
+ *
+ * Custom tools listed in `alwaysActive` should use their declared name
+ * directly — do **not** wrap them with this helper.
+ *
+ * @param serverName - The MCP server name as it appears in
+ *   `AgentConfig.mcpServers` (the key, not the URL/command).
+ * @param toolName - The tool's name as exposed by the MCP server (the
+ *   un-namespaced name the server itself returns).
+ * @returns The namespaced name the harness will register the tool under.
+ *
+ * @example
+ * ```ts
+ * await manager.createAgent(projectRoot, {
+ *     instructions: '...',
+ *     tools: [{ name: 'lookup_account', ... }],   // custom tool
+ *     mcpServers: { sfdx: { command: 'sf-mcp' } },
+ *     toolSearch: {
+ *         pool: '*',
+ *         alwaysActive: [
+ *             'lookup_account',                              // custom — bare name
+ *             formatMcpToolName('sfdx', 'deploy_metadata'),  // MCP — namespaced
+ *         ],
+ *     },
+ * });
+ * ```
+ */
+export declare function formatMcpToolName(serverName: string, toolName: string): string;
+/**
+ * Resolve `pool` / `alwaysActive` against known tools. `'*'` expands to all
+ * known names; unknown pool names are dropped; unknown alwaysActive names are
+ * kept for late MCP discovery; alwaysActive overrides pool on overlap.
+ */
+export declare function partitionPool(poolSpec: string[] | '*', alwaysActive: string[] | undefined, allKnown: ReadonlySet<string>): {
+    pool: string[];
+    alwaysActive: string[];
+};

package/dist/tool-search.js

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Build the namespaced tool name Mastra uses for an MCP-discovered tool.
+ *
+ * The Mastra harness namespaces every MCP tool as `${serverName}_${toolName}`
+ * so two MCP servers exposing tools with the same short name (e.g. `query` on
+ * both `sfdx` and `postgres`) don't collide, and so MCP tools never collide
+ * with custom tools defined inline on `AgentConfig.tools`. Only MCP tool
+ * names are namespaced — custom tools keep their declared name unchanged.
+ *
+ * Reach for this when constructing `toolSearch.alwaysActive` entries that
+ * reference MCP tools at agent-creation time, *before* MCP discovery has
+ * settled. Without this helper you'd have to either hard-code the namespaced
+ * string (brittle if the server name changes) or wait for discovery (which
+ * defeats the point of `alwaysActive`).
+ *
+ * Custom tools listed in `alwaysActive` should use their declared name
+ * directly — do **not** wrap them with this helper.
+ *
+ * @param serverName - The MCP server name as it appears in
+ *   `AgentConfig.mcpServers` (the key, not the URL/command).
+ * @param toolName - The tool's name as exposed by the MCP server (the
+ *   un-namespaced name the server itself returns).
+ * @returns The namespaced name the harness will register the tool under.
+ *
+ * @example
+ * ```ts
+ * await manager.createAgent(projectRoot, {
+ *     instructions: '...',
+ *     tools: [{ name: 'lookup_account', ... }],   // custom tool
+ *     mcpServers: { sfdx: { command: 'sf-mcp' } },
+ *     toolSearch: {
+ *         pool: '*',
+ *         alwaysActive: [
+ *             'lookup_account',                              // custom — bare name
+ *             formatMcpToolName('sfdx', 'deploy_metadata'),  // MCP — namespaced
+ *         ],
+ *     },
+ * });
+ * ```
+ */
+export function formatMcpToolName(serverName, toolName) {
+    return `${serverName}_${toolName}`;
+}
+/**
+ * Resolve `pool` / `alwaysActive` against known tools. `'*'` expands to all
+ * known names; unknown pool names are dropped; unknown alwaysActive names are
+ * kept for late MCP discovery; alwaysActive overrides pool on overlap.
+ */
+export function partitionPool(poolSpec, alwaysActive, allKnown) {
+    const resolvedActive = alwaysActive ?? [];
+    const activeSet = new Set(resolvedActive);
+    const resolvedPoolBase = poolSpec === '*' ? Array.from(allKnown) : poolSpec.filter((n) => allKnown.has(n));
+    const pool = resolvedPoolBase.filter((n) => !activeSet.has(n));
+    return { pool, alwaysActive: resolvedActive };
+}
+//# sourceMappingURL=tool-search.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -27,36 +27,37 @@
     "LICENSE.txt"
   ],
   "dependencies": {
-    "@ai-sdk/provider": "^2.0.1",
-    "@mastra/core": "^1.31.0",
-    "@mastra/libsql": "^1.9.1",
-    "@mastra/mcp": "^1.6.0",
-    "@mastra/memory": "^1.17.4",
-    "@salesforce/agentic-common": "0.3.0",
-    "@salesforce/llm-gateway-sdk": "0.3.0"
+    "@ai-sdk/provider": "^3.0.10",
+    "@mastra/core": "^1.36.0",
+    "@mastra/libsql": "^1.11.1",
+    "@mastra/mcp": "^1.8.0",
+    "@mastra/memory": "^1.19.0",
+    "@mastra/schema-compat": "^1.2.10",
+    "@salesforce/agentic-common": "0.4.0",
+    "@salesforce/llm-gateway-sdk": "0.4.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.4.0"
+    "@salesforce/sfdx-agent-sdk": "0.6.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.4.0",
+    "@salesforce/sfdx-agent-sdk": "0.6.0",
     "@types/node": "^22.19.17",
-    "@vitest/coverage-istanbul": "^4.1.5",
-    "@vitest/eslint-plugin": "^1.6.16",
-    "eslint": "^10.2.1",
+    "@vitest/coverage-istanbul": "^4.1.7",
+    "@vitest/eslint-plugin": "^1.6.17",
+    "eslint": "^10.4.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-n": "^18.0.1",
     "globals": "^17.6.0",
-    "lint-staged": "^17.0.4",
+    "lint-staged": "^17.0.5",
     "prettier": "^3.8.3",
     "rimraf": "^6.1.3",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.3",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.1",
-    "vitest": "^4.1.5"
+    "typescript-eslint": "^8.59.4",
+    "vitest": "^4.1.7"
   },
   "engines": {
     "node": ">=22.19.0"