@fcg-labs/cx-agent-hook 0.2.3 → 0.3.0

package/MIGRATION.md

@@ -0,0 +1,87 @@
+# 0.2.x → 0.3.0 마이그레이션
+
+## 요약 — 깨지는 것은 없다
+
+0.2.x 의 루트 표면(`createCxHook`)·어댑터(`/react` `/vue` `/element` …)·
+클래스명(`fcx-*`)은 **전부 그대로 동작한다** (기존 시험 94건 무수정 통과).
+0.3.0 은 그 아래 구조를 객체화하고 새 표면을 **추가**한 릴리스다.
+
+```js
+// 0.2.x — 그대로 유효
+import { createCxHook } from "@fcg-labs/cx-agent-hook";
+
+// 0.3.0 — 문의별 세션·초안 영속이 필요하면 이걸로 올라온다
+import { createCxAgent } from "@fcg-labs/cx-agent-hook/agent";
+```
+
+## 왜 올라오나 — 0.2.x 훅의 구조적 한계 2가지
+
+0.2.x 훅은 **채택 슬롯이 훅 전역 하나**이고 **초안이 화면(컴포넌트) 상태**다.
+그 귀결로 스테이징 실사용에서 두 결함이 실증됐다 (2026-08-10):
+
+1. 다른 메뉴를 다녀오면 AI 초안이 사라진다 (컴포넌트 언마운트 = 초안 소멸)
+2. 스트림 도중 문의를 전환하면 이전 문의 텍스트가 새 에디터를 오염할 수 있다
+
+0.3.0 세션은 **초안의 정본을 세션 버퍼**에 두고 UI 를 탈착식 sink 로 분리해
+두 결함을 구조의 귀결로 없앤다.
+
+## 새 표면 한 눈에
+
+```js
+const agent = createCxAgent({
+  baseUrl, token, domain,          // 전송 3요소 (0.2.x 와 동일)
+  source: "cms",                   // 인그레스 채널명 (테넌트 선언)
+  draftDecorators: [/* 기본: 한국어 호칭 개인화. 비한국어면 [] */],
+  storage: { ttlMs: 30 * 60_000, maxSessions: 20 },  // 초안 영속 정책
+});
+
+const session = agent.session(csId);          // 문의별 — 같은 id = 같은 세션
+session.attachUi({ getDraft, setDraft, setStatus });
+session.restore();                            // 복귀 시 초안·채택 복원 한 줄
+session.compose({ inquiry, context });        // 이탈해도 버퍼로 완주
+session.remember(editorText);                 // 상담사 편집을 정본에 반영
+session.answerSent(finalText, agentId);       // gold 쌍 후킹 + 세션 소멸
+```
+
+## 훅 → 세션 대응표
+
+| 0.2.x (`createCxHook`)        | 0.3.0 (`agent.session(id)`)      |
+|-------------------------------|----------------------------------|
+| `composeDraft({...sink})`     | `attachUi(sink)` + `compose({})` |
+| `noteAdopted / clearAdopted`  | 동명 메서드                      |
+| `answerSent/scored/edited/discarded` | 동명 메서드 (consume 규칙 동일) |
+| `adoptedAnswerId`             | `session.adoptedAnswerId`        |
+| (없음 — 결함의 원천)          | `detachUi()` · `restore()` · `remember()` |
+| `requestAnswer / inquirySent / ready / flags / messages` | agent 동명 메서드 |
+
+## 행동 변화 (호환층 아님 — 원장 어휘)
+
+- 문의 전환 시 CMS 가 쏘던 `discarded(note:"inquiry_switch")` 는 세션
+  구조에서 **불필요해진다** (전환은 더 이상 오염이 아니다). 대신 수명 종료
+  어휘가 늘었다: `session_expired`(TTL 만료) · `session_evicted`(LRU 퇴거).
+  원장 통계를 사유별로 보던 곳은 note 어휘에 이 둘을 반영할 것.
+- 초안이 sessionStorage 에 남는다 (탭 수명 + TTL, 발송·폐기 시 즉시 삭제).
+  브라우저 공용 PC 정책이 있으면 `storage: { enabled: false }`.
+
+## CSS — 고객 제어권
+
+토큰 선언이 `.fcx-ai` 에서 **사용처 `var(--fcx-*, 폴백)` 직참조**로 바뀌었다.
+이제 소비처 전역 한 줄로 팔레트를 바꾼다:
+
+```css
+:root { --fcx-accent: #7c3aed; --fcx-radius: 6px; }
+[data-fcx-theme="dark"] { /* 다크는 조상 속성으로 켠다 */ }
+```
+
+0.2.x 처럼 `.fcx-ai { --fcx-accent: … }` 로 덮던 코드도 그대로 동작한다
+(더 구체적인 선언이 이긴다). 클래스명 리네임은 없다.
+
+headless 2단계: ① 스타일 0 — styles.css 를 import 하지 않는다.
+② UI 0 — 어댑터 대신 `aiSuggestTree`(view.js)와 세션 표면만 쓴다.
+
+## 기타
+
+- `AnswerResult.answerId` 타입이 `number|string|null` — 신원 수술(ULID)
+  이후 허브 발급분은 문자열이다. 불투명 취급하면 코드 변경은 없다.
+- element 어댑터의 내부 DOM 구조는 동일하나, 어댑터 3종이 `aiSuggestTree`
+  인터프리터로 재구현됐다 — 클래스·이벤트·마크업 계약은 시험으로 고정.

package/README.md

@@ -30,6 +30,33 @@ npm install @fcg-labs/cx-agent-hook
 React·Vue 어댑터를 쓸 때만 그 프레임워크가 필요하다 (optional peer). 전송 계층만
 쓰면 의존성은 0 이다.
 
+## 0.3.0 — 문의별 세션 (권장 표면)
+
+`createCxHook` 은 그대로 동작한다(호환층). 문의별 초안 상태·영속이 필요한
+관리자 화면은 세션 표면으로 올라온다 — **초안의 정본이 세션 버퍼**라 메뉴
+이탈·문의 전환에도 AI 초안이 살아남고, 스트림은 화면과 무관하게 완주한다:
+
+```js
+import { createCxAgent } from "@fcg-labs/cx-agent-hook/agent";
+
+const agent = createCxAgent({ baseUrl, token, domain });
+const session = agent.session(inquiryId);           // 같은 id = 같은 세션
+session.attachUi({ getDraft, setDraft, setStatus });
+session.restore();                                  // 복귀 시 초안 복원 한 줄
+session.compose({ inquiry, context });              // 이탈해도 버퍼로 완주
+session.remember(editorText);                       // 상담사 편집 반영
+session.answerSent(finalText, agentId);             // 발송 후킹 + 세션 소멸
+```
+
+테넌트 특수분은 파라미터다: `source`(인그레스 채널명, 기본 "cms"),
+`draftDecorators`(초안 후처리 — 기본 한국어 호칭 개인화, 비한국어는 `[]`),
+`storage`(sessionStorage TTL·LRU 정책). 상세와 훅→세션 대응표는
+[MIGRATION.md](./MIGRATION.md).
+
+CSS 는 사용처 `var(--fcx-*, 폴백)` 직참조라 소비처 `:root` 한 줄로 팔레트를
+바꾼다. 다크는 조상에 `data-fcx-theme="dark"`. headless 2단계(스타일 0 /
+UI 0 — `aiSuggestTree`)도 공식 표면이다.
+
 ## 지원 프레임워크
 
 | 진입점 | 대상 | 필요한 peer |

package/agent.d.ts

@@ -0,0 +1,126 @@
+/**
+ * 0.3.0 객체 표면 — CxAgent + InquirySession.
+ *
+ * 보편 구조(설정·전송·문구·채택 수명·세션·영속)는 코어가 소유하고, 테넌트
+ * 특수분(source·draftDecorators·storage)은 파라미터다. 전송 계층 타입은
+ * client.d.ts 에 있고 여기서 다시 내보내지 않는다.
+ */
+import type { AnswerResult, CxAgentConfig } from "./client.js";
+import type { Locale } from "./index.js";
+
+export type { AnswerResult };
+export { LOCALES, MESSAGES, normalizeLocale } from "./index.js";
+
+/** 초안 후처리 데코레이터 — 사슬로 적용된다 (예: 호칭 개인화) */
+export type DraftDecorator = (
+  text: string,
+  ctx: { customerName?: string },
+) => string;
+
+/** 세션 영속 정책 (sessionStorage) */
+export interface SessionStorageConfig {
+  /** false 면 영속 없이 메모리 세션만 (기본 true) */
+  enabled?: boolean;
+  /** 초안 보존 시한 — 기본 30분. 만료는 discarded(session_expired)로 원장에 남는다 */
+  ttlMs?: number;
+  /** 동시 보존 세션 수 — 기본 20. 초과는 LRU 퇴거(session_evicted) */
+  maxSessions?: number;
+  /** 저장 키 접두 — 기본 `cx-agent-session:<domain>` */
+  prefix?: string;
+  /** 저장소 주입 (시험·커스텀) — 기본 sessionStorage */
+  impl?: Pick<Storage, "getItem" | "setItem" | "removeItem">;
+}
+
+export type CxAgentSetup = Partial<CxAgentConfig> & {
+  locale?: string;
+  bootstrap?: boolean;
+  messages?: Record<string, string>;
+  /** 인그레스 채널명 (테넌트 선언) — 기본 "cms" */
+  source?: string;
+  /** 초안 후처리 사슬 — 기본 [koreanGreetingDecorator]. 비한국어 테넌트는 [] */
+  draftDecorators?: DraftDecorator[];
+  storage?: SessionStorageConfig;
+};
+
+export interface ComposeHandle {
+  promise: Promise<AnswerResult>;
+  abort: () => void;
+}
+
+export interface SessionUi {
+  getDraft?: () => string;
+  setDraft: (text: string) => void;
+  setStatus?: (text: string) => void;
+}
+
+/** 문의 1건의 AI 초안 수명주기 — 초안의 정본은 세션 버퍼, UI 는 sink 다 */
+export declare class InquirySession {
+  readonly externalId: string;
+  readonly state: "idle" | "composing" | "drafted" | "declined";
+  readonly draft: string;
+  readonly adoptedAnswerId: number | string | null;
+
+  /** UI sink 연결 — 자동 주입 없음, 복원은 restore() 명시 호출 */
+  attachUi(ui: SessionUi): this;
+  /** UI 분리 — 진행 중 스트림은 버퍼로 계속 완주한다 */
+  detachUi(): this;
+  /** 세션 정본을 UI 로 (복귀 한 줄) */
+  restore(): { draft: string; answerId: number | string | null; state: string };
+  /** 상담사 편집을 정본에 반영 (스로틀은 소비처 몫) */
+  remember(text: string): void;
+
+  compose(opts: {
+    inquiry: string;
+    context?: Record<string, string>;
+    customerName?: string;
+    confirmOverwrite?: () => boolean;
+    /** 스트림 시한 관통 — 큰 컨텍스트 창(프리필 분 단위) 운영용. 기본 90s/190s */
+    idleTimeoutMs?: number;
+    overallTimeoutMs?: number;
+  }): ComposeHandle;
+
+  noteAdopted(answerId: number | string | null): void;
+  clearAdopted(): void;
+  answerSent(finalText: string, agent?: string): void;
+  scored(score: number, agent?: string): void;
+  edited(finalText: string, agent?: string): void;
+  discarded(agent?: string, note?: string): void;
+}
+
+export interface CxAgent {
+  enabled: boolean;
+  ready: Promise<void>;
+  readonly flags: Record<string, unknown>;
+  locale: Locale;
+  messages: Record<string, string>;
+  declineText(reason: string): string;
+  /** 원격 설정(bootstrap) 반영 구독 — 반환값으로 해지 */
+  onConfigChange(
+    fn: (cfg: { messages: Record<string, string>; flags: Record<string, unknown> }) => void,
+  ): () => void;
+
+  /** 문의별 세션 — 같은 externalId 는 같은 인스턴스. 인자 없으면 비영속 일회 세션 */
+  session(externalId?: string | number, opts?: { persist?: boolean }): InquirySession;
+
+  requestAnswer(inquiry: string, context?: Record<string, string>): Promise<AnswerResult>;
+  requestInvestigation(
+    externalId: string | number,
+    identity?: { userId?: string | number; subUserId?: string | number },
+  ): Promise<{ ok: boolean; status: string; error: string | null }>;
+  investigationStatus(
+    externalId: string | number,
+  ): Promise<{ ok: boolean; status: string; jobId?: number; error: string | null }>;
+  inquirySent(payload: {
+    externalId: string | number;
+    inquiry: string;
+    reply?: string;
+    agent?: string;
+    meta?: Record<string, string>;
+  }): void;
+}
+
+export declare function createCxAgent(config?: CxAgentSetup): CxAgent;
+/** 기본 초안 데코레이터 — 한국어 인사말 호칭 개인화 (서버 선굽기의 안전망) */
+export declare const koreanGreetingDecorator: DraftDecorator;
+export declare function notConfiguredResult(): AnswerResult;
+export declare function textOf(messages: Record<string, string>, reason: string): string;

package/agent.js

@@ -0,0 +1,242 @@
+/**
+ * CxAgent — 0.3.0 객체 표면. `createCxAgent(config)` 하나로 테넌트를 세운다.
+ *
+ * 구조 원칙 (객체화의 이유):
+ *   - **보편 구조는 코어가 소유한다** — 어느 CMS 든 존재하는 것들: 설정
+ *     동결, 전송, 로케일/문구, 채택 수명, 문의별 세션, 초안 영속.
+ *   - **테넌트 특수분은 파라미터다** — `source`(인그레스 채널명),
+ *     `draftDecorators`(호칭 개인화 등 초안 후처리), `storage`(영속 정책).
+ *     특정 테넌트 전용 값이 코어에 하드코딩되던 것(source:"cms", 한국어
+ *     인사말 정규식)을 기본값 있는 파라미터로 끌어냈다.
+ *   - 전송 계층(client.js)은 여전히 비공개 — 능력이 모자라면 이 표면을
+ *     채운다 (0.2.x 원칙 승계).
+ *
+ * 0.2.x `createCxHook` 은 이 위의 호환 표면이다 (compat.js) — 루트 import
+ * 는 그대로 동작한다. 새 소비처는 이 파일의 표면으로 온다:
+ *
+ * ```js
+ * import { createCxAgent } from "@fcg-labs/cx-agent-hook/agent";
+ * const agent = createCxAgent({ baseUrl, token, domain });
+ * const session = agent.session(csId);      // 문의별 상태·초안 영속
+ * session.attachUi({ getDraft, setDraft, setStatus }).restore();
+ * session.compose({ inquiry, context });    // 이탈해도 완주, 복귀 시 restore
+ * session.answerSent(finalText, agentId);   // gold 쌍 후킹 + 세션 소멸
+ * ```
+ */
+import { CxAgentClient } from "./client.js";
+import { LOCALES, MESSAGES, normalizeLocale, resolveMessages } from "./locales.js";
+import { InquirySession, SessionStore } from "./session.js";
+
+export { LOCALES, MESSAGES, normalizeLocale };
+
+/** 문구 한 벌에서 사유 하나 — 기계 코드를 화면에 노출하지 않는다. */
+export function textOf(messages, reason) {
+  const known = messages[reason];
+  if (known) return known;
+  if (String(reason || "").startsWith("http_")) return messages.http_error;
+  return messages.unknown;
+}
+
+/** 미설정 결과 팩토리 — 0.2.x 의 가변 싱글턴(공유 객체 오염 위험) 청산. */
+export function notConfiguredResult() {
+  return {
+    ok: false, answered: false, answer: "", answerId: null,
+    evidence: [], declinedReason: "not_configured", raw: {},
+  };
+}
+
+/**
+ * 기본 초안 데코레이터 — 한국어 인사말 호칭 개인화.
+ *
+ * 서버가 사설 서빙(AI_CS_LLM_PRIVATE)이면 인사말을 처음부터 이름으로 굽고,
+ * 이 치환은 안전망이다: 이름 없이 "안녕하세요 고객님" 으로 온 초안에만
+ * 작동하고, 서버가 이미 이름을 넣었으면 패턴이 안 맞아 no-op.
+ * 한국어 CS 가 아닌 테넌트는 `draftDecorators: []` 로 끈다.
+ */
+export function koreanGreetingDecorator(text, { customerName } = {}) {
+  const name = String(customerName || "").trim();
+  if (!name) return text;
+  return String(text).replace(
+    /안녕하세요[,]?\s*고객님/,
+    (m) => m.replace("고객님", `${name} 고객님`),
+  );
+}
+
+/**
+ * CxAgent 를 만든다 — 미설정이면 전부 무동작 (자격 없이는 네트워크 0).
+ *
+ * @param {object} config
+ * @param {string} config.baseUrl · config.token · config.domain  전송 3요소
+ * @param {"hub"|"platform"} [config.api="hub"]  기본 대상 — **agent 가 기본값의
+ *   유일한 소유자다** (0.2.x 에서 훅 "hub" vs 클라이언트 "platform" 으로
+ *   갈라져 있던 불일치 청산. 클라이언트에는 항상 명시 전달한다).
+ * @param {string} [config.locale] · @param {object} [config.messages]
+ * @param {boolean} [config.bootstrap=false]  허브 client-config 병합
+ * @param {string} [config.source="cms"]  인그레스 채널명 (테넌트 선언)
+ * @param {Array<(text:string, ctx:{customerName?:string})=>string>}
+ *   [config.draftDecorators]  초안 후처리 사슬 — 기본 [한국어 호칭]
+ * @param {{enabled?:boolean, ttlMs?:number, maxSessions?:number,
+ *          prefix?:string, impl?:Storage}} [config.storage]  세션 영속 정책
+ */
+export function createCxAgent(config = {}) {
+  const {
+    baseUrl, token, domain, api = "hub", onError,
+    locale, messages: messageOverrides,
+    bootstrap = false,
+    source = "cms",
+    draftDecorators = [koreanGreetingDecorator],
+    storage = {},
+    ...rest
+  } = config;
+
+  const messages = resolveMessages(locale, messageOverrides);
+  let flags = {};
+  const configListeners = new Set();
+  const client =
+    baseUrl && token && domain
+      ? new CxAgentClient({
+          baseUrl, token, domain, api, source,
+          // 후킹 실패는 CS 업무와 무관 — 기록만 하고 화면을 막지 않는다.
+          onError:
+            onError ||
+            ((err, ctx) => console.warn("[cx-agent-hook]", ctx.op, err.message)),
+          ...rest,
+        })
+      : null;
+
+  const decorate = (text, ctx) =>
+    draftDecorators.reduce((acc, fn) => {
+      try { return fn(acc, ctx || {}); } catch { return acc; }
+    }, String(text ?? ""));
+
+  const applyRemoteConfig = (remote) => {
+    if (!remote || typeof remote !== "object") return;
+    if (remote.locale || remote.messages) {
+      // 원격 문구 위에 로컬 override 재적용 — 로컬 우선 규칙을 병합 순서로 강제
+      const next = resolveMessages(locale || remote.locale, {
+        ...(remote.messages || {}),
+        ...(messageOverrides || {}),
+      });
+      Object.assign(messages, next);
+    }
+    if (remote.flags && typeof remote.flags === "object") {
+      flags = { ...remote.flags };
+    }
+    for (const fn of configListeners) {
+      try { fn({ messages, flags }); } catch { /* 리스너 실패 무시 */ }
+    }
+  };
+
+  const fetchRemoteConfig = async () => {
+    const doFetch = rest.fetchImpl || (typeof fetch !== "undefined" ? fetch : null);
+    if (!doFetch) return;
+    const cacheKey = `cx-agent-config:${domain}`;
+    try {
+      if (typeof sessionStorage !== "undefined") {
+        const cached = JSON.parse(sessionStorage.getItem(cacheKey) || "null");
+        if (cached && Date.now() - cached.at < 5 * 60 * 1000) {
+          applyRemoteConfig(cached.config);
+          return;
+        }
+      }
+    } catch { /* 캐시 실패는 무시 — 네트워크로 진행 */ }
+    const res = await doFetch(
+      `${String(baseUrl).replace(/\/$/, "")}/v1/domains/${domain}/client-config`,
+      { headers: { Authorization: `Bearer ${token}` } },
+    );
+    if (!res.ok) return; // 404(미발행) 포함 — 정적 설정으로 동작 (fail-soft)
+    const remote = await res.json();
+    applyRemoteConfig(remote);
+    try {
+      if (typeof sessionStorage !== "undefined") {
+        sessionStorage.setItem(
+          cacheKey, JSON.stringify({ at: Date.now(), config: remote }),
+        );
+      }
+    } catch { /* 저장 실패 무시 */ }
+  };
+
+  // 부트스트랩은 백그라운드 — 화면을 막지 않는다. 실패도 resolve.
+  const ready = (bootstrap && client && api === "hub")
+    ? fetchRemoteConfig().catch(() => {})
+    : Promise.resolve();
+
+  // 세션 영속 — 퇴거(TTL·LRU)는 원장에 기각으로 남긴다 (침묵 소거 금지)
+  const store = storage.enabled === false || !client
+    ? null
+    : new SessionStore({
+        impl: storage.impl,
+        prefix: storage.prefix || `cx-agent-session:${domain}`,
+        ttlMs: storage.ttlMs,
+        maxSessions: storage.maxSessions,
+        onEvict: (rec, why) => {
+          if (rec && rec.answerId) client.discarded(rec.answerId, "", why);
+        },
+      });
+
+  const sessionDeps = {
+    client, messages, decorate, store,
+    textOf: (reason) => textOf(messages, reason),
+  };
+  const sessions = new Map();
+
+  return {
+    /** 전송 3요소가 다 있으면 true */
+    enabled: Boolean(client),
+    /** 부트스트랩 완료 신호 — bootstrap 미사용 시 즉시 resolve */
+    ready,
+    /** 중앙 발행 기능 플래그 — 부트스트랩 전/미발행이면 빈 객체 */
+    get flags() { return flags; },
+    /** setup 에서 정해진 화면 언어 (정규화) */
+    locale: normalizeLocale(locale),
+    /** 이 테넌트의 문구 한 벌 — 부트스트랩이 제자리 갱신한다 */
+    messages,
+    declineText(reason) { return textOf(messages, reason); },
+    /** 원격 설정 반영 구독 (bootstrap) — 반환값으로 해지 */
+    onConfigChange(fn) {
+      configListeners.add(fn);
+      return () => configListeners.delete(fn);
+    },
+
+    /**
+     * 문의별 세션 — 같은 externalId 는 같은 인스턴스 (프로세스 내 캐시 +
+     * sessionStorage 복원). externalId 없이 부르면 비영속 일회 세션.
+     */
+    session(externalId, opts = {}) {
+      const id = externalId == null ? "" : String(externalId);
+      if (!id) return new InquirySession("", { ...sessionDeps, store: null });
+      let s = sessions.get(id);
+      if (!s) {
+        s = new InquirySession(id, {
+          ...sessionDeps,
+          store: opts.persist === false ? null : store,
+        });
+        sessions.set(id, s);
+      }
+      return s;
+    },
+
+    /** 답변 제안 (비스트림) — throw 하지 않음 */
+    requestAnswer(inquiry, context) {
+      if (!client || !inquiry) return Promise.resolve(notConfiguredResult());
+      return client.getAnswer(inquiry, context);
+    },
+
+    /** 조사 요청 (E-8) — 큐 적재만, 결과는 investigationStatus 폴링 */
+    requestInvestigation(externalId, identity) {
+      if (!client) return Promise.resolve({ ok: false, status: "", error: "not_configured" });
+      return client.requestInvestigation(externalId, identity);
+    },
+
+    investigationStatus(externalId) {
+      if (!client) return Promise.resolve({ ok: false, status: "", error: "not_configured" });
+      return client.investigationStatus(externalId);
+    },
+
+    /** 문의+최종답변 쌍 적재 (fire-and-forget, external_id 멱등) */
+    inquirySent({ externalId, inquiry, reply, agent, meta } = {}) {
+      if (!client || !externalId || !inquiry) return;
+      client.logInquiry({ externalId, inquiry, reply, agent, meta });
+    },
+  };
+}

package/client.d.ts

@@ -25,6 +25,8 @@ export interface CxAgentConfig {
   feedback?: CapabilityTarget;
   retries?: number;
   timeoutMs?: number;
+  /** 인그레스 body.source (테넌트 채널명) — 기본 "cms" (0.3.0 파라미터화) */
+  source?: string;
   onError?: (err: Error, context: { op: string; code?: string }) => void;
   fetchImpl?: typeof fetch;
 }
@@ -33,7 +35,8 @@ export interface AnswerResult {
   ok: boolean;
   answered: boolean;
   answer: string;
-  answerId: number | null;
+  /** 신원 수술(0048) 이후 허브 발급분은 ULID 문자열 — 불투명 취급 */
+  answerId: number | string | null;
   evidence: Array<{ unit_key: string; title: string; score: number }>;
   declinedReason: string;
   raw: Record<string, unknown>;

package/client.js

@@ -113,7 +113,7 @@ export class CxAgentClient {
    */
   constructor({ baseUrl, token, domain, api = "platform", retries = 2,
                 timeoutMs = 90000, onError, fetchImpl,
-                answer, ingress, feedback } = {}) {
+                answer, ingress, feedback, source = "cms" } = {}) {
     if (!baseUrl || !token || !domain) {
       throw new Error("@fcg-labs/cx-agent-hook: baseUrl·token·domain 은 필수입니다");
     }
@@ -140,6 +140,9 @@ export class CxAgentClient {
     }
     this.retries = retries;
     this.timeoutMs = timeoutMs;
+    // 인그레스 body.source — 문의가 어느 채널에서 왔는지의 테넌트 선언.
+    // "cms" 하드코딩이던 것을 0.3.0 에서 파라미터화 (기본값은 하위호환).
+    this.source = String(source || "cms");
     this.onError = onError || (() => {});
     this.fetchImpl = fetchImpl || globalThis.fetch.bind(globalThis);
   }
@@ -485,7 +488,7 @@ export class CxAgentClient {
       return this._inqFail(new Error("inquiry 필수"), "invalid_inquiry");
     }
     const body = {
-      source: "cms",
+      source: this.source,
       external_id: String(externalId),
       inquiry: String(inquiry),
       ...(reply ? { reply: String(reply) } : {}),

package/compat.js

@@ -0,0 +1,67 @@
+/**
+ * createCxHook — 0.2.x 호환 표면 (내부용 모듈, exports 맵에 없다).
+ *
+ * 0.3.0 에서 구현이 CxAgent + InquirySession 으로 옮겨졌다. 이 파일은 그
+ * 위에 0.2.x 문서화 표면을 **비영속 기본 세션** 하나로 재구성한다 — 기존
+ * 소비처(와 시험 94건)는 글자 하나 안 바꾸고 그대로 동작한다.
+ *
+ * 0.2.x 와 0.3.0 의 관계:
+ *   - hook.noteAdopted/answerSent/... = 기본 세션의 동명 메서드
+ *   - hook.composeDraft = session.compose + 호출별 UI sink
+ *   - 문의별 상태·영속이 필요하면 `createCxAgent` + `agent.session()` 으로
+ *     올라간다 (MIGRATION.md)
+ */
+import { createCxAgent, notConfiguredResult, textOf } from "./agent.js";
+
+/** 후킹 한 벌을 만든다 — 미설정이면 전부 무동작. (0.2.x 표면 그대로) */
+export function createCxHook(config = {}) {
+  const agent = createCxAgent({
+    ...config,
+    // 0.2.x 훅은 문의별 세션 개념이 없다 — 영속은 세션 표면의 능력이다.
+    storage: { enabled: false, ...(config.storage || {}) },
+  });
+  // 훅 전체가 공유하는 단일 채택 슬롯 = 비영속 기본 세션 하나
+  const session = agent.session();
+
+  return {
+    enabled: agent.enabled,
+    ready: agent.ready,
+    get flags() { return agent.flags; },
+    locale: agent.locale,
+    messages: agent.messages,
+    declineText(reason) { return agent.declineText(reason); },
+
+    requestAnswer(inquiry, context) {
+      return agent.requestAnswer(inquiry, context);
+    },
+    requestInvestigation(externalId, identity) {
+      return agent.requestInvestigation(externalId, identity);
+    },
+    investigationStatus(externalId) {
+      return agent.investigationStatus(externalId);
+    },
+
+    /** 초안 직주입 스트리밍 — 세션 compose 에 호출별 UI sink 를 붙인다.
+     * 의미론(자동 채택·교체 기각·실패 원복·abort 무간섭)은 session.js 소유. */
+    composeDraft({ inquiry, context, getDraft, setDraft, setStatus,
+                   confirmOverwrite, customerName } = {}) {
+      if (!agent.enabled || !inquiry || typeof setDraft !== "function") {
+        if (setStatus) setStatus(textOf(agent.messages, "not_configured"));
+        return { promise: Promise.resolve(notConfiguredResult()), abort: () => {} };
+      }
+      session.attachUi({ getDraft, setDraft, setStatus });
+      return session.compose({ inquiry, context, customerName, confirmOverwrite });
+    },
+
+    noteAdopted(answerId) { session.noteAdopted(answerId); },
+    clearAdopted() { session.clearAdopted(); },
+    get adoptedAnswerId() { return session.adoptedAnswerId; },
+
+    answerSent(finalText, agentId) { session.answerSent(finalText, agentId); },
+    scored(score, agentId) { session.scored(score, agentId); },
+    edited(finalText, agentId) { session.edited(finalText, agentId); },
+    discarded(agentId, note) { session.discarded(agentId, note); },
+
+    inquirySent(payload) { agent.inquirySent(payload); },
+  };
+}