@makaio/contracts 1.0.0-dev-1779051654000

package/dist/extension/contributions/web-ui-types.d.ts

@@ -0,0 +1,145 @@
+import type { ComponentType } from 'react';
+import type { FormFieldProps } from '../../shared/ui-config.js';
+import type { UiContextSnapshot } from './ui-context-types.js';
+/**
+ * Request context passed to a WebUI loader function.
+ *
+ * Provides visibility-aware context so loaders can filter data by the active
+ * host UI context. URL params are forwarded from the route match so loaders can
+ * access path segments and query strings.
+ */
+export interface LoaderContext {
+    /**
+     * Active session identifier, if a session is selected.
+     *
+     * `undefined` when no session is currently active.
+     */
+    sessionId?: string;
+    /** Active host UI context for the matched route. */
+    uiContext: UiContextSnapshot;
+    /**
+     * URL parameters from the matched route, including path segments and query
+     * strings.
+     *
+     * Forwarded from the router so loaders can read route-specific identifiers.
+     */
+    params: Record<string, string>;
+}
+/**
+ * Loader function that fetches data for a WebUI route.
+ *
+ * Receives a {@link LoaderContext} with active session, UI context, and URL
+ * params so loaders can return visibility-appropriate data. The resolved data
+ * is passed to the component as `loaderData`.
+ * @typeParam TData - Type of data returned by the loader.
+ * @param context - Request context with session, UI context, and URL params.
+ * @returns Promise resolving to the loader data.
+ */
+export type MakaioWebUiLoader<TData = unknown> = (context: LoaderContext) => Promise<TData>;
+/**
+ * Action function that performs server-side operations.
+ * @typeParam TData - Type of data returned by the action.
+ * @typeParam TArgs - Tuple type of arguments accepted by the action.
+ * @param args - Arguments passed to the action.
+ * @returns Promise resolving to the action result.
+ */
+export type MakaioWebUiAction<TData = unknown, TArgs extends unknown[] = unknown[]> = (...args: TArgs) => Promise<TData>;
+/**
+ * Record of named actions available to a WebUI route.
+ *
+ * Each action can return different data types.
+ */
+export type MakaioWebUiActions = Record<string, MakaioWebUiAction<unknown, unknown[]>>;
+/**
+ * Transforms server-side action definitions into client-side Promise-based
+ * executors.
+ *
+ * Used in component props to provide an async/await API for actions.
+ * @typeParam TActions - The server-side action record shape.
+ */
+export type PromisifiedActions<TActions extends MakaioWebUiActions> = {
+    [K in keyof TActions]: TActions[K] extends (...args: infer Args) => Promise<infer Result> ? (...args: Args) => Promise<Result> : never;
+};
+/**
+ * Props passed to a WebUI component.
+ *
+ * Provides type-safe access to loader data, Promise-based action executors,
+ * and the {@link LoaderContext} that was active when the loader ran.
+ * @typeParam TLoaderData - Type of data returned by the loader.
+ * @typeParam TActions - Record of available actions.
+ */
+export type MakaioWebUiComponentProps<TLoaderData = unknown, TActions extends MakaioWebUiActions = MakaioWebUiActions> = {
+    /** Data resolved by the loader before the component was rendered. */
+    loaderData: TLoaderData;
+    /** Promisified action executors for mutating server-side state. */
+    actions: TActions extends MakaioWebUiActions ? PromisifiedActions<TActions> : Record<string, never>;
+    /** The loader context that was active when the loader ran. */
+    loaderContext: LoaderContext;
+};
+/**
+ * WebUI route definition for packages.
+ *
+ * Defines a route with path, optional loader/actions, and a lazy-loaded React
+ * component. Provides full TypeScript inference for component props.
+ * @typeParam TLoaderData - Type of data returned by the loader.
+ * @typeParam TActions - Record of available actions (or `undefined` if none).
+ */
+export interface MakaioWebUiRoute<TLoaderData = unknown, TActions extends MakaioWebUiActions | undefined = undefined> {
+    /** Route path relative to the package mount point. */
+    path: string;
+    /** Optional data loader. */
+    loader?: MakaioWebUiLoader<TLoaderData>;
+    /** Optional action handlers. */
+    actions?: TActions;
+    /**
+     * Lazy component loader — called only browser-side.
+     *
+     * Must return a module with a default export of a React component that
+     * accepts the inferred {@link MakaioWebUiComponentProps}.
+     */
+    component: () => Promise<{
+        default: ComponentType<MakaioWebUiComponentProps<TLoaderData, TActions extends MakaioWebUiActions ? TActions : Record<string, never>>>;
+    }>;
+}
+/**
+ * Props for custom extension configuration components.
+ *
+ * When an extension provides `ui.configComponent`, the loaded component receives
+ * these props to interact with the extension configuration system.
+ * @typeParam TConfig - Extension configuration type.
+ */
+export interface ExtensionConfigComponentProps<TConfig = unknown> {
+    /** Current configuration values. */
+    config: TConfig;
+    /**
+     * Called when configuration values change.
+     * @param config - Updated configuration.
+     */
+    onChange: (config: TConfig) => void;
+    /** Called when the user confirms the save action. */
+    onSave: () => Promise<void>;
+    /** Whether a save is currently in progress. */
+    isSaving: boolean;
+    /** Validation errors keyed by field name. */
+    errors?: Record<string, string>;
+}
+/**
+ * Async loader for registering custom form field types.
+ *
+ * Must return a module with a default export of a React component that accepts
+ * {@link FormFieldProps}.
+ */
+export type ExtensionFieldTypeLoader = () => Promise<{
+    default: ComponentType<FormFieldProps>;
+}>;
+/**
+ * Async loader for a custom extension configuration component.
+ *
+ * Must return a module with a default export of a React component that accepts
+ * {@link ExtensionConfigComponentProps}.
+ * @typeParam TConfig - Extension configuration type.
+ */
+export type ExtensionConfigComponentLoader<TConfig = unknown> = () => Promise<{
+    default: ComponentType<ExtensionConfigComponentProps<TConfig>>;
+}>;
+//# sourceMappingURL=web-ui-types.d.ts.map

package/dist/extension/contributions/web-ui-types.d.ts.map

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

package/dist/extension/contributions/widget-types.d.ts

@@ -0,0 +1,168 @@
+import type { UiContextSnapshot, UiScope } from './ui-context-types.js';
+/**
+ * Widget size variants.
+ *
+ * Defines the visual footprint a widget can occupy in a layout.
+ * - `'small'`: Minimal space, suitable for status indicators
+ * - `'medium'`: Standard panel size, default for most widgets
+ * - `'large'`: Expanded view, for detailed information
+ * - `'full-width'`: Spans the full available width
+ */
+export type WidgetSize = 'small' | 'medium' | 'large' | 'full-width';
+/**
+ * Serializable widget definition.
+ *
+ * Platform-agnostic description of what data a widget needs and how it
+ * behaves. This definition can be serialized and stored in user preferences.
+ */
+export interface WidgetDefinition {
+    /**
+     * Bus subject for the widget's data source.
+     *
+     * Optional — widgets can render without dynamic data (e.g. static controls).
+     * When provided, the widget requests data from this subject.
+     */
+    dataSource?: string;
+    /**
+     * Events that trigger a widget refresh.
+     *
+     * List of bus event subjects that cause the widget to refresh its data.
+     * @example `['session.updated', 'extension.stateChanged']`
+     */
+    refreshOn?: string[];
+    /**
+     * Supported size variants for this widget.
+     *
+     * Must include at least one size and must include `defaultSize`.
+     */
+    sizes: WidgetSize[];
+    /**
+     * Default size when the widget is first added to a layout.
+     *
+     * Must be one of the values in {@link sizes}.
+     */
+    defaultSize: WidgetSize;
+}
+/**
+ * Props passed to widget components.
+ * @typeParam TData - Type of data from the widget's data source, if any.
+ */
+export interface WidgetProps<TData = unknown> {
+    /** The widget's definition (from declaration). */
+    definition: WidgetDefinition;
+    /** Current size of this widget instance. */
+    size: WidgetSize;
+    /** Data from the widget's data source (when `dataSource` is defined). */
+    data?: TData;
+    /** Active host UI context for this widget surface. */
+    uiContext: UiContextSnapshot;
+}
+/**
+ * Framework-agnostic UI component shape for lazy widget modules.
+ *
+ * Kept free of React imports so the contracts package does not force React
+ * types onto non-web consumers. React function components are structurally
+ * assignable to the call signature.
+ */
+type WidgetComponent = ((props: WidgetProps) => unknown) | (new (props: WidgetProps) => unknown);
+/** Lazy widget component loader. */
+type WidgetComponentLoader = () => Promise<{
+    default: WidgetComponent;
+}>;
+/**
+ * Platform renderers for a widget.
+ *
+ * SEAM: Currently supports React; additional platforms can be added as optional
+ * keys without breaking existing declarations.
+ */
+export interface WidgetRenderers {
+    /**
+     * React renderer for the web UI.
+     *
+     * Lazy-loaded component module with a default export that accepts
+     * `WidgetProps<TData>` where `TData` matches the `dataSource` response.
+     */
+    react: WidgetComponentLoader;
+    /**
+     * SEAM: Future platform renderers (e.g. `reactNative`, `electron`).
+     *
+     * Additional platforms can be added here as optional keys.
+     */
+    [platform: string]: WidgetComponentLoader | undefined;
+}
+/**
+ * Widget declaration contributed by a package.
+ *
+ * Packages declare widgets they provide. These are collected into a global
+ * catalog that the UI system uses to populate focus contexts.
+ * @example
+ * ```typescript
+ * const statusExtension: MakaioExtension = {
+ *   name: 'status-panel',
+ *   ui: {
+ *     widgets: [
+ *       {
+ *         id: 'status-summary',
+ *         name: 'Status Summary',
+ *         description: 'Shows current runtime status',
+ *         scope: 'global',
+ *         definition: {
+ *           dataSource: 'runtime.getStatus',
+ *           refreshOn: ['runtime.ready', 'extension.stateChanged'],
+ *           sizes: ['small', 'medium', 'large'],
+ *           defaultSize: 'medium',
+ *         },
+ *         renderers: {
+ *           react: () => import('./widgets/StatusSummary.js'),
+ *         },
+ *       },
+ *     ],
+ *   },
+ * };
+ * ```
+ */
+export interface WidgetDeclaration {
+    /**
+     * Unique widget identifier.
+     *
+     * Must be unique across all packages. Use the package name as a prefix to
+     * avoid collisions.
+     * @example `'status-summary'`, `'session-activity'`
+     */
+    id: string;
+    /**
+     * Display name for the widget.
+     *
+     * Human-readable name shown in UI when users browse available widgets.
+     */
+    name: string;
+    /**
+     * Optional description of widget purpose.
+     *
+     * Provides additional context about what the widget displays and when to
+     * use it.
+     */
+    description?: string;
+    /**
+     * Widget scope identifier.
+     *
+     * Defaults to `'global'` when not specified.
+     */
+    scope?: UiScope;
+    /**
+     * Serializable widget definition.
+     *
+     * Describes the widget's data needs and behavior without platform-specific
+     * details. Can be serialized and stored in user preferences.
+     */
+    definition: WidgetDefinition;
+    /**
+     * Platform-specific renderers.
+     *
+     * Maps platform names to lazy-loaded component modules. At minimum, the
+     * `'react'` platform is required for the web UI.
+     */
+    renderers: WidgetRenderers;
+}
+export {};
+//# sourceMappingURL=widget-types.d.ts.map

package/dist/extension/contributions/widget-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-types.d.ts","sourceRoot":"","sources":["../../../src/extension/contributions/widget-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAExE;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,CAAC;AAErE;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;;;;OAIG;IACH,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB;;;;OAIG;IACH,WAAW,EAAE,UAAU,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,OAAO;IAC1C,kDAAkD;IAClD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,4CAA4C;IAC5C,IAAI,EAAE,UAAU,CAAC;IACjB,yEAAyE;IACzE,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,sDAAsD;IACtD,SAAS,EAAE,iBAAiB,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,KAAK,eAAe,GAAG,CAAC,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC;AAEjG,oCAAoC;AACpC,KAAK,qBAAqB,GAAG,MAAM,OAAO,CAAC;IAAE,OAAO,EAAE,eAAe,CAAA;CAAE,CAAC,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,KAAK,EAAE,qBAAqB,CAAC;IAE7B;;;;OAIG;IACH,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,UAAU,EAAE,gBAAgB,CAAC;IAC7B;;;;;OAKG;IACH,SAAS,EAAE,eAAe,CAAC;CAC5B"}

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

@@ -0,0 +1,110 @@
+import type { MakaioBusLike } from '@makaio/framework/core';
+import type { CliManifest } from './manifest.js';
+/**
+ * Type-erased output channel used by extension-local CLI handlers.
+ *
+ * Runtime code exposes the fully typed helper API via `@makaio/kernel/cli`.
+ */
+export interface ExtensionCliOutputWriter {
+    /** Write text to standard output. */
+    write(text: string): void;
+    /** Write text to standard error. */
+    error(text: string): void;
+}
+/**
+ * Type-erased handler context stored in the contracts layer.
+ *
+ * Runtime code provides the fully typed variant in `@makaio/kernel/cli`.
+ */
+export interface ExtensionCliHandlerContext<TBus extends MakaioBusLike = MakaioBusLike> {
+    /** Parsed and validated command arguments/options. */
+    readonly args: unknown;
+    /**
+     * Bus client connected to the running Makaio instance.
+     *
+     * `null` when the bus is unavailable and the contribution's `beforeRun`
+     * hook opted into offline execution.
+     */
+    readonly bus: TBus | null;
+    /** Output channel for writing to stdout and stderr. */
+    readonly output: ExtensionCliOutputWriter;
+    /** Abort signal triggered when the invocation is cancelled. */
+    readonly signal: AbortSignal;
+    /**
+     * Set the process-style exit code for the current command invocation.
+     * @param exitCode - Command exit code to report.
+     */
+    setExitCode(exitCode: number): void;
+}
+/**
+ * Interactive entry context stored in the contracts layer.
+ */
+export interface ExtensionCliInteractiveContext<TBus extends MakaioBusLike = MakaioBusLike> {
+    /**
+     * Bus client connected to the running Makaio instance.
+     *
+     * `null` when the bus is unavailable and the contribution's `beforeRun`
+     * hook opted into bus-optional execution.
+     */
+    readonly bus: TBus | null;
+}
+/**
+ * Type-erased CLI subcommand entry for collection storage.
+ *
+ * See `@makaio/kernel/cli` for the full typed API including
+ * `defineCliSubcommand`.
+ */
+export interface ExtensionCliSubcommandEntry<TBus extends MakaioBusLike = MakaioBusLike> {
+    /** Subcommand name. */
+    readonly name: string;
+    /** One-line description shown in help text. */
+    readonly description: string;
+    /** Minimal parse-only schema contract kept free of runtime Zod APIs. */
+    readonly schema: {
+        parse(v: unknown): unknown;
+    };
+    /** Handler invoked with the type-erased CLI execution context. */
+    readonly handler: (ctx: ExtensionCliHandlerContext<TBus>) => Promise<void>;
+}
+/**
+ * Type-erased context for the {@link ExtensionCliContribution.beforeRun} gate.
+ */
+export interface ExtensionCliBeforeRunContext<TBus extends MakaioBusLike = MakaioBusLike> {
+    /** Subcommand name, or `'__interactive__'` for bare interactive invocations. */
+    readonly subcommandName: string;
+    /** Parsed and validated arguments for the subcommand. */
+    readonly args: Record<string, unknown>;
+    /** Bus client, or `null` when the server is unreachable. */
+    readonly bus: TBus | null;
+}
+/**
+ * Type-erased result of an {@link ExtensionCliContribution.beforeRun} gate.
+ */
+export type ExtensionCliBeforeRunResult = {
+    readonly proceed: true;
+} | {
+    readonly proceed: false;
+    readonly message: string;
+    readonly exitCode?: number;
+};
+/**
+ * An extension's CLI contribution declared in its `MakaioExtension` manifest.
+ *
+ * Full implementation types live in `@makaio/kernel/cli`. This contract
+ * keeps the extension layer on the executable shape only.
+ */
+export interface ExtensionCliContribution<TBus extends MakaioBusLike = MakaioBusLike> extends CliManifest {
+    /**
+     * Interactive TUI launched when the command is invoked without a subcommand.
+     */
+    readonly interactive?: (ctx: ExtensionCliInteractiveContext<TBus>) => Promise<void>;
+    /** Declared subcommands exposed by this contribution. */
+    readonly subcommands: ReadonlyArray<ExtensionCliSubcommandEntry<TBus>>;
+    /**
+     * Pre-execution gate that replaces the default bus-required check.
+     * @param context - Subcommand name, parsed args, and bus availability.
+     * @returns Whether to proceed or block with a message.
+     */
+    readonly beforeRun?: (context: ExtensionCliBeforeRunContext<TBus>) => ExtensionCliBeforeRunResult | Promise<ExtensionCliBeforeRunResult>;
+}
+//# sourceMappingURL=extension-cli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extension-cli.d.ts","sourceRoot":"","sources":["../../src/extension/extension-cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,qCAAqC;IACrC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oCAAoC;IACpC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B,CAAC,IAAI,SAAS,aAAa,GAAG,aAAa;IACpF,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B,CAAC,IAAI,SAAS,aAAa,GAAG,aAAa;IACxF;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,IAAI,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B,CAAC,IAAI,SAAS,aAAa,GAAG,aAAa;IACrF,uBAAuB;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,CAAC;IAChD,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,0BAA0B,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5E;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B,CAAC,IAAI,SAAS,aAAa,GAAG,aAAa;IACtF,gFAAgF;IAChF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,EAAE,IAAI,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,MAAM,2BAA2B,GACnC;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB,CAAC,IAAI,SAAS,aAAa,GAAG,aAAa,CAAE,SAAQ,WAAW;IACvG;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,8BAA8B,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,2BAA2B,CAAC,IAAI,CAAC,CAAC,CAAC;IACvE;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CACnB,OAAO,EAAE,4BAA4B,CAAC,IAAI,CAAC,KACxC,2BAA2B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACzE"}

package/dist/extension/extension-config-provider.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Provider for persisted extension configuration and enablement state.
+ *
+ * Injected by the host composition root. When absent, all extensions start
+ * enabled with default (Zod-schema) configuration only.
+ */
+export interface ExtensionConfigProvider {
+    /**
+     * Load persisted configuration for an extension by name.
+     *
+     * Returns `undefined` when no stored config exists for the extension.
+     * Invalid values are ignored by the coordinator during schema parse.
+     * @param name - Extension package name.
+     * @returns Stored configuration object, or `undefined` when absent.
+     */
+    loadConfig(name: string): Record<string, unknown> | undefined;
+    /**
+     * Check whether an extension is enabled in persistent storage.
+     *
+     * Returns `undefined` to indicate no persisted preference — the coordinator
+     * treats `undefined` the same as `true` (start normally).
+     * @param name - Extension package name.
+     * @returns `false` to skip the package at boot, `true` or `undefined` to start normally.
+     */
+    loadEnabled(name: string): boolean | undefined;
+}
+//# sourceMappingURL=extension-config-provider.d.ts.map

package/dist/extension/extension-config-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-config-provider.d.ts","sourceRoot":"","sources":["../../src/extension/extension-config-provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAE9D;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CAChD"}

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

@@ -0,0 +1,100 @@
+import type { MakaioBusLike } from '@makaio/framework/core';
+import type { ExtensionToken } from './extension-token.js';
+import type { ExtensionIdentity } from './extension-lifecycle.js';
+/**
+ * Generic context provided by a host runtime when creating an extension's service.
+ *
+ * Contains host-agnostic runtime seams: the bus instance, extension identity,
+ * extension-local data directory, machine identity, config, service lookup, and
+ * lifecycle controls. Host-specific environment details belong on explicit
+ * context extensions such as {@link NodeExtensionContext}.
+ */
+export interface ExtensionContext<TBus extends MakaioBusLike = MakaioBusLike> {
+    /** Bus instance for registering handlers and emitting events. */
+    readonly bus: TBus;
+    /** Coordinator-minted identity for the extension being created. */
+    readonly identity: ExtensionIdentity;
+    /**
+     * Per-extension writable data directory resolved by the host runtime.
+     *
+     * Use this for extension-local persistence (caches, state files, etc.).
+     */
+    readonly dataDir: string;
+    /**
+     * Stable machine identifier used for machine-scoped persistence and
+     * encryption key derivation.
+     *
+     * Resolved by the composition root (e.g., `node-machine-id`) before
+     * extensions are started.
+     */
+    readonly machineId: string;
+    /**
+     * Resolved configuration for this extension, merged from stored values and
+     * descriptor defaults. Present only when the extension declared a
+     * `configSchema` on its {@link MakaioExtension}.
+     *
+     * Extensions should parse this with their Zod schema to get typed config:
+     * ```ts
+     * const config = parseExtensionConfig(MyConfigSchema, ctx.config);
+     * ```
+     */
+    readonly config?: unknown;
+    /**
+     * Retrieve a service exposed by another active extension.
+     * @param token - Extension-owned token identifying the desired service.
+     * @returns The active service instance, or `undefined` when unavailable.
+     */
+    getService<T>(token: ExtensionToken<T>): T | undefined;
+    /**
+     * Attempt a dynamic import, returning `null` when the package is not installed.
+     *
+     * Only swallows errors caused by the package itself being absent. Transitive
+     * dependency failures and module evaluation errors are re-thrown.
+     * @typeParam T - Expected module shape (caller-asserted, not runtime-verified).
+     * @param specifier - Package specifier to import.
+     * @returns The imported module cast to `T`, or `null` when the package is not installed.
+     */
+    readonly tryImport: <T>(specifier: string) => Promise<T | null>;
+    /**
+     * Abort signal triggered during graceful shutdown.
+     *
+     * Extensions can pass this to long-running operations (fetch, timers, streams)
+     * so they cancel promptly when the runtime is stopping.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Check whether an extension with the given name is active.
+     *
+     * Returns `true` when the named extension has been loaded and reached
+     * `active` state. Use this for optional integration checks without
+     * requiring an ExtensionToken.
+     * @param name - Extension name to check.
+     * @returns `true` when the extension is active.
+     */
+    readonly hasExtension: (name: string) => boolean;
+}
+/**
+ * Node.js host extension context.
+ *
+ * Adds the OS and filesystem fields supplied by Node-based composition roots.
+ * Extensions that need these fields should opt into this context explicitly;
+ * host-agnostic extensions can type themselves against {@link ExtensionContext}.
+ */
+export interface NodeExtensionContext<TBus extends MakaioBusLike = MakaioBusLike> extends ExtensionContext<TBus> {
+    /** Current platform identifier (e.g., `'darwin'`, `'linux'`, `'win32'`). */
+    readonly platform: NodeJS.Platform;
+    /** User's home directory path. */
+    readonly homedir: string;
+    /** Resolved `.makaio` directory root (e.g., `~/.makaio`). */
+    readonly makaioHome: string;
+    /** Current OS username. */
+    readonly username: string;
+    /**
+     * WebSocket URL for the host bus, when the runtime exposes one.
+     *
+     * Detached `bus-websocket` extensions use this to connect back to the host.
+     * Hosts without a WebSocket bus omit it.
+     */
+    readonly busUrl?: string;
+}
+//# sourceMappingURL=extension-context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extension-context.d.ts","sourceRoot":"","sources":["../../src/extension/extension-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB,CAAC,IAAI,SAAS,aAAa,GAAG,aAAa;IAC1E,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IACnB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IACvD;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAChE;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CAClD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB,CAAC,IAAI,SAAS,aAAa,GAAG,aAAa,CAAE,SAAQ,gBAAgB,CAAC,IAAI,CAAC;IAC9G,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IACnC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2BAA2B;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B"}