@ferricstore/ferricstore 0.11.11 → 0.12.1

package/dist/openai-agents.js

@@ -0,0 +1,692 @@
+// src/openai-agents.ts
+import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
+
+// src/agent-persistence/durability.ts
+import { randomUUID } from "crypto";
+import { setTimeout as delay } from "timers/promises";
+
+// src/errors.ts
+var FerricStoreError = class extends Error {
+  code = "ferricstore_error";
+  raw;
+  retryable;
+  safeToRetry;
+  retryAfterMs;
+  constructor(message, options = {}) {
+    super(message, { cause: options.cause });
+    this.name = new.target.name;
+    this.raw = options.raw;
+    this.retryable = options.retryable ?? structuredBooleanField(options.raw, "retryable");
+    this.safeToRetry = options.safeToRetry ?? structuredBooleanField(options.raw, "safe_to_retry");
+    this.retryAfterMs = options.retryAfterMs ?? structuredIntegerField(options.raw, "retry_after_ms");
+  }
+};
+var LockHeldError = class extends FerricStoreError {
+  code = "lock_held";
+};
+function structuredIntegerField(raw, name) {
+  const value = structuredField(raw, name);
+  if (typeof value === "number") {
+    return Number.isSafeInteger(value) && value >= 0 ? value : void 0;
+  }
+  if (typeof value === "bigint") {
+    return value >= 0n && value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : void 0;
+  }
+  const text = binaryText(value);
+  return text == null ? void 0 : nonNegativeSafeIntegerText(text);
+}
+function structuredBooleanField(raw, name) {
+  const value = structuredField(raw, name);
+  if (typeof value === "boolean") return value;
+  const text = binaryText(value)?.toLowerCase();
+  if (text === "true" || text === "1") return true;
+  if (text === "false" || text === "0") return false;
+  return void 0;
+}
+function nonNegativeSafeIntegerText(value) {
+  if (!/^[0-9]+$/u.test(value)) return void 0;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : void 0;
+}
+function structuredField(raw, name) {
+  if (raw instanceof Map) {
+    if (raw.has(name)) return raw.get(name);
+    for (const [key, value] of raw.entries()) {
+      if (binaryText(key) === name) return value;
+    }
+    return void 0;
+  }
+  if (typeof raw === "object" && raw != null && Object.hasOwn(raw, name)) {
+    return raw[name];
+  }
+  return void 0;
+}
+function binaryText(value) {
+  if (typeof value === "string") return value;
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) return Buffer.from(value).toString("utf8");
+  return void 0;
+}
+
+// src/agent-persistence/durability.ts
+var DEFAULT_LOCK_OPTIONS = {
+  lockRetryMs: 10,
+  lockTtlMs: 3e5,
+  lockWaitMs: 3e4
+};
+function normalizeKeyPrefix(value, defaultValue) {
+  const prefix = value.length === 0 ? defaultValue : value;
+  if (prefix.includes("\0")) throw new TypeError("keyPrefix must not contain NUL bytes");
+  const normalized = prefix.replace(/:+$/u, "");
+  if (normalized.length === 0) throw new TypeError("keyPrefix must contain a character other than ':'");
+  return normalized;
+}
+function positiveInteger(value, fallback, name) {
+  const normalized = value ?? fallback;
+  if (!Number.isSafeInteger(normalized) || normalized <= 0) {
+    throw new TypeError(`${name} must be a positive safe integer`);
+  }
+  return normalized;
+}
+function nonNegativeInteger(value, fallback, name) {
+  const normalized = value ?? fallback;
+  if (!Number.isSafeInteger(normalized) || normalized < 0) {
+    throw new TypeError(`${name} must be a non-negative safe integer`);
+  }
+  return normalized;
+}
+function textResponse(value, name) {
+  if (typeof value === "string") return value;
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) return Buffer.from(value).toString("utf8");
+  throw new TypeError(`FerricStore returned an invalid ${name}`);
+}
+function integerResponse(value, name) {
+  const parsed = typeof value === "number" ? value : Number(textResponse(value, name));
+  if (!Number.isSafeInteger(parsed)) throw new TypeError(`FerricStore returned an invalid ${name}`);
+  return parsed;
+}
+async function readAtomicValue(client, key, name) {
+  const value = await client.command("GET", key);
+  if (value == null) return void 0;
+  if (typeof value === "string") return Buffer.from(value, "utf8");
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) return Buffer.from(value);
+  throw new TypeError(`FerricStore returned a non-binary ${name}`);
+}
+async function compareAndSetAtomicValue(client, key, expected, value) {
+  if (expected == null) {
+    const response2 = await client.command("SET", key, value, "NX");
+    if (response2 == null || response2 === false) return false;
+    if (response2 === true) return true;
+    return textResponse(response2, "SET NX response").toUpperCase() === "OK";
+  }
+  const response = await client.command("CAS", key, expected, value);
+  if (response == null || response === false) return false;
+  if (response === true) return true;
+  return integerResponse(response, "CAS response") === 1;
+}
+async function withMutationLocks(client, keys, operation, options = {}) {
+  const orderedKeys = [...new Set(keys)].sort();
+  if (orderedKeys.length === 0) {
+    const signal = new AbortController().signal;
+    return await operation({
+      signal,
+      assertOwned: () => void 0,
+      publish: async (...args) => await additiveCommand(client, args),
+      compareAndSet: async (key, expected, value) => await compareAndSetAtomicValue(client, key, expected, value)
+    });
+  }
+  const normalized = {
+    lockRetryMs: positiveInteger(options.lockRetryMs, DEFAULT_LOCK_OPTIONS.lockRetryMs, "lockRetryMs"),
+    lockTtlMs: positiveInteger(options.lockTtlMs, DEFAULT_LOCK_OPTIONS.lockTtlMs, "lockTtlMs"),
+    lockWaitMs: nonNegativeInteger(options.lockWaitMs, DEFAULT_LOCK_OPTIONS.lockWaitMs, "lockWaitMs")
+  };
+  if (normalized.lockRetryMs >= normalized.lockTtlMs) {
+    throw new TypeError("lockRetryMs must be less than lockTtlMs");
+  }
+  const owner = randomUUID();
+  const acquired = [];
+  const deadline = performance.now() + normalized.lockWaitMs;
+  let primaryError;
+  let heartbeatError;
+  let releaseError;
+  let result;
+  let operationCompleted = false;
+  let conditionalCommitCompleted = false;
+  const heartbeatAbort = new AbortController();
+  const ownershipAbort = new AbortController();
+  const lastExtended = /* @__PURE__ */ new Map();
+  const loseOwnership = (error) => {
+    const normalizedError = errorObject(error);
+    heartbeatError ??= normalizedError;
+    if (!ownershipAbort.signal.aborted) ownershipAbort.abort(normalizedError);
+    return normalizedError;
+  };
+  const assertOwned = () => {
+    if (heartbeatError != null) throw errorObject(heartbeatError);
+    if (ownershipAbort.signal.aborted) throw errorObject(ownershipAbort.signal.reason);
+  };
+  const renewOwned = async () => {
+    assertOwned();
+    for (const key of acquired) {
+      try {
+        const response = await client.command("EXTEND", key, owner, normalized.lockTtlMs);
+        if (integerResponse(response, "EXTEND response") !== 1) {
+          throw new Error(`lost FerricStore lock ${JSON.stringify(key)} while mutating data`);
+        }
+        lastExtended.set(key, performance.now());
+      } catch (error) {
+        throw loseOwnership(new Error(
+          `could not validate FerricStore lock ${JSON.stringify(key)} before mutating data`,
+          { cause: error }
+        ));
+      }
+    }
+    assertOwned();
+  };
+  const lease = {
+    signal: ownershipAbort.signal,
+    assertOwned,
+    publish: async (...args) => {
+      await renewOwned();
+      const response = await additiveCommand(client, args);
+      assertOwned();
+      return response;
+    },
+    compareAndSet: async (key, expected, value) => {
+      await renewOwned();
+      const committed = await compareAndSetAtomicValue(client, key, expected, value);
+      if (committed) conditionalCommitCompleted = true;
+      else assertOwned();
+      return committed;
+    }
+  };
+  try {
+    for (const key of orderedKeys) {
+      while (!await tryAcquireLock(client, key, owner, normalized.lockTtlMs)) {
+        if (performance.now() >= deadline) {
+          throw new Error(`timed out acquiring FerricStore lock ${JSON.stringify(key)}`);
+        }
+        await extendAcquiredLocks(client, acquired, owner, normalized.lockTtlMs);
+        await delay(normalized.lockRetryMs);
+      }
+      acquired.push(key);
+    }
+    await extendAcquiredLocks(client, acquired, owner, normalized.lockTtlMs);
+    for (const key of acquired) lastExtended.set(key, performance.now());
+    const heartbeat = renewLocks(
+      client,
+      acquired,
+      owner,
+      normalized.lockTtlMs,
+      lastExtended,
+      heartbeatAbort.signal,
+      (error) => {
+        loseOwnership(error);
+      }
+    );
+    try {
+      result = await operation(lease);
+      operationCompleted = true;
+    } catch (error) {
+      primaryError = error;
+    } finally {
+      heartbeatAbort.abort();
+      await heartbeat;
+    }
+  } catch (error) {
+    primaryError ??= error;
+  } finally {
+    heartbeatAbort.abort();
+    for (const key of acquired.reverse()) {
+      try {
+        await client.command("UNLOCK", key, owner);
+      } catch (error) {
+        releaseError ??= error;
+      }
+    }
+  }
+  if (primaryError != null) throw errorObject(primaryError);
+  if (heartbeatError != null && !conditionalCommitCompleted) throw errorObject(heartbeatError);
+  if (releaseError != null && !(heartbeatError != null && conditionalCommitCompleted)) {
+    throw errorObject(releaseError);
+  }
+  if (!operationCompleted) throw new Error("FerricStore mutation did not complete");
+  return result;
+}
+async function additiveCommand(client, args) {
+  const rawName = args[0];
+  const name = typeof rawName === "string" ? rawName.toUpperCase() : Buffer.isBuffer(rawName) || rawName instanceof Uint8Array ? Buffer.from(rawName).toString("utf8").toUpperCase() : "";
+  if (name !== "SADD" && name !== "ZADD") {
+    throw new TypeError("FerricStore mutation leases only publish add-only SADD or ZADD indexes");
+  }
+  if (name === "ZADD" && (args.length < 4 || args.length % 2 !== 0 || args.slice(2).some((value, index) => index % 2 === 0 && Number(value) !== 0))) {
+    throw new TypeError("FerricStore mutation leases only publish zero-score ZADD indexes");
+  }
+  return await client.command(...args);
+}
+async function extendAcquiredLocks(client, keys, owner, ttlMs) {
+  for (const key of keys) {
+    const response = await client.command("EXTEND", key, owner, ttlMs);
+    if (integerResponse(response, "EXTEND response") !== 1) {
+      throw new Error(`lost FerricStore lock ${JSON.stringify(key)} before mutating data`);
+    }
+  }
+}
+async function tryAcquireLock(client, key, owner, ttlMs) {
+  try {
+    const response = await client.command("LOCK", key, owner, ttlMs);
+    return response === true || response === "OK" || Buffer.isBuffer(response) && response.equals(Buffer.from("OK"));
+  } catch (error) {
+    if (error instanceof LockHeldError) return false;
+    throw error;
+  }
+}
+async function renewLocks(client, keys, owner, ttlMs, lastExtended, signal, onError) {
+  const intervalMs = Math.max(Math.floor(ttlMs / 3), 1);
+  const retryMs = Math.min(Math.max(Math.floor(intervalMs / 10), 1), 1e3);
+  let waitMs = intervalMs;
+  while (!signal.aborted) {
+    try {
+      await delay(waitMs, void 0, { signal });
+    } catch (error) {
+      if (signal.aborted) return;
+      onError(error);
+      return;
+    }
+    const now = performance.now();
+    let retry = false;
+    for (const key of keys) {
+      try {
+        const response = await client.command("EXTEND", key, owner, ttlMs);
+        if (integerResponse(response, "EXTEND response") !== 1) {
+          onError(new Error(`lost FerricStore lock ${JSON.stringify(key)} while mutating data`));
+          return;
+        }
+        lastExtended.set(key, now);
+      } catch (error) {
+        if (now - (lastExtended.get(key) ?? 0) >= ttlMs) {
+          onError(new Error(`lost FerricStore lock ${JSON.stringify(key)} while mutating data`, { cause: error }));
+          return;
+        }
+        retry = true;
+      }
+    }
+    waitMs = retry ? retryMs : intervalMs;
+  }
+}
+function errorObject(value) {
+  return value instanceof Error ? value : new Error("FerricStore mutation failed", { cause: value });
+}
+
+// src/agent-persistence/snapshot.ts
+import { createHash } from "crypto";
+function encodeSnapshot(value) {
+  return encodeSnapshotWith(value, defaultKeyComparator);
+}
+function decodeSnapshot(value, name) {
+  const bytes = typeof value === "string" ? Buffer.from(value, "utf8") : Buffer.from(asBytes(value, name));
+  let encoded;
+  try {
+    encoded = JSON.parse(bytes.toString("utf8"));
+  } catch (error) {
+    throw new Error(`FerricStore returned an invalid ${name}`, { cause: error });
+  }
+  return restore(encoded, name);
+}
+function snapshotDigest(value) {
+  return createHash("sha256").update(encodeSnapshot(value)).digest("hex");
+}
+function legacySnapshotDigest(value, locale) {
+  return createHash("sha256").update(encodeSnapshotWith(value, (left, right) => left.localeCompare(right, locale))).digest("hex");
+}
+function cloneSnapshot(value) {
+  return decodeSnapshot(encodeSnapshot(value), "snapshot");
+}
+function snapshotsEqual(left, right) {
+  return encodeSnapshot(left).equals(encodeSnapshot(right));
+}
+function encodeSnapshotWith(value, compareKeys) {
+  return Buffer.from(JSON.stringify(snapshot(value, /* @__PURE__ */ new WeakSet(), compareKeys)), "utf8");
+}
+function defaultKeyComparator(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function snapshot(value, ancestors, compareKeys) {
+  if (value === null) return ["null"];
+  if (value === void 0) return ["undefined"];
+  if (typeof value === "string") return ["string", value];
+  if (typeof value === "boolean") return ["boolean", value];
+  if (typeof value === "number") {
+    if (Object.is(value, -0)) return ["number", "-0"];
+    if (Number.isNaN(value)) return ["number", "NaN"];
+    if (value === Infinity) return ["number", "+Infinity"];
+    if (value === -Infinity) return ["number", "-Infinity"];
+    return ["number", value];
+  }
+  if (typeof value !== "object") throw new TypeError("session history contains unsupported data");
+  if (value instanceof Uint8Array) {
+    const keys = Reflect.ownKeys(value);
+    if (keys.length !== value.length || keys.some((key) => typeof key !== "string" || !isArrayIndex(key, value.length))) {
+      throw new TypeError("session history binary data contains custom properties");
+    }
+    return ["binary", Buffer.from(value).toString("base64")];
+  }
+  if (ancestors.has(value)) throw new TypeError("session history contains cyclic data");
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const keys2 = Reflect.ownKeys(value);
+      if (keys2.length !== value.length + 1 || keys2.some((key) => typeof key !== "string" || key !== "length" && !isArrayIndex(key, value.length))) {
+        throw new TypeError("session history contains a sparse or customized array");
+      }
+      const items = [];
+      for (let index = 0; index < value.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (descriptor == null || !descriptor.enumerable || !("value" in descriptor)) {
+          throw new TypeError("session history contains an unsupported array item");
+        }
+        items.push(snapshot(descriptor.value, ancestors, compareKeys));
+      }
+      return ["array", items];
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new TypeError("session history contains an unsupported object");
+    }
+    const keys = Reflect.ownKeys(value);
+    if (keys.some((key) => typeof key !== "string")) {
+      throw new TypeError("session history contains a symbol property");
+    }
+    const entries = [];
+    for (const key of keys.sort(compareKeys)) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (descriptor == null || !descriptor.enumerable || !("value" in descriptor)) {
+        throw new TypeError("session history contains an unsupported property");
+      }
+      entries.push([key, snapshot(descriptor.value, ancestors, compareKeys)]);
+    }
+    return ["object", entries];
+  } finally {
+    ancestors.delete(value);
+  }
+}
+function restore(value, name) {
+  if (!Array.isArray(value) || typeof value[0] !== "string") throw new TypeError(`invalid ${name}`);
+  switch (value[0]) {
+    case "null":
+      return null;
+    case "undefined":
+      return void 0;
+    case "string":
+      return requireValueType(value[1], "string", name);
+    case "boolean":
+      return requireValueType(value[1], "boolean", name);
+    case "binary":
+      return Buffer.from(requireValueType(value[1], "string", name), "base64");
+    case "number":
+      return restoreNumber(value[1], name);
+    case "array": {
+      if (!Array.isArray(value[1])) throw new TypeError(`invalid ${name}`);
+      return value[1].map((item) => restore(item, name));
+    }
+    case "object": {
+      if (!Array.isArray(value[1])) throw new TypeError(`invalid ${name}`);
+      const result = {};
+      for (const entry of value[1]) {
+        if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== "string") {
+          throw new TypeError(`invalid ${name}`);
+        }
+        Object.defineProperty(result, entry[0], {
+          configurable: true,
+          enumerable: true,
+          value: restore(entry[1], name),
+          writable: true
+        });
+      }
+      return result;
+    }
+    default:
+      throw new TypeError(`invalid ${name}`);
+  }
+}
+function restoreNumber(value, name) {
+  if (typeof value === "number") return value;
+  if (value === "NaN") return Number.NaN;
+  if (value === "+Infinity") return Infinity;
+  if (value === "-Infinity") return -Infinity;
+  if (value === "-0") return -0;
+  throw new TypeError(`invalid ${name}`);
+}
+function requireValueType(value, type, name) {
+  if (typeof value !== type) throw new TypeError(`invalid ${name}`);
+  return value;
+}
+function asBytes(value, name) {
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) return value;
+  throw new TypeError(`FerricStore returned a non-binary ${name}`);
+}
+function isArrayIndex(key, length) {
+  if (!/^(?:0|[1-9]\d*)$/u.test(key)) return false;
+  const index = Number(key);
+  return Number.isSafeInteger(index) && index >= 0 && index < length;
+}
+
+// src/openai-agents.ts
+var SESSION_FORMAT_VERSION = 1;
+var SESSION_STATE_FIELD = "state";
+var RECEIPT_DIGEST_VERSION = "v2:";
+var FerricStoreSession = class {
+  client;
+  sessionId;
+  keyPrefix;
+  initialItems;
+  lockOptions;
+  legacyReceiptLocales;
+  sessionKey;
+  stateKey;
+  lockKey;
+  constructor(client, options = {}) {
+    this.client = client;
+    this.sessionId = options.sessionId ?? randomUUID2();
+    if (typeof this.sessionId !== "string" || this.sessionId.trim().length === 0) {
+      throw new TypeError("sessionId must be a non-empty string");
+    }
+    this.keyPrefix = normalizeKeyPrefix(options.keyPrefix ?? "openai:agents:session", "openai:agents:session");
+    this.initialItems = snapshotItems(options.initialItems ?? [], "initialItems");
+    this.lockOptions = {
+      lockRetryMs: options.lockRetryMs,
+      lockTtlMs: options.lockTtlMs,
+      lockWaitMs: options.lockWaitMs
+    };
+    if (options.legacyReceiptLocales != null && !Array.isArray(options.legacyReceiptLocales)) {
+      throw new TypeError("legacyReceiptLocales must be an array");
+    }
+    try {
+      this.legacyReceiptLocales = Intl.getCanonicalLocales(options.legacyReceiptLocales ?? []);
+    } catch (error) {
+      throw new TypeError("legacyReceiptLocales contains an invalid locale", { cause: error });
+    }
+    const digest = createHash2("sha256").update(this.sessionId, "utf8").digest("hex");
+    this.sessionKey = `${this.keyPrefix}:{oais:${digest}}:session`;
+    this.stateKey = `${this.sessionKey}:atomic-state`;
+    this.lockKey = `${this.keyPrefix}:{oais:${digest}}:mutation-lock`;
+  }
+  async getSessionId() {
+    await this.mutate(async (state) => state);
+    return this.sessionId;
+  }
+  async getItems(limit) {
+    if (limit != null && limit <= 0) return [];
+    if (limit != null && !Number.isSafeInteger(limit)) {
+      throw new TypeError("limit must be a safe integer");
+    }
+    const state = await this.readState();
+    const items = limit == null ? state.items : state.items.slice(Math.max(state.items.length - limit, 0));
+    return cloneSnapshot(items);
+  }
+  async addItems(items) {
+    if (items.length === 0) return;
+    const additions = snapshotItems(items, "items");
+    await this.mutate(async (state) => ({
+      ...state,
+      items: [...state.items, ...additions]
+    }));
+  }
+  async replaceHistoryWithCompaction(items) {
+    const replacement = snapshotItems(items, "items");
+    await this.mutate(async (state) => ({ ...state, items: replacement }));
+  }
+  async popItem() {
+    let popped;
+    await this.mutate(async (state) => {
+      popped = state.items.at(-1);
+      return popped == null ? state : { ...state, items: state.items.slice(0, -1) };
+    });
+    return popped == null ? void 0 : cloneSnapshot(popped);
+  }
+  async clearSession() {
+    await this.mutate(async (state) => ({ ...state, items: [], operations: {} }));
+  }
+  async applyHistoryMutations(args) {
+    if (args == null || !Array.isArray(args.mutations)) {
+      throw new TypeError("session history mutations are invalid");
+    }
+    if (args.mutations.length === 0) return;
+    const mutations = cloneSnapshot(args.mutations);
+    await this.mutate(async (state) => {
+      let items = cloneSnapshot(state.items);
+      for (const mutation of mutations) {
+        if (mutation.type !== "replace_function_call") {
+          throw new TypeError("unsupported session history mutation");
+        }
+        const replacement = snapshotItem(mutation.replacement, "mutation replacement");
+        let keptReplacement = false;
+        const next = [];
+        for (const item of items) {
+          if (item.type === "function_call" && item.callId === mutation.callId) {
+            if (!keptReplacement) {
+              next.push(replacement);
+              keptReplacement = true;
+            }
+          } else {
+            next.push(item);
+          }
+        }
+        items = next;
+      }
+      return { ...state, items };
+    });
+  }
+  async applyHistoryTransaction(args) {
+    const { operationId, transaction } = snapshotTransactionArgs(args);
+    const digest = `${RECEIPT_DIGEST_VERSION}${snapshotDigest(transaction)}`;
+    const legacyDigests = /* @__PURE__ */ new Set([
+      snapshotDigest(transaction),
+      legacySnapshotDigest(transaction),
+      ...this.legacyReceiptLocales.map((locale) => legacySnapshotDigest(transaction, locale))
+    ]);
+    await this.mutate(async (state) => {
+      const existing = Object.getOwnPropertyDescriptor(state.operations, operationId)?.value;
+      if (existing != null) {
+        if (typeof existing !== "string") throw new Error("corrupt session history operation receipt");
+        if (existing === digest) return state;
+        if (!legacyDigests.has(existing)) {
+          throw new Error("session history operation was already applied with a different transaction");
+        }
+        return { ...state, operations: { ...state.operations, [operationId]: digest } };
+      }
+      let items;
+      if (transaction.type === "append_items") {
+        items = [...state.items, ...transaction.items];
+      } else {
+        const suffixStart = state.items.length - transaction.expectedSuffix.length;
+        const actualSuffix = suffixStart < 0 ? [] : state.items.slice(suffixStart);
+        if (suffixStart < 0 || !snapshotsEqual(actualSuffix, transaction.expectedSuffix)) {
+          throw new Error("session history suffix no longer matches the transaction precondition");
+        }
+        items = [...state.items.slice(0, suffixStart), ...transaction.replacement];
+      }
+      return {
+        ...state,
+        items,
+        operations: { ...state.operations, [operationId]: digest }
+      };
+    });
+  }
+  async mutate(operation) {
+    await withMutationLocks(this.client, [this.lockKey], async (lease) => {
+      for (let attempt = 0; attempt < 8; attempt += 1) {
+        lease.assertOwned();
+        const snapshot2 = await this.readMutationState();
+        const next = await operation(snapshot2.state);
+        if (await lease.compareAndSet(this.stateKey, snapshot2.expected, encodeSnapshot(next))) return;
+      }
+      throw new Error("concurrent FerricStore OpenAI Agents session mutation did not converge");
+    }, this.lockOptions);
+  }
+  async readState() {
+    return (await this.readMutationState()).state;
+  }
+  async readMutationState() {
+    const expected = await readAtomicValue(this.client, this.stateKey, "OpenAI Agents atomic session state");
+    const value = expected ?? await this.client.command("HGET", this.sessionKey, SESSION_STATE_FIELD);
+    if (value == null) return { expected, state: this.emptyState() };
+    const state = decodeSnapshot(value, "OpenAI Agents session state");
+    if (state == null || typeof state !== "object" || state.formatVersion !== SESSION_FORMAT_VERSION || state.sessionId !== this.sessionId || !Array.isArray(state.items) || state.operations == null || typeof state.operations !== "object" || Array.isArray(state.operations) || Object.values(state.operations).some((digest) => typeof digest !== "string")) {
+      throw new Error("unsupported or corrupt FerricStore OpenAI Agents session state");
+    }
+    return { expected, state };
+  }
+  emptyState() {
+    return {
+      formatVersion: SESSION_FORMAT_VERSION,
+      items: cloneSnapshot(this.initialItems),
+      operations: {},
+      sessionId: this.sessionId
+    };
+  }
+};
+function snapshotTransactionArgs(args) {
+  if (args == null || typeof args !== "object") throw new TypeError("session history transaction is invalid");
+  if (typeof args.operationId !== "string" || args.operationId.trim().length === 0) {
+    throw new TypeError("session history transaction operationId must be a non-empty string");
+  }
+  const transaction = cloneSnapshot(args.transaction);
+  if (transaction == null || typeof transaction !== "object") {
+    throw new TypeError("session history transaction must be an object");
+  }
+  if (transaction.type === "append_items") {
+    if (!Array.isArray(transaction.items)) throw new TypeError("session history append items are invalid");
+    return {
+      operationId: args.operationId,
+      transaction: { type: "append_items", items: snapshotItems(transaction.items, "transaction items") }
+    };
+  }
+  if (transaction.type === "replace_suffix") {
+    if (!Array.isArray(transaction.expectedSuffix) || !Array.isArray(transaction.replacement)) {
+      throw new TypeError("session history suffix transaction is invalid");
+    }
+    return {
+      operationId: args.operationId,
+      transaction: {
+        type: "replace_suffix",
+        expectedSuffix: snapshotItems(transaction.expectedSuffix, "transaction expectedSuffix"),
+        replacement: snapshotItems(transaction.replacement, "transaction replacement")
+      }
+    };
+  }
+  throw new TypeError("unsupported session history transaction type");
+}
+function snapshotItems(items, name) {
+  if (!Array.isArray(items)) throw new TypeError(`${name} must be an array`);
+  return items.map((item) => snapshotItem(item, name));
+}
+function snapshotItem(item, name) {
+  if (item == null || typeof item !== "object" || Array.isArray(item)) {
+    throw new TypeError(`${name} contains an invalid agent item`);
+  }
+  return cloneSnapshot(item);
+}
+export {
+  FerricStoreSession
+};
+//# sourceMappingURL=openai-agents.js.map