@salesforce/sfdx-agent-sdk 0.4.0 → 0.6.0

package/dist/internal/agent-identity-store.js

@@ -0,0 +1,141 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getErrorMessage } from '@salesforce/agentic-common';
+const FILE_VERSION = 1;
+const AGENTS_SUBDIR = 'agents';
+/**
+ * SDK-owned persistence for the agent-identity triple
+ * `{ agentId, projectRoot, AgentConfig }`. Stored as one JSON file per agent
+ * under `${storageRootFolder}/agents/`. Internal to the SDK; not exported.
+ *
+ * Each record carries the current harness's `harnessId`. On `list()`, records
+ * whose `harnessId` does not match the current harness are skipped with a
+ * `LogBus.warn` — restoring an agent into the wrong harness is never the
+ * right answer.
+ */
+export class AgentIdentityStore {
+    storageRootFolder;
+    harnessId;
+    logBus;
+    /**
+     * Per-agentId queue of in-flight writes. Concurrent `write()` calls for the same agentId
+     * chain onto the previous promise so the `writeFile` + `rename` pair runs sequentially.
+     *
+     * Why this matters: POSIX `rename` atomically overwrites an existing target, but Windows
+     * `rename` returns `EPERM` when any handle is open on the target — including a sibling
+     * concurrent rename from the same process. Three concurrent writers calling
+     * `rename(tmp, 'a.json')` succeed on Linux/macOS and fail on Windows. Serializing per
+     * agentId eliminates the race entirely (and removes any need for per-call temp suffixes
+     * because at most one write is touching the temp path at a time). Last-writer-wins
+     * semantics are preserved.
+     */
+    inflightWrites = new Map();
+    constructor(storageRootFolder, harnessId, logBus) {
+        this.storageRootFolder = storageRootFolder;
+        this.harnessId = harnessId;
+        this.logBus = logBus;
+    }
+    async write(agentId, projectRoot, config) {
+        const previous = this.inflightWrites.get(agentId) ?? Promise.resolve();
+        // `.catch(() => undefined)` so a previous failure doesn't poison the next caller's await.
+        // Each caller still observes its own write's success or failure via the returned promise.
+        const next = previous.catch(() => undefined).then(() => this.writeImmediate(agentId, projectRoot, config));
+        this.inflightWrites.set(agentId, next);
+        try {
+            await next;
+        }
+        finally {
+            // Only clear the slot if it still points at this write — a newer write may have
+            // already chained onto `next` and replaced the entry.
+            if (this.inflightWrites.get(agentId) === next) {
+                this.inflightWrites.delete(agentId);
+            }
+        }
+    }
+    async writeImmediate(agentId, projectRoot, config) {
+        const dir = this.dir();
+        await mkdir(dir, { recursive: true });
+        const payload = {
+            version: FILE_VERSION,
+            harnessId: this.harnessId,
+            agentId,
+            projectRoot,
+            config,
+        };
+        const target = join(dir, `${agentId}.json`);
+        const tmp = `${target}.tmp`;
+        await writeFile(tmp, JSON.stringify(payload, null, 2), 'utf8');
+        await rename(tmp, target);
+    }
+    async remove(agentId) {
+        // Wait for any in-flight write before removing so we don't race a rename and leave
+        // the file behind. Same Windows-EPERM hazard as concurrent writes, plus the obvious
+        // last-writer-wins concern (a write completing after a remove would resurrect the file).
+        const previous = this.inflightWrites.get(agentId);
+        if (previous) {
+            await previous.catch(() => undefined);
+        }
+        await rm(join(this.dir(), `${agentId}.json`), { force: true });
+    }
+    async list() {
+        let entries;
+        try {
+            entries = await readdir(this.dir());
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+        const records = [];
+        for (const entry of entries) {
+            if (!entry.endsWith('.json'))
+                continue;
+            const filePath = join(this.dir(), entry);
+            let parsed;
+            try {
+                const raw = await readFile(filePath, 'utf8');
+                parsed = JSON.parse(raw);
+            }
+            catch (err) {
+                this.logBus.warn('skipping unreadable persisted agent identity file', {
+                    filePath,
+                    error: getErrorMessage(err),
+                });
+                continue;
+            }
+            if (!parsed.agentId || !parsed.projectRoot || !parsed.config || !parsed.harnessId) {
+                // `harnessId` is in the missing-fields gate (not the harness-mismatch gate below)
+                // so a record without it produces a "missing required fields" warn rather than
+                // a confusing "different harness" warn with `recordHarnessId: undefined`.
+                this.logBus.warn('skipping persisted agent identity file with missing required fields', {
+                    filePath,
+                });
+                continue;
+            }
+            if (parsed.harnessId !== this.harnessId) {
+                this.logBus.warn('skipping persisted agent identity file from a different harness', {
+                    filePath,
+                    agentId: parsed.agentId,
+                    recordHarnessId: parsed.harnessId,
+                    currentHarnessId: this.harnessId,
+                });
+                continue;
+            }
+            records.push({
+                agentId: parsed.agentId,
+                projectRoot: parsed.projectRoot,
+                config: parsed.config,
+            });
+        }
+        return records;
+    }
+    dir() {
+        return join(this.storageRootFolder, AGENTS_SUBDIR);
+    }
+}
+//# sourceMappingURL=agent-identity-store.js.map

package/dist/mcp-config.d.ts

@@ -43,10 +43,73 @@ export declare enum McpServerStatus {
     Disabled = "disabled",
     Error = "error"
 }
+/**
+ * Behavioral / UI-presentation hints for an MCP-discovered tool.
+ *
+ * Mirrors the MCP protocol's `Tool.annotations` shape
+ * (https://spec.modelcontextprotocol.io/specification/server/tools/#tool-annotations)
+ * without importing `@modelcontextprotocol/sdk`, keeping this package
+ * harness-runtime-free. Each field is optional because MCP servers populate
+ * annotations à la carte; absence means "the server did not declare this
+ * hint," not "false."
+ */
+export type McpToolAnnotations = {
+    /** Human-readable label suitable for UI display (vs. the machine `name`). */
+    title?: string;
+    /** When `true`, the tool only reads data and has no side effects. */
+    readOnlyHint?: boolean;
+    /** When `true`, the tool may perform destructive updates to its environment. */
+    destructiveHint?: boolean;
+    /** When `true`, repeated calls with the same arguments have no additional effect. */
+    idempotentHint?: boolean;
+    /** When `true`, the tool may interact with an open world of external entities (e.g. the public web). */
+    openWorldHint?: boolean;
+};
+/**
+ * Runtime metadata for a single MCP-discovered tool.
+ *
+ * The optional fields are populated when the underlying harness can supply
+ * them from its MCP client. A harness whose MCP runtime does not expose a
+ * given field leaves it `undefined` — consumers must treat every field
+ * except `name` as optional.
+ *
+ * **Why no `outputSchema` field?** The MCP protocol's `tools/list` response
+ * carries an optional `outputSchema` per tool, and a maximally honest mirror
+ * of that protocol shape would expose it here. We deliberately do not, because
+ * neither harness today can populate it: Mastra's `@mastra/mcp` strips
+ * `outputSchema` from each wrapped tool before the harness sees it (a
+ * deliberate choice in Mastra's MCP client to keep `CallToolResult`
+ * validation correct — passing the schema to `createTool` would cause Zod
+ * to strip unrecognized keys from the envelope), and the Claude Agent SDK's
+ * MCP status surface omits the field entirely. Adding `outputSchema?` to the
+ * SDK contract today would mean shipping a field no harness fills — exactly
+ * the "field a consumer should ignore" anti-pattern called out in this
+ * package's design principles. If a future harness gains access to
+ * `outputSchema` (or one of the existing harnesses adds it), expanding the
+ * contract is a non-breaking additive change at that point.
+ */
+export type McpToolInfo = {
+    /** Tool name as exposed to the LLM, including any harness-applied namespacing. */
+    name: string;
+    /** Human-readable description of what the tool does. */
+    description?: string;
+    /**
+     * Tool input parameters as a **JSON Schema** object (the MCP wire format).
+     *
+     * This is a plain JSON Schema, not a Zod schema. Consumers that want a
+     * Zod schema at runtime can convert with a library such as
+     * `json-schema-to-zod`; consumers that want runtime validation can feed
+     * it to AJV. Typed as `Record<string, unknown>` so this package incurs
+     * no `zod` or `@types/json-schema` dependency.
+     */
+    inputSchema?: Record<string, unknown>;
+    /** Behavioral / UI-presentation hints declared by the MCP server. */
+    annotations?: McpToolAnnotations;
+};
 /** Runtime status of a configured MCP server, including its discovered tools. */
 export type McpServerInfo = {
     name: string;
     status: McpServerStatus;
-    tools: string[];
+    tools: McpToolInfo[];
     error?: string;
 };

package/dist/types/usage.d.ts

@@ -16,7 +16,9 @@ export type UsageMetadata = {
 };
 /**
  * Reason the model stopped generating.
- * Aligned with AI SDK `LanguageModelV2FinishReason`.
+ * Aligned with AI SDK V3's unified finish-reason set; harnesses normalize provider-specific
+ * shapes (e.g. V3's `LanguageModelV3FinishReason` object with `{ unified, raw }`) down to this
+ * union so SDK consumers see a stable string regardless of the underlying AI SDK version.
  *
  * - `stop` — The model finished generating naturally (complete response).
  * - `length` — The model hit the maximum output token limit; the response was truncated mid-generation.

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "build": "tsc --build",
     "clean": "tsc --build --clean",
@@ -28,28 +35,28 @@
     "LICENSE.txt"
   ],
   "dependencies": {
-    "@salesforce/agentic-common": "0.3.0",
-    "@salesforce/llm-gateway-sdk": "0.3.0"
+    "@salesforce/agentic-common": "0.4.0",
+    "@salesforce/llm-gateway-sdk": "0.4.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-mastra": "0.4.0",
+    "@salesforce/sfdx-agent-harness-mastra": "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"