@salesforce/sfdx-agent-sdk 0.4.0 → 0.5.0

package/README.md

@@ -6,16 +6,32 @@ without coupling consumer code to a specific AI framework.
 
 ## Quick Start
 
-> **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.
 
 ```typescript
 import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
 import { MastraHarnessFactory } from '@salesforce/sfdx-agent-harness-mastra';
 
-// 1. Create the manager (validates the storage folder exists)
+// 1. Create the manager. This validates the storage folder, gates the harness's
+//    protocol version, and replays any agents the SDK persisted on a prior run
+//    (one JSON file per agent under `${storageRootFolder}/agents/`).
 const manager = await createAgentManager('/path/to/storage', new MastraHarnessFactory());
 
-// 2. Create an agent
+// Bridge SDK logs into your host logger so you observe restore failures + warnings.
+manager.onLog((record) => {
+  console[record.level](record.message, record.context);
+});
+
+// Boot-time restore failures are queryable as instance state — use them to seed
+// per-agent UI state, not for logging (the SDK already emitted each via onLog).
+for (const failure of manager.getRestoreFailures()) {
+  // mark `failure.agentId` as `error` in your application state
+}
+
+// 2. Create an agent. The identity triple `{ agentId, projectRoot, config }` is
+//    persisted to disk; the next call to `createAgentManager` over the same
+//    storage folder will replay this agent automatically.
 const agent = await manager.createAgent('/path/to/project', {
   agentId: 'developer-assistant',
   modelId: 'llmgateway__OpenAIGPT5',
@@ -35,31 +51,57 @@ for await (const event of eventStream) {
   }
 }
 
-// 4. Shut down
+// 4. Shut down. The harness is torn down; persisted identity files are NOT
+//    removed, so a subsequent `createAgentManager` call restores them.
 await manager.shutdown();
 ```
 
 ## API Reference
 
-### `createAgentManager(storageRootFolder, harnessFactory): Promise<AgentManager>`
+### `createAgentManager(storageRootFolder, harnessFactory, connectivityResolver?): Promise<AgentManager>`
 
 Factory function that creates an `AgentManager` backed by the provided `HarnessFactory`. The `storageRootFolder` must be
-an existing directory and is used for persistent state (database, memory). The SDK verifies that the constructed harness
-uses a supported protocol version before returning the manager.
+an existing directory and is used for persistent state (the harness's runtime data plus the SDK's per-agent identity
+files at `${storageRootFolder}/agents/<id>.json`). The SDK verifies that the constructed harness uses a supported
+protocol version, replays any persisted agents the harness can still serve, and returns the manager. The optional
+`connectivityResolver` overrides the default sf-CLI-based org resolution — used by e2e tests and custom-auth
+deployments; production callers leave it unset.
+
+Restore failures (a persisted record the SDK could not bring back online — e.g. missing project directory, harness
+rejection, thread rehydration failure) are queryable on the returned manager via `getRestoreFailures()`. Soft skips
+inside the persistence directory (corrupt JSON, harness-id mismatch) are silently dropped from the restore pass and emit
+a `warn` on the SDK's log bus.
 
 ### `AgentManager`
 
-Top-level orchestrator that owns the harness and manages agent lifecycle.
+Top-level orchestrator that owns the harness and manages agent lifecycle. `AgentManager` is an interface; the concrete
+implementation is internal — `createAgentManager` is the only public entry point.
+
+| Method               | Signature                                                                                                                       | Description                                                                                                                                                               |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createAgent`        | `(projectRoot: string, config?: AgentConfig & { agentId?: string }, options?: { abortSignal?: AbortSignal }) => Promise<Agent>` | Create and register a new agent and persist its identity triple. `projectRoot` must be an existing directory. If `agentId` is omitted a UUID is generated.                |
+| `getAgent`           | `(agentId: string) => Agent`                                                                                                    | Retrieve a live agent by ID. Throws `AgentSDKError` (`AGENT_NOT_FOUND`) for unknown ids and for ids that are only present in `getRestoreFailures()`.                      |
+| `getAgentIds`        | `() => string[]`                                                                                                                | List all live agent IDs (successful + successfully restored). Failed-restore agents are not included — query `getRestoreFailures()` separately.                           |
+| `destroyAgent`       | `(agentId: string) => Promise<void>`                                                                                            | Destroy an agent, remove its identity record from disk, and clear any matching `getRestoreFailures()` entry. Failed-restore-only ids are accepted (no harness call made). |
+| `shutdown`           | `() => Promise<void>`                                                                                                           | Destroy all live agents and shut down the harness. Identity files survive (that's the whole point) — restart `createAgentManager` over the same root to bring them back.  |
+| `onTelemetry`        | `(callback: TelemetryEventCallback) => Unsubscribe`                                                                             | Subscribe to telemetry across all managed agents.                                                                                                                         |
+| `onLog`              | `(callback: (record: LogRecord) => void) => Unsubscribe`                                                                        | Subscribe to structured logs across all managed agents. Bridge this into your host logger to observe restore-failure events + soft-skip warnings.                         |
+| `getRestoreFailures` | `() => RestoreFailure[]`                                                                                                        | Snapshot of agents the SDK could not restore on this boot. Each entry carries the persisted `{ agentId, projectRoot, config }` plus the underlying error.                 |
+
+#### `RestoreFailure`
+
+```typescript
+type RestoreFailure = {
+  agentId: string;
+  projectRoot: string;
+  config: AgentConfig;
+  error: unknown;
+};
+```
 
-| Method         | Signature                                                                                                                       | Description                                                                                                                |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `createAgent`  | `(projectRoot: string, config?: AgentConfig & { agentId?: string }, options?: { abortSignal?: AbortSignal }) => Promise<Agent>` | Create and register a new agent. `projectRoot` must be an existing directory. If `agentId` is omitted a UUID is generated. |
-| `getAgent`     | `(agentId: string) => Agent`                                                                                                    | Retrieve an agent by ID. Throws `AgentSDKError` (`AGENT_NOT_FOUND`) if missing.                                            |
-| `getAgentIds`  | `() => string[]`                                                                                                                | List all managed agent IDs.                                                                                                |
-| `destroyAgent` | `(agentId: string) => Promise<void>`                                                                                            | Destroy an agent and release its resources. Throws `AgentSDKError` (`AGENT_NOT_FOUND`) if missing.                         |
-| `shutdown`     | `() => Promise<void>`                                                                                                           | Destroy all agents and shut down the harness.                                                                              |
-| `onTelemetry`  | `(callback: TelemetryEventCallback) => Unsubscribe`                                                                             | Subscribe to telemetry across all managed agents.                                                                          |
-| `onLog`        | `(callback: (record: LogRecord) => void) => Unsubscribe`                                                                        | Subscribe to structured logs across all managed agents.                                                                    |
+Returned by `AgentManager.getRestoreFailures()`. Use it to seed `error`-state placeholders in your application; do
+**not** iterate it for logging — the SDK already emitted each failure via `onLog` at `error` level during the restore
+pass, before this function returned.
 
 ### `Agent`
 
@@ -134,16 +176,16 @@ Discriminated union (`event.type`) of streaming events:
 
 #### `AgentConfig`
 
-| Field           | Type               | Description                                                          |
-| --------------- | ------------------ | -------------------------------------------------------------------- |
-| `orgAlias?`     | `string`           | Salesforce org alias or username. Falls back to project/default org. |
-| `modelId?`      | `ModelName`        | LLM model identifier (e.g. `'llmgateway__OpenAIGPT5'`).              |
-| `name?`         | `string`           | Human-readable agent name.                                           |
-| `description?`  | `string`           | Agent purpose description.                                           |
-| `instructions?` | `string`           | System instructions for the agent.                                   |
-| `tools?`        | `ToolDefinition[]` | Consumer-executed tool schemas.                                      |
-| `mcpServers?`   | `MCPConfiguration` | MCP server connections.                                              |
-| `skills?`       | `string[]`         | Each entry is either an individual skill folder (containing `SKILL.md`) or a parent folder containing skill subfolders. Relative and absolute paths supported; forms can be mixed in the same array. |
+| Field           | Type               | Description                                                                                                                                                                                                                                                                                                                          |
+| --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `orgAlias?`     | `string`           | Salesforce org alias or username. Falls back to project/default org.                                                                                                                                                                                                                                                                 |
+| `modelId?`      | `ModelName`        | LLM model identifier (e.g. `'llmgateway__OpenAIGPT5'`).                                                                                                                                                                                                                                                                              |
+| `name?`         | `string`           | Human-readable agent name.                                                                                                                                                                                                                                                                                                           |
+| `description?`  | `string`           | Agent purpose description.                                                                                                                                                                                                                                                                                                           |
+| `instructions?` | `string`           | System instructions for the agent.                                                                                                                                                                                                                                                                                                   |
+| `tools?`        | `ToolDefinition[]` | Consumer-executed tool schemas.                                                                                                                                                                                                                                                                                                      |
+| `mcpServers?`   | `MCPConfiguration` | MCP server connections.                                                                                                                                                                                                                                                                                                              |
+| `skills?`       | `string[]`         | Each entry is either an individual skill folder (containing `SKILL.md`) or a parent folder containing skill subfolders. Relative and absolute paths supported; forms can be mixed in the same array.                                                                                                                                 |
 | `rules?`        | `string[]`         | Each entry is either an individual `.md` rule file or a directory of `.md` rule files (scanned one level deep, alphabetical, non-`.md` skipped). Bodies are composed verbatim into the agent's effective system prompt; YAML frontmatter is optional and stripped if present. Matches Claude Code's `.claude/rules/*.md` convention. |
 
 #### `StreamOptions`

package/dist/agent-manager.d.ts

@@ -5,130 +5,168 @@ import { type AgentConfig } from './harness/harness-config.js';
 import { type Agent } from './agent.js';
 import type { TelemetryEventCallback } from './types/telemetry-events.js';
 import { type AgentConnectivityResolver } from './agent-connectivity-resolver.js';
+/**
+ * Per-agent failure recorded during the boot-time restore pass.
+ *
+ * Returned in bulk by {@link AgentManager.getRestoreFailures}. Each entry
+ * captures the persisted identity triple plus the underlying error so the
+ * consumer can mark its placeholder as `error` and either DELETE or recreate
+ * the agent.
+ */
+export type RestoreFailure = {
+    agentId: string;
+    projectRoot: string;
+    config: AgentConfig;
+    error: unknown;
+};
 /**
  * Manages the lifecycle of {@link Agent} instances.
  *
- * 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).
+ * The concrete implementation ({@link DefaultAgentManager}) is internal to
+ * the SDK and constructed only via {@link createAgentManager}. Consumers
+ * program against this interface; they never see the implementation type.
+ *
+ * ### Boot-time restore
+ *
+ * `createAgentManager` reads any agents the SDK persisted on a prior run
+ * (`${storageRootFolder}/agents/<id>.json`) and replays `installAgent` for
+ * each before returning. Failures land in {@link getRestoreFailures}, not
+ * thrown. Subscribe to {@link onLog} to bridge SDK log events into your
+ * host logger; restore failures are emitted at `error` level and soft skips
+ * (corrupt JSON, harness-id mismatch) at `warn`.
+ */
+export interface AgentManager {
+    /**
+     * Creates a new {@link Agent} with the given configuration and persists
+     * its identity triple `{ agentId, projectRoot, config }` so it can be
+     * restored on the next boot.
+     *
+     * @throws If `projectRoot` does not exist or is not a directory.
+     * @throws If `config.agentId` is provided and an agent with that ID is
+     *   already registered (live or in restore-failure state).
+     */
+    createAgent(projectRoot: string, config?: AgentConfig & {
+        agentId?: string;
+    }, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<Agent>;
+    /**
+     * Returns the live {@link Agent} for the given id.
+     *
+     * @throws `AGENT_NOT_FOUND` if the id is unknown or only present in
+     *   {@link getRestoreFailures}.
+     */
+    getAgent(agentId: string): Agent;
+    /**
+     * Returns the ids of all live agents (successfully created or
+     * restored). Failed-restore agents are not included — query
+     * {@link getRestoreFailures} separately.
+     */
+    getAgentIds(): string[];
+    /**
+     * Destroys a managed agent, removes its identity record from disk,
+     * and clears any matching entry in {@link getRestoreFailures}.
+     *
+     * If the id is only in `getRestoreFailures()` (no live agent), the
+     * harness is not consulted; the identity file is removed and the
+     * failure entry cleared. After this returns, the same id may be
+     * passed to {@link createAgent} again.
+     *
+     * @throws `AGENT_NOT_FOUND` if the id is neither live nor a
+     *   restore-failure entry.
+     */
+    destroyAgent(agentId: string): Promise<void>;
+    /** Shuts down the harness and destroys all live agents. */
+    shutdown(): Promise<void>;
+    /** Subscribe to telemetry events across every managed agent. */
+    onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
+    /** Subscribe to structured log records across every managed agent. */
+    onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    /**
+     * Returns a snapshot of the boot-time restore failures the SDK has not
+     * yet been told to forget. Each entry is cleared on a successful
+     * {@link destroyAgent} for the same id; recreating an agent with the
+     * same id via {@link createAgent} also clears the entry.
+     */
+    getRestoreFailures(): RestoreFailure[];
+}
+/**
+ * Concrete implementation of {@link AgentManager}. **Not exported** from
+ * `src/index.ts` — public construction goes through {@link createAgentManager}.
  *
- * ### 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 declare class AgentManager {
+export declare class DefaultAgentManager implements AgentManager {
     private readonly harness;
     private readonly agentIdGenerator;
     private readonly agentConnectivityResolver;
     private readonly clock;
+    private readonly identityStore;
     private readonly agents;
+    private restoreFailures;
     private readonly telemetryBus;
     private readonly logBus;
     private readonly router;
     private readonly unroutedUnsubs;
     private disposed;
+    private constructor();
     /**
-     * Creates a new {@link AgentManager}.
+     * 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).
      *
-     * 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: AgentHarness, agentConnectivityResolver: AgentConnectivityResolver, agentIdGenerator?: UniqueIDGenerator, clock?: Clock, logBus?: LogBus);
-    /**
-     * Shuts down the harness and destroys all managed 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 __build(harness: AgentHarness, agentConnectivityResolver: AgentConnectivityResolver, storageRootFolder: string, agentIdGenerator: UniqueIDGenerator, clock: Clock, logBus: LogBus): Promise<DefaultAgentManager>;
+    private init;
     shutdown(): Promise<void>;
-    /**
-     * 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.
-     */
     createAgent(projectRoot: string, config?: AgentConfig & {
         agentId?: string;
     }, options?: {
         abortSignal?: AbortSignal;
     }): Promise<Agent>;
     /**
-     * Returns the IDs of all currently managed agents.
+     * 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.
      *
-     * @requirements
-     * - MUST return an array of all string keys (agent IDs) currently tracked in the internal `agents` map.
+     * 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.
      */
+    private installAgent;
+    private rollbackInstall;
     getAgentIds(): string[];
-    /**
-     * 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: string): 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.
-     */
     destroyAgent(agentId: string): Promise<void>;
-    /** Subscribe to telemetry events across every managed agent. Returns an unsubscribe function. */
     onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
-    /** Subscribe to structured log records across every managed agent. Returns an unsubscribe function. */
     onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    getRestoreFailures(): RestoreFailure[];
     private assertNotDisposed;
 }
 /**
- * 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 declare function createAgentManager(storageRootFolder: string, harnessFactory: HarnessFactory): Promise<AgentManager>;
+export declare function createAgentManager(storageRootFolder: string, harnessFactory: HarnessFactory, connectivityResolver?: AgentConnectivityResolver): Promise<AgentManager>;

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}"`);
+            throw new Error(`projectRoot is not a directory: "${projectRoot}"`);
         }
-        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`);
-        }
-        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,35 @@ 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];
+    }
     assertNotDisposed() {
         if (this.disposed) {
             throw new AgentSDKError('AgentManager has been shut down.', AgentSDKErrorType.DISPOSED);
@@ -205,23 +242,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 +292,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

@@ -212,6 +212,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/index.d.ts

@@ -8,7 +8,7 @@ export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemote
 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';

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;
+}

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/package.json

@@ -1,10 +1,17 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.4.0",
+  "version": "0.5.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",
@@ -33,7 +40,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-mastra": "0.4.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.5.0",
     "@types/node": "^22.19.17",
     "@vitest/coverage-istanbul": "^4.1.5",
     "@vitest/eslint-plugin": "^1.6.16",