release(v1.4.1): ship completed A2A alignment and publish version bump

kryptobaseddev · kryptobaseddev · commit f41ac6abee3b · 2026-02-24T21:21:07.000-08:00
diff --git a/.cleo/.git-checkpoint-state b/.cleo/.git-checkpoint-state
@@ -1 +1 @@
-1771996375
+1771996754
diff --git a/.cleo/tasks.db b/.cleo/tasks.db
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.1] - 2026-02-25
+
+### Added
+
+- A2A bridge alignment test coverage in `tests/a2aBridge.test.ts` for upstream constants, LAFS artifact envelope extraction, extension requirement checks, and text artifact generation
+- A2A streaming completion APIs in `src/a2a/streaming.ts`:
+  - `PushNotificationDispatcher` for async webhook fan-out from `PushNotificationConfigStore`
+  - `TaskArtifactAssembler` for artifact delta merge semantics (`append` + `lastChunk`)
+
+### Changed
+
+- Updated `src/a2a/bridge.ts` to import `AGENT_CARD_PATH` and `HTTP_EXTENSION_HEADER` as runtime values from `@a2a-js/sdk`
+- Expanded streaming exports through `src/a2a/index.ts` and `src/index.ts` for dispatcher/assembler APIs
+- Expanded `tests/streamingAsync.test.ts` to cover webhook dispatch delivery and artifact append/final-chunk behavior
+
 ### Documentation
 
 - Rewrote `docs/programmatic-construction.md` with comprehensive from-scratch construction guidance: factory parameter breakdown, field constraint tables from the JSON schema, success and error envelope patterns, paginated results (cursor and offset modes), session-correlated messages, versioning fields, MVI levels, construction error handling, and schema import patterns for external validators
diff --git a/README.md b/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.4.0 | [📚 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)
diff --git a/docs/specification.md b/docs/specification.md
@@ -1,7 +1,7 @@
 # LAFS: LLM-Agent-First Specification
 
 > 📚 **Documentation:** https://codluv.gitbook.io/lafs-protocol/  
-> **Version:** 1.4.0 | **Status:** Production Ready
+> **Version:** 1.4.1 | **Status:** Production Ready
 
 ## 1. Scope
 
diff --git a/lafs.md b/lafs.md
@@ -1,7 +1,7 @@
 # LAFS: LLM-Agent-First Specification
 
 > 📚 **Documentation:** https://codluv.gitbook.io/lafs-protocol/  
-> **Version:** 1.4.0 | **Status:** Production Ready
+> **Version:** 1.4.1 | **Status:** Production Ready
 
 ## 1. Scope
 
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/lafs-protocol",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "private": false,
   "type": "module",
   "description": "LLM-Agent-First Specification schemas and conformance tooling",
diff --git a/src/a2a/bridge.ts b/src/a2a/bridge.ts
@@ -11,6 +11,11 @@
 // Imports - Use official A2A SDK types
 // ============================================================================
 
+import {
+  AGENT_CARD_PATH,
+  HTTP_EXTENSION_HEADER,
+} from '@a2a-js/sdk';
+
 import type {
   Task,
   TaskState,
@@ -33,8 +38,6 @@ import type {
   DataPart,
   FilePart,
   FileWithUri,
-  AGENT_CARD_PATH,
-  HTTP_EXTENSION_HEADER,
 } from '@a2a-js/sdk';
 
 // LAFS types
diff --git a/src/a2a/index.ts b/src/a2a/index.ts
@@ -115,12 +115,16 @@ export {
 export {
   TaskEventBus,
   PushNotificationConfigStore,
+  PushNotificationDispatcher,
+  TaskArtifactAssembler,
   streamTaskEvents,
 } from './streaming.js';
 
 export type {
   TaskStreamEvent,
   StreamIteratorOptions,
+  PushNotificationDeliveryResult,
+  PushTransport,
 } from './streaming.js';
 
 export type {
diff --git a/src/a2a/streaming.ts b/src/a2a/streaming.ts
@@ -6,6 +6,7 @@
  */
 
 import type {
+  Artifact,
   PushNotificationConfig,
   TaskArtifactUpdateEvent,
   TaskStatusUpdateEvent,
@@ -175,3 +176,181 @@ export class PushNotificationConfigStore {
     return removed;
   }
 }
+
+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 class PushNotificationDispatcher {
+  constructor(
+    private readonly store: PushNotificationConfigStore,
+    private readonly transport: PushTransport = async (input, init) => {
+      if (typeof fetch !== "function") {
+        throw new Error("Global fetch is not available for push dispatch");
+      }
+      return fetch(input, init);
+    },
+  ) {}
+
+  async dispatch(
+    taskId: string,
+    event: TaskStreamEvent,
+  ): Promise<PushNotificationDeliveryResult[]> {
+    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",
+        } satisfies PushNotificationDeliveryResult;
+      }
+
+      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}` }),
+        } satisfies PushNotificationDeliveryResult;
+      } catch (error) {
+        return {
+          configId,
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        } satisfies PushNotificationDeliveryResult;
+      }
+    });
+
+    return Promise.all(deliveries);
+  }
+
+  private buildHeaders(config: PushNotificationConfig): Record<string, string> {
+    const headers: Record<string, string> = {
+      "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 {
+  private artifacts = new Map<string, Map<string, Artifact>>();
+
+  applyUpdate(event: TaskArtifactUpdateEvent): Artifact {
+    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<string, Artifact>();
+      this.artifacts.set(taskId, taskArtifacts);
+    }
+
+    const prior = taskArtifacts.get(artifactId);
+    const merged = this.mergeArtifact(prior, event);
+    taskArtifacts.set(artifactId, merged);
+    return merged;
+  }
+
+  get(taskId: string, artifactId: string): Artifact | undefined {
+    return this.artifacts.get(taskId)?.get(artifactId);
+  }
+
+  list(taskId: string): Artifact[] {
+    return [...(this.artifacts.get(taskId)?.values() ?? [])];
+  }
+
+  private mergeArtifact(
+    prior: Artifact | undefined,
+    event: TaskArtifactUpdateEvent,
+  ): Artifact {
+    const next = event.artifact as 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,
+      ),
+    };
+  }
+
+  private withLastChunk(
+    metadata: Record<string, unknown> | undefined,
+    lastChunk: boolean,
+  ): Record<string, unknown> {
+    return {
+      ...(metadata ?? {}),
+      "a2a:last_chunk": lastChunk,
+    };
+  }
+}
diff --git a/src/index.ts b/src/index.ts
@@ -59,6 +59,8 @@ export {
   // Streaming and Async (T101)
   TaskEventBus,
   PushNotificationConfigStore,
+  PushNotificationDispatcher,
+  TaskArtifactAssembler,
   streamTaskEvents,
 } from "./a2a/index.js";
 
@@ -74,6 +76,8 @@ export type {
   ListTasksResult,
   TaskStreamEvent,
   StreamIteratorOptions,
+  PushNotificationDeliveryResult,
+  PushTransport,
 } from "./a2a/index.js";
 
 // A2A SDK types (non-conflicting subset)
diff --git a/tests/a2aBridge.test.ts b/tests/a2aBridge.test.ts
diff --git a/tests/streamingAsync.test.ts b/tests/streamingAsync.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@cleocode/lafs-protocol",`
`3`		`- "version": "1.4.0",`
	`3`	`+ "version": "1.4.1",`
`4`	`4`	`"private": false,`
`5`	`5`	`"type": "module",`
`6`	`6`	`"description": "LLM-Agent-First Specification schemas and conformance tooling",`