@salesforce/sfdx-agent-sdk 0.56.0 → 0.57.0

package/CHANGELOG.md

@@ -3,6 +3,11 @@
 All notable changes to `@salesforce/sfdx-agent-sdk` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.57.0] - 2026-08-27
+
+### Features
+- **agent-sdk**: let createAgentManager observe boot-restore logs via onBootLog @W-23992664@ ([#770](https://github.com/forcedotcom/agentic-dx/pull/770))
+
 ## [0.56.0] - 2026-08-27
 
 ### Features

package/dist/agent-manager.d.ts

@@ -213,7 +213,7 @@ export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness>
      * 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, harnessSupportedProviderHints: readonly ProviderHint[], agentConnectivityResolver: AgentConnectivityResolver, resolvers: AgentRuntimeResolvers, storageRootFolder: string, agentIdGenerator: UniqueIDGenerator, clock: Clock, logBus: LogBus): Promise<DefaultAgentManager<H>>;
+    static __build<H extends AgentHarness>(harness: H, harnessSupportedProviderHints: readonly ProviderHint[], agentConnectivityResolver: AgentConnectivityResolver, resolvers: AgentRuntimeResolvers, storageRootFolder: string, agentIdGenerator: UniqueIDGenerator, clock: Clock, logBus: LogBus, onBootLog?: (record: LogRecord) => void): Promise<DefaultAgentManager<H>>;
     private init;
     shutdown(): Promise<void>;
     createAgent(projectRoot: string, config?: ConfigOf<H> & {
@@ -275,6 +275,10 @@ export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness>
  *   resolved bag threads through to `AgentHarness.createAgent`'s
  *   `options.hooks` and reaches the harness's native seam (Claude
  *   `PostToolUse`, Mastra `processInputStep`).
+ * - `onBootLog` — observes logs emitted *during construction only* (boot-time
+ *   restore failures + identity-store warnings), then detaches. It exists
+ *   because {@link AgentManager.onLog} can't be attached until this function
+ *   returns — too late for those. See the `onBootLog` option doc below.
  *
  * @throws {AgentSDKError} `INCOMPATIBLE_HARNESS` when either the factory or
  *   the constructed harness reports a `protocolVersion` outside
@@ -291,4 +295,24 @@ export declare function createAgentManager<H extends AgentHarness = AgentHarness
      * third-party remote MCP servers.
      */
     mcpAuthProviderResolver?: McpAuthProviderResolver;
+    /**
+     * Observes log records emitted *during construction* — and only then.
+     * Boot-time restore runs inside this function (before it returns) and
+     * emits an `agent restore failed` record for every persisted agent that
+     * fails to replay, plus `AgentIdentityStore` warnings (corrupt record
+     * JSON, harness-id mismatch). Those are dropped today:
+     * {@link AgentManager.onLog} can only be attached *after* this function
+     * returns, and `LogBus` has no replay, so a late subscriber never sees
+     * the construction-time records.
+     *
+     * This callback is subscribed before the restore pass and **detached as
+     * soon as construction finishes**, so it observes exactly the pre-return
+     * window and never overlaps {@link AgentManager.onLog}. A host that
+     * bridges SDK logs to its own logger wires `onBootLog` for the boot
+     * window and `manager.onLog` for the runtime window — two disjoint
+     * sources into the same sink, no double-logging. Unlike
+     * `manager.onLog`, this returns no `Unsubscribe`; its lifetime is fixed
+     * to construction.
+     */
+    onBootLog?: (record: LogRecord) => void;
 }): Promise<AgentManager<H>>;

package/dist/agent-manager.js

@@ -76,11 +76,25 @@ export class DefaultAgentManager {
      * is private, so this is the only way to obtain an instance, but
      * consumers should always go through {@link createAgentManager}.
      */
-    static async __build(harness, harnessSupportedProviderHints, agentConnectivityResolver, resolvers, storageRootFolder, agentIdGenerator, clock, logBus) {
-        const identityStore = new AgentIdentityStore(storageRootFolder, harness.harnessId, logBus);
-        const manager = new DefaultAgentManager(harness, harnessSupportedProviderHints, agentConnectivityResolver, resolvers, identityStore, agentIdGenerator, clock, logBus);
-        await manager.init();
-        return manager;
+    static async __build(harness, harnessSupportedProviderHints, agentConnectivityResolver, resolvers, storageRootFolder, agentIdGenerator, clock, logBus, onBootLog) {
+        // Subscribe `onBootLog` FIRST — before constructing anything that takes `logBus` — so it
+        // observes the ENTIRE construction window (identity-store reads + boot-time restore inside
+        // `init()`), then detach in `finally`. Keep it at the top: a caller can't reach
+        // `manager.onLog()` until this method returns, by which point construction has finished
+        // emitting and `LogBus` has no replay — so those records would otherwise be lost. Because
+        // the window closes exactly when construction does, `onBootLog` never overlaps a later
+        // `manager.onLog()`. (Nothing emits on `logBus` from a constructor today, but subscribing
+        // first means it stays correct if that ever changes.)
+        const unsubscribeBootLog = onBootLog ? logBus.on(onBootLog) : undefined;
+        try {
+            const identityStore = new AgentIdentityStore(storageRootFolder, harness.harnessId, logBus);
+            const manager = new DefaultAgentManager(harness, harnessSupportedProviderHints, agentConnectivityResolver, resolvers, identityStore, agentIdGenerator, clock, logBus);
+            await manager.init();
+            return manager;
+        }
+        finally {
+            unsubscribeBootLog?.();
+        }
     }
     async init() {
         const records = await this.identityStore.list();
@@ -386,6 +400,10 @@ export class DefaultAgentManager {
  *   resolved bag threads through to `AgentHarness.createAgent`'s
  *   `options.hooks` and reaches the harness's native seam (Claude
  *   `PostToolUse`, Mastra `processInputStep`).
+ * - `onBootLog` — observes logs emitted *during construction only* (boot-time
+ *   restore failures + identity-store warnings), then detaches. It exists
+ *   because {@link AgentManager.onLog} can't be attached until this function
+ *   returns — too late for those. See the `onBootLog` option doc below.
  *
  * @throws {AgentSDKError} `INCOMPATIBLE_HARNESS` when either the factory or
  *   the constructed harness reports a `protocolVersion` outside
@@ -428,9 +446,9 @@ export async function createAgentManager(storageRootFolder, harnessFactory, opti
     }
     const agentConnectivityResolver = options?.connectivityResolver ?? new DefaultAgentConnectivityResolver();
     const clock = new RealClock();
-    return DefaultAgentManager.__build(harness, harnessFactory.supportedProviderHints, agentConnectivityResolver, { hooksForAgent: options?.hooksForAgent, mcpAuthProviderResolver: options?.mcpAuthProviderResolver }, storageRootFolder, new UUIDGenerator(), clock, 
     // The manager's root log bus shares the manager clock and self-reads the process environment context.
-    new LogBus(clock));
+    const logBus = new LogBus(clock);
+    return DefaultAgentManager.__build(harness, harnessFactory.supportedProviderHints, agentConnectivityResolver, { hooksForAgent: options?.hooksForAgent, mcpAuthProviderResolver: options?.mcpAuthProviderResolver }, storageRootFolder, new UUIDGenerator(), clock, logBus, options?.onBootLog);
 }
 function isSupportedProtocolVersion(version) {
     return (typeof version === 'number' &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -47,9 +47,9 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.52.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.55.0",
-    "@salesforce/sfdx-agent-harness-openai": "0.21.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.53.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.56.0",
+    "@salesforce/sfdx-agent-harness-openai": "0.22.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.27",