@ai4b-team/fsaos-gateway-sdk 3.41.0 → 4.0.0

package/README.md

@@ -76,23 +76,23 @@ Plain HTML can use the same contract without loading the SDK:
 ### Query Key Factory
 - `vfsKeys` — Deterministic query keys for all VFS data
 
-### Channel AI Auto-Response Policy
+### Channel Room Modes
 
-Channels contain principals as members. AI is represented as a principal/member, not as a separate channel type. The SDK exposes channel policy through `Channel.aiMode`, which is now binary:
+Channels contain principals as members. AI is represented as a principal/member, not as a separate channel type. The SDK exposes the room mode through `Channel.aiMode` (Agent System Master Spec D17; kernel revision `b7c4d2a9e1f3`, 2026-10-29):
 
 | `Channel.aiMode` | Meaning |
 |------------------|---------|
-| `"on"` | AI auto-response is enabled for the channel. |
-| `"off"` | AI does not auto-respond; if an AI principal is a member, it must be explicitly invoked or addressed like any other member. |
+| `"open"` | The floor decision runs on every message; whoever it names answers. |
+| `"active"` | Only the on-duty agents answer a person (`Channel.activeAgentIds`; absent = every agent seated in the channel). An agent's message wakes another agent by mention only. |
+| `"strict"` | Mention or named recipient only. |
+| `"hand_raise"` | The floor decision runs on a person's message but nobody is woken; its answer arrives as the `conversation.hands_raised` event (`subscribeToEvents`) and the person picks who speaks, an explicit-recipient send. |
 
-During the backend migration, the channel normalizer accepts legacy backend values and exposes the binary SDK contract to consumers:
+Mentions, a named recipient and `trigger_ai` answer in every mode. The kernel stores exactly these four values (`CHANNEL_AI_MODES`) and refuses any other at `create-channel` (`CHANNEL_AI_MODE_INVALID`); the legacy `on`/`off` rows were rewritten `on → active`, `off → strict`. A row the kernel has not rewritten is read the same way:
 
 | Legacy/backend value | SDK value |
 |----------------------|-----------|
-| `"auto"` | `"on"` |
-| `"mention"` | `"off"` |
-| `"off"` | `"off"` |
-| missing or unknown | `"off"` |
+| `"on"`, `"auto"` | `"active"` |
+| `"off"`, `"mention"`, missing or unknown | `"strict"` |
 
 The SDK does not decide when AI should respond, spawn agents, or infer agent identity. It forwards gateway calls and normalizes read models; the kernel owns channel policy and message-trigger behavior.
 
@@ -209,7 +209,7 @@ reconciles the remaining count. No background polling is used.
 |------|-------------|
 | `useChannelMessages(opts)` | Channel messages + bundled cards |
 | `useInfiniteChannelMessages(opts)` | Cursor-paginated messages (live tail) |
-| `useAllChannels()` / `useChannels()` / `useDmChannels()` | Channel lists (all / public / DM) |
+| `useAllChannels()` / `useChannels()` / `useDmChannels()` | Channel lists (all / public / DM); archived channels only with `{ includeArchived: true }` |
 | `usePersonalItemOrder('channel-order' \| 'project-order', items)` | Apply and save the selected Space member's personal order through existing arrangements. |
 | `useNotifications(opts?)` | Notifications feed |
 | `useUnreadCounts(opts?)` | Aggregated unread counts |