dsh-channel-gateway

A channel gateway plugin for DeepSeek Harness. A channel adapter normalizes provider traffic into one message contract, the gateway authorizes it and announces a single channel/inbound event, and a consumer answers through ctx.channels.send with the route the inbound message carried.

The package covers the transport half of a chat integration: it fixes the message contract and the seam between a provider and a consumer. What a message means, whether it was seen before, and where it goes next are decided above it.

An event alone cannot promise that a consumer stored anything, so a consumer that needs durable intake registers an inbound sink and the adapters then advance their provider cursor only after that sink accepted the message. Without a sink the event is best-effort notification.

Contract

Five surfaces, and they are the public API — keep them small, stable and versionable. Field-by-field reference in docs/architecture.md.

Surface	Shape
Inbound	InboundMessage { channel, providerMessageId, actor, place, visibility, text, attachments?, timestamp, replyTo?, raw? }
Outbound	OutboundMessage { channel, route, text, attachments?, replyTo?, format? }
A transport	Channel { name, capabilities, start(inbox), stop(), send(message), resolveAttachment? }
The gateway	ctx.channels.register(channel) · ctx.channels.send(message) · ctx.channels.resolveAttachment(channel, attachment) · ctx.channels.registerInboundSink(sink) · event channel/inbound
Authorization	ChannelAuth { authorize(request) }, defaulting to an allowlist
Durable intake	ChannelInboundSink { accept(message): Promise<void> }, at most one per gateway

Three parts of the contract exist because a consumer needs them and a provider does not supply them in a usable form:

• actor / place / visibility — who spoke, where, and in front of whom.
• providerMessageId — the provider's stable id, so a consumer can deduplicate and accept durably.
• place.route — an opaque, channel-minted destination. A consumer stores the route it saw and hands it back as OutboundMessage.route; no layer above the adapter composes a provider address.

Install

The package is a DSH bundle: adding it inserts the gateway service row.

dsh plugin add @contexera/dsh-channel-gateway --profile <profile>

Channel adapters are opt-in rows, because each needs its own credentials. A profile adds the ones it wants:

- insert:
    - id: channel-telegram
      name: '@contexera/dsh-channel-gateway/telegram'
      config: { token: '<bot token>' }
    - id: channel-weixin
      name: '@contexera/dsh-channel-gateway/weixin'
      config: { token: '<iLink bot token>' }

Who may speak is the gateway row's own configuration, not the adapter's:

- id: channel-gateway
  config:
    allow:
      - telegram:123456789   # one actor of one channel
      - weixin:*             # every actor of one channel
      # - '*'                # everyone

An empty allow list admits nobody.

Consuming it

A listener is enough when losing a message to a restart is acceptable: the event is a notification, and the gateway does not wait for the handler.

import type { Context } from '@deepseek-ai/cordis'
import type {} from '@contexera/dsh-channel-gateway'

export const name = 'my-ingress'
export const inject = ['channels']

export function apply(ctx: Context) {
  ctx.on('channel/inbound', (message) => {
    // Best-effort: this promise is not awaited by the gateway.
    void handle(message)
  })
}

async function handle(message: InboundMessage) {
  // ... later, answer it:
  await ctx.channels.send({ channel: message.channel, route: message.place.route, text: 'ok' })
}

A sink is what makes intake durable: the gateway awaits it, and an adapter will not advance its provider cursor past a message the sink refused. It must be idempotent, because a page that partially failed is handed over again.

export function apply(ctx: Context) {
  ctx.channels.registerInboundSink({
    async accept(message) {
      // Deduplicate on (message.channel, message.providerMessageId) yourself:
      // the gateway keeps no dedupe state.
      await store.appendOnce(message)
    },
  })

  ctx.on('channel/inbound', (message) => {
    // Announced only after accept() resolved, so it is durable by now.
    void route(message)
  })
}

Adapters

Adapter	Transport	Entry	Notes
Telegram	Bot API long poll (getUpdates)	@contexera/dsh-channel-gateway/telegram	Text and media. An attachment sends from local bytes (data), else a provider ref or url; resolveAttachment reads an inbound attachment's bytes by download. format: 'markdown' renders as Telegram HTML. DSH_TELEGRAM_TOKEN is the fallback for config.token.
Weixin	WeChat iLink long poll (ilink/bot/getupdates)	@contexera/dsh-channel-gateway/weixin	Text and media. A reply quotes the inbound context_token, which WeChat expires after roughly two minutes; the adapter refreshes a stale one before sending. format: 'markdown' renders as sanitized WeChat Markdown. Inbound attachment refs are authenticated, and a download must be https: on a host in attachmentHosts (default: the configured CDN host plus the iLink CDN), capped at maxAttachmentBytes. The media download/upload path follows the reference iLink protocol and is not yet verified against a live account. Starts from a token it is given — the QR login flow is not implemented yet.

Both adapters honour HTTPS_PROXY/NO_PROXY (Node's own fetch does not, unless NODE_USE_ENV_PROXY is set). They always send through this package's own undici fetch, proxied or not, and build multipart uploads with the FormData exported alongside it — a multipart body from a different undici build than the fetch is not recognized as multipart and is sent as the string [object FormData], which the provider rejects as an empty upload.

Compatibility

A DSH release can reach this package only through the two published packages it imports: @deepseek-ai/cordis (the plugin and service API) and @deepseek-ai/schemastery (row config). No @deepseek-ai/dsh-* package is imported — the package's check:boundaries script fails the build if one appears — so the host coupling is exactly those two versions.

Runtime	cordis	schemastery	Verified by
DSH 0.1.5-rc.3 (npm latest)	4.0.2	3.18.2	the 0.1.0 release: npm run typecheck, npm test, npm run build
DSH 0.1.7-rc.1 · 0.1.7-rc.2 (npm next)	4.0.4	3.18.4	the same three checks, plus a real row mount in a booted profile
Declared peer floor	4.0.1	3.18.1	the same three checks

The devDependencies pin the second row, so a checkout typechecks, tests and builds against what the current DSH ships. The declared peers stay at ^4.0.1 / ^3.18.1: the floor admits the older DSH line, the ceiling admits the current one, and the two ranges overlap, so one published version installs against either without a second copy of cordis in the profile.

Re-verify against a running DSH:

pnpm --filter @contexera/dsh-channel-gateway build
cat > /tmp/channel-gateway.yml <<'EOF'
- insert:
    - id: channel-gateway
      name: 'file:///absolute/path/to/dsh-channel-gateway/lib/index.js'
EOF
dsh --profile <profile> --patch /tmp/channel-gateway.yml --help

A row that fails to import is reported on stderr as N entry did not activate with its reason; a clean run prints no such line. To assert the service seam rather than the import alone, add a second row to the overlay that declares inject: ['channels'] and reads ctx.channels.send from it.

Development

pnpm install    # once, at the repository root
pnpm --filter @contexera/dsh-channel-gateway typecheck  # tsc, strict
pnpm --filter @contexera/dsh-channel-gateway test       # boundary guard + vitest
pnpm --filter @contexera/dsh-channel-gateway build      # emits lib/

src/ may import only its own relative modules, Node builtins, and @deepseek-ai/cordis / @deepseek-ai/schemastery; adapters may add undici. pnpm --filter @contexera/dsh-channel-gateway check:boundaries enforces exactly that, so the neutral seam cannot quietly acquire a host dependency.

License

MIT. The Telegram transport is adapted from dsh-telegram-channel (MIT); the WeChat protocol shape follows openclaw-weixin (MIT) and nanobot (MIT).