@ferricstore/ferricstore 0.11.11 → 0.12.0

package/dist/openai-agents.cjs

@@ -0,0 +1,580 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/openai-agents.ts
+var openai_agents_exports = {};
+__export(openai_agents_exports, {
+  FerricStoreSession: () => FerricStoreSession
+});
+module.exports = __toCommonJS(openai_agents_exports);
+var import_node_crypto3 = require("crypto");
+
+// src/agent-persistence/durability.ts
+var import_node_crypto = require("crypto");
+var import_promises = require("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 withMutationLocks(client, keys, operation, options = {}) {
+  const orderedKeys = [...new Set(keys)].sort();
+  if (orderedKeys.length === 0) return await operation();
+  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")
+  };
+  const owner = (0, import_node_crypto.randomUUID)();
+  const acquired = [];
+  const deadline = performance.now() + normalized.lockWaitMs;
+  let primaryError;
+  let heartbeatError;
+  let releaseError;
+  let result;
+  let operationCompleted = false;
+  const heartbeatAbort = new AbortController();
+  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 (0, import_promises.setTimeout)(normalized.lockRetryMs);
+      }
+      acquired.push(key);
+    }
+    const heartbeat = renewLocks(
+      client,
+      acquired,
+      owner,
+      normalized.lockTtlMs,
+      heartbeatAbort.signal,
+      (error) => {
+        heartbeatError ??= error;
+      }
+    );
+    try {
+      result = await operation();
+      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) throw errorObject(heartbeatError);
+  if (releaseError != null) throw errorObject(releaseError);
+  if (!operationCompleted) throw new Error("FerricStore mutation did not complete");
+  return result;
+}
+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, signal, onError) {
+  const intervalMs = Math.max(Math.floor(ttlMs / 3), 10);
+  const retryMs = Math.min(Math.max(Math.floor(intervalMs / 10), 10), 1e3);
+  const lastExtended = new Map(keys.map((key) => [key, performance.now()]));
+  let waitMs = intervalMs;
+  while (!signal.aborted) {
+    try {
+      await (0, import_promises.setTimeout)(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
+var import_node_crypto2 = require("crypto");
+function encodeSnapshot(value) {
+  return Buffer.from(JSON.stringify(snapshot(value, /* @__PURE__ */ new WeakSet())), "utf8");
+}
+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 (0, import_node_crypto2.createHash)("sha256").update(encodeSnapshot(value)).digest("hex");
+}
+function cloneSnapshot(value) {
+  return decodeSnapshot(encodeSnapshot(value), "snapshot");
+}
+function snapshotsEqual(left, right) {
+  return encodeSnapshot(left).equals(encodeSnapshot(right));
+}
+function snapshot(value, ancestors) {
+  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));
+      }
+      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((left, right) => left.localeCompare(right))) {
+      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)]);
+    }
+    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 FerricStoreSession = class {
+  client;
+  sessionId;
+  keyPrefix;
+  initialItems;
+  lockOptions;
+  sessionKey;
+  lockKey;
+  constructor(client, options = {}) {
+    this.client = client;
+    this.sessionId = options.sessionId ?? (0, import_node_crypto3.randomUUID)();
+    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
+    };
+    const digest = (0, import_node_crypto3.createHash)("sha256").update(this.sessionId, "utf8").digest("hex");
+    this.sessionKey = `${this.keyPrefix}:{oais:${digest}}:session`;
+    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 = snapshotDigest(transaction);
+    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) {
+          throw new Error("session history operation was already applied with a different transaction");
+        }
+        return state;
+      }
+      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 () => {
+      const current = await this.readState();
+      const next = await operation(current);
+      await this.client.command("HSET", this.sessionKey, SESSION_STATE_FIELD, encodeSnapshot(next));
+    }, this.lockOptions);
+  }
+  async readState() {
+    const value = await this.client.command("HGET", this.sessionKey, SESSION_STATE_FIELD);
+    if (value == null) return 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 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);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FerricStoreSession
+});
+//# sourceMappingURL=openai-agents.cjs.map