@salesforce/sfdx-agent-sdk 0.24.0 → 0.26.0

package/dist/types/telemetry-events.d.ts

@@ -1,5 +1,6 @@
 import type { EventBus } from '@salesforce/agentic-common';
 import type { McpServerErrorDetail, McpServerStatus, McpToolAnnotations } from '../mcp-config.js';
+import type { Decision, ToolPolicyRule } from './tools.js';
 import type { UsageMetadata } from './usage.js';
 /**
  * Telemetry events emitted by the Agent SDK.
@@ -85,6 +86,46 @@ export type ToolApprovalResolvedEvent = Base<'tool-approval-resolved'> & {
     threadId: string;
     toolCallId: string;
     approved: boolean;
+    /**
+     * `true` when the settle's `remember` flag triggered an
+     * `updateAgentConfig` call that appended a `'remember'` policy rule.
+     * Absent / `false` when the settle did not persist a rule.
+     */
+    policyWritten?: boolean;
+};
+/**
+ * Emitted by a harness on every harness-executed tool call, after
+ * `resolveToolApprovalPolicy` decides and before any gate work happens.
+ * Lets telemetry sinks answer "why did this tool prompt / not prompt / get
+ * denied?" by reading the rule that fired.
+ *
+ * Emitted by the harness layer (Phase 2), not the SDK — the SDK exports the
+ * variant so the public `TelemetryEvent` union is complete before the harness
+ * PRs land.
+ */
+export type ToolApprovalPolicyResolvedEvent = Base<'tool-approval-policy-resolved'> & {
+    agentId: string;
+    threadId: string;
+    toolCallId: string;
+    toolName: string;
+    /** Originating MCP server name, when the tool was discovered through MCP. */
+    serverName?: string;
+    /** The resolved decision. */
+    decision: Decision;
+    /**
+     * The rule that drove the decision under cross-tier-deny-wins /
+     * within-tier-last-wins precedence (the last `'deny'` when denied, else the
+     * last matching non-deny rule). `undefined` when no rule matched and the
+     * resolver fell back to `defaultToolDecision ?? 'allow'`; the harness emits
+     * a `LogBus.warn` in that case.
+     */
+    matchedRule?: ToolPolicyRule;
+    /**
+     * Every matching rule in resolved-list order. Optional debug verbosity for
+     * sinks that surface "remembered allow overridden by built-in deny"
+     * scenarios; most consumers use {@link matchedRule}.
+     */
+    allMatchedRules?: ToolPolicyRule[];
 };
 export type McpServerDiscoveryStartedEvent = Base<'mcp-server-discovery-started'> & {
     agentId: string;
@@ -137,7 +178,7 @@ export type McpServerStatusChangedEvent = Base<'mcp-server-status-changed'> & {
     /** Populated when `nextStatus === 'error'`. */
     error?: string;
 };
-export type TelemetryEvent = AgentCreatedEvent | AgentDestroyedEvent | SessionCreatedEvent | SessionDestroyedEvent | ChatStreamStartedEvent | ChatStreamCompletedEvent | ChatStreamErrorEvent | ToolExecutionStartedEvent | ToolExecutionCompletedEvent | ToolApprovalRequestedEvent | ToolApprovalResolvedEvent | McpServerDiscoveryStartedEvent | McpServerDiscoveryCompletedEvent | McpServerDiscoveryFailedEvent | McpServerStatusChangedEvent;
+export type TelemetryEvent = AgentCreatedEvent | AgentDestroyedEvent | SessionCreatedEvent | SessionDestroyedEvent | ChatStreamStartedEvent | ChatStreamCompletedEvent | ChatStreamErrorEvent | ToolExecutionStartedEvent | ToolExecutionCompletedEvent | ToolApprovalRequestedEvent | ToolApprovalResolvedEvent | ToolApprovalPolicyResolvedEvent | McpServerDiscoveryStartedEvent | McpServerDiscoveryCompletedEvent | McpServerDiscoveryFailedEvent | McpServerStatusChangedEvent;
 export type TelemetryEventCallback = (event: TelemetryEvent) => void;
 export type TelemetryBus = EventBus<TelemetryEvent>;
 export {};

package/dist/types/tools.d.ts

@@ -46,6 +46,89 @@ export type ToolDefinition = {
      */
     annotations?: McpToolAnnotations;
 };
+/**
+ * The policy decision for a single tool invocation.
+ *
+ * - `'allow'` — the harness executes the tool without pausing.
+ * - `'deny'` — the harness refuses the call and synthesizes a
+ *   `tool-result(isError=true)` so the model can recover; no
+ *   `tool-approval-request` surfaces.
+ * - `'require-approval'` — the harness emits a `tool-approval-request`
+ *   and suspends until the consumer settles via `approveToolCall` /
+ *   `declineToolCall`.
+ */
+export type Decision = 'allow' | 'deny' | 'require-approval';
+/**
+ * Structured matcher selecting which tool invocations a {@link ToolPolicyRule}
+ * applies to.
+ *
+ * The three shapes cover every tool category a harness gates:
+ *
+ * - `'builtin'` — harness-built-in tools (e.g. Claude's `Bash` / `Edit`;
+ *   Mastra's `updateWorkingMemory`). Names are **harness-specific**, so a
+ *   `'builtin'` rule applies asymmetrically across harnesses — `Bash` matches
+ *   on Claude and is a no-op on Mastra. A `'builtin'` matcher matches only when
+ *   the invocation has no `serverName` (MCP tools carry one).
+ * - `'mcp'` — MCP-discovered tools. Both `serverName` and `toolName` are
+ *   optional: omitting `toolName` matches every tool from the given server;
+ *   omitting `serverName` matches every tool from every MCP server; omitting
+ *   both matches every MCP tool (a server-agnostic catch-all). MCP rules are
+ *   **portable** — the same rule fires on both harnesses for the same tool.
+ * - `'mcp-annotation'` — matches any MCP tool whose discovered
+ *   {@link McpToolAnnotations} carry the specified hint(s). Every field set on
+ *   the matcher must equal the corresponding field on the discovered
+ *   annotation (logical AND across set fields). A tool with no annotations does
+ *   **not** match — the resolver falls through. This is fail-open by default;
+ *   tenants needing fail-closed for un-annotated MCP servers set
+ *   {@link AgentConfig.defaultToolDecision} to `'require-approval'`.
+ *
+ * There is intentionally no `consumer` matcher. Consumer-declared tools (those
+ * in {@link AgentConfig.tools} without an `execute`) are gated structurally at
+ * the harness boundary and never reach the resolver, so a matcher variant for
+ * them would be API surface for an unreachable case.
+ */
+export type ToolMatcher = {
+    type: 'builtin';
+    name: string;
+} | {
+    type: 'mcp';
+    serverName?: string;
+    toolName?: string;
+} | {
+    type: 'mcp-annotation';
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+};
+/**
+ * One entry in an agent's tool-approval policy list.
+ *
+ * Resolution concatenates the SDK's `BUILT_IN_TOOL_POLICIES`, the harness's
+ * built-in array, any harness factory rules, and `AgentConfig.toolPolicies`,
+ * then applies **cross-tier deny-wins / within-tier last-wins** precedence (see
+ * `resolveToolApprovalPolicy`).
+ */
+export type ToolPolicyRule = {
+    /** Selects which tool invocations this rule applies to. */
+    matcher: ToolMatcher;
+    /** The decision to apply when {@link matcher} matches. */
+    decision: Decision;
+    /**
+     * Where this rule originated. Advisory metadata only — the resolver
+     * **ignores** `source` when computing a decision; telemetry surfaces it so
+     * operators can answer "which tier fired."
+     *
+     * - `'built-in'` — shipped by the SDK's `BUILT_IN_TOOL_POLICIES` or a
+     *   harness package's `<HARNESS>_BUILT_IN_TOOL_POLICIES` array.
+     * - `'agent-config'` — authored by whoever wrote the `AgentConfig`. The
+     *   default when unset on a consumer-supplied rule.
+     * - `'remember'` — written by `approveToolCall(id, { remember: true })` /
+     *   `declineToolCall(id, { remember: true })`.
+     *
+     * v1 ships these three values. A future tenant-managed-policy tier will add
+     * `'managed'` to this union; that widening is strictly additive.
+     */
+    source?: 'built-in' | 'agent-config' | 'remember';
+};
 /**
  * Base shape for a tool call.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -40,12 +40,12 @@
     "LICENSE.txt"
   ],
   "dependencies": {
-    "@salesforce/agentic-common": "0.12.0"
+    "@salesforce/agentic-common": "0.13.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.20.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.23.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.22.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.25.0",
     "@types/node": "^22.20.0",
     "@vitest/coverage-istanbul": "^4.1.8",
     "@vitest/eslint-plugin": "^1.6.20",
@@ -64,7 +64,7 @@
     "vitest": "^4.1.8"
   },
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=22.22.0"
   },
   "lint-staged": {
     "*.{js,jsx,ts,tsx,json,md}": [