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

package/react.js

@@ -19,7 +19,7 @@
  */
 import { createElement as h, useCallback, useEffect, useRef, useState } from "react";
 
-import { aiSuggestTree, aiSuggestView, CLS } from "./view.js";
+import { actionOffersTree, aiSuggestTree, aiSuggestView, CLS } from "./view.js";
 
 // 표시 판단은 프레임워크 중립 코어가 갖는다 — Vue·웹 컴포넌트와 같은 것을 쓴다.
 export { aiSuggestView };
@@ -97,3 +97,82 @@ export function AiSuggestPanel({ hook, inquiry, context, onAdopt, className }) {
 }
 
 export default AiSuggestPanel;
+
+// ── 처리 선택지 카드 (actions/1 프로파일 B) ───────────────────────────────
+//
+// 답변 패널과 같은 이유로 라이브러리에 있다: 카드 상태(잠김·비활성·확인 2단·
+// 실행 중·완료·실패·확인 필요·미보고), 확인 문구, 재실행 금지 규약은 전부 제품
+// 지식이다. 고객사는 배치만 한다 — 세션과 행위자 이름을 넘기면 끝.
+//
+// ```jsx
+// import { ActionOffersPanel } from "@fcg-labs/cx-agent-hook/react";
+// <ActionOffersPanel session={getCsSession(csId)} agent={agent} actorClaimed={answerWriter} />
+// ```
+
+/**
+ * @param {object} props
+ * @param {object} props.session   agent.session(externalId) — offers·pending·executeAction 의 소유자
+ * @param {object} props.agent     createCxAgent() 결과 — actionsEnabled·messages
+ * @param {string} [props.actorClaimed]  표시용 행위자 이름(자기 주장) — 원장에 남는다
+ * @param {(r: object) => void} [props.onResult]  실행 결과 콜백 ({requestId, state, reasonCode, message, reported})
+ * @param {string} [props.className]  바깥 배치용 (레이아웃만)
+ */
+export function ActionOffersPanel({ session, agent, actorClaimed, onResult, className }) {
+  const [offers, setOffers] = useState(() => (session ? session.offers : []));
+  const [pending, setPending] = useState(() => (session ? session.pendingActions() : []));
+  const [confirming, setConfirming] = useState(null);
+  const [ackedOffer, setAckedOffer] = useState(null);   // 고위험 확인은 **offer 단위** — 다른 카드의 체크가 이월되지 않는다
+
+  // 세션이 offers·pending 을 밀어준다 — 답변이 오거나 실행 상태가 바뀔 때
+  useEffect(() => {
+    if (!session || typeof session.attachActionUi !== "function") return undefined;
+    session.attachActionUi({ setOffers: (o, p) => { setOffers(o); setPending(p); } });
+    return () => session.detachActionUi();
+  }, [session]);
+  useEffect(() => { setConfirming(null); setAckedOffer(null); }, [session]);
+
+  const actorRef = useRef(actorClaimed);
+  actorRef.current = actorClaimed;
+
+  const execute = useCallback(async (offerId) => {
+    const offer = offers.find((o) => o.offer_id === offerId);
+    if (!offer) return;
+    if (offer.risk_level === "high" && ackedOffer !== offerId) return;   // 2단 확인 미완
+    setConfirming(null); setAckedOffer(null);
+    const r = await session.executeAction(offer, { actorClaimed: actorRef.current });
+    if (onResult) onResult(r);
+  }, [offers, ackedOffer, session, onResult]);
+
+  if (!session || !agent) return null;
+  const tree = actionOffersTree({ offers, pending, enabled: Boolean(agent.actionsEnabled), confirming, messages: agent.messages });
+  if (!tree) return null;
+
+  const actions = {
+    confirm: (e) => { setConfirming(e.currentTarget.dataset.offer || null); setAckedOffer(null); },
+    cancel: () => { setConfirming(null); setAckedOffer(null); },
+    ack: (e) => { const id = e.currentTarget.dataset.offer; setAckedOffer((v) => (v === id ? null : id)); },
+    execute: (e) => execute(e.currentTarget.dataset.offer),
+    resend: (e) => session.resendResult(e.currentTarget.dataset.request),
+  };
+  const render = (node, key) => {
+    const props = { key, className: node.cls };
+    if (node.tag === "button") { props.type = node.type || "button"; }
+    if (node.action && actions[node.action]) {
+      props.onClick = actions[node.action];
+      if (node.offerId) props["data-offer"] = node.offerId;
+      if (node.requestId) props["data-request"] = node.requestId;
+      if (node.action === "execute" && confirming) {
+        const o = offers.find((x) => x.offer_id === node.offerId);
+        if (o && o.risk_level === "high" && ackedOffer !== node.offerId) props.disabled = true;
+      }
+      if (node.pressed) props["aria-pressed"] = ackedOffer === node.offerId;
+    }
+    if (node.live) props.role = "status";
+    if (node.state) props["data-state"] = node.state;
+    if (node.risk) props["data-risk"] = node.risk;
+    return h(node.tag, props, node.children ? node.children.map((c, i) => render(c, i)) : node.text);
+  };
+  return h("div", { className: className ? `${tree.cls} ${className}` : tree.cls,
+                    onClick: (event) => event.stopPropagation() },
+           tree.children.map((n, i) => render(n, i)));
+}

package/session.js

@@ -20,6 +20,50 @@
  * 남기지 않는다 — 프라이버시 경계).
  */
 
+/** 처리 액션 pending 저장소 — 세션 영속(_persist·TTL 30분·consume 삭제)과
+ * **수명이 다르다**: 요청은 전송 **전에** 남고, 종단 뒤 24h 까지 살아 새로고침·
+ * 재진입 시 "이미 눌렀던 것" 을 안다. 정본은 허브 원장이다 — 브라우저 소실은
+ * 기록 손실이 아니라 표시 손실일 뿐. localStorage 부재면 메모리로만 산다. */
+import { executeViaAdminApi } from "./actions.js";
+
+export class ActionLedger {
+  constructor({ impl, prefix = "cx-agent-actions", terminalTtlMs = 24 * 60 * 60 * 1000 } = {}) {
+    this._impl = impl || (typeof localStorage !== "undefined" ? localStorage : null);
+    this._key = prefix;
+    this._ttl = terminalTtlMs;
+    this._mem = new Map();
+  }
+  _all() {
+    if (!this._impl) return this._mem;
+    try {
+      const raw = JSON.parse(this._impl.getItem(this._key) || "{}");
+      return new Map(Object.entries(raw));
+    } catch { return new Map(); }
+  }
+  _save(map) {
+    if (!this._impl) { this._mem = map; return; }
+    try { this._impl.setItem(this._key, JSON.stringify(Object.fromEntries(map))); } catch { /* quota */ }
+  }
+  put(requestId, rec) {
+    const m = this._all();
+    m.set(requestId, { ...rec, at: Date.now() });
+    this._save(this._prune(m));
+  }
+  get(requestId) { return this._all().get(requestId) || null; }
+  forInquiry(externalId) {
+    const out = [];
+    for (const [rid, r] of this._all()) if (r.externalId === externalId) out.push({ requestId: rid, ...r });
+    return out;
+  }
+  _prune(m) {
+    const now = Date.now();
+    for (const [rid, r] of m) {
+      if ((r.state === "succeeded" || r.state === "failed") && now - (r.at || 0) > this._ttl) m.delete(rid);
+    }
+    return m;
+  }
+}
+
 const NOT_CONFIGURED = () => ({
   ok: false, answered: false, answer: "", answerId: null,
   evidence: [], declinedReason: "not_configured", raw: {},
@@ -109,6 +153,9 @@ export class InquirySession {
     this._statusText = "";
     this._answerId = null;
     this._composeSeq = 0;
+    this._offers = [];              // 마지막 답변의 처리 선택지 (actions/1 §4)
+    this._actionUi = null;
+    this._locks = {};               // action_key\x00target_key → 잠금 조회 결과 (세션 캐시)
 
     // 영속 복원 — TTL 만료분은 store 가 이미 걸렀다
     if (this._id && deps.store) {
@@ -123,6 +170,142 @@ export class InquirySession {
   }
 
   get externalId() { return this._id; }
+  /**
+   * 처리 선택지 (만료 제외) + 브라우저 판정 두 가지를 병합해 돌려준다:
+   *   available: 이 CMS 가 그 API 를 아는가 (adminApi.endpoints[endpoint_key]) — fail-closed
+   *   locked:    같은 대상·같은 입력의 최근 성공이 허브에 있는가 (refreshActionLocks 결과)
+   * 실행 여부는 pendingActions() 로.
+   */
+  get offers() {
+    const now = Date.now();
+    const d = this._d;
+    const endpoints = d.adminApi && d.adminApi.endpoints;
+    return this._offers
+      .filter((o) => !o.expires_at || Date.parse(o.expires_at) > now)
+      .map((o) => {
+        const ek = o.execution && o.execution.endpoint_key;
+        const available = Boolean(d.adminApi && typeof d.adminApi.request === "function" && ek && endpoints && endpoints[ek]);
+        const lock = this._locks[`${o.action_key}\x00${o.target_key || ""}`];
+        const locked = Boolean(lock && lock.locked && lock.paramsHash && lock.paramsHash === o.params_hash);
+        return { ...o, available, locked, lock: locked ? { at: lock.at, actorClaimed: lock.actorClaimed, requestId: lock.requestId } : null };
+      });
+  }
+  attachActionUi(ui) { this._actionUi = ui; this._notifyActions(); }
+  detachActionUi() { this._actionUi = null; }
+  _notifyActions() {
+    if (this._actionUi && typeof this._actionUi.setOffers === "function") {
+      try { this._actionUi.setOffers(this.offers, this.pendingActions()); } catch { /* UI 오류가 세션을 죽이지 않는다 */ }
+    }
+  }
+  /** 이 문의에서 눌렀던 처리들 (pending·unknown·종단 24h 내) — 정본은 허브 원장 */
+  pendingActions() {
+    const d = this._d;
+    return d.actionLedger ? d.actionLedger.forInquiry(this._id) : [];
+  }
+  /**
+   * 잠금 갱신 — target_key 가 있는 offer 마다 허브에 (action_key, target_key) 최근 성공을
+   * 1회 묻는다. 세션 수명 동안 캐시(같은 키는 다시 안 묻는다; 실행 성공 후엔 자기가
+   * 갱신). 실패는 조용히 — 잠금은 편의이고 정본은 허브 원장·CMS 정책이다.
+   */
+  async refreshActionLocks() {
+    const d = this._d;
+    if (!d.client) return;
+    const jobs = [];
+    for (const o of this._offers) {
+      if (!o.target_key || !o.action_key) continue;
+      const k = `${o.action_key}\x00${o.target_key}`;
+      if (this._locks[k] !== undefined) continue;
+      this._locks[k] = null; // in-flight 표시 — 병렬 중복 질의 방지
+      jobs.push(d.client.actionLock(o.action_key, o.target_key).then((r) => {
+        this._locks[k] = r && r.ok ? r : { locked: false };
+      }).catch(() => { this._locks[k] = { locked: false }; }));
+    }
+    if (jobs.length) { await Promise.all(jobs); this._notifyActions(); }
+  }
+  /**
+   * 처리 실행 (프로파일 B, 3단) — 사람 확인은 호출자(UI)가 끝낸 뒤 부른다.
+   *   ① 허브 선점: request_id 를 발급해 **전송 전에** 영속, 재시도 0. 네트워크 오류면
+   *      상태 조회 1회 → 404(미도달)일 때만 같은 request_id 로 1회 재전송 (선점은 부작용
+   *      0 이라 안전). 선점이 안 되면 CMS 를 부르지 않는다 (원장 없는 실행 금지).
+   *   ② CMS 자기 API 호출: adminApi.request 1회, 카탈로그 response_rule 로 판정.
+   *   ③ 결과 보고: 실패하면 ledger 에 unreported 로 남기고 resendResult 로 재보고.
+   * unknown(전송 후 결과 불명)은 재실행하지 않는다 — 카드가 "확인 필요"로 남는다.
+   */
+  async executeAction(offer, { actorClaimed } = {}) {
+    const d = this._d;
+    if (!d.client || !offer || !offer.offer_id) return { ok: false, state: "", error: "not_configured" };
+    if (!d.adminApi || typeof d.adminApi.request !== "function") return { ok: false, state: "", error: "admin_api_missing" };
+    const endpoints = d.adminApi.endpoints || {};
+    const ek = offer.execution && offer.execution.endpoint_key;
+    if (!ek || !endpoints[ek]) return { ok: false, state: "", error: "endpoint_missing" };
+    const requestId = d.newRequestId();
+    const rec = { externalId: this._id, offerId: offer.offer_id, actionKey: offer.action_key,
+                  targetKey: offer.target_key || "", paramsHash: offer.params_hash || "",
+                  label: offer.label || "", state: "pending" };
+    if (d.actionLedger) d.actionLedger.put(requestId, rec);
+    // ① 선점
+    const args = { requestId, offer, actorClaimed, inquiryRef: this._id };
+    let r = await d.client.requestAction(args);
+    if (!r.ok && r.error === "network_error") {
+      const st = await d.client.actionStatus(requestId);
+      if (st.ok && st.state === "none") r = await d.client.requestAction(args);   // 미도달 확정 — 1회 재전송
+      else if (st.ok) r = { ...r, ok: true, state: st.state, error: null };
+    }
+    if (!r.ok) {
+      if (d.actionLedger) d.actionLedger.put(requestId, { ...rec, state: "failed", reasonCode: r.error || "reserve_failed", message: r.message || "" });
+      this._notifyActions();
+      return { requestId, ...r, state: "failed" };
+    }
+    if (r.state && r.state !== "received") {
+      // 재제출로 이미 종단·진행 중인 기록 — 그대로 (재실행 없음)
+      if (d.actionLedger) d.actionLedger.put(requestId, { ...rec, state: r.state, reasonCode: r.reasonCode || "", message: r.message || "" });
+      this._notifyActions();
+      return { requestId, ...r };
+    }
+    if (d.actionLedger) d.actionLedger.put(requestId, { ...rec, state: "received" });
+    // ② CMS 자기 API — 재시도 0
+    const out = await executeViaAdminApi(d.adminApi, offer);
+    if (out.authExpired && typeof d.adminApi.onAuthExpired === "function") {
+      try { d.adminApi.onAuthExpired(out.body); } catch { /* 호출자 오류 무시 */ }
+    }
+    // ③ 보고
+    const report = { state: out.state, reasonCode: out.reasonCode, message: out.message,
+                     httpStatus: out.httpStatus, latencyMs: out.latencyMs };
+    const rep = await d.client.reportActionResult(requestId, report);
+    const unreported = !rep.ok && rep.httpStatus === 0; // 네트워크 — 다시 보고 가능
+    if (d.actionLedger) {
+      d.actionLedger.put(requestId, { ...rec, state: out.state, reasonCode: out.reasonCode || "",
+                                      message: out.message || "", unreported, pendingReport: unreported ? report : undefined });
+    }
+    if (out.state === "succeeded" && offer.target_key) {
+      this._locks[`${offer.action_key}\x00${offer.target_key}`] = { locked: true, paramsHash: offer.params_hash,
+        at: new Date().toISOString(), actorClaimed: actorClaimed || "", requestId };
+    }
+    this._notifyActions();
+    return { requestId, ok: true, state: out.state, reasonCode: out.reasonCode, message: out.message,
+             reported: !unreported, error: null };
+  }
+  /** 미보고 결과 재보고 — 재실행이 아니다. ledger 의 pendingReport 만 다시 보낸다. */
+  async resendResult(requestId) {
+    const d = this._d;
+    if (!d.client || !d.actionLedger || !requestId) return { ok: false, error: "not_configured" };
+    const rec = d.actionLedger.get(requestId);
+    if (!rec || !rec.pendingReport) return { ok: false, error: "nothing_to_report" };
+    const rep = await d.client.reportActionResult(requestId, rec.pendingReport);
+    if (rep.ok || (rep.httpStatus && rep.httpStatus !== 0)) {
+      // 허브가 받았거나(200) 거절 확정(409/404/422)이면 더 재보고할 것이 없다
+      d.actionLedger.put(requestId, { ...rec, unreported: false, pendingReport: undefined,
+                                      reportError: rep.ok ? "" : (rep.error || "") });
+    }
+    this._notifyActions();
+    return rep;
+  }
+  /** 미보고 전부 재시도 — 세션 진입·offer 갱신 시 1회 (fire-and-forget). */
+  async flushUnreportedActions() {
+    for (const p of this.pendingActions()) {
+      if (p.unreported && p.pendingReport) await this.resendResult(p.requestId);
+    }
+  }
   get state() { return this._state; }
   get draft() { return this._draft; }
   get adoptedAnswerId() { return this._answerId; }
@@ -263,6 +446,15 @@ export class InquirySession {
         // 않는다. 0.2.3: 이전 문의 초안이 새 에디터에 주입되던 오염 경로 차단.
         return result;
       }
+      // 처리 선택지 — 답변·거절 무관하게 payload 에 실린다 (만료는 expires_at)
+      this._offers = Array.isArray(result.raw && result.raw.suggested_actions)
+        ? result.raw.suggested_actions.filter((o) => o && o.offer_id) : [];
+      this._notifyActions();
+      // 잠금 조회·미보고 재보고는 백그라운드 — 답변 표시를 막지 않는다
+      if (this._offers.length) {
+        this.refreshActionLocks().catch(() => {});
+        this.flushUnreportedActions().catch(() => {});
+      }
       if (result.answered) {
         this._draft = decorate(result.answer); // 정본 확정 (strip+데코레이터)
         this._setUiDraft(this._draft);

package/skills/cx-agent-hook-setup/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: cx-agent-hook-setup
+description: Use when a developer asks to set up, wire, integrate, add, or upgrade "@fcg-labs/cx-agent-hook" (a.k.a. cx-agent-hook, CX agent hook, CS AX hook, FCG CX Agent) in a CMS / admin web app — the AI answer-draft panel AND the action cards (adminApi). Triggers include "cx-agent-hook 셋업", "cx-agent-hook 붙여줘", "CS AX 연동", "AI 답변 초안 패널 붙이기", "처리 카드 / 처리 액션 붙여", "adminApi 배선", "hook 0.5 로 올려", "wire cx-agent-hook", "install cx agent hook", "action cards". Also use for upgrades from 0.2/0.3/0.4 to 0.5. Never skip the adminApi step unless the project has no admin API at all.
+---
+
+# cx-agent-hook 셋업 — 에이전트 작업 절차
+
+`@fcg-labs/cx-agent-hook` 은 고객사 관리자 화면(CMS)에 두 가지를 붙이는 SDK 다:
+① **AI 답변 초안** 패널(문의 → 초안 → 상담사 편집·발송 후킹) ② **처리 카드**(답변 옆에
+"이 처리를 할까요?" 카드 — 누르면 **이 CMS 의 기존 관리자 API 를 CMS 세션으로** 호출).
+설치·환경변수·훅 파일·슬롯 2개·확인, 여섯 단계가 전부다. 서버에 새로 만드는 것은 없다.
+
+**이 스킬을 따르는 에이전트의 완료 정의**: 아래 §5 체크리스트 전부 참. 특히
+`adminApi` 를 넘긴 훅 + `agent` export + 처리 카드 슬롯이 빠지면 미완이다 — 개발자가
+"답변 패널만" 이라고 명시하지 않는 한 처리 카드까지가 셋업이다.
+
+정확한 API 이름·옵션·이벤트는 같은 폴더의 **reference.md** 가 정본이다. 거기 없는
+export·옵션·컴포넌트를 쓰지 말 것 (`node_modules/@fcg-labs/cx-agent-hook/*.d.ts` 로
+재확인 가능). 이 문서의 코드는 그 정본에서 만든 예다.
+
+## 0. 하는 일 / 하지 않는 일
+
+| 한다 | 하지 않는다 |
+|---|---|
+| 패키지 설치·범위 상향, `.env` 3값, 훅 파일 1개, 답변 슬롯, 처리 카드 슬롯, 확인 | 서버 엔드포인트·어댑터·서명 검증·토큰 발급 코드 (없어야 정상) |
+| 이 CMS 에 **이미 있는** 요청 헬퍼·엔드포인트 맵·세션 만료 처리의 **참조**를 넘김 | 새 관리자 API 를 만들거나 기존 API 의 정책(권한·횟수 제한)을 바꾸는 일 |
+| 프로젝트 성격(프레임워크·번들러·경로 별칭·헬퍼 시그니처)에 맞춰 코드를 조정 | 비밀 생성·저장 (토큰은 운영자가 CS AX 공장 시스템 탭 [연동] 에서 받아 준다) |
+| 실측 표를 먼저 쓰고, 편집 후 빌드·확인까지 | 재시도·자동 실행·정책 판단을 SDK 밖에서 덧붙이는 일 |
+
+## 1. 먼저 실측한다 (편집 전에 아래 표를 채워 개발자에게 보여준다)
+
+| 항목 | 어떻게 찾나 | 결정에 쓰이는 곳 |
+|---|---|---|
+| 프레임워크 | `package.json` dependencies: `react`·`vue`·둘 다 없음(순수 HTML/Astro/Angular) | 어댑터 서브패스: `/react` · `/vue` · `/element` |
+| 번들러·env 접근 | `vite.config.*` → `import.meta.env.VITE_*` / webpack·CRA → `process.env.REACT_APP_*` / Next → `process.env.NEXT_PUBLIC_*` / 번들러 없음 → 값을 훅 파일에 직접 | `.env` 키 접두·훅 파일의 env 읽기 |
+| 경로 별칭 | `vite.config.*`/`tsconfig.json` `paths`/`jsconfig.json` (`@`, `@src`, `~` …) | 화면 파일에서 훅을 import 하는 경로 |
+| 기존 훅 | `grep -rn "cx-agent-hook\|createCxAgent\|createCxHook" src` | 없음 → 새로 만든다 / `createCxHook`(0.2) → 0.3 세션 표면으로 / `createCxAgent`(0.3~0.4) → `adminApi` 추가·`agent` export |
+| 현재 버전 | `package.json` 의 `@fcg-labs/cx-agent-hook` 범위 + `node_modules/@fcg-labs/cx-agent-hook/package.json` | `^0.3.0`/`^0.4.0` 은 0.x semver 라 0.5 를 못 받는다 → `^0.5.0` 으로 올리고 재설치 |
+| **관리자 API 요청 헬퍼** | `grep -rn "axios.create\|static async request\|function request(\|apiClient\|httpClient" src` — 관리자 화면이 서버를 부를 때 쓰는 공용 함수. 시그니처(인자 이름 `method/url/path/query/data|body`)를 적는다 | `adminApi.request` — SDK 는 `{method, url, path, query, data}` 로 부르고 응답이 axios 형(`{status,data}`)이든 본문이든 받는다. 시그니처가 다르면 훅 파일에 5줄 이하 어댑터 |
+| **엔드포인트 맵** | 상수 파일: `{KEY: "…/users/:id/…"}` 모양의 URL 맵(예: `EndPoint`, `API_MAP`, `endpoints`). `:param` 표기가 있으면 그것 | `adminApi.endpoints` — 처리 카드 후보 목록·실행 URL 의 원천 |
+| 메서드 화이트리스트(선택) | `{get:{[url]:…}, post:{…}}` 처럼 메서드→URL 맵이 있으면 | `adminApi.map` — 후보의 메서드 추출용. 없으면 생략 |
+| 세션 만료 처리(선택) | 4011/401 등에서 로그인으로 보내는 함수(`handleAuthExpired…`, `forceLogout…`) | `adminApi.onAuthExpired` |
+| 문의 화면 | 문의 목록·답변 편집기·발송 버튼이 있는 컴포넌트. 문의 ID(`csId`·`inquiryId`), 본문, 고객 식별자(`userId`·`subUserId`), 상담사 이름 변수 | 답변 슬롯·처리 카드 슬롯 위치, `context`·`actorClaimed` 값 |
+| 연동 값 | 개발자가 받은 허브 주소·브라우저 토큰·도메인 (CS AX 공장 [연동] 화면의 `.env` 3줄) | 없으면 자리표시자로 두고 **어디서 받는지** 명시(값을 지어내지 않는다) |
+
+관리자 API 헬퍼·엔드포인트 맵이 **정말 없으면**(관리자 화면이 서버를 직접 부르지 않는 구조)
+개발자에게 그 사실을 알리고 `adminApi` 없이 진행한다 — 이때 처리 카드는 나오지 않고
+답변 패널만 동작한다는 것을 결과 보고에 적는다. 있는데 빼먹는 것은 실패다.
+
+## 2. 결정 규칙
+
+- 어댑터: React → `/react` `AiSuggestPanel`·`ActionOffersPanel` / Next App Router → `/next`(같은 이름,
+  `"use client"` 경계를 라이브러리가 선언; `/react` 를 직접 쓰면 그 파일 첫 줄에 `"use client"`) / Vue 3 → `/vue`
+  같은 이름 / Astro·Angular·순수 HTML → `/element`(또는 `/astro`·`/angular` 재수출) `<cx-ai-suggest>`·
+  `<cx-action-offers>`. 스타일은 공통 `styles.css` 1회 import(진입 파일이나 슬롯 컴포넌트 중 한 곳으로 확정).
+- 훅은 **한 파일에서 한 번** 만들고 `agent`·`getCsSession` 을 export 한다. 화면은 그 결과만
+  import 한다. 이 파일에는 배선 외 로직(상수·화면 판단)을 넣지 않는다.
+- `adminApi.request` 는 기존 헬퍼를 **참조로** 넘긴다. 시그니처가 SDK 와 다르면 훅 파일 안에
+  얇은 어댑터(인자 이름 매핑만)를 둔다 — 예: `request: (a) => AdminApi.call({ ...a, body: a.data })`.
+  `this` 를 쓰는 인스턴스 메서드면 `bind` 한다.
+- `endpoints` = 키→URL 템플릿(엔드포인트 맵), `map` = 메서드 화이트리스트. **바꿔 넣으면**
+  후보 발행이 조용히 0건이 된다(에러 없음).
+- `actorClaimed` = 답변 발송에 쓰는 상담사 이름과 **같은 변수** (원장 대조).
+- 처리 카드 슬롯은 세션당 1곳(인스펙터/상세 패널). 문의 목록 행마다 붙이지 않는다 — 세션의
+  카드 sink 는 하나라(`attachActionUi` 덮어쓰기) 두 곳이면 서로 끊는다. 카드는 **그 문의에서 초안
+  (`compose`)을 한 번 받은 뒤**에만 나오고 새로고침하면 다시 초안을 받아야 한다 — 슬롯 위치는 답변
+  초안 흐름과 같은 화면이어야 한다.
+- 값이 없을 때 폴백은 **빈 문자열**(`""`) — `"<허브 주소>"` 같은 자리표시자 문자열은 truthy 라 `enabled`
+  가 참으로 나와 확인 단계를 거짓 통과한다.
+- 기존 훅이 `storage: { enabled: false }` 면 처리 원장(미보고 재보고·눌렀던 것 기억)도 함께 꺼진다 —
+  개발자에게 알리고 `storage.actionsImpl` 로 원장만 살릴지 정한다.
+- 산출 코드는 **파일 단위 완전체**로 준다(붙여넣기가 성립: Vue 는 `<script setup>` 안에, React 는 컴포넌트 안에).
+  실측 항목 중 파일을 열어 확정할 수 있는 것은 묻지 않는다 — 개발자 질문은 정말 모르는 것만 5개 이하.
+- 답변 패널은 0.3 세션 표면(`session.attachUi/compose/answerSent`) 이 권장. 이미 0.2
+  `AiSuggestPanel hook={createCxHook(...)}` 를 쓰고 있으면 그대로 두어도 되지만, 처리 카드는
+  `createCxAgent` 의 세션이 필요하므로 훅을 `createCxAgent` 로 만들고 `agent.session()` 을 쓴다.
+
+## 3. 단계 (코드는 프로젝트 실측값으로 치환한다)
+
+### 3-1 설치 / 범위 상향
+```bash
+npm install @fcg-labs/cx-agent-hook@^0.5.0    # yarn add / pnpm add 동일
+```
+`package.json` 에 `"@fcg-labs/cx-agent-hook": "^0.5.0"` 이 있는지, `node_modules/…/package.json`
+버전이 0.5.x 인지 확인한다.
+
+### 3-2 환경변수 (`.env` — Vite 예. 접두는 §1 번들러 규칙대로)
+```bash
+VITE_CX_HUB_URL=<허브 주소>
+VITE_CX_HUB_BROWSER_TOKEN=<브라우저 토큰>
+VITE_CX_DOMAIN=<도메인>
+```
+값은 개발자가 CS AX 공장 [연동] 화면에서 받아 온다. 이 토큰은 도메인에 묶인 브라우저
+등급이라 번들에 실려도 되고, 학습 산출물에는 닿지 못한다.
+
+### 3-3 훅 파일 (`src/utils/cxAgent/hook.js` 등 프로젝트 관례 위치) — **adminApi 포함**
+```js
+import { createCxAgent } from "@fcg-labs/cx-agent-hook/agent";
+import AdminApi, { EndPoint } from "../../constant/AdminApi";           // ← 실측한 요청 헬퍼 + 엔드포인트 맵
+import AdminApiMap from "../../constant/AdminApiMap";                  // ← 실측한 메서드 화이트리스트(있을 때)
+import { handleAuthExpiredResponse } from "../session/sessionManager"; // ← 실측한 세션 만료 처리(있을 때)
+
+const env = import.meta.env;                                           // 번들러 규칙대로
+export const agent = createCxAgent({
+  baseUrl: env.VITE_CX_HUB_URL,
+  token: env.VITE_CX_HUB_BROWSER_TOKEN,
+  domain: env.VITE_CX_DOMAIN,
+  api: "hub",
+  locale: "ko",                                                          // ko | en | ja | zh-TW
+  // 처리 카드 — 이 CMS 의 관리자 API 를 CMS 세션으로 부른다 (참조만, 새로 짜는 코드 없음)
+  adminApi: { request: AdminApi.request, endpoints: EndPoint,
+              map: AdminApiMap, onAuthExpired: handleAuthExpiredResponse },
+});
+export const getCsSession = (csId) => agent.session(csId);   // 문의별 세션 — 같은 ID 는 같은 인스턴스
+export const isCxHookEnabled = agent.enabled;
+```
+훅이 뜨면 SDK 가 엔드포인트 맵의 키·메서드·경로 템플릿(호스트 제거)을 허브에 1회 발행한다 —
+운영자가 CS AX 공장에서 "이 CMS 가 이미 하는 처리" 목록으로 보고 처리 선택지를 만든다.
+파라미터 스키마는 발행되지 않는다(맵에 없다) — 운영자 몫.
+
+### 3-4 답변 초안 슬롯 (문의 화면)
+```js
+import { getCsSession } from "<별칭>/utils/cxAgent/hook";
+
+const session = getCsSession(inquiry.id);
+session.attachUi({ getDraft: () => editorText, setDraft: setEditorText, setStatus: setAiStatus }).restore();
+// [AI 초안] 버튼 — context 는 고객 정보 키(처리 카드 입력값의 원천이기도 하다). 있는 것만.
+await session.compose({ inquiry: inquiry.content,
+  context: { external_id: inquiry.id, user_id: inquiry.userId, sub_user_id: inquiry.subUserId } }).promise;
+// 발송 버튼
+session.answerSent(finalText, agentName);
+```
+문의를 바꾸면 그 문의의 세션을 다시 `attachUi(...).restore()` 한다(이전 세션은 `detachUi()`).
+`context` 값은 문자열로 정규화되고 빈 값은 버려진다 — 처리 카드 입력값의 원천이니 값이 있는 키만 넣는다.
+기존 프로젝트가 이미 0.3 세션 표면으로 붙어 있으면(예: `attachUi` 후 `session.draft` 를 직접 읽음) 동등한
+표면이므로 손대지 않고 "이미 배선됨"으로 정산한다.
+
+### 3-5 처리 카드 슬롯 (문의 상세/인스펙터 패널 1곳)
+React:
+```jsx
+import { ActionOffersPanel } from "@fcg-labs/cx-agent-hook/react";
+import "@fcg-labs/cx-agent-hook/styles.css";
+import { agent, getCsSession } from "<별칭>/utils/cxAgent/hook";
+
+<ActionOffersPanel session={getCsSession(inquiry.id)} agent={agent} actorClaimed={agentName}
+                   onResult={(r) => { if (r.state === "succeeded") refreshInquiry(); }} />
+```
+Vue 3: `import { ActionOffersPanel } from "@fcg-labs/cx-agent-hook/vue"` →
+`<ActionOffersPanel :session="getCsSession(inquiry.id)" :agent="agent" :actor-claimed="agentName" @result="onActionResult" />`
+순수 HTML/그 밖: `import { defineCxActionOffers } from "@fcg-labs/cx-agent-hook/element"; defineCxActionOffers();`
+→ `<cx-action-offers>` 에 `el.agent = agent; el.session = getCsSession(id); el.actorClaimed = agentName;`
+이벤트 `cx-action-result`. (번들러가 없으면 import map 으로 `@fcg-labs/cx-agent-hook/` 를
+`/node_modules/@fcg-labs/cx-agent-hook/` 에 매핑하고 훅의 env 자리에 값을 직접 적는다.)
+
+### 3-6 확인
+1. 빌드·타입체크 통과. 2. CMS 를 열고 개발 콘솔에서(훅 파일에 개발 환경 한정으로 `window.__cxAgent = agent` —
+Vite `import.meta.env.DEV`, 번들러 없으면 `location.hostname === "localhost"` 조건 — 을 두거나
+`console.log(agent.actionsEnabled)`) `actionsEnabled === true`, `await agent.candidatesReady` 가
+`{ok:true, count:N}`. 3. 운영자에게 "공장 시스템 탭 [처리 액션] 에 후보 N건 도착" 을 확인해 달라고
+전한다. 4. 운영자가 처리 선택지를 승인하면, **어떤 문의에서 [AI 초안]을 받은 뒤** 그 답변 옆에 카드가
+나온다(`session.offers.length > 0`). 초안을 받기 전·새로고침 직후에는 카드가 없는 것이 정상이다.
+
+## 4. 규약 (어기면 되돌린다)
+- `adminApi` 없이 끝내지 않는다(관리자 API 자체가 없을 때만 예외 — 보고에 명시).
+- 훅 파일은 `agent`·`getCsSession` 을 export 한다 — 카드 컴포넌트가 `agent` 를 직접 받는다.
+- 서버 코드·새 엔드포인트·서명·토큰 발급을 만들지 않는다. 비밀을 저장소에 넣지 않는다.
+- SDK 호출에 재시도·자동 실행을 덧대지 않는다(계약: 재시도 0, 사람 확인 후 실행).
+- reference.md 에 없는 이름을 쓰지 않는다. `context` 는 값이 있는 키만 넣는다.
+- 기존 동작(문의 목록·발송 로직)은 건드리지 않는다 — 배선만 더한다.
+
+## 5. 완료 체크리스트 (전부 참이어야 완료)
+- [ ] `^0.5.0` 이상 설치·재설치됨
+- [ ] `.env` 3값(또는 자리표시자 + 어디서 받는지 명시)
+- [ ] 훅 파일 1개: `createCxAgent({... adminApi: {request, endpoints, map?, onAuthExpired?}})`, `export const agent`, `getCsSession`
+- [ ] 답변 슬롯: `attachUi(...).restore()` · `compose({inquiry, context}).promise` · `answerSent(finalText, agentName)`
+- [ ] 처리 카드 슬롯 1곳 (`ActionOffersPanel` / `<cx-action-offers>`) + `styles.css` import + `actorClaimed`
+- [ ] 빌드 통과 · `agent.actionsEnabled === true` · `candidatesReady.ok` · (선택지 승인 후) 초안 요청한 문의에서 `session.offers.length > 0` 로 카드 노출
+- [ ] 결과 보고: 실측 표 · 바뀐 파일 목록 · 운영자에게 전할 확인 항목 · 넘긴 참조 3~4개의 이름
+
+## 6. 업그레이드 요약 (자세한 것은 패키지 MIGRATION.md)
+- 0.2 `createCxHook`/`AiSuggestPanel hook=` → 0.3 `createCxAgent`+`agent.session()` (호환 표면은 남아 있음)
+- 0.4 의 `actorAssertion` 옵션·`session.reconcileAction` 은 0.5 에서 **삭제됐다** → 대체는 `adminApi` 옵션·
+  `session.resendResult` (둘 다 0.5 신설이며 필수/권장).
+- 처리 카드는 0.5 부터. `^0.3.0`/`^0.4.0` 범위는 0.5 를 받지 못한다.
+
+## 7. 문제 해결
+| 증상 | 원인 | 조치 |
+|---|---|---|
+| `agent.actionsEnabled === false` | 전송 3값(baseUrl·token·domain) 중 누락, 또는 `adminApi.request` 가 함수가 아니거나 `endpoints` 가 객체가 아님 | `.env` 값·참조 이름·바인딩 확인 |
+| `candidatesReady` → `{ok:false, error:"not_configured"}` | `adminApi` 미인식(위와 같은 조건)·전송 3값 누락·`api !== "hub"` | 위 + `api:"hub"` |
+| 카드가 아예 안 보임(에러 없음) | 그 문의에서 아직 초안(`compose`)을 안 받았거나 새로고침으로 offers 가 비었음, 또는 승인된 선택지의 조건에 안 맞음 | [AI 초안] 후 확인 · 운영자에게 선택지 조건 확인 |
+| 카드가 "이 CMS 에 없는 처리" 로 회색 | 승인된 선택지의 API 키가 이 CMS 의 `endpoints` 에 없음 | 운영자와 키 대조(대소문자·이름) |
+| 카드는 있는데 눌러도 실패 (`error:"endpoint_missing"` / `reasonCode:"invalid_execution"`+`message:"params_missing"`) | 실행 사양이 이 CMS 맵·입력값과 어긋남 | 운영자에게 처리 선택지 편집 요청 |
+| 실행 후 "결과가 아직 기록되지 않음" | 허브 보고 네트워크 실패 | 카드의 [결과 다시 보고] — 재실행 아님 |
+| 후보가 공장에 안 보임 | 훅이 아직 안 떴거나 지문 마커로 재발행 생략 | CMS 를 다시 열거나 콘솔 `agent.publishActionCandidates({force:true})` |

package/skills/cx-agent-hook-setup/reference.md

@@ -0,0 +1,92 @@
+# cx-agent-hook 참조표 — 스킬이 인용해도 되는 이름 전부 (0.5.x)
+
+이 표에 없는 export·옵션·prop·이벤트는 존재하지 않는다고 본다. 의심되면
+`node_modules/@fcg-labs/cx-agent-hook/{agent,react,vue,element,view}.d.ts` 를 연다.
+`test/skills.test.js` 가 이 표의 export 이름을 실제 모듈과 대조한다(드리프트 가드).
+
+## 서브패스와 export
+
+<!-- exports:begin — 형식: `subpath | export1, export2` (시험이 파싱한다) -->
+| 서브패스 | export |
+|---|---|
+| `@fcg-labs/cx-agent-hook` | createCxHook, LOCALES, MESSAGES, normalizeLocale, declineText |
+| `@fcg-labs/cx-agent-hook/agent` | createCxAgent, textOf, notConfiguredResult, koreanGreetingDecorator, LOCALES, MESSAGES, normalizeLocale, ACTION_CLS, actionOffersTree, actionOffersView, buildCandidateSnapshot, executeViaAdminApi, judgeResponse, resolveExecution |
+| `@fcg-labs/cx-agent-hook/react` | AiSuggestPanel, ActionOffersPanel, aiSuggestView |
+| `@fcg-labs/cx-agent-hook/vue` | AiSuggestPanel, ActionOffersPanel, aiSuggestView |
+| `@fcg-labs/cx-agent-hook/element` | TAG, ACTIONS_TAG, defineCxAiSuggest, defineCxActionOffers, aiSuggestView |
+| `@fcg-labs/cx-agent-hook/next` | AiSuggestPanel, ActionOffersPanel, aiSuggestView |
+| `@fcg-labs/cx-agent-hook/astro` | TAG, ACTIONS_TAG, defineCxAiSuggest, defineCxActionOffers, aiSuggestView, setupCxAiSuggest |
+| `@fcg-labs/cx-agent-hook/angular` | TAG, ACTIONS_TAG, defineCxAiSuggest, defineCxActionOffers, aiSuggestView |
+| `@fcg-labs/cx-agent-hook/styles.css` | (CSS — `.fcx-ai-*` 답변 패널 · `.fcx-act-*` 처리 카드, 테마 변수 `--fcx-*`) |
+<!-- exports:end -->
+
+`/next`(App Router — 파일 첫 줄에 `"use client"` 를 라이브러리가 선언; `AiSuggestPanel`·**`ActionOffersPanel`** 재수출) ·
+`/astro`·`/angular`(`defineCxAiSuggest`·`TAG`·**`defineCxActionOffers`·`ACTIONS_TAG`** 재수출)도 있다.
+Next App Router 에서 `/react` 를 직접 쓰면 그 파일에 `"use client"` 를 적어야 한다(서버 컴포넌트에서 import 하면 런타임에 깨진다).
+`view.js`·`session.js`·`client.js`·`actions.js` 는 서브패스로 열려 있지 않다 — `/agent` 가 재수출하는
+`ACTION_CLS`·`actionOffersTree`·`actionOffersView`·`buildCandidateSnapshot`·`executeViaAdminApi`·`judgeResponse`·`resolveExecution`
+만 헤드리스 표면이다(`aiSuggestView` 는 어댑터 서브패스에서).
+
+## createCxAgent(config) 옵션 (`agent.d.ts` CxAgentSetup)
+
+| 옵션 | 필수 | 뜻 |
+|---|---|---|
+| `baseUrl` `token` `domain` | 예 (셋 다 없으면 전부 무동작) | 허브 주소 · 브라우저 토큰(도메인 묶임) · 도메인 |
+| `api` | 권장 `"hub"` | 대상. 처리 액션·후보 발행은 `"hub"` 에서만 |
+| `locale` | 선택 | `ko` `en` `ja` `zh-TW` (미지원은 en) |
+| `messages` | 선택 | 문구 override |
+| `bootstrap` | 선택 | 허브 client-config 병합 |
+| `source` | 선택(기본 `"cms"`) | 인그레스 채널명 |
+| `draftDecorators` | 선택 | 초안 후처리 사슬 (기본 한국어 호칭) |
+| `storage` | 선택 | `{enabled, ttlMs, maxSessions, prefix, impl, actionsImpl}` |
+| **`adminApi`** | 처리 카드에 필수 | `{ request, endpoints, map?, onAuthExpired? }` — 아래 |
+| `onError` | 선택 | 후킹 실패 기록 콜백 (화면을 막지 않는다) |
+
+### adminApi
+| 키 | 형 | 뜻 |
+|---|---|---|
+| `request` | `({method, url, path?, query?, data?}) => Promise<axios응답 \| 본문>` | 이 CMS 의 기존 요청 헬퍼 참조. `method` 소문자, `url` 은 `endpoints[key]` 원문(`:param` 포함), `path` 치환·`query`·`data` 는 헬퍼가 처리 |
+| `endpoints` | `Record<KEY, urlTemplate>` | 엔드포인트 맵. 처리 카드 후보·실행 URL 원천 |
+| `map` | `Record<method, Record<urlTemplate, unknown>>` | 메서드 화이트리스트(선택) — 후보 메서드 추출 |
+| `onAuthExpired` | `(body) => void` | HTTP 401/403 이거나, 2xx 본문의 코드가 카탈로그 `response_rule.auth_expired_codes` 에 걸릴 때 호출(인자 = 응답 본문) |
+
+## agent (CxAgent)
+`enabled` · `ready` · `flags` · `locale` · `messages` · `declineText(reason)` · `onConfigChange(fn)` ·
+`session(externalId, {persist?})` · `requestAnswer(inquiry, context?)` · `requestInvestigation(externalId, {userId?, subUserId?})` ·
+`investigationStatus(externalId)` · **`actionsEnabled`** · **`candidatesReady`** · **`publishActionCandidates({force?})`** · `inquirySent({externalId, inquiry, reply?, agent?, meta?})`
+
+## session (InquirySession = agent.session(id))
+답변: `attachUi({getDraft?, setDraft, setStatus?}): this` · `detachUi(): this` · `restore()` · `remember(text)` ·
+`compose({inquiry, context?, customerName?, confirmOverwrite?, idleTimeoutMs?, overallTimeoutMs?}) → {promise, abort}` ·
+`noteAdopted(id)` · `clearAdopted()` · `answerSent(finalText, agent?)` · `scored(score, agent?)` · `edited(finalText, agent?)` · `discarded(agent?, note?)`
+읽기: `externalId` · `state` · `draft` · `adoptedAnswerId`
+처리 카드: `offers` · `attachActionUi({setOffers}): void`(**세션당 sink 1개 — 나중 것이 앞 것을 덮고, 한쪽 detach 가 다른 쪽도 끊는다**) · `detachActionUi()` · `pendingActions()` ·
+`executeAction(offer, {actorClaimed?}) → {requestId, ok, state, reasonCode, message, reported, error}` — 선점 전 거절
+(`error: not_configured|admin_api_missing|endpoint_missing`)이면 `ok:false, state:""` 이고 `requestId` 가 없다 ·
+`resendResult(requestId)` · `flushUnreportedActions()` · `refreshActionLocks()`
+**offers 가 채워지는 유일한 경로는 그 세션의 `compose()` 응답**(`suggested_actions`) — 초안을 한 번도 안 받은 문의엔
+카드가 없고, 새로고침하면 offers 는 비고(pending 만 localStorage 에 남는다) 다시 `compose` 해야 카드가 온다.
+
+## 어댑터
+| 어댑터 | 답변 패널 | 처리 카드 |
+|---|---|---|
+| React (`/react`) | `<AiSuggestPanel hook inquiry context? onAdopt className?>` (0.2 훅용) | `<ActionOffersPanel session agent actorClaimed? onResult? className?>` |
+| Vue 3 (`/vue`) | `<AiSuggestPanel :hook :inquiry :context @adopt>` | `<ActionOffersPanel :session :agent :actor-claimed @result>` |
+| element (`/element`) | `defineCxAiSuggest()` → `<cx-ai-suggest>` (`el.hook` `el.inquiry` `el.context`, 이벤트 `cx-adopt`) | `defineCxActionOffers()` → `<cx-action-offers>` (`el.agent` `el.session` `el.actorClaimed`, 이벤트 `cx-action-result` detail=ActionResult) |
+
+처리 카드 상태(컴포넌트가 처리): 실행 가능 · 확인 2단(고위험은 체크 1번 더, aria-pressed 토글 버튼) ·
+실행 중 · 완료 · 실패(재시도 가능) · 확인 필요(unknown, 재실행 없음) · 이미 처리됨(잠김) ·
+이 CMS 에 없는 처리(비활성) · 결과 다시 보고(미보고). 문구 키 `ui_action_*` 17종(4 로케일).
+
+## 상태·값
+- `ActionResult.state`: `received` | `succeeded` | `failed` | `unknown` (선점 전 거절은 `""`); `reported=false` 면 `resendResult`.
+  실패 사유 위치: `error:"endpoint_missing"`(이 CMS 에 키 없음) · `reasonCode:"invalid_execution"` + `message:"params_missing"`(입력값 치환 실패) ·
+  `reasonCode:"business"|"auth_expired"|"http_client_error"`(CMS 응답 판정) · `state:"unknown"` + `reasonCode:"transport"|"http_server_error"`.
+- `context` 값은 전부 문자열로 정규화되고 **빈 값은 버려진다**(`0`·`""` 키 소실) — 처리 카드 입력값의 원천이므로 값이 있는 키만 문자열로.
+- `storage: { enabled: false }` 는 세션 영속뿐 아니라 **처리 원장(ActionLedger)도 끈다** → `pendingActions()` 빈 배열·미보고 재보고 불가. 공용 PC 정책으로 꺼 둔 프로젝트는 `storage.actionsImpl` 로 원장만 살릴지 결정한다.
+- `.env` 키(Vite 예): `VITE_CX_HUB_URL` `VITE_CX_HUB_BROWSER_TOKEN` `VITE_CX_DOMAIN` — 접두는 번들러 규칙대로.
+- 저장: 세션 sessionStorage(TTL 30분) · 처리 원장 localStorage(종단 24h) · 후보 발행 마커 `cx-agent-catalog:<domain>`(24h).
+- 재시도: 실행 0(선점만 미도달 확정 시 1회 재전송) — 소비처가 재시도를 덧대지 않는다.
+
+## 파일
+`package.json`(files 화이트리스트) · `README.md` · `MIGRATION.md` · `*.d.ts` · `styles.css` · `skills/cx-agent-hook-setup/`(이 문서).