@cjhyy/code-shell-chat 0.8.0

package/dist/mattermost.js

@@ -0,0 +1,170 @@
+import WebSocket from "ws";
+import { BUILTIN_CHANNEL_CAPABILITIES } from "./channel.js";
+import { dispatchSafely, formatOutgoingMarkdown } from "./lifecycle.js";
+import { mediaKind, outgoingAttachments, remoteAttachment, safeAttachmentName } from "./media.js";
+export class MattermostAdapter {
+    config;
+    fetchFn;
+    channel = "mattermost";
+    capabilities = BUILTIN_CHANNEL_CAPABILITIES.mattermost;
+    combinesTextAndAttachmentsAtomically = true;
+    constructor(config, fetchFn = fetch) {
+        this.config = config;
+        this.fetchFn = fetchFn;
+    }
+    async run(handler, signal) {
+        let retryMs = 1_000;
+        while (!signal.aborted) {
+            try {
+                await this.connect(handler, signal);
+                retryMs = 1_000;
+            }
+            catch {
+                if (signal.aborted)
+                    return;
+                await abortableDelay(retryMs, signal);
+                retryMs = Math.min(retryMs * 2, 30_000);
+            }
+        }
+    }
+    async send(target, message) {
+        const attachments = outgoingAttachments(message, this.capabilities.outbound.attachments);
+        const fileIds = [];
+        for (const attachment of attachments) {
+            const form = new FormData();
+            form.set("channel_id", target);
+            form.set("files", new Blob([new Uint8Array(attachment.data)], { type: attachment.mimeType }), safeAttachmentName(attachment.name));
+            const upload = await this.fetchFn(`${this.config.serverUrl}/api/v4/files`, {
+                method: "POST",
+                headers: { authorization: `Bearer ${this.config.botToken}` },
+                body: form,
+                signal: AbortSignal.timeout(30_000),
+            });
+            const uploadBody = (await upload.json().catch(() => ({})));
+            const id = uploadBody.file_infos?.[0]?.id;
+            if (!upload.ok || !id) {
+                throw new Error(uploadBody.message ?? `Mattermost 附件上传失败（HTTP ${upload.status}）`);
+            }
+            fileIds.push(id);
+        }
+        const response = await this.fetchFn(`${this.config.serverUrl}/api/v4/posts`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${this.config.botToken}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                channel_id: target,
+                message: formatOutgoingMarkdown(message.text, message.button),
+                ...(fileIds.length > 0 ? { file_ids: fileIds } : {}),
+            }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => ({})));
+            throw new Error(body.message ?? `Mattermost 发送失败（HTTP ${response.status}）`);
+        }
+    }
+    connect(handler, signal) {
+        return new Promise((resolve, reject) => {
+            const socket = new WebSocket(toWebSocketUrl(this.config.serverUrl));
+            let opened = false;
+            const abort = () => socket.close();
+            signal.addEventListener("abort", abort, { once: true });
+            socket.once("open", () => {
+                opened = true;
+                socket.send(JSON.stringify({
+                    seq: 1,
+                    action: "authentication_challenge",
+                    data: { token: this.config.botToken },
+                }));
+            });
+            socket.on("message", (raw) => this.onMessage(raw, handler, socket));
+            socket.once("error", (error) => {
+                if (!opened)
+                    reject(error);
+            });
+            socket.once("close", () => {
+                signal.removeEventListener("abort", abort);
+                resolve();
+            });
+        });
+    }
+    onMessage(raw, handler, socket) {
+        let event;
+        try {
+            event = JSON.parse(raw.toString());
+        }
+        catch {
+            return;
+        }
+        if (event.data?.error?.message) {
+            socket.close(1008, "authentication failed");
+            return;
+        }
+        if (event.event !== "posted" || !event.data?.post)
+            return;
+        let post;
+        try {
+            post =
+                typeof event.data.post === "string"
+                    ? JSON.parse(event.data.post)
+                    : event.data.post;
+        }
+        catch {
+            return;
+        }
+        if (!post.channel_id ||
+            !post.user_id ||
+            (!post.message && !post.file_ids?.length && !post.metadata?.files?.length) ||
+            post.user_id === this.config.botUserId) {
+            return;
+        }
+        const infos = post.metadata?.files ?? [];
+        const infoById = new Map(infos.flatMap((info) => (info.id ? [[info.id, info]] : [])));
+        const attachmentIds = post.file_ids?.length
+            ? post.file_ids
+            : infos.flatMap((info) => (info.id ? [info.id] : []));
+        const attachments = attachmentIds.map((id) => {
+            const info = infoById.get(id);
+            return remoteAttachment({
+                id,
+                kind: mediaKind(info?.mime_type, info?.name),
+                name: info?.name ?? `mattermost-${id}`,
+                mimeType: info?.mime_type,
+                size: info?.size,
+                url: `${this.config.serverUrl}/api/v4/files/${encodeURIComponent(id)}`,
+                headers: { authorization: `Bearer ${this.config.botToken}` },
+                fetch: this.fetchFn,
+                allowPrivateNetwork: true,
+            });
+        });
+        void dispatchSafely(handler, {
+            channel: this.channel,
+            target: post.channel_id,
+            senderId: post.user_id,
+            text: post.message ?? "",
+            ...(post.id ? { messageId: post.id } : {}),
+            ...(attachments.length > 0 ? { attachments } : {}),
+        });
+    }
+}
+function toWebSocketUrl(serverUrl) {
+    const url = new URL(serverUrl);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.pathname = `${url.pathname.replace(/\/$/, "")}/api/v4/websocket`;
+    return url.toString();
+}
+async function abortableDelay(ms, signal) {
+    if (signal.aborted)
+        return;
+    await new Promise((resolve) => {
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+        function done() {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        }
+    });
+}

package/dist/media.d.ts

@@ -0,0 +1,39 @@
+import type { ChatAttachment, ChatAttachmentKind, OutgoingAttachment, OutgoingMessage } from "./channel.js";
+export declare const MAX_CHANNEL_ATTACHMENTS = 4;
+export declare const MAX_CHANNEL_ATTACHMENT_BYTES: number;
+export interface RemoteAttachmentOptions {
+    id: string;
+    kind?: ChatAttachmentKind;
+    name?: string;
+    mimeType?: string;
+    size?: number;
+    url: string;
+    headers?: Readonly<Record<string, string>>;
+    fetch?: typeof fetch;
+    /** Only for an operator-configured self-hosted platform origin. */
+    allowPrivateNetwork?: boolean;
+}
+/** Infer the Pet/Gateway media kind from a trusted platform MIME or filename. */
+export declare function mediaKind(mimeType?: string, name?: string): ChatAttachmentKind;
+/** Create a lazy platform attachment; no network request occurs before load(). */
+export declare function remoteAttachment(options: RemoteAttachmentOptions): ChatAttachment;
+interface DownloadRemoteAttachmentOptions extends Pick<RequestInit, "headers" | "signal"> {
+    allowPrivateNetwork?: boolean;
+}
+/** Bounded streaming download shared by authenticated platform media URLs. */
+export declare function downloadRemoteAttachment(fetchFn: typeof fetch, url: string, init?: DownloadRemoteAttachmentOptions, maximum?: number): Promise<Uint8Array>;
+/** Validate adapter-facing media before any platform request is made. */
+export declare function outgoingAttachments(message: OutgoingMessage, supported: readonly ChatAttachmentKind[]): readonly OutgoingAttachment[];
+export declare function safeAttachmentName(value: string | undefined, fallback?: string): string;
+/**
+ * Resume a multi-request adapter send at the first unfinished visible step.
+ * DeliveryQueue retries the same cached OutgoingMessage object for Mimi turns,
+ * so this prevents a failed second attachment from duplicating earlier text.
+ * A failure while awaiting one platform call remains honestly at-least-once:
+ * the remote service may have accepted it without returning an acknowledgement.
+ */
+export declare class OutgoingDeliveryTracker {
+    private readonly plans;
+    run(message: OutgoingMessage, createSteps: () => readonly (() => Promise<void>)[] | Promise<readonly (() => Promise<void>)[]>): Promise<void>;
+}
+export {};

package/dist/media.js

@@ -0,0 +1,223 @@
+import { isIP } from "node:net";
+export const MAX_CHANNEL_ATTACHMENTS = 4;
+export const MAX_CHANNEL_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+/** Infer the Pet/Gateway media kind from a trusted platform MIME or filename. */
+export function mediaKind(mimeType, name) {
+    const normalized = mimeType?.toLowerCase().split(";", 1)[0]?.trim() ?? "";
+    if (normalized.startsWith("image/"))
+        return "image";
+    if (normalized.startsWith("audio/"))
+        return "audio";
+    if (normalized.startsWith("video/"))
+        return "video";
+    const extension = name?.toLowerCase().match(/\.([a-z0-9]{1,10})$/)?.[1];
+    if (extension &&
+        ["png", "jpg", "jpeg", "gif", "webp", "bmp", "tif", "tiff"].includes(extension)) {
+        return "image";
+    }
+    if (extension &&
+        ["mp3", "m4a", "aac", "wav", "ogg", "opus", "flac", "amr", "silk"].includes(extension)) {
+        return "audio";
+    }
+    if (extension && ["mp4", "mov", "webm", "mkv", "avi", "3gp"].includes(extension)) {
+        return "video";
+    }
+    return "file";
+}
+/** Create a lazy platform attachment; no network request occurs before load(). */
+export function remoteAttachment(options) {
+    const name = safeAttachmentName(options.name, options.id);
+    return {
+        id: options.id,
+        kind: options.kind ?? mediaKind(options.mimeType, name),
+        name,
+        ...(options.mimeType?.trim() ? { mimeType: options.mimeType.trim() } : {}),
+        ...(options.size !== undefined ? { size: options.size } : {}),
+        load: (signal) => downloadRemoteAttachment(options.fetch ?? fetch, options.url, {
+            ...(options.headers ? { headers: options.headers } : {}),
+            ...(signal ? { signal } : {}),
+            ...(options.allowPrivateNetwork ? { allowPrivateNetwork: true } : {}),
+        }),
+    };
+}
+/** Bounded streaming download shared by authenticated platform media URLs. */
+export async function downloadRemoteAttachment(fetchFn, url, init = {}, maximum = MAX_CHANNEL_ATTACHMENT_BYTES) {
+    const signal = init.signal
+        ? AbortSignal.any([init.signal, AbortSignal.timeout(30_000)])
+        : AbortSignal.timeout(30_000);
+    let currentUrl = url;
+    let currentHeaders = new Headers(init.headers);
+    let response;
+    for (let redirects = 0; redirects <= 5; redirects += 1) {
+        assertSafeMediaUrl(currentUrl, init.allowPrivateNetwork ?? false);
+        response = await fetchFn(currentUrl, {
+            method: "GET",
+            headers: currentHeaders,
+            signal,
+            redirect: "manual",
+        });
+        if (![301, 302, 303, 307, 308].includes(response.status))
+            break;
+        const location = response.headers.get("location");
+        if (!location || redirects === 5)
+            throw new Error("附件下载重定向无效");
+        const nextUrl = new URL(location, currentUrl);
+        if (nextUrl.origin !== new URL(currentUrl).origin) {
+            currentHeaders = new Headers(currentHeaders);
+            currentHeaders.delete("authorization");
+            currentHeaders.delete("cookie");
+            currentHeaders.delete("proxy-authorization");
+        }
+        currentUrl = nextUrl.toString();
+    }
+    if (!response)
+        throw new Error("附件下载失败");
+    if (!response.ok)
+        throw new Error(`附件下载失败（HTTP ${response.status}）`);
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > maximum)
+        throw new Error("附件超过大小限制");
+    if (!response.body) {
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        if (bytes.byteLength > maximum)
+            throw new Error("附件超过大小限制");
+        return bytes;
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maximum) {
+                await reader.cancel();
+                throw new Error("附件超过大小限制");
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const output = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return output;
+}
+function assertSafeMediaUrl(value, allowPrivateNetwork) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("附件下载地址无效");
+    }
+    if (url.protocol !== "https:" && !(allowPrivateNetwork && url.protocol === "http:")) {
+        throw new Error("附件下载地址必须使用 HTTPS");
+    }
+    if (allowPrivateNetwork)
+        return;
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/gu, "");
+    if (host === "localhost" ||
+        host.endsWith(".localhost") ||
+        host.endsWith(".local") ||
+        host.endsWith(".internal") ||
+        isPrivateIpLiteral(host)) {
+        throw new Error("附件下载地址不能指向本机或私有网络");
+    }
+}
+function isPrivateIpLiteral(host) {
+    const family = isIP(host);
+    if (family === 4) {
+        const [a = 0, b = 0] = host.split(".").map(Number);
+        return (a === 0 ||
+            a === 10 ||
+            a === 127 ||
+            (a === 169 && b === 254) ||
+            (a === 172 && b >= 16 && b <= 31) ||
+            (a === 192 && b === 168) ||
+            a >= 224);
+    }
+    if (family === 6) {
+        const normalized = host.toLowerCase();
+        return (normalized === "::" ||
+            normalized === "::1" ||
+            normalized.startsWith("fc") ||
+            normalized.startsWith("fd") ||
+            normalized.startsWith("fe8") ||
+            normalized.startsWith("fe9") ||
+            normalized.startsWith("fea") ||
+            normalized.startsWith("feb") ||
+            normalized.startsWith("::ffff:127.") ||
+            normalized.startsWith("::ffff:10.") ||
+            normalized.startsWith("::ffff:192.168."));
+    }
+    return false;
+}
+/** Validate adapter-facing media before any platform request is made. */
+export function outgoingAttachments(message, supported) {
+    const attachments = message.attachments ?? [];
+    if (attachments.length > MAX_CHANNEL_ATTACHMENTS) {
+        throw new Error(`单条消息最多发送 ${MAX_CHANNEL_ATTACHMENTS} 个附件`);
+    }
+    for (const attachment of attachments) {
+        if (!supported.includes(attachment.kind)) {
+            throw new Error(`当前渠道不支持发送 ${attachment.kind} 附件`);
+        }
+        if (!(attachment.data instanceof Uint8Array) ||
+            attachment.data.byteLength < 1 ||
+            attachment.data.byteLength > MAX_CHANNEL_ATTACHMENT_BYTES) {
+            throw new Error(`附件 ${attachment.name || "attachment"} 的大小不受支持`);
+        }
+        if (!attachment.mimeType.trim())
+            throw new Error("附件 MIME 类型不能为空");
+        if (attachment.kind === "image" && !attachment.mimeType.startsWith("image/")) {
+            throw new Error(`图片 ${attachment.name} 的 MIME 类型无效`);
+        }
+    }
+    return attachments;
+}
+export function safeAttachmentName(value, fallback = "attachment") {
+    const normalized = (value ?? "")
+        .replaceAll("\\", "/")
+        .split("/")
+        .at(-1)
+        ?.replace(/[\u0000-\u001f\u007f]/gu, "")
+        .trim()
+        .slice(0, 255);
+    return (normalized || fallback.replace(/[\u0000-\u001f\u007f]/gu, "").slice(0, 255) || "attachment");
+}
+/**
+ * Resume a multi-request adapter send at the first unfinished visible step.
+ * DeliveryQueue retries the same cached OutgoingMessage object for Mimi turns,
+ * so this prevents a failed second attachment from duplicating earlier text.
+ * A failure while awaiting one platform call remains honestly at-least-once:
+ * the remote service may have accepted it without returning an acknowledgement.
+ */
+export class OutgoingDeliveryTracker {
+    plans = new WeakMap();
+    async run(message, createSteps) {
+        let plan = this.plans.get(message);
+        if (!plan) {
+            plan = { steps: Promise.resolve().then(createSteps), next: 0 };
+            this.plans.set(message, plan);
+            plan.steps.catch(() => {
+                if (this.plans.get(message) === plan)
+                    this.plans.delete(message);
+            });
+        }
+        const steps = await plan.steps;
+        while (plan.next < steps.length) {
+            await steps[plan.next]();
+            plan.next += 1;
+        }
+        if (this.plans.get(message) === plan)
+            this.plans.delete(message);
+    }
+}

package/dist/notification-progress.d.ts

@@ -0,0 +1,46 @@
+export interface NotificationEventDeliveryProgressState {
+    chunks: Record<string, number>;
+    /** Number of attachment descriptors accepted for each opaque target. */
+    attachments: Record<string, number>;
+}
+export interface NotificationDeliveryProgressState {
+    version: 3;
+    events: Record<string, NotificationEventDeliveryProgressState>;
+}
+export interface NotificationDeliveryProgressStore {
+    load(): Promise<NotificationDeliveryProgressState | undefined>;
+    save(state: NotificationDeliveryProgressState): Promise<void>;
+}
+/** Keep transport progress next to, but independent from, the Desktop event cursor. */
+export declare function notificationDeliveryProgressPath(eventCursorPath: string): string;
+/** Opaque key: the progress file never needs to disclose a raw owner destination. */
+export declare function notificationTargetProgressKey(channel: string, target: string): string;
+/** Owner-only, atomic persistence for partially delivered notification events. */
+export declare class FileNotificationDeliveryProgressStore implements NotificationDeliveryProgressStore {
+    readonly path: string;
+    constructor(path: string);
+    load(): Promise<NotificationDeliveryProgressState | undefined>;
+    save(state: NotificationDeliveryProgressState): Promise<void>;
+}
+/**
+ * Serializes progress mutations made by targets delivering in parallel. A
+ * successful transport call is recorded before the event handler returns, so
+ * a later target failure or ordinary process restart resumes at the owed part.
+ */
+export declare class NotificationDeliveryProgress {
+    private readonly store?;
+    private state?;
+    private loadTask?;
+    private writeTail;
+    constructor(store?: NotificationDeliveryProgressStore | undefined);
+    begin(eventKey: string): Promise<void>;
+    chunkIndex(eventKey: string, targetKey: string): number;
+    attachmentIndex(eventKey: string, targetKey: string): number;
+    mark(eventKey: string, targetKey: string, chunkIndex: number, attachmentIndex?: number): Promise<void>;
+    /** Retry a previously failed state write before the outer event is acknowledged. */
+    flush(): Promise<void>;
+    private ensureLoaded;
+    private persistCurrent;
+    private requireState;
+    private requireEventState;
+}