@cleocode/lafs-protocol 1.3.2 → 1.4.1

package/README.md

@@ -4,7 +4,7 @@
 
 LAFS defines a standard envelope format for structured responses from LLM-powered agents and tools. It complements transport protocols like [MCP](https://modelcontextprotocol.io/) and [A2A](https://github.com/google/A2A) by standardizing what comes back — not how it gets there.
 
-**Current version:** 1.3.1 | [📚 Documentation](https://codluv.gitbook.io/lafs-protocol/) | [Spec](lafs.md) | [Migration Guides](migrations/)
+**Current version:** 1.4.1 | [📚 Documentation](https://codluv.gitbook.io/lafs-protocol/) | [Spec](lafs.md) | [Migration Guides](migrations/)
 
 [![GitBook](https://img.shields.io/badge/docs-gitbook-blue)](https://codluv.gitbook.io/lafs-protocol/)
 [![npm](https://img.shields.io/npm/v/@cleocode/lafs-protocol)](https://www.npmjs.com/package/@cleocode/lafs-protocol)
@@ -33,15 +33,35 @@ npm install @cleocode/lafs-protocol
 
 ```typescript
 import {
+  createEnvelope,
+  parseLafsResponse,
+  LafsError,
   validateEnvelope,
   runEnvelopeConformance,
   isRegisteredErrorCode,
 } from "@cleocode/lafs-protocol";
 
+// Build envelope with defaults
+const envelope = createEnvelope({
+  success: true,
+  result: { items: [] },
+  meta: { operation: "example.list", requestId: "req_1" },
+});
+
 // Validate an envelope against the schema
-const result = validateEnvelope(envelope);
-if (!result.valid) {
-  console.error(result.errors);
+const validation = validateEnvelope(envelope);
+if (!validation.valid) {
+  console.error(validation.errors);
+}
+
+// Parse envelope responses with one function
+try {
+  const parsed = parseLafsResponse(envelope);
+  console.log(parsed);
+} catch (error) {
+  if (error instanceof LafsError) {
+    console.error(error.code, error.message);
+  }
 }
 
 // Run full conformance suite (schema + invariants + error codes + strict mode + pagination)
@@ -49,6 +69,13 @@ const report = runEnvelopeConformance(envelope);
 console.log(report.ok); // true if all checks pass
 ```
 
+## LLM-agent implementation guides
+
+- `docs/guides/llm-agent-guide.md` - parser, success/error handling, strict JSON policy
+- `docs/guides/schema-extension.md` - operation-specific result validation on top of core schema
+- `docs/guides/compliance-pipeline.md` - generation middleware with validate + conformance gates
+- `docs/llms.txt` - LLM-oriented index and canonical sources
+
 ## CLI
 
 ```bash

package/dist/schemas/v1/conformance-profiles.json

@@ -0,0 +1,35 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "version": "1.0.0",
+    "tiers": {
+        "core": [
+            "envelope_schema_valid",
+            "envelope_invariants",
+            "error_code_registered"
+        ],
+        "standard": [
+            "envelope_schema_valid",
+            "envelope_invariants",
+            "error_code_registered",
+            "transport_mapping_consistent",
+            "meta_mvi_present",
+            "meta_strict_present",
+            "strict_mode_behavior",
+            "pagination_mode_consistent",
+            "strict_mode_enforced"
+        ],
+        "complete": [
+            "envelope_schema_valid",
+            "envelope_invariants",
+            "error_code_registered",
+            "transport_mapping_consistent",
+            "context_mutation_failure",
+            "context_preservation_valid",
+            "meta_mvi_present",
+            "meta_strict_present",
+            "strict_mode_behavior",
+            "pagination_mode_consistent",
+            "strict_mode_enforced"
+        ]
+    }
+}

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

@@ -29,3 +29,7 @@ export declare const A2A_ERROR_MAPPINGS: ReadonlyMap<A2AErrorType, ErrorCodeMapp
  */
 export declare function getErrorCodeMapping(errorType: A2AErrorType): ErrorCodeMapping;
 export { A2A_GRPC_ERROR_REASONS } from './grpc.js';
+export declare const SUPPORTED_A2A_VERSIONS: readonly ["1.0"];
+export declare const DEFAULT_A2A_VERSION: "1.0";
+export declare function parseA2AVersionHeader(headerValue: string | undefined): string[];
+export declare function negotiateA2AVersion(requestedVersions: string[]): string | null;

package/dist/src/a2a/bindings/index.js

@@ -52,3 +52,28 @@ export function getErrorCodeMapping(errorType) {
 // Also export A2A_GRPC_ERROR_REASONS for convenience (re-exported from grpc.ts via *)
 // but explicitly reference it here so the cross-binding module is self-documenting
 export { A2A_GRPC_ERROR_REASONS } from './grpc.js';
+// ============================================================================
+// Version Negotiation
+// ============================================================================
+export const SUPPORTED_A2A_VERSIONS = ['1.0'];
+export const DEFAULT_A2A_VERSION = '1.0';
+export function parseA2AVersionHeader(headerValue) {
+    if (!headerValue)
+        return [];
+    return headerValue
+        .split(',')
+        .map((v) => v.trim())
+        .filter(Boolean);
+}
+export function negotiateA2AVersion(requestedVersions) {
+    if (requestedVersions.length === 0) {
+        return DEFAULT_A2A_VERSION;
+    }
+    const supported = new Set(SUPPORTED_A2A_VERSIONS);
+    for (const version of requestedVersions) {
+        if (supported.has(version)) {
+            return version;
+        }
+    }
+    return null;
+}

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

@@ -6,7 +6,8 @@
  *
  * Reference: specs/external/specification.md
  */
-import type { Task, TaskState, TaskStatus, Artifact, Part, Message, AgentCard, MessageSendConfiguration, SendMessageResponse, SendMessageSuccessResponse, JSONRPCErrorResponse, AGENT_CARD_PATH, HTTP_EXTENSION_HEADER } 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

package/dist/src/a2a/bridge.js

@@ -7,6 +7,10 @@
  * Reference: specs/external/specification.md
  */
 // ============================================================================
+// Imports - Use official A2A SDK types
+// ============================================================================
+import { AGENT_CARD_PATH, HTTP_EXTENSION_HEADER, } from '@a2a-js/sdk';
+// ============================================================================
 // Result Wrapper
 // ============================================================================
 /**
@@ -267,3 +271,16 @@ export function isExtensionRequired(agentCard, extensionUri) {
 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

@@ -17,7 +17,9 @@ 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 */
@@ -28,6 +30,8 @@ export interface ExtensionNegotiationResult {
     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.
@@ -57,6 +61,19 @@ export interface BuildLafsExtensionOptions {
  * 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).

package/dist/src/a2a/extensions.js

@@ -18,6 +18,7 @@ export const A2A_EXTENSIONS_HEADER = 'A2A-Extensions';
  * Middleware checks both for SDK compatibility.
  */
 const SDK_EXTENSIONS_HEADER = 'x-a2a-extensions';
+const VALID_EXTENSION_KINDS = ['data-only', 'profile', 'method', 'state-machine'];
 // ============================================================================
 // Functions
 // ============================================================================
@@ -57,7 +58,21 @@ export function negotiateExtensions(requestedUris, agentExtensions) {
             missingRequired.push(ext.uri);
         }
     }
-    return { requested: requestedUris, activated, unsupported, missingRequired };
+    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.
@@ -79,9 +94,36 @@ export function buildLafsExtension(options) {
             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
 // ============================================================================

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

@@ -31,7 +31,9 @@
 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 { 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';

package/dist/src/a2a/index.js

@@ -37,7 +37,9 @@ LafsA2AResult,
 // Artifact helpers
 createLafsArtifact, createTextArtifact, createFileArtifact, 
 // Extension helpers
-isExtensionRequired, getExtensionParams, } from './bridge.js';
+isExtensionRequired, getExtensionParams, 
+// Constants
+AGENT_CARD_PATH, HTTP_EXTENSION_HEADER, } from './bridge.js';
 // ============================================================================
 // Extensions (T098)
 // ============================================================================
@@ -59,12 +61,16 @@ TERMINAL_STATES, INTERRUPTED_STATES, VALID_TRANSITIONS,
 // State functions
 isValidTransition, isTerminalState, isInterruptedState, 
 // Error classes
-InvalidStateTransitionError, TaskImmutabilityError, TaskNotFoundError, 
+InvalidStateTransitionError, TaskImmutabilityError, TaskNotFoundError, TaskRefinementError, 
 // Task manager
 TaskManager, 
 // LAFS integration
 attachLafsEnvelope, } from './task-lifecycle.js';
 // ============================================================================
+// Streaming and Async (T101)
+// ============================================================================
+export { TaskEventBus, PushNotificationConfigStore, PushNotificationDispatcher, TaskArtifactAssembler, streamTaskEvents, } from './streaming.js';
+// ============================================================================
 // Protocol Bindings (T100)
 // ============================================================================
 export * from './bindings/index.js';

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

@@ -0,0 +1,74 @@
+/**
+ * A2A streaming and async runtime primitives (T101).
+ *
+ * Provides an in-memory event bus for task status/artifact updates and
+ * push-notification config storage helpers.
+ */
+import type { Artifact, PushNotificationConfig, TaskArtifactUpdateEvent, TaskStatusUpdateEvent } from "@a2a-js/sdk";
+export type TaskStreamEvent = TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
+type StreamListener = (event: TaskStreamEvent) => void;
+/**
+ * In-memory event bus for task lifecycle streaming events.
+ */
+export declare class TaskEventBus {
+    private history;
+    private listeners;
+    publishStatusUpdate(event: TaskStatusUpdateEvent): void;
+    publishArtifactUpdate(event: TaskArtifactUpdateEvent): void;
+    publish(event: TaskStreamEvent): void;
+    subscribe(taskId: string, listener: StreamListener): () => void;
+    getHistory(taskId: string): TaskStreamEvent[];
+}
+export interface StreamIteratorOptions {
+    timeoutMs?: number;
+}
+/**
+ * Build an async iterator for real-time task stream events.
+ */
+export declare function streamTaskEvents(bus: TaskEventBus, taskId: string, options?: StreamIteratorOptions): AsyncGenerator<TaskStreamEvent>;
+/**
+ * In-memory manager for async push-notification configs.
+ */
+export declare class PushNotificationConfigStore {
+    private configs;
+    set(taskId: string, configId: string, config: PushNotificationConfig): void;
+    get(taskId: string, configId: string): PushNotificationConfig | undefined;
+    list(taskId: string): PushNotificationConfig[];
+    delete(taskId: string, configId: string): boolean;
+}
+export interface PushNotificationDeliveryResult {
+    configId: string;
+    ok: boolean;
+    status?: number;
+    error?: string;
+}
+export type PushTransport = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+/**
+ * Deliver task updates to registered push-notification webhooks.
+ */
+export declare class PushNotificationDispatcher {
+    private readonly store;
+    private readonly transport;
+    constructor(store: PushNotificationConfigStore, transport?: PushTransport);
+    dispatch(taskId: string, event: TaskStreamEvent): Promise<PushNotificationDeliveryResult[]>;
+    private buildHeaders;
+}
+/**
+ * Applies append/lastChunk artifact deltas into task-local snapshots.
+ */
+export declare class TaskArtifactAssembler {
+    private artifacts;
+    applyUpdate(event: TaskArtifactUpdateEvent): Artifact;
+    get(taskId: string, artifactId: string): Artifact | undefined;
+    list(taskId: string): Artifact[];
+    private mergeArtifact;
+    private withLastChunk;
+}
+export {};

package/dist/src/a2a/streaming.js

@@ -0,0 +1,265 @@
+/**
+ * A2A streaming and async runtime primitives (T101).
+ *
+ * Provides an in-memory event bus for task status/artifact updates and
+ * push-notification config storage helpers.
+ */
+function resolveTaskId(event) {
+    const candidate = event;
+    const taskId = candidate.taskId ?? candidate.task?.id;
+    if (!taskId) {
+        throw new Error("Task stream event is missing task identifier");
+    }
+    return taskId;
+}
+/**
+ * In-memory event bus for task lifecycle streaming events.
+ */
+export class TaskEventBus {
+    history = new Map();
+    listeners = new Map();
+    publishStatusUpdate(event) {
+        this.publish(event);
+    }
+    publishArtifactUpdate(event) {
+        this.publish(event);
+    }
+    publish(event) {
+        const taskId = resolveTaskId(event);
+        const events = this.history.get(taskId) ?? [];
+        events.push(event);
+        this.history.set(taskId, events);
+        const listeners = this.listeners.get(taskId);
+        if (listeners) {
+            for (const listener of listeners) {
+                listener(event);
+            }
+        }
+    }
+    subscribe(taskId, listener) {
+        let set = this.listeners.get(taskId);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(taskId, set);
+        }
+        set.add(listener);
+        return () => {
+            const active = this.listeners.get(taskId);
+            if (!active)
+                return;
+            active.delete(listener);
+            if (active.size === 0) {
+                this.listeners.delete(taskId);
+            }
+        };
+    }
+    getHistory(taskId) {
+        return [...(this.history.get(taskId) ?? [])];
+    }
+}
+/**
+ * Build an async iterator for real-time task stream events.
+ */
+export async function* streamTaskEvents(bus, taskId, options = {}) {
+    const queue = [];
+    let wakeUp = null;
+    const unsubscribe = bus.subscribe(taskId, (event) => {
+        queue.push(event);
+        if (wakeUp) {
+            wakeUp();
+            wakeUp = null;
+        }
+    });
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    try {
+        // Emit existing history first for catch-up behavior.
+        for (const event of bus.getHistory(taskId)) {
+            yield event;
+        }
+        while (true) {
+            if (queue.length > 0) {
+                const event = queue.shift();
+                if (event) {
+                    yield event;
+                    continue;
+                }
+            }
+            await new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    if (wakeUp === resolve) {
+                        wakeUp = null;
+                    }
+                    resolve();
+                }, timeoutMs);
+                wakeUp = () => {
+                    clearTimeout(timer);
+                    resolve();
+                };
+            });
+        }
+    }
+    finally {
+        unsubscribe();
+    }
+}
+/**
+ * In-memory manager for async push-notification configs.
+ */
+export class PushNotificationConfigStore {
+    configs = new Map();
+    set(taskId, configId, config) {
+        let taskConfigs = this.configs.get(taskId);
+        if (!taskConfigs) {
+            taskConfigs = new Map();
+            this.configs.set(taskId, taskConfigs);
+        }
+        taskConfigs.set(configId, config);
+    }
+    get(taskId, configId) {
+        return this.configs.get(taskId)?.get(configId);
+    }
+    list(taskId) {
+        return [...(this.configs.get(taskId)?.values() ?? [])];
+    }
+    delete(taskId, configId) {
+        const taskConfigs = this.configs.get(taskId);
+        if (!taskConfigs) {
+            return false;
+        }
+        const removed = taskConfigs.delete(configId);
+        if (taskConfigs.size === 0) {
+            this.configs.delete(taskId);
+        }
+        return removed;
+    }
+}
+/**
+ * Deliver task updates to registered push-notification webhooks.
+ */
+export class PushNotificationDispatcher {
+    store;
+    transport;
+    constructor(store, transport = async (input, init) => {
+        if (typeof fetch !== "function") {
+            throw new Error("Global fetch is not available for push dispatch");
+        }
+        return fetch(input, init);
+    }) {
+        this.store = store;
+        this.transport = transport;
+    }
+    async dispatch(taskId, event) {
+        const configs = this.store.list(taskId);
+        if (configs.length === 0) {
+            return [];
+        }
+        const payload = {
+            taskId,
+            event,
+            timestamp: new Date().toISOString(),
+        };
+        const deliveries = configs.map(async (config, index) => {
+            const configId = config.id ?? `${taskId}:${index}`;
+            if (!config.url) {
+                return {
+                    configId,
+                    ok: false,
+                    error: "Push notification config is missing url",
+                };
+            }
+            const headers = this.buildHeaders(config);
+            try {
+                const response = await this.transport(config.url, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify(payload),
+                });
+                return {
+                    configId,
+                    ok: response.ok,
+                    status: response.status,
+                    ...(response.ok ? {} : { error: `HTTP ${response.status}` }),
+                };
+            }
+            catch (error) {
+                return {
+                    configId,
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        });
+        return Promise.all(deliveries);
+    }
+    buildHeaders(config) {
+        const headers = {
+            "content-type": "application/json",
+        };
+        if (config.token) {
+            headers["x-a2a-task-token"] = config.token;
+        }
+        const scheme = config.authentication?.schemes?.[0];
+        const credentials = config.authentication?.credentials;
+        if (scheme && credentials) {
+            headers.authorization = `${scheme} ${credentials}`;
+        }
+        else if (config.token) {
+            headers.authorization = `Bearer ${config.token}`;
+        }
+        return headers;
+    }
+}
+/**
+ * Applies append/lastChunk artifact deltas into task-local snapshots.
+ */
+export class TaskArtifactAssembler {
+    artifacts = new Map();
+    applyUpdate(event) {
+        if (!event.artifact?.artifactId) {
+            throw new Error("Task artifact update is missing artifactId");
+        }
+        const taskId = resolveTaskId(event);
+        const artifactId = event.artifact.artifactId;
+        let taskArtifacts = this.artifacts.get(taskId);
+        if (!taskArtifacts) {
+            taskArtifacts = new Map();
+            this.artifacts.set(taskId, taskArtifacts);
+        }
+        const prior = taskArtifacts.get(artifactId);
+        const merged = this.mergeArtifact(prior, event);
+        taskArtifacts.set(artifactId, merged);
+        return merged;
+    }
+    get(taskId, artifactId) {
+        return this.artifacts.get(taskId)?.get(artifactId);
+    }
+    list(taskId) {
+        return [...(this.artifacts.get(taskId)?.values() ?? [])];
+    }
+    mergeArtifact(prior, event) {
+        const next = event.artifact;
+        const append = Boolean(event.append);
+        const lastChunk = Boolean(event.lastChunk);
+        if (!append || !prior) {
+            return {
+                ...next,
+                metadata: this.withLastChunk(next.metadata, lastChunk),
+            };
+        }
+        return {
+            ...prior,
+            ...next,
+            parts: [...(prior.parts ?? []), ...(next.parts ?? [])],
+            metadata: this.withLastChunk({
+                ...(prior.metadata ?? {}),
+                ...(next.metadata ?? {}),
+            }, lastChunk),
+        };
+    }
+    withLastChunk(metadata, lastChunk) {
+        return {
+            ...(metadata ?? {}),
+            "a2a:last_chunk": lastChunk,
+        };
+    }
+}