@cjhyy/code-shell-chat 0.8.0

package/dist/notification-progress.js

@@ -0,0 +1,299 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+const EVENT_KEY_PATTERN = /^[a-f0-9]{32}:\d{1,16}$/u;
+const TARGET_KEY_PATTERN = /^[A-Za-z0-9_-]{43}$/u;
+const MAX_PROGRESS_EVENTS = 200;
+const MAX_PROGRESS_TARGETS = 32;
+const MAX_TOTAL_PROGRESS_TARGETS = MAX_PROGRESS_EVENTS * MAX_PROGRESS_TARGETS * 2;
+const MAX_CHUNKS_PER_TARGET = 10_000;
+const MAX_PROGRESS_FILE_BYTES = 2 * 1024 * 1024;
+/** Keep transport progress next to, but independent from, the Desktop event cursor. */
+export function notificationDeliveryProgressPath(eventCursorPath) {
+    return `${eventCursorPath}.deliveries`;
+}
+/** Opaque key: the progress file never needs to disclose a raw owner destination. */
+export function notificationTargetProgressKey(channel, target) {
+    return createHash("sha256").update(channel).update("\0").update(target).digest("base64url");
+}
+/** Owner-only, atomic persistence for partially delivered notification events. */
+export class FileNotificationDeliveryProgressStore {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async load() {
+        let handle;
+        try {
+            // Inspect before reading: the size bound must prevent the allocation, not
+            // merely reject it afterwards. lstat also rejects a symlink that could
+            // substitute attacker-controlled "already delivered" markers.
+            const info = await lstat(this.path);
+            if (!info.isFile())
+                throw new Error(`Notification progress is not a file: ${this.path}`);
+            if (process.platform !== "win32" && (info.mode & 0o077) !== 0) {
+                throw new Error(`Notification progress permissions must be 0600: ${this.path}`);
+            }
+            if (info.size > MAX_PROGRESS_FILE_BYTES) {
+                throw new Error(`Notification progress is too large: ${this.path}`);
+            }
+            const noFollow = process.platform === "win32" ? 0 : constants.O_NOFOLLOW;
+            handle = await open(this.path, constants.O_RDONLY | noFollow);
+            const openedInfo = await handle.stat();
+            if (!openedInfo.isFile() || openedInfo.size > MAX_PROGRESS_FILE_BYTES) {
+                throw new Error(`Notification progress is not a bounded regular file: ${this.path}`);
+            }
+            const raw = await handle.readFile("utf-8");
+            if (Buffer.byteLength(raw, "utf-8") > MAX_PROGRESS_FILE_BYTES) {
+                throw new Error(`Notification progress is too large: ${this.path}`);
+            }
+            return parseNotificationDeliveryProgress(raw, this.path);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+        finally {
+            await handle?.close();
+        }
+    }
+    async save(state) {
+        const validated = parseNotificationDeliveryProgress(JSON.stringify(state), this.path);
+        const parent = dirname(this.path);
+        await mkdir(parent, { recursive: true, mode: 0o700 });
+        const parentInfo = await lstat(parent);
+        if (parentInfo.isSymbolicLink() || !parentInfo.isDirectory()) {
+            throw new Error(`Notification progress parent is not a regular directory: ${parent}`);
+        }
+        await chmod(parent, 0o700).catch(() => undefined);
+        const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, `${JSON.stringify(validated)}\n`, {
+                encoding: "utf-8",
+                mode: 0o600,
+                flag: "wx",
+            });
+            await rename(temporary, this.path);
+            await chmod(this.path, 0o600).catch(() => undefined);
+        }
+        catch (error) {
+            await rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+}
+/**
+ * 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 class NotificationDeliveryProgress {
+    store;
+    state;
+    loadTask;
+    writeTail = Promise.resolve();
+    constructor(store) {
+        this.store = store;
+    }
+    async begin(eventKey) {
+        if (!EVENT_KEY_PATTERN.test(eventKey))
+            throw new Error("Invalid notification event key");
+        await this.ensureLoaded();
+        const operation = this.writeTail
+            .catch(() => undefined)
+            .then(async () => {
+            const state = this.state ?? { version: 3, events: {} };
+            this.state = state;
+            if (state.events[eventKey])
+                return;
+            state.events[eventKey] = { chunks: {}, attachments: {} };
+            while (Object.keys(state.events).length > MAX_PROGRESS_EVENTS) {
+                const oldest = Object.keys(state.events)[0];
+                if (!oldest)
+                    break;
+                delete state.events[oldest];
+            }
+            await this.persistCurrent();
+        });
+        this.writeTail = operation;
+        await operation;
+    }
+    chunkIndex(eventKey, targetKey) {
+        return this.requireEventState(eventKey).chunks[targetKey] ?? 0;
+    }
+    attachmentIndex(eventKey, targetKey) {
+        return this.requireEventState(eventKey).attachments[targetKey] ?? 0;
+    }
+    async mark(eventKey, targetKey, chunkIndex, attachmentIndex) {
+        if (!EVENT_KEY_PATTERN.test(eventKey))
+            throw new Error("Invalid notification event key");
+        if (!TARGET_KEY_PATTERN.test(targetKey))
+            throw new Error("Invalid notification target key");
+        if (!Number.isSafeInteger(chunkIndex) || chunkIndex < 0 || chunkIndex > MAX_CHUNKS_PER_TARGET) {
+            throw new Error("Invalid notification chunk progress");
+        }
+        if (attachmentIndex !== undefined &&
+            (!Number.isSafeInteger(attachmentIndex) || attachmentIndex < 0 || attachmentIndex > 4)) {
+            throw new Error("Invalid notification attachment progress");
+        }
+        const operation = this.writeTail
+            .catch(() => undefined)
+            .then(async () => {
+            const eventState = this.requireEventState(eventKey);
+            eventState.chunks[targetKey] = Math.max(eventState.chunks[targetKey] ?? 0, chunkIndex);
+            if (attachmentIndex !== undefined) {
+                eventState.attachments[targetKey] = Math.max(eventState.attachments[targetKey] ?? 0, attachmentIndex);
+            }
+            const state = this.requireState();
+            validateProgressShape(state, "memory");
+            await this.store?.save(cloneProgress(state));
+        });
+        this.writeTail = operation;
+        await operation;
+    }
+    /** Retry a previously failed state write before the outer event is acknowledged. */
+    async flush() {
+        const operation = this.writeTail.catch(() => undefined).then(() => this.persistCurrent());
+        this.writeTail = operation;
+        await operation;
+    }
+    ensureLoaded() {
+        this.loadTask ??= (async () => {
+            const loaded = await this.store?.load();
+            this.state = loaded ? cloneProgress(loaded) : undefined;
+        })();
+        return this.loadTask;
+    }
+    async persistCurrent() {
+        const state = this.requireState();
+        validateProgressShape(state, "memory");
+        await this.store?.save(cloneProgress(state));
+    }
+    requireState() {
+        if (!this.state)
+            throw new Error("Notification progress has not started");
+        return this.state;
+    }
+    requireEventState(eventKey) {
+        const state = this.requireState();
+        const eventState = state.events[eventKey];
+        if (!eventState)
+            throw new Error("Notification event progress has not started");
+        return eventState;
+    }
+}
+function parseNotificationDeliveryProgress(raw, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Invalid notification progress JSON: ${source}`, { cause: error });
+    }
+    const migrated = migrateLegacyProgress(parsed, source);
+    validateProgressShape(migrated, source);
+    return cloneProgress(migrated);
+}
+function validateProgressShape(value, source) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Invalid notification progress: ${source}`);
+    }
+    const candidate = value;
+    if (candidate.version !== 3 ||
+        !candidate.events ||
+        typeof candidate.events !== "object" ||
+        Array.isArray(candidate.events)) {
+        throw new Error(`Invalid notification progress: ${source}`);
+    }
+    const events = Object.entries(candidate.events);
+    if (events.length > MAX_PROGRESS_EVENTS ||
+        events.some(([eventKey, eventState]) => !EVENT_KEY_PATTERN.test(eventKey) || !isValidEventProgress(eventState)) ||
+        events.reduce((total, [, eventState]) => total + Object.keys(eventState.chunks).length + Object.keys(eventState.attachments).length, 0) > MAX_TOTAL_PROGRESS_TARGETS) {
+        throw new Error(`Invalid notification progress: ${source}`);
+    }
+}
+function isValidEventProgress(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const candidate = value;
+    if (!candidate.chunks ||
+        typeof candidate.chunks !== "object" ||
+        Array.isArray(candidate.chunks) ||
+        !candidate.attachments ||
+        typeof candidate.attachments !== "object" ||
+        Array.isArray(candidate.attachments)) {
+        return false;
+    }
+    const chunks = Object.entries(candidate.chunks);
+    const attachments = Object.entries(candidate.attachments);
+    return (chunks.length <= MAX_PROGRESS_TARGETS &&
+        chunks.every(([key, count]) => TARGET_KEY_PATTERN.test(key) &&
+            Number.isSafeInteger(count) &&
+            count >= 0 &&
+            count <= MAX_CHUNKS_PER_TARGET) &&
+        attachments.length <= MAX_PROGRESS_TARGETS &&
+        attachments.every(([key, count]) => TARGET_KEY_PATTERN.test(key) && Number.isSafeInteger(count) && count >= 0 && count <= 4));
+}
+function migrateLegacyProgress(value, source) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Invalid notification progress: ${source}`);
+    }
+    const legacy = value;
+    if (legacy.version === 2) {
+        if (!legacy.events || typeof legacy.events !== "object" || Array.isArray(legacy.events)) {
+            throw new Error(`Invalid notification progress: ${source}`);
+        }
+        const events = Object.fromEntries(Object.entries(legacy.events).map(([eventKey, rawEvent]) => {
+            if (!rawEvent || typeof rawEvent !== "object" || Array.isArray(rawEvent)) {
+                throw new Error(`Invalid notification progress: ${source}`);
+            }
+            const event = rawEvent;
+            if (!Array.isArray(event.attachments)) {
+                throw new Error(`Invalid notification progress: ${source}`);
+            }
+            return [
+                eventKey,
+                {
+                    chunks: event.chunks,
+                    // v2 recorded only an all-attachments boolean. Four is the
+                    // protocol maximum, so every possible descriptor remains skipped.
+                    attachments: Object.fromEntries(event.attachments.map((key) => [key, 4])),
+                },
+            ];
+        }));
+        return { version: 3, events };
+    }
+    if (legacy.version !== 1)
+        return value;
+    if (typeof legacy.eventKey !== "string" ||
+        !EVENT_KEY_PATTERN.test(legacy.eventKey) ||
+        !legacy.chunks ||
+        typeof legacy.chunks !== "object" ||
+        Array.isArray(legacy.chunks) ||
+        !Array.isArray(legacy.attachments)) {
+        throw new Error(`Invalid notification progress: ${source}`);
+    }
+    return {
+        version: 3,
+        events: {
+            [legacy.eventKey]: {
+                chunks: { ...legacy.chunks },
+                attachments: Object.fromEntries(legacy.attachments.map((key) => [key, 4])),
+            },
+        },
+    };
+}
+function cloneProgress(state) {
+    return {
+        version: 3,
+        events: Object.fromEntries(Object.entries(state.events).map(([eventKey, eventState]) => [
+            eventKey,
+            {
+                chunks: { ...eventState.chunks },
+                attachments: { ...eventState.attachments },
+            },
+        ])),
+    };
+}

package/dist/notification-relay.d.ts

@@ -0,0 +1,43 @@
+import { type ChannelAdapter, type ChatAttachmentKind, type ChannelCapabilities, type OutgoingAttachment } from "./channel.js";
+import type { GatewayNotificationTarget } from "./config.js";
+import type { DesktopEventContext } from "./desktop-control-client.js";
+import type { DesktopControlEvent } from "./protocol.js";
+import { type NotificationDeliveryProgressStore } from "./notification-progress.js";
+/** Split without breaking UTF-16 surrogate pairs; prefer readable line/word boundaries. */
+export declare function splitNotificationText(text: string, maximum?: number): string[];
+/**
+ * Personal WeChat accepts the adapter's declared 8k text payload as one
+ * visible message. Other notification adapters keep the conservative shared
+ * limit until their platform-specific limits are represented precisely.
+ */
+export declare function splitNotificationTextForChannel(text: string, channel: string, capabilities: ChannelCapabilities): string[];
+/**
+ * Builds an at-least-once Desktop event sender. Successful targets are kept in
+ * memory while a failed target is retried, so one unhealthy adapter does not
+ * duplicate notifications on the adapters that already accepted the event.
+ */
+export declare function createDesktopNotificationHandler(adapters: readonly ChannelAdapter[], targets: readonly GatewayNotificationTarget[], options?: {
+    progressStore?: NotificationDeliveryProgressStore;
+    /** Revalidate current owner authorization immediately before transport. */
+    authorizeTarget?: (target: GatewayNotificationTarget) => boolean | Promise<boolean>;
+}): (event: DesktopControlEvent, context: DesktopEventContext) => Promise<void>;
+/**
+ * Transport-neutral descriptor for one already-authorized host-local file.
+ * Path authorization remains a host concern; this layer verifies immutable
+ * file metadata before exposing bytes to a channel adapter.
+ */
+export interface LocalOutgoingAttachmentDescriptor {
+    kind: ChatAttachmentKind;
+    path: string;
+    name: string;
+    mimeType: string;
+    size: number;
+}
+/**
+ * Read validated host-local attachments from disk into outgoing bytes.
+ * Shared by event relays, Mimi replies, and proactive sends; throws when
+ * metadata is invalid or the file changed before the transport accepts it.
+ */
+export declare function materializeOutgoingAttachments(attachments: readonly LocalOutgoingAttachmentDescriptor[]): Promise<OutgoingAttachment[]>;
+/** @deprecated Use materializeOutgoingAttachments for transport-neutral code. */
+export declare const materializeEventAttachments: typeof materializeOutgoingAttachments;

package/dist/notification-relay.js

@@ -0,0 +1,285 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { channelCapabilities, } from "./channel.js";
+import { NotificationDeliveryProgress, notificationTargetProgressKey, } from "./notification-progress.js";
+// Keep below Discord's 2,000-character content cap as well as Telegram's
+// 4,096-character cap. A single conservative relay limit makes every adapter
+// safe without letting product events depend on channel-specific truncation.
+const MAX_NOTIFICATION_CHUNK_LENGTH = 1_800;
+const MAX_NOTIFICATION_TEXT_LENGTH = 100_000;
+const MAX_OUTGOING_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+const NOTIFICATION_CONTROL_CHARACTER_RE = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u;
+const NOTIFICATION_DELIVERY_KEY_RE = /^[a-f0-9]{64}$/u;
+/** Split without breaking UTF-16 surrogate pairs; prefer readable line/word boundaries. */
+export function splitNotificationText(text, maximum = MAX_NOTIFICATION_CHUNK_LENGTH) {
+    if (!Number.isSafeInteger(maximum) || maximum < 2) {
+        throw new Error("Notification chunk length must be an integer of at least 2");
+    }
+    if (text.length <= maximum)
+        return [text];
+    const chunks = [];
+    let start = 0;
+    while (start < text.length) {
+        let end = Math.min(start + maximum, text.length);
+        if (end < text.length) {
+            const previous = text.charCodeAt(end - 1);
+            const next = text.charCodeAt(end);
+            if (previous >= 0xd800 && previous <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) {
+                end -= 1;
+            }
+            const minimumReadableBreak = start + Math.floor(maximum * 0.6);
+            const newline = text.lastIndexOf("\n", end - 1);
+            const space = text.lastIndexOf(" ", end - 1);
+            const readableBreak = Math.max(newline, space);
+            if (readableBreak >= minimumReadableBreak)
+                end = readableBreak + 1;
+        }
+        chunks.push(text.slice(start, end));
+        start = end;
+    }
+    return chunks;
+}
+/**
+ * Personal WeChat accepts the adapter's declared 8k text payload as one
+ * visible message. Other notification adapters keep the conservative shared
+ * limit until their platform-specific limits are represented precisely.
+ */
+export function splitNotificationTextForChannel(text, channel, capabilities) {
+    const declaredMaximum = capabilities.outbound.maxTextLength;
+    const safeDeclaredMaximum = Number.isSafeInteger(declaredMaximum) && (declaredMaximum ?? 0) >= 2
+        ? declaredMaximum
+        : MAX_NOTIFICATION_CHUNK_LENGTH;
+    const maximum = channel === "wechat"
+        ? safeDeclaredMaximum
+        : Math.min(MAX_NOTIFICATION_CHUNK_LENGTH, safeDeclaredMaximum);
+    return splitNotificationText(text, maximum);
+}
+/**
+ * Builds an at-least-once Desktop event sender. Successful targets are kept in
+ * memory while a failed target is retried, so one unhealthy adapter does not
+ * duplicate notifications on the adapters that already accepted the event.
+ */
+export function createDesktopNotificationHandler(adapters, targets, options = {}) {
+    const adapterByChannel = new Map(adapters.map((adapter) => [adapter.channel, adapter]));
+    const progress = new NotificationDeliveryProgress(options.progressStore);
+    const configuredTargetKeys = new Set(targets.map(({ channel, target }) => `${channel}\0${target}`));
+    const authorizeTarget = options.authorizeTarget ??
+        (({ channel, target }) => configuredTargetKeys.has(`${channel}\0${target}`));
+    return async (event, context) => {
+        validateDesktopNotificationEvent(event);
+        const requestedTargets = event.target ? [event.target] : targets;
+        const authorizations = await Promise.all(requestedTargets.map((target) => authorizeTarget(target)));
+        const eventTargets = requestedTargets.filter((_, index) => authorizations[index] === true);
+        // Revoking a target is an owner decision, not a transient transport
+        // failure. Treat a fully-revoked event as handled so it cannot block every
+        // later outbox event while still guaranteeing no send occurs.
+        if (eventTargets.length === 0)
+            return;
+        // A semantic key survives Desktop/event-server restarts. Keep the on-disk
+        // progress schema compact by using its first 128 bits plus a reserved zero
+        // event suffix; the producer supplies a full SHA-256 key.
+        const eventKey = event.deliveryKey
+            ? `${event.deliveryKey.slice(0, 32)}:0`
+            : `${context.streamId}:${event.id}`;
+        await progress.begin(eventKey);
+        const results = await Promise.allSettled(eventTargets.map(async ({ channel, target }) => {
+            const targetKey = notificationTargetProgressKey(channel, target);
+            const adapter = adapterByChannel.get(channel);
+            if (!adapter)
+                throw new Error(`Notification adapter is unavailable: ${channel}`);
+            const capabilities = channelCapabilities(adapter);
+            const supportedEventAttachments = (event.attachments ?? []).filter((attachment) => capabilities.outbound.attachments.includes(attachment.kind));
+            const chunks = splitNotificationTextForChannel(event.text, channel, capabilities);
+            let attachmentIndex = Math.min(progress.attachmentIndex(eventKey, targetKey), supportedEventAttachments.length);
+            let combinedAttachments = [];
+            let attachmentError;
+            let chunkIndex = progress.chunkIndex(eventKey, targetKey);
+            // Only adapters that explicitly guarantee one visible platform request
+            // may combine the final text chunk with media. Everyone else sends and
+            // checkpoints each attachment independently, so a later media failure
+            // cannot repeat already accepted text or earlier attachments.
+            const canCombine = adapter.combinesTextAndAttachmentsAtomically === true &&
+                attachmentIndex === 0 &&
+                supportedEventAttachments.length > 0 &&
+                chunkIndex < chunks.length;
+            if (canCombine) {
+                try {
+                    combinedAttachments = await materializeOutgoingAttachments(supportedEventAttachments);
+                }
+                catch (error) {
+                    attachmentError = error;
+                }
+            }
+            const combineAttachments = combinedAttachments.length > 0;
+            while (chunkIndex < chunks.length) {
+                const isLast = chunkIndex === chunks.length - 1;
+                await adapter.send(target, {
+                    text: chunks[chunkIndex],
+                    ...(chunkIndex === 0 && event.title ? { title: event.title } : {}),
+                    ...(isLast && event.button ? { button: event.button } : {}),
+                    ...(isLast && combineAttachments ? { attachments: combinedAttachments } : {}),
+                });
+                chunkIndex += 1;
+                if (isLast && combineAttachments) {
+                    attachmentIndex = supportedEventAttachments.length;
+                }
+                await progress.mark(eventKey, targetKey, chunkIndex, isLast && combineAttachments ? attachmentIndex : undefined);
+            }
+            if (attachmentError)
+                throw attachmentError;
+            while (attachmentIndex < supportedEventAttachments.length) {
+                const descriptor = supportedEventAttachments[attachmentIndex];
+                const [attachment] = await materializeOutgoingAttachments([descriptor]);
+                if (!attachment)
+                    throw new Error("Outgoing attachment could not be materialized");
+                await adapter.send(target, { text: "", attachments: [attachment] });
+                attachmentIndex += 1;
+                await progress.mark(eventKey, targetKey, chunkIndex, attachmentIndex);
+            }
+        }));
+        const failures = results
+            .filter((result) => result.status === "rejected")
+            .map(({ reason }) => reason);
+        if (failures.length > 0) {
+            throw new AggregateError(failures, `Desktop event ${eventKey} notification failed`);
+        }
+        await progress.flush();
+    };
+}
+function validateDesktopNotificationEvent(event) {
+    if (typeof event.text !== "string" ||
+        !event.text.trim() ||
+        event.text.length > MAX_NOTIFICATION_TEXT_LENGTH ||
+        NOTIFICATION_CONTROL_CHARACTER_RE.test(event.text) ||
+        (event.deliveryKey !== undefined &&
+            (typeof event.deliveryKey !== "string" ||
+                !NOTIFICATION_DELIVERY_KEY_RE.test(event.deliveryKey))) ||
+        (event.title !== undefined &&
+            (typeof event.title !== "string" ||
+                !event.title.trim() ||
+                event.title.length > 256 ||
+                NOTIFICATION_CONTROL_CHARACTER_RE.test(event.title))) ||
+        (event.target !== undefined &&
+            (!event.target ||
+                typeof event.target !== "object" ||
+                typeof event.target.channel !== "string" ||
+                !/^[a-z0-9_-]{1,64}$/u.test(event.target.channel) ||
+                typeof event.target.target !== "string" ||
+                !event.target.target.trim() ||
+                event.target.target.length > 4_096 ||
+                NOTIFICATION_CONTROL_CHARACTER_RE.test(event.target.target))) ||
+        (event.button !== undefined && !isValidNotificationButton(event.button)) ||
+        !Array.isArray(event.attachments ?? []) ||
+        (event.attachments?.length ?? 0) > 4 ||
+        (event.attachments ?? []).some((attachment) => !isValidAttachmentDescriptor(attachment))) {
+        throw new Error("Desktop notification event is invalid");
+    }
+}
+function isValidNotificationButton(button) {
+    if (!button ||
+        typeof button !== "object" ||
+        !("text" in button) ||
+        !("url" in button) ||
+        typeof button.text !== "string" ||
+        !button.text.trim() ||
+        button.text.length > 256 ||
+        NOTIFICATION_CONTROL_CHARACTER_RE.test(button.text) ||
+        typeof button.url !== "string" ||
+        button.url.length > 2_048) {
+        return false;
+    }
+    try {
+        const url = new URL(button.url);
+        return ((url.protocol === "http:" || url.protocol === "https:") && !url.username && !url.password);
+    }
+    catch {
+        return false;
+    }
+}
+function isValidAttachmentDescriptor(attachment) {
+    if (!attachment || typeof attachment !== "object")
+        return false;
+    return ("kind" in attachment &&
+        "path" in attachment &&
+        "name" in attachment &&
+        "mimeType" in attachment &&
+        "size" in attachment &&
+        typeof attachment.kind === "string" &&
+        ["image", "file", "audio", "video"].includes(attachment.kind) &&
+        typeof attachment.path === "string" &&
+        isAbsolute(attachment.path) &&
+        typeof attachment.name === "string" &&
+        Boolean(attachment.name.trim()) &&
+        attachment.name.length <= 255 &&
+        !/[\\/\u0000-\u001f\u007f]/u.test(attachment.name) &&
+        typeof attachment.mimeType === "string" &&
+        Boolean(attachment.mimeType.trim()) &&
+        attachment.mimeType.length <= 255 &&
+        !/[\u0000-\u001f\u007f]/u.test(attachment.mimeType) &&
+        (attachment.kind === "image"
+            ? attachment.mimeType.startsWith("image/")
+            : attachment.kind === "audio"
+                ? attachment.mimeType.startsWith("audio/")
+                : attachment.kind === "video"
+                    ? attachment.mimeType.startsWith("video/")
+                    : true) &&
+        typeof attachment.size === "number" &&
+        Number.isSafeInteger(attachment.size) &&
+        attachment.size >= 1 &&
+        attachment.size <= MAX_OUTGOING_ATTACHMENT_BYTES);
+}
+/**
+ * Read validated host-local attachments from disk into outgoing bytes.
+ * Shared by event relays, Mimi replies, and proactive sends; throws when
+ * metadata is invalid or the file changed before the transport accepts it.
+ */
+export async function materializeOutgoingAttachments(attachments) {
+    if (attachments.length > 4)
+        throw new Error("Outgoing attachment metadata is invalid");
+    const output = [];
+    for (const attachment of attachments) {
+        if (!isValidAttachmentDescriptor(attachment)) {
+            throw new Error("Outgoing attachment metadata is invalid");
+        }
+        const data = await readStableOutgoingAttachment(attachment.path, attachment.size);
+        output.push({
+            kind: attachment.kind,
+            name: attachment.name.slice(0, 255) ||
+                (attachment.kind === "image"
+                    ? "generated-image"
+                    : attachment.kind === "audio"
+                        ? "audio"
+                        : attachment.kind === "video"
+                            ? "video"
+                            : "attachment"),
+            mimeType: attachment.mimeType,
+            data,
+        });
+    }
+    return output;
+}
+async function readStableOutgoingAttachment(path, expectedSize) {
+    try {
+        const noFollow = process.platform === "win32" ? 0 : constants.O_NOFOLLOW;
+        const handle = await open(path, constants.O_RDONLY | noFollow);
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() || info.size !== expectedSize) {
+                throw new Error("file metadata changed");
+            }
+            const data = await handle.readFile();
+            if (data.byteLength !== expectedSize)
+                throw new Error("file size changed while reading");
+            return data;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        throw new Error("Outgoing attachment changed before delivery", { cause: error });
+    }
+}
+/** @deprecated Use materializeOutgoingAttachments for transport-neutral code. */
+export const materializeEventAttachments = materializeOutgoingAttachments;

package/dist/platform-canary.d.ts

@@ -0,0 +1,22 @@
+import type { ChannelAdapter } from "./channel.js";
+import { ChatGateway, type ChatAllowlistRule } from "./chat-gateway.js";
+export interface PlatformCanaryOptions {
+    adapters: ChannelAdapter[];
+    allowlists: Readonly<Record<string, ChatAllowlistRule>>;
+    webhook?: ConstructorParameters<typeof ChatGateway>[0]["webhook"];
+    delivery?: ConstructorParameters<typeof ChatGateway>[0]["delivery"];
+    timeoutMs?: number;
+    nonce?: string;
+    onReady?: (instruction: string) => void;
+}
+export interface PlatformCanaryResult {
+    nonce: string;
+    channels: string[];
+    completedAt: number;
+}
+/**
+ * Credential-backed canary: starts the real adapters and ingress, then waits
+ * for one allowlisted inbound `/canary <nonce>` per configured channel and
+ * replies through that same platform. Nothing is sent to users unprompted.
+ */
+export declare function runPlatformCanary(options: PlatformCanaryOptions): Promise<PlatformCanaryResult>;