Interface: AdapterDefinitionContract<TAdapter, TOptions>

Makaio Framework / contracts / AdapterDefinitionContract

Interface: AdapterDefinitionContract<TAdapter, TOptions>

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:112

Runtime contract for an adapter contributed by an extension.

Contains all fields needed by the AdapterSubsystemService to register, initialize, and manage the adapter lifecycle. The generic type parameters allow higher-level adapter types (e.g., AIAdapterDefinition) to narrow both the return type of createAdapter and the options it accepts, without violating TypeScript’s contravariant parameter-type rules.

This interface is not Zod-validatable because it contains functions and Zod schemas as values. The serializable counterpart is AdapterManifest.

Extended by

AIAdapterDefinition

Type Parameters

TAdapter

TAdapter = unknown

Concrete adapter instance type returned by createAdapter. Defaults to unknown so the contract is usable without a type parameter.

TOptions

TOptions = never

Options type accepted by createAdapter. Defaults to never so the type-erased base contract (AdapterContribution.definition) is structurally compatible with any specialised definition via contravariance: (options?: ConcreteOptions) => Promise<T> is assignable to (options?: never) => Promise<T>. Specialised adapter interfaces (e.g. AIAdapterDefinition) pass a narrower options type here to gain compile-time safety in their factory signatures.

Properties

adapterConfigSchema?

readonly optional adapterConfigSchema?: ZodObject<Readonly<{[k: string]: $ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; }>, $strip>

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:136

Zod schema for adapter-level configuration.

Used by the settings.adapter.getConfigSchema bus handler to generate JSON Schema for UI form rendering. Currently a seam — no adapter populates this yet, but it is correctly placed on the definition contract for future adapter-level configuration UI.

clientId?

readonly optional clientId?: string

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:188

Client identifier this adapter delegates to (e.g., 'claude-code').

References a ClientManifest.id declared on the executable AdapterContribution.manifest; descriptor contributions may mirror it for discovery but are not the runtime wiring source.

createAdapter

readonly createAdapter: (options?) => Promise<TAdapter>

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:206

Factory that creates the adapter instance.

Called by the subsystem after all configuration is resolved. The options parameter receives merged adapter config (preset + user overrides). The returned promise resolves to the typed adapter instance.

Parameters

options?

TOptions

Resolved adapter configuration (shape defined by the adapter).

Returns

Promise<TAdapter>

Promise resolving to the adapter instance.

defaultPresetId?

readonly optional defaultPresetId?: string

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:180

Identifier of the default provider preset for this adapter.

When omitted, the runtime or user selects the preset.

defaultTimeouts

readonly defaultTimeouts: RequiredTimeoutConfig

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:162

Required timeout defaults for all adapter operations.

The config factory should read these values instead of importing a parallel constant, making this contract the single source of truth for adapter timeout behavior.

description?

readonly optional description?: string

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:127

Short description of what this adapter does.

displayName?

readonly optional displayName?: string

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:125

Human-readable display name shown in the UI (e.g., 'Claude Code').

When omitted, the subsystem falls back to AdapterManifest.displayName.

helpLinks?

readonly optional helpLinks?: readonly object[]

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:168

External help links for this adapter (e.g., documentation, support).

Displayed in the adapter settings UI when present.

instructions?

readonly optional instructions?: string

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:174

Setup or usage instructions shown in the adapter configuration UI.

May contain Markdown-formatted text.

name

readonly name: string

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:119

Stable machine identifier for this adapter (e.g., 'claude-code').

Must match AdapterManifest.name on the paired manifest entry. Used as the primary key in adapter registries.

protocol?

readonly optional protocol?: "anthropic" | "openai"

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:196

Active wire protocol used by this adapter at runtime.

This is the singular runtime-active protocol consumed by the subsystem to route requests. The serializable counterpart (AdapterManifest.protocols) may declare additional protocols for discovery-time use.

providerConfigSchema?

readonly optional providerConfigSchema?: ZodObject<Readonly<{[k: string]: $ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; }>, $strip>

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:149

Default config schema applied to all providers unless overridden per-provider via AdapterProviderRef.configSchema.

providerCredentialSchema?

readonly optional providerCredentialSchema?: ZodObject<Readonly<{[k: string]: $ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; }>, $strip>

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:154

Default credential schema applied to all providers unless overridden per-provider via AdapterProviderRef.credentialSchema.

providers

readonly providers: readonly AdapterProviderRef[]

Defined in: ../../../packages/contracts/src/extension/adapter-definition.ts:144

Provider IDs this adapter can serve.

Each entry declares a provider by definition ID with optional schema overrides. The adapter subsystem resolves these to full ProviderDefinitionInput objects at boot from the provider registry.