@cleocode/lafs-protocol 1.2.3 → 1.3.2

package/dist/src/a2a/bridge.js

@@ -1,79 +1,28 @@
 /**
- * LAFS A2A Bridge
+ * LAFS A2A Bridge v2.0
  *
- * Integration with official @a2a-js/sdk for Agent-to-Agent communication.
- * LAFS provides envelope wrapping and token budget support.
+ * Full integration with official @a2a-js/sdk for Agent-to-Agent communication.
+ * Implements A2A Protocol v1.0+ specification.
+ *
+ * Reference: specs/external/specification.md
  */
+// ============================================================================
+// Result Wrapper
+// ============================================================================
 /**
- * Wrap A2A client with LAFS envelope support
- *
- * @example
- * ```typescript
- * import { ClientFactory } from '@a2a-js/sdk/client';
- * import { withLafsEnvelope } from '@lafs/envelope/a2a';
- *
- * const factory = new ClientFactory();
- * const a2aClient = await factory.createFromUrl('http://localhost:4000');
- *
- * const client = withLafsEnvelope(a2aClient, {
- *   envelopeResponses: true,
- *   defaultBudget: { maxTokens: 4000 }
- * });
- *
- * const result = await client.sendMessage({
- *   message: { role: 'user', parts: [{ text: 'Hello' }] }
- * });
- *
- * // Access LAFS envelope
- * const envelope = result.getLafsEnvelope();
- * console.log(envelope._meta._tokenEstimate);
- * ```
+ * Wrapper for A2A responses with LAFS envelope support
  */
-export function withLafsEnvelope(client, config = {}) {
-    return new LafsA2AClient(client, config);
-}
-export class LafsA2AClient {
-    client;
-    config;
-    constructor(client, config) {
-        this.client = client;
-        this.config = config;
-    }
-    async sendMessage(params) {
-        // Merge budget with defaults
-        const budget = {
-            ...this.config.defaultBudget,
-            ...params.budget
-        };
-        // Send via official A2A SDK
-        const result = await this.client.sendMessage({
-            message: {
-                kind: 'message',
-                messageId: this.generateId(),
-                role: params.message.role,
-                parts: params.message.parts
-            }
-        });
-        // Wrap result with LAFS envelope support
-        return new LafsA2AResult(result, budget);
-    }
-    generateId() {
-        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
-            const r = Math.random() * 16 | 0;
-            const v = c === 'x' ? r : (r & 0x3 | 0x8);
-            return v.toString(16);
-        });
-    }
-}
 export class LafsA2AResult {
     result;
-    budget;
-    constructor(result, budget) {
+    config;
+    requestId;
+    constructor(result, config, requestId) {
         this.result = result;
-        this.budget = budget;
+        this.config = config;
+        this.requestId = requestId;
     }
     /**
-     * Get the underlying A2A result
+     * Get the raw A2A response
      */
     getA2AResult() {
         return this.result;
@@ -94,43 +43,133 @@ export class LafsA2AResult {
         return null;
     }
     /**
-     * Extract LAFS envelope from A2A artifact
+     * Get success result
      */
-    getLafsEnvelope() {
-        if (this.isError()) {
-            return null;
+    getSuccess() {
+        if (!this.isError()) {
+            return this.result;
         }
-        const successResult = this.result;
-        // Check if result is a Task
-        if (successResult.result?.kind !== 'task') {
+        return null;
+    }
+    /**
+     * Extract Task from response (if present)
+     */
+    getTask() {
+        const success = this.getSuccess();
+        if (!success)
             return null;
+        // Check if result is a Task (has id, contextId, status)
+        const result = success.result;
+        if (result && typeof result === 'object') {
+            // Task objects have these properties
+            if ('id' in result && 'status' in result) {
+                return result;
+            }
         }
-        const task = successResult.result;
-        if (!task.artifacts || task.artifacts.length === 0) {
+        return null;
+    }
+    /**
+     * Extract Message from response (if present)
+     */
+    getMessage() {
+        const success = this.getSuccess();
+        if (!success)
             return null;
-        }
-        // Find LAFS envelope in artifacts
-        for (const artifact of task.artifacts) {
-            for (const part of artifact.parts) {
-                if (part.kind === 'data' && this.isLafsEnvelope(part.data)) {
-                    return part.data;
-                }
+        const result = success.result;
+        if (result && typeof result === 'object') {
+            // Message objects have messageId
+            if ('messageId' in result && !('status' in result)) {
+                return result;
             }
         }
         return null;
     }
     /**
-     * Check if result contains LAFS envelope
+     * Check if response contains a LAFS envelope
      */
     hasLafsEnvelope() {
         return this.getLafsEnvelope() !== null;
     }
     /**
-     * Get token estimate from envelope
+     * Extract LAFS envelope from A2A artifact
+     *
+     * A2A agents can return LAFS envelopes in artifacts for structured data.
+     * This method extracts the envelope from the first artifact containing one.
+     */
+    getLafsEnvelope() {
+        const task = this.getTask();
+        if (!task?.artifacts?.length)
+            return null;
+        for (const artifact of task.artifacts) {
+            for (const part of artifact.parts) {
+                if (this.isDataPart(part)) {
+                    const data = part.data;
+                    if (this.isLafsEnvelope(data)) {
+                        return data;
+                    }
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Get token estimate from LAFS envelope
      */
     getTokenEstimate() {
         const envelope = this.getLafsEnvelope();
-        return envelope?._meta?._tokenEstimate ?? null;
+        if (!envelope?._meta)
+            return null;
+        // Access LAFS meta fields
+        const meta = envelope._meta;
+        return meta._tokenEstimate ?? null;
+    }
+    /**
+     * Get task status
+     */
+    getTaskStatus() {
+        return this.getTask()?.status ?? null;
+    }
+    /**
+     * Get task state
+     */
+    getTaskState() {
+        return this.getTaskStatus()?.state ?? null;
+    }
+    /**
+     * Check if task is in a terminal state
+     */
+    isTerminal() {
+        const state = this.getTaskState();
+        if (!state)
+            return false;
+        const terminalStates = [
+            'completed',
+            'failed',
+            'canceled',
+            'rejected'
+        ];
+        return terminalStates.includes(state);
+    }
+    /**
+     * Check if task requires input
+     */
+    isInputRequired() {
+        return this.getTaskState() === 'input-required';
+    }
+    /**
+     * Check if task requires authentication
+     */
+    isAuthRequired() {
+        return this.getTaskState() === 'auth-required';
+    }
+    /**
+     * Get all artifacts from task
+     */
+    getArtifacts() {
+        return this.getTask()?.artifacts ?? [];
+    }
+    isDataPart(part) {
+        return part.kind === 'data';
     }
     isLafsEnvelope(data) {
         return (typeof data === 'object' &&
@@ -140,17 +179,21 @@ export class LafsA2AResult {
             'success' in data);
     }
 }
+// ============================================================================
+// LAFS Artifact Creation Helpers
+// ============================================================================
 /**
- * Create a LAFS artifact for A2A
+ * Create a LAFS envelope artifact for A2A
  *
  * @example
  * ```typescript
- * const artifact = createLafsArtifact({
+ * const envelope = createEnvelope({
  *   success: true,
  *   result: { data: '...' },
  *   meta: { operation: 'analysis.run' }
  * });
  *
+ * const artifact = createLafsArtifact(envelope);
  * task.artifacts.push(artifact);
  * ```
  */
@@ -158,10 +201,48 @@ export function createLafsArtifact(envelope) {
     return {
         artifactId: generateId(),
         name: 'lafs_response',
+        description: 'LAFS-formatted response envelope',
         parts: [{
                 kind: 'data',
-                data: envelope
-            }]
+                data: envelope,
+            }],
+        metadata: {
+            'x-lafs-version': '2.0.0',
+            'x-content-type': 'application/vnd.lafs.envelope+json',
+        },
+    };
+}
+/**
+ * Create a text artifact
+ */
+export function createTextArtifact(text, name = 'text_response') {
+    const part = {
+        kind: 'text',
+        text,
+    };
+    return {
+        artifactId: generateId(),
+        name,
+        parts: [part],
+    };
+}
+/**
+ * Create a file artifact
+ */
+export function createFileArtifact(fileUrl, mediaType, filename) {
+    const part = {
+        kind: 'file',
+        file: {
+            kind: 'uri',
+            uri: fileUrl,
+            mimeType: mediaType,
+            ...(filename && { filename }),
+        },
+    };
+    return {
+        artifactId: generateId(),
+        name: filename || 'file',
+        parts: [part],
     };
 }
 function generateId() {
@@ -171,3 +252,18 @@ function generateId() {
         return v.toString(16);
     });
 }
+// ============================================================================
+// Extension Helpers
+// ============================================================================
+/**
+ * Check if an extension is required
+ */
+export function isExtensionRequired(agentCard, extensionUri) {
+    return agentCard.capabilities?.extensions?.some(ext => ext.uri === extensionUri && ext.required) ?? false;
+}
+/**
+ * Get extension parameters
+ */
+export function getExtensionParams(agentCard, extensionUri) {
+    return agentCard.capabilities?.extensions?.find(ext => ext.uri === extensionUri)?.params;
+}

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

@@ -0,0 +1,93 @@
+/**
+ * A2A Extensions Support
+ *
+ * Extension negotiation, LAFS extension builder, and Express middleware
+ * for A2A Protocol v1.0+ compliance.
+ *
+ * Reference: specs/external/extensions.md, A2A spec Section 3.2.6
+ */
+import type { AgentExtension } from '@a2a-js/sdk';
+import type { RequestHandler } from 'express';
+/** Canonical LAFS extension URI */
+export declare const LAFS_EXTENSION_URI = "https://lafs.dev/extensions/envelope/v1";
+/** Canonical A2A Extensions header per spec Section 3.2.6 */
+export declare const A2A_EXTENSIONS_HEADER = "A2A-Extensions";
+/** LAFS extension parameters declared in Agent Card */
+export interface LafsExtensionParams {
+    supportsContextLedger: boolean;
+    supportsTokenBudgets: boolean;
+    envelopeSchema: string;
+}
+/** Result of extension negotiation between client and agent */
+export interface ExtensionNegotiationResult {
+    /** URIs requested by the client */
+    requested: string[];
+    /** URIs that matched agent-declared extensions */
+    activated: string[];
+    /** Requested URIs not declared by the agent (ignored per spec) */
+    unsupported: string[];
+    /** Agent-required URIs not present in client request */
+    missingRequired: string[];
+}
+/**
+ * Parse A2A-Extensions header value into URI array.
+ * Splits comma-separated URIs, trims whitespace, removes empty strings.
+ */
+export declare function parseExtensionsHeader(headerValue: string | undefined): string[];
+/**
+ * Negotiate extensions between client-requested and agent-declared sets.
+ * Unsupported extensions are ignored per spec. Required agent extensions
+ * not requested by the client are flagged in missingRequired.
+ */
+export declare function negotiateExtensions(requestedUris: string[], agentExtensions: AgentExtension[]): ExtensionNegotiationResult;
+/**
+ * Format activated extension URIs into header value.
+ * Joins URIs with comma separator.
+ */
+export declare function formatExtensionsHeader(activatedUris: string[]): string;
+/** Options for building the LAFS extension declaration */
+export interface BuildLafsExtensionOptions {
+    required?: boolean;
+    supportsContextLedger?: boolean;
+    supportsTokenBudgets?: boolean;
+    envelopeSchema?: string;
+}
+/**
+ * Build an A2A AgentExtension object declaring LAFS support.
+ * Suitable for inclusion in Agent Card capabilities.extensions[].
+ */
+export declare function buildLafsExtension(options?: BuildLafsExtensionOptions): AgentExtension;
+/**
+ * Error thrown when required A2A extensions are not supported by the client.
+ * Code -32008 (not in SDK, which stops at -32007).
+ */
+export declare class ExtensionSupportRequiredError extends Error {
+    readonly code: -32008;
+    readonly httpStatus: 400;
+    readonly grpcStatus: "FAILED_PRECONDITION";
+    readonly missingExtensions: string[];
+    constructor(missingExtensions: string[]);
+    /** Convert to JSON-RPC error object */
+    toJSONRPCError(): {
+        code: number;
+        message: string;
+        data: Record<string, unknown>;
+    };
+    /** Convert to RFC 9457 Problem Details object */
+    toProblemDetails(): Record<string, unknown>;
+}
+/** Options for the extension negotiation middleware */
+export interface ExtensionNegotiationMiddlewareOptions {
+    /** Agent-declared extensions to negotiate against */
+    extensions: AgentExtension[];
+    /** Return 400 if required extensions are missing (default: true) */
+    enforceRequired?: boolean;
+}
+/**
+ * Express middleware for A2A extension negotiation.
+ *
+ * Parses A2A-Extensions header (and X-A2A-Extensions for SDK compat),
+ * validates against declared extensions, sets response header with
+ * activated extensions, attaches result to res.locals.a2aExtensions.
+ */
+export declare function extensionNegotiationMiddleware(options: ExtensionNegotiationMiddlewareOptions): RequestHandler;

package/dist/src/a2a/extensions.js

@@ -0,0 +1,147 @@
+/**
+ * A2A Extensions Support
+ *
+ * Extension negotiation, LAFS extension builder, and Express middleware
+ * for A2A Protocol v1.0+ compliance.
+ *
+ * Reference: specs/external/extensions.md, A2A spec Section 3.2.6
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/** Canonical LAFS extension URI */
+export const LAFS_EXTENSION_URI = 'https://lafs.dev/extensions/envelope/v1';
+/** Canonical A2A Extensions header per spec Section 3.2.6 */
+export const A2A_EXTENSIONS_HEADER = 'A2A-Extensions';
+/**
+ * SDK header name (differs from spec).
+ * Middleware checks both for SDK compatibility.
+ */
+const SDK_EXTENSIONS_HEADER = 'x-a2a-extensions';
+// ============================================================================
+// Functions
+// ============================================================================
+/**
+ * Parse A2A-Extensions header value into URI array.
+ * Splits comma-separated URIs, trims whitespace, removes empty strings.
+ */
+export function parseExtensionsHeader(headerValue) {
+    if (!headerValue)
+        return [];
+    return headerValue
+        .split(',')
+        .map(uri => uri.trim())
+        .filter(Boolean);
+}
+/**
+ * Negotiate extensions between client-requested and agent-declared sets.
+ * Unsupported extensions are ignored per spec. Required agent extensions
+ * not requested by the client are flagged in missingRequired.
+ */
+export function negotiateExtensions(requestedUris, agentExtensions) {
+    const declared = new Map(agentExtensions.map(ext => [ext.uri, ext]));
+    const activated = [];
+    const unsupported = [];
+    for (const uri of requestedUris) {
+        if (declared.has(uri)) {
+            activated.push(uri);
+        }
+        else {
+            unsupported.push(uri);
+        }
+    }
+    const requestedSet = new Set(requestedUris);
+    const missingRequired = [];
+    for (const ext of agentExtensions) {
+        if (ext.required && !requestedSet.has(ext.uri)) {
+            missingRequired.push(ext.uri);
+        }
+    }
+    return { requested: requestedUris, activated, unsupported, missingRequired };
+}
+/**
+ * Format activated extension URIs into header value.
+ * Joins URIs with comma separator.
+ */
+export function formatExtensionsHeader(activatedUris) {
+    return activatedUris.join(',');
+}
+/**
+ * Build an A2A AgentExtension object declaring LAFS support.
+ * Suitable for inclusion in Agent Card capabilities.extensions[].
+ */
+export function buildLafsExtension(options) {
+    return {
+        uri: LAFS_EXTENSION_URI,
+        description: 'LAFS envelope protocol for structured agent responses',
+        required: options?.required ?? false,
+        params: {
+            supportsContextLedger: options?.supportsContextLedger ?? false,
+            supportsTokenBudgets: options?.supportsTokenBudgets ?? false,
+            envelopeSchema: options?.envelopeSchema ?? 'https://lafs.dev/schemas/v1/envelope.schema.json',
+        },
+    };
+}
+// ============================================================================
+// Error Class
+// ============================================================================
+/**
+ * Error thrown when required A2A extensions are not supported by the client.
+ * Code -32008 (not in SDK, which stops at -32007).
+ */
+export class ExtensionSupportRequiredError extends Error {
+    code = -32008;
+    httpStatus = 400;
+    grpcStatus = 'FAILED_PRECONDITION';
+    missingExtensions;
+    constructor(missingExtensions) {
+        super(`Required extensions not supported: ${missingExtensions.join(', ')}`);
+        this.name = 'ExtensionSupportRequiredError';
+        this.missingExtensions = missingExtensions;
+    }
+    /** Convert to JSON-RPC error object */
+    toJSONRPCError() {
+        return {
+            code: this.code,
+            message: this.message,
+            data: { missingExtensions: this.missingExtensions },
+        };
+    }
+    /** Convert to RFC 9457 Problem Details object */
+    toProblemDetails() {
+        return {
+            type: 'https://a2a-protocol.org/errors/extension-support-required',
+            title: 'Extension Support Required',
+            status: this.httpStatus,
+            detail: this.message,
+            missingExtensions: this.missingExtensions,
+        };
+    }
+}
+/**
+ * Express middleware for A2A extension negotiation.
+ *
+ * Parses A2A-Extensions header (and X-A2A-Extensions for SDK compat),
+ * validates against declared extensions, sets response header with
+ * activated extensions, attaches result to res.locals.a2aExtensions.
+ */
+export function extensionNegotiationMiddleware(options) {
+    const { extensions, enforceRequired = true } = options;
+    return function extensionNegotiationHandler(req, res, next) {
+        // Check both canonical and SDK headers (Express normalizes to lowercase)
+        const headerValue = req.headers[A2A_EXTENSIONS_HEADER.toLowerCase()] ??
+            req.headers[SDK_EXTENSIONS_HEADER];
+        const requested = parseExtensionsHeader(headerValue);
+        const result = negotiateExtensions(requested, extensions);
+        if (enforceRequired && result.missingRequired.length > 0) {
+            const error = new ExtensionSupportRequiredError(result.missingRequired);
+            res.status(error.httpStatus).json(error.toProblemDetails());
+            return;
+        }
+        if (result.activated.length > 0) {
+            res.setHeader(A2A_EXTENSIONS_HEADER, formatExtensionsHeader(result.activated));
+        }
+        res.locals['a2aExtensions'] = result;
+        next();
+    };
+}

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

@@ -1,36 +1,38 @@
 /**
- * LAFS Agent-to-Agent (A2A) Integration
+ * LAFS Agent-to-Agent (A2A) Integration v2.0
  *
- * This module provides integration between LAFS and the official
- * @a2a-js/sdk for Agent-to-Agent communication.
+ * Full integration with the official @a2a-js/sdk for Agent-to-Agent communication.
+ * Implements A2A Protocol v1.0+ specification.
+ *
+ * Reference: specs/external/specification.md
  *
  * @example
  * ```typescript
+ * import type { AgentCard, Task } from '@cleocode/lafs-protocol/a2a';
+ * import {
+ *   createLafsArtifact,
+ *   createTextArtifact,
+ *   LafsA2AResult,
+ *   isExtensionRequired
+ * } from '@cleocode/lafs-protocol/a2a';
+ *
+ * // Use A2A SDK directly for client operations
  * import { ClientFactory } from '@a2a-js/sdk/client';
- * import { withLafsEnvelope } from '@cleocode/lafs-protocol/a2a';
  *
- * // Create official A2A client
  * const factory = new ClientFactory();
- * const a2aClient = await factory.createFromUrl('http://agent.example.com');
- *
- * // Wrap with LAFS support
- * const client = withLafsEnvelope(a2aClient, {
- *   defaultBudget: { maxTokens: 4000 }
- * });
- *
- * // Send message
- * const result = await client.sendMessage({
- *   message: {
- *     role: 'user',
- *     parts: [{ text: 'Analyze data' }]
- *   }
- * });
+ * const client = await factory.createFromUrl('https://agent.example.com');
+ * const result = await client.sendMessage({...});
  *
- * // Extract LAFS envelope from response
- * const envelope = result.getLafsEnvelope();
- * if (envelope) {
- *   console.log(envelope._meta._tokenEstimate);
- * }
+ * // Wrap result with LAFS helpers
+ * const lafsResult = new LafsA2AResult(result, {}, 'req-001');
+ * const envelope = lafsResult.getLafsEnvelope();
  * ```
  */
-export { withLafsEnvelope, LafsA2AClient, LafsA2AResult, createLafsArtifact, type LafsA2AConfig, type LafsEnvelope } from './bridge.js';
+export { LafsA2AResult, createLafsArtifact, createTextArtifact, createFileArtifact, isExtensionRequired, getExtensionParams, AGENT_CARD_PATH, HTTP_EXTENSION_HEADER, } from './bridge.js';
+export { LAFS_EXTENSION_URI, A2A_EXTENSIONS_HEADER, parseExtensionsHeader, negotiateExtensions, formatExtensionsHeader, buildLafsExtension, ExtensionSupportRequiredError, extensionNegotiationMiddleware, } from './extensions.js';
+export type { LafsExtensionParams, ExtensionNegotiationResult, BuildLafsExtensionOptions, ExtensionNegotiationMiddlewareOptions, } from './extensions.js';
+export { TERMINAL_STATES, INTERRUPTED_STATES, VALID_TRANSITIONS, isValidTransition, isTerminalState, isInterruptedState, InvalidStateTransitionError, TaskImmutabilityError, TaskNotFoundError, TaskManager, attachLafsEnvelope, } from './task-lifecycle.js';
+export type { CreateTaskOptions, ListTasksOptions, ListTasksResult, } from './task-lifecycle.js';
+export * from './bindings/index.js';
+export type { LafsA2AConfig, LafsSendMessageParams, } from './bridge.js';
+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';