@n2world/orchestrator 1.1.0

package/dist/browser-agent.js

@@ -0,0 +1,223 @@
+"use strict";
+// ============================================================================
+// BrowserAgent — n2world 웹브라우저 제어 (의미 DOM 지각 #3 + 자동화 구동 #1)
+// ----------------------------------------------------------------------------
+// 설계(분석 결론): 지각=상호작용 요소의 의미 추출(접근성 역할+이름), 구동=Playwright(로컬).
+// 비전(#2)은 폴백, 클라우드(#4)는 기본 배제(헌법 제4조 로컬-only).
+//
+// 비용/CI 안전: Playwright 는 **동적 import(선택 설치)**. 미설치면 정직하게 안내한다
+//   (mock 으로 성공 연기 금지 — 제1계명). 순수 로직(요소 포맷·보안 스크린)은 브라우저 없이 검증.
+// 보안: 모든 액션은 screenBrowserAction 을 통과한다. 되돌릴 수 없는/금융/인증 행동은
+//   deny-by-default (결제·구매·삭제·제출·OAuth 동의 차단, 비밀번호/카드 입력 차단).
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserAgent = exports.PlaywrightBrowserController = void 0;
+exports.formatElements = formatElements;
+exports.screenBrowserAction = screenBrowserAction;
+/** 요소 목록을 LLM 친화 라인으로 압축(토큰 효율). 테스트용 export. */
+function formatElements(els, max = 60) {
+    if (!els.length)
+        return '(상호작용 가능한 요소 없음)';
+    const lines = els.slice(0, max).map((e) => `[${e.ref}] ${e.role} "${(e.name || '').replace(/\s+/g, ' ').slice(0, 80)}"`);
+    if (els.length > max)
+        lines.push(`… 외 ${els.length - max}개`);
+    return lines.join('\n');
+}
+// 되돌릴 수 없는/금융/인증 행동 키워드(클릭 차단). 안전 규칙과 정렬.
+const IRREVERSIBLE_RE = /\b(buy|purchase|pay|payment|checkout|order|place\s*order|subscribe|delete|remove|confirm|submit|authorize|consent|allow|grant|sign\s*up|withdraw|transfer)\b|결제|구매|주문|결제하기|삭제|제거|확인|동의|허용|승인|가입|이체|송금|출금|탈퇴/i;
+// 비밀/금융 입력 필드(타이핑 차단 — 자격증명·결제정보 입력 금지).
+const SECRET_FIELD_RE = /\b(password|passwd|pwd|card|cardnumber|cvv|cvc|ssn|secret|otp|pin|account\s*number)\b|비밀번호|카드(번호)?|주민(등록)?번호|보안코드|계좌번호|인증번호/i;
+/**
+ * 브라우저 액션 보안 스크린(deny-by-default for 위험).
+ * read/back/extract 는 허용, goto 는 http(s)만, click 은 금융/인증/되돌릴수없는 라벨이면 차단,
+ * type 은 비밀/결제 필드면 차단(자격증명 입력 금지).
+ */
+function screenBrowserAction(action, targetName = '') {
+    switch (action.verb) {
+        case 'read':
+        case 'back':
+        case 'extract':
+            return { allowed: true, reason: 'ok' };
+        case 'goto': {
+            const u = (action.url || '').trim();
+            if (!/^https?:\/\//i.test(u))
+                return { allowed: false, reason: 'goto 는 http(s) URL 만 허용(javascript:/file:/data: 차단)' };
+            return { allowed: true, reason: 'ok' };
+        }
+        case 'click':
+            if (IRREVERSIBLE_RE.test(targetName)) {
+                return { allowed: false, reason: `되돌릴 수 없는/금융/인증 행동 차단(대상: "${targetName}"). 사용자가 직접 수행해야 함.` };
+            }
+            return { allowed: true, reason: 'ok' };
+        case 'vclick': {
+            // 비전 폴백 클릭: 설명(query)을 금융/인증 키워드로 스크린(좌표 클릭도 동일 보안).
+            const desc = action.query || targetName;
+            if (IRREVERSIBLE_RE.test(desc)) {
+                return { allowed: false, reason: `되돌릴 수 없는/금융/인증 행동 차단(설명: "${desc}"). 사용자가 직접 수행해야 함.` };
+            }
+            return { allowed: true, reason: 'ok' };
+        }
+        case 'type':
+            if (SECRET_FIELD_RE.test(targetName)) {
+                return { allowed: false, reason: `비밀번호/결제정보 입력 차단(필드: "${targetName}"). 자격증명은 에이전트가 입력하지 않음.` };
+            }
+            return { allowed: true, reason: 'ok' };
+        default:
+            return { allowed: false, reason: `알 수 없는 액션: ${action.verb}` };
+    }
+}
+/**
+ * Playwright 기반 로컬 컨트롤러(#1 구동). Playwright 는 동적 import(선택 설치).
+ * 미설치 시 init() 이 명확히 throw → 상위에서 정직한 안내로 변환.
+ */
+class PlaywrightBrowserController {
+    headless;
+    browser = null;
+    page = null;
+    constructor(headless = true) {
+        this.headless = headless;
+    }
+    async init() {
+        let pw;
+        try {
+            const spec = 'playwright';
+            pw = await import(spec);
+        }
+        catch {
+            throw new Error("Playwright 미설치. 활성화: `npm i -D playwright && npx playwright install chromium` (로컬 전용).");
+        }
+        this.browser = await pw.chromium.launch({ headless: this.headless });
+        this.page = await this.browser.newPage();
+    }
+    async goto(url) {
+        await this.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    }
+    async readElements() {
+        // 페이지 내에서 상호작용 요소를 스캔하고 data-n2w-ref 를 부여(이후 click/type 의 안정적 셀렉터).
+        return await this.page.evaluate(() => {
+            const sel = 'a,button,input,textarea,select,[role=button],[role=link],[role=textbox],[onclick],[contenteditable=true]';
+            const nodes = Array.from(document.querySelectorAll(sel));
+            const out = [];
+            let i = 0;
+            for (const el of nodes) {
+                const style = window.getComputedStyle(el);
+                if (style.display === 'none' || style.visibility === 'hidden')
+                    continue;
+                const rect = el.getBoundingClientRect();
+                if (rect.width === 0 && rect.height === 0)
+                    continue;
+                const ref = 'e' + ++i;
+                el.setAttribute('data-n2w-ref', ref);
+                const role = el.getAttribute('role') || el.tagName.toLowerCase();
+                const name = el.getAttribute('aria-label') ||
+                    el.placeholder ||
+                    el.value ||
+                    (el.innerText || el.textContent || '').trim() ||
+                    el.getAttribute('name') ||
+                    '';
+                out.push({ ref, role, name: String(name).slice(0, 120) });
+                if (i >= 200)
+                    break;
+            }
+            return out;
+        });
+    }
+    async click(ref) {
+        await this.page.click(`[data-n2w-ref="${ref}"]`, { timeout: 10000 });
+    }
+    async type(ref, text) {
+        await this.page.fill(`[data-n2w-ref="${ref}"]`, text, { timeout: 10000 });
+    }
+    async extractText() {
+        return (await this.page.evaluate(() => document.body?.innerText || '')).slice(0, 8000);
+    }
+    async back() {
+        await this.page.goBack({ waitUntil: 'domcontentloaded' });
+    }
+    async screenshot() {
+        const buf = await this.page.screenshot({ type: 'png' });
+        const vp = this.page.viewportSize() || { width: 1280, height: 720 };
+        return { base64: buf.toString('base64'), width: vp.width, height: vp.height };
+    }
+    async clickAt(x, y) {
+        await this.page.mouse.click(x, y);
+    }
+    async close() {
+        try {
+            await this.browser?.close();
+        }
+        catch { /* noop */ }
+    }
+}
+exports.PlaywrightBrowserController = PlaywrightBrowserController;
+/**
+ * BrowserAgent — 지각(read)+구동(click/type/goto)을 보안 스크린으로 감싼 실행기.
+ * act() 가 LLM 도구(controlBrowser)의 백엔드가 된다. 모든 액션은 screenBrowserAction 통과.
+ */
+class BrowserAgent {
+    ctrl;
+    vision;
+    lastElements = new Map();
+    /** 비전 폴백 로케이터(선택). 없으면 vclick 은 안내만. */
+    constructor(ctrl, vision) {
+        this.ctrl = ctrl;
+        this.vision = vision;
+    }
+    /** 한 액션 실행 → 사람이 읽는/LLM이 읽는 결과 문자열. */
+    async act(action) {
+        // ref 대상의 이름을 알아내 보안 스크린에 전달(click/type).
+        const targetName = action.ref ? this.lastElements.get(action.ref)?.name ?? '' : '';
+        const screen = screenBrowserAction(action, targetName);
+        if (!screen.allowed)
+            return `[차단됨] ${screen.reason}`;
+        switch (action.verb) {
+            case 'goto':
+                await this.ctrl.goto(action.url);
+                return await this.refreshAndFormat(`이동: ${action.url}`);
+            case 'read':
+                return await this.refreshAndFormat('현재 페이지 요소:');
+            case 'click':
+                if (!action.ref)
+                    return '[오류] click 에는 ref 가 필요합니다(먼저 read).';
+                await this.ctrl.click(action.ref);
+                return await this.refreshAndFormat(`클릭: ${action.ref}`);
+            case 'type':
+                if (!action.ref)
+                    return '[오류] type 에는 ref 가 필요합니다(먼저 read).';
+                await this.ctrl.type(action.ref, action.text ?? '');
+                return await this.refreshAndFormat(`입력: ${action.ref}`);
+            case 'extract':
+                return (await this.ctrl.extractText()).slice(0, 4000);
+            case 'back':
+                await this.ctrl.back();
+                return await this.refreshAndFormat('뒤로 가기');
+            case 'vclick': {
+                // 비전 폴백(#2): DOM(read)으로 안 잡히는 캔버스/이미지 요소를 설명으로 클릭.
+                const desc = (action.query || '').trim();
+                if (!desc)
+                    return '[오류] vclick 에는 query(클릭할 요소 설명)가 필요합니다.';
+                if (!this.vision)
+                    return '[비전 미사용] 비전 로케이터가 없습니다. 가능하면 read→click 을 쓰세요(캔버스 전용일 때만 vclick).';
+                const shot = await this.ctrl.screenshot();
+                const loc = await this.vision(shot.base64, desc);
+                if (!loc)
+                    return `[비전] "${desc}" 위치를 찾지 못했습니다. 설명을 더 구체적으로 하거나 read 를 시도하세요.`;
+                const px = Math.round(Math.max(0, Math.min(1, loc.x)) * shot.width);
+                const py = Math.round(Math.max(0, Math.min(1, loc.y)) * shot.height);
+                await this.ctrl.clickAt(px, py);
+                return await this.refreshAndFormat(`비전 클릭: "${desc}" → (${px}, ${py})`);
+            }
+            default:
+                return `[오류] 알 수 없는 verb: ${action.verb}`;
+        }
+    }
+    async refreshAndFormat(prefix) {
+        const els = await this.ctrl.readElements();
+        this.lastElements = new Map(els.map((e) => [e.ref, e]));
+        return `${prefix}\n${formatElements(els)}`;
+    }
+    async close() {
+        await this.ctrl.close();
+    }
+}
+exports.BrowserAgent = BrowserAgent;

package/dist/channel-gateway.d.ts

@@ -0,0 +1,74 @@
+import { IChannel, ChannelName, InboundMessage, SendResult, FetchFn } from './channels';
+import { ChatTurn } from './llm';
+import { GovernedAgent } from './governed-llm';
+/** 에이전트 함수: 대화 히스토리 → 응답 텍스트. 테스트에서 주입 가능. */
+export type AgentFn = (history: ChatTurn[], sessionId: string) => Promise<string>;
+export interface ChannelStatus {
+    name: ChannelName;
+    configured: boolean;
+    inbound: string;
+}
+export interface InboundResult {
+    reply: string;
+    /** 자동 전송(폴링·슬랙)일 때의 전송 결과. 웹훅 응답형(디스코드·카카오)은 null. */
+    send: SendResult | null;
+    /** 허용목록 차단 등으로 에이전트를 호출하지 않았는가. */
+    blocked?: boolean;
+}
+/** HTTP 웹훅 응답(서버가 그대로 반환). */
+export interface WebhookResponse {
+    status: number;
+    body: unknown;
+}
+export declare class ChannelGateway {
+    private byName;
+    private agent;
+    private storeDir;
+    private polling;
+    private started;
+    /** 채널별 발신자 허용목록(설정 시 그 외는 차단). 미설정 채널은 전체 허용(하위 호환). */
+    private allowlist;
+    /** v2.5.2 거버넌스(opt-in). 설정 시 인입을 Tier 분류→가드→로컬/외부로 강제 라우팅한다. */
+    private governed?;
+    constructor(opts?: {
+        channels?: IChannel[];
+        agent?: AgentFn;
+        governed?: GovernedAgent;
+        storeDir?: string;
+        fetchFn?: FetchFn;
+        allowlist?: Partial<Record<ChannelName, string[]>>;
+    });
+    /** 거버넌스 라우터(설정 시) — Tier egress 감사 등 조회용. */
+    governedRef(): GovernedAgent | undefined;
+    /** 발신자가 허용되는가. 해당 채널 허용목록이 비어 있으면 전체 허용. */
+    isAllowed(channel: ChannelName, from: string): boolean;
+    /** 채널별 활성/인바운드 상태(정직 보고). */
+    status(): ChannelStatus[];
+    configuredChannels(): ChannelName[];
+    private storeFor;
+    /**
+     * 인바운드 1건 처리: 세션 대화 복원 → 에이전트 응답 → (autoSend 면) 채널로 전송.
+     * 세션 키는 채널:발신자. 대화는 영속된다.
+     */
+    handleInbound(msg: InboundMessage, autoSend?: boolean): Promise<InboundResult>;
+    /**
+     * 웹훅 수신 처리(Slack/Discord/Kakao). 플랫폼별 응답 규약을 지킨다:
+     *   - slack: challenge 응답 또는 200 ack 후 API 로 비동기 전송(autoSend).
+     *   - discord: PING→PONG(type1), 그 외엔 인터랙션 응답 본문(type4)에 답을 담는다.
+     *   - kakao: 오픈빌더 스킬 응답(simpleText) 본문에 답을 담는다.
+     */
+    webhook(channel: ChannelName, payload: any): Promise<WebhookResponse>;
+    /**
+     * 설정된 모든 채널의 인바운드를 시작한다(공개서버 불요):
+     *   - Telegram: 롱폴링 · Discord: Gateway WS · Slack: Socket Mode(SLACK_APP_TOKEN 필요).
+     * 반환: 전체 중단 함수. 어떤 채널이 시작됐는지 기록은 startedInbound() 로 확인.
+     */
+    startInbound(intervalMs?: number): Promise<() => void>;
+    /** startInbound 로 실제 시작된 채널 목록. */
+    startedInbound(): ChannelName[];
+    /**
+     * 폴링 시작(Telegram). 공개서버 없이 양방향 동작. stop() 반환.
+     * 설정된 telegram 채널이 없으면 no-op.
+     */
+    startPolling(intervalMs?: number): () => void;
+}

package/dist/channel-gateway.js

@@ -0,0 +1,270 @@
+"use strict";
+// ============================================================================
+// ChannelGateway — 메시징 채널 ↔ n2world 에이전트 라우팅 (Telegram/Slack/Discord/Kakao)
+// ----------------------------------------------------------------------------
+// 인바운드 메시지를 받아 에이전트(askAgentChat)로 라우팅하고, 응답을 채널로 돌려보낸다.
+// 세션별(채널:발신자) 대화는 ChatStore 로 영속·복원된다(CLI/웹/TUI 와 동일 보존소 패턴).
+//
+// 정직(제1계명): 자격증명이 없는 채널은 비활성으로 보고한다. 실제 송수신 성공은 토큰이
+//   있어야만 검증되며(그 전엔 (목표; 미측정)), mock 으로 성공을 연기하지 않는다.
+// ============================================================================
+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.ChannelGateway = void 0;
+const path = __importStar(require("path"));
+const channels_1 = require("./channels");
+const chat_store_1 = require("./chat-store");
+const llm_1 = require("./llm");
+const oracle_1 = require("./oracle");
+function sanitize(s) {
+    return s.replace(/[^\w.-]/g, '_').slice(0, 64);
+}
+class ChannelGateway {
+    byName = new Map();
+    agent;
+    storeDir;
+    polling = false;
+    started = [];
+    /** 채널별 발신자 허용목록(설정 시 그 외는 차단). 미설정 채널은 전체 허용(하위 호환). */
+    allowlist;
+    /** v2.5.2 거버넌스(opt-in). 설정 시 인입을 Tier 분류→가드→로컬/외부로 강제 라우팅한다. */
+    governed;
+    constructor(opts = {}) {
+        const channels = opts.channels ?? (0, channels_1.createDefaultChannels)(opts.fetchFn);
+        for (const c of channels)
+            this.byName.set(c.name, c);
+        this.storeDir = opts.storeDir ?? 'chat-data';
+        this.agent = opts.agent ?? defaultAgent();
+        this.governed = opts.governed;
+        this.allowlist = buildAllowlist(opts.allowlist);
+    }
+    /** 거버넌스 라우터(설정 시) — Tier egress 감사 등 조회용. */
+    governedRef() { return this.governed; }
+    /** 발신자가 허용되는가. 해당 채널 허용목록이 비어 있으면 전체 허용. */
+    isAllowed(channel, from) {
+        const set = this.allowlist[channel];
+        if (!set || set.size === 0)
+            return true;
+        return set.has(from);
+    }
+    /** 채널별 활성/인바운드 상태(정직 보고). */
+    status() {
+        return [...this.byName.values()].map((c) => ({ name: c.name, configured: c.isConfigured(), inbound: c.inbound }));
+    }
+    configuredChannels() {
+        return [...this.byName.values()].filter((c) => c.isConfigured()).map((c) => c.name);
+    }
+    storeFor(channel, from) {
+        return new chat_store_1.ChatStore(path.join(this.storeDir, `channel-${channel}-${sanitize(from)}.json`));
+    }
+    /**
+     * 인바운드 1건 처리: 세션 대화 복원 → 에이전트 응답 → (autoSend 면) 채널로 전송.
+     * 세션 키는 채널:발신자. 대화는 영속된다.
+     */
+    async handleInbound(msg, autoSend = true) {
+        const ch = this.byName.get(msg.channel);
+        if (!ch)
+            return { reply: '', send: { ok: false, reason: `unknown channel: ${msg.channel}` } };
+        // H1: 발신자 허용목록 — 허용되지 않으면 에이전트 호출 없이 차단(샌드박스 노출 최소화).
+        if (!this.isAllowed(msg.channel, msg.from)) {
+            return { reply: '', send: null, blocked: true };
+        }
+        const store = this.storeFor(msg.channel, msg.from);
+        store.load();
+        store.append({ role: 'user', content: msg.text });
+        let reply;
+        try {
+            if (this.governed) {
+                // v2.5.2: Tier 분류 → TierGuard → 로컬/외부 강제 라우팅(실 강제 지점).
+                reply = (await this.governed.respond(store.history())).text;
+            }
+            else {
+                reply = await this.agent(store.history(), `${msg.channel}:${msg.from}`);
+            }
+        }
+        catch (e) {
+            reply = `[오류] ${e?.message ?? e}`;
+        }
+        store.append({ role: 'assistant', content: reply });
+        if (autoSend) {
+            const send = await ch.send(msg.from, reply);
+            return { reply, send };
+        }
+        return { reply, send: null };
+    }
+    /**
+     * 웹훅 수신 처리(Slack/Discord/Kakao). 플랫폼별 응답 규약을 지킨다:
+     *   - slack: challenge 응답 또는 200 ack 후 API 로 비동기 전송(autoSend).
+     *   - discord: PING→PONG(type1), 그 외엔 인터랙션 응답 본문(type4)에 답을 담는다.
+     *   - kakao: 오픈빌더 스킬 응답(simpleText) 본문에 답을 담는다.
+     */
+    async webhook(channel, payload) {
+        if (channel === 'slack') {
+            if (payload?.type === 'url_verification')
+                return { status: 200, body: { challenge: payload.challenge } };
+            const msg = channels_1.SlackChannel.parseInbound(payload);
+            if (!msg)
+                return { status: 200, body: { ok: true } }; // 무시 대상(봇/비메시지)도 ack
+            await this.handleInbound(msg, true); // chat.postMessage 로 전송
+            return { status: 200, body: { ok: true } };
+        }
+        if (channel === 'discord') {
+            if (payload?.type === 1)
+                return { status: 200, body: { type: 1 } }; // PONG
+            const msg = channels_1.DiscordChannel.parseInbound(payload);
+            if (!msg)
+                return { status: 200, body: { type: 4, data: { content: '(처리할 수 없는 요청)' } } };
+            const { reply } = await this.handleInbound(msg, false);
+            return { status: 200, body: { type: 4, data: { content: reply } } };
+        }
+        if (channel === 'kakao') {
+            const msg = channels_1.KakaoTalkChannel.parseInbound(payload);
+            if (!msg)
+                return { status: 200, body: channels_1.KakaoTalkChannel.formatSkillResponse('(발화를 인식하지 못했습니다)') };
+            const { reply } = await this.handleInbound(msg, false);
+            return { status: 200, body: channels_1.KakaoTalkChannel.formatSkillResponse(reply) };
+        }
+        return { status: 400, body: { error: `webhook 미지원 채널: ${channel}` } };
+    }
+    /**
+     * 설정된 모든 채널의 인바운드를 시작한다(공개서버 불요):
+     *   - Telegram: 롱폴링 · Discord: Gateway WS · Slack: Socket Mode(SLACK_APP_TOKEN 필요).
+     * 반환: 전체 중단 함수. 어떤 채널이 시작됐는지 기록은 startedInbound() 로 확인.
+     */
+    async startInbound(intervalMs = 1500) {
+        const stops = [];
+        this.started = [];
+        const tg = this.byName.get('telegram');
+        if (tg?.isConfigured()) {
+            stops.push(this.startPolling(intervalMs));
+            this.started.push('telegram');
+        }
+        const dc = this.byName.get('discord');
+        if (dc?.isConfigured() && typeof dc.connectGateway === 'function') {
+            stops.push(dc.connectGateway((m) => void this.handleInbound(m, true)));
+            this.started.push('discord');
+        }
+        const sl = this.byName.get('slack');
+        const appToken = (process.env.SLACK_APP_TOKEN || '').trim();
+        if (sl?.isConfigured() && appToken && typeof sl.connectSocketMode === 'function') {
+            try {
+                stops.push(await sl.connectSocketMode(appToken, (m) => void this.handleInbound(m, true)));
+                this.started.push('slack');
+            }
+            catch (e) {
+                // 정직: 연결 실패는 숨기지 않는다(토큰/스코프 문제 등).
+                // eslint-disable-next-line no-console
+                console.error('[slack] Socket Mode 연결 실패:', e?.message ?? e);
+            }
+        }
+        return () => { for (const s of stops) {
+            try {
+                s();
+            }
+            catch { /* noop */ }
+        } };
+    }
+    /** startInbound 로 실제 시작된 채널 목록. */
+    startedInbound() {
+        return [...this.started];
+    }
+    /**
+     * 폴링 시작(Telegram). 공개서버 없이 양방향 동작. stop() 반환.
+     * 설정된 telegram 채널이 없으면 no-op.
+     */
+    startPolling(intervalMs = 1500) {
+        const tg = this.byName.get('telegram');
+        if (!tg || !tg.isConfigured() || typeof tg.poll !== 'function') {
+            return () => { };
+        }
+        this.polling = true;
+        const loop = async () => {
+            while (this.polling) {
+                try {
+                    const msgs = await tg.poll(20);
+                    for (const m of msgs)
+                        await this.handleInbound(m, true);
+                }
+                catch {
+                    /* 일시 오류는 다음 주기에 재시도 */
+                }
+                await new Promise((r) => setTimeout(r, intervalMs));
+            }
+        };
+        void loop();
+        return () => {
+            this.polling = false;
+        };
+    }
+}
+exports.ChannelGateway = ChannelGateway;
+/** 환경변수에서 채널별 허용목록(<CHANNEL>_ALLOWED_IDS, 쉼표 구분)을 만든다. */
+function buildAllowlist(override) {
+    const out = {};
+    const chans = ['telegram', 'slack', 'discord', 'kakao'];
+    for (const c of chans) {
+        const ids = override?.[c] ?? (process.env[`${c.toUpperCase()}_ALLOWED_IDS`] || '').split(',').map((s) => s.trim()).filter(Boolean);
+        if (ids.length)
+            out[c] = new Set(ids);
+    }
+    return out;
+}
+/**
+ * 기본 에이전트: 샌드박스 도구 + askAgentChat. 채널 세션 히스토리를 그대로 사용.
+ * H2: 채널 입력은 신뢰 불가하므로, 도구 실행 전에 oracle 규칙 스크린으로 **알려진 파괴적 명령을
+ *     거부**한다(rm-rf·fork-bomb·디스크 덮어쓰기 등). 통과한 명령만 샌드박스에서 실행.
+ */
+function defaultAgent() {
+    let runShell = null;
+    const oracle = new oracle_1.CrossValidationOracle();
+    return async (history) => {
+        if (!runShell) {
+            // 지연 초기화(테스트가 agent 를 주입하면 여기 도달하지 않음).
+            const { LocalSandbox, WorkerAgent } = await import('./index.js');
+            const sandbox = new LocalSandbox();
+            await sandbox.init();
+            const worker = new WorkerAgent(sandbox);
+            runShell = async (cmd) => {
+                const screen = oracle.screenDangerousAction(cmd);
+                if (screen.flagged) {
+                    return `[차단됨] 위험 명령으로 거부되었습니다(규칙: ${screen.matched.join(', ')}). 채널 입력은 파괴적 명령을 실행할 수 없습니다.`;
+                }
+                const res = await worker.executeTask(cmd);
+                return `[cmd: ${cmd}]\n${res.stdout}\n${res.stderr}`;
+            };
+        }
+        return (0, llm_1.askAgentChat)(history, runShell);
+    };
+}