@naylence/agent-sdk 0.3.12 → 0.3.13

package/dist/types/naylence/agent/agent-proxy.d.ts

@@ -1,36 +1,135 @@
+/**
+ * Agent proxy module for remote agent communication.
+ *
+ * An {@link AgentProxy} is a client-side handle for invoking methods on a remote
+ * agent. Use it when you need to call an agent that lives in another process,
+ * container, or network location.
+ *
+ * @remarks
+ * Create proxies via {@link Agent.remote}, {@link Agent.remoteByAddress}, or
+ * {@link Agent.remoteByCapabilities} rather than instantiating AgentProxy directly.
+ *
+ * @module
+ */
 import { FameAddress } from '@naylence/runtime';
 import type { FameFabric } from '@naylence/runtime';
 import type { FameEnvelope } from '@naylence/core';
 import { type AgentCard, type AuthenticationInfo, type PushNotificationConfig, type Task, type TaskArtifactUpdateEvent, type TaskIdParams, type TaskPushNotificationConfig, type TaskQueryParams, type TaskSendParams, type TaskStatusUpdateEvent } from './a2a-types.js';
 import { Agent, type Payload } from './agent.js';
+/** @internal */
 type RunTaskPayload = Payload;
+/** @internal */
 type AgentTaskResult<TAgent extends Agent> = Awaited<ReturnType<TAgent['runTask']>>;
+/** @internal */
 interface AgentProxyCtorOptions {
     address?: FameAddress | string | null;
     capabilities?: string[] | null;
     intentNl?: string | null;
     fabric: FameFabric;
 }
+/** @internal */
 interface StreamOptions {
     timeoutMs?: number | null;
     maxItems?: number | null;
 }
+/**
+ * Client-side proxy for communicating with remote agents.
+ *
+ * AgentProxy implements the {@link Agent} interface, allowing you to call
+ * remote agents as if they were local objects. Method calls are serialized
+ * and sent over the Fame fabric.
+ *
+ * @remarks
+ * Do not instantiate AgentProxy directly. Use the factory methods on
+ * {@link Agent} to create proxies:
+ * - {@link Agent.remote} for flexible options
+ * - {@link Agent.remoteByAddress} for direct addressing
+ * - {@link Agent.remoteByCapabilities} for capability-based discovery
+ *
+ * The proxy also supports arbitrary RPC method calls. Any method not defined
+ * on the proxy class is forwarded as an RPC call to the remote agent.
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from '@naylence/agent-sdk';
+ *
+ * // Create a proxy to a remote agent
+ * const proxy = Agent.remoteByAddress('fame://calculator');
+ *
+ * // Run a task synchronously
+ * const result = await proxy.runTask({ a: 1, b: 2 });
+ *
+ * // Or start a task and poll for completion
+ * const task = await proxy.startTask({
+ *   id: 'task-1',
+ *   message: { role: 'user', parts: [{ type: 'text', text: 'compute' }] },
+ * });
+ * ```
+ *
+ * @typeParam TAgent - The type of the remote agent for result typing.
+ */
 export declare class AgentProxy<TAgent extends Agent = Agent> extends Agent {
+    /** @internal */
     private readonly targetAddress;
+    /** @internal */
     private readonly targetCapabilities;
+    /** @internal */
     private readonly intentNl;
+    /** @internal */
     private readonly fabric;
+    /**
+     * Index signature allowing arbitrary RPC method calls.
+     * Methods not defined on AgentProxy are forwarded to the remote agent.
+     */
     [key: string]: any;
+    /** @internal */
     constructor(options: AgentProxyCtorOptions);
+    /** Returns null as proxies do not have a local name. */
     get name(): string | null;
+    /** Returns the proxy's targeting specification. */
     get spec(): Record<string, unknown>;
+    /**
+     * The target agent's address, if specified.
+     * @deprecated Use {@link AgentProxy.address} instead.
+     */
     get addressRef(): FameAddress | null;
+    /** The target agent's address, if specified. */
     get address(): FameAddress | null;
+    /** The required capabilities for discovery, if specified. */
     get capabilities(): string[] | undefined;
+    /** The fabric this proxy uses for communication. */
     get proxyFabric(): FameFabric;
     getAgentCard(): Promise<AgentCard>;
     authenticate(_credentials: AuthenticationInfo): boolean;
+    /**
+     * Executes a task on the remote agent and waits for completion.
+     *
+     * Starts the task, subscribes to updates, and returns when the task reaches
+     * a terminal state (completed, failed, or canceled).
+     *
+     * @param payload - The task payload to send.
+     * @param id - Optional task identifier. Generated if not provided.
+     * @returns The task result extracted from the final status message.
+     * @throws Error if the task fails.
+     *
+     * @example
+     * ```typescript
+     * const proxy = Agent.remoteByAddress('fame://echo');
+     * const result = await proxy.runTask('hello');
+     * console.log(result); // 'hello'
+     * ```
+     */
     runTask(payload?: RunTaskPayload, id?: string | null): Promise<AgentTaskResult<TAgent>>;
+    /**
+     * Initiates a task on the remote agent.
+     *
+     * Returns immediately with the initial task status. Use
+     * {@link AgentProxy.subscribeToTaskUpdates} or polling with
+     * {@link AgentProxy.getTaskStatus} to track progress.
+     *
+     * @param params - Task parameters or convenience options.
+     * @returns The created task with initial status.
+     */
     startTask(params: TaskSendParams): Promise<Task>;
     startTask(options: {
         id: string;
@@ -42,17 +141,66 @@ export declare class AgentProxy<TAgent extends Agent = Agent> extends Agent {
         historyLength?: number | null;
         metadata?: Record<string, unknown> | null;
     }): Promise<Task>;
+    /**
+     * Retrieves the current status of a task.
+     *
+     * @param params - Query parameters including the task ID.
+     * @returns The task with current status.
+     */
     getTaskStatus(params: TaskQueryParams): Promise<Task>;
+    /**
+     * Requests cancellation of a running task.
+     *
+     * @param params - Parameters including the task ID.
+     * @returns The task with updated status.
+     */
     cancelTask(params: TaskIdParams): Promise<Task>;
+    /**
+     * Subscribes to real-time updates for a task.
+     *
+     * Returns an async iterable that yields status and artifact events
+     * until the task reaches a terminal state or the stream is closed.
+     *
+     * @param params - Task parameters.
+     * @param options - Optional timeout and item limit settings.
+     * @returns Async iterable of task events.
+     */
     subscribeToTaskUpdates(params: TaskSendParams, options?: StreamOptions): AsyncIterable<TaskStatusUpdateEvent | TaskArtifactUpdateEvent>;
+    /**
+     * Cancels a task subscription.
+     *
+     * @param params - Parameters including the task ID.
+     */
     unsubscribeTask(params: TaskIdParams): Promise<unknown>;
+    /**
+     * Registers a push notification endpoint for task updates.
+     *
+     * @param config - Push notification configuration.
+     * @returns The registered configuration.
+     */
     registerPushEndpoint(config: TaskPushNotificationConfig): Promise<TaskPushNotificationConfig>;
+    /**
+     * Retrieves the push notification config for a task.
+     *
+     * @param params - Parameters including the task ID.
+     * @returns The push notification configuration.
+     */
     getPushNotificationConfig(params: TaskIdParams): Promise<TaskPushNotificationConfig>;
+    /** @internal */
     private _streamRpc;
+    /** @internal */
     private _invokeTarget;
+    /**
+     * Creates a proxy for a remote agent by address.
+     * @internal Use {@link Agent.remoteByAddress} instead.
+     */
     static remoteByAddress<TAgent extends Agent>(address: FameAddress, options: {
         fabric: FameFabric;
     }): AgentProxy<TAgent>;
+    /**
+     * Creates a proxy for a remote agent by capabilities.
+     * @internal Use {@link Agent.remoteByCapabilities} instead.
+     */
     static remoteByCapabilities<TAgent extends Agent>(capabilities: string[], options: {
         fabric: FameFabric;
     }): AgentProxy<TAgent>;

package/dist/types/naylence/agent/agent-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-proxy.d.ts","sourceRoot":"","sources":["../../../../src/naylence/agent/agent-proxy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-proxy.d.ts","sourceRoot":"","sources":["../../../../src/naylence/agent/agent-proxy.ts"],"names":[],"mappings":"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"}

package/dist/types/naylence/agent/agent.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Agent module providing the abstract {@link Agent} class.
+ *
+ * An Agent is a self-contained unit of work that can receive tasks, process them,
+ * and return results. Agents communicate over the Fame fabric using a standard
+ * task-based protocol.
+ *
+ * @remarks
+ * For concrete implementations:
+ * - Use {@link BaseAgent} when you need full control over task handling and state.
+ * - Use {@link BackgroundTaskAgent} for long-running or async background work.
+ *
+ * @module
+ */
 import { FameAddress, FameFabric, LogLevel } from '@naylence/runtime';
 import { RpcMixin } from '@naylence/runtime';
 import type { FameService } from '@naylence/core';
@@ -6,25 +20,57 @@ export { registerAgentProxyFactory } from './agent-proxy-registry.js';
 export type { AgentProxyConstructor } from './agent-proxy-registry.js';
 import type { BaseAgent } from './base-agent.js';
 import type { AgentProxy } from './agent-proxy.js';
+/**
+ * Payload type for agent task messages.
+ *
+ * Can be a JSON object, a string, or null.
+ */
 export type Payload = Record<string, unknown> | string | null;
+/**
+ * Collection of address-payload pairs for broadcasting tasks to multiple agents.
+ */
 export type Targets = Iterable<readonly [FameAddress | string, Payload]>;
+/** @internal */
 type AgentTaskHandler = (payload: Payload, id: string | null) => unknown | Promise<unknown>;
+/**
+ * Constructor signature for BaseAgent implementations.
+ * @internal
+ */
 export type BaseAgentConstructor = new (name?: string | null, options?: any) => BaseAgent;
 /** @internal */
 export declare function registerBaseAgentConstructor(ctor: BaseAgentConstructor): void;
+/**
+ * Options for creating a remote agent proxy.
+ *
+ * Provide exactly one of `address` or `capabilities` to identify the target.
+ */
 export interface AgentRemoteOptions {
+    /** Direct address of the target agent. */
     address?: FameAddress | string;
+    /** Required capabilities for capability-based discovery. */
     capabilities?: string[];
+    /** Fabric instance to use. Defaults to the current fabric. */
     fabric?: FameFabric;
 }
+/**
+ * Options for running tasks on multiple agents.
+ */
 export interface AgentRunManyOptions {
+    /** Fabric instance to use. Defaults to the current fabric. */
     fabric?: FameFabric;
+    /**
+     * If true (default), errors are collected alongside results.
+     * If false, the first error rejects the promise.
+     */
     gatherExceptions?: boolean;
 }
+/**
+ * Options for serving an agent at a given address.
+ */
 export interface AgentServeOptions {
     /**
-     * Log level for the agent. Can be a string ('debug', 'info', 'warning', 'error', 'critical'),
-     * a numeric log level, or a LogLevel enum value.
+     * Log level for the agent.
+     * Accepts 'debug', 'info', 'warning', 'error', 'critical', or a LogLevel value.
      */
     logLevel?: string | number | LogLevel | null;
     /**
@@ -40,31 +86,177 @@ export interface AgentServeOptions {
      */
     [key: string]: unknown;
 }
+/**
+ * Abstract base class for all agents.
+ *
+ * Agents are addressable services that handle tasks over the Fame fabric.
+ * This class defines the core protocol methods every agent must implement.
+ *
+ * @remarks
+ * Do not extend Agent directly. Instead:
+ * - Extend {@link BaseAgent} for standard request-response agents.
+ * - Extend {@link BackgroundTaskAgent} for long-running background work.
+ *
+ * Use {@link Agent.remote} or {@link Agent.remoteByAddress} to create proxies
+ * for communicating with remote agents.
+ *
+ * @example
+ * ```typescript
+ * import { BaseAgent, Payload } from '@naylence/agent-sdk';
+ *
+ * class EchoAgent extends BaseAgent {
+ *   async runTask(payload: Payload): Promise<Payload> {
+ *     return payload;
+ *   }
+ * }
+ *
+ * const agent = new EchoAgent('echo');
+ * await agent.serve('fame://echo');
+ * ```
+ */
 export declare abstract class Agent extends RpcMixin implements FameService {
+    /**
+     * Capabilities advertised by this agent for discovery.
+     */
     get capabilities(): string[] | undefined;
+    /** The agent's name, used for logging and identification. */
     abstract get name(): string | null;
+    /** Returns metadata about this agent (address, capabilities, etc.). */
     abstract get spec(): Record<string, unknown>;
+    /** Returns the agent's card describing its capabilities and metadata. */
     abstract getAgentCard(): Promise<AgentCard>;
+    /**
+     * Validates authentication credentials.
+     * @param credentials - The credentials to validate.
+     * @returns True if authentication succeeds.
+     */
     abstract authenticate(credentials: AuthenticationInfo): boolean;
+    /**
+     * Initiates a new task.
+     * @param params - Task parameters including message and optional metadata.
+     * @returns The created task with its initial status.
+     */
     abstract startTask(params: TaskSendParams): Promise<Task>;
+    /**
+     * Executes a task synchronously and returns the result.
+     * @param payload - The task payload.
+     * @param id - Optional task identifier.
+     * @returns The task result.
+     */
     abstract runTask(payload: Payload, id: string | null): Promise<any>;
+    /**
+     * Retrieves the current status of a task.
+     * @param params - Query parameters including the task ID.
+     */
     abstract getTaskStatus(params: TaskQueryParams): Promise<Task>;
+    /**
+     * Requests cancellation of a running task.
+     * @param params - Parameters including the task ID.
+     * @returns The task with updated status.
+     */
     abstract cancelTask(params: TaskIdParams): Promise<Task>;
+    /**
+     * Subscribes to real-time updates for a task.
+     * @param params - Task parameters.
+     * @returns An async iterable of status and artifact update events.
+     */
     abstract subscribeToTaskUpdates(params: TaskSendParams): AsyncIterable<TaskStatusUpdateEvent | TaskArtifactUpdateEvent>;
+    /**
+     * Cancels a task subscription.
+     * @param params - Parameters including the task ID.
+     */
     abstract unsubscribeTask(params: TaskIdParams): Promise<any>;
+    /**
+     * Registers a push notification endpoint for task updates.
+     * @param config - Push notification configuration.
+     */
     abstract registerPushEndpoint(config: TaskPushNotificationConfig): Promise<TaskPushNotificationConfig>;
+    /**
+     * Retrieves the push notification config for a task.
+     * @param params - Parameters including the task ID.
+     */
     abstract getPushNotificationConfig(params: TaskIdParams): Promise<TaskPushNotificationConfig>;
+    /**
+     * Creates a proxy for communicating with a remote agent.
+     *
+     * @remarks
+     * Provide exactly one of `address` or `capabilities` in the options.
+     *
+     * @example
+     * ```typescript
+     * const proxy = Agent.remote<EchoAgent>({ address: 'fame://echo' });
+     * const result = await proxy.runTask('hello');
+     * ```
+     *
+     * @param options - Remote agent options.
+     * @returns A proxy for the remote agent.
+     * @throws Error if both or neither of address/capabilities are provided.
+     */
     static remote<TAgent extends Agent>(this: typeof Agent, options: AgentRemoteOptions): AgentProxy<TAgent>;
+    /**
+     * Creates a proxy for a remote agent by its address.
+     *
+     * @param address - The target agent's address.
+     * @param options - Optional fabric configuration.
+     * @returns A proxy for the remote agent.
+     */
     static remoteByAddress<TAgent extends Agent>(this: typeof Agent, address: FameAddress | string, options?: {
         fabric?: FameFabric;
     }): AgentProxy<TAgent>;
+    /**
+     * Creates a proxy for a remote agent by required capabilities.
+     *
+     * @param capabilities - Required capabilities for discovery.
+     * @param options - Optional fabric configuration.
+     * @returns A proxy for a matching remote agent.
+     */
     static remoteByCapabilities<TAgent extends Agent>(this: typeof Agent, capabilities: string[], options?: {
         fabric?: FameFabric;
     }): AgentProxy<TAgent>;
+    /**
+     * Creates an agent from a simple handler function.
+     *
+     * @remarks
+     * Useful for quick prototyping without defining a full agent class.
+     *
+     * @param handler - Function that processes task payloads.
+     * @returns A new agent instance wrapping the handler.
+     */
     static fromHandler(handler: AgentTaskHandler): Promise<Agent>;
+    /**
+     * Sends the same payload to multiple agents.
+     *
+     * @param addresses - List of agent addresses.
+     * @param payload - Payload to send to all agents.
+     * @param options - Execution options.
+     * @returns Array of [address, result|error] tuples.
+     */
     static broadcast(this: typeof Agent, addresses: Array<FameAddress | string>, payload?: Payload, options?: AgentRunManyOptions): Promise<Array<[string, any | Error]>>;
+    /**
+     * Runs tasks on multiple agents with individual payloads.
+     *
+     * @param targets - Iterable of [address, payload] pairs.
+     * @param options - Execution options.
+     * @returns Array of [address, result|error] tuples.
+     */
     static runMany<TAgent extends Agent>(this: typeof Agent, targets: Targets, options?: AgentRunManyOptions): Promise<Array<[string, any | Error]>>;
+    /**
+     * Starts serving this agent at the given address.
+     *
+     * @remarks
+     * In Node.js, the agent listens for SIGINT/SIGTERM to shut down gracefully.
+     * The method returns when the agent stops serving.
+     *
+     * @param address - The address to serve at (e.g., 'fame://my-agent').
+     * @param options - Serve options including log level and fabric config.
+     */
     aserve(address: FameAddress | string, options?: AgentServeOptions): Promise<void>;
+    /**
+     * Alias for {@link Agent.aserve}.
+     *
+     * @param address - The address to serve at.
+     * @param options - Serve options.
+     */
     serve(address: FameAddress | string, options?: AgentServeOptions): Promise<void>;
 }
 //# sourceMappingURL=agent.d.ts.map

package/dist/types/naylence/agent/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../../src/naylence/agent/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../../src/naylence/agent/agent.ts"],"names":[],"mappings":"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"}