@makaio/contracts 1.0.0-dev-1779051654000

package/dist/extension/adapter-definition.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Adapter definition contracts for the D2 bus-decoupled adapter subsystem.
+ *
+ * These interfaces define the runtime contract that adapter packages expose
+ * via their {@link MakaioExtension} `adapters` contribution. They replace the
+ * `definition: unknown` opaque type on {@link AdapterContribution} with a
+ * typed contract that the adapter subsystem can consume directly.
+ *
+ * The split between manifest (serializable, bus-transportable) and definition
+ * (runtime-only, contains executable code) is intentional:
+ * - `AdapterManifest` — discovery-time metadata, Zod-validated, bus-safe.
+ * - {@link AdapterDefinitionContract} — runtime contract with executable code.
+ * @see {@link AdapterContribution} for the combined contribution type.
+ */
+import type { z } from 'zod';
+import type { ProtocolId, ProviderDefinitionInput } from '../provider/definition.js';
+import type { RequiredTimeoutConfig } from '../timeout/index.js';
+/**
+ * Adapter-side declaration of a supported provider.
+ *
+ * The adapter declares which providers it can serve by stable definition ID.
+ * The adapter subsystem resolves each ID to a full {@link ProviderDefinitionInput}
+ * from the provider registry at boot. Optional schemas override the adapter-level
+ * defaults for this specific provider.
+ */
+export interface AdapterProviderRef {
+    /** Stable provider definition ID (e.g., `'anthropic'`, `'openai'`). */
+    readonly definitionId: string;
+    /**
+     * Provider-specific config schema override.
+     *
+     * When present, overrides any adapter-level config schema for this provider.
+     */
+    readonly configSchema?: z.ZodObject<z.ZodRawShape>;
+    /**
+     * Provider-specific credential schema override.
+     *
+     * When present, overrides any adapter-level credential schema for this provider.
+     */
+    readonly credentialSchema?: z.ZodObject<z.ZodRawShape>;
+}
+/**
+ * Runtime contract for a single provider supported by an adapter.
+ *
+ * This type is the single source of truth for the provider definition wrapper.
+ * Both `ai-adapters-core/src/types/provider-definition.ts` and
+ * `adapter-subsystem/src/adapter-runtime-types.ts` extend or alias this type.
+ */
+export interface AdapterProviderDefinitionContract {
+    /**
+     * Provider identity, model catalog, and endpoint declarations.
+     *
+     * Accepts {@link ProviderDefinitionInput} so adapter packages that declare
+     * static `providerDefinition` constants can omit `availableModels` (which
+     * the registry service populates at boot time). The runtime-resolved type
+     * narrows after the adapter subsystem merges the registry data.
+     */
+    readonly definition: ProviderDefinitionInput;
+    /**
+     * Zod schema for provider-specific configuration fields.
+     *
+     * When present, the adapter subsystem uses this schema to validate and
+     * expose provider configuration via the settings bus handlers.
+     * Not serializable — kept in the definition, not the manifest.
+     */
+    readonly configSchema?: z.ZodObject<z.ZodRawShape>;
+    /**
+     * Zod schema for provider credential fields (e.g., API key, token).
+     *
+     * When present, the adapter subsystem uses this schema to validate
+     * credentials before forwarding them to the adapter factory.
+     * Not serializable — kept in the definition, not the manifest.
+     */
+    readonly credentialSchema?: z.ZodObject<z.ZodRawShape>;
+}
+/**
+ * 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 {@link 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`.
+ * @typeParam TAdapter - Concrete adapter instance type returned by {@link createAdapter}.
+ *   Defaults to `unknown` so the contract is usable without a type parameter.
+ * @typeParam TOptions - Options type accepted by {@link 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.
+ */
+export interface AdapterDefinitionContract<TAdapter = unknown, TOptions = never> {
+    /**
+     * 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.
+     */
+    readonly name: string;
+    /**
+     * Human-readable display name shown in the UI (e.g., `'Claude Code'`).
+     *
+     * When omitted, the subsystem falls back to `AdapterManifest.displayName`.
+     */
+    readonly displayName?: string;
+    /** Short description of what this adapter does. */
+    readonly description?: string;
+    /**
+     * 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.
+     */
+    readonly adapterConfigSchema?: z.ZodObject<z.ZodRawShape>;
+    /**
+     * 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
+     * {@link ProviderDefinitionInput} objects at boot from the provider registry.
+     */
+    readonly providers: readonly AdapterProviderRef[];
+    /**
+     * Default config schema applied to all providers unless overridden
+     * per-provider via {@link AdapterProviderRef.configSchema}.
+     */
+    readonly providerConfigSchema?: z.ZodObject<z.ZodRawShape>;
+    /**
+     * Default credential schema applied to all providers unless overridden
+     * per-provider via {@link AdapterProviderRef.credentialSchema}.
+     */
+    readonly providerCredentialSchema?: z.ZodObject<z.ZodRawShape>;
+    /**
+     * 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.
+     */
+    readonly defaultTimeouts: RequiredTimeoutConfig;
+    /**
+     * External help links for this adapter (e.g., documentation, support).
+     *
+     * Displayed in the adapter settings UI when present.
+     */
+    readonly helpLinks?: ReadonlyArray<{
+        label: string;
+        url: string;
+    }>;
+    /**
+     * Setup or usage instructions shown in the adapter configuration UI.
+     *
+     * May contain Markdown-formatted text.
+     */
+    readonly instructions?: string;
+    /**
+     * Identifier of the default provider preset for this adapter.
+     *
+     * When omitted, the runtime or user selects the preset.
+     */
+    readonly defaultPresetId?: string;
+    /**
+     * Client identifier this adapter delegates to (e.g., `'claude-code'`).
+     *
+     * References a `ClientManifest.id` declared on the executable
+     * {@link AdapterContribution.manifest}; descriptor contributions may mirror
+     * it for discovery but are not the runtime wiring source.
+     */
+    readonly clientId?: string;
+    /**
+     * 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.
+     */
+    readonly protocol?: ProtocolId;
+    /**
+     * 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.
+     * @param options - Resolved adapter configuration (shape defined by the adapter).
+     * @returns Promise resolving to the adapter instance.
+     */
+    readonly createAdapter: (options?: TOptions) => Promise<TAdapter>;
+}
+//# sourceMappingURL=adapter-definition.d.ts.map

package/dist/extension/adapter-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-definition.d.ts","sourceRoot":"","sources":["../../src/extension/adapter-definition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAMjE;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACnD;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;CACxD;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,iCAAiC;IAChD;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,uBAAuB,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACnD;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;CACxD;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,yBAAyB,CAAC,QAAQ,GAAG,OAAO,EAAE,QAAQ,GAAG,KAAK;IAC7E;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IAC1D;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAClD;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IAC3D;;;OAGG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IAC/D;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnE;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CACnE"}

package/dist/extension/browser-entrypoint.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+/**
+ * Browser entrypoint metadata declared by a package manifest.
+ *
+ * The renderer uses this URL path to load a package's browser bundle.
+ */
+export declare const BrowserEntrypointSchema: z.ZodObject<{
+    entrypoint: z.ZodString;
+}, z.core.$strip>;
+/** Inferred type for browser entrypoint manifest metadata. */
+export type BrowserEntrypoint = z.infer<typeof BrowserEntrypointSchema>;
+//# sourceMappingURL=browser-entrypoint.d.ts.map

package/dist/extension/browser-entrypoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-entrypoint.d.ts","sourceRoot":"","sources":["../../src/extension/browser-entrypoint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;iBAOlC,CAAC;AAEH,8DAA8D;AAC9D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/extension/capability-token.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+/**
+ * Declaration-mergeable registry for extension capability tokens.
+ *
+ * Extend this interface via `declare module` to register capability tokens that
+ * can be referenced by {@link CapabilityToken} at compile time.
+ */
+export interface CapabilityTokenMap {
+    /** Adapter subsystem readiness for adapter metadata, config, and runtime lifecycle. */
+    adapters: true;
+}
+/**
+ * Compile-time capability token used by extension manifests.
+ *
+ * Extracting string keys preserves declaration-merged literal tokens without
+ * relying on intersections that can collapse to `never` in downstream type
+ * contexts.
+ */
+export type CapabilityToken = Extract<keyof CapabilityTokenMap, string>;
+/**
+ * Canonical runtime validator for extension capability tokens.
+ *
+ * Runtime validation intentionally remains string-based so descriptor JSON stays
+ * data-only; declaration merging supplies the compile-time token vocabulary.
+ */
+export declare const CapabilityTokenSchema: z.ZodType<CapabilityToken>;
+//# sourceMappingURL=capability-token.d.ts.map

package/dist/extension/capability-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-token.d.ts","sourceRoot":"","sources":["../../src/extension/capability-token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,uFAAuF;IACvF,QAAQ,EAAE,IAAI,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,MAAM,kBAAkB,EAAE,MAAM,CAAC,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAIK,CAAC"}