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

package/MIGRATION.md

@@ -0,0 +1,116 @@
+# 0.3.0 → 0.4.0 마이그레이션
+
+## 요약 — 깨지는 것은 없다
+
+0.4.0 은 **추가형**이다. 0.3.0 표면(`createCxAgent`·`session`·어댑터·클래스명)은
+전부 그대로 동작한다 (기존 시험 107건 무수정 통과, 신규 10건).
+
+## 새로 생긴 것 — 처리 액션 (선택)
+
+- `createCxAgent({ actorAssertion })` — 고객사가 발행한 단명·목적 한정 행위자
+  토큰을 돌려주는 함수. **넘기지 않으면 아무것도 바뀌지 않는다** (표면 닫힘).
+- `session.offers` / `session.attachActionUi(ui)` / `session.executeAction(offer)` /
+  `session.reconcileAction(requestId)` / `session.pendingActions()`
+- `agent.actionsEnabled`
+- 헤드리스: `actionOffersView` · `actionOffersTree` · `ACTION_CLS` (`view.js`)
+- 로케일 키 `ui_action_*` 14종 (ko 정본, en/ja/zh-TW 미검수)
+- 저장: `storage.actionsImpl` — 눌렀던 처리의 pending 기록(기본 localStorage,
+  종단 후 24h). 세션 영속(sessionStorage 30분)과 **수명이 다르다**.
+
+## 행동 계약 (새 표면에만 해당)
+
+- 실행 요청은 **재시도 0**. 네트워크 오류 → 상태 조회 1회 → 허브에 기록이
+  없을 때(404)만 같은 request_id 로 1회 재전송.
+- `unknown`(실행 여부 미확인)은 재실행 버튼이 없다 — `reconcileAction`(조회)로만
+  수렴한다. 화면이 이 규칙을 어기면 이중 실행이 된다.
+- 결과 `result` 는 서버 화이트리스트 키만 온다. GET 상태 조회에는 `result` 가 없다.
+
+---
+
+# 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,61 @@ 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`)도 공식 표면이다.
+
+## 0.4.0 — 처리 액션 (말에서 행으로, 선택 표면)
+
+답변 제안 옆에 **처리 선택지**가 실릴 수 있다 (`payload.suggested_actions`). 이 SDK 는
+그 선택지를 보관·표시하고, 상담사 확인 뒤 허브에 실행을 요청하고, 결과 3상태를
+보여준다. **실행기·권한·정책은 고객사 서버가 소유**한다 — SDK 는 계약(`actions/1`)의
+클라이언트일 뿐이다.
+
+```js
+const agent = createCxAgent({
+  baseUrl, token, domain,
+  // 고객사가 발행하는 단명·목적 한정 행위자 토큰. 없으면 액션 표면은 닫힌다
+  // (선택지는 오되 실행 버튼이 없다). 전권 세션 토큰을 넘기지 말 것.
+  actorAssertion: () => fetchMyActionToken(),
+});
+const session = agent.session(inquiryId);
+session.attachActionUi({ setOffers: (offers, pending) => render(offers, pending) });
+// 사람 확인(확인 문구·고위험은 2단) 뒤에만:
+const r = await session.executeAction(offer, { actorClaimed: agentDisplayName });
+// r.state: succeeded | failed | unknown — unknown 은 "다시 확인"(reconcile) 만, 재실행 없음
+await session.reconcileAction(r.requestId);
+```
+
+계약 요점: 요청은 request_id(ULID)로 멱등이고 SDK 는 **재시도하지 않는다** —
+네트워크 오류면 상태를 묻고, 허브에 기록이 없을 때만 같은 request_id 로 1회
+재전송한다. 눌렀던 처리는 `session.pendingActions()` 로 새로고침 뒤에도 안다
+(정본은 허브 원장). 헤드리스 뷰: `actionOffersView` / `actionOffersTree`(`view.js`),
+클래스 `fcx-act-*`, 문구는 `ui_action_*` 로케일 키.
+
 ## 지원 프레임워크
 
 | 진입점 | 대상 | 필요한 peer |

package/agent.d.ts

@@ -0,0 +1,197 @@
+/**
+ * 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 & {
+    /** 처리 액션 pending 저장소 구현 (기본 localStorage) — 세션 영속과 수명이 다르다 */
+    actionsImpl?: Storage;
+  };
+  /**
+   * 처리 액션 (actions/1) 행위자 자격증명 — 고객사가 발행한 **단명·목적 한정**
+   * 토큰(aud=cx-action, 분 단위 ttl)을 돌려주는 함수. 없으면 액션 표면은 닫힌다
+   * (선택지는 오되 실행 버튼이 없다). 전권 세션 토큰을 넘기는 것은 계약 위반.
+   */
+  actorAssertion?: () => string | Promise<string>;
+};
+
+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;
+
+  // ── 처리 액션 (actions/1) ──
+  /** 마지막 답변의 처리 선택지 (만료 제외). 실행 시맨틱 없음 — 사람 확인 후 executeAction */
+  readonly offers: ActionOffer[];
+  /** 선택지 UI sink — setOffers(offers, pending) 를 받는다 */
+  attachActionUi(ui: { setOffers: (offers: ActionOffer[], pending: PendingAction[]) => void }): void;
+  detachActionUi(): void;
+  /** 이 문의에서 눌렀던 처리들 (정본은 허브 원장 — 브라우저 소실은 표시 손실뿐) */
+  pendingActions(): PendingAction[];
+  /** 실행 — 확인은 호출자가 끝낸 뒤. request_id 발급·전송 전 영속·재시도 0 */
+  executeAction(offer: ActionOffer, opts?: { actorClaimed?: string }): Promise<ActionResult & { requestId: string }>;
+  /** 재조정 — lookup 만 (재실행 없음). unknown 만 의미 있다 */
+  reconcileAction(requestId: string): Promise<{ ok: boolean; state: string; reasonCode?: string; message?: string; error: string | null }>;
+}
+
+/** 답변 payload 의 suggested_actions 항목 (허브 평탄화 뷰 — endpoint·트리거·승인 시각 없음) */
+export interface ActionOffer {
+  offer_id: string;
+  event_id: string;
+  action_key: string;
+  params_bound: Record<string, string>;
+  params_hash: string;
+  params_display: string;
+  label: string;
+  description: string;
+  confirm: string;
+  risk_level: "low" | "medium" | "high";
+  expires_at: string;
+  catalog_version: number;
+  offer_reason: "issue_key" | "context" | "tokens";
+}
+
+export interface PendingAction {
+  requestId: string;
+  offerId: string;
+  actionKey: string;
+  label: string;
+  state: "pending" | "succeeded" | "failed" | "unknown" | string;
+  reasonCode?: string;
+  message?: string;
+  at: number;
+}
+
+export interface ActionResult {
+  ok: boolean;
+  /** succeeded | failed | unknown | in_flight | '' */
+  state: string;
+  reasonCode: string;
+  message: string;
+  actorAttested: string;
+  auditRef: string;
+  result: Record<string, unknown> | null;
+  deduplicated: boolean;
+  /** offer_locked | request_conflict | actor_assertion_required | actions_disabled | network_error | … */
+  error: string | null;
+  httpStatus: number;
+}
+
+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 }>;
+  /** 처리 액션 표면 열림 여부 — 전송 3요소 + actorAssertion */
+  readonly actionsEnabled: boolean;
+  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;
+
+// 헤드리스 액션 뷰 재수출 (view.d.ts 정본)
+export { ACTION_CLS, actionOffersTree, actionOffersView } from "./view.js";
+export type { ActionOfferItemView } from "./view.js";

package/agent.js

@@ -0,0 +1,258 @@
+/**
+ * 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, newRequestId } from "./client.js";
+import { LOCALES, MESSAGES, normalizeLocale, resolveMessages } from "./locales.js";
+import { ActionLedger, InquirySession, SessionStore } from "./session.js";
+import { ACTION_CLS, actionOffersTree, actionOffersView } from "./view.js";
+
+// 헤드리스 액션 뷰 — 프레임워크 어댑터(react/vue) 슬롯은 0.4.x 후속. 그전엔
+// 소비처가 이 순수 함수로 자기 렌더러에 그린다 (텍스트 노드만 — innerHTML 금지).
+export { ACTION_CLS, actionOffersTree, actionOffersView };
+
+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 = {},
+    // 처리 액션 (actions/1): 고객사가 발행한 단명·목적 한정 행위자 토큰을 돌려주는
+    // 함수. 없으면 액션 표면은 닫힌다 (offers 는 오되 실행 버튼은 없다).
+    actorAssertion,
+    ...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 actionLedger = storage.enabled === false || !client
+    ? null
+    : new ActionLedger({ impl: storage.actionsImpl, prefix: `cx-agent-actions:${domain}` });
+  const sessionDeps = {
+    client, messages, decorate, store,
+    textOf: (reason) => textOf(messages, reason),
+    actorAssertion: typeof actorAssertion === "function" ? actorAssertion : null,
+    actionLedger, newRequestId,
+  };
+  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);
+    },
+
+    /** 처리 액션 표면이 열려 있는가 — 전송 3요소 + actorAssertion 함수 */
+    get actionsEnabled() { return Boolean(client && sessionDeps.actorAssertion); },
+
+    /** 문의+최종답변 쌍 적재 (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>;