@slopus/happy-agent-base 0.0.2 → 0.0.3

package/dist/AgentProviders.js

@@ -1,27 +1,30 @@
 /**
- * Mutable registry of happy-providers instances keyed by a caller-supplied provider ID, so the
- * same provider class can be registered under several IDs (for example per credential). Each
- * entry carries its compatibility type, which decides how far a model change can go before the
- * conversation must reset. Providers can be added and removed while the process runs; lookups
- * return the live reference or null when absent.
+ * Mutable registry of model-aware provider sources keyed by caller-supplied IDs. Each entry carries
+ * its compatibility type, which decides how far a model change can go before the conversation
+ * must reset.
  */
 export class AgentProviders {
-    /** Registered providers keyed by their caller-supplied ID, alongside their compatibility type. */
+    /** Registered provider sources keyed by their caller-supplied ID and compatibility type. */
     #providers = new Map();
-    /** Register a provider under `id`. Throws if that ID is already registered. */
-    add(id, provider, type) {
+    /** Register a provider source under `id`. Throws if that ID is already registered. */
+    add(id, source, type) {
         if (this.#providers.has(id)) {
             throw new Error(`Provider "${id}" is already registered.`);
         }
-        this.#providers.set(id, { provider, type });
+        this.#providers.set(id, { source, type });
     }
     /** Unregister the provider at `id`. Returns whether one was actually removed. */
     remove(id) {
         return this.#providers.delete(id);
     }
-    /** The live provider instance registered at `id`, or null when none is registered. */
-    get(id) {
-        return this.#providers.get(id)?.provider ?? null;
+    /** Resolve the provider suitable for `model`, or null when `id` is not registered. */
+    async resolve(id, model) {
+        const entry = this.#providers.get(id);
+        if (entry === undefined)
+            return null;
+        return typeof entry.source === "function"
+            ? await entry.source({ id, model })
+            : entry.source;
     }
     /** The compatibility type the provider at `id` was registered with, or null when absent. */
     typeOf(id) {

package/dist/AgentProviders.js.map

@@ -1 +1 @@
-{"version":3,"file":"AgentProviders.js","sourceRoot":"","sources":["../sources/AgentProviders.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IACvB,kGAAkG;IACzF,UAAU,GAAG,IAAI,GAAG,EAG1B,CAAC;IAEJ,+EAA+E;IAC/E,GAAG,CAAC,EAAU,EAAE,QAAsB,EAAE,IAAoC;QACxE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,aAAa,EAAE,0BAA0B,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,iFAAiF;IACjF,MAAM,CAAC,EAAU;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,sFAAsF;IACtF,GAAG,CAAC,EAAU;QACV,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,QAAQ,IAAI,IAAI,CAAC;IACrD,CAAC;IAED,4FAA4F;IAC5F,MAAM,CAAC,EAAU;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;IACjD,CAAC;IAED,8CAA8C;IAC9C,IAAI,GAAG;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;CACJ"}
+{"version":3,"file":"AgentProviders.js","sourceRoot":"","sources":["../sources/AgentProviders.ts"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH,MAAM,OAAO,cAAc;IACvB,4FAA4F;IACnF,UAAU,GAAG,IAAI,GAAG,EAG1B,CAAC;IAEJ,sFAAsF;IACtF,GAAG,CAAC,EAAU,EAAE,MAA2B,EAAE,IAAoC;QAC7E,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,aAAa,EAAE,0BAA0B,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,iFAAiF;IACjF,MAAM,CAAC,EAAU;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,sFAAsF;IACtF,KAAK,CAAC,OAAO,CAAC,EAAU,EAAE,KAAyB;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACrC,OAAO,OAAO,KAAK,CAAC,MAAM,KAAK,UAAU;YACrC,CAAC,CAAC,MAAM,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;YACnC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,4FAA4F;IAC5F,MAAM,CAAC,EAAU;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;IACjD,CAAC;IAED,8CAA8C;IAC9C,IAAI,GAAG;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;CACJ"}

package/dist/AgentStorage.d.ts

@@ -1,7 +1,21 @@
+import type { Context } from "@steve.kite/stdlib";
 import type { AgentKV } from "./AgentKV.js";
 import type { AgentPersistence } from "./AgentPersistence.js";
+/**
+ * The exclusive ownership of one durable agent store. The storage adapter must back this with
+ * the database's hard process-level lock rather than an in-memory convention.
+ */
+export interface AgentStorageLock {
+    /** Release the hard lock after the owning AgentSystem has stopped every agent. */
+    release(ctx: Context): Promise<void>;
+}
 /** What an `AgentStorage` is built from. */
 export interface AgentStorageOptions {
+    /**
+     * Acquire exclusive ownership of the whole store. This must fail while any other process or
+     * AgentSystem owns the same durable store.
+     */
+    readonly acquireLock: (ctx: Context) => Promise<AgentStorageLock>;
     /** Shared key-value storage used for state spanning all agents. */
     readonly kv: AgentKV;
     /** Produce the isolated persistence used by one agent. */
@@ -13,6 +27,12 @@ export declare class AgentStorage {
     /** Shared key-value storage used for state spanning all agents. */
     readonly kv: AgentKV;
     constructor(options: AgentStorageOptions);
+    /**
+     * Acquire exclusive ownership until the returned lock is released. The adapter's lock
+     * enforces this across processes; the local guard also rejects accidental reuse of this
+     * object.
+     */
+    acquireLock(ctx: Context): Promise<AgentStorageLock>;
     /** The isolated persistence for the given agent. */
     persistence(agentId: string): AgentPersistence;
 }

package/dist/AgentStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentStorage.d.ts","sourceRoot":"","sources":["../sources/AgentStorage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAChC,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,gBAAgB,CAAC;CAC/D;AAED,gEAAgE;AAChE,qBAAa,YAAY;;IACrB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IAIrB,YAAY,OAAO,EAAE,mBAAmB,EAGvC;IAED,oDAAoD;IACpD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAE7C;CACJ"}
+{"version":3,"file":"AgentStorage.d.ts","sourceRoot":"","sources":["../sources/AgentStorage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,kFAAkF;IAClF,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAClE,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,gBAAgB,CAAC;CAC/D;AAED,gEAAgE;AAChE,qBAAa,YAAY;;IACrB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IAQrB,YAAY,OAAO,EAAE,mBAAmB,EAIvC;IAED;;;;OAIG;IACG,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAmBzD;IAED,oDAAoD;IACpD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAE7C;CACJ"}

package/dist/AgentStorage.js

@@ -2,12 +2,45 @@
 export class AgentStorage {
     /** Shared key-value storage used for state spanning all agents. */
     kv;
+    /** Acquires the database-backed exclusive lock for this store. */
+    #acquireLock;
     /** Produces the isolated persistence used by one agent. */
     #persistence;
+    /** Prevents two systems from sharing even one AgentStorage instance. */
+    #owned = false;
     constructor(options) {
         this.kv = options.kv;
+        this.#acquireLock = options.acquireLock;
         this.#persistence = options.persistence;
     }
+    /**
+     * Acquire exclusive ownership until the returned lock is released. The adapter's lock
+     * enforces this across processes; the local guard also rejects accidental reuse of this
+     * object.
+     */
+    async acquireLock(ctx) {
+        if (this.#owned)
+            throw new Error("The agent store is already owned by another system.");
+        this.#owned = true;
+        let lock;
+        try {
+            lock = await this.#acquireLock(ctx);
+        }
+        catch (error) {
+            this.#owned = false;
+            throw error;
+        }
+        let released = false;
+        return {
+            release: async (releaseCtx) => {
+                if (released)
+                    return;
+                await lock.release(releaseCtx);
+                released = true;
+                this.#owned = false;
+            },
+        };
+    }
     /** The isolated persistence for the given agent. */
     persistence(agentId) {
         return this.#persistence(agentId);

package/dist/AgentStorage.js.map

@@ -1 +1 @@
-{"version":3,"file":"AgentStorage.js","sourceRoot":"","sources":["../sources/AgentStorage.ts"],"names":[],"mappings":"AAWA,gEAAgE;AAChE,MAAM,OAAO,YAAY;IACrB,mEAAmE;IAC1D,EAAE,CAAU;IACrB,2DAA2D;IAClD,YAAY,CAAwC;IAE7D,YAAY,OAA4B;QACpC,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC;QACrB,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAC5C,CAAC;IAED,oDAAoD;IACpD,WAAW,CAAC,OAAe;QACvB,OAAO,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;CACJ"}
+{"version":3,"file":"AgentStorage.js","sourceRoot":"","sources":["../sources/AgentStorage.ts"],"names":[],"mappings":"AA2BA,gEAAgE;AAChE,MAAM,OAAO,YAAY;IACrB,mEAAmE;IAC1D,EAAE,CAAU;IACrB,kEAAkE;IACzD,YAAY,CAA8C;IACnE,2DAA2D;IAClD,YAAY,CAAwC;IAC7D,wEAAwE;IACxE,MAAM,GAAG,KAAK,CAAC;IAEf,YAAY,OAA4B;QACpC,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC;QACrB,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;QACxC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,GAAY;QAC1B,IAAI,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACxF,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,IAAsB,CAAC;QAC3B,IAAI,CAAC;YACD,IAAI,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;YACpB,MAAM,KAAK,CAAC;QAChB,CAAC;QACD,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,OAAO;YACH,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE;gBAC1B,IAAI,QAAQ;oBAAE,OAAO;gBACrB,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;gBAC/B,QAAQ,GAAG,IAAI,CAAC;gBAChB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;YACxB,CAAC;SACJ,CAAC;IACN,CAAC;IAED,oDAAoD;IACpD,WAAW,CAAC,OAAe;QACvB,OAAO,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;CACJ"}

package/dist/AgentSystem.d.ts

@@ -23,6 +23,8 @@ export interface AgentInitialContext {
 export interface AgentSystem {
     /** The models this collection offers its agents. */
     readonly models: readonly AgentModel[];
+    /** Stop every agent and release this system's exclusive ownership of its durable store. */
+    close(ctx: Context): Promise<void>;
     /**
      * Create an agent with a new system-generated cuid2 identity and the configuration it keeps
      * for its whole life. The configuration and optional initial context are persisted before

package/dist/AgentSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentSystem.d.ts","sourceRoot":"","sources":["../sources/AgentSystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IAChC,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CAChD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IACxB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IAEvC;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAEhG,oFAAoF;IACpF,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD,6FAA6F;IAC7F,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAExE,gFAAgF;IAChF,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAEvD;;;OAGG;IACH,KAAK,CACD,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAAG,qBAAqB,GAC1D,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,+FAA+F;IAC/F,IAAI,CACA,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAAG,qBAAqB,GAC1D,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,2FAA2F;IAC3F,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErF,wFAAwF;IACxF,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1F"}
+{"version":3,"file":"AgentSystem.d.ts","sourceRoot":"","sources":["../sources/AgentSystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IAChC,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CAChD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IACxB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IAEvC,2FAA2F;IAC3F,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAEhG,oFAAoF;IACpF,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD,6FAA6F;IAC7F,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAExE,gFAAgF;IAChF,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAEvD;;;OAGG;IACH,KAAK,CACD,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAAG,qBAAqB,GAC1D,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,+FAA+F;IAC/F,IAAI,CACA,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAAG,qBAAqB,GAC1D,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,2FAA2F;IAC3F,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErF,wFAAwF;IACxF,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1F"}

package/dist/AgentSystemLocal.d.ts

@@ -29,10 +29,8 @@ export interface AgentSystemLocalOptions {
  * the identities its storage holds. Concurrent resolutions of the same ID share one load, while a
  * failed load is forgotten so a later resolution can retry.
  *
- * Identity is durable and shared, so more than one live collection can be working over one
- * storage. Everything below therefore serializes per agent rather than per collection — a
- * collection-wide lock would make one agent's feature load block every other agent, including one
- * that load itself resolves — and treats storage, not memory, as the authority on who exists.
+ * Work serializes per agent rather than per collection: a collection-wide lock would make one
+ * agent's feature load block every other agent, including one that load itself resolves.
  *
  * This is the owner's handle, and some of what it offers waits for an agent to reach a point only
  * that agent's run loop can bring it to. Hand an `AgentSystemRef` to anything running inside an
@@ -49,8 +47,7 @@ export declare class AgentSystemLocal implements AgentSystem {
      * was running when the previous process ended is still owed an answer, and this is what
      * makes it happen. Every identity the storage holds is examined, and each one that owes work
      * is resolved and resumed, so by the time this returns the collection is not merely built
-     * but running. An identity another owner is still creating is left alone, since until that
-     * creation commits there is no agent to resume.
+     * but running.
      */
     static create(ctx: Context, storage: AgentStorage, config: AgentSystemLocalOptions): Promise<AgentSystemLocal>;
     /**
@@ -59,6 +56,11 @@ export declare class AgentSystemLocal implements AgentSystem {
      * the storage was left holding — building one without that is building half of it.
      */
     private constructor();
+    /**
+     * Stop every live agent, wait for operations already admitted by this owner, and only then
+     * release the database lock. Repeated callers join the same shutdown.
+     */
+    close(ctx: Context): Promise<void>;
     /**
      * Create an agent with the configuration it keeps for its whole life, and resolve it. The
      * identity is allocated here and nowhere else: it is a cuid2, globally unique, so a new
@@ -66,11 +68,10 @@ export declare class AgentSystemLocal implements AgentSystem {
      * The configuration is persisted before the agent runs, so every later process resolves the
      * agent exactly as it was created.
      *
-     * Nothing here is ever undone: an agent whose features refuse to load leaves an identity
-     * that exists, is resolvable, and will be built the next time something wants it. The
-     * alternative — writing a provisional identity and taking it back when the build fails —
-     * has to get the taking-back right in the presence of crashes and other owners, and a
-     * compensation that can itself fail is not a guarantee.
+     * Nothing here is undone: an agent whose features refuse to load leaves an identity that
+     * exists, is resolvable, and will be built the next time something wants it. Taking a
+     * provisional identity back after a failed build would add a compensation that can itself
+     * fail.
      */
     create(ctx: Context, config: AgentConfig, initialContext?: AgentInitialContext): Promise<Agent>;
     /**

package/dist/AgentSystemLocal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentSystemLocal.d.ts","sourceRoot":"","sources":["../sources/AgentSystemLocal.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AgentSystemLocal.d.ts","sourceRoot":"","sources":["../sources/AgentSystemLocal.ts"],"names":[],"mappings":"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"}

package/dist/AgentSystemLocal.js

@@ -3,7 +3,7 @@ import { Value } from "@sinclair/typebox/value";
 import { asyncLock } from "@steve.kite/stdlib";
 import { Agent } from "./Agent.js";
 import {} from "./AgentBase.js";
-import { agentBaseWithStoreStill } from "./AgentBaseStoreLock.js";
+import { agentId as agentIdOf } from "./AgentContexts.js";
 import { agentConfigSchema, withAgentConfig } from "./AgentConfig.js";
 import { withAgentSystem } from "./AgentSystemContext.js";
 import { AgentSystemRef } from "./AgentSystemRef.js";
@@ -12,10 +12,8 @@ import { AgentSystemRef } from "./AgentSystemRef.js";
  * the identities its storage holds. Concurrent resolutions of the same ID share one load, while a
  * failed load is forgotten so a later resolution can retry.
  *
- * Identity is durable and shared, so more than one live collection can be working over one
- * storage. Everything below therefore serializes per agent rather than per collection — a
- * collection-wide lock would make one agent's feature load block every other agent, including one
- * that load itself resolves — and treats storage, not memory, as the authority on who exists.
+ * Work serializes per agent rather than per collection: a collection-wide lock would make one
+ * agent's feature load block every other agent, including one that load itself resolves.
  *
  * This is the owner's handle, and some of what it offers waits for an agent to reach a point only
  * that agent's run loop can bring it to. Hand an `AgentSystemRef` to anything running inside an
@@ -24,6 +22,8 @@ import { AgentSystemRef } from "./AgentSystemRef.js";
 export class AgentSystemLocal {
     /** The models this collection offers its agents. */
     models;
+    /** The lifetime context retained by this system and its storage lock. */
+    #ctx;
     /**
      * What this collection looks like from inside one of its agents, and the only form of it a
      * derived context ever carries.
@@ -37,6 +37,8 @@ export class AgentSystemLocal {
     #providers;
     /** The registry ID of the provider new agents are created with. */
     #provider;
+    /** Exclusive database-backed ownership of this collection's whole durable store. */
+    #storageLock;
     /** The configuration each identity was created with. */
     #configs;
     /**
@@ -51,6 +53,12 @@ export class AgentSystemLocal {
     #persistences = new Map();
     /** Per-agent locks handed out by `#lockFor`, created lazily the first time an ID is touched. */
     #locks = new Map();
+    /** Public operations admitted before shutdown and therefore allowed to finish. */
+    #admitted = new Set();
+    /** No agent operation is admitted until every feature has finished its beforeStart hook. */
+    #lifecycle = "initializing";
+    /** The shared shutdown, including release of the hard storage lock. */
+    #closePromise;
     /**
      * Bring up a collection over one storage and carry on where the last process left off.
      *
@@ -58,28 +66,109 @@ export class AgentSystemLocal {
      * was running when the previous process ended is still owed an answer, and this is what
      * makes it happen. Every identity the storage holds is examined, and each one that owes work
      * is resolved and resumed, so by the time this returns the collection is not merely built
-     * but running. An identity another owner is still creating is left alone, since until that
-     * creation commits there is no agent to resume.
+     * but running.
      */
     static async create(ctx, storage, config) {
-        const system = new AgentSystemLocal(storage, config);
-        await system.#start(ctx);
-        return system;
+        const systemCtx = ctx;
+        const storageLock = await storage.acquireLock(systemCtx);
+        const system = new AgentSystemLocal(systemCtx, storage, storageLock, config);
+        try {
+            await system.#beforeStart(systemCtx);
+            const active = await system.#start(systemCtx);
+            system.#lifecycle = "open";
+            for (const agent of active)
+                agent.start();
+            await system.#afterStart(systemCtx);
+            return system;
+        }
+        catch (error) {
+            await system.close(systemCtx).catch(() => undefined);
+            throw error;
+        }
     }
     /**
      * Wire this collection to its storage, providers, and feature configuration, without reading
      * any of it. Private: a collection is brought up by `create`, which also resumes the work
      * the storage was left holding — building one without that is building half of it.
      */
-    constructor(storage, options) {
+    constructor(ctx, storage, storageLock, options) {
+        this.#ctx = ctx;
         this.#features = options.features ?? [];
         this.#storage = storage;
+        this.#storageLock = storageLock;
         this.#providers = options.providers;
         this.#provider = options.provider;
         this.models = [...options.models];
         this.#configs = storage.kv.scoped("config");
         this.#sharedFeatureKV = storage.kv.scoped("features");
     }
+    /**
+     * Stop every live agent, wait for operations already admitted by this owner, and only then
+     * release the database lock. Repeated callers join the same shutdown.
+     */
+    async close(ctx) {
+        if (this.#closePromise === undefined) {
+            this.#lifecycle = "closing";
+            this.#closePromise = this.#shutdown();
+        }
+        const closing = this.#closePromise;
+        const caller = agentIdOf(ctx);
+        if (caller !== undefined && this.#agents.has(caller)) {
+            void closing.catch(() => undefined);
+            throw new Error("Closing the agent system from inside one of its own agents would wait for " +
+                "that agent's turn. Shutdown will finish and release the store after this " +
+                "caller returns.");
+        }
+        await closing;
+    }
+    /** The real shutdown barrier, which keeps the hard store lock until every agent is closed. */
+    async #shutdown() {
+        try {
+            while (this.#admitted.size > 0) {
+                await Promise.allSettled(this.#admitted);
+            }
+            const closed = [...this.#agents.values()].map((agent) => {
+                void agent.close().catch(() => undefined);
+                return agent.waitForClosed();
+            });
+            await Promise.allSettled(closed);
+            this.#agents.clear();
+            this.#persistences.clear();
+            this.#locks.clear();
+        }
+        finally {
+            try {
+                await this.#storageLock.release(this.#ctx);
+            }
+            finally {
+                this.#lifecycle = "closed";
+            }
+        }
+    }
+    /**
+     * Admit one public operation while this system still owns the store. Shutdown rejects new
+     * admissions and waits for every earlier one before releasing the hard lock.
+     */
+    #admit(operation) {
+        if (this.#lifecycle !== "open") {
+            return Promise.reject(new Error(this.#lifecycle === "initializing"
+                ? "The agent system is not ready."
+                : "The agent system is closed."));
+        }
+        let running;
+        try {
+            // Begin synchronously so ownership-transfer boundaries such as create(config) copy
+            // caller-owned input before the caller can mutate it after receiving the promise.
+            running = operation();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const settled = running.then(() => undefined, () => undefined);
+        this.#admitted.add(settled);
+        void settled.finally(() => this.#admitted.delete(settled));
+        return running;
+    }
     /**
      * Create an agent with the configuration it keeps for its whole life, and resolve it. The
      * identity is allocated here and nowhere else: it is a cuid2, globally unique, so a new
@@ -87,29 +176,30 @@ export class AgentSystemLocal {
      * The configuration is persisted before the agent runs, so every later process resolves the
      * agent exactly as it was created.
      *
-     * Nothing here is ever undone: an agent whose features refuse to load leaves an identity
-     * that exists, is resolvable, and will be built the next time something wants it. The
-     * alternative — writing a provisional identity and taking it back when the build fails —
-     * has to get the taking-back right in the presence of crashes and other owners, and a
-     * compensation that can itself fail is not a guarantee.
+     * Nothing here is undone: an agent whose features refuse to load leaves an identity that
+     * exists, is resolvable, and will be built the next time something wants it. Taking a
+     * provisional identity back after a failed build would add a compensation that can itself
+     * fail.
      */
     async create(ctx, config, initialContext) {
-        const agentId = createId();
-        if (!Value.Check(agentConfigSchema, config)) {
-            throw new Error(`The configuration for agent "${agentId}" is not valid.`);
-        }
-        // The caller keeps its own object, and may go on editing it. What was created is what
-        // was passed at this moment, so storage and this agent's context both get a copy.
-        const owned = structuredClone(config);
-        return await this.#lockFor(agentId).runInLock(ctx, async (lockCtx) => {
-            await this.#configs.write(lockCtx, agentId, owned);
-            if (initialContext !== undefined) {
-                await this.#seedInitialContext(lockCtx, agentId, initialContext.messages);
+        return await this.#admit(async () => {
+            const agentId = createId();
+            if (!Value.Check(agentConfigSchema, config)) {
+                throw new Error(`The configuration for agent "${agentId}" is not valid.`);
             }
-            const agent = await this.#instantiate(lockCtx, agentId, owned);
-            if (agent === undefined)
-                throw new Error(`Agent "${agentId}" could not be built.`);
-            return agent;
+            // The caller keeps its own object, and may go on editing it. What was created is what
+            // was passed at this moment, so storage and this agent's context both get a copy.
+            const owned = structuredClone(config);
+            return await this.#lockFor(agentId).runInLock(ctx, async (lockCtx) => {
+                await this.#configs.write(lockCtx, agentId, owned);
+                if (initialContext !== undefined) {
+                    await this.#seedInitialContext(lockCtx, agentId, initialContext.messages);
+                }
+                const agent = await this.#instantiate(lockCtx, agentId, owned);
+                if (agent === undefined)
+                    throw new Error(`Agent "${agentId}" could not be built.`);
+                return agent;
+            });
         });
     }
     /**
@@ -123,12 +213,14 @@ export class AgentSystemLocal {
      * what clears it.
      */
     async delete(ctx, agentId) {
-        await this.#lockFor(agentId).runInLock(ctx, async (lockCtx) => {
-            const agent = this.#agents.get(agentId);
-            this.#agents.delete(agentId);
-            await agent?.close();
-            await this.#configs.delete(lockCtx, agentId);
-            this.#persistences.delete(agentId);
+        await this.#admit(async () => {
+            await this.#lockFor(agentId).runInLock(ctx, async (lockCtx) => {
+                const agent = this.#agents.get(agentId);
+                this.#agents.delete(agentId);
+                await agent?.close();
+                await this.#configs.delete(lockCtx, agentId);
+                this.#persistences.delete(agentId);
+            });
         });
     }
     /** Install a projected conversation before the new agent is started. */
@@ -136,15 +228,19 @@ export class AgentSystemLocal {
         if (messages.length === 0)
             return;
         const persistence = this.#persistenceFor(agentId);
-        await agentBaseWithStoreStill(ctx, persistence, (storeCtx) => persistence.transaction(storeCtx, async (txCtx) => {
+        await persistence.transaction(ctx, async (txCtx) => {
             await persistence.append(txCtx, {
                 type: "compaction",
                 messages: structuredClone(messages),
             });
-        }));
+        });
     }
     /** The configuration an agent was created with, or undefined when there is no such agent. */
     async config(ctx, agentId) {
+        return await this.#admit(async () => await this.#config(ctx, agentId));
+    }
+    /** Read one stored configuration while its owning operation is already admitted. */
+    async #config(ctx, agentId) {
         const stored = await this.#configs.read(ctx, agentId);
         if (stored === undefined)
             return undefined;
@@ -158,6 +254,10 @@ export class AgentSystemLocal {
      * Concurrent resolutions of the same ID share one load.
      */
     async resolve(ctx, agentId) {
+        return await this.#admit(async () => await this.#resolve(ctx, agentId));
+    }
+    /** Resolve one agent while its owning public operation is already admitted. */
+    async #resolve(ctx, agentId) {
         const existing = this.#agents.get(agentId);
         if (existing !== undefined)
             return existing;
@@ -165,23 +265,13 @@ export class AgentSystemLocal {
             const resolved = this.#agents.get(agentId);
             if (resolved !== undefined)
                 return resolved;
-            const config = await this.config(lockCtx, agentId);
+            const config = await this.#config(lockCtx, agentId);
             if (config === undefined) {
                 throw new Error(`Agent "${agentId}" has not been created.`);
             }
             const agent = await this.#instantiate(lockCtx, agentId, config);
             if (agent === undefined)
                 throw new Error(`Agent "${agentId}" could not be built.`);
-            // Building an agent takes as long as its features do, and identity is not this
-            // collection's to hold still for that: another owner may have deleted the ID, or a
-            // creation this resolution overtook may have rolled it back. Handing back an agent
-            // for an identity that no longer exists strands its caller with a live object no
-            // restart would ever reproduce, so the answer is checked before it is given.
-            if ((await this.config(lockCtx, agentId)) === undefined) {
-                this.#agents.delete(agentId);
-                await agent.close();
-                throw new Error(`Agent "${agentId}" was deleted while it was being resolved.`);
-            }
             return agent;
         });
     }
@@ -189,7 +279,7 @@ export class AgentSystemLocal {
      * Build one agent and put it to work. Called with the agent's lock held, and only for an ID
      * that has no live instance yet.
      */
-    async #instantiate(ctx, agentId, config, onlyIfActive = false) {
+    async #instantiate(ctx, agentId, config, onlyIfActive = false, start = true) {
         const agentCtx = withAgentConfig(withAgentSystem(ctx, this.#ref), config);
         const options = {
             id: agentId,
@@ -205,13 +295,14 @@ export class AgentSystemLocal {
         // resolves through — so the agent is loaded rather than created, and knows whether it
         // has work left before anything asks it. Bringing a collection up asks only for the
         // agents that do; anything else resolving an agent wants it whether it owes work or not.
-        const agent = onlyIfActive
-            ? await Agent.loadActive(agentCtx, options)
-            : await Agent.load(agentCtx, options);
-        if (agent === undefined)
+        const agent = await Agent.load(agentCtx, options);
+        if (onlyIfActive && !agent.active) {
+            await agent.close();
             return undefined;
-        agent.start();
+        }
         this.#agents.set(agentId, agent);
+        if (start)
+            agent.start();
         return agent;
     }
     /**
@@ -228,15 +319,29 @@ export class AgentSystemLocal {
      */
     async #start(ctx) {
         const created = await this.#configs.list(ctx);
-        await Promise.all(created.map(async ({ key: agentId, value }) => {
+        const results = await Promise.allSettled(created.map(async ({ key: agentId, value }) => {
             if (!Value.Check(agentConfigSchema, value))
-                return;
-            await this.#lockFor(agentId).runInLock(ctx, async (lockCtx) => {
+                return undefined;
+            return await this.#lockFor(agentId).runInLock(ctx, async (lockCtx) => {
                 if (this.#agents.has(agentId))
-                    return;
-                await this.#instantiate(lockCtx, agentId, value, true);
+                    return undefined;
+                return await this.#instantiate(lockCtx, agentId, value, true, false);
             });
         }));
+        throwFirstStartFailure(results);
+        return results.flatMap((result) => result.status === "fulfilled" && result.value !== undefined ? [result.value] : []);
+    }
+    /** Initialize every feature before any active agent is restored or started. */
+    async #beforeStart(ctx) {
+        const startCtx = withAgentSystem(ctx, this.#ref);
+        const results = await Promise.allSettled(this.#features.map(async (feature) => await feature.beforeStart?.(startCtx, this.#ref)));
+        throwFirstStartFailure(results);
+    }
+    /** Notify every feature after all active agents have been restored and started. */
+    async #afterStart(ctx) {
+        const startCtx = withAgentSystem(ctx, this.#ref);
+        const results = await Promise.allSettled(this.#features.map(async (feature) => await feature.afterStart?.(startCtx, this.#ref)));
+        throwFirstStartFailure(results);
     }
     /** The durable store for one agent, created once and reused for the life of the collection. */
     #persistenceFor(agentId) {
@@ -262,21 +367,35 @@ export class AgentSystemLocal {
     }
     /** Queue a steered message for an agent. */
     async steer(ctx, agentId, message, options) {
-        const agent = await this.resolve(ctx, agentId);
-        await agent.steer(ctx, message, options);
+        await this.#admit(async () => {
+            const agent = await this.#resolve(ctx, agentId);
+            await agent.steer(ctx, message, options);
+        });
     }
     /** Queue a message for an agent. */
     async send(ctx, agentId, message, options) {
-        const agent = await this.resolve(ctx, agentId);
-        await agent.send(ctx, message, options);
+        await this.#admit(async () => {
+            const agent = await this.#resolve(ctx, agentId);
+            await agent.send(ctx, message, options);
+        });
     }
     /** Cancel an agent's active turn, leaving its queued messages durable for the next one. */
     async abort(ctx, agentId, options) {
-        await (await this.resolve(ctx, agentId)).abort(ctx, options);
+        await this.#admit(async () => {
+            await (await this.#resolve(ctx, agentId)).abort(ctx, options);
+        });
     }
     /** Ask an agent for its conversation to be replaced by the provider's summary of it. */
     async compact(ctx, agentId, options) {
-        await (await this.resolve(ctx, agentId)).compact(ctx, options);
+        await this.#admit(async () => {
+            await (await this.#resolve(ctx, agentId)).compact(ctx, options);
+        });
     }
 }
+/** Start every feature even when one fails, then surface the first failure in feature order. */
+function throwFirstStartFailure(results) {
+    const failure = results.find((result) => result.status === "rejected");
+    if (failure !== undefined)
+        throw failure.reason;
+}
 //# sourceMappingURL=AgentSystemLocal.js.map