LafsExtensionParams
LAFS extension parameters declared in Agent Card| Property | Type | Required | Description |
|---|---|---|---|
supportsContextLedger | boolean | Yes | Whether the agent supports context ledger tracking |
supportsTokenBudgets | boolean | Yes | Whether the agent supports token budget enforcement |
envelopeSchema | string | Yes | URL of the JSON Schema for the LAFS envelope |
kind | ExtensionKind | undefined | No | Classification of the extension’s behavior. |
ExtensionKind
Classification of an A2A extension’s behavior.ExtensionNegotiationResult
Result of extension negotiation between client and agent| Property | Type | Required | Description |
|---|---|---|---|
requested | string[] | Yes | URIs requested by the client |
activated | string[] | Yes | URIs that matched agent-declared extensions |
unsupported | string[] | Yes | Requested URIs not declared by the agent (ignored per spec) |
missingRequired | string[] | Yes | Agent-required URIs not present in client request |
activatedByKind | Partial<Record<ExtensionKind, string[]>> | Yes | Activated extensions grouped by declared kind (when provided) |
BuildLafsExtensionOptions
Options for building the LAFS extension declaration| Property | Type | Required | Description |
|---|---|---|---|
required | boolean | undefined | No | Whether the LAFS extension is required for all requests. |
supportsContextLedger | boolean | undefined | No | Whether the agent supports context ledger tracking. |
supportsTokenBudgets | boolean | undefined | No | Whether the agent supports token budget enforcement. |
envelopeSchema | string | undefined | No | URL of the JSON Schema for the LAFS envelope. |
BuildExtensionOptions
Options for building a generic A2A extension declaration| Property | Type | Required | Description |
|---|---|---|---|
uri | string | Yes | Canonical URI identifying the extension |
description | string | Yes | Human-readable description of what the extension provides |
required | boolean | undefined | No | Whether the extension is required for all requests. |
kind | ExtensionKind | Yes | Classification of the extension’s behavior |
params | Record<string, unknown> | undefined | No | Additional parameters to include in the extension declaration. |
ExtensionNegotiationMiddlewareOptions
Options for the extension negotiation middleware| Property | Type | Required | Description |
|---|---|---|---|
extensions | AgentExtension[] | Yes | Agent-declared extensions to negotiate against |
enforceRequired | boolean | undefined | No | Return 400 if required extensions are missing. |
AgentProvider
A2A Agent Provider information.| Property | Type | Required | Description |
|---|---|---|---|
url | string | Yes | Organization URL (must be a valid HTTPS URL) |
organization | string | Yes | Organization name (human-readable label) |
AgentCapabilities
A2A Agent Capabilities.| Property | Type | Required | Description |
|---|---|---|---|
streaming | boolean | undefined | No | Supports streaming responses. |
pushNotifications | boolean | undefined | No | Supports push notifications. |
extendedAgentCard | boolean | undefined | No | Supports extended agent card. |
extensions | AgentExtension[] | undefined | No | Supported extensions declared by this agent. |
AgentExtension
A2A Agent Extension declaration.| Property | Type | Required | Description |
|---|---|---|---|
uri | string | Yes | Extension URI (globally-unique identifier) |
description | string | Yes | Human-readable description of what the extension provides |
required | boolean | Yes | Whether the extension is required for interoperability |
params | Record<string, unknown> | undefined | No | Extension-specific parameters. |
AgentSkill
A2A Agent Skill.| Property | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Skill unique identifier (kebab-case recommended) |
name | string | Yes | Human-readable display name |
description | string | Yes | Detailed description of what the skill does |
tags | string[] | Yes | Keywords/tags for discovery and categorization |
examples | string[] | undefined | No | Example prompts that demonstrate typical usage. |
inputModes | string[] | undefined | No | Supported input modes (overrides agent-level AgentCard.defaultInputModes). |
outputModes | string[] | undefined | No | Supported output modes (overrides agent-level AgentCard.defaultOutputModes). |
SecurityScheme
Security scheme for authentication (OpenAPI 3.0 style).| Property | Type | Required | Description |
|---|---|---|---|
type | "http" | "apiKey" | "oauth2" | "openIdConnect" | Yes | Authentication type per OpenAPI 3.0 |
description | string | undefined | No | Human-readable description of the scheme. |
scheme | string | undefined | No | HTTP auth scheme name (e.g., "bearer"). |
bearerFormat | string | undefined | No | Bearer token format hint (e.g., "JWT"). |
AgentCard
A2A v1.0 Agent Card - Standard format for agent discovery.| Property | Type | Required | Description |
|---|---|---|---|
$schema | string | undefined | No | JSON Schema URL for validation. |
name | string | Yes | Human-readable agent name |
description | string | Yes | Detailed description of agent capabilities |
version | string | Yes | Agent version (SemVer) |
url | string | Yes | Base URL for A2A endpoints |
provider | AgentProvider | undefined | No | Service provider information. |
capabilities | AgentCapabilities | Yes | Agent capabilities declaration |
defaultInputModes | string[] | Yes | Supported input content types (MIME types) |
defaultOutputModes | string[] | Yes | Supported output content types (MIME types) |
skills | AgentSkill[] | Yes | Agent skills/capabilities for discovery |
securitySchemes | Record<string, SecurityScheme> | undefined | No | Security authentication schemes (keyed by scheme name). |
security | Record<string, string[]>[] | undefined | No | Required security scheme references (OpenAPI 3.0 format). |
documentationUrl | string | undefined | No | Documentation URL for the agent. |
iconUrl | string | undefined | No | Icon URL for the agent. |
Capability
Deprecated: Use AgentSkill instead.
Legacy capability descriptor.
| Property | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Capability name |
version | string | Yes | Capability version |
description | string | undefined | No | Human-readable description. |
operations | string[] | Yes | Supported operations |
optional | boolean | undefined | No | Whether this capability is optional. |
ServiceConfig
Deprecated: Use AgentCard instead.
Legacy service configuration.
| Property | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Service name |
version | string | Yes | Service version |
description | string | undefined | No | Human-readable description. |
EndpointConfig
Deprecated: Will be removed in v2.0.0.Legacy endpoint configuration.
| Property | Type | Required | Description |
|---|---|---|---|
envelope | string | Yes | Envelope endpoint URL |
context | string | undefined | No | Context endpoint URL. |
discovery | string | Yes | Discovery endpoint URL |
DiscoveryDocument
Deprecated: Use AgentCard instead.
Legacy discovery document format.
| Property | Type | Required | Description |
|---|---|---|---|
$schema | string | Yes | JSON Schema URL |
lafs_version | string | Yes | LAFS specification version |
service | ServiceConfig | Yes | Service configuration |
capabilities | Capability[] | Yes | Declared capabilities |
endpoints | EndpointConfig | Yes | Endpoint configuration |
DiscoveryConfig
Configuration for the discovery middleware (A2A v1.0 format).| Property | Type | Required | Description |
|---|---|---|---|
agent | Omit<AgentCard, "$schema"> | undefined | No | Agent information (required for A2A v1.0; omit only with legacy service). |
baseUrl | string | undefined | No | Base URL for constructing absolute URLs. |
cacheMaxAge | number | undefined | No | Cache duration in seconds. |
schemaUrl | string | undefined | No | Schema URL override. |
headers | Record<string, string> | undefined | No | Optional custom response headers. |
autoIncludeLafsExtension | boolean | { required?: boolean; supportsContextLedger?: boolean; supportsTokenBudgets?: boolean; } | undefined | No | Automatically include LAFS as an A2A extension in Agent Card. Pass true for defaults, or an object to customize parameters. |
service | ServiceConfig | undefined | No | Legacy service configuration. |
capabilities | Capability[] | undefined | No | Legacy capabilities list. |
endpoints | { envelope: string; context?: string; discovery?: string; } | undefined | No | Legacy endpoint URLs. |
lafsVersion | string | undefined | No | Legacy LAFS version override. |
DiscoveryMiddlewareOptions
Discovery middleware options.| Property | Type | Required | Description |
|---|---|---|---|
path | string | undefined | No | Primary path to serve Agent Card. |
legacyPath | string | undefined | No | Legacy path for backward compatibility. |
enableLegacyPath | boolean | undefined | No | Enable legacy path support. |
enableHead | boolean | undefined | No | Enable HEAD requests. |
enableEtag | boolean | undefined | No | Enable ETag caching. |
TokenEstimatorOptions
Configuration options for the token estimator.| Property | Type | Required | Description |
|---|---|---|---|
charsPerToken | number | undefined | No | Characters per token ratio. |
maxDepth | number | undefined | No | Maximum depth to traverse for circular reference detection. |
maxStringLength | number | undefined | No | Maximum string length to process for Unicode grapheme counting. |
LAFSTransport
Transport protocol used to deliver a LAFS envelope.LAFSErrorCategory
Classification category for a LAFS error.Warning
A non-fatal warning attached to a LAFS envelope’s_meta.warnings array.
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Machine-readable warning code (e.g. "W_DEPRECATED_FIELD"). |
message | string | Yes | Human-readable description of the warning. |
deprecated | string | undefined | No | Name of the deprecated field, parameter, or feature. |
replacement | string | undefined | No | Recommended replacement for the deprecated item. |
removeBy | string | undefined | No | Semver version or ISO date after which the deprecated item will be removed. |
MVILevel
Minimum Viable Information level controlling envelope verbosity.LAFSMeta
Metadata block (_meta) embedded in every LAFS envelope.
| Property | Type | Required | Description |
|---|---|---|---|
specVersion | string | Yes | Semantic version of the LAFS protocol specification (e.g. "1.0.0"). |
schemaVersion | string | Yes | Semantic version of the JSON Schema used for this envelope (e.g. "1.0.0"). |
timestamp | string | Yes | ISO 8601 timestamp of when the envelope was created. |
operation | string | Yes | Dot-delimited operation identifier (e.g. "tasks.list"). |
requestId | string | Yes | Unique identifier for correlating this request/response pair. |
transport | LAFSTransport | Yes | Transport protocol through which this envelope is delivered. |
strict | boolean | Yes | When true, schema validation rejects unknown properties. |
mvi | MVILevel | Yes | Minimum Viable Information level controlling field inclusion. |
contextVersion | number | Yes | Monotonically increasing version of the agent’s context ledger. |
sessionId | string | undefined | No | Session identifier for correlating multi-step agent workflows. |
warnings | Warning[] | undefined | No | Non-fatal warnings to surface to the consuming agent. |
LAFSAgentAction
Recommended action an LLM agent should take in response to an error.LAFSError
Structured error payload returned in a failing LAFS envelope.| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable, machine-readable error code (e.g. "E_NOT_FOUND"). |
message | string | Yes | Human-readable description of the error. |
category | LAFSErrorCategory | Yes | High-level classification of the error. |
retryable | boolean | Yes | Whether the operation can be retried without modification. |
retryAfterMs | number | null | Yes | Suggested delay in milliseconds before retrying, or null if not applicable. |
details | Record<string, unknown> | Yes | Arbitrary key-value pairs with additional context about the error. |
agentAction | LAFSAgentAction | undefined | No | Recommended action for the consuming agent to take. |
escalationRequired | boolean | undefined | No | When true, the error requires human intervention or a higher-privilege agent. |
suggestedAction | string | undefined | No | Free-text description of a suggested recovery action for the agent. |
docUrl | string | undefined | No | URL pointing to documentation about this error code. |
LAFSPageCursor
Cursor-based pagination metadata.| Property | Type | Required | Description |
|---|---|---|---|
mode | "cursor" | Yes | Discriminant identifying cursor-based pagination. |
nextCursor | string | null | Yes | Opaque cursor for fetching the next page, or null when at the end. |
hasMore | boolean | Yes | Whether additional pages exist beyond the current one. |
limit | number | undefined | No | Maximum number of items per page. |
total | number | null | undefined | No | Total number of items across all pages, or null if unknown. |
LAFSPageOffset
Offset-based pagination metadata.| Property | Type | Required | Description |
|---|---|---|---|
mode | "offset" | Yes | Discriminant identifying offset-based pagination. |
limit | number | Yes | Maximum number of items per page. |
offset | number | Yes | Zero-based index of the first item in this page. |
hasMore | boolean | Yes | Whether additional pages exist beyond the current one. |
total | number | null | undefined | No | Total number of items across all pages, or null if unknown. |
LAFSPageNone
Sentinel pagination mode indicating no pagination is applied.| Property | Type | Required | Description |
|---|---|---|---|
mode | "none" | Yes | Discriminant indicating no pagination. |
LAFSPage
Discriminated union of all supported pagination modes.ContextLedgerEntry
A single entry in the context ledger recording one state mutation.| Property | Type | Required | Description |
|---|---|---|---|
entryId | string | Yes | Unique identifier for this ledger entry. |
timestamp | string | Yes | ISO 8601 timestamp of when the mutation occurred. |
operation | string | Yes | Operation that produced this context change. |
contextDelta | Record<string, unknown> | Yes | Key-value delta describing the context fields that changed. |
requestId | string | undefined | No | Request identifier that triggered this entry, for tracing. |
ContextLedger
Append-only ledger tracking context mutations across agent interactions.| Property | Type | Required | Description |
|---|---|---|---|
ledgerId | string | Yes | Unique identifier for this ledger instance. |
version | number | Yes | Monotonically increasing version incremented on each mutation. |
createdAt | string | Yes | ISO 8601 timestamp of when the ledger was created. |
updatedAt | string | Yes | ISO 8601 timestamp of the most recent mutation. |
entries | ContextLedgerEntry[] | Yes | Ordered list of context mutations from oldest to newest. |
checksum | string | Yes | Integrity checksum of the current ledger state. |
maxEntries | number | Yes | Maximum number of entries retained before oldest entries are pruned. |
LAFSEnvelope
Top-level LAFS response envelope wrapping every operation result.| Property | Type | Required | Description |
|---|---|---|---|
$schema | "https://lafs.dev/schemas/v1/envelope.schema.json" | Yes | JSON Schema URL identifying the envelope schema version. |
_meta | LAFSMeta | Yes | Protocol and request metadata. |
success | boolean | Yes | Whether the operation completed successfully. |
result | Record<string, unknown> | Record<string, unknown>[] | null | Yes | Operation result payload, or null on failure. |
error | LAFSError | null | undefined | No | Structured error payload, or null on success. |
page | LAFSPage | null | undefined | No | Pagination metadata when the result is a paginated collection. |
_extensions | Record<string, unknown> | undefined | No | Vendor or protocol extension data keyed by extension identifier. |
FlagInput
Input parameters for resolving the output format via flag semantics.| Property | Type | Required | Description |
|---|---|---|---|
requestedFormat | "json" | "human" | undefined | No | Explicitly requested output format string. |
jsonFlag | boolean | undefined | No | Whether the --json CLI flag was provided. |
humanFlag | boolean | undefined | No | Whether the --human CLI flag was provided. |
projectDefault | "json" | "human" | undefined | No | Project-level default output format from configuration. |
userDefault | "json" | "human" | undefined | No | User-level default output format from configuration. |
tty | boolean | undefined | No | When true, indicates the output is connected to an interactive terminal. If no explicit format flag or project/user default is set, TTY terminals default to "human" format while non-TTY (piped, CI, agents) defaults to "json" per the LAFS protocol. CLI tools should pass process.stdout.isTTY ?? false here. |
quiet | boolean | undefined | No | Suppress non-essential output for scripting. When true, only essential data is returned. |
ConformanceReport
Result of a LAFS conformance test run.| Property | Type | Required | Description |
|---|---|---|---|
ok | boolean | Yes | true if all checks passed; false if any check failed. |
checks | { name: string; pass: boolean; detail?: string; }[] | No | Individual conformance check results. |
BudgetEnforcementOptions
Options controlling token-budget enforcement behaviour.TokenEstimate
Token-count estimate attached to a budget-aware envelope.| Property | Type | Required | Description |
|---|---|---|---|
estimated | number | Yes | Estimated token count of the envelope after any truncation. |
truncated | boolean | undefined | No | Whether the result was truncated to fit within the budget. |
originalEstimate | number | undefined | No | Original estimated token count before truncation, if truncation occurred. |
LAFSMetaWithBudget
Extended metadata block that includes an optional token-budget estimate.| Property | Type | Required | Description |
|---|---|---|---|
_tokenEstimate | TokenEstimate | undefined | No | Token-count estimate for budget tracking. |
LAFSEnvelopeWithBudget
LAFS envelope variant whose metadata includes token-budget estimates.| Property | Type | Required | Description |
|---|---|---|---|
_meta | LAFSMetaWithBudget | Yes | Metadata block extended with token-budget estimation. |
MiddlewareFunction
Middleware function that transforms a LAFS envelope.NextFunction
Continuation function passed toBudgetMiddleware to invoke the next middleware in the chain.
BudgetMiddleware
Middleware function for token-budget enforcement with chain delegation.BudgetEnforcementResult
Outcome of running budget enforcement on a LAFS envelope.| Property | Type | Required | Description |
|---|---|---|---|
envelope | LAFSEnvelope | Yes | The envelope after budget enforcement (possibly truncated). |
withinBudget | boolean | Yes | true if the estimated token count is within the allowed budget. |
estimatedTokens | number | Yes | Estimated token count of the final envelope. |
budget | number | Yes | Maximum allowed token count that was enforced. |
truncated | boolean | Yes | Whether the envelope’s result was truncated to fit the budget. |
ConformanceTier
Named conformance tier indicating the breadth of checks applied.ConformanceProfiles
Schema for the conformance-profiles JSON file.| Property | Type | Required | Description |
|---|---|---|---|
version | string | Yes | Semantic version of the conformance-profiles schema. |
tiers | Record<ConformanceTier, string[]> | Yes | Mapping from tier name to the ordered list of check names in that tier. |
RegistryCode
A single entry in the LAFS error-code registry.| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | The canonical LAFS error code (e.g., "E_FORMAT_CONFLICT"). |
category | string | Yes | Broad error category (e.g., "client", "server", "auth"). |
description | string | Yes | Human-readable description of when this error occurs. |
retryable | boolean | Yes | Whether the operation that produced this error is safe to retry. |
httpStatus | number | Yes | HTTP status code mapped to this error. |
grpcStatus | string | Yes | gRPC status string mapped to this error. |
cliExit | number | Yes | CLI exit code mapped to this error. |
agentAction | string | undefined | No | Suggested agent action from the registry (e.g., "retry", "abort"). |
typeUri | string | undefined | No | RFC 9457 type URI for this error, used in Problem Details responses. |
docUrl | string | undefined | No | URL pointing to human-readable documentation for this error. |
ErrorRegistry
Top-level shape of the LAFS error-registry JSON file.| Property | Type | Required | Description |
|---|---|---|---|
version | string | Yes | Semantic version of the error-registry schema. |
codes | RegistryCode[] | Yes | All registered LAFS error codes. |
TransportMapping
A transport-specific status value resolved from the error registry.FlagResolution
Result of resolving output format flags.| Property | Type | Required | Description |
|---|---|---|---|
format | "json" | "human" | Yes | The resolved output format: 'json' for machine-readable or 'human' for human-readable. |
source | "project" | "default" | "flag" | "user" | Yes | Which configuration layer determined the format value. |
quiet | boolean | Yes | When true, suppress non-essential output for scripting. |
NativeValidationResult
Shape of the validation result from the native binding.| Property | Type | Required | Description |
|---|---|---|---|
valid | boolean | Yes | Whether the envelope conforms to the schema. |
errors | string[] | Yes | Flattened human-readable error messages. |
structuredErrors | NativeValidationError[] | Yes | Structured error objects. |
StructuredValidationError
Structured representation of a single schema validation error.| Property | Type | Required | Description |
|---|---|---|---|
path | string | Yes | JSON Pointer path to the property that failed validation (e.g., "/_meta/mvi"). |
keyword | string | Yes | The JSON Schema keyword that triggered the error (e.g., "required", "type"). |
message | string | Yes | Human-readable description of the validation failure. |
params | Record<string, unknown> | Yes | Keyword-specific parameters (e.g., { missingProperty: "success" }). |
EnvelopeValidationResult
Result of validating a value against the LAFS envelope JSON Schema.| Property | Type | Required | Description |
|---|---|---|---|
valid | boolean | Yes | True when the input fully conforms to the envelope schema. |
errors | string[] | Yes | Flattened human-readable error messages (empty when valid). |
structuredErrors | StructuredValidationError[] | Yes | Structured error objects with path, keyword, and params (empty when valid). |
EnvelopeConformanceOptions
Options for configuring envelope conformance checking.| Property | Type | Required | Description |
|---|---|---|---|
tier | ConformanceTier | undefined | No | The conformance tier to filter checks by. |
ComplianceStage
Identifies which stage of the compliance pipeline produced an issue.ComplianceIssue
Describes a single compliance failure detected during enforcement.| Property | Type | Required | Description |
|---|---|---|---|
stage | ComplianceStage | Yes | The pipeline stage that produced this issue. |
message | string | Yes | A short, human-readable description of the failure. |
detail | string | undefined | No | Additional diagnostic information about the failure. |
EnforceComplianceOptions
Options controlling which compliance stages are executed.| Property | Type | Required | Description |
|---|---|---|---|
checkConformance | boolean | undefined | No | Whether to run envelope conformance checks after schema validation. |
checkFlags | boolean | undefined | No | Whether to run flag conformance checks. |
flags | FlagInput | undefined | No | Flag input to validate when checkFlags is enabled. |
requireJsonOutput | boolean | undefined | No | When true, asserts that the resolved output format is JSON. |
ComplianceResult
Aggregated result of a full LAFS compliance run.| Property | Type | Required | Description |
|---|---|---|---|
ok | boolean | Yes | True when every executed stage passes with zero issues. |
envelope | LAFSEnvelope | undefined | No | The parsed envelope, present only when schema validation succeeds. |
validation | EnvelopeValidationResult | Yes | Schema validation result from the native validator (or AJV fallback). |
envelopeConformance | ConformanceReport | undefined | No | Envelope conformance report, present when EnforceComplianceOptions.checkConformance is true. |
flagConformance | ConformanceReport | undefined | No | Flag conformance report, present when EnforceComplianceOptions.checkFlags is true. |
issues | ComplianceIssue[] | Yes | All issues collected across every executed stage. |
ComplianceMiddleware
Middleware signature for intercepting LAFS envelopes in a pipeline.DeprecationEntry
A single deprecation rule in the registry.| Property | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Unique identifier for this deprecation rule |
code | string | Yes | Warning code emitted when detected |
message | string | Yes | Human-readable deprecation message |
deprecated | string | Yes | Version where the feature was deprecated |
replacement | string | undefined | No | Suggested replacement or migration path. |
removeBy | string | Yes | Version where the deprecated feature will be removed |
detector | (envelope: LAFSEnvelope) => boolean | Yes | Predicate that returns true when the envelope uses the deprecated feature |
CreateEnvelopeMetaInput
Input for constructing the_meta block of a LAFS envelope.
| Property | Type | Required | Description |
|---|---|---|---|
operation | string | Yes | Dot-delimited operation identifier (e.g. "tasks.list"). |
requestId | string | Yes | Unique identifier for correlating this request/response pair. |
transport | LAFSTransport | undefined | No | Transport protocol for this envelope. |
specVersion | string | undefined | No | LAFS spec version to stamp on the envelope. |
schemaVersion | string | undefined | No | JSON Schema version to stamp on the envelope. |
timestamp | string | undefined | No | ISO 8601 timestamp; auto-generated when omitted. |
strict | boolean | undefined | No | Whether strict schema validation should be applied. |
mvi | boolean | MVILevel | undefined | No | MVI level as a string, or true for 'minimal' / false for 'standard'. |
contextVersion | number | undefined | No | Context ledger version the caller is operating against. |
sessionId | string | undefined | No | Session identifier for multi-step workflow correlation. |
warnings | import("/mnt/projects/cleocode/packages/lafs/src/types").Warning[] | undefined | No | Non-fatal warnings to attach to the envelope metadata. |
CreateEnvelopeSuccessInput
Input for creating a successful LAFS envelope.| Property | Type | Required | Description |
|---|---|---|---|
success | true | Yes | Discriminant marking this as a success input. |
result | Record<string, unknown> | Record<string, unknown>[] | null | Yes | Operation result payload (object, array, or null). |
page | import("/mnt/projects/cleocode/packages/lafs/src/types").LAFSPage | null | undefined | No | Pagination metadata for collection results. |
error | null | undefined | No | Must be null for success inputs; exists for type uniformity with error inputs. |
_extensions | Record<string, unknown> | undefined | No | Vendor or protocol extension data. |
meta | CreateEnvelopeMetaInput | Yes | Metadata input for constructing the envelope’s _meta block. |
CreateEnvelopeErrorInput
Input for creating a failing LAFS envelope.| Property | Type | Required | Description |
|---|---|---|---|
success | false | Yes | Discriminant marking this as an error input. |
error | Partial<LAFSError> & Pick<LAFSError, "message" | "code"> | Yes | Partial error object; at minimum code and message are required. |
result | Record<string, unknown> | Record<string, unknown>[] | null | undefined | No | Optional result payload to include alongside the error. For validation tools (linters, type checkers), the actionable data (what to fix, suggested fixes) IS the result even when the operation “fails”. Setting this allows agents to access both the error metadata and the detailed result in a single response. When omitted or null, the envelope emits result: null (default behavior). |
page | import("/mnt/projects/cleocode/packages/lafs/src/types").LAFSPage | null | undefined | No | Pagination metadata, if applicable even in error scenarios. |
_extensions | Record<string, unknown> | undefined | No | Vendor or protocol extension data. |
meta | CreateEnvelopeMetaInput | Yes | Metadata input for constructing the envelope’s _meta block. |
CreateEnvelopeInput
Discriminated union of success and error inputs forcreateEnvelope.
ParseLafsResponseOptions
Options forparseLafsResponse.
| Property | Type | Required | Description |
|---|---|---|---|
requireRegisteredErrorCode | boolean | undefined | No | When true, unregistered error codes cause an additional Error to be thrown instead of the normal LafsError. |
FieldExtractionInput
Input flags for the field extraction layer.| Property | Type | Required | Description |
|---|---|---|---|
fieldFlag | string | undefined | No | --field <name>: extract a single field as plain text, discarding the envelope. |
fieldsFlag | string | string[] | undefined | No | --fields <a,b,c>: filter result to these fields while preserving the envelope. Accepts a comma-separated string or an array of field names. |
mviFlag | string | undefined | No | --mvi <level>: requested envelope verbosity level (client-requestable levels only). The 'custom' level is server-set and not valid here. |
FieldExtractionResolution
Resolved field extraction configuration.| Property | Type | Required | Description |
|---|---|---|---|
field | string | undefined | No | When set, extract this field as plain text, discarding the envelope. |
fields | string[] | undefined | No | When set, filter the result to these fields (envelope is preserved). |
mvi | MVILevel | Yes | Resolved MVI level. Falls back to 'minimal' when no valid flag is provided. |
mviSource | "default" | "flag" | Yes | Which input determined the mvi value: 'flag' when mviFlag was valid, 'default' otherwise. |
expectsCustomMvi | boolean | Yes | True when fields are requested, indicating the server SHOULD set _meta.mvi = 'custom' in the response per section 9.1. Separate from the client-resolved mvi level. |
UnifiedFlagInput
Combined input for both format and field extraction layers.| Property | Type | Required | Description |
|---|---|---|---|
human | boolean | undefined | No | Request human-readable output (--human flag). |
json | boolean | undefined | No | Request JSON output (--json flag). |
quiet | boolean | undefined | No | Suppress non-essential output for scripting (--quiet flag). |
requestedFormat | "json" | "human" | undefined | No | Explicit format override, taking highest precedence in the format layer. |
projectDefault | "json" | "human" | undefined | No | Project-level default format from configuration. |
userDefault | "json" | "human" | undefined | No | User-level default format from configuration. |
tty | boolean | undefined | No | TTY detection hint. When true, defaults to human format if no explicit format flag or project/user default is set. CLI tools should pass process.stdout.isTTY ?? false. |
field | string | undefined | No | Extract a single field as plain text, discarding the envelope (--field flag). |
fields | string | string[] | undefined | No | Filter result to these fields while preserving the envelope (--fields flag). Accepts a comma-separated string or an array of field names. |
mvi | string | undefined | No | Requested MVI verbosity level (--mvi flag). |
UnifiedFlagResolution
Combined resolution result with cross-layer warnings.| Property | Type | Required | Description |
|---|---|---|---|
format | FlagResolution | Yes | Resolved format layer from the format precedence chain. |
fields | FieldExtractionResolution | Yes | Resolved field extraction layer from field/fields/mvi flags. |
warnings | string[] | Yes | Warnings for cross-layer interactions (non-fatal, informational only). |
LafsA2AConfig
Configuration for LAFS A2A integration.| Property | Type | Required | Description |
|---|---|---|---|
defaultBudget | { maxTokens?: number; maxItems?: number; maxBytes?: number; } | undefined | No | Default token budget for all operations. |
envelopeResponses | boolean | undefined | No | Whether to automatically wrap responses in LAFS envelopes. |
protocolVersion | string | undefined | No | A2A protocol version to use. |
defaultExtensions | string[] | undefined | No | Extension URIs to activate for all requests. |
LafsSendMessageParams
Request parameters for sending messages.| Property | Type | Required | Description |
|---|---|---|---|
message | { role: "user" | "agent"; parts: Part[]; metadata?: Record<string, unknown>; } | No | Message content including role, parts, and optional metadata |
configuration | MessageSendConfiguration | undefined | No | A2A configuration for this request. |
budget | { maxTokens?: number; maxItems?: number; maxBytes?: number; } | undefined | No | Token budget override for this request. |
extensions | string[] | undefined | No | Extensions to activate for this request. |
contextId | string | undefined | No | Context ID for multi-turn conversations. |
taskId | string | undefined | No | Task ID for continuing existing task. |
CreateTaskOptions
Options for creating a new task| Property | Type | Required | Description |
|---|---|---|---|
contextId | string | undefined | No | Context ID for grouping related tasks. |
metadata | Record<string, unknown> | undefined | No | Arbitrary metadata to attach to the task. |
referenceTaskIds | string[] | undefined | No | IDs of parent tasks this task refines or follows up on. |
parallelFollowUp | boolean | undefined | No | Whether this follow-up can run in parallel with its references. |
ListTasksOptions
Options for listing tasks| Property | Type | Required | Description |
|---|---|---|---|
contextId | string | undefined | No | Filter tasks by context ID. |
state | TaskState | undefined | No | Filter tasks by current state. |
limit | number | undefined | No | Maximum number of tasks to return. |
pageToken | string | undefined | No | Cursor token for pagination (last seen task ID). |
ListTasksResult
Paginated result from listTasks| Property | Type | Required | Description |
|---|---|---|---|
tasks | Task[] | Yes | Array of tasks matching the query |
nextPageToken | string | undefined | No | Token for fetching the next page of results. |
TaskStreamEvent
Union type of task stream events emitted by the event bus.StreamIteratorOptions
Options for the stream task events async iterator| Property | Type | Required | Description |
|---|---|---|---|
timeoutMs | number | undefined | No | Timeout in milliseconds before the iterator yields control. |
PushNotificationDeliveryResult
Result of delivering a push notification to a single webhook| Property | Type | Required | Description |
|---|---|---|---|
configId | string | Yes | Identifier of the config that was dispatched to |
ok | boolean | Yes | Whether the delivery succeeded |
status | number | undefined | No | HTTP status code from the webhook response. |
error | string | undefined | No | Error message if delivery failed. |
PushTransport
Transport function for sending HTTP requests to push-notification webhooks.JsonRpcMethod
Union of all valid JSON-RPC method string values fromJSONRPC_METHODS
A2AErrorType
Union of A2A error type key names fromJSONRPC_A2A_ERROR_CODES
JsonRpcRequest
A JSON-RPC 2.0 request object.| Property | Type | Required | Description |
|---|---|---|---|
jsonrpc | "2.0" | Yes | JSON-RPC protocol version, always "2.0" |
id | string | number | Yes | Client-assigned request identifier |
method | string | Yes | The RPC method name to invoke |
params | Record<string, unknown> | undefined | No | Named parameters for the method call. |
JsonRpcResponse
A JSON-RPC 2.0 success response object.| Property | Type | Required | Description |
|---|---|---|---|
jsonrpc | "2.0" | Yes | JSON-RPC protocol version, always "2.0" |
id | string | number | null | Yes | Identifier matching the originating request, or null for notifications |
result | unknown | Yes | The return value of the invoked method |
JsonRpcErrorResponse
A JSON-RPC 2.0 error response object.| Property | Type | Required | Description |
|---|---|---|---|
jsonrpc | "2.0" | Yes | JSON-RPC protocol version, always "2.0" |
id | string | number | null | Yes | Identifier matching the originating request, or null for notifications |
error | { code: number; message: string; data?: Record<string, unknown>; } | No | Error descriptor containing code, message, and optional data |
GrpcStatusCode
Numeric gRPC status code value (0-16)GrpcStatusName
String name of a gRPC status code (e.g."OK", "NOT_FOUND")
GrpcServiceMethod
Descriptor for a single gRPC service method.| Property | Type | Required | Description |
|---|---|---|---|
request | string | Yes | Protobuf request message type name |
response | string | Yes | Protobuf response message type name |
streaming | boolean | Yes | Whether the method uses server-side streaming |
GrpcStatus
gRPC Status object for A2A errors.| Property | Type | Required | Description |
|---|---|---|---|
code | GrpcStatusCode | Yes | Numeric gRPC status code |
message | string | Yes | Human-readable error message |
details | GrpcErrorInfo[] | undefined | No | Structured error details (typically google.rpc.ErrorInfo entries). |
GrpcErrorInfo
Equivalent ofgoogle.rpc.ErrorInfo for structured gRPC error details.
| Property | Type | Required | Description |
|---|---|---|---|
reason | string | Yes | UPPER_SNAKE_CASE reason string identifying the error |
domain | string | Yes | Error domain (e.g. "a2a-protocol.org") |
metadata | Record<string, string> | undefined | No | Additional key-value metadata for the error. |
HttpEndpoint
Union of all HTTP endpoint descriptor objects fromHTTP_ENDPOINTS
ProblemDetails
RFC 9457 Problem Details object.| Property | Type | Required | Description |
|---|---|---|---|
type | string | Yes | URI reference identifying the problem type |
title | string | Yes | Short human-readable summary of the problem |
status | number | Yes | HTTP status code for this occurrence |
detail | string | Yes | Human-readable explanation specific to this occurrence |
ListTasksQueryParams
Parsed query parameters for the ListTasks endpoint.| Property | Type | Required | Description |
|---|---|---|---|
contextId | string | undefined | No | Filter tasks by context identifier. |
state | string | undefined | No | Filter tasks by state (e.g. "submitted", "working"). |
limit | number | undefined | No | Maximum number of tasks to return. |
pageToken | string | undefined | No | Pagination token from a previous response. |
ErrorCodeMapping
Complete error code mapping across all three transports.| Property | Type | Required | Description |
|---|---|---|---|
jsonRpcCode | number | Yes | JSON-RPC numeric error code (e.g. -32001) |
httpStatus | number | Yes | HTTP response status code (e.g. 404) |
httpTypeUri | string | Yes | RFC 9457 Problem Details type URI |
grpcStatus | string | Yes | gRPC status name (e.g. "NOT_FOUND") |
grpcCode | number | Yes | gRPC numeric status code (e.g. 5) |
CircuitState
Represents the three possible states of a circuit breaker.CircuitBreakerConfig
Configuration options for aCircuitBreaker instance.
| Property | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Unique identifier for this circuit breaker, used in log messages and metrics. |
failureThreshold | number | undefined | No | Number of failures required to trip the circuit from CLOSED to OPEN. |
resetTimeout | number | undefined | No | Milliseconds to wait before transitioning from OPEN to HALF_OPEN. |
halfOpenMaxCalls | number | undefined | No | Maximum number of trial calls allowed while in the HALF_OPEN state. |
successThreshold | number | undefined | No | Consecutive successes required in HALF_OPEN to close the circuit. |
CircuitBreakerMetrics
Snapshot of runtime metrics for aCircuitBreaker.
| Property | Type | Required | Description |
|---|---|---|---|
state | CircuitState | Yes | Current state of the circuit breaker. |
failures | number | Yes | Total number of recorded failures since the last reset. |
successes | number | Yes | Total number of recorded successes since the last reset. |
lastFailureTime | Date | undefined | No | Timestamp of the most recent failure, if any. |
consecutiveSuccesses | number | Yes | Number of consecutive successes since the last failure. |
totalCalls | number | Yes | Total number of calls made through this circuit breaker. |
HealthCheckConfig
Configuration for thehealthCheck middleware.
| Property | Type | Required | Description |
|---|---|---|---|
path | string | undefined | No | URL path at which the health endpoint is mounted. |
checks | HealthCheckFunction[] | undefined | No | Array of custom health check functions to run on each request. |
HealthCheckFunction
A function that performs a single health check.HealthCheckResult
Result of an individual health check.| Property | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Human-readable name identifying this check. |
status | "error" | "warning" | "ok" | Yes | Outcome status of the check. |
message | string | undefined | No | Optional descriptive message providing additional detail. |
duration | number | undefined | No | Execution duration of the check in milliseconds. |
HealthStatus
Aggregated health status returned by the health endpoint.| Property | Type | Required | Description |
|---|---|---|---|
status | "healthy" | "degraded" | "unhealthy" | Yes | Overall service health derived from individual check results. |
timestamp | string | Yes | ISO-8601 timestamp of when the health check was performed. |
version | string | Yes | LAFS package version. |
uptime | number | Yes | Server uptime in seconds since the middleware was initialised. |
checks | HealthCheckResult[] | Yes | Individual check results. |
LafsProblemDetails
RFC 9457 Problem Details with LAFS extensions.| Property | Type | Required | Description |
|---|---|---|---|
type | string | Yes | URI reference identifying the problem type |
title | string | Yes | Short human-readable summary (typically the error code) |
status | number | Yes | HTTP status code for this error |
detail | string | Yes | Human-readable explanation of the specific occurrence |
instance | string | undefined | No | URI reference identifying the specific occurrence (typically the request ID). |
retryable | boolean | Yes | Whether the operation that caused this error can be retried |
agentAction | string | undefined | No | Recommended agent action (e.g., "retry", "escalate"). |
retryAfterMs | number | undefined | No | Suggested delay in milliseconds before retrying. |
escalationRequired | boolean | undefined | No | Whether the error requires human escalation. |
suggestedAction | string | undefined | No | Human-readable suggestion for resolving the error. |
docUrl | string | undefined | No | Documentation URL for more information. |
GracefulShutdownConfig
Configuration for thegracefulShutdown handler.
| Property | Type | Required | Description |
|---|---|---|---|
timeout | number | undefined | No | Maximum time in milliseconds to wait for in-flight requests before forcing exit. |
signals | NodeJS.Signals[] | undefined | No | POSIX signals that trigger a graceful shutdown. |
onShutdown | (() => Promise<void> | void) | undefined | No | Callback invoked at the start of shutdown, before the server stops accepting connections. |
onClose | (() => Promise<void> | void) | undefined | No | Callback invoked after all connections have closed (or the timeout elapsed). |
ShutdownState
Snapshot of the current shutdown state.| Property | Type | Required | Description |
|---|---|---|---|
isShuttingDown | boolean | Yes | Whether a shutdown sequence is currently in progress. |
activeConnections | number | Yes | Number of TCP connections still open. |
shutdownStartTime | Date | undefined | No | Timestamp when the shutdown sequence began. |