@makaio/framework 1.0.0-dev-1781022866275 → 1.0.0-dev-1781023871421

package/dist/index-D90OmGmV.d.mts

@@ -0,0 +1,389 @@
+import { i as CliContribution } from "./types-MfJZ67e9.mjs";
+import { c as ExtensionInfo } from "./index-Bh_Ne7LF.mjs";
+import { r as WindowRegistry } from "./window-registry-CBcrGTv4.mjs";
+import { IMakaioBus } from "@makaio/framework/bus";
+import { ExtensionContributionProcessor, ExtensionService, ExtensionToken, MakaioExtension, NodeExtensionContext, TrayManifest, VersionLiteral } from "@makaio/framework/contracts";
+
+//#region packages/kernel/src/extension/types.d.ts
+/** Concrete Node runtime context supplied by the kernel coordinator. */
+type KernelExtensionContext = NodeExtensionContext<IMakaioBus>;
+/** Concrete executable extension shape loaded by the kernel coordinator. */
+type KernelMakaioExtension = MakaioExtension<KernelExtensionContext>;
+/** Awaited contribution processor registered with the {@link ExtensionCoordinator}. */
+type ContributionProcessor = ExtensionContributionProcessor<KernelExtensionContext>;
+/**
+ * Hosted runtime surface category used for extension/package gating.
+ *
+ * Represents the concrete surface a runtime IS -- `'any'` is intentionally
+ * absent because a runtime cannot BE `'any'`; it is always interactive or
+ * headless. Package manifests may declare `'any'` as their surface affinity,
+ * which the coordinator interprets as "load on all surfaces".
+ */
+type ExtensionRuntimeSurface = 'interactive' | 'headless';
+/**
+ * Host-advertised runtime capability fact.
+ */
+interface RuntimeCapability {
+  /** Stable capability token. */
+  readonly id: string;
+  /** Concrete capability contract version when the host exposes one. */
+  readonly version?: VersionLiteral;
+}
+/**
+ * Snapshot of the runtime environment provided by the host.
+ *
+ * The coordinator uses this to evaluate {@link RuntimeRequirement} gates on
+ * each extension before deciding whether to load it.
+ */
+interface RuntimeEnvironment {
+  /**
+   * Identifiers of the active host runtimes (e.g. `'node'`, `'electron'`).
+   *
+   * Extensions that declare `{ type: 'host', id: '...' }` requirements check
+   * against this set.
+   */
+  readonly hosts: ReadonlySet<string>;
+  /**
+   * Capability tokens advertised by the host (e.g. `'storage.drizzle'`).
+   *
+   * Extensions that declare `{ type: 'capability', id: '...' }` requirements
+   * check against this set. Versioned requirements additionally consult
+   * {@link RuntimeEnvironment.capabilityVersions}.
+   */
+  readonly capabilities: ReadonlySet<string>;
+  /**
+   * Concrete versions for host capabilities that expose a versioned contract.
+   *
+   * A capability requirement with a `version` range is satisfied only when the
+   * capability ID is present and this map contains a satisfying concrete version.
+   */
+  readonly capabilityVersions?: ReadonlyMap<string, VersionLiteral>;
+}
+/**
+ * Options for constructing an {@link ExtensionCoordinator}.
+ */
+interface ExtensionCoordinatorOptions {
+  /** Hosted surface category used to apply package gating. Defaults to `'headless'`. */
+  surface?: ExtensionRuntimeSurface;
+  /**
+   * Host launcher command embedded into client wiring installed from warning actions.
+   *
+   * Defaults to `'makaio'` for framework-only hosts. Hosts pass their
+   * own launcher policy through this seam so the runtime does not infer it
+   * from process entrypoints.
+   */
+  launcherCommand?: string;
+  /** Optional database instance for storage handler registration (opaque — cast to MakaioDatabase at call site). */
+  db?: unknown;
+  /**
+   * Node host fields for the context supplied to extension factories.
+   *
+   * Required when any loaded extension declares a `create` factory. When absent,
+   * extensions with `create` will fail to start.
+   *
+   * Omit `config`, `signal`, and `hasExtension` — those are coordinator-owned
+   * and assembled per extension at context-build time.
+   */
+  extensionContextBase?: Omit<KernelExtensionContext, 'bus' | 'identity' | 'getService' | 'dataDir' | 'config' | 'signal' | 'hasExtension'>;
+  /**
+   * Host-provided runtime environment snapshot used to evaluate extension
+   * {@link RuntimeRequirement} gates during {@link ExtensionCoordinator.load}.
+   *
+   * Extensions whose {@link MakaioExtension.requires} entries are not all
+   * satisfied by the supplied environment are excluded. Omit only in tests that
+   * intentionally bypass environment gating.
+   */
+  runtimeEnvironment?: RuntimeEnvironment;
+  /**
+   * Optional callback to persist enabled/disabled state after a setEnabled call.
+   * The composition root supplies this to bridge into PreferencesSubjects or another durable store.
+   */
+  persistEnabled?: (name: string, enabled: boolean) => Promise<void>;
+  /**
+   * Optional callback to retrieve persisted enabled state during startAll.
+   * Returns `false` to skip a package at boot, `true` or `undefined` to start normally.
+   */
+  loadEnabled?: (name: string) => boolean | undefined;
+  /**
+   * Optional callback to retrieve stored configuration for a package during
+   * startAll and enablePackage. Returns `undefined` when no stored config exists.
+   */
+  loadConfig?: (name: string) => Record<string, unknown> | undefined;
+  /**
+   * Optional callback invoked by {@link ExtensionCoordinator.startAll} to run
+   * database migrations declared by loaded packages before any services start.
+   *
+   * The coordinator collects all packages whose `StorageManifest.migrations`
+   * field is set and passes them as an array of
+   * `{ name, migrationsPath, migrationSourceId }` objects to this callback in topological
+   * (dependency) order. The callback is responsible for applying pending
+   * migrations — typically via Drizzle `migrate()` or the bundled
+   * `applyMigrations()` helper — using a tracking table keyed to the migration
+   * bundle identity so packages that share one folder share one ledger.
+   *
+   * When absent, declared migrations are silently skipped and storage tables
+   * that depend on them will not be created at runtime.
+   *
+   * The `migrationsPath` values are absolute discovery paths resolved by the
+   * coordinator from each package's `StorageManifest.migrations` field
+   * plus executable `storage.packageRoot` metadata when needed.
+   * `migrationSourceId` is the stable runtime identity used for bundled hosts;
+   * when a package does not declare one, it falls back to `migrationsPath`.
+   * @param sources - Migration sources in dependency order, each carrying the
+   *   package name, absolute migration folder path, and stable source id.
+   * @returns A promise that resolves when all migrations have been applied.
+   */
+  runMigrations?: (sources: ReadonlyArray<{
+    name: string;
+    migrationsPath: string;
+    migrationSourceId: string;
+  }>) => Promise<void>;
+}
+//#endregion
+//#region packages/kernel/src/extension/extension-coordinator.d.ts
+/**
+ * Manages optional extensions through a unified lifecycle with per-extension state
+ * machine, bus observability, and window/tray/CLI surface collection.
+ *
+ * Lifecycle flow for each extension:
+ * ```
+ * discovered -> initializing -> [create + init + contributions] -> active
+ *                            ↘ failed  (any step fails, contributions rolled back)
+ *                            ↘ skipped  (ServiceSkipError from create or init,
+ *                                        or loadEnabled returned false at boot)
+ * ```
+ *
+ * Every state transition emits `kernel:extension.stateChanged` on the bus.
+ * Non-critical failures are isolated so remaining extensions continue to start.
+ * Critical extension failures abort boot because the host declared them mandatory.
+ *
+ * During {@link load}, window manifests are registered into
+ * {@link windowRegistry}, tray entries are collected into {@link trayEntries},
+ * and CLI contributions are collected into {@link cliContributions}. Static
+ * tray entries are bridged to the tray menu bus service after each extension
+ * starts so the tray service can be supplied by the same extension graph.
+ *
+ * During {@link startAll}, each extension's {@link MakaioExtension.create} factory
+ * is called with a `NodeExtensionContext`, followed by `service.init()`.
+ * Storage handlers (if any) are registered via
+ * `MakaioExtension.storage.registerHandlers` when a `db` instance is
+ * provided to the constructor.
+ */
+declare class ExtensionCoordinator {
+  private readonly bus;
+  private readonly surface;
+  private readonly db;
+  private readonly extensionContextBase;
+  private readonly runtimeEnvironment;
+  /**
+   * AbortController signalling graceful shutdown to all active packages.
+   *
+   * Aborted at the start of {@link shutdown} so packages receive the signal
+   * before their services are destroyed.
+   */
+  private readonly shutdownController;
+  /** Insertion-ordered map so iteration matches dependency sort order. */
+  private readonly entries;
+  private loadOrder;
+  private loaded;
+  private started;
+  private rpcCleanups;
+  private readonly contributionProcessors;
+  /**
+   * Transient map from composite key (`toastId:actionId`) to the corresponding
+   * {@link ExtensionWarningAction}. Populated during {@link emitWarningsForEntry}
+   * and cleared per package before that package's current warning set is
+   * recorded, then cleared globally on {@link shutdown}.
+   *
+   * This map is intentionally coordinator-owned because toast interactions
+   * arrive after warning emission and need a short-lived runtime lookup without
+   * exposing executable warning actions in the toast payload.
+   */
+  private readonly warningActionMap;
+  /** Window registry populated during {@link load}. */
+  readonly windowRegistry: WindowRegistry;
+  private readonly _trayEntries;
+  private readonly _cliContributions;
+  private readonly persistEnabled;
+  private readonly loadEnabled;
+  private readonly loadConfig;
+  private readonly runMigrations;
+  /**
+   * @param bus - Bus instance for emitting lifecycle events and serving the list RPC.
+   * @param options - Coordinator configuration.
+   */
+  constructor(bus: IMakaioBus, options?: ExtensionCoordinatorOptions);
+  /**
+   * Tray manifest entries collected from packages during {@link load}.
+   * @returns Immutable snapshot of all collected tray entries.
+   */
+  get trayEntries(): ReadonlyArray<TrayManifest & {
+    readonly packageName: string;
+  }>;
+  /**
+   * CLI contributions collected from packages during {@link load}.
+   * @returns Immutable snapshot of all collected CLI contributions.
+   */
+  get cliContributions(): ReadonlyArray<CliContribution>;
+  /**
+   * Returns extensions that declare HTTP routes.
+   * Primarily retained for diagnostics and compatibility with callers that
+   * need a snapshot of loaded HTTP surfaces. Runtime route mounting is handled
+   * by contribution processors as extensions activate or stop.
+   * @returns Loaded extensions that have an `http` field defined.
+   */
+  extensionsWithHttp(): ReadonlyArray<{
+    http: {
+      prefix: string;
+      mount: (app: unknown) => void;
+    };
+  }>;
+  /**
+   * Load extension manifests and build the dependency graph.
+   *
+   * Sets all entries to the `discovered` state and registers the
+   * `kernel:extension.list`, `kernel:extension.get`, `kernel:extension.setEnabled`,
+   * `cli.listContributions`, and `cli.execute` RPC handlers.
+   *
+   * Extensions that do not match the coordinator's runtime surface or declared
+   * environment requirements are
+   * silently excluded. Dependents of excluded extensions are transitively pruned.
+   *
+   * Window manifests are registered into {@link windowRegistry}, tray entries
+   * are collected into {@link trayEntries}, and CLI contributions are collected
+   * into {@link cliContributions} -- all before any services are started.
+   *
+   * Single-use: calling this method twice on the same instance throws.
+   * @param packages - Extension manifests to register.
+   * @param configDefaults - Optional map of extension name to default config values
+   *   sourced from descriptor.json.
+   * @throws Error if called more than once, if a dependency cycle is detected,
+   *   or if dependency sorting fails.
+   */
+  load(packages: ReadonlyArray<KernelMakaioExtension>, configDefaults?: ReadonlyMap<string, Readonly<Record<string, unknown>>>): void;
+  /**
+   * Start all loaded packages in dependency order.
+   *
+   * For each package the state machine advances:
+   * `discovered -> initializing -> active | failed | skipped`
+   *
+   * Failures are isolated: a package that throws during `create` or `init` is
+   * set to `failed` and the error is captured, but remaining packages continue
+   * to start unless the package declares `critical: true`.
+   *
+   * Single-use: calling this method twice on the same instance throws.
+   * @throws Error if called more than once, before {@link load}, or when a
+   *   critical package fails.
+   */
+  startAll(): Promise<void>;
+  /**
+   * Shut down all active packages in reverse dependency order.
+   *
+   * Calls each package's service `destroy()` method (if any). Errors are
+   * logged but do not stop remaining packages from shutting down.
+   *
+   * Safe to call even if {@link startAll} was never called.
+   */
+  shutdown(): Promise<void>;
+  /**
+   * Return the current state snapshot for all registered packages.
+   * @returns Array of {@link ExtensionInfo} objects reflecting current observable states.
+   */
+  list(): ExtensionInfo[];
+  /**
+   * Retrieve the live service instance for a named extension.
+   * @param tokenOrName - Extension token or extension name string.
+   * @returns The active service instance, or `undefined`.
+   */
+  getExtensionService<TService = ExtensionService>(tokenOrName: string | ExtensionToken<TService>): TService | undefined;
+  /**
+   * Look up a loaded extension by name.
+   * @param name - Extension name.
+   * @returns The extension, or `undefined` if not loaded.
+   */
+  getExtension(name: string): KernelMakaioExtension | undefined;
+  /**
+   * Iterate all active extensions in dependency order with their contexts.
+   *
+   * Intended for host-owned integration code that needs a snapshot of active
+   * packages after the coordinator has completed startup.
+   * @param callback - Called once per active extension with its name, manifest,
+   *   and a per-extension `NodeExtensionContext`.
+   */
+  forEachActiveExtension(callback: (name: string, pkg: KernelMakaioExtension, ctx: KernelExtensionContext) => void): void;
+  /**
+   * Invoke a callback for a single active extension with its resolved context.
+   *
+   * Singular complement to {@link forEachActiveExtension} for targeted operations
+   * after an extension is re-enabled.
+   * No-ops when the extension is not found or not in `active` state.
+   * @param name - Name of the extension to target.
+   * @param callback - Called with the extension name, manifest, and a
+   *   per-extension `NodeExtensionContext` when the extension is active.
+   */
+  forExtension(name: string, callback: (name: string, pkg: KernelMakaioExtension, ctx: KernelExtensionContext) => void): void;
+  /**
+   * Register an awaited contribution processor.
+   *
+   * The processor's `processActivated` method is called
+   * (and awaited) each time an extension transitions to `active` — both during
+   * {@link startAll} and on re-enable via `kernel:extension.setEnabled(true)`.
+   *
+   * `processStopped` (when present) is called before
+   * the extension's service is destroyed during {@link shutdown} or
+   * `kernel:extension.setEnabled(false)`.
+   *
+   * Processors run in registration order during activation and reverse
+   * registration order during deactivation. During activation, processor errors
+   * cause the extension to transition to `failed` with rollback of
+   * already-activated contributions. During deactivation, errors are caught and
+   * logged (best-effort).
+   * @param processor - Processor to register.
+   * @returns Cleanup function that removes the processor from the registry.
+   */
+  registerContributionProcessor(processor: ContributionProcessor): () => void;
+  /**
+   * Handle the `kernel:extension.setEnabled` RPC by enabling or disabling an extension.
+   *
+   * Public so the extracted RPC handler module can call it. Delegates to the
+   * shared toggle lifecycle helper.
+   * @param name - Name of the extension to toggle.
+   * @param enabled - `true` to enable, `false` to disable.
+   * @returns `true` on success, `false` when the state machine rejects.
+   */
+  handleSetEnabled(name: string, enabled: boolean): Promise<boolean>;
+  /**
+   * Create the shared extension-context helper host without exposing coordinator internals.
+   * @returns Helper host for config resolution and ExtensionContext construction.
+   */
+  private createExtensionContextHost;
+  /**
+   * Create the helper host for extension health checks.
+   * @returns Coordinator state required by the health runner.
+   */
+  private createExtensionHealthHost;
+  /**
+   * Check whether an extension has reached active state.
+   * @param name - Extension name to check.
+   * @returns `true` when the extension is active.
+   */
+  private hasActiveExtension;
+}
+//#endregion
+//#region packages/kernel/src/extension/extension-selection.d.ts
+/**
+ * Keep the last extension registered for a given name.
+ * @param extensions - Eligible extensions in load priority order.
+ * @returns Unique extensions with later entries winning name collisions.
+ */
+declare function coalesceExtensionOverrides(extensions: ReadonlyArray<KernelMakaioExtension>): KernelMakaioExtension[];
+/**
+ * Filter extensions by runtime surface / environment requirements and prune dependents.
+ * @param extensions - Full extension set to filter.
+ * @param surface - Runtime surface to match.
+ * @param env - Host-provided runtime environment, or `undefined` to allow all.
+ * @returns Extensions eligible for loading in the current host environment.
+ */
+declare function filterEligibleExtensions(extensions: ReadonlyArray<KernelMakaioExtension>, surface: ExtensionRuntimeSurface, env: RuntimeEnvironment | undefined): KernelMakaioExtension[];
+//#endregion
+export { ExtensionCoordinatorOptions as a, KernelMakaioExtension as c, ContributionProcessor as i, RuntimeCapability as l, filterEligibleExtensions as n, ExtensionRuntimeSurface as o, ExtensionCoordinator as r, KernelExtensionContext as s, coalesceExtensionOverrides as t, RuntimeEnvironment as u };

package/dist/index-D9MwJ2Q8.d.mts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+
+//#region services/log-import/src/schemas/mode.d.ts
+/**
+ * Tri-state import mode for external session discovery.
+ *
+ * - `disabled`: No scanning or import
+ * - `discover`: Shallow scan creates stubs in session list (lazy-load on demand)
+ * - `import`: Full import of all sessions and messages
+ */
+declare const LogImportModeSchema: z.ZodEnum<{
+  disabled: "disabled";
+  discover: "discover";
+  import: "import";
+}>;
+/** Tri-state import mode for external session discovery. */
+type LogImportMode = z.infer<typeof LogImportModeSchema>;
+/**
+ * Persisted settings shape for the `log_import_settings` table.
+ *
+ * Represents a global (adapter-level) import mode row. Project-scoped settings
+ * live in the host-owned `log_import_scoped_settings` table and are not
+ * represented here.
+ */
+declare const LogImportSettingsSchema: z.ZodObject<{
+  adapterName: z.ZodString;
+  mode: z.ZodEnum<{
+    disabled: "disabled";
+    discover: "discover";
+    import: "import";
+  }>;
+  createdAt: z.ZodNumber;
+  updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Persisted settings shape for the `log_import_settings` table.
+ *
+ * Represents a global (adapter-level) import mode row.
+ */
+type LogImportSettings = z.infer<typeof LogImportSettingsSchema>;
+//#endregion
+//#region services/log-import/src/schemas/settings.d.ts
+/**
+ * Category key for last scan timestamp in preferences storage.
+ * Separate from settings to avoid read-modify-write race conditions.
+ */
+declare const IMPORT_LAST_SCAN_CATEGORY = "import-last-scan";
+//#endregion
+//#region services/log-import/src/schemas/list-importers.d.ts
+/**
+ * Information about a registered log importer.
+ */
+declare const LogImporterInfoSchema: z.ZodObject<{
+  id: z.ZodString;
+  adapterName: z.ZodString;
+  displayName: z.ZodString;
+  source: z.ZodEnum<{
+    adapter: "adapter";
+    extension: "extension";
+  }>;
+  logFilePattern: z.ZodString;
+  isRunning: z.ZodBoolean;
+  supportsManualImport: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+type LogImporterInfo = z.infer<typeof LogImporterInfoSchema>;
+//#endregion
+export { LogImportSettings as i, IMPORT_LAST_SCAN_CATEGORY as n, LogImportMode as r, LogImporterInfo as t };

package/dist/index-DANINzMu.d.mts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+
+//#region core/contracts/src/provider/visibility.d.ts
+/**
+ * Per-model visibility state. Ordered: disabled → enabled → visible.
+ *
+ * - `disabled` — Model is off; cannot be used by profiles/workers or shown in picker.
+ * - `enabled` — Model is usable by profiles/workers but hidden from the AgentPicker.
+ * - `visible` — Model is usable and shown in the AgentPicker UI.
+ */
+declare const ModelVisibilitySchema: z.ZodEnum<{
+  enabled: "enabled";
+  disabled: "disabled";
+  visible: "visible";
+}>;
+type ModelVisibility = z.infer<typeof ModelVisibilitySchema>;
+/**
+ * Determines the default visibility state for models without explicit overrides.
+ *
+ * - `show-all` — All models default to `visible`. Suitable for curated providers (Anthropic, Gemini).
+ * - `allowlist` — All models default to `disabled`. Suitable for firehose providers (NanoGPT, OpenRouter).
+ */
+declare const ModelFilterModeSchema: z.ZodEnum<{
+  allowlist: "allowlist";
+  "show-all": "show-all";
+}>;
+type ModelFilterMode = z.infer<typeof ModelFilterModeSchema>;
+/**
+ * Resolves the effective visibility for a model given the provider's filter mode
+ * and any per-model overrides.
+ *
+ * Pure function usable by both backend validation and frontend filtering.
+ * @param modelName - The model identifier to resolve
+ * @param filterMode - The provider's filter mode
+ * @param overrides - Sparse per-model visibility overrides (nullable)
+ * @returns The resolved visibility state
+ */
+declare function resolveModelVisibility(modelName: string, filterMode: ModelFilterMode, overrides: Record<string, ModelVisibility> | null | undefined): ModelVisibility;
+//#endregion
+export { resolveModelVisibility as a, ModelVisibilitySchema as i, ModelFilterModeSchema as n, ModelVisibility as r, ModelFilterMode as t };