lafs — Types

Type contracts for the lafs package

Type contracts exported by this package: interfaces, type aliases, and enums.

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.

ExtensionKind

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.

LAFSTransport

LAFSErrorCategory

Classification category for a LAFS error.

LAFSErrorCategory

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.

MVILevel

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.

LAFSAgentAction

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.

LAFSPage

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.

BudgetEnforcementOptions

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.

MiddlewareFunction

NextFunction

Continuation function passed to BudgetMiddleware to invoke the next middleware in the chain.

NextFunction

BudgetMiddleware

Middleware function for token-budget enforcement with chain delegation.

BudgetMiddleware

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.

ConformanceTier

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.

TransportMapping

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.

ComplianceStage

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.

ComplianceMiddleware

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 for createEnvelope.

CreateEnvelopeInput

ParseLafsResponseOptions

Options for parseLafsResponse.

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.

TaskStreamEvent

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.

PushTransport

JsonRpcMethod

Union of all valid JSON-RPC method string values from JSONRPC_METHODS

JsonRpcMethod

A2AErrorType

Union of A2A error type key names from JSONRPC_A2A_ERROR_CODES

"TaskNotFound" | "TaskNotCancelable" | "PushNotificationNotSupported" | "UnsupportedOperation" | "ContentTypeNotSupported" | "InvalidAgentResponse" | "AuthenticatedExtendedCardNotConfigured" | "ExtensionSupportRequired" | "VersionNotSupported"

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)

GrpcStatusCode

GrpcStatusName

String name of a gRPC status code (e.g. "OK", "NOT_FOUND")

"NOT_FOUND" | "INTERNAL" | "FAILED_PRECONDITION" | "INVALID_ARGUMENT" | "ABORTED" | "RESOURCE_EXHAUSTED" | "UNAVAILABLE" | "OK" | "CANCELLED" | "UNKNOWN" | "DEADLINE_EXCEEDED" | "ALREADY_EXISTS" | "PERMISSION_DENIED" | "OUT_OF_RANGE" | "UNIMPLEMENTED" | "DATA_LOSS" | "UNAUTHENTICATED"

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 of google.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 from HTTP_ENDPOINTS

HttpEndpoint

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.

CircuitState

CircuitBreakerConfig

Configuration options for a CircuitBreaker 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 a CircuitBreaker.

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 the healthCheck 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.

HealthCheckFunction

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 the gracefulShutdown 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.