@cleocode/lafs 1.8.0

package/dist/src/a2a/bridge.js

@@ -0,0 +1,286 @@
+/**
+ * LAFS A2A Bridge v2.0
+ *
+ * Full integration with official @a2a-js/sdk for Agent-to-Agent communication.
+ * Implements A2A Protocol v1.0+ specification.
+ *
+ * Reference: specs/external/specification.md
+ */
+// ============================================================================
+// Imports - Use official A2A SDK types
+// ============================================================================
+import { AGENT_CARD_PATH, HTTP_EXTENSION_HEADER, } from '@a2a-js/sdk';
+// ============================================================================
+// Result Wrapper
+// ============================================================================
+/**
+ * Wrapper for A2A responses with LAFS envelope support
+ */
+export class LafsA2AResult {
+    result;
+    config;
+    requestId;
+    constructor(result, config, requestId) {
+        this.result = result;
+        this.config = config;
+        this.requestId = requestId;
+    }
+    /**
+     * Get the raw A2A response
+     */
+    getA2AResult() {
+        return this.result;
+    }
+    /**
+     * Check if result is an error
+     */
+    isError() {
+        return 'error' in this.result;
+    }
+    /**
+     * Get error details if result is an error
+     */
+    getError() {
+        if (this.isError()) {
+            return this.result;
+        }
+        return null;
+    }
+    /**
+     * Get success result
+     */
+    getSuccess() {
+        if (!this.isError()) {
+            return this.result;
+        }
+        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;
+            }
+        }
+        return null;
+    }
+    /**
+     * Extract Message from response (if present)
+     */
+    getMessage() {
+        const success = this.getSuccess();
+        if (!success)
+            return null;
+        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 response contains a LAFS envelope
+     */
+    hasLafsEnvelope() {
+        return this.getLafsEnvelope() !== null;
+    }
+    /**
+     * 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();
+        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' &&
+            data !== null &&
+            '$schema' in data &&
+            '_meta' in data &&
+            'success' in data);
+    }
+}
+// ============================================================================
+// LAFS Artifact Creation Helpers
+// ============================================================================
+/**
+ * Create a LAFS envelope artifact for A2A
+ *
+ * @example
+ * ```typescript
+ * const envelope = createEnvelope({
+ *   success: true,
+ *   result: { data: '...' },
+ *   meta: { operation: 'analysis.run' }
+ * });
+ *
+ * const artifact = createLafsArtifact(envelope);
+ * task.artifacts.push(artifact);
+ * ```
+ */
+export function createLafsArtifact(envelope) {
+    return {
+        artifactId: generateId(),
+        name: 'lafs_response',
+        description: 'LAFS-formatted response envelope',
+        parts: [{
+                kind: 'data',
+                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() {
+    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);
+    });
+}
+// ============================================================================
+// 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;
+}
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * A2A Agent Card well-known path
+ * Reference: specs/external/agent-discovery.md
+ */
+export { AGENT_CARD_PATH };
+/**
+ * HTTP header for A2A Extensions
+ * Reference: specs/external/extensions.md
+ */
+export { HTTP_EXTENSION_HEADER };

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

@@ -0,0 +1,121 @@
+/**
+ * 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;
+    kind?: ExtensionKind;
+}
+export type ExtensionKind = 'data-only' | 'profile' | 'method' | 'state-machine';
+/** 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[];
+    /** Activated extensions grouped by declared kind (when provided) */
+    activatedByKind: Partial<Record<ExtensionKind, 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;
+export interface BuildExtensionOptions {
+    uri: string;
+    description: string;
+    required?: boolean;
+    kind: ExtensionKind;
+    params?: Record<string, unknown>;
+}
+export declare function buildExtension(options: BuildExtensionOptions): AgentExtension;
+export declare function isValidExtensionKind(kind: string): kind is ExtensionKind;
+export declare function validateExtensionDeclaration(extension: AgentExtension): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * 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 with agent-actionable fields */
+    toProblemDetails(): Record<string, unknown> & {
+        agentAction: string;
+    };
+    /** Convert to a LAFSError-compatible object */
+    toLafsError(): {
+        code: string;
+        message: string;
+        category: 'CONTRACT';
+        retryable: boolean;
+        retryAfterMs: null;
+        details: 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,205 @@
+/**
+ * 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';
+const VALID_EXTENSION_KINDS = ['data-only', 'profile', 'method', 'state-machine'];
+// ============================================================================
+// 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);
+        }
+    }
+    const activatedByKind = {};
+    for (const uri of activated) {
+        const ext = declared.get(uri);
+        const kind = ext?.params && typeof ext.params === 'object'
+            ? ext.params['kind']
+            : undefined;
+        if (typeof kind === 'string' && VALID_EXTENSION_KINDS.includes(kind)) {
+            const typedKind = kind;
+            if (!activatedByKind[typedKind]) {
+                activatedByKind[typedKind] = [];
+            }
+            activatedByKind[typedKind].push(uri);
+        }
+    }
+    return { requested: requestedUris, activated, unsupported, missingRequired, activatedByKind };
+}
+/**
+ * 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',
+            kind: 'profile',
+        },
+    };
+}
+export function buildExtension(options) {
+    return {
+        uri: options.uri,
+        description: options.description,
+        required: options.required ?? false,
+        params: {
+            kind: options.kind,
+            ...(options.params ?? {}),
+        },
+    };
+}
+export function isValidExtensionKind(kind) {
+    return VALID_EXTENSION_KINDS.includes(kind);
+}
+export function validateExtensionDeclaration(extension) {
+    const kind = extension.params && typeof extension.params === 'object'
+        ? extension.params['kind']
+        : undefined;
+    if (kind === undefined) {
+        return { valid: true };
+    }
+    if (typeof kind !== 'string' || !isValidExtensionKind(kind)) {
+        return { valid: false, error: `invalid extension kind: ${String(kind)}` };
+    }
+    return { valid: true };
+}
+// ============================================================================
+// 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 with agent-actionable fields */
+    toProblemDetails() {
+        return {
+            type: 'https://a2a-protocol.org/errors/extension-support-required',
+            title: 'Extension Support Required',
+            status: this.httpStatus,
+            detail: this.message,
+            missingExtensions: this.missingExtensions,
+            agentAction: 'retry_modified',
+        };
+    }
+    /** Convert to a LAFSError-compatible object */
+    toLafsError() {
+        return {
+            code: 'E_CONTRACT_EXTENSION_REQUIRED',
+            message: this.message,
+            category: 'CONTRACT',
+            retryable: true,
+            retryAfterMs: null,
+            details: {
+                missingExtensions: this.missingExtensions,
+                agentAction: 'retry_modified',
+            },
+        };
+    }
+}
+/**
+ * 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.setHeader('Content-Type', 'application/problem+json');
+            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

@@ -0,0 +1,40 @@
+/**
+ * LAFS Agent-to-Agent (A2A) Integration v2.0
+ *
+ * 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/a2a';
+ * import {
+ *   createLafsArtifact,
+ *   createTextArtifact,
+ *   LafsA2AResult,
+ *   isExtensionRequired
+ * } from '@cleocode/lafs/a2a';
+ *
+ * // Use A2A SDK directly for client operations
+ * import { ClientFactory } from '@a2a-js/sdk/client';
+ *
+ * const factory = new ClientFactory();
+ * const client = await factory.createFromUrl('https://agent.example.com');
+ * const result = await client.sendMessage({...});
+ *
+ * // Wrap result with LAFS helpers
+ * const lafsResult = new LafsA2AResult(result, {}, 'req-001');
+ * const envelope = lafsResult.getLafsEnvelope();
+ * ```
+ */
+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, TaskRefinementError, TaskManager, attachLafsEnvelope, } from './task-lifecycle.js';
+export { TaskEventBus, PushNotificationConfigStore, PushNotificationDispatcher, TaskArtifactAssembler, streamTaskEvents, } from './streaming.js';
+export type { TaskStreamEvent, StreamIteratorOptions, PushNotificationDeliveryResult, PushTransport, } from './streaming.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';