@fcg-labs/cx-agent-hook 0.7.1 → 0.8.0

package/MIGRATION.md

@@ -214,3 +214,17 @@ headless 2단계: ① 스타일 0 — styles.css 를 import 하지 않는다.
   이후 허브 발급분은 문자열이다. 불투명 취급하면 코드 변경은 없다.
 - element 어댑터의 내부 DOM 구조는 동일하나, 어댑터 3종이 `aiSuggestTree`
   인터프리터로 재구현됐다 — 클래스·이벤트·마크업 계약은 시험으로 고정.
+
+## 0.7.x → 0.8.0 — 다안 (candidates)
+
+전부 **가산적**이라 0.7.x 소비처는 코드 변경 없이 그대로 동작한다.
+
+- 응답에 `candidates[]` 가 실린다 — `[0]` 은 항상 본안(`variant: "primary"`,
+  `answer` 는 최상위 `answer` 와 동일). 서버 env(`AI_CS_CANDIDATES`)가 꺼져
+  있으면 빈 배열이다.
+- 세션: `candidates` / `chosenVariant` getter 와 `choose(index)` — 후보를 초안
+  정본으로 바꾼다(데코레이트는 compose 시점에 끝나 있다). sink 에
+  `setCandidates(list, chosen)` 를 **선택적으로** 구현하면 도착·선택을 받는다.
+- 발송: 본안이 아닌 후보를 골라 보냈으면 `sent` 피드백의 `note` 에
+  `variant:<id>` 가 남는다 — 와이어 계약(허브 Go) 무변경.
+- React: `CandidatePicker` 신규. `AiSuggestPanel` 은 무변경.

package/agent.d.ts

@@ -81,6 +81,9 @@ export interface ComposeHandle {
 }
 
 export interface SessionUi {
+  /** 다안 도착·선택 시 (0.8.0, 선택 구현) — 없으면 조용히 생략된다. */
+  setCandidates?(candidates: Array<{ variant: string; label: string; answer: string }>,
+                 chosen: string): void;
   getDraft?: () => string;
   setDraft: (text: string) => void;
   setStatus?: (text: string) => void;
@@ -92,6 +95,12 @@ export declare class InquirySession {
   readonly state: "idle" | "composing" | "drafted" | "declined";
   readonly draft: string;
   readonly adoptedAnswerId: number | string | null;
+  /** 다안 (0.8.0) — 데코레이트 완료본, [0]=본안. */
+  readonly candidates: Array<{ variant: string; label: string; answer: string;
+    evidence_keys: string[]; contract_warnings: string[] }>;
+  readonly chosenVariant: string;
+  /** 후보를 초안 정본으로 (0.8.0). 잘못된 index 는 무동작. */
+  choose(index: number): void;
 
   /** UI sink 연결 — 자동 주입 없음, 복원은 restore() 명시 호출 */
   attachUi(ui: SessionUi): this;

package/client.d.ts

@@ -38,6 +38,9 @@ export interface AnswerResult {
   /** 신원 수술(0048) 이후 허브 발급분은 ULID 문자열 — 불투명 취급 */
   answerId: number | string | null;
   evidence: Array<{ unit_key: string; title: string; score: number }>;
+  /** 다안 (0.8.0) — [0]=본안. env 끔·거절이면 []. */
+  candidates: Array<{ variant: string; label: string; answer: string;
+    evidence_keys: string[]; contract_warnings: string[] }>;
   declinedReason: string;
   raw: Record<string, unknown>;
 }

package/client.js

@@ -206,7 +206,7 @@ export class CxAgentClient {
       );
       return {
         ok: false, answered: false, answer: "", answerId: null,
-        evidence: [], declinedReason: "unsupported_api", raw: {},
+        evidence: [], candidates: [], declinedReason: "unsupported_api", raw: {},
       };
     }
     try {
@@ -227,7 +227,7 @@ export class CxAgentClient {
         //   공장   JSONResponse({"error": "serving_disabled"}, 503) 등
         return {
           ok: false, answered: false, answer: "", answerId: null,
-          evidence: [],
+          evidence: [], candidates: [],
           declinedReason: (data && data.error) || `http_${status}`,
           raw: data,
         };
@@ -238,6 +238,7 @@ export class CxAgentClient {
         answer: data.answer || "",
         answerId: data.answer_id ?? null,
         evidence: data.evidence || [],
+        candidates: Array.isArray(data.candidates) ? data.candidates : [],
         declinedReason: data.declined_reason || "",
         raw: data,
       };
@@ -245,7 +246,7 @@ export class CxAgentClient {
       this.onError(err, { op: "getAnswer" });
       return {
         ok: false, answered: false, answer: "", answerId: null,
-        evidence: [], declinedReason: "network_error", raw: {},
+        evidence: [], candidates: [], declinedReason: "network_error", raw: {},
       };
     }
   }
@@ -276,7 +277,7 @@ export class CxAgentClient {
   } = {}) {
     const fail = (reason, raw = {}) => ({
       ok: false, answered: false, answer: "", answerId: null,
-      evidence: [], declinedReason: reason, raw,
+      evidence: [], candidates: [], declinedReason: reason, raw,
     });
     const target = this._target("answer");
     const streamPath = PATHS[target.api] && PATHS[target.api].answerStream;
@@ -361,6 +362,7 @@ export class CxAgentClient {
         answer: final.answer || "",
         answerId: final.answer_id ?? null,
         evidence: final.evidence || [],
+        candidates: Array.isArray(final.candidates) ? final.candidates : [],
         declinedReason: final.declined_reason || "",
         raw: final,
       };
@@ -445,9 +447,13 @@ export class CxAgentClient {
     return { ok: false, feedbackId: null, error: code };
   }
 
-  /** 발송 후킹 — CS팀이 실제로 내보낸 최종 문구 (gold 학습 쌍의 원천) */
-  sent(answerId, finalText, agent) {
-    return this.sendFeedback({ answerId, action: "sent", finalText, agent });
+  /** 발송 후킹 — CS팀이 실제로 내보낸 최종 문구 (gold 학습 쌍의 원천).
+   *  note: 다안(0.8.0)에서 선택 변형 표식 `variant:<id>` — 와이어 계약 무변경. */
+  sent(answerId, finalText, agent, note = "") {
+    return this.sendFeedback({
+      answerId, action: "sent", finalText, agent,
+      ...(note ? { note } : {}),
+    });
   }
 
   /** 점수 후킹 (1~5) */

package/index.d.ts

@@ -75,6 +75,12 @@ export interface CxHook {
   /** 채택 기록 폐기 — 문의 전환 시 */
   clearAdopted(): void;
   readonly adoptedAnswerId: number | string | null;
+  /** 다안 (0.8.0) — 데코레이트 완료본, [0]=본안. */
+  readonly candidates: Array<{ variant: string; label: string; answer: string;
+    evidence_keys: string[]; contract_warnings: string[] }>;
+  readonly chosenVariant: string;
+  /** 후보를 초안 정본으로 (0.8.0). 잘못된 index 는 무동작. */
+  choose(index: number): void;
 
   /** 발송됨 — 채택본이었을 때만 gold 쌍 후킹. 보낸 뒤 채택 기록을 비운다. */
   answerSent(finalText: string, agent?: string): void;

package/locales.js

@@ -29,6 +29,9 @@ const en = {
   ui_request: "Suggest a reply",
   ui_requesting: "Generating…",
   ui_adopt: "Insert into editor",
+  ui_candidates: "AI draft options",
+  ui_candidate_use: "Use this draft",
+  ui_candidate_chosen: "Selected",
   ui_feedback_ask: "Was this draft helpful?",
   ui_feedback_up: "Helpful",
   ui_feedback_down: "Not helpful",
@@ -94,6 +97,9 @@ const ko = {
   ui_request: "AI 답변 제안",
   ui_requesting: "제안 생성 중...",
   ui_adopt: "에디터에 넣기",
+  ui_candidates: "AI 답변 후보",
+  ui_candidate_use: "이 안 쓰기",
+  ui_candidate_chosen: "선택됨",
   ui_feedback_ask: "이 초안, 쓸 만했나요?",
   ui_feedback_up: "좋아요",
   ui_feedback_down: "싫어요",
@@ -154,6 +160,9 @@ const ja = {
   ui_request: "AI 返信案",
   ui_requesting: "生成中...",
   ui_adopt: "エディタに挿入",
+  ui_candidates: "AI回答の候補",
+  ui_candidate_use: "この案を使う",
+  ui_candidate_chosen: "選択中",
   ui_feedback_ask: "この下書きは役に立ちましたか?",
   ui_feedback_up: "良い",
   ui_feedback_down: "悪い",
@@ -213,6 +222,9 @@ const ja = {
 const zhTW = {
   ui_request: "AI 回覆建議",
   ui_requesting: "產生中...",
+  ui_candidates: "AI 回覆候選",
+  ui_candidate_use: "使用此草稿",
+  ui_candidate_chosen: "已選擇",
   ui_adopt: "插入編輯器",
   ui_feedback_ask: "這份草稿有幫助嗎?",
   ui_feedback_up: "有幫助",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fcg-labs/cx-agent-hook",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "FCG CX Agent 후킹 SDK — 서빙 답변 수신 + CS팀 교정(점수·수정·발송) 후킹. 의존성 0, CMS에 install만으로 이식",
   "type": "module",
   "main": "index.js",

package/react.d.ts

@@ -41,3 +41,12 @@ export interface AiFeedbackBarProps {
 export declare function AiFeedbackBar(props: AiFeedbackBarProps): ReactElement | null;
 
 export default AiSuggestPanel;
+
+/** 다안 피커 (0.8.0) — 후보 2안 미만이면 null 렌더. 선택 정본은 세션(choose). */
+export declare function CandidatePicker(props: {
+  candidates: Array<{ variant: string; label: string; answer: string }>;
+  chosen: string;
+  messages: Record<string, string>;
+  onChoose: (index: number) => void;
+  className?: string;
+}): unknown;

package/react.js

@@ -19,7 +19,7 @@
  */
 import { createElement as h, useCallback, useEffect, useRef, useState } from "react";
 
-import { actionOffersTree, aiSuggestTree, aiSuggestView, CLS, feedbackBarTree } from "./view.js";
+import { actionOffersTree, aiSuggestTree, aiSuggestView, candidatePickerTree, CLS, feedbackBarTree } from "./view.js";
 
 // 표시 판단은 프레임워크 중립 코어가 갖는다 — Vue·웹 컴포넌트와 같은 것을 쓴다.
 export { aiSuggestView };
@@ -330,3 +330,37 @@ export function AiFeedbackBar({ session, agent, actorClaimed, className }) {
                     onClick: (event) => event.stopPropagation() },
            tree.children.map((n, i) => render(n, i)));
 }
+
+
+// ── 다안 피커 (0.8.0) ────────────────────────────────────────────────────────
+//
+// ```jsx
+// <CandidatePicker candidates={session.candidates} chosen={session.chosenVariant}
+//                  messages={cxMessages} onChoose={(i) => session.choose(i)} />
+// ```
+// 표시 판단은 view.candidatePickerTree 가 소유한다 — 2안 미만이면 아무것도
+// 그리지 않는다. 선택은 세션(choose)이 정본이라 이 컴포넌트는 상태가 없다.
+
+export function CandidatePicker({ candidates, chosen, messages, onChoose, className }) {
+  const tree = candidatePickerTree({ candidates, chosen, messages });
+  if (!tree) return null;
+  const render = (node, key) => {
+    const props = { key, className: node.cls };
+    if (node.tag === "button") {
+      props.type = node.type || "button";
+      if (node.action === "choose" && onChoose) {
+        props.onClick = () => onChoose(node.index);
+      }
+    }
+    const children = node.children
+      ? node.children.map((c, i) => render(c, i))
+      : node.text;
+    return h(node.tag, props, children);
+  };
+  return h(
+    "div",
+    { className: className ? `${tree.cls} ${className}` : tree.cls,
+      onClick: (event) => event.stopPropagation() },   // 문의 행 선택 토글 방지 (패널 선례)
+    tree.children.map((c, i) => render(c, i)),
+  );
+}

package/session.js

@@ -166,6 +166,9 @@ export class InquirySession {
     this._locks = {};               // action_key\x00target_key → 잠금 조회 결과 (세션 캐시)
     this._verify = {};              // offer_id → 대상 확정(더블체크) 결과 (T2.7, 화면 표시용 캐시)
 
+    this._candidates = [];          // 다안 (0.8.0) — 데코레이트 완료본, [0]=본안
+    this._chosenVariant = "primary";
+
     // 영속 복원 — TTL 만료분은 store 가 이미 걸렀다
     if (this._id && deps.store) {
       const rec = deps.store.load(this._id);
@@ -174,6 +177,8 @@ export class InquirySession {
         this._answerId = rec.answerId ?? null;
         this._state = rec.state === "declined" ? "declined"
           : (this._draft || this._answerId ? "drafted" : "idle");
+        this._candidates = Array.isArray(rec.candidates) ? rec.candidates : [];
+        this._chosenVariant = rec.chosenVariant || "primary";
       }
     }
   }
@@ -358,6 +363,26 @@ export class InquirySession {
   get state() { return this._state; }
   get draft() { return this._draft; }
   get adoptedAnswerId() { return this._answerId; }
+  get candidates() { return this._candidates.slice(); }
+  get chosenVariant() { return this._chosenVariant; }
+
+  /** 다안 선택 (0.8.0) — 후보를 초안 정본으로. 판단 기록은 없다(고르기는 판단 전 단계). */
+  choose(index) {
+    const candidate = this._candidates[index];
+    if (!candidate) return;
+    this._draft = String(candidate.answer || "");
+    this._chosenVariant = String(candidate.variant || "primary");
+    this._setUiDraft(this._draft);
+    this._setUiCandidates();
+    this._persist();
+  }
+
+  _setUiCandidates() {
+    // 선택 메서드 — 없는 sink(구 소비처)는 조용히 넘어간다 (0.7.x 호환)
+    if (this._ui && typeof this._ui.setCandidates === "function") {
+      this._ui.setCandidates(this._candidates.slice(), this._chosenVariant);
+    }
+  }
 
   /** UI sink 연결 — 초안을 자동 주입하지 않는다 (복원은 restore() 명시 호출).
    * @param {{getDraft?:()=>string, setDraft:(t:string)=>void,
@@ -378,6 +403,7 @@ export class InquirySession {
     if (this._ui) {
       this._ui.setDraft(this._draft);
       if (this._ui.setStatus) this._ui.setStatus(this._statusText);
+      this._setUiCandidates();
     }
     return { draft: this._draft, answerId: this._answerId, state: this._state };
   }
@@ -393,6 +419,7 @@ export class InquirySession {
     if (this._id && this._d.store) {
       this._d.store.save(this._id, {
         draft: this._draft, answerId: this._answerId, state: this._state,
+        candidates: this._candidates, chosenVariant: this._chosenVariant,
       });
     }
   }
@@ -547,6 +574,12 @@ export class InquirySession {
           d.client.discarded(supersededId, "", "redraft");
         }
         this._answerId = newId;
+        // 다안 (0.8.0) — 지금 데코레이트해 둔다: 이름은 compose 순간의 재료라
+        // 나중에 choose() 가 다시 만들 수 없다. 서버가 후보를 안 보내면 [].
+        this._candidates = (Array.isArray(result.candidates) ? result.candidates : [])
+          .map((c) => ({ ...c, answer: decorate(String(c.answer || "")) }));
+        this._chosenVariant = "primary";
+        this._setUiCandidates();
         this._state = "drafted";
         this._setStatus("");
         this._persist();
@@ -556,6 +589,10 @@ export class InquirySession {
         this._draft = supersededDraft;
         this._answerId = supersededId;
         this._state = supersededDraft || supersededId ? "drafted" : "declined";
+        // 낡은 후보 세트가 새 실패 위에 남으면 화면이 거짓을 고른다 — 비운다 (0.8.0)
+        this._candidates = [];
+        this._chosenVariant = "primary";
+        this._setUiCandidates();
         this._setUiDraft(supersededDraft);
         this._setStatus(d.textOf(result.declinedReason || "unknown"));
         this._persist();
@@ -596,15 +633,22 @@ export class InquirySession {
       this._draft = "";
       this._statusText = "";
       this._state = "idle";
+      this._candidates = [];          // 다안도 초안과 같은 수명 (0.8.0)
+      this._chosenVariant = "primary";
+      this._setUiCandidates();
       this._clearPersist();     // 발송·폐기된 초안을 브라우저에 남기지 않는다
     }
     if (!this._d.client || !id) return;
     send(id);
   }
 
-  /** 발송 — 채택본이었다면 gold 쌍 후킹, 마지막 판단이라 기록을 비운다 */
+  /** 발송 — 채택본이었다면 gold 쌍 후킹, 마지막 판단이라 기록을 비운다.
+   *  다안(0.8.0): 본안이 아닌 후보를 골라 보냈으면 note 에 `variant:<id>` 가 남는다. */
   answerSent(finalText, agent) {
-    this._emit((id) => this._d.client.sent(id, finalText, agent), true);
+    const variant = this._chosenVariant;
+    this._emit((id) => this._d.client.sent(
+      id, finalText, agent, variant !== "primary" ? `variant:${variant}` : "",
+    ), true);
   }
 
   /** 품질 점수 1~5 — 발송 전 여러 번 가능 (비소모). 사유는 여기 안 실린다(아래 계약). */

package/view.d.ts

@@ -84,3 +84,11 @@ export declare function feedbackBarView(input: {
 } | null;
 /** action: "up" | "down" — 어댑터가 자기 이벤트로 배선한다 */
 export declare function feedbackBarTree(input: Parameters<typeof feedbackBarView>[0]): AiSuggestNode | null;
+
+export declare const CAND_CLS: Record<string, string>;
+/** 다안 피커 트리 (0.8.0) — 2안 미만이면 null. 노드의 index 는 choose(index) 배선용. */
+export declare function candidatePickerTree(input: {
+  candidates: Array<{ variant: string; label: string; answer: string }>;
+  chosen?: string;
+  messages?: Record<string, string>;
+}): object | null;

package/view.js

@@ -419,3 +419,49 @@ export function feedbackBarTree(input) {
     ],
   };
 }
+
+
+// ── 다안 피커 (0.8.0) — 후보 2~3안 중 하나를 초안으로 ──────────────────────
+export const CAND_CLS = {
+  root: "fcx-cand",
+  item: "fcx-cand-item",
+  label: "fcx-cand-label",
+  excerpt: "fcx-cand-excerpt",
+  meta: "fcx-cand-meta",
+  use: "fcx-cand-use",
+};
+
+const CAND_EXCERPT_CHARS = 160;
+
+/**
+ * 후보 목록의 프레임워크 중립 트리. 후보가 2안 미만이면 null — 피커는
+ * "고를 것이 있을 때"만 선다 (빈 상자 금지, aiSuggestTree 와 같은 규율).
+ * 노드에 `index` 가 있으면 어댑터가 choose(index) 로 배선한다.
+ */
+export function candidatePickerTree({ candidates, chosen, messages } = {}) {
+  const list = Array.isArray(candidates) ? candidates : [];
+  if (list.length < 2) return null;
+  const m = messages || {};
+  return {
+    tag: "div", cls: CAND_CLS.root,
+    children: list.map((c, index) => {
+      const isChosen = String(c.variant || "") === String(chosen || "primary");
+      return {
+        tag: "div",
+        cls: isChosen ? `${CAND_CLS.item} is-chosen` : CAND_CLS.item,
+        children: [
+          { tag: "span", cls: CAND_CLS.label,
+            text: String(c.label || c.variant || "") },
+          { tag: "div", cls: CAND_CLS.excerpt,
+            text: String(c.answer || "").slice(0, CAND_EXCERPT_CHARS) },
+          { tag: "span", cls: CAND_CLS.meta,
+            text: isChosen ? (m.ui_candidate_chosen || "") : "" },
+          ...(isChosen ? [] : [{
+            tag: "button", cls: CAND_CLS.use, type: "button", disabled: false,
+            text: m.ui_candidate_use || "", action: "choose", index,
+          }]),
+        ],
+      };
+    }),
+  };
+}