@zhin.js/adapter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+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/README.md

@@ -0,0 +1,21 @@
+# @zhin.js/adapter
+
+Zhin Plugin Runtime 的 Adapter Feature。它从插件或项目的 `adapters/**/*.ts` 发现
+`defineAdapter()` 定义，按 Plugin owner 投影 Endpoint，并把 start/open/close/stop 纳入同一
+generation handoff。
+
+```ts
+import { defineAdapter } from '@zhin.js/adapter';
+
+export default defineAdapter({
+  capabilities: ['inbound', 'outbound'],
+  create: (context) => ({ name: context.name }),
+});
+```
+
+本包只依赖 Kernel 与 Feature Kit，不包含具体平台 SDK。生产 manifest 指向
+`lib/provider.js`；开发时可通过 conditional export 读取源码。
+
+验证：`pnpm --filter @zhin.js/adapter test && pnpm --filter @zhin.js/adapter build`。
+
+架构说明见 [Plugin Monorepo 与 Feature Provider](../../../docs/architecture/target-implementation/plugin-monorepo-and-features.md)。

package/lib/adapter-index.d.ts

@@ -0,0 +1,44 @@
+import { type CapabilityId, type CapabilitySlot, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { AdapterCapability, AdapterDefinition, EndpointInstance, EndpointSendRequest } from './definition.js';
+export interface AdapterDescriptor {
+    readonly id: CapabilityId;
+    readonly owner: PluginId;
+    readonly name: string;
+    readonly source: string;
+    readonly capabilities: readonly AdapterCapability[];
+}
+/** Console / Host-facing endpoint row (connected = admission open). */
+export interface AdapterEndpointSummary extends AdapterDescriptor {
+    readonly connected: boolean;
+    readonly status: 'online' | 'offline';
+    readonly phase: AdapterEndpointPhase;
+}
+export type AdapterEndpointPhase = 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
+export declare class AdapterIndex {
+    #private;
+    readonly $projection: "zhin.adapter-index/1";
+    private constructor();
+    static create(slots: readonly Readonly<CapabilitySlot<AdapterDefinition>>[], snapshot: RuntimeSnapshot, options?: {
+        readonly startTimeoutMs?: number;
+        readonly deferredGiveUpMs?: number;
+    }): Promise<AdapterIndex>;
+    list(): readonly AdapterDescriptor[];
+    /** Endpoint rows for Console `endpoint.list` / `endpoint.info`. */
+    describe(): readonly AdapterEndpointSummary[];
+    /**
+     * Resolve a Console `$adapter` + `$endpoint` pair to a capability id.
+     * Matches local name, capability id, or owner path segments.
+     */
+    resolve(adapter: string, endpointId: string): CapabilityId | undefined;
+    /**
+     * Resolve a live EndpointInstance for Host-side side channels (reactions, etc.).
+     */
+    instance(adapter: string, endpointId: string): EndpointInstance | undefined;
+    owner(id: CapabilityId): PluginId;
+    start(): Promise<void>;
+    open(): void;
+    close(): Promise<void>;
+    stop(): Promise<void>;
+    send(id: CapabilityId, request: EndpointSendRequest): Promise<unknown>;
+}
+export declare function isAdapterIndex(value: unknown): value is AdapterIndex;

package/lib/adapter-index.js

@@ -0,0 +1,378 @@
+import { DisposeStack, } from '@zhin.js/plugin-runtime';
+import { createCapabilityContext } from '@zhin.js/feature-kit';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('Adapter');
+export class AdapterIndex {
+    $projection = 'zhin.adapter-index/1';
+    #records = new Map();
+    #order;
+    /** True after `open()` until `close()` / `stop()` — late starts may open themselves. */
+    #admissionOpen = false;
+    #startTimeoutMs;
+    /** Final give-up budget for deferred starts (never-settling start promises). */
+    #deferredGiveUpMs;
+    constructor(records, startTimeoutMs, deferredGiveUpMs) {
+        this.#order = Object.freeze([...records]);
+        this.#startTimeoutMs = startTimeoutMs;
+        this.#deferredGiveUpMs = deferredGiveUpMs;
+        for (const record of records)
+            this.#records.set(record.id, record);
+    }
+    static async create(slots, snapshot, options = {}) {
+        const records = [];
+        const unconfigured = [];
+        try {
+            for (const slot of [...slots].sort((left, right) => left.id.localeCompare(right.id))) {
+                const endpoint = await createEndpointSoft(slot, snapshot);
+                if (endpoint.unconfigured)
+                    unconfigured.push(slot.localName);
+                records.push({
+                    id: slot.id,
+                    owner: slot.owner,
+                    name: slot.localName,
+                    source: slot.source,
+                    capabilities: slot.definition.capabilities,
+                    endpoint: endpoint.instance,
+                    unconfigured: endpoint.unconfigured,
+                    started: false,
+                    open: false,
+                    failed: false,
+                    startAttempted: false,
+                    // Unconfigured stubs skip start/open so kitchen-sink Roots stay quiet.
+                    stopped: endpoint.unconfigured,
+                });
+            }
+            if (unconfigured.length > 0) {
+                logger.info(formatCompact({
+                    op: 'adapters_unconfigured',
+                    count: unconfigured.length,
+                    names: unconfigured.join(','),
+                }));
+            }
+            return new AdapterIndex(records, options.startTimeoutMs ?? 3_000, options.deferredGiveUpMs ?? 60_000);
+        }
+        catch (error) {
+            await stopRecords(records, error);
+            throw error;
+        }
+    }
+    list() {
+        return this.#order.map(({ endpoint: _endpoint, unconfigured: _unconfigured, started: _started, open: _open, stopped: _stopped, failed: _failed, startAttempted: _startAttempted, ...descriptor }) => Object.freeze(descriptor));
+    }
+    /** Endpoint rows for Console `endpoint.list` / `endpoint.info`. */
+    describe() {
+        return Object.freeze(this.#order.map((record) => Object.freeze({
+            id: record.id,
+            owner: record.owner,
+            // Console 展示用 live name（如 ICQQ uin、sandbox bot 名），缺省回退 slot localName
+            name: endpointLiveName(record.endpoint) ?? record.name,
+            source: record.source,
+            capabilities: record.capabilities,
+            connected: record.open && !record.stopped,
+            status: record.open && !record.stopped ? 'online' : 'offline',
+            phase: endpointPhase(record),
+        })));
+    }
+    /**
+     * Resolve a Console `$adapter` + `$endpoint` pair to a capability id.
+     * Matches local name, capability id, or owner path segments.
+     */
+    resolve(adapter, endpointId) {
+        const matches = this.#order.filter((record) => matchesEndpoint(record, adapter, endpointId));
+        if (matches.length === 1)
+            return matches[0]?.id;
+        if (matches.length === 0)
+            return undefined;
+        // Prefer exact localName === endpointId when ambiguous.
+        const exact = matches.find((record) => record.name === endpointId);
+        return exact?.id ?? matches[0]?.id;
+    }
+    /**
+     * Resolve a live EndpointInstance for Host-side side channels (reactions, etc.).
+     */
+    instance(adapter, endpointId) {
+        const id = this.resolve(adapter, endpointId);
+        if (!id)
+            return undefined;
+        return this.#records.get(id)?.endpoint;
+    }
+    owner(id) {
+        const record = this.#records.get(id);
+        if (!record)
+            throw new Error(`Unknown Adapter Endpoint: ${id}`);
+        return record.owner;
+    }
+    async start() {
+        // Soft-start in parallel with a short wait so kitchen-sink Roots do not
+        // stall generation. Configured platforms that need longer (QQ auth, Slack
+        // socket, GitHub verify) stay in-flight instead of being stop()'d mid-connect.
+        const startTimeoutMs = this.#startTimeoutMs;
+        await Promise.all(this.#order.map(async (record) => {
+            if (record.started || record.stopped)
+                return;
+            record.startAttempted = true;
+            const startPromise = (async () => record.endpoint.start?.())();
+            try {
+                await withTimeout(startPromise, startTimeoutMs, `Adapter start timed out after ${startTimeoutMs}ms`);
+                if (record.stopped)
+                    return;
+                record.started = true;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (message.includes('timed out after')) {
+                    logger.info(formatCompact({
+                        op: 'adapter_start_deferred',
+                        id: record.id,
+                        name: record.name,
+                        waitMs: startTimeoutMs,
+                    }));
+                    // Final backstop: a deferred start promise that never settles must
+                    // not keep the Endpoint in limbo forever.
+                    const giveUp = setTimeout(() => {
+                        if (record.stopped || record.started)
+                            return;
+                        record.stopped = true;
+                        record.failed = true;
+                        // Swallow a late rejection so it does not become unhandled.
+                        void startPromise.catch(() => undefined);
+                        logger.warn(formatCompact({
+                            op: 'adapter_start_give_up',
+                            id: record.id,
+                            name: record.name,
+                            waitMs: this.#deferredGiveUpMs,
+                        }));
+                    }, this.#deferredGiveUpMs);
+                    giveUp.unref?.();
+                    void startPromise.then(() => {
+                        clearTimeout(giveUp);
+                        if (record.stopped || record.started)
+                            return;
+                        record.started = true;
+                        if (this.#admissionOpen && !record.open) {
+                            try {
+                                record.endpoint.open?.();
+                                record.open = true;
+                            }
+                            catch (openError) {
+                                logger.warn(formatCompact({
+                                    op: 'adapter_open_after_deferred_fail',
+                                    id: record.id,
+                                    name: record.name,
+                                    error: openError instanceof Error ? openError.message : String(openError),
+                                }));
+                            }
+                        }
+                    }, (startError) => {
+                        clearTimeout(giveUp);
+                        if (record.stopped)
+                            return;
+                        record.stopped = true;
+                        record.failed = true;
+                        logger.warn(formatCompact({
+                            op: 'adapter_start_soft_fail',
+                            id: record.id,
+                            name: record.name,
+                            error: startError instanceof Error ? startError.message : String(startError),
+                            stack: startError instanceof Error ? startError.stack : undefined,
+                        }));
+                    });
+                    return;
+                }
+                record.stopped = true;
+                record.failed = true;
+                void startPromise.catch(() => undefined);
+                // Startup connect failures are logged once here (with stack); Endpoint
+                // implementations must NOT re-log them at error level.
+                logger.warn(formatCompact({
+                    op: 'adapter_start_soft_fail',
+                    id: record.id,
+                    name: record.name,
+                    error: message,
+                    stack: error instanceof Error ? error.stack : undefined,
+                }));
+                // No endpoint.stop() here: adapter Endpoints self-stop in their start()
+                // catch by convention (verified across icqq/qq/slack/… endpoints).
+            }
+        }));
+    }
+    open() {
+        this.#admissionOpen = true;
+        const errors = [];
+        for (const record of this.#order) {
+            if (!record.started || record.open || record.stopped)
+                continue;
+            try {
+                record.endpoint.open?.();
+                record.open = true;
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length > 0)
+            throw new AggregateError(errors, 'Adapter Endpoint open failed');
+    }
+    async close() {
+        this.#admissionOpen = false;
+        const stack = new DisposeStack();
+        for (const record of this.#order) {
+            if (!record.open || record.stopped)
+                continue;
+            stack.add(async () => {
+                await record.endpoint.close?.();
+                record.open = false;
+            });
+        }
+        await stack.dispose();
+    }
+    async stop() {
+        const stack = new DisposeStack();
+        // DisposeStack unwinds in reverse: admission closes before transports stop,
+        // and a close failure cannot skip transport cleanup.
+        stack.add(() => stopRecords(this.#order));
+        stack.add(() => this.close());
+        await stack.dispose();
+    }
+    async send(id, request) {
+        const record = this.#records.get(id);
+        if (!record)
+            throw new Error(`Unknown Adapter Endpoint: ${id}`);
+        if (!record.capabilities.includes('outbound') || !record.endpoint.send) {
+            throw new Error(`Adapter Endpoint does not support outbound: ${id}`);
+        }
+        if (!record.started || record.stopped) {
+            throw new Error(`Adapter Endpoint is not active: ${id}`);
+        }
+        return record.endpoint.send(request);
+    }
+}
+export function isAdapterIndex(value) {
+    return !!value && typeof value === 'object'
+        && value.$projection === 'zhin.adapter-index/1';
+}
+function matchesEndpoint(record, adapter, endpointId) {
+    const adapterOk = record.name === adapter
+        || record.id === adapter
+        || record.id.endsWith(`/${adapter}`)
+        || record.owner === adapter
+        || record.owner.endsWith(`/${adapter}`);
+    // Live EndpointInstance.name is the bot runtime id (e.g. ICQQ uin). Host /
+    // activity-feedback resolve with that id; slot.localName alone is not enough
+    // when multiple plugin instances share localName "icqq".
+    const liveName = endpointLiveName(record.endpoint);
+    const endpointOk = record.name === endpointId
+        || record.id === endpointId
+        || record.id.endsWith(`/${endpointId}`)
+        || (liveName !== undefined && liveName === endpointId);
+    return adapterOk && endpointOk;
+}
+function endpointLiveName(endpoint) {
+    const name = endpoint.name;
+    return typeof name === 'string' && name.length > 0 ? name : undefined;
+}
+function endpointPhase(record) {
+    if (record.unconfigured)
+        return 'unconfigured';
+    if (record.failed)
+        return 'failed';
+    if (record.open && !record.stopped)
+        return 'online';
+    if (record.startAttempted)
+        return 'starting';
+    return 'pending';
+}
+function assertEndpoint(value, id) {
+    if (!value || typeof value !== 'object') {
+        throw new TypeError(`Adapter ${id} create() must return an Endpoint instance`);
+    }
+}
+/**
+ * Adapter `resolveXxxConfig` helpers report missing config/credentials as
+ * TypeError("… requires …") by convention; only those are expected failures.
+ */
+function isUnconfiguredError(error) {
+    return (error instanceof TypeError
+        && /requires|not configured|missing|未配置|缺少/i.test(error.message));
+}
+async function createEndpointSoft(slot, snapshot) {
+    let endpoint;
+    try {
+        endpoint = await slot.definition.create(Object.freeze({
+            ...createCapabilityContext(snapshot, slot.owner),
+            id: slot.id,
+            name: slot.localName,
+        }));
+    }
+    catch (error) {
+        // Missing config / credentials: degrade to an inert stub so the rest of
+        // the generation still boots. Anything else (network failures, bugs in
+        // create()) is unexpected — keep the stub but surface a warning instead
+        // of silently swallowing it at debug level.
+        const message = error instanceof Error ? error.message : String(error);
+        const log = isUnconfiguredError(error) ? logger.debug.bind(logger) : logger.warn.bind(logger);
+        log(formatCompact({
+            op: 'adapter_create_soft_fail',
+            id: slot.id,
+            name: slot.localName,
+            error: message,
+        }));
+        return {
+            instance: createUnconfiguredEndpoint(message),
+            unconfigured: true,
+        };
+    }
+    // Programming errors (create() did not return an Endpoint) must surface:
+    // they propagate to AdapterIndex.create's catch, which disposes the records
+    // created so far instead of hiding the bug behind an unconfigured stub.
+    assertEndpoint(endpoint, slot.id);
+    return { instance: endpoint, unconfigured: false };
+}
+function createUnconfiguredEndpoint(reason) {
+    return Object.freeze({
+        start() {
+            throw new Error(`Adapter unconfigured: ${reason}`);
+        },
+        open() { },
+        close() { },
+        stop() { },
+        send() {
+            throw new Error(`Adapter unconfigured: ${reason}`);
+        },
+    });
+}
+function withTimeout(promise, ms, message) {
+    if (promise === undefined)
+        return Promise.resolve(undefined);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(message)), ms);
+        Promise.resolve(promise).then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+async function stopRecords(records, primaryError) {
+    const stack = new DisposeStack();
+    for (const record of records) {
+        if (record.stopped)
+            continue;
+        stack.add(async () => {
+            record.stopped = true;
+            record.open = false;
+            await record.endpoint.stop?.();
+        });
+    }
+    try {
+        await stack.dispose();
+    }
+    catch (stopError) {
+        if (primaryError !== undefined) {
+            throw new AggregateError([primaryError, stopError], 'Adapter prepare and Endpoint cleanup both failed', { cause: stopError });
+        }
+        throw stopError;
+    }
+}

package/lib/credentials.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Pick an explicit credential string.
+ * The first `typeof === 'string'` wins — including `""` — so an empty config
+ * field disables `process.env` fallbacks (kitchen-sink quiet boot).
+ */
+export declare function pickCredential(...candidates: unknown[]): string;

package/lib/credentials.js

@@ -0,0 +1,12 @@
+/**
+ * Pick an explicit credential string.
+ * The first `typeof === 'string'` wins — including `""` — so an empty config
+ * field disables `process.env` fallbacks (kitchen-sink quiet boot).
+ */
+export function pickCredential(...candidates) {
+    for (const value of candidates) {
+        if (typeof value === 'string')
+            return value;
+    }
+    return '';
+}

package/lib/definition.d.ts

@@ -0,0 +1,36 @@
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import type { CapabilityContext } from '@zhin.js/feature-kit';
+declare const adapterBrand: "zhin.adapter/1";
+export type AdapterCapability = 'inbound' | 'outbound';
+export interface EndpointSendRequest {
+    readonly target: string;
+    readonly payload: unknown;
+    readonly parent?: {
+        readonly type?: string;
+        readonly id?: string;
+        readonly name?: string;
+    };
+}
+export interface EndpointInstance<TResult = unknown> {
+    /** Allocates transport resources but must not admit inbound events yet. */
+    start?(): void | Promise<void>;
+    /** Opens admission after the candidate generation has committed. */
+    open?(): void;
+    /** Stops new inbound events while preserving in-flight work. */
+    close?(): void | Promise<void>;
+    /** Releases transport resources. Calls must be idempotent. */
+    stop?(): void | Promise<void>;
+    send?(request: EndpointSendRequest): TResult | Promise<TResult>;
+}
+export interface AdapterContext<TConfig = unknown> extends CapabilityContext<TConfig> {
+    readonly id: CapabilityId;
+    readonly name: string;
+}
+export interface AdapterDefinition<TConfig = unknown, TResult = unknown> {
+    readonly $feature: typeof adapterBrand;
+    readonly capabilities: readonly AdapterCapability[];
+    create(context: AdapterContext<TConfig>): EndpointInstance<TResult> | Promise<EndpointInstance<TResult>>;
+}
+export declare function defineAdapter<TConfig = unknown, TResult = unknown>(definition: Omit<AdapterDefinition<TConfig, TResult>, '$feature'>): Readonly<AdapterDefinition<TConfig, TResult>>;
+export declare function parseAdapterDefinition(value: unknown): AdapterDefinition;
+export {};

package/lib/definition.js

@@ -0,0 +1,31 @@
+const adapterBrand = 'zhin.adapter/1';
+export function defineAdapter(definition) {
+    if (typeof definition.create !== 'function') {
+        throw new TypeError('Adapter create must be a function');
+    }
+    const capabilities = [...new Set(definition.capabilities)];
+    if (capabilities.length === 0
+        || capabilities.some((value) => value !== 'inbound' && value !== 'outbound')) {
+        throw new TypeError('Adapter capabilities must contain inbound and/or outbound');
+    }
+    return Object.freeze({
+        ...definition,
+        $feature: adapterBrand,
+        capabilities: Object.freeze(capabilities),
+    });
+}
+export function parseAdapterDefinition(value) {
+    if (!value || typeof value !== 'object')
+        throw invalidAdapter();
+    const definition = value;
+    if (definition.$feature !== adapterBrand
+        || typeof definition.create !== 'function'
+        || !Array.isArray(definition.capabilities)
+        || definition.capabilities.length === 0
+        || definition.capabilities.some((capability) => capability !== 'inbound' && capability !== 'outbound'))
+        throw invalidAdapter();
+    return definition;
+}
+function invalidAdapter() {
+    return new TypeError('Adapter module must default-export defineAdapter(...)');
+}

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+export * from './adapter-index.js';
+export * from './credentials.js';
+export * from './definition.js';
+export * from './provider.js';
+export { default } from './provider.js';

package/lib/index.js

@@ -0,0 +1,5 @@
+export * from './adapter-index.js';
+export * from './credentials.js';
+export * from './definition.js';
+export * from './provider.js';
+export { default } from './provider.js';

package/lib/provider.d.ts

@@ -0,0 +1,5 @@
+import { AdapterIndex } from './adapter-index.js';
+export declare const adapterFeatureId: import("@zhin.js/plugin-runtime").FeatureId;
+declare const adapterFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<import("./definition.js").AdapterDefinition<unknown, unknown>, AdapterIndex>>;
+export { adapterFeature };
+export default adapterFeature;

package/lib/provider.js

@@ -0,0 +1,43 @@
+import { featureId } from '@zhin.js/plugin-runtime';
+import { defineFeatureProvider, typeScriptModules } from '@zhin.js/feature-kit';
+import { AdapterIndex } from './adapter-index.js';
+import { parseAdapterDefinition } from './definition.js';
+export const adapterFeatureId = featureId('zhin.adapter');
+const adapterFeature = defineFeatureProvider({
+    protocol: 1,
+    id: adapterFeatureId,
+    authoring: {
+        conventions: [typeScriptModules({
+                id: 'adapters-ts',
+                directory: 'adapters',
+            })],
+        validate: parseAdapterDefinition,
+    },
+    runtime: {
+        async project(slots, context) {
+            const index = await AdapterIndex.create(slots, context.snapshot);
+            let previousIndex;
+            return {
+                value: index,
+                dispose: () => index.stop(),
+                handoff: {
+                    quiescePrevious(previous) {
+                        previousIndex = previousAdapterIndex(previous);
+                        return previousIndex?.close();
+                    },
+                    activateNext: () => index.start(),
+                    deactivateNext: () => index.stop(),
+                    resumePrevious() {
+                        previousIndex?.open();
+                    },
+                    openNext: () => index.open(),
+                },
+            };
+        },
+    },
+});
+function previousAdapterIndex(snapshot) {
+    return snapshot.projections.get(adapterFeatureId);
+}
+export { adapterFeature };
+export default adapterFeature;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@zhin.js/adapter",
+  "version": "1.0.0",
+  "description": "Convention-based Adapter and Endpoint Feature for Zhin Plugin Runtime",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@zhin.js/logger": "1.0.74",
+    "@zhin.js/plugin-runtime": "1.0.0",
+    "@zhin.js/feature-kit": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "feature",
+    "entry": "./lib/provider.js",
+    "engine": "^1.0.0",
+    "featureApi": "1.0.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/im/adapter"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "license": "MIT",
+  "private": false,
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "vitest run --root ../../.. packages/im/adapter/tests"
+  }
+}

package/src/adapter-index.ts

@@ -0,0 +1,467 @@
+import {
+  DisposeStack,
+  type CapabilityId,
+  type CapabilitySlot,
+  type PluginId,
+  type RuntimeSnapshot,
+} from '@zhin.js/plugin-runtime';
+import { createCapabilityContext } from '@zhin.js/feature-kit';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import type {
+  AdapterCapability,
+  AdapterDefinition,
+  EndpointInstance,
+  EndpointSendRequest,
+} from './definition.js';
+
+const logger = getLogger('Adapter');
+
+export interface AdapterDescriptor {
+  readonly id: CapabilityId;
+  readonly owner: PluginId;
+  readonly name: string;
+  readonly source: string;
+  readonly capabilities: readonly AdapterCapability[];
+}
+
+/** Console / Host-facing endpoint row (connected = admission open). */
+export interface AdapterEndpointSummary extends AdapterDescriptor {
+  readonly connected: boolean;
+  readonly status: 'online' | 'offline';
+  readonly phase: AdapterEndpointPhase;
+}
+
+export type AdapterEndpointPhase =
+  'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
+
+interface AdapterRecord extends AdapterDescriptor {
+  readonly endpoint: EndpointInstance;
+  readonly unconfigured: boolean;
+  started: boolean;
+  open: boolean;
+  stopped: boolean;
+  /** Start rejected or was given up on — distinguishes 'failed' from 'unconfigured'. */
+  failed: boolean;
+  /** start() was invoked at least once (may still be in flight). */
+  startAttempted: boolean;
+}
+
+export class AdapterIndex {
+  readonly $projection = 'zhin.adapter-index/1' as const;
+  readonly #records = new Map<CapabilityId, AdapterRecord>();
+  readonly #order: readonly AdapterRecord[];
+  /** True after `open()` until `close()` / `stop()` — late starts may open themselves. */
+  #admissionOpen = false;
+  readonly #startTimeoutMs: number;
+  /** Final give-up budget for deferred starts (never-settling start promises). */
+  readonly #deferredGiveUpMs: number;
+
+  private constructor(
+    records: readonly AdapterRecord[],
+    startTimeoutMs: number,
+    deferredGiveUpMs: number,
+  ) {
+    this.#order = Object.freeze([...records]);
+    this.#startTimeoutMs = startTimeoutMs;
+    this.#deferredGiveUpMs = deferredGiveUpMs;
+    for (const record of records) this.#records.set(record.id, record);
+  }
+
+  static async create(
+    slots: readonly Readonly<CapabilitySlot<AdapterDefinition>>[],
+    snapshot: RuntimeSnapshot,
+    options: {
+      readonly startTimeoutMs?: number;
+      readonly deferredGiveUpMs?: number;
+    } = {},
+  ): Promise<AdapterIndex> {
+    const records: AdapterRecord[] = [];
+    const unconfigured: string[] = [];
+    try {
+      for (const slot of [...slots].sort((left, right) => left.id.localeCompare(right.id))) {
+        const endpoint = await createEndpointSoft(slot, snapshot);
+        if (endpoint.unconfigured) unconfigured.push(slot.localName);
+        records.push({
+          id: slot.id,
+          owner: slot.owner,
+          name: slot.localName,
+          source: slot.source,
+          capabilities: slot.definition.capabilities,
+          endpoint: endpoint.instance,
+          unconfigured: endpoint.unconfigured,
+          started: false,
+          open: false,
+          failed: false,
+          startAttempted: false,
+          // Unconfigured stubs skip start/open so kitchen-sink Roots stay quiet.
+          stopped: endpoint.unconfigured,
+        });
+      }
+      if (unconfigured.length > 0) {
+        logger.info(formatCompact({
+          op: 'adapters_unconfigured',
+          count: unconfigured.length,
+          names: unconfigured.join(','),
+        }));
+      }
+      return new AdapterIndex(
+        records,
+        options.startTimeoutMs ?? 3_000,
+        options.deferredGiveUpMs ?? 60_000,
+      );
+    } catch (error) {
+      await stopRecords(records, error);
+      throw error;
+    }
+  }
+
+  list(): readonly AdapterDescriptor[] {
+    return this.#order.map(({ endpoint: _endpoint, unconfigured: _unconfigured,
+      started: _started, open: _open, stopped: _stopped, failed: _failed,
+      startAttempted: _startAttempted, ...descriptor }) => Object.freeze(descriptor));
+  }
+
+  /** Endpoint rows for Console `endpoint.list` / `endpoint.info`. */
+  describe(): readonly AdapterEndpointSummary[] {
+    return Object.freeze(this.#order.map((record) => Object.freeze({
+      id: record.id,
+      owner: record.owner,
+      // Console 展示用 live name（如 ICQQ uin、sandbox bot 名），缺省回退 slot localName
+      name: endpointLiveName(record.endpoint) ?? record.name,
+      source: record.source,
+      capabilities: record.capabilities,
+      connected: record.open && !record.stopped,
+      status: record.open && !record.stopped ? 'online' as const : 'offline' as const,
+      phase: endpointPhase(record),
+    })));
+  }
+
+  /**
+   * Resolve a Console `$adapter` + `$endpoint` pair to a capability id.
+   * Matches local name, capability id, or owner path segments.
+   */
+  resolve(adapter: string, endpointId: string): CapabilityId | undefined {
+    const matches = this.#order.filter((record) =>
+      matchesEndpoint(record, adapter, endpointId));
+    if (matches.length === 1) return matches[0]?.id;
+    if (matches.length === 0) return undefined;
+    // Prefer exact localName === endpointId when ambiguous.
+    const exact = matches.find((record) => record.name === endpointId);
+    return exact?.id ?? matches[0]?.id;
+  }
+
+  /**
+   * Resolve a live EndpointInstance for Host-side side channels (reactions, etc.).
+   */
+  instance(adapter: string, endpointId: string): EndpointInstance | undefined {
+    const id = this.resolve(adapter, endpointId);
+    if (!id) return undefined;
+    return this.#records.get(id)?.endpoint;
+  }
+
+  owner(id: CapabilityId): PluginId {
+    const record = this.#records.get(id);
+    if (!record) throw new Error(`Unknown Adapter Endpoint: ${id}`);
+    return record.owner;
+  }
+
+  async start(): Promise<void> {
+    // Soft-start in parallel with a short wait so kitchen-sink Roots do not
+    // stall generation. Configured platforms that need longer (QQ auth, Slack
+    // socket, GitHub verify) stay in-flight instead of being stop()'d mid-connect.
+    const startTimeoutMs = this.#startTimeoutMs;
+    await Promise.all(this.#order.map(async (record) => {
+      if (record.started || record.stopped) return;
+      record.startAttempted = true;
+      const startPromise = (async () => record.endpoint.start?.())();
+      try {
+        await withTimeout(
+          startPromise,
+          startTimeoutMs,
+          `Adapter start timed out after ${startTimeoutMs}ms`,
+        );
+        if (record.stopped) return;
+        record.started = true;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('timed out after')) {
+          logger.info(formatCompact({
+            op: 'adapter_start_deferred',
+            id: record.id,
+            name: record.name,
+            waitMs: startTimeoutMs,
+          }));
+          // Final backstop: a deferred start promise that never settles must
+          // not keep the Endpoint in limbo forever.
+          const giveUp = setTimeout(() => {
+            if (record.stopped || record.started) return;
+            record.stopped = true;
+            record.failed = true;
+            // Swallow a late rejection so it does not become unhandled.
+            void startPromise.catch(() => undefined);
+            logger.warn(formatCompact({
+              op: 'adapter_start_give_up',
+              id: record.id,
+              name: record.name,
+              waitMs: this.#deferredGiveUpMs,
+            }));
+          }, this.#deferredGiveUpMs);
+          giveUp.unref?.();
+          void startPromise.then(
+            () => {
+              clearTimeout(giveUp);
+              if (record.stopped || record.started) return;
+              record.started = true;
+              if (this.#admissionOpen && !record.open) {
+                try {
+                  record.endpoint.open?.();
+                  record.open = true;
+                } catch (openError) {
+                  logger.warn(formatCompact({
+                    op: 'adapter_open_after_deferred_fail',
+                    id: record.id,
+                    name: record.name,
+                    error: openError instanceof Error ? openError.message : String(openError),
+                  }));
+                }
+              }
+            },
+            (startError) => {
+              clearTimeout(giveUp);
+              if (record.stopped) return;
+              record.stopped = true;
+              record.failed = true;
+              logger.warn(formatCompact({
+                op: 'adapter_start_soft_fail',
+                id: record.id,
+                name: record.name,
+                error: startError instanceof Error ? startError.message : String(startError),
+                stack: startError instanceof Error ? startError.stack : undefined,
+              }));
+            },
+          );
+          return;
+        }
+        record.stopped = true;
+        record.failed = true;
+        void startPromise.catch(() => undefined);
+        // Startup connect failures are logged once here (with stack); Endpoint
+        // implementations must NOT re-log them at error level.
+        logger.warn(formatCompact({
+          op: 'adapter_start_soft_fail',
+          id: record.id,
+          name: record.name,
+          error: message,
+          stack: error instanceof Error ? error.stack : undefined,
+        }));
+        // No endpoint.stop() here: adapter Endpoints self-stop in their start()
+        // catch by convention (verified across icqq/qq/slack/… endpoints).
+      }
+    }));
+  }
+
+  open(): void {
+    this.#admissionOpen = true;
+    const errors: unknown[] = [];
+    for (const record of this.#order) {
+      if (!record.started || record.open || record.stopped) continue;
+      try {
+        record.endpoint.open?.();
+        record.open = true;
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length > 0) throw new AggregateError(errors, 'Adapter Endpoint open failed');
+  }
+
+  async close(): Promise<void> {
+    this.#admissionOpen = false;
+    const stack = new DisposeStack();
+    for (const record of this.#order) {
+      if (!record.open || record.stopped) continue;
+      stack.add(async () => {
+        await record.endpoint.close?.();
+        record.open = false;
+      });
+    }
+    await stack.dispose();
+  }
+
+  async stop(): Promise<void> {
+    const stack = new DisposeStack();
+    // DisposeStack unwinds in reverse: admission closes before transports stop,
+    // and a close failure cannot skip transport cleanup.
+    stack.add(() => stopRecords(this.#order));
+    stack.add(() => this.close());
+    await stack.dispose();
+  }
+
+  async send(id: CapabilityId, request: EndpointSendRequest): Promise<unknown> {
+    const record = this.#records.get(id);
+    if (!record) throw new Error(`Unknown Adapter Endpoint: ${id}`);
+    if (!record.capabilities.includes('outbound') || !record.endpoint.send) {
+      throw new Error(`Adapter Endpoint does not support outbound: ${id}`);
+    }
+    if (!record.started || record.stopped) {
+      throw new Error(`Adapter Endpoint is not active: ${id}`);
+    }
+    return record.endpoint.send(request);
+  }
+}
+
+export function isAdapterIndex(value: unknown): value is AdapterIndex {
+  return !!value && typeof value === 'object'
+    && (value as { readonly $projection?: unknown }).$projection === 'zhin.adapter-index/1';
+}
+
+function matchesEndpoint(
+  record: AdapterRecord,
+  adapter: string,
+  endpointId: string,
+): boolean {
+  const adapterOk = record.name === adapter
+    || record.id === adapter
+    || record.id.endsWith(`/${adapter}`)
+    || record.owner === adapter
+    || record.owner.endsWith(`/${adapter}`);
+  // Live EndpointInstance.name is the bot runtime id (e.g. ICQQ uin). Host /
+  // activity-feedback resolve with that id; slot.localName alone is not enough
+  // when multiple plugin instances share localName "icqq".
+  const liveName = endpointLiveName(record.endpoint);
+  const endpointOk = record.name === endpointId
+    || record.id === endpointId
+    || record.id.endsWith(`/${endpointId}`)
+    || (liveName !== undefined && liveName === endpointId);
+  return adapterOk && endpointOk;
+}
+
+function endpointLiveName(endpoint: EndpointInstance): string | undefined {
+  const name = (endpoint as { readonly name?: unknown }).name;
+  return typeof name === 'string' && name.length > 0 ? name : undefined;
+}
+
+function endpointPhase(record: AdapterRecord): AdapterEndpointPhase {
+  if (record.unconfigured) return 'unconfigured';
+  if (record.failed) return 'failed';
+  if (record.open && !record.stopped) return 'online';
+  if (record.startAttempted) return 'starting';
+  return 'pending';
+}
+
+function assertEndpoint(value: unknown, id: CapabilityId): asserts value is EndpointInstance {
+  if (!value || typeof value !== 'object') {
+    throw new TypeError(`Adapter ${id} create() must return an Endpoint instance`);
+  }
+}
+
+/**
+ * Adapter `resolveXxxConfig` helpers report missing config/credentials as
+ * TypeError("… requires …") by convention; only those are expected failures.
+ */
+function isUnconfiguredError(error: unknown): boolean {
+  return (
+    error instanceof TypeError
+    && /requires|not configured|missing|未配置|缺少/i.test(error.message)
+  );
+}
+
+async function createEndpointSoft(
+  slot: Readonly<CapabilitySlot<AdapterDefinition>>,
+  snapshot: RuntimeSnapshot,
+): Promise<{ readonly instance: EndpointInstance; readonly unconfigured: boolean }> {
+  let endpoint: unknown;
+  try {
+    endpoint = await slot.definition.create(
+      Object.freeze({
+        ...createCapabilityContext(snapshot, slot.owner),
+        id: slot.id,
+        name: slot.localName,
+      }),
+    );
+  } catch (error) {
+    // Missing config / credentials: degrade to an inert stub so the rest of
+    // the generation still boots. Anything else (network failures, bugs in
+    // create()) is unexpected — keep the stub but surface a warning instead
+    // of silently swallowing it at debug level.
+    const message = error instanceof Error ? error.message : String(error);
+    const log = isUnconfiguredError(error) ? logger.debug.bind(logger) : logger.warn.bind(logger);
+    log(formatCompact({
+      op: 'adapter_create_soft_fail',
+      id: slot.id,
+      name: slot.localName,
+      error: message,
+    }));
+    return {
+      instance: createUnconfiguredEndpoint(message),
+      unconfigured: true,
+    };
+  }
+  // Programming errors (create() did not return an Endpoint) must surface:
+  // they propagate to AdapterIndex.create's catch, which disposes the records
+  // created so far instead of hiding the bug behind an unconfigured stub.
+  assertEndpoint(endpoint, slot.id);
+  return { instance: endpoint, unconfigured: false };
+}
+
+function createUnconfiguredEndpoint(reason: string): EndpointInstance {
+  return Object.freeze({
+    start() {
+      throw new Error(`Adapter unconfigured: ${reason}`);
+    },
+    open() {},
+    close() {},
+    stop() {},
+    send() {
+      throw new Error(`Adapter unconfigured: ${reason}`);
+    },
+  });
+}
+
+function withTimeout<T>(
+  promise: Promise<T> | T | undefined,
+  ms: number,
+  message: string,
+): Promise<T | undefined> {
+  if (promise === undefined) return Promise.resolve(undefined);
+  return new Promise<T | undefined>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), ms);
+    Promise.resolve(promise).then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+async function stopRecords(
+  records: readonly AdapterRecord[],
+  primaryError?: unknown,
+): Promise<void> {
+  const stack = new DisposeStack();
+  for (const record of records) {
+    if (record.stopped) continue;
+    stack.add(async () => {
+      record.stopped = true;
+      record.open = false;
+      await record.endpoint.stop?.();
+    });
+  }
+  try {
+    await stack.dispose();
+  } catch (stopError) {
+    if (primaryError !== undefined) {
+      throw new AggregateError(
+        [primaryError, stopError],
+        'Adapter prepare and Endpoint cleanup both failed',
+        { cause: stopError },
+      );
+    }
+    throw stopError;
+  }
+}

package/src/credentials.ts

@@ -0,0 +1,11 @@
+/**
+ * Pick an explicit credential string.
+ * The first `typeof === 'string'` wins — including `""` — so an empty config
+ * field disables `process.env` fallbacks (kitchen-sink quiet boot).
+ */
+export function pickCredential(...candidates: unknown[]): string {
+  for (const value of candidates) {
+    if (typeof value === 'string') return value;
+  }
+  return '';
+}

package/src/definition.ts

@@ -0,0 +1,76 @@
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import type { CapabilityContext } from '@zhin.js/feature-kit';
+
+const adapterBrand = 'zhin.adapter/1' as const;
+
+export type AdapterCapability = 'inbound' | 'outbound';
+
+export interface EndpointSendRequest {
+  readonly target: string;
+  readonly payload: unknown;
+  readonly parent?: { readonly type?: string; readonly id?: string; readonly name?: string };
+}
+
+export interface EndpointInstance<TResult = unknown> {
+  /** Allocates transport resources but must not admit inbound events yet. */
+  start?(): void | Promise<void>;
+  /** Opens admission after the candidate generation has committed. */
+  open?(): void;
+  /** Stops new inbound events while preserving in-flight work. */
+  close?(): void | Promise<void>;
+  /** Releases transport resources. Calls must be idempotent. */
+  stop?(): void | Promise<void>;
+  send?(request: EndpointSendRequest): TResult | Promise<TResult>;
+}
+
+export interface AdapterContext<TConfig = unknown> extends CapabilityContext<TConfig> {
+  readonly id: CapabilityId;
+  readonly name: string;
+}
+
+export interface AdapterDefinition<TConfig = unknown, TResult = unknown> {
+  readonly $feature: typeof adapterBrand;
+  readonly capabilities: readonly AdapterCapability[];
+  create(
+    context: AdapterContext<TConfig>,
+  ): EndpointInstance<TResult> | Promise<EndpointInstance<TResult>>;
+}
+
+export function defineAdapter<TConfig = unknown, TResult = unknown>(
+  definition: Omit<AdapterDefinition<TConfig, TResult>, '$feature'>,
+): Readonly<AdapterDefinition<TConfig, TResult>> {
+  if (typeof definition.create !== 'function') {
+    throw new TypeError('Adapter create must be a function');
+  }
+  const capabilities = [...new Set(definition.capabilities)];
+  if (
+    capabilities.length === 0
+    || capabilities.some((value) => value !== 'inbound' && value !== 'outbound')
+  ) {
+    throw new TypeError('Adapter capabilities must contain inbound and/or outbound');
+  }
+  return Object.freeze({
+    ...definition,
+    $feature: adapterBrand,
+    capabilities: Object.freeze(capabilities),
+  });
+}
+
+export function parseAdapterDefinition(value: unknown): AdapterDefinition {
+  if (!value || typeof value !== 'object') throw invalidAdapter();
+  const definition = value as Partial<AdapterDefinition>;
+  if (
+    definition.$feature !== adapterBrand
+    || typeof definition.create !== 'function'
+    || !Array.isArray(definition.capabilities)
+    || definition.capabilities.length === 0
+    || definition.capabilities.some(
+      (capability) => capability !== 'inbound' && capability !== 'outbound',
+    )
+  ) throw invalidAdapter();
+  return definition as AdapterDefinition;
+}
+
+function invalidAdapter(): TypeError {
+  return new TypeError('Adapter module must default-export defineAdapter(...)');
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './adapter-index.js';
+export * from './credentials.js';
+export * from './definition.js';
+export * from './provider.js';
+export { default } from './provider.js';

package/src/provider.ts

@@ -0,0 +1,47 @@
+import { featureId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { defineFeatureProvider, typeScriptModules } from '@zhin.js/feature-kit';
+import { AdapterIndex } from './adapter-index.js';
+import { parseAdapterDefinition } from './definition.js';
+
+export const adapterFeatureId = featureId('zhin.adapter');
+
+const adapterFeature = defineFeatureProvider({
+  protocol: 1,
+  id: adapterFeatureId,
+  authoring: {
+    conventions: [typeScriptModules({
+      id: 'adapters-ts',
+      directory: 'adapters',
+    })],
+    validate: parseAdapterDefinition,
+  },
+  runtime: {
+    async project(slots, context) {
+      const index = await AdapterIndex.create(slots, context.snapshot);
+      let previousIndex: AdapterIndex | undefined;
+      return {
+        value: index,
+        dispose: () => index.stop(),
+        handoff: {
+          quiescePrevious(previous) {
+            previousIndex = previousAdapterIndex(previous);
+            return previousIndex?.close();
+          },
+          activateNext: () => index.start(),
+          deactivateNext: () => index.stop(),
+          resumePrevious() {
+            previousIndex?.open();
+          },
+          openNext: () => index.open(),
+        },
+      };
+    },
+  },
+});
+
+function previousAdapterIndex(snapshot: RuntimeSnapshot): AdapterIndex | undefined {
+  return snapshot.projections.get(adapterFeatureId) as AdapterIndex | undefined;
+}
+
+export { adapterFeature };
+export default adapterFeature;