@naylence/agent-sdk 0.3.11 → 0.3.13

package/dist/esm/naylence/agent/base-agent.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Base class for implementing agents.
+ *
+ * {@link BaseAgent} provides the standard implementation of the {@link Agent} protocol
+ * with built-in support for state management, message handling, and task execution.
+ *
+ * @remarks
+ * Extend this class for request-response style agents. For long-running background
+ * work, consider extending {@link BackgroundTaskAgent} instead.
+ *
+ * @module
+ */
 import { type FameDeliveryContext, type FameEnvelope, type FameMessageResponse } from '@naylence/core';
 import { FameAddress, FameFabric, NodeLike, Registerable, type StorageProvider } from '@naylence/runtime';
 import { z } from 'zod';
@@ -5,6 +17,7 @@ import { Agent, type Payload } from './agent.js';
 import { type AgentCard, Task, type TaskArtifactUpdateEvent, TaskIdParams, TaskPushNotificationConfig, TaskQueryParams, TaskSendParams, TaskStatusUpdateEvent } from './a2a-types.js';
 import { TERMINAL_TASK_STATES } from './task-states.js';
 export { TERMINAL_TASK_STATES };
+/** @internal */
 declare class StateContext<StateT extends BaseAgentState> {
     private readonly acquireLock;
     private readonly loadState;
@@ -133,16 +146,73 @@ export declare class BaseAgentState {
      */
     clone(): this;
 }
+/** @internal */
 type StateModelCtor<T extends BaseAgentState> = new () => T;
+/**
+ * Configuration options for {@link BaseAgent}.
+ */
 export interface BaseAgentOptions<StateT extends BaseAgentState> {
+    /** State model class for typed state management. */
     stateModel?: StateModelCtor<StateT> | null;
+    /** Namespace for state storage. Defaults to agent name. */
     stateNamespace?: string | null;
+    /** Key under which state is stored. Defaults to 'state'. */
     stateKey?: string;
+    /** Factory function to create initial state. */
     stateFactory?: (() => StateT) | null;
+    /** Custom storage provider for state persistence. */
     storageProvider?: StorageProvider | null;
 }
+/**
+ * Standard implementation of the {@link Agent} protocol.
+ *
+ * Provides built-in state management, message handling, and task lifecycle support.
+ * Extend this class and override {@link BaseAgent.runTask} to implement your agent logic.
+ *
+ * @remarks
+ * BaseAgent handles:
+ * - JSON-RPC message routing
+ * - State persistence with optional Zod validation
+ * - Task creation from runTask results
+ * - Graceful shutdown via SIGINT/SIGTERM
+ *
+ * For background/async task execution, use {@link BackgroundTaskAgent} instead.
+ *
+ * @example
+ * ```typescript
+ * import { BaseAgent, Payload, BaseAgentState } from '@naylence/agent-sdk';
+ * import { z } from 'zod';
+ *
+ * const CounterSchema = z.object({ count: z.number() });
+ *
+ * class CounterState extends BaseAgentState {
+ *   static readonly schema = CounterSchema;
+ *   count = 0;
+ * }
+ *
+ * class CounterAgent extends BaseAgent<CounterState> {
+ *   static STATE_MODEL = CounterState;
+ *
+ *   async runTask(payload: Payload): Promise<number> {
+ *     return await this.withState(async (state) => {
+ *       state.count += 1;
+ *       return state.count;
+ *     });
+ *   }
+ * }
+ *
+ * const agent = new CounterAgent('counter');
+ * await agent.serve('fame://counter');
+ * ```
+ *
+ * @typeParam StateT - The state model type, defaults to {@link BaseAgentState}.
+ */
 export declare class BaseAgent<StateT extends BaseAgentState = BaseAgentState> extends Agent implements Registerable {
     #private;
+    /**
+     * Default state model class. Override in subclasses to set state type.
+     * @internal
+     */
     static STATE_MODEL: StateModelCtor<BaseAgentState> | null;
     private _name;
     private _address;
@@ -158,12 +228,29 @@ export declare class BaseAgent<StateT extends BaseAgentState = BaseAgentState> e
     private _fabric;
     private _stateStore;
     private _stateCache;
+    /**
+     * Creates a new BaseAgent.
+     *
+     * @param name - Agent name. Defaults to snake_case of the class name.
+     * @param options - Configuration options for state and storage.
+     */
     constructor(name?: string | null, options?: BaseAgentOptions<StateT>);
+    /**
+     * Capabilities advertised by this agent.
+     * Includes the standard agent capability by default.
+     */
     get capabilities(): string[];
+    /** The agent's name. */
     get name(): string | null;
     get spec(): Record<string, unknown>;
+    /** The address this agent is registered at. */
     get address(): FameAddress | null;
+    /** @internal */
     set address(value: FameAddress | null);
+    /**
+     * Storage provider for state persistence.
+     * @throws Error if no storage provider is available.
+     */
     get storageProvider(): StorageProvider;
     /**
      * Returns the fabric this agent is registered with.
@@ -172,21 +259,74 @@ export declare class BaseAgent<StateT extends BaseAgentState = BaseAgentState> e
      */
     protected get fabric(): FameFabric | null;
     onRegister?(node: NodeLike): Promise<void>;
+    /** @internal */
     protected acquireStateLock(): Promise<() => void>;
+    /** @internal */
     private ensureStateModel;
+    /** @internal */
     private ensureStateStore;
+    /** @internal */
     private defaultStateNamespace;
+    /** @internal */
     protected loadStateInternal(): Promise<StateT>;
+    /** @internal */
     protected saveStateInternal(state: StateT): Promise<void>;
+    /**
+     * State context for lock-protected state access.
+     *
+     * @remarks
+     * Prefer using {@link BaseAgent.withState} for simpler access patterns.
+     *
+     * @throws Error if no state model is configured.
+     */
     get state(): StateContext<StateT>;
+    /**
+     * Executes a callback with exclusive access to the agent's state.
+     *
+     * State changes are automatically persisted after the callback completes.
+     *
+     * @param callback - Function receiving the current state.
+     * @returns The callback's return value.
+     *
+     * @example
+     * ```typescript
+     * const count = await this.withState(async (state) => {
+     *   state.count += 1;
+     *   return state.count;
+     * });
+     * ```
+     */
     withState<T>(callback: (state: StateT) => Promise<T>): Promise<T>;
+    /**
+     * Retrieves a snapshot of the current state.
+     *
+     * @remarks
+     * Returns a point-in-time copy. For modifications, use {@link BaseAgent.withState}.
+     */
     getState(): Promise<StateT>;
+    /**
+     * Deletes all persisted state for this agent.
+     */
     clearState(): Promise<void>;
+    /** @internal */
     private static isRpcRequest;
+    /** @internal */
     handleMessage(envelope: FameEnvelope, _context?: FameDeliveryContext): Promise<FameMessageResponse | AsyncIterable<FameMessageResponse> | null | void>;
+    /**
+     * Override to handle non-RPC messages.
+     *
+     * Called when the agent receives a message that is not a JSON-RPC request.
+     * The default implementation logs a warning and returns null.
+     *
+     * @param message - The decoded message payload.
+     * @returns Optional response to send back.
+     */
     onMessage(message: unknown): Promise<FameMessageResponse | null | void>;
+    /** @internal */
     private handleRpcMessage;
+    /** @internal */
     private startSubscriptionTask;
+    /** @internal */
     private streamSendSubscribe;
     authenticate(_credentials: unknown): boolean;
     registerPushEndpoint(_config: TaskPushNotificationConfig): Promise<TaskPushNotificationConfig>;
@@ -196,7 +336,38 @@ export declare class BaseAgent<StateT extends BaseAgentState = BaseAgentState> e
     cancelTask(_params: TaskIdParams): Promise<Task>;
     getAgentCard(): Promise<AgentCard>;
     getTaskStatus(_params: TaskQueryParams): Promise<Task>;
+    /**
+     * Override to implement task execution logic.
+     *
+     * This is the primary extension point for agent behavior. Return the task result
+     * or throw an error to fail the task.
+     *
+     * @param _payload - The task payload.
+     * @param _id - Optional task identifier.
+     * @returns The task result.
+     * @throws UnsupportedOperationException if not overridden.
+     *
+     * @example
+     * ```typescript
+     * async runTask(payload: Payload): Promise<string> {
+     *   const input = typeof payload === 'string' ? payload : '';
+     *   return `Hello, ${input}!`;
+     * }
+     * ```
+     */
     runTask(_payload: Payload, _id: string | null): Promise<unknown>;
+    /**
+     * Initiates a task and returns its status.
+     *
+     * @remarks
+     * If you override {@link BaseAgent.runTask}, this method automatically
+     * creates a Task from the result. Override this method for custom
+     * task lifecycle management.
+     *
+     * @param params - Task parameters including message and metadata.
+     * @returns The completed task with result.
+     * @throws Error if neither startTask nor runTask is implemented.
+     */
     startTask(params: TaskSendParams): Promise<Task>;
     aserve(address: FameAddress | string, options?: Parameters<Agent['aserve']>[1]): Promise<void>;
 }

package/dist/esm/naylence/agent/base-agent.js

@@ -4,6 +4,18 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _BaseAgent_instances, _BaseAgent_createTaskFromPayloadResponse;
+/**
+ * Base class for implementing agents.
+ *
+ * {@link BaseAgent} provides the standard implementation of the {@link Agent} protocol
+ * with built-in support for state management, message handling, and task execution.
+ *
+ * @remarks
+ * Extend this class for request-response style agents. For long-running background
+ * work, consider extending {@link BackgroundTaskAgent} instead.
+ *
+ * @module
+ */
 import { AGENT_CAPABILITY, createFameEnvelope, createMessageResponse, } from '@naylence/core';
 import { AsyncLock, FameAddress, FameFabric, generateId, getFabricForNode, getLogger, } from '@naylence/runtime';
 import { z } from 'zod';
@@ -15,6 +27,7 @@ import { decodeFameDataPayload, makeTask } from './util.js';
 import { handleAgentRpcRequest } from './rpc-adapter.js';
 const logger = getLogger('naylence.agent.base_agent');
 export { TERMINAL_TASK_STATES };
+/** @internal */
 class StateContext {
     constructor(acquireLock, loadState, saveState) {
         this.acquireLock = acquireLock;
@@ -246,17 +259,20 @@ export class BaseAgentState {
  * ```
  */
 BaseAgentState.schema = z.object({});
+/** @internal */
 function camelToSnakeCase(name) {
     return name
         .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
         .replace(/([A-Z])([A-Z][a-z])/g, '$1_$2')
         .toLowerCase();
 }
+/** @internal */
 function sanitizeNamespace(ns) {
     const replaced = ns.replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^[._-]+|[._-]+$/g, '');
     const safe = replaced.length > 0 ? replaced : 'ns';
     return safe.slice(0, 120);
 }
+/** @internal */
 async function delay(ms) {
     await new Promise((resolve) => {
         const timeout = globalThis.setTimeout;
@@ -266,19 +282,71 @@ async function delay(ms) {
         timeout(resolve, ms);
     });
 }
+/** @internal */
 function resolveRpcParams(params) {
     if (params && typeof params === 'object') {
         return params;
     }
     return {};
 }
+/** @internal */
 function resolveReplyTarget(explicit, params) {
     const fromParams = params['reply_to'] ??
         params['replyTo'];
     const resolved = explicit ?? fromParams ?? null;
     return resolved === undefined ? null : resolved;
 }
+/**
+ * Standard implementation of the {@link Agent} protocol.
+ *
+ * Provides built-in state management, message handling, and task lifecycle support.
+ * Extend this class and override {@link BaseAgent.runTask} to implement your agent logic.
+ *
+ * @remarks
+ * BaseAgent handles:
+ * - JSON-RPC message routing
+ * - State persistence with optional Zod validation
+ * - Task creation from runTask results
+ * - Graceful shutdown via SIGINT/SIGTERM
+ *
+ * For background/async task execution, use {@link BackgroundTaskAgent} instead.
+ *
+ * @example
+ * ```typescript
+ * import { BaseAgent, Payload, BaseAgentState } from '@naylence/agent-sdk';
+ * import { z } from 'zod';
+ *
+ * const CounterSchema = z.object({ count: z.number() });
+ *
+ * class CounterState extends BaseAgentState {
+ *   static readonly schema = CounterSchema;
+ *   count = 0;
+ * }
+ *
+ * class CounterAgent extends BaseAgent<CounterState> {
+ *   static STATE_MODEL = CounterState;
+ *
+ *   async runTask(payload: Payload): Promise<number> {
+ *     return await this.withState(async (state) => {
+ *       state.count += 1;
+ *       return state.count;
+ *     });
+ *   }
+ * }
+ *
+ * const agent = new CounterAgent('counter');
+ * await agent.serve('fame://counter');
+ * ```
+ *
+ * @typeParam StateT - The state model type, defaults to {@link BaseAgentState}.
+ */
 export class BaseAgent extends Agent {
+    /**
+     * Creates a new BaseAgent.
+     *
+     * @param name - Agent name. Defaults to snake_case of the class name.
+     * @param options - Configuration options for state and storage.
+     */
     constructor(name = null, options = {}) {
         super();
         _BaseAgent_instances.add(this);
@@ -299,9 +367,14 @@ export class BaseAgent extends Agent {
         this._stateKey = options.stateKey ?? 'state';
         this._stateFactory = options.stateFactory ?? null;
     }
+    /**
+     * Capabilities advertised by this agent.
+     * Includes the standard agent capability by default.
+     */
     get capabilities() {
         return [...this._capabilities];
     }
+    /** The agent's name. */
     get name() {
         return this._name;
     }
@@ -310,12 +383,18 @@ export class BaseAgent extends Agent {
             address: this._address?.toString() ?? null,
         };
     }
+    /** The address this agent is registered at. */
     get address() {
         return this._address;
     }
+    /** @internal */
     set address(value) {
         this._address = value;
     }
+    /**
+     * Storage provider for state persistence.
+     * @throws Error if no storage provider is available.
+     */
     get storageProvider() {
         if (!this._storageProvider) {
             if (this._node) {
@@ -340,6 +419,7 @@ export class BaseAgent extends Agent {
         // Look up the fabric from the registry (set by InProcessFameFabric.start())
         this._fabric = getFabricForNode(node) ?? null;
     }
+    /** @internal */
     async acquireStateLock() {
         let acquiredResolve;
         const acquired = new Promise((resolve) => {
@@ -366,12 +446,14 @@ export class BaseAgent extends Agent {
             });
         };
     }
+    /** @internal */
     ensureStateModel() {
         if (this._stateModel) {
             return this._stateModel;
         }
         throw new Error("No state model configured. Provide via Generic, STATE_MODEL, constructor 'stateModel', or 'stateFactory'.");
     }
+    /** @internal */
     async ensureStateStore(modelType) {
         if (this._stateStore) {
             return;
@@ -384,12 +466,14 @@ export class BaseAgent extends Agent {
         const namespace = sanitizeNamespace(namespaceRaw);
         this._stateStore = await provider.getKeyValueStore(modelType, namespace);
     }
+    /** @internal */
     defaultStateNamespace() {
         if (!this._name) {
             throw new Error("Cannot derive default state namespace without agent name. Set 'name' or provide 'stateNamespace'.");
         }
         return `__agent_${this._name}`;
     }
+    /** @internal */
     async loadStateInternal() {
         if (this._stateCache) {
             return this._stateCache;
@@ -419,6 +503,7 @@ export class BaseAgent extends Agent {
         this._stateCache = state;
         return state;
     }
+    /** @internal */
     async saveStateInternal(state) {
         const modelType = this.ensureStateModel();
         await this.ensureStateStore(modelType);
@@ -430,15 +515,45 @@ export class BaseAgent extends Agent {
         await this._stateStore.set(this._stateKey, state);
         this._stateCache = state;
     }
+    /**
+     * State context for lock-protected state access.
+     *
+     * @remarks
+     * Prefer using {@link BaseAgent.withState} for simpler access patterns.
+     *
+     * @throws Error if no state model is configured.
+     */
     get state() {
         if (!this._stateModel && !this._stateFactory) {
             throw new Error('No state model configured');
         }
         return new StateContext(() => this.acquireStateLock(), () => this.loadStateInternal(), (state) => this.saveStateInternal(state));
     }
+    /**
+     * Executes a callback with exclusive access to the agent's state.
+     *
+     * State changes are automatically persisted after the callback completes.
+     *
+     * @param callback - Function receiving the current state.
+     * @returns The callback's return value.
+     *
+     * @example
+     * ```typescript
+     * const count = await this.withState(async (state) => {
+     *   state.count += 1;
+     *   return state.count;
+     * });
+     * ```
+     */
     async withState(callback) {
         return await this.state.use(callback);
     }
+    /**
+     * Retrieves a snapshot of the current state.
+     *
+     * @remarks
+     * Returns a point-in-time copy. For modifications, use {@link BaseAgent.withState}.
+     */
     async getState() {
         const release = await this.acquireStateLock();
         try {
@@ -448,6 +563,9 @@ export class BaseAgent extends Agent {
             release();
         }
     }
+    /**
+     * Deletes all persisted state for this agent.
+     */
     async clearState() {
         const release = await this.acquireStateLock();
         try {
@@ -460,6 +578,7 @@ export class BaseAgent extends Agent {
             release();
         }
     }
+    /** @internal */
     static isRpcRequest(payload) {
         if (!payload || typeof payload !== 'object') {
             return false;
@@ -474,6 +593,7 @@ export class BaseAgent extends Agent {
         }
         return true;
     }
+    /** @internal */
     async handleMessage(envelope, _context) {
         void _context;
         const frame = envelope.frame;
@@ -497,10 +617,20 @@ export class BaseAgent extends Agent {
         }
         return await this.handleRpcMessage(decoded, envelope);
     }
+    /**
+     * Override to handle non-RPC messages.
+     *
+     * Called when the agent receives a message that is not a JSON-RPC request.
+     * The default implementation logs a warning and returns null.
+     *
+     * @param message - The decoded message payload.
+     * @returns Optional response to send back.
+     */
     async onMessage(message) {
         logger.warning('unhandled_inbound_message', { message });
         return null;
     }
+    /** @internal */
     async handleRpcMessage(rpcRequest, envelope) {
         if (rpcRequest.method === 'tasks/sendSubscribe') {
             this.startSubscriptionTask(rpcRequest, envelope.replyTo ?? null);
@@ -537,6 +667,7 @@ export class BaseAgent extends Agent {
         }.bind(this);
         return generator();
     }
+    /** @internal */
     startSubscriptionTask(rpcRequest, replyTo) {
         const id = rpcRequest.id != null ? String(rpcRequest.id) : null;
         if (!id) {
@@ -561,6 +692,7 @@ export class BaseAgent extends Agent {
             });
         }
     }
+    /** @internal */
     async streamSendSubscribe(rpcRequest, replyTo, signal) {
         try {
             const params = resolveRpcParams(rpcRequest.params);
@@ -652,11 +784,42 @@ export class BaseAgent extends Agent {
         void _params;
         throw new UnsupportedOperationException(`Agent ${this.constructor.name} does not support operation 'getTaskStatus'`);
     }
+    /**
+     * Override to implement task execution logic.
+     *
+     * This is the primary extension point for agent behavior. Return the task result
+     * or throw an error to fail the task.
+     *
+     * @param _payload - The task payload.
+     * @param _id - Optional task identifier.
+     * @returns The task result.
+     * @throws UnsupportedOperationException if not overridden.
+     *
+     * @example
+     * ```typescript
+     * async runTask(payload: Payload): Promise<string> {
+     *   const input = typeof payload === 'string' ? payload : '';
+     *   return `Hello, ${input}!`;
+     * }
+     * ```
+     */
     async runTask(_payload, _id) {
         void _payload;
         void _id;
         throw new UnsupportedOperationException(`Agent ${this.constructor.name} does not support operation 'runTask'`);
     }
+    /**
+     * Initiates a task and returns its status.
+     *
+     * @remarks
+     * If you override {@link BaseAgent.runTask}, this method automatically
+     * creates a Task from the result. Override this method for custom
+     * task lifecycle management.
+     *
+     * @param params - Task parameters including message and metadata.
+     * @returns The completed task with result.
+     * @throws Error if neither startTask nor runTask is implemented.
+     */
     async startTask(params) {
         const ctor = this.constructor;
         const parts = params.message?.parts ?? [];
@@ -684,7 +847,9 @@ export class BaseAgent extends Agent {
         await super.aserve(address, options);
     }
 }
-_BaseAgent_instances = new WeakSet(), _BaseAgent_createTaskFromPayloadResponse = async function _BaseAgent_createTaskFromPayloadResponse(params, payload, runner) {
+_BaseAgent_instances = new WeakSet(), _BaseAgent_createTaskFromPayloadResponse = 
+/** @internal */
+async function _BaseAgent_createTaskFromPayloadResponse(params, payload, runner) {
     const responsePayload = await runner(payload, params.id ?? null);
     let sanitizedPayload = null;
     if (typeof responsePayload === 'string') {
@@ -700,6 +865,10 @@ _BaseAgent_instances = new WeakSet(), _BaseAgent_createTaskFromPayloadResponse =
         sessionId: params.sessionId ?? null,
     });
 };
+/**
+ * Default state model class. Override in subclasses to set state type.
+ * @internal
+ */
 BaseAgent.STATE_MODEL = null;
 registerBaseAgentConstructor(BaseAgent);
 //# sourceMappingURL=base-agent.js.map