@ai4b-team/fsaos-gateway-sdk 3.42.0 → 4.1.0

package/README.md

@@ -76,23 +76,34 @@ 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"` |
+
+### Chats, Threads and Breakouts
+
+A channel is a chat (a DM or a group) and its members are its audience (Agent System Master Spec D21, 2026-10-30). Inside a chat every message is one thing, a message, with two flags the kernel computes on each top-level row:
+
+| Flag | Meaning |
+|------|---------|
+| `ChannelMessage.reply_count > 0` | A thread: a side conversation inside the chat (`useChannelMessages(...).threads`). |
+| `ChannelMessage.member_count > 0` | A breakout: the thread root has members of its own, and only they (and the owners above it) read and post in it; the kernel hides it from everyone else (`useChannelMessages(...).breakouts`). |
+
+A chat created with `member_ids` is born `auto_thread: false` (messages happen in the channel feed); a member's own agent channel keeps `auto_thread: true`. Agents hand work to other agents in other chats with the `todo` tool's `assign_to` / `report_to`; the assignee is woken in that chat and the delegating agent is woken in the original conversation when the work completes, fails or needs input.
 
 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.