@ai4b-team/fsaos-gateway-sdk 3.37.0 → 3.38.0

package/README.md

@@ -138,6 +138,7 @@ The SDK does not decide when AI should respond, spawn agents, or infer agent ide
 | `useList(path)` / `useChildren(path)` | Children of a path (location) |
 | `useItems(filter)` | Items by type with filters (location; account-scoped, **not** frame-aware) |
 | `useInfiniteItems(filter, { realtime? })` | Kernel-filtered infinite pages; optional event-driven refresh, cached items, load more and refetch. No polling. |
+| `useIncrementalItems(filter, { shouldReadUpdate? })` | Live created-at feed: query pages once, point-read inserts and selected updates, reconcile after deletes/reconnect. No polling. |
 | `useInfiniteChildren(path)` | Infinite-scroll directory listing |
 | `useTree(path, depth?)` | Recursive tree |
 | `useSearch(query, types?)` | Keyword search |
@@ -168,6 +169,15 @@ loaded items moving out still refresh their former list. Closed lists are marked
 stale without fetching, and unchanged lists reopen from cache. All consumers of
 the same filtered query should use the same realtime setting.
 
+For a high-traffic message feed, `useIncrementalItems` avoids reloading every
+loaded page whenever a reply changes. It supports one item `type`, an explicit
+`scope`, `sort_by: 'created_at'`, and optional `parent_id`, `fields`, or
+`field_in`. It returns the same list and pagination fields as
+`useInfiniteItems`. Inserts cost one item read; updates are ignored unless
+`shouldReadUpdate(change, loadedItems)` selects them; deletes and reconnects
+reconcile the pages. More complex filters fall back to the ordinary realtime
+listing. The host still needs its normal account or path WebSocket subscription.
+
 A filter names one `type`, or `any_of`: 1-10 groups, each with an `item_type`,
 `fields` and `field_in`, so one listing spans item types with one total and one
 page order. `discovery: 'catalog'` keeps only what the kernel classes as a