@salesforce/sfdx-agent-sdk 0.5.0 → 0.7.0

package/README.md

@@ -58,7 +58,7 @@ await manager.shutdown();
 
 ## API Reference
 
-### `createAgentManager(storageRootFolder, harnessFactory, connectivityResolver?): Promise<AgentManager>`
+### `createAgentManager<F>(storageRootFolder, harnessFactory, connectivityResolver?): Promise<AgentManager<H>>`
 
 Factory function that creates an `AgentManager` backed by the provided `HarnessFactory`. The `storageRootFolder` must be
 an existing directory and is used for persistent state (the harness's runtime data plus the SDK's per-agent identity
@@ -67,26 +67,46 @@ protocol version, replays any persisted agents the harness can still serve, and
 `connectivityResolver` overrides the default sf-CLI-based org resolution — used by e2e tests and custom-auth
 deployments; production callers leave it unset.
 
+The harness type `H` is **inferred from the factory's `create()` return type**, so consumers don't pass an explicit type
+argument:
+
+```typescript
+import { MastraHarnessFactory } from '@salesforce/sfdx-agent-harness-mastra';
+
+const manager = await createAgentManager(storageRoot, new MastraHarnessFactory());
+//    ^? AgentManager<MastraAgentHarness>
+```
+
+When the factory's `create()` is typed as `Promise<AgentHarness>` (the default), the manager is
+`AgentManager<AgentHarness>` and behaves exactly as before. Harness packages that ship a branded subtype (e.g.
+`MastraAgentHarness`) lift consumers into that subtype automatically — see "Harness Extensibility" below.
+
 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`
+### `AgentManager<H extends AgentHarness = AgentHarness>`
 
 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.                 |
+The optional `H` type parameter (default `AgentHarness`) lets harness-aware consumers reach harness-specific features
+through a typed `manager.extensions` slot. `createAgentManager` infers `H` from the factory; you usually don't write it
+explicitly. The `createAgent` config parameter narrows automatically when the harness brands itself with
+`WithAgentConfig` — see "Harness Extensibility" below.
+
+| Property / Method    | Signature                                                                                                                          | Description                                                                                                                                                                                                                                             |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `extensions`         | `H['extensions']`                                                                                                                  | Harness-specific extensions namespace (read-only). Re-exposes the harness's `extensions` slot typed off `H`. Per-agent accessors take the agent id as their first argument. The SDK never reads or interprets this — see "Harness Extensibility" below. |
+| `createAgent`        | `(projectRoot: string, config?: ConfigOf<H> & { agentId?: string }, options?: { abortSignal?: AbortSignal }) => Promise<Agent<H>>` | 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. The config type is inferred from the harness — see `ConfigOf<H>`.                            |
+| `getAgent`           | `(agentId: string) => Agent<H>`                                                                                                    | 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`
 
@@ -103,9 +123,11 @@ Returned by `AgentManager.getRestoreFailures()`. Use it to seed `error`-state pl
 **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`
+### `Agent<H extends AgentHarness = AgentHarness>`
 
-A configured AI agent. Factory for chat sessions.
+A configured AI agent. Factory for chat sessions. The optional `H` type parameter is currently informational on `Agent`
+— harness-specific features are reached through `manager.extensions`, not `agent.extensions`. The default `AgentHarness`
+keeps unparameterized call sites working.
 
 | Method                 | Signature                                                                          | Description                                                            |
 | ---------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
@@ -226,9 +248,53 @@ type MCPRemoteServerConfig = {
 | -------- | ------------------------------------------------------ | --------------------------------------- |
 | `name`   | `string`                                               | Server identifier.                      |
 | `status` | `'connected' \| 'connecting' \| 'disabled' \| 'error'` | Connection state.                       |
-| `tools`  | `string[]`                                             | Discovered tool names.                  |
+| `tools`  | [`McpToolInfo[]`](#mcptoolinfo)                        | Discovered tools (name + metadata).     |
 | `error?` | `string`                                               | Error message when status is `'error'`. |
 
+#### `McpToolInfo`
+
+Runtime metadata for a single MCP-discovered tool. Optional fields are populated when the underlying harness can supply
+them from its MCP client; harnesses whose runtime does not expose a given field leave it `undefined`. Consumers must
+treat every field except `name` as optional.
+
+| Field          | Type                                        | Description                                                                                          |
+| -------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `name`         | `string`                                    | Tool name as exposed to the LLM, including any harness-applied namespacing.                          |
+| `description?` | `string`                                    | Human-readable description of what the tool does.                                                    |
+| `inputSchema?` | `Record<string, unknown>`                   | Tool input parameters as a [**JSON Schema**](https://json-schema.org/) object (the MCP wire format). |
+| `annotations?` | [`McpToolAnnotations`](#mcptoolannotations) | Behavioral / UI-presentation hints declared by the MCP server.                                       |
+
+**`inputSchema` is a JSON Schema object, not a Zod schema.** It is typed as `Record<string, unknown>` so this package
+incurs no `zod` or `@types/json-schema` dependency. If you need a Zod schema at runtime, convert with a library such as
+[`json-schema-to-zod`](https://www.npmjs.com/package/json-schema-to-zod); for runtime validation, feed the schema to a
+JSON Schema validator such as [AJV](https://ajv.js.org/).
+
+The exact set of keys present on `inputSchema` depends on the harness's normalization step. The Mastra harness, for
+example, reaches consumers after passing through `@mastra/schema-compat`'s converter, which adds a `$schema` annotation
+(typically `http://json-schema.org/draft-07/schema#`) and `additionalProperties: false` even when the source MCP server
+did not declare them. Both are valid JSON Schema annotations and are forwarded untouched.
+
+**Why no `outputSchema` field?** The MCP protocol carries an optional `outputSchema` per tool, but neither shipped
+harness can supply it: Mastra's `@mastra/mcp` strips it from each wrapped tool before the harness sees it (to keep
+`CallToolResult` validation correct), and the Claude Agent SDK's MCP status surface omits the field entirely. We
+deliberately keep it off the SDK contract rather than ship an always-`undefined` field consumers would have to ignore;
+adding it later if a harness gains the data is non-breaking.
+
+#### `McpToolAnnotations`
+
+Mirrors the
+[MCP protocol's `Tool.annotations` shape](https://spec.modelcontextprotocol.io/specification/server/tools/#tool-annotations).
+Each field is optional because MCP servers populate annotations à la carte; absence means "the server did not declare
+this hint," not "false."
+
+| Field              | Type      | Description                                                                    |
+| ------------------ | --------- | ------------------------------------------------------------------------------ |
+| `title?`           | `string`  | Human-readable label suitable for UI display (vs. the machine `name`).         |
+| `readOnlyHint?`    | `boolean` | When `true`, the tool only reads data and has no side effects.                 |
+| `destructiveHint?` | `boolean` | When `true`, the tool may perform destructive updates to its environment.      |
+| `idempotentHint?`  | `boolean` | When `true`, repeated calls with the same arguments have no additional effect. |
+| `openWorldHint?`   | `boolean` | When `true`, the tool may interact with an open world of external entities.    |
+
 ### Tool Types
 
 ```typescript
@@ -338,7 +404,14 @@ const agent = await manager.createAgent('/project', {
 // Poll until connected
 const servers = agent.getMcpServerInfo();
 for (const s of servers) {
-  console.log(`${s.name}: ${s.status}, tools: ${s.tools.join(', ')}`);
+  const toolNames = s.tools.map((t) => t.name).join(', ');
+  console.log(`${s.name}: ${s.status}, tools: ${toolNames}`);
+
+  // Each tool also carries description / inputSchema / annotations when available.
+  for (const tool of s.tools) {
+    if (tool.description) console.log(`  ${tool.name} — ${tool.description}`);
+    // tool.inputSchema is a JSON Schema object; convert with json-schema-to-zod if you need Zod.
+  }
 }
 ```
 
@@ -419,6 +492,84 @@ Returns `true` if the URL matches a Salesforce Hosted MCP Server endpoint (prod,
 The SDK exposes typed `TelemetryEvent` / `LogRecord` streams at the manager, agent, and session scopes. See
 [Telemetry & Logs](#telemetry--logs) below for the event catalog, emit contract, and structured-log table.
 
+### Harness Extensibility
+
+The `AgentHarness` contract is the SDK's lowest-common-denominator surface — every harness implements it, and the SDK
+consumes only that. Features a single harness has but the contract can't generalize over (Mastra workflows, Mastra's
+`ToolSearchProcessor`, structured working memory, etc.) live on a typed `extensions` slot the harness package owns. The
+SDK never reads or interprets `extensions`; it just threads the type through.
+
+For most consumers, the inference machinery means **you never write the type parameters**:
+
+```typescript
+import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
+import { MastraHarnessFactory } from '@salesforce/sfdx-agent-harness-mastra';
+
+const manager = await createAgentManager(storageRoot, new MastraHarnessFactory());
+//    ^? AgentManager<MastraAgentHarness>   (inferred from the factory)
+
+const agent = await manager.createAgent(projectRoot, {
+  instructions: '...',
+  toolSearch: { pool: '*' }, // ← Mastra-specific config; autocompletes via WithAgentConfig
+});
+
+const processor = manager.extensions.mastra.getToolSearchProcessor(agent.getId());
+//    ^? ToolSearchHandle | undefined
+```
+
+Per-agent accessors (like `getToolSearchProcessor` above) take the agent id as their first argument; orchestrator-level
+accessors (e.g. workflow registries) don't. Everything lives on `manager.extensions` regardless of scope — the SDK chose
+the harness-scoped shape for simplicity over a per-feature scope split. See `ARCHITECTURE.md` → "Harness Extensibility"
+for the rationale.
+
+#### `AgentHarness.extensions: Record<string, unknown>`
+
+Passthrough slot on the harness contract. Concrete harnesses narrow it on their branded subtype (e.g.
+`MastraAgentHarness` declares `extensions: { mastra: { ... } }`). The SDK never reads this; it surfaces it as
+`AgentManager.extensions` typed off the harness type.
+
+#### `WithAgentConfig<H extends AgentHarness, C extends AgentConfig>`
+
+Opt-in helper for harnesses that accept extra `AgentConfig` fields. Wrap your branded harness type with this helper and
+`AgentManager.createAgent`'s config parameter narrows to `C` automatically:
+
+```typescript
+import type { AgentHarness, WithAgentConfig, AgentConfig } from '@salesforce/sfdx-agent-sdk';
+
+type MyAgentConfig = AgentConfig & { custom?: { ... } };
+
+type MyAgentHarness = WithAgentConfig<
+    AgentHarness & {
+        readonly harnessId: 'my-harness';
+        readonly extensions: { 'my-harness': { ... } };
+    },
+    MyAgentConfig
+>;
+```
+
+The brand is type-only; it never exists at runtime. Harnesses that don't accept extra config fields leave
+`WithAgentConfig` unused — the base `AgentHarness` interface stays untouched.
+
+#### `ConfigOf<H extends AgentHarness>`
+
+Resolves the `AgentConfig` subtype declared by a harness via `WithAgentConfig`. Falls back to plain `AgentConfig` when
+the harness wasn't branded. Used internally by `AgentManager.createAgent`'s parameter type; harness-package authors
+don't usually reference it directly.
+
+#### Decision rule: cross-harness contract vs. extension
+
+When deciding where a new harness-package feature should live:
+
+| Question                                                                                        | Answer → Where it goes                                       |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Could a second harness implement this with similar semantics?                                   | Likely cross-harness contract                                |
+| Is this an operational handle on a harness-internal runtime object (e.g. processor, workspace)? | Extension namespace                                          |
+| Does this require harness-specific config that doesn't generalize?                              | Extension (extra fields on a `WithAgentConfig`-branded type) |
+| Is the polyfill cheap and faithful across harnesses?                                            | Cross-harness contract with a polyfilled default             |
+
+Extensions are the default for "Mastra has a thing nothing else has." See `ARCHITECTURE.md` → "Harness Extensibility"
+for the full design including the `WithAgentConfig` rationale.
+
 ## Writing a Harness
 
 The SDK ships no harness implementation. Consumers pick one by passing a `HarnessFactory` instance to
@@ -430,7 +581,7 @@ Harness authors implement two interfaces and can compose one helper class, all e
 
 | Export                        | Role                                                                                                                                   |
 | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `HarnessFactory`              | Construct an `AgentHarness` bound to a storage root. Declares `harnessId` and `protocolVersion`.                                       |
+| `HarnessFactory<H>`           | Construct a harness of type `H` bound to a storage root. Declares `harnessId` and `protocolVersion`. Default `H = AgentHarness`.       |
 | `AgentHarness`                | Runtime contract: agent / thread / stream / tool / message lifecycle. Declares its own `harnessId` and `protocolVersion`.              |
 | `SUPPORTED_PROTOCOL_VERSIONS` | Readonly list of harness protocol versions this SDK accepts. `createAgentManager` checks both the factory and the constructed harness. |
 | `HarnessBusOwner`             | Composition helper owning telemetry + log buses with `dispose()` semantics. Reuse it instead of reimplementing bus plumbing.           |
@@ -461,10 +612,10 @@ class MyHarness implements AgentHarness {
   // implement the remaining AgentHarness methods (createAgent, stream, …)
 }
 
-export class MyHarnessFactory implements HarnessFactory {
+export class MyHarnessFactory implements HarnessFactory<MyHarness> {
   readonly harnessId = 'my-harness';
   readonly protocolVersion = 1;
-  async create(storageRootFolder: string): Promise<AgentHarness> {
+  async create(storageRootFolder: string): Promise<MyHarness> {
     return new MyHarness(storageRootFolder);
   }
 }

package/dist/agent-manager.d.ts

@@ -1,5 +1,5 @@
 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';
@@ -35,17 +35,23 @@ export type RestoreFailure = {
  * host logger; restore failures are emitted at `error` level and soft skips
  * (corrupt JSON, harness-id mismatch) at `warn`.
  */
-export interface AgentManager {
+export interface AgentManager<H extends AgentHarness = AgentHarness> {
     /**
      * 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.
      *
+     * 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.
+     *
      * @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 & {
+    createAgent(projectRoot: string, config?: ConfigOf<H> & {
         agentId?: string;
     }, options?: {
         abortSignal?: AbortSignal;
@@ -78,6 +84,21 @@ export interface AgentManager {
     destroyAgent(agentId: string): Promise<void>;
     /** Shuts down the harness and destroys all live agents. */
     shutdown(): Promise<void>;
+    /**
+     * Harness-specific extensions namespace, typed off the harness subtype `H`.
+     *
+     * 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)`.
+     *
+     * Per-agent extension accessors take the agent id as their first argument;
+     * orchestrator-level accessors (e.g. workflow registries) don't.
+     *
+     * The SDK never reads or interprets this object; it is a passthrough surface
+     * owned by the harness package.
+     */
+    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. */
@@ -99,7 +120,7 @@ export interface AgentManager {
  * pattern mirrors {@link Workspace.create}: a private constructor for sync
  * field assignment, then a static async builder that calls `init()`.
  */
-export declare class DefaultAgentManager implements AgentManager {
+export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness> implements AgentManager<H> {
     private readonly harness;
     private readonly agentIdGenerator;
     private readonly agentConnectivityResolver;
@@ -123,10 +144,10 @@ export declare class DefaultAgentManager implements AgentManager {
      * 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>;
+    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?: AgentConfig & {
+    createAgent(projectRoot: string, config?: ConfigOf<H> & {
         agentId?: string;
     }, options?: {
         abortSignal?: AbortSignal;
@@ -150,6 +171,15 @@ export declare class DefaultAgentManager implements AgentManager {
     onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
     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;
 }
 /**
@@ -169,4 +199,4 @@ export declare class DefaultAgentManager implements AgentManager {
  *   {@link SUPPORTED_PROTOCOL_VERSIONS}, or when the harness's reported
  *   version disagrees with the factory's.
  */
-export declare function createAgentManager(storageRootFolder: string, harnessFactory: HarnessFactory, connectivityResolver?: AgentConnectivityResolver): Promise<AgentManager>;
+export declare function createAgentManager<H extends AgentHarness = AgentHarness>(storageRootFolder: string, harnessFactory: HarnessFactory<H>, connectivityResolver?: AgentConnectivityResolver): Promise<AgentManager<H>>;

package/dist/agent-manager.js

@@ -157,7 +157,7 @@ export class DefaultAgentManager {
         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, projectRoot, config, 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.identityStore, this.router, agentSlice, { telemetry: this.telemetryBus, log: this.logBus }, this.clock, this.agentIdGenerator);
         this.agents.set(agentId, agent);
         this.telemetryBus.emit({
             type: 'agent-created',
@@ -235,6 +235,20 @@ export class DefaultAgentManager {
         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);

package/dist/agent.d.ts

@@ -5,6 +5,7 @@ import { type ChatSession } from './chat-session.js';
 import type { McpServerInfo } from './mcp-config.js';
 import { type JSONWebToken, type LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
 import type { AgentConnectivityResolver } from './agent-connectivity-resolver.js';
+import type { AgentIdentityStore } from './internal/agent-identity-store.js';
 import type { TelemetryRouter, TelemetrySlice } from './internal/telemetry-router.js';
 import type { TelemetryBus, TelemetryEventCallback } from './types/telemetry-events.js';
 /**
@@ -20,6 +21,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. */
@@ -106,6 +111,7 @@ export declare class DefaultAgent implements Agent {
     private orgConnection;
     private orgJwt;
     private readonly agentConnectivityResolver;
+    private readonly identityStore;
     private readonly sessions;
     private readonly sessionSliceUnregisters;
     private readonly router;
@@ -125,11 +131,13 @@ export declare class DefaultAgent implements Agent {
      * @param orgConnection - Authenticated org connection carrying identity and env inference.
      * @param orgJwt - Self-refreshing JWT for the resolved org (used for MCP auth injection).
      * @param agentConnectivityResolver - Used to re-resolve org connectivity when the org or model changes.
+     * @param identityStore - SDK-owned persistence for the `{ agentId, projectRoot, AgentConfig }` triple. The agent
+     *     calls `write()` on a successful `updateAgentConfig` so disk state and in-memory state stay in lockstep.
      * @param router - Telemetry router used to obtain session slices when sessions are created.
      * @param inbound - Router slice delivering harness events routed to this agent (non-session-scoped).
      * @param parent - Manager's bus pair; this agent forwards its events upward into them.
      */
-    constructor(harness: AgentHarness, agentId: string, projectRoot: string, config: AgentConfig, llmGatewayClient: LLMGatewayClient, orgConnection: OrgConnection, orgJwt: JSONWebToken, agentConnectivityResolver: AgentConnectivityResolver, router: TelemetryRouter, inbound: TelemetrySlice, parent: AgentParentBuses, clock?: Clock, idGenerator?: UniqueIDGenerator);
+    constructor(harness: AgentHarness, agentId: string, projectRoot: string, config: AgentConfig, llmGatewayClient: LLMGatewayClient, orgConnection: OrgConnection, orgJwt: JSONWebToken, agentConnectivityResolver: AgentConnectivityResolver, identityStore: AgentIdentityStore, router: TelemetryRouter, inbound: TelemetrySlice, parent: AgentParentBuses, clock?: Clock, idGenerator?: UniqueIDGenerator);
     /**
      * @requirements
      * - MUST return the agent's ID.
@@ -150,7 +158,9 @@ export declare class DefaultAgent implements Agent {
      * - MUST guarantee that the `agentId` remains unchanged during the merge.
      * - MUST destroy the existing agent in the harness by delegating to `this.harness.destroyAgent(this.getId())`.
      * - MUST recreate the agent in the harness with the newly merged configuration by delegating to `this.harness.createAgent(...)`.
-     * - MUST preserve the previous in-memory config state if recreation fails.
+     * - MUST persist the merged config via `this.identityStore.write(...)` after the harness recreate succeeds and
+     *   before the in-memory swaps, so a write failure rolls back through the same catch path as a recreate failure.
+     * - MUST preserve the previous in-memory config state if recreation or persistence fails.
      */
     updateAgentConfig(config?: AgentConfig, options?: {
         abortSignal?: AbortSignal;

package/dist/agent.js

@@ -20,6 +20,7 @@ export class DefaultAgent {
     orgConnection;
     orgJwt;
     agentConnectivityResolver;
+    identityStore;
     sessions = new Map();
     sessionSliceUnregisters = new Map();
     router;
@@ -39,11 +40,13 @@ export class DefaultAgent {
      * @param orgConnection - Authenticated org connection carrying identity and env inference.
      * @param orgJwt - Self-refreshing JWT for the resolved org (used for MCP auth injection).
      * @param agentConnectivityResolver - Used to re-resolve org connectivity when the org or model changes.
+     * @param identityStore - SDK-owned persistence for the `{ agentId, projectRoot, AgentConfig }` triple. The agent
+     *     calls `write()` on a successful `updateAgentConfig` so disk state and in-memory state stay in lockstep.
      * @param router - Telemetry router used to obtain session slices when sessions are created.
      * @param inbound - Router slice delivering harness events routed to this agent (non-session-scoped).
      * @param parent - Manager's bus pair; this agent forwards its events upward into them.
      */
-    constructor(harness, agentId, projectRoot, config, llmGatewayClient, orgConnection, orgJwt, agentConnectivityResolver, router, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
+    constructor(harness, agentId, projectRoot, config, llmGatewayClient, orgConnection, orgJwt, agentConnectivityResolver, identityStore, router, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
         this.harness = harness;
         this.agentId = agentId;
         this.projectRoot = projectRoot;
@@ -52,6 +55,7 @@ export class DefaultAgent {
         this.orgConnection = orgConnection;
         this.orgJwt = orgJwt;
         this.agentConnectivityResolver = agentConnectivityResolver;
+        this.identityStore = identityStore;
         this.router = router;
         this.clock = clock;
         this.idGenerator = idGenerator;
@@ -93,7 +97,9 @@ export class DefaultAgent {
      * - MUST guarantee that the `agentId` remains unchanged during the merge.
      * - MUST destroy the existing agent in the harness by delegating to `this.harness.destroyAgent(this.getId())`.
      * - MUST recreate the agent in the harness with the newly merged configuration by delegating to `this.harness.createAgent(...)`.
-     * - MUST preserve the previous in-memory config state if recreation fails.
+     * - MUST persist the merged config via `this.identityStore.write(...)` after the harness recreate succeeds and
+     *   before the in-memory swaps, so a write failure rolls back through the same catch path as a recreate failure.
+     * - MUST preserve the previous in-memory config state if recreation or persistence fails.
      */
     async updateAgentConfig(config = {}, options) {
         this.assertNotDisposed();
@@ -121,6 +127,10 @@ export class DefaultAgent {
         await this.harness.destroyAgent(this.agentId);
         try {
             await this.harness.createAgent(this.agentId, this.projectRoot, nextClient, toHarnessConfig(nextConfig, nextOrgJwt), options);
+            // Persist before the in-memory swaps so a write failure flows through the same
+            // catch block as a recreate failure: the rollback restores the harness with
+            // previousConfig and disk state remains the pre-update record.
+            await this.identityStore.write(this.agentId, this.projectRoot, nextConfig);
             this.config = nextConfig;
             this.llmGatewayClient = nextClient;
             this.orgConnection = nextConnection;
@@ -138,6 +148,12 @@ export class DefaultAgent {
                 if (nextClient === previousClient) {
                     previousClient.setModel(Models.getByName(previousModelName));
                 }
+                // Clear any nextConfig registration left behind by a successful harness recreate
+                // before the rollback createAgent runs. On the harness-recreate-failure path this
+                // is a no-op (the agent was never registered with nextConfig); on the
+                // identityStore.write-failure path it removes the live nextConfig so the rollback
+                // doesn't trip the harness's duplicate-registration guard.
+                await this.harness.destroyAgent(this.agentId);
                 await this.harness.createAgent(this.agentId, this.projectRoot, previousClient, toHarnessConfig(previousConfig, previousOrgJwt));
             }
             catch {

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,7 +4,7 @@ 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';
@@ -12,7 +12,7 @@ export { type AgentManager, type RestoreFailure, createAgentManager } from './ag
 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/mcp-config.d.ts

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

package/dist/types/usage.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -35,28 +35,28 @@
     "LICENSE.txt"
   ],
   "dependencies": {
-    "@salesforce/agentic-common": "0.3.0",
-    "@salesforce/llm-gateway-sdk": "0.3.0"
+    "@salesforce/agentic-common": "0.4.0",
+    "@salesforce/llm-gateway-sdk": "0.4.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-mastra": "0.5.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.6.0",
     "@types/node": "^22.19.17",
-    "@vitest/coverage-istanbul": "^4.1.5",
-    "@vitest/eslint-plugin": "^1.6.16",
-    "eslint": "^10.2.1",
+    "@vitest/coverage-istanbul": "^4.1.7",
+    "@vitest/eslint-plugin": "^1.6.17",
+    "eslint": "^10.4.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-n": "^18.0.1",
     "globals": "^17.6.0",
-    "lint-staged": "^17.0.4",
+    "lint-staged": "^17.0.5",
     "prettier": "^3.8.3",
     "rimraf": "^6.1.3",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.3",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.1",
-    "vitest": "^4.1.5"
+    "typescript-eslint": "^8.59.4",
+    "vitest": "^4.1.7"
   },
   "engines": {
     "node": ">=22.19.0"