@slopus/happy-agent-base 0.0.5 → 0.0.7

package/dist/AgentStorage.js

@@ -1,17 +1,38 @@
-/** Storage roots shared by an `AgentSystemLocal` collection. */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { sql } from "drizzle-orm";
+import { asyncLock, withAfterCommit } from "@steve.kite/stdlib";
+import { agentDatabaseRows, agentDatabaseRun, isAgentSQLiteDatabase, } from "./AgentDatabase.js";
+import { agentStorageTransaction, withAgentStorageTransaction, } from "./AgentContexts.js";
+import { AgentKV } from "./AgentKV.js";
+import { AgentPersistenceDrizzle, } from "./AgentPersistenceDrizzle.js";
+const storageTransactions = new AsyncLocalStorage();
+/** Storage roots and Drizzle persistence shared by an `AgentSystemLocal` collection. */
 export class AgentStorage {
+    /** The root Drizzle facade. */
+    database;
     /** 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;
+    /** Drizzle transaction integration shared by every owned persistence scope. */
+    #drizzle;
     /** 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;
+        this.database = options.database;
+        const owner = {};
+        const rawTransaction = options.transaction ?? defaultTransactionIntegration(options.database);
+        const integration = {
+            database: options.database,
+            owner,
+            transaction: storageTransactionIntegration(owner, rawTransaction),
+        };
+        this.#drizzle = integration;
+        this.kv = new AgentKV(new AgentPersistenceDrizzle(integration, ""), "agentSystem.");
+        this.#persistence = (agentId) => new AgentPersistenceDrizzle(integration, agentId);
     }
     /**
      * Acquire exclusive ownership until the returned lock is released. The adapter's lock
@@ -45,5 +66,155 @@ export class AgentStorage {
     persistence(agentId) {
         return this.#persistence(agentId);
     }
+    /** Run work in this storage's default or host-supplied transaction integration. */
+    async transaction(ctx, work) {
+        return await this.#drizzle.transaction(ctx, work);
+    }
+    /**
+     * Install the base schema and every module's ordered keyed migrations. Each migration and
+     * its success marker commit atomically. Applied keys must remain an exact prefix, so inserting
+     * or reordering historical migrations fails instead of silently changing their meaning.
+     */
+    async migrate(ctx, modules) {
+        const names = modules.map((module) => module.name);
+        if (names.includes("@happy-agent-base") || new Set(names).size !== names.length) {
+            throw new Error("Module names must be unique and cannot use the agent-base owner.");
+        }
+        await this.#drizzle.transaction(ctx, async (txCtx, database) => {
+            await agentDatabaseRun(database, sql `CREATE TABLE IF NOT EXISTS happy_agent_migrations (
+                    module_key TEXT NOT NULL,
+                    migration_key TEXT NOT NULL,
+                    position BIGINT NOT NULL,
+                    PRIMARY KEY (module_key, migration_key),
+                    UNIQUE (module_key, position)
+                )`);
+        });
+        await this.#migrateModule(ctx, "@happy-agent-base", [
+            [
+                "001-core-storage",
+                async (_migrationCtx, database) => {
+                    await agentDatabaseRun(database, sql `CREATE TABLE happy_agent_records (
+                            owner_id TEXT NOT NULL,
+                            position BIGINT NOT NULL,
+                            record_json TEXT NOT NULL,
+                            PRIMARY KEY (owner_id, position)
+                        )`);
+                    await agentDatabaseRun(database, sql `CREATE TABLE happy_agent_values (
+                            owner_id TEXT NOT NULL,
+                            key TEXT NOT NULL,
+                            value_json TEXT NOT NULL,
+                            PRIMARY KEY (owner_id, key)
+                        )`);
+                },
+            ],
+        ]);
+        for (const module of modules) {
+            await this.#migrateModule(ctx, module.name, module.migrations ?? []);
+        }
+    }
+    async #migrateModule(ctx, module, migrations) {
+        const keys = migrations.map(([key]) => key);
+        if (keys.some((key) => key.length === 0) || new Set(keys).size !== keys.length) {
+            throw new Error(`Module "${module}" has an empty or duplicate migration key.`);
+        }
+        const applied = await agentDatabaseRows(this.#drizzle.database, sql `SELECT migration_key, position
+                FROM happy_agent_migrations
+                WHERE module_key = ${module}
+                ORDER BY position`);
+        for (let index = 0; index < applied.length; index += 1) {
+            if (applied[index]?.migration_key !== keys[index] ||
+                Number(applied[index]?.position) !== index) {
+                throw new Error(`The applied migrations for module "${module}" are not a prefix of its current migrations.`);
+            }
+        }
+        for (let index = applied.length; index < migrations.length; index += 1) {
+            const migration = migrations[index];
+            if (migration === undefined)
+                continue;
+            const [key, run] = migration;
+            await this.#drizzle.transaction(ctx, async (txCtx, database) => {
+                await run(txCtx, database);
+                await agentDatabaseRun(database, sql `INSERT INTO happy_agent_migrations
+                        (module_key, migration_key, position)
+                        VALUES (${module}, ${key}, ${index})`);
+            });
+        }
+    }
+}
+function defaultTransactionIntegration(database) {
+    const transactionLock = isAgentSQLiteDatabase(database) ? asyncLock() : undefined;
+    const commitTransaction = async (ctx, work) => {
+        let runAfterCommit;
+        const result = await runDrizzleTransaction(database, async (activeDatabase) => {
+            const [commitCtx, drainAfterCommit] = withAfterCommit(ctx);
+            runAfterCommit = drainAfterCommit;
+            return await work(commitCtx, activeDatabase);
+        });
+        return [result, runAfterCommit];
+    };
+    const transaction = async (ctx, work) => {
+        const [result, runAfterCommit] = transactionLock === undefined
+            ? await commitTransaction(ctx, work)
+            : await transactionLock.runInLock(ctx, async (lockCtx) => {
+                return await commitTransaction(lockCtx, work);
+            });
+        try {
+            await runAfterCommit();
+        }
+        catch (error) {
+            process.emitWarning(new AggregateError([error], "Agent storage committed, but post-commit work failed."));
+        }
+        return result;
+    };
+    return transaction;
+}
+/**
+ * Own transaction identity and nesting independently of the supplied database integration.
+ * A normal context from another storage remains a normal context, while an actual foreign
+ * transaction can neither leak its facade into this store nor silently open a second commit.
+ */
+function storageTransactionIntegration(owner, transaction) {
+    return async (ctx, work) => {
+        const carried = agentStorageTransaction(ctx);
+        const ambient = storageTransactions.getStore();
+        if (ambient !== undefined && !ambient.lifetime.aborted) {
+            if (ambient.owner === owner && carried === ambient) {
+                return await work(ctx, ambient.database);
+            }
+            throw new Error("Work started inside an agent storage transaction must use that transaction's context.");
+        }
+        if (carried !== undefined) {
+            if (carried.lifetime.aborted) {
+                throw new Error("The agent storage transaction carried by this context has ended.");
+            }
+            if (carried.owner !== owner) {
+                throw new Error("A transaction context cannot be used with another agent storage.");
+            }
+            return await work(ctx, carried.database);
+        }
+        return await transaction(ctx, async (txCtx, database) => {
+            const lifetime = new AbortController();
+            const state = {
+                database,
+                lifetime: lifetime.signal,
+                owner,
+            };
+            const activeCtx = withAgentStorageTransaction(txCtx, state);
+            try {
+                return await storageTransactions.run(state, async () => {
+                    return await work(activeCtx, database);
+                });
+            }
+            finally {
+                lifetime.abort();
+            }
+        });
+    };
+}
+async function runDrizzleTransaction(database, work) {
+    if (isAgentSQLiteDatabase(database)) {
+        return await database.transaction(async (transaction) => await work(transaction));
+    }
+    return await database.transaction(async (transaction) => await work(transaction));
 }
 //# sourceMappingURL=AgentStorage.js.map

package/dist/AgentStorage.js.map

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

package/dist/AgentSystem.d.ts

@@ -3,47 +3,69 @@ import type { Context } from "@steve.kite/stdlib";
 import type { Agent } from "./Agent.js";
 import type { AgentBaseAwaitOptions, AgentBaseMessageOptions } from "./AgentBase.js";
 import type { AgentConfig } from "./AgentConfig.js";
+import type { AgentDatabase } from "./AgentDatabase.js";
+import type { AgentMetadata } from "./AgentMetadata.js";
+import type { AgentMessageAcceptance } from "./AgentMessageAcceptance.js";
 import type { AgentModel } from "./AgentModel.js";
+import type { AnyAgentTool } from "./AgentTool.js";
 /** Conversation state installed atomically before a newly created agent starts. */
 export interface AgentInitialContext {
     /** The conversation installed as the agent's history before its first turn runs. */
     readonly messages: readonly SessionMessage[];
 }
+/** Optional identity, ancestry, and conversation supplied while creating one agent. */
+export interface AgentCreateOptions {
+    /** Client-chosen cuid2 identity; generated when omitted. */
+    readonly id?: string;
+    /** The conversation installed before the agent's first turn. */
+    readonly initialContext?: AgentInitialContext;
+    /**
+     * The parent agent. Omission inherits the creating reference or calling agent, `null` creates
+     * a root, and an explicit ID must already exist.
+     */
+    readonly parent?: string | null;
+}
 /**
  * A collection of agents addressed by ID: what an owner can ask of the agents it runs. An agent
- * exists only once it has been created with its configuration, which is persisted and stays in
- * effect for the agent's whole life; resolving one that was never created is an error.
+ * exists only once it has been created with its persisted configuration; resolving one that was
+ * never created is an error. Environment and module settings stay fixed, while metadata changes
+ * through a transactional shallow merge.
  *
  * This is the full surface, including the operations that wait for an agent's run loop to reach a
  * particular point — `delete`, and anything reached through the returned `Agent`. Those are for
- * the caller that owns the agents' lifetime. Code running *inside* an agent, such as a feature
+ * the caller that owns the agents' lifetime. Code running *inside* an agent, such as a module
  * hook or a tool, is waited for by that loop and must not wait for it in turn: it should hold an
  * `AgentSystemRef`, whose every operation returns without waiting for a loop.
  */
-export interface AgentSystem {
+export interface AgentSystem<Database extends AgentDatabase = AgentDatabase> {
     /** 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
-     * the agent runs; a creation that fails to produce an agent leaves no identity behind.
+     * Create an agent with a generated or caller-supplied cuid2 identity. Configuration,
+     * parentage, and optional initial context are persisted before it runs.
      */
-    create(ctx: Context, config: AgentConfig, initialContext?: AgentInitialContext): Promise<Agent>;
+    create(ctx: Context, config: AgentConfig, options?: AgentCreateOptions): Promise<Agent<AnyAgentTool, Database>>;
     /** Close an agent and release its identity, so the same ID can be created again. */
     delete(ctx: Context, agentId: string): Promise<void>;
-    /** The configuration an agent was created with, or undefined when there is no such agent. */
+    /** The current configuration of an agent, or undefined when there is no such agent. */
     config(ctx: Context, agentId: string): Promise<AgentConfig | undefined>;
+    /** Shallow-merge fields into an agent's immutable metadata. */
+    updateMetadata(ctx: Context, agentId: string, update: AgentMetadata): Promise<void>;
+    /** The direct children of an agent, in durable key order. */
+    childOf(ctx: Context, agentId: string): Promise<readonly string[]>;
+    /** The parent of an agent, or `null` when it is a root. */
+    parentOf(ctx: Context, agentId: string): Promise<string | null>;
     /** The live agent for an ID, loading it if this process has not seen it yet. */
-    resolve(ctx: Context, agentId: string): Promise<Agent>;
+    resolve(ctx: Context, agentId: string): Promise<Agent<AnyAgentTool, Database>>;
     /**
      * Queue a user message for an agent, injected as soon as its current response and tool batch
      * finish.
      */
-    steer(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<void>;
+    steer(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<AgentMessageAcceptance>;
     /** Queue a user message for an agent that injects only when the agent would otherwise stop. */
-    send(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<void>;
+    send(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<AgentMessageAcceptance>;
     /** Cancel an agent's active turn, leaving its queued messages durable for the next one. */
     abort(ctx: Context, agentId: string, options?: AgentBaseAwaitOptions): Promise<void>;
     /** Ask an agent for its conversation to be replaced by the provider's summary of it. */

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,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"}
+{"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,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IAChC,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CAChD;AAED,uFAAuF;AACvF,MAAM,WAAW,kBAAkB;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,QAAQ,CAAC,cAAc,CAAC,EAAE,mBAAmB,CAAC;IAC9C;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW,CAAC,QAAQ,SAAS,aAAa,GAAG,aAAa;IACvE,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;;;OAGG;IACH,MAAM,CACF,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,kBAAkB,GAC7B,OAAO,CAAC,KAAK,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;IAE1C,oFAAoF;IACpF,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD,uFAAuF;IACvF,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAExE,+DAA+D;IAC/D,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpF,6DAA6D;IAC7D,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IAEnE,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEhE,gFAAgF;IAChF,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;IAE/E;;;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,sBAAsB,CAAC,CAAC;IAEnC,+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,sBAAsB,CAAC,CAAC;IAEnC,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/AgentSystemContext.d.ts

@@ -1,15 +1,15 @@
 import { type Context } from "@steve.kite/stdlib";
 import type { AgentSystemRef } from "./AgentSystemRef.js";
 /**
- * Carry the collection that owns an agent and its features, as a reference.
+ * Carry the collection that owns an agent and its modules, as a reference.
  *
- * Only the reference travels on a context. Everything that reads one — a feature hook, a tool —
+ * Only the reference travels on a context. Everything that reads one — a module hook, a tool —
  * is code some run loop is waiting for, while the owner's surface holds the operations that wait
  * for a loop to reach a particular point. A collection therefore puts an `AgentSystemRef` on
  * every context it derives, and agents come back from it as `AgentRef`, so nothing reached
  * through a context can wait for the loop that is waiting for it.
  */
 export declare function withAgentSystem(ctx: Context, value: AgentSystemRef): Context;
-/** The collection owning the current feature or agent operation. */
+/** The collection owning the current module or agent operation. */
 export declare function agentSystem(ctx: Context): AgentSystemRef | undefined;
 //# sourceMappingURL=AgentSystemContext.d.ts.map

package/dist/AgentSystemContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentSystemContext.d.ts","sourceRoot":"","sources":["../sources/AgentSystemContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ1D;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAE5E;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAEpE"}
+{"version":3,"file":"AgentSystemContext.d.ts","sourceRoot":"","sources":["../sources/AgentSystemContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ1D;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAE5E;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAEpE"}

package/dist/AgentSystemContext.js

@@ -1,10 +1,10 @@
 import { createContextNamespace } from "@steve.kite/stdlib";
-/** The context slot that carries the collection owning the current agent or feature operation. */
+/** The context slot that carries the collection owning the current agent or module operation. */
 const agentSystemNamespace = createContextNamespace("happyAgent.agentSystem", undefined);
 /**
- * Carry the collection that owns an agent and its features, as a reference.
+ * Carry the collection that owns an agent and its modules, as a reference.
  *
- * Only the reference travels on a context. Everything that reads one — a feature hook, a tool —
+ * Only the reference travels on a context. Everything that reads one — a module hook, a tool —
  * is code some run loop is waiting for, while the owner's surface holds the operations that wait
  * for a loop to reach a particular point. A collection therefore puts an `AgentSystemRef` on
  * every context it derives, and agents come back from it as `AgentRef`, so nothing reached
@@ -13,7 +13,7 @@ const agentSystemNamespace = createContextNamespace("happyAgent.agentSystem", un
 export function withAgentSystem(ctx, value) {
     return agentSystemNamespace.set(ctx, value);
 }
-/** The collection owning the current feature or agent operation. */
+/** The collection owning the current module or agent operation. */
 export function agentSystem(ctx) {
     return agentSystemNamespace.get(ctx);
 }

package/dist/AgentSystemContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"AgentSystemContext.js","sourceRoot":"","sources":["../sources/AgentSystemContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAgB,MAAM,oBAAoB,CAAC;AAI1E,kGAAkG;AAClG,MAAM,oBAAoB,GAAG,sBAAsB,CAC/C,wBAAwB,EACxB,SAAS,CACZ,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY,EAAE,KAAqB;IAC/D,OAAO,oBAAoB,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AAChD,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,WAAW,CAAC,GAAY;IACpC,OAAO,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC"}
+{"version":3,"file":"AgentSystemContext.js","sourceRoot":"","sources":["../sources/AgentSystemContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAgB,MAAM,oBAAoB,CAAC;AAI1E,iGAAiG;AACjG,MAAM,oBAAoB,GAAG,sBAAsB,CAC/C,wBAAwB,EACxB,SAAS,CACZ,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY,EAAE,KAAqB;IAC/D,OAAO,oBAAoB,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AAChD,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAC,GAAY;IACpC,OAAO,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC"}

package/dist/AgentSystemLocal.d.ts

@@ -2,21 +2,25 @@ import type { SessionUserMessage } from "@slopus/happy-providers";
 import { type Context } from "@steve.kite/stdlib";
 import { Agent } from "./Agent.js";
 import { type AgentBaseAwaitOptions, type AgentBaseMessageOptions } from "./AgentBase.js";
+import type { AgentDatabase } from "./AgentDatabase.js";
 import { type AgentConfig } from "./AgentConfig.js";
-import type { AgentFeature } from "./AgentFeature.js";
+import type { AgentModule } from "./AgentModule.js";
+import { type AgentMetadata } from "./AgentMetadata.js";
+import type { AgentMessageAcceptance } from "./AgentMessageAcceptance.js";
 import type { AgentModel } from "./AgentModel.js";
 import type { AgentProviders } from "./AgentProviders.js";
 import type { AgentStorage } from "./AgentStorage.js";
-import type { AgentInitialContext, AgentSystem } from "./AgentSystem.js";
+import type { AgentCreateOptions, AgentSystem } from "./AgentSystem.js";
+import type { AnyAgentTool } from "./AgentTool.js";
 /** Everything `AgentSystemLocal` needs to build and run the agents in its collection. */
-export interface AgentSystemLocalOptions {
+export interface AgentSystemLocalOptions<Database extends AgentDatabase = AgentDatabase> {
     /**
-     * The features every agent in this collection runs with, given as instances the caller has
+     * The modules every agent in this collection runs with, given as instances the caller has
      * already built and ready to serve. One instance serves the whole collection: a hook is told
-     * which agent it is running for by the scope it is handed, so any per-agent state a feature
+     * which agent it is running for by the scope it is handed, so any per-agent state a module
      * keeps in memory has to be keyed by that ID rather than held as a single value.
      */
-    readonly features?: readonly AgentFeature[];
+    readonly modules?: readonly AgentModule<AnyAgentTool, Database>[];
     /** The registry providers are resolved from when an agent is built. */
     readonly providers: AgentProviders;
     /** The registry ID of the provider new agents are created with. */
@@ -30,13 +34,13 @@ export interface AgentSystemLocalOptions {
  * failed load is forgotten so a later resolution can retry.
  *
  * 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.
+ * agent's module 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
  * agent instead.
  */
-export declare class AgentSystemLocal implements AgentSystem {
+export declare class AgentSystemLocal<Database extends AgentDatabase = AgentDatabase> implements AgentSystem<Database> {
     #private;
     /** The models this collection offers its agents. */
     readonly models: readonly AgentModel[];
@@ -49,9 +53,9 @@ export declare class AgentSystemLocal implements AgentSystem {
      * is resolved and resumed, so by the time this returns the collection is not merely built
      * but running.
      */
-    static create(ctx: Context, storage: AgentStorage, config: AgentSystemLocalOptions): Promise<AgentSystemLocal>;
+    static create<Database extends AgentDatabase>(ctx: Context, storage: AgentStorage<Database>, config: AgentSystemLocalOptions<Database>): Promise<AgentSystemLocal<Database>>;
     /**
-     * Wire this collection to its storage, providers, and feature configuration, without reading
+     * Wire this collection to its storage, providers, and module 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.
      */
@@ -62,18 +66,17 @@ export declare class AgentSystemLocal implements AgentSystem {
      */
     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
-     * agent never lands on an identity that already exists or on a store something else wrote.
-     * The configuration is persisted before the agent runs, so every later process resolves the
-     * agent exactly as it was created.
+     * Create and resolve an agent. Its identity is either a validated caller-supplied cuid2 or
+     * allocated here, and the transaction refuses an existing identity rather than overwriting
+     * it. Configuration and parentage are persisted before the agent runs, so every later process
+     * resolves the same agent; only its metadata may subsequently change.
      *
-     * Nothing here is undone: an agent whose features refuse to load leaves an identity that
+     * Nothing here is undone: an agent whose modules 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>;
+    create(ctx: Context, config: AgentConfig, options?: AgentCreateOptions): Promise<Agent<AnyAgentTool, Database>>;
     /**
      * Close an agent and release its identity, so the same ID can be created again. Used to undo
      * a creation whose follow-up work failed; an ID that was never created is left alone.
@@ -85,17 +88,23 @@ export declare class AgentSystemLocal implements AgentSystem {
      * what clears it.
      */
     delete(ctx: Context, agentId: string): Promise<void>;
-    /** The configuration an agent was created with, or undefined when there is no such agent. */
+    /** The current configuration of an agent, or undefined when there is no such agent. */
     config(ctx: Context, agentId: string): Promise<AgentConfig | undefined>;
+    /** Shallow-merge fields into one agent's immutable metadata. */
+    updateMetadata(ctx: Context, agentId: string, update: AgentMetadata): Promise<void>;
+    /** The direct children of an existing agent, in durable key order. */
+    childOf(ctx: Context, agentId: string): Promise<readonly string[]>;
+    /** The parent of an existing agent, or `null` when it is a root. */
+    parentOf(ctx: Context, agentId: string): Promise<string | null>;
     /**
      * The live agent for an ID, loading and starting it if this process has not seen it yet.
      * Concurrent resolutions of the same ID share one load.
      */
-    resolve(ctx: Context, agentId: string): Promise<Agent>;
+    resolve(ctx: Context, agentId: string): Promise<Agent<AnyAgentTool, Database>>;
     /** Queue a steered message for an agent. */
-    steer(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<void>;
+    steer(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<AgentMessageAcceptance>;
     /** Queue a message for an agent. */
-    send(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<void>;
+    send(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<AgentMessageAcceptance>;
     /** Cancel an agent's active turn, leaving its queued messages durable for the next one. */
     abort(ctx: Context, agentId: string, options?: AgentBaseAwaitOptions): Promise<void>;
     /** Ask an agent for its conversation to be replaced by the provider's summary of it. */

package/dist/AgentSystemLocal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentSystemLocal.d.ts","sourceRoot":"","sources":["../sources/AgentSystemLocal.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAkB,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElF,OAAO,EAA6B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7E,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,KAAK,qBAAqB,EAAE,KAAK,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAI1F,OAAO,EAAsC,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIzE,yFAAyF;AACzF,MAAM,WAAW,uBAAuB;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC5C,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAiB,YAAW,WAAW;;IAChD,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IAwCvC;;;;;;;;OAQG;IACH,OAAa,MAAM,CACf,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,uBAAuB,GAChC,OAAO,CAAC,gBAAgB,CAAC,CAe3B;IAED;;;;OAIG;IACH,OAAO,eAeN;IAED;;;OAGG;IACG,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBvC;IAwDD;;;;;;;;;;;OAWG;IACG,MAAM,CACR,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,WAAW,EACnB,cAAc,CAAC,EAAE,mBAAmB,GACrC,OAAO,CAAC,KAAK,CAAC,CAmBhB;IAED;;;;;;;;;OASG;IACG,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUzD;IAkBD,6FAA6F;IACvF,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAE5E;IAYD;;;OAGG;IACG,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAE3D;IA8HD,4CAA4C;IACtC,KAAK,CACP,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAAG,qBAAqB,GAC1D,OAAO,CAAC,IAAI,CAAC,CAKf;IAED,oCAAoC;IAC9B,IAAI,CACN,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAAG,qBAAqB,GAC1D,OAAO,CAAC,IAAI,CAAC,CAKf;IAED,2FAA2F;IACrF,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIzF;IAED,wFAAwF;IAClF,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAI3F;CACJ"}
+{"version":3,"file":"AgentSystemLocal.d.ts","sourceRoot":"","sources":["../sources/AgentSystemLocal.ts"],"names":[],"mappings":"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"}