@dsbot-channel/core 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zerodegress
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/skill.md

@@ -0,0 +1,203 @@
+# dsbot-channel configuration
+
+Configure the gateway: adapter links, delivery, policy, pipeline and one optional judge provider. The transports come from `@dsbot-channel/p2p`, `@dsbot-channel/onebot`, `@dsbot-channel/webhook` and `@dsbot-channel/mail`, each mounted as its own plugin. Every key is read at load; a key the plugin does not read fails the mount.
+
+## Gateway
+
+The gateway's own config holds the global defaults (`reply`, `turn`, `delivery`, `policy`) and the infrastructure (`pipeline.global`, `identity`, `impressions`, `skill`), listed under Behaviour blocks below. An adapter's `channel`, `botName`, `transport` and any behaviour block it overrides are written on that adapter's plugin entry; the compatibility shell `dsbot-channel` also reads the older `adapters` list, where an entry carries `kind` as well.
+
+`channel` is the adapter's only name. `secret`, `accessToken` and judge `credential` are reference names in the host credentials service, not secrets. Paths are read as POSIX paths; Windows is not supported.
+
+An adapter anchors its turns to exactly one of `botName` and `session`; both or neither fails the mount. `botName` follows that bot's current segment from the host roster at `$DSH_HOME/bot/state.json` (`~/.dsh/bot/state.json` when `DSH_HOME` is unset), read on every turn. The name is matched exactly first, by name and then by id, and ignoring case only when nothing matches exactly; two entries matching at the same step fail with `session_ambiguous`. The configured `botName` is the name peers address: an inbound `p2p` request carries it in `to` and must match it exactly, and an outbound turn sends it in `sender` as written. A missing roster keeps the last good session without a warning and fails the turn with `session_unresolved`, warning once, when there is none; an unreadable roster warns once and keeps the last good session, failing the turn when there is none. `session` pins one existing session, checked at mount and on every turn: `session_stale` when its bot has left it, `session_unknown` when no roster names it. One bot takes one anchor: pinning the session of a bot another adapter follows refuses the mount, and the turn fails with `session_anchor_conflict` when the roster was unreadable at mount. `cwd` and `agentPreset` are refused: sessions are never created. An adapter's internal identity is its `botName`, or its `channel` when it pins a `session`; a pinned adapter fixes its wire name at mount, the session owner's `name` when the roster is readable and its `channel` otherwise, and every turn checks `to` against that name and sends it in `sender`, unchanged when the bot moves to another segment. One adapter runs one turn at a time and selects `model` once per resolved session.
+
+<!-- dsbot-channel: adapter skill sections -->
+### Behaviour blocks
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `policy.requireMention` | `false` | group messages must name the bot or everyone; a transport that cannot tell mentions (`p2p`, `mail`) refuses it at mount |
+| `policy.groupBots` | `whenMentioned` | `whenMentioned`, `silent` or `answer`; a `webhook` adapter starts at `answer` and answers its `transport.bots` logins unless the profile sets the key |
+| `policy.relayLimit` | `3` | rounds one peer may hold in a row |
+| `policy.relayResetMs` | `300000` | idle time that resets the count |
+| `policy.budget.capacity` | off | points per window |
+| `policy.budget.hardLimit` | `1` | ratio that refuses |
+| `policy.budget.restrictAt` | off | ratio where a `budget` node may restrict; above 0 and below `hardLimit` |
+| `policy.deny.words` / `regexes` | `[]` | refuse a message whose text matches |
+| `policy.allow.peers` | `[]` | matches `source.peer`: a peer instance on p2p, or the group or user id of a OneBot event |
+| `reply.default` | `auto` | `auto` or `tool` |
+| `reply.byScope` | off | mode per scope: `c2c`, `group`, `p2p` |
+| `reply.rules` | off | ordered rules; first match wins |
+| `turn.coalesceMs` | `0` | merge window |
+| `turn.maxBatch` | `10` | messages per batch |
+| `turn.maxChars` | `8000` | batch budget |
+| `turn.context.messages` | `0` | earlier messages put before the turn |
+| `turn.context.chars` | `2000` | context budget |
+| `delivery.split.byBlankLine` | `true` | split a reply at blank lines |
+| `delivery.split.maxParts` | `4` | parts per reply, tail merged |
+| `delivery.split.maxChars` | `0` | code points per part, off |
+| `delivery.pacing.charsPerSecond` | `14` | reading speed for the wait |
+| `delivery.pacing.minMs` | `700` | shortest wait between parts |
+| `delivery.pacing.maxMs` | `5000` | longest wait between parts |
+| `pipeline.maxTurnMs` | `120000` | one turn's budget |
+| `pipeline.judgeTimeoutMs` | `8000` | one judge call, retries included |
+| `pipeline.judgePoints` | `1` | points a verdict costs |
+| `allowAtLeast` (judge node) | off | score that allows the message |
+| `belowThreshold` (judge node) | `deny` | what a score below `allowAtLeast` does: `deny` or `pass`; fails the mount without `allowAtLeast` |
+| `impressions.dir` | off | absolute notes root; the library is off without it |
+| `impressions.import` | off | once: `{ path, as: { personId } }` or `{ path, as: { groupKey } }` |
+| `turn.impressions.chars` | `400` | notes injected into a turn, `0` to `2000`; `0` injects none |
+| `identity.people` / `identity.bots` | `[]` | nodes `{ id, accounts: [{ kind, instance, accountId }] }`; an account fills `author.personId` |
+
+The impression library is off until a top-level `impressions` block names an absolute `dir`. It keeps short notes about the person a turn answers or about its group; `impression_put`, `impression_get` and `impression_forget` read and write them, `turn.impressions.chars` caps how much goes in front of a turn. `impressions.import` runs once per bot at mount from a file in the host memory format; `path` is absolute, `as.personId` must be a declared person, `as.groupKey` is `<channel>|<sessionKey>`; the channel may mount later, the import applies once it does, and a channel still missing at the assembly before the first inbound request records a warning that names it and runs no turn, it reads bullet lines only, and a second run adds nothing. Notes are injected for `c2c` and `group` turns only; on `p2p` the three tools answer `unsupported`. `impression_put` writes about the counterpart, which needs a `personId`, or with `about: "group"` about its group; `impression_get` takes `about: "group"` too; `impression_forget` takes `all: true` or `about: "group"`. `identity` declares `people` and `bots` nodes of `{ id, accounts: [{ kind, instance, accountId }] }`; ids and accounts appear once, `accounts` may not be empty, a built-in instance may mount later: its check runs in the assembly before the first inbound request, and an instance still missing then runs no turn and records a `ConfigError` warning that names it; the binding takes effect once the instance mounts, a configured p2p peer counts, a third-party kind is only warned about, and a resolved account fills `author.personId`.
+
+## Judge provider
+
+Mount one of two entries. Both provide `dsbot-channel/judge`, so a profile mounts one; a second mount fails at load with `one judge service per instance`. Mount the provider before the gateway: the gateway reads the service while it mounts.
+
+A provider holds the connection; what to ask is written on the judge node, in the fields listed under `Pipeline nodes`.
+
+A judge enters as one node of the pipeline, not as a gate: without `allowAtLeast` it only adds its score, and a chain that ends without an allow still refuses; with it, a score at or above the threshold allows the message, and one below refuses it, or with `belowThreshold: pass` adds its score and passes the chain on, recorded as `judge_below_threshold_pass`. A judge call costs its `judgePoints` whether it decides or only scores, and `belowThreshold` does not change that.
+
+`system-one` asks the question its node names and reads a probability.
+
+```yaml
+- id: dsbot-channel/system-one
+  name: dsbot-channel/system-one
+  config:
+    credential: JUDGE_KEY
+    baseUrl: https://api.typesafe.ai/v1/systemone
+    model: jev-latest
+```
+
+`llm` asks an OpenAI-compatible chat completion for bare JSON `{"score","reason"}`.
+
+```yaml
+- id: dsbot-channel/llm
+  name: dsbot-channel/llm
+  config:
+    credential: JUDGE_KEY
+    baseUrl: https://openrouter.ai/api/v1
+    model: vendor/model
+```
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `credential` | required | reference name |
+| `baseUrl` | required | absolute http(s) URL; `llm` posts to `{baseUrl}/chat/completions` |
+| `model` | required | model id |
+| `maxChars` | `2000` (`system-one`), `6000` (`llm`) | body is truncated to this; one node's `context` is capped at it too |
+
+A key other than these four fails the mount and is named in the error. A judge service from another package that reports no `needsQuestion` or `maxChars` counts as `false` and `2000`: its nodes take a `context` of 2000 code points at most and no `question`.
+
+The provider sets no timer of its own; `pipeline.judgeTimeoutMs` bounds the call. A `429` or `529` is retried once. Only the channel (`<kind>:<instance>`), the peer, the scope, the author id and kind, whether the bot was named, the message body and the node's `context` are sent — no history, no tools. `llm` accepts bare JSON only; a fenced block fails the verdict.
+
+## Score provider
+
+A `score` node needs a host service named `dsbot-channel/score`, which answers `score(event, context)` with a number, synchronously or as a promise. Mount it before the gateway: the gateway reads the service while it mounts.
+
+```ts
+import type { PipelineEvent, NodeContext } from 'dsbot-channel'
+
+export function apply(ctx) {
+  ctx.provide('dsbot-channel/score')
+  ctx.set('dsbot-channel/score', {
+    score(event: PipelineEvent, context: NodeContext): number {
+      return context.score + 1
+    },
+  })
+}
+```
+
+The value is added to the running score; it may be negative and it decides nothing by itself. Later nodes see the running score in `context.score`, and a judge provider that reads it can fold it into its own verdict. The two built-in providers do not read it, so a score never enters their prompt. `allowAtLeast` compares the judge's own score, not the running total.
+
+## How a message is decided
+
+An inbound message is deduplicated by the adapter, then the policy keys in the table above decide whether it may become a turn, then the pipeline decides whether the turn is allowed. A refusal is recorded as `outcome: rejected` with the gate's code, with the detail in the log. `policy.deny` and `policy.allow` need a `deny` or `allow` node: a profile that declares no `pipeline` gets it added, one that declares a pipeline must add it. A judge is a node of the pipeline; its threshold, scoring and points are under `Judge provider`.
+
+## Pipeline nodes
+
+A node is `{ id, type }` plus the fields its type reads. The chain runs in order; the first `deny` or `allow` ends it, and a chain that reaches the end refuses. `id` names the node in `matched` and `reasons`.
+
+| Node | Effect |
+| --- | --- |
+| `deny` | refuses when `policy.deny` matches; no `policy.deny` rule fails the mount |
+| `allow` | allows when `policy.allow` matches and stops later `score` and `judge`; no `policy.allow` peer fails the mount |
+| `judge` | scores through the host judge service; `allowAtLeast` sets its threshold, `belowThreshold` decides what a lower score does, and it reads `question` and `context` |
+| `score` | adds the value the host score service returns; a throw or a non-finite value refuses with `score_failed` |
+| `budget` | reads the spend of the busiest window: a hard state refuses, and `mayRestrict` at `restrictAt` restricts |
+| `prepare` | runs the host prepare hook, then passes; every adapter for the bot needs the hook |
+| `chance` | fires with `probability`: a hit ends the chain as an `allow` or a `deny`, a miss passes |
+| `when` | decides by a Matcher: a match returns its `outcome`, no match passes |
+
+A `judge` node names what it asks and what it adds.
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `question` | required | what this node asks; `system-one` needs one, an `llm` node may not carry it |
+| `question.type` | required | `noul`, `score` or `choice` |
+| `question.instructions` | required | one question or statement |
+| `question.criteria` | required | `noul`: `{ true, false }`; `score`: 2 to 10 ordered levels, low to high |
+| `question.options` | required | for `choice`: at least two options |
+| `question.target` | required | for `choice`: one of `question.options`; its probability becomes the score |
+| `question.min` / `question.max` | off | `score` only: convert a raw score; equal values fail the verdict |
+| `context` | off | static material for this node: a string or a mapping of name to string |
+| `probability` | required | `chance` only: 0 to 1 |
+| `outcome` | required | `when`: `allow`, `deny` or `pass`; `chance`: `allow` or `deny` |
+| `test` | required | `when` only: the Matcher it reads |
+| `when` | off | `chance` only: the Matcher it rolls behind |
+| `restrictSkip` | off | `budget` only: what a restrict skips; required with `mayRestrict`. `scoring` skips `score` and `judge`; `judge` skips only `judge` |
+| `mayRestrict` | off | `budget` only: turn a ratio at `policy.budget.restrictAt` into a restrict |
+
+A `when` node decides by a Matcher: a match returns its `outcome`, no match passes. The same Matcher guards a `chance` node; a guard that does not hold passes without rolling, without a `counters.chance` entry and without a `chance_miss` reason.
+
+| Matcher key | Values | Meaning |
+| --- | --- | --- |
+| `scope` | `c2c`, `group`, `p2p` | the conversation kind |
+| `peer` | a string, or `{ in: [...] }` / `{ notIn: [...] }` | the peer the event names; when the event names no peer, `in` does not match and `notIn` does |
+| `mentioned` | `true` / `false` | this bot or everyone was named |
+| `replyToMe` | `true` / `false` | the message quotes something this bot sent on the same channel |
+| `ownRecent` | `true` / `false` | this bot has spoken here, the conversation has been quiet for less than ten minutes, and fewer than ten messages have arrived since |
+| `event` | a string or a list of strings | the transport class, the same name `events.turn` takes, e.g. `action.ci`; absent when the adapter names no class, and a rule naming `event` then never matches |
+| `action` | a string or a list of strings | the transport sub-action, e.g. `completed`; an event that names none never matches |
+
+At least one key is required and every key present must hold. A successful send by the bot resets `ownRecent` and a failed send does not; it expires after ten minutes without a message in the conversation, and a message in the conversation refreshes it. `replyToMe` is reported by the adapter, false when the transport carries no parent message id; both are false for non-message events. `event` and `action` compare the transport class and sub-action; a list matches any of its entries, and an event that carries no sub-action never matches `action`. An event whose adapter names no class carries no `event`, so a rule naming `event` does not match it. A matcher with no key, an unknown key, both `in` and `notIn`, an empty list, a non-string class or a non-boolean flag fails the mount. A match records `when_allow` or `when_deny` under `reasons`; `pass` and a miss record nothing.
+
+```yaml
+config:
+  pipeline:
+    global:
+      - { id: named, type: when, test: { mentioned: true }, outcome: allow }
+      - { id: roll, type: chance, when: { ownRecent: false }, probability: 0.99, outcome: deny }
+```
+
+A key other than these in `question` fails the mount and names the node and the field. One `context` may total `maxChars` code points, mapping names included; an empty name or value, another type or an over-long one fails the mount. `context` carries what the profile knows, not what happened: the channel, the peer, the scope, the author id and kind, whether the bot was named and the message body are sent already, and history, sessions and tools are never read. `llm` renders it after the message facts; `system-one` sends it as `state.context`.
+
+`question`, `context`, `probability`, `outcome`, `test`, `when`, `restrictSkip` and `mayRestrict` may be written in `pipeline.global` and in an adapter's `insert` and `override`. A session layer's `insert` takes only `id`, `type`, `after` and `before`, so it carries none of them; a session's `override` may set them.
+
+A `chance` node takes its bucket from a fixed hash of the event key and the node id: the same message replayed takes the same outcome, and two chance nodes on one message draw independently. It records `chance_allow`, `chance_deny` or `chance_miss` with `p=` under `reasons`, and the adapter that carried the message counts it under `counters.chance[nodeId]` as `{ hit, miss }`; the key appears only after the node has run.
+
+A `score` node adds what `dsbot-channel/score` returns. A profile that declares one without that service fails the mount; a call that throws or returns anything but a finite number refuses the turn with `score_failed` and leaves the running score untouched. The running score is in the result; it decides nothing on its own, and `allowAtLeast`, `question` and `context` stay on `judge`.
+
+A `budget` node reads the spend of the busiest window: the ratio is the largest of the global, bot and session usage divided by `policy.budget.capacity`. `hardLimit` refuses; with `mayRestrict`, a ratio at or above `policy.budget.restrictAt` returns a restrict, which skips what `restrictSkip` names and lets the chain continue. A restrict is not an allow: a chain that ends after one still refuses, with `pipeline-restrict` in the gate. `restrictSkip` without `mayRestrict`, `mayRestrict` without `restrictAt` or without a non-empty `restrictSkip`, declares a field that would do nothing and fails the mount.
+
+An adapter changes the chain it starts from with `inherit`, `remove`, `insert` and `override`: `inherit` names the layer (an adapter takes `global`), `remove` drops nodes by id, `insert` adds a node after or before a named node (one of the two, no reused id), `override` replaces fields by id and only those the type reads; an unknown id fails the mount.
+
+```yaml
+config:
+  policy:
+    deny: { words: [spam] }
+  pipeline:
+    global:
+      - { id: guard, type: deny }
+      - { id: shadow, type: deny }
+  adapters:
+    - kind: p2p
+      channel: p2p:peer-a
+      botName: self-bot
+      transport: { listen: { host: 127.0.0.1, port: 7123 }, peers: { peer-b: PEER_B_REFERENCE } }
+      pipeline:
+        remove: [shadow]
+        insert: [{ id: extra, type: deny, after: guard }]
+```
+
+`override` replaces fields by id; a judge node uses it for `allowAtLeast`, `belowThreshold`, `question` and `context`, and needs one provider mounted. A chain with no `allow` node and no judge threshold refuses every message.

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# The base the five plugins share: one registry, then the gateway. Adapters register themselves.
+- insert:
+    - id: dsbot-channel-registry
+      name: '@dsbot-channel/core/registry.js'
+    - id: dsbot-channel
+      name: '@dsbot-channel/core'

package/dist/adapter-meta.d.ts

@@ -0,0 +1,6 @@
+/** Longest serialized adapter payload an event carries, so one transport cannot bloat every event. */
+export declare const ADAPTER_META_MAX_BYTES: number;
+/** How deep an adapter payload may nest. */
+export declare const ADAPTER_META_MAX_DEPTH = 8;
+/** Copies the payload core only carries: json-safe, bounded, and detached from the caller. */
+export declare function adapterMetaOf(input: Record<string, unknown> | undefined): Record<string, unknown>;

package/dist/adapter-meta.js

@@ -0,0 +1,47 @@
+/** Longest serialized adapter payload an event carries, so one transport cannot bloat every event. */
+export const ADAPTER_META_MAX_BYTES = 8 * 1024;
+/** How deep an adapter payload may nest. */
+export const ADAPTER_META_MAX_DEPTH = 8;
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function refuse(where, reason) {
+    throw new Error(`meta.adapter${where}: ${reason}`);
+}
+function checkValue(value, where, depth) {
+    if (depth > ADAPTER_META_MAX_DEPTH)
+        refuse(where, `nests deeper than ${ADAPTER_META_MAX_DEPTH}`);
+    if (value === null)
+        return;
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return;
+        case 'number':
+            if (!Number.isFinite(value))
+                refuse(where, 'numbers must be finite');
+            return;
+        case 'object':
+            break;
+        default:
+            refuse(where, `${typeof value} is not a json value`);
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => checkValue(item, `${where}[${index}]`, depth + 1));
+        return;
+    }
+    for (const [key, item] of Object.entries(value)) {
+        if (FORBIDDEN_KEYS.has(key))
+            refuse(`${where}.${key}`, 'a key that can reach a prototype is refused');
+        checkValue(item, `${where}.${key}`, depth + 1);
+    }
+}
+/** Copies the payload core only carries: json-safe, bounded, and detached from the caller. */
+export function adapterMetaOf(input) {
+    if (input === undefined)
+        return {};
+    checkValue(input, '', 0);
+    const text = JSON.stringify(input);
+    if (Buffer.byteLength(text, 'utf8') > ADAPTER_META_MAX_BYTES) {
+        refuse('', `serializes to more than ${ADAPTER_META_MAX_BYTES} bytes`);
+    }
+    return JSON.parse(text);
+}

package/dist/adapter-plugin.d.ts

@@ -0,0 +1,105 @@
+import type { Context } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import type { AdapterFactory, AdapterMount } from './adapter-registry.js';
+/** The fields an adapter plugin's own `config` carries: everything `AdapterConfig` has except `kind`. */
+export declare const AdapterPluginConfig: Schema<Schemastery.ObjectS<NoInfer<{
+    channel: Schema<string, string, "plain">;
+    botName: Schema<string, string, "plain">;
+    anchor: Schema<string, string, "plain">;
+    session: Schema<string, string, "plain">;
+    model: Schema<string, string, "plain">;
+    reply: Schema<any, any, "plain">;
+    turn: Schema<any, any, "plain">;
+    delivery: Schema<any, any, "plain">;
+    policy: Schema<any, any, "plain">;
+    pipeline: Schema<any, any, "plain">;
+    events: Schema<any, any, "plain">;
+    status: Schema<boolean, boolean, "plain">;
+    transport: Schema<any, any, "plain">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    channel: Schema<string, string, "plain">;
+    botName: Schema<string, string, "plain">;
+    anchor: Schema<string, string, "plain">;
+    session: Schema<string, string, "plain">;
+    model: Schema<string, string, "plain">;
+    reply: Schema<any, any, "plain">;
+    turn: Schema<any, any, "plain">;
+    delivery: Schema<any, any, "plain">;
+    policy: Schema<any, any, "plain">;
+    pipeline: Schema<any, any, "plain">;
+    events: Schema<any, any, "plain">;
+    status: Schema<boolean, boolean, "plain">;
+    transport: Schema<any, any, "plain">;
+}>>, "plain">;
+export interface AdapterPluginSpec {
+    name: string;
+    kind: string;
+    factory: AdapterFactory;
+    check(mount: AdapterMount): unknown;
+}
+export declare function makeAdapterPlugin(spec: AdapterPluginSpec): {
+    Config: Schema<Schemastery.ObjectS<NoInfer<{
+        channel: Schema<string, string, "plain">;
+        botName: Schema<string, string, "plain">;
+        anchor: Schema<string, string, "plain">;
+        session: Schema<string, string, "plain">;
+        model: Schema<string, string, "plain">;
+        reply: Schema<any, any, "plain">;
+        turn: Schema<any, any, "plain">;
+        delivery: Schema<any, any, "plain">;
+        policy: Schema<any, any, "plain">;
+        pipeline: Schema<any, any, "plain">;
+        events: Schema<any, any, "plain">;
+        status: Schema<boolean, boolean, "plain">;
+        transport: Schema<any, any, "plain">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        channel: Schema<string, string, "plain">;
+        botName: Schema<string, string, "plain">;
+        anchor: Schema<string, string, "plain">;
+        session: Schema<string, string, "plain">;
+        model: Schema<string, string, "plain">;
+        reply: Schema<any, any, "plain">;
+        turn: Schema<any, any, "plain">;
+        delivery: Schema<any, any, "plain">;
+        policy: Schema<any, any, "plain">;
+        pipeline: Schema<any, any, "plain">;
+        events: Schema<any, any, "plain">;
+        status: Schema<boolean, boolean, "plain">;
+        transport: Schema<any, any, "plain">;
+    }>>, "plain">;
+    apply: (ctx: Context, config?: Record<string, unknown>) => void;
+    plugin: {
+        name: string;
+        inject: string[];
+        Config: Schema<Schemastery.ObjectS<NoInfer<{
+            channel: Schema<string, string, "plain">;
+            botName: Schema<string, string, "plain">;
+            anchor: Schema<string, string, "plain">;
+            session: Schema<string, string, "plain">;
+            model: Schema<string, string, "plain">;
+            reply: Schema<any, any, "plain">;
+            turn: Schema<any, any, "plain">;
+            delivery: Schema<any, any, "plain">;
+            policy: Schema<any, any, "plain">;
+            pipeline: Schema<any, any, "plain">;
+            events: Schema<any, any, "plain">;
+            status: Schema<boolean, boolean, "plain">;
+            transport: Schema<any, any, "plain">;
+        }>>, Schemastery.ObjectT<NoInfer<{
+            channel: Schema<string, string, "plain">;
+            botName: Schema<string, string, "plain">;
+            anchor: Schema<string, string, "plain">;
+            session: Schema<string, string, "plain">;
+            model: Schema<string, string, "plain">;
+            reply: Schema<any, any, "plain">;
+            turn: Schema<any, any, "plain">;
+            delivery: Schema<any, any, "plain">;
+            policy: Schema<any, any, "plain">;
+            pipeline: Schema<any, any, "plain">;
+            events: Schema<any, any, "plain">;
+            status: Schema<boolean, boolean, "plain">;
+            transport: Schema<any, any, "plain">;
+        }>>, "plain">;
+        apply: (ctx: Context, config?: Record<string, unknown>) => void;
+    };
+};

package/dist/adapter-plugin.js

@@ -0,0 +1,56 @@
+import Schema from '@deepseek-ai/schemastery';
+import { MOUNT_SERVICE, REGISTRY_SERVICE } from './adapter-registry.js';
+import { ConfigError } from './config.js';
+import { createWarn } from './warn.js';
+/** The fields an adapter plugin's own `config` carries: everything `AdapterConfig` has except `kind`. */
+export const AdapterPluginConfig = Schema.object({
+    channel: Schema.string(),
+    botName: Schema.string(),
+    anchor: Schema.string(),
+    session: Schema.string(),
+    model: Schema.string(),
+    reply: Schema.any(),
+    turn: Schema.any(),
+    delivery: Schema.any(),
+    policy: Schema.any(),
+    pipeline: Schema.any(),
+    events: Schema.any(),
+    status: Schema.boolean(),
+    transport: Schema.any(),
+});
+export function makeAdapterPlugin(spec) {
+    const apply = (ctx, config) => {
+        const registry = ctx.get(REGISTRY_SERVICE);
+        if (registry === undefined) {
+            throw new ConfigError(`${spec.name} needs the registry from @dsbot-channel/core; mount its registry plugin first`, []);
+        }
+        if (!registry.has(spec.kind))
+            registry.builtin(spec.kind, spec.factory);
+        const channel = config?.channel;
+        if (typeof channel !== 'string' || channel.length === 0) {
+            createWarn(ctx)(`${spec.name} mounted without a channel: no adapter instance; write it under this plugin's config`);
+            return;
+        }
+        const botName = config?.botName;
+        if (typeof botName !== 'string' || botName.length === 0) {
+            throw new ConfigError(`${spec.name}: config.botName must be a non-empty string`, ['botName']);
+        }
+        const transport = (config?.transport ?? {});
+        spec.check({ kind: spec.kind, channel, botName, transport });
+        const instance = {
+            ...config,
+            kind: spec.kind,
+            channel,
+            botName,
+            transport,
+            source: `${spec.name} plugin`,
+        };
+        const mount = ctx.get(MOUNT_SERVICE);
+        if (mount === undefined)
+            registry.addInstance(instance);
+        else
+            mount.add(instance);
+    };
+    const plugin = { name: spec.name, inject: [REGISTRY_SERVICE], Config: AdapterPluginConfig, apply };
+    return { Config: AdapterPluginConfig, apply, plugin };
+}

package/dist/adapter-registry.d.ts

@@ -0,0 +1,78 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ChannelAdapter } from './contract.js';
+/** What core knows about an adapter before it asks the transport to validate itself. */
+export interface AdapterMount {
+    kind: string;
+    /** The one name this adapter answers to, on the wire and in the profile. */
+    channel: string;
+    botName: string;
+    /** The name peers address this Bot by; a pinned adapter may differ from its identity. */
+    wireBotName?: string | undefined;
+    /** The transport block the profile declared; only the adapter knows its shape. */
+    transport: Record<string, unknown>;
+    /** Whether this adapter answers its own status route; the transport decides what that means. */
+    status?: boolean | undefined;
+}
+export interface AdapterOptions {
+    warn(message: string): void;
+}
+export type AdapterFactory = (mount: AdapterMount, options: AdapterOptions) => ChannelAdapter;
+/** Kinds the package ships and owns; a profile names them directly. */
+export declare const BUILTIN_KINDS: readonly ["p2p", "onebot", "mail", "webhook"];
+/** Longest kind an adapter may declare. */
+export declare const ADAPTER_KIND_MAX = 32;
+/** A third-party transport keeps to its own namespace, so it cannot pose as a built-in. */
+export declare const THIRD_PARTY_KIND: RegExp;
+/** The service one context's registry lives under; a second copy of this package sees another. */
+export declare const REGISTRY_SERVICE = "dsbot-channel.registry";
+/** Refuses a kind a profile declared that cannot identify a transport. */
+export declare function checkAdapterKind(kind: string): void;
+/** The service an adapter plugin hands its own configured instance to; the gateway mounts or queues it. */
+export declare const MOUNT_SERVICE = "dsbot-channel.mount";
+/** One adapter a plugin configured for itself: everything `AdapterConfig` carries except `kind` (the plugin fills it). */
+export interface RegisteredAdapter {
+    kind: string;
+    /** Who declared this instance, so a duplicate can name both sides. */
+    source?: string | undefined;
+    channel: string;
+    botName?: string | undefined;
+    anchor?: 'bot' | 'session' | undefined;
+    session?: string | undefined;
+    model?: string | undefined;
+    reply?: unknown;
+    turn?: unknown;
+    delivery?: unknown;
+    policy?: unknown;
+    pipeline?: unknown;
+    events?: unknown;
+    status?: boolean | undefined;
+    transport?: Record<string, unknown> | undefined;
+}
+/** One context's transports: a third-party plugin and the gateway share this instance, no module state. */
+export declare class AdapterRegistry {
+    #private;
+    /** Queues one configured instance; the gateway drains it at start. */
+    addInstance(instance: RegisteredAdapter): void;
+    /** Hands the gateway every queued instance. */
+    takeInstances(): RegisteredAdapter[];
+    /** Lets a third-party transport offer itself; its kind must stay in the `x-` namespace. One call per kind. */
+    register(kind: string, factory: AdapterFactory): void;
+    /** Registers a kind the package ships; only the gateway calls it, with its own copies. */
+    builtin(kind: string, factory: AdapterFactory): void;
+    has(kind: string): boolean;
+    /** The kinds registered in this context, for a message a user can act on. */
+    known(): string[];
+    /** The factory for a declared kind, or a refusal naming what is available and where the plugin goes. */
+    factory(kind: string): AdapterFactory;
+    private add;
+}
+export interface AdapterPluginOptions {
+    kind: string;
+    create: AdapterFactory;
+}
+/** The only supported way for a third-party package to offer a transport. */
+export declare function defineAdapterPlugin(options: AdapterPluginOptions): {
+    name: string;
+    inject: readonly string[];
+    apply(ctx: Context): void;
+};

package/dist/adapter-registry.js

@@ -0,0 +1,86 @@
+import { ConfigError } from './config.js';
+/** Kinds the package ships and owns; a profile names them directly. */
+export const BUILTIN_KINDS = ['p2p', 'onebot', 'mail', 'webhook'];
+/** Longest kind an adapter may declare. */
+export const ADAPTER_KIND_MAX = 32;
+/** A third-party transport keeps to its own namespace, so it cannot pose as a built-in. */
+export const THIRD_PARTY_KIND = /^x-[a-z0-9-]+$/;
+/** The service one context's registry lives under; a second copy of this package sees another. */
+export const REGISTRY_SERVICE = 'dsbot-channel.registry';
+const ORDER = `mount the adapter plugin between "dsbot-channel/registry" and "dsbot-channel"`;
+/** Refuses a kind a profile declared that cannot identify a transport. */
+export function checkAdapterKind(kind) {
+    if (BUILTIN_KINDS.includes(kind))
+        return;
+    if (kind.length > ADAPTER_KIND_MAX || !THIRD_PARTY_KIND.test(kind)) {
+        throw new ConfigError(`adapter kind "${kind}" must be a built-in name or match x-[a-z0-9-]+ within ${ADAPTER_KIND_MAX} characters`, ['adapters', 'kind']);
+    }
+}
+/** The service an adapter plugin hands its own configured instance to; the gateway mounts or queues it. */
+export const MOUNT_SERVICE = 'dsbot-channel.mount';
+/** One context's transports: a third-party plugin and the gateway share this instance, no module state. */
+export class AdapterRegistry {
+    #factories = new Map();
+    #instances = [];
+    /** Queues one configured instance; the gateway drains it at start. */
+    addInstance(instance) {
+        this.#instances.push(instance);
+    }
+    /** Hands the gateway every queued instance. */
+    takeInstances() {
+        return this.#instances.splice(0);
+    }
+    /** Lets a third-party transport offer itself; its kind must stay in the `x-` namespace. One call per kind. */
+    register(kind, factory) {
+        if (BUILTIN_KINDS.includes(kind)) {
+            throw new ConfigError(`adapter kind "${kind}" is reserved for the built-in transport; a third-party kind starts with "x-"`, ['adapters', 'kind']);
+        }
+        if (kind.length > ADAPTER_KIND_MAX || !THIRD_PARTY_KIND.test(kind)) {
+            throw new ConfigError(`a third-party adapter kind must match x-[a-z0-9-]+ and be at most ${ADAPTER_KIND_MAX} characters: "${kind}"`, ['adapters', 'kind']);
+        }
+        this.add(kind, factory);
+    }
+    /** Registers a kind the package ships; only the gateway calls it, with its own copies. */
+    builtin(kind, factory) {
+        if (!BUILTIN_KINDS.includes(kind)) {
+            throw new ConfigError(`"${kind}" is not a built-in adapter kind`, ['adapters', 'kind']);
+        }
+        this.add(kind, factory);
+    }
+    has(kind) {
+        return this.#factories.has(kind);
+    }
+    /** The kinds registered in this context, for a message a user can act on. */
+    known() {
+        return [...this.#factories.keys()];
+    }
+    /** The factory for a declared kind, or a refusal naming what is available and where the plugin goes. */
+    factory(kind) {
+        const factory = this.#factories.get(kind);
+        if (factory !== undefined)
+            return factory;
+        const known = this.known();
+        throw new ConfigError(`no adapter serves kind "${kind}"${known.length === 0 ? '' : `; known: ${known.join(', ')}`}; ${ORDER}`, ['adapters', 'kind']);
+    }
+    add(kind, factory) {
+        if (this.#factories.has(kind)) {
+            throw new ConfigError(`adapter kind "${kind}" is already registered`, ['adapters', 'kind']);
+        }
+        this.#factories.set(kind, factory);
+    }
+}
+/** The only supported way for a third-party package to offer a transport. */
+export function defineAdapterPlugin(options) {
+    return {
+        name: `dsbot-channel/adapter/${options.kind}`,
+        inject: [REGISTRY_SERVICE],
+        apply(ctx) {
+            const registry = ctx.get(REGISTRY_SERVICE);
+            // Defensive only: `inject` keeps this plugin from running before the registry exists.
+            if (registry === undefined) {
+                throw new ConfigError(`adapter "${options.kind}" found no registry: mount "dsbot-channel/registry" before this plugin`, ['adapters', 'kind']);
+            }
+            registry.register(options.kind, options.create);
+        },
+    };
+}