@fcg-labs/cx-agent-hook 0.3.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,6 +37,10 @@ const PATHS = {
     ingress: (d) => `/v1/domains/${d}/ingress`,
     // 조사 접점 (E-8) — 트리거는 큐 적재만, 상태는 경량 메타만 (허브 계약)
     investigation: (d) => `/v1/domains/${d}/investigations`,
+    // 처리 액션 (actions/1 프로파일 B) — 선점·결과 보고·상태·잠금·후보 발행.
+    // 정본: docs/contracts/action-contract-v1.md
+    actions: (d) => `/v1/domains/${d}/actions`,
+    actionCandidates: (d) => `/v1/domains/${d}/action-candidates`,
   },
   // platform 은 인그레스 API 미제공 (공장 큐레이션 파이프라인이 담당)
 };
@@ -591,6 +595,168 @@ export class CxAgentClient {
       clearTimeout(timer);
     }
   }
+
+  // ── 처리 액션 (actions/1 프로파일 B — 브라우저 실행기) ────────────────────
+  //
+  // 흐름: ① requestAction 으로 허브에 선점(received) → ② 호출자가 CMS 자기 API 를
+  // 부른다 → ③ reportActionResult 로 succeeded/failed/unknown 보고. 허브는 어떤
+  // 고객사 서버도 부르지 않는다. **재시도 0.** 선점은 부작용이 없어 미도달(404)
+  // 확정 시 1회 재전송이 안전하지만(session 규칙), CMS 호출·보고에는 재시도가 없다.
+
+  /**
+   * 선점. request_id 는 호출자(세션)가 발급·영속한 뒤 넘긴다 — 멱등 키.
+   * @returns {Promise<{ok:boolean, state:string, requestId:string, reasonCode:string,
+   *   message:string, targetKey:string, deduplicated:boolean, error:string|null, httpStatus:number}>}
+   */
+  async requestAction({ requestId, offer, actorClaimed, inquiryRef } = {}) {
+    if (this.api !== "hub" || !requestId || !offer || !offer.offer_id) {
+      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 || {},
+      target_key: String(offer.target_key || ""), actor_claimed: String(actorClaimed || ""),
+      inquiry_ref: inquiryRef != null ? String(inquiryRef) : "",
+      confirmed_at: new Date().toISOString(),
+    };
+    try {
+      const { status, data } = await this._post(PATHS.hub.actions(this.domain), body);
+      const view = (d) => ({
+        state: d.state || "", requestId: d.request_id || String(requestId),
+        reasonCode: d.reason_code || "", message: d.message || "",
+        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 계약 위반 — 그대로 전달
+      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: "",
+               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 };
+    }
+  }
+
+  /** 상태 조회 — 원장 뷰(result 없음). 404 = 허브에 기록 없음(미도달 확정). */
+  async actionStatus(requestId) {
+    if (this.api !== "hub" || !requestId) return { ok: false, state: "", error: "unsupported" };
+    return this._getJson(
+      PATHS.hub.actions(this.domain) + `/${encodeURIComponent(String(requestId))}`,
+      "actionStatus",
+      (status, data) => {
+        if (status === 200) return { ok: true, state: data.state || "", reasonCode: data.reason_code || "",
+                                     message: data.message || "", error: null };
+        if (status === 404) return { ok: true, state: "none", reasonCode: "", message: "", error: null };
+        return { ok: false, state: "", error: data.error || `http_${status}` };
+      },
+    );
+  }
+
+  /**
+   * 잠금 조회 — (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.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 };
+      }
+      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: "publishActionCandidates", code: "network_error" });
+      return { ok: false, error: "network_error", httpStatus: 0 };
+    }
+  }
+
+  async _getJson(path, op, interpret) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(this.baseUrl + path, {
+        headers: { "Authorization": `Bearer ${this.token}` }, signal: controller.signal,
+      });
+      const data = await res.json().catch(() => ({}));
+      return interpret(res.status, data);
+    } catch (err) {
+      this.onError(err, { op, code: "network_error" });
+      return { ok: false, state: "", error: "network_error" };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/** ULID (Crockford 26자) — request_id 발급. 의존성 0 (공장 event_ids 와 동형). */
+export function newRequestId(now = Date.now()) {
+  const A = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+  let ts = BigInt(now) & ((1n << 48n) - 1n);
+  const rnd = new Uint8Array(10);
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) crypto.getRandomValues(rnd);
+  else for (let i = 0; i < 10; i++) rnd[i] = Math.floor(Math.random() * 256);
+  // 상위 48bit 시각 → 10자, 하위 80bit 무작위 → 16자 (공장 event_ids 와 동일 배치)
+  const out = [];
+  let t = ts;
+  for (let i = 0; i < 10; i++) { out.unshift(A[Number(t & 31n)]); t >>= 5n; }
+  let r = 0n;
+  for (const b of rnd) r = (r << 8n) | BigInt(b);
+  const tail = [];
+  for (let i = 0; i < 16; i++) { tail.unshift(A[Number(r & 31n)]); r >>= 5n; }
+  return out.join("") + tail.join("");
 }
 
 export default CxAgentClient;

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

@@ -31,6 +31,23 @@ const en = {
   ui_adopt: "Insert into editor",
   ui_evidence: "Sources",
   ui_correcting: "Fixing phrasing — rewriting…",
+  ui_action_execute: "Process",
+  ui_action_confirm_default: "Run this action?",
+  ui_action_confirm_ok: "Yes, run",
+  ui_action_confirm_cancel: "Cancel",
+  ui_action_ack: "I understand this cannot be undone",
+  ui_action_running: "Processing…",
+  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_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",
+  ui_action_risk_high: "high risk",
   ui_overwrite_confirm: "Replace your current draft with the AI draft?",
   // 거절·오류 사유
   not_configured: "AI reply suggestions are not connected yet.",
@@ -57,6 +74,23 @@ const ko = {
   ui_adopt: "에디터에 넣기",
   ui_evidence: "근거",
   ui_correcting: "표현 교정 중 — 다시 쓰는 중...",
+  ui_action_execute: "처리하기",
+  ui_action_confirm_default: "이 처리를 진행할까요?",
+  ui_action_confirm_ok: "네, 진행",
+  ui_action_confirm_cancel: "취소",
+  ui_action_ack: "되돌릴 수 없음을 확인했습니다",
+  ui_action_running: "처리 중…",
+  ui_action_succeeded: "처리 완료",
+  ui_action_failed: "처리되지 않음",
+  ui_action_unknown: "실행 여부를 확인하지 못했습니다 — 다시 누르지 말고 먼저 확인하세요.",
+  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: "위험 보통",
+  ui_action_risk_high: "위험 높음",
   ui_overwrite_confirm: "작성 중인 답변을 지우고 AI 초안으로 바꿀까요?",
   not_configured: "AI 답변 제안이 아직 연결되지 않았습니다.",
   unsupported_api: "AI 답변 제안이 아직 연결되지 않았습니다.",
@@ -78,6 +112,23 @@ const ja = {
   ui_adopt: "エディタに挿入",
   ui_evidence: "根拠",
   ui_correcting: "表現を修正中 — 書き直しています…",
+  ui_action_execute: "処理する",
+  ui_action_confirm_default: "この処理を実行しますか？",
+  ui_action_confirm_ok: "はい、実行",
+  ui_action_confirm_cancel: "キャンセル",
+  ui_action_ack: "元に戻せないことを確認しました",
+  ui_action_running: "処理中…",
+  ui_action_succeeded: "処理完了",
+  ui_action_failed: "未処理",
+  ui_action_unknown: "実行の有無を確認できませんでした — 再度押さずに先に確認してください。",
+  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: "リスク中",
+  ui_action_risk_high: "リスク高",
   ui_overwrite_confirm: "作成中の回答を消してAI下書きに置き換えますか？",
   not_configured: "AI 返信案はまだ接続されていません。",
   unsupported_api: "AI 返信案はまだ接続されていません。",
@@ -99,6 +150,23 @@ const zhTW = {
   ui_adopt: "插入編輯器",
   ui_evidence: "依據",
   ui_correcting: "正在修正表述 — 重新撰寫中…",
+  ui_action_execute: "處理",
+  ui_action_confirm_default: "要執行這項處理嗎？",
+  ui_action_confirm_ok: "是，執行",
+  ui_action_confirm_cancel: "取消",
+  ui_action_ack: "我已確認此操作無法復原",
+  ui_action_running: "處理中…",
+  ui_action_succeeded: "處理完成",
+  ui_action_failed: "未套用",
+  ui_action_unknown: "無法確認是否已執行 — 請先確認再重試。",
+  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: "風險中",
+  ui_action_risk_high: "風險高",
   ui_overwrite_confirm: "要清除目前草稿並以 AI 草稿取代嗎？",
   not_configured: "AI 回覆建議尚未連接。",
   unsupported_api: "AI 回覆建議尚未連接。",

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.3.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;