@ferricstore/ferricstore 0.11.11 → 0.12.1

package/docs/api/media/agent-frameworks.md

@@ -0,0 +1,176 @@
+# Agent framework persistence
+
+FerricStore's TypeScript package has optional adapters for LangGraph.js and the
+OpenAI Agents SDK. They live in separate package entry points, so the base SDK
+does not load either framework.
+
+## Install
+
+For LangGraph.js:
+
+```bash
+npm install @ferricstore/ferricstore @langchain/langgraph @langchain/core
+```
+
+For the OpenAI Agents SDK:
+
+```bash
+npm install @ferricstore/ferricstore @openai/agents
+```
+
+Both adapters accept the normal `FerricStoreClient`. Their serialization is
+independent of the client's configured codec.
+
+## LangGraph.js checkpoints
+
+`FerricStoreSaver` implements LangGraph's `BaseCheckpointSaver` contract:
+
+```ts
+import { Annotation, END, START, StateGraph } from "@langchain/langgraph";
+import { FerricStoreClient } from "@ferricstore/ferricstore";
+import { FerricStoreSaver } from "@ferricstore/ferricstore/langgraph";
+
+const client = await FerricStoreClient.fromUrl("ferric://127.0.0.1:6388");
+const saver = new FerricStoreSaver(client);
+
+const State = Annotation.Root({ count: Annotation<number>() });
+const graph = new StateGraph(State)
+  .addNode("increment", ({ count }) => ({ count: count + 1 }))
+  .addEdge(START, "increment")
+  .addEdge("increment", END)
+  .compile({ checkpointer: saver });
+
+await graph.invoke(
+  { count: 0 },
+  { configurable: { thread_id: "agent-42" } }
+);
+```
+
+The saver supports named checkpoint namespaces, latest and exact reads,
+ordered and filtered listing, parent chains, pending writes, retry-safe write
+indexes, global listing, and complete thread deletion. It uses LangGraph's
+serializer, so framework-specific values round-trip correctly.
+
+Checkpoint mutations are serialized per thread with renewable,
+ownership-checked locks. Indexes are published before the final checkpoint
+record; readers validate each record and skip incomplete entries. This makes a
+process failure during publication invisible and a retry safe.
+
+## LangGraph.js long-term memory
+
+`FerricStoreStore` implements `BaseStore`:
+
+```ts
+import { FerricStoreStore } from "@ferricstore/ferricstore/langgraph";
+
+const store = new FerricStoreStore(client);
+
+await store.put(["users", "u-42"], "preferences", {
+  language: "en",
+  notifications: true
+});
+
+const memories = await store.search(["users", "u-42"], {
+  filter: { notifications: true }
+});
+```
+
+It supports hierarchical namespaces, atomic per-item mutation ordering,
+batched operations, exact and comparison filters (`$eq`, `$ne`, `$gt`, `$gte`,
+`$lt`, `$lte`, `$in`, `$nin`), ordered pagination, namespace listing, updates,
+and deletion.
+Semantic `query` search currently throws a clear error because no vector index
+is configured; it never silently returns unranked data.
+
+## Run LangGraph inside FerricFlow
+
+The checkpointer makes graph steps resumable. `LangGraphFlow` adds the durable
+outer lifecycle: leases and fencing, retries, scheduled work, signals,
+approvals, workflow history, and terminal state.
+
+```ts
+import { LangGraphFlow } from "@ferricstore/ferricstore/langgraph";
+
+const agentFlow = new LangGraphFlow(graph, {
+  interruptState: "waiting_for_approval"
+});
+
+workflow.state("running", agentFlow.handler.bind(agentFlow));
+```
+
+By default, the bridge derives a stable LangGraph `thread_id` from the Flow
+type, partition, and ID. It sends the Flow payload on the first invocation and
+uses `null` input when a checkpoint already exists. LangGraph runtime context
+includes the active `WorkflowContext`. Completed graphs become `complete()`
+outcomes; interrupts can transition to a chosen Flow state or use a custom
+outcome mapper. Call `resume(flowContext, value)` from a handler to send a
+LangGraph `Command({ resume: value })`.
+
+Static `invokeOptions` and values returned by the `config` callback are merged,
+including their nested `configurable` and `metadata` objects. Dynamic values
+override static values; the bridge always owns `thread_id`, `checkpoint_ns`, and
+the `ferricflow_*` metadata fields. An explicitly supplied runtime context is
+preserved.
+
+The graph checkpointer and FerricFlow solve different layers and are intended
+to be used together:
+
+```text
+FerricFlow durable run lifecycle
+        ↓
+LangGraphFlow invocation bridge
+        ↓
+LangGraph graph + FerricStoreSaver
+        ↓
+FerricStore
+```
+
+## OpenAI Agents SDK Session
+
+`FerricStoreSession` implements the base `Session` contract plus the optional
+history rewrite and atomic transaction capabilities used by the current
+OpenAI Agents SDK:
+
+```ts
+import { Agent, run } from "@openai/agents";
+import { FerricStoreSession } from "@ferricstore/ferricstore/openai-agents";
+
+const session = new FerricStoreSession(client, {
+  sessionId: "customer-42"
+});
+const agent = new Agent({ name: "Support", instructions: "Be helpful." });
+
+await run(agent, "Where is my order?", { session });
+```
+
+The adapter provides chronological reads with tail limits, append, pop,
+clear, compaction replacement, function-call history rewrites, and atomic
+`append_items` / `replace_suffix` transactions. A transaction stores its
+operation ID and history mutation in one atomic record. Repeating the same
+operation is a no-op; reusing its ID for different content or replacing a
+non-matching suffix fails without changing history. Versioned transaction
+digests are deterministic across worker locales, while receipts created by the
+original locale-ordered format remain valid during migration. When an existing
+deployment also changes locale, pass its previous locale tags through
+`legacyReceiptLocales` until its receipts have been replayed and upgraded.
+
+All session mutations use a renewable FerricStore lock for contention control
+and a native compare-and-swap commit for correctness. Reads see either the old
+or new complete session record, never a partial history, and a writer whose
+lock expires cannot overwrite a newer state. `clearSession()` also clears
+transaction receipts. Session persistence stores conversation history; put the
+overall agent run in FerricFlow when it also needs durable leases, retries,
+timers, signals, or multi-step business state.
+
+## Operational options
+
+All three adapters accept `keyPrefix`, `lockTtlMs`, `lockWaitMs`, and
+`lockRetryMs`. The saver and store also accept `scanCount`; the saver accepts a
+custom LangGraph serializer. Defaults are suitable for ordinary use. Give
+different applications or environments different prefixes when they share a
+FerricStore deployment. `lockRetryMs` must be lower than `lockTtlMs`. Before
+publishing authoritative state, the adapters use FerricStore CAS. LangGraph
+checkpoint deletion advances a thread epoch, and BaseStore deletion writes a
+CAS tombstone; their discovery indexes are append-only and validated on reads.
+These rules make late commands from expired writers harmless even across
+processes.

package/docs/api/media/langgraph.ts

@@ -0,0 +1,23 @@
+import { Annotation, END, START, StateGraph } from "@langchain/langgraph";
+import { FerricStoreClient } from "@ferricstore/ferricstore";
+import { FerricStoreSaver, FerricStoreStore } from "@ferricstore/ferricstore/langgraph";
+
+const client = await FerricStoreClient.fromUrl(
+  process.env.FERRICSTORE_URL ?? "ferric://127.0.0.1:6388"
+);
+const checkpointer = new FerricStoreSaver(client);
+const store = new FerricStoreStore(client);
+
+const State = Annotation.Root({ count: Annotation<number>() });
+const graph = new StateGraph(State)
+  .addNode("increment", ({ count }) => ({ count: count + 1 }))
+  .addEdge(START, "increment")
+  .addEdge("increment", END)
+  .compile({ checkpointer, store });
+
+const result = await graph.invoke(
+  { count: 0 },
+  { configurable: { thread_id: "example-agent" } }
+);
+console.log(result);
+await client.close();

package/docs/api/media/openai-agents-session.ts

@@ -0,0 +1,13 @@
+import { Agent, run } from "@openai/agents";
+import { FerricStoreClient } from "@ferricstore/ferricstore";
+import { FerricStoreSession } from "@ferricstore/ferricstore/openai-agents";
+
+const client = await FerricStoreClient.fromUrl(
+  process.env.FERRICSTORE_URL ?? "ferric://127.0.0.1:6388"
+);
+const session = new FerricStoreSession(client, { sessionId: "example-conversation" });
+const agent = new Agent({ name: "Assistant", instructions: "Be concise and helpful." });
+
+const result = await run(agent, "Remember that my preferred language is TypeScript.", { session });
+console.log(result.finalOutput);
+await client.close();

package/docs/api/variables/FERRICSTORE_SDK_VERSION.html

@@ -10,7 +10,7 @@
 <ul class="tsd-breadcrumb" aria-label="Breadcrumb">
 <li><a href="" aria-current="page">FERRICSTORE_SDK_VERSION</a></li></ul>
 <h1>Variable FERRICSTORE_SDK_VERSION<code class="tsd-tag">Const</code></h1></div>
-<div class="tsd-signature"><span class="tsd-kind-variable">FERRICSTORE_SDK_VERSION</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">&quot;0.11.11&quot;</span></div>
+<div class="tsd-signature"><span class="tsd-kind-variable">FERRICSTORE_SDK_VERSION</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">&quot;0.12.0&quot;</span></div>
 <div class="tsd-comment tsd-typography"><p>TypeScript SDK package version.</p>
 </div><aside class="tsd-sources">
 <ul>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferricstore/ferricstore",
-  "version": "0.11.11",
+  "version": "0.12.1",
   "description": "TypeScript SDK for FerricStore and FerricFlow",
   "type": "module",
   "license": "Apache-2.0",
@@ -52,6 +52,26 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./langgraph": {
+      "import": {
+        "types": "./dist/langgraph.d.ts",
+        "default": "./dist/langgraph.js"
+      },
+      "require": {
+        "types": "./dist/langgraph.d.cts",
+        "default": "./dist/langgraph.cjs"
+      }
+    },
+    "./openai-agents": {
+      "import": {
+        "types": "./dist/openai-agents.d.ts",
+        "default": "./dist/openai-agents.js"
+      },
+      "require": {
+        "types": "./dist/openai-agents.d.cts",
+        "default": "./dist/openai-agents.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -61,10 +81,10 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --sourcemap --clean",
+    "build": "tsup src/index.ts src/langgraph.ts src/openai-agents.ts --format esm,cjs --dts --sourcemap --clean --splitting false",
     "check": "npm run typecheck && npm run lint && npm run test && npm run build && npm run test:exports && npm run docs:check",
-    "docs": "typedoc",
-    "docs:check": "typedoc --logLevel Warn && node scripts/check-generated-docs.mjs",
+    "docs": "typedoc --logLevel Warn && typedoc --options typedoc.agent.json --logLevel Warn",
+    "docs:check": "npm run docs && node scripts/check-generated-docs.mjs",
     "integration:down": "docker compose down -v",
     "integration:up": "docker compose up -d ferricstore && node scripts/wait-for-ferricstore.mjs",
     "lint": "eslint .",
@@ -84,6 +104,9 @@
     "@emnapi/core": "^1.11.3",
     "@emnapi/runtime": "^1.11.3",
     "@eslint/js": "^10.0.1",
+    "@langchain/core": "^1.2.9",
+    "@langchain/langgraph": "^1.4.12",
+    "@openai/agents": "^0.17.0",
     "@types/node": "^22.20.1",
     "eslint": "^10.9.0",
     "tsup": "^8.5.1",
@@ -91,5 +114,21 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.67.0",
     "vitest": "^4.1.11"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=1.1.48 <2",
+    "@langchain/langgraph": ">=1.4.12 <2",
+    "@openai/agents": ">=0.17.0 <1"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    },
+    "@langchain/langgraph": {
+      "optional": true
+    },
+    "@openai/agents": {
+      "optional": true
+    }
   }
 }