@salesforce/sfdx-agent-sdk 0.4.0 → 0.6.0

package/dist/agent-manager.js

@@ -2,7 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-import { EventBus, LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
+import { EventBus, getErrorMessage, LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
 import { resolve } from 'node:path';
 import { stat } from 'node:fs/promises';
 import { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
@@ -10,49 +10,34 @@ import { toHarnessConfig } from './harness/harness-config.js';
 import { DefaultAgent } from './agent.js';
 import { AgentSDKError, AgentSDKErrorType } from './errors.js';
 import { TelemetryRouter } from './internal/telemetry-router.js';
+import { AgentIdentityStore } from './internal/agent-identity-store.js';
 import { DefaultAgentConnectivityResolver } from './agent-connectivity-resolver.js';
 /**
- * Manages the lifecycle of {@link Agent} instances.
+ * Concrete implementation of {@link AgentManager}. **Not exported** from
+ * `src/index.ts` — public construction goes through {@link createAgentManager}.
  *
- * The manager owns an {@link AgentHarness} and coordinates initialization,
- * agent creation, and graceful shutdown. The harness implementation is
- * abstracted away from downstream code (agents, sessions).
- *
- * ### Persistence Responsibility
- * Persistence is shared between the harness and the consuming application:
- * - **Engine**: Handles physical data persistence (database storage of threads, messages, and memory state).
- * - **Application**: Handles lifecycle persistence. It manages the discovery and restoration of saved agents,
- *   and calls `createAgent(projectRoot, { agentId: savedId, ...savedConfig })` to rebuild active agent state in memory
- *   (like MCP connections and custom tool closures) while reconnecting to the persistent memory data.
+ * Construction is asynchronous because {@link init} reads the persistence
+ * directory and replays prior agents before the manager becomes useful. The
+ * pattern mirrors {@link Workspace.create}: a private constructor for sync
+ * field assignment, then a static async builder that calls `init()`.
  */
-export class AgentManager {
+export class DefaultAgentManager {
     harness;
     agentIdGenerator;
     agentConnectivityResolver;
     clock;
+    identityStore;
     agents = new Map();
+    restoreFailures = [];
     telemetryBus = new EventBus();
     logBus;
     router;
     unroutedUnsubs;
     disposed = false;
-    /**
-     * Creates a new {@link AgentManager}.
-     *
-     * This constructor is **exposed for testing only** so unit tests can inject a stubbed
-     * {@link AgentHarness} and deterministic ID generator.
-     *
-     * Production callers should use {@link createAgentManager} instead.
-     *
-     * @example
-     * ```ts
-     * // Recommended for production usage (constructs the default connectivity resolver):
-     * const manager = await createAgentManager(storageRootFolder, harnessFactory);
-     * ```
-     */
-    constructor(harness, agentConnectivityResolver, agentIdGenerator = new UUIDGenerator(), clock = new RealClock(), logBus = new LogBus()) {
+    constructor(harness, agentConnectivityResolver, identityStore, agentIdGenerator, clock, logBus) {
         this.harness = harness;
         this.agentConnectivityResolver = agentConnectivityResolver;
+        this.identityStore = identityStore;
         this.agentIdGenerator = agentIdGenerator;
         this.clock = clock;
         this.logBus = logBus;
@@ -62,15 +47,47 @@ export class AgentManager {
             this.router.unrouted.log.forwardTo(this.logBus),
         ];
     }
-    // Note: harness construction is async (see createAgentManager), so AgentManager itself no longer has initialize().
     /**
-     * Shuts down the harness and destroys all managed agents.
+     * Module-internal builder used by {@link createAgentManager}. Mirrors
+     * {@link Workspace.create}: sync field assignment in the private
+     * constructor, then `await init()` to do async startup work
+     * (reading the persistence directory + replaying prior agents).
      *
-     * @requirements
-     * - MUST iterate through all agents in the internal `agents` map and call `agent.destroy()` on each.
-     * - MUST clear the internal `agents` map.
-     * - MUST delegate to `this.harness.shutdown()` to release harness-level resources.
+     * The double-underscore signals "do not call directly" — the constructor
+     * is private, so this is the only way to obtain an instance, but
+     * consumers should always go through {@link createAgentManager}.
      */
+    static async __build(harness, agentConnectivityResolver, storageRootFolder, agentIdGenerator, clock, logBus) {
+        const identityStore = new AgentIdentityStore(storageRootFolder, harness.harnessId, logBus);
+        const manager = new DefaultAgentManager(harness, agentConnectivityResolver, identityStore, agentIdGenerator, clock, logBus);
+        await manager.init();
+        return manager;
+    }
+    async init() {
+        const records = await this.identityStore.list();
+        const failures = [];
+        await Promise.all(records.map(async (record) => {
+            try {
+                await this.installAgent(record.agentId, record.projectRoot, record.config, {
+                    rehydrateThreads: true,
+                });
+            }
+            catch (err) {
+                failures.push({
+                    agentId: record.agentId,
+                    projectRoot: record.projectRoot,
+                    config: record.config,
+                    error: err,
+                });
+                this.logBus.error('agent restore failed', err instanceof Error ? err : undefined, {
+                    agentId: record.agentId,
+                    projectRoot: record.projectRoot,
+                    message: getErrorMessage(err),
+                });
+            }
+        }));
+        this.restoreFailures = failures;
+    }
     async shutdown() {
         if (this.disposed) {
             return;
@@ -88,78 +105,99 @@ export class AgentManager {
         this.logBus.dispose();
         this.disposed = true;
     }
-    /**
-     * Creates a new `Agent` with the given configuration.
-     *
-     * @param projectRoot - Absolute path to the project folder the agent can manipulate files from.
-     *   Relative paths are resolved against `process.cwd()`. The path must exist and be a directory.
-     * @param config - Agent configuration (instructions, tools, model, etc.).
-     * @param options - Optional execution options, including abort signals.
-     * @returns A new `Agent` ready for chat sessions.
-     *
-     * @throws If `projectRoot` does not exist or is not a directory.
-     *
-     * @requirements
-     * - MUST resolve `projectRoot` to an absolute, normalized path before use.
-     * - MUST throw an Error if the resolved `projectRoot` does not exist or is not a directory.
-     * - MUST throw an Error if `config.agentId` is provided and an agent with that ID already exists in the internal `agents` map.
-     * - MUST generate a unique ID via `this.agentIdGenerator` if `config.agentId` is omitted.
-     * - MUST delegate to `this.harness.createAgent(agentId, projectRoot, llmGatewayClient, config, options)` to register the agent in the harness and allow for cancellation.
-     * - MUST instantiate a `DefaultAgent` with the harness and the complete configuration.
-     * - MUST store the newly created agent in the internal `agents` map, keyed by its `agentId`.
-     * - MUST return the newly created agent.
-     */
     async createAgent(projectRoot, config = {}, options) {
         this.assertNotDisposed();
         const resolvedProjectRoot = resolve(projectRoot);
+        const { agentId: providedAgentId, ...agentConfig } = config;
+        const agentId = providedAgentId ?? this.agentIdGenerator.getUniqueId();
+        if (this.agents.has(agentId)) {
+            throw new Error(`Agent with id "${agentId}" already exists`);
+        }
+        // installAgent validates projectRoot existence — same path as the restore loop.
+        const agent = await this.installAgent(agentId, resolvedProjectRoot, agentConfig, {
+            abortSignal: options?.abortSignal,
+        });
+        // If the disk write fails (disk full, permissions, fs error), the in-memory install
+        // is now stale — the harness has the agent, the manager has it in `agents`, but no
+        // record on disk means a subsequent restart loses it. Roll back the install so the
+        // failure is observable and the id stays reusable, then rethrow.
+        try {
+            await this.identityStore.write(agentId, resolvedProjectRoot, agentConfig);
+        }
+        catch (err) {
+            await this.rollbackInstall(agentId, agent);
+            throw err;
+        }
+        // A successful (re)create clears any prior failed-restore entry for the same id.
+        this.restoreFailures = this.restoreFailures.filter((f) => f.agentId !== agentId);
+        return agent;
+    }
+    /**
+     * Shared install path for {@link createAgent} and the boot-time restore
+     * loop. Resolves connectivity, calls `harness.createAgent`, constructs
+     * the {@link DefaultAgent}, registers the telemetry slice, emits
+     * `agent-created`, and (when restoring) attaches a chat session per
+     * persisted thread id.
+     *
+     * Returns {@link DefaultAgent} (concrete) rather than {@link Agent}
+     * because both call sites are internal — widening to the interface only
+     * happens at the public-method return statement.
+     */
+    async installAgent(agentId, projectRoot, config, options = {}) {
         let dirStat;
         try {
-            dirStat = await stat(resolvedProjectRoot);
+            dirStat = await stat(projectRoot);
         }
         catch {
-            throw new Error(`projectRoot does not exist: "${resolvedProjectRoot}"`);
+            throw new Error(`projectRoot does not exist: "${projectRoot}"`);
         }
         if (!dirStat.isDirectory()) {
-            throw new Error(`projectRoot is not a directory: "${resolvedProjectRoot}"`);
-        }
-        const { agentId: providedAgentId, ...agentConfig } = config;
-        const agentId = providedAgentId ?? this.agentIdGenerator.getUniqueId();
-        if (providedAgentId && this.agents.has(providedAgentId)) {
-            throw new Error(`Agent with id "${providedAgentId}" already exists`);
+            throw new Error(`projectRoot is not a directory: "${projectRoot}"`);
         }
-        const runtime = await this.agentConnectivityResolver.resolve(resolvedProjectRoot, agentConfig);
-        await this.harness.createAgent(agentId, resolvedProjectRoot, runtime.llmGatewayClient, toHarnessConfig(agentConfig, runtime.orgJwt), options);
+        const runtime = await this.agentConnectivityResolver.resolve(projectRoot, config);
+        await this.harness.createAgent(agentId, projectRoot, runtime.llmGatewayClient, toHarnessConfig(config, runtime.orgJwt), options.abortSignal !== undefined ? { abortSignal: options.abortSignal } : undefined);
         const agentSlice = this.router.registerAgent(agentId);
-        const agent = new DefaultAgent(this.harness, agentId, resolvedProjectRoot, agentConfig, runtime.llmGatewayClient, runtime.orgConnection, runtime.orgJwt, this.agentConnectivityResolver, this.router, agentSlice, { telemetry: this.telemetryBus, log: this.logBus }, this.clock, this.agentIdGenerator);
+        const agent = new DefaultAgent(this.harness, agentId, projectRoot, config, runtime.llmGatewayClient, runtime.orgConnection, runtime.orgJwt, this.agentConnectivityResolver, this.router, agentSlice, { telemetry: this.telemetryBus, log: this.logBus }, this.clock, this.agentIdGenerator);
         this.agents.set(agentId, agent);
         this.telemetryBus.emit({
             type: 'agent-created',
             timestamp: this.clock.now(),
             agentId,
-            projectRoot: resolvedProjectRoot,
+            projectRoot,
             modelName: runtime.llmGatewayClient.getModel().name,
         });
+        if (options.rehydrateThreads) {
+            // If thread enumeration or session attachment fails, the restore is a full failure
+            // (the user would otherwise see an agent marked `ready` whose chat sessions return 404).
+            // We must roll back the in-memory installation so the failure surfaces in
+            // `restoreFailures` and the id remains reusable via createAgent.
+            try {
+                const threadIds = await this.harness.getThreadIds(agentId);
+                agent.restoreSessions(threadIds);
+            }
+            catch (err) {
+                await this.rollbackInstall(agentId, agent);
+                throw err;
+            }
+        }
         return agent;
     }
-    /**
-     * Returns the IDs of all currently managed agents.
-     *
-     * @requirements
-     * - MUST return an array of all string keys (agent IDs) currently tracked in the internal `agents` map.
-     */
+    async rollbackInstall(agentId, agent) {
+        // `agent.destroy()` already calls `harness.destroyAgent(agentId)` internally
+        // (see `DefaultAgent.destroy` in `agent.ts`), so we don't need a second harness call.
+        try {
+            await agent.destroy();
+        }
+        catch {
+            // Swallow secondary failure; the original error (passed to caller) is what matters.
+        }
+        this.router.unregisterAgent(agentId);
+        this.agents.delete(agentId);
+    }
     getAgentIds() {
         this.assertNotDisposed();
         return Array.from(this.agents.keys());
     }
-    /**
-     * Retrieves a managed agent by its ID.
-     *
-     * @param agentId - ID of the agent to retrieve.
-     *
-     * @requirements
-     * - MUST throw an Error if the provided `agentId` is not found in the internal `agents` map.
-     * - MUST return the `Agent` instance associated with the given `agentId`.
-     */
     getAgent(agentId) {
         this.assertNotDisposed();
         const agent = this.agents.get(agentId);
@@ -168,36 +206,49 @@ export class AgentManager {
         }
         return agent;
     }
-    /**
-     * Destroys a managed agent by its ID, releasing all its resources.
-     *
-     * @param agentId - ID of the agent to destroy.
-     *
-     * @requirements
-     * - MUST throw an Error if the provided `agentId` is not found in the internal `agents` map.
-     * - MUST call `destroy()` on the target agent instance.
-     * - MUST remove the agent from the internal `agents` map.
-     */
     async destroyAgent(agentId) {
         this.assertNotDisposed();
         const agent = this.agents.get(agentId);
-        if (!agent) {
+        const failureIndex = this.restoreFailures.findIndex((f) => f.agentId === agentId);
+        if (!agent && failureIndex === -1) {
             throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
         }
-        await agent.destroy();
-        this.router.unregisterAgent(agentId);
-        this.agents.delete(agentId);
+        if (agent) {
+            await agent.destroy();
+            this.router.unregisterAgent(agentId);
+            this.agents.delete(agentId);
+        }
+        if (failureIndex !== -1) {
+            this.restoreFailures.splice(failureIndex, 1);
+        }
+        await this.identityStore.remove(agentId);
     }
-    /** Subscribe to telemetry events across every managed agent. Returns an unsubscribe function. */
     onTelemetry(callback) {
         this.assertNotDisposed();
         return this.telemetryBus.on(callback);
     }
-    /** Subscribe to structured log records across every managed agent. Returns an unsubscribe function. */
     onLog(callback) {
         this.assertNotDisposed();
         return this.logBus.on(callback);
     }
+    getRestoreFailures() {
+        this.assertNotDisposed();
+        return [...this.restoreFailures];
+    }
+    /**
+     * Re-exposes `harness.extensions` typed off `H`. Read-only; the SDK never
+     * leaks the harness reference itself, only its declared extensions surface.
+     * `assertNotDisposed` is intentionally NOT called here — the extensions
+     * object is reachable on the harness, and reading it after shutdown is the
+     * harness's prerogative to handle (its own disposal mechanics may have
+     * already torn down the underlying state).
+     */
+    get extensions() {
+        // The harness reference is constrained to `H`, so `harness.extensions`
+        // is structurally `H['extensions']` — but TS widens the property access
+        // through the constraint, requiring this cast.
+        return this.harness.extensions;
+    }
     assertNotDisposed() {
         if (this.disposed) {
             throw new AgentSDKError('AgentManager has been shut down.', AgentSDKErrorType.DISPOSED);
@@ -205,23 +256,23 @@ export class AgentManager {
     }
 }
 /**
- * Creates an {@link AgentManager} using the provided harness factory.
- *
- * Use this function in production code. It validates the `storageRootFolder`,
- * verifies the factory advertises a supported protocol version (failing fast
- * before any expensive harness construction), constructs the harness
- * asynchronously, sanity-checks that the constructed harness honors the
- * factory's advertised version, and returns a ready-to-use manager.
+ * Public entry point. Validates the storage root, gates the harness's
+ * advertised protocol version, constructs the harness, and returns a
+ * fully-restored {@link AgentManager}. Boot-time restore runs before this
+ * function returns; failures are queryable via
+ * {@link AgentManager.getRestoreFailures}.
  *
- * @param storageRootFolder - Existing directory used for agent persistence.
- * @param harnessFactory - Factory that constructs the harness implementation.
+ * The optional `connectivityResolver` overrides the default
+ * `DefaultAgentConnectivityResolver` — used by e2e tests and custom-auth
+ * deployments where the SDK should not run sf-CLI-based org resolution.
+ * Production callers leave it unset.
  *
  * @throws {AgentSDKError} `INCOMPATIBLE_HARNESS` when either the factory or
  *   the constructed harness reports a `protocolVersion` outside
  *   {@link SUPPORTED_PROTOCOL_VERSIONS}, or when the harness's reported
  *   version disagrees with the factory's.
  */
-export async function createAgentManager(storageRootFolder, harnessFactory) {
+export async function createAgentManager(storageRootFolder, harnessFactory, connectivityResolver) {
     let stats;
     try {
         stats = await stat(storageRootFolder);
@@ -255,8 +306,8 @@ export async function createAgentManager(storageRootFolder, harnessFactory) {
             `advertised version ${factoryVersion} (SDK supports: ${SUPPORTED_PROTOCOL_VERSIONS.join(', ')}). ` +
             `Update the SDK or harness package.`, AgentSDKErrorType.INCOMPATIBLE_HARNESS);
     }
-    const agentConnectivityResolver = new DefaultAgentConnectivityResolver();
-    return new AgentManager(harness, agentConnectivityResolver, new UUIDGenerator());
+    const agentConnectivityResolver = connectivityResolver ?? new DefaultAgentConnectivityResolver();
+    return DefaultAgentManager.__build(harness, agentConnectivityResolver, storageRootFolder, new UUIDGenerator(), new RealClock(), new LogBus());
 }
 function isSupportedProtocolVersion(version) {
     return (typeof version === 'number' &&

package/dist/agent.d.ts

@@ -20,6 +20,10 @@ export type AgentParentBuses = {
  * Each `Agent` wraps a single agent in the underlying harness. It
  * provides agent-level operations (configuration, MCP, lifecycle) and serves
  * as the factory for {@link ChatSession} instances.
+ *
+ * Harness-specific features (tool-search processor handles, workflows, etc.)
+ * are reached through {@link AgentManager.extensions}, not `Agent`. Per-agent
+ * accessors take the agent id as their first argument.
  */
 export interface Agent {
     /** Returns the unique agent identifier. */
@@ -212,6 +216,17 @@ export declare class DefaultAgent implements Agent {
     destroy(): Promise<void>;
     onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
     onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    /**
+     * Re-attach `DefaultChatSession` wrappers for thread ids that already
+     * exist in the harness's persistent store. Called by the SDK during
+     * boot-time restore. Idempotent — thread ids that already have a session
+     * are skipped.
+     *
+     * Not on the public {@link Agent} interface because it's only meaningful
+     * to {@link DefaultAgentManager}; that's also why `installAgent` returns
+     * the concrete `DefaultAgent` type rather than `Agent`.
+     */
+    restoreSessions(threadIds: string[]): void;
     private attachSession;
     private detachSession;
     private assertNotDisposed;

package/dist/agent.js

@@ -279,6 +279,24 @@ export class DefaultAgent {
         this.assertNotDisposed();
         return this.logBus.on(callback);
     }
+    /**
+     * Re-attach `DefaultChatSession` wrappers for thread ids that already
+     * exist in the harness's persistent store. Called by the SDK during
+     * boot-time restore. Idempotent — thread ids that already have a session
+     * are skipped.
+     *
+     * Not on the public {@link Agent} interface because it's only meaningful
+     * to {@link DefaultAgentManager}; that's also why `installAgent` returns
+     * the concrete `DefaultAgent` type rather than `Agent`.
+     */
+    restoreSessions(threadIds) {
+        this.assertNotDisposed();
+        for (const threadId of threadIds) {
+            if (!this.sessions.has(threadId)) {
+                this.attachSession(threadId);
+            }
+        }
+    }
     attachSession(threadId) {
         const slice = this.router.registerSession(threadId);
         const session = new DefaultChatSession(this.harness, this.agentId, threadId, slice, {

package/dist/harness/agent-harness.d.ts

@@ -4,9 +4,42 @@ import type { ChatStreamResult } from '../types/events.js';
 import type { Message } from '../types/messages.js';
 import type { TelemetryEventCallback } from '../types/telemetry-events.js';
 import type { ToolResultInfo } from '../types/tools.js';
-import type { HarnessAgentConfig, StreamOptions } from './harness-config.js';
+import type { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness-config.js';
 import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
 export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly [1];
+/**
+ * Opt-in helper that brands a harness type with the {@link AgentConfig}
+ * subtype it expects. Harness authors wrap their branded subtype with
+ * this helper when they want consumers to get the harness-specific
+ * config shape inferred at the `createAgent` call site:
+ *
+ * ```ts
+ * type MastraAgentHarness = WithAgentConfig<
+ *     AgentHarness & {
+ *         readonly harnessId: 'mastra';
+ *         readonly extensions: { mastra: { ... } };
+ *     },
+ *     MastraAgentConfig
+ * >;
+ * ```
+ *
+ * The helper attaches an optional, type-only `__agentConfig` slot that
+ * never exists at runtime. {@link ConfigOf} reads it. Harnesses that
+ * don't need extra config fields don't use the helper, and the base
+ * `AgentHarness` interface stays free of the phantom.
+ */
+export type WithAgentConfig<H extends AgentHarness, C extends AgentConfig> = H & {
+    readonly __agentConfig?: C;
+};
+/**
+ * Resolves the {@link AgentConfig} subtype declared by a harness via the
+ * {@link WithAgentConfig} helper. Falls back to `AgentConfig` when the
+ * harness wasn't branded. Used by `AgentManager.createAgent` so consumers
+ * don't have to pass `<MastraAgentConfig>` at the call site.
+ */
+export type ConfigOf<H extends AgentHarness> = H extends {
+    readonly __agentConfig?: infer C;
+} ? unknown extends C ? AgentConfig : C : AgentConfig;
 /**
  * Harness-agnostic interface abstracting the agentic runtime.
  *
@@ -25,6 +58,17 @@ export interface AgentHarness {
     readonly harnessId: string;
     /** Version of the SDK-to-harness protocol implemented by this harness. */
     readonly protocolVersion: number;
+    /**
+     * Harness-specific extensions namespace.
+     *
+     * Concrete harnesses narrow this to a typed shape (e.g.
+     * `MastraAgentHarness` declares `extensions.mastra.getToolSearchProcessor`).
+     * The SDK core never reads or interprets this object; it is a passthrough
+     * surface owned by the harness package. Consumers reach harness-specific
+     * features through `manager.extensions` (typed off the harness subtype);
+     * per-agent accessors take the agent id as their first argument.
+     */
+    readonly extensions: Record<string, unknown>;
     /**
      * Shut down the harness gracefully, releasing all resources.
      * Disconnects MCP servers, closes storage connections, and

package/dist/harness/harness-config.d.ts

@@ -73,6 +73,16 @@ export type HarnessAgentConfig = Omit<AgentConfig, 'orgAlias'> & {
  * Strips `orgAlias` since org resolution is handled above the harness and attaches
  * the resolved `orgJwt` so harness implementations can use {@link resolveMcpServerHeaders}
  * to inject auth for Salesforce Hosted MCP Servers.
+ *
+ * **Contract — extra fields survive the round-trip.** Harness packages that brand
+ * their harness type via {@link WithAgentConfig} extend `AgentConfig` with extra
+ * fields (e.g. `MastraAgentConfig.toolSearch`). Those fields are not declared on
+ * `AgentConfig` or `HarnessAgentConfig`; they ride through the spread below and the
+ * harness reads them at its own boundary via runtime narrowing
+ * (`(config as { toolSearch? }).toolSearch`). The spread-pass-through is part of
+ * the contract — refactoring to `pick` known fields would silently drop those
+ * fields and break harness extensibility. There is a regression test in
+ * `test/harness/harness-config.test.ts` that asserts unknown fields survive.
  */
 export declare function toHarnessConfig(config: AgentConfig, orgJwt?: JSONWebToken): HarnessAgentConfig;
 /**

package/dist/harness/harness-config.js

@@ -9,6 +9,16 @@
  * Strips `orgAlias` since org resolution is handled above the harness and attaches
  * the resolved `orgJwt` so harness implementations can use {@link resolveMcpServerHeaders}
  * to inject auth for Salesforce Hosted MCP Servers.
+ *
+ * **Contract — extra fields survive the round-trip.** Harness packages that brand
+ * their harness type via {@link WithAgentConfig} extend `AgentConfig` with extra
+ * fields (e.g. `MastraAgentConfig.toolSearch`). Those fields are not declared on
+ * `AgentConfig` or `HarnessAgentConfig`; they ride through the spread below and the
+ * harness reads them at its own boundary via runtime narrowing
+ * (`(config as { toolSearch? }).toolSearch`). The spread-pass-through is part of
+ * the contract — refactoring to `pick` known fields would silently drop those
+ * fields and break harness extensibility. There is a regression test in
+ * `test/harness/harness-config.test.ts` that asserts unknown fields survive.
  */
 export function toHarnessConfig(config, orgJwt) {
     const { orgAlias: _, ...rest } = config;

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

@@ -12,10 +12,10 @@ import type { AgentHarness } from './agent-harness.js';
  * guards against a factory that lies about its version or a harness package
  * whose runtime drifts from its packaging metadata.
  */
-export interface HarnessFactory {
+export interface HarnessFactory<H extends AgentHarness = AgentHarness> {
     /** Unique identifier for the harness type this factory builds (e.g., `'mastra'`). */
     readonly harnessId: string;
     /** SDK-to-harness protocol version implemented by the harness this factory builds. */
     readonly protocolVersion: number;
-    create(storageRootFolder: string): Promise<AgentHarness>;
+    create(storageRootFolder: string): Promise<H>;
 }

package/dist/harness/index.d.ts

@@ -1,4 +1,4 @@
-export type { AgentHarness } from './agent-harness.js';
+export type { AgentHarness, WithAgentConfig, ConfigOf } from './agent-harness.js';
 export type { HarnessFactory } from './harness-factory.js';
 export type { AgentConfig, StreamOptions } from './harness-config.js';
 export { toHarnessConfig, DEFAULT_MAX_STEPS } from './harness-config.js';

package/dist/index.d.ts

@@ -4,15 +4,15 @@ export type { ToolDefinition, ToolCallInfo, ToolResultInfo } from './types/tools
 export type { FinishReason, UsageMetadata } from './types/usage.js';
 export type { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness/harness-config.js';
 export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
-export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpServerInfo, } from './mcp-config.js';
+export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpServerInfo, McpToolInfo, McpToolAnnotations, } from './mcp-config.js';
 export { McpServerStatus } from './mcp-config.js';
 export { ModelName } from '@salesforce/llm-gateway-sdk';
 export { SfApiEnv } from '@salesforce/agentic-common';
-export { AgentManager, createAgentManager } from './agent-manager.js';
+export { type AgentManager, type RestoreFailure, createAgentManager } from './agent-manager.js';
 export { type Agent } from './agent.js';
 export { type ChatSession, type ChatOptions } from './chat-session.js';
 export type { AgentConnectivityResolver, ResolvedConnectivity } from './agent-connectivity-resolver.js';
-export type { AgentHarness, HarnessFactory } from './harness/index.js';
+export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './harness/index.js';
 export { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
 export { HarnessBusOwner } from './harness/harness-bus-owner.js';
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';

package/dist/index.js

@@ -7,7 +7,7 @@ export { McpServerStatus } from './mcp-config.js';
 export { ModelName } from '@salesforce/llm-gateway-sdk';
 export { SfApiEnv } from '@salesforce/agentic-common';
 // ── Agent Layer ─────────────────────────────────────────────────────
-export { AgentManager, createAgentManager } from './agent-manager.js';
+export { createAgentManager } from './agent-manager.js';
 export {} from './agent.js';
 export {} from './chat-session.js';
 export { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';

package/dist/internal/agent-identity-store.d.ts

@@ -0,0 +1,41 @@
+import { type LogBus } from '@salesforce/agentic-common';
+import type { AgentConfig } from '../harness/harness-config.js';
+export type AgentIdentityRecord = {
+    agentId: string;
+    projectRoot: string;
+    config: AgentConfig;
+};
+/**
+ * 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 declare class AgentIdentityStore {
+    private readonly storageRootFolder;
+    private readonly harnessId;
+    private readonly 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.
+     */
+    private readonly inflightWrites;
+    constructor(storageRootFolder: string, harnessId: string, logBus: LogBus);
+    write(agentId: string, projectRoot: string, config: AgentConfig): Promise<void>;
+    private writeImmediate;
+    remove(agentId: string): Promise<void>;
+    list(): Promise<AgentIdentityRecord[]>;
+    private dir;
+}