docs: add Coven Group Chat product & tech specs#258
Merged
Conversation
Introduce server-side group chat design: adds PRODUCT.md and TECH.md under specs/coven-group-chat. Defines GroupConversation and GroupEvent types, server-owned monotonic seq, fan-out send with SSE multiplexed streams, API endpoints (create, list, get, send, patch, delete), migration/adopt path from iOS sessionIds, client impacts (iOS/web/CLI), and edge-case handling. Establishes architecture and acceptance criteria for v1 to provide durable, cross-device, re-syncable group conversations.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a draft v1 product + technical specification for server-side “Coven Group Chat” under specs/coven-group-chat/, describing a durable group object, a canonical server-assigned event sequence, fan-out to per-familiar child sessions, and a multiplexed SSE stream for clients.
Changes:
- Introduces the product spec: problem statement, goals/non-goals, interface contract, and v1 acceptance criteria.
- Introduces the technical spec: proposed types (
GroupConversation,GroupEvent), sequencing invariant, fan-out sketch, endpoints, migration/adoption flow, and edge handling.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| specs/coven-group-chat/PRODUCT.md | Defines the product goals, contract expectations, and acceptance criteria for server-native group chat. |
| specs/coven-group-chat/TECH.md | Specifies the proposed server model, sequencing rules, API surface, migration path, and failure/edge-case behavior. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+109
to
+116
| | Method | Path | Body / returns | | ||
| | --- | --- | --- | | ||
| | `GET` | `/api/groups` | list account's `GroupConversation`s | | ||
| | `POST` | `/api/groups` | `{ title?, memberFamiliarIds[] }` → provisions a child session per member; returns `GroupConversation` | | ||
| | `GET` | `/api/groups/:id` | `{ group, events: GroupEvent[] }` — full ordered timeline (re-sync + first load) | | ||
| | `POST` | `/api/groups/:id/send` | `{ text }` → **SSE stream** of `GroupEvent` | | ||
| | `PATCH` | `/api/groups/:id` | rename, or add/remove member (add provisions a session; remove archives it) | | ||
| | `DELETE` | `/api/groups/:id` | delete group + child sessions | |
| | `PATCH` | `/api/groups/:id` | rename, or add/remove member (add provisions a session; remove archives it) | | ||
| | `DELETE` | `/api/groups/:id` | delete group + child sessions | | ||
|
|
||
| SSE framing matches the existing chat stream conventions (`/api/chat/send`, `/api/sessions/[id]/events`) so clients reuse their stream parser — they just additionally read `seq` + `familiarId` off each event. |
Comment on lines
+31
to
+35
| The single-session endpoints (`/api/chat/send`, `/api/chat/conversation/:id`) are unchanged. A group's child sessions are ordinary sessions — they remain individually addressable, which is what makes migration and "leave the group, keep the chat" cheap. | ||
|
|
||
| ## Today's reality (what we build on) | ||
|
|
||
| - A session is one conversation with one familiar. `POST /api/chat/send` streams a reply; `GET /api/chat/conversation/:id` returns history; `DELETE` removes it. |
|
|
||
| Group chat exists on exactly one surface — the iOS Cave — and only as a client-side illusion. | ||
|
|
||
| The server has **no multi-familiar concept**. A session is one conversation with one familiar (`/api/chat/send`, `GET/DELETE /api/chat/conversation/:id`). iOS fakes a group by holding a `sessionIds` map (familiarId → sessionId) and fanning a prompt out to N independent sessions concurrently, then streaming each reply into its own attributed bubble (`ChatThread.swift`, lines 36–40). |
BunsDev
added a commit
that referenced
this pull request
Jun 24, 2026
Document v0.0.49 changes across English, Spanish, and Russian release notes: - Co-published @opencoven/coven wrapper alongside @opencoven/cli (PR #257). Both wrappers depend on the same native cli-* platform packages and resolve to the same binary. - Coven Group Chat product + tech spec (PR #258) under specs/coven-group-chat/. Implementation tracked separately. - OpenMeow references scrubbed from docs, api test fixture, and task-manager skill (PR #256). Product-neutral language. No runtime behavior changes for end users in this release.
BunsDev
added a commit
to OpenCoven/coven-cave
that referenced
this pull request
Jun 24, 2026
Another huge release: 120 PRs building on the v0.0.112 push. The iOS app gains a real Calendar tab, Library/Bookmarks, Journal, Live Activities, Siri Shortcuts / App Intents, iPad split-view across Chats/Tasks/Developer, a Board (kanban) view, and an actionable home-screen widget with deep links. The desktop gets a new visual Flow editor (n8n-style with live execution overlay), a Marketplace surface with credential & config collection and remote MCP endpoint validation, a redesigned Code Projects explorer (fluid-glass, keyboard nav, drag-to-reorder), broad undo support (Cmd+Z across journal, vault, automations, chats), and a wide accessibility sweep across combobox/tablist ARIA, WCAG contrast, and reduced-motion behaviour. Group Chat (broadcast one prompt to many familiars) ships as the foundation for the v1 group-chat work tracked in OpenCoven/coven#258. The Calls surface introduced in v0.0.112 was removed in favor of the upcoming server-side group-chat primitive. Co-authored-by: Val Alexander <kitty@openclaw.ai>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the v1 design for server-side group chat under
specs/coven-group-chat/. Companion to the existingcoven-channels,coven-handoff-packet, andcoven-workflow-standardspecs.What this is
Today, group chat exists only on iOS as a client-side illusion:
ChatThread.swiftholds asessionIdsmap (familiarId → sessionId) and fans a single user prompt out to N independent server sessions. The server has no multi-familiar concept, so groups can't re-sync, can't cross devices, and can't render on web/CLI.This spec defines a first-class server group primitive so a group becomes one durable, synced object that every surface reads the same way.
Files
specs/coven-group-chat/PRODUCT.md— problem, goals, non-goals, acceptance target, migration path from iOS's localsessionIds.specs/coven-group-chat/TECH.md—GroupConversation+GroupEventtypes, server-owned monotonic sequence, fan-out + SSE multiplex, API surface (/api/groups,/api/groups/[id],/api/groups/[id]/send), edge cases.Status
Draft v1. Opening as a draft PR so the spec can be reviewed/iterated before merging — implementation is not blocked by merge timing.