@cjhyy/code-shell-chat 0.8.0

package/dist/platform-canary.js

@@ -0,0 +1,55 @@
+import { randomBytes } from "node:crypto";
+import { ChatGateway, createAllowlistMiddleware } from "./chat-gateway.js";
+/**
+ * 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 async function runPlatformCanary(options) {
+    if (options.adapters.length === 0)
+        throw new Error("canary requires at least one adapter");
+    const expected = new Set(options.adapters.map(({ channel }) => channel));
+    const completed = new Set();
+    const nonce = options.nonce ?? randomBytes(6).toString("hex");
+    const command = `/canary ${nonce}`;
+    const timeoutMs = options.timeoutMs ?? 10 * 60_000;
+    const abort = new AbortController();
+    let resolveComplete;
+    const complete = new Promise((resolve) => {
+        resolveComplete = resolve;
+    });
+    const gateway = new ChatGateway({
+        adapters: options.adapters,
+        webhook: options.webhook,
+        delivery: options.delivery,
+    });
+    gateway.use(createAllowlistMiddleware(options.allowlists));
+    gateway.use(async ({ message, reply }) => {
+        if (message.text.trim() !== command)
+            return;
+        await reply({ text: `✅ CodeShell ${message.channel} canary passed (${nonce})` });
+        completed.add(message.channel);
+        if ([...expected].every((channel) => completed.has(channel)))
+            resolveComplete();
+    });
+    options.onReady?.(`请在以下 channel 的白名单会话中各发送一次：${command}\n${[...expected].join(", ")}`);
+    const gatewayTask = gateway.run(abort.signal);
+    const timer = setTimeout(() => abort.abort(), timeoutMs);
+    try {
+        await Promise.race([
+            complete,
+            gatewayTask.then(() => {
+                throw new Error("platform canary gateway exited before completion");
+            }),
+            new Promise((_resolve, reject) => abort.signal.addEventListener("abort", () => reject(new Error(`platform canary timed out; missing: ${[...expected]
+                .filter((channel) => !completed.has(channel))
+                .join(", ")}`)), { once: true })),
+        ]);
+        return { nonce, channels: [...completed].sort(), completedAt: Date.now() };
+    }
+    finally {
+        clearTimeout(timer);
+        abort.abort();
+        await gatewayTask.catch(() => undefined);
+    }
+}

package/dist/protocol.d.ts

@@ -0,0 +1,102 @@
+import type { ChannelCapabilities } from "./channel.js";
+export declare const DESKTOP_CONTROL_PROTOCOL_VERSION = 1;
+export interface DesktopControlDescriptor {
+    version: typeof DESKTOP_CONTROL_PROTOCOL_VERSION;
+    pid: number;
+    baseUrl: string;
+    token: string;
+    startedAt: number;
+}
+export interface DesktopControlEvent {
+    id: number;
+    createdAt: number;
+    /**
+     * Optional opaque semantic delivery identity. Unlike streamId:id it remains
+     * stable when Desktop republishes one durable event after a process restart.
+     */
+    deliveryKey?: string;
+    type: "tunnel.connected" | "tunnel.disconnected" | "tunnel.error" | "pet.task.completed" | "pet.task.failed" | "pet.task.cancelled" | "pet.task.reported" | "automation.completed" | "automation.failed" | "automation.stopped" | "automation.cancelled";
+    text: string;
+    title?: string;
+    button?: {
+        text: string;
+        url: string;
+    };
+    attachments?: DesktopControlEventAttachment[];
+    /** One originating IM conversation; bypasses general notification targets. */
+    target?: {
+        channel: string;
+        target: string;
+    };
+}
+export interface DesktopControlEventAttachment {
+    kind: PetChatAttachmentKind;
+    name: string;
+    mimeType: string;
+    size: number;
+    /** Validated local path on the same host as the loopback gateway. */
+    path: string;
+}
+export interface DesktopControlEventPage {
+    /** Durable outbox identity; changes only when Desktop initializes a replacement event store. */
+    streamId: string;
+    events: DesktopControlEvent[];
+    cursor: number;
+    /** Desktop retained the stream identity but recovered behind this checkpoint. */
+    resetCursor?: true;
+}
+export interface MobileRemoteOpenResult {
+    url: string;
+    pairingUrl: string;
+    expiresAt: number;
+    mode: "tunnel" | "lan";
+}
+export interface MobileRemoteStatus {
+    running: boolean;
+    url?: string;
+    mode?: "tunnel" | "lan";
+    tunnelRunning: boolean;
+    tunnelConnected: boolean;
+    passcodeSet: boolean;
+    onlineDeviceCount: number;
+}
+export type PetChatAttachmentKind = "image" | "file" | "audio" | "video";
+/** Bytes already fetched by the gateway and ready for loopback transfer to desktop main. */
+export interface PetChatInputAttachment {
+    id: string;
+    kind: PetChatAttachmentKind;
+    name?: string;
+    mimeType?: string;
+    size: number;
+    dataBase64: string;
+}
+export interface PetChatRequest {
+    message: string;
+    attachments?: PetChatInputAttachment[];
+    origin?: {
+        channel: string;
+        target: string;
+        senderId: string;
+        messageId?: string;
+        /** Adapter-declared implementation capabilities for this exact route. */
+        capabilities: ChannelCapabilities;
+        /** Enabled adapters in this Gateway process, without credentials or target ids. */
+        channels?: PetChatGatewayChannel[];
+    };
+}
+export interface PetChatGatewayChannel {
+    channel: string;
+    capabilities: ChannelCapabilities;
+}
+export interface PetChatResult {
+    text: string;
+    petSessionId: string;
+    reason?: string;
+    /** GatewayReply URL action; rendered natively or as a labelled link by the adapter. */
+    button?: {
+        text: string;
+        url: string;
+    };
+    /** Host-produced reply attachments; same host-local path shape as event attachments. */
+    attachments?: DesktopControlEventAttachment[];
+}

package/dist/protocol.js

@@ -0,0 +1 @@
+export const DESKTOP_CONTROL_PROTOCOL_VERSION = 1;

package/dist/service-manager.d.ts

@@ -0,0 +1,47 @@
+export interface GatewayServiceOptions {
+    configPath: string;
+    platform?: NodeJS.Platform;
+    home?: string;
+    executable?: string;
+    cliPath?: string;
+    run?: (command: string, args: string[]) => Promise<{
+        stdout?: string;
+        stderr?: string;
+    }>;
+}
+export interface GatewayServiceStatus {
+    installed: boolean;
+    running: boolean;
+    definitionPath?: string;
+    detail?: string;
+}
+/** Install the gateway as a per-user launchd/systemd/Task Scheduler service. */
+export declare class GatewayServiceManager {
+    private readonly options;
+    private readonly platform;
+    private readonly home;
+    private readonly executable;
+    private readonly cliPath;
+    private readonly run;
+    constructor(options: GatewayServiceOptions);
+    install(): Promise<GatewayServiceStatus>;
+    uninstall(): Promise<GatewayServiceStatus>;
+    status(): Promise<GatewayServiceStatus>;
+    private installLaunchd;
+    private installSystemd;
+    private installTaskScheduler;
+    private launchdPath;
+    private systemdPath;
+}
+export declare function renderLaunchdService(input: {
+    executable: string;
+    cliPath: string;
+    configPath: string;
+    stdoutPath: string;
+    stderrPath: string;
+}): string;
+export declare function renderSystemdService(input: {
+    executable: string;
+    cliPath: string;
+    configPath: string;
+}): string;

package/dist/service-manager.js

@@ -0,0 +1,222 @@
+import { execFile as nodeExecFile } from "node:child_process";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(nodeExecFile);
+/** Install the gateway as a per-user launchd/systemd/Task Scheduler service. */
+export class GatewayServiceManager {
+    options;
+    platform;
+    home;
+    executable;
+    cliPath;
+    run;
+    constructor(options) {
+        this.options = options;
+        this.platform = options.platform ?? process.platform;
+        this.home = resolve(options.home ?? process.env.HOME ?? homedir());
+        this.executable = resolve(options.executable ?? process.execPath);
+        this.cliPath = resolve(options.cliPath ?? process.argv[1] ?? "");
+        this.run = options.run ?? ((command, args) => execFileAsync(command, args));
+    }
+    async install() {
+        if (this.platform === "darwin")
+            return this.installLaunchd();
+        if (this.platform === "linux")
+            return this.installSystemd();
+        if (this.platform === "win32")
+            return this.installTaskScheduler();
+        throw new Error(`不支持的服务平台：${this.platform}`);
+    }
+    async uninstall() {
+        if (this.platform === "darwin") {
+            const path = this.launchdPath();
+            await this.run("launchctl", ["bootout", `gui/${process.getuid?.() ?? 0}`, path]).catch(() => undefined);
+            await rm(path, { force: true });
+            return { installed: false, running: false, definitionPath: path };
+        }
+        if (this.platform === "linux") {
+            const path = this.systemdPath();
+            await this.run("systemctl", ["--user", "disable", "--now", "codeshell-chat.service"]).catch(() => undefined);
+            await rm(path, { force: true });
+            await this.run("systemctl", ["--user", "daemon-reload"]);
+            return { installed: false, running: false, definitionPath: path };
+        }
+        if (this.platform === "win32") {
+            await this.run("schtasks.exe", ["/Delete", "/TN", "CodeShell Chat Gateway", "/F"]).catch(() => undefined);
+            return { installed: false, running: false };
+        }
+        throw new Error(`不支持的服务平台：${this.platform}`);
+    }
+    async status() {
+        if (this.platform === "darwin") {
+            const path = this.launchdPath();
+            const installed = await fileExists(path);
+            if (!installed)
+                return { installed: false, running: false, definitionPath: path };
+            const result = await this.run("launchctl", [
+                "print",
+                `gui/${process.getuid?.() ?? 0}/com.cjhyy.codeshell.chat-gateway`,
+            ]).catch((error) => ({ stderr: String(error) }));
+            return {
+                installed: true,
+                running: !result.stderr,
+                definitionPath: path,
+                ...(result.stderr ? { detail: result.stderr } : {}),
+            };
+        }
+        if (this.platform === "linux") {
+            const path = this.systemdPath();
+            const installed = await fileExists(path);
+            if (!installed)
+                return { installed: false, running: false, definitionPath: path };
+            const result = await this.run("systemctl", ["--user", "is-active", "codeshell-chat.service"])
+                .then(({ stdout }) => ({ running: stdout?.trim() === "active", detail: stdout?.trim() }))
+                .catch((error) => ({ running: false, detail: String(error) }));
+            return { installed: true, definitionPath: path, ...result };
+        }
+        if (this.platform === "win32") {
+            const result = await this.run("schtasks.exe", [
+                "/Query",
+                "/TN",
+                "CodeShell Chat Gateway",
+                "/FO",
+                "LIST",
+            ]).catch((error) => ({ stdout: "", stderr: String(error) }));
+            const installed = !result.stderr;
+            return {
+                installed,
+                running: installed && /Running/i.test(result.stdout ?? ""),
+                ...(result.stderr ? { detail: result.stderr } : {}),
+            };
+        }
+        throw new Error(`不支持的服务平台：${this.platform}`);
+    }
+    async installLaunchd() {
+        const path = this.launchdPath();
+        const logDir = join(this.home, ".code-shell", "im-gateway", "logs");
+        await mkdir(logDir, { recursive: true, mode: 0o700 });
+        await writeOwnerFile(path, renderLaunchdService({
+            executable: this.executable,
+            cliPath: this.cliPath,
+            configPath: resolve(this.options.configPath),
+            stdoutPath: join(logDir, "gateway.log"),
+            stderrPath: join(logDir, "gateway.error.log"),
+        }));
+        await this.run("launchctl", ["bootout", `gui/${process.getuid?.() ?? 0}`, path]).catch(() => undefined);
+        await this.run("launchctl", ["bootstrap", `gui/${process.getuid?.() ?? 0}`, path]);
+        return { installed: true, running: true, definitionPath: path };
+    }
+    async installSystemd() {
+        const path = this.systemdPath();
+        await writeOwnerFile(path, renderSystemdService({
+            executable: this.executable,
+            cliPath: this.cliPath,
+            configPath: resolve(this.options.configPath),
+        }));
+        await this.run("systemctl", ["--user", "daemon-reload"]);
+        await this.run("systemctl", ["--user", "enable", "--now", "codeshell-chat.service"]);
+        return { installed: true, running: true, definitionPath: path };
+    }
+    async installTaskScheduler() {
+        const command = windowsCommand([
+            this.executable,
+            this.cliPath,
+            "--config",
+            resolve(this.options.configPath),
+        ]);
+        await this.run("schtasks.exe", [
+            "/Create",
+            "/TN",
+            "CodeShell Chat Gateway",
+            "/TR",
+            command,
+            "/SC",
+            "ONLOGON",
+            "/RL",
+            "LIMITED",
+            "/F",
+        ]);
+        await this.run("schtasks.exe", ["/Run", "/TN", "CodeShell Chat Gateway"]);
+        return { installed: true, running: true };
+    }
+    launchdPath() {
+        return join(this.home, "Library", "LaunchAgents", "com.cjhyy.codeshell.chat-gateway.plist");
+    }
+    systemdPath() {
+        return join(this.home, ".config", "systemd", "user", "codeshell-chat.service");
+    }
+}
+export function renderLaunchdService(input) {
+    const args = [input.executable, input.cliPath, "--config", input.configPath]
+        .map((value) => `    <string>${escapeXml(value)}</string>`)
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>com.cjhyy.codeshell.chat-gateway</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>StandardOutPath</key><string>${escapeXml(input.stdoutPath)}</string>
+  <key>StandardErrorPath</key><string>${escapeXml(input.stderrPath)}</string>
+</dict>
+</plist>
+`;
+}
+export function renderSystemdService(input) {
+    return `[Unit]
+Description=CodeShell Chat Gateway
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${systemdQuote(input.executable)} ${systemdQuote(input.cliPath)} --config ${systemdQuote(input.configPath)}
+Restart=on-failure
+RestartSec=5
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=read-only
+ReadWritePaths=%h/.code-shell
+
+[Install]
+WantedBy=default.target
+`;
+}
+async function writeOwnerFile(path, contents) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, contents, { encoding: "utf-8", mode: 0o600 });
+    if (process.platform !== "win32")
+        await chmod(path, 0o600);
+}
+async function fileExists(path) {
+    try {
+        await readFile(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function escapeXml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+function systemdQuote(value) {
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+function windowsCommand(args) {
+    return args.map((value) => `"${value.replaceAll('"', '\\"')}"`).join(" ");
+}

package/dist/slack.d.ts

@@ -0,0 +1,17 @@
+import type { ChannelAdapter, ChannelMessageHandler, OutgoingMessage } from "./channel.js";
+export interface SlackAdapterConfig {
+    botToken: string;
+    appToken: string;
+}
+export declare class SlackAdapter implements ChannelAdapter {
+    readonly channel = "slack";
+    readonly capabilities: import("./channel.js").ChannelCapabilities;
+    readonly combinesTextAndAttachmentsAtomically = true;
+    private readonly socket;
+    private readonly web;
+    private readonly botToken;
+    private readonly fetchFn;
+    constructor(config: SlackAdapterConfig, fetchFn?: typeof fetch);
+    run(handler: ChannelMessageHandler, signal: AbortSignal): Promise<void>;
+    send(target: string, message: OutgoingMessage): Promise<void>;
+}

package/dist/slack.js

@@ -0,0 +1,136 @@
+import { SocketModeClient } from "@slack/socket-mode";
+import { WebClient } from "@slack/web-api";
+import { BUILTIN_CHANNEL_CAPABILITIES } from "./channel.js";
+import { dispatchSafely, formatOutgoingMarkdown, waitForAbort } from "./lifecycle.js";
+import { mediaKind, outgoingAttachments, remoteAttachment } from "./media.js";
+export class SlackAdapter {
+    channel = "slack";
+    capabilities = BUILTIN_CHANNEL_CAPABILITIES.slack;
+    combinesTextAndAttachmentsAtomically = true;
+    socket;
+    web;
+    botToken;
+    fetchFn;
+    constructor(config, fetchFn = fetch) {
+        this.socket = new SocketModeClient({ appToken: config.appToken });
+        this.web = new WebClient(config.botToken);
+        this.botToken = config.botToken;
+        this.fetchFn = fetchFn;
+    }
+    async run(handler, signal) {
+        const onEvent = async ({ event, ack }) => {
+            if (event?.type !== "message" ||
+                typeof event.channel !== "string" ||
+                typeof event.user !== "string" ||
+                event.bot_id ||
+                (event.subtype && event.subtype !== "file_share")) {
+                await ack();
+                return;
+            }
+            const files = Array.isArray(event.files) ? event.files : [];
+            const attachments = files.flatMap((file) => {
+                const url = file.url_private_download ?? file.url_private;
+                if (!file.id || !url)
+                    return [];
+                return [
+                    remoteAttachment({
+                        id: file.id,
+                        kind: mediaKind(file.mimetype, file.name),
+                        name: file.name,
+                        mimeType: file.mimetype,
+                        size: file.size,
+                        url,
+                        headers: { authorization: `Bearer ${this.botToken}` },
+                        fetch: this.fetchFn,
+                    }),
+                ];
+            });
+            const text = typeof event.text === "string" ? event.text : "";
+            if (!text && attachments.length === 0) {
+                await ack();
+                return;
+            }
+            // dispatchSafely so a rejected delivery (e.g. inbox backpressure) never
+            // escapes this SocketMode listener as an unhandled rejection — emit does
+            // not await listeners, so an unhandled rejection would crash the process
+            // and skip the ack below.
+            await dispatchSafely(handler, {
+                channel: this.channel,
+                target: event.channel,
+                senderId: event.user,
+                text,
+                ...(event.client_msg_id || event.ts
+                    ? { messageId: String(event.client_msg_id ?? event.ts) }
+                    : {}),
+                ...(attachments.length > 0 ? { attachments } : {}),
+            });
+            await ack();
+        };
+        const onCommand = async ({ body, ack }) => {
+            if (typeof body.command !== "string" ||
+                typeof body.channel_id !== "string" ||
+                typeof body.user_id !== "string") {
+                await ack();
+                return;
+            }
+            await dispatchSafely(handler, {
+                channel: this.channel,
+                target: body.channel_id,
+                senderId: body.user_id,
+                text: [body.command, typeof body.text === "string" ? body.text : ""]
+                    .filter(Boolean)
+                    .join(" "),
+                ...(body.trigger_id ? { messageId: String(body.trigger_id) } : {}),
+            });
+            await ack();
+        };
+        this.socket.on("events_api", onEvent);
+        this.socket.on("slash_commands", onCommand);
+        await this.socket.start();
+        try {
+            await waitForAbort(signal);
+        }
+        finally {
+            this.socket.off("events_api", onEvent);
+            this.socket.off("slash_commands", onCommand);
+            await this.socket.disconnect();
+        }
+    }
+    async send(target, message) {
+        const attachments = outgoingAttachments(message, this.capabilities.outbound.attachments);
+        if (attachments.length > 0) {
+            // Slack's v2 upload can publish all files and the comment atomically,
+            // avoiding a text-first partial send that would duplicate on retry.
+            await this.web.filesUploadV2({
+                channel_id: target,
+                initial_comment: formatOutgoingMarkdown(message.text, message.button),
+                file_uploads: attachments.map((attachment) => ({
+                    file: Buffer.from(attachment.data),
+                    filename: attachment.name,
+                })),
+            });
+            return;
+        }
+        await this.web.chat.postMessage({
+            channel: target,
+            text: message.text,
+            ...(message.button
+                ? {
+                    blocks: [
+                        { type: "section", text: { type: "mrkdwn", text: message.text } },
+                        {
+                            type: "actions",
+                            elements: [
+                                {
+                                    type: "button",
+                                    text: { type: "plain_text", text: message.button.text },
+                                    url: message.button.url,
+                                },
+                            ],
+                        },
+                    ],
+                }
+                : {}),
+        });
+    }
+}

package/dist/teams.d.ts

@@ -0,0 +1,26 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ChannelMessageHandler, OutgoingMessage, WebhookChannelAdapter } from "./channel.js";
+export interface TeamsAdapterConfig {
+    appId: string;
+    appPassword: string;
+    appType?: string;
+    tenantId?: string;
+    statePath?: string;
+}
+export declare class TeamsAdapter implements WebhookChannelAdapter {
+    readonly channel = "teams";
+    readonly capabilities: import("./channel.js").ChannelCapabilities;
+    readonly combinesTextAndAttachmentsAtomically = true;
+    readonly webhookPath = "/webhooks/teams";
+    private readonly adapter;
+    private readonly appId;
+    private readonly contexts;
+    private readonly references;
+    private readonly statePath?;
+    constructor(config: TeamsAdapterConfig);
+    run(_handler: ChannelMessageHandler, signal: AbortSignal): Promise<void>;
+    handleWebhook(request: IncomingMessage, response: ServerResponse, handler: ChannelMessageHandler, maxBodyBytes: number): Promise<void>;
+    send(target: string, message: OutgoingMessage): Promise<void>;
+    private loadReferences;
+    private saveReferences;
+}