@makaio/framework 1.0.0-dev-1787670559522 → 1.0.0-dev-1788258714339

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,7 +1,7 @@
 {
   "version": 1,
-  "fingerprint": "5bf2f9f10fb074df67c816720aff7008cfd4e010ef6c1ef9a17d38de13deb2a0",
-  "builtAt": "2026-08-25T15:10:23.684Z",
+  "fingerprint": "25ca69d297c0d5b224063509e81806dd8302c105d6d0004126a233f97aa2d635",
+  "builtAt": "2026-09-01T10:32:58.708Z",
   "declarations": true,
   "declarationBackend": "tsc"
 }

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

@@ -1 +1 @@
-import{t as e}from"./json-value-D57aJhVn.mjs";import"./shared-BFVuCDPx.mjs";import{g as t,h as n,m as r}from"./profile-BtznZlq3.mjs";import{n as i}from"./version-BfNnVAGr.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

@@ -12,6 +12,68 @@ import { AdapterFileConfigSet, IAdapterConfigRepository, IAdapterConfigRepositor
 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). */
@@ -157,67 +239,6 @@ interface LoadedAdapter {
   protocol?: ProtocolId;
 }
 //#endregion
-//#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.
- * @returns The class this attempt proves, with a `detail` for the weak ones.
- */
-declare function classifyAdapterInstanceClose(adapterId: string, failure: unknown, hadCloseHook: boolean): 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-lifecycle.d.ts
 /**
  * Platform-provided defaults injected by the runtime host.
@@ -268,15 +289,6 @@ declare function toAvailableAdapter(adapter: LoadedAdapter): AvailableAdapter;
  * @returns Per-instance results and the class standing for all of them.
  */
 declare function shutdownAdapterInstances(instances: Map<string, AdapterInstance>): Promise<AdapterInstanceShutdownReport>;
-/**
- * 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>;
 /**
  * Ensure a file-backed adapter config exists for each loaded adapter.
  *
@@ -312,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.
    */
@@ -351,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.
@@ -397,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.
@@ -756,4 +798,4 @@ interface CreateAdapterSubsystemPackageOptions {
  */
 declare function createAdapterSubsystemPackage(options: CreateAdapterSubsystemPackageOptions): MakaioNodeExtension<IMakaioBus>;
 //#endregion
-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, initializeEnabledAdapters, orderAfterAdapterSubsystem, 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 };