@vibesdotdev/chat 0.0.0-stage → 1.0.0-rc.1

package/dist/docs/chat.messages.docs.descriptor.js

@@ -0,0 +1,209 @@
+const markdown = `---
+id: chat.messages
+title: Chat Messages
+summary: Message structure, threading, history, and real-time updates
+tags: [chat, messages, threading, history, realtime]
+parent: chat
+order: 2
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Chat Messages
+
+Messages are the fundamental unit of chat communication. A room exposes a
+\`messages\` collection for reading/writing the persisted message log, while
+\`room.send()\` / \`room.run()\` drive an agent turn (which appends user and
+assistant messages for you). Messages are typed as \`UnifiedChatMessage\` and
+work identically on consumer (browser/CLI) and cloud surfaces.
+
+## Message structure
+
+The persisted message shape is \`UnifiedChatMessage\` (Zod-validated). Roles are
+\`system | user | assistant\`; \`senderType\` distinguishes \`user | agent | system\`.
+
+:::usage{language="ts"}
+import type { UnifiedChatMessage } from '@vibesdotdev/chat';
+
+const message: UnifiedChatMessage = {
+  id: 'msg_123',
+  roomId: 'room_abc',
+  senderType: 'agent',
+  agentId: 'assistant',
+  role: 'assistant',
+  content: 'Hello, world!',
+  status: 'completed', // sending | sent | streaming | completed | failed | ...
+  createdAt: new Date().toISOString(),
+  // optional
+  userId: undefined,
+  replyToId: undefined,
+  streaming: false,
+  attachments: [],
+  metadata: {
+    // toolCalls, reasoningSteps, usage, durationMs, agentName, ...
+  }
+};
+:::
+
+## Driving a turn
+
+To send user input and get an agent response, call \`room.send()\` (awaits the
+final result) or \`room.run()\` (streams events). Both take a \`ChatRunInput\`.
+
+:::usage{language="ts"}
+import { getVibesChatClient } from '@vibesdotdev/chat/client';
+
+const chat = await getVibesChatClient(runtime);
+const room = await chat.rooms.get(roomId);
+if (!room) throw new Error('room not found');
+
+// Await the completed result (user + assistant messages are persisted)
+const result = await room.send({
+  content: 'Hello, world!',
+  agentId: 'assistant',  // optional
+  toolIds: ['workspace-fs'],  // optional tool allow-list for this turn
+  maxTokens: 2048,       // optional
+});
+
+console.log(result.assistantMessageId, result.content, result.usage);
+:::
+
+## Streaming a turn
+
+\`room.run()\` is an async generator yielding \`ChatRunEvent\`s and returning the
+final \`ChatRunResult\`. Event \`type\`s are dot-namespaced.
+
+:::usage{language="ts"}
+const stream = room.run({ content: 'Summarize the repo' });
+
+for await (const event of stream) {
+  switch (event.type) {
+    case 'chunk':
+      appendChunk(event.messageId, event.content);
+      break;
+    case 'tool.started':
+      console.log('tool', event.toolName, event.args);
+      break;
+    case 'tool.completed':
+      console.log('done', event.toolName, event.output);
+      break;
+    case 'done':
+      console.log('result', event.result);
+      break;
+  }
+}
+:::
+
+You can also attach a passive listener instead of consuming the generator:
+
+:::usage{language="ts"}
+const unsubscribe = room.onEvent((event) => {
+  if (event.type === 'message.created') addMessage(event.messageId);
+  if (event.type === 'message.updated') updateMessage(event.messageId);
+});
+
+await room.cancel(); // abort the in-flight turn
+// later: unsubscribe()
+:::
+
+## Reading messages
+
+\`room.messages.list()\` returns \`UnifiedChatMessage[]\`. Pagination uses a
+\`cursor\` plus a \`direction\` (\`before\` | \`after\`), not separate before/after args.
+
+:::usage{language="ts"}
+// Most recent page
+const recent = await room.messages.list({ limit: 50 });
+
+// Older messages before a known message id
+const older = await room.messages.list({
+  limit: 50,
+  cursor: recent[0]?.id,
+  direction: 'before'
+});
+
+// Single message
+const message = await room.messages.get(messageId);
+:::
+
+## Writing messages directly
+
+The \`messages\` collection can create/update/remove persisted messages without
+running an agent — useful for system notices or migrations. \`create()\` takes a
+\`CreateMessageInput\` (\`role\` is required).
+
+:::usage{language="ts"}
+const created = await room.messages.create({
+  role: 'system',
+  content: 'User joined the room',
+  senderType: 'system'
+});
+
+// Patch an existing message; returns the updated message or null
+const updated = await room.messages.update(created.id, {
+  content: 'User joined the room (edited)'
+});
+
+// Remove a single message, or clear the whole log
+await room.messages.remove(created.id);
+await room.messages.clear();
+:::
+
+## Real-time updates
+
+Subscribe to the live message list. The callback receives the full
+\`UnifiedChatMessage[]\` snapshot on each change.
+
+:::usage{language="ts"}
+const unsubscribe = room.messages.subscribe((messages) => {
+  render(messages);
+});
+
+// later: unsubscribe()
+:::
+
+## Attachments
+
+Attachments are carried on the message and on \`ChatRunInput\`. Pass
+\`attachmentIds\` (references) or inline \`attachments\` when sending a turn.
+
+:::usage{language="ts"}
+await room.send({
+  content: 'Check this file',
+  attachmentIds: ['att_123']
+});
+:::
+
+## Related descriptors
+
+:::descriptor{kind="docs/topic" id="chat.sessions"}
+:::
+
+:::descriptor{kind="docs/topic" id="chat.threads"}
+:::
+
+:::descriptor{kind="docs/topic" id="chat.history"}
+:::
+
+:::descriptor{kind="docs/topic" id="ai.streaming"}
+:::
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'chat.messages',
+    title: 'Chat Messages',
+    summary: 'Message structure, threading, history, and real-time updates',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: markdown
+    },
+    parent: 'chat',
+    order: 2,
+    tags: ['chat', 'messages', 'threading', 'history', 'realtime'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=chat.messages.docs.descriptor.js.map

package/dist/docs/chat.messages.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.messages.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/chat.messages.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6LhB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,eAAe;IACnB,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,8DAA8D;IACvE,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,QAAQ;KAChB;IACD,MAAM,EAAE,MAAM;IACd,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC;IAC9D,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/chat.moderation.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=chat.moderation.docs.descriptor.d.ts.map

package/dist/docs/chat.moderation.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.moderation.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/chat.moderation.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAuEvE,QAAA,MAAM,UAAU,EAAE,mBAiBjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/chat.moderation.docs.descriptor.js

@@ -0,0 +1,87 @@
+const markdown = `---
+title: Chat Moderation
+summary: The chat.message moderation subject, the chat.moderation battery, the default thresholds and how a host overrides them
+tags: [chat, moderation, labels, thresholds]
+parent: chat
+order: 7
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Chat Moderation
+
+Chat registers the content type and the battery that [\`@vibesdotdev/moderation\`](moderation) judges. Nothing in chat calls it yet: the publish path and chat-web wiring land separately, so no chat message is moderated live today.
+
+## What chat registers
+
+- \`moderation/subject\` \`chat.message\` — batteryId \`chat.moderation\`, all eight moderation labels.
+- \`ai/evaluation-schema\` \`chat.moderation\` — one \`noul\` head per label, named exactly as the label, with \`requiredState: ['message']\`.
+
+Both are in \`chatPlugin\` only. The browser plugin variants do not register them, because moderation runs server-side.
+
+## The heads
+
+| Head | The message… |
+|---|---|
+| \`harassment\` | insults, threatens, bullies or demeans a specific person |
+| \`hate\` | attacks or dehumanizes people for a protected characteristic |
+| \`sexual\` | contains sexually explicit content |
+| \`sexual_minors\` | sexualizes a minor or seeks such content |
+| \`violence\` | threatens, incites or glorifies violence against people |
+| \`self_harm\` | encourages, instructs or expresses intent of self-harm or suicide |
+| \`spam\` | is unsolicited bulk, repetitive or off-topic promotion |
+| \`scam\` | uses fraud, phishing or impersonation to obtain money, credentials or personal data |
+
+## Default thresholds
+
+| Labels | reviewAt | hideAt |
+|---|---|---|
+| default | 0.5 | 0.85 |
+| \`sexual_minors\` | 0.2 | 0.5 |
+| \`self_harm\` | 0.35 | 0.95 |
+
+\`\`\`ts
+import { moderateSubject } from '@vibesdotdev/moderation';
+
+const decision = await moderateSubject(runtime, {
+	subject: { type: 'chat.message', id: message.id, containerId: room.id },
+	state: { message: message.content }
+});
+\`\`\`
+
+An answer from a JSON-mode model (\`source: 'adapted'\`) can reach review but never hide.
+
+## Overriding the thresholds
+
+\`chat.message\` is single-owner: a host cannot re-register it. A host with its own policy registers its own subject id against the same battery and passes that id as \`subject.type\`:
+
+\`\`\`ts
+createModerationSubjectDescriptor({
+	id: 'cinderlink.chat-message',
+	name: 'Cinderlink chat message',
+	description: 'Chat messages under Cinderlink community policy',
+	batteryId: 'chat.moderation',
+	labels: ['harassment', 'hate', 'sexual', 'sexual_minors', 'violence', 'self_harm', 'spam', 'scam'],
+	thresholds: { default: { reviewAt: 0.3, hideAt: 0.6 } }
+});
+\`\`\`
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'chat.moderation',
+    title: 'Chat Moderation',
+    summary: 'The chat.message moderation subject, the chat.moderation battery, the default thresholds and how a host overrides them',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: markdown
+    },
+    parent: 'chat',
+    order: 7,
+    tags: ['chat', 'moderation', 'labels', 'thresholds'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=chat.moderation.docs.descriptor.js.map

package/dist/docs/chat.moderation.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.moderation.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/chat.moderation.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmEhB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,iBAAiB;IACrB,KAAK,EAAE,iBAAiB;IACxB,OAAO,EACN,wHAAwH;IACzH,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,QAAQ;KAChB;IACD,MAAM,EAAE,MAAM;IACd,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,CAAC;IACpD,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/chat.sessions.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=chat.sessions.docs.descriptor.d.ts.map

package/dist/docs/chat.sessions.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.sessions.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/chat.sessions.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AA+JvE,QAAA,MAAM,UAAU,EAAE,mBAgBjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/chat.sessions.docs.descriptor.js

@@ -0,0 +1,175 @@
+const markdown = `---
+title: Chat Sessions
+summary: Chat sessions, persistence, lifecycle management, and room state
+tags: [chat, sessions, rooms, persistence, lifecycle]
+parent: chat
+order: 1
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Chat Sessions
+
+Chat sessions (rooms) are the primary unit of conversation. Sessions persist state, manage participants, and track message history.
+
+## Session structure
+
+:::usage{language="ts"}
+interface UnifiedChatRoom {
+  id: string;
+  name: string;
+  type: 'direct' | 'group' | 'agent' | 'public' | 'private';
+  visibility: 'public' | 'private' | 'project';
+  participants: ChatParticipant[];
+  items: ChatItem[];  // messages, tool calls, generations
+  metadata: {
+    createdAt: string;
+    updatedAt: string;
+    lastActivityAt: string;
+  };
+}
+:::
+
+## Creating sessions
+
+:::usage{language="ts"}
+import { getVibesChatClient } from '@vibesdotdev/chat';
+
+const chat = await getVibesChatClient(runtime);
+const room = await chat.rooms.create({
+  title: 'Project Discussion',
+  visibility: 'private',
+  participants: [
+    { id: 'agent-1', type: 'agent', name: 'Assistant' }
+  ]
+});
+:::
+
+## Session lifecycle
+
+Sessions have a lifecycle managed by the storage backend:
+
+| Lifecycle Stage | Description | Actions |
+|----------------|-------------|---------|
+| \`created\` | Initial creation | Set metadata, add owner |
+| \`active\` | Ongoing conversation | Send messages, add participants |
+| \`inactive\` | No recent activity | Auto-archive after timeout |
+| \`archived\` | Read-only history | Export, delete |
+
+## Session persistence
+
+Sessions persist via storage adapters:
+
+:::usage{language="ts"}
+// \`runtime\` is the VibesRuntime you were handed: \`context.runtime\` in a tool, command or job, or the plugin's \`RuntimeRef\`.
+const storage = await runtime.query('storage/manifest')
+  .withId('chat.rooms')
+  .resolve();
+
+// Storage adapter selected by scope:
+// - consumer: json/localdb
+// - cloud: cloud-api/postgres
+await storage.upsertRoom(room);
+:::
+
+## Active session
+
+Track the currently active session:
+
+:::usage{language="ts"}
+const activeRoomId = await storage.getActiveRoomId();
+await storage.setActiveRoomId(room.id);
+
+// Switch rooms
+const newRoom = await chat.rooms.create({ title: 'New Chat' });
+await storage.setActiveRoomId(newRoom.id);
+:::
+
+## Session metadata
+
+Sessions track comprehensive metadata:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`createdAt\` | ISO date | Session creation time |
+| \`updatedAt\` | ISO date | Last modification |
+| \`lastActivityAt\` | ISO date | Last message/action |
+| \`messageCount\` | number | Total messages |
+| \`participantCount\` | number | Active participants |
+| \`agentMode\` | boolean | AI agent enabled |
+
+## Session modes
+
+Sessions support different modes:
+
+| Mode | Description | Use Case |
+|------|-------------|-----------|
+| \`direct\` | 1:1 conversation | Private chat |
+| \`group\` | Multi-user | Team collaboration |
+| \`agent\` | AI-assisted | Coding assistant |
+| \`public\` | Open access | Community channels |
+
+## Session queries
+
+Query sessions by criteria:
+
+:::usage{language="ts"}
+const rooms = await chat.rooms.list();
+
+// Filter by type
+const agentRooms = rooms.filter(r => r.type === 'agent');
+
+// Filter by activity
+const activeRooms = rooms.filter(r => {
+  const last = new Date(r.metadata.lastActivityAt);
+  return Date.now() - last.getTime() < 24 * 60 * 60 * 1000;
+});
+
+// Sort by recency
+rooms.sort((a, b) => 
+  new Date(b.metadata.lastActivityAt).getTime() - 
+  new Date(a.metadata.lastActivityAt).getTime()
+);
+:::
+
+## Session deletion
+
+Remove sessions and associated data:
+
+:::usage{language="ts"}
+await room.remove();  // Deletes room + messages
+
+// Or via storage
+await storage.deleteRoom(roomId);
+:::
+
+## Related descriptors
+
+:::descriptor{kind="docs/topic" id="chat.messages"}
+:::
+
+:::descriptor{kind="docs/topic" id="chat.threads"}
+:::
+
+:::descriptor{kind="docs/topic" id="chat.history"}
+:::
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'chat.sessions',
+    title: 'Chat Sessions',
+    summary: 'Chat sessions, persistence, lifecycle management, and room state',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: markdown
+    },
+    parent: 'chat',
+    order: 1,
+    tags: ['chat', 'sessions', 'rooms', 'persistance', 'lifecycle'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=chat.sessions.docs.descriptor.js.map

package/dist/docs/chat.sessions.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.sessions.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/chat.sessions.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2JhB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,eAAe;IACnB,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,kEAAkE;IAC3E,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,QAAQ;KAChB;IACD,MAAM,EAAE,MAAM;IACd,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,WAAW,CAAC;IAC/D,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/chat.threads.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=chat.threads.docs.descriptor.d.ts.map

package/dist/docs/chat.threads.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.threads.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/chat.threads.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AA2GvE,QAAA,MAAM,UAAU,EAAE,mBAgBjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/chat.threads.docs.descriptor.js

@@ -0,0 +1,123 @@
+const markdown = `---
+title: Chat Threads
+summary: Branching conversations via room forking and reply linkage
+tags: [chat, threads, branching, fork, replies]
+parent: chat
+order: 3
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+id: chat.threads
+---
+
+# Chat Threads
+
+The chat client models branching conversations at the **room** level, not as
+a nested message tree. There are two real primitives:
+
+- **Fork** — \`chat.rooms.fork(sourceRoomId, upToMessageId?)\` copies a room's
+  history (optionally up to a chosen message) into a brand-new room, so you can
+  explore an alternative direction without touching the original.
+- **Reply linkage** — a message can carry a \`replyToId\` pointing at the
+  message it answers, which surfaces are free to render as a reply.
+
+There is no message-level thread API (no \`getThread\`, \`branch\`, \`merge\`,
+or \`deleteThread\` methods). Branching means forking a room.
+
+## Forking a conversation
+
+\`fork\` creates a new room seeded with copied messages. Pass
+\`upToMessageId\` to branch from a specific point; omit it to copy the whole
+history. The returned value is a live \`ChatRoom\` handle you can run against.
+
+:::usage{language="ts"}
+import { getVibesChatClient } from '@vibesdotdev/chat';
+
+const chat = await getVibesChatClient(runtime);
+
+// Branch from a decision point — the new room contains every message
+// up to and including \`decisionPointId\`, with fresh message ids.
+const branch = await chat.rooms.fork(sourceRoomId, decisionPointId);
+
+// The fork is a full room — run the agent down the alternative path.
+const result = await branch.send({ content: 'Try the alternative approach' });
+:::
+
+To copy an entire conversation (e.g. to keep an immutable snapshot before
+continuing), call \`fork\` without a message id:
+
+:::usage{language="ts"}
+const snapshot = await chat.rooms.fork(sourceRoomId);
+:::
+
+## Reply linkage
+
+Messages reference the message they reply to through \`replyToId\` on
+\`CreateMessageInput\`. This is a flat back-reference, not a recursive tree.
+
+:::usage{language="ts"}
+import { getVibesChatClient } from '@vibesdotdev/chat';
+
+const chat = await getVibesChatClient(runtime);
+const room = await chat.rooms.get(roomId);
+if (!room) throw new Error('Room not found');
+
+const target = (await room.messages.list({ limit: 1 })).at(-1);
+
+const reply = await room.messages.create({
+  role: 'user',
+  content: 'Replying specifically to your last point...',
+  replyToId: target?.id
+});
+:::
+
+To reconstruct a reply chain, read messages with \`room.messages.list()\` and
+follow \`replyToId\` yourself — the client does not walk the chain for you.
+
+## Room messages API
+
+\`room.messages\` is a \`ChatRoomMessages\` collection. The full surface:
+
+| Method | Description |
+|--------|-------------|
+| \`list(opts?)\` | List messages; supports \`limit\`, \`cursor\`, \`direction\` (\`'before'\`/\`'after'\`) |
+| \`get(id)\` | Fetch one message or \`null\` |
+| \`create(input)\` | Append a message (\`role\`, \`content\`, optional \`replyToId\`) |
+| \`update(id, patch)\` | Patch a message |
+| \`remove(id)\` | Delete a single message |
+| \`clear()\` | Remove all messages in the room |
+| \`subscribe(cb)\` | React to message changes |
+
+Deleting a message removes only that message — there is no cascade. To drop an
+entire branch, remove its forked room with \`chat.rooms.remove(roomId)\` or the
+handle's \`room.remove()\`.
+
+## Related descriptors
+
+:::descriptor{kind="docs/topic" id="chat.sessions"}
+:::
+
+:::descriptor{kind="docs/topic" id="chat.messages"}
+:::
+
+:::descriptor{kind="docs/topic" id="chat.history"}
+:::
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'chat.threads',
+    title: 'Chat Threads',
+    summary: 'Branching conversations via room forking and reply linkage',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: markdown
+    },
+    parent: 'chat',
+    order: 3,
+    tags: ['chat', 'threads', 'branching', 'fork', 'replies'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=chat.threads.docs.descriptor.js.map

package/dist/docs/chat.threads.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.threads.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/chat.threads.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuGhB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,cAAc;IAClB,KAAK,EAAE,cAAc;IACrB,OAAO,EAAE,4DAA4D;IACrE,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,QAAQ;KAChB;IACD,MAAM,EAAE,MAAM;IACd,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC;IACzD,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/error-notice.d.ts

@@ -0,0 +1,17 @@
+import { CapabilityError, type CaughtFailure } from '@vibesdotdev/kernel';
+/**
+ * The user-facing text for a caught chat failure.
+ *
+ * Typed failures already carry the message to show: a `CapabilityError`'s
+ * message is value-free by contract and its `recoveryHint` says what to do,
+ * and a wire failure's message is what the RPC describer kept. Showing the
+ * `valueFreeFailure` reason id (or the class name) instead is how real
+ * refusals became "Could not send". Anything untyped may quote request
+ * values in its text, so it earns only the caller's fixed fallback.
+ */
+export declare function chatFailureMessage(cause: CaughtFailure, fallback: string): string;
+/** Keep HTTP response bodies out of the conversation's primary error notice. */
+export declare function chatErrorNotice(message: string): string;
+/** Preserve typed refusals; untyped causes remain private behind fixed Chat text. */
+export declare function chatCapabilityFailure(cause: CaughtFailure, reason: string, message: string): CapabilityError;
+//# sourceMappingURL=error-notice.d.ts.map

package/dist/error-notice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-notice.d.ts","sourceRoot":"","sources":["../src/error-notice.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAA0C,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAelH;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWjF;AAED,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAavD;AAED,qFAAqF;AACrF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,CAG5G"}