@makaio/framework 1.0.0-dev-1779046984397

package/dist/index-BB419vv-.d.mts

@@ -0,0 +1,3897 @@
+import { A as VersionRange, O as VersionLiteral, r as ClientDefinition } from "./definition-DxvZ9e22.mjs";
+import { t as RequiredTimeoutConfig } from "./schemas-CGZy_rU6.mjs";
+import { o as ProviderDefinitionInput, r as ProtocolId } from "./definition-DtUNiGom.mjs";
+import { B as SESSION_EVENT_TYPES, i as MakaioSessionEvent, p as SessionMessage } from "./types-BjToUrHp.mjs";
+import { D as EntityUIConfig, I as FormFieldProps } from "./index-BJOfdtbw.mjs";
+import { z } from "zod";
+import { MakaioBusLike, PayloadFilter, RegistrableBusNamespaceDefinition, SubjectSchema } from "@makaio/framework/core";
+import { Toolset } from "@makaio/framework/tools";
+import { ComponentType } from "react";
+
+//#region packages/contracts/src/extension/browser-entrypoint.d.ts
+/**
+ * Browser entrypoint metadata declared by a package manifest.
+ *
+ * The renderer uses this URL path to load a package's browser bundle.
+ */
+declare const BrowserEntrypointSchema: z.ZodObject<{
+  entrypoint: z.ZodString;
+}, z.core.$strip>;
+/** Inferred type for browser entrypoint manifest metadata. */
+type BrowserEntrypoint = z.infer<typeof BrowserEntrypointSchema>;
+//#endregion
+//#region packages/contracts/src/extension/contribution-manifest.d.ts
+/**
+ * Protocol-specific configuration for an adapter contribution.
+ *
+ * Acts as a seam for future protocol-level settings (e.g., custom base URLs,
+ * auth overrides, timeout policies). Currently intentionally empty — consuming
+ * code should treat an absent value the same as `{}`.
+ */
+interface ProtocolConfig {
+  /** Optional custom endpoint URL overriding the protocol default. */
+  readonly endpoint?: string;
+}
+/** Zod schema for {@link ProtocolConfig}. */
+declare const ProtocolConfigSchema: z.ZodObject<{
+  endpoint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Reference to a supported wire protocol, with optional per-protocol config.
+ *
+ * - **Simple string** — use the protocol with default settings: `'anthropic'`.
+ * - **Config object** — declare one or more protocols with overrides:
+ *   `{ anthropic: { endpoint: 'https://custom.host/v1' } }`.
+ *
+ * Both forms are valid in the `protocols` array on {@link AdapterManifest}.
+ * @example Simple form
+ * ```json
+ * "protocols": ["anthropic", "openai"]
+ * ```
+ * @example Config form
+ * ```json
+ * "protocols": [{ "anthropic": { "endpoint": "https://custom.host/v1" } }]
+ * ```
+ */
+type ProtocolRef = ProtocolId | { readonly [K in ProtocolId]?: ProtocolConfig };
+/** Zod schema for {@link ProtocolRef}. */
+declare const ProtocolRefSchema: 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>]>;
+/**
+ * Reference from an adapter to a client package it depends on.
+ *
+ * The `version` field follows npm/package.json semver range syntax so the
+ * executable adapter contribution can verify compatibility against the
+ * installed client (npm package) version. The optional `binaryVersion` field
+ * constrains the version of the shipped binary separately — useful when the
+ * npm package version and the embedded binary version diverge.
+ * @example `{ id: 'claude-code', version: '^1.5.0' }`
+ * @example `{ id: 'claude-code', version: '^1.5.0', binaryVersion: '>=1.0.0 <1.2.0' }`
+ */
+interface AdapterClientRef {
+  /** Stable client identifier matching {@link ClientManifest.id}. */
+  readonly id: string;
+  /**
+   * Semver range the adapter is compatible with for the npm package version.
+   *
+   * Uses the same syntax as `package.json` dependency fields
+   * (e.g., `'^1.5.0'`, `'>=2.0.0'`, `'*'`).
+   */
+  readonly version: VersionRange;
+  /**
+   * Optional semver range constraining the binary version separately from the
+   * npm package version. The adapter subsystem evaluates this field at
+   * activation time by resolving the active client binary.
+   *
+   * Omit when the binary version is assumed to match the npm package version.
+   */
+  readonly binaryVersion?: VersionRange;
+}
+/** Zod schema for {@link AdapterClientRef}. */
+declare const AdapterClientRefSchema: z.ZodObject<{
+  id: z.ZodString;
+  version: z.ZodString;
+  binaryVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Describes an adapter contributed by an extension.
+ *
+ * Serializable metadata for discovery, filtering, and inspection. The
+ * executable runtime source is `MakaioExtension.adapters[].manifest`, paired
+ * with its adapter definition; descriptor-level contributions do not register
+ * adapters by themselves.
+ *
+ * The `protocols` field is required because an adapter must declare at least
+ * which wire protocol(s) it implements; all other fields are optional metadata.
+ */
+interface AdapterManifest {
+  /**
+   * Stable machine identifier for this adapter contribution (e.g., `'claude-code'`).
+   *
+   * Used as the key in adapter registries. Must be unique within the declaring
+   * extension.
+   */
+  readonly name: string;
+  /** Human-readable display name shown in the UI (e.g., `'Claude Code'`). */
+  readonly displayName?: string;
+  /** Short description of what this adapter does. */
+  readonly description?: string;
+  /**
+   * Client packages this adapter depends on.
+   *
+   * Each entry declares a required client by ID and semver range. Executable
+   * adapter processors verify that referenced clients are installed and
+   * compatible before activating the adapter.
+   */
+  readonly clients?: readonly AdapterClientRef[];
+  /**
+   * Wire protocol(s) this adapter implements.
+   *
+   * At least one entry is required. Each entry is either a plain
+   * {@link ProtocolId} string or a {@link ProtocolRef} config object with
+   * per-protocol overrides.
+   */
+  readonly protocols: readonly ProtocolRef[];
+  /**
+   * Identifier of the provider this adapter defaults to.
+   *
+   * When omitted, the runtime or user selects the provider. Must reference a
+   * registered provider definition `id`.
+   */
+  readonly defaultProvider?: string;
+}
+/** Zod schema for {@link AdapterManifest}. */
+declare const AdapterManifestSchema: 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>;
+/**
+ * Describes a client binary contributed by an extension.
+ *
+ * A "client" is a standalone executable (e.g., the Claude Code CLI) that an
+ * adapter delegates work to. This manifest is discovery-time metadata;
+ * executable `MakaioExtension.clients` definitions are the runtime source for
+ * locating, verifying, and managing the binary lifecycle.
+ */
+interface ClientManifest {
+  /**
+   * Stable machine identifier for this client (e.g., `'claude-code'`).
+   *
+   * Must be unique within the declaring extension. Referenced by
+   * {@link AdapterClientRef.id} to express adapter-to-client dependencies.
+   */
+  readonly id: string;
+  /** Human-readable display name (e.g., `'Claude Code'`). */
+  readonly name: string;
+  /** Short description of what this client binary does. */
+  readonly description?: string;
+  /**
+   * Binary identity for this client.
+   *
+   * When present, carries the executable name used for PATH detection.
+   * When omitted, executable client definitions use {@link id} as the
+   * default binary lookup key.
+   * @example `{ name: 'claude' }`
+   */
+  readonly binary?: {
+    readonly name: string;
+  };
+}
+/** Zod schema for {@link ClientManifest}. */
+declare const ClientManifestSchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  binary: z.ZodOptional<z.ZodObject<{
+    name: z.ZodString;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+/**
+ * Describes a model provider contributed by an extension.
+ *
+ * A "provider" is an inference backend (e.g., Anthropic, OpenAI, Z.AI) that
+ * adapters use to route model requests. This manifest is discovery-time
+ * metadata; executable `MakaioExtension.providers` definitions are the
+ * runtime source for credential resolution and model catalog registration.
+ * @example
+ * ```json
+ * { "id": "anthropic", "name": "Anthropic", "description": "Official Anthropic API" }
+ * ```
+ */
+interface ProviderManifest {
+  /**
+   * Stable machine identifier for this provider (e.g., `'anthropic'`).
+   *
+   * Must be unique within the declaring extension. Used as the primary key
+   * in provider registries and referenced by
+   * {@link AdapterManifest.defaultProvider}.
+   */
+  readonly id: string;
+  /** Human-readable display name (e.g., `'Anthropic'`). */
+  readonly name: string;
+  /** Short description of this provider. */
+  readonly description?: string;
+}
+/** Zod schema for {@link ProviderManifest}. */
+declare const ProviderManifestSchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Pipeline stage a hash trigger participates in.
+ *
+ * Mirrors {@link HashTriggerStage} from the runtime contribution types.
+ * Kept as a local type alias so this manifest module remains self-contained.
+ */
+type TriggerStage = 'gather' | 'transform' | 'action';
+/**
+ * Describes a hash trigger contributed by an extension.
+ *
+ * Serializable metadata for discovery and introspection. The executable
+ * runtime source is `MakaioExtension.triggers.createTriggers()`; descriptor
+ * contributions are not a registration fallback.
+ */
+interface TriggerManifest {
+  /**
+   * Prefix token this trigger responds to (e.g., `'loop'`, `'file'`).
+   *
+   * Must be unique within the declaring extension. Used by the hash trigger
+   * service to route `#prefix:argument` directives.
+   */
+  readonly prefix: string;
+  /** Human-readable description of what this trigger does. */
+  readonly description?: string;
+  /**
+   * Pipeline stage this trigger participates in.
+   *
+   * Defaults to `'action'` when omitted.
+   */
+  readonly stage?: TriggerStage;
+}
+/** Zod schema for {@link TriggerManifest}. */
+declare const TriggerManifestSchema: z.ZodObject<{
+  prefix: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  stage: z.ZodOptional<z.ZodEnum<{
+    transform: "transform";
+    action: "action";
+    gather: "gather";
+  }>>;
+}, z.core.$strip>;
+/**
+ * Describes a log importer contributed by an extension.
+ *
+ * Serializable metadata for discovery, filtering, and inspection. The
+ * executable runtime source is `MakaioExtension.logImport`; descriptor
+ * contributions are not a registration fallback.
+ */
+interface LogImporterManifest {
+  /**
+   * Adapter name used for attribution (e.g., `'plugin:opencode'`).
+   *
+   * Must be unique within the declaring extension.
+   */
+  readonly adapterName: string;
+  /** Human-readable display name (e.g., `'OpenCode'`). */
+  readonly displayName: string;
+  /**
+   * Glob pattern matching importable log files.
+   *
+   * Discovery tooling can use this pattern to filter file system entries
+   * without loading the extension code.
+   * @example `'** /storage/session/* /*.json'`
+   */
+  readonly logFilePattern?: string;
+}
+/** Zod schema for {@link LogImporterManifest}. */
+declare const LogImporterManifestSchema: z.ZodObject<{
+  adapterName: z.ZodString;
+  displayName: z.ZodString;
+  logFilePattern: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Describes a session event action contributed by an extension.
+ *
+ * Serializable metadata for discovery and introspection. The executable
+ * runtime source is `MakaioExtension.sessionEventActions.createActions()`;
+ * descriptor contributions are not a registration fallback.
+ */
+interface SessionEventActionManifest {
+  /**
+   * Unique action identifier within the declaring extension
+   * (e.g., `'pin-message:pin'`).
+   */
+  readonly id: string;
+  /** Display label shown in action menus. */
+  readonly label: string;
+  /** Optional human-readable description. */
+  readonly description?: string;
+  /** Optional icon identifier. */
+  readonly icon?: string;
+  /**
+   * Whether the action operates on a single event or multiple events.
+   *
+   * - `'single'` — immediate execution from a kebab menu.
+   * - `'multi'` — opens a picker modal for multi-event selection.
+   */
+  readonly selectionMode: 'single' | 'multi';
+  /**
+   * Message roles the action applies to.
+   *
+   * Maps to the `entrypoint.messageRole` field on the runtime action options.
+   */
+  readonly messageRoles?: readonly ('user' | 'assistant')[];
+}
+/** Zod schema for {@link SessionEventActionManifest}. */
+declare const SessionEventActionManifestSchema: z.ZodObject<{
+  id: z.ZodString;
+  label: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  icon: z.ZodOptional<z.ZodString>;
+  selectionMode: z.ZodEnum<{
+    single: "single";
+    multi: "multi";
+  }>;
+  messageRoles: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+    user: "user";
+    assistant: "assistant";
+  }>>>>;
+}, z.core.$strip>;
+/**
+ * Discovery-time flags for browser UI contribution surfaces.
+ *
+ * Each boolean flag indicates that the extension's executable
+ * {@link ExtensionUiContribution} declares the corresponding surface.
+ * Absent or `false` means the surface is not contributed.
+ */
+interface UiSurfaceFlags {
+  /** Extension contributes one or more tile declarations. */
+  readonly tiles?: boolean;
+  /** Extension contributes one or more widget declarations. */
+  readonly widgets?: boolean;
+  /** Extension contributes one or more page declarations. */
+  readonly pages?: boolean;
+  /** Extension contributes one or more web UI routes. */
+  readonly routes?: boolean;
+}
+/** Zod schema for {@link UiSurfaceFlags}. */
+declare const UiSurfaceFlagsSchema: 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>;
+/**
+ * Top-level container for all contributions an extension declares.
+ *
+ * Added as an optional field on {@link ExtensionManifest}. Extensions that do
+ * not need discovery-time contribution metadata may omit this field entirely.
+ * This manifest is intentionally not a runtime wiring surface; it mirrors the
+ * executable contribution fields only for pre-load introspection.
+ *
+ * Rich metadata fields ({@link adapters}, {@link clients}, {@link providers},
+ * {@link triggers}, {@link logImporters}, {@link sessionEventActions}) carry
+ * structured data for discovery and filtering. Boolean surface flags
+ * ({@link create}, {@link tools}, {@link bootstrap}, etc.) declare which
+ * executable surfaces the extension contributes without duplicating runtime
+ * detail.
+ * @example Extension contributing an adapter and a client
+ * ```json
+ * {
+ *   "contributions": {
+ *     "adapters": [
+ *       {
+ *         "name": "claude-code",
+ *         "protocols": ["anthropic"],
+ *         "clients": [{ "id": "claude-code", "version": "^1.5.0" }]
+ *       }
+ *     ],
+ *     "clients": [
+ *       { "id": "claude-code", "name": "Claude Code", "binary": { "name": "claude" } }
+ *     ]
+ *   }
+ * }
+ * ```
+ * @example Extension contributing hash triggers and tools
+ * ```json
+ * {
+ *   "contributions": {
+ *     "triggers": [
+ *       { "prefix": "loop", "description": "Retry-until-success execution", "stage": "action" }
+ *     ],
+ *     "create": true,
+ *     "tools": true,
+ *     "configSchema": true,
+ *     "ui": { "widgets": true }
+ *   }
+ * }
+ * ```
+ */
+interface ContributionManifest {
+  /** Adapter contributions declared by this extension. */
+  readonly adapters?: readonly AdapterManifest[];
+  /** Client binary contributions declared by this extension. */
+  readonly clients?: readonly ClientManifest[];
+  /** Provider contributions declared by this extension. */
+  readonly providers?: readonly ProviderManifest[];
+  /** Hash trigger contributions declared by this extension. */
+  readonly triggers?: readonly TriggerManifest[];
+  /** Log importer contribution declared by this extension. */
+  readonly logImporters?: readonly LogImporterManifest[];
+  /** Session event action contributions declared by this extension. */
+  readonly sessionEventActions?: readonly SessionEventActionManifest[];
+  /** Extension provides a service factory ({@link MakaioExtension.create}). */
+  readonly create?: boolean;
+  /** Extension contributes one or more toolsets ({@link MakaioExtension.tools}). */
+  readonly tools?: boolean;
+  /** Extension contributes bootstrap import/export ({@link MakaioExtension.bootstrap}). */
+  readonly bootstrap?: boolean;
+  /** Extension declares a bus namespace ({@link MakaioExtension."namespace"}). */
+  readonly namespace?: boolean;
+  /** Extension declares a config schema ({@link MakaioExtension.configSchema}). */
+  readonly configSchema?: boolean;
+  /** Extension declares UI config overrides ({@link MakaioExtension.uiConfig}). */
+  readonly uiConfig?: boolean;
+  /** Browser UI surface flags ({@link MakaioExtension.ui}). */
+  readonly ui?: UiSurfaceFlags;
+}
+/** Zod schema for {@link ContributionManifest}. */
+declare const ContributionManifestSchema: 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;
+    }, 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<{
+      transform: "transform";
+      action: "action";
+      gather: "gather";
+    }>>;
+  }, 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<{
+      single: "single";
+      multi: "multi";
+    }>;
+    messageRoles: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+      user: "user";
+      assistant: "assistant";
+    }>>>>;
+  }, 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>;
+//#endregion
+//#region packages/contracts/src/extension/capability-token.d.ts
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+declare const CapabilityTokenSchema: z.ZodType<CapabilityToken>;
+//#endregion
+//#region packages/contracts/src/extension/manifest.d.ts
+/**
+ * Visual presentation style for an extension window.
+ *
+ * - `'tray-popover'` — small overlay anchored to the system tray icon.
+ * - `'utility'` — standalone auxiliary window (e.g., settings panel).
+ * - `'panel'` — docked or floating workspace panel.
+ */
+type WindowStyle = 'tray-popover' | 'utility' | 'panel';
+/**
+ * Describes a window surface an extension can open.
+ *
+ * The shell uses this declaration to pre-register the window and manage
+ * its lifecycle without requiring the extension to be initialized first.
+ */
+interface WindowManifest {
+  /**
+   * Identifier unique within the declaring extension.
+   * Referenced by {@link TrayManifest.opensWindow} to associate tray
+   * actions with specific windows.
+   */
+  readonly id: string;
+  /** Visual presentation style that governs how the shell positions and sizes the window. */
+  readonly style: WindowStyle;
+  /** Preferred initial width in logical pixels. */
+  readonly width?: number;
+  /** Preferred initial height in logical pixels. */
+  readonly height?: number;
+  /**
+   * When `true`, the shell ensures at most one instance of this window is
+   * open at a time, focusing the existing window instead of opening a new one.
+   */
+  readonly singleton?: boolean;
+  /**
+   * Named route parameters this window accepts.
+   * The shell uses these to map URL path segments to query params and
+   * to generalize window deduplication without hardcoding host IDs.
+   */
+  readonly params?: readonly WindowParamSpec[];
+}
+/**
+ * Specification for a named window route parameter.
+ */
+interface WindowParamSpec {
+  /** Parameter name (e.g. `'projectId'`). */
+  readonly name: string;
+  /** Whether this parameter is required for window creation. */
+  readonly required?: boolean;
+}
+/** Zod schema for {@link WindowParamSpec}. */
+declare const WindowParamSpecSchema: z.ZodObject<{
+  name: z.ZodString;
+  required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Zod schema for {@link WindowManifest}. */
+declare const WindowManifestSchema: z.ZodObject<{
+  id: z.ZodString;
+  style: z.ZodEnum<{
+    "tray-popover": "tray-popover";
+    utility: "utility";
+    panel: "panel";
+  }>;
+  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>;
+/**
+ * Describes an extension's entry in the system tray menu.
+ *
+ * The shell renders tray items grouped by {@link section}. Only one of
+ * {@link opensWindow} or {@link action} should be set; if both are present
+ * the shell prefers {@link opensWindow}.
+ */
+interface TrayManifest {
+  /** Human-readable label shown in the tray menu. */
+  readonly label: string;
+  /**
+   * Logical grouping for tray menu layout.
+   *
+   * - `'utilities'` — system / account tools (e.g., auth switcher).
+   * - `'tools'` — productivity tools (e.g., code review).
+   * - `'views'` — windows or panels that present content.
+   */
+  readonly section?: 'utilities' | 'tools' | 'views';
+  /**
+   * {@link WindowManifest.id} of the window to open when this tray item is
+   * clicked. Takes precedence over {@link action} when both are defined.
+   */
+  readonly opensWindow?: string;
+  /**
+   * Opaque action identifier echoed in `host:tray.item.clicked` metadata when
+   * this tray item is clicked.
+   */
+  readonly action?: string;
+}
+/** Zod schema for {@link TrayManifest}. */
+declare const TrayManifestSchema: 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>;
+/**
+ * Describes a single positional argument or named option for a CLI subcommand.
+ *
+ * This is the serializable, framework-agnostic counterpart to
+ * `CliSubcommandDefinition` — it carries only metadata, no handler.
+ */
+interface CliArgManifest {
+  /**
+   * Argument or option name.
+   * For positional args this is the display name shown in usage text.
+   * For named options it is the schema field name. The CLI adapter converts it
+   * to a kebab-case long flag when registering Commander options
+   * (e.g. `'clientId'` -\> `--client-id`).
+   */
+  readonly name: string;
+  /** One-line description shown in help text. */
+  readonly description: string;
+  /** When `true`, the CLI parser rejects invocations that omit this argument. */
+  readonly required?: boolean;
+  /** When `true`, treat as a positional argument rather than a named option. */
+  readonly positional?: boolean;
+  /** Short single-character flag alias (e.g. `'-p'`). */
+  readonly short?: string;
+  /**
+   * Value type for this argument or option.
+   * Used by manifest-based CLI registration to determine whether an option
+   * takes a value or is a boolean flag. Defaults to `'string'` when omitted.
+   * Manifest-based registration also uses this metadata to coerce numeric
+   * values before they reach the subcommand's Zod schema.
+   */
+  readonly type?: 'string' | 'boolean' | 'number';
+}
+/** Zod schema for {@link CliArgManifest}. */
+declare const CliArgManifestSchema: 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<{
+    string: "string";
+    number: "number";
+    boolean: "boolean";
+  }>>;
+}, z.core.$strip>;
+/**
+ * Describes a single subcommand nested under the extension's top-level CLI command.
+ *
+ * Pure metadata — no handler. Used for help generation and manifest inspection.
+ */
+interface CliSubcommandManifest {
+  /** Subcommand name (e.g. `'list'`, `'switch'`). */
+  readonly name: string;
+  /** One-line description shown in help text. */
+  readonly description: string;
+  /** Arguments and options accepted by this subcommand. */
+  readonly args?: readonly CliArgManifest[];
+}
+/** Zod schema for {@link CliSubcommandManifest}. */
+declare const CliSubcommandManifestSchema: 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<{
+      string: "string";
+      number: "number";
+      boolean: "boolean";
+    }>>;
+  }, z.core.$strip>>>>;
+}, z.core.$strip>;
+/**
+ * Describes the top-level CLI command an extension contributes.
+ *
+ * Serializable and framework-agnostic. The executable extension,
+ * `ExtensionCliContribution`, adds the interactive handler and typed subcommand
+ * definitions. The CLI router uses this manifest for help generation and
+ * command discovery without loading handler code.
+ */
+interface CliManifest {
+  /** Top-level command name (e.g. `'account-manager'`). */
+  readonly name: string;
+  /** One-line description shown in help text. */
+  readonly description: string;
+  /** Non-interactive subcommands registered under this command. */
+  readonly subcommands?: readonly CliSubcommandManifest[];
+  /**
+   * Whether this extension provides an interactive TUI handler.
+   *
+   * When `true`, invoking the bare command (without a subcommand) launches
+   * the interactive handler. When `false` or omitted, bare invocation shows
+   * help. This is a serializable declaration in `descriptor.json`; the
+   * executable handler itself lives in `ExtensionCliContribution.interactive`.
+   *
+   * Named `hasInteractive` (not `interactive`) to avoid a type conflict with
+   * the `ExtensionCliContribution` property of the same short name, which carries
+   * the function implementation rather than a boolean flag.
+   */
+  readonly hasInteractive?: boolean;
+}
+/** Zod schema for {@link CliManifest}. */
+declare const CliManifestSchema: 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<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+      }>>;
+    }, z.core.$strip>>>>;
+  }, z.core.$strip>>>>;
+  hasInteractive: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Describes the storage requirements of an extension.
+ *
+ * Serializable metadata that the runtime uses to run migrations before
+ * starting the extension's service. The migrations path is relative to the
+ * extension root and resolved to an absolute path by the composition root.
+ * Bundled hosts may also provide a stable `migrationSourceId` so migration
+ * identity does not collapse onto packaged output paths.
+ */
+interface StorageManifest {
+  /**
+   * Path to the Drizzle migration folder, relative to the extension root.
+   *
+   * The runtime resolves this to an absolute path and passes it to the
+   * host-supplied `runMigrations` callback
+   * before any extension services are started. The callback is responsible for
+   * applying pending migrations against the shared database using a
+   * per-extension tracking table to avoid filename collisions.
+   * @example 'drizzle'
+   */
+  readonly migrations?: string;
+  /**
+   * Stable runtime identity for the migration bundle.
+   *
+   * Hosts use this to key deduplication, ledger tables, and bundled migration
+   * lookup independently of the on-disk discovery path. When omitted, the
+   * resolved migration folder path remains the identity.
+   */
+  readonly migrationSourceId?: string;
+}
+/** Zod schema for {@link StorageManifest}. */
+declare const StorageManifestSchema: z.ZodObject<{
+  migrations: z.ZodOptional<z.ZodString>;
+  migrationSourceId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * A structured dependency declaration on another extension.
+ *
+ * Carries the dependency name, a semver version range the declared extension
+ * must satisfy, and an optional `optional` flag for non-fatal dependencies.
+ */
+interface ExtensionDependency {
+  /** Discriminant — always `'extension'`. */
+  readonly type: 'extension';
+  /**
+   * {@link ExtensionManifest.name} of the required extension.
+   *
+   * Accepts the same plain or scoped npm identifier format as
+   * {@link ExtensionManifest.name}.
+   */
+  readonly name: string;
+  /**
+   * Semver range the installed extension version must satisfy.
+   *
+   * Uses the same syntax as npm range strings (e.g. `'>=1.0.0 <2.0.0'`,
+   * `'^1.5.0'`).
+   */
+  readonly version: VersionRange;
+  /**
+   * When `true` the extension may start even if this dependency is absent or
+   * fails to activate.
+   *
+   * Omitting this field is equivalent to `false`.
+   */
+  readonly optional?: boolean;
+}
+/** Zod schema for {@link ExtensionDependency}. */
+declare const ExtensionDependencySchema: z.ZodObject<{
+  type: z.ZodLiteral<"extension">;
+  name: z.ZodString;
+  version: z.ZodString;
+  optional: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Factory that creates an {@link ExtensionDependency} with `type: 'extension'`.
+ *
+ * Prefer this helper over inline object literals to keep dependency
+ * declarations concise and consistent across package descriptors.
+ * @param name - {@link ExtensionManifest.name} of the required extension.
+ * @param version - Semver range the required extension must satisfy.
+ * @param optional - When `true`, activation continues if the dependency is absent.
+ * @returns A fully-typed {@link ExtensionDependency} object.
+ * @example
+ * dependencies: [dep('provider-anthropic'), dep('makaio.clients-core')]
+ */
+declare function dep(name: string, version?: VersionRange, optional?: boolean): ExtensionDependency;
+/**
+ * A typed runtime-environment gate that an extension declares it needs before
+ * the kernel will activate it.
+ *
+ * Two flavors are supported:
+ * - `'host'` — the runtime host must be present (e.g. `{ type: 'host', id: 'node' }`).
+ * - `'capability'` — the host must advertise the named capability token
+ *   (e.g. `{ type: 'capability', id: 'storage.drizzle' }`). The optional
+ *   `version` field requires the host capability to declare a satisfying
+ *   concrete version.
+ *
+ * This is an environment compatibility gate, not an extension-to-extension
+ * dependency. Use {@link ExtensionManifest.dependencies} for structural ordering.
+ */
+type RuntimeRequirement = {
+  readonly type: 'host';
+  readonly id: string;
+} | {
+  readonly type: 'capability';
+  readonly id: string;
+  readonly version?: VersionRange;
+};
+/** Zod schema for {@link RuntimeRequirement}. */
+declare const RuntimeRequirementSchema: 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">;
+/**
+ * Pure-data manifest for a Makaio extension.
+ *
+ * Fully serializable and safe to inspect or transmit without executing any
+ * extension code. The shell and registry use this to discover extension surfaces
+ * (windows, tray, CLI, storage) before deciding whether to initialize them.
+ * @see {@link MakaioExtension} for the executable extension that adds `create`,
+ * typed CLI handlers, and storage registration.
+ */
+interface ExtensionManifest {
+  /**
+   * Unique extension identifier.
+   *
+   * Accepts plain identifiers (e.g. `'account-manager'`) and npm-scoped
+   * names (e.g. `'@acme/weather-tools'`). Used as the primary key in the
+   * extension registry and as the top-level CLI command name when no
+   * {@link cli} override is provided.
+   */
+  readonly name: string;
+  /** Human-readable display name shown in UI surfaces (e.g. `'Auth Switcher'`). */
+  readonly displayName: string;
+  /**
+   * SemVer version of this extension package.
+   *
+   * Descriptor-only synthesized packages receive this from `descriptor.json`;
+   * code-defined executable packages declare the same field directly on their
+   * package object.
+   */
+  readonly version: VersionLiteral;
+  /**
+   * Execution surface the extension targets.
+   *
+   * - `'interactive'` — requires a UI shell (e.g., Electron renderer).
+   * - `'headless'` — suitable for daemon or CLI-only runtimes.
+   * - `'any'` — works in any surface (default when omitted).
+   */
+  readonly surface?: 'interactive' | 'headless' | 'any';
+  /**
+   * Structured dependencies on other extensions.
+   *
+   * The registry ensures all listed extensions are initialized before this
+   * extension starts. Each entry carries the dependency name, a semver version
+   * range the installed extension must satisfy, and an optional `optional` flag.
+   * @see {@link ExtensionDependency}
+   */
+  readonly dependencies?: readonly ExtensionDependency[];
+  /**
+   * Runtime-environment gates this extension must satisfy before the kernel
+   * activates it.
+   *
+   * Each entry is a {@link RuntimeRequirement} that declares either a required
+   * host identity (e.g. `'node'`) or a host-advertised capability token (e.g.
+   * `'storage.drizzle'`). All entries must be satisfied (AND semantics).
+   *
+   * This is an environment compatibility gate, not an extension-to-extension
+   * dependency. Use {@link dependencies} for structural extension ordering.
+   */
+  readonly requires?: readonly RuntimeRequirement[];
+  /**
+   * Capability tokens this extension provides when active.
+   *
+   * Consumers and onboarding surfaces can inspect these declarations to decide
+   * whether a capability exists at all before prompting the user to configure it.
+   */
+  readonly provides?: readonly CapabilityToken[];
+  /** Windows this extension can open, keyed by {@link WindowManifest.id}. */
+  readonly windows?: readonly WindowManifest[];
+  /** System tray entry for this extension. */
+  readonly tray?: TrayManifest;
+  /**
+   * CLI command contributed by this extension.
+   *
+   * On {@link ExtensionManifest} this is pure metadata. On {@link MakaioExtension}
+   * this is widened to `ExtensionCliContribution` with executable handlers.
+   */
+  readonly cli?: CliManifest;
+  /** Storage requirements (migrations) declared by this extension. */
+  readonly storage?: StorageManifest;
+  /**
+   * Browser entry point for this extension.
+   * URL path the renderer fetches to load the extension's UI.
+   * @example '/extensions/my-extension/browser/index.js'
+   */
+  readonly browser?: BrowserEntrypoint;
+  /**
+   * Adapters and client binaries contributed by this extension.
+   *
+   * Discovery-time metadata only — serializable and safe to inspect without
+   * loading any extension code. Runtime activation and registration use the
+   * executable contribution fields on {@link MakaioExtension}; descriptor
+   * metadata may mirror those fields for pre-load introspection but is not
+   * used as a fallback wiring source.
+   */
+  readonly contributions?: ContributionManifest;
+}
+/** Zod schema for {@link ExtensionManifest}. */
+declare const ExtensionManifestSchema: z.ZodObject<{
+  name: z.ZodString;
+  displayName: z.ZodString;
+  version: z.ZodString;
+  surface: z.ZodOptional<z.ZodEnum<{
+    any: "any";
+    interactive: "interactive";
+    headless: "headless";
+  }>>;
+  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<{
+      "tray-popover": "tray-popover";
+      utility: "utility";
+      panel: "panel";
+    }>;
+    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<{
+          string: "string";
+          number: "number";
+          boolean: "boolean";
+        }>>;
+      }, 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;
+      }, 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<{
+        transform: "transform";
+        action: "action";
+        gather: "gather";
+      }>>;
+    }, 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<{
+        single: "single";
+        multi: "multi";
+      }>;
+      messageRoles: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+        user: "user";
+        assistant: "assistant";
+      }>>>>;
+    }, 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>>;
+}, z.core.$strip>;
+//#endregion
+//#region packages/contracts/src/extension/extension-token.d.ts
+/**
+ * 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.
+ */
+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.
+ */
+declare function extensionToken<T>(name: string): ExtensionToken<T>;
+//#endregion
+//#region packages/contracts/src/extension/adapter-definition.d.ts
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+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>;
+}
+//#endregion
+//#region packages/contracts/src/extension/extension-warning.d.ts
+/**
+ * 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.
+ */
+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.
+ */
+declare const ExtensionWarningSeveritySchema: z.ZodEnum<{
+  info: "info";
+  recommended: "recommended";
+  degraded: "degraded";
+}>;
+/**
+ * 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.
+ */
+declare const ExtensionWarningSchema: z.ZodObject<{
+  severity: z.ZodEnum<{
+    info: "info";
+    recommended: "recommended";
+    degraded: "degraded";
+  }>;
+  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}. */
+type ExtensionWarning = z.infer<typeof ExtensionWarningSchema>;
+/** Inferred TypeScript type for {@link ExtensionWarningActionSchema}. */
+type ExtensionWarningAction = z.infer<typeof ExtensionWarningActionSchema>;
+/** Inferred TypeScript type for {@link ExtensionWarningSeveritySchema}. */
+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.
+ */
+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.
+ */
+declare const ExtensionWarningEntrySchema: z.ZodObject<{
+  extensionName: z.ZodString;
+  warnings: z.ZodArray<z.ZodObject<{
+    severity: z.ZodEnum<{
+      info: "info";
+      recommended: "recommended";
+      degraded: "degraded";
+    }>;
+    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}. */
+type ExtensionWarningEntry = z.infer<typeof ExtensionWarningEntrySchema>;
+//#endregion
+//#region packages/contracts/src/extension/extension-lifecycle.d.ts
+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.
+ */
+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.
+ */
+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.
+ */
+type ExtensionService = ExtensionServiceLifecycle;
+//#endregion
+//#region packages/contracts/src/extension/extension-context.d.ts
+/**
+ * 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}.
+ */
+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}.
+ */
+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;
+}
+//#endregion
+//#region packages/contracts/src/extension/extension-cli.d.ts
+/**
+ * Type-erased output channel used by extension-local CLI handlers.
+ *
+ * Runtime code exposes the fully typed helper API via `@makaio/kernel/cli`.
+ */
+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`.
+ */
+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.
+ */
+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`.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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>;
+}
+//#endregion
+//#region packages/contracts/src/extension/extension-runtime-boot.d.ts
+/**
+ * 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.
+ */
+interface ExtensionRuntimeOwnership {
+  /** Owns the `session.sendMessage` orchestration handlers for this runtime. */
+  readonly sessionOrchestrator?: boolean;
+}
+//#endregion
+//#region packages/contracts/src/extension/contributions/session-event-action-types.d.ts
+/** Keyboard modifier flags for an action shortcut. */
+interface ActionShortcutModifiers {
+  /** Meta/Command key. */
+  meta?: boolean;
+  /** Alt/Option key. */
+  alt?: boolean;
+  /** Shift key. */
+  shift?: boolean;
+  /** Control key. */
+  ctrl?: boolean;
+}
+/** Full keyboard shortcut definition including modifiers and display metadata. */
+interface ActionShortcut extends ActionShortcutModifiers {
+  /** Primary key character or name. */
+  key: string;
+  /** Human-readable label shown in keyboard shortcut hints. */
+  label: string;
+  /** Category grouping for the shortcut. */
+  category: ActionCategory;
+  /** Optional human-readable description. */
+  description?: string;
+  /** Whether the shortcut should not activate while focus is in an input field. */
+  skipInInputs?: boolean;
+  /** Optional context scope string or list of scopes. */
+  context?: string | string[];
+}
+/**
+ * Extension point for registering custom action categories.
+ *
+ * Extend via declaration merging from packages or UI layers.
+ * @example
+ * ```typescript
+ * declare module '@makaio/framework/contracts' {
+ *   interface ActionCategoryMap {
+ *     timeline: true;
+ *   }
+ * }
+ * ```
+ */
+interface ActionCategoryMap {
+  /** Default category for uncategorized actions. */
+  general: true;
+}
+type RegisteredActionCategory = keyof ActionCategoryMap & string;
+/** Resolved action category type, extensible via {@link ActionCategoryMap} declaration merging. */
+type ActionCategory = RegisteredActionCategory;
+/** Allowed message role values for event action entrypoints. */
+type MessageRole = 'user' | 'assistant';
+/** Event filter that matches message events with optional role restriction. */
+interface MessageEventFilter {
+  /** Discriminant: must be `'message'`. */
+  eventType: 'message';
+  /** Optional list of message roles this filter applies to. */
+  messageRole?: MessageRole[];
+}
+/** All core session event types except `'message'`. */
+type StructuralEventType = Exclude<(typeof SESSION_EVENT_TYPES)[number], 'message'>;
+/** Event filter that matches structural (non-message) session events. */
+interface StructuralEventFilter {
+  /** The specific structural event type to match. */
+  eventType: StructuralEventType;
+}
+/** Union of message and structural event filters. */
+type EventFilter = MessageEventFilter | StructuralEventFilter;
+/**
+ * Context passed to a session event action factory.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+interface SessionEventActionContext<TBus extends MakaioBusLike = MakaioBusLike> {
+  /** Bus instance for registering action handlers. */
+  bus: TBus;
+  /** Name of the extension registering the action. */
+  extensionName: string;
+  /**
+   * Register one executable action with the owning session-event-action service.
+   *
+   * The service package owns the bus subjects and callback plumbing; extension
+   * contributors receive this factory through the contribution context instead
+   * of importing service implementation modules directly.
+   * @param options - Action declaration and runtime callbacks.
+   * @returns Serializable declaration plus unregister hook.
+   */
+  createAction: <TMode extends 'single' | 'multi', TRoles extends MessageRole[]>(options: SessionEventActionOptions<TMode, TRoles, TBus>) => CreateSessionEventActionResult;
+}
+/**
+ * Context passed to a session event action's `when` predicate.
+ * @typeParam TRoles - Message roles accepted by the action entrypoint.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+interface WhenContext<TRoles extends MessageRole[] = MessageRole[], TBus extends MakaioBusLike = MakaioBusLike> {
+  /** The message event that triggered the predicate check. */
+  message: SessionMessage & {
+    role: TRoles[number];
+  };
+  /** Active session identifier. */
+  sessionId: string;
+  /** Bus instance for runtime queries. */
+  bus: TBus;
+}
+/**
+ * Context passed to a session event action's `onPickerOpen` callback.
+ * @typeParam TRoles - Message roles accepted by the action entrypoint.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+interface PickerOpenContext<TRoles extends MessageRole[] = MessageRole[], TBus extends MakaioBusLike = MakaioBusLike> {
+  /** Entrypoint information for the action. */
+  entrypoint: {
+    /** The message that was actioned. */messageId: string; /** Full message object. */
+    message: SessionMessage & {
+      role: TRoles[number];
+    };
+  };
+  /** Active session identifier. */
+  sessionId: string;
+  /** Active project identifier. */
+  projectId?: string;
+  /** Bus instance for runtime queries. */
+  bus: TBus;
+}
+/** Configuration returned by `onPickerOpen` to control the event picker UI. */
+interface PickerConfig {
+  /** Event IDs that should be pre-selected when the picker opens. */
+  preSelectedEventIds?: string[];
+  /** Maximum number of events that can be selected. */
+  maxSelections?: number;
+  /** Custom title for the picker dialog. */
+  title?: string;
+}
+/**
+ * Context passed to a session event action's `onSelectionChange` callback.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+interface SelectionChangeContext<TBus extends MakaioBusLike = MakaioBusLike> {
+  /** Currently selected session events. */
+  selectedEvents: MakaioSessionEvent[];
+  /** Entrypoint information for the action. */
+  entrypoint: {
+    /** The message that was actioned. */messageId: string; /** Full message object. */
+    message: SessionMessage;
+  };
+  /** Active session identifier. */
+  sessionId: string;
+  /** Bus instance for runtime queries. */
+  bus: TBus;
+}
+/** Feedback returned by `onSelectionChange` to inform the picker UI. */
+interface SelectionFeedback {
+  /** Estimated token count for the selected events. */
+  tokenEstimate?: number;
+  /** Warning message to display in the picker. */
+  warning?: string;
+  /** Error message that blocks confirmation. */
+  error?: string;
+}
+/** Context passed to a session event action's `onExecute` callback. */
+interface ExecuteContext<TMode extends 'single' | 'multi' = 'single' | 'multi', TRoles extends MessageRole[] = MessageRole[], TBus extends MakaioBusLike = MakaioBusLike> {
+  /** Entrypoint information for the action. */
+  entrypoint: {
+    /** The message that was actioned. */messageId: string; /** Full message object. */
+    message: SessionMessage & {
+      role: TRoles[number];
+    };
+  };
+  /** Selected events when in multi-selection mode, otherwise `undefined`. */
+  selectedEvents: TMode extends 'multi' ? MakaioSessionEvent[] : undefined;
+  /** Active session identifier. */
+  sessionId: string;
+  /** Active project identifier. */
+  projectId?: string;
+  /** Bus instance for runtime queries. */
+  bus: TBus;
+}
+/** Result returned by a session event action's `onExecute` callback. */
+interface ExecuteResult {
+  /** Whether execution succeeded. */
+  success: boolean;
+  /** Human-readable error message when `success` is `false`. */
+  error?: string;
+}
+/** Configuration for a session event action's message entrypoint. */
+interface EntrypointConfig<TRoles extends MessageRole[] = MessageRole[]> {
+  /** Allowed message roles that can trigger this action. */
+  messageRole: TRoles;
+}
+/** Full options for defining a session event action. */
+interface SessionEventActionOptions<TMode extends 'single' | 'multi' = 'single' | 'multi', TRoles extends MessageRole[] = MessageRole[], TBus extends MakaioBusLike = MakaioBusLike> {
+  /** Unique action identifier within the registering package. */
+  id: string;
+  /** Display label for the action. */
+  label: string;
+  /** Optional human-readable description. */
+  description?: string;
+  /** Optional icon identifier. */
+  icon?: string;
+  /** Message entrypoint configuration. */
+  entrypoint: EntrypointConfig<TRoles>;
+  /** Whether this action operates on a single event or multiple events. */
+  selectionMode: TMode;
+  /** Event type filters for multi-selection mode. */
+  applicableTo?: TMode extends 'multi' ? EventFilter[] : never;
+  /**
+   * Optional predicate that determines whether the action is available.
+   * @param ctx - Context with the triggering message.
+   * @returns `true` when the action should be shown.
+   */
+  when?: (ctx: WhenContext<TRoles, TBus>) => Promise<boolean>;
+  /**
+   * Optional callback invoked when the event picker opens.
+   * @param ctx - Context with entrypoint and session info.
+   * @returns Picker configuration, `false` to cancel, or `void`.
+   */
+  onPickerOpen?: TMode extends 'multi' ? (ctx: PickerOpenContext<TRoles, TBus>) => Promise<PickerConfig | false | void> : never;
+  /**
+   * Optional callback invoked when the event selection changes.
+   * @param ctx - Context with selected events.
+   * @returns Selection feedback to display in the picker.
+   */
+  onSelectionChange?: TMode extends 'multi' ? (ctx: SelectionChangeContext<TBus>) => Promise<SelectionFeedback | void> : never;
+  /** Category grouping for this action. */
+  category?: ActionCategory;
+  /** Optional keyboard shortcut. */
+  shortcut?: ActionShortcut;
+  /**
+   * Main execution callback invoked when the action is confirmed.
+   * @param ctx - Context with entrypoint, selected events, and bus.
+   * @returns Execution result, or `void` on success.
+   */
+  onExecute: (ctx: ExecuteContext<TMode, TRoles, TBus>) => Promise<ExecuteResult | void>;
+}
+/** Serializable declaration stored in registries and emitted over the bus. */
+interface SessionEventActionDeclaration {
+  /** Unique action identifier. */
+  id: string;
+  /** Display label. */
+  label: string;
+  /** Optional description. */
+  description?: string;
+  /** Optional icon identifier. */
+  icon?: string;
+  /** Entrypoint configuration. */
+  entrypoint: EntrypointConfig;
+  /** Selection mode. */
+  selectionMode: 'single' | 'multi';
+  /** Event type filters (multi mode only). */
+  applicableTo?: EventFilter[];
+  /** Whether a `when` predicate was provided. */
+  hasWhenPredicate: boolean;
+  /** Whether an `onPickerOpen` callback was provided. */
+  hasPickerOpenCallback: boolean;
+  /** Whether an `onSelectionChange` callback was provided. */
+  hasSelectionChangeCallback: boolean;
+  /** Resolved action category. */
+  category: ActionCategory;
+  /** Optional keyboard shortcut. */
+  shortcut?: ActionShortcut;
+}
+/** Return value from `createSessionEventAction` — declaration plus unregister hook. */
+interface CreateSessionEventActionResult {
+  /** Serializable declaration for registry and bus publication. */
+  declaration: SessionEventActionDeclaration;
+  /** Unregisters the action and cleans up bus subscriptions. */
+  unregister: () => void;
+}
+//#endregion
+//#region packages/contracts/src/extension/contributions/hash-trigger-types.d.ts
+/** Pipeline stage a hash trigger participates in. */
+type HashTriggerStage = 'gather' | 'transform' | 'action';
+/** Single suggestion entry returned by a hash trigger's suggest call. */
+interface HashSuggestion {
+  /** Display label shown in the completion UI. */
+  label: string;
+  /** Human-readable explanation of the suggestion. */
+  description: string;
+  /** Whether this suggestion is a leaf (directly usable) or a group (opens sub-list). */
+  kind: 'leaf' | 'group';
+  /** Text inserted into the input when the suggestion is accepted. */
+  insertText: string;
+  /** Underlying value passed to execute when the suggestion is used. */
+  value: string;
+  /** Optional icon identifier for the suggestion entry. */
+  icon?: string;
+  /** Pipeline stage override for this particular suggestion. */
+  stage?: HashTriggerStage;
+}
+/** A single entry gathered by a gather-stage hash trigger. */
+interface GatheredEntry {
+  /** Gathered content string. */
+  content: string;
+  /** Prefix token that matched this entry. */
+  prefix: string;
+  /** Argument portion of the matched hash value. */
+  argument: string;
+  /** Optional arbitrary metadata from the gatherer. */
+  metadata?: Record<string, unknown>;
+}
+/** Snapshot of all entries gathered by gather-stage triggers in this pipeline run. */
+interface GatheredContext {
+  /** Immutable map of prefix → entry. */
+  entries: ReadonlyMap<string, GatheredEntry>;
+}
+/**
+ * Context passed to a hash trigger's suggest and execute methods.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+interface HashTriggerContext<TBus extends MakaioBusLike = MakaioBusLike> {
+  /** Active session identifier, if any. */
+  sessionId?: string;
+  /** Active project identifier, if any. */
+  projectId?: string;
+  /** Current message text. */
+  message?: string;
+  /** Bus instance for trigger operations. */
+  bus: TBus;
+  /** Optional abort signal for cancellable operations. */
+  signal?: AbortSignal;
+  /** Entries gathered by earlier gather-stage triggers. */
+  gathered?: GatheredContext;
+}
+/** Static descriptor for a registered hash trigger. */
+interface HashTriggerMetadata {
+  /** Prefix token this trigger responds to (e.g. `'@'`, `'#'`). */
+  prefix: string;
+  /** Human-readable explanation of what this trigger does. */
+  description: string;
+  /** Semantic version of this trigger. */
+  version: string;
+  /** Pipeline stage this trigger participates in. */
+  stage?: HashTriggerStage;
+  /** Names of triggers that must run before this one. */
+  runAfter?: string[];
+}
+/** Return value from a hash trigger's suggest call. */
+interface HashTriggerSuggestResult {
+  /** Suggested completions. */
+  suggestions: HashSuggestion[];
+  /** Optional metadata about the result set. */
+  metadata?: {
+    /** Whether the result set was truncated due to size limits. */truncated?: boolean;
+  };
+}
+/**
+ * A registered hash trigger that can suggest completions and execute values.
+ *
+ * Implement this interface and return instances from
+ * `MakaioExtension.triggers.createTriggers` so the runtime registers them
+ * with the HashTriggerService.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+interface HashTrigger<TBus extends MakaioBusLike = MakaioBusLike> {
+  /** Static descriptor used for registration and pipeline ordering. */
+  metadata: HashTriggerMetadata;
+  /**
+   * Return completion suggestions for the current query.
+   * @param query - Text typed after the prefix token.
+   * @param context - Runtime context for this suggestion request.
+   * @returns Suggestion list with optional pagination metadata.
+   */
+  suggest(query: string, context: HashTriggerContext<TBus>): Promise<HashTriggerSuggestResult>;
+  /**
+   * Execute the selected value (optional).
+   *
+   * Called when the user accepts a suggestion whose `kind` is `'leaf'`.
+   * @param value - The accepted suggestion's `value` field.
+   * @param context - Runtime context for this execution.
+   * @returns Resolved content string inserted into the message.
+   */
+  execute?(value: string, context: HashTriggerContext<TBus>): Promise<string>;
+}
+//#endregion
+//#region packages/contracts/src/extension/contributions/ui-context-types.d.ts
+/**
+ * Extension point for UI scope identifiers.
+ *
+ * Hosts and extensions add host-specific scopes via declaration
+ * merging. Framework defaults stay host-agnostic.
+ */
+interface UiScopeMap {
+  /** Available in framework-global contexts. */
+  global: true;
+  /** Available regardless of active UI context. */
+  any: true;
+}
+/** UI scope identifier, extensible via {@link UiScopeMap}. */
+type UiScope = keyof UiScopeMap & string;
+/**
+ * Extension point for UI navigation levels.
+ *
+ * Hosts add domain levels through declaration merging.
+ */
+interface UiNavigationLevelMap {
+  /** Root shell level with no host context implied. */
+  root: true;
+  /** Available at every registered navigation level. */
+  any: true;
+}
+/** UI navigation level, extensible via {@link UiNavigationLevelMap}. */
+type UiNavigationLevel = keyof UiNavigationLevelMap & string;
+/**
+ * Runtime UI navigation level.
+ *
+ * Runtime context snapshots describe the active renderer surface. The `'any'`
+ * level is reserved for definition matching and is never an active navigation
+ * level.
+ */
+type UiRuntimeNavigationLevel = Exclude<UiNavigationLevel, 'any'>;
+/**
+ * Extension point for typed UI context values.
+ *
+ * Keys are context dimensions; values are the serializable values exposed for
+ * that dimension in a host context snapshot.
+ */
+interface UiContextValueMap {
+  /** Active session identifier, if the framework shell has one. */
+  session: string;
+}
+/** UI context dimension identifier, extensible via {@link UiContextValueMap}. */
+type UiContextDimension = keyof UiContextValueMap & string;
+/** Snapshot of host UI context passed to contributed UI. */
+interface UiContextSnapshot {
+  /** Active navigation level for the renderer surface. */
+  readonly level: UiRuntimeNavigationLevel;
+  /** Active context values keyed by registered context dimension. */
+  readonly values: Partial<{ readonly [K in UiContextDimension]: UiContextValueMap[K] | null }>;
+}
+//#endregion
+//#region packages/contracts/src/extension/contributions/tile-types.d.ts
+/** Optional feature flags a tile can declare. */
+interface TileCapabilities {
+  /** Whether this tile supports fullscreen mode. */
+  supportsFullscreen?: boolean;
+}
+/**
+ * Props passed to tile components.
+ *
+ * Tiles do not receive host context as direct props; hosts expose context
+ * through their UI runtime.
+ */
+interface TileProps {
+  /** Optional class name for styling. */
+  className?: string;
+}
+/**
+ * Icon loader for a tile.
+ *
+ * Lazy-loads an icon component (typically from `lucide-react`).
+ * @example
+ * ```typescript
+ * icon: () => import('lucide-react').then(m => ({ default: m.Terminal }))
+ * ```
+ */
+type TileIconLoader = () => Promise<{
+  default: ComponentType<{
+    size?: number;
+  }>;
+}>;
+/**
+ * Platform renderers for a tile.
+ *
+ * SEAM: Currently supports React; additional platforms can be added as optional
+ * keys without breaking existing declarations.
+ */
+interface TileRenderers {
+  /**
+   * React renderer for the web UI.
+   *
+   * Lazy-loaded component module with a default export that accepts
+   * {@link TileProps}.
+   */
+  react: () => Promise<{
+    default: ComponentType<TileProps>;
+  }>;
+  /**
+   * SEAM: Future platform renderers (e.g. `reactNative`, `electron`).
+   *
+   * Additional platforms can be added here as optional keys.
+   */
+  [platform: string]: (() => Promise<{
+    default: ComponentType<TileProps>;
+  }>) | undefined;
+}
+/**
+ * Tile declaration contributed by a package.
+ *
+ * Packages declare tiles they provide for pane placement. These are registered
+ * with `TileRegistry` and shown in the "Add Pane" palette.
+ * @example
+ * ```typescript
+ * const terminalExtension: MakaioExtension = {
+ *   name: 'terminal',
+ *   ui: {
+ *     tiles: [
+ *       {
+ *         id: 'status',
+ *         name: 'Status',
+ *         description: 'Runtime status panel',
+ *         scope: 'global',
+ *         icon: () => import('lucide-react').then(m => ({ default: m.Activity })),
+ *         allowMultiple: true,
+ *         capabilities: { supportsFullscreen: true },
+ *         renderers: {
+ *           react: () => import('./ui/StatusTile.js'),
+ *         },
+ *       },
+ *     ],
+ *   },
+ * };
+ * ```
+ */
+interface TileDeclaration {
+  /**
+   * Unique tile identifier.
+   *
+   * Must be unique across all packages. Use the package name as a prefix to
+   * avoid collisions.
+   * @example `'status'`, `'session-summary'`
+   */
+  id: string;
+  /**
+   * Display name for the tile.
+   *
+   * Human-readable name shown in the "Add Pane" palette.
+   * @example `'Status'`, `'Session Summary'`
+   */
+  name: string;
+  /**
+   * Optional description of tile purpose.
+   *
+   * Shown in the "Add Pane" palette below the name.
+   */
+  description?: string;
+  /**
+   * Tile scope — where the tile is available.
+   *
+   * Defaults to `'any'` when not specified.
+   */
+  scope?: UiScope;
+  /**
+   * Icon loader for the tile.
+   *
+   * Lazy-loads an icon component for the "Add Pane" palette. Required for
+   * tiles to appear in the palette.
+   */
+  icon: TileIconLoader;
+  /**
+   * Whether multiple instances of this tile are allowed simultaneously.
+   *
+   * Defaults to `true`. When `false`, only one instance can exist at a time.
+   */
+  allowMultiple?: boolean;
+  /** Optional capability flags for the tile. */
+  capabilities?: TileCapabilities;
+  /**
+   * Context dimensions this tile's state depends on.
+   *
+   * When declared, the host can remount the tile when any listed dimension
+   * changes to prevent stale in-memory state from leaking across contexts.
+   */
+  contextDependencies?: UiContextDimension[];
+  /**
+   * Platform-specific renderers.
+   *
+   * Maps platform names to lazy-loaded component modules. At minimum, the
+   * `'react'` platform is required for the web UI.
+   */
+  renderers: TileRenderers;
+}
+//#endregion
+//#region packages/contracts/src/extension/contributions/widget-types.d.ts
+/**
+ * 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
+ */
+type WidgetSize$1 = '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.
+ */
+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$1[];
+  /**
+   * Default size when the widget is first added to a layout.
+   *
+   * Must be one of the values in {@link sizes}.
+   */
+  defaultSize: WidgetSize$1;
+}
+/**
+ * Props passed to widget components.
+ * @typeParam TData - Type of data from the widget's data source, if any.
+ */
+interface WidgetProps<TData = unknown> {
+  /** The widget's definition (from declaration). */
+  definition: WidgetDefinition;
+  /** Current size of this widget instance. */
+  size: WidgetSize$1;
+  /** 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.
+ */
+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'),
+ *         },
+ *       },
+ *     ],
+ *   },
+ * };
+ * ```
+ */
+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;
+}
+//#endregion
+//#region packages/contracts/src/extension/contributions/page-types.d.ts
+/**
+ * Widget size values used for slot declarations in page layouts.
+ */
+type WidgetSize = 'small' | 'medium' | 'large' | 'full-width';
+/**
+ * Normalized slot identifiers for page layout regions.
+ */
+type SlotId = 'main' | 'sidebar-left' | 'sidebar-right' | 'detail-panel' | 'bottom-panel' | 'widget-zone';
+/**
+ * Page mode controlling sidebar navigation behavior.
+ *
+ * - `'switch'`: Takes over the workspace; shown in the sidebar "Navigate" section
+ * - `'peek'`: Small overlay that preserves existing state
+ * - `'cover'`: Full-viewport overlay that preserves existing state
+ */
+type PageMode = 'switch' | 'peek' | 'cover';
+/** Props passed to all page components. */
+interface PageComponentProps {
+  /** Optional CSS class name for the page container. */
+  className?: string;
+  /** Current internal route within the page. */
+  internalRoute?: string | null;
+  /**
+   * Callback for internal navigation within the page.
+   * @param route - The new internal route path.
+   */
+  onNavigate?: (route: string) => void;
+}
+/** Slot definition for package declarations (fully serializable). */
+interface SlotDeclaration {
+  /** Slot identifier. */
+  id: SlotId;
+  /** Human-readable slot name. */
+  name: string;
+  /** Sizes accepted by this slot. */
+  acceptsSizes: WidgetSize[];
+  /** Minimum column width in pixels. */
+  minColumnWidth: number;
+  /** Maximum number of columns. */
+  maxColumns: number;
+  /** Whether the slot can be collapsed. */
+  collapsible?: boolean;
+  /** Whether the slot starts collapsed. */
+  defaultCollapsed?: boolean;
+}
+/** Content reference for a slot placement (view or widget). */
+type SlotContentDeclaration = {
+  type: 'view';
+  viewId: string;
+  props?: Record<string, unknown>;
+} | {
+  type: 'widget';
+  widgetId: string;
+  config?: Record<string, unknown>;
+};
+/** Placement declaration with a mandatory flag and optional position. */
+interface SlotPlacementDeclaration {
+  /**
+   * Stable unique identifier for this placement.
+   *
+   * Used as a React key and for layout persistence.
+   */
+  instanceId: string;
+  /** Content reference for this placement. */
+  content: SlotContentDeclaration;
+  /** Whether this placement is mandatory (cannot be removed by the user). */
+  mandatory: boolean;
+  /** Optional grid position. */
+  position?: {
+    col: number;
+    row: number;
+  };
+}
+/**
+ * Page declaration for packages.
+ *
+ * Fully serializable — lazy-loads any custom components. To also register the
+ * page in sidebar navigation (`PageDefinitionRegistry`), provide `mode`,
+ * `level`, and `component`. The package loader will bridge this declaration to
+ * a `PageDefinition` entry automatically.
+ * @example
+ * ```typescript
+ * // Minimal page (slot-layout system only, no sidebar entry):
+ * { id: 'my-page', name: 'My Page', scope: 'any', slots: [], defaultContent: {} }
+ *
+ * // Page with sidebar navigation entry:
+ * {
+ *   id: 'my-page',
+ *   name: 'My Page',
+ *   scope: 'any',
+ *   mode: 'switch',
+ *   level: 'any',
+ *   component: () => import('./MyPage.js'),
+ *   slots: [],
+ *   defaultContent: {},
+ * }
+ * ```
+ */
+interface PageDeclaration {
+  /**
+   * Unique page identifier.
+   *
+   * Will be namespaced to `'<package-name>:<page-id>'` by the loader.
+   */
+  id: string;
+  /** Human-readable name. */
+  name: string;
+  /** Optional description shown in page listings. */
+  description?: string;
+  /**
+   * Route path relative to the package mount point.
+   * @example `'dashboard'` becomes `/extensions/my-package/dashboard`
+   */
+  route?: string;
+  /** UI scope for this page context. */
+  scope: UiScope;
+  /** Slot definitions for this page's layout. */
+  slots: SlotDeclaration[];
+  /** Default content per slot. */
+  defaultContent: Partial<Record<SlotId, SlotPlacementDeclaration[]>>;
+  /** Optional page-level icon (lazy-loaded). */
+  icon?: () => Promise<{
+    default: ComponentType<{
+      size?: number;
+    }>;
+  }>;
+  /** Optional page-level layout constraints. */
+  layout?: {
+    /** Minimum page width in pixels. */minWidth?: number;
+  };
+  /**
+   * Navigation mode for sidebar registration.
+   *
+   * When provided alongside `level` and `component`, the package loader
+   * registers this page in the sidebar navigation (`PageDefinitionRegistry`).
+   * Omit to register in the slot-layout system only (`pageRegistry`).
+   */
+  mode?: PageMode;
+  /**
+   * Navigation level for sidebar registration.
+   *
+   * Required when `mode` is provided.
+   */
+  level?: UiNavigationLevel;
+  /**
+   * Lazy-loaded page component for sidebar navigation.
+   *
+   * Required when `mode` is provided. Must return a module with a default
+   * export that accepts {@link PageComponentProps}.
+   * @example
+   * ```typescript
+   * () => import('./MyPage.js').then(m => ({ default: m.MyPage }))
+   * ```
+   */
+  component?: () => Promise<{
+    default: ComponentType<PageComponentProps>;
+  }>;
+  /**
+   * Display order in sidebar (lower = first).
+   *
+   * Only used when `mode` is provided. Defaults to `50` when omitted.
+   */
+  order?: number;
+}
+//#endregion
+//#region packages/contracts/src/extension/contributions/tool-formatter-types.d.ts
+/** Discriminated content types for formatted tool call output. */
+type PluginTransformedContentType = 'markdown';
+/** Formatted content block for tool call display. */
+interface PluginTransformedContent {
+  /** Content rendering strategy. */
+  type: PluginTransformedContentType;
+  /** Content string interpreted according to `type`. */
+  content: string;
+}
+/**
+ * Output from a tool call formatter (package-side declaration).
+ *
+ * All fields are optional — formatters can override any subset.
+ */
+interface PluginFormattedToolCallOutput {
+  /** Replaces the tool name in the block header. */
+  label?: string;
+  /** Replaces the Arguments section. */
+  content?: PluginTransformedContent;
+  /** Replaces the Output section rendering. */
+  outputContent?: PluginTransformedContent;
+}
+/** Input shape passed to a formatter's `format` function. */
+interface PluginToolCallFormatterInput {
+  /** Name of the tool being called. */
+  toolName: string;
+  /** Arguments passed to the tool. */
+  args: Record<string, unknown>;
+  /** Current status of the tool call. */
+  status: 'pending' | 'running' | 'completed' | 'error';
+  /** Output from the tool when the call has completed. */
+  output?: string;
+}
+/**
+ * A tool call formatter declaration contributed by a package.
+ *
+ * Structurally compatible with `ToolCallFormatterDefinition` used by the
+ * UI registry, so the package loader can register declarations directly
+ * without bridging.
+ */
+interface ToolCallFormatterDeclaration {
+  /** Unique identifier for this formatter. */
+  id: string;
+  /**
+   * Declarative filter matched against the tool call input shape.
+   *
+   * Uses a `PayloadFilter` with dot-path support (e.g. `'args.subagent_type'`).
+   * All conditions are ANDed.
+   */
+  filter: PayloadFilter;
+  /**
+   * Priority for ordering when multiple formatters match.
+   *
+   * Lower number = higher priority (checked first). Default: `50`.
+   */
+  priority: number;
+  /**
+   * Pure function that transforms a tool call block into formatted output.
+   *
+   * Returns `undefined` if the formatter decides not to handle this specific
+   * call, falling through to the next formatter.
+   * @param input - The tool call block data.
+   * @returns Formatted output, or `undefined` to skip to the next formatter.
+   */
+  format: (input: PluginToolCallFormatterInput) => PluginFormattedToolCallOutput | undefined;
+}
+//#endregion
+//#region packages/contracts/src/extension/contributions/web-ui-types.d.ts
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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).
+ */
+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.
+ */
+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}.
+ */
+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.
+ */
+type ExtensionConfigComponentLoader<TConfig = unknown> = () => Promise<{
+  default: ComponentType<ExtensionConfigComponentProps<TConfig>>;
+}>;
+//#endregion
+//#region packages/contracts/src/extension/extension-contributions.d.ts
+/**
+ * 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.
+ */
+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.
+ */
+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. */
+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.
+ */
+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.
+ */
+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. */
+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. */
+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;
+}
+//#endregion
+//#region packages/contracts/src/extension/contributions/bootstrap-types.d.ts
+/**
+ * Context passed to bootstrap discovery and export operations.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+interface BootstrapDiscoverContext<TBus extends MakaioBusLike = MakaioBusLike> {
+  /** Bus instance for querying the runtime. */
+  bus: TBus;
+  /** Active project identifier. */
+  projectId: string;
+  /** Absolute path to the project repository. */
+  repoPath: string;
+}
+/** Context for export operations - identical to discover context. */
+type BootstrapExportContext<TBus extends MakaioBusLike = MakaioBusLike> = BootstrapDiscoverContext<TBus>;
+/** Context for import operations - extends discover context with the bootstrap folder path. */
+interface BootstrapImportContext<TBus extends MakaioBusLike = MakaioBusLike> extends BootstrapDiscoverContext<TBus> {
+  /** Absolute path to the `.makaio/bootstrap/` folder being imported from. */
+  bootstrapFolderPath: string;
+}
+/** A single exportable or importable bootstrap asset. */
+interface BootstrapAsset {
+  /** Identifier of the extension that owns this asset. */
+  extensionId: string;
+  /** Logical asset type (e.g. `'session'`, `'config'`). */
+  type: string;
+  /** Human-readable asset name. */
+  name: string;
+  /** Filename within the bootstrap folder. */
+  filename: string;
+  /** Whether the asset already exists in the target environment. */
+  exists?: boolean;
+  /** Identifier of an existing asset that would be replaced by import. */
+  existingId?: string;
+}
+/** Stable key type for bootstrap asset lookups. */
+type BootstrapAssetKey = string;
+/**
+ * Build a stable key for a bootstrap asset.
+ * @param asset - The asset to key.
+ * @returns Stable asset key for UI state and list rendering.
+ */
+declare function getBootstrapAssetKey(asset: BootstrapAsset): BootstrapAssetKey;
+/** Result of a single bootstrap import operation. */
+interface BootstrapImportResult {
+  /** Whether the import succeeded. */
+  success: boolean;
+  /** Action taken during import. */
+  action: 'created' | 'replaced' | 'skipped';
+  /** Error message when `success` is `false`. */
+  error?: string;
+}
+/** User-selected action for a conflicting bootstrap asset. */
+interface BootstrapChoice {
+  /** The conflicting asset. */
+  asset: BootstrapAsset;
+  /** Chosen resolution action. */
+  action: 'replace' | 'skip';
+}
+/** Result of a completed bootstrap operation (import or export). */
+interface BootstrapResult {
+  /** The asset that was processed. */
+  asset: BootstrapAsset;
+  /** Action taken. */
+  action: 'replaced' | 'skipped' | 'created';
+  /** Error message when the operation failed. */
+  error?: string;
+}
+/** Result of a bootstrap export operation. */
+interface BootstrapExportResult {
+  /** The asset that was exported. */
+  asset: BootstrapAsset;
+  /** Absolute path to the file that was written. */
+  filePath: string;
+  /** Error message when the export failed. */
+  error?: string;
+}
+/**
+ * Bootstrap capability contributed by an extension.
+ *
+ * Participates in project export (`discoverExportable` + `export`) and
+ * project import (`listImportable` + `import`) workflows.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+interface ExtensionBootstrap<TBus extends MakaioBusLike = MakaioBusLike> {
+  /** Subfolder name within `.makaio/bootstrap/` for this extension's assets. */
+  folder: string;
+  /**
+   * List assets that can be imported from the bootstrap folder.
+   * @param ctx - Import context with bus, project, and bootstrap folder path.
+   * @param files - Files present in the bootstrap folder.
+   * @returns Assets available for import.
+   */
+  listImportable: (ctx: BootstrapImportContext<TBus>, files: string[]) => Promise<BootstrapAsset[]>;
+  /**
+   * Discover assets available for export from the current project.
+   * @param ctx - Discovery context with bus and project info.
+   * @returns Assets that can be exported.
+   */
+  discoverExportable: (ctx: BootstrapDiscoverContext<TBus>) => Promise<BootstrapAsset[]>;
+  /**
+   * Export a single asset and return its serialized content.
+   * @param ctx - Export context with bus and project info.
+   * @param asset - The asset to export.
+   * @returns Serialized content string written to the bootstrap folder.
+   */
+  export: (ctx: BootstrapExportContext<TBus>, asset: BootstrapAsset) => Promise<string>;
+  /**
+   * Import a single asset from its serialized content.
+   * @param ctx - Import context with bus, project, and bootstrap folder path.
+   * @param asset - The asset being imported.
+   * @param content - Serialized content string from the bootstrap folder.
+   * @param action - User-selected conflict resolution action.
+   * @returns Result of the import operation.
+   */
+  import: (ctx: BootstrapImportContext<TBus>, asset: BootstrapAsset, content: string, action: 'replace' | 'skip') => Promise<BootstrapImportResult>;
+}
+//#endregion
+//#region packages/contracts/src/extension/makaio-extension.d.ts
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+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),
+ * };
+ * ```
+ */
+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.
+ */
+type MakaioNodeExtension<TBus extends MakaioBusLike> = MakaioExtension<NodeExtensionContext<TBus>>;
+//#endregion
+//#region packages/contracts/src/extension/extension-descriptor.d.ts
+/**
+ * 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).
+ */
+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<{
+    none: "none";
+    always: "always";
+    "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<{
+    none: "none";
+    always: "always";
+    "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}. */
+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.
+ */
+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}. */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+declare const ExtensionDescriptorSchema: z.ZodObject<{
+  name: z.ZodString;
+  displayName: z.ZodString;
+  surface: z.ZodOptional<z.ZodEnum<{
+    any: "any";
+    interactive: "interactive";
+    headless: "headless";
+  }>>;
+  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<{
+      "tray-popover": "tray-popover";
+      utility: "utility";
+      panel: "panel";
+    }>;
+    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<{
+          string: "string";
+          number: "number";
+          boolean: "boolean";
+        }>>;
+      }, 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;
+      }, 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<{
+        transform: "transform";
+        action: "action";
+        gather: "gather";
+      }>>;
+    }, 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<{
+        single: "single";
+        multi: "multi";
+      }>;
+      messageRoles: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+        user: "user";
+        assistant: "assistant";
+      }>>>>;
+    }, 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<{
+    embedded: "embedded";
+    detached: "detached";
+  }>>;
+  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<{
+      none: "none";
+      always: "always";
+      "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<{
+      none: "none";
+      always: "always";
+      "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.
+ */
+declare function parseExtensionDescriptor(input: unknown): ExtensionDescriptor;
+/** Result shape returned by {@link safeParseExtensionDescriptor}. */
+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.
+ */
+declare function safeParseExtensionDescriptor(input: unknown): ExtensionDescriptorParseResult;
+//#endregion
+//#region packages/contracts/src/extension/parse-extension-config.d.ts
+/**
+ * Parse raw extension config with a Zod schema, applying schema defaults.
+ *
+ * Handles the common extension initialization pattern where `ctx.config` may be
+ * `undefined` (no stored config) or a partial object. The schema is expected
+ * to provide defaults for all optional fields so that parsing `{}` always
+ * yields a valid config.
+ * @param schema - Zod schema with defaults for all optional fields.
+ * @param rawConfig - Raw config value from {@link ExtensionContext.config} (may be undefined).
+ * @returns Validated and defaulted config object.
+ * @example
+ * ```typescript
+ * create: (ctx) => {
+ *   const config = parseExtensionConfig(MyConfigSchema, ctx.config);
+ *   return new MyService(ctx.bus, config);
+ * },
+ * ```
+ */
+declare function parseExtensionConfig<T extends z.ZodType>(schema: T, rawConfig: unknown): z.infer<T>;
+//#endregion
+//#region packages/contracts/src/extension/extension-config-provider.d.ts
+/**
+ * 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.
+ */
+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;
+}
+//#endregion
+export { ToolCallFormatterDeclaration as $, AdapterClientRefSchema as $n, WhenContext as $t, ExtensionBootstrap as A, CliManifestSchema as An, HashTriggerContext as At, ExtensionConfigComponentProps as B, StorageManifestSchema as Bn, EventFilter as Bt, BootstrapChoice as C, AdapterProviderDefinitionContract as Cn, UiRuntimeNavigationLevel as Ct, BootstrapImportContext as D, CliArgManifest as Dn, GatheredEntry as Dt, BootstrapExportResult as E, extensionToken as En, GatheredContext as Et, ExtensionToolsContribution as F, ExtensionManifest as Fn, ActionCategoryMap as Ft, MakaioWebUiComponentProps as G, WindowParamSpec as Gn, PickerConfig as Gt, LoaderContext as H, TrayManifestSchema as Hn, ExecuteResult as Ht, ExtensionTriggersContribution as I, ExtensionManifestSchema as In, ActionShortcut as It, PromisifiedActions as J, dep as Jn, SelectionFeedback as Jt, MakaioWebUiLoader as K, WindowParamSpecSchema as Kn, PickerOpenContext as Kt, ExtensionUiContribution as L, RuntimeRequirement as Ln, ActionShortcutModifiers as Lt, AdapterContribution as M, CliSubcommandManifestSchema as Mn, HashTriggerStage as Mt, ExtensionNamespaceContribution as N, ExtensionDependency as Nn, HashTriggerSuggestResult as Nt, BootstrapImportResult as O, CliArgManifestSchema as On, HashSuggestion as Ot, ExtensionSessionEventActionsContribution as P, ExtensionDependencySchema as Pn, ActionCategory as Pt, PluginTransformedContentType as Q, AdapterClientRef as Qn, StructuralEventFilter as Qt, LogImportContribution as R, RuntimeRequirementSchema as Rn, CreateSessionEventActionResult as Rt, BootstrapAssetKey as S, AdapterDefinitionContract as Sn, BrowserEntrypointSchema as Sr, UiNavigationLevelMap as St, BootstrapExportContext as T, ExtensionToken as Tn, UiScopeMap as Tt, MakaioWebUiAction as U, WindowManifest as Un, MessageEventFilter as Ut, ExtensionFieldTypeLoader as V, TrayManifest as Vn, ExecuteContext as Vt, MakaioWebUiActions as W, WindowManifestSchema as Wn, MessageRole as Wt, PluginToolCallFormatterInput as X, CapabilityTokenMap as Xn, SessionEventActionDeclaration as Xt, PluginFormattedToolCallOutput as Y, CapabilityToken as Yn, SessionEventActionContext as Yt, PluginTransformedContent as Z, CapabilityTokenSchema as Zn, SessionEventActionOptions as Zt, ExtensionRuntimeBootContext as _, ExtensionWarningEntrySchema as _n, TriggerManifestSchema as _r, TileRenderers as _t, DetachedTransportSchema as a, ExtensionCliInteractiveContext as an, ContributionManifestSchema as ar, SlotId as at, MakaioNodeExtension as b, ExtensionWarningSeveritySchema as bn, UiSurfaceFlagsSchema as br, UiContextValueMap as bt, ExtensionDescriptorBase as c, ExtensionContext as cn, ProtocolConfig as cr, WidgetDeclaration as ct, ExtensionEntrypoints as d, ExtensionService as dn, ProtocolRefSchema as dr, WidgetRenderers as dt, ExtensionRuntimeOwnership as en, AdapterManifest as er, PageComponentProps as et, ExtensionEntrypointsSchema as f, ExtensionServiceLifecycle as fn, ProviderManifest as fr, WidgetSize$1 as ft, ExtensionContributionProcessor as g, ExtensionWarningEntry as gn, TriggerManifest as gr, TileProps as gt, safeParseExtensionDescriptor as h, ExtensionWarningActionSchema as hn, SessionEventActionManifestSchema as hr, TileIconLoader as ht, DetachedTransportConfig as i, ExtensionCliHandlerContext as in, ContributionManifest as ir, SlotDeclaration as it, getBootstrapAssetKey as j, CliSubcommandManifest as jn, HashTriggerMetadata as jt, BootstrapResult as k, CliManifest as kn, HashTrigger as kt, ExtensionDescriptorParseResult as l, NodeExtensionContext as ln, ProtocolConfigSchema as lr, WidgetDefinition as lt, parseExtensionDescriptor as m, ExtensionWarningAction as mn, SessionEventActionManifest as mr, TileDeclaration as mt, parseExtensionConfig as n, ExtensionCliBeforeRunResult as nn, ClientManifest as nr, PageMode as nt, EmbeddedDescriptor as o, ExtensionCliOutputWriter as on, LogImporterManifest as or, SlotPlacementDeclaration as ot, isDetachedDescriptor as p, ExtensionWarning as pn, ProviderManifestSchema as pr, TileCapabilities as pt, MakaioWebUiRoute as q, WindowStyle as qn, SelectionChangeContext as qt, DetachedDescriptor as r, ExtensionCliContribution as rn, ClientManifestSchema as rr, SlotContentDeclaration as rt, ExtensionDescriptor as s, ExtensionCliSubcommandEntry as sn, LogImporterManifestSchema as sr, WidgetSize as st, ExtensionConfigProvider as t, ExtensionCliBeforeRunContext as tn, AdapterManifestSchema as tr, PageDeclaration as tt, ExtensionDescriptorSchema as u, ExtensionIdentity as un, ProtocolRef as ur, WidgetProps as ut, ExtensionRuntimeBootContribution as v, ExtensionWarningSchema as vn, TriggerStage as vr, UiContextDimension as vt, BootstrapDiscoverContext as w, AdapterProviderRef as wn, UiScope as wt, BootstrapAsset as x, getExtensionWarningActionLabel as xn, BrowserEntrypoint as xr, UiNavigationLevel as xt, MakaioExtension as y, ExtensionWarningSeverity as yn, UiSurfaceFlags as yr, UiContextSnapshot as yt, ExtensionConfigComponentLoader as z, StorageManifest as zn, EntrypointConfig as zt };