@slopus/happy-agent-base 0.0.5 → 0.0.7

package/dist/{AgentFeatureAction.d.ts → AgentModuleAction.d.ts}

@@ -1,16 +1,21 @@
 import type { SessionUserMessage } from "@slopus/happy-providers";
+import type { AgentMessageMetadata } from "./AgentMetadata.js";
 /**
  * What a lifecycle hook can ask the agent to do next: queue a steering or sent message through
  * the ordinary durable queues, or trigger a compaction. An action drives the loop exactly like
  * an external call to `steer`, `send`, or `compact` would.
  */
-export type AgentFeatureAction = {
+export type AgentModuleAction = {
     readonly type: "steer";
+    readonly id?: string;
     readonly message: SessionUserMessage;
+    readonly metadata?: AgentMessageMetadata;
 } | {
     readonly type: "send";
+    readonly id?: string;
     readonly message: SessionUserMessage;
+    readonly metadata?: AgentMessageMetadata;
 } | {
     readonly type: "compact";
 };
-//# sourceMappingURL=AgentFeatureAction.d.ts.map
+//# sourceMappingURL=AgentModuleAction.d.ts.map

package/dist/AgentModuleAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentModuleAction.d.ts","sourceRoot":"","sources":["../sources/AgentModuleAction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACvB;IACI,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CAC5C,GACD;IACI,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CAC5C,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC"}

package/dist/AgentModuleAction.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=AgentModuleAction.js.map

package/dist/AgentModuleAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentModuleAction.js","sourceRoot":"","sources":["../sources/AgentModuleAction.ts"],"names":[],"mappings":""}

package/dist/AgentPermissionMode.d.ts

@@ -5,7 +5,7 @@ import { type Static } from "@sinclair/typebox";
  * The mode is part of what an agent is running on, exactly like its model: it is carried on every
  * context the agent derives, it is durable, and a message may change it. What the runtime does not
  * do is enforce it — the loop has no idea what any particular tool touches. Enforcement belongs to
- * the features and tools that know, and they read the mode in force from the context they are
+ * the modules and tools that know, and they read the mode in force from the context they are
  * given.
  */
 export declare const agentPermissionModeSchema: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"read_only">, import("@sinclair/typebox").TLiteral<"workspace_write">, import("@sinclair/typebox").TLiteral<"auto">, import("@sinclair/typebox").TLiteral<"full_access">]>;

package/dist/AgentPermissionMode.js

@@ -6,7 +6,7 @@ import { Value } from "@sinclair/typebox/value";
  * The mode is part of what an agent is running on, exactly like its model: it is carried on every
  * context the agent derives, it is durable, and a message may change it. What the runtime does not
  * do is enforce it — the loop has no idea what any particular tool touches. Enforcement belongs to
- * the features and tools that know, and they read the mode in force from the context they are
+ * the modules and tools that know, and they read the mode in force from the context they are
  * given.
  */
 export const agentPermissionModeSchema = Type.Union([

package/dist/AgentPersistence.d.ts

@@ -1,5 +1,7 @@
 import type { SessionAssistantBlock, SessionMessage, SessionSystemMessage, SessionToolResultMessage, SessionUserMessage } from "@slopus/happy-providers";
 import type { Context } from "@steve.kite/stdlib";
+import type { AgentDatabase } from "./AgentDatabase.js";
+import type { AgentMessageMetadata } from "./AgentMetadata.js";
 /**
  * One record of the main context store. Only content that is part of the model context lives
  * here: user messages enter when a turn consumes them, assistant output is appended one finished
@@ -11,7 +13,9 @@ import type { Context } from "@steve.kite/stdlib";
  */
 export type AgentRecord = {
     readonly type: "user";
+    readonly id: string;
     readonly message: SessionUserMessage;
+    readonly metadata?: AgentMessageMetadata;
 } | {
     readonly type: "block";
     readonly block: SessionAssistantBlock;
@@ -29,17 +33,21 @@ export type AgentRecord = {
  * Storage for one agent: an append-only main context store plus a sorted key-value store held
  * alongside it. A sent message is first written under a `pending.` key ordered by append time;
  * it reaches the main store only when a turn consumes it into the context, and its pending key
- * is deleted at that moment. Exactly one owner connects to a store, and the agent serializes its
- * own record and bookkeeping writes through one lock, so history order always matches storage
- * order. Key-value operations — a feature's or a tool's — run as they come, so each one has to be
- * atomic on its own, but no implementation ever has to defend against a second owner.
+ * is deleted at that moment. A `message.` uniqueness key makes retrying a cuid2 message ID an
+ * ignored database conflict; history replacement removes keys for the records it deletes.
+ * Exactly one owner connects to a store, and the agent serializes its own record and bookkeeping
+ * writes through one lock, so history order always matches storage order. Key-value operations —
+ * a module's or a tool's — run as they come, so each one has to be atomic on its own, but no
+ * implementation ever has to defend against a second owner.
  */
 export interface AgentPersistence {
+    /** The root Drizzle facade for this store. */
+    readonly database: AgentDatabase;
     /**
      * Run work atomically. The implementation opens a transaction and passes work a derived
-     * context that its own operations recognize; how the transaction rides on that context is
-     * entirely the implementation's business. Work resolving commits every operation; a thrown
-     * error rolls them all back.
+     * context that its own operations recognize and that carries stdlib's universal
+     * `afterCommit` scope. Work resolving commits every operation and then drains that scope; a
+     * thrown error rolls everything back without draining it.
      */
     transaction<Result>(ctx: Context, work: (ctx: Context) => Promise<Result>): Promise<Result>;
     /** Every record in the main context store, in append order. */
@@ -59,6 +67,11 @@ export interface AgentPersistence {
     }[]>;
     /** Store the value under `key`, replacing whatever was there before. */
     writeValue(ctx: Context, key: string, value: unknown): Promise<void>;
+    /**
+     * Store the value only when `key` is absent. Returns false for the database uniqueness
+     * conflict without changing the existing value.
+     */
+    writeValueIfAbsent(ctx: Context, key: string, value: unknown): Promise<boolean>;
     /** Remove the entry stored under `key`, if any. */
     deleteValue(ctx: Context, key: string): Promise<void>;
 }

package/dist/AgentPersistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentPersistence.d.ts","sourceRoot":"","sources":["../sources/AgentPersistence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,qBAAqB,EACrB,cAAc,EACd,oBAAoB,EACpB,wBAAwB,EACxB,kBAAkB,EACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAA;CAAE,GACrE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GACnE;IACI,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CAChD,CAAC;AAER;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5F,+DAA+D;IAC/D,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IACpD,gEAAgE;IAChE,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,0EAA0E;IAC1E,UAAU,CACN,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,GACf,OAAO,CAAC,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC,CAAC;IACzE,wEAAwE;IACxE,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,mDAAmD;IACnD,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD"}
+{"version":3,"file":"AgentPersistence.d.ts","sourceRoot":"","sources":["../sources/AgentPersistence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,qBAAqB,EACrB,cAAc,EACd,oBAAoB,EACpB,wBAAwB,EACxB,kBAAkB,EACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GACjB;IACI,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CAC5C,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAA;CAAE,GACrE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GACnE;IACI,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CAChD,CAAC;AAER;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5F,+DAA+D;IAC/D,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IACpD,gEAAgE;IAChE,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,0EAA0E;IAC1E,UAAU,CACN,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,GACf,OAAO,CAAC,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC,CAAC;IACzE,wEAAwE;IACxE,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE;;;OAGG;IACH,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChF,mDAAmD;IACnD,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD"}

package/dist/AgentPersistenceDrizzle.d.ts

@@ -0,0 +1,31 @@
+import type { Context } from "@steve.kite/stdlib";
+import { type AgentDatabase, type AgentStorageTransaction } from "./AgentDatabase.js";
+import type { AgentPersistence, AgentRecord } from "./AgentPersistence.js";
+/** The database and transaction integration shared by every scope in one AgentStorage. */
+export interface AgentPersistenceDrizzleOptions<Database extends AgentDatabase = AgentDatabase> {
+    readonly database: Database;
+    readonly owner: object;
+    readonly transaction: AgentStorageTransaction<Database>;
+}
+/**
+ * Drizzle-backed records and key-value entries for either the collection root or one agent.
+ * Tables are shared by every instance; `ownerId` is empty for collection state and the cuid2
+ * agent identity for a conversation.
+ */
+export declare class AgentPersistenceDrizzle<Database extends AgentDatabase = AgentDatabase> implements AgentPersistence {
+    #private;
+    constructor(options: AgentPersistenceDrizzleOptions<Database>, ownerId: string);
+    get database(): AgentDatabase;
+    transaction<Result>(ctx: Context, work: (ctx: Context) => Promise<Result>): Promise<Result>;
+    load(ctx: Context): Promise<readonly AgentRecord[]>;
+    append(ctx: Context, record: AgentRecord): Promise<void>;
+    clearRecords(ctx: Context): Promise<void>;
+    readValues(ctx: Context, prefix: string): Promise<readonly {
+        readonly key: string;
+        readonly value: unknown;
+    }[]>;
+    writeValue(ctx: Context, key: string, value: unknown): Promise<void>;
+    writeValueIfAbsent(ctx: Context, key: string, value: unknown): Promise<boolean>;
+    deleteValue(ctx: Context, key: string): Promise<void>;
+}
+//# sourceMappingURL=AgentPersistenceDrizzle.d.ts.map

package/dist/AgentPersistenceDrizzle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentPersistenceDrizzle.d.ts","sourceRoot":"","sources":["../sources/AgentPersistenceDrizzle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAGH,KAAK,aAAa,EAElB,KAAK,uBAAuB,EAC/B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAE3E,0FAA0F;AAC1F,MAAM,WAAW,8BAA8B,CAAC,QAAQ,SAAS,aAAa,GAAG,aAAa;IAC1F,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;CAC3D;AAED;;;;GAIG;AACH,qBAAa,uBAAuB,CAChC,QAAQ,SAAS,aAAa,GAAG,aAAa,CAChD,YAAW,gBAAgB;;IAIzB,YAAY,OAAO,EAAE,8BAA8B,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM,EAG7E;IAED,IAAI,QAAQ,IAAI,aAAa,CAE5B;IAEK,WAAW,CAAC,MAAM,EACpB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,GACxC,OAAO,CAAC,MAAM,CAAC,CAEjB;IAEK,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAWxD;IAEK,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAU7D;IAEK,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9C;IAEK,UAAU,CACZ,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,GACf,OAAO,CAAC,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC,CAYvE;IAEK,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAYzE;IAEK,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAapF;IAEK,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ1D;CAoBJ"}

package/dist/AgentPersistenceDrizzle.js

@@ -0,0 +1,99 @@
+import { sql } from "drizzle-orm";
+import { agentDatabaseRows, agentDatabaseRun, } from "./AgentDatabase.js";
+import { agentStorageTransaction } from "./AgentContexts.js";
+/**
+ * Drizzle-backed records and key-value entries for either the collection root or one agent.
+ * Tables are shared by every instance; `ownerId` is empty for collection state and the cuid2
+ * agent identity for a conversation.
+ */
+export class AgentPersistenceDrizzle {
+    #options;
+    #ownerId;
+    constructor(options, ownerId) {
+        this.#options = options;
+        this.#ownerId = ownerId;
+    }
+    get database() {
+        return this.#options.database;
+    }
+    async transaction(ctx, work) {
+        return await this.#options.transaction(ctx, async (txCtx) => await work(txCtx));
+    }
+    async load(ctx) {
+        return await this.#operation(ctx, async (database) => {
+            const rows = await agentDatabaseRows(database, sql `SELECT record_json
+                    FROM happy_agent_records
+                    WHERE owner_id = ${this.#ownerId}
+                    ORDER BY position`);
+            return rows.map(({ record_json }) => JSON.parse(record_json));
+        });
+    }
+    async append(ctx, record) {
+        await this.#operation(ctx, async (database) => {
+            await agentDatabaseRun(database, sql `INSERT INTO happy_agent_records (owner_id, position, record_json)
+                    SELECT ${this.#ownerId}, COALESCE(MAX(position), -1) + 1, ${JSON.stringify(record)}
+                    FROM happy_agent_records
+                    WHERE owner_id = ${this.#ownerId}`);
+        });
+    }
+    async clearRecords(ctx) {
+        await this.#operation(ctx, async (database) => {
+            await agentDatabaseRun(database, sql `DELETE FROM happy_agent_records WHERE owner_id = ${this.#ownerId}`);
+        });
+    }
+    async readValues(ctx, prefix) {
+        return await this.#operation(ctx, async (database) => {
+            const rows = await agentDatabaseRows(database, sql `SELECT key, value_json
+                    FROM happy_agent_values
+                    WHERE owner_id = ${this.#ownerId}
+                      AND substr(key, 1, length(${prefix})) = ${prefix}
+                    ORDER BY key`);
+            return rows.map(({ key, value_json }) => ({ key, value: JSON.parse(value_json) }));
+        });
+    }
+    async writeValue(ctx, key, value) {
+        const encoded = JSON.stringify(value);
+        if (encoded === undefined)
+            throw new Error("Agent storage cannot persist undefined.");
+        await this.#operation(ctx, async (database) => {
+            await agentDatabaseRun(database, sql `INSERT INTO happy_agent_values (owner_id, key, value_json)
+                    VALUES (${this.#ownerId}, ${key}, ${encoded})
+                    ON CONFLICT (owner_id, key)
+                    DO UPDATE SET value_json = EXCLUDED.value_json`);
+        });
+    }
+    async writeValueIfAbsent(ctx, key, value) {
+        const encoded = JSON.stringify(value);
+        if (encoded === undefined)
+            throw new Error("Agent storage cannot persist undefined.");
+        return await this.#operation(ctx, async (database) => {
+            const rows = await agentDatabaseRows(database, sql `INSERT INTO happy_agent_values (owner_id, key, value_json)
+                    VALUES (${this.#ownerId}, ${key}, ${encoded})
+                    ON CONFLICT (owner_id, key) DO NOTHING
+                    RETURNING key`);
+            return rows.length > 0;
+        });
+    }
+    async deleteValue(ctx, key) {
+        await this.#operation(ctx, async (database) => {
+            await agentDatabaseRun(database, sql `DELETE FROM happy_agent_values
+                    WHERE owner_id = ${this.#ownerId} AND key = ${key}`);
+        });
+    }
+    async #operation(ctx, work) {
+        const transaction = agentStorageTransaction(ctx);
+        if (transaction !== undefined) {
+            if (transaction.lifetime.aborted) {
+                throw new Error("The agent storage transaction carried by this context has ended.");
+            }
+            if (transaction.owner !== this.#options.owner) {
+                throw new Error("A transaction context cannot be used with another agent storage.");
+            }
+            return await work(transaction.database);
+        }
+        return await this.#options.transaction(ctx, async (_txCtx, database) => {
+            return await work(database);
+        });
+    }
+}
+//# sourceMappingURL=AgentPersistenceDrizzle.js.map

package/dist/AgentPersistenceDrizzle.js.map

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

package/dist/AgentRef.d.ts

@@ -2,15 +2,19 @@ import type { SessionUserMessage } from "@slopus/happy-providers";
 import type { Context } from "@steve.kite/stdlib";
 import type { Agent } from "./Agent.js";
 import type { AgentBaseMessageOptions } from "./AgentBase.js";
+import type { AgentDatabase } from "./AgentDatabase.js";
+import type { AgentMetadata } from "./AgentMetadata.js";
+import type { AgentMessageAcceptance } from "./AgentMessageAcceptance.js";
+import type { AnyAgentTool } from "./AgentTool.js";
 /**
  * Whether this caller may be told that `agentId` durably accepted a message. Acceptance is a
  * queue write under that agent's own persistence lock, so waiting for it is safe from anywhere
- * except inside that agent's loop, which is holding the lock the write needs. The proof is the
- * caller's context naming a different agent; a context naming none proves nothing.
+ * except inside that agent's loop, which is holding the lock the write needs. A caller naming no
+ * agent is an external host and may wait; only the target agent itself cannot.
  */
 export declare function acceptanceIsWaitable(ctx: Context, target: string): boolean;
 /**
- * A reference to an agent for code that runs inside one — a feature hook, or a tool the run loop
+ * A reference to an agent for code that runs inside one — a module hook, or a tool the run loop
  * is waiting on. No operation here waits for a run loop: `compact` and `abort` are requests that
  * resolve once they have been made, and there is no `close`, `waitForIdle` or `start`, each of
  * which is whole-agent lifetime owned by whoever created the agent and nothing *but* the wait
@@ -21,18 +25,22 @@ export declare function acceptanceIsWaitable(ctx: Context, target: string): bool
  * agent's conversation and reject when the write fails, so a caller routing work elsewhere knows
  * whether it arrived. Addressed to the agent the caller is running inside — whose loop would have
  * to perform that write — the message is queued and not waited for. The context decides, since it
- * names the agent the caller is in; a context that names none proves nothing and waits for
- * nothing.
+ * names the agent the caller is in; a context that names none is an external host and receives
+ * the durable acceptance result.
  */
-export declare class AgentRef {
+export declare class AgentRef<Database extends AgentDatabase = AgentDatabase> {
     #private;
-    constructor(agent: Agent);
+    /** The durable parent captured when this reference was resolved, or `null` for a root. */
+    readonly parent: string | null;
+    constructor(agent: Agent<AnyAgentTool, Database>, parent?: string | null);
     /** The wrapped agent's ID. */
     get id(): string;
     /** Queue a message that injects as soon as the current response and its tool batch finish. */
-    steer(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<void>;
+    steer(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<AgentMessageAcceptance>;
     /** Queue a message that injects when the agent would otherwise stop. */
-    send(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<void>;
+    send(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<AgentMessageAcceptance>;
+    /** Shallow-merge fields into this agent's immutable metadata. */
+    updateMetadata(ctx: Context, update: AgentMetadata): Promise<void>;
     /** Ask the agent to compact, which it does between turns. */
     compact(ctx: Context): Promise<void>;
     /** Cancel the agent's active turn. */

package/dist/AgentRef.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentRef.d.ts","sourceRoot":"","sources":["../sources/AgentRef.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAG9D;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAG1E;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,QAAQ;;IAIjB,YAAY,KAAK,EAAE,KAAK,EAEvB;IAED,8BAA8B;IAC9B,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,8FAA8F;IACxF,KAAK,CACP,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC,CAKf;IAED,wEAAwE;IAClE,IAAI,CACN,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC,CAKf;IAED,6DAA6D;IACvD,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzC;IAED,sCAAsC;IAChC,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvC;CACJ"}
+{"version":3,"file":"AgentRef.d.ts","sourceRoot":"","sources":["../sources/AgentRef.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAE9D,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,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAG1E;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,QAAQ,CAAC,QAAQ,SAAS,aAAa,GAAG,aAAa;;IAGhE,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B,YAAY,KAAK,EAAE,KAAK,CAAC,YAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAE,MAAM,GAAG,IAAW,EAG7E;IAED,8BAA8B;IAC9B,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,8FAA8F;IACxF,KAAK,CACP,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAKjC;IAED,wEAAwE;IAClE,IAAI,CACN,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAKjC;IAED,iEAAiE;IAC3D,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvE;IAED,6DAA6D;IACvD,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzC;IAED,sCAAsC;IAChC,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvC;CACJ"}

package/dist/AgentRef.js

@@ -2,15 +2,15 @@ import { agentId } from "./AgentContexts.js";
 /**
  * Whether this caller may be told that `agentId` durably accepted a message. Acceptance is a
  * queue write under that agent's own persistence lock, so waiting for it is safe from anywhere
- * except inside that agent's loop, which is holding the lock the write needs. The proof is the
- * caller's context naming a different agent; a context naming none proves nothing.
+ * except inside that agent's loop, which is holding the lock the write needs. A caller naming no
+ * agent is an external host and may wait; only the target agent itself cannot.
  */
 export function acceptanceIsWaitable(ctx, target) {
     const caller = agentId(ctx);
-    return caller !== undefined && caller !== target;
+    return caller !== target;
 }
 /**
- * A reference to an agent for code that runs inside one — a feature hook, or a tool the run loop
+ * A reference to an agent for code that runs inside one — a module hook, or a tool the run loop
  * is waiting on. No operation here waits for a run loop: `compact` and `abort` are requests that
  * resolve once they have been made, and there is no `close`, `waitForIdle` or `start`, each of
  * which is whole-agent lifetime owned by whoever created the agent and nothing *but* the wait
@@ -21,14 +21,17 @@ export function acceptanceIsWaitable(ctx, target) {
  * agent's conversation and reject when the write fails, so a caller routing work elsewhere knows
  * whether it arrived. Addressed to the agent the caller is running inside — whose loop would have
  * to perform that write — the message is queued and not waited for. The context decides, since it
- * names the agent the caller is in; a context that names none proves nothing and waits for
- * nothing.
+ * names the agent the caller is in; a context that names none is an external host and receives
+ * the durable acceptance result.
  */
 export class AgentRef {
     /** The agent this reference wraps. */
     #agent;
-    constructor(agent) {
+    /** The durable parent captured when this reference was resolved, or `null` for a root. */
+    parent;
+    constructor(agent, parent = null) {
         this.#agent = agent;
+        this.parent = parent;
     }
     /** The wrapped agent's ID. */
     get id() {
@@ -36,18 +39,22 @@ export class AgentRef {
     }
     /** Queue a message that injects as soon as the current response and its tool batch finish. */
     async steer(ctx, message, options) {
-        await this.#agent.steer(ctx, message, {
+        return await this.#agent.steer(ctx, message, {
             ...options,
             await: acceptanceIsWaitable(ctx, this.#agent.id),
         });
     }
     /** Queue a message that injects when the agent would otherwise stop. */
     async send(ctx, message, options) {
-        await this.#agent.send(ctx, message, {
+        return await this.#agent.send(ctx, message, {
             ...options,
             await: acceptanceIsWaitable(ctx, this.#agent.id),
         });
     }
+    /** Shallow-merge fields into this agent's immutable metadata. */
+    async updateMetadata(ctx, update) {
+        await this.#agent.updateMetadata(ctx, update);
+    }
     /** Ask the agent to compact, which it does between turns. */
     async compact(ctx) {
         await this.#agent.compact(ctx, { await: false });

package/dist/AgentRef.js.map

@@ -1 +1 @@
-{"version":3,"file":"AgentRef.js","sourceRoot":"","sources":["../sources/AgentRef.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAY,EAAE,MAAc;IAC7D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,MAAM,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,QAAQ;IACjB,sCAAsC;IAC7B,MAAM,CAAQ;IAEvB,YAAY,KAAY;QACpB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACxB,CAAC;IAED,8BAA8B;IAC9B,IAAI,EAAE;QACF,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;IAC1B,CAAC;IAED,8FAA8F;IAC9F,KAAK,CAAC,KAAK,CACP,GAAY,EACZ,OAA2B,EAC3B,OAAiC;QAEjC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE;YAClC,GAAG,OAAO;YACV,KAAK,EAAE,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;SACnD,CAAC,CAAC;IACP,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,IAAI,CACN,GAAY,EACZ,OAA2B,EAC3B,OAAiC;QAEjC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE;YACjC,GAAG,OAAO;YACV,KAAK,EAAE,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;SACnD,CAAC,CAAC;IACP,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,OAAO,CAAC,GAAY;QACtB,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,sCAAsC;IACtC,KAAK,CAAC,KAAK,CAAC,GAAY;QACpB,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACnD,CAAC;CACJ"}
+{"version":3,"file":"AgentRef.js","sourceRoot":"","sources":["../sources/AgentRef.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAM7C;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAY,EAAE,MAAc;IAC7D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,MAAM,KAAK,MAAM,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,QAAQ;IACjB,sCAAsC;IAC7B,MAAM,CAAgC;IAC/C,0FAA0F;IACjF,MAAM,CAAgB;IAE/B,YAAY,KAAoC,EAAE,MAAM,GAAkB,IAAI;QAC1E,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAED,8BAA8B;IAC9B,IAAI,EAAE;QACF,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;IAC1B,CAAC;IAED,8FAA8F;IAC9F,KAAK,CAAC,KAAK,CACP,GAAY,EACZ,OAA2B,EAC3B,OAAiC;QAEjC,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE;YACzC,GAAG,OAAO;YACV,KAAK,EAAE,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;SACnD,CAAC,CAAC;IACP,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,IAAI,CACN,GAAY,EACZ,OAA2B,EAC3B,OAAiC;QAEjC,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE;YACxC,GAAG,OAAO;YACV,KAAK,EAAE,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;SACnD,CAAC,CAAC;IACP,CAAC;IAED,iEAAiE;IACjE,KAAK,CAAC,cAAc,CAAC,GAAY,EAAE,MAAqB;QACpD,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,OAAO,CAAC,GAAY;QACtB,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,sCAAsC;IACtC,KAAK,CAAC,KAAK,CAAC,GAAY;QACpB,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACnD,CAAC;CACJ"}

package/dist/AgentStorage.d.ts

@@ -1,32 +1,43 @@
-import type { Context } from "@steve.kite/stdlib";
-import type { AgentKV } from "./AgentKV.js";
+import { type Context } from "@steve.kite/stdlib";
+import { type AgentDatabase, type AgentDatabaseFacade, type AgentStorageTransaction } from "./AgentDatabase.js";
+import type { AgentModule } from "./AgentModule.js";
+import { AgentKV } from "./AgentKV.js";
 import type { AgentPersistence } from "./AgentPersistence.js";
+import type { AnyAgentTool } from "./AgentTool.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.
+ * The exclusive ownership of one durable agent store. A host sharing its database between
+ * processes should back this with the same hard process-level lock as the database itself.
  */
 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 {
+interface AgentStorageCommonOptions {
     /**
      * 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. */
-    readonly persistence: (agentId: string) => AgentPersistence;
 }
-/** Storage roots shared by an `AgentSystemLocal` collection. */
-export declare class AgentStorage {
+/** Drizzle-owned storage with optional host transaction integration. */
+export type AgentStorageOptions<Database extends AgentDatabase = AgentDatabase> = AgentStorageCommonOptions & {
+    /** The engine-specific Drizzle facade; the same object is passed through to modules. */
+    readonly database: Database;
+    /**
+     * Host transaction integration. It must pass the active Drizzle transaction facade and a
+     * context carrying the host transaction's stdlib `afterCommit` scope to `work`. Omission
+     * uses the Drizzle facade's own transaction method and installs that scope automatically.
+     */
+    readonly transaction?: AgentStorageTransaction<Database>;
+};
+/** Storage roots and Drizzle persistence shared by an `AgentSystemLocal` collection. */
+export declare class AgentStorage<Database extends AgentDatabase = AgentDatabase> {
     #private;
+    /** The root Drizzle facade. */
+    readonly database: Database;
     /** Shared key-value storage used for state spanning all agents. */
     readonly kv: AgentKV;
-    constructor(options: AgentStorageOptions);
+    constructor(options: AgentStorageOptions<Database>);
     /**
      * 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
@@ -35,5 +46,14 @@ export declare class AgentStorage {
     acquireLock(ctx: Context): Promise<AgentStorageLock>;
     /** The isolated persistence for the given agent. */
     persistence(agentId: string): AgentPersistence;
+    /** Run work in this storage's default or host-supplied transaction integration. */
+    transaction<Result>(ctx: Context, work: (ctx: Context, database: AgentDatabaseFacade<Database>) => Promise<Result>): Promise<Result>;
+    /**
+     * 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.
+     */
+    migrate(ctx: Context, modules: readonly AgentModule<AnyAgentTool, Database>[]): Promise<void>;
 }
+export {};
 //# sourceMappingURL=AgentStorage.d.ts.map

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,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"}
+{"version":3,"file":"AgentStorage.d.ts","sourceRoot":"","sources":["../sources/AgentStorage.ts"],"names":[],"mappings":"AAEA,OAAO,EAA8B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE9E,OAAO,EAIH,KAAK,aAAa,EAClB,KAAK,mBAAmB,EAExB,KAAK,uBAAuB,EAC/B,MAAM,oBAAoB,CAAC;AAM5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAMnD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,kFAAkF;IAClF,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,UAAU,yBAAyB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACrE;AAED,wEAAwE;AACxE,MAAM,MAAM,mBAAmB,CAAC,QAAQ,SAAS,aAAa,GAAG,aAAa,IAC1E,yBAAyB,GAAG;IACxB,wFAAwF;IACxF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;CAC5D,CAAC;AAIN,wFAAwF;AACxF,qBAAa,YAAY,CAAC,QAAQ,SAAS,aAAa,GAAG,aAAa;;IACpE,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IAUrB,YAAY,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC,EAcjD;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;IAED,mFAAmF;IAC7E,WAAW,CAAC,MAAM,EACpB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,mBAAmB,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,GACjF,OAAO,CAAC,MAAM,CAAC,CAEjB;IAED;;;;OAIG;IACG,OAAO,CACT,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,SAAS,WAAW,CAAC,YAAY,EAAE,QAAQ,CAAC,EAAE,GACxD,OAAO,CAAC,IAAI,CAAC,CA6Cf;CA8CJ"}