@makaio/contracts 1.0.0-dev-1779051654000

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

@@ -0,0 +1,27 @@
+/**
+ * Typed extension service tokens.
+ *
+ * Extension tokens pair a runtime extension name with the service type the
+ * extension exposes. Consumers import an extension-owned token instead of
+ * repeating string literals at service lookup call sites.
+ */
+/**
+ * Typed token for retrieving an extension service from an extension context.
+ *
+ * The type parameter is intentionally phantom: the runtime uses {@link name}
+ * while TypeScript carries the expected service type through `getService`.
+ * @typeParam T - Service type exposed by the extension.
+ */
+export interface ExtensionToken<T = unknown> {
+    /** Extension name registered with the runtime coordinator. */
+    readonly name: string;
+    /** Phantom marker for the token's service type. */
+    readonly __service?: T;
+}
+/**
+ * Create a typed extension service token.
+ * @param name - Extension name registered with the runtime coordinator.
+ * @returns Frozen token carrying the extension name and service type.
+ */
+export declare function extensionToken<T>(name: string): ExtensionToken<T>;
+//# sourceMappingURL=extension-token.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extension-token.d.ts","sourceRoot":"","sources":["../../src/extension/extension-token.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAEjE"}

package/dist/extension/extension-warning.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Extension health-warning contracts.
+ *
+ * Defines the serializable {@link ExtensionWarning} shape that extensions return
+ * from their {@link ExtensionServiceLifecycle.checkHealth} hook, plus the
+ * discriminated-union {@link ExtensionWarningAction} type that lets the UI
+ * surface a single call-to-action button per warning.
+ *
+ * All types are fully serializable — no functions, no class instances.
+ */
+import { z } from 'zod';
+/**
+ * Discriminated union of actionable responses to an extension warning.
+ *
+ * Each variant carries the data the host needs to execute the action without
+ * further round-trips to the extension.
+ *
+ * - `configure-integration` — open the integration settings for a client.
+ * - `install-extension`    — prompt the user to install another extension.
+ * - `open-url`             — navigate to an external or internal URL.
+ * - `run-command`          — invoke a registered bus command by name.
+ */
+export declare const ExtensionWarningActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"configure-integration">;
+    clientId: z.ZodString;
+    bundle: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"install-extension">;
+    extensionName: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"open-url">;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"run-command">;
+    command: z.ZodString;
+}, z.core.$strip>], "kind">;
+/**
+ * Severity levels for an {@link ExtensionWarning}.
+ *
+ * - `'info'`        — informational note; the extension functions normally.
+ * - `'recommended'` — a recommended configuration is missing; functionality is reduced.
+ * - `'degraded'`    — the extension is operating in a degraded fallback mode.
+ */
+export declare const ExtensionWarningSeveritySchema: z.ZodEnum<{
+    degraded: "degraded";
+    info: "info";
+    recommended: "recommended";
+}>;
+/**
+ * A single health warning emitted by a package's `checkHealth` hook.
+ *
+ * The host collects these after startup and may display them in the UI as
+ * notification toasts or persistent status indicators.
+ */
+export declare const ExtensionWarningSchema: z.ZodObject<{
+    severity: z.ZodEnum<{
+        degraded: "degraded";
+        info: "info";
+        recommended: "recommended";
+    }>;
+    title: z.ZodString;
+    message: z.ZodString;
+    action: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"configure-integration">;
+        clientId: z.ZodString;
+        bundle: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"install-extension">;
+        extensionName: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"open-url">;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"run-command">;
+        command: z.ZodString;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>;
+/** Inferred TypeScript type for {@link ExtensionWarningSchema}. */
+export type ExtensionWarning = z.infer<typeof ExtensionWarningSchema>;
+/** Inferred TypeScript type for {@link ExtensionWarningActionSchema}. */
+export type ExtensionWarningAction = z.infer<typeof ExtensionWarningActionSchema>;
+/** Inferred TypeScript type for {@link ExtensionWarningSeveritySchema}. */
+export type ExtensionWarningSeverity = z.infer<typeof ExtensionWarningSeveritySchema>;
+/**
+ * Return the default user-facing label for an extension warning action.
+ *
+ * Kept with the action contract so every surface labels the same action kind
+ * consistently without duplicating switch statements.
+ * @param action - Extension warning action to label.
+ * @returns Short button label for the action kind.
+ */
+export declare function getExtensionWarningActionLabel(action: ExtensionWarningAction): string;
+/**
+ * Aggregated warning entry grouping all health warnings for a single extension.
+ *
+ * Used as the payload shape for `kernel:extension.warnings.list` responses and
+ * `kernel:extension.warnings.changed` events so consumers receive extension identity
+ * alongside the full warning array in one atomic value.
+ */
+export declare const ExtensionWarningEntrySchema: z.ZodObject<{
+    extensionName: z.ZodString;
+    warnings: z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<{
+            degraded: "degraded";
+            info: "info";
+            recommended: "recommended";
+        }>;
+        title: z.ZodString;
+        message: z.ZodString;
+        action: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"configure-integration">;
+            clientId: z.ZodString;
+            bundle: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"install-extension">;
+            extensionName: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"open-url">;
+            url: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"run-command">;
+            command: z.ZodString;
+        }, z.core.$strip>], "kind">>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Inferred TypeScript type for {@link ExtensionWarningEntrySchema}. */
+export type ExtensionWarningEntry = z.infer<typeof ExtensionWarningEntrySchema>;
+//# sourceMappingURL=extension-warning.d.ts.map

package/dist/extension/extension-warning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-warning.d.ts","sourceRoot":"","sources":["../../src/extension/extension-warning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;2BAuBvC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B;;;;EAA8C,CAAC;AAE1F;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;iBAajC,CAAC;AAEH,mEAAmE;AACnE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,yEAAyE;AACzE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,2EAA2E;AAC3E,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAWrF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;iBAKtC,CAAC;AAEH,wEAAwE;AACxE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}

package/dist/extension/index.d.ts

@@ -0,0 +1,27 @@
+export { BrowserEntrypointSchema } from './browser-entrypoint.js';
+export { AdapterClientRefSchema, AdapterManifestSchema, ClientManifestSchema, ContributionManifestSchema, LogImporterManifestSchema, ProtocolConfigSchema, ProtocolRefSchema, ProviderManifestSchema, SessionEventActionManifestSchema, TriggerManifestSchema, UiSurfaceFlagsSchema, } from './contribution-manifest.js';
+export type { AdapterClientRef, AdapterManifest, ClientManifest, ContributionManifest, LogImporterManifest, ProtocolConfig, ProtocolRef, ProviderManifest, SessionEventActionManifest, TriggerManifest, TriggerStage, UiSurfaceFlags, } from './contribution-manifest.js';
+export { CliArgManifestSchema, CliManifestSchema, CliSubcommandManifestSchema, dep, ExtensionDependencySchema, ExtensionManifestSchema, RuntimeRequirementSchema, StorageManifestSchema, TrayManifestSchema, WindowParamSpecSchema, WindowManifestSchema, } from './manifest.js';
+export type { CliArgManifest, CliManifest, CliSubcommandManifest, ExtensionDependency, ExtensionManifest, RuntimeRequirement, StorageManifest, TrayManifest, WindowManifest, WindowParamSpec, WindowStyle, } from './manifest.js';
+export type { BrowserEntrypoint } from './browser-entrypoint.js';
+export { extensionToken } from './extension-token.js';
+export type { ExtensionToken } from './extension-token.js';
+export type { AdapterDefinitionContract, AdapterProviderDefinitionContract, AdapterProviderRef, } from './adapter-definition.js';
+export type { ExtensionIdentity, ExtensionService, ExtensionServiceLifecycle } from './extension-lifecycle.js';
+export type { ExtensionContext, NodeExtensionContext } from './extension-context.js';
+export type { ExtensionCliBeforeRunContext, ExtensionCliBeforeRunResult, ExtensionCliContribution, ExtensionCliHandlerContext, ExtensionCliInteractiveContext, ExtensionCliOutputWriter, ExtensionCliSubcommandEntry, } from './extension-cli.js';
+export type { ExtensionRuntimeOwnership } from './extension-runtime-boot.js';
+export type { AdapterContribution, ExtensionNamespaceContribution, ExtensionSessionEventActionsContribution, ExtensionToolsContribution, ExtensionTriggersContribution, ExtensionUiContribution, LogImportContribution, } from './extension-contributions.js';
+export type { ExtensionContributionProcessor, ExtensionRuntimeBootContext, ExtensionRuntimeBootContribution, MakaioExtension, MakaioNodeExtension, } from './makaio-extension.js';
+export type { EntityUIConfig } from '../shared/ui-config.js';
+export { DetachedTransportSchema, ExtensionDescriptorSchema, ExtensionEntrypointsSchema, isDetachedDescriptor, parseExtensionDescriptor, safeParseExtensionDescriptor, } from './extension-descriptor.js';
+export type { DetachedDescriptor, DetachedTransportConfig, EmbeddedDescriptor, ExtensionDescriptor, ExtensionDescriptorBase, ExtensionDescriptorParseResult, ExtensionEntrypoints, } from './extension-descriptor.js';
+export { ExtensionWarningActionSchema, ExtensionWarningEntrySchema, ExtensionWarningSeveritySchema, ExtensionWarningSchema, getExtensionWarningActionLabel, } from './extension-warning.js';
+export type { ExtensionWarning, ExtensionWarningAction, ExtensionWarningEntry, ExtensionWarningSeverity, } from './extension-warning.js';
+export { parseExtensionConfig } from './parse-extension-config.js';
+export { CapabilityTokenSchema } from './capability-token.js';
+export type { CapabilityToken, CapabilityTokenMap } from './capability-token.js';
+export type { ExtensionConfigProvider } from './extension-config-provider.js';
+export { getBootstrapAssetKey } from './contributions/index.js';
+export type { ActionCategory, ActionCategoryMap, ActionShortcut, ActionShortcutModifiers, BootstrapAsset, BootstrapAssetKey, BootstrapChoice, BootstrapDiscoverContext, BootstrapExportContext, BootstrapExportResult, BootstrapImportContext, BootstrapImportResult, BootstrapResult, CreateSessionEventActionResult, EntrypointConfig, EventFilter, ExecuteContext, ExecuteResult, ExtensionBootstrap, ExtensionConfigComponentLoader, ExtensionConfigComponentProps, ExtensionFieldTypeLoader, GatheredContext, GatheredEntry, HashSuggestion, HashTrigger, HashTriggerContext, HashTriggerMetadata, HashTriggerStage, HashTriggerSuggestResult, LoaderContext, MakaioWebUiAction, MakaioWebUiActions, MakaioWebUiComponentProps, MakaioWebUiLoader, MakaioWebUiRoute, MessageEventFilter, MessageRole, PageComponentProps, PageDeclaration, PageMode, PageWidgetSize, PickerConfig, PickerOpenContext, PluginFormattedToolCallOutput, PluginToolCallFormatterInput, PluginTransformedContent, PluginTransformedContentType, PromisifiedActions, SelectionChangeContext, SelectionFeedback, SessionEventActionContext, SessionEventActionDeclaration, SessionEventActionOptions, SlotContentDeclaration, SlotDeclaration, SlotId, SlotPlacementDeclaration, StructuralEventFilter, TileCapabilities, TileDeclaration, TileIconLoader, TileProps, TileRenderers, ToolCallFormatterDeclaration, UiContextDimension, UiContextSnapshot, UiContextValueMap, UiNavigationLevel, UiNavigationLevelMap, UiRuntimeNavigationLevel, UiScope, UiScopeMap, WhenContext, WidgetDeclaration, WidgetDefinition, WidgetProps, WidgetRenderers, WidgetSize, } from './contributions/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/extension/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extension/index.ts"],"names":[],"mappings":"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"}

package/dist/extension/index.mjs

@@ -0,0 +1 @@
+import{A as e,C as t,D as n,E as r,F as i,I as a,L as o,M as s,N as c,O as l,P as u,R as d,S as f,T as p,_ as m,a as h,b as g,c as _,d as v,f as y,g as b,h as x,i as S,j as C,k as w,l as T,m as E,n as D,o as O,p as k,r as A,s as j,t as M,u as N,v as P,w as F,x as I,y as L}from"../extension-CfIRUup2.mjs";export{n as AdapterClientRefSchema,l as AdapterManifestSchema,d as BrowserEntrypointSchema,r as CapabilityTokenSchema,x as CliArgManifestSchema,b as CliManifestSchema,m as CliSubcommandManifestSchema,w as ClientManifestSchema,e as ContributionManifestSchema,_ as DetachedTransportSchema,P as ExtensionDependencySchema,T as ExtensionDescriptorSchema,N as ExtensionEntrypointsSchema,L as ExtensionManifestSchema,A as ExtensionWarningActionSchema,S as ExtensionWarningEntrySchema,h as ExtensionWarningSchema,O as ExtensionWarningSeveritySchema,C as LogImporterManifestSchema,s as ProtocolConfigSchema,c as ProtocolRefSchema,u as ProviderManifestSchema,g as RuntimeRequirementSchema,i as SessionEventActionManifestSchema,I as StorageManifestSchema,f as TrayManifestSchema,a as TriggerManifestSchema,o as UiSurfaceFlagsSchema,t as WindowManifestSchema,F as WindowParamSpecSchema,p as dep,E as extensionToken,M as getBootstrapAssetKey,j as getExtensionWarningActionLabel,v as isDetachedDescriptor,D as parseExtensionConfig,y as parseExtensionDescriptor,k as safeParseExtensionDescriptor};

package/dist/extension/makaio-extension.d.ts

@@ -0,0 +1,324 @@
+import type { z } from 'zod';
+import type { MakaioBusLike, RegistrableBusNamespaceDefinition } from '@makaio/framework/core';
+import type { ExtensionManifest, StorageManifest } from './manifest.js';
+import type { ExtensionContext, NodeExtensionContext } from './extension-context.js';
+import type { ExtensionService } from './extension-lifecycle.js';
+import type { ExtensionRuntimeOwnership } from './extension-runtime-boot.js';
+import type { ExtensionCliContribution } from './extension-cli.js';
+import type { AdapterContribution, ExtensionNamespaceContribution, ExtensionSessionEventActionsContribution, ExtensionToolsContribution, ExtensionTriggersContribution, ExtensionUiContribution, LogImportContribution } from './extension-contributions.js';
+import type { ClientDefinition } from '../client/definition.js';
+import type { ProviderDefinitionInput } from '../provider/definition.js';
+import type { EntityUIConfig } from '../shared/ui-config.js';
+import type { ExtensionBootstrap } from './contributions/bootstrap-types.js';
+/**
+ * Awaited contribution processor registered with the runtime coordinator.
+ *
+ * Processors are registered before package startup and are invoked when a
+ * package activates or stops. A processor can filter the packages it handles
+ * by inspecting the executable {@link MakaioExtension} manifest.
+ * @typeParam THostContext - Host context supplied to active extensions.
+ */
+export interface ExtensionContributionProcessor<THostContext extends ExtensionContext = NodeExtensionContext> {
+    /**
+     * Optional activation filter.
+     * @param pkg - Extension manifest to evaluate.
+     * @returns `true` when this processor should handle the extension.
+     */
+    readonly filter?: (pkg: MakaioExtension<THostContext>) => boolean;
+    /**
+     * Called when an extension is being activated.
+     * @param name - Extension package name.
+     * @param pkg - Extension manifest.
+     * @param ctx - Per-extension runtime context.
+     */
+    readonly processActivated: (name: string, pkg: MakaioExtension<THostContext>, ctx: THostContext) => Promise<void>;
+    /**
+     * Called when an extension is stopped or disabled.
+     * @param name - Extension package name.
+     */
+    readonly processStopped?: (name: string) => Promise<void>;
+}
+/**
+ * Context for executable boot contributions declared by extension packages.
+ *
+ * This seam runs after all packages have been loaded into the coordinator and
+ * before startup begins, so packages can register contribution processors for
+ * extension surfaces they own.
+ * @typeParam THostContext - Host context supplied to contribution processors.
+ */
+export interface ExtensionRuntimeBootContext<THostContext extends ExtensionContext = NodeExtensionContext> {
+    /** Runtime bus. */
+    readonly bus: THostContext['bus'];
+    /**
+     * Register a contribution processor before package startup.
+     * @param processor - Processor to add to the coordinator.
+     */
+    readonly registerContributionProcessor: (processor: ExtensionContributionProcessor<THostContext>) => void;
+    /**
+     * Enumerate active extensions lazily after startup.
+     * @param callback - Called for each active extension with its context.
+     */
+    readonly forEachActiveExtension: (callback: (name: string, pkg: MakaioExtension<THostContext>, ctx: THostContext) => void) => void;
+}
+/**
+ * Executable boot contribution declared by an extension package.
+ *
+ * Use this for runtime wiring that must be installed before
+ * {@link ExtensionContributionProcessor} activation starts, such as registering
+ * processors for extension-owned contribution surfaces.
+ * @typeParam THostContext - Host context supplied by the runtime.
+ */
+export interface ExtensionRuntimeBootContribution<THostContext extends ExtensionContext = NodeExtensionContext> {
+    /**
+     * Configure the runtime coordinator before package startup.
+     * @param context - Minimal boot context supplied by the host runtime.
+     * @returns Optional cleanup callback or callbacks for runtime shutdown.
+     */
+    readonly configure: (context: ExtensionRuntimeBootContext<THostContext>) => void | (() => void) | readonly (() => void)[];
+}
+/**
+ * Executable Makaio extension manifest.
+ *
+ * Extends {@link ExtensionManifest} with executable code: a service factory,
+ * a CLI contribution with interactive TUI support, and a Drizzle storage
+ * handler registration callback.
+ *
+ * Source-of-truth rule: fields on this executable extension are the runtime
+ * wiring source. Serializable descriptor fields, including
+ * {@link ExtensionManifest.contributions}, are discovery metadata and are not
+ * promoted into executable contribution surfaces by the loader.
+ *
+ * The host runtime calls {@link create} (if defined) with a
+ * {@link ExtensionContext} to instantiate the service. Window-only extensions
+ * that have no background service may omit {@link create} entirely.
+ * @typeParam THostContext - Concrete context shape supplied by the host
+ *   runtime. Defaults to {@link NodeExtensionContext} because the current
+ *   framework hosts are Node-based.
+ * @example
+ * ```ts
+ * export const myExtension: MakaioExtension = {
+ *   name: 'my-extension',
+ *   displayName: 'My Extension',
+ *   create: (ctx) => new MyService(ctx.bus),
+ * };
+ * ```
+ */
+export interface MakaioExtension<THostContext extends ExtensionContext = NodeExtensionContext> extends ExtensionManifest {
+    /**
+     * Bus namespace definitions owned by this extension.
+     *
+     * Registered by `ExtensionCoordinator` during extension activation, before
+     * {@link create} is called, so handlers registered during construction can
+     * rely on the namespace being available.
+     *
+     * Extensions that don't own bus namespaces omit this field.
+     */
+    readonly namespaces?: readonly RegistrableBusNamespaceDefinition[];
+    /**
+     * Factory that creates and returns the extension's service.
+     *
+     * Optional — window-only extensions that have no background service may omit
+     * this field entirely. When present, the host calls this during startup; the
+     * extension is responsible for all internal composition (choosing backends,
+     * creating sources, etc.) based on the provided context.
+     * @param ctx - Runtime context with bus, host details, and machine identity.
+     * @returns The extension's service instance (not yet initialized — host calls `init`).
+     */
+    readonly create?: (ctx: THostContext) => ExtensionService | Promise<ExtensionService>;
+    /**
+     * Executable ownership declarations for runtime responsibilities that must
+     * have exactly one owner in a booted runtime.
+     */
+    readonly runtimeOwnership?: ExtensionRuntimeOwnership;
+    /**
+     * Boot-time executable contribution for registering runtime processors or
+     * services before package startup begins.
+     */
+    readonly runtimeBoot?: ExtensionRuntimeBootContribution<THostContext>;
+    /**
+     * When true, startup fails if this extension fails to initialize.
+     *
+     * Optional extensions default to isolated failure so one extension cannot
+     * prevent the runtime from booting. Framework and host core extensions set
+     * this to true when the runtime cannot safely continue without them.
+     */
+    readonly critical?: boolean;
+    /**
+     * Executable CLI contribution registered under `makaio <name>`.
+     *
+     * The runtime exposes the fully typed helper API through
+     * `@makaio/kernel/cli` when authoring CLI commands. This manifest stores
+     * only the type-erased executable shape used after loading.
+     */
+    readonly cli?: ExtensionCliContribution<THostContext['bus']>;
+    /**
+     * Server-side HTTP routes.
+     * Hosts that support HTTP route contributions call `mount()` on a fresh,
+     * rebuildable app graph as extensions activate or stop. Contracts keeps the
+     * app type erased so this layer does not depend on Hono.
+     * @param app - Host-owned HTTP app instance.
+     */
+    readonly http?: {
+        readonly prefix: string;
+        readonly mount: (app: unknown) => void;
+    };
+    /**
+     * Executable storage contribution.
+     *
+     * Extends {@link StorageManifest} (migration paths) with a Drizzle handler
+     * registration callback invoked by the composition root after migrations
+     * have been applied but before services are started.
+     *
+     * The `db` parameter is typed as `unknown` in the contracts layer (which
+     * does not take a drizzle dependency) — composition roots cast it to
+     * `MakaioDatabase` before calling. The returned cleanup function is
+     * invoked during graceful shutdown to unregister bus handlers.
+     */
+    readonly storage?: StorageManifest & {
+        /**
+         * Absolute extension root used to resolve relative storage asset paths.
+         *
+         * Required when a code-defined extension declares relative
+         * {@link StorageManifest.migrations} paths, since there is no descriptor
+         * file path for the runtime to infer from.
+         */
+        readonly packageRoot?: string;
+        /**
+         * Stable runtime identity for the migration bundle.
+         *
+         * Bundled hosts use this instead of packaged output paths when they need a
+         * durable key for migration deduplication and embedded lookup.
+         */
+        readonly migrationSourceId?: string;
+        /**
+         * Registers Drizzle-backed bus storage handlers for this extension.
+         * @param bus - The application bus instance.
+         * @param db - The Drizzle database instance (typed opaquely here; cast at the call site).
+         * @param ctx - Runtime extension context supplying host details and machine identity
+         *   (e.g., for machine-scoped storage registration).
+         * @returns Optional cleanup function called during shutdown to unregister handlers.
+         */
+        readonly registerHandlers?: (bus: THostContext['bus'], db: unknown, ctx: THostContext) => (() => void) | void;
+    };
+    /**
+     * Zod schema describing this extension's configuration shape.
+     *
+     * When present, the coordinator:
+     * 1. Exposes the schema as JSON Schema via `extension.getConfigSchema` RPC
+     * 2. Loads stored config from `ExtensionConfigStorageSubjects` at boot
+     * 3. Parses it through this schema and injects the result into
+     *    {@link ExtensionContext.config}
+     *
+     * The schema should provide `.default()` values for all optional fields
+     * so parsing `{}` always yields a valid config.
+     */
+    readonly configSchema?: z.ZodType;
+    /**
+     * UI configuration for schema-driven configuration forms.
+     *
+     * Controls how the config form is rendered: edit mode (slidePanel vs full),
+     * which fields to hide, and per-field widget overrides (e.g. slider, color
+     * picker). Only meaningful when {@link configSchema} is also declared.
+     */
+    readonly uiConfig?: EntityUIConfig;
+    /**
+     * Client runtime definitions contributed by this extension.
+     *
+     * Loaded clients are passed to `createClientsCorePackage` during boot and
+     * registered with the client bootstrap service. These definitions are the
+     * runtime source of truth for client wiring; descriptor `contributions.clients`
+     * is discovery metadata only.
+     */
+    readonly clients?: readonly ClientDefinition[];
+    /**
+     * Provider definitions contributed by this extension.
+     *
+     * Each entry defines a model provider (e.g., Anthropic, OpenAI) with its
+     * supported models, capabilities, and credential requirements. Loaded
+     * providers are registered with the provider subsystem during boot.
+     *
+     * Provider definitions are executable extension contributions. Descriptor
+     * `contributions.providers` may mirror provider identity metadata for
+     * pre-load discovery, but is not a registration fallback.
+     */
+    readonly providers?: readonly ProviderDefinitionInput[];
+    /**
+     * Adapter runtime definitions contributed by this extension.
+     *
+     * Each entry pairs JSON-serializable discovery metadata with the full
+     * runtime adapter definition typed via {@link AdapterDefinitionContract}.
+     * The adapter contribution processor consumes this executable field directly;
+     * descriptor `contributions.adapters` is not a registration fallback.
+     */
+    readonly adapters?: readonly AdapterContribution[];
+    /**
+     * Log import capability for external tool session import.
+     *
+     * Opaque in contracts. The log-import contribution processor narrows
+     * `config` to `PluginLogImport` at processing time.
+     */
+    readonly logImport?: LogImportContribution;
+    /**
+     * Tool contribution factory for this extension.
+     *
+     * When present, the runtime calls `createToolsets(ctx)` after all
+     * dependencies are loaded and registers the returned toolsets with
+     * `ToolRegistry`. Extensions that contribute tools should declare a dependency
+     * on the tool-registry service if one is required for registration.
+     */
+    readonly tools?: ExtensionToolsContribution<THostContext>;
+    /**
+     * Hash trigger factory for this extension.
+     *
+     * When present, the runtime calls `createTriggers(bus)` after all
+     * dependencies are loaded, then registers the returned triggers with
+     * `HashTriggerService`.
+     *
+     * Extensions declaring triggers should depend on `'hash-trigger'` to ensure
+     * the service exists when triggers are registered.
+     */
+    readonly triggers?: ExtensionTriggersContribution<THostContext['bus']>;
+    /**
+     * Session event action factory for this extension.
+     *
+     * When present, the runtime calls `createActions(ctx)` after all
+     * dependencies are loaded and registers the returned declarations with
+     * `SessionEventActionService`. Unregister callbacks are stored for
+     * shutdown cleanup.
+     */
+    readonly sessionEventActions?: ExtensionSessionEventActionsContribution<THostContext['bus']>;
+    /**
+     * Bootstrap capability for project config import/export.
+     *
+     * When present, this extension participates in:
+     * - Project export: extension data can be saved to `.makaio/bootstrap/`
+     * - Project import: extension data can be restored from `.makaio/bootstrap/`
+     */
+    readonly bootstrap?: ExtensionBootstrap<THostContext['bus']>;
+    /**
+     * Bus namespace introspection for this extension.
+     *
+     * The domain is auto-prefixed to `'extension:NAME'` to avoid collisions.
+     * Register schemas statically in a `namespace.ts` file for type-safe
+     * subjects, then reference them here for documentation and introspection.
+     */
+    readonly namespace?: ExtensionNamespaceContribution;
+    /**
+     * Browser UI contributions for this extension.
+     *
+     * Groups all UI-layer contribution surfaces. Absent for headless-only
+     * extensions. The coordinator passes this bag to the UI loader
+     * which bridges each surface to the appropriate client-side registry.
+     */
+    readonly ui?: ExtensionUiContribution;
+}
+/**
+ * Convenience executable extension type for Node hosts.
+ *
+ * Contracts stays independent of the concrete bus implementation; Node-based
+ * packages bind `TBus` from their host layer (for example `IMakaioBus` from
+ * `@makaio/bus-core`) when they need the full typed bus authoring surface.
+ * @typeParam TBus - Concrete bus type supplied by the Node host.
+ */
+export type MakaioNodeExtension<TBus extends MakaioBusLike> = MakaioExtension<NodeExtensionContext<TBus>>;
+//# sourceMappingURL=makaio-extension.d.ts.map

package/dist/extension/makaio-extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"makaio-extension.d.ts","sourceRoot":"","sources":["../../src/extension/makaio-extension.ts"],"names":[],"mappings":"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"}