@makaio/framework 1.0.0-dev-1785409369816 → 1.0.0-dev-1787670071418

package/README.md

@@ -21,6 +21,8 @@ Makaio Framework is runtime infrastructure for AI agent systems. It provides a t
 
 ## Install
 
+Requires Node.js 22.15 or newer.
+
 ```bash
 npm install @makaio/framework
 ```

package/dist/.makaio-build.json

@@ -1,6 +1,7 @@
 {
   "version": 1,
-  "fingerprint": "2a3cce3f4286964d4f4a5fe170e3253ec3ac6bf417f363e82e95db284b563d0f",
-  "builtAt": "2026-07-30T11:04:14.221Z",
-  "declarations": true
+  "fingerprint": "3a1b63b04a47970fe52c665793ebed38936f36bbc0d6972a3fa4bdc07a1fc8e6",
+  "builtAt": "2026-08-25T15:02:19.216Z",
+  "declarations": true,
+  "declarationBackend": "tsc"
 }

package/dist/{account-identity-DFx8pwKL.mjs → account-identity-B3vLwm9O.mjs}

@@ -1 +1 @@
-import{t as e}from"./json-value-DmU8ibo_.mjs";import"./shared-BQ0CHIVy.mjs";import{g as t,h as n,m as r}from"./profile-BTAI31Nt.mjs";import{n as i}from"./version-CoCeMxDT.mjs";import{z as a}from"zod";const o=a.enum([`strong`,`alias`]),s=a.object({scheme:t,value:t,strength:o}),c=a.object({key:t,label:a.string(),usedPercentage:a.number().finite().min(0).max(100),resetsAt:n.optional()}),l=a.object({windows:a.array(c)}),u=a.record(a.string(),a.unknown()).optional(),d=a.object({clientId:t,found:a.boolean(),binaryPath:r.optional(),version:a.string().optional(),warningMessage:a.string().optional()}),f=a.object({clientId:t,binaryName:t,supportedVersions:i.optional()}),p=a.object({clientAccountId:t,clientId:t,observedAt:n,source:t,displayLabel:a.string().optional(),usage:l,metadata:u}),m=a.discriminatedUnion(`kind`,[a.object({kind:a.literal(`session`),sessionId:t}),a.object({kind:a.literal(`adapter-session`),adapterSessionId:t}),a.object({kind:a.literal(`both`),sessionId:t,adapterSessionId:t})]),h=a.object({clientId:a.string(),source:a.string(),kind:a.string(),observedAt:n,payload:e}),g={request:a.object({clientId:t,observedAt:n.optional(),displayLabel:a.string().optional(),identifiers:a.array(s).min(1),metadata:u}),response:a.object({clientAccountId:t,displayLabel:a.string().optional()})},_={request:h.extend({locator:m}),response:a.object({handled:a.boolean(),sessionId:t.nullable(),clientAccountId:t.nullable(),changed:a.boolean()})},v={request:a.object({clientId:t,observedAt:n,source:t,account:a.object({displayLabel:a.string().optional(),identifiers:a.array(s).min(1)}),usage:l,metadata:u}),response:a.object({clientAccountId:t,snapshot:p})};export{u as a,_ as c,p as d,c as f,h as i,m as l,g as n,d as o,l as p,o as r,f as s,s as t,v as u};
+import{n as e}from"./json-value-BBZ6uGwc.mjs";import"./shared-B9AWRm9A.mjs";import{g as t,h as n,m as r}from"./profile-N5qGUpF0.mjs";import{n as i}from"./version-BYeVh1pI.mjs";import{z as a}from"zod";const o=a.enum([`strong`,`alias`]),s=a.object({scheme:t,value:t,strength:o}),c=a.object({key:t,label:a.string(),usedPercentage:a.number().finite().min(0).max(100),resetsAt:n.optional()}),l=a.object({windows:a.array(c)}),u=a.record(a.string(),a.unknown()).optional(),d=a.object({clientId:t,found:a.boolean(),binaryPath:r.optional(),version:a.string().optional(),warningMessage:a.string().optional()}),f=a.object({clientId:t,binaryName:t,supportedVersions:i.optional()}),p=a.object({clientAccountId:t,clientId:t,observedAt:n,source:t,displayLabel:a.string().optional(),usage:l,metadata:u}),m=a.discriminatedUnion(`kind`,[a.object({kind:a.literal(`session`),sessionId:t}),a.object({kind:a.literal(`adapter-session`),adapterSessionId:t}),a.object({kind:a.literal(`both`),sessionId:t,adapterSessionId:t})]),h=a.object({clientId:a.string(),source:a.string(),kind:a.string(),observedAt:n,payload:e}),g={request:a.object({clientId:t,observedAt:n.optional(),displayLabel:a.string().optional(),identifiers:a.array(s).min(1),metadata:u}),response:a.object({clientAccountId:t,displayLabel:a.string().optional()})},_={request:h.extend({locator:m}),response:a.object({handled:a.boolean(),sessionId:t.nullable(),clientAccountId:t.nullable(),changed:a.boolean()})},v={request:a.object({clientId:t,observedAt:n,source:t,account:a.object({displayLabel:a.string().optional(),identifiers:a.array(s).min(1)}),usage:l,metadata:u}),response:a.object({clientAccountId:t,snapshot:p})};export{u as a,_ as c,p as d,c as f,h as i,m as l,g as n,d as o,l as p,o as r,f as s,s as t,v as u};

package/dist/adapter-Dz1fX5Wa.mjs

@@ -0,0 +1 @@
+import{D as e,E as t,T as n,c as r,d as i,f as a,g as o,h as s,k as c,l,m as u,o as d,p as f,s as p,t as m,u as h,v as g,wn as _,y as v}from"./schemas-_2Syo_01.mjs";import"./compression-CtgeVLpP.mjs";import"./provider-context-zTDSH2x9.mjs";import"./contracts/adapter/schemas/session-lineage.mjs";import{createBusNamespace as y}from"@makaio/framework/core";const b={getCapabilities:_,startAgent:c,infer:e,listAgents:t,getAgent:n,stopAgent:v,rehydrateAgent:g,acknowledgeCallerSettlement:o,getConfigSchema:s,"agent.created":u,"session.created":f,"session.discovered":m,"session.usage":a,"session.closed":i,log:h,error:l,initialized:r,deinitialized:p,quota:d},x=y(`adapter`,b),S=x.subjects;export{S as n,b as r,x as t};

package/dist/adapter-subsystem/index.d.mts

@@ -1,17 +1,79 @@
 import { z } from "zod";
 import { IMakaioBus } from "@makaio/framework/bus";
 import * as _$_makaio_contracts0 from "@makaio/framework/contracts";
-import { AdapterClientRef, AdapterProviderDefinitionContract, AdapterProviderRef, MakaioNodeExtension, ProtocolId, ResolvedProviderContext } from "@makaio/framework/contracts";
+import { AdapterClientRef, AdapterProviderDefinitionContract, AdapterProviderRef, ConnectorTeardownResult, MakaioNodeExtension, ProtocolId, ResolvedProviderContext } from "@makaio/framework/contracts";
+import { ContributionProcessor, ExtensionCoordinator, KernelMakaioExtension } from "@makaio/framework/kernel";
 import { BaseService } from "@makaio/framework/service-base";
 import { ClientAuthMethodDefinition, ProviderAuthMethodDefinition, ProviderConfigAuth } from "@makaio/framework/contracts/auth";
 import { AdapterFile, ProviderConfigFile } from "@makaio/framework/contracts/config";
 import { ClientDefinition as ClientDefinition$1 } from "@makaio/framework/contracts/client";
 import { ClientRecord, ProviderRecord } from "@makaio/framework/services/settings/storage";
-import { ContributionProcessor, ExtensionCoordinator } from "@makaio/framework/kernel";
 import { AdapterFileConfigSet, IAdapterConfigRepository, IAdapterConfigRepository as IAdapterConfigRepository$1, ProviderConfigFileSet } from "@makaio/framework/services/adapter-subsystem";
 import { AvailableAdapter, HelpLink } from "@makaio/framework/services/settings";
 import { KernelExtensionContext as KernelExtensionContext$1, KernelMakaioExtension as KernelMakaioExtension$1 } from "@makaio/framework/kernel/extension";
 
+//#region subsystems/adapter/src/adapter-instance-teardown.d.ts
+/** One adapter instance's teardown, named so a caller can act per instance. */
+interface AdapterInstanceTeardownResult extends ConnectorTeardownResult {
+  /** Runtime adapter ID whose instance this result belongs to. */
+  readonly adapterId: string;
+}
+/**
+ * Every instance teardown of one shutdown, plus the class standing for all of them.
+ *
+ * Both halves are carried because they answer different questions: the aggregate
+ * is what a future instance retirement branches on, and the per-instance results
+ * are what a human triaging a weak aggregate needs in order to find the adapter
+ * responsible for it.
+ */
+interface AdapterInstanceShutdownReport extends ConnectorTeardownResult {
+  /** One result per instance that was live, in shutdown order. */
+  readonly results: readonly AdapterInstanceTeardownResult[];
+}
+/**
+ * The failure a close hook that outlived its budget produces.
+ *
+ * A distinct type rather than a message, because the two failures this layer can
+ * see mean different things to whoever reads the report: a hook that **threw**
+ * reported its own failure, a hook that **timed out** reported nothing at all and
+ * may still be running. Both are `unknown`, and a reader that has to tell them
+ * apart should not be parsing prose to do it.
+ */
+declare class AdapterInstanceCloseTimeoutError extends Error {
+  readonly adapterId: string;
+  readonly timeoutMs: number;
+  /**
+   * @param adapterId - Runtime adapter ID whose close hook did not return.
+   * @param timeoutMs - Budget the hook was given.
+   */
+  constructor(adapterId: string, timeoutMs: number);
+}
+/**
+ * Classify one attempted instance close.
+ *
+ * Declared beside the taxonomy it applies rather than inside the shutdown loop, so
+ * the rule stays readable and a second caller cannot restate it differently.
+ * @param adapterId - Runtime adapter ID being closed.
+ * @param failure - Failure the attempt produced, or `undefined` when it returned.
+ * @param hadCloseHook - Whether the instance exposed a close hook at all.
+ * @param reported - Evidence returned directly by the close hook, when available.
+ * @returns The class this attempt proves, with a `detail` for the weak ones.
+ */
+declare function classifyAdapterInstanceClose(adapterId: string, failure: unknown, hadCloseHook: boolean, reported: ConnectorTeardownResult | void): AdapterInstanceTeardownResult;
+/**
+ * Reduce every instance teardown of one shutdown to the report a host publishes.
+ *
+ * Class and joined `detail` come from the contract's
+ * {@link aggregateTeardownResults} — the weakest in the set, `released` for an
+ * empty set — so a shutdown that hosted nothing and one whose adapters all let go
+ * answer the same, which is correct for every consumer of "may this instance be
+ * retired". What this layer adds is the per-instance breakdown the aggregate was
+ * derived from.
+ * @param results - Per-instance results, in shutdown order.
+ * @returns The aggregate class plus the results it was derived from.
+ */
+declare function aggregateAdapterInstanceTeardowns(results: readonly AdapterInstanceTeardownResult[]): AdapterInstanceShutdownReport;
+//#endregion
 //#region subsystems/adapter/src/adapter-runtime-types.d.ts
 /**
  * Minimal log import configuration surface needed by adapter lifecycle utilities.
@@ -76,6 +138,21 @@ interface AdapterInitOptions {
    */
   prepareAuthRuntime?: unknown;
 }
+/**
+ * Runtime identity injected immediately before the adapter factory is called.
+ *
+ * Stored adapter options intentionally exclude these values: the active
+ * authority incarnation changes across runtime lifetimes and must never be
+ * captured in contribution-time configuration.
+ */
+interface AdapterRuntimeInitOptions extends AdapterInitOptions {
+  /** Per-adapter unique identifier assigned by the runtime. */
+  adapterId: string;
+  /** Session-ownership authority incarnation hosting this adapter. */
+  ownerInstanceId: string;
+  /** Stable machine identity hosting this adapter runtime. */
+  machineId: string;
+}
 /**
  * Minimal adapter instance surface returned by the adapter factory.
  *
@@ -85,6 +162,12 @@ interface AdapterInitOptions {
 interface AdapterInstance {
   /** Unique identifier assigned when the adapter instance is created. */
   adapterId?: string;
+  /** Preferred awaitable shutdown hook, which may report actual teardown evidence. */
+  closeAsync?: () => void | ConnectorTeardownResult | Promise<void | ConnectorTeardownResult>;
+  /** Legacy shutdown hook, which may report actual teardown evidence. */
+  shutdown?: () => void | ConnectorTeardownResult | Promise<void | ConnectorTeardownResult>;
+  /** Fire-and-forget compatible shutdown hook, which may report actual teardown evidence. */
+  close?: () => void | ConnectorTeardownResult | Promise<void | ConnectorTeardownResult>;
 }
 /**
  * Provider definition resolved for one loaded adapter.
@@ -113,14 +196,13 @@ interface LoadedAdapter {
   /**
    * Factory function that creates a live adapter instance.
    *
-   * The parameter is typed as `unknown` because the full option shape
-   * (`AIAdapterInitOptions`) lives in the host layer. The core layer
-   * forwards the options object without inspecting it, so the loose type
-   * avoids a contravariant incompatibility at the core/host boundary.
+   * This core-layer runtime shape carries the authority and machine identities
+   * required by every live adapter. Host-specific fields stay opaque where the
+   * core layer does not need to inspect them.
    * @param options - Initialization options forwarded by the runtime
    * @returns Promise resolving to a live adapter instance
    */
-  factory: (options?: unknown) => Promise<AdapterInstance>;
+  factory: (options: AdapterRuntimeInitOptions) => Promise<AdapterInstance>;
   /** Runtime initialization options merged from config and defaults. */
   options: AdapterInitOptions;
   /** Adapter-wide config schema (runtime-only, for adapter-level settings). */
@@ -188,19 +270,25 @@ declare function extractAdapterIdFromPackageName(packageName: string): string;
  */
 declare function toAvailableAdapter(adapter: LoadedAdapter): AvailableAdapter;
 /**
- * Best-effort shutdown of all adapter instances and clear the map.
+ * Shut down all adapter instances, report each one, and clear the map.
+ *
+ * **A timed-out instance is no longer indistinguishable from a clean close**
+ * (Wave 3 R49). Every instance is still attempted and the map is still cleared —
+ * one adapter that will not let go must not keep the others hosted — but the
+ * shutdown now says what it observed per instance and in aggregate, because the
+ * only consumer that could act on it is one that knows whether anything is still
+ * running.
+ *
+ * The instances are closed **concurrently**. They are independent resources and no
+ * consumer of this report depends on the order they let go in, whereas serialising
+ * them meant one adapter that will not let go spent the whole close budget before
+ * the next one was even asked — so a host with several stuck adapters waited a
+ * multiple of a budget it had declared once. Result order still follows the map, so
+ * the per-instance breakdown reads the same as before.
  * @param instances - Mutable map of adapter instances to shut down.
+ * @returns Per-instance results and the class standing for all of them.
  */
-declare function shutdownAdapterInstances(instances: Map<string, AdapterInstance>): Promise<void>;
-/**
- * Initialize the subset of loaded adapters that are enabled in settings.
- * @param bus - Bus instance used for adapter-subsystem requests.
- * @param machineId - Current machine identifier.
- * @param adapters - Loaded adapter definitions to initialize.
- * @param adapterInstances - Mutable instance registry.
- * @param platformDefaults - Platform-provided adapter defaults.
- */
-declare function initializeEnabledAdapters(bus: IMakaioBus, machineId: string, adapters: readonly LoadedAdapter[], adapterInstances: Map<string, AdapterInstance>, platformDefaults: PlatformDefaults): Promise<void>;
+declare function shutdownAdapterInstances(instances: Map<string, AdapterInstance>): Promise<AdapterInstanceShutdownReport>;
 /**
  * Ensure a file-backed adapter config exists for each loaded adapter.
  *
@@ -236,6 +324,8 @@ interface AdapterSubsystemServiceOptions {
    * Stable machine identifier used for deterministic adapter ID derivation.
    */
   readonly machineId: string;
+  /** Resolve the currently active session-ownership authority incarnation. */
+  readonly resolveOwnerInstanceId?: () => string;
   /**
    * Platform-provided defaults forwarded to adapter factories.
    */
@@ -275,6 +365,7 @@ declare class AdapterSubsystemService extends BaseService {
   private readonly contributionProcessor;
   private readonly runtimeSnapshotHandlerPriority;
   private readonly runtimeDefinitionHandlerPriority;
+  private readonly resolveOwnerInstanceId;
   /**
    * Create a new adapter subsystem service.
    * @param options - Service dependencies provided by the package factory.
@@ -296,6 +387,13 @@ declare class AdapterSubsystemService extends BaseService {
   private registerMutationHandlers;
   /**
    * Shut down adapter instances and clear in-memory state on destroy.
+   *
+   * The registry reports what its instance closes actually proved, and this is the
+   * top of that chain: nothing above `onDestroy` can act on the report, so an
+   * unproven shutdown either becomes a log line here or becomes nothing at all.
+   * Recording it is what makes the whole reporting path worth having — a host
+   * whose adapters may still be holding provider connections after teardown is a
+   * fact somebody triaging a stuck process needs, and it is only knowable here.
    */
   protected onDestroy(): Promise<void>;
   /**
@@ -314,6 +412,33 @@ declare class AdapterSubsystemService extends BaseService {
    * @returns Readonly map of adapter ID to live adapter instance.
    */
   getAdapterInstances(): ReadonlyMap<string, AdapterInstance>;
+  /**
+   * Resolve a named adapter to its currently registered local instance ID.
+   * @param adapterName - Adapter driver name.
+   * @returns Live instance ID, or undefined when the adapter is not dispatchable.
+   */
+  resolveLiveAdapterId(adapterName: string): string | undefined;
+  /**
+   * Resolve an exact currently live adapter identity.
+   * @param adapterId - Instance ID to resolve from the live runtime registry.
+   * @returns Exact identity, or `undefined` when no matching instance is live.
+   */
+  resolveLiveAdapterIdentity(adapterId: string): {
+    adapterId: string;
+    adapterName: string;
+    machineId: string;
+    ownerInstanceId: string;
+  } | undefined;
+  /**
+   * Snapshot every currently live adapter identity.
+   * @returns Exact identities for all dispatchable local instances.
+   */
+  getLiveAdapterIdentities(): Array<{
+    adapterId: string;
+    adapterName: string;
+    machineId: string;
+    ownerInstanceId: string;
+  }>;
   /**
    * Return settings-facing available-adapter list derived from loaded adapters.
    * @returns Readonly list of adapter metadata for the settings UI.
@@ -555,6 +680,40 @@ declare class ProviderRuntimeContextError extends Error {
 }
 //#endregion
 //#region subsystems/adapter/src/adapter-subsystem-contribution-factory.d.ts
+/**
+ * Whether a package's contributions are processed by the adapter subsystem.
+ *
+ * The single definition of "adapter-contributing", shared by the processor that
+ * consumes such a package and the ordering helper that has to start the
+ * subsystem before it.
+ * @param pkg - Package manifest to classify.
+ * @returns `true` when the package contributes adapters or providers.
+ */
+declare function contributesToAdapterSubsystem(pkg: KernelMakaioExtension): boolean;
+/**
+ * Declare the adapter subsystem as a dependency of every adapter contributor.
+ *
+ * The contribution processor resolves the subsystem service **eagerly** when a
+ * contributing package activates, so such a package starting first is a hard
+ * failure. That ordering used to hold by accident of the load list, which is not
+ * something a package graph may rest on: any dependency added anywhere can move
+ * the subsystem later, and a contributed adapter is discovered code that cannot
+ * be asked to declare a framework package it never names.
+ *
+ * The composition root that installs the processor is therefore the party that
+ * states the ordering, once, for whatever it loads.
+ *
+ * **No self-dependency guard, deliberately.** The subsystem's own package
+ * declares neither `adapters` nor `providers`, so {@link
+ * contributesToAdapterSubsystem} answers `false` for it and it is returned
+ * untouched — a self-dependency is not something this can produce. A guard here
+ * would be a check against a state the classifier already excludes, and it would
+ * quietly absorb the real defect if the subsystem package ever *did* start
+ * contributing, which is a graph problem that should be loud.
+ * @param packages - Load set to stamp.
+ * @returns The same packages, contributors carrying the subsystem dependency.
+ */
+declare function orderAfterAdapterSubsystem<T extends KernelMakaioExtension>(packages: readonly T[]): T[];
 /**
  * Dependencies for the adapter subsystem contribution processor factory.
  */
@@ -581,7 +740,13 @@ interface AdapterSubsystemContributionProcessorDeps {
 declare function createAdapterSubsystemContributionProcessor(deps: AdapterSubsystemContributionProcessorDeps): ContributionProcessor;
 //#endregion
 //#region subsystems/adapter/src/index.d.ts
-/** Extension token for the adapter subsystem service. */
+/**
+ * Extension token for the adapter subsystem service.
+ *
+ * Built from the name declared alongside the subsystem's bus subjects, so a
+ * framework package that must order itself after this one can name it without
+ * importing the subsystem — which would invert the package layering.
+ */
 declare const AdapterSubsystemToken: _$_makaio_contracts0.ExtensionToken<AdapterSubsystemService>;
 /**
  * Options for creating the adapter subsystem extension package.
@@ -619,9 +784,18 @@ interface CreateAdapterSubsystemPackageOptions {
  * {@link createAdapterSubsystemContributionProcessor} before calling
  * `coordinator.startAll()` to ensure adapter contributions are processed in a
  * stable order.
+ *
+ * It declares the session package as a dependency because an adapter that
+ * starts an agent must be able to reserve provider-session ownership first, and
+ * the session package is what registers that authority. No new package edge is
+ * created — `@makaio/services-core` is already a dependency of this subsystem —
+ * only a declared start order, so a reserving adapter can never come up before
+ * the authority it reserves from. The coordinator tears packages down in
+ * reverse dependency order, which additionally puts adapter teardown before
+ * session teardown.
  * @param options - Package-scoped dependencies including the coordinator.
  * @returns Critical Makaio extension for the adapter subsystem.
  */
 declare function createAdapterSubsystemPackage(options: CreateAdapterSubsystemPackageOptions): MakaioNodeExtension<IMakaioBus>;
 //#endregion
-export { type AdapterInitOptions, type AdapterInstance, type AdapterLogImportConfig, AdapterSubsystemService, AdapterSubsystemToken, CreateAdapterSubsystemPackageOptions, FileAdapterConfigRepository, type IAdapterConfigRepository, type LoadedAdapter, type PlatformDefaults, type ProviderConfigAuthValidationCode, ProviderConfigAuthValidationError, type ProviderConfigDiagnosticCode, ProviderConfigDiagnosticError, ProviderRuntimeContextError, type ProviderRuntimeContextErrorCode, type ValidatedProviderConfigAuth, assertProviderConfigAuthDefinitionsEnabled, createAdapterSubsystemContributionProcessor, createAdapterSubsystemPackage, ensureAdapterConfigs, extractAdapterIdFromPackageName, initializeEnabledAdapters, shutdownAdapterInstances, toAvailableAdapter, validateProviderConfigAuth };
+export { type AdapterInitOptions, type AdapterInstance, AdapterInstanceCloseTimeoutError, type AdapterInstanceShutdownReport, type AdapterInstanceTeardownResult, type AdapterLogImportConfig, AdapterSubsystemService, AdapterSubsystemToken, CreateAdapterSubsystemPackageOptions, FileAdapterConfigRepository, type IAdapterConfigRepository, type LoadedAdapter, type PlatformDefaults, type ProviderConfigAuthValidationCode, ProviderConfigAuthValidationError, type ProviderConfigDiagnosticCode, ProviderConfigDiagnosticError, ProviderRuntimeContextError, type ProviderRuntimeContextErrorCode, type ValidatedProviderConfigAuth, aggregateAdapterInstanceTeardowns, assertProviderConfigAuthDefinitionsEnabled, classifyAdapterInstanceClose, contributesToAdapterSubsystem, createAdapterSubsystemContributionProcessor, createAdapterSubsystemPackage, ensureAdapterConfigs, extractAdapterIdFromPackageName, orderAfterAdapterSubsystem, shutdownAdapterInstances, toAvailableAdapter, validateProviderConfigAuth };