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

package/README.md

@@ -109,6 +109,30 @@ Mastra-internal pool / index / loaded-tools state is intentionally not on the ha
 are `getStateStats()`, `clearState(threadId?)`, `clearAllState()`, and `cleanupNow()` on `ToolSearchHandle`, plus `id`
 on both handles.
 
+### MCP tool-event enrichment
+
+The harness enriches every `tool-call`, `tool-result`, and `tool-approval-request` event with the originating MCP server
+name and any annotations the server declared, so consumers can branch on tool hints or group by server without parsing
+the namespaced tool name themselves. `serverName` is `undefined` for non-MCP tools (workspace tools, consumer-declared
+tools); `annotations` is `undefined` when the server omitted the field (per the MCP spec).
+
+```ts
+for await (const event of result.eventStream) {
+  if (event.type === 'tool-approval-request') {
+    if (event.annotations?.readOnlyHint) {
+      // Auto-approve safe reads.
+      await session.approveToolCall(event.toolCall.toolCallId);
+    } else {
+      // Group/label by server when present, e.g. "sfdx wants to: deploy_metadata".
+      const approved = await promptUser(event.serverName, event.toolCall);
+      approved
+        ? await session.approveToolCall(event.toolCall.toolCallId)
+        : await session.declineToolCall(event.toolCall.toolCallId);
+    }
+  }
+}
+```
+
 ### Using LLM Gateway Express
 
 ```ts

package/dist/mastra-harness.js

@@ -168,6 +168,50 @@ async function listMarkdownFilesInDirectory(dir) {
     }
     return names.sort().map((name) => path.join(dir, name));
 }
+/**
+ * Resolve the MCP server name and (optionally) annotations for a Mastra
+ * namespaced tool name (`${serverName}_${toolName}`). Returns `undefined` for
+ * tools that are not in any MCP server's catalog (consumer-declared client
+ * tools, workspace tools).
+ *
+ * Iterates `agentState.mcpServers` and prefix-matches rather than splitting on
+ * `_`, because server names themselves may contain underscores
+ * (`data_pipeline_query_records` → server `data_pipeline`, tool
+ * `query_records`). Mirrors the catalog access pattern used by
+ * {@link mapMastraToolsToMcpToolInfo}.
+ *
+ * Design debt: this walk runs per `tool-call` / `tool-result` /
+ * `tool-approval-request` event and reconstructs the tool→server linkage from
+ * the namespaced string. The cost is O(servers) on a typically-small map, but
+ * three call sites now share the same lookup, so the carry-on-the-record fix —
+ * attaching an `McpToolInfo` reference (with `serverName`) on the in-memory
+ * tool-call record from the moment Mastra namespaces the name — becomes
+ * proportionally more valuable. That fix touches `MastraEventAdapter`,
+ * `ToolCallInfo`, and the per-stream pipeline; out of scope for W-22693491.
+ * If a fourth per-event MCP-catalog lookup gets added, do the
+ * carry-on-the-record refactor first; if this walk shows up in profiles
+ * before that, build a `Map<namespacedToolName, { serverName, McpToolInfo }>`
+ * index keyed off discovery completion.
+ */
+/**
+ * Tool ChatEvents that carry the optional `serverName` + `annotations`
+ * enrichment fields. Centralizing the predicate lets `createEventStream`
+ * narrow once and apply the lookup uniformly across the three variants.
+ */
+function isEnrichableToolEvent(event) {
+    return event.type === 'tool-call' || event.type === 'tool-result' || event.type === 'tool-approval-request';
+}
+function lookupMcpToolMetadata(agentState, namespacedToolName) {
+    for (const [serverName, serverState] of agentState.mcpServers) {
+        if (!namespacedToolName.startsWith(`${serverName}_`))
+            continue;
+        const original = namespacedToolName.slice(serverName.length + 1);
+        const annotations = serverState.tools[original]
+            ?.mcp?.annotations;
+        return { serverName, ...(annotations ? { annotations } : {}) };
+    }
+    return undefined;
+}
 /**
  * Projects the namespaced Mastra `ToolAction` map for one MCP server into the
  * SDK's harness-agnostic `McpToolInfo[]` shape.
@@ -452,6 +496,13 @@ export class MastraHarness {
             const localFs = new LocalFilesystem({ basePath: projectRoot, allowedPaths });
             const sandbox = new LocalSandbox({
                 workingDirectory: projectRoot,
+                // Forward the parent process env so spawned commands see HOME,
+                // locale, etc. (LocalSandbox's default forwards only PATH, which
+                // breaks tools like `sf org list` that resolve config from HOME).
+                // TODO: filter sensitive vars (e.g. ANTHROPIC_*, AWS creds) here
+                // if the harness ever runs alongside secrets it shouldn't leak
+                // into spawned tool subprocesses.
+                env: process.env,
             });
             mastraWorkspace = new Workspace({
                 filesystem: localFs,
@@ -978,7 +1029,7 @@ export class MastraHarness {
         agentState.activeRuns.set(threadId, { runId: output.runId, fullStream: output.fullStream });
         const adapter = new MastraEventAdapter(this.buses.getLogBus());
         return {
-            eventStream: this.createEventStream(output.fullStream, adapter),
+            eventStream: this.createEventStream(output.fullStream, adapter, agentState),
             textStream: this.readableStreamToAsyncGenerator(output.textStream),
         };
     }
@@ -993,11 +1044,23 @@ export class MastraHarness {
     agentResourceId(agentId) {
         return `AGENT_INSTANCE:${agentId}`;
     }
-    async *createEventStream(fullStream, adapter) {
+    async *createEventStream(fullStream, adapter, agentState) {
         for await (const chunk of this.readableStreamToAsyncGenerator(fullStream)) {
             const event = adapter.toChatEvent(chunk);
             if (!event)
                 continue;
+            if (isEnrichableToolEvent(event)) {
+                const toolName = event.type === 'tool-approval-request' ? event.toolCall.toolName : event.toolName;
+                const metadata = lookupMcpToolMetadata(agentState, toolName);
+                if (metadata) {
+                    yield {
+                        ...event,
+                        serverName: metadata.serverName,
+                        ...(metadata.annotations ? { annotations: metadata.annotations } : {}),
+                    };
+                    continue;
+                }
+            }
             yield event;
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -34,14 +34,14 @@
     "@mastra/memory": "^1.19.0",
     "@mastra/schema-compat": "^1.2.10",
     "@salesforce/agentic-common": "0.4.0",
-    "@salesforce/llm-gateway-sdk": "0.4.0"
+    "@salesforce/llm-gateway-sdk": "0.5.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.6.0"
+    "@salesforce/sfdx-agent-sdk": "0.8.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.6.0",
+    "@salesforce/sfdx-agent-sdk": "0.8.0",
     "@types/node": "^22.19.17",
     "@vitest/coverage-istanbul": "^4.1.7",
     "@vitest/eslint-plugin": "^1.6.17",