@phuetz/code-buddy 1.0.0 → 1.2.0

package/dist/channels/feishu/index.js

@@ -9,7 +9,148 @@
  * identity-aware headers, full thread context.
  */
 import { logger } from '../../utils/logger.js';
-import { BaseChannel } from '../core.js';
+import { BaseChannel, } from '../core.js';
+/** Map a Feishu `message_type` onto a Code Buddy {@link ContentType}. */
+function feishuMessageTypeToContentType(messageType) {
+    switch (messageType) {
+        case 'image':
+            return 'image';
+        case 'audio':
+            return 'audio';
+        case 'media':
+            return 'video';
+        case 'file':
+            return 'file';
+        case 'sticker':
+            return 'sticker';
+        // 'text', 'post', 'interactive', 'share_chat', … all surface as text.
+        default:
+            return 'text';
+    }
+}
+/**
+ * Best-effort plain-text extraction from a Feishu message `content` JSON string.
+ *
+ * - `text`     → `{ "text": "hello" }`
+ * - `post`     → `{ "<locale>": { "title": "...", "content": [[{tag,text}, …]] } }`
+ * - otherwise  → the raw JSON string (so callers still see *something*).
+ */
+function extractFeishuText(messageType, contentJson) {
+    if (!contentJson)
+        return '';
+    let parsed;
+    try {
+        parsed = JSON.parse(contentJson);
+    }
+    catch {
+        // Not JSON (shouldn't happen for real events) — fall back to the raw string.
+        return contentJson;
+    }
+    if (parsed && typeof parsed === 'object') {
+        const obj = parsed;
+        // text / share_chat / etc.
+        if (typeof obj.text === 'string')
+            return obj.text;
+        // post: locale-keyed rich text. Walk the first locale's `content` matrix
+        // and concatenate every `text` segment.
+        if (messageType === 'post' || (!('text' in obj) && hasPostShape(obj))) {
+            const localeKey = Object.keys(obj)[0];
+            const post = localeKey ? obj[localeKey] : undefined;
+            const rows = post?.['content'];
+            if (Array.isArray(rows)) {
+                const pieces = [];
+                const title = typeof post?.['title'] === 'string' ? post['title'] : '';
+                if (title)
+                    pieces.push(title);
+                for (const row of rows) {
+                    if (!Array.isArray(row))
+                        continue;
+                    for (const seg of row) {
+                        if (seg && typeof seg === 'object') {
+                            const t = seg.text;
+                            if (typeof t === 'string')
+                                pieces.push(t);
+                        }
+                    }
+                }
+                return pieces.join(' ').trim();
+            }
+        }
+    }
+    // Unknown structure — return the raw JSON so nothing is silently dropped.
+    return contentJson;
+}
+function hasPostShape(obj) {
+    const firstKey = Object.keys(obj)[0];
+    if (!firstKey)
+        return false;
+    const v = obj[firstKey];
+    return !!v && typeof v === 'object' && 'content' in v;
+}
+/**
+ * Parse a Lark `im.message.receive_v1` event into a Code Buddy
+ * {@link InboundMessage}.
+ *
+ * Envelope-tolerant: accepts either the unwrapped event body (what the SDK's
+ * `EventDispatcher` hands the handler) or the full `{ schema, header, event }`
+ * webhook envelope.
+ *
+ * Returns `null` when the event carries no usable message (e.g. a non-message
+ * event slipped through, or no chat/text could be resolved).
+ */
+export function parseFeishuMessageEvent(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    // Unwrap `{ event: … }` if present; otherwise treat `raw` as the body.
+    const body = 'event' in raw && raw.event ? raw.event : raw;
+    const message = body.message;
+    if (!message)
+        return null;
+    const chatId = message.chat_id;
+    if (!chatId)
+        return null;
+    const senderId = body.sender?.sender_id?.open_id ??
+        body.sender?.sender_id?.union_id ??
+        body.sender?.sender_id?.user_id ??
+        'unknown';
+    const content = extractFeishuText(message.message_type, message.content);
+    const createTimeMs = message.create_time ? Number(message.create_time) : NaN;
+    const timestamp = Number.isFinite(createTimeMs) ? new Date(createTimeMs) : new Date();
+    const inbound = {
+        id: message.message_id ?? `feishu_${Date.now()}`,
+        channel: {
+            id: chatId,
+            type: 'feishu',
+            isDM: message.chat_type === 'p2p',
+            isGroup: message.chat_type === 'group',
+        },
+        sender: {
+            id: senderId,
+            raw: body.sender,
+        },
+        content,
+        contentType: feishuMessageTypeToContentType(message.message_type),
+        timestamp,
+        raw,
+    };
+    if (message.thread_id)
+        inbound.threadId = message.thread_id;
+    if (message.parent_id)
+        inbound.replyTo = message.parent_id;
+    return inbound;
+}
+/**
+ * Legacy in-process adapter.
+ *
+ * The real outbound transport now lives in {@link FeishuChannel}, which mints a
+ * genuine `tenant_access_token` and POSTs through the REST `im/v1/messages`
+ * API. This class is retained for its still-useful, network-free helpers — the
+ * interactive-card builders, reasoning-stream hooks, and `getThreadMessages`
+ * (exercised by `tests/channels/feishu-cards.test.ts`). Its `sendText` /
+ * `sendCard` / `sendImage` / `replyMessage` methods, however, perform NO
+ * network I/O and return synthetic ids; they are kept only for backward-compat
+ * and are not on the real send path. Prefer {@link FeishuChannel.send}.
+ */
 export class FeishuAdapter {
     config;
     running = false;
@@ -39,6 +180,7 @@ export class FeishuAdapter {
     isRunning() {
         return this.running;
     }
+    /** @deprecated No network I/O — returns a synthetic id. Use {@link FeishuChannel.send}. */
     async sendText(chatId, text) {
         if (!this.running) {
             throw new Error('FeishuAdapter is not running');
@@ -47,6 +189,7 @@ export class FeishuAdapter {
         logger.debug('FeishuAdapter: send text', { chatId, textLength: text.length });
         return { success: true, messageId };
     }
+    /** @deprecated No network I/O — returns a synthetic id. Use {@link FeishuChannel.send}. */
     async sendCard(chatId, card) {
         if (!this.running) {
             throw new Error('FeishuAdapter is not running');
@@ -55,6 +198,7 @@ export class FeishuAdapter {
         logger.debug('FeishuAdapter: send card', { chatId });
         return { success: true, messageId };
     }
+    /** @deprecated No network I/O — returns a synthetic id. Use {@link FeishuChannel.send}. */
     async sendImage(chatId, imageKey) {
         if (!this.running) {
             throw new Error('FeishuAdapter is not running');
@@ -63,6 +207,7 @@ export class FeishuAdapter {
         logger.debug('FeishuAdapter: send image', { chatId, imageKey });
         return { success: true, messageId };
     }
+    /** @deprecated No network I/O. Use {@link FeishuChannel.send} with `replyTo` instead. */
     async replyMessage(messageId, text) {
         if (!this.running) {
             throw new Error('FeishuAdapter is not running');
@@ -194,11 +339,46 @@ export class FeishuAdapter {
         return [];
     }
 }
+// ============================================================================
+// Real-transport status
+// ============================================================================
+const DEFAULT_FEISHU_BASE_URL = 'https://open.feishu.cn';
 export class FeishuChannel extends BaseChannel {
     adapter = null;
+    baseUrl;
+    /** Cached tenant_access_token (re-minted on demand if the API rejects it). */
+    tenantToken = null;
+    receiveStatus = null;
+    /** Live official-SDK long-connection client, when the SDK is installed. */
+    wsClient = null;
     constructor(config) {
         super('feishu', config);
+        const rawBase = config.options?.['baseUrl'] ??
+            process.env.FEISHU_BASE_URL ??
+            process.env.LARK_BASE_URL ??
+            DEFAULT_FEISHU_BASE_URL;
+        this.baseUrl = rawBase.trim().replace(/\/+$/, '');
     }
+    /**
+     * Bring the channel up.
+     *
+     * Outbound (`send()`) is fully functional: it lazily mints a
+     * `tenant_access_token` and POSTs to `/open-apis/im/v1/messages`.
+     *
+     * Inbound (receiving user messages) requires Feishu's proprietary
+     * long-connection — see {@link FeishuReceiveStatus}. We do NOT fake it. We
+     * attempt to bring up the REAL inbound socket using the official Lark SDK
+     * (`@larksuiteoapi/node-sdk`), imported OPTIONALLY at runtime — it is not a
+     * declared dependency, so most installs won't have it. When it IS present
+     * (and app credentials are configured) we start its `WSClient` and register
+     * the `im.message.receive_v1` handler, which parses each message into an
+     * {@link InboundMessage} and re-emits it via `this.emit('message' | 'command')`.
+     * The SDK owns the long-connection + reconnect internally.
+     *
+     * When the SDK is absent (the default) we keep the honest "send-only" state:
+     * `status.connected = false`, the receive reason surfaced in
+     * `status.error` / `status.info`. No throw — outbound still works.
+     */
     async connect() {
         const cfg = this.config;
         this.adapter = new FeishuAdapter({
@@ -209,28 +389,185 @@ export class FeishuChannel extends BaseChannel {
             port: cfg.port,
         });
         await this.adapter.start();
-        this.status.connected = true;
+        // Default to the honest send-only state. `tryStartInbound()` upgrades it
+        // in place if (and only if) the optional SDK is installed and usable.
+        this.receiveStatus = {
+            connected: false,
+            reason: 'lark-sdk-required',
+            detail: 'Feishu inbound long-connection (real-time receive) is not active: the ' +
+                'official Lark SDK (@larksuiteoapi/node-sdk) — which owns the proprietary ' +
+                "Protobuf 'pbbp2' long-connection framing — is not installed (it is an " +
+                'optional dependency). Install it and configure app credentials to enable ' +
+                'real-time receive. Outbound send() is fully functional via the REST ' +
+                'im/v1/messages API.',
+        };
+        this.status.connected = false;
+        this.status.authenticated = false;
+        this.status.error = this.receiveStatus.detail;
+        this.status.info = {
+            outbound: 'ready',
+            inbound: this.receiveStatus.reason,
+        };
+        await this.tryStartInbound(cfg);
+    }
+    /**
+     * Attempt to bring up the REAL inbound long-connection via the optional
+     * official Lark SDK. Mutates `this.receiveStatus` / `this.status` to the live
+     * `'lark-ws'` state on success; otherwise leaves the honest send-only state
+     * untouched. Never throws — a missing SDK or a start() failure degrades
+     * gracefully to outbound-only.
+     */
+    async tryStartInbound(cfg) {
+        // Optional dependency: the `as string` specifier keeps TS/Vite from trying
+        // to statically resolve a package that isn't installed, so this becomes a
+        // genuine runtime import that rejects (→ caught) when the SDK is absent.
+        const lark = (await import('@larksuiteoapi/node-sdk').catch(() => null));
+        if (!lark || typeof lark.WSClient !== 'function' || typeof lark.EventDispatcher !== 'function') {
+            // SDK not installed — keep the honest 'lark-sdk-required' state.
+            return;
+        }
+        if (!cfg.appId || !cfg.appSecret) {
+            // SDK present but unconfigured — still send-only. Keep the reason code
+            // (`lark-sdk-required`, so the honest-state contract holds) but correct
+            // the detail: the SDK is here; the missing piece is app credentials.
+            logger.warn('Feishu: Lark SDK installed but appId/appSecret missing — inbound disabled');
+            if (this.receiveStatus) {
+                this.receiveStatus.detail =
+                    'Feishu inbound long-connection is not active: the official Lark SDK ' +
+                        '(@larksuiteoapi/node-sdk) IS installed, but appId/appSecret are not ' +
+                        'configured, so the WSClient cannot authenticate. Provide app credentials ' +
+                        'to enable real-time receive. Outbound send() is fully functional.';
+                this.status.error = this.receiveStatus.detail;
+            }
+            return;
+        }
+        try {
+            const dispatcher = new lark.EventDispatcher({}).register({
+                'im.message.receive_v1': (data) => {
+                    try {
+                        this.dispatchInboundEvent(data);
+                    }
+                    catch (err) {
+                        logger.warn(`Feishu inbound handler error: ${err instanceof Error ? err.message : err}`);
+                    }
+                },
+            });
+            const wsClient = new lark.WSClient({
+                appId: cfg.appId,
+                appSecret: cfg.appSecret,
+            });
+            await wsClient.start({ eventDispatcher: dispatcher });
+            this.wsClient = wsClient;
+            this.receiveStatus = {
+                connected: true,
+                reason: 'lark-ws',
+                detail: 'Feishu inbound is live over the official Lark SDK WSClient long-connection ' +
+                    '(@larksuiteoapi/node-sdk). im.message.receive_v1 events are parsed into ' +
+                    'InboundMessages and re-emitted; the SDK manages reconnect internally.',
+            };
+            this.status.connected = true;
+            this.status.authenticated = true;
+            delete this.status.error;
+            this.status.info = { outbound: 'ready', inbound: 'lark-ws' };
+            this.status.lastActivity = new Date();
+            logger.info('Feishu: inbound long-connection established via @larksuiteoapi/node-sdk');
+        }
+        catch (err) {
+            // start() failed (bad creds, network). Stay honest: send-only.
+            logger.warn(`Feishu: Lark WSClient failed to start, falling back to send-only: ${err instanceof Error ? err.message : err}`);
+            this.wsClient = null;
+        }
+    }
+    /**
+     * Parse a raw `im.message.receive_v1` event and re-emit it as a Code Buddy
+     * `message` (and `command`) event. This is the seam the live SDK handler
+     * delegates to; it is also unit-testable directly without a live tenant.
+     *
+     * @returns the parsed {@link InboundMessage}, or `null` if the event carried
+     *   no usable message.
+     */
+    dispatchInboundEvent(event) {
+        const parsed = parseFeishuMessageEvent(event);
+        if (!parsed)
+            return null;
+        // Skip messages from the bot itself / disallowed users where configured.
+        if (!this.isUserAllowed(parsed.sender.id))
+            return null;
+        if (!this.isChannelAllowed(parsed.channel.id))
+            return null;
+        const withCommand = this.parseCommand(parsed);
+        this.status.lastActivity = new Date();
+        this.emit('message', withCommand);
+        if (withCommand.isCommand) {
+            this.emit('command', withCommand);
+        }
+        return withCommand;
     }
     async disconnect() {
+        if (this.wsClient) {
+            try {
+                await this.wsClient.stop?.();
+            }
+            catch (err) {
+                logger.debug(`Feishu: WSClient stop error: ${err instanceof Error ? err.message : err}`);
+            }
+            this.wsClient = null;
+        }
         if (this.adapter) {
             await this.adapter.stop();
             this.adapter = null;
         }
+        this.tenantToken = null;
+        this.receiveStatus = null;
         this.status.connected = false;
+        this.status.authenticated = false;
+        delete this.status.error;
+        this.emit('disconnected', this.type);
     }
+    /**
+     * Send an outbound message through the real Feishu REST API.
+     *
+     * Cards are sent with `msg_type: 'interactive'`; everything else as
+     * `msg_type: 'text'`. The chat id (`message.channelId`) becomes the
+     * `receive_id` with `receive_id_type=chat_id`.
+     */
     async send(message) {
         if (!this.adapter) {
             return { success: false, error: 'Not connected', timestamp: new Date() };
         }
         const chatId = message.channelId || '';
-        // Send as card if channelData.feishu.card is provided
+        if (!chatId) {
+            return { success: false, error: 'Missing channelId (Feishu chat_id)', timestamp: new Date() };
+        }
         const feishuData = message.channelData?.feishu;
+        let msgType;
+        let content;
         if (feishuData?.card) {
-            const result = await this.adapter.sendCard(chatId, feishuData.card);
-            return { success: result.success, messageId: result.messageId, timestamp: new Date() };
+            msgType = 'interactive';
+            content = JSON.stringify(feishuData.card);
+        }
+        else {
+            msgType = 'text';
+            content = JSON.stringify({ text: message.content });
+        }
+        try {
+            return await this.postMessage(chatId, msgType, content);
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                timestamp: new Date(),
+            };
         }
-        const result = await this.adapter.sendText(chatId, message.content);
-        return { success: result.success, messageId: result.messageId, timestamp: new Date() };
+    }
+    /**
+     * Honest, structured account of the inbound receive channel. Returns `null`
+     * before `connect()` has run; otherwise a {@link FeishuReceiveStatus}
+     * explaining why no live socket exists.
+     */
+    getReceiveStatus() {
+        return this.receiveStatus;
     }
     /**
      * Get the underlying adapter (for direct card/reasoning API access).
@@ -238,5 +575,93 @@ export class FeishuChannel extends BaseChannel {
     getAdapter() {
         return this.adapter;
     }
+    // ==========================================================================
+    // REST outbound (real)
+    // ==========================================================================
+    /**
+     * POST a message to `/open-apis/im/v1/messages`, minting (and caching) a
+     * tenant_access_token first. On an auth-class failure the token is dropped
+     * and the call retried once with a fresh token.
+     */
+    async postMessage(chatId, msgType, content, retried = false) {
+        const token = await this.ensureTenantToken();
+        const url = `${this.baseUrl}/open-apis/im/v1/messages?receive_id_type=chat_id`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json; charset=utf-8',
+            },
+            body: JSON.stringify({ receive_id: chatId, msg_type: msgType, content }),
+        });
+        const text = await response.text().catch(() => '');
+        let parsed = {};
+        try {
+            parsed = text ? JSON.parse(text) : {};
+        }
+        catch {
+            parsed = {};
+        }
+        const code = typeof parsed.code === 'number' ? parsed.code : undefined;
+        // Feishu signals an expired/invalid tenant token with a non-zero `code`
+        // (99991663/99991664/...) and HTTP 200. Drop the cached token and retry once.
+        if (!retried && (code === 99991663 || code === 99991664 || response.status === 401)) {
+            this.tenantToken = null;
+            return this.postMessage(chatId, msgType, content, true);
+        }
+        if (!response.ok || (code !== undefined && code !== 0)) {
+            const msg = typeof parsed.msg === 'string' ? parsed.msg : text.slice(0, 300);
+            return {
+                success: false,
+                error: `Feishu send failed: status=${response.status} code=${code ?? 'n/a'} msg=${msg}`,
+                timestamp: new Date(),
+            };
+        }
+        const data = (parsed.data ?? {});
+        const messageId = typeof data.message_id === 'string' ? data.message_id : undefined;
+        this.status.lastActivity = new Date();
+        const result = { success: true, timestamp: new Date() };
+        if (messageId)
+            result.messageId = messageId;
+        return result;
+    }
+    /**
+     * Return a cached tenant_access_token, minting one via
+     * `/open-apis/auth/v3/tenant_access_token/internal` if needed. This is the
+     * same internal-app credential exchange used by `src/tools/feishu-tool.ts`.
+     */
+    async ensureTenantToken() {
+        if (this.tenantToken)
+            return this.tenantToken;
+        const cfg = this.config;
+        if (!cfg.appId || !cfg.appSecret) {
+            throw new Error('Feishu appId/appSecret are required to mint a tenant_access_token');
+        }
+        const response = await fetch(`${this.baseUrl}/open-apis/auth/v3/tenant_access_token/internal`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json; charset=utf-8' },
+            body: JSON.stringify({ app_id: cfg.appId, app_secret: cfg.appSecret }),
+        });
+        const text = await response.text().catch(() => '');
+        let parsed = {};
+        try {
+            parsed = text ? JSON.parse(text) : {};
+        }
+        catch {
+            parsed = {};
+        }
+        const code = typeof parsed.code === 'number' ? parsed.code : undefined;
+        if (!response.ok || (code !== undefined && code !== 0)) {
+            const msg = typeof parsed.msg === 'string' ? parsed.msg : text.slice(0, 300);
+            throw new Error(`Feishu tenant_access_token request failed: status=${response.status} code=${code ?? 'n/a'} msg=${msg}`);
+        }
+        const token = typeof parsed.tenant_access_token === 'string' ? parsed.tenant_access_token : '';
+        if (!token) {
+            throw new Error('Feishu tenant_access_token response missing tenant_access_token');
+        }
+        this.tenantToken = token;
+        this.status.authenticated = true;
+        return token;
+    }
 }
 //# sourceMappingURL=index.js.map

package/dist/channels/gateway-lifecycle.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Gateway Lifecycle Manager
+ *
+ * Unified lifecycle management (start/stop/restart/status) for the
+ * messaging gateway subsystem. Tracks which channel adapters are
+ * currently active and provides per-channel readiness information.
+ */
+import { EventEmitter } from 'events';
+import type { ChannelType } from './core.js';
+import { ChannelManager } from './core.js';
+/**
+ * Per-channel readiness state
+ */
+export type ChannelReadiness = 'connected' | 'disconnected' | 'error' | 'not-configured';
+/**
+ * Per-channel status entry in the gateway status report
+ */
+export interface GatewayChannelStatus {
+    /** Channel type identifier */
+    channelId: ChannelType;
+    /** Current readiness state */
+    readiness: ChannelReadiness;
+    /** Whether the channel is authenticated */
+    authenticated: boolean;
+    /** Last activity timestamp (ISO string) */
+    lastActivity?: string;
+    /** Error message if readiness is 'error' */
+    error?: string;
+    /** Additional platform-specific info */
+    info?: Record<string, unknown>;
+}
+/**
+ * Full gateway status report
+ */
+export interface GatewayStatus {
+    /** Overall gateway health */
+    ok: boolean;
+    /** Timestamp of this report */
+    generatedAt: string;
+    /** Total number of registered channels */
+    totalChannels: number;
+    /** Number of connected channels */
+    connectedCount: number;
+    /** Number of channels in error state */
+    errorCount: number;
+    /** Number of disconnected channels */
+    disconnectedCount: number;
+    /** Per-channel status entries */
+    channels: GatewayChannelStatus[];
+}
+/**
+ * Events emitted by the GatewayLifecycleManager
+ */
+export interface GatewayLifecycleEvents {
+    'channel:started': (channelId: ChannelType) => void;
+    'channel:stopped': (channelId: ChannelType) => void;
+    'channel:error': (channelId: ChannelType, error: Error) => void;
+    'gateway:started': () => void;
+    'gateway:stopped': () => void;
+}
+/**
+ * Manages the lifecycle of the messaging gateway and its channel adapters.
+ *
+ * Wraps the existing ChannelManager with explicit start/stop/restart/status
+ * semantics for individual channels and the entire gateway.
+ */
+export declare class GatewayLifecycleManager extends EventEmitter {
+    private manager;
+    private activeChannels;
+    private channelErrors;
+    constructor(manager?: ChannelManager);
+    /**
+     * Get the underlying ChannelManager.
+     */
+    getManager(): ChannelManager;
+    /**
+     * Start a single channel adapter by its channel type.
+     *
+     * The channel must already be registered with the ChannelManager.
+     * This calls connect() on the adapter and marks it as active.
+     *
+     * @param channelId - The channel type to start
+     * @throws Error if the channel is not registered
+     */
+    start(channelId: ChannelType): Promise<void>;
+    /**
+     * Stop a single channel adapter by its channel type.
+     *
+     * Calls disconnect() on the adapter and removes it from the active set.
+     *
+     * @param channelId - The channel type to stop
+     * @throws Error if the channel is not registered
+     */
+    stop(channelId: ChannelType): Promise<void>;
+    /**
+     * Restart a single channel adapter (stop + start).
+     *
+     * @param channelId - The channel type to restart
+     */
+    restart(channelId: ChannelType): Promise<void>;
+    /**
+     * Start all registered channel adapters.
+     */
+    startAll(): Promise<void>;
+    /**
+     * Stop all active channel adapters.
+     */
+    stopAll(): Promise<void>;
+    /**
+     * Get the full gateway status report.
+     *
+     * Aggregates per-channel readiness from the ChannelManager's status,
+     * the active set, and any recorded errors.
+     */
+    status(): GatewayStatus;
+    /**
+     * Check whether a specific channel is currently active.
+     */
+    isActive(channelId: ChannelType): boolean;
+    /**
+     * Get the set of currently active channel IDs.
+     */
+    getActiveChannels(): ChannelType[];
+}
+/**
+ * Get the singleton GatewayLifecycleManager instance.
+ */
+export declare function getGatewayLifecycle(): GatewayLifecycleManager;
+/**
+ * Reset the singleton (for testing).
+ */
+export declare function resetGatewayLifecycle(): void;