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

package/dist/runtime-node/index.d.mts

@@ -0,0 +1,745 @@
+import { RuntimeSubjects } from "./bus/runtime/namespace.mjs";
+import { a as FilesystemDescriptorDiscovery, n as ExplicitDescriptorDiscovery, o as FilesystemDescriptorDiscoveryOptions, r as ExtensionDiscovery, t as DiscoveredExtension } from "../extension-discovery-CkV_VRdJ.mjs";
+import { a as isMakaioExtensionLike, c as resolveConventionEntrypoint, i as isCliContributionLike, n as LoadExtensionsOptions, o as isWithinDirectory, r as entrypointStem, s as loadExtensions, t as DescriptorSourcePackageGroup } from "../load-extensions-D9nbDIiW.mjs";
+import { A as normalizeNodeHostCapabilities, B as HttpContributionPhase, C as TransportReadyInfo, D as WorkflowWorkerEntryResolverOptions, E as WorkflowWorkerEntryMode, F as NodeFrameworkModuleResolver, H as HonoRouteGraph, I as NoopFrameworkModuleResolver, L as resolveFrameworkSpecifier, M as ShutdownStep, N as BridgeBrowserOptions, O as resolveWorkflowWorkerEntry, P as FrameworkModuleResolver, R as HttpRouteGraphBuilder, S as ServerTransportProvider, T as WorkflowRunnerBootOptions, U as HonoRouteGraphOptions, V as HttpRouteContribution, W as createHonoRouteGraph, _ as WorkflowRunResult, a as InProcessWorkflowRunnerOptions, b as CoreBootOptions, g as ThinWorkflowPiscinaRunnerOptions, h as IWorkflowRunner, i as InProcessWorkflowRunner, j as selectFrameworkCorePackages, k as HostCapabilityDeclaration, m as ThinWorkflowPiscinaRunner, v as BootCoordinatorSetupContext, w as UpstreamTelemetryBootOptions, x as MakaioRuntime, y as BootMakaioRuntimeOptions, z as createHttpRouteGraphBuilder } from "../index-YDfOv0GT.mjs";
+import { ConfiguredRuntimeOptions, LoadMakaioConfigOptions, LoadedMakaioConfig, MAKAIO_CONFIG_FILE_ENV, MAKAIO_HOME_ENV, MakaioConfig, ParseMakaioConfigOptions, ParsedMakaioConfig, WorkflowRunnerConfig, buildConfiguredRuntimeOptions, createMakaioConfigDiscovery, defineMakaioConfig, loadMakaioConfig, parseMakaioConfig, resolveMakaioConfigPath, resolveMakaioHome, shouldIncludeExtension } from "./makaio-config.mjs";
+import { z } from "zod";
+import { IConfigStorage } from "@makaio/framework/core";
+import { BusTransport, IMakaioBus } from "@makaio/framework/bus";
+import { AdapterClientRef, AdapterProviderDefinitionContract, Config, MakaioNodeExtension, ProtocolId } from "@makaio/framework/contracts";
+import { BaseService } from "@makaio/framework/service-base";
+import { MakaioDatabase } from "@makaio/framework/storage/drizzle";
+import { AdapterFile, CredentialRef, ProviderConfigFile } from "@makaio/framework/contracts/config";
+import { IAdapterConfigRepository, IAdapterConfigRepository as IAdapterConfigRepository$1 } from "@makaio/framework/services/adapter-subsystem";
+import { DispatchingAuth } from "@makaio/framework/node/transports";
+import { DatabaseClient } from "@makaio/framework/storage/drizzle/client";
+import { ContributionProcessor, ExtensionCoordinator, KernelMakaioExtension, TransportProvider } from "@makaio/framework/kernel";
+import { IModelRegistryCache, ModelRegistry } from "@makaio/framework/services/model-registry";
+import { MachineKeyStatus, MachineKeyValidation, PersistedMachineIdentity, loadOrCreateMachineIdentity, machineKeysExist, validateMachineKeys } from "@makaio/framework/node/machine-identity";
+import { TransportAuth as TransportAuth$1 } from "@makaio/framework/node/bus-server";
+import { ConfigProvider } from "@makaio/framework/providers";
+import { Server } from "node:http";
+//#region runtimes/node/src/register-adapter-name-resolver.d.ts
+/**
+ * Register middleware to resolve `adapterName` to `adapterId` for `getCapabilities` requests.
+ *
+ * Problem: Adapter handlers filter by `adapterId` only — name-only requests never reach handlers.
+ * Solution: Middleware with priority 20 resolves `adapterName` through the
+ * runtime identity seam before adapter handlers run.
+ * @param bus - The bus instance to register the middleware on
+ * @returns Cleanup function to unsubscribe the middleware
+ */
+declare function registerAdapterNameResolver(bus: IMakaioBus): () => void;
+//#endregion
+//#region subsystems/adapter/src/adapter-runtime-lifecycle.d.ts
+/**
+ * Platform-provided defaults injected by the runtime host.
+ *
+ * Mirrors the shape of `PlatformDefaults` from `@makaio/ai-adapters-core`
+ * without taking a dependency on the host-layer package.
+ */
+interface PlatformDefaults {
+  /** Default working directory for agent execution (e.g. `os.tmpdir()` on Node.js). */
+  cwd?: string;
+  /** Default environment variables. */
+  env?: Record<string, string>;
+}
+//#endregion
+//#region subsystems/adapter/src/index.d.ts
+/**
+ * Options for creating the adapter subsystem extension package.
+ */
+interface CreateAdapterSubsystemPackageOptions {
+  /**
+   * Repository seam used by the subsystem service for file-backed config storage.
+   */
+  readonly configRepository: IAdapterConfigRepository;
+  /**
+   * Extension coordinator forwarded to {@link AdapterContributionProcessor}.
+   *
+   * The composition root registers the contribution processor (via
+   * {@link createAdapterSubsystemContributionProcessor}) with this coordinator
+   * before `coordinator.startAll()` so adapter contributions run in a stable
+   * order relative to other contribution processors.
+   */
+  readonly coordinator: ExtensionCoordinator;
+  /**
+   * Platform-provided defaults forwarded to adapter factories.
+   */
+  readonly platformDefaults: PlatformDefaults;
+}
+/**
+ * Create the adapter subsystem extension package.
+ *
+ * The returned package is critical and declares the `adapters` capability.
+ * The composition root must register the contribution processor via
+ * {@link createAdapterSubsystemContributionProcessor} before calling
+ * `coordinator.startAll()` to ensure adapter contributions are processed in a
+ * stable order.
+ * @param options - Package-scoped dependencies including the coordinator.
+ * @returns Critical Makaio extension for the adapter subsystem.
+ */
+declare function createAdapterSubsystemPackage(options: CreateAdapterSubsystemPackageOptions): MakaioNodeExtension<IMakaioBus>;
+//#endregion
+//#region runtimes/node/src/compose-adapter-runtime.d.ts
+/**
+ * Composition seam for booting a local adapter runtime.
+ *
+ * Encapsulates the proven host sequence for making `adapter.*` execution
+ * subjects locally owned, so every adapter-capable runtime composes it the
+ * same way instead of reinventing it. There are two phases because the kernel
+ * lifecycle requires it:
+ *
+ * 1. {@link prepareAdapterRuntime} — call **before** `coordinator.startAll()`:
+ *    builds the adapter-subsystem package (add it to the coordinator load set)
+ *    and registers the adapter contribution processor so adapter contributions
+ *    are awaited during activation.
+ * 2. {@link activateAdapterRuntimeIdentity} — call **after** `coordinator.startAll()`:
+ *    registers the adapter-runtime identity handlers and the adapter-name
+ *    resolver, which resolve `adapterName` to the deterministic adapter id that
+ *    live `AIAdapter` instances filter `AdapterSubjects.startAgent` on.
+ *
+ * The locality invariant this seam upholds: the `currentMachineId` passed to
+ * {@link activateAdapterRuntimeIdentity} MUST be the same machine id the
+ * coordinator injects as `extensionContextBase.machineId` (and therefore the
+ * id `AdapterSubsystemService` and `SubagentService` derive adapter ids from).
+ * If they diverge, `AdapterRuntimeSubjects.resolveId` yields an id no local
+ * adapter listens on and `startAgent` silently falls through to the transport.
+ */
+/** Input for {@link prepareAdapterRuntime} (the pre-`startAll` phase). */
+interface PrepareAdapterRuntimeInput {
+  /** Coordinator that loads the adapter-subsystem package and owns activation. */
+  readonly coordinator: ExtensionCoordinator;
+  /** Persistence seam for adapter/provider configuration. */
+  readonly configRepository: IAdapterConfigRepository$1;
+  /** Platform defaults (cwd/env) supplied to adapter instances. */
+  readonly platformDefaults: PlatformDefaults;
+}
+/** Result of {@link prepareAdapterRuntime}. */
+interface PreparedAdapterRuntime {
+  /**
+   * The adapter-subsystem package. The caller MUST add this to the array passed
+   * to `coordinator.load(...)`; its `create` reads `ctx.machineId`, so adapter
+   * ids derive from the coordinator's machine id.
+   */
+  readonly adapterSubsystemPackage: ReturnType<typeof createAdapterSubsystemPackage>;
+}
+/** Input for {@link activateAdapterRuntimeIdentity} (the post-`startAll` phase). */
+interface ActivateAdapterRuntimeIdentityInput {
+  /** Bus the identity handlers and name resolver are registered on. */
+  readonly bus: IMakaioBus;
+  /**
+   * The runtime's machine id. MUST equal the coordinator's
+   * `extensionContextBase.machineId` (see the locality invariant above).
+   */
+  readonly currentMachineId: string;
+  /**
+   * Optional override for enumerating known adapter names. Defaults to querying
+   * `AdapterSubsystemSubjects.listAdapterConfigs` on the bus, matching the host.
+   */
+  readonly listKnownAdapterNames?: () => Promise<Iterable<string>>;
+}
+/** Result of {@link activateAdapterRuntimeIdentity}. */
+interface ActivatedAdapterRuntimeIdentity {
+  /** Tear down the identity handlers and the adapter-name resolver. */
+  readonly cleanup: () => void;
+}
+/**
+ * Build the adapter-subsystem package and register its contribution processor.
+ *
+ * Call before `coordinator.startAll()`. Registering the contribution processor
+ * only stores it for use during activation, so it is order-independent relative
+ * to `coordinator.load(...)` as long as it happens before `startAll()`.
+ * @param input - Coordinator, config repository, and platform defaults.
+ * @returns The adapter-subsystem package to add to the coordinator load set.
+ */
+declare function prepareAdapterRuntime(input: PrepareAdapterRuntimeInput): PreparedAdapterRuntime;
+/**
+ * Register the adapter-runtime identity handlers and adapter-name resolver.
+ *
+ * Call after `coordinator.startAll()` so that `CapabilityService` and the
+ * adapter subsystem have registered their handlers.
+ * @param input - Bus, the runtime machine id, and an optional name enumerator.
+ * @returns A cleanup that tears both registrations down.
+ */
+declare function activateAdapterRuntimeIdentity(input: ActivateAdapterRuntimeIdentityInput): ActivatedAdapterRuntimeIdentity;
+//#endregion
+//#region runtimes/node/src/db-migrations.d.ts
+/** Options for applying framework central migrations. */
+interface RunMigrationsOptions {
+  /** Optional filesystem path to a bundled framework `drizzle/` migrations directory. */
+  readonly migrationsDir?: string;
+}
+/**
+ * Run all database migrations.
+ *
+ * 1. Runs Drizzle-generated migrations for all framework tables
+ * 2. Creates framework-owned FTS5 virtual tables and triggers (not supported by Drizzle)
+ * @param db - Drizzle database instance
+ * @param options - Optional migration source overrides for bundled hosts.
+ */
+declare function runMigrations(db: MakaioDatabase, options?: RunMigrationsOptions): Promise<void>;
+//#endregion
+//#region runtimes/node/src/file-config-storage.d.ts
+/**
+ * File-based config storage for Node.js runtime.
+ *
+ * Reads/writes `<makaioHome>/config.json` for bootstrap configuration.
+ * Returns default config if file is missing.
+ */
+declare class FileConfigStorage implements IConfigStorage<Config> {
+  private readonly configPath;
+  /**
+   * Create a new FileConfigStorage instance.
+   * @param makaioHome - Makaio home directory (e.g. `~/.makaio`). The config
+   *   file is stored as `config.json` inside this directory.
+   */
+  constructor(makaioHome: string);
+  /**
+   * Get the current config.
+   * Returns default config (applying Zod defaults) if file doesn't exist.
+   * @returns The config object
+   */
+  getConfig(): Promise<Config>;
+  /**
+   * Save the config.
+   * Creates directory if it doesn't exist.
+   * @param config - The config object to save
+   */
+  saveConfig(config: Config): Promise<void>;
+}
+//#endregion
+//#region runtimes/node/src/model-registry/static-registry-path.d.ts
+/**
+ * Resolve the source-tree static model registry YAML when running from a repo checkout.
+ *
+ * Packaged Electron bundles run from `app.asar/dist`, where no workspace root
+ * exists. In that case the static source-tree fallback is unavailable and the
+ * registry fetcher chain should continue with the other configured sources.
+ * @param baseDir - Absolute directory inside the source workspace when available
+ * @returns Static model registry path, or `undefined` outside a source checkout
+ */
+declare function resolveStaticModelRegistryPath(baseDir: string): string | undefined;
+//#endregion
+//#region runtimes/node/src/http-server-utils.d.ts
+/**
+ * Wait until an HTTP server emits `listening` or fails with an error.
+ *
+ * Fast-exits if the server is already bound. Attaches a persistent error
+ * handler after binding to prevent unhandled rejections from post-bind errors.
+ * @param server - HTTP server to observe.
+ * @param port - Configured port, used in the EADDRINUSE error message.
+ */
+declare function waitForServerListening(server: Server, port: number): Promise<void>;
+/**
+ * Resolve the bound TCP port from an HTTP server that is already listening.
+ * @param server - HTTP server instance.
+ * @returns Numeric TCP port.
+ */
+declare function resolveListeningPort(server: Server): number;
+//#endregion
+//#region runtimes/node/src/optional-package.d.ts
+/**
+ * Detect the intentional absence of an optional runtime package.
+ *
+ * Only errors proving the named package itself is missing are swallowed.
+ * Transitive dependency failures or module evaluation errors must surface so
+ * callers do not treat a broken package the same as an absent one.
+ * @param error - Dynamic import error.
+ * @param packageName - Exact package name the host attempted to import.
+ * @returns `true` when the named package is not installed.
+ */
+declare function isMissingOptionalRuntimePackage(error: unknown, packageName: string): boolean;
+/**
+ * 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 so callers
+ * do not silently ignore broken packages.
+ * @typeParam T - Expected module shape (caller-asserted, not runtime-verified).
+ * @param specifier - Package specifier to import (e.g. `'@makaio/foo'` or `'@makaio/foo/runtime'`).
+ * @returns The imported module cast to `T`, or `null` when the package is not installed.
+ */
+declare function tryImport<T>(specifier: string): Promise<T | null>;
+//#endregion
+//#region runtimes/node/src/boot.d.ts
+/**
+ * Platform-agnostic Makaio runtime boot core.
+ *
+ * Runs the full startup sequence (steps 1–12) given a pre-constructed
+ * transport provider and the bound address of the server it is attached to.
+ * The transport must be constructed but NOT yet connected — this function
+ * calls `transport.connect(bus, machineId)` internally once the bus and
+ * machine ID are available (step 3).
+ *
+ * This function is the shared implementation reused by both
+ * {@link bootMakaioRuntime} (Node.js) and the Bun platform wrapper in
+ * `@makaio/runtime-bun`.
+ * @param transport - Pre-constructed (not yet connected) server transport provider.
+ * @param boundPort - TCP port the server is listening on.
+ * @param boundHost - Host address the server is bound to.
+ * @param options - Platform-agnostic boot options.
+ * @returns Runtime handle with `port`, `machineId`, and `shutdown()`.
+ */
+declare function bootMakaioRuntimeCore(transport: ServerTransportProvider, boundPort: number, boundHost: string, options: CoreBootOptions): Promise<MakaioRuntime>;
+/**
+ * Boot the full Makaio runtime against a pre-existing Node.js HTTP server.
+ *
+ * Thin Node.js wrapper around {@link bootMakaioRuntimeCore}. Creates a
+ * {@link BusServerTransportProvider} from the provided HTTP server, resolves
+ * the bound address via `httpServer.address()`, then delegates all startup
+ * logic to the platform-agnostic core.
+ *
+ * The caller owns the HTTP server and Hono app lifecycle. This function owns
+ * everything from step 1 (Config) through step 12 (Ready) and returns a
+ * {@link MakaioRuntime} handle that the caller uses to shut down.
+ * @param options - Boot configuration including the pre-bound HTTP server.
+ * @returns Runtime handle with `port`, `machineId`, and `shutdown()`.
+ */
+declare function bootMakaioRuntime(options: BootMakaioRuntimeOptions): Promise<MakaioRuntime>;
+//#endregion
+//#region runtimes/node/src/upstream-telemetry.d.ts
+/**
+ * Returned by {@link attachUpstreamTelemetry} after the projected transport is connected
+ * and the bus observer is attached.
+ */
+interface AttachedUpstreamTelemetry {
+  /** Shutdown step that detaches the observer and disconnects the inner transport. */
+  readonly shutdown: ShutdownStep;
+}
+/**
+ * Attach a projected telemetry exporter to a booted runtime bus.
+ *
+ * Observed local messages are projected into sanitized `subject-telemetry.fact`
+ * events and forwarded upstream. The exporter is driven by
+ * {@link IMakaioBus.observeMessages} instead of being registered as a normal
+ * bus transport: upstream telemetry is a collector, not an application message
+ * peer, and must observe local requests that would not otherwise route through
+ * transport dispatch.
+ *
+ * The raw inner transport is never registered directly on the bus.
+ * @param bus - Runtime bus whose namespace registry is used for projection.
+ * @param machineId - Source machine identifier included in telemetry facts.
+ * @param options - Upstream telemetry boot options.
+ * @returns Shutdown hook for boot rollback/shutdown.
+ */
+declare function attachUpstreamTelemetry(bus: IMakaioBus, machineId: string, options: UpstreamTelemetryBootOptions): Promise<AttachedUpstreamTelemetry>;
+//#endregion
+//#region runtimes/node/src/upstream-telemetry-config.d.ts
+/**
+ * Environment surface used by {@link resolveUpstreamTelemetryBootOptionsFromEnv}.
+ */
+interface UpstreamTelemetryEnv {
+  /** WebSocket URL for the upstream collector bus. */
+  readonly MAKAIO_UPSTREAM_URL?: string;
+  /** Optional HMAC secret for the upstream collector bus. */
+  readonly MAKAIO_UPSTREAM_SECRET?: string;
+}
+/**
+ * Transport factory input resolved from upstream telemetry environment.
+ */
+interface UpstreamTelemetryTransportConfig {
+  /** WebSocket URL for the upstream collector bus. */
+  readonly url: string;
+  /** Optional HMAC secret for upstream bus authentication. */
+  readonly secret?: string;
+}
+/**
+ * Options for resolving push embedded upstream telemetry boot configuration.
+ */
+interface ResolveUpstreamTelemetryBootOptionsFromEnvOptions {
+  /** Environment variables to read. Defaults to `process.env`. */
+  readonly env?: UpstreamTelemetryEnv;
+  /** Transport factory override for tests and alternate host transports. */
+  readonly createTransport?: (config: UpstreamTelemetryTransportConfig) => BusTransport;
+}
+/** Environment variable that enables push embedded upstream telemetry. */
+declare const MAKAIO_UPSTREAM_URL_ENV = "MAKAIO_UPSTREAM_URL";
+/** Environment variable carrying the optional HMAC secret for upstream telemetry. */
+declare const MAKAIO_UPSTREAM_SECRET_ENV = "MAKAIO_UPSTREAM_SECRET";
+/**
+ * Create the default upstream telemetry WebSocket transport.
+ * @param config - Resolved upstream telemetry transport configuration.
+ * @returns WebSocket client transport configured for upstream telemetry.
+ */
+declare function createUpstreamTelemetryTransport(config: UpstreamTelemetryTransportConfig): BusTransport;
+/**
+ * Resolve push embedded upstream telemetry boot options from environment.
+ *
+ * `MAKAIO_UPSTREAM_URL` is the activation switch. When it is absent or blank,
+ * no upstream telemetry transport is created. `MAKAIO_UPSTREAM_SECRET` is
+ * optional, but when set it must be non-empty and requires a URL.
+ * @param options - Environment and transport factory overrides.
+ * @returns Boot options for projected upstream telemetry, or `undefined` when disabled.
+ */
+declare function resolveUpstreamTelemetryBootOptionsFromEnv(options?: ResolveUpstreamTelemetryBootOptionsFromEnvOptions): UpstreamTelemetryBootOptions | undefined;
+//#endregion
+//#region runtimes/node/src/node-runtime-options.d.ts
+/**
+ * Node runtime discovery options.
+ *
+ * Narrows the generic boot option shape so Node entrypoints can pass the same
+ * discovery strategy to both CLI command discovery and runtime boot.
+ */
+interface NodeRuntimeOptions extends ConfiguredRuntimeOptions {
+  /**
+   * Extension discovery strategy selected by runtime config.
+   *
+   * Corresponds to {@link CoreBootOptions.discovery}. Node entrypoints use the
+   * same `makaio.config.*` loader path as the CLI, so runtime extension
+   * selection is controlled by explicit config, `MAKAIO_CONFIG_FILE`, or
+   * user-home defaults.
+   */
+  readonly discovery: ExtensionDiscovery;
+  /** Host capability facts for Node.js boot. */
+  readonly hostCapabilities: readonly HostCapabilityDeclaration[];
+}
+/**
+ * Build runtime options for Node.js boot.
+ *
+ * Runtime extension selection is owned by `makaio.config.*`, including the
+ * no-config defaults for installed extension roots. Host capabilities stay out
+ * of runtime config and only express the narrow Node.js environment gate used
+ * by extension `requires`.
+ * @param options - Runtime config lookup options.
+ * @returns Runtime options for Node.js boot.
+ */
+declare function buildNodeRuntimeOptions(options: LoadMakaioConfigOptions): Promise<NodeRuntimeOptions>;
+//#endregion
+//#region runtimes/node/src/initialize-node-database.d.ts
+/**
+ * Options for {@link initializeNodeDatabase}.
+ */
+interface InitializeNodeDatabaseOptions {
+  /** Override database file path. Defaults to MAKAIO_DATABASE_PATH env var, then `<makaioHome>/makaio.db`. */
+  dbPath?: string;
+  /**
+   * Override framework central migrations directory.
+   *
+   * Bundled hosts copy migrations next to their entrypoint and pass that
+   * runtime asset path explicitly because package-local source paths are not
+   * available in the final image.
+   */
+  migrationsDir?: string;
+  /**
+   * Makaio home directory used to derive the default database path.
+   * Superseded by `dbPath` and `MAKAIO_DATABASE_PATH`.
+   */
+  makaioHome: string;
+}
+/**
+ * Result returned by {@link initializeNodeDatabase}.
+ */
+interface InitializeNodeDatabaseResult {
+  databaseClient: DatabaseClient;
+  dbPath: string;
+}
+/**
+ * Initialize SQLite database for Node runtime persistence.
+ *
+ * Supports `MAKAIO_DATABASE_PATH` for test or custom environments.
+ * When `options.dbPath` is provided it takes precedence over the environment
+ * variable, avoiding the need for callers to mutate `process.env`.
+ * @param options - Configuration; see {@link InitializeNodeDatabaseOptions}.
+ * @returns Initialized database client and resolved database path.
+ */
+declare function initializeNodeDatabase(options: InitializeNodeDatabaseOptions): Promise<InitializeNodeDatabaseResult>;
+//#endregion
+//#region runtimes/node/src/bus-server-transport.d.ts
+/**
+ * Configuration options for {@link BusServerTransportProvider}.
+ */
+interface BusServerTransportOptions {
+  /** Pre-existing HTTP server that is already listening. */
+  httpServer: Server;
+  /**
+   * Auth strategy.
+   *
+   * When `undefined` the server runs with no authentication. Pass a
+   * {@link DispatchingAuth} to support hot-swapping E2E auth after machine
+   * identity is loaded.
+   */
+  auth?: TransportAuth$1;
+  /**
+   * Loopback transport registry name for in-process cross-client relay.
+   *
+   * Defaults to `'node'`.
+   */
+  loopbackName?: string;
+}
+/**
+ * Platform-specific bus server transport provider for Node.js.
+ */
+declare class BusServerTransportProvider implements TransportProvider {
+  private readonly options;
+  /** Active bus server instance. Set during connect, cleared on disconnect. */
+  private busServer;
+  /** Active `ws` server instance. Set during connect, cleared on disconnect. */
+  private websocketServer;
+  /** HTTP server that currently owns the active upgrade handler. */
+  private upgradeHandlerServer;
+  /** Active `/bus` upgrade handler attached during connect. */
+  private upgradeHandler;
+  /**
+   * Whether the bus server has completed startup and is accepting connections.
+   * Guards against WebSocket upgrade requests racing with bus startup.
+   */
+  private busReady;
+  /**
+   * Set synchronously at the top of {@link connect} to close the TOCTOU window
+   * between the guard check and the first `await`.
+   */
+  private connecting;
+  /**
+   * @param options - Transport configuration. `httpServer` must already be listening.
+   */
+  constructor(options: BusServerTransportOptions);
+  /**
+   * The {@link DispatchingAuth} instance if the caller passed one.
+   *
+   * Exposed so composition roots that need to hot-swap E2E auth after machine
+   * identity becomes available can call `dispatchingAuth.setE2EAuth(e2eAuth)`.
+   * @returns The {@link DispatchingAuth} instance, or `undefined` when auth was
+   *   not provided or is not a `DispatchingAuth`.
+   */
+  get dispatchingAuth(): DispatchingAuth | undefined;
+  /**
+   * Attach the `/bus` upgrade handler to the HTTP server and start the bus server.
+   * @param bus - Bus instance to attach the transport to.
+   * @param _machineId - Machine identifier (unused; callers provide auth externally).
+   */
+  connect(bus: IMakaioBus, _machineId: string): Promise<void>;
+  /**
+   * Stop the bus server and detach the upgrade wiring.
+   *
+   * The HTTP server and Hono app are owned by the composition root and are not
+   * closed here.
+   */
+  disconnect(): Promise<void>;
+  /**
+   * Stop the bus server and mark the transport as not ready.
+   * @param reason - Context string used in error log messages.
+   */
+  private stopBusServer;
+  /**
+   * Detach the active upgrade handler from the HTTP server.
+   */
+  private detachUpgradeHandler;
+  /**
+   * Close the `ws` server.
+   *
+   * "The server is not running" is silently ignored: the HTTP server closes the
+   * underlying socket when it shuts down first, so `wss.close()` finds it
+   * already gone. This is not an error — it is the expected teardown order in
+   * tests and in production when the HTTP server is closed before disconnect().
+   * @param reason - Context string used in error log messages.
+   */
+  private stopWebSocketServer;
+}
+//#endregion
+//#region runtimes/node/src/credential-provider.d.ts
+/**
+ * Credential provider interface for resolving credential references.
+ *
+ * Implementations are platform-specific (e.g. Node.js keychain, stored refs).
+ */
+interface CredentialProvider {
+  /**
+   * Resolve a credential reference to its runtime value.
+   * @param ref - Credential reference string
+   * @returns Resolved value, or null if unavailable
+   */
+  resolve(ref: CredentialRef): Promise<string | null>;
+}
+/**
+ * Node.js credential provider.
+ *
+ * Resolves env:, file:, and keychain: credential references.
+ */
+declare class NodeCredentialProvider implements CredentialProvider {
+  /**
+   * Resolve a credential reference to its plaintext value.
+   * @param ref - Credential reference (`env:`, `file:`, or `keychain:`)
+   * @returns Resolved credential value, or null when unavailable
+   */
+  resolve(ref: CredentialRef): Promise<string | null>;
+  private resolveKeychain;
+}
+/**
+ * Credential provider that resolves stored refs via credential service.
+ *
+ * Falls back to NodeCredentialProvider for env/file/keychain refs.
+ * Uses a lazy-opened DirectChannel for the channel-only `credential.get` subject.
+ */
+declare class StoredCredentialProvider implements CredentialProvider {
+  private readonly bus;
+  private readonly fallbackProvider;
+  /** Lazily-opened channel to the credentials endpoint. */
+  private channelPromise?;
+  /**
+   * Create a new stored credential provider.
+   * @param bus - Bus instance for credential retrieval
+   */
+  constructor(bus: IMakaioBus);
+  /**
+   * Resolve a credential reference, including stored refs.
+   *
+   * Handles the `stored:providerConfig:<configId>:<key>` format via
+   * `CredentialSubjects.get` over an encrypted DirectChannel. Falls back to
+   * NodeCredentialProvider for env:, file:, and keychain: refs.
+   * @param ref - Credential reference to resolve
+   * @returns Resolved credential value, or null when unavailable
+   */
+  resolve(ref: CredentialRef): Promise<string | null>;
+  /**
+   * Lazily open (and cache) the encrypted channel to the credentials endpoint.
+   *
+   * The promise is cleared on `ChannelClosedError` (post-open channel closure)
+   * and also on open failures so the next call always retries rather than
+   * re-using a permanently-rejected or permanently-closed promise.
+   * @returns The open DirectChannel
+   */
+  private getChannel;
+  /**
+   * Open a fresh encrypted channel to the credentials endpoint.
+   * @returns Newly opened DirectChannel
+   */
+  private openCredentialChannel;
+}
+//#endregion
+//#region runtimes/node/src/read-framework-version.d.ts
+/**
+ * Read the framework version from `@makaio/runtime-node`'s `package.json`.
+ *
+ * Resolves `package.json` relative to the compiled source using
+ * `import.meta.url`, which is always available in ESM. Used as a fallback
+ * when the caller does not pass an explicit `frameworkVersion`.
+ * @returns The `version` field from `package.json`.
+ * @throws If `package.json` cannot be read or has no `version` field.
+ */
+declare function readFrameworkVersion(): Promise<string>;
+//#endregion
+//#region runtimes/node/src/model-registry/file-registry-cache.d.ts
+/**
+ * Options for file-backed registry cache persistence.
+ */
+interface FileRegistryCacheOptions {
+  /**
+   * Persist an ISO timestamp next to the registry payload.
+   *
+   * The read contract still returns only the registry; the timestamp is a
+   * persistence seam for future TTL policy.
+   */
+  readonly trackFetchedAt?: boolean;
+}
+/**
+ * File-based model registry cache for Node.js.
+ *
+ * Persists the model registry as JSON at `<cachePath>`.
+ * Silently returns null on read errors (cache miss) and logs warnings on
+ * write errors (non-fatal, in-memory data still serves requests).
+ */
+declare class FileRegistryCache implements IModelRegistryCache {
+  private readonly cachePath;
+  private readonly trackFetchedAt;
+  /**
+   * Creates a new FileRegistryCache.
+   * @param cachePath - Absolute path to the cache file (e.g. `~/.makaio/cache/model-registry.json`)
+   * @param options - Cache persistence options.
+   */
+  constructor(cachePath: string, options?: FileRegistryCacheOptions);
+  /**
+   * Read cached registry from disk.
+   * @returns Parsed registry or null if file missing or corrupt
+   */
+  get(): Promise<ModelRegistry | null>;
+  /**
+   * Write registry to disk cache.
+   * Creates parent directories if they don't exist.
+   * @param registry - Registry data to persist
+   */
+  set(registry: ModelRegistry): Promise<void>;
+}
+//#endregion
+//#region runtimes/node/src/extension-browser-entry-paths.d.ts
+/**
+ * Build the Rollup input name for a descriptor browser entry.
+ *
+ * Vite appends `.js` through the `[name].js` output pattern, so the input name
+ * intentionally omits the descriptor source extension.
+ * @param extensionName - Descriptor/package name of the extension.
+ * @param browserEntrypoint - Descriptor browser entrypoint path.
+ * @returns Stable Rollup input name for the browser bundle.
+ */
+declare function buildExtensionBrowserRollupInputName(extensionName: string, browserEntrypoint: string): string;
+/**
+ * Build the runtime import URL for a descriptor browser entry.
+ *
+ * Runtime URLs point at the JavaScript asset emitted by Vite, even when the
+ * descriptor points at a TypeScript source entry.
+ * @param extensionName - Descriptor/package name of the extension.
+ * @param browserEntrypoint - Descriptor browser entrypoint path.
+ * @returns Public browser entrypoint URL.
+ */
+declare function buildExtensionBrowserRuntimeEntrypoint(extensionName: string, browserEntrypoint: string): string;
+//#endregion
+//#region runtimes/node/src/bridge-extension-browser-entries.d.ts
+/**
+ * Augment extension packages with browser entry and HTTP serving fields.
+ *
+ * For each loaded package whose descriptor declares `entrypoints.browser`,
+ * adds `browser` (URL entrypoint) and `http` (static file serving) fields.
+ * Skips packages that already declare either field — the server entry author
+ * is assumed to handle their own serving.
+ *
+ * The URL convention is `/extensions/<name>/browser/<entry-stem>.js`.
+ * Static files are served from the directory containing the browser bundle.
+ * @param discovered - The discovered extensions (for descriptor access).
+ * @param packages - Loaded {@link KernelMakaioExtension} array from `loadExtensions`.
+ * @param options - Optional injection overrides for testability.
+ * @returns New array with augmented packages. Input array is not mutated.
+ */
+declare function bridgeExtensionBrowserEntries(discovered: ReadonlyArray<DiscoveredExtension>, packages: ReadonlyArray<KernelMakaioExtension>, options?: BridgeBrowserOptions): KernelMakaioExtension[];
+//#endregion
+//#region runtimes/node/src/find-workspace-root.d.ts
+/**
+ * Error raised when no workspace root exists above the supplied start
+ * directory.
+ */
+declare class WorkspaceRootNotFoundError extends Error {
+  /**
+   * Creates a workspace-root lookup failure.
+   * @param startDir - Directory where the workspace-root search started.
+   */
+  constructor(startDir: string);
+}
+/** Parsed workspace-root metadata from the nearest workspace package.json. */
+interface WorkspaceRootInfo {
+  /** Absolute workspace root directory. */
+  readonly root: string;
+  /** Absolute path to the root package.json that declared workspaces. */
+  readonly packageJsonPath: string;
+  /** Workspace glob entries declared by the root package.json. */
+  readonly workspaces: readonly string[];
+}
+/**
+ * Walk up from `startDir` to find the nearest directory containing a
+ * `package.json` with a `workspaces` field (the workspace root).
+ *
+ * Use {@link findWorkspaceRootInfo} when the caller also needs the parsed
+ * workspace globs; that avoids re-reading the same root package.json.
+ * @param startDir - Directory to start searching from.
+ * @returns Absolute path to the workspace root.
+ * @throws If no workspace root is found before reaching the filesystem root.
+ */
+declare function findWorkspaceRoot(startDir: string): string;
+/**
+ * Walk up from `startDir` and return the nearest workspace root plus its
+ * parsed workspace globs.
+ * @param startDir - Directory to start searching from.
+ * @returns Workspace root metadata.
+ * @throws If no workspace root is found before reaching the filesystem root.
+ */
+declare function findWorkspaceRootInfo(startDir: string): WorkspaceRootInfo;
+//#endregion
+export { type ActivateAdapterRuntimeIdentityInput, type ActivatedAdapterRuntimeIdentity, type AttachedUpstreamTelemetry, type BootCoordinatorSetupContext, type BootMakaioRuntimeOptions, type BridgeBrowserOptions, type BusServerTransportOptions, BusServerTransportProvider, type ConfiguredRuntimeOptions, type CoreBootOptions, type CredentialProvider, type DescriptorSourcePackageGroup, type DiscoveredExtension, ExplicitDescriptorDiscovery, type ExtensionDiscovery, FileConfigStorage, FileRegistryCache, FilesystemDescriptorDiscovery, type FilesystemDescriptorDiscoveryOptions, type FrameworkModuleResolver, type HonoRouteGraph, type HonoRouteGraphOptions, type HttpContributionPhase, type HttpRouteContribution, type HttpRouteGraphBuilder, type IWorkflowRunner, InProcessWorkflowRunner, type InProcessWorkflowRunnerOptions, type InitializeNodeDatabaseOptions, type InitializeNodeDatabaseResult, type LoadExtensionsOptions, type LoadMakaioConfigOptions, type LoadedMakaioConfig, MAKAIO_CONFIG_FILE_ENV, MAKAIO_HOME_ENV, MAKAIO_UPSTREAM_SECRET_ENV, MAKAIO_UPSTREAM_URL_ENV, type MachineKeyStatus, type MachineKeyValidation, type MakaioConfig, type MakaioRuntime, NodeCredentialProvider, NodeFrameworkModuleResolver, type NodeRuntimeOptions, NoopFrameworkModuleResolver, type ParseMakaioConfigOptions, type ParsedMakaioConfig, type PersistedMachineIdentity, type PrepareAdapterRuntimeInput, type PreparedAdapterRuntime, type ResolveUpstreamTelemetryBootOptionsFromEnvOptions, RuntimeSubjects, type ServerTransportProvider, StoredCredentialProvider, ThinWorkflowPiscinaRunner, type ThinWorkflowPiscinaRunnerOptions, type TransportReadyInfo, type UpstreamTelemetryBootOptions, type UpstreamTelemetryEnv, type UpstreamTelemetryTransportConfig, type WorkflowRunResult, type WorkflowRunnerBootOptions, type WorkflowRunnerConfig, type WorkflowWorkerEntryMode, type WorkflowWorkerEntryResolverOptions, type WorkspaceRootInfo, WorkspaceRootNotFoundError, activateAdapterRuntimeIdentity, attachUpstreamTelemetry, bootMakaioRuntime, bootMakaioRuntimeCore, bridgeExtensionBrowserEntries, buildConfiguredRuntimeOptions, buildExtensionBrowserRollupInputName, buildExtensionBrowserRuntimeEntrypoint, buildNodeRuntimeOptions, createHonoRouteGraph, createHttpRouteGraphBuilder, createMakaioConfigDiscovery, createUpstreamTelemetryTransport, defineMakaioConfig, entrypointStem, findWorkspaceRoot, findWorkspaceRootInfo, initializeNodeDatabase, isCliContributionLike, isMakaioExtensionLike, isMissingOptionalRuntimePackage, isWithinDirectory, loadExtensions, loadMakaioConfig, loadOrCreateMachineIdentity, machineKeysExist, normalizeNodeHostCapabilities, parseMakaioConfig, prepareAdapterRuntime, readFrameworkVersion, registerAdapterNameResolver, resolveConventionEntrypoint, resolveFrameworkSpecifier, resolveListeningPort, resolveMakaioConfigPath, resolveMakaioHome, resolveStaticModelRegistryPath, resolveUpstreamTelemetryBootOptionsFromEnv, resolveWorkflowWorkerEntry, runMigrations, selectFrameworkCorePackages, shouldIncludeExtension, tryImport, validateMachineKeys, waitForServerListening };