@cleocode/lafs 2026.3.74 → 2026.4.3

package/dist/src/a2a/bridge.d.ts

@@ -4,99 +4,196 @@
  * Full integration with official @a2a-js/sdk for Agent-to-Agent communication.
  * Implements A2A Protocol v1.0+ specification.
  *
+ * @remarks
+ * Provides the core bridge between LAFS envelopes and A2A protocol types.
+ * Includes a result wrapper ({@link LafsA2AResult}) for extracting typed data
+ * from A2A responses, artifact creation helpers for LAFS envelopes, text, and
+ * files, and extension introspection utilities.
+ *
  * Reference: specs/external/specification.md
  */
+import type { AgentCard, Artifact, JSONRPCErrorResponse, Message, MessageSendConfiguration, Part, SendMessageResponse, SendMessageSuccessResponse, Task, TaskState, TaskStatus } from '@a2a-js/sdk';
 import { AGENT_CARD_PATH, HTTP_EXTENSION_HEADER } from '@a2a-js/sdk';
-import type { Task, TaskState, TaskStatus, Artifact, Part, Message, AgentCard, MessageSendConfiguration, SendMessageResponse, SendMessageSuccessResponse, JSONRPCErrorResponse } from '@a2a-js/sdk';
 import type { LAFSEnvelope } from '../types.js';
 /**
- * Configuration for LAFS A2A integration
+ * Configuration for LAFS A2A integration.
+ *
+ * @remarks
+ * Controls default token budgets, envelope wrapping behavior, protocol
+ * version, and extension activation for all A2A operations.
  */
 export interface LafsA2AConfig {
-    /** Default token budget for all operations */
+    /**
+     * Default token budget for all operations.
+     * @defaultValue undefined
+     */
     defaultBudget?: {
+        /** Maximum number of tokens allowed */
         maxTokens?: number;
+        /** Maximum number of items allowed */
         maxItems?: number;
+        /** Maximum number of bytes allowed */
         maxBytes?: number;
     };
-    /** Whether to automatically wrap responses in LAFS envelopes */
+    /**
+     * Whether to automatically wrap responses in LAFS envelopes.
+     * @defaultValue undefined
+     */
     envelopeResponses?: boolean;
-    /** A2A protocol version to use (default: "1.0") */
+    /**
+     * A2A protocol version to use.
+     * @defaultValue undefined
+     */
     protocolVersion?: string;
-    /** Extension URIs to activate for all requests */
+    /**
+     * Extension URIs to activate for all requests.
+     * @defaultValue undefined
+     */
     defaultExtensions?: string[];
 }
 /**
- * Request parameters for sending messages
+ * Request parameters for sending messages.
+ *
+ * @remarks
+ * Encapsulates the message content, A2A configuration, token budget,
+ * extension activation, and conversation context for a single send
+ * operation.
  */
 export interface LafsSendMessageParams {
-    /** Message content */
+    /** Message content including role, parts, and optional metadata */
     message: {
+        /** Role of the message sender */
         role: 'user' | 'agent';
+        /** Content parts composing the message */
         parts: Part[];
-        /** Optional message metadata */
+        /**
+         * Optional message metadata.
+         * @defaultValue undefined
+         */
         metadata?: Record<string, unknown>;
     };
-    /** A2A configuration for this request */
+    /**
+     * A2A configuration for this request.
+     * @defaultValue undefined
+     */
     configuration?: MessageSendConfiguration;
-    /** Token budget override */
+    /**
+     * Token budget override for this request.
+     * @defaultValue undefined
+     */
     budget?: {
+        /** Maximum number of tokens allowed */
         maxTokens?: number;
+        /** Maximum number of items allowed */
         maxItems?: number;
+        /** Maximum number of bytes allowed */
         maxBytes?: number;
     };
-    /** Extensions to activate for this request */
+    /**
+     * Extensions to activate for this request.
+     * @defaultValue undefined
+     */
     extensions?: string[];
-    /** Context ID for multi-turn conversations */
+    /**
+     * Context ID for multi-turn conversations.
+     * @defaultValue undefined
+     */
     contextId?: string;
-    /** Task ID for continuing existing task */
+    /**
+     * Task ID for continuing existing task.
+     * @defaultValue undefined
+     */
     taskId?: string;
 }
 /**
- * Wrapper for A2A responses with LAFS envelope support
+ * Wrapper for A2A responses with LAFS envelope support.
+ *
+ * @remarks
+ * Provides typed accessors for extracting tasks, messages, LAFS envelopes,
+ * token estimates, and state information from raw A2A `SendMessageResponse`
+ * objects. All methods are null-safe and return `null` when the expected
+ * data is not present.
  */
 export declare class LafsA2AResult {
     private result;
-    private config;
-    private requestId;
-    constructor(result: SendMessageResponse, config: LafsA2AConfig, requestId: string);
     /**
-     * Get the raw A2A response
+     * Create a LafsA2AResult wrapper.
+     *
+     * @param result - Raw A2A SendMessageResponse to wrap
+     * @param _config - LAFS A2A configuration (reserved for future use)
+     * @param _requestId - Request ID for correlation (reserved for future use)
+     */
+    constructor(result: SendMessageResponse, _config: LafsA2AConfig, _requestId: string);
+    /**
+     * Get the raw A2A response.
+     *
+     * @returns The underlying SendMessageResponse object
      */
     getA2AResult(): SendMessageResponse;
     /**
-     * Check if result is an error
+     * Check if the result is an error response.
+     *
+     * @returns True if the response contains a JSON-RPC error
      */
     isError(): boolean;
     /**
-     * Get error details if result is an error
+     * Get error details if the result is an error.
+     *
+     * @returns The JSON-RPC error response, or null if the result is a success
      */
     getError(): JSONRPCErrorResponse | null;
     /**
-     * Get success result
+     * Get the success result.
+     *
+     * @returns The success response, or null if the result is an error
      */
     getSuccess(): SendMessageSuccessResponse | null;
     /**
-     * Extract Task from response (if present)
+     * Extract a Task from the response (if present).
+     *
+     * @remarks
+     * Checks the success result for an object with `id` and `status` properties,
+     * which identifies it as a Task rather than a Message.
+     *
+     * @returns The extracted Task, or null if not present or result is an error
      */
     getTask(): Task | null;
     /**
-     * Extract Message from response (if present)
+     * Extract a Message from the response (if present).
+     *
+     * @remarks
+     * Checks the success result for an object with `messageId` but without
+     * `status`, which distinguishes it from a Task.
+     *
+     * @returns The extracted Message, or null if not present or result is an error
      */
     getMessage(): Message | null;
     /**
-     * Check if response contains a LAFS envelope
+     * Check if the response contains a LAFS envelope.
+     *
+     * @returns True if a LAFS envelope was found in the task's artifacts
      */
     hasLafsEnvelope(): boolean;
     /**
-     * Extract LAFS envelope from A2A artifact
+     * Extract a LAFS envelope from A2A artifact.
      *
+     * @remarks
      * A2A agents can return LAFS envelopes in artifacts for structured data.
-     * This method extracts the envelope from the first artifact containing one.
+     * This method scans all artifacts for a DataPart containing an object
+     * with `$schema`, `_meta`, and `success` fields (the LAFS envelope shape).
+     *
+     * @returns The first LAFS envelope found, or null if none present
      */
     getLafsEnvelope(): LAFSEnvelope | null;
     /**
-     * Get token estimate from LAFS envelope
+     * Get token estimate from LAFS envelope.
+     *
+     * @remarks
+     * Extracts the `_tokenEstimate` field from the LAFS envelope's `_meta`
+     * section, which contains estimated token usage, budget, and truncation
+     * information.
+     *
+     * @returns Token estimate object, or null if no envelope or no estimate present
      */
     getTokenEstimate(): {
         estimated: number;
@@ -104,34 +201,59 @@ export declare class LafsA2AResult {
         truncated?: boolean;
     } | null;
     /**
-     * Get task status
+     * Get the task status.
+     *
+     * @returns The task's current status, or null if no task is present
      */
     getTaskStatus(): TaskStatus | null;
     /**
-     * Get task state
+     * Get the task state.
+     *
+     * @returns The task's current state string, or null if no task is present
      */
     getTaskState(): TaskState | null;
     /**
-     * Check if task is in a terminal state
+     * Check if the task is in a terminal state.
+     *
+     * @remarks
+     * Terminal states are `completed`, `failed`, `canceled`, and `rejected`.
+     *
+     * @returns True if the task is in a terminal state, false otherwise or if no task is present
      */
     isTerminal(): boolean;
     /**
-     * Check if task requires input
+     * Check if the task requires user input.
+     *
+     * @returns True if the task state is `input-required`
      */
     isInputRequired(): boolean;
     /**
-     * Check if task requires authentication
+     * Check if the task requires authentication.
+     *
+     * @returns True if the task state is `auth-required`
      */
     isAuthRequired(): boolean;
     /**
-     * Get all artifacts from task
+     * Get all artifacts from the task.
+     *
+     * @returns Array of task artifacts, or empty array if no task or no artifacts
      */
     getArtifacts(): Artifact[];
+    /** Type guard: checks whether a Part is a DataPart by inspecting its `kind` field. */
     private isDataPart;
+    /** Heuristic check: returns true if the data object looks like a LAFS envelope (has `$schema`, `_meta`, `success`). */
     private isLafsEnvelope;
 }
 /**
- * Create a LAFS envelope artifact for A2A
+ * Create a LAFS envelope artifact for A2A.
+ *
+ * @remarks
+ * Wraps a LAFS envelope in an A2A Artifact with a DataPart. The artifact
+ * is tagged with LAFS version and content type metadata for identification
+ * by consumers.
+ *
+ * @param envelope - LAFS envelope to wrap as an artifact
+ * @returns A2A Artifact containing the envelope as a DataPart
  *
  * @example
  * ```typescript
@@ -147,29 +269,100 @@ export declare class LafsA2AResult {
  */
 export declare function createLafsArtifact(envelope: LAFSEnvelope): Artifact;
 /**
- * Create a text artifact
+ * Create a text artifact.
+ *
+ * @remarks
+ * Wraps a plain text string in an A2A Artifact with a TextPart.
+ *
+ * @param text - Text content for the artifact
+ * @param name - Display name for the artifact
+ * @returns A2A Artifact containing the text as a TextPart
+ *
+ * @example
+ * ```typescript
+ * const artifact = createTextArtifact('Hello, world!', 'greeting');
+ * ```
  */
 export declare function createTextArtifact(text: string, name?: string): Artifact;
 /**
- * Create a file artifact
+ * Create a file artifact.
+ *
+ * @remarks
+ * Wraps a file URI in an A2A Artifact with a FilePart. The media type
+ * and optional filename are included for proper content handling by
+ * consumers.
+ *
+ * @param fileUrl - URI pointing to the file resource
+ * @param mediaType - MIME type of the file (e.g., `application/pdf`)
+ * @param filename - Optional display filename for the artifact
+ * @returns A2A Artifact containing the file reference as a FilePart
+ *
+ * @example
+ * ```typescript
+ * const artifact = createFileArtifact(
+ *   'https://example.com/report.pdf',
+ *   'application/pdf',
+ *   'report.pdf',
+ * );
+ * ```
  */
 export declare function createFileArtifact(fileUrl: string, mediaType: string, filename?: string): Artifact;
 /**
- * Check if an extension is required
+ * Check if an extension is required in an Agent Card.
+ *
+ * @remarks
+ * Scans the agent card's declared extensions for one matching the given
+ * URI with `required: true`.
+ *
+ * @param agentCard - Agent Card to inspect
+ * @param extensionUri - URI of the extension to check
+ * @returns True if the extension is declared as required
+ *
+ * @example
+ * ```typescript
+ * if (isExtensionRequired(agentCard, LAFS_EXTENSION_URI)) {
+ *   console.log('LAFS extension is mandatory for this agent');
+ * }
+ * ```
  */
 export declare function isExtensionRequired(agentCard: AgentCard, extensionUri: string): boolean;
 /**
- * Get extension parameters
+ * Get extension parameters from an Agent Card.
+ *
+ * @remarks
+ * Finds the extension matching the given URI and returns its `params` object.
+ *
+ * @param agentCard - Agent Card to inspect
+ * @param extensionUri - URI of the extension to look up
+ * @returns The extension's params object, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const params = getExtensionParams(agentCard, LAFS_EXTENSION_URI);
+ * if (params?.supportsTokenBudgets) {
+ *   // Enable budget tracking
+ * }
+ * ```
  */
 export declare function getExtensionParams(agentCard: AgentCard, extensionUri: string): Record<string, unknown> | undefined;
 /**
- * A2A Agent Card well-known path
+ * A2A Agent Card well-known path.
+ *
+ * @remarks
+ * The standard path `/.well-known/agent-card.json` where A2A Agent Cards
+ * are published. Re-exported from the A2A SDK.
+ *
  * Reference: specs/external/agent-discovery.md
  */
-export { AGENT_CARD_PATH };
 /**
- * HTTP header for A2A Extensions
+ * HTTP header for A2A Extensions.
+ *
+ * @remarks
+ * Used to communicate extension activation between client and agent.
+ * Re-exported from the A2A SDK.
+ *
  * Reference: specs/external/extensions.md
  */
-export { HTTP_EXTENSION_HEADER };
-export type { Task, TaskState, TaskStatus, Artifact, Part, Message, AgentCard, AgentSkill, AgentCapabilities, AgentExtension, PushNotificationConfig, MessageSendConfiguration, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, SendMessageResponse, SendMessageSuccessResponse, JSONRPCErrorResponse, TextPart, DataPart, FilePart, } from '@a2a-js/sdk';
+export { AGENT_CARD_PATH, HTTP_EXTENSION_HEADER };
+export type { AgentCapabilities, AgentCard, AgentExtension, AgentSkill, Artifact, DataPart, FilePart, JSONRPCErrorResponse, Message, MessageSendConfiguration, Part, PushNotificationConfig, SendMessageResponse, SendMessageSuccessResponse, Task, TaskArtifactUpdateEvent, TaskState, TaskStatus, TaskStatusUpdateEvent, TextPart, } from '@a2a-js/sdk';
+//# sourceMappingURL=bridge.d.ts.map

package/dist/src/a2a/bridge.d.ts.map

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