@openmarket/rooms-client 0.5.0 → 0.6.0

package/dist/agent/armed-mode.d.ts

@@ -100,14 +100,6 @@ export declare function rearmedRoomState(roomId: string, retired: ArmedRoomState
 /** Seqs of the user's own posts in a window of entries; the reply-trigger
  *  check tests `inReplyTo` against this set. Pure. */
 export declare function ownSeqsOf(entries: ReadonlyArray<RoomLedgerEntry>, ownUserId: string): Set<number>;
-/**
- * Whether a single incoming entry is a qualifying TRIGGER: a NEW human POST in
- * the room that @mentions the user's own handle, OR (when `ownSeqs` is given)
- * directly replies to one of the user's own messages. Reply semantics match a
- * mention (replying pings the author), so armed mode treats both as addressed
- * to the user. Agent posts, system entries, the user's own posts, and
- * non-mentions never trigger. Pure.
- */
 export declare function isTriggeringEntry(entry: RoomLedgerEntry, ownHandle: string, ownUserId: string, ownSeqs?: ReadonlySet<number>): boolean;
 /**
  * The newest qualifying trigger among entries strictly newer than

package/dist/agent/armed-mode.js

@@ -117,11 +117,21 @@ export function ownSeqsOf(entries, ownUserId) {
  * to the user. Agent posts, system entries, the user's own posts, and
  * non-mentions never trigger. Pure.
  */
+/** Webhook-ingested entries are machine posts even though isAgent is
+ *  false (the flag marks agent USERS). They must never count as the human
+ *  in any autonomy gate: a webhook @mention cannot start an unreviewed
+ *  autonomous turn, and webhook chatter cannot satisfy the
+ *  human-activity brake. */
+function isWebhookEntry(entry) {
+    return Boolean(entry.metadata?.webhook);
+}
 export function isTriggeringEntry(entry, ownHandle, ownUserId, ownSeqs) {
     if (entry.type !== RoomLedgerEntryType.POST)
         return false;
     if (entry.isAgent)
         return false;
+    if (isWebhookEntry(entry))
+        return false;
     if (!entry.text?.trim())
         return false;
     // Never trigger on our own message (we post as this handle/userId).
@@ -312,6 +322,8 @@ export function isHumanResetEntry(entry, ownHandle, ownUserId) {
         return false;
     if (entry.isAgent)
         return false;
+    if (isWebhookEntry(entry))
+        return false;
     if (entry.userId === ownUserId)
         return false;
     const fromHandle = normalizeHandle(entry.handle).toLowerCase();

package/dist/agent/clients/common.d.ts

@@ -1,5 +1,12 @@
 import { type KnownProvider } from "@earendil-works/pi-ai";
-export type SurfaceId = "cli" | "telegram" | "discord" | "slack" | "webui";
+/** Every chat surface, as a runtime list. The `SurfaceId` union derives from
+ *  this literal so per-surface policy checklists (packages/cli/test/
+ *  harness-budgets.test.ts) can iterate the surfaces at runtime while a new
+ *  entry still breaks type-exhaustive tables at compile time. Adding a
+ *  surface here requires classifying it in EVERY policy set (see AGENTS.md,
+ *  "Harness invariants"). */
+export declare const SURFACE_IDS: readonly ["cli", "telegram", "discord", "slack", "webui"];
+export type SurfaceId = (typeof SURFACE_IDS)[number];
 export interface AgentToolCall {
     id: string;
     name: string;

package/dist/agent/clients/common.js

@@ -1,4 +1,11 @@
 import { getProviders } from "@earendil-works/pi-ai";
+/** Every chat surface, as a runtime list. The `SurfaceId` union derives from
+ *  this literal so per-surface policy checklists (packages/cli/test/
+ *  harness-budgets.test.ts) can iterate the surfaces at runtime while a new
+ *  entry still breaks type-exhaustive tables at compile time. Adding a
+ *  surface here requires classifying it in EVERY policy set (see AGENTS.md,
+ *  "Harness invariants"). */
+export const SURFACE_IDS = ["cli", "telegram", "discord", "slack", "webui"];
 /** OM-level provider for any OpenAI-compatible /v1/chat/completions endpoint
  *  (Ollama, vLLM, LM Studio, llama.cpp, custom proxies). Not a pi-ai
  *  KnownProvider: the model object is constructed at turn time from the
@@ -32,7 +39,10 @@ export function stringifyToolContent(value) {
         return "";
     if (typeof value === "string")
         return value;
-    return JSON.stringify(value, null, 2);
+    // Compact on purpose: this string is LLM input, and 2-space pretty-printing
+    // inflated every structured tool result by roughly a fifth in tokens for
+    // zero model benefit.
+    return JSON.stringify(value);
 }
 export function parseToolArguments(raw) {
     if (raw === undefined || raw === null)

package/dist/agent/sidebar-model.d.ts

@@ -22,6 +22,9 @@ export interface SidebarRoom {
     headSeq: number | null;
     lastReadSeq: number | null;
     unread: number;
+    /** Unread mention count from the latest read-state snapshot: the server's
+     *  number verbatim, 0 when the snapshot carried none for this room. */
+    mentionUnread: number;
     joined: boolean;
     /** Topics dial from room meta. Absent reads as "allowed" since the
      *  2026-07-12 dial-default flip; explicit "off" keeps topics inert. */
@@ -40,6 +43,13 @@ export interface SidebarSnapshot {
     dms: SidebarDm[];
     popular: SidebarRoom[];
     globalReplyUnread: number;
+    /** Per-room unread mention counts exactly as the server sent them in the
+     *  latest read-state snapshot: sparse (zero-count rooms absent) and
+     *  global (rooms outside the current listings may appear). Empty when the
+     *  snapshot carried none; a fresh snapshot replaces it wholesale. */
+    mentionCounts: Record<string, number>;
+    /** User-wide unread mention total from the same snapshot. */
+    mentionTotal: number;
     fetchedAt: number;
 }
 export declare const EMPTY_SIDEBAR_SNAPSHOT: SidebarSnapshot;
@@ -48,10 +58,22 @@ export declare function computeRoomUnread(input: {
     headSeq: number | null;
     lastReadSeq: number | null;
 }): number;
+/** A READ_STATE reply that carries the additive mention decorations beside
+ *  the cursor map (RoomReadStatePayload satisfies this shape). Old
+ *  fetchReadState implementations returning the bare cursor Record keep
+ *  working; mention fields then read as zero. */
+export interface SidebarReadState {
+    readState: Record<string, number>;
+    mentionCounts?: Record<string, number> | undefined;
+    mentionTotal?: number | undefined;
+}
 export declare function buildSidebarSnapshot(input: {
     rooms: RoomMeta[];
     spaces: RoomSpace[];
     readState: Record<string, number>;
+    /** Server numbers pass through verbatim; merge policy is the caller's. */
+    mentionCounts?: Record<string, number> | undefined;
+    mentionTotal?: number | undefined;
     dms: SidebarDm[];
     globalReplyUnread: number;
     joinedUnread: (roomName: string) => number | null;
@@ -60,7 +82,9 @@ export declare function buildSidebarSnapshot(input: {
 export interface SidebarModelDeps {
     fetchRooms: () => Promise<RoomMeta[]>;
     fetchSpaces: () => Promise<RoomSpace[]>;
-    fetchReadState: (roomNames: string[]) => Promise<Record<string, number>>;
+    /** Either the bare cursor Record (the 0.2.0 shape) or a SidebarReadState
+     *  whose mention decorations feed the snapshot's mention fields. */
+    fetchReadState: (roomNames: string[]) => Promise<Record<string, number> | SidebarReadState>;
     fetchDms: () => Promise<SidebarDm[]>;
     fetchGlobalReplyUnread: () => Promise<number>;
     joinedUnread: (roomName: string) => number | null;

package/dist/agent/sidebar-model.js

@@ -4,6 +4,8 @@ export const EMPTY_SIDEBAR_SNAPSHOT = {
     dms: [],
     popular: [],
     globalReplyUnread: 0,
+    mentionCounts: {},
+    mentionTotal: 0,
     fetchedAt: 0,
 };
 const POPULAR_MAX = 6;
@@ -34,6 +36,11 @@ export function buildSidebarSnapshot(input) {
             headSeq,
             lastReadSeq,
             unread: computeRoomUnread({ joinedUnread, headSeq, lastReadSeq }),
+            // Own-key guard like the readState read above: rooms named after
+            // Object.prototype members must read 0 from a sparse map, not NaN.
+            mentionUnread: Math.max(0, input.mentionCounts && Object.hasOwn(input.mentionCounts, name)
+                ? (input.mentionCounts[name] ?? 0)
+                : 0),
             // Joined = an open context OR a server read cursor (you only get a
             // cursor by having been in the room). This is what decides whether a
             // room lives in your channel tree or in the POPULAR discovery shelf.
@@ -92,9 +99,30 @@ export function buildSidebarSnapshot(input) {
         dms: input.dms,
         popular,
         globalReplyUnread: Math.max(0, input.globalReplyUnread),
+        mentionCounts: input.mentionCounts ?? {},
+        mentionTotal: Math.max(0, input.mentionTotal ?? 0),
         fetchedAt: input.now,
     };
 }
+/** A bare cursor Record maps room name to seq (numbers only), so an object
+ *  under the "readState" key can only be the snapshot shape, even for a
+ *  room literally named "readState" (its cursor would be a number). */
+function normalizeSidebarReadState(reply) {
+    const nested = reply.readState;
+    if (typeof nested === "object" && nested !== null) {
+        const snapshot = reply;
+        return {
+            readState: snapshot.readState,
+            mentionCounts: snapshot.mentionCounts,
+            mentionTotal: snapshot.mentionTotal,
+        };
+    }
+    return {
+        readState: reply,
+        mentionCounts: undefined,
+        mentionTotal: undefined,
+    };
+}
 export class SidebarModel {
     deps;
     snapshotValue = EMPTY_SIDEBAR_SNAPSHOT;
@@ -174,13 +202,16 @@ export class SidebarModel {
             this.deps.fetchDms().catch(() => []),
             this.deps.fetchGlobalReplyUnread().catch(() => 0),
         ]);
-        const readState = await this.deps
+        const readStateReply = await this.deps
             .fetchReadState(rooms.map((room) => room.name))
             .catch(() => ({}));
+        const { readState, mentionCounts, mentionTotal } = normalizeSidebarReadState(readStateReply);
         return buildSidebarSnapshot({
             rooms,
             spaces,
             readState,
+            mentionCounts,
+            mentionTotal,
             dms,
             globalReplyUnread,
             joinedUnread: this.deps.joinedUnread,

package/dist/shared/rooms-protocol.d.ts

@@ -231,7 +231,7 @@ export interface RoomLedgerEntry {
     pinnedAt?: string | number | Date | null | undefined;
     attachments?: RoomAttachment[] | undefined;
     roomRole?: RoomRole | null | undefined;
-    metadata?: (Record<string, unknown> & Partial<RoomForwardMetadata>) | undefined;
+    metadata?: (Record<string, unknown> & Partial<RoomForwardMetadata> & Partial<RoomWebhookMetadata>) | undefined;
 }
 export type RoomForwardedFrom = {
     kind: "room";
@@ -245,6 +245,18 @@ export type RoomForwardedFrom = {
 export interface RoomForwardMetadata {
     forwardedFrom: RoomForwardedFrom;
 }
+/** Sender identity for messages posted through a channel webhook (the
+ *  Discord-compatible ingest). Entries carrying it render the webhook's
+ *  name and avatar with an APP-style badge; the entry's handle mirrors
+ *  the display name and its userId is the synthetic `webhook:<id>`, so a
+ *  webhook can never impersonate a member. */
+export interface RoomWebhookMetadata {
+    webhook: {
+        id: string;
+        name: string;
+        avatarUrl?: string | undefined;
+    };
+}
 export interface RoomAttachment {
     /**
      * Object key under room-attachments/; clients sign it at render time.
@@ -330,6 +342,16 @@ export interface RoomReadStatePayload {
      *  Present when the store surfaces it and on ROOM_SET_ATTENTION acks
      *  (which reply READ_STATE scoped to the one room, readState empty). */
     attention?: Record<string, RoomTopicAttention> | undefined;
+    /** Unread mention counts by room, server-computed from the notify
+     *  worker's ROOM_MENTION rows so badges survive reload and clear through
+     *  the ack path. Unlike readState/attention the map is SPARSE AND
+     *  GLOBAL: every room with a nonzero count appears (requested or not),
+     *  zero-count rooms are absent. Missing on servers older than the
+     *  mentions-completion store. */
+    mentionCounts?: Record<string, number> | undefined;
+    /** User-wide unread mention total (drives the app badge). Rides beside
+     *  mentionCounts; missing on older servers. */
+    mentionTotal?: number | undefined;
     requestId?: string | undefined;
 }
 export interface RoomSearchResultsPayload {
@@ -491,7 +513,7 @@ export interface RoomDmMessage {
     createdAt?: string | number | undefined;
     /** Sealed DM: content is '' and the opaque envelope rides here. */
     secret?: RoomLedgerSecretPayload | null | undefined;
-    metadata?: (Record<string, unknown> & Partial<RoomForwardMetadata>) | undefined;
+    metadata?: (Record<string, unknown> & Partial<RoomForwardMetadata> & Partial<RoomWebhookMetadata>) | undefined;
     /** Legacy public chat-image URL (renders as-is, no signing). */
     imageUrl?: string | null | undefined;
     /** Private, signed, scanned DM attachments (dm-attachments/ keyspace).

package/dist/social-client.d.ts

@@ -1,5 +1,5 @@
-import type { RoomDmConversation, RoomDmHistory, RoomDmSendResult, RoomDmUnreadConversation, RoomDoc, RoomDocAttribution, RoomDocChanges, RoomDocConflictHead, RoomDocEditingLease, RoomDocProvenance, RoomDocRevision, RoomDocRunRevertResult, RoomDocWriteResult, RoomFollow, RoomFollowResult, RoomFriend, RoomFriendRequests, RoomPublicProfile, RoomRepliesReadResult, RoomRepliesResult, RoomSocialConfig, RoomSpaceRestorePlan, RoomSpaceRestoreReceipt, RoomSuggestion, RoomSuggestionRequest } from "./social-types.js";
-export type { RoomAttachment, RoomDmConversation, RoomDmHistory, RoomDmMessage, RoomDmParticipant, RoomDmSendResult, RoomDmUnreadConversation, RoomDocAttribution, RoomDocEditingLease, RoomDocMergeRegion, RoomDocRevisionSource, RoomDocRunRevertResult, RoomFollow, RoomFollowResult, RoomFriend, RoomFriendRequest, RoomFriendRequests, RoomPublicProfile, RoomRepliesReadResult, RoomRepliesResult, RoomReplyInboxItem, RoomSocialConfig, RoomSpaceRestoreAction, RoomSpaceRestoreActionKind, RoomSpaceRestorePlan, RoomSpaceRestoreReceipt, RoomSpaceRestoreSummary, RoomSuggestion, RoomSuggestionIntent, RoomSuggestionRequest, RoomSuggestionSource, } from "./social-types.js";
+import type { RoomDmConversation, RoomDmHistory, RoomDmSendResult, RoomDmUnreadConversation, RoomDoc, RoomDocAttribution, RoomDocChanges, RoomDocConflictHead, RoomDocEditingLease, RoomDocProvenance, RoomDocRevision, RoomDocRunRevertResult, RoomDocWriteResult, RoomFollow, RoomFollowResult, RoomFriend, RoomFriendRequests, RoomNotificationInboxResult, RoomPublicProfile, RoomRepliesReadResult, RoomRepliesResult, RoomSocialConfig, RoomSpaceRestorePlan, RoomSpaceRestoreReceipt, RoomSuggestion, RoomSuggestionRequest } from "./social-types.js";
+export type { RoomAttachment, RoomDmConversation, RoomDmHistory, RoomDmMessage, RoomDmParticipant, RoomDmSendResult, RoomDmUnreadConversation, RoomDocAttribution, RoomDocEditingLease, RoomDocMergeRegion, RoomDocRevisionSource, RoomDocRunRevertResult, RoomFollow, RoomFollowResult, RoomFriend, RoomFriendRequest, RoomFriendRequests, RoomNotificationInboxItem, RoomNotificationInboxResult, RoomNotificationKind, RoomNotificationMessageData, RoomPublicProfile, RoomRepliesReadResult, RoomRepliesResult, RoomReplyInboxItem, RoomSocialConfig, RoomSpaceRestoreAction, RoomSpaceRestoreActionKind, RoomSpaceRestorePlan, RoomSpaceRestoreReceipt, RoomSpaceRestoreSummary, RoomSuggestion, RoomSuggestionIntent, RoomSuggestionRequest, RoomSuggestionSource, } from "./social-types.js";
 /** Largest per-file size any tier accepts (plus tier). The server enforces
  *  the per-tier caps (free 10MB/file, plus 25MB/file) and daily quotas; this
  *  constant only pre-flights uploads no tier could ever accept. */
@@ -210,6 +210,31 @@ export declare function updateSpaceRole(config: RoomSocialConfig, spaceId: strin
     position?: number;
 }): Promise<RoomSpaceRole>;
 export declare function deleteSpaceRole(config: RoomSocialConfig, spaceId: string, roleId: string): Promise<void>;
+/** A channel webhook: the Discord-compatible ingest capability. The
+ *  posting URL is `<chat-api>/webhooks/<webhookId>/<token>`; the token is
+ *  the whole credential, so treat listed webhooks like secrets. */
+export interface RoomWebhook {
+    webhookId: string;
+    room: string;
+    name: string;
+    avatarUrl: string | null;
+    token: string;
+    createdBy: string;
+    /** Creator's handle at create time (display; createdBy is the id). */
+    createdByHandle?: string | null;
+    createdAt: string;
+    lastUsedAt: string | null;
+    deliveryCount: number;
+    disabled: boolean;
+}
+export declare function listRoomWebhooks(config: RoomSocialConfig, room: string): Promise<RoomWebhook[]>;
+export declare function createRoomWebhook(config: RoomSocialConfig, room: string, input: {
+    name: string;
+    avatarUrl?: string | null;
+}): Promise<RoomWebhook>;
+export declare function deleteRoomWebhook(config: RoomSocialConfig, room: string, webhookId: string): Promise<void>;
+/** Rotate the capability: the old URL dies immediately. */
+export declare function regenerateRoomWebhookToken(config: RoomSocialConfig, room: string, webhookId: string): Promise<RoomWebhook>;
 export declare function setSpaceMemberRoles(config: RoomSocialConfig, spaceId: string, targetUserId: string, roleIds: string[]): Promise<{
     spaceId: string;
     userId: string;
@@ -368,6 +393,24 @@ export declare function markRoomRepliesRead(config: RoomSocialConfig, options?:
     room?: string;
     before?: string | Date;
 }): Promise<RoomRepliesReadResult>;
+/**
+ * The chat-scoped notification inbox (GET /users/notifications): the durable
+ * rows behind mention/reply/dm/keyword pushes, newest first, room kinds only.
+ * Voucher-reachable like the rest of the chat surface (the bearer token may
+ * be an API key or a chat voucher). Pagination is the composite cursor: pass
+ * the previous page's lastCursor and lastCursorId back TOGETHER (the store
+ * rejects one without the other); unread=true filters to unread rows.
+ */
+export declare function listRoomNotifications(config: RoomSocialConfig, options?: {
+    limit?: number | undefined;
+    /** Feed a page's lastCursor back here (explicit undefined reads as
+     *  "first page", so `page.lastCursor ?? undefined` composes under
+     *  exactOptionalPropertyTypes). */
+    cursor?: string | undefined;
+    cursorId?: string | undefined;
+    unread?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+}): Promise<RoomNotificationInboxResult>;
 export declare function suggestRooms(config: RoomSocialConfig, request: RoomSuggestionRequest, options?: {
     signal?: AbortSignal;
 }): Promise<RoomSuggestion[]>;
@@ -377,6 +420,9 @@ export declare function socialRequest<T>(config: RoomSocialConfig, path: string,
     signal?: AbortSignal;
     formData?: FormData;
     headers?: Record<string, string>;
+    /** Fetch cache mode; token-bearing reads pass "no-store" so posting
+     *  credentials never persist in a browser HTTP cache. */
+    cache?: RequestCache;
 }): Promise<T>;
 export declare function cleanUsername(username: string): string;
 export declare function cleanRoomId(room: string): string;

package/dist/social-client.js

@@ -378,6 +378,36 @@ export async function updateSpaceRole(config, spaceId, roleId, patch) {
 export async function deleteSpaceRole(config, spaceId, roleId) {
     await socialRequest(config, `/spaces/${encodeURIComponent(spaceId)}/roles/${encodeURIComponent(roleId)}`, { method: "DELETE" });
 }
+export async function listRoomWebhooks(config, room) {
+    const result = await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/webhooks`, { cache: "no-store" });
+    return result.webhooks ?? [];
+}
+export async function createRoomWebhook(config, room, input) {
+    const result = await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/webhooks`, { method: "POST", body: input });
+    if (!result.webhook)
+        throw new Error("Webhook create returned no webhook");
+    return result.webhook;
+}
+/** Store-minted webhook ids are `wh_<hex>`. Anything else is rejected
+ *  BEFORE it reaches a URL: encodeURIComponent does not escape dots, and
+ *  a `..` segment would normalize `/webhooks/..` onto the parent room
+ *  route, turning a webhook delete into a channel archive. */
+function assertWebhookId(webhookId) {
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(webhookId)) {
+        throw new Error(`Invalid webhook id: ${JSON.stringify(webhookId)}`);
+    }
+    return webhookId;
+}
+export async function deleteRoomWebhook(config, room, webhookId) {
+    await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/webhooks/${assertWebhookId(webhookId)}`, { method: "DELETE" });
+}
+/** Rotate the capability: the old URL dies immediately. */
+export async function regenerateRoomWebhookToken(config, room, webhookId) {
+    const result = await socialRequest(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/webhooks/${assertWebhookId(webhookId)}/regenerate`, { method: "POST" });
+    if (!result.webhook)
+        throw new Error("Webhook regenerate returned no webhook");
+    return result.webhook;
+}
 export async function setSpaceMemberRoles(config, spaceId, targetUserId, roleIds) {
     return socialRequest(config, `/spaces/${encodeURIComponent(spaceId)}/members/${encodeURIComponent(targetUserId)}/roles`, { method: "PUT", body: { roleIds } });
 }
@@ -592,6 +622,35 @@ export async function markRoomRepliesRead(config, options = {}) {
     });
     return { markedRead: result.markedRead ?? 0 };
 }
+/**
+ * The chat-scoped notification inbox (GET /users/notifications): the durable
+ * rows behind mention/reply/dm/keyword pushes, newest first, room kinds only.
+ * Voucher-reachable like the rest of the chat surface (the bearer token may
+ * be an API key or a chat voucher). Pagination is the composite cursor: pass
+ * the previous page's lastCursor and lastCursorId back TOGETHER (the store
+ * rejects one without the other); unread=true filters to unread rows.
+ */
+export async function listRoomNotifications(config, options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit !== undefined)
+        params.set("limit", String(options.limit));
+    if (options.cursor !== undefined)
+        params.set("cursor", options.cursor);
+    if (options.cursorId !== undefined)
+        params.set("cursorId", options.cursorId);
+    if (options.unread !== undefined)
+        params.set("unread", String(options.unread));
+    const init = {};
+    if (options.signal)
+        init.signal = options.signal;
+    const result = await socialRequest(config, `/users/notifications${params.size ? `?${params.toString()}` : ""}`, init);
+    return {
+        notifications: result.notifications ?? [],
+        hasMore: result.hasMore ?? false,
+        lastCursor: result.lastCursor ?? null,
+        lastCursorId: result.lastCursorId ?? null,
+    };
+}
 export async function suggestRooms(config, request, options = {}) {
     const init = {
         method: "POST",
@@ -607,6 +666,7 @@ export async function socialRequest(config, path, init = {}) {
     const hasJsonBody = init.body !== undefined;
     const res = await fetch(url, {
         method: init.method ?? "GET",
+        ...(init.cache ? { cache: init.cache } : {}),
         headers: {
             Authorization: `Bearer ${config.apiKey}`,
             Accept: "application/json",

package/dist/social-types.d.ts

@@ -171,6 +171,44 @@ export interface RoomRepliesResult {
 export interface RoomRepliesReadResult {
     markedRead: number;
 }
+/** The room kinds the chat notification inbox returns (the store's
+ *  ROOM_INBOX_NOTIFICATION_TYPES). ROOM_FOLLOW rows stay out of the inbox:
+ *  follow is a push channel, not a badge source. */
+export type RoomNotificationKind = "ROOM_MENTION" | "ROOM_REPLY" | "ROOM_DM" | "ROOM_KEYWORD";
+/** Shared room payload on a notification row, wire names verbatim from the
+ *  store's notification schema (room_message_data). `preview` follows the
+ *  push body rules (140 chars, empty for sealed content); `hash` is the
+ *  client deep link. */
+export interface RoomNotificationMessageData {
+    kind: "dm" | "mention" | "reply" | "follow" | "keyword";
+    room_id?: string;
+    room_name?: string;
+    space_id?: string;
+    conversation_id?: string;
+    seq?: number;
+    from_handle: string;
+    preview: string;
+    hash: string;
+}
+/** One chat notification inbox row: the store's explicit field pick
+ *  (snake_case wire names, dates as ISO strings, room_message_data only
+ *  when the row carries one). */
+export interface RoomNotificationInboxItem {
+    id: string;
+    type: RoomNotificationKind;
+    created_at: string;
+    read_at: string | null;
+    room_message_data?: RoomNotificationMessageData;
+}
+/** A newest-first inbox page plus the composite cursor naming the last row
+ *  returned; feed lastCursor and lastCursorId back together to request the
+ *  next page. Both are null on an empty page. */
+export interface RoomNotificationInboxResult {
+    notifications: RoomNotificationInboxItem[];
+    hasMore: boolean;
+    lastCursor: string | null;
+    lastCursorId: string | null;
+}
 /** A living markdown doc scoped to a space (head state; content on demand). */
 export interface RoomDoc {
     docId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmarket/rooms-client",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "OM Rooms protocol client: wire types, WebSocket + REST clients, and chat view-models. Browser-safe (no node:/bun: imports).",
   "type": "module",
   "license": "Apache-2.0",
@@ -17,12 +17,7 @@
     "bun": ">=1.3.0",
     "node": ">=22"
   },
-  "files": [
-    "src",
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": ["src", "dist", "README.md", "LICENSE"],
   "publishConfig": {
     "access": "public"
   },

package/src/agent/armed-mode.ts

@@ -164,6 +164,17 @@ export function ownSeqsOf(entries: ReadonlyArray<RoomLedgerEntry>, ownUserId: st
  * to the user. Agent posts, system entries, the user's own posts, and
  * non-mentions never trigger. Pure.
  */
+/** Webhook-ingested entries are machine posts even though isAgent is
+ *  false (the flag marks agent USERS). They must never count as the human
+ *  in any autonomy gate: a webhook @mention cannot start an unreviewed
+ *  autonomous turn, and webhook chatter cannot satisfy the
+ *  human-activity brake. */
+function isWebhookEntry(entry: RoomLedgerEntry): boolean {
+  return Boolean(
+    (entry.metadata as { webhook?: unknown } | undefined)?.webhook,
+  );
+}
+
 export function isTriggeringEntry(
   entry: RoomLedgerEntry,
   ownHandle: string,
@@ -172,6 +183,7 @@ export function isTriggeringEntry(
 ): boolean {
   if (entry.type !== RoomLedgerEntryType.POST) return false;
   if (entry.isAgent) return false;
+  if (isWebhookEntry(entry)) return false;
   if (!entry.text?.trim()) return false;
   // Never trigger on our own message (we post as this handle/userId).
   const fromHandle = normalizeHandle(entry.handle).toLowerCase();
@@ -379,6 +391,7 @@ export function isHumanResetEntry(
 ): boolean {
   if (entry.type !== RoomLedgerEntryType.POST) return false;
   if (entry.isAgent) return false;
+  if (isWebhookEntry(entry)) return false;
   if (entry.userId === ownUserId) return false;
   const fromHandle = normalizeHandle(entry.handle).toLowerCase();
   const me = normalizeHandle(ownHandle).toLowerCase();

package/src/agent/clients/common.ts

@@ -1,6 +1,14 @@
 import { getProviders, type KnownProvider } from "@earendil-works/pi-ai";
 
-export type SurfaceId = "cli" | "telegram" | "discord" | "slack" | "webui";
+/** Every chat surface, as a runtime list. The `SurfaceId` union derives from
+ *  this literal so per-surface policy checklists (packages/cli/test/
+ *  harness-budgets.test.ts) can iterate the surfaces at runtime while a new
+ *  entry still breaks type-exhaustive tables at compile time. Adding a
+ *  surface here requires classifying it in EVERY policy set (see AGENTS.md,
+ *  "Harness invariants"). */
+export const SURFACE_IDS = ["cli", "telegram", "discord", "slack", "webui"] as const;
+
+export type SurfaceId = (typeof SURFACE_IDS)[number];
 
 export interface AgentToolCall {
   id: string;
@@ -79,7 +87,10 @@ export type RunLlmTurn = (input: RunLlmTurnInput) => AsyncIterable<TurnEvent>;
 export function stringifyToolContent(value: unknown): string {
   if (value === undefined) return "";
   if (typeof value === "string") return value;
-  return JSON.stringify(value, null, 2);
+  // Compact on purpose: this string is LLM input, and 2-space pretty-printing
+  // inflated every structured tool result by roughly a fifth in tokens for
+  // zero model benefit.
+  return JSON.stringify(value);
 }
 
 export function parseToolArguments(raw: unknown): unknown {

package/src/agent/sidebar-model.ts

@@ -23,6 +23,9 @@ export interface SidebarRoom {
   headSeq: number | null;
   lastReadSeq: number | null;
   unread: number;
+  /** Unread mention count from the latest read-state snapshot: the server's
+   *  number verbatim, 0 when the snapshot carried none for this room. */
+  mentionUnread: number;
   joined: boolean;
   /** Topics dial from room meta. Absent reads as "allowed" since the
    *  2026-07-12 dial-default flip; explicit "off" keeps topics inert. */
@@ -40,6 +43,13 @@ export interface SidebarSnapshot {
   dms: SidebarDm[];
   popular: SidebarRoom[];
   globalReplyUnread: number;
+  /** Per-room unread mention counts exactly as the server sent them in the
+   *  latest read-state snapshot: sparse (zero-count rooms absent) and
+   *  global (rooms outside the current listings may appear). Empty when the
+   *  snapshot carried none; a fresh snapshot replaces it wholesale. */
+  mentionCounts: Record<string, number>;
+  /** User-wide unread mention total from the same snapshot. */
+  mentionTotal: number;
   fetchedAt: number;
 }
 
@@ -49,6 +59,8 @@ export const EMPTY_SIDEBAR_SNAPSHOT: SidebarSnapshot = {
   dms: [],
   popular: [],
   globalReplyUnread: 0,
+  mentionCounts: {},
+  mentionTotal: 0,
   fetchedAt: 0,
 };
 
@@ -65,10 +77,23 @@ export function computeRoomUnread(input: {
   return Math.max(0, input.headSeq - input.lastReadSeq);
 }
 
+/** A READ_STATE reply that carries the additive mention decorations beside
+ *  the cursor map (RoomReadStatePayload satisfies this shape). Old
+ *  fetchReadState implementations returning the bare cursor Record keep
+ *  working; mention fields then read as zero. */
+export interface SidebarReadState {
+  readState: Record<string, number>;
+  mentionCounts?: Record<string, number> | undefined;
+  mentionTotal?: number | undefined;
+}
+
 export function buildSidebarSnapshot(input: {
   rooms: RoomMeta[];
   spaces: RoomSpace[];
   readState: Record<string, number>;
+  /** Server numbers pass through verbatim; merge policy is the caller's. */
+  mentionCounts?: Record<string, number> | undefined;
+  mentionTotal?: number | undefined;
   dms: SidebarDm[];
   globalReplyUnread: number;
   joinedUnread: (roomName: string) => number | null;
@@ -91,6 +116,14 @@ export function buildSidebarSnapshot(input: {
       headSeq,
       lastReadSeq,
       unread: computeRoomUnread({ joinedUnread, headSeq, lastReadSeq }),
+      // Own-key guard like the readState read above: rooms named after
+      // Object.prototype members must read 0 from a sparse map, not NaN.
+      mentionUnread: Math.max(
+        0,
+        input.mentionCounts && Object.hasOwn(input.mentionCounts, name)
+          ? (input.mentionCounts[name] ?? 0)
+          : 0,
+      ),
       // Joined = an open context OR a server read cursor (you only get a
       // cursor by having been in the room). This is what decides whether a
       // room lives in your channel tree or in the POPULAR discovery shelf.
@@ -154,6 +187,8 @@ export function buildSidebarSnapshot(input: {
     dms: input.dms,
     popular,
     globalReplyUnread: Math.max(0, input.globalReplyUnread),
+    mentionCounts: input.mentionCounts ?? {},
+    mentionTotal: Math.max(0, input.mentionTotal ?? 0),
     fetchedAt: input.now,
   };
 }
@@ -161,13 +196,39 @@ export function buildSidebarSnapshot(input: {
 export interface SidebarModelDeps {
   fetchRooms: () => Promise<RoomMeta[]>;
   fetchSpaces: () => Promise<RoomSpace[]>;
-  fetchReadState: (roomNames: string[]) => Promise<Record<string, number>>;
+  /** Either the bare cursor Record (the 0.2.0 shape) or a SidebarReadState
+   *  whose mention decorations feed the snapshot's mention fields. */
+  fetchReadState: (roomNames: string[]) => Promise<Record<string, number> | SidebarReadState>;
   fetchDms: () => Promise<SidebarDm[]>;
   fetchGlobalReplyUnread: () => Promise<number>;
   joinedUnread: (roomName: string) => number | null;
   now?: () => number;
 }
 
+/** A bare cursor Record maps room name to seq (numbers only), so an object
+ *  under the "readState" key can only be the snapshot shape, even for a
+ *  room literally named "readState" (its cursor would be a number). */
+function normalizeSidebarReadState(reply: Record<string, number> | SidebarReadState): {
+  readState: Record<string, number>;
+  mentionCounts: Record<string, number> | undefined;
+  mentionTotal: number | undefined;
+} {
+  const nested = (reply as SidebarReadState).readState;
+  if (typeof nested === "object" && nested !== null) {
+    const snapshot = reply as SidebarReadState;
+    return {
+      readState: snapshot.readState,
+      mentionCounts: snapshot.mentionCounts,
+      mentionTotal: snapshot.mentionTotal,
+    };
+  }
+  return {
+    readState: reply as Record<string, number>,
+    mentionCounts: undefined,
+    mentionTotal: undefined,
+  };
+}
+
 export class SidebarModel {
   private snapshotValue: SidebarSnapshot = EMPTY_SIDEBAR_SNAPSHOT;
   private inflight: Promise<SidebarSnapshot> | null = null;
@@ -243,13 +304,16 @@ export class SidebarModel {
       this.deps.fetchDms().catch(() => [] as SidebarDm[]),
       this.deps.fetchGlobalReplyUnread().catch(() => 0),
     ]);
-    const readState = await this.deps
+    const readStateReply = await this.deps
       .fetchReadState(rooms.map((room) => room.name))
       .catch(() => ({}) as Record<string, number>);
+    const { readState, mentionCounts, mentionTotal } = normalizeSidebarReadState(readStateReply);
     return buildSidebarSnapshot({
       rooms,
       spaces,
       readState,
+      mentionCounts,
+      mentionTotal,
       dms,
       globalReplyUnread,
       joinedUnread: this.deps.joinedUnread,

package/src/shared/rooms-protocol.ts

@@ -259,7 +259,7 @@ export interface RoomLedgerEntry {
   pinnedAt?: string | number | Date | null | undefined;
   attachments?: RoomAttachment[] | undefined;
   roomRole?: RoomRole | null | undefined;
-  metadata?: (Record<string, unknown> & Partial<RoomForwardMetadata>) | undefined;
+  metadata?: (Record<string, unknown> & Partial<RoomForwardMetadata> & Partial<RoomWebhookMetadata>) | undefined;
 }
 
 export type RoomForwardedFrom =
@@ -278,6 +278,19 @@ export interface RoomForwardMetadata {
   forwardedFrom: RoomForwardedFrom;
 }
 
+/** Sender identity for messages posted through a channel webhook (the
+ *  Discord-compatible ingest). Entries carrying it render the webhook's
+ *  name and avatar with an APP-style badge; the entry's handle mirrors
+ *  the display name and its userId is the synthetic `webhook:<id>`, so a
+ *  webhook can never impersonate a member. */
+export interface RoomWebhookMetadata {
+  webhook: {
+    id: string;
+    name: string;
+    avatarUrl?: string | undefined;
+  };
+}
+
 export interface RoomAttachment {
   /**
    * Object key under room-attachments/; clients sign it at render time.
@@ -370,6 +383,16 @@ export interface RoomReadStatePayload {
    *  Present when the store surfaces it and on ROOM_SET_ATTENTION acks
    *  (which reply READ_STATE scoped to the one room, readState empty). */
   attention?: Record<string, RoomTopicAttention> | undefined;
+  /** Unread mention counts by room, server-computed from the notify
+   *  worker's ROOM_MENTION rows so badges survive reload and clear through
+   *  the ack path. Unlike readState/attention the map is SPARSE AND
+   *  GLOBAL: every room with a nonzero count appears (requested or not),
+   *  zero-count rooms are absent. Missing on servers older than the
+   *  mentions-completion store. */
+  mentionCounts?: Record<string, number> | undefined;
+  /** User-wide unread mention total (drives the app badge). Rides beside
+   *  mentionCounts; missing on older servers. */
+  mentionTotal?: number | undefined;
   requestId?: string | undefined;
 }
 
@@ -583,7 +606,7 @@ export interface RoomDmMessage {
   createdAt?: string | number | undefined;
   /** Sealed DM: content is '' and the opaque envelope rides here. */
   secret?: RoomLedgerSecretPayload | null | undefined;
-  metadata?: (Record<string, unknown> & Partial<RoomForwardMetadata>) | undefined;
+  metadata?: (Record<string, unknown> & Partial<RoomForwardMetadata> & Partial<RoomWebhookMetadata>) | undefined;
   /** Legacy public chat-image URL (renders as-is, no signing). */
   imageUrl?: string | null | undefined;
   /** Private, signed, scanned DM attachments (dm-attachments/ keyspace).

package/src/social-client.ts

@@ -18,6 +18,7 @@ import type {
   RoomFollowResult,
   RoomFriend,
   RoomFriendRequests,
+  RoomNotificationInboxResult,
   RoomPublicProfile,
   RoomRepliesReadResult,
   RoomRepliesResult,
@@ -46,6 +47,10 @@ export type {
   RoomFriend,
   RoomFriendRequest,
   RoomFriendRequests,
+  RoomNotificationInboxItem,
+  RoomNotificationInboxResult,
+  RoomNotificationKind,
+  RoomNotificationMessageData,
   RoomPublicProfile,
   RoomRepliesReadResult,
   RoomRepliesResult,
@@ -744,6 +749,88 @@ export async function deleteSpaceRole(
   );
 }
 
+/** A channel webhook: the Discord-compatible ingest capability. The
+ *  posting URL is `<chat-api>/webhooks/<webhookId>/<token>`; the token is
+ *  the whole credential, so treat listed webhooks like secrets. */
+export interface RoomWebhook {
+  webhookId: string;
+  room: string;
+  name: string;
+  avatarUrl: string | null;
+  token: string;
+  createdBy: string;
+  /** Creator's handle at create time (display; createdBy is the id). */
+  createdByHandle?: string | null;
+  createdAt: string;
+  lastUsedAt: string | null;
+  deliveryCount: number;
+  disabled: boolean;
+}
+
+export async function listRoomWebhooks(
+  config: RoomSocialConfig,
+  room: string,
+): Promise<RoomWebhook[]> {
+  const result = await socialRequest<{ webhooks?: RoomWebhook[] }>(
+    config,
+    `/rooms/${encodeURIComponent(cleanRoomId(room))}/webhooks`,
+    { cache: "no-store" },
+  );
+  return result.webhooks ?? [];
+}
+
+export async function createRoomWebhook(
+  config: RoomSocialConfig,
+  room: string,
+  input: { name: string; avatarUrl?: string | null },
+): Promise<RoomWebhook> {
+  const result = await socialRequest<{ webhook?: RoomWebhook }>(
+    config,
+    `/rooms/${encodeURIComponent(cleanRoomId(room))}/webhooks`,
+    { method: "POST", body: input },
+  );
+  if (!result.webhook) throw new Error("Webhook create returned no webhook");
+  return result.webhook;
+}
+
+/** Store-minted webhook ids are `wh_<hex>`. Anything else is rejected
+ *  BEFORE it reaches a URL: encodeURIComponent does not escape dots, and
+ *  a `..` segment would normalize `/webhooks/..` onto the parent room
+ *  route, turning a webhook delete into a channel archive. */
+function assertWebhookId(webhookId: string): string {
+  if (!/^[A-Za-z0-9_-]{1,64}$/.test(webhookId)) {
+    throw new Error(`Invalid webhook id: ${JSON.stringify(webhookId)}`);
+  }
+  return webhookId;
+}
+
+export async function deleteRoomWebhook(
+  config: RoomSocialConfig,
+  room: string,
+  webhookId: string,
+): Promise<void> {
+  await socialRequest(
+    config,
+    `/rooms/${encodeURIComponent(cleanRoomId(room))}/webhooks/${assertWebhookId(webhookId)}`,
+    { method: "DELETE" },
+  );
+}
+
+/** Rotate the capability: the old URL dies immediately. */
+export async function regenerateRoomWebhookToken(
+  config: RoomSocialConfig,
+  room: string,
+  webhookId: string,
+): Promise<RoomWebhook> {
+  const result = await socialRequest<{ webhook?: RoomWebhook }>(
+    config,
+    `/rooms/${encodeURIComponent(cleanRoomId(room))}/webhooks/${assertWebhookId(webhookId)}/regenerate`,
+    { method: "POST" },
+  );
+  if (!result.webhook) throw new Error("Webhook regenerate returned no webhook");
+  return result.webhook;
+}
+
 export async function setSpaceMemberRoles(
   config: RoomSocialConfig,
   spaceId: string,
@@ -1197,6 +1284,47 @@ export async function markRoomRepliesRead(
   return { markedRead: result.markedRead ?? 0 };
 }
 
+/**
+ * The chat-scoped notification inbox (GET /users/notifications): the durable
+ * rows behind mention/reply/dm/keyword pushes, newest first, room kinds only.
+ * Voucher-reachable like the rest of the chat surface (the bearer token may
+ * be an API key or a chat voucher). Pagination is the composite cursor: pass
+ * the previous page's lastCursor and lastCursorId back TOGETHER (the store
+ * rejects one without the other); unread=true filters to unread rows.
+ */
+export async function listRoomNotifications(
+  config: RoomSocialConfig,
+  options: {
+    limit?: number | undefined;
+    /** Feed a page's lastCursor back here (explicit undefined reads as
+     *  "first page", so `page.lastCursor ?? undefined` composes under
+     *  exactOptionalPropertyTypes). */
+    cursor?: string | undefined;
+    cursorId?: string | undefined;
+    unread?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+  } = {},
+): Promise<RoomNotificationInboxResult> {
+  const params = new URLSearchParams();
+  if (options.limit !== undefined) params.set("limit", String(options.limit));
+  if (options.cursor !== undefined) params.set("cursor", options.cursor);
+  if (options.cursorId !== undefined) params.set("cursorId", options.cursorId);
+  if (options.unread !== undefined) params.set("unread", String(options.unread));
+  const init: { signal?: AbortSignal } = {};
+  if (options.signal) init.signal = options.signal;
+  const result = await socialRequest<Partial<RoomNotificationInboxResult>>(
+    config,
+    `/users/notifications${params.size ? `?${params.toString()}` : ""}`,
+    init,
+  );
+  return {
+    notifications: result.notifications ?? [],
+    hasMore: result.hasMore ?? false,
+    lastCursor: result.lastCursor ?? null,
+    lastCursorId: result.lastCursorId ?? null,
+  };
+}
+
 export async function suggestRooms(
   config: RoomSocialConfig,
   request: RoomSuggestionRequest,
@@ -1224,12 +1352,16 @@ export async function socialRequest<T>(
     signal?: AbortSignal;
     formData?: FormData;
     headers?: Record<string, string>;
+    /** Fetch cache mode; token-bearing reads pass "no-store" so posting
+     *  credentials never persist in a browser HTTP cache. */
+    cache?: RequestCache;
   } = {},
 ): Promise<T> {
   const url = `${trimTrailingSlash(config.apiUrl)}${path}`;
   const hasJsonBody = init.body !== undefined;
   const res = await fetch(url, {
     method: init.method ?? "GET",
+    ...(init.cache ? { cache: init.cache } : {}),
     headers: {
       Authorization: `Bearer ${config.apiKey}`,
       Accept: "application/json",

package/src/social-types.ts

@@ -192,6 +192,48 @@ export interface RoomRepliesReadResult {
   markedRead: number;
 }
 
+/** The room kinds the chat notification inbox returns (the store's
+ *  ROOM_INBOX_NOTIFICATION_TYPES). ROOM_FOLLOW rows stay out of the inbox:
+ *  follow is a push channel, not a badge source. */
+export type RoomNotificationKind = "ROOM_MENTION" | "ROOM_REPLY" | "ROOM_DM" | "ROOM_KEYWORD";
+
+/** Shared room payload on a notification row, wire names verbatim from the
+ *  store's notification schema (room_message_data). `preview` follows the
+ *  push body rules (140 chars, empty for sealed content); `hash` is the
+ *  client deep link. */
+export interface RoomNotificationMessageData {
+  kind: "dm" | "mention" | "reply" | "follow" | "keyword";
+  room_id?: string;
+  room_name?: string;
+  space_id?: string;
+  conversation_id?: string;
+  seq?: number;
+  from_handle: string;
+  preview: string;
+  hash: string;
+}
+
+/** One chat notification inbox row: the store's explicit field pick
+ *  (snake_case wire names, dates as ISO strings, room_message_data only
+ *  when the row carries one). */
+export interface RoomNotificationInboxItem {
+  id: string;
+  type: RoomNotificationKind;
+  created_at: string;
+  read_at: string | null;
+  room_message_data?: RoomNotificationMessageData;
+}
+
+/** A newest-first inbox page plus the composite cursor naming the last row
+ *  returned; feed lastCursor and lastCursorId back together to request the
+ *  next page. Both are null on an empty page. */
+export interface RoomNotificationInboxResult {
+  notifications: RoomNotificationInboxItem[];
+  hasMore: boolean;
+  lastCursor: string | null;
+  lastCursorId: string | null;
+}
+
 /** A living markdown doc scoped to a space (head state; content on demand). */
 export interface RoomDoc {
   docId: string;