@makaio/framework 1.0.0-dev-1781117225170 → 1.0.0-dev-1781354548379

package/README.md

@@ -67,6 +67,35 @@ Switch `adapterName` and the same code runs against any supported provider.
 | `@makaio/framework/tools` | Tool contract, defineTool(), defineToolset() |
 | `@makaio/framework/testing` | Test helpers, bus fixtures, SQLite harness |
 
+## PostgreSQL Backend
+
+SQLite is the default backend and needs no configuration. To run against PostgreSQL instead, install the `@makaio/storage-pg` engine package in your application and point the runtime at your server:
+
+```bash
+npm install @makaio/storage-pg
+export MAKAIO_DATABASE_URL=postgres://user:password@host:5432/makaio
+```
+
+The node-postgres driver (`pg` ^8.x) is a regular dependency of `@makaio/storage-pg` — neither is listed in this package's dependencies or peer dependencies, so selecting SQLite never pulls in a Postgres driver and SQLite-only installs add nothing extra. The driver is pure JavaScript and runs under both Node.js and Bun.
+
+**Selecting the backend.** The connection target resolves in this order (empty and whitespace-only values count as unset):
+
+1. The `database.url` boot option
+2. The `MAKAIO_DATABASE_URL` environment variable
+3. The `dbPath` option of direct `initializeNodeDatabase` callers (SQLite file path)
+4. The `MAKAIO_DATABASE_PATH` environment variable (SQLite file path)
+5. `<makaioHome>/makaio.db` (SQLite default)
+
+A `postgres://` or `postgresql://` URL from the first two sources selects PostgreSQL — Node and Bun runtime hosts recognize the scheme and auto-register the installed `@makaio/storage-pg` engine before any database client is created (the `database.engines` boot option stays the explicit registration path). Any other URL scheme there is rejected with an error rather than falling through to SQLite. The connection pool defaults to 4 connections; tune it with the `database.poolMax` boot option.
+
+**Migrations.** The package bundles only the SQLite migration chain (`dist/drizzle/`); the Postgres chain ships inside `@makaio/storage-pg` and is resolved through its storage engine. Boot applies the chain matching the selected backend automatically. Concurrent boots against the same Postgres database are safe — migration runs are serialized with a transaction-scoped advisory lock.
+
+**Full-text search** works on both backends through the same contracts: FTS5 on SQLite, `tsvector` on Postgres (web-search query syntax via `websearch_to_tsquery`). Relevance scores are positive on both backends but not comparable across them.
+
+**Supported version.** CI runs the storage conformance suite against PostgreSQL 18 (`postgres:18-alpine`); use 18 or newer.
+
+**Switching an existing SQLite install.** Install `@makaio/storage-pg` and set `MAKAIO_DATABASE_URL`; delete any custom `dbPath` wiring (a URL outranks it, so leftover path configuration is inert). Data is not migrated across backends — the Postgres database starts empty.
+
 ## Documentation
 
 - [Getting Started](https://github.com/makaio-ai/makaio-framework/blob/main/docs/getting-started.md)

package/dist/.makaio-build.json

@@ -1,5 +1,5 @@
 {
   "version": 1,
-  "fingerprint": "56ee29aab6bc81d4f32667315bdded805adbfb4cffa15b855a7edc5aa5ba7ec1",
-  "builtAt": "2026-06-10T18:48:14.941Z"
+  "fingerprint": "00c7f9131f71c9d21fdf94dcf209e3da95bcc7e2a860520e0dd206e990ecc031",
+  "builtAt": "2026-06-13T12:43:27.094Z"
 }

package/dist/adapter-UpcpZDOv.mjs

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

package/dist/adapters/config/index.d.mts

@@ -1,4 +1,4 @@
-import { g as BaseAgentConnectorConfig } from "../../types-0u6hpELc.mjs";
+import { g as BaseAgentConnectorConfig } from "../../types-D6jnDjP2.mjs";
 import { z } from "zod";
 import { IMakaioBus, MakaioBusContext } from "@makaio/framework/bus";
 import { AIModelSchema, ProtocolId, ProviderContext } from "@makaio/framework/contracts";

package/dist/adapters/config/index.mjs

@@ -1 +1 @@
-import{t as e}from"../../cleanEnvForAdapter-BlpmyXYk.mjs";import{z as t}from"zod";import n from"node:fs/promises";import{createBusInstance as r,openChannel as i}from"@makaio/framework/bus";import{AIModelSchema as a,CredentialSubjects as o}from"@makaio/framework/contracts";import{BaseAdapterConfigSchema as s,ProviderConfigSchema as c,ProviderDefaultsSchema as l}from"@makaio/framework/contracts/config";import{ProviderStorageSubjects as u}from"@makaio/framework/services/settings/storage";import{resolveTimeouts as d}from"@makaio/framework/utils";import{AdapterSubsystemSubjects as f}from"@makaio/framework/services/adapter-subsystem";import{resolveClientBinary as p}from"@makaio/framework/clients";async function m(e,t={}){if(e.startsWith(`env:`)){let n=e.slice(4);if(!n)throw Error(`Credential reference is missing environment variable name`);return(t.readEnv??(e=>process.env[e]))(n)||null}if(e.startsWith(`file:`)){let r=e.slice(5);if(!r)throw Error(`Credential reference is missing file path`);return(await(t.readFile??(async e=>await n.readFile(e,`utf-8`)))(r)).trim()||null}if(e.startsWith(`keychain:`)){let[n,...r]=e.slice(9).split(`:`);if(!n||r.length===0)throw Error(`Credential reference is missing keychain service or account`);if(!t.resolveKeychain)throw Error(`Keychain credential resolution is not configured`);return t.resolveKeychain(n,r.join(`:`))}return e||null}function h(e,t){let n=e.find(e=>e.id===t);if(!n)throw Error(`Provider definition not found: '${t}'`);if(!g(n))throw Error(`Provider definition '${t}' is missing a defaultModel`);return n}function g(e){return typeof e.defaultModel==`string`&&e.defaultModel.length>0}const _=t.record(t.string(),t.unknown());function v(e){return{getDefaults:()=>e().adapterDefaults,getConfig:async t=>{let{adapterName:n,adapterDefaults:r,adapterDefinition:i,protocol:a}=e(),{providerContext:o}=t,s=o.endpointOverrides?.[a]??null,c=d([{layer:`adapter`,source:n,config:i.defaultTimeouts},{layer:`runtime`,source:`config.ts`,config:t.runtimeTimeouts}]),l={...r.providerConfig,...t.providerConfig,baseUrl:s??t.providerConfig?.baseUrl??r.providerConfig?.baseUrl},u=t.model??r.model;if(!u)throw Error(`No model resolved for adapter "${n}" (agentId: ${t.agentId}). Provide a model explicitly or configure adapterDefaults.model.`);return{...r,...t,adapterName:t.adapterName,model:u,cwd:t.cwd??r.cwd??process.cwd(),timeouts:c,providerConfig:l}}}}async function y(e,t){let n=Object.entries(t);if(n.length===0)return{};let a={},s=e.getContext(),{token:c}=await r({context:s}).request(o.getChannelToken,{}),l=await i(s,`credentials`,{token:c,transports:[]});try{let e=await Promise.allSettled(n.map(([,e])=>l.request(o.resolve,{ref:e})));for(let t=0;t<n.length;t++){let[r,i]=n[t],o=e[t];if(o.status===`fulfilled`)if(o.value.value!==null)a[r]=o.value.value;else if(o.value.error){let e=JSON.stringify(i);console.warn(`[resolveConnectorCredentials] Failed to resolve field '${r}' (ref ${e}):`,o.value.error)}else{let e=JSON.stringify(i);console.info(`[resolveConnectorCredentials] Credential unavailable for field '${r}' (ref ${e}); omitting it from the resolved connector credentials.`)}else{let e=JSON.stringify(i);console.warn(`[resolveConnectorCredentials] Failed to resolve field '${r}' (ref ${e}):`,o.reason)}}}finally{l.close()}return a}async function b(e,t,n){let{config:r}=await e.request(f.getProviderConfig,{id:t});if(!r)throw Error(`ProviderConfig '${t}' not found`);let{context:i}=await e.request(f.buildProviderContext,{providerConfigId:t});if(!i)throw Error(`ProviderConfig '${t}' not found`);if(i.definitionId!==r.definitionId)throw Error(`ProviderConfig '${t}' changed during resolution; retry`);let{provider:a}=await e.request(u.get,{id:i.definitionId});if(!a)throw Error(`ProviderDefinition '${r.definitionId}' not found for config '${t}'`);return{config:r,definition:a,baseUrl:i.endpointOverrides?.[n]??a.endpoints?.[n]??null,credentials:await y(e,i.credentialRefs)}}async function x(e,t,n){let{baseUrl:r,credentials:i}=await b(e,t,n);if(!r)throw Error(`Could not resolve baseUrl for ProviderConfig '${t}' with protocol '${n}'. Ensure the provider definition or config override declares an endpoint for this protocol.`);let a=i.apiKey;if(!a)throw Error(`Could not resolve apiKey for ProviderConfig '${t}'. Store credentials via settings before using this provider.`);return{baseUrl:r,apiKey:a}}function S(e,t){if(!t)return{};let n={};for(let[r,i]of Object.entries(t)){let t=e[r];t!==void 0&&(n[i]=t)}return n}async function C(t){let{bus:n,providerContext:r,clientId:i,baseEnv:a={}}=t,o=await y(n,r?.credentialRefs??{}),s=S(o,r?.credentialEnvVars),c=await p(i);return{credentials:o,credEnv:s,resolvedBinary:c,spawnEnv:{...e(a,{omitEnvVars:r?.ambientCredentialEnvVars}),...s,...c?.env??{}}}}export{a as AIModelSchema,s as BaseAdapterConfigSchema,_ as BaseProviderConfigSchema,c as ProviderConfigSchema,l as ProviderDefaultsSchema,S as buildCredentialEnv,v as createAdapterConfigFactory,h as getDefinitionOrThrow,y as resolveConnectorCredentials,m as resolveCredentialRef,x as resolveProviderEndpoint,b as resolveProviderResolution,C as resolveSessionEnvironment};
+import{t as e}from"../../cleanEnvForAdapter-vZfPGi0X.mjs";import{z as t}from"zod";import n from"node:fs/promises";import{createBusInstance as r,openChannel as i}from"@makaio/framework/bus";import{AIModelSchema as a,CredentialSubjects as o}from"@makaio/framework/contracts";import{BaseAdapterConfigSchema as s,ProviderConfigSchema as c,ProviderDefaultsSchema as l}from"@makaio/framework/contracts/config";import{ProviderStorageSubjects as u}from"@makaio/framework/services/settings/storage";import{resolveTimeouts as d}from"@makaio/framework/utils";import{AdapterSubsystemSubjects as f}from"@makaio/framework/services/adapter-subsystem";import{resolveClientBinary as p}from"@makaio/framework/clients";async function m(e,t={}){if(e.startsWith(`env:`)){let n=e.slice(4);if(!n)throw Error(`Credential reference is missing environment variable name`);return(t.readEnv??(e=>process.env[e]))(n)||null}if(e.startsWith(`file:`)){let r=e.slice(5);if(!r)throw Error(`Credential reference is missing file path`);return(await(t.readFile??(async e=>await n.readFile(e,`utf-8`)))(r)).trim()||null}if(e.startsWith(`keychain:`)){let[n,...r]=e.slice(9).split(`:`);if(!n||r.length===0)throw Error(`Credential reference is missing keychain service or account`);if(!t.resolveKeychain)throw Error(`Keychain credential resolution is not configured`);return t.resolveKeychain(n,r.join(`:`))}return e||null}function h(e,t){let n=e.find(e=>e.id===t);if(!n)throw Error(`Provider definition not found: '${t}'`);if(!g(n))throw Error(`Provider definition '${t}' is missing a defaultModel`);return n}function g(e){return typeof e.defaultModel==`string`&&e.defaultModel.length>0}const _=t.record(t.string(),t.unknown());function v(e){return{getDefaults:()=>e().adapterDefaults,getConfig:async t=>{let{adapterName:n,adapterDefaults:r,adapterDefinition:i,protocol:a}=e(),{providerContext:o}=t,s=o.endpointOverrides?.[a]??null,c=d([{layer:`adapter`,source:n,config:i.defaultTimeouts},{layer:`runtime`,source:`config.ts`,config:t.runtimeTimeouts}]),l={...r.providerConfig,...t.providerConfig,baseUrl:s??t.providerConfig?.baseUrl??r.providerConfig?.baseUrl},u=t.model??r.model;if(!u)throw Error(`No model resolved for adapter "${n}" (agentId: ${t.agentId}). Provide a model explicitly or configure adapterDefaults.model.`);return{...r,...t,adapterName:t.adapterName,model:u,cwd:t.cwd??r.cwd??process.cwd(),timeouts:c,providerConfig:l}}}}async function y(e,t){let n=Object.entries(t);if(n.length===0)return{};let a={},s=e.getContext(),{token:c}=await r({context:s}).request(o.getChannelToken,{}),l=await i(s,`credentials`,{token:c,transports:[]});try{let e=await Promise.allSettled(n.map(([,e])=>l.request(o.resolve,{ref:e})));for(let t=0;t<n.length;t++){let[r,i]=n[t],o=e[t];if(o.status===`fulfilled`)if(o.value.value!==null)a[r]=o.value.value;else if(o.value.error){let e=JSON.stringify(i);console.warn(`[resolveConnectorCredentials] Failed to resolve field '${r}' (ref ${e}):`,o.value.error)}else{let e=JSON.stringify(i);console.info(`[resolveConnectorCredentials] Credential unavailable for field '${r}' (ref ${e}); omitting it from the resolved connector credentials.`)}else{let e=JSON.stringify(i);console.warn(`[resolveConnectorCredentials] Failed to resolve field '${r}' (ref ${e}):`,o.reason)}}}finally{l.close()}return a}async function b(e,t,n){let{config:r}=await e.request(f.getProviderConfig,{id:t});if(!r)throw Error(`ProviderConfig '${t}' not found`);let{context:i}=await e.request(f.buildProviderContext,{providerConfigId:t});if(!i)throw Error(`ProviderConfig '${t}' not found`);if(i.definitionId!==r.definitionId)throw Error(`ProviderConfig '${t}' changed during resolution; retry`);let{provider:a}=await e.request(u.get,{id:i.definitionId});if(!a)throw Error(`ProviderDefinition '${r.definitionId}' not found for config '${t}'`);return{config:r,definition:a,baseUrl:i.endpointOverrides?.[n]??a.endpoints?.[n]??null,credentials:await y(e,i.credentialRefs)}}async function x(e,t,n){let{baseUrl:r,credentials:i}=await b(e,t,n);if(!r)throw Error(`Could not resolve baseUrl for ProviderConfig '${t}' with protocol '${n}'. Ensure the provider definition or config override declares an endpoint for this protocol.`);let a=i.apiKey;if(!a)throw Error(`Could not resolve apiKey for ProviderConfig '${t}'. Store credentials via settings before using this provider.`);return{baseUrl:r,apiKey:a}}function S(e,t){if(!t)return{};let n={};for(let[r,i]of Object.entries(t)){let t=e[r];t!==void 0&&(n[i]=t)}return n}async function C(t){let{bus:n,providerContext:r,clientId:i,baseEnv:a={}}=t,o=await y(n,r?.credentialRefs??{}),s=S(o,r?.credentialEnvVars),c=await p(i);return{credentials:o,credEnv:s,resolvedBinary:c,spawnEnv:{...e(a,{omitEnvVars:r?.ambientCredentialEnvVars}),...s,...c?.env??{}}}}export{a as AIModelSchema,s as BaseAdapterConfigSchema,_ as BaseProviderConfigSchema,c as ProviderConfigSchema,l as ProviderDefaultsSchema,S as buildCredentialEnv,v as createAdapterConfigFactory,h as getDefinitionOrThrow,y as resolveConnectorCredentials,m as resolveCredentialRef,x as resolveProviderEndpoint,b as resolveProviderResolution,C as resolveSessionEnvironment};

package/dist/adapters/index.d.mts

@@ -1,5 +1,5 @@
-import { A as MessageHandle, B as ReasoningLevelMap, C as SendMessageRequestPayload, D as IAdapterConfigFactory, E as ConfigFactoryInput, F as MessageState, H as LedgerSessionContext, I as ProcessingState, L as SendMessageOptions, M as NormalizedMessageInput, N as normalizeMessageInput, O as AIAgentConnector, P as MessageResult, R as AIModel, S as NormalizedCallUsage, T as StartAgentOptions, U as SessionToolLedger, V as ISessionToolLedger, W as ToolLedgerEntry, _ as ConnectorSendMessageOptions, a as AgentCwdChangeRequestPayload, b as ExecutionContext, c as AgentInterruptRequestPayload, d as AgentMcpServersSetResponsePayload, f as AgentModelChangeRequestPayload, g as BaseAgentConnectorConfig, h as AgentStartResult, i as AgentCredentialChangeResponsePayload, j as markCompletedWithFinalResult, k as MessageDeliveryMode, l as AgentInterruptResponsePayload, m as AgentSendMessageOptions, n as AgentContext, o as AgentCwdChangeResponsePayload, p as AgentModelChangeResponsePayload, r as AgentCredentialChangeRequestPayload, s as AgentIdentity, t as AIAgentConfig, u as AgentMcpServersSetRequestPayload, v as ConnectorStartOptions, w as SendMessageResponsePayload, x as GetCapabilitiesResponsePayload, y as ContextWindowInput, z as AIReasoningLevel } from "../types-0u6hpELc.mjs";
-import { _ as LogImporterConfig, a as CompactionMetadata, b as StorageMessagePayload, c as ExternalToolIdentifiers, d as ImportMetadata, f as ImportSegment, g as LogImporter, h as LogImportTestConfig, l as ExternalToolMeta, m as LogImportSessionContext, n as LogOrchestratorConfig, o as DiscoveryMetadata, p as ImportSegmentLineage, r as ParseFileResult, s as ExternalToolIdentifier, u as ImportCursorPosition, v as NormalizedEvent, x as toImportSegment, y as ProcessLogFileResult } from "../base-orchestrator-D-S9v5VY.mjs";
+import { A as MessageHandle, B as ReasoningLevelMap, C as SendMessageRequestPayload, D as IAdapterConfigFactory, E as ConfigFactoryInput, F as MessageState, H as LedgerSessionContext, I as ProcessingState, L as SendMessageOptions, M as NormalizedMessageInput, N as normalizeMessageInput, O as AIAgentConnector, P as MessageResult, R as AIModel, S as NormalizedCallUsage, T as StartAgentOptions, U as SessionToolLedger, V as ISessionToolLedger, W as ToolLedgerEntry, _ as ConnectorSendMessageOptions, a as AgentCwdChangeRequestPayload, b as ExecutionContext, c as AgentInterruptRequestPayload, d as AgentMcpServersSetResponsePayload, f as AgentModelChangeRequestPayload, g as BaseAgentConnectorConfig, h as AgentStartResult, i as AgentCredentialChangeResponsePayload, j as markCompletedWithFinalResult, k as MessageDeliveryMode, l as AgentInterruptResponsePayload, m as AgentSendMessageOptions, n as AgentContext, o as AgentCwdChangeResponsePayload, p as AgentModelChangeResponsePayload, r as AgentCredentialChangeRequestPayload, s as AgentIdentity, t as AIAgentConfig, u as AgentMcpServersSetRequestPayload, v as ConnectorStartOptions, w as SendMessageResponsePayload, x as GetCapabilitiesResponsePayload, y as ContextWindowInput, z as AIReasoningLevel } from "../types-D6jnDjP2.mjs";
+import { _ as LogImporterConfig, a as CompactionMetadata, b as StorageMessagePayload, c as ExternalToolIdentifiers, d as ImportMetadata, f as ImportSegment, g as LogImporter, h as LogImportTestConfig, l as ExternalToolMeta, m as LogImportSessionContext, n as LogOrchestratorConfig, o as DiscoveryMetadata, p as ImportSegmentLineage, r as ParseFileResult, s as ExternalToolIdentifier, u as ImportCursorPosition, v as NormalizedEvent, x as toImportSegment, y as ProcessLogFileResult } from "../base-orchestrator-M5mAB5-w.mjs";
 import { z } from "zod";
 import * as _$_makaio_core0 from "@makaio/framework/core";
 import { CreateBusNamespaceOptions, ExtractSubjectPayload, FilterablePayloadIntersection, HandlerForSubjectDefinition, RequestContext, SchemaRecord, ScopedSubjectDefinition, SubjectDefinition, SubjectRecordFromSchemaRecord } from "@makaio/framework/core";
@@ -1922,6 +1922,8 @@ declare abstract class AIAgent<TBus extends ScopedBus<string> = ScopedBus<string
     cwd: string;
     model: string;
     providerContext: ProviderContext;
+    adapterSessionId: string;
+    resumeAdapterSessionId: string;
     mcpSessionContext: McpRuntimeSessionContext | McpSessionContext | LedgerSessionContext;
   }>): Promise<void>;
   /**
@@ -2340,8 +2342,9 @@ type StartAgentRequestPayload = ExtractSubjectPayload<typeof AdapterSubjects.sta
  * through complex union schemas. Using the canonical TypeScript type preserves
  * the brand and ensures `resolveConnectorCredentials()` receives the correct type.
  */
-type AgentCreationOptions = Omit<Partial<Pick<StartAgentRequestPayload, 'model' | 'cwd' | 'env' | 'allowedTools' | 'disallowedTools' | 'reasoningEffort' | 'mode' | 'mcpSessionContext' | 'harnessId' | 'clientId' | 'clientProfileName' | 'providerContext' | 'ephemeral'>>, 'providerContext'> & {
-  adapterSessionId?: string; /** Unresolved provider context (credential refs, not plaintext). */
+type AgentCreationOptions = Omit<Partial<Pick<StartAgentRequestPayload, 'model' | 'cwd' | 'env' | 'allowedTools' | 'disallowedTools' | 'allowedDirectories' | 'reasoningEffort' | 'adapterConfig' | 'mode' | 'mcpSessionContext' | 'harnessId' | 'clientId' | 'clientProfileName' | 'providerContext' | 'ephemeral'>>, 'providerContext'> & {
+  adapterSessionId?: string;
+  resumeAdapterSessionId?: string; /** Unresolved provider context (credential refs, not plaintext). */
   providerContext?: ProviderContext;
 };
 /**
@@ -2433,6 +2436,7 @@ interface AgentConnectorLifecycleManagerConfig<TBus extends ScopedBus<string>, T
     model: string;
     providerContext: ProviderContext;
     adapterSessionId: string;
+    resumeAdapterSessionId: string;
     mcpSessionContext: McpRuntimeSessionContext | McpSessionContext | LedgerSessionContext;
   }>) => ConfigFactoryInput<TBus>;
   /** Adapter config factory from AIAgent config. */
@@ -2492,6 +2496,8 @@ declare class AgentConnectorLifecycleManager<TBus extends ScopedBus<string>, TCo
     cwd: string;
     model: string;
     providerContext: ProviderContext;
+    adapterSessionId: string;
+    resumeAdapterSessionId: string;
     mcpSessionContext: McpRuntimeSessionContext | McpSessionContext | LedgerSessionContext;
   }>): Promise<void>;
 }
@@ -2667,6 +2673,8 @@ interface AgentRuntimeConnectorOverrides {
   cwd: string;
   model: string;
   providerContext: ProviderContext;
+  adapterSessionId: string;
+  resumeAdapterSessionId: string;
   mcpSessionContext: McpRuntimeSessionContext | McpSessionContext | LedgerSessionContext;
 }
 /** Dependencies for runtime mutation handling. */
@@ -3993,8 +4001,8 @@ interface TurnTrackerSerializedState {
 declare const TurnTrackerSerializedStateSchema: z.ZodDefault<z.ZodObject<{
   sessions: z.ZodRecord<z.ZodString, z.ZodObject<{
     state: z.ZodEnum<{
-      active: "active";
       idle: "idle";
+      active: "active";
     }>;
     currentTurnId: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>>;