@cleocode/lafs 2026.4.0 → 2026.4.4

package/README.md

@@ -1,12 +1,11 @@
 # LAFS Protocol
 
-**LLM-Agent-First Specification** — a response envelope contract for AI agent systems.
+**LLM-Agent-First Specification** -- a response envelope contract for AI agent systems.
 
-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.
+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.5.0 | [📚 Documentation](https://codluv.gitbook.io/lafs/) | [Spec](lafs.md) | [Migration Guides](migrations/)
+**Current version:** 2026.4.0 | [Spec](lafs.md)
 
-[![GitBook](https://img.shields.io/badge/docs-gitbook-blue)](https://codluv.gitbook.io/lafs/)
 [![npm](https://img.shields.io/npm/v/@cleocode/lafs)](https://www.npmjs.com/package/@cleocode/lafs)
 
 ## What LAFS provides
@@ -16,17 +15,24 @@ LAFS defines a standard envelope format for structured responses from LLM-powere
 | **Spec** | `lafs.md` | Protocol specification with RFC 2119 language |
 | **Schemas** | `schemas/v1/envelope.schema.json` | Envelope schema (Draft-07) with conditional pagination validation |
 | | `schemas/v1/context-ledger.schema.json` | Context ledger for state tracking across request/response cycles |
-| | `schemas/v1/error-registry.json` | 12 registered error codes with HTTP/gRPC/CLI transport mappings |
+| | `schemas/v1/discovery.schema.json` | Agent Card discovery schema |
+| | `schemas/v1/conformance-profiles.json` | Conformance tier definitions |
+| | `schemas/v1/error-registry.json` | 13 registered error codes with HTTP/gRPC/CLI transport mappings |
 | **Tooling** | `src/` | TypeScript validation, conformance runner, CLI diagnostic tool |
-| **A2A** | `src/a2a/` | Agent-to-Agent integration: extensions, task lifecycle, protocol bindings (JSON-RPC/HTTP/gRPC) |
-| **Tests** | `tests/` | Tests covering envelope, pagination, strict mode, error handling, A2A extensions, task lifecycle, bindings |
-| **Fixtures** | `fixtures/` | 14 JSON fixtures (valid + invalid) for conformance testing |
-| **Docs** | `docs/` | [GitBook documentation](https://codluv.gitbook.io/lafs/) with guides, SDK reference, and specs |
+| **A2A** | `src/a2a/` | Agent-to-Agent integration: extensions, task lifecycle, streaming, protocol bindings (JSON-RPC/HTTP/gRPC) |
+| **Tests** | `tests/` | 20 test suites covering envelope, pagination, strict mode, error handling, A2A extensions, task lifecycle, bindings |
+| **Fixtures** | `fixtures/` | 25 JSON fixtures (valid + invalid + agent workflow scenarios) for conformance testing |
+| **Docs** | `docs/` | Guides, SDK reference, architecture docs, and specs |
 
 ## Install
 
 ```bash
+# Inside the monorepo (pnpm workspace)
+pnpm add @cleocode/lafs
+
+# External consumers
 npm install @cleocode/lafs
+# or: yarn add @cleocode/lafs
 ```
 
 ## Usage
@@ -41,7 +47,7 @@ import {
   isRegisteredErrorCode,
 } from "@cleocode/lafs";
 
-// Build envelope with defaults
+// Build a success envelope
 const envelope = createEnvelope({
   success: true,
   result: { items: [] },
@@ -54,7 +60,7 @@ if (!validation.valid) {
   console.error(validation.errors);
 }
 
-// Parse envelope responses with one function
+// Parse envelope responses
 try {
   const parsed = parseLafsResponse(envelope);
   console.log(parsed);
@@ -69,26 +75,6 @@ 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
-# Run conformance checks on a fixture
-npm run conformance -- --envelope fixtures/valid-success-envelope.json
-
-# Run tests
-npm test
-
-# Type check
-npm run typecheck
-```
-
 ## Envelope structure
 
 ```json
@@ -115,17 +101,28 @@ npm run typecheck
 }
 ```
 
+### Envelope invariants
+
+- `$schema`, `_meta`, `success`, and `result` are always required.
+- `success: true` implies `error` is `null` (or absent).
+- `success: false` requires a non-null `error` object. `result` MAY be non-null on error envelopes -- this allows validation tools to include actionable data (e.g., suggested fixes) alongside error metadata.
+- Exactly one pagination mode (`cursor`, `offset`, `none`) with mode-specific required fields.
+- `strict: true` rejects additional properties; `strict: false` allows them.
+
 ## Key features
 
-- **Conditional pagination** — cursor, offset, and none modes with mode-specific required fields
-- **Strict/lenient mode** — `strict: true` rejects unknown properties; `strict: false` allows them
-- **MVI disclosure levels** — `minimal`, `standard`, `full`, `custom` control response verbosity
+- **Conditional pagination** -- cursor, offset, and none modes with mode-specific required fields
+- **Strict/lenient mode** -- `strict: true` rejects unknown properties; `strict: false` allows them
+- **MVI disclosure levels** -- `minimal`, `standard`, `full`, `custom` control response verbosity
 - **Field selection** (`_fields`) and **expansion** (`_expand`) request parameters
-- **Context ledger** — tracks state across request/response cycles with monotonic versioning
-- **Error registry** — 12 codes with category, retryability, and transport-specific status mappings
-- **Extension mechanism** — `_extensions` field for vendor metadata (`x-` prefix convention)
-- **Adoption tiers** — Core, Standard, Complete with progressive conformance requirements
-- **A2A integration** — Agent Card discovery, extension negotiation, task lifecycle management, protocol bindings
+- **Context ledger** -- tracks state across request/response cycles with monotonic versioning
+- **Error registry** -- 13 codes with category, retryability, agent action, and transport-specific status mappings
+- **Extension mechanism** -- `_extensions` field for vendor metadata (`x-` prefix convention)
+- **Adoption tiers** -- Core, Standard, Complete with progressive conformance requirements
+- **A2A integration** -- Agent Card discovery, extension negotiation, task lifecycle management, protocol bindings
+- **Operations and reliability** -- circuit breaker, health checks, graceful shutdown, budget enforcement, token estimation
+- **MCP adapter** -- wrap LAFS envelopes for Model Context Protocol tool responses
+- **Problem Details** -- RFC 9457 Problem Details generation from LAFS errors
 
 ## A2A Integration
 
@@ -150,7 +147,7 @@ import {
 } from "@cleocode/lafs/a2a";
 ```
 
-**Agent Card with LAFS extension** — use `autoIncludeLafsExtension` in discovery config:
+**Agent Card with LAFS extension** -- use `autoIncludeLafsExtension` in discovery config:
 
 ```typescript
 import { discoveryMiddleware } from "@cleocode/lafs/discovery";
@@ -167,6 +164,19 @@ app.use(discoveryMiddleware({
 import { getErrorCodeMapping } from "@cleocode/lafs/a2a/bindings";
 ```
 
+## CLI
+
+```bash
+# Run conformance checks on a fixture
+pnpm run conformance -- --envelope fixtures/valid-success-envelope.json
+
+# Run tests
+pnpm test
+
+# Type check
+pnpm run typecheck
+```
+
 ## Conformance checks
 
 | Check | Description | Tier |
@@ -187,48 +197,67 @@ lafs.md                          # Protocol specification
 schemas/v1/
   envelope.schema.json           # Envelope schema (Draft-07)
   context-ledger.schema.json     # Context ledger schema
-  error-registry.json            # Error code registry
+  discovery.schema.json          # Agent Card discovery schema
+  conformance-profiles.json      # Conformance tier definitions
+  agent-card.schema.json         # Agent Card schema
+  error-registry.json            # Error code registry (13 codes)
 src/
-  types.ts                       # TypeScript types (discriminated unions)
-  validateEnvelope.ts            # Ajv-based schema validator
-  conformance.ts                 # Conformance runner (8 checks)
-  errorRegistry.ts               # Error code helpers
-  flagSemantics.ts               # Format flag resolution
+  index.ts                       # Barrel export (all public API)
+  types.ts                       # Core types (LAFSEnvelope, LAFSError, etc.)
+  envelope.ts                    # createEnvelope(), parseLafsResponse(), LafsError
+  validateEnvelope.ts            # Schema validator (native Rust via napi-rs, AJV fallback)
+  conformance.ts                 # Conformance runner (runEnvelopeConformance)
+  conformanceProfiles.ts         # Tier-based conformance profile definitions
+  compliance.ts                  # Compliance pipeline utilities
+  errorRegistry.ts               # Error code helpers (getRegistryCode, isRegisteredErrorCode)
+  flagSemantics.ts               # Format flag resolution (--json / --human)
+  flagResolver.ts                # Flag resolution with config precedence
+  fieldExtraction.ts             # _fields / _expand parameter extraction
+  mviProjection.ts               # MVI disclosure level projection
+  tokenEstimator.ts              # Token budget estimation
+  budgetEnforcement.ts           # Token budget enforcement
+  problemDetails.ts              # RFC 9457 Problem Details from LAFS errors
+  deprecationRegistry.ts         # Deprecation tracking and warnings
+  native-loader.ts               # Lazy native Rust validator loader
   discovery.ts                   # A2A Agent Card discovery middleware
-  cli.ts                         # CLI diagnostic tool
+  cli.ts                         # CLI diagnostic tool (lafs-conformance)
+  health/index.ts                # Health check endpoint
+  circuit-breaker/index.ts       # Circuit breaker pattern
+  shutdown/index.ts              # Graceful shutdown handler
   a2a/
+    index.ts                     # A2A barrel export
     bridge.ts                    # A2A SDK integration & result wrapper
     extensions.ts                # Extension negotiation & LAFS extension builder
     task-lifecycle.ts            # Task state machine & lifecycle management
+    streaming.ts                 # SSE/streaming task event support
     bindings/
+      index.ts                   # Barrel export & cross-binding error mapping
       jsonrpc.ts                 # JSON-RPC 2.0 method/error constants & builders
       http.ts                    # HTTP endpoints, RFC 9457 Problem Details
       grpc.ts                    # gRPC status codes & service definitions (types only)
-      index.ts                   # Barrel export & cross-binding error mapping
-tests/                           # Tests (vitest)
-fixtures/                        # JSON test fixtures
-docs/
-  POSITIONING.md                 # MCP/A2A complementary positioning
-  VISION.md                      # Project vision and primary persona
-  CONFORMANCE.md                 # Conformance checks and adoption tiers
-migrations/
-  v0.3.0-to-v0.4.0.md           # Envelope rationalization migration
-  v0.4.0-to-v0.5.0.md           # Pagination & MVI schema migration
-CONTRIBUTING.md                  # Contributor guidelines, RFC process
+tests/                           # 20 test suites (vitest)
+fixtures/                        # 25 JSON fixtures (valid + invalid + agent workflows)
+docs/                            # Guides, architecture, SDK reference
+CONTRIBUTING.md                  # Contributor guidelines
 ```
 
 ## Version history
 
-| Version | Phase | Description |
-|---------|-------|-------------|
-| **v1.2.3** | **4** | **A2A v1.0+ compliance: extension negotiation, task lifecycle, protocol bindings (JSON-RPC/HTTP/gRPC)** |
-| v1.0.0 | 3 | Production release: Token budgets, agent discovery, MCP integration, complete SDKs |
-| v0.5.0 | 2B | Conditional pagination, MVI field selection/expansion, context ledger schema |
-| v0.4.0 | 2A | Optional page/error, extensions, strict/lenient mode, warnings |
-| v0.3.0 | 1 | Strategic positioning, vision alignment, adoption tiers |
-| v0.2.0 | 0 | Protocol cleanup, fixtures, governance, security considerations |
-| v0.1.1 | — | Initial npm publish |
-| v0.1.0 | — | Bootstrap |
+| Version | Description |
+|---------|-------------|
+| **2026.4.0** | CalVer adoption. Operations and reliability modules (circuit breaker, health, shutdown, budget enforcement). MCP adapter. Problem Details (RFC 9457). Streaming support. |
+| 1.8.0 | Error envelopes MAY include non-null `result` for actionable data alongside error metadata. |
+| 1.5.0 | Agent workflows fixtures. Deprecation registry. Field extraction. MVI projection. |
+| 1.2.3 | A2A v1.0+ compliance: extension negotiation, task lifecycle, protocol bindings (JSON-RPC/HTTP/gRPC). |
+| 1.0.0 | Production release: token budgets, agent discovery, MCP integration. |
+| 0.5.0 | Conditional pagination, MVI field selection/expansion, context ledger schema. |
+| 0.4.0 | Optional page/error, extensions, strict/lenient mode, warnings. |
+| 0.3.0 | Strategic positioning, vision alignment, adoption tiers. |
+| 0.1.0 | Initial release. |
+
+## Repository
+
+This package lives at [`packages/lafs`](https://github.com/kryptobaseddev/cleo/tree/main/packages/lafs) in the [kryptobaseddev/cleo](https://github.com/kryptobaseddev/cleo) monorepo.
 
 ## License
 

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

@@ -8,61 +8,167 @@
  * Reference: A2A spec Section 10.3-10.6
  */
 import type { A2AErrorType } from './jsonrpc.js';
-/** Standard gRPC status codes (numeric values 0-16) */
+/**
+ * Standard gRPC status codes (numeric values 0-16).
+ *
+ * @remarks
+ * Canonical gRPC status codes as defined in the gRPC specification.
+ * Used to map A2A errors to appropriate gRPC status values.
+ */
 export declare const GRPC_STATUS_CODE: {
+    /** Not an error; returned on success */
     readonly OK: 0;
+    /** The operation was cancelled by the caller */
     readonly CANCELLED: 1;
+    /** Unknown error */
     readonly UNKNOWN: 2;
+    /** Client specified an invalid argument */
     readonly INVALID_ARGUMENT: 3;
+    /** Deadline expired before operation could complete */
     readonly DEADLINE_EXCEEDED: 4;
+    /** Requested entity was not found */
     readonly NOT_FOUND: 5;
+    /** Entity already exists */
     readonly ALREADY_EXISTS: 6;
+    /** Caller does not have permission */
     readonly PERMISSION_DENIED: 7;
+    /** Resource has been exhausted (e.g. quota) */
     readonly RESOURCE_EXHAUSTED: 8;
+    /** Operation rejected because the system is not in a required state */
     readonly FAILED_PRECONDITION: 9;
+    /** The operation was aborted (e.g. concurrency conflict) */
     readonly ABORTED: 10;
+    /** Operation was attempted past the valid range */
     readonly OUT_OF_RANGE: 11;
+    /** Operation is not implemented or not supported */
     readonly UNIMPLEMENTED: 12;
+    /** Internal error */
     readonly INTERNAL: 13;
+    /** The service is currently unavailable */
     readonly UNAVAILABLE: 14;
+    /** Unrecoverable data loss or corruption */
     readonly DATA_LOSS: 15;
+    /** The request does not have valid authentication credentials */
     readonly UNAUTHENTICATED: 16;
 };
+/** Numeric gRPC status code value (0-16) */
 export type GrpcStatusCode = (typeof GRPC_STATUS_CODE)[keyof typeof GRPC_STATUS_CODE];
+/** String name of a gRPC status code (e.g. `"OK"`, `"NOT_FOUND"`) */
 export type GrpcStatusName = keyof typeof GRPC_STATUS_CODE;
-/** Maps A2A error types to gRPC status names */
+/**
+ * Maps A2A error types to gRPC status names.
+ *
+ * @remarks
+ * Used to determine the appropriate gRPC status code for each A2A error
+ * type per spec Section 5.4.
+ */
 export declare const A2A_GRPC_STATUS_CODES: Record<A2AErrorType, GrpcStatusName>;
-/** UPPER_SNAKE_CASE error reasons without "Error" suffix */
+/**
+ * UPPER_SNAKE_CASE error reasons without "Error" suffix.
+ *
+ * @remarks
+ * Used as the `reason` field in gRPC `google.rpc.ErrorInfo` details
+ * per spec Section 10.6.
+ */
 export declare const A2A_GRPC_ERROR_REASONS: Record<A2AErrorType, string>;
-/** Error domain for A2A gRPC errors */
+/**
+ * Error domain for A2A gRPC errors.
+ *
+ * @remarks
+ * Used as the `domain` field in `google.rpc.ErrorInfo` to identify
+ * the error source as the A2A protocol.
+ */
 export declare const A2A_GRPC_ERROR_DOMAIN: "a2a-protocol.org";
-/** gRPC service method descriptor */
+/**
+ * Descriptor for a single gRPC service method.
+ *
+ * @remarks
+ * Describes the Protobuf request/response message types and whether
+ * the method uses server-side streaming.
+ */
 export interface GrpcServiceMethod {
+    /** Protobuf request message type name */
     request: string;
+    /** Protobuf response message type name */
     response: string;
+    /** Whether the method uses server-side streaming */
     streaming: boolean;
 }
-/** gRPC service method definitions for the A2A protocol */
+/**
+ * gRPC service method definitions for the A2A protocol.
+ *
+ * @remarks
+ * Enumerates all RPC methods in the A2A gRPC service with their Protobuf
+ * message types and streaming mode per spec Section 10.3.
+ */
 export declare const GRPC_SERVICE_METHODS: Record<string, GrpcServiceMethod>;
-/** gRPC metadata key for A2A protocol version */
+/**
+ * gRPC metadata key for A2A protocol version.
+ *
+ * @remarks
+ * Sent as gRPC metadata to declare the A2A protocol version in use.
+ */
 export declare const GRPC_METADATA_VERSION_KEY: "a2a-version";
-/** gRPC metadata key for activated A2A extensions */
+/**
+ * gRPC metadata key for activated A2A extensions.
+ *
+ * @remarks
+ * Sent as gRPC metadata to declare which A2A extensions are active on the connection.
+ */
 export declare const GRPC_METADATA_EXTENSIONS_KEY: "a2a-extensions";
-/** gRPC Status object for A2A errors */
+/**
+ * gRPC Status object for A2A errors.
+ *
+ * @remarks
+ * Models the gRPC `Status` message with an optional `details` array
+ * containing `google.rpc.ErrorInfo` entries for rich error context.
+ */
 export interface GrpcStatus {
+    /** Numeric gRPC status code */
     code: GrpcStatusCode;
+    /** Human-readable error message */
     message: string;
+    /**
+     * Structured error details (typically `google.rpc.ErrorInfo` entries).
+     * @defaultValue undefined
+     */
     details?: GrpcErrorInfo[];
 }
-/** google.rpc.ErrorInfo equivalent */
+/**
+ * Equivalent of `google.rpc.ErrorInfo` for structured gRPC error details.
+ *
+ * @remarks
+ * Provides machine-readable error context including a reason code,
+ * error domain, and optional key-value metadata.
+ */
 export interface GrpcErrorInfo {
+    /** UPPER_SNAKE_CASE reason string identifying the error */
     reason: string;
+    /** Error domain (e.g. `"a2a-protocol.org"`) */
     domain: string;
+    /**
+     * Additional key-value metadata for the error.
+     * @defaultValue undefined
+     */
     metadata?: Record<string, string>;
 }
 /**
  * Create a gRPC Status object for an A2A error type.
- * Includes ErrorInfo details with reason and domain.
+ *
+ * @remarks
+ * Resolves the gRPC status code from the A2A error type mapping and
+ * attaches an `ErrorInfo` detail entry with the error reason and domain.
+ *
+ * @param errorType - The A2A error type name (e.g. `"TaskNotFound"`)
+ * @param message - Human-readable error message
+ * @param metadata - Optional key-value metadata to include in the ErrorInfo detail
+ * @returns A fully formed {@link GrpcStatus} object with ErrorInfo details
+ *
+ * @example
+ * ```ts
+ * const status = createGrpcStatus('TaskNotFound', 'No task with id xyz');
+ * // { code: 5, message: '...', details: [{ reason: 'TASK_NOT_FOUND', domain: 'a2a-protocol.org' }] }
+ * ```
  */
 export declare function createGrpcStatus(errorType: A2AErrorType, message: string, metadata?: Record<string, string>): GrpcStatus;
 //# sourceMappingURL=grpc.d.ts.map

package/dist/src/a2a/bindings/grpc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grpc.d.ts","sourceRoot":"","sources":["../../../../src/a2a/bindings/grpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAMjD,uDAAuD;AACvD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;CAkBnB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AACtF,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAM3D,gDAAgD;AAChD,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,YAAY,EAAE,cAAc,CAU7D,CAAC;AAMX,4DAA4D;AAC5D,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAUtD,CAAC;AAEX,uCAAuC;AACvC,eAAO,MAAM,qBAAqB,EAAG,kBAA2B,CAAC;AAMjE,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAwDzD,CAAC;AAMX,iDAAiD;AACjD,eAAO,MAAM,yBAAyB,EAAG,aAAsB,CAAC;AAEhE,qDAAqD;AACrD,eAAO,MAAM,4BAA4B,EAAG,gBAAyB,CAAC;AAMtE,wCAAwC;AACxC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,UAAU,CAeZ"}
+{"version":3,"file":"grpc.d.ts","sourceRoot":"","sources":["../../../../src/a2a/bindings/grpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAMjD;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;IAC3B,wCAAwC;;IAExC,gDAAgD;;IAEhD,oBAAoB;;IAEpB,2CAA2C;;IAE3C,uDAAuD;;IAEvD,qCAAqC;;IAErC,4BAA4B;;IAE5B,sCAAsC;;IAEtC,+CAA+C;;IAE/C,uEAAuE;;IAEvE,4DAA4D;;IAE5D,mDAAmD;;IAEnD,oDAAoD;;IAEpD,qBAAqB;;IAErB,2CAA2C;;IAE3C,4CAA4C;;IAE5C,iEAAiE;;CAEzD,CAAC;AAEX,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AACtF,qEAAqE;AACrE,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAM3D;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,YAAY,EAAE,cAAc,CAU7D,CAAC;AAMX;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAUtD,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAG,kBAA2B,CAAC;AAMjE;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAwDzD,CAAC;AAMX;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAG,aAAsB,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAG,gBAAyB,CAAC;AAMtE;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,IAAI,EAAE,cAAc,CAAC;IACrB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,UAAU,CAeZ"}

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

@@ -10,30 +10,59 @@
 // ============================================================================
 // gRPC Status Codes (standard)
 // ============================================================================
-/** Standard gRPC status codes (numeric values 0-16) */
+/**
+ * Standard gRPC status codes (numeric values 0-16).
+ *
+ * @remarks
+ * Canonical gRPC status codes as defined in the gRPC specification.
+ * Used to map A2A errors to appropriate gRPC status values.
+ */
 export const GRPC_STATUS_CODE = {
+    /** Not an error; returned on success */
     OK: 0,
+    /** The operation was cancelled by the caller */
     CANCELLED: 1,
+    /** Unknown error */
     UNKNOWN: 2,
+    /** Client specified an invalid argument */
     INVALID_ARGUMENT: 3,
+    /** Deadline expired before operation could complete */
     DEADLINE_EXCEEDED: 4,
+    /** Requested entity was not found */
     NOT_FOUND: 5,
+    /** Entity already exists */
     ALREADY_EXISTS: 6,
+    /** Caller does not have permission */
     PERMISSION_DENIED: 7,
+    /** Resource has been exhausted (e.g. quota) */
     RESOURCE_EXHAUSTED: 8,
+    /** Operation rejected because the system is not in a required state */
     FAILED_PRECONDITION: 9,
+    /** The operation was aborted (e.g. concurrency conflict) */
     ABORTED: 10,
+    /** Operation was attempted past the valid range */
     OUT_OF_RANGE: 11,
+    /** Operation is not implemented or not supported */
     UNIMPLEMENTED: 12,
+    /** Internal error */
     INTERNAL: 13,
+    /** The service is currently unavailable */
     UNAVAILABLE: 14,
+    /** Unrecoverable data loss or corruption */
     DATA_LOSS: 15,
+    /** The request does not have valid authentication credentials */
     UNAUTHENTICATED: 16,
 };
 // ============================================================================
 // A2A gRPC Status Mapping (spec Section 5.4)
 // ============================================================================
-/** Maps A2A error types to gRPC status names */
+/**
+ * Maps A2A error types to gRPC status names.
+ *
+ * @remarks
+ * Used to determine the appropriate gRPC status code for each A2A error
+ * type per spec Section 5.4.
+ */
 export const A2A_GRPC_STATUS_CODES = {
     TaskNotFound: 'NOT_FOUND',
     TaskNotCancelable: 'FAILED_PRECONDITION',
@@ -48,7 +77,13 @@ export const A2A_GRPC_STATUS_CODES = {
 // ============================================================================
 // Error Reasons (spec Section 10.6)
 // ============================================================================
-/** UPPER_SNAKE_CASE error reasons without "Error" suffix */
+/**
+ * UPPER_SNAKE_CASE error reasons without "Error" suffix.
+ *
+ * @remarks
+ * Used as the `reason` field in gRPC `google.rpc.ErrorInfo` details
+ * per spec Section 10.6.
+ */
 export const A2A_GRPC_ERROR_REASONS = {
     TaskNotFound: 'TASK_NOT_FOUND',
     TaskNotCancelable: 'TASK_NOT_CANCELABLE',
@@ -60,9 +95,21 @@ export const A2A_GRPC_ERROR_REASONS = {
     ExtensionSupportRequired: 'EXTENSION_SUPPORT_REQUIRED',
     VersionNotSupported: 'VERSION_NOT_SUPPORTED',
 };
-/** Error domain for A2A gRPC errors */
+/**
+ * Error domain for A2A gRPC errors.
+ *
+ * @remarks
+ * Used as the `domain` field in `google.rpc.ErrorInfo` to identify
+ * the error source as the A2A protocol.
+ */
 export const A2A_GRPC_ERROR_DOMAIN = 'a2a-protocol.org';
-/** gRPC service method definitions for the A2A protocol */
+/**
+ * gRPC service method definitions for the A2A protocol.
+ *
+ * @remarks
+ * Enumerates all RPC methods in the A2A gRPC service with their Protobuf
+ * message types and streaming mode per spec Section 10.3.
+ */
 export const GRPC_SERVICE_METHODS = {
     SendMessage: {
         request: 'MessageSendParams',
@@ -123,13 +170,37 @@ export const GRPC_SERVICE_METHODS = {
 // ============================================================================
 // gRPC Metadata Constants
 // ============================================================================
-/** gRPC metadata key for A2A protocol version */
+/**
+ * gRPC metadata key for A2A protocol version.
+ *
+ * @remarks
+ * Sent as gRPC metadata to declare the A2A protocol version in use.
+ */
 export const GRPC_METADATA_VERSION_KEY = 'a2a-version';
-/** gRPC metadata key for activated A2A extensions */
+/**
+ * gRPC metadata key for activated A2A extensions.
+ *
+ * @remarks
+ * Sent as gRPC metadata to declare which A2A extensions are active on the connection.
+ */
 export const GRPC_METADATA_EXTENSIONS_KEY = 'a2a-extensions';
 /**
  * Create a gRPC Status object for an A2A error type.
- * Includes ErrorInfo details with reason and domain.
+ *
+ * @remarks
+ * Resolves the gRPC status code from the A2A error type mapping and
+ * attaches an `ErrorInfo` detail entry with the error reason and domain.
+ *
+ * @param errorType - The A2A error type name (e.g. `"TaskNotFound"`)
+ * @param message - Human-readable error message
+ * @param metadata - Optional key-value metadata to include in the ErrorInfo detail
+ * @returns A fully formed {@link GrpcStatus} object with ErrorInfo details
+ *
+ * @example
+ * ```ts
+ * const status = createGrpcStatus('TaskNotFound', 'No task with id xyz');
+ * // { code: 5, message: '...', details: [{ reason: 'TASK_NOT_FOUND', domain: 'a2a-protocol.org' }] }
+ * ```
  */
 export function createGrpcStatus(errorType, message, metadata) {
     const statusName = A2A_GRPC_STATUS_CODES[errorType];

package/dist/src/a2a/bindings/grpc.js.map

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