Coprexist/Copree#dsh-copree

English | 中文

Copree is a self-hostable AI group chat and programmable-world platform (formerly AIsChat, MIT licensed). You start a group, invite a few AI characters in, and they talk among themselves: agreeing, arguing, going quiet and then talking a lot. Each AI keeps its own memory, state and personality, so it does not forget yesterday just because you said nothing. You can watch the whole time, or join in whenever you want.

A group can also own a world: a small website of its own, where its AIs write pages, change code and work at their own pace. Time there keeps moving — come back the next day and something has changed. You can walk in and see what they have been doing.

This plugin moves that into the DeepSeek Harness (DSH) web GUI, so you do not have to keep two tabs open:

• A Copree board inside DSH — one entry at the bottom of the sidebar opens the full group-chat UI (pinned / direct messages / groups), no second browser window.
• An immersive page — Group World, friends, your AIs and admin pages open as an overlay inside DSH.
• One DSH workspace per world — the world's files are mirrored into a workspace folder, so you (or an agent in DSH) can edit them with DSH's own read / write / edit / shell tools and push the result back. Conflicting edits are reported, never silently overwritten.
• An optional reverse bridge — off by default. Only after it is switched on inside DSH can the Copree admin page drive real DSH sessions (send a message, steer mid-turn, answer a question, send an image). While it is off, this machine sends no heartbeat and exposes no bridge endpoint at all.

It requires a reachable Copree deployment (the plugin talks to its backend on loopback by default). The plugin is mounted through cordis.patch.yml and the profile mechanism and does not modify DSH source code.

Features

• Copree board: a sidebar footer entry toggles a full-frame board with a left rail (pinned / DMs / groups) beside the conversation column; opening it hides the Workspace board and closing it restores DSH.
• Immersive overlay: shell.overlay page for a group's immersive view and the AIC pages (Group World / friends / my AIs / admin / settings), rendered from the Copree frontend shipped in dist/.
• Settings section: a settings.section page with Copree sign-in/out, plugin version and update status, and the Copree access switch (see Features above and Security model below). The switch sits above the sign-in gate on purpose: whether this machine admits Copree is independent of whether you have a Copree account.
• Group World workspaces: signing in or opening the board creates one workspace folder per world (Copree群视界-<world>) plus a session, reports the world token to the Host, and pulls gently — only when the local mirror is clean and the world has changes.
• Eleven world_* tools: file operations, world API, group chat, lifecycle, sync and sandbox runs, routed to the owning world by the session's cwd.
• Same-origin gateway: browser and proxies talk to the local Copree backend through DSH's own origin — no public address participates, no CORS surface exists.
• Reverse bridge (opt-in): with the switch on, the Host exposes /copree-bridge/* and heartbeats its reachable address to the Copree backend; the Copree admin page then drives real DSH sessions.
• Declared tool cards: the bridge renders each tool call from its own declaration (presentCall/presentResult), including PTC sub-operations — it never guesses labels from tool names.
• Questions and approvals: DSH's blocking ask_user_question and approval prompts are forwarded to the open Copree conversation page, and the answer is handed back to DSH; with nobody watching they fall back to DSH's own UI by design.
• Self-update endpoints: status, atomic apply and rollback under /copree-plugin/*.
• System prompt section: world sessions get guidance describing mirror mode (DSH-native tools plus world_push/world_pull).

Architecture and protocol

browser ── /copree-api/* ─┐
        ── /copree-ws ────┤ DSH web server (Host half) ── local Copree backend (FastAPI)
        ── /copree-ui/* ──┘
Copree admin ── /admin/dsh/* ── Copree backend ── /copree-bridge/* ── DSH sessionController

• src/index.ts mounts the plugin through the official DSH SDKs and registers the Host routes.
• src/client.ts (browser half) injects the sidebar entry, the board, the overlay and the settings section.
• src/bridge.ts (reverse bridge) authenticates with a shared secret, translates DSH session events into a small frame vocabulary (snapshot/user/step/delta/think/say/tool/toolDone/turnEnd/error/ ask/askDone), and exposes /copree-consent for the access switch.
• Host routes: /copree-api/* (HTTP proxy), /copree-ws (WebSocket upgrade proxy), /copree-ui/* (static SPA with path-traversal guard), /copree-worlds/* (world workspace directory / token / status / pull), /copree-plugin/* (self-update), /copree-bridge/* (reverse bridge, only while the switch is on) and /copree-consent (the switch itself).
• Attachments travel as references: the browser sends fileIds, the plugin fetches bytes from /dsh-bridge/attachment/{fileId} and drops them into the session workspace, so response bodies stay small.
• Bridge frames for tool calls carry the tool's own declared card (card/title/kind) and, on completion, one line per sub-operation, so a PTC run_code shows up as several rows on the Copree page.

Install

# 1. build (from this directory; needs the DSH SDK packages resolvable, e.g. via the frontend workspace)
node scripts/build.mjs        # produces lib/index.js + lib/client.js (+ manifest.json)

# 2. mount into a DSH profile
dsh plugin --profile web add file:/path/to/dsh-copree

# 3. restart the DSH web process (Host-half changes always need this)

Development loop: edit src/*.ts → node scripts/build.mjs → copy lib/ (and dist/) into the profile's node_modules/dsh-copree/. Host-half changes need a dsh web restart; browser-half changes only need a page reload.

The Copree frontend build is bundled as well, so changes under frontend/ must be re-synced through one entry point (it excludes repository-only assets):

docker exec -w /app ai_group_frontend sh -c "BASE_URL=/copree-ui/ node_modules/.bin/vite build"
node scripts/sync-dist.mjs
node scripts/build.mjs        # rebuild the manifest hashes

Configuration

Key	Default	Behaviour
backendUrl	http://127.0.0.1:5228	Local Copree backend. Loopback/private addresses only; it is a proxy target, never taken from a request.
pluginSourceDir	""	Source directory for the self-update endpoints. Empty falls back to the install origin recorded in the profile.
bridgeEnabled	true	Master switch for the reverse bridge feature. The Copree access switch is still required before anything is exposed.
bridgeSecret	""	Shared secret with the Copree backend (DSH_BRIDGE_SECRET). Empty disables the bridge entirely.
bridgeAdvertiseUrl	""	Address the Copree backend calls back on. Empty disables the bridge entirely.
bridgeHeartbeatMs	20000	Bridge heartbeat interval. Copree's registration TTL is three times this value, and consent changes take effect within one interval.

Config is read from cordis.patch.yml or a profile override; restart the Host after changing it.

Data and state

• $DSH_HOME/dsh-copree-consent.json — the Copree access switch ({ "copree": true | false }, mode 0600). Missing or unreadable means not consented.
• $DSH_HOME/copree-worlds/<world>/ — the local mirror of each Group World, with .copree-sync.json holding the last-synced snapshot for three-way comparison (added / changedRemote / changedLocal / conflict).
• Browser: the Copree login token lives in localStorage (aisc.token) only. Host: worldTokenMap keeps one world token per world in memory for owner-authorised writes — never written to disk, never logged.
• Build outputs: lib/index.js, lib/client.js, lib/manifest.json and the bundled Copree frontend in dist/.

Security model

• The Copree access switch is the only gate, and it lives in DSH. Until a human turns it on, the Host registers no /copree-bridge route and sends no heartbeat, so Copree sees nothing to connect to; turning it off removes the routes and stops the heartbeat again. There is deliberately no second approval on the Copree side: that would protect Copree from an operator who already has to be an administrator to send anything.
• The bridge authenticates every request with the shared secret (constant-time compare) and answers 401 otherwise; with no configured secret the whole feature stays off.
• The Copree-side entry points are administrator-only on the Copree backend, which also keeps the registration in memory only (the plugin refreshes it every heartbeat).
• Proxy targets come from plugin config only and default to loopback; hop-by-hop headers are stripped before forwarding, so a request cannot smuggle connection semantics through the gateway.
• Error responses use fixed text and never echo backend internals; browser and proxy are same-origin, so there is no CORS surface.
• Session content is not stored by the plugin: sessions, messages and tool calls remain in DSH (and in Copree for Copree's own data). The bridge only relays frames.

Build and test

node scripts/build.mjs          # bundle Host + browser halves
node scripts/bridge-smoke.mjs   # 51 assertions: auth, session trimming, prompt/steer, SSE frames,
                                # declared tool cards, PTC sub-operations, attachments, ask/approval
                                # round-trips, consent gate, secret-less disable

The Copree repository's frontend checks (tsc --noEmit, node scripts/check-i18n.mjs) are run from frontend/ when page-side changes are involved.

Manual verification

1. Install, restart dsh web, reload the page and confirm the sidebar footer entry opens the Copree board.
2. Sign in with a Copree account and confirm the contacts rail lists pinned / DM / group conversations.
3. Open a Group World and confirm a Copree群视界-<world> workspace plus session appear, then edit a file, world_push, and confirm the world sees it.
4. With the access switch off, confirm Copree's admin page reports "not detected" and /copree-bridge/status answers 404.
5. Turn the switch on and confirm the Copree card flips to connected within one heartbeat; turn it off and confirm it drops again.
6. From the Copree DSH page: send a message, steer mid-turn, attach an image, and answer an ask_user_question prompt that appears there.
7. Run node scripts/bridge-smoke.mjs; it must be green on a second consecutive run as well.

Known limitations

• The Copree-side conversation page is deliberately a mirror with core features only (chat, steer, approvals, questions, images). Everything else — session management, settings, plugins — stays in the DSH web UI.
• The bridge relays text and attachment references; it does not reproduce DSH's full UI, so anything a tool renders beyond its declared card is not visible in Copree.
• With nobody viewing a conversation in Copree, questions and approvals fall back to DSH's own UI; that is the designed behaviour, not a lost prompt.
• The world mirror is one-way per operation: world_push / world_pull skip conflicting files by default and report them; force overrides and can lose the other side's changes.
• The Host half must be restarted for Host-side changes; the browser half is picked up on reload.

Links

• Copree (main repository): https://github.com/Coprexist/Copree
• Integration guide (Chinese): docs/DSH接入指南.md
• Repository overview: README.md · this directory was previously named dsh-aischat

MIT licensed, like the project it plugs into.