dsh-ringcentral
RingCentral Team Messaging IM channel plugin for
deepseek-harness (dsh).
It turns a RingCentral Bot Add-in into a first-class frontend for a dsh agent:
inbound posts from RingCentral chats drive the agent loop, and assistant
replies flow back as threaded RingCentral posts.
English | 中文说明
Architecture
RingCentral user ──▶ WebSocket (PostAdded) ──▶ im-ringcentral ──▶ ctx.agents ──▶ dsh agent loop ──▶ LLM
│ │
└── admission / session / event ◀────┘
(assistant reply ──▶ RingCentral post, threaded)
The plugin is a pure Cordis plugin following the dsh "Plugins, not loop changes"
principle. It speaks the RingCentral Team Messaging v1 REST API + WebSocket
subscription stream directly (no external SDK) and reuses the host dsh services
for agents, sessions, models, compaction, and tool presentation.
Install
1. Via dsh plugin manager
# install into a profile
npx @deepseek-ai/dsh plugin --profile ringcentral add dsh-ringcentral
# start
export RC_BOT_TOKEN="your-bot-jwt"
export DEEPSEEK_API_KEY="your-deepseek-key"
npx @deepseek-ai/dsh --profile ringcentral
Or run the bundled installer: sh install.sh.
2. Local path
cd /path/to/dsh-ringcentral
pnpm install && pnpm build
npx @deepseek-ai/dsh plugin --profile ringcentral add /path/to/dsh-ringcentral
export RC_BOT_TOKEN="your-bot-jwt"
npx @deepseek-ai/dsh --profile ringcentral
3. --patch development mode
The --patch overlay loads the plugin from a local absolute path without
installing it into a profile. Generate the machine-local patch first, then
boot:
cd /path/to/dsh-ringcentral
pnpm install && pnpm build # dist entry (npx dsh cannot resolve .js -> .ts)
node scripts/gen-dev-patch.mjs # writes cordis.local.yml with the real path
export RC_BOT_TOKEN="your-bot-jwt"
npx @deepseek-ai/dsh web --patch ./cordis.local.yml
Use pnpm dev (tsc --watch) while iterating: the loader hot-reloads the
plugin whenever dist/ changes. Pointing the patch at src/index.ts only
works inside a deepseek-harness source tree (pnpm dsh), not with the
npx-installed package.
RingCentral bot setup
- Sign in at https://developers.ringcentral.com/.
- Create an app with the Bot platform type.
- Grant at least:
TeamMessaging, ReadAccounts, WebSocketsSubscription.
- Install or publish the bot to your RingCentral account.
- Copy the bot JWT and use it as
RC_BOT_TOKEN.
Optional owner credentials (JWT REST API app for your own account, with
TeamMessaging + WebSocketsSubscription + ReadMessages) give
ringcentral_get_recent_messages owner read fallback and outbound owner
fallback. The history tool always reads through the bot client
(RC_BOT_TOKEN) first; without owner credentials it uses only the bot
client (chats the bot is a member of).
Configuration
Config follows dsh practice: the cordis config tree is the single source
(profile cordis.patch.yml / cordis.yml), with Schema defaults applied
automatically. Secrets (RC_BOT_TOKEN, RC_USER_CLIENT_ID,
RC_USER_CLIENT_SECRET, RC_USER_JWT_TOKEN) resolve through the host
credentials domain — an explicit config value wins, then environment →
managed $DSH_HOME/.credentials.yaml → project/user .env, with the plain
process environment as the final fallback. RC_SERVER_URL works the other
way for operational overrides (e.g. sandbox): the environment value wins over
the configured/default server. Secrets are never persisted into profile YAML.
To drive any other setting from an environment variable, use the cordis
loader's !!js tag (double bang — a single !js is not evaluated), e.g.
access.groupMode: !!js process.env.RC_GROUP_MODE ?? 'open'.
The access-control block mirrors @tencent-connect/dsh-qqbot exactly
(QQ's c2c surface is dm here). RingCentral's three non-DM chat types
(Team / Everyone / Group) are all governed by the group surface.
| Config | Type | Default | Description |
|---|
botToken | string | required | Bot static JWT (env: RC_BOT_TOKEN) |
ownerCredentials.clientId / clientSecret / jwt | string | - | Owner JWT (env: RC_USER_*) |
server | string | https://platform.ringcentral.com | API server (env: RC_SERVER_URL) |
access.dmMode | enum | open | DM handling: disabled, allowlist, open |
access.dmAllow | string[] | [] | Person ids allowed in DMs; empty or ["*"] = allow all |
access.groupMode | enum | open | Group handling: disabled, allowlist, open |
access.groupAllow | string[] | [] | Chat ids allowed in groups; empty or ["*"] = allow all |
requireMention | boolean | true | Require @-mention in group chats |
groupPrompt | string | - | Extra system prompt for group chats |
directPrompt | string | - | Extra system prompt for DMs |
processingPlaceholder.enabled | boolean | false | Post 👀 → ⏳ while the agent works (texts/delay are fixed) |
historyMessageLimit | number | 250 | Default record count for the history tool |
homeChannel | string | - | Fallback target for the history tool |
|
Every row except the secret entries is editable from the Web GUI card
described below.
Web GUI configuration
Installed into a web profile (dsh plugin --profile web add dsh-ringcentral),
the plugin registers a settings namespace and a configuration card under
Settings → Plugins → Plugin configuration. The card:
- edits every non-secret entry of the table above; saves apply to the next
inbound IM message (no restart), and a per-field Reset returns a value
to the composed profile layer;
- renders the four secrets (
RC_BOT_TOKEN, RC_USER_*) as write-only
controls: it reports only whether each is configured and writes through the
settings domain (fallback to the host credentials domain where reachable);
secret values are never sent back to the page. Credential changes apply
live: within ~1s the plugin rebuilds its REST clients and reconnects the
websocket with the new token — no restart, and the per-peer session context
survives rotation (the account key derives from the stable bot identity).
Without a settings service (a bare custom cordis.yml), the card simply does
not mount and the plugin behaves exactly as before.
Commands
| Command | Description |
|---|
/new (/reset, /clear) | Start a new session (clear context) |
/compact | Compress session history (summary replaces old records) |
/model | Show or switch the model |
/stop | Abort the current generation |
/rc-ping | Connectivity test |
/rc-version | Plugin version |
/rc-status | Current session status |
/rc-help | List all commands |
Session routing
sessionKey: ringcentral:<accountScopeKey>:<scope>:<peerId> where scope is
direct (peer = person id), group (peer = Group DM chat id), or
channel (peer = Team/Everyone chat id), and accountScopeKey is a
SHA-256 fingerprint of server + bot token. The SessionId is derived
deterministically (SHA-256), so the same user/chat always routes to the same
session and survives restarts. Resolution order: in-process reuse → persisted
resume → fresh create.
Agent questions (ask_user)
When the agent calls ask_user_question, the plugin renders the question
into the chat (thread-anchored) and waits for the user to reply in the same
session:
- Reply with an option number or label to select a choice (
multi_select
accepts "1, 3"), or type a free-text answer.
- Multi-question asks are answered one question at a time.
- Answers resolve the pending question and are not appended to session
history (same semantics as the web GUI).
- Waiting times out after 10 minutes (the ask is cancelled with a notice).
Note: the provider registers on the userQuestions service seam. In a web
profile the GUI provider takes precedence — questions then appear in the web
UI, not in RingCentral. Use a dedicated profile for IM-only operation.
Design principles
- Pure Cordis plugin — follows dsh "Plugins, not loop changes".
- Declarative deps —
inject = ['agents']; tools/compaction/presets are optional seams.
- Session isolation — one agent per RingCentral peer.
- Mini-Markdown outbound — replies are converted to RingCentral Mini-Markdown and chunked.
- Threading — replies always anchor on the triggering post (threadId preferred), with owner fallback and unthreaded retry.
- Idle eviction — inactive agents are disposed automatically.
- Defensive degradation — missing tools/presets/owner credentials never crash the plugin.
Not in v1 (planned follow-ups)
- Adaptive Card / note / calendar / task artifact tools
- Cron and out-of-process notification sender
- Multi-account support
- Native streaming (RingCentral has no stream API; the processing placeholder is the typing affordance)
Local development
pnpm install
pnpm build # or: pnpm dev (watch)
pnpm test
pnpm typecheck
# run against the npx-installed dsh
export RC_BOT_TOKEN="xxx"
node scripts/gen-dev-patch.mjs
npx @deepseek-ai/dsh web --patch ./cordis.local.yml
scripts/gen-dev-patch.mjs emits the gitignored cordis.local.yml directly,
with the entry resolved to an absolute path on the machine (default
dist/index.js; pass src/index.ts to point at the TypeScript entry).
Test coverage map
pnpm test runs 143 cases across 17 files. No network is touched — clients,
websockets, and harness services are stubbed.
| File | Covers |
|---|
tests/accounts.test.ts | Secret resolution precedence, schema-default fallbacks, legacy __FROM_ENV__ compat, numeric clamping |
tests/account-scope-key.test.ts | Stable-identity account key: rotation keeps session keys; token-fingerprint fallback |
tests/credentials.test.ts | resolveSecret chain (service → env → managed file), inject handle, file parser, file watcher |
tests/settings-merge.test.ts | Live config merge into runtime/account copies, secret-field exemption, server/placeholder branches |
tests/settings-redact.test.ts | role('secret') wire redaction and its sidecar |
tests/settings-section.test.ts | Cross-version settings mounting: installSection (harness ≥ 0.1.2) vs legacy installSettingsSection fallback (≤ 0.1.1-rc.2), failure containment |
tests/monitor.test.ts | WS frame extraction, post filtering (own echoes, answer markers), websocket URL building |
tests/rotation-scheduler.test.ts | Debounce coalescing, single-flight, dispose (extracted module, fake timers) |
tests/gateway-rotation.test.ts | Fake-harness integration: rotate() rebuilds clients, re-registers the history tool, reconnects the websocket; no-op on same token; fail-safe on missing token |
tests/session-manager.test.ts | Deterministic session ids, per-scope isolation, setAccountKey re-derivation |
tests/inbound.test.ts | Admission (dm/group allowlists), mention gating, prompt injection, command routing |
tests/outbound.test.ts | Reply chunking, showToolResults gating, placeholder lifecycle |
tests/history-tool.test.ts | Reader precedence (bot → owner), record clamping, target resolution |
tests/threading.test.ts | Thread-participation tracking and follow-up classification |
tests/targets.test.ts | Reply-target resolution and thread anchoring |
Troubleshooting
| Symptom | Likely cause | Fix |
|---|
| Plugin not starting | RC_BOT_TOKEN missing | Set RC_BOT_TOKEN (env or $DSH_HOME/.credentials.yaml) or botToken in config |
Debug log shows [cred] … service=absent | In desktop-style deployments, bundle-row plugins cannot read host services via ctx.get (isolate scoping) | Not an error: 0.3.15+ ships a file fallback and 0.3.17 an inject-based path — see docs/credentials-service-unreachable.md |
| Bot never replies in a group chat | access.groupMode: disabled, not allowlisted, or no mention | Check access.groupMode / access.groupAllow and @-mention the bot |
| DM ignored | access.dmMode: disabled or sender not in access.dmAllow | Check access.dmMode / access.dmAllow |
| History tool returns nothing | Chat not visible to bot or owner | Reads try the bot first, then the owner; pass a bare chat id or channel:<chatId> and make sure one client is a member |
| Agent question not answered from RingCentral | Web GUI provider registered (web profile) | Questions go to the web UI; use a dedicated profile or answer in the web UI |
| Plugin config card missing from the Web GUI, or save/reset fails, after a harness upgrade | Harness ≥ 0.1.2 moved settings registration to settings.installSection() and removed connection.api; ≤ 0.4.1 used the removed APIs | Upgrade to dsh-ringcentral ≥ 0.4.2 (dual-path: installSection on ≥ 0.1.2, legacy fallback on ≤ 0.1.1-rc.2) |
Harness compatibility
dsh-ringcentral ≥ 0.4.2 supports both harness lines: ≥ 0.1.2-alpha (settings via settings.installSection, writes via settingsScope.mutate) and 0.1.1-rc.2 and earlier (legacy installSettingsSection + connection.api.settings.mutate fallback).dsh-ringcentral ≤ 0.4.1 requires the ≤ 0.1.1-rc.2 settings API; it does not start on harness ≥ 0.1.2.
License
MIT
