@n2world/orchestrator 1.1.0

package/dist/channels.d.ts

@@ -0,0 +1,120 @@
+export type ChannelName = 'telegram' | 'slack' | 'discord' | 'kakao';
+/** 인바운드 메시지(채널 수신 → 에이전트로 라우팅). */
+export interface InboundMessage {
+    channel: ChannelName;
+    /** 답장 대상 식별자(telegram chat_id, slack channel, discord channel id, kakao user id). */
+    from: string;
+    text: string;
+}
+export interface SendResult {
+    ok: boolean;
+    reason?: string;
+    /** 플랫폼 응답(디버그/검증용). */
+    raw?: unknown;
+}
+/** 인바운드 능력 분류(정직). socket=WS 푸시(공개서버 불요). */
+export type InboundMode = 'poll' | 'webhook' | 'socket' | 'none';
+/** WS 인바운드 연결 해제 함수. */
+export type Disconnect = () => void;
+export type FetchFn = (url: string, init?: any) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<any>;
+    text: () => Promise<string>;
+}>;
+export interface IChannel {
+    readonly name: ChannelName;
+    /** 인바운드 방식(정직 — 구현 가능 범위). */
+    readonly inbound: InboundMode;
+    /** 자격증명이 설정돼 실제 동작 가능한가. */
+    isConfigured(): boolean;
+    /** 아웃바운드 전송(실 HTTP). 미설정이면 ok:false('미설정'). */
+    send(to: string, text: string): Promise<SendResult>;
+}
+export declare class TelegramChannel implements IChannel {
+    private token;
+    private fetchFn?;
+    readonly name: "telegram";
+    readonly inbound: InboundMode;
+    private offset;
+    constructor(token?: string, fetchFn?: FetchFn | undefined);
+    isConfigured(): boolean;
+    send(chatId: string, text: string): Promise<SendResult>;
+    /** 롱폴링 1회 — 새 메시지들을 반환하고 offset 을 갱신한다(공개서버 불필요). */
+    poll(timeoutSec?: number): Promise<InboundMessage[]>;
+}
+export declare class SlackChannel implements IChannel {
+    private token;
+    private fetchFn?;
+    readonly name: "slack";
+    readonly inbound: InboundMode;
+    constructor(token?: string, fetchFn?: FetchFn | undefined);
+    isConfigured(): boolean;
+    send(channel: string, text: string): Promise<SendResult>;
+    /** Events API 페이로드 파싱. url_verification(challenge)·봇 자신/비-메시지는 null. */
+    static parseInbound(payload: any): InboundMessage | null;
+    /**
+     * Slack 웹훅 서명 검증(v0 HMAC-SHA256). 위조·재전송 차단.
+     * sig = 'v0=' + HMAC(signingSecret, `v0:${ts}:${rawBody}`), |now-ts| ≤ 300s, 타이밍 안전 비교.
+     */
+    static verifySignature(rawBody: string, signature: string | undefined, timestamp: string | undefined, signingSecret: string): boolean;
+    /** Socket Mode 봉투 파싱 → InboundMessage|null. events_api·slash_commands 지원. */
+    static parseSocketEnvelope(env: any): InboundMessage | null;
+    /**
+     * Slack Socket Mode 연결(공개 URL 불요). app-level token(xapp-, connections:write)으로
+     * apps.connections.open → WSS 접속, 이벤트 봉투를 ack 하고 메시지를 onMessage 로 넘긴다.
+     * 정직: 실제 수신은 app/bot 토큰·스코프가 있어야 검증됨(그 전엔 미측정).
+     */
+    connectSocketMode(appToken: string, onMessage: (m: InboundMessage) => void): Promise<Disconnect>;
+}
+/** Discord Gateway intents: GUILDS|GUILD_MESSAGES|DIRECT_MESSAGES|MESSAGE_CONTENT. */
+export declare const DISCORD_INTENTS: number;
+export declare class DiscordChannel implements IChannel {
+    private token;
+    private fetchFn?;
+    readonly name: "discord";
+    readonly inbound: InboundMode;
+    constructor(token?: string, fetchFn?: FetchFn | undefined);
+    isConfigured(): boolean;
+    send(channelId: string, text: string): Promise<SendResult>;
+    /** 인터랙션(슬래시 커맨드) 웹훅 파싱. PING(type 1)·비-메시지는 null. */
+    static parseInbound(payload: any): InboundMessage | null;
+    /**
+     * Discord 인터랙션 웹훅 서명 검증(Ed25519, 명세상 필수). 위조 차단.
+     * message = timestamp + rawBody, X-Signature-Ed25519 를 앱 공개키로 검증.
+     */
+    static verifySignature(rawBody: string, signatureHex: string | undefined, timestamp: string | undefined, publicKeyHex: string): boolean;
+    /** IDENTIFY(op 2) 페이로드. */
+    static identifyPayload(token: string, intents?: number): any;
+    /** Gateway MESSAGE_CREATE 데이터(d) → InboundMessage|null. 봇/빈 메시지는 null. */
+    static gatewayMessageToInbound(d: any): InboundMessage | null;
+    /**
+     * Discord Gateway WebSocket 연결(공개 URL 불요). HELLO(op10)→하트비트+IDENTIFY,
+     * MESSAGE_CREATE(op0) 수신 시 onMessage. 끊기면 재연결.
+     * 정직: MESSAGE_CONTENT 는 특권 인텐트 — 개발자 포털에서 활성화해야 본문이 온다.
+     *   실제 수신은 토큰·인텐트가 있어야 검증됨(그 전엔 미측정).
+     */
+    connectGateway(onMessage: (m: InboundMessage) => void): Disconnect;
+}
+export declare class KakaoTalkChannel implements IChannel {
+    private accessToken;
+    private fetchFn?;
+    readonly name: "kakao";
+    readonly inbound: InboundMode;
+    constructor(accessToken?: string, fetchFn?: FetchFn | undefined);
+    isConfigured(): boolean;
+    /** '나에게 보내기'(memo/default) — 텍스트 템플릿. to 는 무시(항상 인증 사용자 본인). */
+    send(_to: string, text: string): Promise<SendResult>;
+    /**
+     * Kakao 오픈빌더 웹훅 검증. 카카오는 표준 서명이 없으므로 **공유 비밀 헤더**로 보호한다.
+     * configuredSecret 설정 시 헤더 값과 타이밍 안전 비교, 미설정 시 false(보안 기본 — 호출측에서
+     * 로컬바인딩 등 별도 정책 결정). 즉 명시적 비밀 없이는 웹훅 수용을 보장하지 않는다.
+     */
+    static verifyWebhook(headerSecret: string | undefined, configuredSecret: string): boolean;
+    /** 카카오 i 오픈빌더 스킬 웹훅 파싱: { userRequest: { utterance, user:{id} } }. */
+    static parseInbound(payload: any): InboundMessage | null;
+    /** 오픈빌더 스킬 응답 포맷(simpleText). 웹훅 응답으로 그대로 반환한다. */
+    static formatSkillResponse(text: string): any;
+}
+/** 환경변수 기준으로 4채널 인스턴스를 만든다(미설정 채널도 포함 — isConfigured 로 판별). */
+export declare function createDefaultChannels(fetchFn?: FetchFn): IChannel[];

package/dist/channels.js

@@ -0,0 +1,432 @@
+"use strict";
+// ============================================================================
+// 채널 어댑터 — Telegram / Slack / Discord / KakaoTalk (메시징 게이트웨이)
+// ----------------------------------------------------------------------------
+// 정직 고지(제1계명): 이 모듈은 각 플랫폼 HTTP API 로 **실제 전송**을 시도한다(SDK 미사용, fetch).
+//   그러나 자격증명(토큰) 없이는 비활성이며, 실제 전송 성공은 토큰이 있어야만 검증된다
+//   → 토큰 부재 시 send 는 ok:false('미설정')를 정직히 반환한다. mock 으로 성공을 연기하지 않는다.
+//
+// 인바운드(수신) 능력은 플랫폼마다 다르다(정직):
+//   - Telegram: getUpdates 롱폴링 → 공개서버 없이 로컬에서 양방향 가능.
+//   - Slack:    Events API 웹훅(공개 URL 필요). 본 모듈은 페이로드 파싱·서명검증 제공.
+//   - Discord:  일반 메시지 수신은 Gateway WebSocket 필요(미구현). 아웃바운드/인터랙션 웹훅만.
+//   - KakaoTalk: 개방형 양방향 봇 API 없음. 아웃바운드='나에게 보내기'(자기 자신).
+//                인바운드는 카카오 i 오픈빌더 '스킬 웹훅'(사업자 채널) 페이로드 파싱 제공.
+// ============================================================================
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KakaoTalkChannel = exports.DiscordChannel = exports.DISCORD_INTENTS = exports.SlackChannel = exports.TelegramChannel = void 0;
+exports.createDefaultChannels = createDefaultChannels;
+const crypto = __importStar(require("crypto"));
+/** 길이 안전 + 타이밍 안전 문자열 비교(서명 검증용). */
+function timingSafeEqual(a, b) {
+    const ba = Buffer.from(a, 'utf8');
+    const bb = Buffer.from(b, 'utf8');
+    if (ba.length !== bb.length)
+        return false;
+    return crypto.timingSafeEqual(ba, bb);
+}
+function getWebSocket() {
+    const W = globalThis.WebSocket;
+    if (!W)
+        throw new Error('global WebSocket 이 없습니다(Node 21+ 필요).');
+    return W;
+}
+function getFetch(injected) {
+    if (injected)
+        return injected;
+    const f = globalThis.fetch;
+    if (!f)
+        throw new Error('global fetch 가 없습니다(Node 18+ 필요).');
+    return f;
+}
+// ─────────────────────────── Telegram ───────────────────────────
+class TelegramChannel {
+    token;
+    fetchFn;
+    name = 'telegram';
+    inbound = 'poll';
+    offset = 0;
+    constructor(token = process.env.TELEGRAM_BOT_TOKEN || '', fetchFn) {
+        this.token = token;
+        this.fetchFn = fetchFn;
+    }
+    isConfigured() {
+        return !!this.token.trim();
+    }
+    async send(chatId, text) {
+        if (!this.isConfigured())
+            return { ok: false, reason: 'TELEGRAM_BOT_TOKEN 미설정' };
+        const fetch = getFetch(this.fetchFn);
+        const res = await fetch(`https://api.telegram.org/bot${this.token}/sendMessage`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ chat_id: chatId, text }),
+        });
+        const body = await res.json().catch(() => ({}));
+        return { ok: res.ok && body?.ok !== false, reason: res.ok ? undefined : `HTTP ${res.status}`, raw: body };
+    }
+    /** 롱폴링 1회 — 새 메시지들을 반환하고 offset 을 갱신한다(공개서버 불필요). */
+    async poll(timeoutSec = 30) {
+        if (!this.isConfigured())
+            return [];
+        const fetch = getFetch(this.fetchFn);
+        const res = await fetch(`https://api.telegram.org/bot${this.token}/getUpdates?timeout=${timeoutSec}&offset=${this.offset}`, { method: 'GET' });
+        const body = await res.json().catch(() => ({}));
+        const out = [];
+        for (const u of body?.result ?? []) {
+            this.offset = Math.max(this.offset, (u.update_id ?? 0) + 1);
+            const msg = u.message ?? u.edited_message;
+            if (msg?.text && msg.chat?.id != null)
+                out.push({ channel: 'telegram', from: String(msg.chat.id), text: msg.text });
+        }
+        return out;
+    }
+}
+exports.TelegramChannel = TelegramChannel;
+// ─────────────────────────── Slack ───────────────────────────
+class SlackChannel {
+    token;
+    fetchFn;
+    name = 'slack';
+    // Socket Mode(WS) 로 공개서버 없이 수신. 웹훅(Events API) 파싱도 지원.
+    inbound = 'socket';
+    constructor(token = process.env.SLACK_BOT_TOKEN || '', fetchFn) {
+        this.token = token;
+        this.fetchFn = fetchFn;
+    }
+    isConfigured() {
+        return !!this.token.trim();
+    }
+    async send(channel, text) {
+        if (!this.isConfigured())
+            return { ok: false, reason: 'SLACK_BOT_TOKEN 미설정' };
+        const fetch = getFetch(this.fetchFn);
+        const res = await fetch('https://slack.com/api/chat.postMessage', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json; charset=utf-8', Authorization: `Bearer ${this.token}` },
+            body: JSON.stringify({ channel, text }),
+        });
+        const body = await res.json().catch(() => ({}));
+        return { ok: !!body?.ok, reason: body?.ok ? undefined : body?.error || `HTTP ${res.status}`, raw: body };
+    }
+    /** Events API 페이로드 파싱. url_verification(challenge)·봇 자신/비-메시지는 null. */
+    static parseInbound(payload) {
+        if (!payload || typeof payload !== 'object')
+            return null;
+        if (payload.type === 'url_verification')
+            return null; // challenge 는 별도 처리
+        const e = payload.event;
+        if (payload.type === 'event_callback' && e?.type === 'message' && e.text && !e.bot_id && !e.subtype) {
+            return { channel: 'slack', from: String(e.channel), text: String(e.text) };
+        }
+        return null;
+    }
+    /**
+     * Slack 웹훅 서명 검증(v0 HMAC-SHA256). 위조·재전송 차단.
+     * sig = 'v0=' + HMAC(signingSecret, `v0:${ts}:${rawBody}`), |now-ts| ≤ 300s, 타이밍 안전 비교.
+     */
+    static verifySignature(rawBody, signature, timestamp, signingSecret) {
+        if (!signingSecret || !signature || !timestamp)
+            return false;
+        const ts = parseInt(timestamp, 10);
+        if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > 300)
+            return false; // 재전송 방지
+        const base = `v0:${timestamp}:${rawBody}`;
+        const expected = 'v0=' + crypto.createHmac('sha256', signingSecret).update(base).digest('hex');
+        return timingSafeEqual(expected, signature);
+    }
+    /** Socket Mode 봉투 파싱 → InboundMessage|null. events_api·slash_commands 지원. */
+    static parseSocketEnvelope(env) {
+        if (!env || typeof env !== 'object')
+            return null;
+        if (env.type === 'events_api')
+            return SlackChannel.parseInbound(env.payload);
+        if (env.type === 'slash_commands' && env.payload?.text) {
+            return { channel: 'slack', from: String(env.payload.channel_id), text: String(env.payload.text) };
+        }
+        return null;
+    }
+    /**
+     * Slack Socket Mode 연결(공개 URL 불요). app-level token(xapp-, connections:write)으로
+     * apps.connections.open → WSS 접속, 이벤트 봉투를 ack 하고 메시지를 onMessage 로 넘긴다.
+     * 정직: 실제 수신은 app/bot 토큰·스코프가 있어야 검증됨(그 전엔 미측정).
+     */
+    async connectSocketMode(appToken, onMessage) {
+        if (!appToken?.trim())
+            return () => { };
+        const fetch = getFetch(this.fetchFn);
+        const WS = getWebSocket();
+        let ws = null;
+        let closed = false;
+        const open = async () => {
+            const res = await fetch('https://slack.com/api/apps.connections.open', {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${appToken}`, 'Content-Type': 'application/x-www-form-urlencoded' },
+            });
+            const j = await res.json().catch(() => ({}));
+            if (!j?.ok || !j.url)
+                throw new Error(`apps.connections.open 실패: ${j?.error || `HTTP ${res.status}`}`);
+            ws = new WS(j.url);
+            ws.onmessage = (ev) => {
+                let env;
+                try {
+                    env = JSON.parse(ev.data);
+                }
+                catch {
+                    return;
+                }
+                if (env.type === 'hello' || env.type === 'disconnect') {
+                    if (env.type === 'disconnect' && !closed)
+                        void open().catch(() => { });
+                    return;
+                }
+                if (env.envelope_id) {
+                    try {
+                        ws.send(JSON.stringify({ envelope_id: env.envelope_id }));
+                    }
+                    catch { /* ack 실패 무시 */ }
+                }
+                const m = SlackChannel.parseSocketEnvelope(env);
+                if (m)
+                    onMessage(m);
+            };
+            ws.onclose = () => { if (!closed)
+                setTimeout(() => void open().catch(() => { }), 3000); };
+            ws.onerror = () => { };
+        };
+        await open();
+        return () => { closed = true; try {
+            ws?.close();
+        }
+        catch { /* noop */ } };
+    }
+}
+exports.SlackChannel = SlackChannel;
+// ─────────────────────────── Discord ───────────────────────────
+/** Discord Gateway intents: GUILDS|GUILD_MESSAGES|DIRECT_MESSAGES|MESSAGE_CONTENT. */
+exports.DISCORD_INTENTS = (1 << 0) | (1 << 9) | (1 << 12) | (1 << 15);
+class DiscordChannel {
+    token;
+    fetchFn;
+    name = 'discord';
+    // Gateway WebSocket 으로 일반 메시지 수신(공개서버 불요). 인터랙션 웹훅 파싱도 지원.
+    inbound = 'socket';
+    constructor(token = process.env.DISCORD_BOT_TOKEN || '', fetchFn) {
+        this.token = token;
+        this.fetchFn = fetchFn;
+    }
+    isConfigured() {
+        return !!this.token.trim();
+    }
+    async send(channelId, text) {
+        if (!this.isConfigured())
+            return { ok: false, reason: 'DISCORD_BOT_TOKEN 미설정' };
+        const fetch = getFetch(this.fetchFn);
+        const res = await fetch(`https://discord.com/api/v10/channels/${channelId}/messages`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: `Bot ${this.token}` },
+            body: JSON.stringify({ content: text }),
+        });
+        const body = await res.json().catch(() => ({}));
+        return { ok: res.ok, reason: res.ok ? undefined : body?.message || `HTTP ${res.status}`, raw: body };
+    }
+    /** 인터랙션(슬래시 커맨드) 웹훅 파싱. PING(type 1)·비-메시지는 null. */
+    static parseInbound(payload) {
+        if (!payload || typeof payload !== 'object')
+            return null;
+        if (payload.type === 1)
+            return null; // PING
+        if (payload.type === 2 && payload.data) {
+            const opt = (payload.data.options ?? []).find((o) => o?.value);
+            const text = opt?.value ?? payload.data.name;
+            const from = payload.channel_id ?? payload.channel?.id;
+            if (text && from)
+                return { channel: 'discord', from: String(from), text: String(text) };
+        }
+        return null;
+    }
+    /**
+     * Discord 인터랙션 웹훅 서명 검증(Ed25519, 명세상 필수). 위조 차단.
+     * message = timestamp + rawBody, X-Signature-Ed25519 를 앱 공개키로 검증.
+     */
+    static verifySignature(rawBody, signatureHex, timestamp, publicKeyHex) {
+        if (!publicKeyHex || !signatureHex || !timestamp)
+            return false;
+        try {
+            // raw 32바이트 Ed25519 공개키를 SPKI DER 로 감싼다(고정 프리픽스).
+            const der = Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), Buffer.from(publicKeyHex, 'hex')]);
+            const pub = crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
+            return crypto.verify(null, Buffer.from(timestamp + rawBody), pub, Buffer.from(signatureHex, 'hex'));
+        }
+        catch {
+            return false;
+        }
+    }
+    /** IDENTIFY(op 2) 페이로드. */
+    static identifyPayload(token, intents = exports.DISCORD_INTENTS) {
+        return { op: 2, d: { token, intents, properties: { os: 'linux', browser: 'n2world', device: 'n2world' } } };
+    }
+    /** Gateway MESSAGE_CREATE 데이터(d) → InboundMessage|null. 봇/빈 메시지는 null. */
+    static gatewayMessageToInbound(d) {
+        if (!d || d.author?.bot)
+            return null;
+        if (!d.content || !d.channel_id)
+            return null;
+        return { channel: 'discord', from: String(d.channel_id), text: String(d.content) };
+    }
+    /**
+     * Discord Gateway WebSocket 연결(공개 URL 불요). HELLO(op10)→하트비트+IDENTIFY,
+     * MESSAGE_CREATE(op0) 수신 시 onMessage. 끊기면 재연결.
+     * 정직: MESSAGE_CONTENT 는 특권 인텐트 — 개발자 포털에서 활성화해야 본문이 온다.
+     *   실제 수신은 토큰·인텐트가 있어야 검증됨(그 전엔 미측정).
+     */
+    connectGateway(onMessage) {
+        if (!this.isConfigured())
+            return () => { };
+        const WS = getWebSocket();
+        let ws = null;
+        let hb = null;
+        let seq = null;
+        let closed = false;
+        const connect = () => {
+            ws = new WS('wss://gateway.discord.gg/?v=10&encoding=json');
+            ws.onmessage = (ev) => {
+                let m;
+                try {
+                    m = JSON.parse(ev.data);
+                }
+                catch {
+                    return;
+                }
+                if (m.s != null)
+                    seq = m.s;
+                if (m.op === 10) {
+                    const interval = m.d?.heartbeat_interval ?? 41250;
+                    hb = setInterval(() => { try {
+                        ws.send(JSON.stringify({ op: 1, d: seq }));
+                    }
+                    catch { /* noop */ } }, interval);
+                    ws.send(JSON.stringify(DiscordChannel.identifyPayload(this.token)));
+                }
+                else if (m.op === 0 && m.t === 'MESSAGE_CREATE') {
+                    const im = DiscordChannel.gatewayMessageToInbound(m.d);
+                    if (im)
+                        onMessage(im);
+                }
+            };
+            ws.onclose = () => { if (hb)
+                clearInterval(hb); if (!closed)
+                setTimeout(connect, 3000); };
+            ws.onerror = () => { };
+        };
+        connect();
+        return () => { closed = true; if (hb)
+            clearInterval(hb); try {
+            ws?.close();
+        }
+        catch { /* noop */ } };
+    }
+}
+exports.DiscordChannel = DiscordChannel;
+// ─────────────────────────── KakaoTalk ───────────────────────────
+// 정직: 개방형 양방향 봇 API 없음. 아웃바운드='나에게 보내기'(자기 자신, Kakao OAuth access token).
+//        인바운드=카카오 i 오픈빌더 스킬 웹훅 페이로드 파싱(사업자 채널 필요).
+class KakaoTalkChannel {
+    accessToken;
+    fetchFn;
+    name = 'kakao';
+    inbound = 'webhook';
+    constructor(accessToken = process.env.KAKAO_ACCESS_TOKEN || '', fetchFn) {
+        this.accessToken = accessToken;
+        this.fetchFn = fetchFn;
+    }
+    isConfigured() {
+        return !!this.accessToken.trim();
+    }
+    /** '나에게 보내기'(memo/default) — 텍스트 템플릿. to 는 무시(항상 인증 사용자 본인). */
+    async send(_to, text) {
+        if (!this.isConfigured())
+            return { ok: false, reason: 'KAKAO_ACCESS_TOKEN 미설정' };
+        const fetch = getFetch(this.fetchFn);
+        const template = {
+            object_type: 'text',
+            text: text.slice(0, 200), // 카카오 텍스트 템플릿 길이 제한(보수적)
+            link: { web_url: 'https://localhost', mobile_web_url: 'https://localhost' },
+        };
+        const form = `template_object=${encodeURIComponent(JSON.stringify(template))}`;
+        const res = await fetch('https://kapi.kakao.com/v2/api/talk/memo/default/send', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded;charset=utf-8', Authorization: `Bearer ${this.accessToken}` },
+            body: form,
+        });
+        const body = await res.json().catch(() => ({}));
+        // 카카오 성공 시 {result_code:0}.
+        return { ok: res.ok && body?.result_code === 0, reason: res.ok ? undefined : body?.msg || `HTTP ${res.status}`, raw: body };
+    }
+    /**
+     * Kakao 오픈빌더 웹훅 검증. 카카오는 표준 서명이 없으므로 **공유 비밀 헤더**로 보호한다.
+     * configuredSecret 설정 시 헤더 값과 타이밍 안전 비교, 미설정 시 false(보안 기본 — 호출측에서
+     * 로컬바인딩 등 별도 정책 결정). 즉 명시적 비밀 없이는 웹훅 수용을 보장하지 않는다.
+     */
+    static verifyWebhook(headerSecret, configuredSecret) {
+        if (!configuredSecret)
+            return false;
+        if (!headerSecret)
+            return false;
+        return timingSafeEqual(configuredSecret, headerSecret);
+    }
+    /** 카카오 i 오픈빌더 스킬 웹훅 파싱: { userRequest: { utterance, user:{id} } }. */
+    static parseInbound(payload) {
+        const ur = payload?.userRequest;
+        if (ur?.utterance)
+            return { channel: 'kakao', from: String(ur.user?.id ?? 'self'), text: String(ur.utterance) };
+        return null;
+    }
+    /** 오픈빌더 스킬 응답 포맷(simpleText). 웹훅 응답으로 그대로 반환한다. */
+    static formatSkillResponse(text) {
+        return { version: '2.0', template: { outputs: [{ simpleText: { text } }] } };
+    }
+}
+exports.KakaoTalkChannel = KakaoTalkChannel;
+/** 환경변수 기준으로 4채널 인스턴스를 만든다(미설정 채널도 포함 — isConfigured 로 판별). */
+function createDefaultChannels(fetchFn) {
+    return [
+        new TelegramChannel(undefined, fetchFn),
+        new SlackChannel(undefined, fetchFn),
+        new DiscordChannel(undefined, fetchFn),
+        new KakaoTalkChannel(undefined, fetchFn),
+    ];
+}

package/dist/chat-store.d.ts

@@ -0,0 +1,29 @@
+import { ChatTurn } from './llm';
+/** 기본 대화 보존 경로(로컬). beta-data 와 분리. */
+export declare const DEFAULT_CHAT_HISTORY_PATH: string;
+export declare class ChatStore {
+    private readonly filePath;
+    /** 보존 상한(턴 수). 초과분은 앞에서 절단 — 메모리·파일·토큰 통제. */
+    private readonly maxTurns;
+    private turns;
+    constructor(filePath?: string, 
+    /** 보존 상한(턴 수). 초과분은 앞에서 절단 — 메모리·파일·토큰 통제. */
+    maxTurns?: number);
+    /**
+     * 디스크에서 복원한다(파일 없음/손상이면 빈 히스토리 — 정직, 가짜 복원 금지).
+     * 반환은 복원된 턴 배열(내부 상태와 동일 참조 아님 — 복사본).
+     */
+    load(): ChatTurn[];
+    /** 현재 히스토리(복사본). */
+    history(): ChatTurn[];
+    count(): number;
+    /** 한 턴 추가 + 즉시 영속(다운돼도 직전 턴까지 보존). 상한 초과분은 앞에서 절단. */
+    append(turn: ChatTurn): void;
+    /** 원자적 쓰기(임시파일 → rename) — 쓰는 도중 죽어도 기존 파일이 깨지지 않는다. */
+    private persist;
+    /** 히스토리 비우기(메모리 + 디스크 파일 제거). */
+    clear(): void;
+    /** 사람이 읽는 마크다운으로 내보내기(복구·공유용). */
+    exportMarkdown(): string;
+    path_(): string;
+}