@salesforce/sfdx-agent-sdk 0.4.0 → 0.6.0

package/dist/agent-manager.d.ts

@@ -1,134 +1,202 @@
 import { type Clock, LogBus, type LogRecord, type Unsubscribe, type UniqueIDGenerator } from '@salesforce/agentic-common';
-import { type AgentHarness } from './harness/agent-harness.js';
+import { type AgentHarness, type ConfigOf } from './harness/agent-harness.js';
 import type { HarnessFactory } from './harness/harness-factory.js';
 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
  *
- * ### 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.
+ * `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 declare class AgentManager {
-    private readonly harness;
-    private readonly agentIdGenerator;
-    private readonly agentConnectivityResolver;
-    private readonly clock;
-    private readonly agents;
-    private readonly telemetryBus;
-    private readonly logBus;
-    private readonly router;
-    private readonly unroutedUnsubs;
-    private disposed;
+export interface AgentManager<H extends AgentHarness = AgentHarness> {
     /**
-     * Creates a new {@link 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.
      *
-     * This constructor is **exposed for testing only** so unit tests can inject a stubbed
-     * {@link AgentHarness} and deterministic ID generator.
+     * The config type is inferred from the harness type `H`. Harnesses that
+     * declare a subtype via `__agentConfig` (e.g. `MastraAgentHarness`
+     * declares `MastraAgentConfig`) get their extra fields autocompleted
+     * without an explicit generic at the call site. Extra fields thread
+     * through opaquely to the harness, which narrows what it cares about.
      *
-     * Production callers should use {@link createAgentManager} instead.
+     * @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?: ConfigOf<H> & {
+        agentId?: string;
+    }, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<Agent>;
+    /**
+     * Returns the live {@link Agent} for the given id.
      *
-     * @example
-     * ```ts
-     * // Recommended for production usage (constructs the default connectivity resolver):
-     * const manager = await createAgentManager(storageRootFolder, harnessFactory);
-     * ```
+     * @throws `AGENT_NOT_FOUND` if the id is unknown or only present in
+     *   {@link getRestoreFailures}.
      */
-    constructor(harness: AgentHarness, agentConnectivityResolver: AgentConnectivityResolver, agentIdGenerator?: UniqueIDGenerator, clock?: Clock, logBus?: LogBus);
+    getAgent(agentId: string): Agent;
     /**
-     * Shuts down the harness and destroys all managed agents.
+     * 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.
      *
-     * @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.
+     * @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>;
     /**
-     * Creates a new `Agent` with the given configuration.
+     * Harness-specific extensions namespace, typed off the harness subtype `H`.
      *
-     * @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.
+     * For the default `AgentHarness`, this is the opaque `Record<string, unknown>`
+     * declared on the contract — no IDE help. Consumers parameterize the manager
+     * over a harness-specific subtype (e.g. `MastraAgentHarness`) to get a typed
+     * slot like `manager.extensions.mastra.getToolSearchProcessor(agentId)`.
      *
-     * @throws If `projectRoot` does not exist or is not a directory.
+     * Per-agent extension accessors take the agent id as their first argument;
+     * orchestrator-level accessors (e.g. workflow registries) don't.
      *
-     * @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.
+     * The SDK never reads or interprets this object; it is a passthrough surface
+     * owned by the harness package.
      */
-    createAgent(projectRoot: string, config?: AgentConfig & {
+    readonly extensions: H['extensions'];
+    /** 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}.
+ *
+ * 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 DefaultAgentManager<H extends AgentHarness = AgentHarness> implements AgentManager<H> {
+    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();
+    /**
+     * 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).
+     *
+     * 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<H extends AgentHarness>(harness: H, agentConnectivityResolver: AgentConnectivityResolver, storageRootFolder: string, agentIdGenerator: UniqueIDGenerator, clock: Clock, logBus: LogBus): Promise<DefaultAgentManager<H>>;
+    private init;
+    shutdown(): Promise<void>;
+    createAgent(projectRoot: string, config?: ConfigOf<H> & {
         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[];
+    /**
+     * 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(): H['extensions'];
     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<H extends AgentHarness = AgentHarness>(storageRootFolder: string, harnessFactory: HarnessFactory<H>, connectivityResolver?: AgentConnectivityResolver): Promise<AgentManager<H>>;