@slopus/happy-agent-base 0.0.6 → 0.0.8

package/dist/AgentConfig.d.ts

@@ -6,12 +6,12 @@ export declare const agentPlatformSchema: import("@sinclair/typebox").TUnion<[im
 /** The TypeScript type inferred from {@link agentPlatformSchema}. */
 export type AgentPlatform = Static<typeof agentPlatformSchema>;
 /**
- * The settings one feature was configured with. The agent never looks inside: a feature owns
+ * The settings one module was configured with. The agent never looks inside: a module owns
  * the shape of its own entry and validates it against its own schema.
  */
-export declare const agentFeatureConfigSchema: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>;
-/** The TypeScript type inferred from {@link agentFeatureConfigSchema}. */
-export type AgentFeatureConfig = Static<typeof agentFeatureConfigSchema>;
+export declare const agentModuleConfigSchema: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>;
+/** The TypeScript type inferred from {@link agentModuleConfigSchema}. */
+export type AgentModuleConfig = Static<typeof agentModuleConfigSchema>;
 /**
  * The machine an agent works on. It is all or nothing: an agent either knows its environment
  * completely or not at all, so nothing it is told about the machine is ever half-true.
@@ -30,7 +30,7 @@ export declare const agentEnvironmentSchema: import("@sinclair/typebox").TObject
 export type AgentEnvironment = Static<typeof agentEnvironmentSchema>;
 /**
  * What an agent was created with: the environment it works on, when it has one, one opaque
- * settings map per feature, and descriptive metadata. Environment and feature settings stay
+ * settings map per module, and descriptive metadata. Environment and module settings stay
  * fixed; metadata changes only through the agent metadata API, which shallow-merges updates and
  * persists the resulting complete configuration.
  */
@@ -46,8 +46,8 @@ export declare const agentConfigSchema: import("@sinclair/typebox").TObject<{
         /** The shell the agent's commands run in, such as `/bin/zsh`. */
         shell: import("@sinclair/typebox").TString;
     }>>;
-    /** Per-feature settings, keyed by feature name; each entry is opaque to the agent. */
-    features: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>>;
+    /** Per-module settings, keyed by module name; each entry is opaque to the agent. */
+    modules: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>>;
     /** Immutable descriptive metadata, replaced only through a merged metadata update. */
     metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TIntersect<[import("@sinclair/typebox").TObject<{
         title: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -69,6 +69,6 @@ export declare function agentConfig(ctx: Context): AgentConfig | undefined;
 export declare function agentEnvironment(ctx: Context): AgentEnvironment | undefined;
 /** The immutable metadata describing the agent owning this context, when it has any. */
 export declare function agentMetadata(ctx: Context): AgentMetadata | undefined;
-/** The opaque settings the named feature was configured with, if it was configured at all. */
-export declare function agentFeatureConfig(ctx: Context, name: string): AgentFeatureConfig | undefined;
+/** The opaque settings the named module was configured with, if it was configured at all. */
+export declare function agentModuleConfig(ctx: Context, name: string): AgentModuleConfig | undefined;
 //# sourceMappingURL=AgentConfig.d.ts.map

package/dist/AgentConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentConfig.d.ts","sourceRoot":"","sources":["../sources/AgentConfig.ts"],"names":[],"mappings":"AAEA,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE1E,OAAO,EAAyC,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE/F,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,kjBAY9B,CAAC;AAEH,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAE/D;;;GAGG;AACH,eAAO,MAAM,wBAAwB,gHAA6C,CAAC;AAEnF,0EAA0E;AAC1E,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,sBAAsB;IAC/B,wEAAwE;;IAExE,8CAA8C;;IAE9C,uDAAuD;;IAEvD,iEAAiE;;EAEnE,CAAC;AAEH,wEAAwE;AACxE,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;IAC1B,qFAAqF;;QApBrF,wEAAwE;;QAExE,8CAA8C;;QAE9C,uDAAuD;;QAEvD,iEAAiE;;;IAgBjE,sFAAsF;;IAEtF,sFAAsF;;;;EAExF,CAAC;AAEH,mEAAmE;AACnE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAe3D;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,gBAAgB,CAQ1D;AAQD,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAE1E;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAEjE;AAED,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAE3E;AAED,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAErE;AAED,8FAA8F;AAC9F,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAE7F"}
+{"version":3,"file":"AgentConfig.d.ts","sourceRoot":"","sources":["../sources/AgentConfig.ts"],"names":[],"mappings":"AAEA,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE1E,OAAO,EAAyC,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE/F,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,kjBAY9B,CAAC;AAEH,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAE/D;;;GAGG;AACH,eAAO,MAAM,uBAAuB,gHAA6C,CAAC;AAElF,yEAAyE;AACzE,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAEvE;;;GAGG;AACH,eAAO,MAAM,sBAAsB;IAC/B,wEAAwE;;IAExE,8CAA8C;;IAE9C,uDAAuD;;IAEvD,iEAAiE;;EAEnE,CAAC;AAEH,wEAAwE;AACxE,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;IAC1B,qFAAqF;;QApBrF,wEAAwE;;QAExE,8CAA8C;;QAE9C,uDAAuD;;QAEvD,iEAAiE;;;IAgBjE,oFAAoF;;IAEpF,sFAAsF;;;;EAExF,CAAC;AAEH,mEAAmE;AACnE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAe3D;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,gBAAgB,CAQ1D;AAQD,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAE1E;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAEjE;AAED,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAE3E;AAED,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAErE;AAED,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAE3F"}

package/dist/AgentConfig.js

@@ -18,10 +18,10 @@ export const agentPlatformSchema = Type.Union([
     Type.Literal("win32"),
 ]);
 /**
- * The settings one feature was configured with. The agent never looks inside: a feature owns
+ * The settings one module was configured with. The agent never looks inside: a module owns
  * the shape of its own entry and validates it against its own schema.
  */
-export const agentFeatureConfigSchema = Type.Record(Type.String(), Type.Unknown());
+export const agentModuleConfigSchema = Type.Record(Type.String(), Type.Unknown());
 /**
  * The machine an agent works on. It is all or nothing: an agent either knows its environment
  * completely or not at all, so nothing it is told about the machine is ever half-true.
@@ -38,15 +38,15 @@ export const agentEnvironmentSchema = Type.Object({
 });
 /**
  * What an agent was created with: the environment it works on, when it has one, one opaque
- * settings map per feature, and descriptive metadata. Environment and feature settings stay
+ * settings map per module, and descriptive metadata. Environment and module settings stay
  * fixed; metadata changes only through the agent metadata API, which shallow-merges updates and
  * persists the resulting complete configuration.
  */
 export const agentConfigSchema = Type.Object({
     /** The machine this agent was told it works on, when it was told anything at all. */
     environment: Type.Optional(agentEnvironmentSchema),
-    /** Per-feature settings, keyed by feature name; each entry is opaque to the agent. */
-    features: Type.Optional(Type.Record(Type.String(), agentFeatureConfigSchema)),
+    /** Per-module settings, keyed by module name; each entry is opaque to the agent. */
+    modules: Type.Optional(Type.Record(Type.String(), agentModuleConfigSchema)),
     /** Immutable descriptive metadata, replaced only through a merged metadata update. */
     metadata: Type.Optional(agentMetadataSchema),
 });
@@ -94,8 +94,8 @@ export function agentEnvironment(ctx) {
 export function agentMetadata(ctx) {
     return configNamespace.get(ctx)?.metadata;
 }
-/** The opaque settings the named feature was configured with, if it was configured at all. */
-export function agentFeatureConfig(ctx, name) {
-    return configNamespace.get(ctx)?.features?.[name];
+/** The opaque settings the named module was configured with, if it was configured at all. */
+export function agentModuleConfig(ctx, name) {
+    return configNamespace.get(ctx)?.modules?.[name];
 }
 //# sourceMappingURL=AgentConfig.js.map

package/dist/AgentConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"AgentConfig.js","sourceRoot":"","sources":["../sources/AgentConfig.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AgentConfig.js","sourceRoot":"","sources":["../sources/AgentConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,OAAO,EAAE,IAAI,EAAe,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAgB,MAAM,oBAAoB,CAAC;AAE1E,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAsB,MAAM,oBAAoB,CAAC;AAE/F,uEAAuE;AACvE,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1C,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;IACnB,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;IACvB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;IACtB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;IACtB,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;IACvB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;IACrB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;IACrB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;IACtB,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;IACvB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;IACrB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;CACxB,CAAC,CAAC;AAKH;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;AAKlF;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC,MAAM,CAAC;IAC9C,wEAAwE;IACxE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE;IACxB,8CAA8C;IAC9C,QAAQ,EAAE,mBAAmB;IAC7B,uDAAuD;IACvD,gBAAgB,EAAE,IAAI,CAAC,MAAM,EAAE;IAC/B,iEAAiE;IACjE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAKH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,MAAM,CAAC;IACzC,qFAAqF;IACrF,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,sBAAsB,CAAC;IAClD,oFAAoF;IACpF,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,uBAAuB,CAAC,CAAC;IAC3E,sFAAsF;IACtF,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,mBAAmB,CAAC;CAC/C,CAAC,CAAC;AAKH,uFAAuF;AACvF,MAAM,UAAU,cAAc,CAAC,MAAmB;IAC9C,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,iBAAiB,EAAE,MAAM,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACnD,OAAO;QACH,GAAG,MAAM;QACT,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;KAClD,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB;IACnC,MAAM,QAAQ,GAAkB,OAAO,CAAC,QAAQ,CAAC;IACjD,OAAO;QACH,SAAS,EAAE,OAAO,EAAE;QACpB,QAAQ;QACR,gBAAgB,EAAE,OAAO,CAAC,GAAG,EAAE;QAC/B,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE;KACjC,CAAC;AACN,CAAC;AAED,mGAAmG;AACnG,MAAM,eAAe,GAAG,sBAAsB,CAC1C,4BAA4B,EAC5B,SAAS,CACZ,CAAC;AAEF,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,GAAY,EAAE,MAAmB;IAC7D,OAAO,eAAe,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,WAAW,CAAC,GAAY;IACpC,OAAO,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,gBAAgB,CAAC,GAAY;IACzC,OAAO,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC;AACjD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,aAAa,CAAC,GAAY;IACtC,OAAO,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC;AAC9C,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,iBAAiB,CAAC,GAAY,EAAE,IAAY;IACxD,OAAO,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;AACrD,CAAC"}

package/dist/AgentContexts.d.ts

@@ -1,12 +1,26 @@
 import type { SessionReasoningEffort, SessionServiceTier } from "@slopus/happy-providers";
 import { type Context } from "@steve.kite/stdlib";
+import type { AgentDatabase } from "./AgentDatabase.js";
 import type { AgentKV } from "./AgentKV.js";
 import { type AgentPermissionMode } from "./AgentPermissionMode.js";
+/** Storage-owned identity and lifetime of an active transaction facade. */
+export interface AgentStorageTransactionContext {
+    readonly database: AgentDatabase;
+    readonly root: AgentDatabase;
+    readonly lifetime: AbortSignal;
+}
+declare global {
+    namespace stdlib {
+        interface ContextExtensions {
+            readonly db: AgentDatabase;
+        }
+    }
+}
 /**
  * Derive the agent's context carrying its ID, provider ID, model, effort, service tier, and
  * permission mode — all serializable values. The agent applies this once at construction, so hooks
  * and tool executions can read the values back through the accessors below. The ID is what lets one
- * feature instance serve every agent in a collection: a shared feature learns which agent a hook is
+ * module instance serve every agent in a collection: a shared module learns which agent a hook is
  * running for from the context rather than from something it was constructed with.
  */
 export declare function withAgentContext(ctx: Context, values: {
@@ -51,4 +65,14 @@ export declare function agentKV(ctx: Context): AgentKV | undefined;
 export declare function withAgentRunKV(ctx: Context, kv: AgentKV): Context;
 /** The run's own store carried on this context, when the agent attached one. */
 export declare function agentRunKV(ctx: Context): AgentKV | undefined;
+/** Carry the active Drizzle database or transaction facade on a derived context. */
+export declare function withAgentDatabase(ctx: Context, database: AgentDatabase): Context;
+/** The active Drizzle database or transaction facade, when this work has durable storage. */
+export declare function agentDatabase(ctx: Context): AgentDatabase | undefined;
+/** Install the active facade for the duration of one transaction callback. */
+export declare function withAgentStorageTransaction(ctx: Context, transaction: AgentStorageTransactionContext): Context;
+/** The storage transaction carried by this context, including its ended state when retained. */
+export declare function agentStorageTransaction(ctx: Context): AgentStorageTransactionContext | undefined;
+/** Drop a caller's transaction lifetime when creating independently owned agent work. */
+export declare function withoutAgentStorageTransaction(ctx: Context): Context;
 //# sourceMappingURL=AgentContexts.d.ts.map

package/dist/AgentContexts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentContexts.d.ts","sourceRoot":"","sources":["../sources/AgentContexts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC1F,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE1E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAiC,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AA4BnG;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC5B,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE;IACJ,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,cAAc,EAAE,mBAAmB,CAAC;CAChD,GACF,OAAO,CAOT;AAED,+CAA+C;AAC/C,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAExD;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE3D;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,sBAAsB,GAAG,SAAS,CAE5E;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE9D;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAE7E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,mBAAmB,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAExF;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,OAAO,CAE9D;AAED,uFAAuF;AACvF,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,OAAO,CAEjE;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAE5D"}
+{"version":3,"file":"AgentContexts.d.ts","sourceRoot":"","sources":["../sources/AgentContexts.ts"],"names":[],"mappings":"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"}

package/dist/AgentContexts.js

@@ -1,4 +1,4 @@
-import { createContextNamespace } from "@steve.kite/stdlib";
+import { createContextNamespace, registerContextExtension } from "@steve.kite/stdlib";
 import { DEFAULT_AGENT_PERMISSION_MODE } from "./AgentPermissionMode.js";
 /** Backing storage for `agentId`: the ID of the agent owning a context. */
 const idNamespace = createContextNamespace("agentId", undefined);
@@ -16,11 +16,23 @@ const permissionModeNamespace = createContextNamespace("agentPermissionMode", DE
 const kvNamespace = createContextNamespace("agentKV", undefined);
 /** Backing storage for `agentRunKV`: the run's own store, erased when the agent settles. */
 const runKVNamespace = createContextNamespace("agentRunKV", undefined);
+const databaseNamespace = createContextNamespace("agentDatabase", undefined);
+const storageTransactionNamespace = createContextNamespace("agentStorageTransaction", undefined);
+registerContextExtension("db", (ctx) => {
+    const transaction = storageTransactionNamespace.get(ctx);
+    if (transaction?.lifetime.aborted === true) {
+        throw new Error("The agent storage transaction carried by this context has ended.");
+    }
+    const database = databaseNamespace.get(ctx);
+    if (database === undefined)
+        throw new Error("Context has no agent database.");
+    return database;
+});
 /**
  * Derive the agent's context carrying its ID, provider ID, model, effort, service tier, and
  * permission mode — all serializable values. The agent applies this once at construction, so hooks
  * and tool executions can read the values back through the accessors below. The ID is what lets one
- * feature instance serve every agent in a collection: a shared feature learns which agent a hook is
+ * module instance serve every agent in a collection: a shared module learns which agent a hook is
  * running for from the context rather than from something it was constructed with.
  */
 export function withAgentContext(ctx, values) {
@@ -87,4 +99,36 @@ export function withAgentRunKV(ctx, kv) {
 export function agentRunKV(ctx) {
     return runKVNamespace.get(ctx);
 }
+/** Carry the active Drizzle database or transaction facade on a derived context. */
+export function withAgentDatabase(ctx, database) {
+    const transaction = storageTransactionNamespace.get(ctx);
+    if (transaction !== undefined &&
+        (database === transaction.database || database === transaction.root)) {
+        return ctx;
+    }
+    return databaseNamespace.set(storageTransactionNamespace.set(ctx, undefined), database);
+}
+/** The active Drizzle database or transaction facade, when this work has durable storage. */
+export function agentDatabase(ctx) {
+    return databaseNamespace.get(ctx);
+}
+/** Install the active facade for the duration of one transaction callback. */
+export function withAgentStorageTransaction(ctx, transaction) {
+    if (databaseNamespace.get(ctx) !== transaction.root) {
+        throw new Error("A transaction context cannot be used with another agent storage.");
+    }
+    return storageTransactionNamespace.set(databaseNamespace.set(ctx, transaction.database), transaction);
+}
+/** The storage transaction carried by this context, including its ended state when retained. */
+export function agentStorageTransaction(ctx) {
+    return storageTransactionNamespace.get(ctx);
+}
+/** Drop a caller's transaction lifetime when creating independently owned agent work. */
+export function withoutAgentStorageTransaction(ctx) {
+    const transaction = storageTransactionNamespace.get(ctx);
+    const withoutTransaction = storageTransactionNamespace.set(ctx, undefined);
+    return transaction === undefined
+        ? withoutTransaction
+        : databaseNamespace.set(withoutTransaction, transaction.root);
+}
 //# sourceMappingURL=AgentContexts.js.map

package/dist/AgentContexts.js.map

@@ -1 +1 @@
-{"version":3,"file":"AgentContexts.js","sourceRoot":"","sources":["../sources/AgentContexts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAgB,MAAM,oBAAoB,CAAC;AAG1E,OAAO,EAAE,6BAA6B,EAA4B,MAAM,0BAA0B,CAAC;AAEnG,2EAA2E;AAC3E,MAAM,WAAW,GAAG,sBAAsB,CAAqB,SAAS,EAAE,SAAS,CAAC,CAAC;AACrF,8FAA8F;AAC9F,MAAM,cAAc,GAAG,sBAAsB,CAAqB,YAAY,EAAE,SAAS,CAAC,CAAC;AAC3F,4FAA4F;AAC5F,MAAM,eAAe,GAAG,sBAAsB,CAC1C,aAAa,EACb,SAAS,CACZ,CAAC;AACF,6FAA6F;AAC7F,MAAM,iBAAiB,GAAG,sBAAsB,CAAqB,eAAe,EAAE,SAAS,CAAC,CAAC;AACjG,6FAA6F;AAC7F,MAAM,oBAAoB,GAAG,sBAAsB,CAC/C,kBAAkB,EAClB,SAAS,CACZ,CAAC;AACF,2FAA2F;AAC3F,MAAM,uBAAuB,GAAG,sBAAsB,CAClD,qBAAqB,EACrB,6BAA6B,CAChC,CAAC;AACF,sFAAsF;AACtF,MAAM,WAAW,GAAG,sBAAsB,CAAsB,SAAS,EAAE,SAAS,CAAC,CAAC;AACtF,4FAA4F;AAC5F,MAAM,cAAc,GAAG,sBAAsB,CAAsB,YAAY,EAAE,SAAS,CAAC,CAAC;AAE5F;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC5B,GAAY,EACZ,MAOC;IAED,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,iBAAiB,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpE,MAAM,SAAS,GAAG,cAAc,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IACjE,MAAM,UAAU,GAAG,eAAe,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACjE,MAAM,QAAQ,GAAG,oBAAoB,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IAC1E,OAAO,uBAAuB,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;AACxE,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,OAAO,CAAC,GAAY;IAChC,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,UAAU,CAAC,GAAY;IACnC,OAAO,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,WAAW,CAAC,GAAY;IACpC,OAAO,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,aAAa,CAAC,GAAY;IACtC,OAAO,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACtC,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,gBAAgB,CAAC,GAAY;IACzC,OAAO,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC5C,OAAO,uBAAuB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAY,EAAE,IAAyB;IAC3E,OAAO,uBAAuB,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,WAAW,CAAC,GAAY,EAAE,EAAW;IACjD,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACpC,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,OAAO,CAAC,GAAY;IAChC,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY,EAAE,EAAW;IACpD,OAAO,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,UAAU,CAAC,GAAY;IACnC,OAAO,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC"}
+{"version":3,"file":"AgentContexts.js","sourceRoot":"","sources":["../sources/AgentContexts.ts"],"names":[],"mappings":"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"}

package/dist/AgentDatabase.d.ts

@@ -0,0 +1,35 @@
+import { type SQL } from "drizzle-orm";
+import { PgDatabase } from "drizzle-orm/pg-core";
+import { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
+import type { Context } from "@steve.kite/stdlib";
+/**
+ * Any asynchronous Drizzle SQLite database or transaction. The erased schema and result types
+ * deliberately preserve the complete Drizzle query-builder surface without choosing a driver.
+ */
+export type AgentSQLiteDatabase = BaseSQLiteDatabase<"async", any, any, any>;
+/**
+ * Any Drizzle PostgreSQL database or transaction, including PGlite. The concrete module generic
+ * retains the caller's exact database type when a module needs its own typed schema.
+ */
+export type AgentPostgresDatabase = PgDatabase<any, any, any>;
+/** A supported engine-agnostic Drizzle database or active transaction facade. */
+export type AgentDatabase = AgentSQLiteDatabase | AgentPostgresDatabase;
+/**
+ * The schema-aware Drizzle surface shared by a concrete root database and its transaction.
+ * Driver-only root members such as `batch` and `$client` are intentionally absent.
+ */
+export type AgentDatabaseFacade<Database extends AgentDatabase> = Database extends BaseSQLiteDatabase<infer ResultKind, infer RunResult, infer FullSchema, infer Schema> ? BaseSQLiteDatabase<ResultKind, RunResult, FullSchema, Schema> : Database extends PgDatabase<infer QueryResult, infer FullSchema, infer Schema> ? PgDatabase<QueryResult, FullSchema, Schema> : never;
+/** One ordered, durably tracked module migration. */
+export type AgentModuleMigration<Database extends AgentDatabase = AgentDatabase> = readonly [
+    key: string,
+    migrate: (ctx: Context, database: AgentDatabaseFacade<Database>) => void | Promise<void>
+];
+/** Work run inside the caller's outer transaction integration. */
+export type AgentStorageTransaction<Database extends AgentDatabase = AgentDatabase> = <Result>(ctx: Context, work: (ctx: Context, database: AgentDatabaseFacade<Database>) => Promise<Result>) => Promise<Result>;
+/** Whether a supported facade belongs to Drizzle's SQLite family. */
+export declare function isAgentSQLiteDatabase(database: AgentDatabase): database is AgentSQLiteDatabase;
+/** Run a query that returns rows on either supported Drizzle engine. */
+export declare function agentDatabaseRows<Row>(database: AgentDatabase, query: SQL): Promise<readonly Row[]>;
+/** Run a statement that does not need its returned rows. */
+export declare function agentDatabaseRun(database: AgentDatabase, query: SQL): Promise<void>;
+//# sourceMappingURL=AgentDatabase.d.ts.map

package/dist/AgentDatabase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentDatabase.d.ts","sourceRoot":"","sources":["../sources/AgentDatabase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,GAAG,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;GAGG;AAEH,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAE7E;;;GAGG;AAEH,MAAM,MAAM,qBAAqB,GAAG,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAE9D,iFAAiF;AACjF,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,qBAAqB,CAAC;AAExE;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,QAAQ,SAAS,aAAa,IAC1D,QAAQ,SAAS,kBAAkB,CAC/B,MAAM,UAAU,EAChB,MAAM,SAAS,EACf,MAAM,UAAU,EAChB,MAAM,MAAM,CACf,GACK,kBAAkB,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,GAC7D,QAAQ,SAAS,UAAU,CAAC,MAAM,WAAW,EAAE,MAAM,UAAU,EAAE,MAAM,MAAM,CAAC,GAC5E,UAAU,CAAC,WAAW,EAAE,UAAU,EAAE,MAAM,CAAC,GAC3C,KAAK,CAAC;AAElB,qDAAqD;AACrD,MAAM,MAAM,oBAAoB,CAAC,QAAQ,SAAS,aAAa,GAAG,aAAa,IAAI,SAAS;IACxF,GAAG,EAAE,MAAM;IACX,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,mBAAmB,CAAC,QAAQ,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAC3F,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,uBAAuB,CAAC,QAAQ,SAAS,aAAa,GAAG,aAAa,IAAI,CAAC,MAAM,EACzF,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,mBAAmB,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,KAC/E,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB,qEAAqE;AACrE,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,QAAQ,IAAI,mBAAmB,CAE9F;AAED,wEAAwE;AACxE,wBAAsB,iBAAiB,CAAC,GAAG,EACvC,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,GAAG,GACX,OAAO,CAAC,SAAS,GAAG,EAAE,CAAC,CAWzB;AAED,4DAA4D;AAC5D,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAMzF"}

package/dist/AgentDatabase.js

@@ -0,0 +1,30 @@
+import { is } from "drizzle-orm";
+import { PgDatabase } from "drizzle-orm/pg-core";
+import { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
+/** Whether a supported facade belongs to Drizzle's SQLite family. */
+export function isAgentSQLiteDatabase(database) {
+    return is(database, BaseSQLiteDatabase);
+}
+/** Run a query that returns rows on either supported Drizzle engine. */
+export async function agentDatabaseRows(database, query) {
+    if (isAgentSQLiteDatabase(database)) {
+        return await database.all(query);
+    }
+    const result = await database.execute(query);
+    if (Array.isArray(result))
+        return result;
+    const rows = Reflect.get(result, "rows");
+    if (!Array.isArray(rows)) {
+        throw new Error("The PostgreSQL Drizzle query did not return a row collection.");
+    }
+    return rows;
+}
+/** Run a statement that does not need its returned rows. */
+export async function agentDatabaseRun(database, query) {
+    if (isAgentSQLiteDatabase(database)) {
+        await database.run(query);
+        return;
+    }
+    await database.execute(query);
+}
+//# sourceMappingURL=AgentDatabase.js.map

package/dist/AgentDatabase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentDatabase.js","sourceRoot":"","sources":["../sources/AgentDatabase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAY,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAgD7D,qEAAqE;AACrE,MAAM,UAAU,qBAAqB,CAAC,QAAuB;IACzD,OAAO,EAAE,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC;AAC5C,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACnC,QAAuB,EACvB,KAAU;IAEV,IAAI,qBAAqB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClC,OAAO,MAAM,QAAQ,CAAC,GAAG,CAAM,KAAK,CAAC,CAAC;IAC1C,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,MAAe,CAAC;IAClD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,MAAgB,EAAE,MAAM,CAAC,CAAC;IACnD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,IAAa,CAAC;AACzB,CAAC;AAED,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,QAAuB,EAAE,KAAU;IACtE,IAAI,qBAAqB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClC,MAAM,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO;IACX,CAAC;IACD,MAAM,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC"}

package/dist/AgentKV.d.ts

@@ -1,21 +1,21 @@
-import { type Context } from "@steve.kite/stdlib";
+import { type AsyncLock, type Context } from "@steve.kite/stdlib";
 import type { AgentPersistence } from "./AgentPersistence.js";
 /**
  * A key-value store scoped under one prefix of the agent's sorted store. The agent carries a
- * session-scoped instance on its context, and narrows it for each caller: a feature works
+ * session-scoped instance on its context, and narrows it for each caller: a module works
  * under its own name, a tool execution under its call ID. Keys are always relative to the
  * scope — a holder can neither see nor touch anything outside it. Segments join with `.`.
  *
- * The object is nothing but a scope: every operation runs on the context it is given, so which
- * transaction a write joins and how long the handle stays usable are both decided by that
- * context and never by the handle.
+ * Every operation runs on the context it is given, so that context decides which transaction a
+ * write joins. Most handles also take their lifetime from that context; explicitly bounded
+ * handles, such as a tool call's KV, additionally become unusable when their owner ends.
  */
 export declare class AgentKV {
     #private;
     /** The absolute key prefix of this scope, ending with the separator. */
     readonly prefix: string;
     /** Build a scope over `prefix` of `persistence`. */
-    constructor(persistence: AgentPersistence, prefix: string);
+    constructor(persistence: AgentPersistence, prefix: string, available?: () => boolean, lock?: AsyncLock);
     /**
      * A narrower store under `segments` within this scope. Each segment is exactly one level:
      * a dot inside a segment is escaped, so the scope `alpha.beta` cannot be reached through
@@ -23,6 +23,12 @@ export declare class AgentKV {
      * their segment lists differ.
      */
     scoped(...segments: readonly string[]): AgentKV;
+    /**
+     * A handle to this exact scope that becomes permanently unusable when `signal` aborts.
+     * Narrower scopes inherit the same bound. Agent base uses this for call KV so no context can
+     * recreate invocation state after the winning result erases it.
+     */
+    until(signal: AbortSignal, available?: () => boolean): AgentKV;
     /** The stored value, or undefined when the key is absent. */
     read(ctx: Context, key: string): Promise<unknown>;
     /** Every entry under the scope — or under `prefix` within it — with scope-relative keys. */
@@ -38,6 +44,13 @@ export declare class AgentKV {
      * updater that throws leaves the stored value untouched.
      */
     update<Value>(ctx: Context, key: string, updater: (current: unknown) => Value | Promise<Value>): Promise<Value>;
+    /**
+     * Return the durable value already stored under `key`, or create and store it exactly once.
+     * The read and possible write share one persistence transaction, and an existing outer
+     * transaction is reused. A tool can use this on its call-bound KV for retry-stable operation
+     * identities without coupling them to a provider call ID.
+     */
+    getOrCreate<Value>(ctx: Context, key: string, create: () => Value | Promise<Value>): Promise<Value>;
     /**
      * Run work as one atomic step of the underlying store: everything it writes commits together,
      * and a thrown error leaves the store exactly as it was. The work is given this same scope and

package/dist/AgentKV.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentKV.d.ts","sourceRoot":"","sources":["../sources/AgentKV.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAEhE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAe9D;;;;;;;;;GASG;AACH,qBAAa,OAAO;;IAChB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAKxB,oDAAoD;IACpD,YAAY,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAGxD;IAED;;;;;OAKG;IACH,MAAM,CAAC,GAAG,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAK9C;IAED,6DAA6D;IACvD,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKtD;IAED,4FAA4F;IACtF,IAAI,CACN,GAAG,EAAE,OAAO,EACZ,MAAM,SAAK,GACZ,OAAO,CAAC,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC,CAIvE;IAED,wEAAwE;IAClE,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAGpE;IAED;;;;OAIG;IACG,MAAM,CAAC,KAAK,EACd,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GACtD,OAAO,CAAC,KAAK,CAAC,CAQhB;IAED;;;;;OAKG;IACG,WAAW,CAAC,MAAM,EACpB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,GACvD,OAAO,CAAC,MAAM,CAAC,CAWjB;IAED;;;;;OAKG;IACG,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvC;IAED,mDAAmD;IAC7C,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrD;CACJ"}
+{"version":3,"file":"AgentKV.d.ts","sourceRoot":"","sources":["../sources/AgentKV.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;;GASG;AACH,qBAAa,OAAO;;IAChB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IASxB,oDAAoD;IACpD,YACI,WAAW,EAAE,gBAAgB,EAC7B,MAAM,EAAE,MAAM,EACd,SAAS,gBAAa,EACtB,IAAI,CAAC,EAAE,SAAS,EAMnB;IAkBD;;;;;OAKG;IACH,MAAM,CAAC,GAAG,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAU9C;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,gBAAa,GAAG,OAAO,CAO1D;IAED,6DAA6D;IACvD,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMtD;IAED,4FAA4F;IACtF,IAAI,CACN,GAAG,EAAE,OAAO,EACZ,MAAM,SAAK,GACZ,OAAO,CAAC,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC,CAQvE;IAED,wEAAwE;IAClE,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpE;IAED;;;;OAIG;IACG,MAAM,CAAC,KAAK,EACd,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GACtD,OAAO,CAAC,KAAK,CAAC,CAShB;IAED;;;;;OAKG;IACG,WAAW,CAAC,KAAK,EACnB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GACrC,OAAO,CAAC,KAAK,CAAC,CAoBhB;IAED;;;;;OAKG;IACG,WAAW,CAAC,MAAM,EACpB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,GACvD,OAAO,CAAC,MAAM,CAAC,CAWjB;IAED;;;;;OAKG;IACG,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAOvC;IAED,mDAAmD;IAC7C,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIrD;CAwBJ"}

package/dist/AgentKV.js

@@ -1,35 +1,39 @@
-import { withLifetime } from "@steve.kite/stdlib";
-/**
- * Refuse a store operation whose context has already ended. What a holder of a store may do is
- * decided by the context it is given rather than by the object: a store used inside a transaction,
- * or handed to a tool for the length of its turn, keeps working exactly as long as that work
- * does. Using it afterwards is a mistake in the caller, and says so instead of quietly writing
- * into a transaction that has committed or a turn that was cancelled.
- */
-function assertLive(ctx) {
-    if (ctx.lifetime?.aborted === true) {
-        throw new Error("The store cannot be used: the work its context belongs to has ended.");
-    }
-}
+import { asyncLock, withLifetime } from "@steve.kite/stdlib";
 /**
  * A key-value store scoped under one prefix of the agent's sorted store. The agent carries a
- * session-scoped instance on its context, and narrows it for each caller: a feature works
+ * session-scoped instance on its context, and narrows it for each caller: a module works
  * under its own name, a tool execution under its call ID. Keys are always relative to the
  * scope — a holder can neither see nor touch anything outside it. Segments join with `.`.
  *
- * The object is nothing but a scope: every operation runs on the context it is given, so which
- * transaction a write joins and how long the handle stays usable are both decided by that
- * context and never by the handle.
+ * Every operation runs on the context it is given, so that context decides which transaction a
+ * write joins. Most handles also take their lifetime from that context; explicitly bounded
+ * handles, such as a tool call's KV, additionally become unusable when their owner ends.
  */
 export class AgentKV {
     /** The absolute key prefix of this scope, ending with the separator. */
     prefix;
     /** The append-only store this scope reads and writes through. */
     #persistence;
+    /** An object-owned lifetime used by bounded stores such as one tool invocation's KV. */
+    #available;
+    /** Serializes this scope tree so disposal always follows every write that already started. */
+    #lock;
     /** Build a scope over `prefix` of `persistence`. */
-    constructor(persistence, prefix) {
+    constructor(persistence, prefix, available = () => true, lock) {
         this.#persistence = persistence;
         this.prefix = prefix;
+        this.#available = available;
+        this.#lock = lock;
+    }
+    /**
+     * A handle to this scope whose operations serialize with all descendants derived from it.
+     * Agent base uses this only for one tool call, so disposal can drain writes already in flight
+     * without serializing unrelated module and agent stores.
+     *
+     * @internal
+     */
+    serialized() {
+        return new AgentKV(this.#persistence, this.prefix, this.#available, asyncLock({ reentry: "block" }));
     }
     /**
      * A narrower store under `segments` within this scope. Each segment is exactly one level:
@@ -39,25 +43,39 @@ export class AgentKV {
      */
     scoped(...segments) {
         const escaped = segments.map((segment) => segment.replaceAll("%", "%25").replaceAll(".", "%2E"));
-        return new AgentKV(this.#persistence, `${this.prefix}${escaped.join(".")}.`);
+        return new AgentKV(this.#persistence, `${this.prefix}${escaped.join(".")}.`, this.#available, this.#lock);
+    }
+    /**
+     * A handle to this exact scope that becomes permanently unusable when `signal` aborts.
+     * Narrower scopes inherit the same bound. Agent base uses this for call KV so no context can
+     * recreate invocation state after the winning result erases it.
+     */
+    until(signal, available = () => true) {
+        return new AgentKV(this.#persistence, this.prefix, () => this.#available() && !signal.aborted && available(), this.#lock);
     }
     /** The stored value, or undefined when the key is absent. */
     async read(ctx, key) {
-        assertLive(ctx);
-        const full = `${this.prefix}${key}`;
-        const entries = await this.#persistence.readValues(ctx, full);
-        return entries.find((entry) => entry.key === full)?.value;
+        return await this.#locked(ctx, async (lockCtx) => {
+            const full = `${this.prefix}${key}`;
+            const entries = await this.#persistence.readValues(lockCtx, full);
+            return entries.find((entry) => entry.key === full)?.value;
+        });
     }
     /** Every entry under the scope — or under `prefix` within it — with scope-relative keys. */
     async list(ctx, prefix = "") {
-        assertLive(ctx);
-        const entries = await this.#persistence.readValues(ctx, `${this.prefix}${prefix}`);
-        return entries.map(({ key, value }) => ({ key: key.slice(this.prefix.length), value }));
+        return await this.#locked(ctx, async (lockCtx) => {
+            const entries = await this.#persistence.readValues(lockCtx, `${this.prefix}${prefix}`);
+            return entries.map(({ key, value }) => ({
+                key: key.slice(this.prefix.length),
+                value,
+            }));
+        });
     }
     /** Store the value under `key`, replacing whatever was there before. */
     async write(ctx, key, value) {
-        assertLive(ctx);
-        await this.#persistence.writeValue(ctx, `${this.prefix}${key}`, value);
+        await this.#locked(ctx, async (lockCtx) => {
+            await this.#persistence.writeValue(lockCtx, `${this.prefix}${key}`, value);
+        });
     }
     /**
      * Read, decide, and write, so the value the updater sees is exactly the value it replaces.
@@ -65,13 +83,39 @@ export class AgentKV {
      * updater that throws leaves the stored value untouched.
      */
     async update(ctx, key, updater) {
-        assertLive(ctx);
-        const full = `${this.prefix}${key}`;
-        const entries = await this.#persistence.readValues(ctx, full);
-        const current = entries.find((entry) => entry.key === full)?.value;
-        const next = await updater(current);
-        await this.#persistence.writeValue(ctx, full, next);
-        return next;
+        return await this.#locked(ctx, async (lockCtx) => {
+            const full = `${this.prefix}${key}`;
+            const entries = await this.#persistence.readValues(lockCtx, full);
+            const current = entries.find((entry) => entry.key === full)?.value;
+            const next = await updater(current);
+            await this.#persistence.writeValue(lockCtx, full, next);
+            return next;
+        });
+    }
+    /**
+     * Return the durable value already stored under `key`, or create and store it exactly once.
+     * The read and possible write share one persistence transaction, and an existing outer
+     * transaction is reused. A tool can use this on its call-bound KV for retry-stable operation
+     * identities without coupling them to a provider call ID.
+     */
+    async getOrCreate(ctx, key, create) {
+        return await this.#locked(ctx, async (lockCtx) => {
+            return await this.#persistence.transaction(lockCtx, async (txCtx) => {
+                const full = `${this.prefix}${key}`;
+                const entries = await this.#persistence.readValues(txCtx, full);
+                const existing = entries.find((entry) => entry.key === full);
+                if (existing !== undefined)
+                    return existing.value;
+                const value = await create();
+                if (await this.#persistence.writeValueIfAbsent(txCtx, full, value))
+                    return value;
+                const winner = (await this.#persistence.readValues(txCtx, full)).find((entry) => entry.key === full);
+                if (winner === undefined) {
+                    throw new Error("The durable get-or-create value disappeared before it was read.");
+                }
+                return winner.value;
+            });
+        });
     }
     /**
      * Run work as one atomic step of the underlying store: everything it writes commits together,
@@ -80,7 +124,7 @@ export class AgentKV {
      * cannot be written into after it has committed.
      */
     async transaction(ctx, work) {
-        assertLive(ctx);
+        this.#assertLive(ctx);
         return await this.#persistence.transaction(ctx, async (txCtx) => {
             const committed = new AbortController();
             const liveCtx = withLifetime(txCtx, committed.signal);
@@ -99,16 +143,39 @@ export class AgentKV {
      * write.
      */
     async clear(ctx) {
-        assertLive(ctx);
-        const entries = await this.#persistence.readValues(ctx, this.prefix);
-        for (const entry of entries) {
-            await this.#persistence.deleteValue(ctx, entry.key);
-        }
+        await this.#locked(ctx, async (lockCtx) => {
+            const entries = await this.#persistence.readValues(lockCtx, this.prefix);
+            for (const entry of entries) {
+                await this.#persistence.deleteValue(lockCtx, entry.key);
+            }
+        });
     }
     /** Remove the entry stored under `key`, if any. */
     async delete(ctx, key) {
-        assertLive(ctx);
-        await this.#persistence.deleteValue(ctx, `${this.prefix}${key}`);
+        await this.#locked(ctx, async (lockCtx) => {
+            await this.#persistence.deleteValue(lockCtx, `${this.prefix}${key}`);
+        });
+    }
+    /** Re-check availability only after every earlier operation in this scope tree has finished. */
+    async #locked(ctx, work) {
+        if (this.#lock === undefined) {
+            this.#assertLive(ctx);
+            return await work(ctx);
+        }
+        return await this.#lock.runInLock(ctx, async (lockCtx) => {
+            this.#assertLive(lockCtx);
+            return await work(lockCtx);
+        });
+    }
+    /**
+     * Refuse a store operation when either its caller-owned context or this bounded handle has
+     * ended. The latter is what makes call KV stay erased even if retained code supplies a fresh
+     * unrelated context after commit.
+     */
+    #assertLive(ctx) {
+        if (ctx.lifetime?.aborted === true || !this.#available()) {
+            throw new Error("The store cannot be used: the work its context belongs to has ended.");
+        }
     }
 }
 //# sourceMappingURL=AgentKV.js.map