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

package/bin/cx-agent-hook.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * cx-agent-hook CLI — 에이전트 스킬 설치 (의존성 0).
+ *
+ * 개발자가 자기 코딩 에이전트에게 "cx-agent-hook 셋업 도와줘" 라고만 해도 되게, 패키지에
+ * 실린 스킬(skills/cx-agent-hook-setup/SKILL.md + reference.md)을 프로젝트의 에이전트
+ * 디렉터리에 복사한다. 네트워크 0 — 설치된 패키지 안의 파일만 쓴다.
+ *
+ *   npx cx-agent-hook skills install            # → .claude/skills/cx-agent-hook-setup/  (Claude Code)
+ *   npx cx-agent-hook skills install --cursor   # + .cursor/rules/cx-agent-hook-setup.mdc (Cursor 규칙 → 스킬 참조)
+ *   npx cx-agent-hook skills install --agents-md# + AGENTS.md 에 한 줄 추가 (Codex 등 AGENTS.md 계열)
+ *   npx cx-agent-hook skills install --all      # 위 전부
+ *   npx cx-agent-hook skills install --to DIR   # 임의 디렉터리 (예: .agents/skills)
+ *   npx cx-agent-hook skills path               # SKILL.md 절대 경로 (에이전트에게 "이 파일 읽어" 라고 줄 때)
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(here, "..");
+const SKILL = "cx-agent-hook-setup";
+const src = join(pkgRoot, "skills", SKILL);
+const [cmd, sub, ...rest] = process.argv.slice(2);
+
+const flag = (name) => rest.includes(name);
+const opt = (name) => { const i = rest.indexOf(name); return i >= 0 ? rest[i + 1] : null; };
+const cwd = process.cwd();
+const log = (s) => process.stdout.write(s + "\n");
+
+function usage(code = 0) {
+  log(`cx-agent-hook skills <install|path> [--to DIR] [--cursor] [--agents-md] [--all]
+  install     스킬을 .claude/skills/${SKILL}/ 에 복사 (Claude Code). --cursor / --agents-md / --all 로 다른 에이전트도.
+  path        SKILL.md 절대 경로 출력 — 에이전트에게 "이 파일을 읽고 따라줘" 라고 줄 때.
+그 뒤 에이전트에게: "cx-agent-hook 셋업 도와줘" (adminApi·처리 카드까지가 셋업이다)`);
+  process.exit(code);
+}
+
+if (cmd !== "skills" || !sub) usage(cmd ? 1 : 0);
+if (!existsSync(join(src, "SKILL.md"))) { log(`스킬 파일이 없습니다: ${src}`); process.exit(1); }
+
+if (sub === "path") { log(join(src, "SKILL.md")); process.exit(0); }
+if (sub !== "install") usage(1);
+
+const done = [];
+const to = opt("--to");
+const targets = to ? [resolve(cwd, to, SKILL)] : [join(cwd, ".claude", "skills", SKILL)];
+if (flag("--all") && !to) { /* Claude Code 는 기본 대상 */ }
+for (const dir of targets) {
+  mkdirSync(dir, { recursive: true });
+  cpSync(src, dir, { recursive: true });
+  done.push(`스킬 복사 → ${dir}`);
+}
+const skillRel = to ? join(to, SKILL, "SKILL.md") : join(".claude", "skills", SKILL, "SKILL.md");
+
+if (flag("--cursor") || flag("--all")) {
+  const rulesDir = join(cwd, ".cursor", "rules");
+  mkdirSync(rulesDir, { recursive: true });
+  const mdc = join(rulesDir, `${SKILL}.mdc`);
+  writeFileSync(mdc, `---
+description: cx-agent-hook (@fcg-labs/cx-agent-hook) 셋업·배선·업그레이드 — AI 답변 초안 패널 + 처리 카드(adminApi)
+globs:
+alwaysApply: false
+---
+cx-agent-hook 관련 작업(셋업·연동·처리 카드·adminApi·업그레이드)은 먼저 \`${skillRel}\` 을 읽고
+그 절차(실측 → 결정 규칙 → 6단계 → 완료 체크리스트)를 그대로 따른다. reference.md 에 없는 API 이름을 쓰지 않는다.
+`);
+  done.push(`Cursor 규칙 → ${mdc}`);
+}
+if (flag("--agents-md") || flag("--all")) {
+  const agentsMd = join(cwd, "AGENTS.md");
+  const line = `\n## cx-agent-hook\ncx-agent-hook(@fcg-labs/cx-agent-hook) 셋업·연동·처리 카드(adminApi)·업그레이드 작업은 먼저 \`${skillRel}\` 을 읽고 그 절차와 완료 체크리스트를 따른다.\n`;
+  const cur = existsSync(agentsMd) ? readFileSync(agentsMd, "utf8") : "";
+  if (cur.includes("cx-agent-hook-setup")) done.push(`AGENTS.md 는 이미 스킬을 가리킴 (변경 없음)`);
+  else { appendFileSync(agentsMd, (cur && !cur.endsWith("\n") ? "\n" : "") + line); done.push(`AGENTS.md 에 안내 한 줄 추가 → ${agentsMd}`); }
+}
+for (const d of done) log(d);
+log(`\n다음: 에이전트에게 "cx-agent-hook 셋업 도와줘" — 답변 패널과 처리 카드(adminApi)까지가 셋업입니다.`);

package/client.js

@@ -37,8 +37,10 @@ const PATHS = {
     ingress: (d) => `/v1/domains/${d}/ingress`,
     // 조사 접점 (E-8) — 트리거는 큐 적재만, 상태는 경량 메타만 (허브 계약)
     investigation: (d) => `/v1/domains/${d}/investigations`,
-    // 처리 액션 (actions/1) — 실행 요청·상태·재조정. 정본: docs/contracts/action-contract-v1.md
+    // 처리 액션 (actions/1 프로파일 B) — 선점·결과 보고·상태·잠금·후보 발행.
+    // 정본: docs/contracts/action-contract-v1.md
     actions: (d) => `/v1/domains/${d}/actions`,
+    actionCandidates: (d) => `/v1/domains/${d}/action-candidates`,
   },
   // platform 은 인그레스 API 미제공 (공장 큐레이션 파이프라인이 담당)
 };
@@ -594,29 +596,28 @@ export class CxAgentClient {
     }
   }
 
-  // ── 처리 액션 (actions/1) ──────────────────────────────────────────────
+  // ── 처리 액션 (actions/1 프로파일 B — 브라우저 실행기) ────────────────────
   //
-  // **재시도 0.** sendFeedback 의 5xx 재시도 루프를 여기 쓰면 비멱등 실행이 두 번
-  // 간다. 네트워크 오류면 호출자가 actionStatus(request_id) 로 원장을 묻고,
-  // 404(미도달 확정)일 때만 같은 request_id 로 1회 재전송한다 (client 밖 규칙).
+  // 흐름: ① requestAction 으로 허브에 선점(received) → ② 호출자가 CMS 자기 API 를
+  // 부른다 → ③ reportActionResult 로 succeeded/failed/unknown 보고. 허브는 어떤
+  // 고객사 서버도 부르지 않는다. **재시도 0.** 선점은 부작용이 없어 미도달(404)
+  // 확정 시 1회 재전송이 안전하지만(session 규칙), CMS 호출·보고에는 재시도가 없다.
 
   /**
-   * 실행 요청. request_id 는 호출자(세션)가 발급·영속한 뒤 넘긴다 — 멱등 키.
+   * 선점. request_id 는 호출자(세션)가 발급·영속한 뒤 넘긴다 — 멱등 키.
    * @returns {Promise<{ok:boolean, state:string, requestId:string, reasonCode:string,
-   *   message:string, actorAttested:string, auditRef:string, result:object|null,
-   *   deduplicated:boolean, error:string|null, httpStatus:number}>}
+   *   message:string, targetKey:string, deduplicated:boolean, error:string|null, httpStatus:number}>}
    */
-  async requestAction({ requestId, offer, actorAssertion, actorClaimed, inquiryRef } = {}) {
+  async requestAction({ requestId, offer, actorClaimed, inquiryRef } = {}) {
     if (this.api !== "hub" || !requestId || !offer || !offer.offer_id) {
-      return { ok: false, state: "", requestId: requestId || "", reasonCode: "",
-               message: "", actorAttested: "", auditRef: "", result: null,
-               deduplicated: false, error: "unsupported", httpStatus: 0 };
+      return { ok: false, state: "", requestId: requestId || "", reasonCode: "", message: "",
+               targetKey: "", deduplicated: false, error: "unsupported", httpStatus: 0 };
     }
     const body = {
       request_id: String(requestId), offer_id: String(offer.offer_id),
       event_id: String(offer.event_id || ""), action_key: String(offer.action_key || ""),
       params_hash: String(offer.params_hash || ""), params: offer.params_bound || {},
-      actor_assertion: String(actorAssertion || ""), actor_claimed: String(actorClaimed || ""),
+      target_key: String(offer.target_key || ""), actor_claimed: String(actorClaimed || ""),
       inquiry_ref: inquiryRef != null ? String(inquiryRef) : "",
       confirmed_at: new Date().toISOString(),
     };
@@ -625,20 +626,47 @@ export class CxAgentClient {
       const view = (d) => ({
         state: d.state || "", requestId: d.request_id || String(requestId),
         reasonCode: d.reason_code || "", message: d.message || "",
-        actorAttested: d.actor_attested || "", auditRef: d.audit_ref || "",
-        result: d.result ?? null, deduplicated: Boolean(d.deduplicated),
+        targetKey: d.target_key || "", deduplicated: Boolean(d.deduplicated),
       });
       if (status === 200 || status === 202) {
         return { ok: true, ...view(data), error: null, httpStatus: status };
       }
-      // 409 offer_locked / request_conflict, 422 계약 위반, 503 잠김 — 그대로 전달
+      // 409 offer_locked / request_conflict, 422 계약 위반 — 그대로 전달
       this.onError(new Error(`HTTP ${status}`), { op: "requestAction", code: data.error || "http_error" });
       return { ok: false, ...view(data), error: data.error || `http_${status}`, httpStatus: status };
     } catch (err) {
       this.onError(err, { op: "requestAction", code: "network_error" });
       return { ok: false, state: "", requestId: String(requestId), reasonCode: "", message: "",
-               actorAttested: "", auditRef: "", result: null, deduplicated: false,
-               error: "network_error", httpStatus: 0 };
+               targetKey: "", deduplicated: false, error: "network_error", httpStatus: 0 };
+    }
+  }
+
+  /**
+   * 결과 보고 — CMS 호출이 끝난 뒤 1회. 같은 종단 재보고는 허브가 멱등(200 deduplicated),
+   * 다른 종단은 409 state_conflict, 선점 없는 request 는 404.
+   * @param {string} requestId
+   * @param {{state:"succeeded"|"failed"|"unknown", reasonCode?:string, message?:string,
+   *          httpStatus?:number, latencyMs?:number, result?:object}} r
+   */
+  async reportActionResult(requestId, { state, reasonCode, message, httpStatus, latencyMs, result } = {}) {
+    if (this.api !== "hub" || !requestId) return { ok: false, state: "", error: "unsupported", httpStatus: 0 };
+    const body = {
+      state: String(state || ""), reason_code: String(reasonCode || ""), message: String(message || "").slice(0, 200),
+      http_status: Number(httpStatus) || 0, latency_ms: Number(latencyMs) || 0, result: result || null,
+    };
+    try {
+      const { status, data } = await this._post(
+        PATHS.hub.actions(this.domain) + `/${encodeURIComponent(String(requestId))}/result`, body,
+      );
+      if (status === 200) {
+        return { ok: true, state: data.state || "", reasonCode: data.reason_code || "", message: data.message || "",
+                 deduplicated: Boolean(data.deduplicated), error: null, httpStatus: status };
+      }
+      this.onError(new Error(`HTTP ${status}`), { op: "reportActionResult", code: data.error || "http_error" });
+      return { ok: false, state: data.state || "", error: data.error || `http_${status}`, httpStatus: status };
+    } catch (err) {
+      this.onError(err, { op: "reportActionResult", code: "network_error" });
+      return { ok: false, state: "", error: "network_error", httpStatus: 0 };
     }
   }
 
@@ -657,22 +685,41 @@ export class CxAgentClient {
     );
   }
 
-  /** 재조정 — lookup 전용 (재실행 아님). unknown 만 의미 있고 종단이면 그대로 온다. */
-  async actionReconcile(requestId) {
-    if (this.api !== "hub" || !requestId) return { ok: false, state: "", error: "unsupported" };
+  /**
+   * 잠금 조회 — (action_key, target_key) 최근 성공. locked 면 params_hash·at·actor_claimed.
+   * 카드 잠금 판정은 호출자: locked && params_hash === offer.params_hash.
+   */
+  async actionLock(actionKey, targetKey) {
+    if (this.api !== "hub" || !actionKey || !targetKey) return { ok: false, locked: false, error: "unsupported" };
+    const q = `?action_key=${encodeURIComponent(actionKey)}&target_key=${encodeURIComponent(targetKey)}`;
+    return this._getJson(PATHS.hub.actions(this.domain) + "/lock" + q, "actionLock", (status, data) => {
+      if (status === 200) {
+        return { ok: true, locked: Boolean(data.locked), paramsHash: data.params_hash || "",
+                 requestId: data.request_id || "", at: data.at || "", actorClaimed: data.actor_claimed || "", error: null };
+      }
+      return { ok: false, locked: false, error: data.error || `http_${status}` };
+    });
+  }
+
+  /**
+   * 후보 스냅샷 발행 — "이 CMS 가 이미 하는 처리" (키·메서드·경로 템플릿, 호스트 없음).
+   * 같은 snapshot_hash 면 허브가 200 unchanged 로 쓰기 0. 신규/교체는 201.
+   * @param {{snapshotHash:string, items:Array<{endpoint_key:string, methods:string[], path_template:string}>}} snap
+   */
+  async publishActionCandidates({ snapshotHash, items } = {}) {
+    if (this.api !== "hub" || !Array.isArray(items)) return { ok: false, error: "unsupported", httpStatus: 0 };
     try {
-      const { status, data } = await this._post(
-        PATHS.hub.actions(this.domain) + `/${encodeURIComponent(String(requestId))}/reconcile`, {},
-      );
-      if (status === 200 || status === 202) {
-        return { ok: true, state: data.state || "", reasonCode: data.reason_code || "",
-                 message: data.message || "", actorAttested: data.actor_attested || "",
-                 auditRef: data.audit_ref || "", error: null };
+      const { status, data } = await this._post(PATHS.hub.actionCandidates(this.domain),
+                                                { snapshot_hash: String(snapshotHash || ""), items });
+      if (status === 200 || status === 201) {
+        return { ok: true, unchanged: Boolean(data.unchanged), count: Number(data.count) || 0,
+                 snapshotHash: data.snapshot_hash || "", error: null, httpStatus: status };
       }
-      return { ok: false, state: "", error: data.error || `http_${status}` };
+      this.onError(new Error(`HTTP ${status}`), { op: "publishActionCandidates", code: data.error || "http_error" });
+      return { ok: false, error: data.error || `http_${status}`, httpStatus: status };
     } catch (err) {
-      this.onError(err, { op: "actionReconcile", code: "network_error" });
-      return { ok: false, state: "", error: "network_error" };
+      this.onError(err, { op: "publishActionCandidates", code: "network_error" });
+      return { ok: false, error: "network_error", httpStatus: 0 };
     }
   }
 

package/element.d.ts

@@ -16,8 +16,19 @@ export interface CxAiSuggestElement extends HTMLElement {
 /** 커스텀 엘리먼트 등록. 두 번 불러도 안전하고, 브라우저가 아니면 무동작(false). */
 export declare function defineCxAiSuggest(tagName?: string): boolean;
 
+/** 처리 선택지 카드 태그 이름 */
+export declare const ACTIONS_TAG: "cx-action-offers";
+export interface CxActionOffersElement extends HTMLElement {
+  agent: import("./agent.js").CxAgent | null;
+  session: import("./agent.js").InquirySession | null;
+  actorClaimed: string;
+}
+/** `<cx-action-offers>` 등록 — 결과는 `cx-action-result` 이벤트(detail = ActionResult) */
+export declare function defineCxActionOffers(tagName?: string): boolean;
+
 declare global {
-  interface HTMLElementTagNameMap { "cx-ai-suggest": CxAiSuggestElement }
+  interface HTMLElementTagNameMap { "cx-ai-suggest": CxAiSuggestElement; "cx-action-offers": CxActionOffersElement }
+  interface HTMLElementEventMap { "cx-action-result": CustomEvent<import("./agent.js").ActionResult & { requestId: string }> }
   interface HTMLElementEventMap {
     "cx-adopt": CustomEvent<{ text: string; answerId: number | string | null }>;
   }

package/element.js

@@ -24,7 +24,7 @@
  * 클래스를 모듈 최상위에서 만들지 않는 이유: `HTMLElement` 가 없는 곳(SSR·Node)
  * 에서 import 만 해도 죽는다. 등록 시점에 만든다.
  */
-import { aiSuggestTree, aiSuggestView, CLS } from "./view.js";
+import { actionOffersTree, aiSuggestTree, aiSuggestView, CLS } from "./view.js";
 
 export { aiSuggestView };
 
@@ -137,3 +137,126 @@ export function defineCxAiSuggest(tagName = TAG) {
   window.customElements.define(tagName, createClass());
   return true;
 }
+
+// ── 처리 선택지 카드 — 표준 커스텀 엘리먼트 `<cx-action-offers>` ─────────────
+//
+// ```html
+// <cx-action-offers></cx-action-offers>
+// <script type="module">
+//   import { defineCxActionOffers } from "@fcg-labs/cx-agent-hook/element";
+//   defineCxActionOffers();
+//   const el = document.querySelector("cx-action-offers");
+//   el.agent = agent; el.session = agent.session(csId); el.actorClaimed = "상담사 이름";
+//   el.addEventListener("cx-action-result", (e) => console.log(e.detail.state));
+// </script>
+// ```
+export const ACTIONS_TAG = "cx-action-offers";
+
+function createActionsClass() {
+  return class CxActionOffersElement extends HTMLElement {
+    #agent = null;
+    #session = null;
+    #actorClaimed = "";
+    #offers = [];
+    #pending = [];
+    #confirming = null;
+    #ackedOffer = null;   // 고위험 확인은 offer 단위
+
+    get agent() { return this.#agent; }
+    set agent(v) { this.#agent = v; this.#render(); }
+    get actorClaimed() { return this.#actorClaimed; }
+    set actorClaimed(v) { this.#actorClaimed = v == null ? "" : String(v); }
+    get session() { return this.#session; }
+    set session(s) {
+      if (this.#session && typeof this.#session.detachActionUi === "function") this.#session.detachActionUi();
+      this.#session = s || null;
+      this.#confirming = null; this.#ackedOffer = null;
+      this.#attach();
+      this.#render();
+    }
+    // sink 연결 — session setter 와 재연결(connectedCallback) 양쪽에서. detach 후 다시 DOM 에
+    // 붙는 엘리먼트가 화석 스냅샷으로 남지 않게 한다.
+    #attach() {
+      const s = this.#session;
+      if (s && typeof s.attachActionUi === "function") {
+        this.#offers = s.offers; this.#pending = s.pendingActions();
+        s.attachActionUi({ setOffers: (o, p) => { this.#offers = o; this.#pending = p; this.#render(); } });
+      } else { this.#offers = []; this.#pending = []; }
+    }
+    connectedCallback() { this.#attach(); this.#render(); }
+    disconnectedCallback() { if (this.#session && typeof this.#session.detachActionUi === "function") this.#session.detachActionUi(); }
+
+    async #execute(offerId) {
+      const offer = this.#offers.find((o) => o.offer_id === offerId);
+      if (!offer || !this.#session) return;
+      if (offer.risk_level === "high" && this.#ackedOffer !== offerId) return;
+      this.#confirming = null; this.#ackedOffer = null; this.#render();
+      const r = await this.#session.executeAction(offer, { actorClaimed: this.#actorClaimed });
+      this.#render();
+      this.dispatchEvent(new CustomEvent("cx-action-result", { detail: r, bubbles: true }));
+    }
+
+    #render() {
+      // 포커스 복원 — DOM 을 갈아 끼우므로 눌린 컨트롤(data-offer/data-request + action)을 다시 찾아 준다
+      const active = document.activeElement;
+      const focusKey = active && this.contains(active)
+        ? { action: active.dataset.action || "", offer: active.dataset.offer || "", request: active.dataset.request || "" } : null;
+      this.replaceChildren();
+      if (!this.#agent || !this.#session) return;
+      const tree = actionOffersTree({ offers: this.#offers, pending: this.#pending,
+        enabled: Boolean(this.#agent.actionsEnabled), confirming: this.#confirming, messages: this.#agent.messages });
+      if (!tree) return;
+      const actions = {
+        confirm: (e) => { this.#confirming = e.currentTarget.dataset.offer || null; this.#ackedOffer = null; this.#render(); },
+        cancel: () => { this.#confirming = null; this.#ackedOffer = null; this.#render(); },
+        ack: (e) => { const id = e.currentTarget.dataset.offer; this.#ackedOffer = this.#ackedOffer === id ? null : id; this.#render(); },
+        execute: (e) => this.#execute(e.currentTarget.dataset.offer),
+        resend: (e) => this.#session.resendResult(e.currentTarget.dataset.request),
+      };
+      const build = (node) => {
+        const dom = document.createElement(node.tag);
+        if (node.cls) dom.className = node.cls;
+        if (node.tag === "button") dom.type = node.type || "button";
+        if (node.action && actions[node.action]) {
+          dom.addEventListener("click", actions[node.action]);
+          dom.dataset.action = node.action;
+          if (node.offerId) dom.dataset.offer = node.offerId;
+          if (node.requestId) dom.dataset.request = node.requestId;
+          if (node.action === "execute" && this.#confirming) {
+            const o = this.#offers.find((x) => x.offer_id === node.offerId);
+            if (o && o.risk_level === "high" && this.#ackedOffer !== node.offerId) dom.disabled = true;
+          }
+          if (node.pressed) dom.setAttribute("aria-pressed", String(this.#ackedOffer === node.offerId));
+        }
+        if (node.live) dom.setAttribute("role", "status");
+        if (node.state) dom.dataset.state = node.state;
+        if (node.risk) dom.dataset.risk = node.risk;
+        if (node.children) for (const c of node.children) dom.append(build(c));
+        else if (node.text !== undefined) dom.textContent = node.text;
+        return dom;
+      };
+      const root = document.createElement("div");
+      root.className = tree.cls;
+      root.addEventListener("click", (e) => e.stopPropagation());
+      for (const n of tree.children) root.append(build(n));
+      this.append(root);
+      if (focusKey) {
+        // 같은 컨트롤이 남아 있으면 그것, 확인 패널을 연 직후면 패널의 첫 버튼(실행/체크)로
+        const same = focusKey.action && [...root.querySelectorAll("[data-action]")]
+          .find((el) => el.dataset.action === focusKey.action && (el.dataset.offer || "") === focusKey.offer && (el.dataset.request || "") === focusKey.request && !el.disabled);
+        const target = same
+          || (focusKey.action === "confirm" && root.querySelector(`.${"fcx-act-confirm"} button:not(:disabled)`))
+          || null;
+        if (target && typeof target.focus === "function") target.focus();
+      }
+    }
+  };
+}
+
+/** 커스텀 엘리먼트 등록 — 두 번 불러도 안전, 브라우저가 아니면 무동작. */
+export function defineCxActionOffers(tagName = ACTIONS_TAG) {
+  if (typeof window === "undefined" || !window.customElements) return false;
+  if (window.customElements.get(tagName)) return false;
+  window.customElements.define(tagName, createActionsClass());
+  return true;
+}

package/locales.js

@@ -40,7 +40,10 @@ const en = {
   ui_action_succeeded: "Done",
   ui_action_failed: "Not applied",
   ui_action_unknown: "Could not confirm whether this was applied — check again before retrying.",
-  ui_action_reconcile: "Check again",
+  ui_action_resend: "Report result again",
+  ui_action_unreported: "result not yet recorded",
+  ui_action_locked: "Already processed",
+  ui_action_unavailable: "This CMS does not know this action — ask your CMS admin to update the hook.",
   ui_action_disabled: "Actions are not enabled for this seat.",
   ui_action_risk_low: "low risk",
   ui_action_risk_medium: "medium risk",
@@ -80,7 +83,10 @@ const ko = {
   ui_action_succeeded: "처리 완료",
   ui_action_failed: "처리되지 않음",
   ui_action_unknown: "실행 여부를 확인하지 못했습니다 — 다시 누르지 말고 먼저 확인하세요.",
-  ui_action_reconcile: "다시 확인",
+  ui_action_resend: "결과 다시 보고",
+  ui_action_unreported: "결과가 아직 기록되지 않음",
+  ui_action_locked: "이미 처리됨",
+  ui_action_unavailable: "이 CMS 에 없는 처리입니다 — CMS 담당자에게 훅 갱신을 요청하세요.",
   ui_action_disabled: "이 계정에는 처리 기능이 켜져 있지 않습니다.",
   ui_action_risk_low: "위험 낮음",
   ui_action_risk_medium: "위험 보통",
@@ -115,7 +121,10 @@ const ja = {
   ui_action_succeeded: "処理完了",
   ui_action_failed: "未処理",
   ui_action_unknown: "実行の有無を確認できませんでした — 再度押さずに先に確認してください。",
-  ui_action_reconcile: "再確認",
+  ui_action_resend: "結果を再報告",
+  ui_action_unreported: "結果がまだ記録されていません",
+  ui_action_locked: "処理済み",
+  ui_action_unavailable: "このCMSにない処理です — CMS担当者にフック更新を依頼してください。",
   ui_action_disabled: "このアカウントでは処理機能が有効になっていません。",
   ui_action_risk_low: "リスク低",
   ui_action_risk_medium: "リスク中",
@@ -150,7 +159,10 @@ const zhTW = {
   ui_action_succeeded: "處理完成",
   ui_action_failed: "未套用",
   ui_action_unknown: "無法確認是否已執行 — 請先確認再重試。",
-  ui_action_reconcile: "再次確認",
+  ui_action_resend: "重新回報結果",
+  ui_action_unreported: "結果尚未記錄",
+  ui_action_locked: "已處理",
+  ui_action_unavailable: "此 CMS 沒有這個處理 — 請 CMS 負責人更新掛鉤。",
   ui_action_disabled: "此帳號未啟用處理功能。",
   ui_action_risk_low: "風險低",
   ui_action_risk_medium: "風險中",

package/next.d.ts

@@ -1,3 +1,3 @@
 /** Next.js (App Router) 진입점 — react 와 같되 "use client" 경계를 선언한다. */
-export { AiSuggestPanel, aiSuggestView, default } from "./react.js";
-export type { AiSuggestPanelProps, AiSuggestView } from "./react.js";
+export { AiSuggestPanel, ActionOffersPanel, aiSuggestView, default } from "./react.js";
+export type { AiSuggestPanelProps, ActionOffersPanelProps, AiSuggestView } from "./react.js";

package/next.js

@@ -17,4 +17,4 @@
  * Pages Router 나 순수 React 라면 `@fcg-labs/cx-agent-hook/react` 와 같다.
  * 지시자는 그쪽에서 무시되므로 이 진입점을 써도 문제는 없다.
  */
-export { AiSuggestPanel, aiSuggestView, default } from "./react.js";
+export { AiSuggestPanel, ActionOffersPanel, aiSuggestView, default } from "./react.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fcg-labs/cx-agent-hook",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "FCG CX Agent 후킹 SDK — 서빙 답변 수신 + CS팀 교정(점수·수정·발송) 후킹. 의존성 0, CMS에 install만으로 이식",
   "type": "module",
   "main": "index.js",
@@ -61,6 +61,7 @@
     "agent.js",
     "agent.d.ts",
     "session.js",
+    "actions.js",
     "compat.js",
     "client.js",
     "client.d.ts",
@@ -83,7 +84,10 @@
     "element.d.ts",
     "styles.css",
     "README.md",
-    "LICENSE"
+    "AGENTS.md",
+    "LICENSE",
+    "bin/",
+    "skills/"
   ],
   "scripts": {
     "test": "node --test test/*.test.js",
@@ -108,5 +112,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "//name": "스코프는 @fcg-labs — org 소유이고 @fcg-labs/tlm 과 같은 자리다. @fcg 는 우리 것이 아니다(발행 불가)."
-}
+  "//name": "스코프는 @fcg-labs — org 소유이고 @fcg-labs/tlm 과 같은 자리다. @fcg 는 우리 것이 아니다(발행 불가).",
+  "bin": {
+    "cx-agent-hook": "bin/cx-agent-hook.js"
+  }
+}

package/react.d.ts

@@ -1,5 +1,6 @@
 import type { ReactElement } from "react";
 import type { AnswerResult, CxHook } from "./index.js";
+import type { ActionResult, CxAgent, InquirySession } from "./agent.js";
 
 export { aiSuggestView } from "./view.js";
 export type { AiSuggestView } from "./view.js";
@@ -17,4 +18,17 @@ export interface AiSuggestPanelProps {
 /** AI 답변 제안 패널. hook 이 미설정이면 아무것도 그리지 않는다. */
 export declare function AiSuggestPanel(props: AiSuggestPanelProps): ReactElement | null;
 
+
+export interface ActionOffersPanelProps {
+  /** agent.session(externalId) — offers·pending·executeAction 의 소유자 */
+  session: InquirySession;
+  agent: CxAgent;
+  /** 표시용 행위자 이름(자기 주장) — 원장 actor_claimed */
+  actorClaimed?: string;
+  onResult?: (r: ActionResult & { requestId: string }) => void;
+  className?: string;
+}
+/** 처리 선택지 카드 (actions/1 프로파일 B) — 잠김·비활성·2단 확인·상태·미보고 규약을 갖는다. */
+export declare function ActionOffersPanel(props: ActionOffersPanelProps): ReactElement | null;
+
 export default AiSuggestPanel;

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)));
+}