@microsoft/agents-hosting 1.9.0-beta.8.gf58e66b2ee → 1.9.1

package/dist/src/outboundHostValidator.js

@@ -7,7 +7,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OutboundHostValidator = void 0;
 exports.loadOutboundHostValidatorOptionsFromEnv = loadOutboundHostValidatorOptionsFromEnv;
 exports.createOutboundHostValidator = createOutboundHostValidator;
-const env_1 = require("./utils/env");
+const configuration_1 = require("./configuration/configuration");
+const environmentConfiguration_1 = require("./configuration/environmentConfiguration");
+const utils_1 = require("./utils");
 /** Hosts used by Microsoft channel callbacks and hosted attachments. */
 const DEFAULT_MICROSOFT_HOSTS = Object.freeze([
     'botframework.com',
@@ -19,8 +21,6 @@ const DEFAULT_MICROSOFT_HOSTS = Object.freeze([
     'svc.ms',
     'blob.core.windows.net'
 ]);
-const OUTBOUND_HOST_VALIDATOR_ENV_PREFIX = 'OutboundHostValidator__';
-const OUTBOUND_HOST_VALIDATOR_ENV_PREFIX_UPPER = OUTBOUND_HOST_VALIDATOR_ENV_PREFIX.toUpperCase();
 /**
  * Shared allowlist policy for server-side outbound requests.
  *
@@ -30,13 +30,16 @@ const OUTBOUND_HOST_VALIDATOR_ENV_PREFIX_UPPER = OUTBOUND_HOST_VALIDATOR_ENV_PRE
 class OutboundHostValidator {
     constructor(options = {}) {
         var _a, _b, _c;
-        this.enabled = (_a = options.enabled) !== null && _a !== void 0 ? _a : false;
+        const resolved = options.configurationContext
+            ? resolveOutboundHostValidatorOptions(options)
+            : options;
+        this.enabled = (_a = resolved.enabled) !== null && _a !== void 0 ? _a : false;
         const suffixes = new Set();
-        if ((_b = options.includeDefaultMicrosoftHosts) !== null && _b !== void 0 ? _b : true) {
+        if ((_b = resolved.includeDefaultMicrosoftHosts) !== null && _b !== void 0 ? _b : true) {
             for (const host of DEFAULT_MICROSOFT_HOSTS)
                 suffixes.add(host);
         }
-        for (const host of (_c = options.hosts) !== null && _c !== void 0 ? _c : []) {
+        for (const host of (_c = resolved.hosts) !== null && _c !== void 0 ? _c : []) {
             const normalized = normalizeConfiguredHost(host);
             if (normalized)
                 suffixes.add(normalized);
@@ -65,50 +68,24 @@ exports.OutboundHostValidator = OutboundHostValidator;
  * indexed values such as `Hosts__0`, `Hosts__1`, and so on.
  */
 function loadOutboundHostValidatorOptionsFromEnv() {
-    const result = {};
-    const indexedHosts = new Map();
-    const hosts = [];
-    for (const [envKey, rawValue] of Object.entries(process.env)) {
-        const upperKey = envKey.toUpperCase();
-        if (!upperKey.startsWith(OUTBOUND_HOST_VALIDATOR_ENV_PREFIX_UPPER))
-            continue;
-        const property = envKey.substring(OUTBOUND_HOST_VALIDATOR_ENV_PREFIX.length);
-        const upperProperty = property.toUpperCase();
-        if (upperProperty === 'ENABLED') {
-            const value = (0, env_1.parseBooleanEnv)(rawValue);
-            if (value !== undefined)
-                result.enabled = value;
-        }
-        else if (upperProperty === 'INCLUDEDEFAULTMICROSOFTHOSTS') {
-            const value = (0, env_1.parseBooleanEnv)(rawValue);
-            if (value !== undefined)
-                result.includeDefaultMicrosoftHosts = value;
-        }
-        else if (upperProperty === 'HOSTS' && rawValue) {
-            hosts.push(...rawValue.split(',').map(host => host.trim()).filter(Boolean));
-        }
-        else {
-            const match = /^HOSTS__(\d+)$/i.exec(property);
-            if (match && (rawValue === null || rawValue === void 0 ? void 0 : rawValue.trim()))
-                indexedHosts.set(Number(match[1]), rawValue.trim());
-        }
-    }
-    for (const [, host] of [...indexedHosts.entries()].sort(([left], [right]) => left - right)) {
-        hosts.push(host);
-    }
-    if (hosts.length > 0)
-        result.hosts = hosts;
-    return result;
+    return { ...(0, environmentConfiguration_1.loadModernEnvironmentConfiguration)().outboundHostValidator };
 }
-/** Creates the default validator, with explicit settings overriding the environment. */
-function createOutboundHostValidator(options) {
-    var _a, _b, _c;
+/** Creates a validator using the shared configuration precedence. */
+function createOutboundHostValidator(options = {}) {
+    return new OutboundHostValidator(resolveOutboundHostValidatorOptions(options));
+}
+function resolveOutboundHostValidatorOptions(options) {
+    const external = (0, configuration_1.getConfigurationSnapshot)(options.configurationContext);
     const fromEnv = loadOutboundHostValidatorOptionsFromEnv();
-    return new OutboundHostValidator({
-        enabled: (_a = options === null || options === void 0 ? void 0 : options.enabled) !== null && _a !== void 0 ? _a : fromEnv.enabled,
-        includeDefaultMicrosoftHosts: (_b = options === null || options === void 0 ? void 0 : options.includeDefaultMicrosoftHosts) !== null && _b !== void 0 ? _b : fromEnv.includeDefaultMicrosoftHosts,
-        hosts: (_c = options === null || options === void 0 ? void 0 : options.hosts) !== null && _c !== void 0 ? _c : fromEnv.hosts
-    });
+    const direct = {};
+    if (options.enabled !== undefined)
+        direct.enabled = options.enabled;
+    if (options.includeDefaultMicrosoftHosts !== undefined) {
+        direct.includeDefaultMicrosoftHosts = options.includeDefaultMicrosoftHosts;
+    }
+    if (options.hosts !== undefined)
+        direct.hosts = options.hosts;
+    return (0, utils_1.mergeDefined)(external.fallback.outboundHostValidator, fromEnv, external.overrideEnvironment.outboundHostValidator, direct, external.enforce.outboundHostValidator);
 }
 function getUrlHost(input) {
     if (!input)

package/dist/src/outboundHostValidator.js.map

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

package/dist/src/state/agentState.d.ts

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Licensed under the MIT License.
  */
-import { Storage, StorageKeyFactory } from '../storage/storage';
+import { StorageKeyFactory, StorageProvider } from '../storage/storage';
 import { TurnContext } from '../turnContext';
 import { AgentStatePropertyAccessor } from './agentStatePropertyAccesor';
 /**
@@ -22,6 +22,10 @@ export interface CachedAgentState {
      * Hash of the state used to detect changes
      */
     hash: string;
+    /** Version returned when the state was loaded, used to reject stale V2 writes. */
+    version?: string;
+    /** Whether the state was not found when it was loaded. */
+    isNew?: boolean;
 }
 /**
  * Represents a custom key for storing state in a specific location.
@@ -54,16 +58,17 @@ export interface CustomKey {
  * for typed access to state properties.
  */
 export declare class AgentState {
-    protected storage: Storage;
+    protected storage: StorageProvider;
     protected storageKey: StorageKeyFactory;
     private readonly stateKey;
+    private get internalStorage();
     /**
      * Creates a new instance of AgentState.
      *
      * @param storage The storage provider used to persist state between turns
      * @param storageKey A factory function that generates keys for storing state data
      */
-    constructor(storage: Storage, storageKey: StorageKeyFactory);
+    constructor(storage: StorageProvider, storageKey: StorageKeyFactory);
     /**
      * Creates a property accessor for the specified property.
      *

package/dist/src/state/agentState.js

@@ -5,6 +5,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentState = void 0;
+const storage_1 = require("../storage/storage");
+const storageCompatibility_1 = require("../storage/storageCompatibility");
 const node_crypto_1 = require("node:crypto");
 const agentStatePropertyAccesor_1 = require("./agentStatePropertyAccesor");
 const agents_telemetry_1 = require("@microsoft/agents-telemetry");
@@ -19,6 +21,9 @@ const logger = (0, agents_telemetry_1.debug)('agents:state');
  * for typed access to state properties.
  */
 class AgentState {
+    get internalStorage() {
+        return (0, storageCompatibility_1.asStorageV2)(this.storage);
+    }
     /**
      * Creates a new instance of AgentState.
      *
@@ -84,14 +89,21 @@ class AgentState {
      * If state is already cached in the turn context and force is not set, the cached version will be used.
      */
     async load(context, force = false, customKey) {
+        var _a, _b;
+        var _c;
         const cached = context.turnState.get(this.stateKey);
         if (force || !cached || !cached.state) {
             const key = await this.getStorageOrCustomKey(customKey, context);
             logger.info(`Reading storage with key ${key}`);
-            const storedItem = await this.storage.read([key]);
-            const state = storedItem[key] || {};
+            const storedItems = await this.internalStorage.read([key]);
+            const state = (_c = (0, storageCompatibility_1.getStorageReadValue)(storedItems, key)) !== null && _c !== void 0 ? _c : {};
             const hash = this.calculateChangeHash(state);
-            context.turnState.set(this.stateKey, { state, hash });
+            context.turnState.set(this.stateKey, {
+                state,
+                hash,
+                version: (_a = storedItems[key]) === null || _a === void 0 ? void 0 : _a.version,
+                isNew: ((_b = storedItems[key]) === null || _b === void 0 ? void 0 : _b.status) === storage_1.StorageOperationStatus.NotFound,
+            });
             return state;
         }
         return cached.state;
@@ -113,12 +125,17 @@ class AgentState {
             if (!cached) {
                 cached = { state: {}, hash: '' };
             }
-            cached.state.eTag = '*';
-            const changes = {};
             const key = await this.getStorageOrCustomKey(customKey, context);
-            changes[key] = cached.state;
             logger.info(`Writing storage with key ${key}`);
-            await this.storage.write(changes);
+            const results = await this.internalStorage.write({ [key]: cached.state }, cached.version !== undefined
+                ? { expectedVersion: cached.version }
+                : cached.isNew && (0, storageCompatibility_1.isStorageV2)(this.storage)
+                    ? { mode: storage_1.StorageWriteMode.CreateOnly }
+                    : undefined);
+            (0, storageCompatibility_1.assertAgentStateWriteSucceeded)(results, key, this.constructor.name);
+            const result = results[key];
+            cached.version = result.version;
+            cached.isNew = false;
             cached.hash = this.calculateChangeHash(cached.state);
             context.turnState.set(this.stateKey, cached);
         }
@@ -172,7 +189,8 @@ class AgentState {
         }
         const key = await this.getStorageOrCustomKey(customKey, context);
         logger.info(`Deleting storage with key ${key}`);
-        await this.storage.delete([key]);
+        const results = await this.internalStorage.delete([key]);
+        (0, storageCompatibility_1.assertStorageDeleteSucceeded)(results, [key]);
     }
     /**
      * Gets the state from the turn context without loading it from storage.

package/dist/src/state/agentState.js.map

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

package/dist/src/state/conversationState.d.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 import { AgentState } from './agentState';
-import { Storage } from '../storage/storage';
+import { StorageProvider } from '../storage/storage';
 /**
  * Manages the state of a conversation.
  */
@@ -13,6 +13,6 @@ export declare class ConversationState extends AgentState {
      * Creates a new instance of ConversationState.
      * @param storage The storage provider.
      */
-    constructor(storage: Storage, namespace?: string);
+    constructor(storage: StorageProvider, namespace?: string);
     private getStorageKey;
 }

package/dist/src/state/conversationState.js.map

@@ -1 +1 @@
-{"version":3,"file":"conversationState.js","sourceRoot":"","sources":["../../../src/state/conversationState.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,6CAAyC;AAGzC,gEAAsE;AACtE,gDAAuC;AAEvC;;GAEG;AACH,uBAA+B,SAAQ,uBAAU;IAC/C;;;OAGG;IACH,YAAa,OAAgB,EAAmB,SAAS,GAAW,EAAE;QACpE,KAAK,CAAC,OAAO,EAAE,CAAC,OAAoB,EAAE,EAAE;YACtC,MAAM,GAAG,GAAW,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;YAE/C,OAAO,GAAG,aAAH,GAAG,cAAH,GAAG,GAAI,IAAI,KAAK,CAAC,0EAA0E,CAAC,CAAA;QACrG,CAAC,CAAC,CAAA;yBAL4C,SAAS;IAMzD,CAAC;IAEO,aAAa,CAAE,OAAoB;QACzC,MAAM,QAAQ,GAAa,OAAO,CAAC,QAAQ,CAAA;QAC3C,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAA;QACpC,MAAM,cAAc,GAAG,QAAQ,IAAI,CAAC,QAAQ,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;QAErI,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,iCAAe,CAAC,iBAAiB,CAAC,KAAK,EAAE,oBAAM,CAAC,wBAAwB,CAAC,CAAA;QACjF,CAAC;QAED,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,iCAAe,CAAC,iBAAiB,CAAC,KAAK,EAAE,oBAAM,CAAC,6BAA6B,CAAC,CAAA;QACtF,CAAC;QAED,OAAO,GAAG,SAAS,kBAAkB,cAAc,IAAI,IAAI,CAAC,SAAS,EAAE,CAAA;IACzE,CAAC;CACF"}
+{"version":3,"file":"conversationState.js","sourceRoot":"","sources":["../../../src/state/conversationState.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,6CAAyC;AAGzC,gEAAsE;AACtE,gDAAuC;AAEvC;;GAEG;AACH,uBAA+B,SAAQ,uBAAU;IAC/C;;;OAGG;IACH,YAAa,OAAwB,EAAmB,SAAS,GAAW,EAAE;QAC5E,KAAK,CAAC,OAAO,EAAE,CAAC,OAAoB,EAAE,EAAE;YACtC,MAAM,GAAG,GAAW,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;YAE/C,OAAO,GAAG,aAAH,GAAG,cAAH,GAAG,GAAI,IAAI,KAAK,CAAC,0EAA0E,CAAC,CAAA;QACrG,CAAC,CAAC,CAAA;yBALoD,SAAS;IAMjE,CAAC;IAEO,aAAa,CAAE,OAAoB;QACzC,MAAM,QAAQ,GAAa,OAAO,CAAC,QAAQ,CAAA;QAC3C,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAA;QACpC,MAAM,cAAc,GAAG,QAAQ,IAAI,CAAC,QAAQ,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;QAErI,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,iCAAe,CAAC,iBAAiB,CAAC,KAAK,EAAE,oBAAM,CAAC,wBAAwB,CAAC,CAAA;QACjF,CAAC;QAED,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,iCAAe,CAAC,iBAAiB,CAAC,KAAK,EAAE,oBAAM,CAAC,6BAA6B,CAAC,CAAA;QACtF,CAAC;QAED,OAAO,GAAG,SAAS,kBAAkB,cAAc,IAAI,IAAI,CAAC,SAAS,EAAE,CAAA;IACzE,CAAC;CACF"}

package/dist/src/state/userState.d.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 import { AgentState } from './agentState';
-import { Storage } from '../storage/storage';
+import { StorageProvider } from '../storage/storage';
 /**
  * Manages the state of a user.
  */
@@ -13,6 +13,6 @@ export declare class UserState extends AgentState {
       * Creates a new instance of UserState.
       * @param storage The storage provider.
       */
-    constructor(storage: Storage, namespace?: string);
+    constructor(storage: StorageProvider, namespace?: string);
     private getStorageKey;
 }

package/dist/src/state/userState.js.map

@@ -1 +1 @@
-{"version":3,"file":"userState.js","sourceRoot":"","sources":["../../../src/state/userState.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,6CAAyC;AAGzC,gEAAsE;AACtE,gDAAuC;AAEvC;;GAEG;AACH,eAAuB,SAAQ,uBAAU;IACvC;;;QAGI;IACJ,YAAa,OAAgB,EAAmB,SAAS,GAAW,EAAE;QACpE,KAAK,CAAC,OAAO,EAAE,CAAC,OAAoB,EAAE,EAAE;YACtC,MAAM,GAAG,GAAW,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;YAE/C,OAAO,GAAG,aAAH,GAAG,cAAH,GAAG,GAAI,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAA;QAC7F,CAAC,CAAC,CAAA;yBAL4C,SAAS;IAMzD,CAAC;IAEO,aAAa,CAAE,OAAoB;QACzC,MAAM,QAAQ,GAAa,OAAO,CAAC,QAAQ,CAAA;QAE3C,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAA;QACpC,MAAM,MAAM,GAAG,QAAQ,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;QAErG,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,iCAAe,CAAC,iBAAiB,CAAC,KAAK,EAAE,oBAAM,CAAC,wBAAwB,CAAC,CAAA;QACjF,CAAC;QAED,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,iCAAe,CAAC,iBAAiB,CAAC,KAAK,EAAE,oBAAM,CAAC,qBAAqB,CAAC,CAAA;QAC9E,CAAC;QAED,OAAO,GAAG,SAAS,UAAU,MAAM,IAAI,IAAI,CAAC,SAAS,EAAE,CAAA;IACzD,CAAC;CACF"}
+{"version":3,"file":"userState.js","sourceRoot":"","sources":["../../../src/state/userState.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,6CAAyC;AAGzC,gEAAsE;AACtE,gDAAuC;AAEvC;;GAEG;AACH,eAAuB,SAAQ,uBAAU;IACvC;;;QAGI;IACJ,YAAa,OAAwB,EAAmB,SAAS,GAAW,EAAE;QAC5E,KAAK,CAAC,OAAO,EAAE,CAAC,OAAoB,EAAE,EAAE;YACtC,MAAM,GAAG,GAAW,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;YAE/C,OAAO,GAAG,aAAH,GAAG,cAAH,GAAG,GAAI,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAA;QAC7F,CAAC,CAAC,CAAA;yBALoD,SAAS;IAMjE,CAAC;IAEO,aAAa,CAAE,OAAoB;QACzC,MAAM,QAAQ,GAAa,OAAO,CAAC,QAAQ,CAAA;QAE3C,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAA;QACpC,MAAM,MAAM,GAAG,QAAQ,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;QAErG,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,iCAAe,CAAC,iBAAiB,CAAC,KAAK,EAAE,oBAAM,CAAC,wBAAwB,CAAC,CAAA;QACjF,CAAC;QAED,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,iCAAe,CAAC,iBAAiB,CAAC,KAAK,EAAE,oBAAM,CAAC,qBAAqB,CAAC,CAAA;QAC9E,CAAC;QAED,OAAO,GAAG,SAAS,UAAU,MAAM,IAAI,IAAI,CAAC,SAAS,EAAE,CAAA;IACzD,CAAC;CACF"}

package/dist/src/statusCodes.d.ts

@@ -67,6 +67,11 @@ export declare enum StatusCodes {
      * or different communication method to fulfill the request.
      */
     UPGRADE_REQUIRED = 426,
+    /**
+     * The user has sent too many requests in a given amount of time.
+     * Used when rate limiting or throttling prevents a turn from being processed.
+     */
+    TOO_MANY_REQUESTS = 429,
     /**
      * The server encountered an unexpected condition that prevented it from fulfilling the request.
      * Generic error message when an unexpected agent hosting error occurs

package/dist/src/statusCodes.js

@@ -71,6 +71,11 @@ var StatusCodes;
      * or different communication method to fulfill the request.
      */
     StatusCodes[StatusCodes["UPGRADE_REQUIRED"] = 426] = "UPGRADE_REQUIRED";
+    /**
+     * The user has sent too many requests in a given amount of time.
+     * Used when rate limiting or throttling prevents a turn from being processed.
+     */
+    StatusCodes[StatusCodes["TOO_MANY_REQUESTS"] = 429] = "TOO_MANY_REQUESTS";
     /**
      * The server encountered an unexpected condition that prevented it from fulfilling the request.
      * Generic error message when an unexpected agent hosting error occurs

package/dist/src/statusCodes.js.map

@@ -1 +1 @@
-{"version":3,"file":"statusCodes.js","sourceRoot":"","sources":["../../src/statusCodes.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;;;GAMG;AACH,IAAY,WAwFX;AAxFD,WAAY,WAAW;IACrB;;;OAGG;IACH,2CAAQ,CAAA;IAER;;;OAGG;IACH,qDAAa,CAAA;IAEb;;;OAGG;IACH,uEAAsB,CAAA;IAEtB;;;;OAIG;IACH,6DAAiB,CAAA;IAEjB;;;;OAIG;IACH,+DAAkB,CAAA;IAElB;;;;OAIG;IACH,yDAAe,CAAA;IAEf;;;;OAIG;IACH,2EAAwB,CAAA;IAExB;;;;OAIG;IACH,uDAAc,CAAA;IAEd;;;;OAIG;IACH,6EAAyB,CAAA;IAEzB;;;;OAIG;IACH,uEAAsB,CAAA;IAEtB;;;;OAIG;IACH,iFAA2B,CAAA;IAE3B;;;;OAIG;IACH,qEAAqB,CAAA;IAErB;;;;OAIG;IACH,6DAAiB,CAAA;AACnB,CAAC,EAxFW,WAAW,aAAX,WAAW,GAAX,WAAW,QAwFtB"}
+{"version":3,"file":"statusCodes.js","sourceRoot":"","sources":["../../src/statusCodes.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;;;GAMG;AACH,IAAY,WA8FX;AA9FD,WAAY,WAAW;IACrB;;;OAGG;IACH,2CAAQ,CAAA;IAER;;;OAGG;IACH,qDAAa,CAAA;IAEb;;;OAGG;IACH,uEAAsB,CAAA;IAEtB;;;;OAIG;IACH,6DAAiB,CAAA;IAEjB;;;;OAIG;IACH,+DAAkB,CAAA;IAElB;;;;OAIG;IACH,yDAAe,CAAA;IAEf;;;;OAIG;IACH,2EAAwB,CAAA;IAExB;;;;OAIG;IACH,uDAAc,CAAA;IAEd;;;;OAIG;IACH,6EAAyB,CAAA;IAEzB;;;;OAIG;IACH,uEAAsB,CAAA;IAEtB;;;OAGG;IACH,yEAAuB,CAAA;IAEvB;;;;OAIG;IACH,iFAA2B,CAAA;IAE3B;;;;OAIG;IACH,qEAAqB,CAAA;IAErB;;;;OAIG;IACH,6DAAiB,CAAA;AACnB,CAAC,EA9FW,WAAW,aAAX,WAAW,GAAX,WAAW,QA8FtB"}

package/dist/src/storage/fileStorage.d.ts

@@ -2,109 +2,124 @@
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Licensed under the MIT License.
  */
-import { Storage, StoreItem } from './storage';
+import { StorageDeleteOptions, StorageDeleteResults, StorageReadResults, StorageWriteOptions, StorageWriteResults, Storage, StorageV2, StoreItem } from './storage';
+declare class FileStorageInternals {
+    private readonly statePath;
+    private readonly versionsPath;
+    private readonly expirationsPath;
+    readonly state: Record<string, unknown>;
+    readonly versions: Record<string, string>;
+    readonly expirations: Record<string, number>;
+    constructor(folder: string);
+    flush(): void;
+    getOrCreateVersion(key: string): string;
+    isExpired(key: string): boolean;
+    remove(key: string): void;
+}
 /**
  * A file-based storage implementation that persists data to the local filesystem.
  *
  * @remarks
- * FileStorage stores all data in a single JSON file named 'state.json' within a specified folder.
+ * FileStorage stores all data in a single JSON file named `state.json` within a specified folder.
  * This implementation is suitable for development scenarios, local testing, and single-instance
  * deployments where shared state across multiple instances is not required.
  *
- * The storage format is a simple key-value JSON object where keys are strings and values
- * can be any JSON-serializable data. All operations are synchronous file I/O operations
- * wrapped in Promise interfaces to match the Storage contract.
+ * Values remain a key-value JSON object in `state.json`. V2 keeps generated storage versions in
+ * `state.versions.json` so a value's own `eTag` property is not changed. All operations use
+ * synchronous file I/O wrapped in Promise interfaces. Use {@link FileStorageV2} for the
+ * structured StorageV2 contract.
+ * V2 supports create-only, replace, and expected-version conditions.
+ *
+ * The inherited constructor creates the folder and `state.json` when needed, then loads values
+ * and V2 version metadata into memory. It creates `state.versions.json` on the first V2 write.
  *
  * ### Warning
  * This implementation does not provide:
  * - Thread safety for concurrent access
- * - Optimistic concurrency control (eTag support)
  * - Atomic operations across multiple keys
  * - Scale for large datasets
  *
- * For production scenarios requiring these features, consider using
- * database-backed storage implementations instead.
+ * For production scenarios requiring these features, use a database-backed storage implementation.
  *
  * @example
  * ```typescript
- * const storage = new FileStorage('./data');
+ * const legacyStorage = new FileStorage('./data')
+ * const storageV2 = new FileStorageV2('./data-v2')
  *
- * // Write some data
- * await storage.write({
- *   'user123': { name: 'John', lastSeen: new Date().toISOString() },
- *   'conversation456': { turn: 5, context: 'discussing weather' }
- * });
+ * await storageV2.write({
+ *   user123: { name: 'John', lastSeen: new Date().toISOString() }
+ * })
  *
- * // Read specific keys
- * const data = await storage.read(['user123']);
- * console.log(data.user123); // { name: 'John', lastSeen: '...' }
+ * const result = await storageV2.read(['user123'])
+ * console.log(result.user123.value)
  *
- * // Delete data
- * await storage.delete(['conversation456']);
+ * await storageV2.delete(['user123'])
  * ```
- *
  */
-export declare class FileStorage implements Storage {
-    private _folder;
-    private _stateFile;
+export declare class FileStorage extends FileStorageInternals implements Storage {
     /**
-     * Creates a new FileStorage instance that stores data in the specified folder.
-     *
-     * @param folder The absolute or relative path to the folder where the state.json file will be stored
-     * @throws May throw filesystem errors if the folder cannot be created or accessed
-     *
-     * @remarks
-     * The constructor performs the following initialization steps:
-     * 1. Creates the target folder if it doesn't exist (including parent directories)
-     * 2. Creates an empty state.json file if it doesn't exist
-     * 3. Loads existing data from state.json into memory for fast access
+     * Reads legacy items from `state.json`.
      *
+     * @param keys The keys to read; must not be empty.
+     * @returns Existing items keyed by storage key. Missing keys are omitted.
      */
-    constructor(folder: string);
+    read(keys: string[]): Promise<StoreItem>;
     /**
-     * Reads store items from the filesystem storage.
-     *
-     * @param keys Array of keys to read from storage
-     * @returns Promise resolving to an object containing the requested items (keys that don't exist are omitted)
-     * @throws ReferenceError if keys array is empty or undefined
-     *
-     * @remarks
-     * This method reads from the in-memory cache that was loaded during construction,
-     * making it very fast but potentially returning stale data if the file was
-     * modified by external processes.
+     * Writes legacy items to `state.json`.
      *
+     * @param changes The items to write, keyed by storage key.
+     * @throws If `changes` is invalid or the file cannot be written.
      */
-    read(keys: string[]): Promise<StoreItem>;
+    write(changes: StoreItem): Promise<void>;
     /**
-     * Writes store items to the filesystem storage.
-     *
-     * @param changes Object containing key-value pairs to write to storage
-     * @returns Promise that resolves when the write operation completes
-     *
-     * @remarks
-     * This method updates both the in-memory cache and writes the entire state
-     * to the state.json file. The file is written with pretty-printing (2-space indentation)
-     * for better readability during development and debugging.
-     *
-     * > [!NOTE]
-     * > This implementation does not support eTag-based optimistic concurrency control.
-     * > Any eTag values in the changes object are ignored.
+     * Deletes legacy items from `state.json`.
      *
+     * @param keys The keys to delete; must not be empty. Missing keys are ignored.
      */
-    write(changes: StoreItem): Promise<void>;
+    delete(keys: string[]): Promise<void>;
+}
+/**
+ * A file-backed provider for the structured {@link StorageV2} contract.
+ *
+ * This is the V2 counterpart to {@link FileStorage}. Values are stored in `state.json`, while
+ * generated storage versions are stored separately in `state.versions.json`; an `eTag` property
+ * in an application value is therefore preserved. Reads and mutations return a result for every
+ * requested key and support create-only, replace, and expected-version conditions.
+ *
+ * Like {@link FileStorage}, this provider is for development, local testing, and single-instance
+ * deployments. It does not provide cross-process concurrency or multi-key atomicity.
+ */
+export declare class FileStorageV2 extends StorageV2 {
+    private readonly internals;
     /**
-     * Deletes store items from the filesystem storage.
+     * Creates a V2 file storage provider.
      *
-     * @param keys Array of keys to delete from storage
-     * @returns Promise that resolves when the delete operation completes
+     * @param folder The absolute or relative folder where `state.json` is stored.
+     * @throws May throw filesystem errors if the folder or state file cannot be created or read.
+     */
+    constructor(folder: string);
+    /**
+     * Reads items and their stored versions from the local state files.
      *
-     * @throws ReferenceError if keys array is empty or undefined
+     * @param keys The keys to read. Empty batches are valid.
+     * @returns A result for every key, with `notFound` for missing items. Returned values are cloned.
+     */
+    read<T extends object = Record<string, unknown>>(keys: string[]): Promise<StorageReadResults<T>>;
+    /**
+     * Writes cloned items and generated versions to the local state files.
      *
-     * @remarks
-     * This method removes the specified keys from both the in-memory cache
-     * and writes the updated state to the state.json file. Keys that don't
-     * exist in storage are silently ignored.
+     * @param changes The values to write, keyed by storage key.
+     * @param options Create-only, replace, or expected-version conditions.
+     * @returns A result for every supplied key, including concurrency-condition outcomes.
+     */
+    write<T extends object = Record<string, unknown>>(changes: Record<string, T>, options?: StorageWriteOptions): Promise<StorageWriteResults>;
+    /**
+     * Deletes items and their versions from the local state files.
      *
+     * @param keys The keys to delete. Empty batches are valid.
+     * @param options An optional expected storage version.
+     * @returns A result for every supplied key.
      */
-    delete(keys: string[]): Promise<void>;
+    delete(keys: string[], options?: StorageDeleteOptions): Promise<StorageDeleteResults>;
 }
+export {};