@cjhyy/code-shell-chat 0.8.0

package/dist/attachments.d.ts

@@ -0,0 +1,13 @@
+import type { ChatAttachment } from "./channel.js";
+import type { PetChatInputAttachment } from "./protocol.js";
+export declare const DEFAULT_MAX_CHAT_ATTACHMENTS = 4;
+export declare const DEFAULT_MAX_CHAT_ATTACHMENT_BYTES: number;
+export declare const DEFAULT_MAX_CHAT_ATTACHMENTS_TOTAL_BYTES: number;
+export interface MaterializeChatAttachmentsOptions {
+    maxAttachments?: number;
+    maxAttachmentBytes?: number;
+    maxTotalBytes?: number;
+    timeoutMs?: number;
+}
+/** Fetch lazy channel media under bounded count, per-file, total, and time limits. */
+export declare function materializeChatAttachments(attachments: readonly ChatAttachment[] | undefined, options?: MaterializeChatAttachmentsOptions): Promise<PetChatInputAttachment[]>;

package/dist/attachments.js

@@ -0,0 +1,74 @@
+export const DEFAULT_MAX_CHAT_ATTACHMENTS = 4;
+export const DEFAULT_MAX_CHAT_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+export const DEFAULT_MAX_CHAT_ATTACHMENTS_TOTAL_BYTES = 20 * 1024 * 1024;
+/** Fetch lazy channel media under bounded count, per-file, total, and time limits. */
+export async function materializeChatAttachments(attachments, options = {}) {
+    const input = attachments ?? [];
+    const maxAttachments = options.maxAttachments ?? DEFAULT_MAX_CHAT_ATTACHMENTS;
+    const maxAttachmentBytes = options.maxAttachmentBytes ?? DEFAULT_MAX_CHAT_ATTACHMENT_BYTES;
+    const maxTotalBytes = options.maxTotalBytes ?? DEFAULT_MAX_CHAT_ATTACHMENTS_TOTAL_BYTES;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    if (input.length > maxAttachments) {
+        throw new Error(`单条消息最多接收 ${maxAttachments} 个附件`);
+    }
+    const seen = new Set();
+    const output = [];
+    let total = 0;
+    for (const attachment of input) {
+        if (!attachment.id?.trim() || seen.has(attachment.id)) {
+            throw new Error("附件 ID 为空或重复");
+        }
+        seen.add(attachment.id);
+        if (attachment.size !== undefined &&
+            (!Number.isSafeInteger(attachment.size) ||
+                attachment.size < 0 ||
+                attachment.size > maxAttachmentBytes)) {
+            throw new Error(`附件 ${attachment.name ?? attachment.id} 超过大小限制`);
+        }
+        const bytes = new Uint8Array(await attachment.load(AbortSignal.timeout(timeoutMs)));
+        if (bytes.byteLength > maxAttachmentBytes) {
+            throw new Error(`附件 ${attachment.name ?? attachment.id} 超过大小限制`);
+        }
+        if (attachment.size !== undefined && attachment.size !== bytes.byteLength) {
+            throw new Error(`附件 ${attachment.name ?? attachment.id} 实际大小与声明不一致`);
+        }
+        total += bytes.byteLength;
+        if (total > maxTotalBytes)
+            throw new Error("附件总大小超过限制");
+        const mimeType = attachment.kind === "image"
+            ? (detectImageMime(bytes) ?? attachment.mimeType)
+            : attachment.mimeType;
+        output.push({
+            id: attachment.id,
+            kind: attachment.kind,
+            ...(attachment.name ? { name: attachment.name } : {}),
+            ...(mimeType ? { mimeType } : {}),
+            size: bytes.byteLength,
+            dataBase64: Buffer.from(bytes).toString("base64"),
+        });
+    }
+    return output;
+}
+function detectImageMime(bytes) {
+    if (bytes.length >= 8 &&
+        bytes[0] === 0x89 &&
+        bytes[1] === 0x50 &&
+        bytes[2] === 0x4e &&
+        bytes[3] === 0x47 &&
+        bytes[4] === 0x0d &&
+        bytes[5] === 0x0a &&
+        bytes[6] === 0x1a &&
+        bytes[7] === 0x0a) {
+        return "image/png";
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+        return "image/jpeg";
+    }
+    const ascii = (start, end) => String.fromCharCode(...bytes.subarray(start, end));
+    if (bytes.length >= 6 && ["GIF87a", "GIF89a"].includes(ascii(0, 6)))
+        return "image/gif";
+    if (bytes.length >= 12 && ascii(0, 4) === "RIFF" && ascii(8, 12) === "WEBP") {
+        return "image/webp";
+    }
+    return undefined;
+}

package/dist/channel.d.ts

@@ -0,0 +1,112 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export type ChatAttachmentKind = "image" | "file" | "audio" | "video";
+export type ChannelButtonCapability = "native" | "link";
+/**
+ * JSON-safe adapter contract shared with the Gateway and Desktop/Pet bridge.
+ * Capabilities describe what this implementation actually supports, not every
+ * feature offered by the upstream platform.
+ */
+export interface ChannelCapabilities {
+    inbound: {
+        text: true;
+        attachments: readonly ChatAttachmentKind[];
+    };
+    outbound: {
+        text: true;
+        /**
+         * Whether the adapter supports an owner-addressed send outside the current
+         * reply call. Platform prerequisites may still apply; for example WeChat
+         * needs a persisted inbound context token and exposes dynamic readiness in
+         * the Desktop status instead of pretending tokenless push is guaranteed.
+         */
+        proactive: boolean;
+        /** Whether send() works on a fresh adapter without run() being active. */
+        direct: boolean;
+        /** Maximum complete GatewayReply text before transport-safe chunking. */
+        maxTextLength?: number;
+        /** Native interactive button, or a normal labelled URL rendered in text/markdown. */
+        button: ChannelButtonCapability;
+        attachments: readonly ChatAttachmentKind[];
+        maxAttachments?: number;
+        maxAttachmentBytes?: number;
+    };
+}
+/** Built-in adapter capability matrix; keep this aligned with adapter send/ingress tests. */
+export declare const BUILTIN_CHANNEL_CAPABILITIES: {
+    readonly telegram: ChannelCapabilities;
+    readonly discord: ChannelCapabilities;
+    readonly slack: ChannelCapabilities;
+    readonly lark: ChannelCapabilities;
+    readonly dingtalk: ChannelCapabilities;
+    readonly wecom: ChannelCapabilities;
+    readonly wechat: ChannelCapabilities;
+    readonly matrix: ChannelCapabilities;
+    readonly mattermost: ChannelCapabilities;
+    readonly line: ChannelCapabilities;
+    readonly whatsapp: ChannelCapabilities;
+    readonly teams: ChannelCapabilities;
+};
+/**
+ * Lazy inbound attachment. Adapters expose metadata first; bytes are only
+ * fetched after allowlist middleware has accepted the sender.
+ */
+export interface ChatAttachment {
+    id: string;
+    kind: ChatAttachmentKind;
+    name?: string;
+    mimeType?: string;
+    size?: number;
+    load(signal?: AbortSignal): Promise<Uint8Array>;
+}
+export interface ChannelMessage {
+    channel: string;
+    target: string;
+    senderId: string;
+    text: string;
+    attachments?: readonly ChatAttachment[];
+    messageId?: string;
+    threadId?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}
+export interface OutgoingMessage {
+    text: string;
+    title?: string;
+    button?: {
+        text: string;
+        url: string;
+    };
+    /** Materialized outbound media bytes. Adapters may support a bounded subset. */
+    attachments?: readonly OutgoingAttachment[];
+}
+export interface OutgoingAttachment {
+    kind: ChatAttachmentKind;
+    name: string;
+    mimeType: string;
+    data: Uint8Array;
+}
+export type ChannelMessageHandler = (message: ChannelMessage) => Promise<void>;
+export interface ChannelAdapter {
+    readonly channel: string;
+    readonly capabilities?: ChannelCapabilities;
+    /**
+     * True only when one visible platform request atomically publishes both the
+     * text and every attachment. Retry coordinators default to separate sends;
+     * optimistic combination would duplicate accepted text after a media error.
+     */
+    readonly combinesTextAndAttachmentsAtomically?: boolean;
+    /** @deprecated Use capabilities.outbound.attachments or supportsOutgoingAttachment(). */
+    readonly supportsOutgoingAttachments?: boolean;
+    run(handler: ChannelMessageHandler, signal: AbortSignal): Promise<void>;
+    send(target: string, message: OutgoingMessage): Promise<void>;
+}
+export declare function channelCapabilities(adapter: ChannelAdapter): ChannelCapabilities;
+export declare function supportsOutgoingAttachment(adapter: ChannelAdapter, kind: ChatAttachmentKind): boolean;
+export interface ChatCommandDefinition {
+    name: string;
+    description: string;
+}
+export interface WebhookChannelAdapter extends ChannelAdapter {
+    readonly webhookPath: string;
+    handleWebhook(request: IncomingMessage, response: ServerResponse, handler: ChannelMessageHandler, maxBodyBytes: number): Promise<void>;
+}
+export declare function isWebhookChannelAdapter(adapter: ChannelAdapter): adapter is WebhookChannelAdapter;

package/dist/channel.js

@@ -0,0 +1,60 @@
+const ALL_ATTACHMENT_KINDS = ["image", "file", "audio", "video"];
+const TEN_MIB = 10 * 1024 * 1024;
+function capabilities(button, inboundAttachments = [], outboundAttachments = [], options = {}) {
+    return {
+        inbound: { text: true, attachments: inboundAttachments },
+        outbound: {
+            text: true,
+            proactive: options.proactive ?? true,
+            direct: options.direct ?? false,
+            maxTextLength: options.maxTextLength ?? 8_000,
+            button,
+            attachments: outboundAttachments,
+            ...(outboundAttachments.length > 0
+                ? { maxAttachments: 4, maxAttachmentBytes: options.maxAttachmentBytes ?? TEN_MIB }
+                : {}),
+        },
+    };
+}
+/** Built-in adapter capability matrix; keep this aligned with adapter send/ingress tests. */
+export const BUILTIN_CHANNEL_CAPABILITIES = {
+    telegram: capabilities("native", ALL_ATTACHMENT_KINDS, ALL_ATTACHMENT_KINDS, { direct: true }),
+    discord: capabilities("native", ALL_ATTACHMENT_KINDS, ALL_ATTACHMENT_KINDS),
+    slack: capabilities("native", ALL_ATTACHMENT_KINDS, ALL_ATTACHMENT_KINDS, { direct: true }),
+    lark: capabilities("native", ALL_ATTACHMENT_KINDS, ALL_ATTACHMENT_KINDS, { direct: true }),
+    dingtalk: capabilities("native"),
+    wecom: capabilities("link", ["image", "file", "video"], ALL_ATTACHMENT_KINDS),
+    // A fresh adapter can reuse a persisted inbound context_token. Stale tokens
+    // are durably evicted; tokenless retry is best-effort, not a protocol promise.
+    wechat: capabilities("link", ALL_ATTACHMENT_KINDS, ALL_ATTACHMENT_KINDS, {
+        direct: true,
+    }),
+    matrix: capabilities("link", ALL_ATTACHMENT_KINDS, ALL_ATTACHMENT_KINDS, { direct: true }),
+    mattermost: capabilities("link", ALL_ATTACHMENT_KINDS, ALL_ATTACHMENT_KINDS, { direct: true }),
+    line: capabilities("native", ALL_ATTACHMENT_KINDS, [], { direct: true }),
+    whatsapp: capabilities("native", ALL_ATTACHMENT_KINDS, ALL_ATTACHMENT_KINDS, { direct: true }),
+    // Bot Framework supports inline data-URI pictures. General file/audio/video
+    // delivery needs a public URL or the Teams file-consent/Graph flow, neither
+    // of which this credential shape currently configures.
+    teams: capabilities("link", ALL_ATTACHMENT_KINDS, ["image"], {
+        maxAttachmentBytes: 1024 * 1024,
+    }),
+};
+const DEFAULT_CHANNEL_CAPABILITIES = capabilities("link");
+export function channelCapabilities(adapter) {
+    if (adapter.capabilities)
+        return adapter.capabilities;
+    // Preserve compatibility for third-party adapters built against the old
+    // boolean contract. Built-in adapters always publish the granular shape.
+    if (adapter.supportsOutgoingAttachments) {
+        return capabilities("link", [], ALL_ATTACHMENT_KINDS);
+    }
+    return DEFAULT_CHANNEL_CAPABILITIES;
+}
+export function supportsOutgoingAttachment(adapter, kind) {
+    return channelCapabilities(adapter).outbound.attachments.includes(kind);
+}
+export function isWebhookChannelAdapter(adapter) {
+    return ("webhookPath" in adapter &&
+        typeof adapter.webhookPath === "string");
+}

package/dist/chat-gateway.d.ts

@@ -0,0 +1,58 @@
+import type { ChannelAdapter, ChannelMessage, OutgoingMessage } from "./channel.js";
+import { type DeliveryQueueConfig } from "./delivery-queue.js";
+import { type WebhookIngressConfig } from "./webhook.js";
+export interface ChatContext {
+    readonly message: ChannelMessage;
+    readonly adapter: ChannelAdapter;
+    reply(message: OutgoingMessage): Promise<void>;
+}
+export type ChatMiddleware = (context: ChatContext, next: () => Promise<void>) => Promise<void>;
+export interface ChatGatewayOptions {
+    adapters: ChannelAdapter[];
+    webhook?: Partial<WebhookIngressConfig>;
+    delivery?: Partial<DeliveryQueueConfig>;
+    adapterRestart?: Partial<{
+        baseMs: number;
+        maxMs: number;
+    }>;
+    onError?: (error: unknown, message: ChannelMessage) => void;
+    onAdapterState?: (state: AdapterRuntimeState) => void;
+}
+export interface AdapterRuntimeState {
+    id: string;
+    channel: string;
+    state: "starting" | "running" | "backoff" | "stopped";
+    attempts: number;
+    error?: string;
+}
+export interface ChatAllowlistRule {
+    targetIds: Iterable<string>;
+    userIds?: Iterable<string>;
+}
+/**
+ * Transport-agnostic chat runtime. It owns channel lifecycles and webhook ingress,
+ * while application behavior is supplied entirely through middleware.
+ */
+export declare class ChatGateway {
+    private readonly middleware;
+    private readonly adapters;
+    private readonly webhook;
+    private readonly delivery;
+    private readonly adapterRestart;
+    private readonly onError;
+    private readonly onAdapterState?;
+    private readonly adapterStates;
+    private queue?;
+    private startedAt?;
+    constructor(options: ChatGatewayOptions);
+    use(middleware: ChatMiddleware): this;
+    dispatch(adapter: ChannelAdapter, message: ChannelMessage): Promise<void>;
+    run(signal: AbortSignal): Promise<void>;
+    healthSnapshot(): Record<string, unknown>;
+    private superviseAdapter;
+    private setAdapterState;
+}
+/** Deny-by-default allowlist middleware for multi-channel gateways. */
+export declare function createAllowlistMiddleware(rules: Readonly<Record<string, ChatAllowlistRule>>): ChatMiddleware;
+/** Fixed-window per-sender limiter; rejected messages never reach expensive middleware. */
+export declare function createRateLimitMiddleware(maxMessages: number, windowMs?: number, onLimited?: (message: ChannelMessage) => void): ChatMiddleware;

package/dist/chat-gateway.js

@@ -0,0 +1,232 @@
+import { isWebhookChannelAdapter } from "./channel.js";
+import { DeliveryQueue, UnroutableDeliveryError, } from "./delivery-queue.js";
+import { waitForAbort } from "./lifecycle.js";
+import { WebhookIngressServer, } from "./webhook.js";
+const DEFAULT_WEBHOOK_CONFIG = {
+    host: "127.0.0.1",
+    port: 8787,
+    maxBodyBytes: 1_048_576,
+    healthPath: "/healthz",
+    readyPath: "/readyz",
+    requestTimeoutMs: 15_000,
+};
+const DEFAULT_DELIVERY_CONFIG = {
+    maxPending: 1_000,
+    maxConcurrent: 4,
+    maxPerTarget: 1,
+    retryBaseMs: 1_000,
+    retryMaxMs: 30_000,
+    completedTtlMs: 7 * 24 * 60 * 60 * 1_000,
+};
+/**
+ * Transport-agnostic chat runtime. It owns channel lifecycles and webhook ingress,
+ * while application behavior is supplied entirely through middleware.
+ */
+export class ChatGateway {
+    middleware = [];
+    adapters;
+    webhook;
+    delivery;
+    adapterRestart;
+    onError;
+    onAdapterState;
+    adapterStates = new Map();
+    queue;
+    startedAt;
+    constructor(options) {
+        this.adapters = [...options.adapters];
+        this.webhook = { ...DEFAULT_WEBHOOK_CONFIG, ...options.webhook };
+        this.delivery = { ...DEFAULT_DELIVERY_CONFIG, ...options.delivery };
+        this.adapterRestart = {
+            baseMs: options.adapterRestart?.baseMs ?? 1_000,
+            maxMs: options.adapterRestart?.maxMs ?? 30_000,
+        };
+        this.onAdapterState = options.onAdapterState;
+        this.onError =
+            options.onError ??
+                ((error, message) => {
+                    console.error(`[chat] ${message.channel} message failed: ${error instanceof Error ? error.message : String(error)}`);
+                });
+    }
+    use(middleware) {
+        this.middleware.push(middleware);
+        return this;
+    }
+    async dispatch(adapter, message) {
+        if (message.channel !== adapter.channel) {
+            throw new Error(`Adapter ${adapter.channel} emitted a message for channel ${message.channel}`);
+        }
+        const context = {
+            message,
+            adapter,
+            reply: (outgoing) => adapter.send(message.target, outgoing),
+        };
+        let index = -1;
+        const next = async (position) => {
+            if (position <= index)
+                throw new Error("Chat middleware called next() more than once");
+            index = position;
+            const current = this.middleware[position];
+            if (current)
+                await current(context, () => next(position + 1));
+        };
+        await next(0);
+    }
+    async run(signal) {
+        if (this.startedAt)
+            throw new Error("ChatGateway is already running");
+        this.startedAt = Date.now();
+        const ownedAbort = new AbortController();
+        const stopOwned = () => ownedAbort.abort();
+        if (signal.aborted)
+            ownedAbort.abort();
+        else
+            signal.addEventListener("abort", stopOwned, { once: true });
+        const webhooks = [];
+        const adapterById = new Map();
+        // Key adapters by a per-channel ordinal (channel:0, channel:1, …) rather
+        // than the global array index. Delivery-queue records persist this id and
+        // are replayed on the next run; a global index would shift when an
+        // unrelated channel is removed from config, orphaning durable messages
+        // against an id that no longer maps to their adapter.
+        const perChannelCount = new Map();
+        for (const adapter of this.adapters) {
+            const ordinal = perChannelCount.get(adapter.channel) ?? 0;
+            perChannelCount.set(adapter.channel, ordinal + 1);
+            adapterById.set(`${adapter.channel}:${ordinal}`, adapter);
+        }
+        const queue = new DeliveryQueue(this.delivery, async (adapterId, message) => {
+            const adapter = adapterById.get(adapterId);
+            if (!adapter) {
+                // A durable record survived a config change that removed its adapter.
+                // Signal unroutable so the queue drops it instead of retrying forever.
+                throw new UnroutableDeliveryError(`Chat adapter no longer exists: ${adapterId}`);
+            }
+            await this.dispatch(adapter, message);
+        }, this.onError);
+        this.queue = queue;
+        await queue.start();
+        const runners = [];
+        for (const [adapterId, adapter] of adapterById) {
+            const handler = (message) => queue.enqueue(adapterId, message).then(() => undefined);
+            if (isWebhookChannelAdapter(adapter))
+                webhooks.push({ adapter, handler });
+            runners.push(this.superviseAdapter(adapterId, adapter, handler, ownedAbort.signal));
+        }
+        // Only bind the ingress host:port when a channel actually needs a webhook
+        // route. A polling-only config (e.g. Telegram/Discord) must not open an
+        // HTTP listener — doing so unexpectedly exposes a port and fails startup
+        // outright when that port is already taken.
+        if (webhooks.length > 0) {
+            runners.push(new WebhookIngressServer(this.webhook, webhooks, () => this.healthSnapshot()).run(ownedAbort.signal));
+        }
+        try {
+            await Promise.all(runners);
+        }
+        finally {
+            ownedAbort.abort();
+            queue.stop();
+            this.queue = undefined;
+            this.startedAt = undefined;
+            signal.removeEventListener("abort", stopOwned);
+        }
+    }
+    healthSnapshot() {
+        const adapters = [...this.adapterStates.values()];
+        return {
+            status: adapters.every(({ state }) => state === "running") ? "ready" : "degraded",
+            startedAt: this.startedAt,
+            adapters,
+            inbox: this.queue?.status() ?? { pending: 0, inFlight: 0, delayed: 0 },
+        };
+    }
+    async superviseAdapter(id, adapter, handler, signal) {
+        let attempts = 0;
+        while (!signal.aborted) {
+            this.setAdapterState({ id, channel: adapter.channel, state: "starting", attempts });
+            try {
+                this.setAdapterState({ id, channel: adapter.channel, state: "running", attempts });
+                await adapter.run(handler, signal);
+                if (signal.aborted)
+                    break;
+                throw new Error("adapter exited unexpectedly");
+            }
+            catch (error) {
+                if (signal.aborted)
+                    break;
+                attempts += 1;
+                const delay = Math.min(this.adapterRestart.maxMs, this.adapterRestart.baseMs * 2 ** Math.min(attempts - 1, 10));
+                this.setAdapterState({
+                    id,
+                    channel: adapter.channel,
+                    state: "backoff",
+                    attempts,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                await abortableDelay(delay, signal);
+            }
+        }
+        this.setAdapterState({ id, channel: adapter.channel, state: "stopped", attempts });
+    }
+    setAdapterState(state) {
+        this.adapterStates.set(state.id, state);
+        this.onAdapterState?.({ ...state });
+    }
+}
+/** Deny-by-default allowlist middleware for multi-channel gateways. */
+export function createAllowlistMiddleware(rules) {
+    const normalized = new Map(Object.entries(rules).map(([channel, rule]) => [
+        channel,
+        {
+            targets: new Set(rule.targetIds),
+            users: rule.userIds ? new Set(rule.userIds) : undefined,
+        },
+    ]));
+    return async ({ message }, next) => {
+        const rule = normalized.get(message.channel);
+        if (!rule?.targets.has(message.target))
+            return;
+        if (rule.users && rule.users.size > 0 && !rule.users.has(message.senderId))
+            return;
+        await next();
+    };
+}
+/** Fixed-window per-sender limiter; rejected messages never reach expensive middleware. */
+export function createRateLimitMiddleware(maxMessages, windowMs = 60_000, onLimited) {
+    if (!Number.isSafeInteger(maxMessages) || maxMessages <= 0 || windowMs <= 0) {
+        throw new Error("invalid chat rate limit");
+    }
+    const buckets = new Map();
+    return async ({ message }, next) => {
+        const now = Date.now();
+        const key = `${message.channel}\0${message.senderId}`;
+        let bucket = buckets.get(key);
+        if (!bucket || now - bucket.startedAt >= windowMs) {
+            bucket = { startedAt: now, count: 0 };
+            buckets.set(key, bucket);
+        }
+        if (bucket.count >= maxMessages) {
+            onLimited?.(message);
+            return;
+        }
+        bucket.count += 1;
+        if (buckets.size > 10_000) {
+            for (const [candidate, value] of buckets) {
+                if (now - value.startedAt >= windowMs)
+                    buckets.delete(candidate);
+            }
+        }
+        await next();
+    };
+}
+async function abortableDelay(ms, signal) {
+    if (signal.aborted)
+        return;
+    await Promise.race([
+        new Promise((resolve) => {
+            const timer = setTimeout(resolve, ms);
+            timer.unref?.();
+        }),
+        waitForAbort(signal),
+    ]);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};