> ## Documentation Index > Fetch the complete documentation index at: https://codluv.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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. ```typescript theme={null} 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>` | 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 \| 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 \| 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 \| undefined` | No | Security authentication schemes (keyed by scheme name). | | `security` | `Record[] \| 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 \| 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 \| 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. ```typescript theme={null} LAFSTransport ``` ## LAFSErrorCategory Classification category for a LAFS error. ```typescript theme={null} 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. ```typescript theme={null} 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. ```typescript theme={null} 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` | 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. ```typescript theme={null} 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` | 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 \| Record[] \| 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 \| 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. ```typescript theme={null} 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. ```typescript theme={null} MiddlewareFunction ``` ## NextFunction Continuation function passed to `BudgetMiddleware` to invoke the next middleware in the chain. ```typescript theme={null} NextFunction ``` ## BudgetMiddleware Middleware function for token-budget enforcement with chain delegation. ```typescript theme={null} 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. ```typescript theme={null} 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` | 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. ```typescript theme={null} 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` | 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. ```typescript theme={null} 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. ```typescript theme={null} 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 \| Record[] \| 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 \| 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 & Pick` | Yes | Partial error object; at minimum `code` and `message` are required. | | `result` | `Record \| Record[] \| 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 \| 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`. ```typescript theme={null} 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 `: extract a single field as plain text, discarding the envelope. | | `fieldsFlag` | `string \| string[] \| undefined` | No | `--fields `: 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 `: 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; }` | 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 \| 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. ```typescript theme={null} 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. ```typescript theme={null} PushTransport ``` ## JsonRpcMethod Union of all valid JSON-RPC method string values from `JSONRPC_METHODS` ```typescript theme={null} JsonRpcMethod ``` ## A2AErrorType Union of A2A error type key names from `JSONRPC_A2A_ERROR_CODES` ```typescript theme={null} "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 \| 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; }` | No | Error descriptor containing code, message, and optional data | ## GrpcStatusCode Numeric gRPC status code value (0-16) ```typescript theme={null} GrpcStatusCode ``` ## GrpcStatusName String name of a gRPC status code (e.g. `"OK"`, `"NOT_FOUND"`) ```typescript theme={null} "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 \| undefined` | No | Additional key-value metadata for the error. | ## HttpEndpoint Union of all HTTP endpoint descriptor objects from `HTTP_ENDPOINTS` ```typescript theme={null} 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. ```typescript theme={null} 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. ```typescript theme={null} 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) \| undefined` | No | Callback invoked at the start of shutdown, before the server stops accepting connections. | | `onClose` | `(() => Promise \| 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. |