@openmarket/rooms-client 0.5.1 → 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/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.
@@ -501,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

@@ -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;
@@ -395,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 } });
 }
@@ -636,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmarket/rooms-client",
-  "version": "0.5.1",
+  "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/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.
@@ -593,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

@@ -749,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,
@@ -1270,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",