@slopus/happy-agent-base 0.0.5 → 0.0.7

package/dist/AgentBasePending.js

@@ -1,5 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { Value } from "@sinclair/typebox/value";
+import { cuid2Schema } from "./AgentMetadata.js";
 /**
  * The one key an agent's outstanding work lives under, in the agent's own store. It is a single
  * key rather than a prefix of many, because what it records is one fact — that this agent has
@@ -19,6 +20,8 @@ export const AgentBasePendingStage = Type.Union([
     Type.Literal("tools"),
     /** The conversation is being replaced by the provider's summary of it. */
     Type.Literal("compaction"),
+    /** The loop has ended and its durable settlement transaction remains to commit. */
+    Type.Literal("settlement"),
 ]);
 /**
  * The agent's outstanding work, as the run itself recorded it. Its presence is the whole of the
@@ -28,6 +31,10 @@ export const AgentBasePendingStage = Type.Union([
  */
 export const AgentBasePendingState = Type.Object({
     stage: AgentBasePendingStage,
+    loopId: cuid2Schema,
+    turnId: Type.Optional(cuid2Schema),
+    inferenceId: Type.Optional(cuid2Schema),
+    settlementId: Type.Optional(cuid2Schema),
 });
 /**
  * Read one store's pending state, or undefined when it holds none. Anything stored under the key

package/dist/AgentBasePending.js.map

@@ -1 +1 @@
-{"version":3,"file":"AgentBasePending.js","sourceRoot":"","sources":["../sources/AgentBasePending.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAe,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAKhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC,KAAK,CAAC;IAC5C,uFAAuF;IACvF,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;IACzB,oEAAoE;IACpE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;IACrB,0EAA0E;IAC1E,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC;CAC7B,CAAC,CAAC;AAGH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC,MAAM,CAAC;IAC7C,KAAK,EAAE,qBAAqB;CAC/B,CAAC,CAAC;AAGH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CACzC,GAAY,EACZ,WAA6B;IAE7B,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,UAAU,CAAC,GAAG,EAAE,sBAAsB,CAAC,CAAC;IAC1E,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,KAAK,sBAAsB,CAAC,EAAE,KAAK,CAAC;IACpF,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,qBAAqB,EAAE,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAClE,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CACxC,GAAY,EACZ,WAA6B;IAE7B,IAAI,CAAC,MAAM,uBAAuB,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACjF,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACrC,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;AAClF,CAAC"}
+{"version":3,"file":"AgentBasePending.js","sourceRoot":"","sources":["../sources/AgentBasePending.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAe,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAIhD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC,KAAK,CAAC;IAC5C,uFAAuF;IACvF,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;IACzB,oEAAoE;IACpE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;IACrB,0EAA0E;IAC1E,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC;IAC1B,mFAAmF;IACnF,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC;CAC7B,CAAC,CAAC;AAGH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC,MAAM,CAAC;IAC7C,KAAK,EAAE,qBAAqB;IAC5B,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;IAClC,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;IACvC,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;CAC3C,CAAC,CAAC;AAGH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CACzC,GAAY,EACZ,WAA6B;IAE7B,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,UAAU,CAAC,GAAG,EAAE,sBAAsB,CAAC,CAAC;IAC1E,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,KAAK,sBAAsB,CAAC,EAAE,KAAK,CAAC;IACpF,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,qBAAqB,EAAE,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAClE,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CACxC,GAAY,EACZ,WAA6B;IAE7B,IAAI,CAAC,MAAM,uBAAuB,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACjF,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACrC,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;AAClF,CAAC"}

package/dist/AgentConfig.d.ts

@@ -1,16 +1,17 @@
 import { type Static } from "@sinclair/typebox";
 import { type Context } from "@steve.kite/stdlib";
+import { type AgentMetadata } from "./AgentMetadata.js";
 /** The operating systems Node reports, mirroring `NodeJS.Platform`. */
 export declare const agentPlatformSchema: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"aix">, import("@sinclair/typebox").TLiteral<"android">, import("@sinclair/typebox").TLiteral<"cygwin">, import("@sinclair/typebox").TLiteral<"darwin">, import("@sinclair/typebox").TLiteral<"freebsd">, import("@sinclair/typebox").TLiteral<"haiku">, import("@sinclair/typebox").TLiteral<"linux">, import("@sinclair/typebox").TLiteral<"netbsd">, import("@sinclair/typebox").TLiteral<"openbsd">, import("@sinclair/typebox").TLiteral<"sunos">, import("@sinclair/typebox").TLiteral<"win32">]>;
 /** 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.
@@ -28,10 +29,10 @@ export declare const agentEnvironmentSchema: import("@sinclair/typebox").TObject
 /** The TypeScript type inferred from {@link agentEnvironmentSchema}. */
 export type AgentEnvironment = Static<typeof agentEnvironmentSchema>;
 /**
- * What an agent was created with: the environment it works on, when it has one, and one opaque
- * settings map per feature, keyed by the feature's name. The configuration is static for the
- * agent's whole life and is persisted when the agent is created, so a later process resolves
- * the very same agent it was created as.
+ * What an agent was created with: the environment it works on, when it has one, one opaque
+ * 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 declare const agentConfigSchema: import("@sinclair/typebox").TObject<{
     /** The machine this agent was told it works on, when it was told anything at all. */
@@ -45,8 +46,12 @@ 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>;
+    }>, import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TRecursive<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TNull, import("@sinclair/typebox").TArray<import("@sinclair/typebox").TThis>, import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TThis>]>>>]>>;
 }>;
 /** The TypeScript type inferred from {@link agentConfigSchema}. */
 export type AgentConfig = Static<typeof agentConfigSchema>;
@@ -56,12 +61,14 @@ export type AgentConfig = Static<typeof agentConfigSchema>;
  * than slipping into a persisted configuration; an unset `SHELL` reports as no shell at all.
  */
 export declare function currentAgentEnvironment(): AgentEnvironment;
-/** Carry the configuration an agent was created with; every hook and tool reads it back. */
+/** Carry the agent's current configuration; every hook and tool reads it back. */
 export declare function withAgentConfig(ctx: Context, config: AgentConfig): Context;
 /** The configuration of the agent owning this context, when one was attached. */
 export declare function agentConfig(ctx: Context): AgentConfig | undefined;
 /** The environment of the agent owning this context, when it was created with one. */
 export declare function agentEnvironment(ctx: Context): AgentEnvironment | 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 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 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;AACtD,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE1E,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;;EAExF,CAAC;AAEH,mEAAmE;AACnE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE3D;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,gBAAgB,CAQ1D;AAQD,4FAA4F;AAC5F,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,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

@@ -1,6 +1,8 @@
 import { release } from "node:os";
 import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
 import { createContextNamespace } from "@steve.kite/stdlib";
+import { agentMetadataSchema, ownAgentMetadata } from "./AgentMetadata.js";
 /** The operating systems Node reports, mirroring `NodeJS.Platform`. */
 export const agentPlatformSchema = Type.Union([
     Type.Literal("aix"),
@@ -16,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.
@@ -35,17 +37,31 @@ export const agentEnvironmentSchema = Type.Object({
     shell: Type.String(),
 });
 /**
- * What an agent was created with: the environment it works on, when it has one, and one opaque
- * settings map per feature, keyed by the feature's name. The configuration is static for the
- * agent's whole life and is persisted when the agent is created, so a later process resolves
- * the very same agent it was created as.
+ * What an agent was created with: the environment it works on, when it has one, one opaque
+ * 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),
 });
+/** @internal Validate and own one configuration while deeply freezing its metadata. */
+export function ownAgentConfig(config) {
+    if (!Value.Check(agentConfigSchema, config)) {
+        throw new Error("The agent configuration is not valid.");
+    }
+    const cloned = structuredClone(config);
+    const metadata = ownAgentMetadata(cloned.metadata);
+    return {
+        ...cloned,
+        ...(metadata === undefined ? {} : { metadata }),
+    };
+}
 /**
  * The environment this process is running in, ready to be handed to an agent at creation. The
  * platform is typed, so a Node release reporting an unknown platform fails to compile rather
@@ -62,7 +78,7 @@ export function currentAgentEnvironment() {
 }
 /** The context slot the agent's configuration is carried in, unset until an agent attaches one. */
 const configNamespace = createContextNamespace("happyAgentBase.agentConfig", undefined);
-/** Carry the configuration an agent was created with; every hook and tool reads it back. */
+/** Carry the agent's current configuration; every hook and tool reads it back. */
 export function withAgentConfig(ctx, config) {
     return configNamespace.set(ctx, config);
 }
@@ -74,8 +90,12 @@ export function agentConfig(ctx) {
 export function agentEnvironment(ctx) {
     return configNamespace.get(ctx)?.environment;
 }
-/** 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 immutable metadata describing the agent owning this context, when it has any. */
+export function agentMetadata(ctx) {
+    return configNamespace.get(ctx)?.metadata;
+}
+/** 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":"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"}

package/dist/AgentContexts.d.ts

@@ -1,12 +1,19 @@
 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 lifetime: AbortSignal;
+    readonly owner: object;
+}
 /**
  * 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 +58,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 and its owning storage 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

@@ -16,11 +16,14 @@ 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);
+/** Backing storage for the active Drizzle database or transaction facade. */
+const databaseNamespace = createContextNamespace("agentDatabase", undefined);
+const storageTransactionNamespace = createContextNamespace("agentStorageTransaction", undefined);
 /**
  * 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 +90,24 @@ 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) {
+    return databaseNamespace.set(ctx, 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 and its owning storage for the duration of one transaction callback. */
+export function withAgentStorageTransaction(ctx, transaction) {
+    return storageTransactionNamespace.set(withAgentDatabase(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) {
+    return storageTransactionNamespace.set(ctx, undefined);
+}
 //# sourceMappingURL=AgentContexts.js.map

package/dist/AgentContexts.js.map

@@ -1 +1 @@
-{"version":3,"file":"AgentContexts.js","sourceRoot":"","sources":["../sources/AgentContexts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AgentContexts.js","sourceRoot":"","sources":["../sources/AgentContexts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAgB,MAAM,oBAAoB,CAAC;AAI1E,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;AAC5F,6EAA6E;AAC7E,MAAM,iBAAiB,GAAG,sBAAsB,CAC5C,eAAe,EACf,SAAS,CACZ,CAAC;AAOF,MAAM,2BAA2B,GAAG,sBAAsB,CAExD,yBAAyB,EAAE,SAAS,CAAC,CAAC;AAExC;;;;;;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;AAED,oFAAoF;AACpF,MAAM,UAAU,iBAAiB,CAAC,GAAY,EAAE,QAAuB;IACnE,OAAO,iBAAiB,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAChD,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,aAAa,CAAC,GAAY;IACtC,OAAO,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACtC,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,2BAA2B,CACvC,GAAY,EACZ,WAA2C;IAE3C,OAAO,2BAA2B,CAAC,GAAG,CAClC,iBAAiB,CAAC,GAAG,EAAE,WAAW,CAAC,QAAQ,CAAC,EAC5C,WAAW,CACd,CAAC;AACN,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,uBAAuB,CACnC,GAAY;IAEZ,OAAO,2BAA2B,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAChD,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,8BAA8B,CAAC,GAAY;IACvD,OAAO,2BAA2B,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;AAC3D,CAAC"}

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"}