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

1. Sign in at https://developers.ringcentral.com/.
2. Create an app with the Bot platform type.
3. Grant at least: TeamMessaging, ReadAccounts, WebSocketsSubscription.
4. Install or publish the bot to your RingCentral account.
5. 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.

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

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.

Troubleshooting

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