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

package/README.md

@@ -94,8 +94,33 @@ Mentions, a named recipient and `trigger_ai` answer in every mode. The kernel st
 | `"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.
 
+### Members, Seats and Agents
+
+The typed surface of the membership doors (Agent System Master Spec D13–D21). Each function forwards one gateway call with the exact params the kernel reads and returns its receipt; the hooks (`useInviteMember`, `useAcceptInvite`, `useSeatMember`, `useCreateAgent`, `useAnswerInput`) wrap the same calls with the cache invalidation each needs.
+
+| Call | Kernel door | What it does |
+|------|-------------|--------------|
+| `inviteMember({ email, target_scope_id, role? })` | `invite-member` | A member item, `pending` until accepted. `role` is their standing in the account (ladder role, default `editor`; `ROLE_ABOVE_INVITER` if above yours). Returns `member_id`. |
+| `seatMember({ chat_id, member_id, role? })` | `link` (`has_member`) | Seats them on one chat (a channel) or breakout (a thread root). `role` goes in the edge `context` and is their role on that chat only; absent reads as editor. There is no `metadata` on an edge. Seat an invited member right after the invite: the roster shows the seat as pending and it opens on accept. |
+| `acceptInvite({ member_id })` | `accept-invite` | The member turns `active`; `can_do` on every chat (and thread/breakout under it) they are seated on is false before this call and true after. No second seating step. |
+| `createAgent({ display_name, description?, role_path?, character?, upload?, instructions? })` | `create-agent` | One transaction: identity, home member item, `instructions/` blocks, account-wide role, seats in every space you are in. `role_path` must already exist (`ROLE_NOT_FOUND`); omit it for the user-default role. Only a person may call it. Returns `principal_id`, `handle`, `member_id`, `member_path`, `seats`. It creates no chat: to talk to the agent, `create-channel` with `member_ids: [principal_id]` births a DM. |
+| `answerInput({ step_id, answer, input_request_id? \| input_request? })` | `todo-control` `answer_input` | Answers a step that is `awaiting_input`, with either the request id or the request object read from the step (`TODO_INPUT_CHANGED` if the step moved on). The kernel records `input_response`, returns the step to pending and wakes the assignee; the agent decides the next step. Nothing mechanical reads the answer as yes or no. |
+
+`update` with `type_data` **merges at the top level**: each key sent replaces that whole key, keys not sent are kept (`{ type_data: { ai_mode: 'strict' } }` changes the mode and nothing else; `_remove_keys: ['x']` deletes a key). A channel's `name` (its path) is governed and refused; change `type_data.display_name`.
+
 ### VFS Operations (pure async functions)
 - `normalizeItem(raw)` — Normalize raw gateway response to `VFSItem`
 - `fetchVfsItem(path)` — Fetch a single item
@@ -108,6 +133,7 @@ The SDK does not decide when AI should respond, spawn agents, or infer agent ide
 - `fetchVfsTree(path, depth?, types?, limit?)` — Fetch recursive tree
 - `fetchMemberFocus(scopeId, types?, limit?)` — Fetch member-focus items
 - `fetchResolvedItems(contextId, itemType)` — Imperative form of `useResolvedItems` (access resolution)
+- `inviteMember` / `acceptInvite` / `seatMember` / `createAgent` / `answerInput` — see Members, Seats and Agents
 
 ### Cache Invalidation
 - `invalidateChildren(path)` — Invalidate children query