@oobe-protocol-labs/sap-mcp-server 0.9.16 → 0.9.20

package/dist/session/session-types.d.ts

@@ -1,9 +1,25 @@
 /**
- * Session type definitions
+ * @name session/session-types
+ * @description Type definitions for session creation requests, validation results, and session updates.
+ *
+ * @flow
+ *   1. `CreateSessionRequest` is used by session creation MCP tools.
+ *   2. `SessionValidationResult` is returned by session validation functions.
+ *   3. `SessionUpdate` is used by session mutation operations.
+ *
+ * @module session/session-types
  */
 import type { SapAgentSession, SapPermission } from '../core/types.js';
 /**
- * Session creation request
+ * @name CreateSessionRequest
+ * @description Request payload for creating a new agent session.
+ *
+ * @property agentId          — Unique identifier for the agent.
+ * @property permissions      — Array of permissions to grant the session.
+ * @property spendingLimits   — Spending limits for per-transaction, per-day, and per-session SOL amounts.
+ * @property expiresInSeconds — Optional session validity duration in seconds.
+ *
+ * @usedBy Session creation MCP tools, `session/index.ts`
  */
 export interface CreateSessionRequest {
     agentId: string;
@@ -16,7 +32,14 @@ export interface CreateSessionRequest {
     expiresInSeconds?: number;
 }
 /**
- * Session validation result
+ * @name SessionValidationResult
+ * @description Result of validating a session for a requested action.
+ *
+ * @property valid   — Whether the session passed validation.
+ * @property session — The validated session object (present when valid).
+ * @property error   — Error explanation (present when invalid).
+ *
+ * @usedBy Session validation functions, `session/index.ts`
  */
 export interface SessionValidationResult {
     valid: boolean;
@@ -24,7 +47,13 @@ export interface SessionValidationResult {
     error?: string;
 }
 /**
- * Session update
+ * @name SessionUpdate
+ * @description Partial update payload for modifying an existing session.
+ *
+ * @property remainingSessionSol — Optional new remaining session balance in SOL.
+ * @property permissions         — Optional new array of permissions.
+ *
+ * @usedBy Session mutation MCP tools, `session/index.ts`
  */
 export interface SessionUpdate {
     remainingSessionSol?: number;

package/dist/session/session-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-types.d.ts","sourceRoot":"","sources":["../../src/session/session-types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,cAAc,EAAE;QACd,oBAAoB,EAAE,MAAM,CAAC;QAC7B,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;CAC/B"}
+{"version":3,"file":"session-types.d.ts","sourceRoot":"","sources":["../../src/session/session-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,cAAc,EAAE;QACd,oBAAoB,EAAE,MAAM,CAAC;QAC7B,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;CAC/B"}

package/dist/session/session-types.js

@@ -1,5 +1,13 @@
 /**
- * Session type definitions
+ * @name session/session-types
+ * @description Type definitions for session creation requests, validation results, and session updates.
+ *
+ * @flow
+ *   1. `CreateSessionRequest` is used by session creation MCP tools.
+ *   2. `SessionValidationResult` is returned by session validation functions.
+ *   3. `SessionUpdate` is used by session mutation operations.
+ *
+ * @module session/session-types
  */
 export {};
 //# sourceMappingURL=session-types.js.map

package/dist/session/session-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-types.js","sourceRoot":"","sources":["../../src/session/session-types.ts"],"names":[],"mappings":"AAAA;;GAEG"}
+{"version":3,"file":"session-types.js","sourceRoot":"","sources":["../../src/session/session-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/signer/index.d.ts

@@ -1,5 +1,11 @@
 /**
- * Signer module barrel export
+ * @name signer/index
+ * @description Barrel export for the SAP MCP signer module.
+ *
+ * Re-exports signer type definitions, keypair loading functions, local and external
+ * signer factories, and the signer resolver.
+ *
+ * @module signer/index
  */
 export type { Signer, SignerMode, SignerConfig, SignerResult, } from './signer-types.js';
 export { loadKeypairFromFile, loadKeypairFromEnv } from './load-keypair.js';

package/dist/signer/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/signer/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACV,MAAM,EACN,UAAU,EACV,YAAY,EACZ,YAAY,GACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/signer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EACV,MAAM,EACN,UAAU,EACV,YAAY,EACZ,YAAY,GACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/signer/index.js

@@ -1,5 +1,11 @@
 /**
- * Signer module barrel export
+ * @name signer/index
+ * @description Barrel export for the SAP MCP signer module.
+ *
+ * Re-exports signer type definitions, keypair loading functions, local and external
+ * signer factories, and the signer resolver.
+ *
+ * @module signer/index
  */
 export { loadKeypairFromFile, loadKeypairFromEnv } from './load-keypair.js';
 export { createLocalKeypairSigner } from './local-keypair-signer.js';

package/dist/signer/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/signer/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/signer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/signer/load-keypair.d.ts

@@ -1,15 +1,36 @@
 /**
- * Load keypair from file
+ * @name signer/load-keypair
+ * @description Loads Solana keypairs from filesystem or environment variables.
  *
- * WARNING: Only use in local-dev-keypair mode. NEVER in production.
+ * WARNING: Only use in `local-dev-keypair` mode. NEVER in production.
+ *
+ * @flow
+ *   1. `loadKeypairFromFile` reads a JSON keypair array from disk and constructs a `Keypair`.
+ *   2. `loadKeypairFromEnv` reads a base58-encoded secret key from an environment variable.
+ *
+ * @module signer/load-keypair
  */
 import { Keypair } from '@solana/web3.js';
 /**
- * Load keypair from JSON file
+ * @name loadKeypairFromFile
+ * @description Loads a Solana keypair from a JSON file on disk.
+ *
+ * @param walletPath — Filesystem path to the keypair JSON file (array of 64 bytes).
+ * @returns A Solana `Keypair` constructed from the secret key.
+ * @throws `SignerError` if the file cannot be read or parsed.
+ *
+ * @usedBy `local-keypair-signer.ts:createLocalKeypairSigner`, `sap-client-manager.ts:SapClientManager.initialize`
  */
 export declare function loadKeypairFromFile(walletPath: string): Keypair;
 /**
- * Load keypair from environment variable (base58 encoded)
+ * @name loadKeypairFromEnv
+ * @description Loads a Solana keypair from a base58-encoded environment variable.
+ *
+ * @param envVar — Name of the environment variable containing the base58-encoded secret key.
+ * @returns A Solana `Keypair` constructed from the decoded secret key.
+ * @throws `SignerError` if the environment variable is not set.
+ *
+ * @usedBy Signer initialization in environments where file-based keypairs are not available.
  */
 export declare function loadKeypairFromEnv(envVar: string): Promise<Keypair>;
 //# sourceMappingURL=load-keypair.d.ts.map

package/dist/signer/load-keypair.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-keypair.d.ts","sourceRoot":"","sources":["../../src/signer/load-keypair.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAK1C;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAW/D;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAczE"}
+{"version":3,"file":"load-keypair.d.ts","sourceRoot":"","sources":["../../src/signer/load-keypair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAK1C;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAW/D;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAczE"}

package/dist/signer/load-keypair.js

@@ -1,14 +1,28 @@
 /**
- * Load keypair from file
+ * @name signer/load-keypair
+ * @description Loads Solana keypairs from filesystem or environment variables.
  *
- * WARNING: Only use in local-dev-keypair mode. NEVER in production.
+ * WARNING: Only use in `local-dev-keypair` mode. NEVER in production.
+ *
+ * @flow
+ *   1. `loadKeypairFromFile` reads a JSON keypair array from disk and constructs a `Keypair`.
+ *   2. `loadKeypairFromEnv` reads a base58-encoded secret key from an environment variable.
+ *
+ * @module signer/load-keypair
  */
 import { Keypair } from '@solana/web3.js';
 import { readFileSync } from 'fs';
 import { logger } from '../core/logger.js';
 import { SignerError } from '../core/errors.js';
 /**
- * Load keypair from JSON file
+ * @name loadKeypairFromFile
+ * @description Loads a Solana keypair from a JSON file on disk.
+ *
+ * @param walletPath — Filesystem path to the keypair JSON file (array of 64 bytes).
+ * @returns A Solana `Keypair` constructed from the secret key.
+ * @throws `SignerError` if the file cannot be read or parsed.
+ *
+ * @usedBy `local-keypair-signer.ts:createLocalKeypairSigner`, `sap-client-manager.ts:SapClientManager.initialize`
  */
 export function loadKeypairFromFile(walletPath) {
     logger.debug('Loading keypair from file', { walletPath: '[REDACTED]' });
@@ -23,7 +37,14 @@ export function loadKeypairFromFile(walletPath) {
     }
 }
 /**
- * Load keypair from environment variable (base58 encoded)
+ * @name loadKeypairFromEnv
+ * @description Loads a Solana keypair from a base58-encoded environment variable.
+ *
+ * @param envVar — Name of the environment variable containing the base58-encoded secret key.
+ * @returns A Solana `Keypair` constructed from the decoded secret key.
+ * @throws `SignerError` if the environment variable is not set.
+ *
+ * @usedBy Signer initialization in environments where file-based keypairs are not available.
  */
 export async function loadKeypairFromEnv(envVar) {
     const secretKeyBase58 = process.env[envVar];

package/dist/signer/load-keypair.js.map

@@ -1 +1 @@
-{"version":3,"file":"load-keypair.js","sourceRoot":"","sources":["../../src/signer/load-keypair.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,MAAM,CAAC,KAAK,CAAC,2BAA2B,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAC;IAExE,IAAI,CAAC;QACH,MAAM,eAAe,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAC1D,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC;QAC/D,OAAO,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,wBAAwB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAClD,MAAM,IAAI,WAAW,CAAC,mCAAmC,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAc;IACrD,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAE5C,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,MAAM,IAAI,WAAW,CAAC,wBAAwB,MAAM,UAAU,CAAC,CAAC;IAClE,CAAC;IAED,0CAA0C;IAC1C,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC;IAExE,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAE9H,OAAO,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;AAC1C,CAAC"}
+{"version":3,"file":"load-keypair.js","sourceRoot":"","sources":["../../src/signer/load-keypair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,MAAM,CAAC,KAAK,CAAC,2BAA2B,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAC;IAExE,IAAI,CAAC;QACH,MAAM,eAAe,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAC1D,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC;QAC/D,OAAO,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,wBAAwB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAClD,MAAM,IAAI,WAAW,CAAC,mCAAmC,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAc;IACrD,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAE5C,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,MAAM,IAAI,WAAW,CAAC,wBAAwB,MAAM,UAAU,CAAC,CAAC;IAClE,CAAC;IAED,0CAA0C;IAC1C,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC;IAExE,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAE9H,OAAO,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;AAC1C,CAAC"}

package/dist/signer/local-keypair-signer.d.ts

@@ -1,13 +1,27 @@
 /**
- * Local keypair signer.
+ * @name signer/local-keypair-signer
+ * @description Local hot-key signer for development and local-dev-keypair mode.
  *
  * WARNING: This is a local hot-key signer. The hosted SAP MCP server never
  * receives keypair bytes, but production custody should prefer an external
  * signer, hardware wallet, delegated session, or a tightly capped profile.
+ *
+ * @flow
+ *   1. `createLocalKeypairSigner` loads a keypair from file via `loadKeypairFromFile`.
+ *   2. Returns a `Signer` object with `publicKey`, `signTransaction`, and `signAllTransactions`
+ *      that sign transactions locally using the loaded keypair.
+ *
+ * @module signer/local-keypair-signer
  */
 import type { Signer } from './signer-types.js';
 /**
- * Create local keypair signer
+ * @name createLocalKeypairSigner
+ * @description Creates a local `Signer` backed by a keypair loaded from disk.
+ *
+ * @param walletPath — Filesystem path to the keypair JSON file.
+ * @returns A `Signer` implementation that signs `Transaction` and `VersionedTransaction` objects locally.
+ *
+ * @usedBy `signer-resolver.ts:resolveSigner` when mode is `local-keypair`.
  */
 export declare function createLocalKeypairSigner(walletPath: string): Signer;
 //# sourceMappingURL=local-keypair-signer.d.ts.map

package/dist/signer/local-keypair-signer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-keypair-signer.d.ts","sourceRoot":"","sources":["../../src/signer/local-keypair-signer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAoCnE"}
+{"version":3,"file":"local-keypair-signer.d.ts","sourceRoot":"","sources":["../../src/signer/local-keypair-signer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAoCnE"}

package/dist/signer/local-keypair-signer.js

@@ -1,15 +1,29 @@
 /**
- * Local keypair signer.
+ * @name signer/local-keypair-signer
+ * @description Local hot-key signer for development and local-dev-keypair mode.
  *
  * WARNING: This is a local hot-key signer. The hosted SAP MCP server never
  * receives keypair bytes, but production custody should prefer an external
  * signer, hardware wallet, delegated session, or a tightly capped profile.
+ *
+ * @flow
+ *   1. `createLocalKeypairSigner` loads a keypair from file via `loadKeypairFromFile`.
+ *   2. Returns a `Signer` object with `publicKey`, `signTransaction`, and `signAllTransactions`
+ *      that sign transactions locally using the loaded keypair.
+ *
+ * @module signer/local-keypair-signer
  */
 import { Transaction, VersionedTransaction } from '@solana/web3.js';
 import { logger } from '../core/logger.js';
 import { loadKeypairFromFile } from './load-keypair.js';
 /**
- * Create local keypair signer
+ * @name createLocalKeypairSigner
+ * @description Creates a local `Signer` backed by a keypair loaded from disk.
+ *
+ * @param walletPath — Filesystem path to the keypair JSON file.
+ * @returns A `Signer` implementation that signs `Transaction` and `VersionedTransaction` objects locally.
+ *
+ * @usedBy `signer-resolver.ts:resolveSigner` when mode is `local-keypair`.
  */
 export function createLocalKeypairSigner(walletPath) {
     logger.info('Creating local keypair signer', { walletPath: '[REDACTED]' });

package/dist/signer/local-keypair-signer.js.map

@@ -1 +1 @@
-{"version":3,"file":"local-keypair-signer.js","sourceRoot":"","sources":["../../src/signer/local-keypair-signer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGxD;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,UAAkB;IACzD,MAAM,CAAC,IAAI,CAAC,+BAA+B,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAC;IAE3E,MAAM,OAAO,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAEhD,MAAM,CAAC,IAAI,CAAC,8BAA8B,EAAE;QAC1C,OAAO,EAAE,YAAY;QACrB,cAAc,EAAE,gCAAgC;QAChD,cAAc,EAAE,qFAAqF;KACtG,CAAC,CAAC;IAEH,OAAO;QACL,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,eAAe,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;YAC5B,IAAI,EAAE,YAAY,oBAAoB,EAAE,CAAC;gBACvC,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;YACrB,CAAC;iBAAM,IAAI,EAAE,YAAY,WAAW,EAAE,CAAC;gBACrC,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAC1B,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;YAClD,CAAC;YACD,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,mBAAmB,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACjC,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;gBACrB,IAAI,EAAE,YAAY,oBAAoB,EAAE,CAAC;oBACvC,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;gBACrB,CAAC;qBAAM,IAAI,EAAE,YAAY,WAAW,EAAE,CAAC;oBACrC,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;gBAC1B,CAAC;qBAAM,CAAC;oBACN,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;gBAClD,CAAC;YACH,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"local-keypair-signer.js","sourceRoot":"","sources":["../../src/signer/local-keypair-signer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGxD;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,UAAkB;IACzD,MAAM,CAAC,IAAI,CAAC,+BAA+B,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAC;IAE3E,MAAM,OAAO,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAEhD,MAAM,CAAC,IAAI,CAAC,8BAA8B,EAAE;QAC1C,OAAO,EAAE,YAAY;QACrB,cAAc,EAAE,gCAAgC;QAChD,cAAc,EAAE,qFAAqF;KACtG,CAAC,CAAC;IAEH,OAAO;QACL,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,eAAe,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;YAC5B,IAAI,EAAE,YAAY,oBAAoB,EAAE,CAAC;gBACvC,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;YACrB,CAAC;iBAAM,IAAI,EAAE,YAAY,WAAW,EAAE,CAAC;gBACrC,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAC1B,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;YAClD,CAAC;YACD,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,mBAAmB,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACjC,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;gBACrB,IAAI,EAAE,YAAY,oBAAoB,EAAE,CAAC;oBACvC,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;gBACrB,CAAC;qBAAM,IAAI,EAAE,YAAY,WAAW,EAAE,CAAC;oBACrC,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;gBAC1B,CAAC;qBAAM,CAAC;oBACN,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;gBAClD,CAAC;YACH,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/signer/signer-resolver.d.ts

@@ -1,10 +1,27 @@
 /**
- * Resolve signer based on MCP mode
+ * @name signer/signer-resolver
+ * @description Resolves the appropriate signer implementation based on SAP MCP configuration mode.
+ *
+ * @flow
+ *   1. `resolveSigner` reads the config mode and determines the signer mode via `getSignerModeFromConfig`.
+ *   2. For `local-keypair` mode, creates a local keypair signer from `walletPath`.
+ *   3. For `external` mode, creates an external signer from `externalSignerUrl`.
+ *   4. For `none` mode (readonly), returns a result with no signer.
+ *   5. For `delegated` mode, throws — delegated signers are session-bound and resolved at runtime.
+ *
+ * @module signer/signer-resolver
  */
 import type { SapMcpConfig } from '../core/types.js';
 import type { SignerResult } from './signer-types.js';
 /**
- * Resolve signer based on configuration
+ * @name resolveSigner
+ * @description Resolves and creates a signer instance based on the SAP MCP configuration.
+ *
+ * @param config — SAP MCP configuration with mode, wallet path, and external signer URL.
+ * @returns A `SignerResult` containing the signer, mode, and optional public key.
+ * @throws `SignerError` if required config is missing for the resolved mode, or if the mode is `delegated`.
+ *
+ * @usedBy `create-server.ts:createSapMcpServer`.
  */
 export declare function resolveSigner(config: SapMcpConfig): Promise<SignerResult>;
 //# sourceMappingURL=signer-resolver.d.ts.map

package/dist/signer/signer-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signer-resolver.d.ts","sourceRoot":"","sources":["../../src/signer/signer-resolver.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD;;GAEG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAuC/E"}
+{"version":3,"file":"signer-resolver.d.ts","sourceRoot":"","sources":["../../src/signer/signer-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAuC/E"}

package/dist/signer/signer-resolver.js

@@ -1,12 +1,29 @@
 /**
- * Resolve signer based on MCP mode
+ * @name signer/signer-resolver
+ * @description Resolves the appropriate signer implementation based on SAP MCP configuration mode.
+ *
+ * @flow
+ *   1. `resolveSigner` reads the config mode and determines the signer mode via `getSignerModeFromConfig`.
+ *   2. For `local-keypair` mode, creates a local keypair signer from `walletPath`.
+ *   3. For `external` mode, creates an external signer from `externalSignerUrl`.
+ *   4. For `none` mode (readonly), returns a result with no signer.
+ *   5. For `delegated` mode, throws — delegated signers are session-bound and resolved at runtime.
+ *
+ * @module signer/signer-resolver
  */
 import { logger } from '../core/logger.js';
 import { SignerError } from '../core/errors.js';
 import { createLocalKeypairSigner } from './local-keypair-signer.js';
 import { createExternalSigner } from './external-signer.js';
 /**
- * Resolve signer based on configuration
+ * @name resolveSigner
+ * @description Resolves and creates a signer instance based on the SAP MCP configuration.
+ *
+ * @param config — SAP MCP configuration with mode, wallet path, and external signer URL.
+ * @returns A `SignerResult` containing the signer, mode, and optional public key.
+ * @throws `SignerError` if required config is missing for the resolved mode, or if the mode is `delegated`.
+ *
+ * @usedBy `create-server.ts:createSapMcpServer`.
  */
 export async function resolveSigner(config) {
     const mode = getSignerModeFromConfig(config);
@@ -43,7 +60,13 @@ export async function resolveSigner(config) {
     }
 }
 /**
- * Map resolved MCP config to signer mode.
+ * @name getSignerModeFromConfig
+ * @description Maps the SAP MCP config mode to a `SapSignerMode` value.
+ *
+ * @param config — SAP MCP configuration.
+ * @returns The resolved signer mode: `none`, `local-keypair`, `external`, or `delegated`.
+ *
+ * @internal
  */
 function getSignerModeFromConfig(config) {
     switch (config.mode) {

package/dist/signer/signer-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"signer-resolver.js","sourceRoot":"","sources":["../../src/signer/signer-resolver.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAoB;IACtD,MAAM,IAAI,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAE7C,MAAM,CAAC,KAAK,CAAC,kBAAkB,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IAE7E,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM;YACT,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAE1B,KAAK,eAAe,CAAC,CAAC,CAAC;YACrB,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;gBACvB,MAAM,IAAI,WAAW,CAAC,qDAAqD,CAAC,CAAC;YAC/E,CAAC;YACD,MAAM,WAAW,GAAG,wBAAwB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YAChE,OAAO;gBACL,IAAI,EAAE,eAAe;gBACrB,MAAM,EAAE,WAAW;gBACnB,SAAS,EAAE,WAAW,CAAC,SAAS,CAAC,QAAQ,EAAE;aAC5C,CAAC;QACJ,CAAC;QAED,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;gBAC9B,MAAM,IAAI,WAAW,CAAC,2DAA2D,CAAC,CAAC;YACrF,CAAC;YACD,MAAM,cAAc,GAAG,MAAM,oBAAoB,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;YAC5E,OAAO;gBACL,IAAI,EAAE,UAAU;gBAChB,MAAM,EAAE,cAAc;gBACtB,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC,QAAQ,EAAE;aAC/C,CAAC;QACJ,CAAC;QAED,KAAK,WAAW;YACd,MAAM,IAAI,WAAW,CAAC,gGAAgG,CAAC,CAAC;QAE1H;YACE,MAAM,IAAI,WAAW,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,uBAAuB,CAAC,MAAoB;IACnD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,UAAU;YACb,OAAO,MAAM,CAAC;QAChB,KAAK,YAAY;YACf,IAAI,MAAM,CAAC,iBAAiB,EAAE,CAAC;gBAC7B,OAAO,UAAU,CAAC;YACpB,CAAC;YACD,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;gBACtB,OAAO,eAAe,CAAC;YACzB,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,KAAK,mBAAmB;YACtB,OAAO,eAAe,CAAC;QACzB,KAAK,iBAAiB;YACpB,OAAO,UAAU,CAAC;QACpB,KAAK,mBAAmB;YACtB,OAAO,WAAW,CAAC;QACrB;YACE,OAAO,MAAM,CAAC;IAClB,CAAC;AACH,CAAC"}
+{"version":3,"file":"signer-resolver.js","sourceRoot":"","sources":["../../src/signer/signer-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAoB;IACtD,MAAM,IAAI,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAE7C,MAAM,CAAC,KAAK,CAAC,kBAAkB,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IAE7E,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM;YACT,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAE1B,KAAK,eAAe,CAAC,CAAC,CAAC;YACrB,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;gBACvB,MAAM,IAAI,WAAW,CAAC,qDAAqD,CAAC,CAAC;YAC/E,CAAC;YACD,MAAM,WAAW,GAAG,wBAAwB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YAChE,OAAO;gBACL,IAAI,EAAE,eAAe;gBACrB,MAAM,EAAE,WAAW;gBACnB,SAAS,EAAE,WAAW,CAAC,SAAS,CAAC,QAAQ,EAAE;aAC5C,CAAC;QACJ,CAAC;QAED,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;gBAC9B,MAAM,IAAI,WAAW,CAAC,2DAA2D,CAAC,CAAC;YACrF,CAAC;YACD,MAAM,cAAc,GAAG,MAAM,oBAAoB,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;YAC5E,OAAO;gBACL,IAAI,EAAE,UAAU;gBAChB,MAAM,EAAE,cAAc;gBACtB,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC,QAAQ,EAAE;aAC/C,CAAC;QACJ,CAAC;QAED,KAAK,WAAW;YACd,MAAM,IAAI,WAAW,CAAC,gGAAgG,CAAC,CAAC;QAE1H;YACE,MAAM,IAAI,WAAW,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,uBAAuB,CAAC,MAAoB;IACnD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,UAAU;YACb,OAAO,MAAM,CAAC;QAChB,KAAK,YAAY;YACf,IAAI,MAAM,CAAC,iBAAiB,EAAE,CAAC;gBAC7B,OAAO,UAAU,CAAC;YACpB,CAAC;YACD,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;gBACtB,OAAO,eAAe,CAAC;YACzB,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,KAAK,mBAAmB;YACtB,OAAO,eAAe,CAAC;QACzB,KAAK,iBAAiB;YACpB,OAAO,UAAU,CAAC;QACpB,KAAK,mBAAmB;YACtB,OAAO,WAAW,CAAC;QACrB;YACE,OAAO,MAAM,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/signer/signer-types.d.ts

@@ -1,10 +1,29 @@
 /**
- * Signer type definitions
+ * @name signer/signer-types
+ * @description Core type definitions for the SAP MCP signer subsystem.
+ *
+ * Defines the `Signer` interface, signer modes, signer configuration, and the
+ * result of signer resolution. These types flow through the signer resolver,
+ * local keypair signer, and external signer modules.
+ *
+ * @flow
+ *   1. `signer-resolver.ts` uses `SignerResult` to return the resolved signer.
+ *   2. `local-keypair-signer.ts` and `external-signer.ts` implement the `Signer` interface.
+ *   3. `signer/index.ts` re-exports all types for external consumers.
+ *
+ * @module signer/signer-types
  */
 import type { PublicKey, Transaction, VersionedTransaction } from '@solana/web3.js';
 import type { SapAgentSession } from '../core/types.js';
 /**
- * Signer interface
+ * @name Signer
+ * @description Interface for signing Solana transactions in the SAP MCP runtime.
+ *
+ * @property publicKey           — The signer's Solana public key.
+ * @property signTransaction     — Signs a single transaction (legacy or versioned).
+ * @property signAllTransactions — Signs multiple transactions in batch.
+ *
+ * @usedBy `local-keypair-signer.ts`, `external-signer.ts`, `core/types.ts:SapMcpContext`
  */
 export interface Signer {
     publicKey: PublicKey;
@@ -12,11 +31,27 @@ export interface Signer {
     signAllTransactions: <T extends Transaction | VersionedTransaction>(txs: T[]) => Promise<T[]>;
 }
 /**
- * Signer mode
+ * @name SignerMode
+ * @description The operational mode of the signer in the SAP MCP runtime.
+ *
+ * - `none`           — Read-only mode, no signing capability.
+ * - `local-keypair`  — Local hot-key signer loaded from disk.
+ * - `external`       — External signer reached over HTTP.
+ * - `delegated`      — Session-bound delegated signer (resolved per-session).
+ *
+ * @usedBy `SignerConfig.mode`, `SignerResult.mode`, `signer-resolver.ts`
  */
 export type SignerMode = 'none' | 'local-keypair' | 'external' | 'delegated';
 /**
- * Signer configuration
+ * @name SignerConfig
+ * @description Configuration for constructing a signer instance.
+ *
+ * @property mode             — The signer operational mode.
+ * @property walletPath       — Optional filesystem path to a local keypair file.
+ * @property externalSignerUrl — Optional URL for an external signer service.
+ * @property delegatedSession — Optional session for delegated signing.
+ *
+ * @usedBy Signer construction logic across the signer module.
  */
 export interface SignerConfig {
     mode: SignerMode;
@@ -25,7 +60,14 @@ export interface SignerConfig {
     delegatedSession?: SapAgentSession;
 }
 /**
- * Signer result
+ * @name SignerResult
+ * @description Result of resolving a signer from configuration.
+ *
+ * @property signer     — The resolved `Signer` instance (absent when mode is `none`).
+ * @property mode       — The resolved signer mode.
+ * @property publicKey  — Optional base58-encoded public key of the signer.
+ *
+ * @usedBy `signer-resolver.ts:resolveSigner`, `create-server.ts:createSapMcpServer`
  */
 export interface SignerResult {
     signer?: Signer;

package/dist/signer/signer-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signer-types.d.ts","sourceRoot":"","sources":["../../src/signer/signer-types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,eAAe,EAAE,CAAC,CAAC,SAAS,WAAW,GAAG,oBAAoB,EAAE,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACrF,mBAAmB,EAAE,CAAC,CAAC,SAAS,WAAW,GAAG,oBAAoB,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CAC/F;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,eAAe,GAAG,UAAU,GAAG,WAAW,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,eAAe,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"signer-types.d.ts","sourceRoot":"","sources":["../../src/signer/signer-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,WAAW,MAAM;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,eAAe,EAAE,CAAC,CAAC,SAAS,WAAW,GAAG,oBAAoB,EAAE,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACrF,mBAAmB,EAAE,CAAC,CAAC,SAAS,WAAW,GAAG,oBAAoB,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CAC/F;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,eAAe,GAAG,UAAU,GAAG,WAAW,CAAC;AAE7E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,eAAe,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/signer/signer-types.js

@@ -1,5 +1,17 @@
 /**
- * Signer type definitions
+ * @name signer/signer-types
+ * @description Core type definitions for the SAP MCP signer subsystem.
+ *
+ * Defines the `Signer` interface, signer modes, signer configuration, and the
+ * result of signer resolution. These types flow through the signer resolver,
+ * local keypair signer, and external signer modules.
+ *
+ * @flow
+ *   1. `signer-resolver.ts` uses `SignerResult` to return the resolved signer.
+ *   2. `local-keypair-signer.ts` and `external-signer.ts` implement the `Signer` interface.
+ *   3. `signer/index.ts` re-exports all types for external consumers.
+ *
+ * @module signer/signer-types
  */
 export {};
 //# sourceMappingURL=signer-types.js.map

package/dist/signer/signer-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"signer-types.js","sourceRoot":"","sources":["../../src/signer/signer-types.ts"],"names":[],"mappings":"AAAA;;GAEG"}
+{"version":3,"file":"signer-types.js","sourceRoot":"","sources":["../../src/signer/signer-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/tools/agent-start-tool.js

@@ -236,6 +236,18 @@ function buildAgentNextActionPayload(input) {
             forbiddenActions: [...baseForbidden, 'Do not hand-roll PAYMENT-SIGNATURE headers for hosted SAP tools.'],
         });
     }
+    if (containsAny(combined, ['pricing_menu', 'pricing menu', 'accountnotinitialized', 'account not initialized', 'error number: 3012', 'anchor 3012', '3012'])) {
+        return nextAction({
+            classification: 'sap_registry_account_lifecycle',
+            retryable: false,
+            safeToRetryNow: false,
+            paymentCharged: 'no',
+            nextTool: 'sap_protocol_invariants',
+            nextAction: 'Do not repair the runtime and do not retry the same write. Inspect SAP protocol invariants and the agent registration/update lifecycle; the registry account set is missing a required on-chain PDA such as pricing_menu.',
+            userMessage: 'The local bridge is not the problem. The SAP registry write reached the on-chain program, but a required registry account such as pricing_menu is not initialized for this agent lifecycle.',
+            forbiddenActions: [...baseForbidden, 'Do not classify Anchor 3012/pricing_menu as missing sap_payments.', 'Do not retry paid or local writes until the account lifecycle is fixed or the SDK/server has an initializer path.'],
+        });
+    }
     if (containsAny(combined, ['hosted_local_signer_required', 'local signer required', 'hosted server cannot sign', 'no signer configured'])) {
         return nextAction({
             classification: 'local_signer_route_required',
@@ -475,6 +487,12 @@ function buildAgentStartPayload(context, goal) {
                 required: false,
                 reason: 'Read the machine-readable x402/pay.sh pricing tiers before paid hosted tools or marketplace execution.',
             },
+            {
+                namespace: 'hosted sap',
+                tool: 'sap_estimate_tool_cost',
+                required: false,
+                reason: 'Before any paid tool call, pass the tool name to get the exact tier, estimated USD cost, and recommended maxPriceUsd. Avoids silent cap aborts.',
+            },
             {
                 namespace: 'hosted sap',
                 tool: 'sap_skills_upgrade_plan',
@@ -536,8 +554,9 @@ function buildAgentStartPayload(context, goal) {
             'For initial orientation, use free exact/base reads first: sap_agent_context, sap_get_agent, sap_get_agent_profile, sap_get_agent_stats, sap_is_agent_active, sap_get_global_state, or sap_list_agents with limit <= 20 and view: compact. Use paid sap_discover_agents or sap_list_all_agents only when the user needs search, enrichment, analytics, or larger pages.',
             'If a capability-filtered SAP agent lookup returns zero rows, retry with query or wallet before saying the agent is absent because secondary indexes can lag AgentAccount rows.',
             'For free reads, call hosted tools directly.',
+            'Before any paid call, verify USDC and SOL balances using free core balance tools: sol_get_balance, spl-token_getBalance, spl-token_getTokenAccounts, or magicblock_balance. Use paid read-premium holdings tools only when the user needs enriched portfolio context. An agent without USDC cannot make paid calls.',
             'For paid/write calls, use sap_payments_call_paid_tool from the local sap_payments bridge when available.',
-            'Before paid calls, use sap_pricing_catalog or the x402 challenge itself as the price source of truth.',
+            'Before paid calls, use sap_estimate_tool_cost to know the exact tier and estimated USD cost of a specific tool, or sap_pricing_catalog for the full tier overview. The x402 challenge itself is the final price source of truth.',
             'For external HTTP x402 agent endpoints discovered through SAP registry metadata, use sap_payments_call_external_x402 instead of hand-rolled HTTP/sign/retry scripts.',
             'If sap_payments is missing, ask the user to run the wizard repair flow and restart the agent runtime.',
             'If hosted sap_register_agent returns hosted_local_signer_required, do not retry the hosted direct write. No x402 payment was charged; call local sap_payments_register_agent with the same registration fields and confirm: true.',