@lambdot/protocol-qq 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.1
+
+### Patch Changes
+
+- [#10](https://github.com/Embers-of-the-Fire/lambdot/pull/10) [`19d37e4`](https://github.com/Embers-of-the-Fire/lambdot/commit/19d37e42c7a5514fb62c8f31c65e1aa01916d355) Thanks [@Embers-of-the-Fire](https://github.com/Embers-of-the-Fire)! - Switch inter-package dependency pins from exact versions to `workspace:*` so workspace members always resolve against local sources during development; pnpm rewrites the protocol to exact versions at pack/publish time.
+- Updated dependencies [[`19d37e4`](https://github.com/Embers-of-the-Fire/lambdot/commit/19d37e42c7a5514fb62c8f31c65e1aa01916d355)]:
+  - @lambdot/core@0.1.1
+  - @lambdot/websocket@0.1.1
+
 ## [0.1.0](https://github.com/Embers-of-the-Fire/lambdot/compare/protocol-qq-v0.0.1...protocol-qq-v0.1.0) (2026-08-29)
 
 

package/README.md

@@ -0,0 +1,166 @@
+# @lambdot/protocol-qq
+
+The QQ wire protocol for lambdot: address and stream contracts, frame
+codec, and plugin factories for both QQ bot infrastructures — the websocket
+gateway and the webhook (reversed post) — sharing one REST client. Both
+transports deliver messages only; sending a message is always an HTTPS call
+against the open platform, so the output half is transport-independent.
+
+## Two infras, one platform tag
+
+Both infras emit the same stream contract (`QqMessageStream` —
+`Stream<Message<QqMessage, QqAddress>>`) and share the output
+(`QqCommandStream` — `Stream<Command<QqAddress, string>>`), so a feature
+plugin written against those two types runs unchanged on either infra: the
+wiring `mapping` is the platform adapter. What differs is how messages
+arrive:
+
+- **Gateway** — the bot holds a websocket to QQ. The socket URL is not
+  static configuration: it is discovered through the REST client
+  (`GET /gateway` with the access token), so `qqGatewayTransport` consumes
+  `{ api: QqApi }`, resolves the URL at activation, owns the socket, and
+  emits the `WsConnection` (from `@lambdot/websocket`) as its namespace
+  value. `qqGatewayInput` then runs the basic gateway algorithm on it —
+  identify on hello (op 10), heartbeat on the advertised interval (op 1),
+  decode dispatches (op 0) into the emitted message stream. Resume (op 6)
+  is deliberately not implemented: a dropped connection is a fresh
+  identify.
+- **Webhook** — QQ pushes events to an HTTPS callback address owned by your
+  HTTP surface (a hono route, a worker's fetch). `qqWebhook` implements the
+  callback algorithm and emits it as a `QqWebhook` — `{ handle, messages }`:
+  op 13 callback-address validation (sign `event_ts + plain_token`), and
+  ed25519 verification of `X-Signature-Ed25519` over `timestamp + body` for
+  every other request. Decoded message dispatches join the `messages`
+  stream. The bot secret seeds the ed25519 keypair (repeated to 32 bytes);
+  a forged signature gets a 401.
+
+Both infras read credentials from an env namespace (see `@lambdot/env`) via
+`readQqCredentials` — `QQ_BOT_APP_ID` and `QQ_BOT_APP_SECRET` by default,
+overridable through `QqCredentialKeys` in each plugin's config.
+
+## Assembling a platform
+
+Prefer the bundles: `qqGatewayPlatform` / `qqWebhookPlatform` build a whole
+platform under one name. The pieces stay separate plugins (rather than one
+fused plugin) so features compose between the input (whose message stream
+is `use`d under the platform name) and the terminal output, with the api
+and transport `bind`ed as internal wiring. Wiring a consumer before its
+dependency is a compile error — the `mapping` parameter is typed as the
+namespaces visible so far.
+
+```ts
+import { createKernel, definePlugin, mapStream } from "@lambdot/core";
+import { envVars } from "@lambdot/env";
+import type { QqMessageStream } from "@lambdot/protocol-qq";
+import { qqGatewayPlatform } from "@lambdot/protocol-qq";
+
+const reply = definePlugin({
+    name: "reply",
+    apply(input: { messages: QqMessageStream }) {
+        return mapStream(input.messages, (event) => ({
+            address: event.address,
+            content: `echo: ${event.payload.content}`,
+        }));
+    },
+});
+
+const qq = qqGatewayPlatform("qq");
+
+const kernel = createKernel()
+    .use(envVars("qq-env", ["QQ_BOT_APP_ID", "QQ_BOT_APP_SECRET"]))
+    .bind(qq.api, { option: {}, mapping: (ctx) => ({ env: ctx["qq-env"] }) })
+    .bind(qq.transport, { mapping: (ctx) => ({ api: ctx["qq/api"] }) })
+    .use(qq.input, {
+        option: {},
+        mapping: (ctx) => ({ connection: ctx["qq/transport"], api: ctx["qq/api"] }),
+    })
+    .use(reply, { mapping: (ctx) => ({ messages: ctx.qq }) })
+    .bind(qq.output, { mapping: (ctx) => ({ api: ctx["qq/api"], commands: ctx.reply }) });
+
+await kernel.start();
+```
+
+The webhook bundle swaps the socket for a request bridge — the HTTP route
+lives outside the composition and hands each callback to the emitted
+`handle`:
+
+```ts
+const qq = qqWebhookPlatform("qq");
+
+const kernel = createKernel()
+    .use(envVars("qq-env", ["QQ_BOT_APP_ID", "QQ_BOT_APP_SECRET"]))
+    .use(qq.webhook, { option: {}, mapping: (ctx) => ({ env: ctx["qq-env"] }) })
+    .bind(qq.api, { option: {}, mapping: (ctx) => ({ env: ctx["qq-env"] }) })
+    .use(reply, { mapping: (ctx) => ({ messages: ctx.qq.messages }) })
+    .bind(qq.output, { mapping: (ctx) => ({ api: ctx["qq/api"], commands: ctx.reply }) });
+// in the hono route: return kernel.ctx.qq.handle(c.req.raw);
+```
+
+`option` is required (even as `{}`) wherever the plugin's config type is
+non-void: `qq.api` accepts `{ apiBase }` to point the REST client at a mock
+in tests, and `qq.input` accepts `{ intents }` (defaults to
+`QQ_INTENT_GROUP_AND_C2C`).
+
+## API overview
+
+Shared by both infras:
+
+- `qqApi(name)` — emits the REST client as `QqApi` under `name`; consumes
+  `{ env: Readonly<Record<string, string>> }`. `QqApi` owns the
+  access-token lifecycle (cached, refreshed ahead of expiry) and exposes
+  `appId`, `accessToken()`, `gatewayUrl()`, and `sendMessage(to, content)`
+  — plain text (`msg_type` 0) to `/v2/groups/:openid/messages` or
+  `/v2/users/:openid/messages`. When the address carries a `msgId` the send
+  is a passive reply: `msg_seq` is taken from the address or
+  auto-incremented per `msgId` when omitted.
+- `qqOutput(name)` — the output half; consumes `{ api, commands }` and
+  sends each command's content (`string`) through the api. Terminal: wire
+  it last.
+- `QqAddress` — `scope: "group" | "c2c"`, `openid` (`group_openid` or the
+  user's openid), optional `msgId`/`msgSeq` passive-reply reference.
+- `QqMessage`, `QqMessageStream`, `QqCommandStream` — the plain-text
+  payload and the two stream contracts features are written against.
+- `decodeMessageEvent(t, d)` — decode a dispatch pair into a message
+  (`GROUP_AT_MESSAGE_CREATE`, `C2C_MESSAGE_CREATE`), or null to ignore.
+  Both inputs share it: the transports deliver the same `{op, t, d}`
+  envelope.
+- `readQqCredentials`, `QqCredentials`, `QqCredentialKeys`,
+  `DEFAULT_QQ_CREDENTIAL_KEYS` — the credentials half.
+
+Gateway infra:
+
+- `qqGatewayPlatform(name)` — the bundle (`api`, `transport`, `input`,
+  `output`), typed as `QqGatewayPlatform`. The api/transport/output are
+  named `${name}/api`, `${name}/transport`, `${name}/output`; the input is
+  named `name`.
+- `qqGatewayTransport(name)` — resolve `GET /gateway`, own the socket, emit
+  the `WsConnection`.
+- `qqGatewayInput(name)` — the receiving half; `QqGatewayInputConfig` for
+  the intents bitmask, `QQ_INTENT_GROUP_AND_C2C` for the default.
+
+Webhook infra:
+
+- `qqWebhookPlatform(name)` — the bundle (`webhook`, `api`, `output`),
+  typed as `QqWebhookPlatform`. The webhook is named `name`; api and output
+  are `${name}/api` and `${name}/output`.
+- `qqWebhook(name)` — the callback algorithm, emitted as `QqWebhook`;
+  `QqWebhook.handle(request)` returns the `Response` to send back, and
+  `QqWebhook.messages` is the decoded message stream. `QqWebhookConfig`
+  carries the credential keys.
+
+## Examples
+
+- [qq-gateway-bot](../../../examples/qq-gateway-bot) — the full gateway round
+  trip against a fake platform: token endpoint, gateway discovery, and a
+  websocket speaking the op-code flow.
+- [qq-webhook-bot](../../../examples/qq-webhook-bot) — a hono-served callback
+  against a fake platform, exercising op-13 validation, a signed dispatch,
+  and a rejected forged signature.
+
+The gateway transport mirrors the generic machinery of
+[`@lambdot/websocket`](../../core/websocket) — the `WsConnection` shape is
+documented there.
+
+## License
+
+Dual-licensed under [Apache-2.0](../../../LICENSE-APACHE) and [MIT](../../../LICENSE-MIT).

package/package.json

@@ -1,16 +1,21 @@
 {
-    "name": "@lambdot/protocol-qq",
-    "version": "0.1.0",
-    "type": "module",
-    "exports": {
-        ".": "./src/index.ts"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "dependencies": {
-        "@lambdot/core": "workspace:*",
-        "@lambdot/websocket": "workspace:*",
-        "tweetnacl": "^1.0.3"
-    }
-}
+  "name": "@lambdot/protocol-qq",
+  "version": "0.1.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Embers-of-the-Fire/lambdot",
+    "directory": "packages/protocol/qq"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "tweetnacl": "^1.0.3",
+    "@lambdot/core": "0.1.1",
+    "@lambdot/websocket": "0.1.1"
+  }
+}

package/src/api.ts

@@ -1,15 +1,16 @@
-import type { Disposer, FeaturePlugin } from "@lambdot/core";
+import type { Plugin } from "@lambdot/core";
+import { definePlugin } from "@lambdot/core";
 
-import { readQqCredentials, type QqCredentialKeys, type QqEnvNeeds } from "./credentials.ts";
+import { readQqCredentials, type QqCredentialKeys } from "./credentials.ts";
 import type { QqAddress } from "./events.ts";
 
 /**
- * The REST half of the qq protocol, provided as a typed capability. Both
- * receiving transports (gateway, webhook) deliver events only; sending a
- * message is always an HTTPS call against the open platform. Owns the
- * access-token lifecycle: tokens are cached and refreshed ahead of expiry
- * (the platform hands out ~7200s tokens and keeps the old one valid for a
- * 60s overlap).
+ * The REST half of the qq protocol, emitted as the plugin's namespace value.
+ * Both receiving transports (gateway, webhook) deliver messages only;
+ * sending a message is always an HTTPS call against the open platform. Owns
+ * the access-token lifecycle: tokens are cached and refreshed ahead of
+ * expiry (the platform hands out ~7200s tokens and keeps the old one valid
+ * for a 60s overlap).
  */
 export interface QqApi {
     readonly appId: string;
@@ -26,8 +27,6 @@ export interface QqApi {
     sendMessage(to: QqAddress, content: string): Promise<void>;
 }
 
-export type QqCapability<TCap extends string> = { readonly [K in TCap]: QqApi };
-
 export interface QqApiConfig {
     /** Open-platform base URL; override to point at a mock in tests. */
     readonly apiBase?: string;
@@ -40,33 +39,22 @@ const DEFAULT_API_BASE = "https://api.bot.qq.com";
 const EXPIRY_MARGIN_MS = 60_000;
 
 /**
- * Provide the qq REST client as a typed capability, reading credentials from
- * the env capability (see `@lambdot/env`). Register the env provider first:
+ * The qq REST client as a plugin, reading credentials from an env snapshot
+ * (see `@lambdot/env`). Wire the env namespace through the mapping:
  *
  * ```ts
  * createKernel()
  *     .use(envVars("qq-env", ["QQ_BOT_APP_ID", "QQ_BOT_APP_SECRET"]))
- *     .use(qqApi("qq-api", "qq-env"));
- * // ctx["qq-api"]: QqApi
+ *     .bind(qqApi("qq/api"), { mapping: (ctx) => ({ env: ctx["qq-env"] }) });
  * ```
  */
-export function qqApi<TCap extends string, TEnvCap extends string>(
-    capability: TCap,
-    env: TEnvCap,
-): FeaturePlugin<
-    {},
-    {},
-    undefined,
-    QqApiConfig,
-    `qq-api:${TCap}`,
-    QqCapability<TCap>,
-    QqEnvNeeds<TEnvCap>
-> {
-    return {
-        name: `qq-api:${capability}`,
-        inject: [env],
-        apply(ctx, config) {
-            const credentials = readQqCredentials(ctx[env], config.keys);
+export function qqApi<const TName extends string>(
+    name: TName,
+): Plugin<{ env: Readonly<Record<string, string>> }, QqApi, QqApiConfig, TName> {
+    return definePlugin({
+        name,
+        apply(input, _scope, config) {
+            const credentials = readQqCredentials(input.env, config.keys);
             const apiBase = config.apiBase ?? DEFAULT_API_BASE;
 
             let cached: { token: string; expiresAt: number } | undefined;
@@ -128,7 +116,7 @@ export function qqApi<TCap extends string, TEnvCap extends string>(
             // Passive replies to one msg_id must increment msg_seq.
             const msgSeqs = new Map<string, number>();
 
-            const api: QqApi = {
+            return {
                 appId: credentials.appId,
                 accessToken,
                 async gatewayUrl() {
@@ -153,13 +141,6 @@ export function qqApi<TCap extends string, TEnvCap extends string>(
                     await authed(path, { method: "POST", body: JSON.stringify(body) });
                 },
             };
-
-            // See `wsTransport` in @lambdot/websocket for why `provide` is pinned here.
-            return (ctx.provide as (name: TCap, value: QqApi) => Disposer).call(
-                ctx,
-                capability,
-                api,
-            );
         },
-    };
+    });
 }

package/src/credentials.ts

@@ -1,13 +1,3 @@
-/**
- * The env-capability view the qq plugins declare as `TInjects`: any
- * string-keyed snapshot of variables. `@lambdot/env`'s
- * `EnvCapability<TCap, TKey>` narrows the keys but stays assignable to this,
- * so the fold's capability-type check accepts it.
- */
-export type QqEnvNeeds<TEnvCap extends string> = {
-    readonly [K in TEnvCap]: Readonly<Record<string, string>>;
-};
-
 /** The bot credentials issued by the QQ open platform. */
 export interface QqCredentials {
     readonly appId: string;

package/src/events.ts

@@ -1,4 +1,4 @@
-import type { Address, EventDef, OutputContract } from "@lambdot/core";
+import type { Address, Command, Message, Stream } from "@lambdot/core";
 
 /**
  * Where a qq message goes. Owned by the output half of the qq platform —
@@ -17,7 +17,7 @@ export interface QqAddress extends Address<"qq"> {
     readonly msgSeq?: number;
 }
 
-/** The payload produced by qq message events: plain-text content only. */
+/** The payload produced by qq message inputs: plain-text content only. */
 export interface QqMessage {
     /** Message id (`msg_id`), reused as the passive-reply reference. */
     readonly id: string;
@@ -27,19 +27,13 @@ export interface QqMessage {
 }
 
 /**
- * Events produced by qq inputs (gateway and webhook alike): one kind per
- * conversation scope. A type alias (not an interface extending `EventMap`)
- * so `keyof` stays exactly these kinds.
+ * The qq platform's stream contracts: inputs emit message streams, features
+ * emit command streams, outputs consume them. Features written against these
+ * two types run on either infra (gateway or webhook) — the wiring `mapping`
+ * is the platform adapter.
  */
-export type QqEvents = {
-    "qq.group-message": EventDef<QqMessage, QqAddress>;
-    "qq.c2c-message": EventDef<QqMessage, QqAddress>;
-};
-
-/** The qq platform's output contract: plain text (msg_type 0). */
-export type QqOutputs = {
-    qq: OutputContract<QqAddress, string>;
-};
+export type QqMessageStream = Stream<Message<QqMessage, QqAddress>>;
+export type QqCommandStream = Stream<Command<QqAddress, string>>;
 
 /** The wire shape of a `GROUP_AT_MESSAGE_CREATE` dispatch body. */
 interface QqRawGroupMessage {
@@ -59,14 +53,14 @@ interface QqRawC2cMessage {
 }
 
 /**
- * Decode a dispatch (`t`, `d`) pair into an ingestible event, or null to
- * ignore it. Shared by the gateway and webhook inputs — both transports
- * deliver the same `{op, t, d}` envelope.
+ * Decode a dispatch (`t`, `d`) pair into a message, or null to ignore it.
+ * Shared by the gateway and webhook inputs — both transports deliver the
+ * same `{op, t, d}` envelope.
  */
 export function decodeMessageEvent(
     t: string,
     d: unknown,
-): { kind: keyof QqEvents; payload: QqMessage; address: QqAddress } | null {
+): { payload: QqMessage; address: QqAddress } | null {
     if (typeof d !== "object" || d === null) return null;
 
     if (t === "GROUP_AT_MESSAGE_CREATE") {
@@ -79,7 +73,6 @@ export function decodeMessageEvent(
         )
             return null;
         return {
-            kind: "qq.group-message",
             payload: {
                 id: raw.id,
                 // The platform strips the @bot prefix but leaves padding.
@@ -105,7 +98,6 @@ export function decodeMessageEvent(
         )
             return null;
         return {
-            kind: "qq.c2c-message",
             payload: {
                 id: raw.id,
                 content: raw.content.trim(),

package/src/gateway.ts

@@ -1,8 +1,10 @@
-import type { Disposer, FeaturePlugin, InputPlugin } from "@lambdot/core";
-import type { WsCapability, WsConnection } from "@lambdot/websocket";
+import type { Message, Plugin } from "@lambdot/core";
+import { channel, definePlugin, message, shareStream } from "@lambdot/core";
+import type { WsConnection } from "@lambdot/websocket";
 
-import type { QqCapability } from "./api.ts";
-import { decodeMessageEvent, type QqEvents } from "./events.ts";
+import type { QqApi } from "./api.ts";
+import type { QqAddress, QqMessage, QqMessageStream } from "./events.ts";
+import { decodeMessageEvent } from "./events.ts";
 
 /** `GROUP_AND_C2C_EVENT` (1 << 25): group at-messages and C2C messages. */
 export const QQ_INTENT_GROUP_AND_C2C = 1 << 25;
@@ -11,31 +13,21 @@ export const QQ_INTENT_GROUP_AND_C2C = 1 << 25;
  * The qq-specific half of the transport: unlike the generic `wsTransport`,
  * the gateway URL is not static configuration — it is discovered through the
  * REST client (`GET /gateway` with the access token). Resolves the URL at
- * activation, owns the socket, and provides the connection as a typed
- * `WsCapability` so the input can ride it. Register after the api:
- *
+ * activation, owns the socket, and emits the connection so the input can
+ * ride it. Wire the api through the mapping:
+
  * ```ts
- * .use(qqApi("qq-api", "qq-env"))
- * .use(qqGatewayTransport("qq-ws", "qq-api"))
+ * .bind(qqApi("qq/api"), ...)
+ * .bind(qqGatewayTransport("qq/transport"), { mapping: (ctx) => ({ api: ctx["qq/api"] }) })
  * ```
  */
-export function qqGatewayTransport<TWsCap extends string, TApiCap extends string>(
-    capability: TWsCap,
-    api: TApiCap,
-): FeaturePlugin<
-    {},
-    {},
-    undefined,
-    void,
-    `qq-gateway-transport:${TWsCap}`,
-    WsCapability<TWsCap>,
-    QqCapability<TApiCap>
-> {
-    return {
-        name: `qq-gateway-transport:${capability}`,
-        inject: [api],
-        async apply(ctx) {
-            const url = await ctx[api].gatewayUrl();
+export function qqGatewayTransport<const TName extends string>(
+    name: TName,
+): Plugin<{ api: QqApi }, WsConnection, void, TName> {
+    return definePlugin({
+        name,
+        async apply(input, scope) {
+            const url = await input.api.gatewayUrl();
             const socket = new WebSocket(url);
             await new Promise<void>((resolve, reject) => {
                 socket.addEventListener("open", () => resolve(), { once: true });
@@ -45,36 +37,21 @@ export function qqGatewayTransport<TWsCap extends string, TApiCap extends string
                     { once: true },
                 );
             });
-
-            const listeners = new Set<(data: string) => void>();
-            socket.addEventListener("message", (event) => {
-                if (typeof event.data !== "string") return;
-                for (const listener of listeners) listener(event.data);
+            scope.onDispose(() => {
+                socket.close();
             });
 
-            const connection: WsConnection = {
+            return {
                 url,
                 send: (data) => socket.send(data),
                 onMessage(listener) {
-                    listeners.add(listener);
-                    return () => {
-                        listeners.delete(listener);
-                    };
+                    socket.addEventListener("message", (event) => {
+                        if (typeof event.data === "string") listener(event.data);
+                    });
                 },
             };
-
-            // See `wsTransport` in @lambdot/websocket for why `provide` is pinned here.
-            const unprovide = (ctx.provide as (name: TWsCap, value: WsConnection) => Disposer).call(
-                ctx,
-                capability,
-                connection,
-            );
-            return () => {
-                socket.close();
-                void unprovide();
-            };
         },
-    };
+    });
 }
 
 export interface QqGatewayInputConfig {
@@ -83,33 +60,25 @@ export interface QqGatewayInputConfig {
 }
 
 /**
- * The receiving half of the gateway infra: consumes the connection provided
+ * The receiving half of the gateway infra: consumes the connection emitted
  * by {@link qqGatewayTransport} and runs the basic gateway algorithm —
  * identify on hello (op 10), heartbeat on the advertised interval (op 1),
- * decode dispatches (op 0) into message events. Resume (op 6) is deliberately
- * not implemented: a dropped connection is a fresh identify.
+ * decode dispatches (op 0) into the emitted message stream. Resume (op 6) is
+ * deliberately not implemented: a dropped connection is a fresh identify.
  */
-export function qqGatewayInput<TWsCap extends string, TApiCap extends string>(
-    ws: TWsCap,
-    api: TApiCap,
-): InputPlugin<
-    QqEvents,
-    QqGatewayInputConfig,
-    "qq-gateway-input",
-    {},
-    WsCapability<TWsCap> & QqCapability<TApiCap>
-> {
-    return {
-        role: "input",
-        name: "qq-gateway-input",
-        inject: [ws, api],
-        apply(ctx, config) {
-            const connection = ctx[ws];
+export function qqGatewayInput<const TName extends string>(
+    name: TName,
+): Plugin<{ connection: WsConnection; api: QqApi }, QqMessageStream, QqGatewayInputConfig, TName> {
+    return definePlugin({
+        name,
+        apply(input, scope, config) {
+            const { connection, api } = input;
             const intents = config.intents ?? QQ_INTENT_GROUP_AND_C2C;
+            const out = channel<Message<QqMessage, QqAddress>>();
             let lastSeq: number | null = null;
             let heartbeat: ReturnType<typeof setInterval> | undefined;
 
-            const unsubscribe = connection.onMessage((data) => {
+            connection.onMessage((data) => {
                 let frame: { op?: unknown; d?: unknown; s?: unknown; t?: unknown };
                 try {
                     frame = JSON.parse(data) as typeof frame;
@@ -126,7 +95,7 @@ export function qqGatewayInput<TWsCap extends string, TApiCap extends string>(
                             typeof d?.heartbeat_interval === "number"
                                 ? d.heartbeat_interval
                                 : 45_000;
-                        void ctx[api].accessToken().then((token) => {
+                        void api.accessToken().then((token) => {
                             connection.send(
                                 JSON.stringify({
                                     op: 2,
@@ -145,21 +114,22 @@ export function qqGatewayInput<TWsCap extends string, TApiCap extends string>(
                         break;
                     }
                     case 0: {
-                        // Dispatch: message events become lambdot events.
+                        // Dispatch: message frames join the emitted stream.
                         if (typeof frame.t !== "string") break;
                         const decoded = decodeMessageEvent(frame.t, frame.d);
-                        if (decoded)
-                            void ctx.ingest(decoded.kind, decoded.payload, decoded.address);
+                        if (decoded) out.push(message(decoded.payload, decoded.address));
                         break;
                     }
                     // 11 is a heartbeat ack; every other opcode needs no handling.
                 }
             });
 
-            return () => {
+            scope.onDispose(() => {
                 if (heartbeat !== undefined) clearInterval(heartbeat);
-                void unsubscribe();
-            };
+                out.close();
+            });
+            // Shared: several consumers may subscribe to the message stream.
+            return shareStream(out.stream);
         },
-    };
+    });
 }

package/src/index.ts

@@ -1,27 +1,25 @@
-import type { FeaturePlugin, InputPlugin, OutputPlugin } from "@lambdot/core";
-import type { WsCapability } from "@lambdot/websocket";
+import type { Plugin } from "@lambdot/core";
+import type { WsConnection } from "@lambdot/websocket";
 
-import { qqApi, type QqApiConfig, type QqCapability } from "./api.ts";
-import type { QqEnvNeeds } from "./credentials.ts";
-import type { QqAddress, QqEvents } from "./events.ts";
+import { qqApi, type QqApi, type QqApiConfig } from "./api.ts";
+import type { QqCommandStream, QqMessageStream } from "./events.ts";
 import { qqGatewayInput, qqGatewayTransport, type QqGatewayInputConfig } from "./gateway.ts";
 import { qqOutput } from "./output.ts";
-import { qqWebhookInput, type QqWebhookCapability, type QqWebhookConfig } from "./webhook.ts";
+import { qqWebhook, type QqWebhook, type QqWebhookConfig } from "./webhook.ts";
 
-export { qqApi, type QqApi, type QqApiConfig, type QqCapability } from "./api.ts";
+export { qqApi, type QqApi, type QqApiConfig } from "./api.ts";
 export {
     DEFAULT_QQ_CREDENTIAL_KEYS,
     readQqCredentials,
     type QqCredentialKeys,
     type QqCredentials,
-    type QqEnvNeeds,
 } from "./credentials.ts";
 export {
     decodeMessageEvent,
     type QqAddress,
-    type QqEvents,
+    type QqCommandStream,
     type QqMessage,
-    type QqOutputs,
+    type QqMessageStream,
 } from "./events.ts";
 export {
     QQ_INTENT_GROUP_AND_C2C,
@@ -30,150 +28,107 @@ export {
     type QqGatewayInputConfig,
 } from "./gateway.ts";
 export { qqOutput } from "./output.ts";
-export {
-    qqWebhookInput,
-    type QqWebhook,
-    type QqWebhookCapability,
-    type QqWebhookConfig,
-} from "./webhook.ts";
+export { qqWebhook, type QqWebhook, type QqWebhookConfig } from "./webhook.ts";
 
 /**
- * One qq platform over the websocket gateway, bundled: the REST client, the
- * gateway transport that discovers the socket URL through it, the receiving
- * input, and the shared output. The pieces stay separate (rather than one
- * fused plugin) so the type fold can keep enforcing registration order:
- * env provider → api → transport → input → output → features.
- *
+ * One qq platform over the websocket gateway, bundled as leaves. The api and
+ * transport are internal wiring (compose them with `bind`); the input's
+ * message stream is exposed under the platform name (compose with `use`).
+ * The output is terminal, so it is always wired last:
+
  * ```ts
- * const qq = qqGatewayPlatform({ ws: "qq-ws", api: "qq-api", env: "qq-env" });
+ * const qq = qqGatewayPlatform("qq");
  * createKernel()
  *     .use(envVars("qq-env", ["QQ_BOT_APP_ID", "QQ_BOT_APP_SECRET"]))
- *     .use(qq.api, {})
- *     .use(qq.transport)
- *     .use(qq.input, {})
- *     .use(qq.output);
+ *     .bind(qq.api, { option: {}, mapping: (ctx) => ({ env: ctx["qq-env"] }) })
+ *     .bind(qq.transport, { mapping: (ctx) => ({ api: ctx["qq/api"] }) })
+ *     .use(qq.input, {
+ *         option: {},
+ *         mapping: (ctx) => ({ connection: ctx["qq/transport"], api: ctx["qq/api"] }),
+ *     })
+ *     .use(reply, { mapping: (ctx) => ({ messages: ctx.qq }) })
+ *     .bind(qq.output, { mapping: (ctx) => ({ api: ctx["qq/api"], commands: ctx.reply }) });
  * ```
  */
-export interface QqGatewayPlatform<
-    TWsCap extends string,
-    TApiCap extends string,
-    TEnvCap extends string,
-> {
-    readonly api: FeaturePlugin<
-        {},
-        {},
-        undefined,
+export interface QqGatewayPlatform<TName extends string> {
+    readonly api: Plugin<
+        { env: Readonly<Record<string, string>> },
+        QqApi,
         QqApiConfig,
-        `qq-api:${TApiCap}`,
-        QqCapability<TApiCap>,
-        QqEnvNeeds<TEnvCap>
-    >;
-    readonly transport: FeaturePlugin<
-        {},
-        {},
-        undefined,
-        void,
-        `qq-gateway-transport:${TWsCap}`,
-        WsCapability<TWsCap>,
-        QqCapability<TApiCap>
+        `${TName}/api`
     >;
-    readonly input: InputPlugin<
-        QqEvents,
+    readonly transport: Plugin<{ api: QqApi }, WsConnection, void, `${TName}/transport`>;
+    readonly input: Plugin<
+        { connection: WsConnection; api: QqApi },
+        QqMessageStream,
         QqGatewayInputConfig,
-        "qq-gateway-input",
-        {},
-        WsCapability<TWsCap> & QqCapability<TApiCap>
+        TName
     >;
-    readonly output: OutputPlugin<
-        "qq",
-        QqAddress,
-        string,
+    readonly output: Plugin<
+        { api: QqApi; commands: QqCommandStream },
         void,
-        "qq-output",
-        {},
-        QqCapability<TApiCap>
+        void,
+        `${TName}/output`
     >;
 }
 
-/** Build a whole gateway-backed qq platform from its capability names. */
-export function qqGatewayPlatform<
-    TWsCap extends string,
-    TApiCap extends string,
-    TEnvCap extends string,
->(capabilities: {
-    readonly ws: TWsCap;
-    readonly api: TApiCap;
-    readonly env: TEnvCap;
-}): QqGatewayPlatform<TWsCap, TApiCap, TEnvCap> {
+/** Build a whole gateway-backed qq platform under one name. */
+export function qqGatewayPlatform<const TName extends string>(
+    name: TName,
+): QqGatewayPlatform<TName> {
     return {
-        api: qqApi(capabilities.api, capabilities.env),
-        transport: qqGatewayTransport(capabilities.ws, capabilities.api),
-        input: qqGatewayInput(capabilities.ws, capabilities.api),
-        output: qqOutput(capabilities.api),
+        api: qqApi(`${name}/api`),
+        transport: qqGatewayTransport(`${name}/transport`),
+        input: qqGatewayInput(name),
+        output: qqOutput(`${name}/output`),
     };
 }
 
 /**
- * One qq platform over the webhook (reversed-post) infra, bundled: the
- * webhook input that provides the callback-handler capability, the REST
- * client, and the output. Registration order: env provider → webhook → api →
- * output → features.
- *
+ * One qq platform over the webhook (reversed-post) infra, bundled as leaves.
+ * The webhook is exposed under the platform name — its `handle` serves the
+ * HTTP callback route, its `messages` stream feeds the features. The api is
+ * internal wiring; the output is terminal:
+
  * ```ts
- * const qq = qqWebhookPlatform({ webhook: "qq-webhook", api: "qq-api", env: "qq-env" });
+ * const qq = qqWebhookPlatform("qq");
  * createKernel()
  *     .use(envVars("qq-env", ["QQ_BOT_APP_ID", "QQ_BOT_APP_SECRET"]))
- *     .use(qq.webhook, {})
- *     .use(qq.api, {})
- *     .use(qq.output);
- * // in the hono route: return kernel.ctx["qq-webhook"].handle(c.req.raw);
+ *     .use(qq.webhook, { option: {}, mapping: (ctx) => ({ env: ctx["qq-env"] }) })
+ *     .bind(qq.api, { option: {}, mapping: (ctx) => ({ env: ctx["qq-env"] }) })
+ *     .use(reply, { mapping: (ctx) => ({ messages: ctx.qq.messages }) })
+ *     .bind(qq.output, { mapping: (ctx) => ({ api: ctx["qq/api"], commands: ctx.reply }) });
+ * // in the hono route: return kernel.ctx.qq.handle(c.req.raw);
  * ```
  */
-export interface QqWebhookPlatform<
-    TCap extends string,
-    TApiCap extends string,
-    TEnvCap extends string,
-> {
-    readonly webhook: InputPlugin<
-        QqEvents,
+export interface QqWebhookPlatform<TName extends string> {
+    readonly webhook: Plugin<
+        { env: Readonly<Record<string, string>> },
+        QqWebhook,
         QqWebhookConfig,
-        `qq-webhook:${TCap}`,
-        QqWebhookCapability<TCap>,
-        QqEnvNeeds<TEnvCap>
+        TName
     >;
-    readonly api: FeaturePlugin<
-        {},
-        {},
-        undefined,
+    readonly api: Plugin<
+        { env: Readonly<Record<string, string>> },
+        QqApi,
         QqApiConfig,
-        `qq-api:${TApiCap}`,
-        QqCapability<TApiCap>,
-        QqEnvNeeds<TEnvCap>
+        `${TName}/api`
     >;
-    readonly output: OutputPlugin<
-        "qq",
-        QqAddress,
-        string,
+    readonly output: Plugin<
+        { api: QqApi; commands: QqCommandStream },
+        void,
         void,
-        "qq-output",
-        {},
-        QqCapability<TApiCap>
+        `${TName}/output`
     >;
 }
 
-/** Build a whole webhook-backed qq platform from its capability names. */
-export function qqWebhookPlatform<
-    TCap extends string,
-    TApiCap extends string,
-    TEnvCap extends string,
->(capabilities: {
-    readonly webhook: TCap;
-    readonly api: TApiCap;
-    readonly env: TEnvCap;
-}): QqWebhookPlatform<TCap, TApiCap, TEnvCap> {
+/** Build a whole webhook-backed qq platform under one name. */
+export function qqWebhookPlatform<const TName extends string>(
+    name: TName,
+): QqWebhookPlatform<TName> {
     return {
-        webhook: qqWebhookInput(capabilities.webhook, capabilities.env),
-        api: qqApi(capabilities.api, capabilities.env),
-        output: qqOutput(capabilities.api),
+        webhook: qqWebhook(name),
+        api: qqApi(`${name}/api`),
+        output: qqOutput(`${name}/output`),
     };
 }

package/src/output.ts

@@ -1,31 +1,29 @@
-import type { OutputPlugin } from "@lambdot/core";
+import type { Plugin } from "@lambdot/core";
+import { definePlugin, pumpStream } from "@lambdot/core";
 
-import type { QqApi, QqCapability } from "./api.ts";
-import type { QqAddress } from "./events.ts";
+import type { QqApi } from "./api.ts";
+import type { QqCommandStream } from "./events.ts";
 
 /**
- * The output half of the qq platform: plain text (msg_type 0) through the
- * REST client provided by `qqApi`. Sending is transport-independent — the
- * gateway and webhook infras share this output.
+ * The output half of the qq platform: consumes a command stream and sends
+ * each command as plain text (msg_type 0) through the REST client. Sending
+ * is transport-independent — the gateway and webhook infras share this
+ * output. Terminal: wire it last, after the features it consumes.
  */
-export function qqOutput<TApiCap extends string>(
-    api: TApiCap,
-): OutputPlugin<"qq", QqAddress, string, void, "qq-output", {}, QqCapability<TApiCap>> {
-    let client: QqApi | undefined;
-    return {
-        role: "output",
-        name: "qq-output",
-        platform: "qq",
-        inject: [api],
-        async send(to, content) {
-            if (!client) throw new Error('output "qq" is not active');
-            await client.sendMessage(to, content);
+export function qqOutput<const TName extends string>(
+    name: TName,
+): Plugin<{ api: QqApi; commands: QqCommandStream }, void, void, TName> {
+    return definePlugin({
+        name,
+        apply(input, scope) {
+            const { api } = input;
+            scope.onDispose(
+                pumpStream(
+                    input.commands,
+                    (cmd) => api.sendMessage(cmd.address, cmd.content),
+                    (error) => scope.onError(error),
+                ),
+            );
         },
-        apply(ctx) {
-            client = ctx[api];
-            return () => {
-                client = undefined;
-            };
-        },
-    };
+    });
 }

package/src/webhook.ts

@@ -1,21 +1,22 @@
-import type { Disposer, InputPlugin } from "@lambdot/core";
+import type { Message, Plugin } from "@lambdot/core";
+import { channel, definePlugin, message, shareStream } from "@lambdot/core";
 import nacl from "tweetnacl";
 
-import { readQqCredentials, type QqCredentialKeys, type QqEnvNeeds } from "./credentials.ts";
-import { decodeMessageEvent, type QqEvents } from "./events.ts";
+import { readQqCredentials, type QqCredentialKeys } from "./credentials.ts";
+import type { QqAddress, QqMessage, QqMessageStream } from "./events.ts";
+import { decodeMessageEvent } from "./events.ts";
 
 /**
- * The request bridge, provided as a typed capability: the HTTP route lives
- * outside the event pipeline (a hono handler, a worker's fetch), so it hands
- * each callback request to `handle` and sends back the returned response —
- * the same bridge pattern as the cloudflare example's `PingService`.
+ * The request bridge, emitted as the plugin's namespace value: the HTTP
+ * route lives outside the composition (a hono handler, a worker's fetch), so
+ * it hands each callback request to `handle` and sends back the returned
+ * response. Decoded message dispatches join the `messages` stream.
  */
 export interface QqWebhook {
     handle(request: Request): Promise<Response>;
+    readonly messages: QqMessageStream;
 }
 
-export type QqWebhookCapability<TCap extends string> = { readonly [K in TCap]: QqWebhook };
-
 export interface QqWebhookConfig {
     /** Which env variables carry the credentials. */
     readonly keys?: QqCredentialKeys;
@@ -23,40 +24,37 @@ export interface QqWebhookConfig {
 
 /**
  * The webhook (reversed-post) input: QQ pushes events to an HTTPS callback
- * address. Registers the message event kinds and provides a {@link QqWebhook}
- * capability that implements the callback algorithm — op 13 address
- * validation (sign `event_ts + plain_token`), ed25519 verification of
- * `X-Signature-Ed25519` over `timestamp + body` for everything else — then
- * ingests message dispatches. The bot secret seeds the ed25519 keypair
- * (repeated to 32 bytes).
+ * address. Emits a {@link QqWebhook} that implements the callback algorithm —
+ * op 13 address validation (sign `event_ts + plain_token`), ed25519
+ * verification of `X-Signature-Ed25519` over `timestamp + body` for
+ * everything else — then pushes message dispatches to the stream. The bot
+ * secret seeds the ed25519 keypair (repeated to 32 bytes).
  *
  * ```ts
- * .use(qqWebhookInput("qq-webhook", "qq-env"), {});
- * // in the hono route: return kernel.ctx["qq-webhook"].handle(c.req.raw);
+ * .use(qqWebhook("qq"), { option: {}, mapping: (ctx) => ({ env: ctx["qq-env"] }) });
+ * // in the hono route: return kernel.ctx.qq.handle(c.req.raw);
  * ```
  */
-export function qqWebhookInput<TCap extends string, TEnvCap extends string>(
-    capability: TCap,
-    env: TEnvCap,
-): InputPlugin<
-    QqEvents,
-    QqWebhookConfig,
-    `qq-webhook:${TCap}`,
-    QqWebhookCapability<TCap>,
-    QqEnvNeeds<TEnvCap>
-> {
-    return {
-        role: "input",
-        name: `qq-webhook:${capability}`,
-        inject: [env],
-        apply(ctx, config) {
-            const credentials = readQqCredentials(ctx[env], config.keys);
+export function qqWebhook<const TName extends string>(
+    name: TName,
+): Plugin<{ env: Readonly<Record<string, string>> }, QqWebhook, QqWebhookConfig, TName> {
+    return definePlugin({
+        name,
+        apply(input, scope, config) {
+            const credentials = readQqCredentials(input.env, config.keys);
             // The bot secret seeds the ed25519 keypair: repeat to 32 bytes.
             let seed = credentials.clientSecret;
             while (seed.length < 32) seed += seed;
             const keyPair = nacl.sign.keyPair.fromSeed(new TextEncoder().encode(seed.slice(0, 32)));
 
+            const messages = channel<Message<QqMessage, QqAddress>>();
+            scope.onDispose(() => {
+                messages.close();
+            });
+
             const webhook: QqWebhook = {
+                // Shared: several consumers may subscribe to the stream.
+                messages: shareStream(messages.stream),
                 async handle(request) {
                     if (request.method !== "POST")
                         return new Response("method not allowed", { status: 405 });
@@ -98,21 +96,15 @@ export function qqWebhookInput<TCap extends string, TEnvCap extends string>(
 
                     if (frame.op === 0 && typeof frame.t === "string") {
                         const decoded = decodeMessageEvent(frame.t, frame.d);
-                        if (decoded)
-                            await ctx.ingest(decoded.kind, decoded.payload, decoded.address);
+                        if (decoded) messages.push(message(decoded.payload, decoded.address));
                     }
                     return Response.json({});
                 },
             };
 
-            // See `wsTransport` in @lambdot/websocket for why `provide` is pinned here.
-            return (ctx.provide as (name: TCap, value: QqWebhook) => Disposer).call(
-                ctx,
-                capability,
-                webhook,
-            );
+            return webhook;
         },
-    };
+    });
 }
 
 function verify(publicKey: Uint8Array, message: string, signatureHex: string): boolean {