@makaio/contracts 1.0.0-dev-1779051654000

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

@@ -0,0 +1,156 @@
+import type { MakaioBusLike, SubjectSchema } from '@makaio/framework/core';
+import type { Toolset } from '@makaio/framework/tools';
+import type { AdapterManifest } from './contribution-manifest.js';
+import type { AdapterDefinitionContract } from './adapter-definition.js';
+import type { ExtensionContext, NodeExtensionContext } from './extension-context.js';
+import type { SessionEventActionContext, CreateSessionEventActionResult } from './contributions/session-event-action-types.js';
+import type { HashTrigger } from './contributions/hash-trigger-types.js';
+import type { TileDeclaration } from './contributions/tile-types.js';
+import type { WidgetDeclaration } from './contributions/widget-types.js';
+import type { PageDeclaration } from './contributions/page-types.js';
+import type { ToolCallFormatterDeclaration } from './contributions/tool-formatter-types.js';
+import type { MakaioWebUiRoute, MakaioWebUiActions, ExtensionConfigComponentLoader, ExtensionFieldTypeLoader } from './contributions/web-ui-types.js';
+/**
+ * Typed adapter contribution declared by an extension.
+ *
+ * The `manifest` field carries the adapter metadata that runtime processors
+ * consume alongside the executable `definition`. Descriptor-level
+ * `ExtensionManifest.contributions.adapters` may repeat this metadata for
+ * pre-load discovery, but activation reads this executable surface.
+ * @typeParam TAdapter - Concrete adapter instance type. Defaults to `unknown`
+ *   for use in collections where the concrete type is not available.
+ */
+export interface AdapterContribution<TAdapter = unknown> {
+    /** Runtime adapter metadata paired with the executable definition. */
+    readonly manifest: AdapterManifest;
+    /**
+     * Full adapter runtime definition.
+     *
+     * Typed via {@link AdapterDefinitionContract} — the adapter subsystem
+     * consumes this directly. The generic parameter allows higher-level types
+     * (e.g., `AIAdapterDefinition`) to narrow the factory return type.
+     */
+    readonly definition: AdapterDefinitionContract<TAdapter>;
+}
+/**
+ * Opaque log import contribution declared by an extension.
+ *
+ * Typed as `unknown` in the contracts layer to avoid importing from
+ * `ai-adapters-core`. The log-import contribution processor narrows
+ * this to `PluginLogImport` at processing time.
+ */
+export interface LogImportContribution {
+    /** Adapter name for attribution (e.g. `'opencode'`). */
+    readonly adapterName: string;
+    /** Human-readable display name (e.g. `'OpenCode'`). */
+    readonly displayName: string;
+    /** Full log importer configuration, opaque in contracts. */
+    readonly config: unknown;
+}
+/** Tool contribution surface declared by an extension. */
+export interface ExtensionToolsContribution<THostContext extends ExtensionContext = NodeExtensionContext> {
+    /**
+     * Create toolsets for this extension.
+     * @param ctx - Runtime context with bus, host details, and machine identity.
+     * @returns Array of toolsets to register with `ToolRegistry`.
+     */
+    readonly createToolsets: (ctx: THostContext) => Toolset[];
+}
+/**
+ * Hash trigger contribution surface declared by an extension.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+export interface ExtensionTriggersContribution<TBus extends MakaioBusLike = MakaioBusLike> {
+    /**
+     * Create hash triggers for this extension.
+     * @param bus - The bus instance for trigger operations.
+     * @returns Array of hash triggers to register with `HashTriggerService`.
+     */
+    readonly createTriggers: (bus: TBus) => HashTrigger<TBus>[];
+}
+/**
+ * Session event action contribution surface declared by an extension.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+export interface ExtensionSessionEventActionsContribution<TBus extends MakaioBusLike = MakaioBusLike> {
+    /**
+     * Create session event actions for this extension.
+     * @param ctx - Context with bus instance and extension metadata.
+     * @returns Map of action ID to registration result (declaration + unregister).
+     */
+    readonly createActions: (ctx: SessionEventActionContext<TBus>) => Record<string, CreateSessionEventActionResult>;
+}
+/** Bus namespace introspection surface declared by an extension. */
+export interface ExtensionNamespaceContribution {
+    /**
+     * Schema record for bus subject introspection.
+     *
+     * Keys are subject short-names; values are subject schema descriptors.
+     */
+    readonly schemas: Record<string, SubjectSchema>;
+}
+/** Browser UI contribution surface declared by an extension. */
+export interface ExtensionUiContribution {
+    /**
+     * WebUI routes mounted under `/extensions/<extension-name>/`.
+     *
+     * Each route defines a path, an optional data loader, optional action
+     * handlers, and a lazy-loaded React component.
+     */
+    readonly routes?: readonly MakaioWebUiRoute<unknown, MakaioWebUiActions | undefined>[];
+    /**
+     * Tile declarations for pane-placeable content.
+     *
+     * Tiles are registered with `TileRegistry` and shown in the "Add Pane"
+     * palette. Each declaration includes metadata, an icon, and platform
+     * renderers.
+     */
+    readonly tiles?: readonly TileDeclaration[];
+    /**
+     * Widget declarations for small dashboard cards.
+     *
+     * Widgets are registered in the global widget catalog. They are NOT pane
+     * content — use `tiles` for pane-placeable content.
+     */
+    readonly widgets?: readonly WidgetDeclaration[];
+    /**
+     * Page declarations for the page registry and optional sidebar navigation.
+     *
+     * Pages are registered in the page registry. When `mode`, `level`, and
+     * `component` are provided, the loader also registers the page in the
+     * sidebar navigation (`PageDefinitionRegistry`).
+     */
+    readonly pages?: readonly PageDeclaration[];
+    /**
+     * Tool call formatter declarations.
+     *
+     * Formatters customize how specific tool calls are rendered in the chat
+     * UI. Registered with `ToolCallFormatterRegistry` on extension load.
+     */
+    readonly toolFormatters?: readonly ToolCallFormatterDeclaration[];
+    /**
+     * Custom field type loaders for schema-driven forms.
+     *
+     * Maps field type identifiers to lazy-loaded React components that accept
+     * `FormFieldProps`. Registered with `FormFieldRegistry` on extension load.
+     * @example
+     * ```typescript
+     * fieldTypes: {
+     *   'image-upload': () => import('./ui/ImageUploadField.js'),
+     * }
+     * ```
+     */
+    readonly fieldTypes?: Record<string, ExtensionFieldTypeLoader>;
+    /**
+     * Fully custom configuration component loader.
+     *
+     * When provided, the schema-driven form is bypassed entirely. Use this
+     * for complex UIs where &gt;50% of fields need custom rendering.
+     * @example
+     * ```typescript
+     * configComponent: () => import('./ui/CustomConfigPanel.js'),
+     * ```
+     */
+    readonly configComponent?: ExtensionConfigComponentLoader;
+}
+//# sourceMappingURL=extension-contributions.d.ts.map

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

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

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

@@ -0,0 +1,413 @@
+/**
+ * Pure-data descriptor for Makaio extensions.
+ *
+ * Maps 1:1 to `descriptor.json` shipped in the extension package root.
+ * Extends {@link ExtensionManifest} with distribution-only fields: version,
+ * entry points, execution mode, and version compatibility gate.
+ *
+ * The loading bridge reads this descriptor, validates it, and dynamically
+ * imports the appropriate entry point to produce a {@link MakaioExtension}.
+ * Descriptor `contributions` are intentionally not merged into that executable
+ * extension; they remain pre-load metadata for discovery and inspection.
+ */
+import { z } from 'zod';
+import type { ExtensionManifest } from './manifest.js';
+import type { VersionRange } from '../version/index.js';
+/**
+ * Discriminated union of supported transports for detached extensions.
+ *
+ * - `bus-stdio` — bidirectional Makaio bus over stdin/stdout.
+ * - `bus-websocket` — bidirectional Makaio bus over a WebSocket connection.
+ * - `mcp-stdio` — MCP protocol over stdin/stdout (no restart policy).
+ */
+export declare const DetachedTransportSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    healthTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    shutdownTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    restartPolicy: z.ZodOptional<z.ZodEnum<{
+        always: "always";
+        none: "none";
+        "on-crash": "on-crash";
+    }>>;
+    type: z.ZodLiteral<"bus-stdio">;
+}, z.core.$strip>, z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    healthTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    shutdownTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    restartPolicy: z.ZodOptional<z.ZodEnum<{
+        always: "always";
+        none: "none";
+        "on-crash": "on-crash";
+    }>>;
+    type: z.ZodLiteral<"bus-websocket">;
+}, z.core.$strip>, z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    healthTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    shutdownTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"mcp-stdio">;
+}, z.core.$strip>], "type">;
+/** Inferred type from {@link DetachedTransportSchema}. */
+export type DetachedTransportConfig = z.infer<typeof DetachedTransportSchema>;
+/**
+ * Convention-based entrypoint declarations for each runtime surface.
+ *
+ * `true` means "use the surface name as the stem". A string value is a custom
+ * stem whose final path segment names the file (e.g. `"cli/index"` resolves to
+ * `src/cli/index.ts` in dev or `dist/cli/index.mjs` in production). Omit
+ * surfaces the extension does not target.
+ *
+ * The runtime resolves the stem by trying `src/{stem}.ts` first (dev), then
+ * `dist/{stem}.mjs` (production). No path prefix or file extension should be
+ * included in the descriptor — those are added by convention.
+ */
+export interface ExtensionEntrypoints {
+    /** Server entry — exports a {@link MakaioExtension} as default export. */
+    readonly server?: true | string;
+    /** Browser entry — bundled JS loaded in the renderer. */
+    readonly browser?: true | string;
+    /** CLI entry — exports an `ExtensionCliContribution` as default export. */
+    readonly cli?: true | string;
+}
+/** Zod schema for {@link ExtensionEntrypoints}. */
+export declare const ExtensionEntrypointsSchema: z.ZodObject<{
+    server: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodString]>>;
+    browser: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodString]>>;
+    cli: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodString]>>;
+}, z.core.$strip>;
+/**
+ * Shared base fields for all extension descriptors.
+ *
+ * Contains the fields common to both embedded and detached descriptors,
+ * excluding `entrypoints` and `transport` which differ per execution mode.
+ */
+export interface ExtensionDescriptorBase extends ExtensionManifest {
+    /** SemVer version of the extension package. */
+    readonly version: string;
+    /** Framework version range required (npm semver range, e.g. `">=1.0.0 <2.0.0"`). */
+    readonly makaio: {
+        readonly framework: VersionRange;
+    };
+    /**
+     * Default configuration values for this extension.
+     *
+     * Applied when no stored config exists. Keys should match the properties
+     * in the extension's `configSchema` (declared on its {@link MakaioExtension}).
+     * The Zod schema's own `.default()` values layer on top of these.
+     */
+    readonly config?: {
+        readonly defaults?: Readonly<Record<string, unknown>>;
+    };
+}
+/**
+ * Descriptor for extensions running in the host process (default mode).
+ *
+ * `entrypoints` is required; `execution` is `'embedded'` or omitted.
+ * `transport` must be absent.
+ */
+export interface EmbeddedDescriptor extends ExtensionDescriptorBase {
+    /**
+     * Handler execution mode — `'embedded'` or omitted (defaults to embedded).
+     * Code is `import()`'d directly into the host process.
+     */
+    readonly execution?: 'embedded';
+    /**
+     * Convention-based entrypoint stems and enabled-surface flags per runtime
+     * surface. Required for embedded extensions.
+     */
+    readonly entrypoints: ExtensionEntrypoints;
+    /** Must be absent for embedded extensions. */
+    readonly transport?: undefined;
+}
+/**
+ * Descriptor for extensions running as child processes.
+ *
+ * `transport` is required; `execution` must be `'detached'`.
+ * `entrypoints` must be absent.
+ */
+export interface DetachedDescriptor extends ExtensionDescriptorBase {
+    /**
+     * Handler execution mode — must be `'detached'` for subprocess extensions.
+     * The extension runs as a child process communicating via the chosen transport.
+     */
+    readonly execution: 'detached';
+    /**
+     * Transport configuration for detached extensions.
+     *
+     * Specifies the IPC mechanism and process lifecycle options for the child
+     * process.
+     */
+    readonly transport: DetachedTransportConfig;
+    /** Must be absent for detached extensions. */
+    readonly entrypoints?: undefined;
+}
+/**
+ * Discriminated union of extension descriptor shapes.
+ *
+ * Narrows automatically via `execution` check:
+ * - `descriptor.execution === 'detached'` → `DetachedDescriptor`
+ * - Otherwise (including `undefined`) → `EmbeddedDescriptor`
+ *
+ * Use {@link isDetachedDescriptor} for an explicit type guard.
+ */
+export type ExtensionDescriptor = EmbeddedDescriptor | DetachedDescriptor;
+/**
+ * Type guard for detached extension descriptors.
+ *
+ * After this guard returns `true`, TypeScript narrows the descriptor to
+ * {@link DetachedDescriptor} where `transport` is required and `entrypoints`
+ * is absent.
+ * @param descriptor - The extension descriptor to check.
+ * @returns Whether the descriptor is for a detached (subprocess) extension.
+ */
+export declare function isDetachedDescriptor(descriptor: ExtensionDescriptor): descriptor is DetachedDescriptor;
+/**
+ * Zod schema for {@link ExtensionDescriptor}.
+ *
+ * Enforces execution-mode invariants via `superRefine`:
+ * - `execution === 'detached'` requires `transport`; `entrypoints` is optional.
+ * - All other modes (including the default embedded mode) require `entrypoints`.
+ *
+ * Note: `satisfies z.ZodType<ExtensionDescriptor>` is intentionally omitted
+ * because `superRefine` wraps the schema in `ZodEffects`, which is incompatible
+ * with that constraint.
+ */
+export declare const ExtensionDescriptorSchema: z.ZodObject<{
+    name: z.ZodString;
+    displayName: z.ZodString;
+    surface: z.ZodOptional<z.ZodEnum<{
+        any: "any";
+        headless: "headless";
+        interactive: "interactive";
+    }>>;
+    dependencies: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"extension">;
+        name: z.ZodString;
+        version: z.ZodString;
+        optional: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>>;
+    requires: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"host">;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"capability">;
+        id: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "type">>>>;
+    provides: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodType<"adapters", unknown, z.core.$ZodTypeInternals<"adapters", unknown>>>>>;
+    windows: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        style: z.ZodEnum<{
+            panel: "panel";
+            "tray-popover": "tray-popover";
+            utility: "utility";
+        }>;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        singleton: z.ZodOptional<z.ZodBoolean>;
+        params: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            required: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strip>>>>;
+    tray: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        section: z.ZodOptional<z.ZodEnum<{
+            tools: "tools";
+            utilities: "utilities";
+            views: "views";
+        }>>;
+        opensWindow: z.ZodOptional<z.ZodString>;
+        action: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    cli: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        subcommands: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            args: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                description: z.ZodString;
+                required: z.ZodOptional<z.ZodBoolean>;
+                positional: z.ZodOptional<z.ZodBoolean>;
+                short: z.ZodOptional<z.ZodString>;
+                type: z.ZodOptional<z.ZodEnum<{
+                    boolean: "boolean";
+                    number: "number";
+                    string: "string";
+                }>>;
+            }, z.core.$strip>>>>;
+        }, z.core.$strip>>>>;
+        hasInteractive: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    storage: z.ZodOptional<z.ZodObject<{
+        migrations: z.ZodOptional<z.ZodString>;
+        migrationSourceId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    browser: z.ZodOptional<z.ZodObject<{
+        entrypoint: z.ZodString;
+    }, z.core.$strip>>;
+    contributions: z.ZodOptional<z.ZodObject<{
+        adapters: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            displayName: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            clients: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                version: z.ZodString;
+                binaryVersion: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>>;
+            protocols: z.ZodReadonly<z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<{
+                anthropic: "anthropic";
+                openai: "openai";
+            }>, z.ZodObject<{
+                anthropic: z.ZodOptional<z.ZodObject<{
+                    endpoint: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+                openai: z.ZodOptional<z.ZodObject<{
+                    endpoint: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>]>>>;
+            defaultProvider: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>>;
+        clients: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            binary: z.ZodOptional<z.ZodObject<{
+                name: z.ZodString;
+                managed: z.ZodOptional<z.ZodBoolean>;
+                version: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>>>;
+        providers: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>>;
+        triggers: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            prefix: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            stage: z.ZodOptional<z.ZodEnum<{
+                action: "action";
+                gather: "gather";
+                transform: "transform";
+            }>>;
+        }, z.core.$strip>>>>;
+        logImporters: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            adapterName: z.ZodString;
+            displayName: z.ZodString;
+            logFilePattern: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>>;
+        sessionEventActions: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            icon: z.ZodOptional<z.ZodString>;
+            selectionMode: z.ZodEnum<{
+                multi: "multi";
+                single: "single";
+            }>;
+            messageRoles: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+                assistant: "assistant";
+                user: "user";
+            }>>>>;
+        }, z.core.$strip>>>>;
+        create: z.ZodOptional<z.ZodBoolean>;
+        tools: z.ZodOptional<z.ZodBoolean>;
+        bootstrap: z.ZodOptional<z.ZodBoolean>;
+        namespace: z.ZodOptional<z.ZodBoolean>;
+        configSchema: z.ZodOptional<z.ZodBoolean>;
+        uiConfig: z.ZodOptional<z.ZodBoolean>;
+        ui: z.ZodOptional<z.ZodObject<{
+            tiles: z.ZodOptional<z.ZodBoolean>;
+            widgets: z.ZodOptional<z.ZodBoolean>;
+            pages: z.ZodOptional<z.ZodBoolean>;
+            routes: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    version: z.ZodString;
+    makaio: z.ZodReadonly<z.ZodObject<{
+        framework: z.ZodString;
+    }, z.core.$strict>>;
+    entrypoints: z.ZodOptional<z.ZodObject<{
+        server: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodString]>>;
+        browser: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodString]>>;
+        cli: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodString]>>;
+    }, z.core.$strip>>;
+    execution: z.ZodOptional<z.ZodEnum<{
+        detached: "detached";
+        embedded: "embedded";
+    }>>;
+    transport: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        healthTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        shutdownTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        restartPolicy: z.ZodOptional<z.ZodEnum<{
+            always: "always";
+            none: "none";
+            "on-crash": "on-crash";
+        }>>;
+        type: z.ZodLiteral<"bus-stdio">;
+    }, z.core.$strip>, z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        healthTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        shutdownTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        restartPolicy: z.ZodOptional<z.ZodEnum<{
+            always: "always";
+            none: "none";
+            "on-crash": "on-crash";
+        }>>;
+        type: z.ZodLiteral<"bus-websocket">;
+    }, z.core.$strip>, z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        healthTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        shutdownTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"mcp-stdio">;
+    }, z.core.$strip>], "type">>;
+    config: z.ZodOptional<z.ZodObject<{
+        defaults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Parse and validate an extension descriptor from raw JSON input.
+ *
+ * This is the typed wrapper around {@link ExtensionDescriptorSchema} that
+ * returns the {@link ExtensionDescriptor} discriminated union. Throws a Zod
+ * error on invalid input.
+ * @param input - Raw JSON-like value to parse.
+ * @returns Parsed and typed extension descriptor.
+ */
+export declare function parseExtensionDescriptor(input: unknown): ExtensionDescriptor;
+/** Result shape returned by {@link safeParseExtensionDescriptor}. */
+export type ExtensionDescriptorParseResult = {
+    readonly success: true;
+    readonly data: ExtensionDescriptor;
+} | {
+    readonly success: false;
+    readonly error: z.ZodError;
+};
+/**
+ * Safely parse and validate an extension descriptor from raw JSON input.
+ *
+ * This is the typed wrapper around {@link ExtensionDescriptorSchema} that
+ * returns a result with the {@link ExtensionDescriptor} discriminated union on
+ * success.
+ * @param input - Raw JSON-like value to parse.
+ * @returns Parse result with `data` typed as {@link ExtensionDescriptor} on
+ *   success, or a Zod error on failure.
+ */
+export declare function safeParseExtensionDescriptor(input: unknown): ExtensionDescriptorParseResult;
+//# sourceMappingURL=extension-descriptor.d.ts.map

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

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

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

@@ -0,0 +1,46 @@
+import type { ExtensionWarning } from './extension-warning.js';
+declare const extensionIdentityBrand: unique symbol;
+/**
+ * Opaque extension identity minted by the runtime coordinator.
+ *
+ * This identity proves which loaded extension is calling runtime-owned seams
+ * such as future direct channels. Extension code receives it through
+ * {@link ExtensionContext.identity}; external callers cannot construct one
+ * without a type assertion.
+ */
+export interface ExtensionIdentity {
+    /** Extension name associated with this identity. */
+    readonly extensionName: string;
+    /** Opaque brand preventing structural construction. */
+    readonly [extensionIdentityBrand]: true;
+}
+/**
+ * Minimal lifecycle shape accepted as an extension service.
+ *
+ * BaseService satisfies this interface, but plain service classes can also
+ * participate in extension startup when they expose the same lifecycle.
+ */
+export interface ExtensionServiceLifecycle {
+    /** Initialize the service when startup work is not constructor-owned. */
+    init?(): Promise<void> | void;
+    /** Destroy the service and release resources when teardown is required. */
+    destroy?(): Promise<void> | void;
+    /**
+     * Called after the extension reaches active state.
+     *
+     * Returns zero or more {@link ExtensionWarning} entries describing integration
+     * health issues the user may want to act on. An empty array (or omitting the
+     * hook entirely) signals that the extension is fully healthy.
+     * @returns Active health warnings, or an empty array when the extension is healthy.
+     */
+    checkHealth?(): Promise<ExtensionWarning[]> | ExtensionWarning[];
+}
+/**
+ * Service shape returned by {@link MakaioExtension.create}.
+ *
+ * Any class that extends `BaseService` satisfies this interface structurally
+ * because `BaseService` exposes the same lifecycle methods.
+ */
+export type ExtensionService = ExtensionServiceLifecycle;
+export {};
+//# sourceMappingURL=extension-lifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extension-lifecycle.d.ts","sourceRoot":"","sources":["../../src/extension/extension-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,CAAC,MAAM,sBAAsB,EAAE,OAAO,MAAM,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAC;CACzC;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,yEAAyE;IACzE,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9B,2EAA2E;IAC3E,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjC;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,GAAG,gBAAgB,EAAE,CAAC;CAClE;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,yBAAyB,CAAC"}

package/dist/extension/extension-runtime-boot.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Runtime subsystems with exactly one executable owner per boot.
+ *
+ * These declarations are runtime-owned metadata on {@link MakaioExtension},
+ * not descriptor discovery metadata. Boot uses them to select default
+ * framework packages only when no loaded extension provides the same
+ * executable responsibility.
+ */
+export interface ExtensionRuntimeOwnership {
+    /** Owns the `session.sendMessage` orchestration handlers for this runtime. */
+    readonly sessionOrchestrator?: boolean;
+}
+//# sourceMappingURL=extension-runtime-boot.d.ts.map

package/dist/extension/extension-runtime-boot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-runtime-boot.d.ts","sourceRoot":"","sources":["../../src/extension/extension-runtime-boot.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC"}